BigQuery コネクタのエラーと制限事項のトラブルシューティング

データポータルを BigQuery に接続すると、タイムアウト、SQL 構文の制限、割り当ての制限、VPC Service Controls のエラーが発生することがあります。このガイドでは、BigQuery コネクタ全体で発生する一般的な問題について説明します。[解決手順] を開いて、問題を調査し、解決します。

クエリと SQL 構文エラー

データポータルのカスタム SQL クエリには特定の制限事項があります。クエリがこれらの上限に違反すると、エラーが発生する可能性があります。

Field is ambiguous 結合エラー

カスタムクエリに重複する列名が含まれている場合、グラフに次のエラーが表示されます。

User Configuration Error: Field is ambiguous

エラー メッセージ テキスト: ユーザーの設定エラー

原因: 結合されたテーブル（JOIN）で重複する列名を共有することはできません。たとえば、同じスキーマを持つ 2 つのテーブルを Criteria_ID フィールドで結合すると、結果の仮想テーブルに重複する列（Criteria_ID、Parent_ID、Name）が作成され、あいまいさエラーがトリガーされます。

解決手順

AS キーワードまたは EXCEPT 句を使用して、すべての列名を一意にします。

オプション 1: エイリアスを使用して重複するフィールドの名前を明示的に変更する

SELECT *
FROM (
  SELECT
    Criteria_ID AS Criteria_ID_1,
    Parent_ID AS Parent_ID_1,
    Name AS NAME_1
  FROM
    `project.dataset.table_1` ) AS table_1
LEFT JOIN (
  SELECT
    Criteria_ID AS Criteria_ID_2,
    Parent_ID AS Parent_ID_2,
    Name AS NAME_2
  FROM
    `project.dataset.table_2` ) AS table_2
ON
  table_1.Criteria_ID_1 = table_2.Criteria_ID_2;

オプション 2: EXCEPT を使用して特定のフィールドを除外して名前を変更する

残りのフィールドを保持しながら、少数のフィールドの名前を変更するだけでよい場合は、EXCEPT を使用します。

SELECT * EXCEPT (city), city AS city_1 FROM `project.dataset.table_1`

カスタム SQL クエリの構文エラー（複数のステートメント）

カスタム SQL クエリに変数または複数のステートメント（DECLARE、SET）が含まれている場合、クエリは失敗します。

原因: データポータルは、外側の SELECT クエリ（SELECT * FROM (<your_custom_sql>)）内で SQL を実行します。そのため、クエリは単一の SELECT ステートメントである必要があります。

たとえば、次のクエリは選択前に変数を宣言しているため失敗します。

DECLARE cost_per_tb_in_dollar FLOAT64 DEFAULT 4.2;
SELECT total_bytes_billed / (1024 * 1024) * cost_per_tb_in_dollar / (1024 * 1024) FROM `billing_table`;

解決手順

共通テーブル式（CTE または WITH 句）を使用して、計算を 1 つの SELECT ステートメントに結合します。

WITH constants AS (
  SELECT 4.2 AS cost_per_tb_in_dollar
)
SELECT
  total_bytes_billed / (1024 * 1024) * c.cost_per_tb_in_dollar / (1024 * 1024) AS cost
FROM `billing_table`, constants AS c;

パフォーマンスとクエリのタイムアウト

クエリの実行に 3 ～ 5 分以上かかる場合、データポータルは結果を受信する前にタイムアウトし、HTTP 504 Gateway timeout を返します。

HTTP 504 Gateway timeout エラーまたは長時間実行クエリのエラー

データポータルのカスタムクエリや複雑なグラフの集計は、3 ～ 5 分後にタイムアウトして HTTP 504 Gateway timeout エラーが返されることがあります。

解決手順

クエリが常にタイムアウトする場合は、次の最適化を使用します。

  • BigQuery Storage Read API を有効にする: BigQuery Storage Read API を有効にして、データ スループットを向上させます。
  • クエリを簡素化する: 不要な `JOIN` コマンドを削除し、より長い期間でデータをグループ化し、必要な列のみを選択します。
  • BigQuery BI Engine を使用する: BigQuery BI Engine で容量を予約して、1 秒未満のパフォーマンスを実現します。
  • データベース ビューを使用する: カスタム SQL を BigQuery ビューまたはマテリアライズド ビューとして保存し、データポータルをそのビューに直接接続します。
  • レポート テーブルに事前集計する: BigQuery のスケジュール設定されたクエリを使用して、概要レコードを別のテーブルに書き込み、概要テーブルをクエリします。

割り当てとテーブルの制限事項

データセットに数千のテーブルが含まれている場合や、数百万件のレコードが返される場合は、上限エラーが発生することがあります。

5,000 を超えるテーブルを含むデータセットの UI の応答がフリーズする

データポータルのテーブル選択リストを使用して BigQuery データセットに接続しようとすると、ユーザー インターフェースがフリーズするか、応答しなくなる。

原因: コネクタは、データセットあたり最大 5,000 個のテーブルをサポートしています。データセットが 5,000 個のテーブルまたはビューを超えると、テーブル選択リストがタイムアウトしてフリーズします。

解決手順

テーブル リストを読み込まずに接続するには、次のいずれかの方法を使用します。

  • カスタムクエリを使用して接続する: [カスタムクエリ] を選択し、複雑でない `SELECT` ステートメントを作成します。
    SELECT * FROM `your_project.your_dataset.your_table`
  • BigQuery から直接接続する: BigQuery コンソールでテーブルを見つけ、[エクスポート] または [データを探索] をクリックして、[Looker Studio で開く] を選択します。
  • データセットを分割または再編成する: レポート テーブルを、テーブル数が 5,000 未満の専用の小さなレポート データセットに移動します。

最大 200 万行の戻り上限

大規模なデータセットを可視化すると、グラフにデータ切り捨ての警告が表示されたり、200 万件を超えるレコードの行が省略されたりすることがあります。

原因: コネクタは、グラフクエリあたり最大 200 万行を返します。クエリが 200 万件を超えるレコードを返す場合、グラフはデータを切り捨てて警告を表示します。

解決手順

データが切り捨てられないようにするには:

  • レポート単位の日付フィルタを適用して、クエリ量を絞り込みます。
  • パーティション フィルタが必要な日付パーティション分割テーブル（`DATE`、`DATETIME`、`TIMESTAMP`）をクエリします（詳細）。
  • データポータルで可視化する前に、BigQuery 内でカーディナリティの高いディメンションをグループ化します。

MEDIAN と PERCENTILE の分散

BigQuery に接続されているグラフで正確な中央値（MEDIAN）またはパーセンタイル（PERCENTILE）を計算すると、他の SQL データベースや CSV エクスポートで実行される同じ計算と出力が若干異なる場合があります。

原因: BigQuery クエリでは、MEDIAN と PERCENTILE は APPROX_QUANTILES 近似集計関数を使用します。これにより、ペタバイト規模のデータセットを迅速に処理できますが、概算結果は CSV エクスポートや他の SQL データベースで実行される正確な計算と若干異なる場合があります。

データ型と暗号化のエラー

サポートされていない列の型と組織で適用される鍵暗号化ポリシーを処理する方法について説明します。

CONDITION_NOT_MET 暗号化エラー（CMEK）

データセットをクエリすると、グラフが失敗し、次のエラーが返されます。

User Configuration Error: CONDITION_NOT_MET

原因: コネクタは、顧客管理の暗号鍵（CMEK）をサポートしていません。組織ポリシーでクエリまたは一時ストレージに CMEK 暗号化が必要な場合（組織ポリシー サービス）、グラフに User Configuration Error: CONDITION_NOT_MET が表示されます。

解決手順

組織の管理者と協力して、レポート プロジェクトを CMEK ポリシーから除外するか、レポートデータを標準の Google-owned and Google-managed encryption keysに則って管理されるデータセットにエクスポートします。

TIME データ型がサポートされていない

TIME データ型の列（23:59:59 など）を含む BigQuery テーブルに接続すると、データポータルはフィールドを TEXT に変換します。これにより、時間ベースの並べ替えや集計ができなくなります。

原因: データポータルは、BigQuery の TIME データ型（23:59:59 など）をネイティブにサポートしていません。コネクタは取り込み時に TIME 列を TEXT 文字列に変換するため、時間ベースの並べ替えができません。

解決手順

次のいずれかの回避策を使用して、`TIME` 列を DATETIME オブジェクトに変換します。

回避策 1: カスタム SQL クエリを使用する

SQL で `TIME` フィールドを基準日（`1970-01-01`）と直接組み合わせます。

SELECT
  *,
  -- Combine a dummy date (1970-01-01) with your TIME field
  DATETIME(DATE "1970-01-01", your_time_field) AS time_as_datetime
FROM
  `your_project.your_dataset.your_table`
  • 結果: データポータルは、`time_as_datetime` を [**日付と時刻**] フィールドとして取り込みます。
  • 書式設定: レポートのグラフのプロパティで、フィールドの [**表示形式**] を [**時間**]、[**分**]、またはカスタムの時刻形式（`h:mm:ss`）に変更して、時刻部分のみを表示します（詳細）。

回避策 2: データポータルで計算フィールドを作成する

SQL クエリを変更しない場合は、データソース内に計算フィールドを作成します。

PARSE_DATETIME("%H:%M:%S", CAST(your_time_field AS TEXT))
  • 結果: `PARSE_DATETIME` 関数は、テキスト文字列を **日付と時刻** オブジェクトに解析し、カレンダーの日付をデフォルトで 1970 年 1 月 1 日に設定します（詳細）。

VPC Service Controls のエラー

サービス境界内で作業しているときに、アクセス拒否エラーとバックグラウンド プロセスの制限のトラブルシューティングを行います。

VPN を使用せずにレポートを表示している場合: Service Control Failure

組織の VPN または企業ネットワーク外でレポートを表示すると、一部またはすべてのグラフが次のエラーで失敗します。

Service Control Failure

原因: コネクタは、VPC Service Controls の IP ベースのアクセスレベルを確認するために、レポート閲覧者の IP アドレスを BigQuery に渡します。レポートをコピーすると、コピー内の以前のカスタム SQL データソースまたは「ゴースト」カスタム SQL データソースが、プライマリ データセットが外部にある場合でも、サービス境界内で保護されている課金プロジェクトを参照する可能性があります。

解決手順

レポートで、非表示の境界内請求プロジェクトを特定して削除するか、再割り当てします。

  1. 影響を受けるレポートのコピーを作成して、安全にトラブルシューティングを行います。
  2. コピーのレポート エディタで、[リソース] > [追加済みのデータソースの管理] に移動します。
  3. レポートに添付されている埋め込みの **BigQuery** または **カスタム SQL** のデータソースをすべて確認します。
  4. 各カスタム SQL 接続を編集して、構成された [**請求先プロジェクト**] を確認します。データソースが VPC Service Controls の境界で保護されている課金プロジェクトを指している場合は、保護されていない課金プロジェクトを使用するように更新するか、使用されなくなったデータソースを削除します。

VPC Service Controls の背後でメール配信のスケジュール設定またはグラフ アラートが失敗する

VPC Service Controls で保護された BigQuery データセットに接続されているグラフで自動バックグラウンド機能（送信日時を設定したメール配信やグラフ アラートなど）が実行されると、レポートのコンテンツや添付ファイルなしでメールが配信されるか、アラートがトリガーされません（VPC Service Controls unexpected field in error map）。

原因: 自動化されたバックグラウンド機能（メールの定期配信やグラフ アラートなど）は、エンドユーザーの IP アドレスなしでバックグラウンド タスクとして実行されるため、VPC Service Controls（VPC-SC）は IP ベースのアクセスレベル（VPC Service Controls unexpected field in error map）を評価するときにこれらの機能をブロックします。

解決手順

VPC Service Controls の境界の背後にある自動バックグラウンド機能を使用するには、サービス アカウントの認証情報を使用するようにデータソースを構成するか、ID ベースのアクセスレベルを作成します。