Conao3 Notes

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が実際に生成したものです。

構成

img

どの構成でも動くのは、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件の流れ

img

クライアントがクエリを送ると、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の改行と字下げは私が足しました。

img

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件でした。

購読

img

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を読むと確かめられます。