建立已儲存的查詢

在查詢編輯器中撰寫 SQL 時，您可以儲存查詢並與他人共用。儲存的查詢是 BigQuery Studio 程式碼資產，由 Dataform 提供支援。

如要進一步瞭解如何刪除已儲存的查詢及管理已儲存的查詢記錄，請參閱「管理已儲存的查詢」一文。

所需權限

設定適當的權限，即可建立、編輯或查看已儲存的查詢。

所有具備 Dataform 管理員角色 (roles/dataform.admin) 的使用者，都能以擁有者身分存取專案中建立的所有已儲存查詢。

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

建立已儲存查詢的權限

如要建立及執行已儲存的查詢，您必須具備下列 IAM 權限：

• dataform.locations.get
• dataform.locations.list
• dataform.repositories.list
• dataform.repositories.create

您可以透過下列 IAM 角色取得這些權限：

• BigQuery 工作使用者 (roles/bigquery.jobUser)
• BigQuery 讀取工作階段使用者 (roles/bigquery.readSessionUser)
• 程式碼建立者 (roles/dataform.codeCreator)

注意：在專案中獲派程式碼建立者角色的使用者，可以使用 Dataform API 或 Dataform 指令列介面 (CLI)，列出該專案中的程式碼資產名稱。

注意：建立已儲存的查詢時，BigQuery 會將該查詢的 Dataform 管理員角色 (roles/dataform.admin) 授予您。在 Google Cloud 專案中獲授 Dataform 管理員角色的所有使用者，都擁有專案中所有已儲存查詢的擁有者存取權。如要覆寫這項行為，請參閱在建立資源時授予特定角色。

編輯已儲存查詢的權限

如要編輯及執行已儲存的查詢，您必須具備下列 IAM 角色：

• BigQuery 工作使用者 (roles/bigquery.jobUser)
• BigQuery 讀取工作階段使用者 (roles/bigquery.readSessionUser)
• 程式碼編輯器 (roles/dataform.codeEditor)

查看已儲存查詢的權限

如要查看及執行已儲存的查詢，您必須具備下列 IAM 角色：

• BigQuery 工作使用者 (roles/bigquery.jobUser)
• BigQuery 讀取工作階段使用者 (roles/bigquery.readSessionUser)
• 程式碼檢視器 (roles/dataform.codeViewer)

已儲存查詢的安全考量

由於 BigQuery 中的程式碼資產是由 Dataform 支援，因此請考慮以下安全性影響，以確保使用者能存取這些資產：

• 程式碼資產的可見度取決於專案層級的 Dataform 權限。擁有 dataform.repositories.list 權限的使用者 (包含在標準 BigQuery 角色中，例如「BigQuery Job User」、「BigQuery Studio User」和「BigQuery User」)，可以在專案的 Google Cloud 「Explorer」面板中查看所有程式碼資產，無論這些資產是由他們建立，還是與他們共用。如要限制瀏覽權限，可以建立排除 dataform.repositories.list 權限的自訂角色。
• 與 Dataform 服務代理程式共用的任何密鑰，都可能遭到可編輯這些資產的使用者存取。為確保憑證安全，請限制只有信任的使用者可以建立及編輯憑證，並限制 Dataform 服務代理程式可存取的密鑰。詳情請參閱「在套件安裝期間存取密鑰」。

詳情請參閱「Dataform 權限的安全考量」。

設定程式碼資產的預設區域

Google Cloud 專案中的所有新程式碼資產都會使用預設區域。資產建立後，就無法變更區域。

重要事項： 如果您在建立程式碼資產時變更區域，該區域會成為後續所有程式碼資產的預設區域。現有程式碼資產不受影響。

如要為新的程式碼資產設定預設區域，請按照下列步驟操作：

1. 前往「BigQuery」頁面

   前往「BigQuery」

2. 在左側窗格中，按一下「檔案」開啟檔案瀏覽器：

   

3. 在專案名稱旁，按一下 「查看檔案面板動作」>「切換程式碼區域」。

4. 選取要設為預設的程式碼區域。

5. 按一下 [儲存]。

如需支援的區域清單，請參閱「BigQuery Studio 位置」。

使用 CMEK 加密

您可以為 Dataform 支援的已儲存查詢加密，方法是使用 Dataform API 的預設專案層級 CMEK 金鑰。您無法在 Google Cloud 控制台中，對已儲存的查詢套用個別 CMEK 金鑰。新設定只會套用至新建立的已儲存查詢。

如要進一步瞭解如何設定預設金鑰，請參閱使用 CMEK 保護 BigQuery Studio 程式碼資產。

建立已儲存的查詢

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

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

   前往「BigQuery」

2. 按一下 「SQL 查詢」。

3. 在查詢編輯器中輸入有效的 SQL 查詢。舉例來說，您可以查詢公開資料集：

   SELECT
     name,
     SUM(number) AS total
   FROM
     `bigquery-public-data.usa_names.usa_1910_2013`
   GROUP BY
     name
   ORDER BY
     total DESC
   LIMIT
     10;

   或者，您也可以使用「參考」面板建構新查詢。

4. 按一下「儲存」>「儲存查詢」，或按下 Ctrl+S 鍵 (在 macOS 上為 Command+S 鍵)。

5. 在「儲存查詢」對話方塊中，輸入已儲存的查詢的名稱。

6. 選用：如要變更這項已儲存的查詢和所有其他程式碼資產日後使用的區域，請在「區域」欄位中選取新區域。

7. 按一下 [儲存]。

   系統會建立儲存查詢的第一個版本。

8. 選用：儲存查詢後，使用下列工具列查看查詢詳細資料或版本記錄、新增註解、回覆現有註解或取得現有註解的連結：

   

   「註解」工具列功能為預先發布版。如要提供意見回饋或尋求這項功能的支援，請傳送電子郵件至 [e-mail]。

共用已儲存的查詢

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

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

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

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

   前往「BigQuery」

2. 在左側窗格中，按一下「檔案」，開啟檔案瀏覽器。

   如果沒有看到左側窗格，請按一下 「Expand left pane」(展開左側窗格)，開啟窗格。

3. 在「檔案」窗格中展開專案和子資料夾，找出要共用的已儲存的查詢。

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

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

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

7. 在「Role」(角色) 清單中，選取下列其中一個角色：

   • 程式碼擁有者：可以對已儲存的查詢執行任何動作，包括刪除或共用查詢。
   • 程式碼編輯器：可編輯查詢。
   • 程式碼檢視者：可以查看查詢。
   注意： 主體也必須具備 BigQuery 使用者 (roles/bigquery.user) 角色，才能執行已儲存的查詢。

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

9. 按一下 [儲存]。

10. 如要返回已儲存的查詢詳細資料，請按一下「關閉」。

11. 如要產生已儲存的查詢連結，請依序點選「查看動作」>「分享」>「複製連結」。

    連結即會複製到剪貼簿。

將已儲存的查詢版本開啟為新查詢

如要將現有已儲存查詢的任何版本開啟為新查詢，請按照下列步驟操作：

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

   前往「BigQuery」

2. 在左側窗格中，按一下「檔案」開啟檔案瀏覽器：

   

   如果沒有看到左側窗格，請按一下 「Expand left pane」(展開左側窗格)，開啟窗格。

3. 在「Files」窗格中展開專案和子資料夾，找出要開啟的已儲存的查詢。

4. 按一下已儲存的查詢，然後點選「版本記錄」。

5. 按一下已儲存的查詢版本旁的 「查看動作」，然後點選「以新查詢開啟」。

更新已儲存的查詢

停止輸入文字兩秒後，系統會自動儲存您對已儲存的查詢文字所做的變更，並在「版本記錄」中顯示為「您的變更」。自動儲存的變更並非查詢的新版本。 您開啟查詢時，系統會重新顯示自動儲存的變更，但除非您明確將變更儲存為查詢的新版本，否則其他人都看不到這些變更。自動儲存的查詢會顯示在「預覽」中。

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

   前往「BigQuery」

2. 在左側窗格中，按一下「檔案」開啟檔案瀏覽器：

   

   如果沒有看到左側窗格，請按一下 「Expand left pane」(展開左側窗格)，開啟窗格。

3. 在「Files」窗格中，展開專案和子資料夾，找出要更新的已儲存的查詢。

4. 按一下已儲存的查詢即可開啟。

5. 修改查詢。

6. 如要儲存修改後的查詢，請依序點按 「儲存查詢」>「儲存查詢」，或按下 Ctrl+S 鍵 (在 macOS 上為 Command+S 鍵)。

   系統會建立查詢的新版本。

上傳已儲存的查詢

您可以上傳本機 SQL 查詢，在 BigQuery Studio 中做為已儲存的查詢使用。上傳的已儲存的查詢也會顯示在 Google Cloud 控制台的 BigQuery 頁面。

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

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

   前往「BigQuery」

2. 在左側窗格中，按一下「檔案」開啟檔案瀏覽器：

   

   如果沒有看到左側窗格，請按一下 「Expand left pane」(展開左側窗格)，開啟窗格。

3. 在「檔案」窗格中，依序點選要上傳查詢的資料夾旁邊的「查看動作」圖示 >「上傳」>「查詢」。

4. 在「Upload SQL」(上傳 SQL) 對話方塊的「SQL」欄位中，按一下「Browse」(瀏覽)，然後選取要上傳的查詢。

5. 選用：在「SQL 名稱」欄位中，編輯查詢名稱。

6. 在「Region」(區域) 欄位中，選取要上傳已儲存的查詢的區域。

7. 按一下「上傳」。

您可以透過「檔案」或「Explorer」窗格存取已儲存的查詢。

排解已儲存查詢的問題

本節說明如何解決儲存查詢的常見問題。

無法儲存查詢

如果無法儲存查詢，可能是因為專案未啟用 Dataform API。大多數專案都會自動啟用 Dataform API，但如果專案使用限制資源服務用量組織政策限制 (例如受保障的專案)，則不會啟用。

如要解決這個問題，請確認已啟用 Dataform API：

1. 在 Google Cloud 控制台中，前往「APIs & Services」(API 與服務) 頁面。
2. 搜尋「Dataform API」，並確認已啟用。
3. 如果 API 尚未啟用，請點選「啟用」。
4. 使用已儲存的查詢重試。

已儲存查詢的區域不符

變更程式碼資產的預設區域只會影響變更後建立的資產。現有資產會保留在原始區域。

如要解決這個問題，請確保為已儲存的查詢選取的區域與其中一個支援的區域相符。如有需要，請在支援的區域中建立新的已儲存查詢，或調整程式碼資產的預設區域。

傳統版已儲存查詢

已淘汰： BigQuery Studio 中的已儲存查詢，日後將完全取代傳統的已儲存查詢。我們正在審查淘汰時程。 詳情請參閱淘汰傳統版已儲存查詢一文。 如要瞭解如何遷移至已儲存的查詢，請參閱「遷移傳統版已儲存的查詢」一文。

請參閱下列章節，瞭解如何建立及更新傳統儲存的查詢。如要進一步瞭解如何共用、遷移及刪除傳統版已儲存查詢，請參閱「傳統版已儲存查詢」。

注意： 如果尚未啟用 BigQuery Studio，系統會將傳統儲存的查詢顯示在「Explorer」窗格的「已儲存的查詢 (NUMBER)」資料夾中，而不是「(傳統) 查詢」資料夾。

傳統版已儲存查詢的必要權限

如要建立、查看、更新及刪除傳統儲存查詢，必須要有以下 IAM 權限：

• 不公開的傳統版已儲存查詢：
  • 建立不公開的傳統已儲存查詢不需要任何特殊權限。您可以在任何專案中儲存不公開的查詢，但只有您可以查看、更新或刪除該查詢。
• 專案層級的傳統版已儲存查詢：
  • 建立專案層級的傳統版已儲存的查詢需要擁有 bigquery.savedqueries.create 權限。bigquery.admin 這個預先定義的角色具備 bigquery.savedqueries.create 權限。
  • 查看專案層級的傳統版已儲存的查詢需要擁有 bigquery.savedqueries.get 與 bigquery.savedqueries.list 權限。bigquery.admin 和 bigquery.user 這些預先定義的角色具備 bigquery.savedqueries.get 與 bigquery.savedqueries.list 權限。
  • 更新專案層級的傳統版已儲存的查詢需要擁有 bigquery.savedqueries.update 權限。bigquery.admin 這個預先定義的角色具備 bigquery.savedqueries.update 權限。
  • 刪除專案層級的傳統版已儲存的查詢需要擁有 bigquery.savedqueries.delete 權限。bigquery.admin 這個預先定義的角色具備 bigquery.savedqueries.delete 權限。
• 公開的傳統版已儲存查詢：
  • 建立公開的傳統已儲存查詢不需要任何特殊權限。您可以在任何專案中儲存公開的傳統版已儲存的查詢，但只有您可以更新或刪除該查詢。擁有連結的任何人都可查看公開的已儲存傳統查詢。

如要進一步瞭解 BigQuery 中的 IAM 角色，請參閱預先定義的角色與權限一文。

建立傳統版已儲存查詢

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

   前往「BigQuery」

2. 按一下 「SQL 查詢」。

3. 在查詢編輯器中輸入有效的 SQL 查詢。舉例來說，您可以查詢公開資料集：

   SELECT
     name,
     SUM(number) AS total
   FROM
     `bigquery-public-data.usa_names.usa_1910_2013`
   GROUP BY
     name
   ORDER BY
     total DESC
   LIMIT
     10;

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

5. 在「Save query」(儲存查詢) 對話方塊中，輸入查詢的名稱，然後將「Visibility」(瀏覽權限) 設定為下列其中一個選項：

   • 個人 (只能由您編輯)：不公開的傳統版已儲存的查詢。
   • 專案 (可由具備適當權限的主體編輯)，適用於專案層級的傳統版已儲存的查詢。
   • 公開：傳統版公開已儲存的查詢。

6. 按一下 [儲存]。

共用傳統版已儲存的查詢

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

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

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

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

如要分享傳統已儲存的查詢，請按照下列步驟操作：

1. 點選左側窗格中的 「Explorer」。

   如果沒有看到左側窗格，請按一下 「Expand left pane」(展開左側窗格)，開啟窗格。

2. 在「Explorer」窗格中展開專案，然後按一下「(Classic) Queries」(查詢 (傳統版))。

3. 找出並按一下要授予存取權的傳統已儲存查詢。 您可以使用搜尋功能或篩選器尋找查詢。

4. 按一下查詢旁的 「View actions」(查看動作)，然後按一下「Copy link」(複製連結)。

5. 將連結分享給要授予查詢存取權的使用者。

更新傳統版已儲存的查詢

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

   前往「BigQuery」

2. 點選左側窗格中的 「Explorer」。

   

   如果沒有看到左側窗格，請按一下 「Expand left pane」(展開左側窗格)，開啟窗格。

3. 在「Explorer」窗格中，展開專案和「(Classic) Queries」資料夾，以及「Project queries」資料夾 (如有需要)。

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

5. 修改查詢。

6. 如要儲存修改後的查詢，請依序點按「儲存查詢 (傳統版)」>「儲存查詢 (傳統版)」。

排解傳統版已儲存查詢的問題

本節說明如何解決傳統已儲存查詢的常見問題。

無法存取已停用使用者的已儲存查詢

與 BigQuery Studio 儲存的查詢不同，專案管理員可以存取私人傳統儲存查詢，但如果建立查詢的使用者已離開機構，且 Google 帳戶已停用或暫停，這些查詢就會無法存取。除了原始擁有者以外，所有使用者都無法再透過 Google Cloud 控制台 查看查詢。

如要復原這些查詢，Google Workspace 或 Cloud Identity 管理員必須執行下列步驟：

1. 暫時重新啟用已停用的使用者帳戶。
2. 重設使用者的密碼。
3. 以重新啟用的使用者身分登入 Google Cloud 控制台。
4. 在查詢編輯器中，開啟每個已儲存的查詢。
5. 按一下「儲存」或「將查詢另存為」。
6. 將「瀏覽權限」從「個人」變更為「專案」。
7. 按一下 [儲存]。這樣一來，專案中具有必要權限的其他使用者就能看到查詢。
8. 遷移所有查詢後，請重新停權使用者帳戶。

為避免發生這個問題，請將業務關鍵或團隊共用的查詢儲存為「專案」瀏覽權限。

後續步驟

• 瞭解如何管理已儲存的查詢。