HasuraがGraphQLのクエリを1本のSQLにする仕組み
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が実際に生成したものです。
構成
どの構成でも動くのは、HasuraのコンテナとPostgreSQLの2つです。権限の判定、GraphQLのschemaの生成、GraphQLからSQLへの変換は、どのリクエストでも動きます。図では青い部品です。
APIの形を決めるのはmetadataです。metadataは、公開するテーブル、テーブルのあいだのrelationship、roleごとの権限の定義で、ConsoleやCLI、Metadata APIから登録します。HasuraがmetadataをJSONで保存するのはPostgreSQLの hdb_catalog というschemaです。公式のドキュメントによると、テーブルを1つ登録すると、Hasuraはその型を作ります。検索、主キーでの取得、集計、追加、更新、削除、購読のフィールドも作ります。
図の点線の部品が動くのは設定したときだけです。認証はHasuraの外で行います。HasuraはJWTかwebhookでroleとsession variableを受け取ります。ActionsとRemote Schemasは外部のAPIをschemaに加える機能で、Event Triggersは行の変更をwebhookに送る機能です。HasuraはMySQLやOracleなどには、data connector agentというサービスを経由してつなぎます。
クエリ1件の流れ
クライアントがクエリを送ると、Hasuraは図の②から⑤の順でSQLを作ります。 ②から⑤の段階は、Hasuraの設計の文書に書かれています。 ②で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に送りました。Explain APIは、Hasuraが生成するSQLを返すAPIです。次の図は、上が送ったクエリ、下が返ってきたSQLで、SQLの改行と字下げは私が足しました。
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に送りました。記事の副問い合わせは次のように変わりました。
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 で加わりました。
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件でした。
購読
subscriptionも1本のSQLにする同じ仕組みで動きます。ここで説明するのは、Hasuraのsubscriptionのうちlive queryと呼ばれる方式です。公式のドキュメントによると、Hasuraは購読されたクエリを一定の間隔で再実行し、結果が前回から変わった購読にだけ新しい結果を送ります。間隔の既定値は1秒です。Hasuraはroleと形が同じで変数だけが違う購読を、100件まで1本のSQLにまとめます。
idを変数にして記事を1件購読するクエリをExplain APIに送ると、次の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回実行した時間の中央値です。
| クエリ | 応答の大きさ | HasuraのSQL | 手書きのSQL |
|---|---|---|---|
| A | 4.8KB | 1.7ms | 1.5ms |
| B | 3.4MB | 71.7ms | 81.4ms |
| C | 8.4MB | 689ms | 358ms |
Aの差は0.2msで、15回の測定の範囲は重なっています。BはHasuraのSQLのほうが速く終わりました。Cだけは、手書きのおよそ2倍の時間がかかっています。
Cが遅いのは、PostgreSQLがrelationshipの副問い合わせを親の行ごとに実行したからです。Cの EXPLAIN (ANALYZE) から、コストと時間の表示を省いて次の行を抜き出しました。loops は実行した回数です。PostgreSQLは記事のテーブルを2,000回、コメントのテーブルを4万回引いています。
-> 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つ並べると速くなります。
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としてHasuraに登録する方法もあります。この方法では、記事とコメントが json 型の1つのフィールドになり、その中の項目をGraphQLで選べなくなります。
次の表は、HasuraにHTTPでクエリを送って15回測った時間の中央値です。
| 取り方 | 時間 | 応答の大きさ |
|---|---|---|
| 入れ子 | 699ms | 8.4MB |
| root fieldを分ける | 280ms | 12.5MB |
| Native Query | 375ms | 9.1MB |
画面に表示するページ単位のクエリでは、生成されるSQLの長さは速さに影響しませんでした。書き直したほうがよいのは、エクスポートや集計のように、親と子を数万件まとめて取るクエリです。
調べ方
権限の式を入れたクエリも、購読も、最後は1本のSQLになっていました。Hasuraの動きで分からないところは、Explain APIが返すSQLを読むと確かめられます。