使用遠端函式
您可以使用 BigQuery 遠端函式,透過標準使用者定義函式不支援的語言、程式庫或服務,實作自訂函式。您可以將遠端函式部署至 Cloud Run 或 Cloud Run functions,直接從 GoogleSQL 查詢叫用。
工作流程
- 在 Cloud Run functions 或 Cloud Run 中建立 HTTP 端點。
- 在 BigQuery 建立遠端函式。
- 建立
CLOUD_RESOURCE類型的連線。 - 建立遠端函式。
- 建立
- 在查詢中使用遠端函式,就像使用其他 user-defined function 一樣。
限制
遠端函式僅支援下列其中一種資料類型做為引數類型或傳回類型:
- 布林值
- 位元組數
- 數字
- 字串
- 日期
- 日期時間
- 時間
- 時間戳記
- JSON
遠端函式不支援
ARRAY、STRUCT、INTERVAL或GEOGRAPHY類型。您無法建立資料表值遠端函式。
建立 materialized view 時,無法使用遠端函式。
遠端函式的傳回值一律視為不確定,因此系統不會快取呼叫遠端函式的查詢結果。
即使成功回應,您仍可能會看到端點收到相同資料的重複要求,這是因為暫時性網路錯誤或 BigQuery 內部錯誤所致。
如果因短路而略過某些資料列的遠端函式評估,例如在條件運算式或含有
WHEN [NOT] MATCHED的MERGE陳述式中,則遠端函式不會使用批次處理。在本例中,HTTP 要求主體中的calls欄位只有一個元素。如果與遠端函式相關聯的資料集透過跨區域資料集複製功能複製到目的地區域,則只能在建立遠端函式的區域中查詢該函式。
遠端函式支援端點網址中的自訂路徑。自訂路徑有下列限制:
- 路徑只能使用大寫英文字母 (A-Z)、小寫英文字母 (a-z)、數字 (0-9)、連字號 (
-) 和底線 (_)。 - 不得使用片段 ID (
#)、查詢參數 (?) 和波浪號 (~)。 - 不得使用開頭為
/_ah/的路徑、特定路徑/eventlog,以及結尾為字母z的任何路徑。
- 路徑只能使用大寫英文字母 (A-Z)、小寫英文字母 (a-z)、數字 (0-9)、連字號 (
建立端點
如要建立可實作商業邏輯的遠端函式,您必須使用 Cloud Run functions 或 Cloud Run 建立 HTTP 端點。端點必須能夠在單一 HTTP POST 要求中處理一批資料列,並以 HTTP 回應的形式傳回該批資料列的結果。遠端函式支援端點網址中的自訂路徑 (請參閱限制)。
如果您使用 BigQuery DataFrames 建立遠端函式,就不必手動建立 HTTP 端點,服務會自動為您建立。
如要瞭解如何編寫、部署、測試及維護 Cloud Run 函式,請參閱 Cloud Run functions 教學課程和其他 Cloud Run functions 說明文件。
請參閱 Cloud Run 快速入門導覽課程和其他 Cloud Run 說明文件,瞭解如何編寫、部署、測試及維護 Cloud Run 服務。
建議您保留預設驗證,不要允許未經驗證就叫用 Cloud Run 函式或 Cloud Run 服務。
輸入格式
BigQuery 會傳送 HTTP POST 要求,其中包含下列格式的 JSON 主體:
| 欄位名稱 | 說明 | 欄位類型 |
|---|---|---|
| requestId | 要求的 ID。在 GoogleSQL 查詢中,傳送至這個端點的多項要求不重複。 | 一律提供。字串。 |
| caller | 呼叫遠端函式的 GoogleSQL 查詢完整工作資源名稱。 | 一律提供。字串。 |
| sessionUser | 執行 GoogleSQL 查詢的使用者電子郵件地址。 | 一律提供。字串。 |
| userDefinedContext | 在 BigQuery 建立遠端函式時,所使用的使用者定義情境。 | 選用。含有鍵/值組合的 JSON 物件。 |
| 通話 | 一批輸入資料。 | 一律提供。JSON 陣列。 每個元素本身都是 JSON 陣列,也就是一個遠端函式呼叫的 JSON 編碼引數清單。 |
請參考以下範例要求:
{
"requestId": "124ab1c",
"caller": "//bigquery.googleapis.com/projects/myproject/jobs/myproject:US.bquxjob_5b4c112c_17961fafeaf",
"sessionUser": "test-user@test-company.com",
"userDefinedContext": {
"key1": "value1",
"key2": "v2"
},
"calls": [
[null, 1, "", "abc"],
["abc", "9007199254740993", null, null]
]
}
輸出格式
BigQuery 預期端點應以下列格式傳回 HTTP 回應,否則 BigQuery 無法使用該回應,且呼叫遠端函式的查詢會失敗。
| 欄位名稱 | 說明 | 值範圍 |
| 回覆 | 一批傳回值。 | 必須提供,才能成功回應。JSON 陣列。 每個元素都對應到外部函式的 JSON 編碼傳回值。
陣列大小必須與 HTTP 要求中 |
| errorMessage | 傳回 200 以外的 HTTP 回應代碼時,會顯示這則錯誤訊息。如果是無法重試的錯誤,我們會將這項資訊做為 BigQuery 工作錯誤訊息的一部分傳回給使用者。 | 選用。字串。大小不得超過 1 KB。 |
成功回應範例:
{
"replies": [
1,
0
]
}
失敗回應範例:
{
"errorMessage": "Received but not expected that the argument 0 be null".
}
HTTP 回應代碼
端點應傳回 HTTP 回應代碼 200,表示回應成功。如果 BigQuery 收到任何其他值,則會將回應視為失敗,並在 HTTP 回應代碼為 408、429、500、503 或 504 時重試,直到達到內部限制。
SQL 資料類型的 JSON 編碼
HTTP 要求和回應中的 JSON 編碼,會遵循 TO_JSON_STRING 函式現有的 BigQuery JSON 編碼。
Cloud Run 函式程式碼範例
下列 Python 程式碼範例會實作新增遠端函式的所有整數引數。它會處理含有批次叫用引數的要求,並在回應中傳回所有結果。
import functions_framework
from flask import jsonify
# Max INT64 value encoded as a number in JSON by TO_JSON_STRING. Larger values are encoded as
# strings.
# See https://docs.cloud.google.com/bigquery/docs/reference/standard-sql/json_functions#json_encodings
_MAX_LOSSLESS=9007199254740992
@functions_framework.http
def batch_add(request):
try:
return_value = []
request_json = request.get_json()
calls = request_json['calls']
for call in calls:
return_value.append(sum([int(x) if isinstance(x, str) else x for x in call if x is not None]))
replies = [str(x) if x > _MAX_LOSSLESS or x < -_MAX_LOSSLESS else x for x in return_value]
return_json = jsonify( { "replies": replies } )
return return_json
except Exception as e:
return jsonify( { "errorMessage": str(e) } ), 400
假設函式部署在專案 my_gcf_project 的 us-east1 區域,函式名稱為 remote_add,則可使用端點 https://us-east1-my_gcf_project.cloudfunctions.net/remote_add 存取。
Cloud Run 程式碼範例
下列 Python 程式碼範例會實作網路服務,您可以建構該服務並部署至 Cloud Run,以達到相同功能。
import os
from flask import Flask, request, jsonify
# Max INT64 value encoded as a number in JSON by TO_JSON_STRING. Larger values are encoded as
# strings.
# See https://docs.cloud.google.com/bigquery/docs/reference/standard-sql/json_functions#json_encodings
_MAX_LOSSLESS=9007199254740992
app = Flask(__name__)
@app.route("/", methods=['POST'])
def batch_add():
try:
return_value = []
request_json = request.get_json()
calls = request_json['calls']
for call in calls:
return_value.append(sum([int(x) if isinstance(x, str) else x for x in call if x is not None]))
replies = [str(x) if x > _MAX_LOSSLESS or x < -_MAX_LOSSLESS else x for x in return_value]
return jsonify( { "replies" : replies } )
except Exception as e:
return jsonify( { "errorMessage": str(e) } ), 400
if __name__ == "__main__":
app.run(debug=True, host="0.0.0.0", port=int(os.environ.get("PORT", 8080)))
請參閱指南,瞭解如何建構及部署程式碼。
假設 Cloud Run 服務部署在專案 my_gcf_project 的 us-east1 區域,服務名稱為 remote_add,則可使用端點 https://remote_add-<project_id_hash>-ue.a.run.app 存取。
下列 Python 範例會在先前部署的網路服務中,實作不同的路徑 /subtract_list (請參閱自訂網址路徑限制):
@app.route("/subtract_list", methods=['POST'])
def batch_subtract():
"""
Processes batch requests to subtract numbers within inner lists (e.g., a - b - c).
Handles integers, string representations of integers, and None values.
"""
try:
return_value = []
request_json = request.get_json()
calls = request_json['calls']
for call in calls:
nums_to_process = [int(x) if isinstance(x, str) else x for x in call if x is not None]
if not nums_to_process:
result = 0
else:
result = nums_to_process[0] - sum(nums_to_process[1:])
return_value.append(result)
replies = [str(x) if abs(x) > _MAX_LOSSLESS else x for x in return_value]
return jsonify({"replies": replies})
except Exception as e:
return jsonify({"errorMessage": str(e)}), 400
建立遠端函式
BigQuery 會使用 CLOUD_RESOURCE 連線與 Cloud Run 函式互動。如要建立遠端函式,您必須建立 CLOUD_RESOURCE 連線。如果您使用 BigQuery DataFrames 建立遠端函式,且已取得專案 IAM 管理員 (roles/resourcemanager.projectIamAdmin) 角色,則不必手動建立連線並授予存取權,服務會自動執行這些操作。
建立連線
您必須具備 Cloud 資源連結,才能連線至 Cloud Run 函式和 Cloud Run。
如果您已設定預設連線,或具備 BigQuery 管理員角色,則可略過這個步驟。
選取下列選項之一:控制台
前往「BigQuery」頁面。
點選左側窗格中的 「Explorer」。

如果沒有看到左側窗格,請按一下 「Expand left pane」(展開左側窗格),開啟窗格。
在「Explorer」窗格中展開專案名稱,然後按一下「Connections」(連線)。
在「Connections」(連線) 頁面,按一下「Create connection」(建立連線)。
在「連線類型」部分,選擇「Vertex AI 遠端模型、遠端函式、BigLake 和 Spanner (Cloud 資源)」。
在「連線 ID」欄位輸入連線名稱。
在「位置類型」部分,選取連線位置。連線應與資料集等其他資源位於相同位置。
點選「建立連線」。
點選「前往連線」。
在「連線資訊」窗格中,複製服務帳戶 ID,以便在後續步驟中使用。
SQL
前往 Google Cloud 控制台的「BigQuery」頁面。
在查詢編輯器中輸入下列陳述式:
CREATE CONNECTION [IF NOT EXISTS] `CONNECTION_NAME` OPTIONS ( connection_type = "CLOUD_RESOURCE", friendly_name = "FRIENDLY_NAME", description = "DESCRIPTION" );
替換下列內容:
-
CONNECTION_NAME:連線名稱,格式為PROJECT_ID.LOCATION.CONNECTION_ID、LOCATION.CONNECTION_ID或CONNECTION_ID。如果省略專案或位置,系統會根據執行陳述式的專案和位置推論。 -
FRIENDLY_NAME(選用):連線的描述性名稱。 -
DESCRIPTION(選用):連線說明。
-
按一下「 執行」。
如要進一步瞭解如何執行查詢,請參閱「執行互動式查詢」。
bq
在指令列環境中建立連線:
bq mk --connection --location=REGION --project_id=PROJECT_ID \ --connection_type=CLOUD_RESOURCE CONNECTION_ID
--project_id參數會覆寫預設專案。更改下列內容:
REGION:連線區域PROJECT_ID:您的 Google Cloud 專案 IDCONNECTION_ID:連線 ID
建立連線資源時,BigQuery 會建立專屬的系統服務帳戶,並與連線建立關聯。
疑難排解:如果收到下列連線錯誤訊息,請更新 Google Cloud SDK:
Flags parsing error: flag --connection_type=CLOUD_RESOURCE: value should be one of...
擷取並複製服務帳戶 ID,以便在後續步驟中使用:
bq show --connection PROJECT_ID.REGION.CONNECTION_ID
輸出結果會與下列內容相似:
name properties 1234.REGION.CONNECTION_ID {"serviceAccountId": "connection-1234-9u56h9@gcp-sa-bigquery-condel.iam.gserviceaccount.com"}
Python
在試用這個範例之前,請先按照「使用用戶端程式庫的 BigQuery 快速入門導覽課程」中的 Python 設定操作說明進行操作。詳情請參閱 BigQuery Python API 參考文件。
如要向 BigQuery 進行驗證,請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。
Node.js
在試用這個範例之前,請先按照「使用用戶端程式庫的 BigQuery 快速入門導覽課程」中的 Node.js 設定操作說明進行操作。詳情請參閱 BigQuery Node.js API 參考文件。
如要向 BigQuery 進行驗證,請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。
Java
在試用這個範例之前,請先按照「使用用戶端程式庫的 BigQuery 快速入門導覽課程」中的 Java 設定操作說明進行操作。詳情請參閱 BigQuery Java API 參考文件。
如要向 BigQuery 進行驗證,請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。
Terraform
使用 google_bigquery_connection 資源。
如要向 BigQuery 進行驗證,請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。
下列範例會在 US 區域中,建立名為 my_cloud_resource_connection 的 Cloud 資源連結:
如要在 Google Cloud 專案中套用 Terraform 設定,請完成下列各節的步驟。
準備 Cloud Shell
- 啟動 Cloud Shell。
-
設定要套用 Terraform 設定的預設 Google Cloud 專案。
這項指令在每個專案中只需執行一次,且可在任何目錄中執行。
export GOOGLE_CLOUD_PROJECT=PROJECT_ID
如果您在 Terraform 設定檔中設定明確的值,環境變數就會遭到覆寫。
準備目錄
每個 Terraform 設定檔都必須有自己的目錄 (也稱為「根模組」)。
-
在 Cloud Shell 中建立目錄,並在該目錄中建立新檔案。檔案名稱必須有
.tf副檔名,例如main.tf。在本教學課程中,這個檔案稱為main.tf。mkdir DIRECTORY && cd DIRECTORY && touch main.tf
-
如果您正在進行教學課程,可以複製每個章節或步驟中的程式碼範例。
將程式碼範例複製到新建立的
main.tf。您也可以從 GitHub 複製程式碼。如果 Terraform 程式碼片段是端對端解決方案的一部分,建議您採用這種做法。
- 請查看並修改範例參數,以便套用至您的環境。
- 儲存變更。
-
初始化 Terraform。每個目錄只需執行一次這項操作。
terraform init
如要使用最新版 Google 供應商,請視需要加入
-upgrade選項:terraform init -upgrade
套用變更
-
查看設定,確認 Terraform 要建立或更新的資源符合預期:
terraform plan
視需要修正設定。
-
執行下列指令,並在提示中輸入
yes,套用 Terraform 設定:terraform apply
等待 Terraform 顯示「Apply complete!」訊息。
- 開啟 Google Cloud 專案即可查看結果。在 Google Cloud 控制台的使用者介面中,前往資源頁面,確認 Terraform 已建立或更新資源。
設定存取權
您必須授予新連線對 Cloud Run 函式或 Cloud Run 服務的唯讀存取權。不建議允許未經驗證的 Cloud Run 函式或 Cloud Run 服務叫用。
如要授予角色,請按照下列步驟操作:
前往「IAM & Admin」(IAM 與管理) 頁面。
按一下「 新增」。
「Add principals」(新增主體) 對話方塊隨即開啟。
在「新增主體」欄位,輸入先前複製的服務帳戶 ID。
在「Select a role」(選取角色) 欄位中,選取下列其中一個選項:
- 如果使用第 1 代 Cloud Run 函式,請依序選取「Cloud 函式」和「Cloud 函式叫用者角色」。
- 如果使用第 2 代 Cloud Run 函式,請依序選取「Cloud Run」和「Cloud Run 叫用者角色」。
- 如果您使用的是 Cloud Run 服務,請選擇「Cloud Run」,然後選取「Cloud Run 叫用者角色」。
按一下「儲存」。
建立遠端函式
如要建立遠端函式,請按照下列指示操作:
SQL
在 BigQuery 中執行下列 CREATE FUNCTION 陳述式:
前往 Google Cloud 控制台的「BigQuery」頁面。
在查詢編輯器中輸入下列陳述式:
CREATE FUNCTION
PROJECT_ID.DATASET_ID.remote_add(x INT64, y INT64) RETURNS INT64 REMOTE WITH CONNECTIONPROJECT_ID.LOCATION.CONNECTION_NAMEOPTIONS ( endpoint = 'ENDPOINT_URL' )替換下列內容:
DATASET_ID:BigQuery 資料集的 ID。ENDPOINT_URL:Cloud Run 函式或 Cloud Run 遠端函式端點的網址。遠端函式支援端點網址中的自訂路徑 (請參閱自訂路徑限制)。您可以在同一個應用程式的各個路徑上,建立不同的遠端函式。CREATE FUNCTION陳述式中的endpoint選項可包含緊接在 Cloud Run 網址後方的路徑 (例如https://service_name-project_number.region.run.app/subtract_list)。
按一下「 執行」。
如要進一步瞭解如何執行查詢,請參閱「執行互動式查詢」。
BigQuery DataFrames
- 啟用必要的 API,並確認您已取得必要角色,如「遠端函式」的「需求」一節所述。
- 使用
remote_function裝飾器。
您必須具備建立遠端函式的資料集 bigquery.routines.create 權限,以及遠端函式所用連線的 bigquery.connections.delegate 權限 (可透過 BigQuery 連線管理員角色取得)。
提供使用者定義的情境
您可以在 OPTIONS 中以鍵/值組合的形式指定 user_defined_context,這會成為傳送至端點的每個 HTTP 要求的一部分。有了使用者定義的情境,您就能建立多個遠端函式,但重複使用單一端點,根據傳遞至該端點的情境提供不同的行為。
下列範例會建立兩個遠端函式,使用同一個端點加密及解密 BYTES 資料。
CREATE FUNCTION `PROJECT_ID.DATASET_ID`.encrypt(x BYTES)
RETURNS BYTES
REMOTE WITH CONNECTION `PROJECT_ID.LOCATION.CONNECTION_NAME`
OPTIONS (
endpoint = 'ENDPOINT_URL',
user_defined_context = [("mode", "encryption")]
)
CREATE FUNCTION `PROJECT_ID.DATASET_ID`.decrypt(x BYTES)
RETURNS BYTES
REMOTE WITH CONNECTION `PROJECT_ID.LOCATION.CONNECTION_NAME`
OPTIONS (
endpoint = 'ENDPOINT_URL',
user_defined_context = [("mode", "decryption")]
)
限制批次要求中的資料列數量
您可以在 OPTIONS 中指定 max_batching_rows 做為每個 HTTP 要求中的資料列數量上限,避免 Cloud Run functions 逾時。如果指定 max_batching_rows,BigQuery 會決定批次中的資料列數量,最多不超過 max_batching_rows 限制。如未指定,BigQuery 會自動決定要批次處理的資料列數量。
在查詢中使用遠端函式
請務必授予 Cloud Run 函式權限,讓與遠端函式連線相關聯的 BigQuery 服務帳戶可以存取該函式。
您也必須具備遠端函式所在資料集的 bigquery.routines.get 權限,以及遠端函式所用連線的 bigquery.connections.use 權限 (可透過 BigQuery Connection User 角色取得)。
您可以在查詢中使用遠端函式,就像使用使用者定義函式一樣。
舉例來說,您可以在範例查詢中使用 remote_add 函式:
SELECT
val,
`PROJECT_ID.DATASET_ID`.remote_add(val, 2)
FROM
UNNEST([NULL,2,3,5,8]) AS val;
這個範例會產生下列輸出內容:
+------+-----+
| val | f0_ |
+------+-----+
| NULL | 2 |
| 2 | 4 |
| 3 | 5 |
| 5 | 7 |
| 8 | 10 |
+------+-----+
支援的地區
BigQuery 的位置分為兩種類型:
「地區」是特定的地理位置,例如倫敦。
「多區域」是指包含兩個及以上地理位置的大型地理區域,例如美國。
單一地區
在 BigQuery 單一區域資料集中,您只能建立使用部署在相同區域的 Cloud Run 函式的遠端函式。例如:
- BigQuery 單一區域
us-east4中的遠端函式,只能使用us-east4中的 Cloud Run 函式。
因此,如果是單一區域,遠端函式僅適用於同時支援 Cloud Run functions 和 BigQuery 的區域。
多區域
在 BigQuery 多區域 (US、EU) 資料集中,您只能建立遠端函式,並使用部署在相同大型地理區域 (美國、歐盟) 內某個區域的 Cloud Run 函式。例如:
- BigQuery
US多區域中的遠端函式,只能使用部署在美國地理區域中任何單一區域的 Cloud Run 函式,例如us-central1、us-east4、us-west2等。 - BigQuery
EU多區域中的遠端函式,只能使用部署在歐盟成員國中任一區域的 Cloud Run 函式,例如europe-north1、europe-west3等。
如要進一步瞭解 BigQuery 區域和多區域,請參閱「資料集位置」頁面。如要進一步瞭解 Cloud Run functions 區域,請參閱「Cloud Run functions 位置」頁面。
連線
無論是單一區域或多區域位置,您只能在與所用連線相同的位置建立遠端函式。舉例來說,如要在 US 多區域建立遠端函式,請使用位於 US 多區域的連線。
定價
適用標準 BigQuery 定價。
此外,使用這項功能可能會產生 Cloud Run functions 和 Cloud Run 費用。詳情請參閱 Cloud Run functions 和 Cloud Run 定價頁面。
使用 VPC Service Controls
VPC Service Controls 是一項 Google Cloud 功能,可用來設定安全 perimeter 以防範資料遭竊。如要搭配使用 VPC Service Controls 與遠端函式,進一步提升安全性,或搭配使用端點與internal traffic
輸入設定,請按照 VPC Service Controls 指南操作:
建立 service perimeter。
將使用遠端函式的查詢 BigQuery 專案新增至 perimeter。
將端點專案新增至 perimeter,並根據端點類型,在受限制的服務中設定
Cloud Functions API或Cloud Run API。詳情請參閱「Cloud Run functions VPC Service Controls」和「Cloud Run VPC Service Controls」。
遠端函式的最佳做法
- 預先篩選輸入內容:如果能在將輸入內容傳遞至遠端函式之前先進行篩選,查詢速度可能會更快,費用也更低。
確保 Cloud Run 函式可擴充。擴充性取決於執行個體數量下限、執行個體數量上限和並行。
- 請盡可能使用 Cloud Run 函式執行個體數量上限的預設值。
- 請注意,第 1 代 HTTP Cloud Run 函式沒有預設限制。為避免第 1 代 HTTP Cloud Run 函式在測試或正式環境中無限制擴充,建議設定限制,例如 3000。
請按照其他 Cloud Run 函式提示操作,提升效能。如果遠端函式查詢與高延遲的 Cloud Run 函式互動,可能會因逾時而失敗。
實作端點,針對失敗的回應傳回正確的 HTTP 回應代碼和酬載。
如要盡量減少 BigQuery 的重試次數,請使用 408、429、500、503 和 504 以外的 HTTP 回應代碼來表示失敗的回應,並確保在函式程式碼中擷取所有例外狀況。否則,HTTP 服務架構可能會自動針對任何未擷取的例外狀況傳回 500。當 BigQuery 重試失敗的資料分區或查詢時,您可能仍會看到重試的 HTTP 要求。
端點應以定義的格式傳回 JSON 酬載,表示回應失敗。雖然這並非必要,但有助於 BigQuery 區分失敗的回應是來自函式實作,還是 Cloud Run functions/Cloud Run 的基礎架構。如果是後者,BigQuery 可能會以不同的內部限制重試。
配額
請參考下列資訊,排解遠端函式的配額問題。
包含遠端函式的並行查詢數量上限
如果含有遠端函式的並行查詢數量超過上限,BigQuery 就會傳回這項錯誤。
如要進一步瞭解遠端函式限制,請參閱「遠端函式」。
錯誤訊息
Exceeded rate limits: too many concurrent queries with remote functions for this project
這項上限可以提高。請先嘗試解決方法和最佳做法。
診斷
如要查看包含遠端函式的並行查詢限制,請參閱「遠端函式限制」。