管理已儲存的查詢

本文說明如何管理已儲存的查詢和傳統已儲存的查詢，以及如何在 Dataplex Universal Catalog 中管理已儲存查詢的中繼資料。

已儲存的查詢是 BigQuery Studio 程式碼資產，由 Dataform 提供支援。

事前準備

您可以在遷移期間選擇對已遷移的公開或專案傳統已儲存查詢設定 IAM 權限、建立或選取 BigQuery Studio 已儲存查詢，並授予所選的身分與存取權管理 (IAM) 權限給該已儲存查詢。

將公開或專案的傳統已儲存查詢遷移至 BigQuery Studio 已儲存查詢時，請選取 BigQuery Studio 已儲存查詢，將授予該查詢的權限複製到遷移的已儲存查詢。

必要的角色

如要取得管理已儲存查詢所需的權限，請要求管理員在您要管理已儲存查詢的專案中，授予下列 IAM 角色：

如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和機構的存取權」。

這些預先定義的角色具備管理已儲存查詢所需的權限。如要查看確切的必要權限，請展開「必要權限」部分：

所需權限

如要管理已儲存的查詢，必須具備下列權限：

  • 如要在 Google Cloud 控制台中管理 BigQuery Studio 已儲存的查詢： bigquery.config.get, bigquery.jobs.create, dataform.locations., resourcemanager.projects.get, resourcemanager.projects.list, bigquery.readsessions., dataform.repositories., dataform.workspaces.
  • 如要使用 BigQuery API 管理 BigQuery Studio 已儲存的查詢，請按照下列步驟操作： dataform.locations., dataform.repositories., dataform.workspaces.*, resourcemanager.projects.get, resourcemanager.projects.list
  • 如要將專案的傳統版已儲存查詢遷移至 BigQuery Studio 已儲存查詢，請按照下列步驟操作： bigquery.savedqueries.get, bigquery.savedqueries.list, bigquery.savedqueries.update, bigquery.savedqueries.delete, bigquery.savedqueries.create
  • 如要允許已驗證的使用者查看公開存取查詢： dataform.locations.*, dataform.repositories.computeAccessTokenStatus, dataform.repositories.fetchHistory, dataform.repositories.fetchRemoteBranches, dataform.repositories.get, dataform.repositories.getIamPolicy, dataform.repositories.list, dataform.repositories.queryDirectoryContents, dataform.repositories.readFile, dataform.workspaces.fetchFileDiff, dataform.workspaces.fetchFileGitStatuses, dataform.workspaces.fetchGitAheadBehind. dataform.workspaces.get, dataform.workspaces.getIamPolicy, dataform.workspaces.list, dataform.workspaces.queryDirectoryContents, dataform.workspaces.readFile, dataform.workspaces.searchFiles, resourcemanager.projects.get, resourcemanager.projects.list

您或許還可透過自訂角色或其他預先定義的角色取得這些權限。

如要進一步瞭解 BigQuery IAM，請參閱「使用身分與存取權管理功能控管存取權」一文。

如要在 Dataplex Universal Catalog 中管理已儲存的查詢中繼資料，請確認您具備必要的 Dataplex Universal Catalog 角色和 dataform.repositories.get 權限。

共用已儲存的查詢

如要與使用者共用已儲存的查詢，請先授予該使用者已儲存查詢的存取權，然後將他們新增至適當的 IAM 角色。然後產生已儲存查詢的連結，並與使用者共用該連結。

與您共用查詢的使用者只會看到最新版本的查詢。 系統不會在共用查詢中顯示您尚未明確儲存的自動儲存變更。

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

    前往 BigQuery

  2. 在「Explorer」窗格中，展開專案和「Queries」資料夾，以及視需要展開「Shared queries」資料夾。找出並點選要授予存取權的已儲存查詢。

  3. 依序點按「分享」和「管理權限」。

  4. 在「管理權限」窗格中，按一下「新增使用者/群組」。

  5. 在「New principals」(新增主體) 欄位中輸入主體。

  6. 在「角色」清單中，選取下列其中一個角色：

  7. 選用：如要查看完整的角色清單和進階共用設定，請按一下「進階共用設定」。

  8. 按一下 [儲存]。

  9. 如要返回已儲存的查詢資訊，請按一下「關閉」。

  10. 如要產生已儲存查詢的連結，請按一下「分享」圖示 ，然後按一下「取得連結」。

    連結即會複製到剪貼簿。

授予已儲存查詢的公開存取權

如要授予 BigQuery Studio 已儲存查詢的公開存取權，請將已儲存查詢的程式碼檢視者 (roles/dataform.codeViewer) 角色授予 allAuthenticatedUsers 主體。

將 IAM 角色指派給allAuthenticatedUsers主體後，透過 Google 帳戶完成驗證的服務帳戶和所有使用者都會獲得該角色。這包括未連結至 Google Workspace 帳戶或 Cloud Identity 網域的帳戶，例如個人 Gmail 帳戶。未通過驗證的使用者 (如匿名訪客) 不會具有這個識別碼。詳情請參閱「所有已驗證的使用者」。

舉例來說，如果您在sales已儲存的查詢中，將「程式碼檢視者」角色授予 allAuthenticatedUsers，那麼網路上所有已透過 Google 帳戶完成驗證的服務帳戶和使用者，都將擁有sales已儲存查詢的唯讀存取權。

如要授予 BigQuery Studio 已儲存查詢的公開存取權，請按照下列步驟操作：

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

    前往 BigQuery

  2. 在「Explorer」窗格中，展開專案和「Queries」資料夾，以及視需要展開「Shared queries」資料夾。找出要授予公開存取權的已儲存查詢。

  3. 按一下已儲存查詢旁的 「查看動作」，然後依序點選「共用」> 管理權限。

  4. 在「管理權限」窗格中，按一下「新增使用者/群組」。

  5. 在「New principals」(新增主體) 欄位中輸入 allAuthenticatedUsers。

  6. 在「Role」(角色) 清單中，選取「Code Viewer」(程式碼檢視者) 角色。

  7. 按一下 [儲存]。

  8. 如要返回已儲存的查詢資訊，請按一下「關閉」。

禁止公開存取已儲存的查詢

為確保任何 BigQuery Studio 儲存的查詢都不會授予公開存取權，請限制專案中的 allAuthenticatedUsers 主體。

如要在專案中限制 allAuthenticatedUsers，您可以設定 iam.allowedPolicyMemberDomains 政策，並從 allowed_values 清單中移除 allAuthenticatedUsers。

在iam.allowedPolicyMemberDomains政策中限制 allAuthenticatedUsers 後，專案中的任何 IAM 政策都無法使用 allAuthenticatedUsers 主體，因此無法授予所有資源公開存取權，包括 BigQuery Studio 已儲存的查詢。

如要進一步瞭解 iam.allowedPolicyMemberDomains 政策和設定方式，請參閱「依照網域設定身分限制」。

設定預設區域

如果您是第一次建立程式碼資產，請設定程式碼資產的預設區域。程式碼資產建立後，就無法變更區域。

BigQuery Studio 中的所有程式碼資產都使用相同的預設區域。如要設定程式碼資產的預設區域，請按照下列步驟操作：

  1. 前往「BigQuery」頁面

    前往 BigQuery

  2. 在「Explorer」窗格中，找出已啟用程式碼資產的專案。

  3. 按一下專案旁的 「查看動作」，然後按一下「變更預設程式碼區域」。

  4. 「區域」請選取要用於程式碼資產的區域。

  5. 按一下 [選取]。

如需可用區域清單，請參閱 BigQuery Studio 位置。

查看所有已儲存的查詢

如要查看專案中所有已儲存查詢的清單，請按照下列步驟操作：

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

    前往 BigQuery

  2. 在「Explorer」窗格中，點選「Queries」旁邊的「View actions」，然後執行下列其中一項操作：

  • 如要在目前的分頁中開啟清單，請按一下「顯示全部」。
  • 如要在新分頁中開啟清單，請依序點選「全部顯示」 >「新分頁」。
  • 如要在分割分頁中開啟清單，請依序點選「顯示所有項目」 >「分割分頁」。

查看已儲存查詢的中繼資料

如要查看已儲存查詢的中繼資料，請按照下列步驟操作：

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

    前往 BigQuery

  2. 在「Explorer」窗格中，展開專案和「Queries」資料夾，以及視需要展開「Shared queries」資料夾。按一下要查看中繼資料的已儲存查詢名稱。

  3. 按一下「資訊」詳細資料，即可查看已儲存查詢的相關資訊，例如使用的區域和上次修改日期。

使用已儲存的查詢版本

您可以選擇在存放區內或外部建立已儲存的查詢。系統會根據已儲存查詢的位置，以不同方式處理版本控管。

存放區中的已儲存查詢版本控管

存放區是位於 BigQuery 或第三方供應商的 Git 存放區。您可以在存放區中使用「工作區」，對已儲存的查詢執行版本控管。詳情請參閱「使用檔案的版本控管功能」。

在存放區外部儲存查詢版本

請參閱下列各節，瞭解如何查看、比較及還原已儲存查詢的版本。

查看已儲存的查詢版本

如要查看已儲存的查詢版本，請按照下列步驟操作：

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

    前往 BigQuery

  2. 在「Explorer」窗格中，展開專案和「Queries」資料夾，以及視需要展開「Shared queries」資料夾。按一下要查看版本記錄的已儲存查詢名稱。

  3. 按一下「版本記錄」，即可查看已儲存的查詢版本清單，並依日期降序排列。

比較已儲存的查詢版本

如要比較已儲存的查詢版本，請按照下列步驟操作：

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

    前往 BigQuery

  2. 在「Explorer」窗格中，展開專案和「Queries」資料夾，以及視需要展開「Shared queries」資料夾。按一下要比較版本資訊的已儲存查詢名稱。

  3. 按一下 「版本記錄」。

  4. 按一下已儲存查詢版本旁的「查看動作」，然後點選「比較」。 比較窗格隨即開啟，比較您選取的已儲存查詢版本與目前的查詢。

  5. 選用：目前的查詢也會顯示自動儲存的變更。如要明確儲存這些變更，請按一下「覆寫」。

  6. 選用：如要改為在同一窗格中比較版本，請依序點按「比較」和「內嵌」。

還原已儲存的查詢版本

從比較窗格還原時，您可以先比較儲存查詢的先前版本與目前版本，再選擇是否要還原。

  1. 在「Explorer」窗格中，展開專案和「Queries」資料夾，以及視需要展開「Shared queries」資料夾。按一下要還原先前版本的已儲存查詢名稱。
  2. 按一下 「版本記錄」。
  3. 按一下要還原的已儲存查詢版本旁的「查看動作」，然後按一下「比較」。比較窗格隨即開啟，比較您選取的已儲存查詢版本與最新查詢版本，包括任何自動儲存的變更。
  4. 如要在比較後還原先前的已儲存查詢版本，請按一下「還原」。
  5. 按一下「確認」。

下載已儲存的查詢

如要下載已儲存的查詢，請按照下列步驟操作：

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

    前往 BigQuery

  2. 在「Explorer」窗格中，展開專案和「Queries」資料夾，以及視需要展開「Shared queries」資料夾。按一下已儲存查詢的名稱即可開啟。

  3. 點選 [下載]。

刪除已儲存的查詢

如要刪除已儲存的查詢，請按照下列步驟操作：

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

    前往 BigQuery

  2. 在「Explorer」窗格中，展開專案和「Queries」資料夾，以及視需要展開「Shared queries」資料夾。找出要刪除的已儲存查詢。

  3. 按一下已儲存查詢旁的 「查看動作」，然後按一下「刪除」。

  4. 如要確認刪除，請在對話方塊中輸入 delete。

  5. 點選「刪除」。

傳統版已儲存查詢

請參閱下列各節，瞭解如何管理傳統儲存的查詢。

共用傳統版已儲存的查詢

您可以共用已設為專案或公開瀏覽權限的傳統版已儲存查詢。專案層級瀏覽權限可讓具備必要權限的主體檢視、更新或刪除查詢。公開瀏覽權限可讓擁有查詢連結的任何人查看查詢，但無法更新或刪除查詢。

如要與其他使用者共用傳統版已儲存的查詢，請產生並分享傳統版已儲存查詢的連結。

如要執行傳統共用查詢，使用者必須能存取查詢所存取的資料。詳情請參閱「授予資料集存取權」。

如果您打算共用傳統儲存的查詢，請考慮在查詢中加入說明用途的註解。

  1. 在「Explorer」窗格中，展開專案和「(Classic) Queries」資料夾，然後找出要共用的傳統版已儲存查詢。
  2. 按一下查詢旁的「查看動作」，然後點選「取得連結」。
  3. 將連結分享給要授予查詢存取權的使用者。

將傳統版查詢儲存為已儲存的查詢

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

    前往 BigQuery

  2. 在「Explorer」窗格中，展開專案和「(Classic) Queries」資料夾，並視需要展開「Project queries」資料夾。

  3. 按一下已儲存的傳統查詢名稱即可開啟。

  4. 依序點按 「儲存查詢 (傳統版)」>「將查詢另存為...」。

  5. 在「儲存查詢」對話方塊中輸入名稱，然後選擇查詢位置。

  6. 按一下 [儲存]。

遷移傳統版已儲存的查詢

如要批次遷移傳統版已儲存查詢，您必須具備必要角色。這些角色授予的權限會決定可遷移的傳統已儲存查詢類型。

您可以批次遷移下列傳統版已儲存查詢：

個人傳統版已儲存查詢
只有建立個人傳統版已儲存查詢的使用者才能看到。這類項目會以 圖示標示。個人儲存的傳統查詢只能由擁有者遷移。
公開的傳統版已儲存查詢

擁有查詢連結的任何人都可看到公開的傳統版已儲存查詢。這類項目會以 圖示標示。只有擁有者才能遷移傳統版已儲存的公開查詢。

公開傳統版已儲存查詢的 IAM 權限，不會對應至 BigQuery Studio 已儲存查詢的權限。也就是說，從公開傳統儲存查詢遷移的 BigQuery Studio 儲存查詢，預設不會公開。您必須在遷移期間或之後，為遷移的 BigQuery Studio 已儲存查詢設定 IAM 權限。

如要在遷移期間為遷移的 BigQuery Studio 已儲存查詢設定 IAM 權限，您可以選取現有的 BigQuery Studio 已儲存查詢，並將其權限套用至遷移的已儲存查詢。BigQuery 會複製所選 BigQuery Studio 已儲存查詢的權限，並套用至已遷移的已儲存查詢。您也可以手動新增要共用已遷移儲存查詢的使用者或群組。

如果您在遷移期間未設定 IAM 權限，只有您能存取遷移的 BigQuery Studio 已儲存查詢。

專案傳統版已儲存查詢

凡是擁有必要權限的主體，都能看到專案層級的儲存查詢。這類檔案會以 圖示表示。您可以批次遷移專案中的所有傳統版已儲存查詢。

專案傳統儲存查詢的 IAM 權限，不會直接對應至 BigQuery Studio 儲存查詢的權限。您必須在遷移期間或之後，為遷移的 BigQuery Studio 已儲存查詢設定 IAM 權限。

如要在遷移期間為遷移的 BigQuery Studio 已儲存查詢設定 IAM 權限，您可以選取現有的 BigQuery Studio 已儲存查詢，並將其權限套用至遷移的已儲存查詢。BigQuery 會複製所選 BigQuery Studio 已儲存查詢的權限，並套用至已遷移的已儲存查詢。您也可以手動新增要共用已遷移儲存查詢的使用者或群組。

如果您在遷移期間未設定 IAM 權限，只有您能存取遷移的 BigQuery Studio 已儲存查詢。

批次遷移傳統版已儲存查詢時，BigQuery 會執行下列操作：

  • 將所有要遷移的傳統版已儲存查詢儲存為 BigQuery Studio 已儲存查詢，並儲存在所選區域中。
  • 將所有遷移的傳統版已儲存查詢轉換為唯讀傳統版已儲存查詢。

遷移後，您可將個人、公開和專案的傳統已儲存查詢，做為 BigQuery Studio 已儲存查詢和唯讀傳統已儲存查詢存取。

遷移風險

批次遷移後，您將無法修改遷移的傳統已儲存查詢。遷移的個人、公開和專案傳統版已儲存查詢會變成唯讀。

BigQuery 會使用 Dataform API，將遷移的 BigQuery Studio 已儲存查詢新增至您的 Google Cloud 專案。如要還原這些變更，則必須手動清理。

批次遷移傳統版已儲存查詢

如要將專案中的傳統已儲存查詢批次遷移至 BigQuery Studio 已儲存查詢，請按照下列步驟操作：

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

    前往 BigQuery

  2. 在「Explorer」窗格中展開專案，然後依序點選「(傳統版) 查詢」旁邊的「查看動作」圖示 和「遷移傳統版已儲存的查詢」。

  3. 在「傳統版已儲存查詢遷移作業」窗格的「檢查遷移作業準備狀態」部分，按一下「下一步」，確認您擁有必要角色。

    您的 IAM 權限決定了可遷移的傳統版已儲存查詢類型，以及傳統版已儲存查詢遷移作業窗格中可見的部分。

  4. 在「區域」部分中，從「區域」下拉式選單選取區域，BigQuery 會將遷移的已儲存查詢儲存在該區域。

    建議您選取 BigQuery Studio 程式碼資產的預設區域。詳情請參閱設定預設區域。

  5. 如要遷移所有個人傳統版已儲存的查詢，請在「遷移個人查詢」部分中，選取「遷移所有個人查詢」核取方塊，然後按一下「下一步」。

  6. 如要遷移專案中的所有傳統版公開儲存查詢，請在「遷移公開查詢」部分執行下列操作：

    1. 勾選「遷移所有公開查詢」核取方塊。
    2. 在「SQL」下拉式選單中，選取您要套用至已遷移儲存查詢的 IAM 政策，這些政策必須來自 BigQuery Studio 儲存查詢。

    3. 選用：如要新增要與之共用已遷移儲存查詢的使用者或群組，請按一下「新增使用者/群組」。

      如要公開分享已遷移的儲存查詢，請將 allAuthenticatedUsers 設為主體，並授予程式碼檢視者角色。詳情請參閱「授予公開存取權」。

    4. 點選「下一步」。

  7. 如要遷移專案層級的傳統版已儲存查詢，請在「遷移專案查詢」部分中執行下列操作：

    1. 勾選「遷移所有專案查詢」核取方塊。
    2. 在「SQL」下拉式選單中，選取 BigQuery Studio 儲存的查詢，該查詢具有要套用至已遷移儲存查詢的 IAM 政策。
    3. 選用：如要新增要與之共用已遷移儲存查詢的使用者或群組，請按一下「新增使用者/群組」。
    4. 點選「下一步」。

  8. 如要確認您瞭解遷移作業的風險，並要批次遷移傳統版已儲存查詢，請在「Confirm」(確認) 區段的「Confirm」(確認) 欄位中輸入 confirm，然後按一下「Next」(下一步)。

  9. 按一下「提交」。

視要遷移的查詢數量而定，遷移作業可能需要 15 分鐘以上。

刪除傳統版已儲存的查詢

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

    前往 BigQuery

  2. 在「Explorer」窗格中，展開專案和「(Classic) Queries」資料夾，並視需要展開「Project queries」資料夾。

  3. 找出要刪除的傳統已儲存查詢。

  4. 按一下查詢旁的 「查看動作」，然後按一下「刪除」。

  5. 如要確認刪除，請在對話方塊中輸入 delete。

  6. 點選「刪除」。

在 Dataplex Universal Catalog 中管理中繼資料

Dataplex Universal Catalog 可讓您儲存及管理已儲存查詢的中繼資料。預設情況下，Dataplex Universal Catalog 會提供已儲存的查詢，無需額外設定。

您可以使用 Dataplex Universal Catalog 管理所有已儲存查詢位置的已儲存查詢。在 Dataplex Universal Catalog 中管理已儲存的查詢時，須遵守 Dataplex Universal Catalog 配額和限制，以及 Dataplex Universal Catalog 定價。

Dataplex Universal Catalog 會自動從已儲存的查詢中擷取下列中繼資料：

  • 資料資產名稱
  • 資料資產父項
  • 資料資產位置
  • 資料資產類型
  • 對應 Google Cloud 專案

Dataplex Universal Catalog 會將儲存的查詢記錄為項目，並提供下列項目值：

系統項目群組
已儲存查詢的系統項目群組為 @dataform。如要在 Dataplex Universal Catalog 中查看已儲存查詢項目的詳細資料，您需要查看 dataform 系統項目群組。如要瞭解如何查看項目群組中的所有項目清單，請參閱 Dataplex Universal Catalog 說明文件的「查看項目群組詳細資料」一節。
系統項目類型
已儲存查詢的系統項目類型為 dataform-code-asset。如要查看已儲存查詢的詳細資料，您需要查看 dataform-code-asset 系統項目類型、使用以面向為準的篩選器篩選結果，並將 dataform-code-asset 面向內的 type 欄位設為 SQL_QUERY。然後選取所選已儲存查詢的項目。 如要瞭解如何查看所選項目類型的詳細資料，請參閱 Dataplex Universal Catalog 說明文件中的「查看項目類型的詳細資料」。如要瞭解如何查看所選項目的詳細資料，請參閱 Dataplex Universal Catalog 說明文件的「查看項目的詳細資料」一節。
系統切面類型
已儲存查詢的系統切面類型為 dataform-code-asset。如要為 Dataplex Universal Catalog 中儲存的查詢提供額外背景資訊，請使用切面註解儲存的查詢項目、查看 dataform-code-asset 切面類型、使用以切面為準的篩選器篩選結果，並在 dataform-code-asset 切面中將 type 欄位設為 SQL_QUERY。如需為項目加上切面註解的操作說明，請參閱 Dataplex Universal Catalog 說明文件中的「管理切面及豐富中繼資料」一節。
類型
已儲存查詢的類型為 SQL_QUERY。您可以使用以切面為準的篩選器，依 dataform-code-asset 系統項目類型和 dataform-code-asset 切面類型篩選已儲存的查詢。aspect:dataplex-types.global.dataform-code-asset.type=SQL_QUERY

如需在 Dataplex Universal Catalog 中搜尋資產的操作說明，請參閱 Dataplex Universal Catalog 說明文件中的「在 Dataplex Universal Catalog 中搜尋資料資產」。

後續步驟