# HasuraがGraphQLのクエリを1本のSQLにする仕組み

Date: 2026-11-17
Tags: hasura, graphql, postgresql, performance
URL: https://s.conao3.com/blog/2026/360ae9
Author: conao3 (Naoya Yamashita)

HasuraはPostgreSQLのテーブルからGraphQLのAPIを作るサーバーで、気に入って使っています。
ただ、HasuraがどのようにSQLを生成するのかは、これまで調べていませんでした。

調べると、Hasuraはresolverを持たないコンパイラでした。
テーブルとrelationshipと権限の定義からGraphQLのschemaを作り、届いたクエリを1本のSQLに変換します。
行の取得も結合もJSONの組み立ても、そのSQLを受け取ったPostgreSQLが行います。

SQLが長いので、速さも測りました。
ページ単位で取るクエリは、手で書いたSQLと変わらない時間で終わりました。
親と子を数万件まとめて取る入れ子のクエリだけが、手書きのおよそ2倍の時間がかかりました。

この記事はHasura GraphQL Engineのv2を対象にしています。
載せたSQLは、PostgreSQL 17.11に接続したv2.51.6が実際に生成したものです。

# 構成

![img](https://s.conao3.com/img/360ae9-architecture.svg)

どの構成でも動くのは、HasuraのコンテナとPostgreSQLの2つです。
権限の判定、GraphQLのschemaの生成、GraphQLからSQLへの変換は、どのリクエストでも動きます。
図では青い部品です。

APIの形を決めるのはmetadataです。
metadataは、公開するテーブル、テーブルのあいだのrelationship、roleごとの権限の定義で、ConsoleやCLI、Metadata APIから登録します。
HasuraがmetadataをJSONで保存するのはPostgreSQLの `hdb_catalog` というschemaです。
[公式のドキュメント](https://hasura.io/docs/2.0/getting-started/how-it-works/index/)によると、テーブルを1つ登録すると、Hasuraはその型を作ります。
検索、主キーでの取得、集計、追加、更新、削除、購読のフィールドも作ります。

図の点線の部品が動くのは設定したときだけです。
[認証](https://hasura.io/docs/2.0/auth/overview/)はHasuraの外で行います。
HasuraはJWTかwebhookでroleとsession variableを受け取ります。
ActionsとRemote Schemasは外部のAPIをschemaに加える機能で、Event Triggersは行の変更をwebhookに送る機能です。
HasuraはMySQLやOracleなどには、[data connector agent](https://hasura.io/docs/2.0/databases/data-connectors/)というサービスを経由してつなぎます。

# クエリ1件の流れ

![img](https://s.conao3.com/img/360ae9-flow.svg)

クライアントがクエリを送ると、Hasuraは図の②から⑤の順でSQLを作ります。
②から⑤の段階は、Hasuraの[設計の文書](https://github.com/hasura/graphql-engine/blob/master/architecture/live-queries.md)に書かれています。
②でroleとsession variableを取り出し、③でクエリをGraphQLのASTにします。
④でroleごとの権限の式をASTに入れます。
⑤では、そのASTをSQLのASTに変えてからSQLの文字列にします。

Hasuraが実行するSQLはroot fieldごとに1本で、クエリのroot fieldが1つならSQLも1本です。
PostgreSQLは結果のJSONを1つの値で返し、Hasuraはそれを `data` に包んで応答にします。
著者2,000人を記事とコメントごと取るクエリでは、SQLの結果が8,423,123バイト、HTTPの応答が8,423,143バイトでした。
差の20バイトは、応答の先頭と末尾に付く `data` とフィールド名の分です。

resolverがフィールドごとにデータを取る作りでは、親の行の数だけ子のSQLを実行するN+1問題が起きます。
設計の文書は、クエリ全体を1本のSQLにすればN+1問題がなくなり、データベースが全体を見て最適化できると書いています。

# GraphQLとSQLの対応

検証するため、著者、記事、コメントの3つのテーブルを作りました。
公開日の新しい順に記事を20件取り、著者の名前とコメントの先頭5件を付けるクエリを、[Explain API](https://hasura.io/docs/2.0/api-reference/explain/)に送りました。
Explain APIは、Hasuraが生成するSQLを返すAPIです。
次の図は、上が送ったクエリ、下が返ってきたSQLで、SQLの改行と字下げは私が足しました。

![img](https://s.conao3.com/img/360ae9-mapping.svg)

GraphQLの入れ子1段が、SQLでは副問い合わせ1つになっています。

-   青の `article` と引数は、記事のテーブルを `ORDER BY` と `LIMIT 20` で絞る副問い合わせになります。
-   黄の `id` と `title` は、 `row_to_json` に渡す列です。
-   緑の `author` は記事1件に著者1人のrelationshipで、 `LEFT OUTER JOIN LATERAL` と `LIMIT 1` の副問い合わせになります。
-   紫の `comments` は記事1件にコメント複数のrelationshipで、 `LEFT OUTER JOIN LATERAL` の中の `json_agg` がコメントの行を配列にします。

色を付けていない一番外側の `json_agg` の値が応答の配列です。

# 権限

権限では、roleごとに見せる行の条件を式で定義します。
`user` というroleに、自分が著者の記事と、その記事のコメントだけを見せる権限を付けました。
記事の条件は、 `author_id` がsession variableの `X-Hasura-User-Id` と等しいことです。

roleが `user` で `X-Hasura-User-Id` が42のリクエストとして、同じクエリをExplain APIに送りました。
記事の副問い合わせは次のように変わりました。

```sql
FROM (SELECT * FROM "public"."article"
      WHERE (("public"."article"."author_id") = (('42')::integer))
      ORDER BY "published_at" DESC NULLS FIRST LIMIT 20 ) AS "_root.base"
```

adminのroleで生成した最初のSQLでは `WHERE ('true')` だった場所に、権限の式が入っています。
コメントの副問い合わせには、コメントの権限の式が `EXISTS` で加わりました。

```sql
FROM (SELECT * FROM "public"."comment"
      WHERE ((("_root.base"."id") = ("article_id"))
        AND (EXISTS (SELECT 1 FROM "public"."article" AS "__be_0_article"
          WHERE (((("__be_0_article"."id") = ("public"."comment"."article_id")) AND ('true'))
            AND (('true') AND (((("__be_0_article"."author_id") = (('42')::integer))
              AND ('true')) AND ('true')))) )))
      ORDER BY "id" ASC NULLS LAST LIMIT 5 ) AS "_root.ar.root.comments.base"
```

権限の式は、テーブルを参照する副問い合わせごとに入ります。
このroleで記事を数えると、20万件のうち20件でした。

# 購読

![img](https://s.conao3.com/img/360ae9-subscription.svg)

subscriptionも1本のSQLにする同じ仕組みで動きます。
ここで説明するのは、Hasuraのsubscriptionのうちlive queryと呼ばれる方式です。
[公式のドキュメント](https://hasura.io/docs/2.0/subscriptions/postgres/livequery/execution/)によると、Hasuraは購読されたクエリを一定の間隔で再実行し、結果が前回から変わった購読にだけ新しい結果を送ります。
間隔の既定値は1秒です。
Hasuraはroleと形が同じで変数だけが違う購読を、100件まで1本のSQLにまとめます。

idを変数にして記事を1件購読するクエリをExplain APIに送ると、次のSQLになりました。
`...` の行は省いたところです。

```sql
SELECT "__subs"."result_id" , "__fld_resp"."root" AS "result"
FROM UNNEST(($1)::uuid[], ($2)::json[]) AS "__subs"("result_id", "result_vars")
LEFT OUTER JOIN LATERAL (
  ...
      FROM (SELECT * FROM "public"."article"
            WHERE (("public"."article"."id") =
                   ((("__subs"."result_vars"#>>ARRAY['query', 'id']))::integer)) ) AS "_root.base"
  ...
) AS "__fld_resp" ON ('true')
```

`$1` は購読のIDの配列、 `$2` は購読ごとの変数の配列です。
`UNNEST` がこの2つを購読1件につき1行の表にし、 `LATERAL` の中のクエリが行ごとの変数で記事を絞ります。
結果もその行ごとに返ります。

# 1本のSQLの速さ

生成されるSQLは長いので、手で書いたSQLより遅くならないのかを測りました。
データは著者1万件、記事20万件、コメント100万件で、外部キーの列にはindexを張っています。
roleはadminで、HasuraとPostgreSQLはDockerのコンテナで動かし、CPUをそれぞれ2コアに制限しました。

測ったクエリは3つです。

-   Aは「GraphQLとSQLの対応」の節のクエリで、記事20件に著者とコメント5件を付けます。
-   Bは記事5万件に著者を付けます。
-   Cは著者2,000人に、その記事4万件と、記事のコメント20万件を入れ子で付けます。

手書きのSQLは、JOINと `json_build_object` で同じデータを返すように書きました。
次の表は、それぞれのSQLをpsqlで15回実行した時間の中央値です。

<table border="2" cellspacing="0" cellpadding="6" rules="groups" frame="hsides">

<colgroup>
<col  class="org-left" />

<col  class="org-left" />

<col  class="org-left" />

<col  class="org-left" />
</colgroup>
<thead>
<tr>
<th scope="col" class="org-left">クエリ</th>
<th scope="col" class="org-left">応答の大きさ</th>
<th scope="col" class="org-left">HasuraのSQL</th>
<th scope="col" class="org-left">手書きのSQL</th>
</tr>
</thead>
<tbody>
<tr>
<td class="org-left">A</td>
<td class="org-left">4.8KB</td>
<td class="org-left">1.7ms</td>
<td class="org-left">1.5ms</td>
</tr>

<tr>
<td class="org-left">B</td>
<td class="org-left">3.4MB</td>
<td class="org-left">71.7ms</td>
<td class="org-left">81.4ms</td>
</tr>

<tr>
<td class="org-left">C</td>
<td class="org-left">8.4MB</td>
<td class="org-left">689ms</td>
<td class="org-left">358ms</td>
</tr>
</tbody>
</table>

Aの差は0.2msで、15回の測定の範囲は重なっています。
BはHasuraのSQLのほうが速く終わりました。
Cだけは、手書きのおよそ2倍の時間がかかっています。

Cが遅いのは、PostgreSQLがrelationshipの副問い合わせを親の行ごとに実行したからです。
Cの `EXPLAIN (ANALYZE)` から、コストと時間の表示を省いて次の行を抜き出しました。
`loops` は実行した回数です。
PostgreSQLは記事のテーブルを2,000回、コメントのテーブルを4万回引いています。

```text
->  Aggregate  (rows=1 loops=2000)
      ->  Nested Loop Left Join  (rows=20 loops=2000)
            ->  Bitmap Heap Scan on article  (rows=20 loops=2000)
            ->  Aggregate  (rows=1 loops=40000)
                  ->  Bitmap Heap Scan on comment  (rows=5 loops=40000)
```

手書きのSQLでは、PostgreSQLは3つのテーブルをHash Joinで結合し、コメントのテーブルを1回だけ読みました。

Cのような一括取得は、入れ子をやめてroot fieldを3つ並べると速くなります。

```graphql
query D {
  author(limit: 2000, order_by: {id: asc}) { id name }
  article(where: {author_id: {_lte: 2000}}) { id title author_id }
  comment(where: {article: {author_id: {_lte: 2000}}}) { article_id body }
}
```

`comment` の `where` でrelationshipを使うと、SQLでは `EXISTS` の副問い合わせになり、PostgreSQLはHash Joinを選びました。
クライアントが `author_id` と `article_id` を使って入れ子を組み立てます。
この書き方を使えるのは、親を選ぶ条件を子の `where` にも書けるときです。
このデータでは著者のidが1から順に並ぶので、 `author_id` が2000以下という条件で、先頭の2,000人を選ぶ `limit: 2000` と同じ著者を選べました。

手書きのSQLを[Native Query](https://hasura.io/docs/2.0/schema/postgres/native-queries/)としてHasuraに登録する方法もあります。
この方法では、記事とコメントが `json` 型の1つのフィールドになり、その中の項目をGraphQLで選べなくなります。

次の表は、HasuraにHTTPでクエリを送って15回測った時間の中央値です。

<table border="2" cellspacing="0" cellpadding="6" rules="groups" frame="hsides">

<colgroup>
<col  class="org-left" />

<col  class="org-left" />

<col  class="org-left" />
</colgroup>
<thead>
<tr>
<th scope="col" class="org-left">取り方</th>
<th scope="col" class="org-left">時間</th>
<th scope="col" class="org-left">応答の大きさ</th>
</tr>
</thead>
<tbody>
<tr>
<td class="org-left">入れ子</td>
<td class="org-left">699ms</td>
<td class="org-left">8.4MB</td>
</tr>

<tr>
<td class="org-left">root fieldを分ける</td>
<td class="org-left">280ms</td>
<td class="org-left">12.5MB</td>
</tr>

<tr>
<td class="org-left">Native Query</td>
<td class="org-left">375ms</td>
<td class="org-left">9.1MB</td>
</tr>
</tbody>
</table>

画面に表示するページ単位のクエリでは、生成されるSQLの長さは速さに影響しませんでした。
書き直したほうがよいのは、エクスポートや集計のように、親と子を数万件まとめて取るクエリです。

# 調べ方

権限の式を入れたクエリも、購読も、最後は1本のSQLになっていました。
Hasuraの動きで分からないところは、Explain APIが返すSQLを読むと確かめられます。
