テーブルの分析情報を生成する

このドキュメントでは、BigQuery テーブル、BigLake テーブル、外部テーブルのテーブル分析情報を生成する方法について説明します。テーブル分析情報は、テーブルのメタデータに基づいて自然言語の質問と SQL クエリを生成することで、単一のテーブル内のデータを理解するのに役立ちます。

テーブルの分析情報を使用すると、複雑なクエリを作成しなくても、新しいテーブルや見慣れないテーブルの構造とコンテンツをすばやく把握できるため、データ探索を迅速に行うことができます。自然言語の質問に基づいて SQL クエリを生成することもできるため、クエリを手動で作成するのに必要な時間と労力を削減できます。テーブルの分析情報は、SQL を使用しないユーザーが自然言語クエリを通じてデータを理解し、分析するうえでも役立ちます。

テーブルとデータセットの分析情報の概要については、データ分析情報の概要をご覧ください。

テーブルのデータ分析情報を生成するモード

BigQuery では、テーブルの分析情報を生成する際に次の 2 つのモードが用意されています。

モード	説明	用途
生成して公開（プレビュー）	生成されたテーブルの分析情報をメタデータアスペクトとして Dataplex Universal Catalog で保持します。公開するには、必要な権限が付与されている必要があります。[生成して公開] を使用すると、次のアクションが行われます。テーブルと列の説明を Dataplex Universal Catalog に保存します。クエリと質問の提案を再利用可能なアスペクトとしてキャプチャします。公開された分析情報に、適切な Dataplex Universal Catalog アクセス権を持つすべてのユーザーがアクセスできるようにし、組織で知識を共有できるようにします。 Dataplex Universal Catalog 内で説明を直接編集して保存できます。	このモードは、永続化して再利用できる全社的なデータドキュメントや、カタログ主導のガバナンスワークフローを構築する場合に使用します。
公開せずに生成	説明、自然言語の質問、SQL クエリなどのテーブル分析情報をオンデマンドで作成します。[公開せずに生成] を選択すると、分析情報は Dataplex Universal Catalog に公開されません。	このモードは、アドホックな探索をすばやく行う場合に使用し、カタログが煩雑になるのを防ぎます。

モード

説明

用途

生成して公開（プレビュー）

生成されたテーブルの分析情報をメタデータアスペクトとして Dataplex Universal Catalog で保持します。公開するには、必要な権限が付与されている必要があります。[生成して公開] を使用すると、次のアクションが行われます。

テーブルと列の説明を Dataplex Universal Catalog に保存します。
クエリと質問の提案を再利用可能なアスペクトとしてキャプチャします。
公開された分析情報に、適切な Dataplex Universal Catalog アクセス権を持つすべてのユーザーがアクセスできるようにし、組織で知識を共有できるようにします。
Dataplex Universal Catalog 内で説明を直接編集して保存できます。

このモードは、永続化して再利用できる全社的なデータドキュメントや、カタログ主導のガバナンスワークフローを構築する場合に使用します。

公開せずに生成

説明、自然言語の質問、SQL クエリなどのテーブル分析情報をオンデマンドで作成します。[公開せずに生成] を選択すると、分析情報は Dataplex Universal Catalog に公開されません。

このモードは、アドホックな探索をすばやく行う場合に使用し、カタログが煩雑になるのを防ぎます。

始める前に

データ分析情報は Gemini in BigQuery を使用して生成されます。分析情報の生成を開始するには、まず Gemini in BigQuery を設定する必要があります。

API を有効にする

データ分析情報を使用するには、プロジェクトで Dataplex API、BigQuery API、Gemini for Google Cloud API を有効にします。

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

Gemini for Google Cloud API の有効化の詳細については、 Google Cloud プロジェクトで Gemini for Google Cloud API を有効にするをご覧ください。

ロールと権限

データ分析情報を作成、管理、取得するには、次の Identity and Access Management（IAM）ロールを付与するよう管理者に依頼してください。

分析情報を生成するプロジェクトに対する Dataplex Universal Catalog DataScan 編集者（roles/dataplex.dataScanEditor）または Dataplex Universal Catalog DataScan 管理者（roles/dataplex.dataScanAdmin）。
分析情報を生成する BigQuery テーブルに対する BigQuery データ閲覧者（roles/bigquery.dataViewer）
分析情報を生成する BigQuery テーブルに対する BigQuery データ編集者（roles/bigquery.dataEditor）
分析情報を生成するプロジェクトに対する BigQuery ユーザー（roles/bigquery.user）または BigQuery Studio ユーザー（roles/bigquery.studioUser）。

生成された分析情報への読み取り専用アクセス権を取得するには、次の IAM ロールを付与するよう管理者に依頼してください。

分析情報を表示する BigQuery テーブルを含むプロジェクトに対する Dataplex Universal Catalog DataScan データ閲覧者（roles/dataplex.dataScanDataViewer）。

データ分析情報を Dataplex Universal Catalog に公開するには、管理者に依頼して、リソースの次の IAM ロールを付与してもらってください。

説明をアスペクトとして公開する: Dataplex Universal Catalog Catalog 編集者（roles/dataplex.catalogEditor）
クエリをアスペクトとして公開する: Dataplex Universal Catalog エントリ / エントリリンクオーナー（roles/dataplex.entryOwner）

API を有効にするには、管理者に依頼して、次の IAM ロールを付与してもらってください。

分析情報を生成するプロジェクトに対する Service Usage 管理者（roles/serviceusage.serviceUsageAdmin）。

ロールの付与については、プロジェクト、フォルダ、組織へのアクセス権の管理をご覧ください。

必要な権限は、カスタムロールや他の事前定義ロールから取得することもできます。分析情報を生成するために必要な正確な権限については、「必要な権限」セクションを開いてください。

必要な権限

bigquery.jobs.create
bigquery.tables.get
bigquery.tables.getData
dataplex.datascans.create
dataplex.datascans.get
dataplex.datascans.getData
dataplex.datascans.run

BigQuery テーブルの分析情報を生成する

BigQuery テーブルの分析情報を生成するには、Google Cloud コンソールまたは Dataplex Universal Catalog の DataScans API でサポートされている DATA_DOCUMENTATION スキャンタイプを使用します。これらのスキャンでは、メタデータ、データ探索用の SQL クエリ、スキーマの説明、テーブルレベルの概要が生成されます。

コンソール

BigQuery テーブルの分析情報を生成するには、BigQuery Studio を使用して BigQuery のテーブルエントリにアクセスする必要があります。

Google Cloud コンソールで、[BigQuery Studio] に移動します。

[BigQuery Studio] に移動
[エクスプローラ] ペインで、プロジェクト、データセット、分析情報を生成するテーブルを選択します。
[分析情報] タブをクリックします。タブが空の場合、このテーブルの分析情報はまだ生成されていません。
分析情報を生成して Dataplex Universal Catalog に公開するには、[生成して公開]（プレビュー）をクリックします。

Dataplex Universal Catalog に公開せずに分析情報を生成するには、[公開せずに生成] をクリックします。

[生成して公開] モードと [公開せずに生成] モードの違いについては、分析情報を生成するモードをご覧ください。
分析情報を生成するリージョンを選択し、[生成] をクリックします。

分析情報が生成されるまで数分かかります。

テーブルの公開されているデータプロファイリングの結果が利用可能な場合は、それを使用して分析情報を生成します。そうでない場合は、列名と説明に基づいて分析情報が生成されます。詳細については、生成された分析情報を改善するためのベストプラクティスをご覧ください。
[分析情報] タブで、生成された自然言語の質問を確認します。
質問に回答する SQL クエリを表示するには、質問をクリックします。
BigQuery でクエリを開くには、[クエリにコピー] をクリックします。
フォローアップの質問を行うには、次の手順を行います。
1. [追加で質問する] をクリックします。クエリが新しいデータキャンバスで開きます。
2. [実行]、[これらの結果に対してクエリを実行する] の順にクリックします。
3. フォローアップの質問をするには、[自然言語] プロンプトフィールドにプロンプトを入力するか、クエリエディタで SQL を編集します。
新しいクエリのセットを生成するには、[分析情報を生成] をクリックして、パイプラインを再度トリガーします。

テーブルの分析情報を生成すると、dataplex.datascans.getData 権限とテーブルへのアクセス権を持つすべてのユーザーがその分析情報を表示できます。

REST

分析情報をプログラムで生成するには、Dataplex Universal Catalog の DataScans API を使用します。その方法は次のとおりです。

省略可: テーブルのデータプロファイルスキャンを作成する
BigQuery テーブルのデータドキュメントデータスキャンを生成する
データドキュメントのスキャンステータスを確認する
データドキュメントスキャン結果を BigQuery テーブルに公開する

省略可: テーブルのデータプロファイルスキャンを作成する

データプロファイルスキャンが存在することで、Gemini のハルシネーションと近似が減ります。これは、出力がデータ内の実際の値に基づいているためです。

データプロファイルスキャンを作成して実行する手順は次のとおりです。

dataScans.create メソッドを使用して、データプロファイルスキャンを作成します。
dataScans.run メソッドを使用してデータプロファイルスキャンを実行します。実行が完了するまで待ちます。
次のデータプロファイリングラベルをテーブルに付加して、スキャン結果を BigQuery テーブルに公開します。
- dataplex-dp-published-scan:DATASCAN_ID
- dataplex-dp-published-project:PROJECT_ID
- dataplex-dp-published-location:LOCATION
詳細については、テーブルとビューにラベルを追加するをご覧ください。

BigQuery テーブルのデータドキュメントデータスキャンを生成する

標準のマネージドスキャンまたは効率化された 1 回限りのスキャンを実行できます。

オプション A: 標準のマネージドスキャン（作成 + 実行）

スキャンリソースを長期にわたって管理する場合は、この方法を使用します。

dataScans.create メソッドを使用して、データドキュメントデータスキャンを作成します。generation_scopes パラメータを使用して、スキーマ、説明、クエリ、またはそれらの組み合わせを含むように生成のスコープをカスタマイズできます。

スキーマ、テーブルの説明、SQL クエリを生成するには、data_documentation_spec を空のままにするか、generation_scopes を ALL に設定します。次に例を示します。
```
gcurl -X POST \
https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/\
dataScans?dataScanId=DATASCAN_ID \
-d '{
  "data": {
    "resource": "//bigquery.googleapis.com/projects/PROJECT_ID/\
datasets/DATASET_ID/tables/TABLE_ID"
  },
  "executionSpec": {
    "trigger": { "onDemand": {} }
  },
  "type": "DATA_DOCUMENTATION",
  "dataDocumentationSpec": {
    "generation_scopes": "ALL"
  }
}'
```
次のように置き換えます。
- PROJECT_ID: データセットが存在する Google Cloudプロジェクトの ID
- LOCATION: データスキャンが実行されるリージョン
- DATASCAN_ID: このスキャンに指定する一意の名前
- DATASET_ID: スキャン対象の BigQuery データセットの ID
- TABLE_ID: スキャンされる BigQuery テーブルの ID

SQL クエリなしでスキーマ、テーブルの説明、列の説明を生成するには、generation_scopes を TABLE_AND_COLUMN_DESCRIPTIONS に設定します。次に例を示します。

gcurl -X POST \
https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/\
dataScans?dataScanId=DATASCAN_ID \
-d '{
  "data": {
    "resource": "//bigquery.googleapis.com/projects/PROJECT_ID/\
datasets/DATASET_ID/tables/TABLE_ID"
  },
  "executionSpec": {
    "trigger": { "onDemand": {} }
  },
  "type": "DATA_DOCUMENTATION",
  "dataDocumentationSpec": {
    "generation_scopes": "TABLE_AND_COLUMN_DESCRIPTIONS"
  }
}'

説明なしで SQL クエリを生成するには、generation_scopes を SQL_QUERIES に設定します。次に例を示します。

gcurl -X POST \
https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/\
dataScans?dataScanId=DATASCAN_ID \
-d '{
  "data": {
    "resource": "//bigquery.googleapis.com/projects/PROJECT_ID/\
datasets/DATASET_ID/tables/TABLE_ID"
  },
  "executionSpec": {
    "trigger": { "onDemand": {} }
  },
  "type": "DATA_DOCUMENTATION",
  "dataDocumentationSpec": {
    "generation_scopes": "SQL_QUERIES"
  }
}'

dataScans.run メソッドを使用して、データドキュメントスキャンジョブを開始します。

例:
```
gcurl -X POST \
https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/\
dataScans/DATASCAN_ID:run
```
このリクエストは、初期状態とともに一意のジョブ ID を返します。

オプション B: 1 回限りのスキャン（簡略化）

このメソッドを使用すると、1 回の API 呼び出しでスキャンを開始して完了できます。このメソッドを使用すると、run メソッドを個別に呼び出す必要がなくなり、有効期間（TTL）機能を使用してスキャンリソースを自動的に削除できます。

dataScans.create メソッドを使用してスキャンを作成してトリガーします。次に例を示します。

gcurl -X POST \
"https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/dataScans?\
dataScanId=DATASCAN_ID" \
-d '{
  "data": {
    "resource": "//bigquery.googleapis.com/projects/PROJECT_ID/datasets/DATASET_ID/\
    tables/TABLE_ID"
  },
  "type": "DATA_DOCUMENTATION",
  "dataDocumentationSpec": { "generation_scopes": "ALL" },
  "executionSpec": {
    "trigger": {
      "one_time": {
        "ttl_after_scan_completion": { "seconds": TTL_TIME }
      }
    }
  }
}'

次のように置き換えます。

PROJECT_ID: データセットが存在する Google Cloudプロジェクトの ID
LOCATION: データスキャンが実行されるリージョン
DATASCAN_ID: このスキャンに指定する一意の名前
DATASET_ID: スキャン対象の BigQuery データセットの ID
TABLE_ID: スキャンされる BigQuery テーブルの ID
TTL_TIME: スキャンリソースが自動的に削除されるまでの期間（秒単位）。たとえば、1 時間の場合は 3600

データドキュメントのスキャンのステータスを確認する

dataScans.get メソッドを使用して、スキャンジョブの実行の完了を確認します。

ジョブ ID を使用して、ジョブのステータスを取得します。例:

gcurl -X GET https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/dataScans/DATASCAN_ID/jobs/JOB_ID

ステータスが SUCCEEDED または FAILURE になると、ジョブは完了します。

データドキュメントスキャン結果を BigQuery テーブルに公開する

スキャン結果を BigQuery テーブルに公開するには、次のデータドキュメントラベルをテーブルに付加します。

dataplex-data-documentation-published-scan:DATASCAN_ID
dataplex-data-documentation-published-project:PROJECT_ID
dataplex-data-documentation-published-location:LOCATION

BigQuery 外部テーブルの分析情報を生成する

BigQuery データインサイトは、Cloud Storage にデータがある BigQuery 外部テーブルのインサイトを生成できます。ユーザーと現在のプロジェクトの Dataplex Universal Catalog サービスアカウントには、データを含む Cloud Storage バケットに対するストレージオブジェクト閲覧者ロール（roles/storage.objectViewer）が必要です。詳細については、バケットレベルのポリシーにプリンシパルを追加するをご覧ください。

BigQuery 外部テーブルの分析情報を生成するには、このドキュメントの BigQuery テーブルの分析情報の生成の説明に従います。

BigLake テーブルの分析情報を生成する

BigLake テーブルの分析情報を生成する手順は次のとおりです。

プロジェクトで BigQuery Connection API を有効にします。

BigQuery Connection API を有効にする
BigQuery Connection を作成します。詳細については、接続を管理するをご覧ください。
作成した BigQuery 接続に関連するサービスアカウントに Storage オブジェクト閲覧者（roles/storage.objectViewer）IAM ロールを付与します。

サービスアカウント ID は、接続の詳細から取得できます。
分析情報を生成するには、このドキュメントの BigQuery テーブルの分析情報を生成するセクションの説明に従います。

テーブルと列の説明を生成する

Gemini in BigQuery は、データ分析情報を生成するときに、テーブルと列の説明を自動的に生成します。必要に応じてこれらの説明を編集し、テーブルのメタデータに保存できます。保存された説明は、今後の分析情報を生成するために使用されます。

生成言語を制御する

特定の言語でテーブルと列の説明を生成するように Gemini に指示できます。これを行うには、データ分析を生成する前に、テーブルの既存の説明に短い指示を追加します（たとえば、「フランス語を使用してテーブルと列の説明を生成して」など）。

分析情報を生成すると、Gemini はこのディレクティブを解釈し、リクエストされた言語でメタデータを生成します。Gemini は、新しいテーブルの説明を生成するときに既存のテーブルの説明をコンテキストとして使用するため、このメカニズムが機能します。

サポートされている言語の一覧については、Gemini の言語サポートをご覧ください。

説明を生成する

テーブルと列の説明を生成する手順は次のとおりです。

このドキュメントの関連セクションに記載されている手順に沿って、分析情報を生成します。
[スキーマ] タブをクリックします。
[列の説明を表示] をクリックします。

注: [列の説明を表示] ボタンが表示されない場合は、[データを説明する] をクリックします。このボタンを表示するには、必要に応じてスクロールしてください。

Gemini によって生成されたテーブルの説明と列の説明が表示されます。
生成されたテーブルの説明を編集して保存する手順は次のとおりです。
1. [テーブルの説明] セクションで、[詳細に保存] をクリックします。
2. 現在の説明を生成された説明に置き換えるには、[Copy suggested description] をクリックします。
3. 必要に応じてテーブルの説明を編集し、[詳細に保存] をクリックします。
  
  テーブルの説明はすぐに更新されます。
生成された列の説明を編集して保存する手順は次のとおりです。
1. [列の説明] セクションで、[スキーマに保存] をクリックします。
  
  生成された列の説明は、各列の [新しい説明] フィールドに入力されます。
2. 必要に応じて列の説明を編集し、[保存] をクリックします。
  
  列の説明はすぐに更新されます。
プレビューパネルを閉じるには、（閉じる）をクリックします。

データ分析情報を生成するためのベストプラクティス

生成される分析情報の精度を高めるには、次の推奨事項に沿って操作してください。

包括的な説明を提供します。データセット内のテーブルと列の両方に、明確で詳細な説明があることを確認します。
プロファイリングで分析情報をグラウンディングします。説明がない場合は、生成された分析情報のグラウンディングに役立つように、プロファイルスキャンがデータセット内の各テーブルにリンクされていることを確認します。
ルールを明示的に定義します。分析情報モジュールが関係の生成に影響を与えるために使用する関係やビジネスロジックは、それぞれのテーブルの説明に含めます。

分析情報をデータプロファイリングの結果に反映する

生成 AI において、グラウンディングとは、モデルの出力を検証可能な情報源に紐付ける仕組みを指します。生成されたテーブルの分析情報をデータプロファイリングの結果に関連付けることができます。データプロファイリングは、BigQuery テーブル内の列を分析し、一般的なデータ値やデータの分散などの一般的な統計特性を特定します。

テーブルのデータプロファイリングスキャンを作成するときに、スキャン結果を Google Cloud コンソールの BigQuery ページと Dataplex Universal Catalog ページに公開できます。分析情報は、データプロファイリングの結果を使用して、次の方法でより正確で関連性の高いクエリを作成します。

データプロファイリングの結果を分析して、データ内の興味深いパターン、傾向、外れ値を特定します。
これらのパターン、傾向、外れ値に注目するクエリを生成して、分析情報を発見します。
生成されたクエリをデータプロファイリングの結果と照らし合わせて検証し、クエリが有意義な結果を返すようにします。

データプロファイリングスキャンがないと、次のようになります。

生成されるクエリに不正確な句が含まれる可能性や、意味のない結果が生成される可能性が高くなります。
生成される列の説明は、列名のみに基づいています。

テーブルのデータプロファイリングスキャンが最新であり、結果が BigQuery に公開されていることを確認します。

データプロファイリングの設定を調整して、サンプリングサイズを大きくして、行と列を除外できます。新しいデータプロファイリングスキャンを実行したら、分析情報を再生成します。

データセット内のテーブルにデータプロファイリングの結果がある場合、データセットの分析情報の品質も大幅に向上します。

テーブルの説明を追加する

テーブルで分析する内容を記述した詳細なテーブルの説明は、Gemini in BigQuery でテーブルとデータセットの両方の分析情報について、より関連性の高い分析情報を生成するのに役立ちます。テーブルの説明を追加したら、分析情報を再生成します。

たとえば、テーブルデータの分析情報の例で使用されているような telco_churn テーブルに、次の説明を追加できます。

This table tracks customer churn data, including subscription details, tenure,
and service usage, to predict customer churn behavior.

Gemini が生成したテーブルの説明を保存すると、その説明を使用して今後の分析情報が生成されます。

列の説明を追加する

各列の内容や、列同士の関係を説明する列の説明を追加すると、テーブルとデータセットの両方の分析情報の質を高めることができます。テーブルの列の説明を更新したら、分析情報を再作成します。

たとえば、テーブルデータの分析情報の例で使用されているような telco_churn テーブルの特定の列に次の説明を追加できます。

tenure 列の場合:

The number of months the customer has been with the service.

churn 列の場合:

Whether the customer has stopped using the service. TRUE indicates the customer
no longer uses the service, FALSE indicates the customer is active.

Gemini が生成した列の説明を保存すると、その説明は今後の分析情報の生成に使用されます。

次のステップ

データ分析情報の概要について学習する。
データセットの分析情報を生成する方法を学習する。
Dataplex Universal Catalog データプロファイリングの詳細を学習する。