登録済みクエリ

概要

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

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

前提条件

登録済みクエリを依頼する前に、担当部門の対象スキーマがデータウェアハウスにすでに存在している必要があります。部門別の新しいスキーマの作成と権限の設定は、このワークフローの対象外であり、別途手配する必要があります。チームのスキーマがまだない場合は、依頼を提出する前にデータチームに連絡し、作成してもらってください。専用の部門別スキーマがまだないチームには、デフォルトとして汎用スキーマを用意しています。

メリット

• 信頼性: 登録済みクエリはデータチームが監視します。上流で何かが壊れた場合、データチームがそれを把握し、修正できます。クエリを把握済みのモデルとして扱うことで、データチームが内部の変更によって意図せず壊す可能性も低くなります。
• テスト可能性: モデルとして扱うことで基本的なテストを適用でき、データが予期しない形で変化したときに早期に検知できます。
• スケーラビリティ: ほかのチームメンバーも同じクエリを必要とする場合、ドキュメント付きのビューとしてウェアハウスに配置することが、最も簡単な共有方法です。

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

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

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

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

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

依頼方法

1. 登録済みクエリの Issue テンプレート （近日公開） を使用して Issue を作成します。
2. Issue に以下を含めます。
   • 登録したい SQL クエリのテキスト。
   • 結果に SAFE データが含まれるかどうか（必須 — これによってクエリを配置するスキーマが決まります）。
   • 任意で、コードオーナーとして登録されることを希望するかどうか（登録されると、今後の変更を承認する必要があります）。
   • 任意で、一意性テストに使用する列または列のリスト。
3. Issue をデータチームの開発者に割り当てます。
4. データチームから MR の準備ができたと Issue で通知されたら、レビューして承認します。

依頼後の流れ

Issue を提出すると、データチームの開発者が以下を行います。

1. クエリを読み、設定を既存のスキーマとディレクトリ構造に照らして確認します。設定が既存のディレクトリに適合しない場合は、Issue で報告します。
2. 依頼内容と大きく重複する既存のクエリやモデルがないか確認します。既存のものとクエリがよく似ている場合は、代替案を報告します。
3. 標準の命名形式を使用して新しいブランチでマージリクエストを作成します。
4. 標準の rq_<name>.sql 命名形式を使用して SQL ファイルを追加または更新し、コードをフォーマット、リント、コンパイルして、エラーを解消します。
5. クエリのドキュメントを生成します。
6. CI ジョブを実行してボットレビューを依頼し、フィードバックに対応します。
7. 最終レビューのためにコードオーナー（設定されている場合）とメンテナーを割り当てます。
8. レビュー用の MR の準備ができたことを Issue で通知します。

メンテナーによるマージ後、CI ジョブが本番環境のすべての登録済みクエリを自動的に再構築し、クエリがすぐに利用可能になります。

設定オプション

必須

任意

制約

• すべての登録済みクエリはビューとしてマテリアライズされます。これにより、本番環境の 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.