排解相關錯誤

使用 BigQuery 時,可能會發生兩種類型的錯誤:HTTP 錯誤代碼和工作錯誤。工作錯誤會在呼叫 jobs.get 時出現在 status 物件中。

錯誤表

下表列出了向 BigQuery API 傳送要求時可能傳回的錯誤代碼。API 回應包含 HTTP 錯誤代碼和錯誤物件。下方的「錯誤代碼」一欄與錯誤物件中的 reason 屬性對應。

根據預設,使用 bq 指令列工具查看工作狀態時不會傳回錯誤物件。如要查看錯誤物件及與下表對應的 reason 屬性,請使用 -- format=prettyjson 標記。例如 bq --format=prettyjson show -j <job id>

如果您收到的 HTTP 回應碼沒有出現在下表中,那麼該回應碼可能表示您的 HTTP 要求發生問題,或是結果符合預期。舉例來說,502 錯誤表示您的網路連線發生問題。如需完整的 HTTP 回應碼清單,請參閱 HTTP 回應碼

錯誤代碼 HTTP 代碼 說明 疑難排解
accessDenied 403 當您嘗試存取資源 (例如資料表資料集或工作),但沒有存取權時,就會傳回這個錯誤。如果您嘗試修改唯讀物件,也會傳回這個錯誤。 與支援擁有者聯絡,要求資源的存取權
backendError 500 或 503 伺服器發生暫時性問題時 (例如網路連線問題或伺服器超載),就會傳回這個錯誤。 通常只需稍候片刻,然後再試一次即可。不過,排解這個錯誤時有兩種特殊情況:jobs.get 呼叫與 jobs.insert 呼叫。

jobs.get 呼叫

  • 如果您在輪詢 jobs.get 時收到 503 錯誤,請稍後片刻再重新輪詢。
  • 如果工作完成,但出現含 backendError 的錯誤物件,表示工作失敗。您可以安全地重試工作,不必擔心資料一致性的問題。

jobs.insert 呼叫

如果您在呼叫 jobs.insert 時收到這個錯誤,則不確定工作是否成功。在這種情況下,您必須重試工作。

billingNotEnabled 403 專案的計費功能未啟用時會傳回這個錯誤。 Google Cloud Platform 主控台中為專案啟用計費功能。
blocked 403 當 BigQuery 暫時將您嘗試執行的作業加入黑名單時 (通常是為了避免服務中斷),就會傳回這個錯誤。這是罕見錯誤。 詳情請洽詢支援小組
duplicate 409 當您嘗試建立的工作、資料集或資料表已存在時,就會傳回這個錯誤。如果工作的 writeDisposition 屬性設為 WRITE_EMPTY,且工作所存取的目的地資料表已存在,也會傳回這個錯誤。 將您嘗試建立的資源重新命名,或變更工作中的 writeDisposition 值。
internalError 500 BigQuery 中發生內部錯誤時會傳回這個錯誤。 洽詢支援小組或使用 BigQuery 問題追蹤工具回報錯誤
invalid 400 除了查詢無效以外的任何無效輸入類型都會傳回這個錯誤,例如未填妥必填欄位或資料表結構定義無效。查詢無效時則會傳回 invalidQuery 錯誤。
invalidQuery 400 當您嘗試執行的查詢無效時,就會傳回這個錯誤。 再次檢查您的查詢有無語法錯誤。查詢參考資料內含建立有效查詢的相關說明與範例。
notFound 404 當您參照的資源 (資料集、資料表或工作) 不存在時,就會傳回這個錯誤。如果使用快照修飾符參照最近串流過的已刪除資料表,也會發生這個錯誤。 修正資源名稱,或是在串流後等待至少 6 小時,再查詢已刪除的資料表。.
notImplemented 501 當您嘗試存取未實作的功能時,就會傳回這個錯誤。 詳情請洽詢支援小組
quotaExceeded 403 如果您的專案超過 BigQuery 配額自訂配額,或是您未設定帳單資訊且超過免費版查詢配額,就會傳回這個錯誤。 查看錯誤物件的 message 屬性,進一步瞭解超過了哪一項配額。如要重設或調高 BigQuery 配額,請洽詢支援小組。如要調整自訂配額,請透過 Google Cloud Platform 主控台頁面提交要求。如果您是在採用 BigQuery 沙箱機制時收到這個錯誤,則可以升級
rateLimitExceeded 403 如果您的專案在短時間內傳送的要求過多,超過了並行率限制API 要求限制,就會傳回這個錯誤。 設法讓要求頻率降低。

如果您確信專案未超過任何一項限制,請洽詢支援小組

resourceInUse 400 當您嘗試刪除含有資料表的資料集或目前正在執行的工作時,就會傳回這個錯誤。 先清空資料集再予以刪除,或等待工作完成再予以刪除。
resourcesExceeded 400 當您的查詢使用的資源過多時,就會傳回這個錯誤。
  • 嘗試分割查詢。
  • 嘗試移除 ORDER BY 子句。
  • 如果您的查詢使用 JOIN,請確定較大的資料表在子句左側。
  • 如果您的查詢使用 FLATTEN,請判斷是否必要。詳情請參閱巢狀和重複的資料
  • 如果查詢使用 EXACT_COUNT_DISTINCT,建議改用 COUNT(DISTINCT)
  • 如果查詢使用 COUNT(DISTINCT <value>, <n>)<n> 的值較大,建議改用 GROUP BY。詳情請參閱 COUNT(DISTINCT) 說明
  • 如果查詢使用 UNIQUE,建議改用 GROUP BY 或在 subselect 內使用窗型函式
responseTooLarge 403 當您的查詢結果超過回應大小上限時,就會傳回這個錯誤。某些查詢會分成多個階段執行,即使最終結果未超過大小上限,只要有任一階段傳回的回應超過大小上限,就會傳回這個錯誤。使用 ORDER BY 子句的查詢常會傳回這個錯誤。 加入 LIMIT 子句 (可能有幫助) 或移除 ORDER BY 子句。如要確保大型結果能順利傳回,您可以將 allowLargeResults 屬性設為 true 並指定目的地資料表。
已停止 200 工作遭到取消時會傳回這個狀態碼。
tableUnavailable 400 特定 BigQuery 資料表所含的資料是由其他 Google 產品小組負責管理。這個錯誤代表無法存取這類資料表。 收到這則錯誤訊息時,您可以重試要求 (請參閱 internalError 疑難排解建議),或是洽詢將資料存取權授予您的 Google 產品小組。

錯誤回應範例

GET https://www.googleapis.com/bigquery/v2/projects/12345/datasets/foo
Response:
[404]
{
  "error": {
  "errors": [
  {
    "domain": "global",
    "reason": "notFound",
    "message": "Not Found: Dataset myproject:foo"
  }],
  "code": 404,
  "message": "Not Found: Dataset myproject:foo"
  }
}

驗證錯誤

根據 OAuth2 規格定義,由 OAuth 憑證產生系統擲回的錯誤會傳回以下 JSON 物件。

{"error" : "description_string"}

這個錯誤會與 HTTP 400「不正確的要求」錯誤或 HTTP 401「未授權」錯誤一起出現。description_string 是根據 OAuth2 規格所定義的其中一個錯誤碼。例如:

{"error":"invalid_client"}

返回頁首

排解串流資料插入疑難

以下各節討論如何針對串流資料至 BigQuery 時發生的錯誤進行疑難排解。

失敗 HTTP 回應碼

如果您收到失敗 HTTP 回應碼 (例如網路錯誤),則無法判定串流資料插入是否成功。如果您嘗試直接重新傳送要求,可能會導致資料表中產生重複的資料列。為了防止資料表出現重複的內容,請在重新傳送要求時設定 insertId 屬性。BigQuery 會使用 insertId 屬性執行清除重複工作。

如果您收到權限錯誤、資料表名稱無效錯誤或超過配額錯誤,則不會插入任何資料列,且整個要求都會失敗。

成功 HTTP 回應碼

即使您收到成功 HTTP 回應碼,仍須查看回應的 insertErrors 屬性才能判定是否成功插入資料列,因為 BigQuery 資料列插入可能只有部分成功。

如果 insertErrors 屬性是空白清單,表示成功插入了所有資料列。否則,除了資料列中有結構定義不相符的情況以外,insertErrors 屬性中指出的資料列並未插入,其他所有資料列則成功插入。errors 屬性內含詳細資訊,可讓您瞭解各資料列插入失敗的原因。index 屬性會針對發生錯誤的要求指出以 0 為基礎的資料列索引。

如果 BigQuery 遇到要求中個別資料列有結構定義不相符的情況,則不會插入任何資料列,並且會針對各資料列傳回 insertErrors 項目,即使是沒有結構定義不相符情形的資料列亦然。在沒有結構定義不相符情形的資料列所收到的錯誤中,reason 屬性會設為 stopped,可直接重新傳送。插入失敗的資料列則會包含關於結構定義不相符情形的詳細資訊。

串流資料插入的中繼資料錯誤

由於 BigQuery 的串流 API 是針對高插入率所設計,因此對基礎資料表中繼資料所做的修改最終會在與串流系統互動時保持一致。在大多數情況下,中繼資料變更會在幾分鐘內生效,但在這段期間 API 回應可能會反映資料表的不一致狀態。

部分情況包括:

  • 結構定義變更 - 針對最近收到串流資料插入的資料表修改結構定義時,回應可能會指出結構定義不相符錯誤,因為串流系統可能不會立即反映結構資料變更。
  • 資料表建立/刪除 - 串流至不存在的資料表會傳回 notFound 回應的變化類型。如果在回應中建立資料表,後續的串流資料插入可能無法立即辨識。同樣地,刪除和/或重新建立資料表時,串流資料插入可能會在一段時間內傳送至舊資料表,而不會出現在新建立的資料表中。
  • 資料表截斷 - 同樣地,截斷資料表的資料 (例如查詢工作會使用 WRITE_TRUNCATE 的 writeDisposition 時),可能會導致後續插入的一致性出現落差。

遺失/無法取得資料

串流資料插入會暫時留駐在串流緩衝區,其可用性特質與受管理的儲存空間不同。BigQuery 中的特定作業不會與串流緩衝區互動,例如資料表複製工作和 tabledata.list 這類 API 方法。因此,近期的串流資料不會出現在目的地資料表或輸出內容中。

返回頁首

本頁內容對您是否有任何幫助?請提供意見:

傳送您對下列選項的寶貴意見...

這個網頁