生成表格洞察

控制台

如要為 BigQuery 資料表生成洞察資料，您必須使用 BigQuery Studio 存取 BigQuery 中的資料表項目。

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

   前往 BigQuery Studio

2. 在「Explorer」窗格中，依序選取要生成洞察資料的專案、資料集和資料表。

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. 選取要生成洞察資料的區域，然後點選「生成」。

   系統需要幾分鐘才能填入洞察資料。

   如果資料表有已發布的資料剖析結果，系統會使用這些結果生成洞察。否則，系統會根據資料欄名稱和說明生成洞察資料。詳情請參閱「產生資料洞察的最佳做法」。

8. 在「洞察」分頁中，查看生成的自然語言問題。

9. 如要查看回答問題的 SQL 查詢，請按一下問題。

10. 如要在 BigQuery 中開啟查詢，請按一下「複製到查詢」。

11. 如要提出後續問題，請按照下列步驟操作：

    1. 按一下「繼續提問」，查詢會在新的資料畫布中開啟。

    2. 依序點選「執行」和「查詢這些結果」。

    3. 如要提出後續問題，請在「Natural language」(自然語言) 提示欄位中輸入提示，或在查詢編輯器中編輯 SQL。

12. 如要生成一組新的查詢，請按一下「Generate insights」(生成洞察資料)，然後再次觸發管道。

生成資料表的洞察資料後，凡是具備 dataplex.datascans.getData 權限且可存取資料表的使用者，都能查看這些洞察資料。

REST

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

1. 選用：建立資料表的資料剖析掃描
2. 為 BigQuery 資料表生成資料文件資料掃描
3. 查看資料說明文件掃描狀態
4. 將資料文件掃描結果發布至 BigQuery 資料表

選用：建立資料表的資料剖析掃描作業

資料剖析掃描可確保 Gemini 輸出內容以資料中的實際值為依據，減少幻覺和近似值。

如要建立及執行資料剖析掃描作業，請按照下列步驟操作：

1. 使用 dataScans.create 方法建立資料剖析掃描。

2. 使用 dataScans.run 方法執行資料剖析掃描。等待執行作業完成。

3. 將下列資料剖析標籤附加至資料表，將掃描結果發布至 BigQuery 資料表：

   • dataplex-dp-published-scan:DATASCAN_ID
   • dataplex-dp-published-project:PROJECT_ID
   • dataplex-dp-published-location:LOCATION

   詳情請參閱「為資料表和檢視表新增標籤」。

為 BigQuery 資料表生成資料說明文件資料掃描

您可以選擇執行標準代管掃描，或簡化的一次性掃描。

方法 A：標準代管掃描 (建立 + 執行)

如要長期管理掃描資源，請使用這個方法。

1. 使用 dataScans.create 方法建立資料說明文件資料掃描作業。

您可以使用 generation_scopes 參數自訂生成範圍，納入結構定義、說明、查詢或組合。您也可以將 catalogPublishingEnabled 參數設為 true，將這些洞察資訊發布至 Knowledge Catalog。

• 如要生成結構定義、資料表說明和 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": {
        "generationScopes": "ALL"
        "catalogPublishingEnabled": true
      }
    }'
  

  更改下列內容：

  • 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": {
        "generationScopes": "TABLE_AND_COLUMN_DESCRIPTIONS"
        "catalogPublishingEnabled": true
      }
    }'
  

• 如要生成不含說明的 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": {
        "generationScopes": "SQL_QUERIES"
        "catalogPublishingEnabled": true
      }
    }'
  

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

   例如：

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

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

方法 B：單次掃描 (簡化版)

使用這個方法，只要呼叫一次 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": {
    "generationScopes": "ALL",
    "catalogPublishingEnabled": true
  }
  "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：掃描資源應自動刪除的時間長度 (以秒為單位)，例如 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