排解錯誤

當您使用 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 Console 中啟用專案的計費功能。
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 Console 頁面提交要求。如果您是在採用 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,並指定目的地資料表。
stopped 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 方法。因此,近期的串流資料不會出現在目的地資料表或輸出內容中。

返回頁首

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

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

這個網頁
需要協助嗎?請前往我們的支援網頁