生成資料集洞察資訊

控制台

1. 前往 Google Cloud 控制台的「BigQuery Studio」。

   前往 BigQuery Studio

2. 在「Explorer」窗格中，選取要生成洞察資料的專案和資料集。如果是 Iceberg 命名空間，請選取代表目錄命名空間的資料集。

3. 點按「深入分析結果」分頁標籤。

   如果分頁空白，表示尚未產生這個資料集的洞察資訊。

4. 點按「生成」。

5. 選取發布條件：

   • 如要生成洞察資料，並將其永久附加至資產做為中繼資料，請開啟「Publish condition」(發布條件) 切換鈕。這樣一來，機構中的其他使用者就能建立索引、搜尋及查看洞察。

   • 如要在目前的工作階段中暫時生成及查看洞察資料，請關閉「Publish condition」(發布條件) 切換鈕。

   如要進一步瞭解「Generate and publish」(生成並發布) 和「Generate without publishing」(生成但不發布) 模式之間的差異，請參閱「生成資料洞察的模式」。

6. 選用：在「Custom instructions」(自訂指令) 欄位中，提供指引和網域背景資訊，自訂 Gemini 生成洞察資料的方式。

   例如，您可以強制執行命名慣例、指定業務定義，或描述 join 鍵：

   LANGUAGE: Always write column descriptions in uppercase.
   
   DOMAIN_CONTEXT:
   - This dataset supports the Order-to-Cash process for the EMEA commercial
     sales team.
   - Primary consumers are finance analysts and regional sales managers, not
     engineers.
   
   RELATIONSHIPS:
   - returns.order_item_id → order_items.id (one-to-one; use LEFT JOIN to
     preserve unreturned items)
   

7. 如果資料集位於多區域，系統可能會提示您選取要產生洞察資料的區域。請依據要建立洞察資訊掃描作業的多區域，選取相應的區域。

   系統需要幾分鐘才能填入洞察資料。如果資料集中的資料表有資料剖析結果，深入分析的品質就會提升。

生成洞察後，BigQuery 會顯示資料集說明、關係圖、關係資料表，以及跨資料表查詢範例。

REST

如要以程式輔助方式生成洞察資料，請使用 Knowledge Catalog DataScans API。如要這樣做，請按照下列步驟進行：

1. 為 BigQuery 資料集生成資料文件資料掃描作業
2. 查看資料說明文件掃描狀態
3. 確認發布至 Knowledge Catalog

為 BigQuery 資料集產生資料說明文件資料掃描

1. 使用 dataScans.create 方法建立資料說明文件資料掃描作業。您也可以將 catalog_publishing_enabled 參數設為 true，將這些洞察資訊發布至 Knowledge Catalog。

   例如：

   alias gcurl='curl -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json"'
   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"
     },
     "executionSpec": {
       "trigger": { "onDemand": {} }
     },
     "type": "DATA_DOCUMENTATION",
     "dataDocumentationSpec": {
       "catalog_publishing_enabled": true
     }
   }'
   

   更改下列內容：

   • PROJECT_ID：資料集所在的 Google Cloud專案 ID
   • LOCATION：資料掃描作業執行的區域
   • DATASCAN_ID：您為這項掃描作業提供的專屬名稱
   • DATASET_ID：要掃描的 BigQuery 資料集 ID

2. 使用 dataScans.run 方法啟動資料文件掃描工作。

   例如：

   gcurl -X POST \
   https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/\
   dataScans/DATASCAN_ID:run
   

   這項要求會傳回專屬工作 ID 和初始狀態。

查看資料文件掃描狀態

使用 dataScans.get 方法，檢查掃描工作執行作業是否完成。如要擷取完整結果 (包括洞察資料和發布狀態)，請將 view 參數設為 FULL。

使用工作 ID 擷取工作狀態。例如：

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

狀態為 SUCCEEDED 或 FAILURE 時，工作即完成。

如果工作成功，回應的 dataDocumentationResult 欄位會包含生成的洞察資料。

確認發布至 Knowledge Catalog

如果 catalog_publishing_enabled 設為 true，則資料掃描工作完成後，洞察資訊會以非同步方式發布至 Knowledge Catalog。如要確認洞察資料是否已保存，請使用 Dataplex API 檢查資料集的切面。

雖然洞察資料是透過資料集層級的資料掃描產生，但產生的項目連結會儲存在連結的資料表之間。如要驗證這些關係，請使用 lookupEntryLinks 方法，擷取與特定資料表項目相關聯的項目連結。

如要擷取 BigQuery 資料集的中繼資料，請使用 entries.get 方法。如要納入所有面向，請將 view 參數設為 FULL。例如：

gcurl -X GET https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/entryGroups/@bigquery/entries/bigquery.googleapis.com/projects/DATASET_PROJECT_ID/datasets/DATASET_ID?view=FULL

更改下列內容：

• PROJECT_ID：設定資料掃描作業的 Google Cloud專案 ID
• LOCATION：項目群組所在的區域
• DATASET_PROJECT_ID：BigQuery 資料集所在 Google Cloud專案的 ID
• DATASET：BigQuery 資料集的 ID

如果成功發布至 Knowledge Catalog，下列面向會附加至 BigQuery 資料集：

• 說明：包含 AI 生成的資料集說明
• 查詢：包含與資料集相關的 SQL 查詢
• 關係：以資料集中資料表之間的項目連結形式保留