登録済みクエリ

概要

登録済みクエリは、GitLab のチームメンバーが、再利用可能な SQL クエリを、ドキュメントとテストを備えたビューとして少ない手間でデータウェアハウスに配置できる、データチームのサービスです。アドホックなクエリをローカルで管理したり、完全なデータモデルを依頼したりする代わりに、クエリを登録してウェアハウスで安定して利用できます。通常、依頼を提出してから 24 時間以内に利用可能になります。

登録済みクエリがウェアハウス全体のアーキテクチャでどのように位置付けられるかは、エンタープライズデータウェアハウスのページを参照してください。

登録済みクエリの位置付け

再利用可能なロジックを配置できる PROD の 3 つの層のうち、登録済みクエリはその 1 つです。各層では、対応の速さと厳密さの間にトレードオフがあります。

まずレジストリから始め、クエリが昇格に値するものになったら上の層に移す、というのがよい目安です。

前提条件

登録済みクエリを依頼する前に、自分の担当部門の対象スキーマがすでに存在している必要があります。新しい部門別スキーマの作成と権限の設定は、このワークフローの対象外です。Standard Data Team Issueを作成し、別途手配する必要があります。チームのスキーマがまだない場合は、デフォルトの general スキーマを使ってください。

スキーマの例を以下に示します。

正式な一覧は、dbt_project.ymlの query_registry ブロックにあります。存在しないスキーマを指定すると、フローは停止し、有効な選択肢を Issue に列挙します。

メリット

• 信頼性。登録済みクエリはデータチームが監視します。上流で何かが壊れた場合、データチームが把握して修正できます。クエリを把握済みのモデルとして扱うことで、内部の変更によってデータチームが意図せず壊す可能性も低くなります。
• テスト可能性。モデルとして扱うことで基本的なテストを適用でき、データが予期しない形で変化した際に早期に検知できます。
• スケーラビリティ。ほかのチームメンバーも同じクエリを必要とする場合、ドキュメント付きのビューとしてウェアハウスに配置することが、最も簡単な共有方法です。
• 透明性とデータリネージ。ロジックは MR の履歴とともにバージョン管理され、Atlan などのデータリネージツールで上流のソースまで追跡できます。
• AI とツールへの対応。説明と列のドキュメントは、Snowflake にオブジェクトのコメントとして永続化されるため、AI エージェント、Snowflake Cortex、ほかの BI ツールがビューを発見し、理解できます。
• 移植性。ウェアハウス内のロジックは、レポートツールを変更しても作り直す必要がありません。

主なユースケース

BI ツールのカスタム SQL

BI ツールに埋め込まれたカスタム SQL は、データスタックのほかの部分からは見えません。登録すると、以下のメリットがあります。

• 複数のワークブックにコピーされたほぼ同一のカスタム SQL を、統制された 1 つのビューに置き換えられる。
• Analytics Engineers が依存関係を把握でき、上流の変更時にワークブックを壊すことなく、その依存関係を考慮できる。
• カスタム SQL よりも dbt ビューをはるかに確実に追跡できる、Atlan のデータリネージを利用できる。
• Tableau Desktop で知らないうちに編集する代わりに、ロジックの変更をレビューし、バージョン管理できる。
• ロジックを書き直さずに、AI を使ったレポートや、ほかの BI ツールでも再利用できる。
• restricted_safe スキーマのセキュアビューを通じて、SAFE データを一貫して扱える。

Streamlit アプリ

Streamlit アプリの SQL は通常 Python コードに埋め込まれており、検索、レビュー、再利用が困難です。登録すると、以下のメリットがあります。

• アプリのコードを、ドキュメント付きのビューに対する単純な SELECT に減らせる。
• アプリを再デプロイせずに、MR を通じてロジックを修正できる。
• ほかのアプリやツールからも、クエリを確認し、再利用できる。
• CODEOWNERS によって、担当部門が明確になる。

アプリのオーナーロールには、レジストリスキーマへの SELECT 権限が必要です。アクセスを参照してください。

このサービスを利用する場合

次の場合に登録済みクエリを利用してください。

• 繰り返し実行するクエリがあり、信頼性を高め、ほかの人も利用できるようにしたい場合。
• ビューでユースケースに十分なパフォーマンスが得られる場合。
• 上流の変更によるクエリの不具合を、データチームに監視してもらいたい場合。
• 結果に基本的なデータ品質テストを適用したい場合。

このサービスを利用しない場合

• ビューを超えるパフォーマンスが必要な場合。クエリの性能要件を満たすためにマテリアライズされたテーブルが必要な場合は、ワークスペーステーブルやモデリング済みテーブルの作成など、データチームのほかのサービスを利用してください。
• その上にほかのモデルを構築する場合。登録済みクエリは、ほかの dbt モデルから参照（ref()）できません。下流のモデルを構築する必要がある場合は、完全なデータモデル開発プロセスを使ってください。
• 全社で認定された指標を定義する場合。公式な全社指標を定義するロジックは、完全な開発プロセスを経て PROD.COMMON に配置する必要があります。

依頼方法

1. 登録済みクエリの Issue テンプレートを使って Issue を作成します。
2. Issue に以下を記載します。
   • 登録したい SQL クエリのテキスト。
   • 結果に SAFE データが含まれるかどうか（必須。これにより、クエリを配置するスキーマが決まります）。
   • 最終レビューとマージを担当するメンテナーの GitLab ユーザー名（必須）。
   • 任意で、担当部門のスキーマキー（デフォルトは general）。
   • 任意で、レビュアーの GitLab ユーザー名（デフォルトは Issue の作成者）。
   • 任意で、コードオーナーとして登録されることを希望するかどうか（登録すると、今後の変更を承認する必要があります）。
   • 任意で、一意性テストに使う列または列のリスト。
3. Issue をデータチームの開発者にアサインします。
4. データチームから MR の準備ができたと Issue で通知されたら、レビューして承認します。

依頼後の流れ

Issue がアサインされると、Duo フローが以下を行います。

1. Config と SQL を解析し、検証します。必須項目が不足しているか無効な場合は、Issue にコメントし、停止します。
2. 既存の登録済みクエリと大きく重複していないかを確認します。よく似たクエリがあれば、リンクをコメントして停止するため、それを再利用するか、違いを明確にできます。
3. ブランチを作成し、rq_<name>.sql ファイル、schema.yml の項目、ドキュメントを作成または更新します。
4. SQLFluff でリントし、dbt parse と dbt compile を実行し、最大 3 回まで自動的にエラーの修正を試みます。
5. SQL スタイルガイドと Snowflake のガイドラインに照らしてセルフレビューを行い、スタイルの問題を修正し、パフォーマンス上の注意点を MR のコメントとして指摘します。
6. MR を作成し、指定されたレビュアーとメンテナーをアサインします。
7. MR のリンクを Issue にコメントします。

メンテナーがマージすると、deploy_query_registry CI ジョブが PROD の登録済みクエリを再構築し、クエリが利用可能になります。

セルフサービスでの MR 作成

gitlab-data/analytics プロジェクトで Developer 権限を持つチームメンバーは、dbt Registered Query Changes MR テンプレートを使って直接 MR を作成できます。このページに記載するファイル構成、命名、ドキュメントの規約に従ってください。レビューと承認には、同じルールが適用されます。

設定オプション

必須

任意

レビューと承認

• CODEOWNERSの [Query Registry] セクションで、query_registry ディレクトリをデータチームのメンバーに割り当てます。
• Issue にコードオーナーが指定されている場合、フローはそのクエリに対するファイル単位の CODEOWNERS の項目を追加します。
• マージ前にメンテナーの承認が必要です。

アクセス

登録済みクエリの読み取りには、ほかの PROD データと同じ Snowflake ロールを使います。restricted_safe スキーマのビューはセキュアビューであり、SAFE アクセスが必要です。サービスアカウント、Tableau 接続、Streamlit アプリのオーナーロールには、該当するレジストリスキーマへの SELECT 権限が必要です。

制約

• すべての登録済みクエリは ビュー としてマテリアライズされます。これにより、本番環境の dbt の実行を中断せずに継続的にデプロイできます。
• すべてのファイルに rq_ プレフィックスを使います（例として rq_my_query.sql）。これは監査に役立ち、これらのオブジェクトに潜在的な制約があることをユーザーに示します。
• 登録済みクエリは、ウェアハウスのほかの部分から分離された 独立したスキーマ に配置されます。使用するスキーマは、クエリが SAFE かどうかによって決まります。専用のワークスペースがまだないチームには、デフォルトとして汎用スキーマが用意されています。
• 登録済みクエリは、ほかの dbt モデルから 参照できません（ref()）。これを防ぐために、専用のプライベートな dbt グループに配置されます。
• 90 日 を超えて使われていないクエリは、四半期ごとの監査で削除の対象となります。
• 新しい依頼への対応時間の目安は 約 24 時間 です。

リポジトリ構造

登録済みクエリのファイルは、query_registry ディレクトリの下に、部門と SAFE ステータス別に整理されます。

query_registry/
  <function>/
    restricted_safe/
      rq_<name>.sql
    rq_<name>.sql

SAFE クエリは、該当部門のディレクトリ内にある restricted_safe/ に配置されます。SAFE ではないクエリは、部門のディレクトリに直接配置されます。

ページのソースコードを見る - ページの編集 - please contribute.