クエリ ベータ

クエリ（保存済クエリ と呼ぶ場合もあります）は、コネクション 単位で再利用する SQL を保存する機能です。複数のノートブックから同じ SQL を参照したり、クエリ画面で直接実行したりできます。グローバルナビ > クエリ から利用できます。

専用のリソースロールはありません。操作可否は紐づくコネクションの権限に準じます。詳細は クエリの権限 を参照してください。

INFO

この機能はベータです。仕様は予告なく変更される場合があります。

主な機能

• SQL の保存と実行: クエリ画面で編集・保存し、実行 から SQL を発行できます
• フォルダによる整理: コネクション配下でクエリを整理します
• ノートブック連携: SQLブロックからの SQLを保存、および / による保存済クエリの参照ができます（SQLブロック）
• カタログ の クエリ タブ: メタデータ（説明・タグ・カラム・参照・人気度など）を確認・編集できます
• ワークフロー: 保存済クエリをスケジュール実行できます
• タグ: クエリタグを付与できます。定義はワークスペース設定で管理します
• テーブル関数として書き出す: BigQuery の保存済クエリを、データセット上のテーブル関数として書き出せます

作成

クエリ画面から

1. グローバルナビ > クエリ を開きます
2. クエリを作成 をクリックします（下書きが開き、コネクションを選択できます）
3. SQL を編集し、保存 で名前・コネクション・フォルダを指定して本保存します

左サイドバーのコネクションまたはフォルダから クエリを作成 すると、その位置に空のクエリを直接作成できます。フォルダの作成・移動も左サイドバーから行えます。

ノートブックから

1. ノートブックの SQLブロック右上メニューから SQLを保存 を選びます
2. 名前・コネクション・フォルダを指定して保存します

保存時の挙動は次のとおりです。

• 他の SQLブロック参照・保存済クエリ参照は、展開済みの SQL 文字列として保存されます
• パラメータは、その時点の値に置き換えて保存されます
• 説明には、元ノートブックへのリンク（Source notebook: ...）が自動で入ります
• 直近の実行結果がある場合、カラム情報も保存できます

編集・実行・管理

操作	説明
保存 / 名前を付けて保存	SQL・名前などを更新します。別名保存もできます
実行	紐づくコネクションの認証情報で SQL を実行します
スター	一覧の スター タブやクイック検索向けに付与・解除します
説明・タグ	クエリ詳細、または カタログ から編集します
カラム	説明やタグを付与できます（実行結果のカラム情報を基に管理します）
ノートブックを作成	当該クエリを含むノートブックを新規作成します
移動・削除	左サイドバーや詳細メニューから行います。移動は同一コネクション内のみです
履歴	過去バージョンを閲覧できます
テーブル関数として書き出す	BigQuery の保存済クエリをテーブル関数として書き出します

保存後は、所属コネクションを変更できません。コネクションを変えたい場合は、名前を付けて保存 などで別クエリとして作り直してください。

テーブル関数の書き出し

BigQuery コネクションに本保存したクエリを、BigQuery のテーブル関数として書き出せます。下書きと BigQuery 以外のコネクションでは、メニューは表示されません。

書き出しに使う SQL は、保存済みの SQL です。エディタ上の未保存の内容は使いません。同名のテーブル関数がある場合は上書きされます。

テーブル関数として書き出す

次の場合は テーブル関数として書き出す を選べません。

• コネクションの実行権限がない
• カラム情報がない
• 未保存の変更がある

1. グローバルナビ > クエリ を開き、対象のクエリを開きます
2. ヘッダの 保存 メニューから テーブル関数として書き出す をクリックします
3. プロジェクト（初期値はコネクションのプロジェクトID）・データセット・関数名（初期値はクエリ名から生成）を指定します
4. 書き出す をクリックします

ノートブックとの連携

• 参照: SQLブロックで / を入力し、保存済クエリ から挿入します。挿入時点の SQL が埋め込まれます。実行時は埋め込み SQL が使われます。ソースのクエリが変わると参照チップに 差分あり と表示され、埋め込みクエリを更新 で反映できます
• 保存: SQLを保存 では、参照やパラメータは展開・置換された固定 SQL になります

ノートブック側の詳細は SQLブロック を参照してください。

制約

• 所属コネクションの変更はできません（保存後）
• クエリ・フォルダの移動は同一コネクション内に限ります
• フォルダの階層は最大 5 です（制約と上限値）
• フォルダを削除すると、配下のクエリも削除されます
• クエリ数の上限はご契約内容により異なります（制約と上限値。グローバルナビ > ワークスペース設定 > 使用量 で確認できます）
• コネクションを削除 すると、関連する保存済クエリも削除されます
• 引数のないテーブル関数として書き出します
• SQL は SELECT または WITH で始まる必要があります。複数のステートメントは書けません
• 書き出しには、コネクションの認証情報が対象データセットでテーブル関数を作成・置換できる必要があります
• 書き出しに成功すると、書き出し先を表示します
• 書き出しに失敗すると、ダイアログに理由を表示します
• テーブル関数の書き出し履歴は、BigQuery で実行した成功と失敗の最新 50 件です（制約と上限値）。実行前に拒否された場合は残りません
• 履歴は 右サイドバー > このクエリについて の エクスポート で、書き出し先ごとに日時・実行者・DDL を確認できます
• 同じ書き出しを短時間に繰り返すと拒否されます
• プロジェクト・データセットは一覧にない ID も入力できます

権限

操作ごとの条件は クエリの権限 を参照してください。閲覧はコネクションの読み取り系、編集・実行・テーブル関数の書き出し・フォルダ操作はコネクションの実行権限が必要です。