排解查詢相關問題
在 BigQuery 執行查詢時,可能會遇到執行速度緩慢、資源配額錯誤或查詢工作失敗等問題。您可以檢查查詢執行詳細資料、使用自動診斷工具,以及套用指定修正,診斷並解決這些常見的查詢問題。
排解查詢執行速度緩慢的問題
如要排解查詢效能緩慢的問題,請按照下列步驟操作:
查看 Google Cloud Service Health 頁面,瞭解是否有已知的 BigQuery 服務中斷情形,可能會影響查詢效能。
在工作探索工具中查看查詢的工作時間軸,瞭解查詢的每個階段執行所需的時間。
如果大部分時間都花在建立作業上,請聯絡 Cloud Customer Care 尋求協助。
如果耗用時間大多是因為執行時間過長,請查看查詢效能深入分析。查詢效能深入分析可讓您瞭解查詢執行時間是否超過平均執行時間,並提供可能原因。可能原因包括查詢運算單元爭用或重組配額不足。如要進一步瞭解各項查詢效能問題和可能的解決方法,請參閱「解讀查詢效能深入分析」。
查看查詢工作的
JobStatistics物件類型中的finalExecutionDurationMs欄位。系統可能已重試查詢。finalExecutionDurationMs欄位包含這項工作最後一次嘗試執行的時間長度 (以毫秒為單位)。請查看查詢工作詳細資料頁面中處理的位元組,確認是否高於預期。方法是比較目前查詢處理的位元組數,與另一個在可接受時間內完成的查詢工作。如果兩項查詢處理的位元組數有很大差異,則查詢速度緩慢可能是因為資料量過大。如要瞭解如何最佳化查詢,以便處理大量資料,請參閱「最佳化查詢運算」。
您也可以使用
INFORMATION_SCHEMA.JOBS檢視表搜尋最昂貴的查詢,找出專案中處理大量資料的查詢。查看預留項目用量,並檢查是否有運算單元爭用情形。詳情請參閱「工作負載統計資料分析」。
檢查相同查詢雜湊的先前和近期執行作業,看看速度較慢的工作是否有新的查詢效能深入分析,例如資料輸入規模變更。您可以在管理工作探索工具中,依查詢雜湊篩選。
比較相同查詢的執行速度
如果先前執行速度很快的查詢現在變慢,請檢查 Job API 物件輸出,找出執行作業的變化。
快取命中
查看 cacheHit 值,確認工作快速執行是否為快取命中。如果快速執行查詢的值為 true,則查詢會使用快取結果,而不是執行查詢。
如果您預期速度緩慢的工作會使用快取結果,請調查查詢不再使用快取結果的原因。如果您不希望查詢從快取擷取資料,請尋找未命中快取的快速查詢執行範例,以便進行調查。
配額延遲
如要判斷速度變慢是否由配額延遲造成,請檢查兩項工作的 quotaDeferments 欄位。比較這些值,判斷較慢查詢的開始時間是否因配額延遲而延遲,而較快的作業則不受影響。
執行作業時間長度
如要瞭解兩項工作最後一次嘗試的執行時間長度差異,請比較 finalExecutionDurationMs 欄位的值。
如果 finalExecutionDurationMs 的值非常相似,但兩項查詢的實際執行時間差異 (計算方式為 startTime - endTime) 較大,這表示可能因暫時性問題,導致慢速工作重試內部查詢執行作業。如果反覆看到這種差異模式,請聯絡 Cloud Customer Care 尋求協助
處理的位元組數
請在查詢工作詳細資料頁面中查看處理的位元組數,或查看 JobStatistics 的 totalBytesProcessed,確認是否高於預期。如果兩項查詢處理的位元組數有很大差異,則查詢速度可能會因處理的資料量變化而變慢。如要瞭解如何最佳化查詢,以便處理大量資料,請參閱「最佳化查詢運算」。下列原因可能會導致查詢處理的位元組數增加:
- 查詢參照的資料表大小增加。
- 查詢現在會讀取資料表中較大的分區。
- 查詢參照的檢視表定義已變更。
參照的資料表
分析 JobStatistics2 中 referencedTables 欄位的輸出內容,確認查詢是否讀取相同的資料表。參考表格之間的差異可由下列原因解釋:
- SQL 查詢已修改為讀取不同資料表。請比較查詢文字來確認。
- 檢視表定義在查詢執行期間有所變更。請檢查這項查詢參照的檢視表定義,並視需要更新。
totalBytesProcessed 的變化可能是因為參照的資料表不同。
materialized view 用量
如果查詢參照任何 materialized view,則效能差異可能是因為在查詢執行期間選擇或拒絕 materialized view 所致。檢查 MaterializedViewStatistics,瞭解快速查詢中使用的任何 materialized view 是否在慢速查詢中遭到拒絕。查看 MaterializedView 物件中的 chosen 和 rejectedReason 欄位。
中繼資料快取統計資料
如果查詢涉及 Amazon S3 BigLake 資料表或已啟用中繼資料快取的 Cloud Storage BigLake 資料表,請比較 MetadataCacheStatistics 的輸出內容,檢查慢速和快速查詢之間的中繼資料快取用量是否有差異,以及相應的原因。例如,中繼資料快取可能超出為資料表設定的 maxStaleness 時間間隔。
比較 BigQuery BI Engine 統計資料
如果查詢使用 BigQuery BI Engine,請分析 BiEngineStatistics 的輸出內容,判斷是否對慢速和快速查詢套用相同的加速模式。查看 BiEngineReason 欄位,瞭解部分加速或完全未加速的大致原因,例如記憶體不足、缺少預留項目或輸入內容過大。
查看查詢成效洞察的差異
在 Google Cloud 控制台中查看執行圖,或查看StagePerformanceStandaloneInsight物件,比較各項查詢的查詢效能深入分析,瞭解下列可能問題:
- 運算單元爭用情況 (
slotContention) - 高基數彙整 (
highCardinalityJoins) - 重組配額不足 (
insufficientShuffleQuota) - 資料偏斜 (
partitionSkew)
請留意系統為慢速工作提供的洞察資料,以及為快速工作產生的洞察資料之間的差異,找出影響效能的階段變化。
指派的預留項目
請檢查指派給這兩項工作的預留項目是否有差異。變更預留項目或從隨選模式改為預留項目,可能會影響效能。詳情請參閱「Workload Manager 模型和預留項目大小」。
如要更徹底地分析工作執行中繼資料,您必須比較兩項工作的 ExplainQueryStage 物件,逐一檢查查詢執行的各個階段。
首先,請查看解讀查詢階段資訊一節中說明的 Wait ms 和 Shuffle output bytes 指標。
INFORMATION_SCHEMA.JOBS檢視畫面中的資源警告
查詢 INFORMATION_SCHEMA.JOBS 檢視表的 query_info.resource_warning 欄位,查看 BigQuery 分析的警告是否因使用的資源而有所不同。
工作負載統計資料分析
可用的運算單元資源和運算單元爭用情況,可能會影響查詢執行時間。以下各節可協助您瞭解特定查詢執行的運算單元用量和可用性。
每秒平均運算單元數
如要計算查詢每毫秒使用的平均運算單元數,請將工作的運算單元毫秒值 totalSlotMs (來自 JobStatistics2) 除以這項工作最後一次嘗試執行的時間長度 (以毫秒為單位),即 finalExecutionDurationMs (來自 JobStatistics)。
您也可以查詢 INFORMATION_SCHEMA.JOBS 檢視表,計算工作每毫秒使用的平均運算單元數量
如果工作執行的工作量相似,但每秒平均運算單元數量較多,則完成速度較快。每秒平均運算單元用量較低的原因可能如下:
- 不同工作之間發生資源爭用,因此沒有額外資源可用,預留項目已達上限。
- 在執行作業的大部分時間,工作並未要求更多運算單元。例如,資料偏斜時就可能發生這種情況。
Workload Manager 模型和預留項目大小
如果使用隨選計費模式,每個專案可用的運算單元數量有限。此外,如果在特定位置對隨選容量有大量爭用,則專案可用運算單元數量有時可能會較少。
以運算能力為基礎的模型較容易預測,可讓您指定確定的基準運算單元數量。
比較使用隨選模式和預留項目執行的查詢時,請考量這些差異。
建議使用預留項目,確保查詢執行效能穩定且可預測。如要進一步瞭解隨選和容量型工作負載之間的差異,請參閱「工作負載管理簡介」。
並行工作數量
工作並行是指在執行查詢期間,工作之間競爭運算單元資源的情況。工作並行程度較高時,工作可存取的運算單元較少,因此執行速度通常較慢。
您可以查詢 INFORMATION_SCHEMA.JOBS 檢視表,找出與專案中特定查詢同時執行的並行工作平均數量。
如果有多個專案指派給同一個預留項目,請修改查詢,使用 JOBS_BY_ORGANIZATION 而非 JOBS_BY_PROJECT,以取得準確的預留項目層級資料。
與快速工作相比,慢速工作執行期間的平均並行程度較高,是導致整體速度緩慢的原因之一。
建議您降低專案或預留項目中的並行數量,方法是在預留項目或專案中,將耗用大量資源的查詢分散到不同時間執行,或分散到不同預留項目或專案。
另一個解決方案是購買預留項目,或增加現有預留項目的大小。建議允許預留項目使用閒置的運算單元。
如要瞭解應新增多少運算單元,請參閱「預估運算單元容量需求」一文。
如果預留項目指派了多項專案,在預留項目中執行的工作,可能會因執行專案的不同,而有不同的運算單元指派結果,但平均工作並行數相同。如要瞭解詳情,請參閱公平排程。
預留項目使用率
管理員資源圖表和 BigQuery Cloud Monitoring 可用於監控預留項目使用率。詳情請參閱「監控 BigQuery 預留項目」。
如要瞭解工作是否要求任何額外運算單元,請查看預估可執行單位指標,也就是 Job API 回應中的 estimatedRunnableUnits,或 INFORMATION_SCHEMA.JOBS_TIMELINE 檢視畫面中的 period_estimated_runnable_units。如果這項指標的值大於 0,代表工作在當時可能需要更多運算單元。如要估算工作執行時間中,工作可受益於額外運算單元的百分比,請對 INFORMATION_SCHEMA.JOBS_TIMELINE 檢視表執行下列查詢:
SELECT ROUND(COUNTIF(period_estimated_runnable_units > 0) / COUNT(*) * 100, 1) AS execution_duration_percentage FROM `myproject`.`region-us`.INFORMATION_SCHEMA.JOBS_TIMELINE WHERE job_id = 'my_job_id' GROUP BY job_id;
+---------------------------------+ | execution_duration_percentage | +---------------------------------+ | 96.7 | +---------------------------------+
如果百分比偏低,代表在這個情境中,運算單元資源可用性並非查詢速度緩慢的主要因素。
如果百分比偏高,且預留項目在這段期間未充分利用,請與 Cloud Customer Care 聯絡,以便調查。
如果預留項目在工作執行速度緩慢期間已用盡,且百分比偏高,表示工作受到資源限制。請考慮降低並行、增加預留項目大小、允許預留項目使用閒置的運算單元,或在工作依隨選執行時購買預留項目。
工作中繼資料和工作負載分析結果不確定
如果還是找不到查詢效能不如預期的原因,請與 Cloud Customer Care 團隊聯絡尋求協助。
使用 Gemini Cloud Assist 排解查詢問題
如要使用 Gemini Cloud Assist 協助排解查詢失敗或效能問題,請按照下列步驟操作:
前往 Google Cloud 控制台的「BigQuery」頁面。
在 Google Cloud 工具列,點選spark「Open or close Gemini Cloud Assist chat」。
在「Cloud Assist」面板中輸入提示,並附上工作 ID,即可調查執行情況、成效指標或失敗原因。例如:
為什麼 JOB_ID 失敗?為什麼這項工作要花這麼久的時間?JOB_ID總結我過去 24 小時的工作成效。
使用 gcpdiag 排解查詢失敗問題
gcpdiag 是開放原始碼工具。並非官方支援的 Google Cloud 產品。您可以使用 gcpdiag 工具,找出並修正 Google Cloud專案問題。詳情請參閱 GitHub 上的 gcpdiag 專案。
gcpdiag 工具可協助您分析失敗的 BigQuery 查詢,瞭解是否有已知的根本原因,以及特定失敗的緩解措施。
執行 gcpdiag 指令
您可以透過 Google Cloud CLI 執行 gcpdiag 指令:
Google Cloud 控制台
- 完成並複製下列指令。
- 開啟 Google Cloud 控制台,並啟用 Cloud Shell。 開啟 Cloud 控制台
- 貼上複製的指令。
- 執行
gcpdiag指令,下載gcpdiagDocker 映像檔,然後執行診斷檢查。如果適用,請按照輸出內容中的指示修正失敗的檢查。
gcpdiag runbook bigquery/failed-query \
--parameter project_id=PROJECT_ID \
--parameter bigquery_job_region=JOB_REGION \
--parameter bigquery_job_id=JOB_ID \
--parameter bigquery_skip_permission_check=SKIP_PERMISSION_CHECKDocker
您可以使用包裝函式執行 gcpdiag,在 Docker 容器中啟動 gcpdiag。必須安裝 Docker 或 Podman。
- 請複製下列指令,並在本機工作站執行。
curl https://gcpdiag.dev/gcpdiag.sh >gcpdiag && chmod +x gcpdiag
- 執行
gcpdiag指令。./gcpdiag runbook bigquery/failed-query \ --parameter project_id=PROJECT_ID \ --parameter bigquery_job_region=JOB_REGION \ --parameter bigquery_job_id=JOB_ID \ --parameter bigquery_skip_permission_check=SKIP_PERMISSION_CHECK
查看這個 Runbook 的可用參數。
更改下列內容:
- PROJECT_ID:包含資源的專案 ID。
- JOB_REGION:執行 BigQuery 工作的區域。
- JOB_ID:BigQuery 工作的 ID。
- SKIP_PERMISSION_CHECK:(選用) 如要略過相關權限檢查並加快執行手冊執行速度,請將此值設為
True(預設值為False)。
實用旗標:
--universe-domain:託管資源的可信任合作夥伴 Sovereign Cloud 網域 (如適用)--parameter或-p:Runbook 參數
如需所有 gcpdiag 工具旗標的清單和說明,請參閱 gcpdiag 使用說明。
Avro 結構定義解析
錯誤字串:Cannot skip stream
載入多個結構定義不同的 Avro 檔案時,可能會發生這項錯誤,導致結構定義解析問題,並造成匯入工作在隨機檔案失敗。
如要解決這項錯誤,請確保載入工作中最後一個字母順序的檔案,包含不同結構定義的超集 (聯集)。這項規定是根據 Avro 處理結構定義解析的方式而定。
並行查詢衝突
錯誤字串:
Resources exceeded during query execution: Another job JOB_ID is currently running in the session SESSION_ID. Concurrent jobs in the same session are not allowed.Session SESSION_ID has expired and is no longer available.
如果多個查詢在同一個工作階段中同時執行 (不支援),或工作階段在閒置 24 小時後或建立 7 天後自動終止,就會發生這項錯誤。請參閱工作階段限制和自動終止工作階段。
如要解決這個問題,請按照下列其中一種做法進行:
- 請錯開共用
session_id的查詢,並在前一個工作 (JOB_ID) 完成後再啟動下一個查詢,或在不同的工作階段中執行並行查詢。 - 如果工作階段已過期或終止,請建立新的工作階段 (並更新
.bigqueryrc或connectionProperties中的--session_id,如有設定)。請參閱「建立工作階段」。
衝突的 DML 陳述式
錯誤字串:Could not serialize access to table due to concurrent update
如果並行變動 data manipulation language (DML) 陳述式 (UPDATE、DELETE 或 MERGE) 嘗試同時修改同一個資料表分區中的資料,或是在 DML 陳述式執行期間截斷資料表,就會發生這項錯誤。
BigQuery 允許在同一個資料表上執行並行變動 DML 陳述式,只要這些陳述式修改不同的分區即可。不過,如果兩項工作嘗試修改同一個分區,則第一項提交的工作會成功,後續工作則會失敗並顯示這項錯誤。
如要解決這項錯誤,請嘗試下列做法:
- 重試失敗的工作:如果衝突是因為與其他工作暫時重疊,請在衝突的工作完成後重試查詢。
- 找出並協調衝突的工作:執行下一節的診斷查詢,找出競爭的工作,然後協調排程,確保不會同時對同一個分區執行變動 DML 作業。
- 分區資料表:如果並行 DML 工作更新不同的資料區隔,請依日期或整數範圍分區資料表。如果並行變動 DML 陳述式修改不同的分區,則會成功執行,不會發生衝突。
- 批次 DML 作業:將多個獨立的
UPDATE或DELETE作業合併為單一MERGE陳述式或批次工作,以減少並行和修訂負擔。詳情請參閱「最佳做法」。
找出衝突的工作
如要找出發生錯誤時,有哪些工作同時更新資料表,請對 INFORMATION_SCHEMA.JOBS 檢視表執行查詢:
SELECT job_id, query, start_time, end_time FROM `region-REGION`.INFORMATION_SCHEMA.JOBS WHERE creation_time BETWEEN TIMESTAMP_SUB(TIMESTAMP 'FAILED_JOB_START_TIME', INTERVAL 1 DAY) AND TIMESTAMP 'FAILED_JOB_END_TIME' AND destination_table.table_id = 'TABLE_NAME' AND destination_table.dataset_id = 'DATASET_NAME' AND statement_type IN ('UPDATE', 'DELETE', 'MERGE') AND start_time <= 'FAILED_JOB_END_TIME' AND (end_time >= 'FAILED_JOB_START_TIME' OR end_time IS NULL) ORDER BY start_time;
更改下列內容:
REGION:資料集所在的區域名稱,例如us。FAILED_JOB_START_TIME:失敗工作開始的時間戳記,例如2026-09-01 09:55:00 UTC。FAILED_JOB_END_TIME:失敗工作結束的時間戳記,例如2026-09-01 10:00:00 UTC。TABLE_NAME:失敗的 DML 陳述式嘗試更新的資料表名稱。DATASET_NAME:資料表所在資料集的名稱。
如果查詢未傳回任何衝突的使用者啟動工作,則衝突可能是由其他背景作業 (例如分區到期) 引起。
並行更新衝突的其他原因
- 分區到期:如果到期分區的背景系統工作在執行工作期間修改相同分區,可能會與 DML 陳述式發生衝突。如果您使用分區到期功能,請在分區到期時間以外的時間安排 DML 工作。
- 多陳述式交易:當多陳述式交易變更資料表時,會封鎖該資料表上的所有其他並行 DML 陳述式,直到交易完成為止。
- 影響零個資料列的 DML 陳述式:
UPDATE、DELETE或MERGE陳述式會鎖定目標分區,即使沒有任何資料列符合篩選條件,也可能導致序列化衝突。
詳情請參閱「DML 陳述式衝突」。
相互關聯的子查詢
錯誤字串:Correlated subqueries that reference other tables are not
supported unless they can be de-correlated
如果查詢包含的子查詢參照了子查詢外部的資料欄 (稱為「關聯」資料欄),就可能發生這項錯誤。系統會使用效率不佳的巢狀執行策略評估關聯子查詢,其中子查詢會針對產生關聯資料欄的外部查詢中的每個資料列進行評估。有時,BigQuery 可以在內部重寫具有關聯子查詢的查詢,以便更有效率地執行。如果 BigQuery 無法充分最佳化查詢,就會發生關聯子查詢錯誤。
如要解決這項錯誤,請嘗試下列做法:
- 從子查詢中移除任何
ORDER BY、LIMIT、EXISTS、NOT EXISTS或IN子句。 - 使用多重陳述式查詢建立暫存資料表,以便在子查詢中參照。
- 請重寫查詢,改用
CROSS JOIN。
資料欄層級存取控管權限不足
錯誤字串:
Access denied: Requires fineGrainedGet permission on the read columns to execute the DML statements- `Access denied: User does not have permission to access policy tag projects/PROJECT_ID/locations/LOCATION/taxonomies/TAXONOMY_ID/policyTags/POLICY_TAG_ID on column PROJECT_ID.DATASET.TABLE.COLUMN.'
如果嘗試執行 SQL 查詢或 DML DELETE、UPDATE 或 MERGE 陳述式,但未獲派使用資料欄層級存取控管的資料欄精細讀取者角色,就會發生這些錯誤。設定政策標記時,系統會將這個角色指派給主體。詳情請參閱「資料欄層級存取控管對寫入作業的影響」。
如要解決這個問題,請修改查詢,排除含有政策標記的資料欄,或將精細讀取者角色授予使用者。設定政策標記時,系統會將這個角色指派給主體。詳情請參閱「更新政策標記的權限」。
排解排定查詢的問題
設定或執行排定查詢時,可能會發生下列問題。
排定的查詢觸發重複執行作業
排定的查詢可能會在排定時間觸發多次。如果查詢排定在整點 (例如 09:00),就更有可能發生這種情況。這可能會導致非預期的結果,例如查詢執行 INSERT 作業時,可能會產生重複資料。
為盡可能降低重複執行的風險,請將查詢排定在非整點時間,例如整點前後幾分鐘 (例如 08:58 或 09:03)。詳情請參閱「排定查詢」。
排定查詢的憑證無效
錯誤字串:
Error code: INVALID_USERIDError code 5: Authentication failure: User Id not foundPERMISSION_DENIED: BigQuery: Permission denied while getting Drive credentials
如果排定的查詢因憑證過期而失敗,就可能發生這項錯誤,尤其是查詢 Google 雲端硬碟資料時。
如要解決這項錯誤,請按照下列步驟操作:
- 請務必啟用 BigQuery 資料移轉服務,這是使用排定查詢的必要條件。
- 更新排定查詢憑證。
服務帳戶憑證無效
錯誤字串:HttpError 403 when requesting returned: The caller does not have permission
嘗試使用服務帳戶設定排定的查詢時,可能會出現這項錯誤。如要解決這項錯誤,請參閱「授權和權限問題」中的疑難排解步驟。
目的地資料表已刪除或過期
錯誤字串:Destination deleted/expired during operation: DETAILS
如果查詢、載入或複製工作嘗試寫入的目的地資料表,在工作執行完畢前遭到移除,就會發生這個 HTTP 400 Bad Request 錯誤 (reason: invalid)。
診斷
這項錯誤通常是以下兩個原因之一所致:
- 資料表或資料集已達存留時間 (TTL)。目的地資料表 (或資料集的預設資料表到期時間) 已設定到期時間戳記。如果長時間執行的工作在資料表到期時間戳記過後仍繼續執行,BigQuery 會在工作仍在執行時刪除到期資料表。
- 並行明確刪除。其他使用者、服務帳戶或自動化工作流程 (例如自動化調度管理 DAG 或清除指令碼),在工作執行期間對目的地資料表執行
DROP TABLE陳述式或tables.deleteAPI 呼叫。
如要判斷目的地資料表遭到刪除的原因,請查詢 INFORMATION_SCHEMA.TABLE_STORAGE 檢視表:
SELECT table_name, deleted, table_deletion_time, table_deletion_reason FROM `PROJECT_ID`.`region-REGION`.INFORMATION_SCHEMA.TABLE_STORAGE WHERE table_schema = "DATASET_ID" AND table_name = "TABLE_ID"
更改下列內容:
PROJECT_ID:您的專案 ID。REGION:資料表所在資料集的區域。DATASET_ID:資料表所在資料集的 ID。TABLE_ID:目的地資料表的 ID。
如果資料表已過期,table_deletion_reason 欄會包含 TABLE_EXPIRATION;如果使用者刪除了資料表,則會包含 USER_DELETED;如果使用者刪除了包含資料表的資料集,則會包含 DATASET_DELETION。詳情請參閱「找出資料表刪除原因」。
如果原因是 USER_DELETED,請在 Logs Explorer 中查詢 Cloud 稽核記錄,找出刪除資料表的使用者。篩選工作失敗前後的項目:
resource.type=("bigquery_resource" OR "bigquery_dataset")
protoPayload.methodName=("tableservice.delete" OR "google.cloud.bigquery.v2.TableService.DeleteTable")
protoPayload.resourceName:"YOUR_TABLE_NAME"
將 YOUR_TABLE_NAME 替換為目的地資料表的 ID。
檢查相符記錄項目中的 protoPayload.authenticationInfo.principalEmail 欄位,找出刪除資料表的使用者或服務帳戶。
如果原因是 DATASET_DELETION,請使用「找出資料表的刪除時間」中的資料集篩選器。
解析度
如要解決這項錯誤,請執行下列操作:
- 延長資料表和資料集的到期時間。檢查目的地資料表的到期時間,以及資料集的預設資料表到期時間設定。請確保設定的存留時間夠長,足以超過寫入該資料表的工作預期執行時間上限 (包括佇列時間和重試次數)。如需操作說明,請參閱「更新資料表的到期時間」。
- 序列化管道工作。如果自動化 ETL 管道 (例如 Managed Service for Apache Airflow、Apache Airflow 或 Dataform) 會重新建立或清理暫存資料表,請設定嚴格的工作依附元件,確保
DROP TABLE或清理工作不會與針對相同資料表的有效寫入工作同時執行。 - 使用不重複的中繼資料表名稱。執行平行管道執行個體時,請將中繼結果寫入名稱不重複的臨時或暫存資料表 (例如在多陳述式查詢中使用
CREATE TEMP TABLE,或附加不重複的執行 ID),而非在並行執行作業中共用單一可變動的暫存資料表。
對含有串流緩衝區的資料表執行 DML 陳述式
錯誤字串:
UPDATE or DELETE statement over table
PROJECT_ID.DATASET_ID.TABLE_NAME would affect
rows in the streaming buffer, which is not supported
如果變動 DML 陳述式 (UPDATE、DELETE 或 MERGE) 嘗試修改或刪除最近使用舊版 tabledata.insertAll 串流 API 擷取且仍在串流緩衝區中的資料列,就會發生這個 HTTP 400 Bad Request 錯誤 (reason: invalidQuery)。資料列可能會在串流緩衝區中保留幾分鐘,在極少數情況下最多可達 90 分鐘。詳情請參閱「串流資料可用性」和「DML 限制」。
如要解決這個錯誤,請採取下列任一做法:
- 遷移至 BigQuery Storage Write API (gRPC)。使用 BigQuery Storage Write API (gRPC) 串流資料,讓最近寫入的資料列立即可用於變更 DML 陳述式 (
UPDATE、DELETE和MERGE),不受串流緩衝區限制。 - 請等待串流緩衝區清除,或篩除最近的資料列。查看
streamingBuffer區段的tables.get回應。如果沒有streamingBuffer,所有資料列都可用於 DML。您也可以檢查streamingBuffer.oldestEntryTime,並在 DML 陳述式中新增WHERE篩選器,只指定早於串流緩衝區時間範圍的資料列。
查詢無效錯誤
如果 BigQuery 傳回 HTTP 400 Bad Request 錯誤,且錯誤原因為 invalidQuery,表示 SQL 查詢未通過驗證或執行檢查。請根據 BigQuery 傳回的特定錯誤訊息,診斷下列四個類別的問題:
語法和文法錯誤
錯誤字串:
Syntax error: Expected TOKEN but got INPUT at [LINE:COLUMN]Syntax error: Unexpected keyword KEYWORD at [LINE:COLUMN]Unrecognized name: IDENTIFIER at [LINE:COLUMN]或Function not found: FUNCTION_NAME at [LINE:COLUMN]
如要解決語法和 ID 錯誤,請執行下列操作:
- 檢查
[LINE:COLUMN]位置。 檢查錯誤訊息中的行和欄 (以及緊接在前的符記),看看是否有未封閉的括號、缺少逗號、結尾逗號、未逸出的引號,或CASE運算式中缺少END關鍵字。 - 請確認 SQL 子句順序和方言。確認 SQL 子句遵循必要的 GoogleSQL 查詢語法順序 (
SELECT→FROM→WHERE→GROUP BY→HAVING→QUALIFY→ORDER BY→LIMIT),並確認要求使用 GoogleSQL (useLegacySql=false)。如需瞭解舊版 SQL 錯誤,請參閱「舊版 SQL 錯誤」。 - 確認資料欄、別名和函式範圍。如果錯誤回報
Unrecognized name或Function not found,請檢查下列情況:- ID 拼寫錯誤或大小寫不符。請根據資料表結構定義,驗證資料欄或資料表的拼寫和大小寫。
WHERE中參照的SELECT別名。請勿在同一個WHERE子句中參照SELECT清單中定義的別名。請重複運算式、使用子查詢或 CTE,或在QUALIFY中篩選 (適用於視窗函式)。- 未限定的 persistent user-defined function (UDF)。使用
PROJECT_ID.DATASET_ID.FUNCTION_NAME限定 persistent UDF。 - 特殊字元或保留關鍵字。如果資料表或資料欄名稱含有特殊字元或保留關鍵字,請用反引號 (
`) 括住。您也可以在 BigQuery Studio 中使用查詢驗證工具,在執行查詢前找出語法問題。
資料類型相容性錯誤
錯誤字串:
No matching signature for operator OPERATOR for argument types: TYPE_A, TYPE_BNo matching signature for function FUNCTION_NAME for argument types: ARG_TYPESQuery column COLUMN_NUMBER has type SOURCE_TYPE which cannot be inserted into column TARGET_COLUMN, which has type TARGET_TYPEUnsupported type TYPE
如要解決資料類型不符的問題,請按照下列步驟操作:
- 在比較、彙整和函式中調整類型。查詢
INFORMATION_SCHEMA.COLUMNS或在Google Cloud 控制台中檢查資料表結構定義,確認所有輸入內容在下列位置使用相容的 GoogleSQL 資料類型:WHERE個篩選器和JOIN ... ON個鍵COALESCE和IFNULL引數UNION和INSERT ... SELECT欄位置- UDF 引數和傳回類型 (包括 JavaScript UDF
RETURNS類型) - BigQuery ML 函式 (
ML.EVALUATE、ML.PREDICT)
- 套用明確類型轉換。請使用
CAST()或SAFE_CAST(),或日期和時間剖析函式 (例如PARSE_DATE、PARSE_TIMESTAMP和TIMESTAMP_SECONDS) 明確轉換值,而非依賴隱含強制轉型。 - 處理不支援的匯出或聯合類型。對不支援的複雜或地理類型 (例如
GEOGRAPHY、INTERVAL或BIGNUMERIC) 執行EXPORT DATA或聯合查詢時,請選擇下列其中一個選項:- 在
SELECT清單中,將資料欄轉換為STRING。 - 請將
EXPORT DATA格式切換為AVRO或PARQUET,以保留類型保真度。
- 在
功能和架構限制
錯誤字串:
Invalid table-valued function FUNCTION_NAME或Missing required option OPTION_NAMEUnsupported aggregate function in materialized viewCannot query over table 'TABLE_NAME' without a filter over column(s) 'COLUMN_NAME' that can be used for partition eliminationUPDATE/MERGE must match at most one source row for each target rowInvalid snapshot timeToo many nested views/persistent user-defined functions...Too many partitions produced by query, allowed LIMIT, query produces at least COUNT partitionsResource exhausted. The model might be too large.
如要解決功能、DDL 和查詢限制錯誤,請執行下列操作:
- 確認 DDL 陳述式中必要的
OPTIONS(...)。建立外部資料表、遠端函式或模型時,請確認OPTIONS子句中已指定所有必要選項 (例如外部資料表的format和uris),且類型有效。請參閱「資料定義語言 (DDL) 陳述式」。 - 查看 materialized view SQL 限制。materialized view 支援受限的 SQL 匯總子集,且無法參照非確定性函式,例如
CURRENT_DATE()、RAND()或SESSION_USER()。請參閱「支援的 materialized view」。 - 加入必要的分區篩選器。如果目標資料表強制執行
require_partition_filter = true,請在可剪除分區的分區資料欄中加入WHERE述詞。請參閱「查詢分區資料表」。 - 簡化
UPDATE或MERGE來源資料列。如果UPDATE或MERGE陳述式因多個來源資料列與單一目標資料列相符而失敗,請匯總或簡化FROM或USING來源 (例如使用GROUP BY或QUALIFY ROW_NUMBER() OVER (...) = 1)。請參閱「DML 限制」。 - 遵守分區和 BigQuery ML 模型限制。如果查詢失敗並顯示
Too many partitions produced by query, allowed LIMIT, query produces at least COUNT partitions錯誤,請將查詢分割成較小的批次,每項工作修改的分區不超過 4,000 個。您也可以使用較粗略的分區,例如按月而非按日分區,並搭配分群,讓每項工作修改較少的分區,並將資料表保持在 10,000 個分區限制內。如果CREATE MODEL陳述式失敗並顯示Resource exhausted. The model might be too large錯誤,請減少輸入特徵、分組或篩除高基數類別值,或在建立 BigQuery ML 模型時簡化模型架構。例如減少樹狀結構深度、樹狀結構數量或隱藏單元。 - 查看時間旅行、檢視巢狀結構和子查詢限制。請根據錯誤訊息,參閱下列其中一節:
FOR SYSTEM_TIME AS OF在保留期外。請參閱「快照時間無效」。- 檢視表或常式超過 16 層巢狀深度限制。請參閱「巢狀檢視或 persistent user-defined function 數量過多」。
- 不支援關聯子查詢。請參閱「關聯子查詢」。
執行狀態和並行限制
錯誤字串:
Concurrent conflicting update to DML transaction conflict或Could not serialize access to table TABLE_NAME due to concurrent updateTransaction is aborted due to concurrent update against table TABLE_NAMEUPDATE or DELETE statement over table TABLE_NAME would affect rows in the streaming buffer, which is not supported
如要解決執行狀態和並行錯誤,請參閱錯誤訊息的專屬章節:
- 並行 DML 或交易衝突。請參閱「衝突的 DML 陳述式」和「因並行更新而中止交易」。
- 對含有有效串流緩衝區的資料表執行 DML。請參閱「對含有串流緩衝區的資料表執行 DML 陳述式」。
快照時間無效
錯誤字串:Invalid snapshot time
嘗試查詢資料集時光旅行時間範圍以外的歷來資料時,可能會發生這項錯誤。如要解決這個錯誤,請變更查詢,在資料集的時間旅行期間內存取歷來資料。
如果查詢中使用的其中一個資料表在查詢開始後遭到捨棄並重新建立,也可能出現這項錯誤。請檢查是否有排定的查詢或應用程式執行這項作業,且與失敗的查詢同時執行。如果有的話,請嘗試將執行捨棄和重新建立作業的程序,移至與讀取該資料表的查詢不衝突的時間執行。
工作已存在
錯誤字串:Already Exists: Job <job name>
如果查詢工作必須評估大型陣列,建立查詢工作的時間會比平均時間長,因此可能會發生這項錯誤。例如,含有 WHERE 子句的查詢,例如 WHERE column IN (<2000+ elements array>)。
如要解決這項錯誤,請按照下列步驟操作:
如果您手動設定工作 ID,但工作未在逾時期間內成功傳回,也可能發生這項錯誤。在這種情況下,您可以新增例外狀況處理常式,檢查工作是否存在。如果已完成,您就可以從工作中提取查詢結果。
找不到所需工作
錯誤字串:Job not found
如果 getQueryResults 呼叫未指定 location 欄位的值,就可能發生這項錯誤。如果是這種情況,請再次嘗試呼叫,並提供 location 值。
詳情請參閱「避免多次評估相同的一般資料表運算式 (CTE)」。
找不到位置
錯誤字串:Dataset [project_id]:[dataset_id] was not found in location [region]
如果參照的資料集資源不存在,或要求中的位置與資料集的位置不符,系統就會傳回這項錯誤。
如要解決這個問題,請在查詢中指定資料集的位置,或確認資料集位於相同位置。
查詢超過執行時間限制
錯誤字串:
Query fails due to reaching the execution time limitOperation timed out after 6.0 hours. Consider reducing the amount of work performed by your operation so that it can complete within this limit.Dry run query timed out.Request timed out. Please try again. at [LINE:COLUMN]BigQuery external table schema detection timed out.
如果作業超過執行時間限制,就會發生這個 HTTP 400 Bad Request 錯誤 (reason: timeout)。如果工作超過您設定的自訂 configuration.jobTimeoutMs 值,BigQuery 會取消工作並傳回 reason: stopped (請參閱「工作執行已取消」)。
請根據錯誤訊息找出子類型和解決方法:
查詢或模擬測試執行時間限制 (
Operation timed out after 6.0 hours或Dry run query timed out.): 減少作業執行的工作量,以便在 6 小時的查詢執行時間限制內完成,例如篩選分區或叢集資料欄、簡化複雜的 join,或將大型查詢拆分為較小的階段。您也可以查詢INFORMATION_SCHEMA.JOBS檢視表,比較先前執行的執行時間:SELECT TIMESTAMP_DIFF(end_time, start_time, SECOND) AS runtime_in_seconds FROM `region-us`.INFORMATION_SCHEMA.JOBS WHERE statement_type = 'QUERY' AND query = "my query string";
如果先前的執行時間明顯較短,請使用查詢效能深入分析診斷迴歸。
多重陳述式查詢子項工作逾時 (
Request timed out. Please try again. at [LINE:COLUMN]):多重陳述式查詢中的陳述式達到 6 小時的執行時間限制或逾時。請檢查回報的行和欄,或列舉子工作,找出並最佳化逾時的陳述式。外部資料表結構定義自動偵測逾時 (
BigQuery external table schema detection timed out.): 建立或更新外部資料表時,結構定義自動偵測逾時。請指定明確的結構定義,不要依賴自動偵測功能、縮小來源 URI 範圍,使其比對較少檔案,或使用CREATE EXTERNAL TABLEDDL 陳述式建立資料表。
查詢超過計費位元組數上限
錯誤字串:Query exceeded limit for bytes billed: LIMIT_BYTES. REQUIRED_BYTES or higher required.
如果查詢預估會產生費用的位元組數 (REQUIRED_BYTES) 超過 maximumBytesBilled (LIMIT_BYTES) 中設定的位元組限制,就會發生這個 HTTP 400 Bad Request 錯誤 (reason: bytesBilledLimitExceeded)。BigQuery 會在執行前失敗,且不會收取查詢費用。
由於隨選定價會對每個參照資料表強制執行 10 MB (10,485,760 位元組) 的下限,且分群資料表的預先執行估算會在分群剪除發生前,計算所有相符分區的上限,因此 REQUIRED_BYTES 可能會高於查詢執行時掃描的實際位元組數。
如要解決這個問題,請按照下列其中一種做法進行:
- 透過模擬測試預覽預估位元組數。執行模擬測試 (bq CLI 中的
bq query --dry_run或 API 中的configuration.dryRun = true),或在 Google Cloud 控制台中查看查詢驗證工具,在執行查詢前檢查totalBytesProcessed。 - 最佳化查詢,減少掃描的位元組數。請只選取查詢所需的資料欄,而非執行
SELECT *,並篩選分區資料欄,讓 BigQuery 在預先執行估算期間能剪除分區。篩選分群欄可減少查詢執行時實際計費的位元組數,但不會減少執行前根據maximumBytesBilled檢查的預估上限。詳情請參閱「減少處理的資料」。 - 提高
maximumBytesBilled限制。請使用 Google Cloud 控制台中的「Maximum bytes billed」(計費位元組上限) (位於「Query settings」(查詢設定) >「Advanced options」(進階選項) 下方)、bq CLI 中的--maximum_bytes_billed旗標,或 API 中的configuration.query.maximumBytesBilled工作設定屬性,將maximumBytesBilled位元組限制設為等於或高於錯誤訊息中回報的REQUIRED_BYTES值。
查詢回應過大
錯誤字串:responseTooLarge
如果查詢結果大於回應大小上限,或單一資料列超過 REST API 資料列大小限制,就會發生這項錯誤。
有些查詢會分多個階段執行,如果任何階段傳回的回應大小過大,即使最終結果小於上限,也會發生這項錯誤。如果查詢使用 ORDER BY 子句,通常會發生這項錯誤。移除 ORDER BY 子句或新增 LIMIT 子句有時可以解決問題。為確保能傳回大型結果,請在工作設定中指定目的地資料表。如果是舊版 SQL 查詢,您也必須將 configuration.query.allowLargeResults 屬性設為 true。詳情請參閱「寫入大型查詢結果」。
超過單列回應大小上限
錯誤字串:
Response too large to return. Message before conversion exceeds max row limit, limit: LIMIT actual: ACTUALResponse too large to return. single row too big to return due to byte limit, actual: ACTUAL limit: LIMIT
使用
jobs.getQueryResults
或 tabledata.list REST API
方法讀取查詢結果或資料表列 (包括在 Google Cloud 控制台或
bq 指令列工具中顯示結果) 時,
如果單一未巢狀序列化資料列超過 REST 分頁端點
支援的大小上限
(jobs.getQueryResults 為 20 MB,
tabledata.list 為 100 MB),就會發生這個 HTTP 403 Forbidden 錯誤 (reason: responseTooLarge)。
如果資料表含有寬結構定義、深度巢狀重複
ARRAY 或 STRUCT 欄位,或大型 STRING 或 BYTES 值,通常會發生這種情況。
如要讀取超過 REST API 資料列大小限制的資料列,請採取下列任一做法:
- 使用 BigQuery Storage Read API。使用 Storage Read API 讀取資料表或臨時查詢目的地資料表,該 API 會以二進位 Apache Arrow 或 Avro 格式串流資料,並支援大型和複雜資料列結構的高處理量讀取作業。
- 將資料表匯出至 Cloud Storage。使用
EXPORT DATA陳述式或擷取工作,將資料表或查詢結果匯出至 Cloud Storage (例如 Avro、Parquet 或 JSON 格式),然後從 Cloud Storage 讀取匯出的檔案。 - 投影或匯總較少的資料欄。請勿執行
SELECT *,而是只選取應用程式所需的特定資料欄或子欄位,或在查詢中取消巢狀重複陣列,讓個別輸出資料列保持在大小限制內。
缺少必要參數
錯誤字串:Required parameter is missing: PARAMETER_NAME
這項 HTTP 400 Bad Request 錯誤 (reason: required) 是預先執行的 API 驗證錯誤,會在 API 要求酬載或網址中缺少必要欄位,或用戶端程式庫設定物件的必要屬性為 null 或 None 時發生。
如要解決這項錯誤,請執行下列操作:
- 查看 REST API 參考資料。檢查錯誤訊息中的
PARAMETER_NAME,並在 BigQuery REST API 參考資料中,查看該方法所需的要求主體和查詢參數,確保程式碼填入所有必填欄位。 - 驗證用戶端程式庫參數。如果您使用 BigQuery 用戶端程式庫 (例如 Java 或 Python 用戶端程式庫),請參閱用戶端程式庫說明文件,瞭解所呼叫方法的必要參數。
- 呼叫 API 前,請先檢查設定物件。在 API 呼叫執行前,使用偵錯工具或記錄陳述式檢查工作或要求設定物件,並檢查指派給必要屬性 (例如
destinationTable) 的None或null值。
找不到預留項目或缺少運算單元
錯誤字串:Cannot run query: project does not have the reservation in the data region or no slots are configured
如果指派給查詢區域中專案的預留項目未指派任何運算單元,就會發生這個錯誤。您可以將運算單元新增至預留項目、允許預留項目使用閒置運算單元、使用其他預留項目,或移除指派作業並視需求執行查詢。
找不到資料表
錯誤字串:Not found: Table [project_id]:[dataset].[table_name] was not found in location [region]
如果查詢中的資料表不在您指定的資料集或區域,就會發生這項錯誤。如要解決這項錯誤,請執行下列任一操作:
- 確認查詢包含正確的專案、資料集和資料表名稱,並確認 ID 的大小寫完全正確 (請參閱「區分大小寫」)。如果查詢省略專案 ID,BigQuery 預設會使用執行工作的計費專案。查詢其他專案中的資料表時,請指定完整
PROJECT_ID.DATASET_ID.TABLE_NAME。 - 請確認資料表位於查詢執行位置。根據預設,查詢讀取或寫入的每個資料集,都必須與查詢工作位於相同位置。如果您自行設定工作位置 (例如使用
--location旗標或工作參照中的location屬性),請確保該位置與資料集的位置相符。單一區域 (例如us-central1) 與多區域 (例如US) 不相符。詳情請參閱「指定位置」。 - 如要在單一查詢中查詢不同位置的資料表,請使用全域查詢(預先發布版)。執行查詢的專案和包含資料的專案都必須啟用全域查詢,且沙箱模式不支援全域查詢。
- 請查詢
INFORMATION_SCHEMA.TABLE_STORAGE,或檢查 Cloud 稽核記錄中的DeleteTable或InternalTableExpired事件,確認資料表或資料集是否已過期或刪除。如果資料表是在時間旅行期間 (最多 7 天) 內刪除,您可以還原刪除的資料表。如果父項資料集也已刪除,請先重新建立名稱和位置完全相同的空白資料集,再複製歷來快照。 - 如果您在以底線 (
_) 開頭的隱藏資料集中,查詢匿名快取結果資料表,請注意,快取結果資料表會在約 24 小時後過期。請重新執行原始查詢,或將輸出內容寫入永久目的地資料表。 - 如果您查詢的是由 Cloud Storage 或 Google 雲端硬碟支援的外部資料表,請確認基礎來源檔案仍存在於設定的 URI 路徑 (
Not found: URI、Not found: Uris或Not found: Files)。 - 請確認資料表在工作執行期間未遭到捨棄及重新建立。否則,中繼資料傳播不完整可能會導致這項錯誤。
DML 陳述式過多
錯誤字串:Too many DML statements outstanding against <table-name>, limit is 20
如果單一資料表的佇列中,處於 PENDING 狀態的變動 DML 陳述式超過 20 個,就會發生這項錯誤。如果提交 DML 工作的速度超過 BigQuery 處理單一資料表的速度,通常就會發生這項錯誤。
如要查看佇列中處於 PENDING 狀態的工作,以及可能導致這些工作無法移出佇列的 RUNNING 工作,請查詢 INFORMATION_SCHEMA.JOBS 檢視表:
SELECT
project_id,
job_id,
creation_time,
user_email,
statement_type,
state
FROM
`region-us`.INFORMATION_SCHEMA.JOBS
WHERE
statement_type IN ('UPDATE', 'DELETE', 'MERGE', 'TRUNCATE_TABLE')
AND state IN ('RUNNING', 'PENDING')
ORDER BY
creation_time DESC;
其中一個可能的解決方案,是將多項較小的 DML 作業分組為較大但數量較少的工作,例如批次更新和插入。將較小的工作分組為較大的工作時,執行較大工作的成本會分攤,且執行速度會更快。合併影響相同資料的 DML 陳述式,通常可以提高 DML 工作的效率,且較不可能超出佇列大小配額限制。如要進一步瞭解如何最佳化 DML 作業,請參閱「避免使用更新或插入單一資料列的 DML 陳述式」。
其他提高 DML 效率的解決方案包括將資料表分區或分群。詳情請參閱「最佳做法」。
錯誤 403:超過配額
錯誤字串:403 Quota exceeded: Your table exceeded quota for total number of
DML jobs writing to a table, pending + running.
如果寫入單一資料表的 DML 工作 (INSERT、UPDATE、DELETE 和 MERGE) 總數 (包括 PENDING 和 RUNNING 狀態) 超過資料表的並行配額,就會發生這項錯誤。
limit is 20 錯誤會特別限制 PENDING 佇列,不允許變更 DML 陳述式 (UPDATE、DELETE 和 MERGE),而 403 Quota
exceeded 錯誤則適用於同時寫入資料表的所有 DML 工作 (INSERT 加上變更 DML) 總和。由於 DML 異動作業已受限於 20 項工作的佇列限制,因此當您對單一資料表提交過多並行 INSERT 查詢時,最常發生這項 403 配額錯誤。如要解決這項錯誤,請按照下列步驟操作:
- 增加預留項目運算單元:增加預留項目中的運算單元數量,加快工作完成速度並減少工作並行。這可減少佇列中待處理工作的數量,並有助於避免達到限制。
- 最佳化工作流程自動化調度管理:限制自動化調度管理工具中的並行 DML 工作數量,避免超出資料表層級的並行限制 (包括針對相同資料表的高頻率
INSERT查詢)。 - 批次 DML 作業:將多個較小的 DML 陳述式合併為較少、較大的陳述式,減少資料表排入佇列的工作總數。
巢狀檢視表或 persistent user-defined function 過多
錯誤字串:Too many nested views/persistent user-defined functions or possible circular reference of views/persistent user-defined functions referenced in query. Only 16 levels of nested views/persistent user-defined functions are allowed.
如果查詢
或檢視表建立作業參照的檢視表鏈結或永久使用者定義
函式 (UDF) 超過支援的巢狀深度上限 (16 層),
或查詢參照的檢視表或 UDF 在循環
相依迴圈中相互參照 (例如 view_a 查詢 view_b,而 查詢
view_a),就會發生這個 HTTP 400 Bad Request 錯誤 (reason: invalidQuery)。如要進一步瞭解檢視表和常式限制,請參閱
「檢視表限制」和
「UDF 限制」。如果錯誤是因為 STRUCT (RECORD) 欄、載入檔案或巢狀常式引數和傳回類型超過 15 層巢狀結構限制所造成,請參閱「排解結構定義、檔案和常式巢狀結構限制錯誤」。
您最多可以建立 16 層巢狀結構的檢視表,但查詢最多只能參照 15 層巢狀結構的檢視表。
此上限無法提高。如要解決這項錯誤,請執行下列操作:
- 檢查是否有循環參照。檢查查詢鏈結中的檢視表和 persistent UDF 定義,確認沒有任何檢視表或函式直接或間接參照自身。
- 整合巢狀檢視畫面。將中繼邏輯合併至單一檢視表或查詢中的一般資料表運算式 (
WITH子句),藉此重構巢狀檢視表鏈結。 - 具體化中繼層。在深層檢視區塊階層中,將中繼層替換為寫入實體資料表的排定查詢,或使用支援的 materialized view。
並行更新導致交易中止
錯誤字串:Transaction is aborted due to concurrent update against table [table_name]
如果兩個不同的變動 DML 陳述式嘗試同時更新同一個資料表,就可能發生這項錯誤。舉例來說,假設您在工作階段中啟動交易,其中包含變動 DML 陳述式,後面接著錯誤。如果沒有例外狀況處理常式,BigQuery 會在工作階段結束時自動復原交易,最多需要 24 小時。在此期間,其他嘗試在資料表上執行變動 DML 陳述式的作業都會失敗。
如要解決這項錯誤,請列出有效工作階段,並檢查其中是否有任何工作階段包含狀態為 ERROR 的查詢工作,且該工作在資料表上執行了變動 DML 陳述式。在該工作階段中執行 ROLLBACK TRANSACTION;,復原未提交的交易,或執行 CALL BQ.ABORT_SESSION(SESSION_ID); 終止該工作階段。為避免失敗的多重陳述式交易在工作階段到期前保留資料表鎖定,請在多重陳述式交易中加入 EXCEPTION WHEN ERROR THEN ROLLBACK TRANSACTION; 處理常式。
錯誤 412:工作參照的資料表屬於容錯移轉資料集
錯誤字串:Error 412: The job references a table that belongs to a failover dataset in the ... region (PROJECT_ID:DATASET_ID). However, only jobs that run on a reservation with the "ENTERPRISE_PLUS" edition can modify or write to failover datasets. Please also make sure that the job that is writing to the failover dataset is running in the current primary location.
這表示工作並非在 BigQuery Enterprise Plus 版本下執行,或是在容錯移轉資料集主要位置以外的區域執行。詳情請參閱「代管災難復原」。
使用快取結果時,載入檢視畫面發生錯誤
錯誤字串:BigQuery data export: There was an error loading this view. IAM
setPolicy failed for Dataset <PROJECT_ID>. One or more users named in the policy
do not belong to a permitted customer.
這項錯誤代表您的 Google Workspace 客戶 ID 未獲得組織政策限制的存取權。如要瞭解如何使用 iam.allowedPolicyMemberDomains 限制,請參閱「使用 iam.allowedPolicyMemberDomains 限制實施網域限制共用」。
舊版 SQL 錯誤
使用舊版 SQL 時,可能會發生下列錯誤。
Cannot be queried with legacy SQL
錯誤字串:cannot be queried with legacy SQL. Please consider switching to standard SQL
發生這項錯誤的原因有兩種:
查詢是以標準 SQL 編寫,但已提供明確使用舊版 SQL 的選項。請務必按照公開文件,使用標準 SQL 執行查詢,例如使用 bq 指令列工具提供
--use_legacy_sql=false。您嘗試使用舊版 SQL 查詢含有定序的資料表,但系統不支援這項操作。
無法使用舊版 SQL 查詢資料欄已重新命名的資料表
錯誤字串:Table project:dataset.table with renamed columns cannot be queried with legacy SQL. Please consider switching to standard SQL or dropping column my_column
如果使用舊版 SQL 查詢資料欄已重新命名的資料表,就會發生這項錯誤。請改用標準 SQL。
使用者沒有權限
錯誤字串:
Access Denied: Project [project_id]: User does not have bigquery.jobs.create permission in project [project_id].User does not have permission to query table project-id:dataset.table.Access Denied: User does not have permission to query table or perhaps it does not exist.
執行查詢時,如果對執行查詢的專案沒有 bigquery.jobs.create 權限,就可能發生這些錯誤,無論您對包含資料的專案具備哪些權限。
如果服務帳戶、使用者或群組對查詢參照的所有資料表和檢視表沒有 bigquery.tables.getData 權限,也可能收到這些錯誤。如要進一步瞭解執行查詢所需的權限,請參閱「必要角色」。
如果資料表不存在於查詢的區域 (例如 asia-south1),也可能發生這些錯誤。您可以查看資料集位置來驗證區域。
解決這些錯誤時,請考量下列事項:
服務帳戶:服務帳戶必須具備執行專案的
bigquery.jobs.create權限,以及查詢參照的所有資料表和檢視表的bigquery.tables.getData權限。自訂角色:自訂 IAM 角色必須在相關角色中明確包含
bigquery.jobs.create權限,且必須對查詢參照的所有資料表和檢視表具備bigquery.tables.getData權限。共用資料集:在獨立專案中使用共用資料集時,您可能仍需要專案中的
bigquery.jobs.create權限,才能在該資料集中執行查詢或工作。
如要授予資料表或檢視表的存取權限,請參閱「授予資料表或檢視表的存取權」。
預留項目的 bigquery.reservations.use 權限遭拒
錯誤字串:
Access Denied: Reservation projects/project/locations/region/reservations/reservation_name: Permission bigquery.reservations.use denied on reservation projects/project/locations/region/reservations/reservation_name (or it may not exist)
如果使用 SET @@reservation 陳述式指派查詢在特定預留項目中執行,但使用者或服務帳戶缺少 bigquery.reservations.use 權限,就會發生這個錯誤。您可以在 Cloud Logging 或 BigQuery 工作頁面中檢查失敗,找出嘗試執行這項作業的主體。
其他 Access Denied 錯誤
錯誤字串:
Access Denied: Dataset project_id:dataset_id: Permission bigquery.datasets.get denied on dataset project_id:dataset_id (or it may not exist).Access Denied: Dataset project_id:dataset_id: Permission bigquery.datasets.update denied on dataset project_id:dataset_id (or it may not exist).Access Denied: BigQuery BigQuery: User does not have permission to access data protected by policy tag
如要排解 BigQuery 中的一般 Access Denied 錯誤,請使用政策分析工具判斷主體對資源具備哪些存取權。
在政策分析工具中,提供您嘗試存取的 BigQuery 資源 (例如 //bigquery.googleapis.com/projects/YOUR_PROJECT/datasets/YOUR_DATASET/tables/YOUR_TABLE),以及收到 Access Denied 錯誤的使用者或服務帳戶電子郵件地址做為主體。分析結果會顯示主體對資源的權限,您可以與錯誤訊息中缺少的權限進行比較。
指令碼不支援目的地加密
錯誤字串:configuration.query.destinationEncryptionConfiguration cannot be set for scripts
嘗試為 BigQuery 指令碼工作設定目的地加密設定時,就會發生這項錯誤,因為系統不支援這項操作。
組織政策禁止存取
錯誤字串:
IAM setPolicy failed for Dataset DATASET: Operation
denied by org policy on resource.
如果組織政策禁止主體查詢 BigQuery 資源,就會發生這項錯誤。組織政策服務可讓您在整個組織階層中,對支援的資源強制執行限制。
如果主體應有權存取資源,請使用可用的 VPC 疑難排解工具,診斷組織政策的問題。
資源超出問題
如果 BigQuery 沒有足夠的資源來完成查詢,就會發生下列問題。
查詢超過 CPU 資源
錯誤字串:Query exceeded resource limits. This query used
CPU_SECONDS_USED CPU seconds but would charge only
ANALYSIS_MEGABYTES_BILLEDM Analysis bytes. This exceeds the ratio
supported by the on-demand pricing model. Please consider moving this workload
to a capacity-based pricing model, which does not have this limit.
CPU_SECONDS_USED CPU seconds were used, and this query must use less
than CPU_SECONDS_LIMIT CPU seconds.
如果使用隨選計價模式的查詢超出每 MiB 掃描資料的 CPU 用量上限 (約 256 CPU 秒),就會發生這項錯誤 (billingTierLimitExceeded)。如果隨選查詢對相對少量的掃描資料執行 CPU 密集作業,例如不受限制的 CROSS
JOIN 作業、不精確的彙整條件、複雜的規則運算式、未分區的分析視窗函式,或運算量大的 JavaScript UDF,就會發生這種情況。
如要解決這個錯誤,請採取下列任一做法:
- 最佳化查詢。重構 SQL,減少掃描資料的運算負擔,例如移除非預期的笛卡爾乘積 (不含篩選條件的
CROSS JOIN作業)、取代不精確的 join 述詞、簡化複雜的規則運算式、在大型未分區視窗的 window 函式中加入PARTITION BY子句,或最佳化 JavaScript UDF。詳情請參閱「避免反 SQL 模式」、「最佳化查詢效能簡介」和「排解資源超出問題」。 - 改用依運算資源計價模式。使用以運算資源 (運算單元) 為基礎的計價模式執行工作負載。在運算資源定價模式中,查詢不受隨選 CPU 與位元組比率限制。
查詢超過記憶體資源
錯誤字串:Resources exceeded during query execution: The query could not be executed in the allotted memory
如果是 SELECT 陳述式,當查詢使用的資源過多時,就會發生這項錯誤。如要解決這項錯誤,請參閱「排解資源超出限制的問題」。
堆疊空間不足
錯誤字串:Out of stack space due to deeply nested query expression during query resolution.
如果查詢包含過多巢狀函式呼叫,就可能發生這項錯誤。有時,查詢的某些部分會在剖析期間轉譯為函式呼叫。例如,具有重複串連運算子的運算式 (例如 A || B || C || ...CONCAT(A, CONCAT(B, CONCAT(C, ...)))
如要解決這個錯誤,請重寫查詢,減少巢狀結構數量。
查詢執行期間資源超出上限
錯誤字串:Resources exceeded during query execution: The query could not be executed in the allotted memory. Peak usage: [percentage]% of limit. Top memory consumer(s): ORDER BY operations.
ORDER BY ... LIMIT ... OFFSET ... 查詢可能會發生這種情況。由於實作細節,排序可能會在單一運算單元上進行,如果需要在套用 LIMIT 和 OFFSET 之前處理過多資料列,可能會記憶體不足,尤其是 OFFSET 較大時。
如要解決這項錯誤,請避免在 ORDER BY ... LIMIT 查詢中使用過大的 OFFSET 值。或者,您也可以使用可擴充的 ROW_NUMBER() 視窗函式,根據所選順序指派排名,然後在 WHERE 子句中篩選這些排名。例如:
SELECT ...
FROM (
SELECT ROW_NUMBER() OVER (ORDER BY ...) AS rn
FROM ...
)
WHERE rn > @start_index AND rn <= @page_size + @start_index -- note that row_number() starts with 1
TensorFlow worker 記憶體不足
錯誤字串:Resources exceeded during query execution: TENSORFLOW worker out
of memory。
如果模型超出記憶體限制 (通常為 250 MB),特別是使用 ML.EXPLAIN_PREDICT 等需要大量資源的函式時,就可能觸發這項錯誤。
如要解決這項錯誤,請執行下列任一操作:
使用 Gemini Enterprise Agent Platform 遠端模型:如果模型超出記憶體限制,請使用 Vertex AI SDK for Python 部署模型,將模型部署至 Agent Platform,然後使用遠端模型存取模型。這會將記憶體需求卸載至專屬的 Agent Platform 基礎架構。
最佳化模型:透過簡化架構、量化或剪枝,減少模型占用的 RAM 空間。
使用較不耗費資源的函式:如果錯誤發生在
ML.EXPLAIN_PREDICT呼叫期間,請嘗試使用ML.PREDICT執行工作,判斷模型是否能在不耗費額外資源的情況下執行可解釋性功能。分析輸入資料大小:個別資料列過大可能會導致記憶體耗盡。使用下列指令,查看最大資料列的大小:
SELECT BYTE_LENGTH(TO_JSON_STRING(t)) AS row_size FROM your_table AS t ORDER BY row_size DESC LIMIT 10
查詢超過重組資源
錯誤字串:Resources exceeded during query execution: Your project or organization exceeded the maximum disk and memory limit available for shuffle operations
如果查詢無法存取足夠的重組資源,就會發生這項錯誤。
如要解決這個錯誤,請佈建更多運算單元,或減少查詢處理的資料量。如要進一步瞭解如何執行這項操作,請參閱「重組配額不足」。
如果使用隨選定價模式,則最多只能使用 2,000 個運算單元。如要增加運算單元數量,必須改用依運算資源計費的定價模式。
如要進一步瞭解如何解決這些問題,請參閱「排解資源超出限制的問題」。
查詢過於複雜
錯誤字串:
Resources exceeded during query execution: Not enough resources for query planning - too many subqueries or query is too complex.Resources exceeded during query execution: Not enough resources for query planning - too many fields accessed or query is too complex.Resources exceeded during query execution: Not enough resources for query planning - query is too complex.Resources exceeded during query execution: The query is too complex.
在查詢計畫期間展開檢視表、WITH 子句和 SQL user-defined function (UDF) 後,如果查詢過於複雜,就會發生這項錯誤。造成複雜性的主要原因如下:
WITH子句深度巢狀或重複使用。- 深度巢狀或重複使用的檢視畫面。
- 重複使用
UNION ALL運算子。 - 複雜的 SQL UDF 或新增多個資料欄的廣泛參照資料表。
如要解決這項錯誤,請嘗試下列方法:
- 將查詢拆分為多個查詢,然後使用程序語言,以共用狀態依序執行這些查詢。
- 使用臨時資料表,而非
WITH子句或深度巢狀檢視表。請參閱「避免多次評估相同的 CTE」。 - 改寫查詢,減少參照的物件、資料欄和比較項目數量。
您可以使用 INFORMATION_SCHEMA.JOBS 檢視表中的 query_info.resource_warning 欄位,主動監控接近複雜度限制的查詢。下列範例會傳回過去三天內資源用量偏高的查詢:
SELECT
ANY_VALUE(query) AS query,
MAX(query_info.resource_warning) AS resource_warning
FROM
<your_project_id>.`region-us`.INFORMATION_SCHEMA.JOBS
WHERE
creation_time > TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 3 DAY)
AND query_info.resource_warning IS NOT NULL
GROUP BY
query_info.query_hashes.normalized_literals
LIMIT
1000
如要進一步瞭解如何解決這些問題,請參閱「排解資源超出限制的問題」。
排解資源用量超出上限的問題
查詢工作:
如要最佳化查詢,請嘗試下列步驟:
- 請嘗試移除
ORDER BY子句 (特別是子查詢或WITH子句中的子句)、新增LIMIT子句,或在回報Top memory consumer(s): ORDER BY operations時使用ROW_NUMBER() OVER (ORDER BY ...)而非大型OFFSET進行分頁。請參閱「查詢超出記憶體資源」。 - 如果查詢失敗,並顯示
Top memory consumer(s): sort operations used for analytic OVER() clauses或analytic OVER() clauses,請重寫查詢,減少每個視窗分區中的資料量 (新增或精簡PARTITION BY鍵),或在適用情況下,將RANGE BETWEEN替換為有界限的ROWS BETWEEN視窗框架。 - 如果查詢使用
JOIN(或因Top memory consumer(s): JOIN operations而失敗),請確認較大的資料表位於子句左側,且資料不含重複的彙整索引鍵。如果CROSS JOIN後面接著GROUP BY超出記憶體,請先將CROSS JOIN的中繼結果儲存至暫存資料表,再執行GROUP BY。 - 如果變動 DML 陳述式失敗並顯示
Top memory consumer(s): sort operation used for table update (UPDATE/DELETE/MERGE),請分割UPDATE或MERGE陳述式,一次更新較少資料列或資料欄 (或將使用ON FALSE的MERGE替換為多陳述式交易中的INSERT和DELETE)。 - 如果查詢失敗並顯示
Top memory consumer(s): query parsing and optimization,請將大型硬式編碼文字清單儲存在臨時資料表,而非內嵌在查詢文字中,或將查詢拆分為較小的查詢。 - 如果查詢失敗並顯示
UDF out of memory或Top memory consumer(s): non-SQL user-defined functions,請避免在 JavaScript UDF 中累積過多本機狀態、以較小的區塊處理輸入資料,或使用 SQL UDF 或內建 GoogleSQL 函式重寫 UDF。請參閱「JavaScript UDF 最佳做法」。 - 如果查詢使用
FLATTEN,請判斷是否需要用於您的用途。詳情請參閱巢狀與重複的資料。 - 如果查詢使用
EXACT_COUNT_DISTINCT,建議改用COUNT(DISTINCT)。 - 如果查詢使用
COUNT(DISTINCT <value>, <n>)且<n>值很大,建議改用GROUP BY。詳情請參閱COUNT(DISTINCT)。 - 如果查詢使用
UNIQUE,建議改用GROUP BY,或在子選取項目中使用視窗函式。 - 如果查詢使用
LIMIT子句具體化許多資料列,請考慮篩選其他資料欄 (例如ROW_NUMBER()),或完全移除LIMIT子句,以允許寫入平行處理。 - 如果查詢使用深度巢狀檢視和
WITH子句,複雜度可能會呈指數級成長,進而達到上限。 - 使用暫存資料表,而非
WITH子句。WITH子句可能需要重新計算多次,這會使查詢變得複雜,因此速度變慢。將中繼結果保存在臨時資料表中,可降低複雜度。 - 避免使用
UNION ALL查詢。 - 如果查詢使用
MATCH_RECOGNIZE,請修改PARTITION BY子句,縮減分區大小,或新增PARTITION BY子句 (如果沒有的話)。 - 如果工作失敗並顯示
Table TABLE_NAME will have N partitions when the job finishes, exceeding limit 10000錯誤,表示完成工作會超過目的地資料表的 10,000 個分區限制。如果具有多個來源資料表的複製工作失敗,並顯示COUNT partitions will be copied to the table TABLE_NAME, which exceeds the limit 10000 for number of partitions in the table錯誤,則表示來源資料表包含超過 10,000 個不同的分區。請在INFORMATION_SCHEMA.PARTITIONS中檢查資料表的分區數量、設定分區到期時間、明確刪除不必要的分區,或使用較粗略的分區,例如按月而非按日分區,並搭配叢集。除非您明確刪除,否則最近過期的分區可能需要一段時間才會反映在分區數量中。如果查詢失敗並顯示Too many partitions produced by query, allowed LIMIT, query produces at least COUNT partitions錯誤,請參閱「功能和架構限制」。 - 如果工作失敗並顯示
Too many output columns錯誤,請只選取必要資料欄,不要使用SELECT *,或減少結果中的輸出資料欄和巢狀欄位數量。即使在 10,000 欄限制內,寬度或深度巢狀結果也可能超出寫入輸出的記憶體預算。 - 如果工作在存取受客戶自行管理的加密金鑰 (CMEK) 保護的資料表時,因
Cloud KMS Error: Project 'PROJECT_NUMBER' exceeded limit for metric METRIC_NAME錯誤 (例如cloudkms.googleapis.com/hsm_symmetric_requests) 而失敗,代表工作超出 Cloud Key Management Service (Cloud KMS) 頻率限制。請錯開或減少對 CMEK 加密資料表執行的並行查詢,或針對錯誤訊息中指出的指標,要求提高 Cloud KMS 配額。 - 如果工作失敗並顯示
Streaming read system resources exceeded, table: TABLE_NAME錯誤,請使用截斷指數輪詢重試查詢。 - 如果全域查詢失敗並顯示
Global query response is too large. Query returned more than BYTES bytes. Consider editing your query to return smaller results.錯誤,表示遠端跨區域子查詢超過跨區域資料移轉限制。新增WHERE篩選器,並僅選取遠端資料表中的必要資料欄,減少跨區域移轉的子查詢結果大小。您也可以在遠端區域建立檢視表,封裝複雜的運算式,或將所需STRUCT欄位傳回為不含STRUCT類型的個別資料欄,以便下推篩選器。或者,您也可以將查詢拆分為較小的查詢,並縮小篩選範圍。 - 如果工作失敗並顯示
Too many DML statements outstanding against table TABLE_NAME, limit is 20,請將多個較小的UPDATE、DELETE或MERGE陳述式分組為較少、較大的工作,或對目標資料表進行分區和分群。請參閱「DML 陳述式過多」和「資料表有過多待處理的 DML 陳述式」。 - 如果工作失敗並顯示
All our servers are busy processing data transferred between regions. Please try again shortly.,請重試查詢,或降低跨雲端 (BigQuery Omni) join、CREATE TABLE AS SELECT、INSERT INTO SELECT或LOAD DATA查詢的並行率 (或與支援團隊聯絡,要求提高跨區域移轉查詢頻率限制)。請參閱「BigQuery Omni 彙整限制」和「使用跨雲端移轉功能載入資料」。 - 如果工作失敗並顯示
Google Sheets service overloaded for spreadsheet id: SPREADSHEET_ID,請重試暫時性的 Google 試算表超載,或將試算表資料複製到永久 BigQuery 資料表 (並重構檢視表或錯開排定的查詢,減少對同一試算表的並行讀取)。 - 如果 BigQuery Omni 查詢失敗,並顯示
Response too large. Query returned ACTUAL_MBMB, and limit is LIMIT_MBMB.,表示查詢輸出內容超出 BigQuery Omni 查詢結果大小上限或跨雲端移轉限制。篩選或匯總查詢,傳回較小的結果,或使用EXPORT DATA陳述式,將大型結果直接匯出至外部儲存空間,而非目的地資料表。
詳情請參閱下列資源:
載入工作:
如果您載入的是 Avro 或 Parquet 檔案,請縮減檔案中的資料列大小。請查看您載入的檔案格式是否有特定大小限制:
如果載入 ORC 檔案時收到這則錯誤訊息,請與支援團隊聯絡。
Storage API:
錯誤字串:Stream memory usage exceeded
在 Storage Read API ReadRows 呼叫期間,部分記憶體用量偏高的串流可能會收到 RESOURCE_EXHAUSTED 錯誤,並顯示這則訊息。讀取寬資料表或結構定義複雜的資料表時,可能會發生這種情況。如要解決這個問題,請減少要讀取的資料欄 (使用 selected_fields 參數),或簡化資料表結構定義,藉此縮減結果列大小。
排解連線問題
下列各節說明如何排解嘗試與 BigQuery 互動時發生的連線問題:
將 Google DNS 加入許可清單
使用 Google IP Dig 工具,將 BigQuery DNS 端點 bigquery.googleapis.com 解析為單一「A」記錄 IP。請確認防火牆設定未封鎖這個 IP。
一般來說,建議您將 Google DNS 名稱加入許可清單。https://www.gstatic.com/ipranges/goog.json 和 https://www.gstatic.com/ipranges/cloud.json 檔案中分享的 IP 範圍經常變更,因此建議您改為將 Google DNS 名稱加入許可清單。以下是我們建議加入許可清單的常見 DNS 名稱:
*.1e100.net*.google.com*.gstatic.com*.googleapis.com*.googleusercontent.com*.appspot.com*.gvt1.com
找出捨棄封包的 Proxy 或防火牆
如要找出用戶端與 Google Front End (GFE) 之間的所有封包躍點,請在用戶端機器上執行 traceroute 指令,找出丟棄傳送至 GFE 封包的伺服器。以下是 traceroute 指令範例:
traceroute -T -p 443 bigquery.googleapis.com
如果問題與特定 IP 位址有關,您也可以找出特定 GFE IP 位址的封包躍點:
traceroute -T -p 443 142.250.178.138
如果 Google 端發生逾時問題,您會看到要求一路傳送至 GFE。
如果封包未到達 GFE,請與網路管理員聯絡,解決這個問題。
產生 PCAP 檔案並分析防火牆或 Proxy
產生封包擷取檔案 (PCAP) 並加以分析,確認防火牆或 Proxy 未篩除傳送至 Google IP 的封包,且允許封包傳送至 GFE。
以下是可透過 tcpdump 工具執行的指令範例:
tcpdump -s 0 -w debug.pcap -K -n host bigquery.googleapis.com
設定間歇性連線問題的重試機制
在某些情況下,GFE 負載平衡器可能會捨棄來自用戶端 IP 的連線,例如偵測到 DDoS 流量模式,或負載平衡器執行個體縮減,導致端點 IP 遭到回收。如果 GFE 負載平衡器中斷連線,用戶端必須擷取逾時要求,並重新向 DNS 端點傳送要求。在要求成功前,請勿使用相同的 IP 位址,因為 IP 位址可能已變更。
如果您發現 Google 端持續逾時,且重試也無法解決問題,請與 Cloud Customer Care 聯絡,並務必附上執行 tcpdump 等封包擷取工具後產生的最新 PCAP 檔案。
排解 API 和查詢工作錯誤
下列各節提供疑難排解操作說明,協助您解決 BigQuery 傳回的 API 和查詢工作錯誤。
排解 backendError 錯誤
backendError 錯誤 (HTTP 500、502、503 或 504) 表示服務暫時無法使用,原因可能是服務需求激增 (負載削減)、網路連線間歇性中斷、內部資源耗盡,或後端元件發生暫時性問題。
如何解決這項錯誤:
- 重試
jobs.get和jobs.insert呼叫:使用截斷指數輪詢重試要求:jobs.get呼叫:如果在輪詢jobs.get時收到503錯誤,請稍候幾秒再重新輪詢。如果jobs.get傳回已完成的工作資源,且其錯誤物件包含backendError,則表示工作失敗,您可以使用新的jobId重試工作,而不會影響資料一致性 (在失敗的jobId上再次呼叫jobs.getQueryResults會傳回相同的錯誤)。jobs.insert呼叫:如果在呼叫jobs.insert時收到這項錯誤,表示無法確定工作是否成功。請先檢查現有工作,再重新提交,或使用不重複的jobId重試工作。
- 計算錯誤率並提報給 Cloud Customer Care:如果要求持續發生間歇性錯誤,請使用 Cloud Logging 或 Cloud Monitoring 計算失敗要求的整體比率,以及過去 30 天的正常運作時間百分比,並與 BigQuery 服務水準協議進行比較。如果 30 天運作時間低於服務水準協議,請聯絡 Cloud Customer Care,並提供觀察到的錯誤率和運作時間計算結果。如果特定要求或工作在多次嘗試重新啟動工作流程,並透過指數輪詢重試後,仍持續失敗並傳回
5xx錯誤,無論整體錯誤率為何,請與 Cloud Customer Care 聯絡,提供受影響的工作 ID,並說明業務影響。
排解 internalError 錯誤
如果 BigQuery 發生內部錯誤,系統會傳回 internalError 錯誤 (HTTP 500)。
如何解決這項錯誤:
- 請按照《BigQuery 服務水準協議 (SLA)》所述的輪詢規定等待,然後使用截斷指數輪詢重試作業。
- 使用預留項目取得專屬運算單元容量,減少暫時性內部錯誤的發生頻率。
- 如果重試後仍發生錯誤,請與 Cloud Customer Care 團隊聯絡,或使用 BigQuery Issue Tracker 回報錯誤。
排解 jobBackendError 和 jobInternalError 錯誤
錯誤字串:
The job encountered an error during execution. Retrying the job may solve the problem.(reason: jobBackendError)The job encountered an internal error during execution and was unable to complete.(reason: jobInternalError)
如果工作建立後,在執行期間失敗並傳回 backendError 或 internalError,就會發生這些 HTTP 400 Bad Request 錯誤。當您呼叫 jobs.query 或 jobs.getQueryResults 來擷取失敗工作的結果時,BigQuery 會傳回 HTTP 400,並附帶 jobBackendError 或 jobInternalError (而輪詢 jobs.get 則會傳回工作資源,其中 status.errorResult.reason 設為 backendError 或 internalError)。
如要解決這些錯誤,請按照下列步驟操作:
- 使用截斷指數輪詢,以新的
jobId重試工作。對失敗的jobId再次呼叫jobs.getQueryResults會傳回相同的錯誤。 - 請確保用戶端重試政策會處理含有
jobBackendError或jobInternalError的 HTTP400回應,因為僅檢查5xx狀態碼的重試邏輯不會重試這些回應。 - 如果重試後仍發生錯誤,請與 Cloud Customer Care 團隊聯絡,並提供受影響的工作 ID。
排解輸入內容無效和結構定義錯誤
如果輸入內容無效 (不包括查詢無效),例如缺少必填欄位、資料表結構定義不相容,或目的地資料表已刪除,系統會傳回 invalid 錯誤 (HTTP 400) (查詢無效會傳回 invalidQuery 錯誤)。請根據錯誤訊息,查看對應的疑難排解章節:
- 缺少必要參數 (
Required parameter is missing):請參閱「缺少必要參數」。 - 結構定義不符 (
Provided Schema does not match Table):請參閱「排解結構定義不符錯誤」。 - 超過巢狀結構限制 (
Schema nested too deeply):請參閱「排解結構定義、檔案和常式巢狀結構限制錯誤」。 - 目的地資料表已刪除或過期 (
Destination deleted/expired during operation):請參閱「目的地資料表已刪除或過期」。
已取消執行工作
錯誤字串:Job execution was cancelled: DETAILS
如果工作遭到取消,無論是呼叫端明確取消工作,還是工作超過設定的執行或佇列逾時時間,都會發生 stopped 錯誤。使用 jobs.get 輪詢已取消的工作時,BigQuery 會傳回 HTTP 200 OK,並在 status.errorResult 中傳回 reason: stopped。同步要求取消時,BigQuery 會傳回 HTTP 499 (CANCELLED)。
請根據錯誤訊息找出子類型:
- 執行逾時 (
Job timed out after DURATION): 工作超過設定的執行逾時時間。請在工作設定中提高configuration.jobTimeoutMs,或在預設設定中提高default_query_job_timeout_ms,或最佳化查詢,加快完成速度。如果是多重陳述式查詢,這項限制適用於所有陳述式的累計執行時間。 - 佇列逾時 (
Job timed out in the queue after DURATION):工作在查詢佇列中等待的時間超過設定的佇列逾時時間。使用ALTER PROJECT或ALTER ORGANIZATION SET OPTIONS增加default_interactive_query_queue_timeout_ms或default_batch_query_queue_timeout_ms(請參閱「控制佇列逾時」)、增加configuration.jobTimeoutMs,或減少查詢並行。 - 明確取消 (
User requested cancellation):使用者、服務帳戶或自動調度管理工具取消了工作。在 Cloud Logging (protoPayload.methodName="jobservice.cancel"或"google.cloud.bigquery.v2.JobService.CancelJob") 中檢查 BigQuery 稽核記錄,找出叫用jobs.cancel的呼叫端。如需一般工作管理,請參閱「管理工作」。
不符合要求先決條件
如果未滿足要求的前提條件,就會發生 preconditionFailed 錯誤 (HTTP 400 或 412)。請根據錯誤訊息找出子類型:
- 更新中繼資料時 ETag 不符 (
Resource RESOURCE did not meet condition CONDITION): 請先擷取目前資源中繼資料 (例如使用tables.get或datasets.get),取得目前的etag值,再使用If-Match標頭重試。 - 組織政策要求使用 CMEK (
Your administrator requires that you specify an encryption key for queries in project PROJECT_ID):請為查詢工作指定 Cloud Key Management Service 金鑰 (configuration.query.destinationEncryptionConfiguration.kmsKeyName或bq query --destination_kms_key),或在資料集或專案設定預設 Cloud KMS 金鑰,並確認 BigQuery 服務帳戶具備roles/cloudkms.cryptoKeyEncrypterDecrypter角色。請參閱「要求所有資源使用 CMEK」。 - 版本限制 (
disallowed in STANDARD edition或cannot be used with STANDARD Edition): 在指派給企業版或 Enterprise Plus 預留項目的專案中執行工作,或使用隨選計價模式。請參閱「BigQuery 版本簡介」。 - 容錯移轉資料集寫入 (
The job references a table that belongs to a failover dataset): 在資料集主要位置的 Enterprise Plus 預留項目上,執行寫入容錯移轉資料集的工作。載入和擷取工作需要PIPELINE預留項目指派作業。請參閱「錯誤 412:工作參照的資料表屬於容錯移轉資料集」。 - CDC 基礎資料表上的 materialized view 有待處理的 upsert (
MV has a base table TABLE with upsert data that wait to be applied. Please wait a few minutes and try again.): 請稍候幾分鐘,讓背景變更資料擷取 (CDC) upsert 更新套用至基礎資料表,然後重試查詢。
資源仍在使用中
錯誤字串:
RESOURCE_TYPE RESOURCE_ID is still in use
當您嘗試刪除仍含有資源的資料集,或仍處於待處理或執行中的工作時,就會發生這個 HTTP 400 Bad Request 錯誤 (reason: resourceInUse):
- 刪除非空白資料集 (
Dataset DATASET_ID is still in use): 請先清空資料集再刪除,或刪除資料集及其所有內容,方法是在 GoogleSQL 中執行DROP SCHEMA IF EXISTS DATASET_NAME CASCADE、在 bq 指令列工具中執行bq rm -r -f -d PROJECT_ID:DATASET_ID,或在datasets.deleteAPI 呼叫中設定deleteContents=true。請參閱「刪除資料集」。 - 刪除執行中的工作 (
Job JOB_ID is still in use): 請等待工作完成 (或先使用jobs.cancel或bq cancel取消工作),再呼叫jobs.delete或執行bq rm -j。請參閱「刪除工作中繼資料」。
已有這項資源
錯誤字串:
Already Exists: RESOURCE_TYPE RESOURCE_ID
如果您嘗試建立已存在的資源,或工作將 writeDisposition 設為 WRITE_EMPTY,且目的地資料表已存在,就會發生這個 HTTP 409 Conflict 錯誤 (reason: duplicate):
- 資料表 (
Already Exists: Table TABLE):指定其他目的地資料表名稱、在 DDL 查詢中使用CREATE TABLE IF NOT EXISTS或CREATE OR REPLACE TABLE,或將工作的writeDisposition屬性從WRITE_EMPTY變更為WRITE_APPEND或WRITE_TRUNCATE。 - 資料集 (
Already Exists: Dataset DATASET):請選擇其他資料集名稱、在 DDL 查詢中使用CREATE SCHEMA IF NOT EXISTS,或在呼叫datasets.insert之前,先檢查資料集是否已存在。 - 工作 (
Already Exists: Job JOB):讓 BigQuery 產生隨機jobId、在重試失敗的工作時產生新的jobId、在重試前檢查先前的工作是否成功,或在IN子句中對大型陣列使用查詢參數。請參閱「工作已存在」。 - 限制、索引或常式 (
Already Exists: RESOURCE_TYPE RESOURCE_ID): 指定其他資源名稱、在 DDL 陳述式中使用IF NOT EXISTS或CREATE OR REPLACE(例如ADD CONSTRAINT IF NOT EXISTS或CREATE OR REPLACE VECTOR INDEX),或是在新增替代項目之前,先捨棄現有限制。
作業已取消
如果作業因並行修改或交易衝突而停止,就會發生這個 HTTP 409 Conflict 錯誤 (reason: abortd)。請注意,API 會將這項錯誤原因拼寫為 abortd。多陳述式交易和並行 DML 衝突 (Transaction is aborted due to concurrent update 和 Could not serialize access to table) 則會傳回 HTTP 400 和 invalidQuery。
如何解決這項錯誤:
- 請在衝突作業完成後重試,或使用截斷指數輪詢重試。
- 如果多陳述式交易因並行更新而停止,請先執行
ROLLBACK TRANSACTION(或使用CALL BQ.ABORT_SESSION(SESSION_ID)結束工作階段),然後再重試。請參閱「因並行更新而取消交易」和「衝突的 DML 陳述式」。
無法使用表格儲存空間
錯誤字串:
Storage of RESOURCE_ID is unusable because REASON.
如果保存資料表資料的內部 BigQuery 儲存空間無法使用,就會發生這個 HTTP 400 Bad Request 錯誤 (reason: storageUnusable)。這個錯誤代表服務端儲存空間發生問題,而非設定問題。
使用截斷指數輪詢重試工作。如果重試後仍發生錯誤,請與 Cloud Customer Care 團隊聯絡。
暫時無法提供串流資料
錯誤字串:
Job failed because streaming data from TABLE_SOURCE is temporarily unavailable. Retrying the job may solve the problem.(reason: streamingDataUnavailable)Job failed because vortex streaming data from TABLE_SOURCE is temporarily unavailable. Retrying the job may solve the problem.(reason: vortexDataUnavailable)
如果最近串流至資料表的資料暫時無法使用,而工作讀取了該資料表,就會發生這些 HTTP 400 Bad Request 錯誤。最近串流的資料會暫時存放在寫入最佳化儲存空間,其可用性特性與代管儲存空間不同。
如要解決這些錯誤,請按照下列步驟操作:
- 使用截斷指數輪詢,以新的
jobId重試查詢工作。對失敗的jobId再次呼叫jobs.getQueryResults會傳回相同的錯誤。 - 請更新用戶端重試政策,使用
streamingDataUnavailable或vortexDataUnavailable重試 HTTP400回應,因為僅檢查5xx狀態碼的重試邏輯會略過這些回應。 - 詳情請參閱「排解串流資料即時插入問題」、「BigQuery Storage Write API (gRPC) 總覽」和「BigQuery Storage Write API (gRPC) 最佳做法」。
無法使用外部或備份資料表
如果 BigQuery 無法讀取資料並非由其管理的資料表,就會發生這個 HTTP 400 Bad Request 錯誤 (reason: tableUnavailable)。請根據錯誤訊息找出子類型:
- Apache Iceberg 或 Delta Lake 資料表的結構定義擷取逾時 (
Timed out while fetching schema of the requested resource. Contact the table owner for assistance.):請使用截斷指數輪詢重試查詢。如果錯誤持續發生,請與 Cloud Customer Care 團隊聯絡。 - 缺少 Hive 分區鍵 (
No partition key detected on this table. Hive partitioned table must have at least one partition key): 請確認 Cloud Storage URI 路徑遵循key=valueHive 分區版面配置, 然後使用至少一個分區鍵重新建立外部資料表。 - 由其他 Google 產品團隊管理的資料支援的資料表 (
Something went wrong with the table you queried. Contact the table owner for assistance.): 請使用截斷指數輪詢重試要求,如果錯誤持續發生,請與 Cloud Customer Care 聯絡。
使用者擁有的外部資源錯誤
錯誤字串:
Error when accessing a user-owned external RESOURCE_TYPE resource RESOURCE_NAME. The resource provided error: EXTERNAL_ERROR
當 BigQuery 讀取或呼叫您擁有的外部資源 (例如 Cloud Storage bucket、Cloud Key Management Service 金鑰或外部連線),且外部資源傳回錯誤時,就會發生這個 HTTP 400 Bad Request 錯誤 (reason: userOwnedResourceError)。
檢查錯誤訊息中的 <var>RESOURCE_TYPE</var> 和 <var>RESOURCE_NAME</var>,找出外部資源,然後解決 <var>EXTERNAL_ERROR</var> 中回報的基礎錯誤。
未實作功能或作業
錯誤字串:Not Implemented: DETAILS
當您嘗試使用未針對目標資源實作的功能或作業時,就會發生這個 HTTP 501 Not Implemented 錯誤 (reason: notImplemented):
- 不支援的資料表複製 (
Not Implemented: Tables with this storage type cannot be copied): 來源資料表的儲存空間類型 (例如INFORMATION_SCHEMA檢視表或不支援的非代管儲存空間) 不支援資料表複製工作 (具有複製設定的jobs.insert)。請改為執行CREATE TABLE DESTINATION_TABLE AS SELECT * FROM SOURCE_TABLE,將可查詢的結果具體化為標準 BigQuery 資料表。請參閱「複製資料表」。 - 不支援的搜尋索引修改 (
Not Implemented: ALTER SEARCH INDEX does not support): 請使用DROP SEARCH INDEX捨棄現有的搜尋索引,並使用CREATE SEARCH INDEX搭配更新後的選項重新建立。請參閱「管理搜尋索引」。 - 其他情況: 請與 Cloud Customer Care 聯絡,並提供完整錯誤訊息和工作 ID。
後續步驟
- 取得查詢成效洞察。
- 進一步瞭解如何最佳化查詢效能。
- 查看查詢的配額與限制。
- 查看 BigQuery API 的 HTTP 狀態和錯誤代碼。
- 進一步瞭解其他 BigQuery 錯誤訊息。