注: 以下の翻訳の正確性は検証されていません。AIPを利用して英語版の原文から機械的に翻訳されたものです。

BigQuery

Foundry を Google BigQuery に接続して、BigQuery のテーブルと Foundry のデータセット間でデータを読み込みおよび同期します。

サポートされている機能

機能	ステータス
一括インポート	🟢 一般提供
エクスポートタスク	🟢 一般提供
探索	🟢 一般提供
増分	🟢 一般提供
仮想テーブル	🟢 一般提供

データモデル

BigQuery からのテーブルが Foundry にインポートされ、データは Avro 形式で保存されます。 BIGNUMERIC および TIME タイプの列はインポート時にサポートされていません。

Foundry から BigQuery にデータをエクスポートする場合、MAPS、STRUCTS、および ARRAYS を除くすべての列タイプがサポートされています。

パフォーマンスと制限事項

非標準の BigQuery テーブルから 20GB 以上のデータを同期する場合、一時ストレージテーブルを有効にする必要があります。単一の同期では、ディスク上で利用可能なサイズまでのデータをインポートできます。直接接続で実行される同期の場合、これは通常 600GB に制限されます。より大きなテーブルをインポートするには、増分同期を使用してください。

セットアップ

データ接続アプリケーションを開き、画面右上の + 新しいソース を選択します。
利用可能なコネクタタイプから BigQuery を選択します。
インターネット経由で 直接接続 を使用するか、中間エージェント経由で接続する を選択します。
以下のセクションに記載されている情報を使用して、コネクタのセットアップを続行する追加の構成プロンプトに従います。

Foundry でコネクタを設定する方法について詳しく学びましょう。

BigQuery の認証とセットアップを進めるには、Google Cloud IAM サービスアカウントが必要です。

認証

BigQuery コネクタを使用するには、次の Identity and Access Management（IAM）ロールが必要です。

BigQuery データを読み取る：

BigQuery Read Session User: BigQuery プロジェクトに付与
BigQuery Data Viewer: データとメタデータを読み取るために BigQuery データに付与
BigQuery Job User（オプション）：ビューを取り込み、カスタムクエリを実行するために付与

Foundry から BigQuery にデータをエクスポートする：

BigQuery Data Editor: BigQuery データセットまたはプロジェクトに付与
BigQuery Job User: BigQuery プロジェクトに付与
Storage Object Admin: Google Cloud Storage でデータがエクスポートされる場合、バケットに付与

一時テーブルを使用する：

BigQuery Data Editor: コネクタによってデータセットが自動的に作成される場合、BigQuery プロジェクトに付与
BigQuery Data Editor: 一時テーブルを格納するために提供されたデータセットに付与

Google Cloud のアクセス制御に関するドキュメントで、必要なロールについて詳しく学びましょう。

2 つの利用可能な認証方法から選択します。

GCP インスタンスアカウント: インスタンスベースの認証を設定する方法については、Google Cloud のドキュメントを参照してください。
- GCP インスタンス認証は、GCP で適切に設定されたインスタンスで実行されるエージェントを通じて動作するコネクタに対してのみ機能します。
- 仮想テーブルでは、GCP インスタンス認証資格情報はサポートされていません。
サービスアカウントキーファイル: サービスアカウントキーファイル認証の設定方法については、Google Cloud のドキュメントを参照してください。キーファイルは、JSON または PKCS8 資格情報として提供できます。

ネットワーキング

BigQuery コネクタは、443 ポートで次のドメインへのネットワークアクセスが必要です。

bigquery.googleapis.com
bigquerystorage.googleapis.com
storage.googleapis.com
www.googleapis.com

次のドメインに追加のアクセスが必要になる場合があります。

oauth2.googleapis.com
accounts.google.com

Google Cloud Platform（GCP）上の Foundry と GCP 上の BigQuery 間の直接接続を確立する場合、関連する VPC サービスコントロールを介して接続を有効にする必要があります。この接続がセットアップに必要な場合は、Palantir サポートにお問い合わせください。

接続の詳細

BigQuery コネクタには、次の構成オプションが用意されています。

オプション	必須？	説明
`Project ID`	はい	BigQuery プロジェクトの ID。このプロジェクトは、同期されるデータに関係なく、BigQuery のコンピューティング使用量が請求されます。
`Credentials settings`	はい	上記の認証ガイダンスを使用して構成します。
`Cloud Storage bucket`	いいえ	BigQuery にデータを書き込むためのステージング場所として使用される Cloud Storage バケットの名前を追加します。
`Proxy settings`	いいえ	BigQuery へのプロキシ接続を許可するように設定します。
`Settings for temporary tables`	いいえ*	一時テーブルを使用するために有効にします。
`GRPC Settings`	いいえ	GRPC チャンネルを構成するために使用される高度な設定。
`Additional projects`	いいえ	同じ接続でアクセスする必要がある追加のプロジェクトの ID を追加します。このコネクタの資格情報として使用される Google Cloud アカウントは、これらのプロジェクトにアクセスする必要があります。 BigQuery データアクセスまたはコンピューティング使用量について、コネクタの `Project Id` が請求されます。

*一時テーブルは、仮想テーブルを介して BigQuery ビューを登録する場合に有効にする必要があります。

BigQuery からのデータ同期

BigQuery 同期を設定するには、ソースの概要画面の右上にある 探索および同期の作成 を選択します。次に、Foundry に同期するテーブルを選択します。同期する準備ができたら、x データセットの同期を作成 を選択します。

Foundry でソース探索について詳しく学びましょう。

一時テーブル

非標準の BigQuery テーブルから 20GB 以上のデータを同期する場合、一時テーブルを有効にする必要があります。一時テーブルを使用すると、BigQuery は大きなクエリ出力からの結果をインポートし、ビューおよび他の非標準テーブルからのデータをインポートし、大規模な増分インポートおよび取り込みを可能にします。

一時テーブルを使用するには、コネクタ構成で Settings for temporary tables を有効にします。

データセットを自動的に作成する： 一時テーブルを格納する Palantir_temporary_tables データセットを作成するこのオプションを選択します。このオプションでは、BigQuery アカウントにプロジェクトの BigQuery Data Editor ロールが必要です。
使用するデータセットを提供する： 手動で Project ID および一時テーブルを格納するデータセットの Dataset name を追加するこのオプションを選択します。このオプションでは、BigQuery アカウントに提供されたデータセットの BigQuery Data Editor ロールが必要です。

一時テーブルは、BigQuery ビューを仮想テーブルとともに使用する場合、有効にする必要があります。

BigQuery 同期の構成

BigQuery コネクタは、大規模なデータ同期およびカスタムクエリに対して高度な同期構成を提供します。

利用可能な同期を探索し、それらをコネクタに追加した後、同期の編集 に移動します。左側の同期パネルで、構成する同期を見つけ、右側の > を選択します。

インポート設定

BigQuery から Foundry に同期するデータを選択します。

同期フルテーブル

Foundry にテーブル全体を同期するために、次の情報を入力します。

オプション	必須？	説明
`BigQuery project Id`	いいえ	テーブルが属するプロジェクトの ID。
`BigQuery dataset`	はい	テーブルが属するデータセットの名前。
`BigQuery table`	いいえ	Foundry に同期されるテーブルの名前。

カスタム SQL

任意のクエリを実行し、その結果が Foundry に保存されます。クエリの出力は、20GB（BigQuery テーブルの最大サイズ）未満であるか、一時テーブルの使用が有効になっている必要があります。クエリは、キーワード select または with で始める必要があります。たとえば：SELECT * from table_name limit 100;。

増分同期

通常、同期はターゲットテーブルからすべての一致する行をインポートします。同期間のデータが変更されたかどうかに関係なく。対照的に、増分同期は、最新の同期に関する状態を維持し、ターゲットから新しい一致行のみを取り込みます。

増分同期は、BigQuery から大規模なテーブルを取り込む場合に使用できます。増分同期を使用するには、テーブルに厳密に単調増加する列が含まれている必要があります。さらに、読み取り元のテーブルまたはクエリに、次のデータ型のいずれかが含まれている必要があります。

INT64
FLOAT64
NUMERIC
BIGNUMERIC
STRING
TIMESTAMP
DATE
TIME
DATETIME

例： 5TB のテーブルには、BigQuery に同期するために何十億もの行が含まれています。テーブルには、単調増加列である id という名前の列があります。同期は、増分列 として id 列を使用して、初期値が -1 であり、50 万行の制限が設定された状態で 1 回に 50 万行を取り込むように構成できます。

同期が最初に実行されると、最初の 50 万行（id に基づいて昇順）が、id 値が -1 より大きい行から Foundry に取り込まれます。たとえば、この同期が複数回実行され、最後の同期の実行中に取り込まれた最大の id が 19384004822 だった場合、次の同期では、19384004822 より大きい最初の id から始まる次の 50 万行がインポートされます。これは、以降も続きます。

増分同期には、次の構成が必要です。

オプション	必須？	説明
列	はい	増分取り込みに使用される列を選択します。テーブルがサポートされている列タイプを含まない場合、ドロップダウンは空になります。
`Initial value`	はい	データを同期し始める値。
`Limit`	いいえ	単一の同期でダウンロードするレコードの数。

カスタムクエリ用の増分同期

カスタムクエリ同期の増分クエリを有効にするには、クエリを次の形式に更新する必要があります。

SELECT * from table_name where incremental_column_name > @value order by incremental_column_name asc limit @limit

BigQuery にデータをエクスポートする

コネクタは、2 つの方法で BigQuery にエクスポートできます。

Google Cloud Storage を仲介ストアとして使用します（推奨）。下記の Cloud Storage 経由でのエクスポートのセクションで詳細を確認してください。
BigQuery API を通じて。ローカルファイルからのデータの読み取りで、使用される API の詳細を確認してください。

API を介しての書き込みは、いくつかの百万行のデータスケールに適しています。このモードの期待されるパフォーマンスは、約 2 分で 100 万行をエクスポートすることです。データスケールが何十億行に達する場合は、代わりに Google Cloud Storage を使用してください。

タスク構成

データをエクスポートするには、エクスポートタスクを構成する必要があります。エクスポートするコネクタが含まれているプロジェクトフォルダーに移動します。コネクタ名を右クリックし、Create Data Connection Task を選択します。

データ接続ビューの左側のパネルで、Source 名が使用するコネクタと一致することを確認します。次に、Input フィールドに入力データセットを追加します。入力データセットは inputDataset と呼ばれる必要があり、これはエクスポートされる Foundry データセットです。エクスポートタスクには、1 つの Output を構成する必要があります。出力データセットは、outputDataset と呼ばれる必要があり、Foundry データセットを指します。出力データセットは、タスクの実行、スケジュール、および監視に使用されます。

データ接続ビューの左パネルで：

Source 名が使用するコネクタと一致することを確認します。
inputDataset という名前の Input を追加します。入力データセット は、エクスポートされる Foundry データセットです。
outputDataset という名前の Output を追加します。出力データセット は、タスクの実行、スケジュール、および監視に使用されます。
最後に、テキストフィールドに YAML ブロックを追加して、タスク構成を定義します。

YAMl で定義された名前は、左側のパネルに表示されるコネクタと入力データセットのラベルに反映されません。

エクスポートタスクの YAML を作成する際に、次のオプションを使用します。

オプション	必須？	デフォルト	説明
`project`	いいえ	コネクタのプロジェクト ID	宛先テーブルが属するプロジェクトの ID。
`dataset`	はい		テーブルが属するデータセットの名前。
`table`	はい		データがエクスポートされるテーブルの名前。
`incrementalType`	はい	SNAPSHOT	値は SNAPSHOT または REQUIRE_INCREMENTAL にすることができます。 • スナップショットモードでエクスポートする：宛先テーブルの内容が置き換えられます。 • インクリメンタルモードでエクスポートする：内容が既存のテーブルに追加されます。

増分エクスポートを設定するには、最初に SNAPSHOT としてエクスポートを実行し、incrementalType を REQUIRE_INCREMENTAL に変更します。

例のタスク構成：

Copied!1
2
3
4
5
6
7
type: magritte-bigquery-export-task
config:
    table:
      dataset: datasetInBigQuery  #BigQuery内のデータセット
      table: tableInBigQuery  #BigQuery内のテーブル
      project: projectId #(Optional: Do not specify unless the Project for export differs from the Project configured for the connector.) #（任意：エクスポート用のプロジェクトがコネクター用に設定されたプロジェクトと異なる場合にのみ指定してください。）
    incrementalType: SNAPSHOT | REQUIRE_INCREMENTAL  #インクリメンタルタイプ：SNAPSHOT | REQUIRE_INCREMENTAL

Parquet 形式で行が保存されているデータセットのみが、BigQueryへのエクスポートをサポートしています。

エクスポートタスクを設定した後、右上隅の Save を選択します。

出力テーブルへの行の追加

目的のテーブルに行を追加する必要がある場合、データセットを置換するのではなく、REQUIRE_INCREMENTALを使用できます。

インクリメンタル同期では、行が入力データセットにのみ追加され、BigQueryの目的地テーブルがFoundryの入力データセットのスキーマと一致する必要があります。

Cloud Storage 経由でのエクスポート（推奨）

Cloud Storage 経由でエクスポートするには、コネクターの設定設定で Cloud Storage バケットが設定されている必要があります。さらに、Cloud Storage バケットは、コネクターの一時テーブル専用に使用され、バケットに一時的に書き込まれた任意のデータが可能な限り少ないユーザーにアクセス可能となるようにする必要があります。

BigQuery APIs 経由でのエクスポートよりも、Cloud Storage 経由で BigQuery にエクスポートすることをお勧めします。Cloud Storage はスケールで良好に動作し、BigQuery で一時テーブルを作成しません。

BigQuery APIs 経由でのエクスポート

エクスポートジョブは、目的地テーブルの隣に一時テーブルを作成します。この一時テーブルには追加のアクセス制限が適用されません。さらに、SNAPSHOTエクスポートはテーブルをドロップし、再作成します。これは、追加のアクセス制限もドロップされることを意味します。

BigQuery APIs 経由でのエクスポート中、データは一時テーブル datasetName.tableName_temp_$timestamp にエクスポートされます。エクスポートが完了すると、行は自動的に一時テーブルから目的地テーブルに転送されます。

Hive テーブルパーティションは BigQuery APIs 経由でのエクスポートをサポートしていません。Hive テーブルでパーティション化されたデータセットは、Cloud Storage 経由でエクスポートしてください。

エクスポートが REQUIRE_INCREMENTAL モードで実行される場合、目的地テーブルを共有できます。SNAPSHOT モードで実行すると、テーブルは各実行時に再作成され、共有を再適用する必要があります。

BigQuery APIs 経由で成功裏にエクスポートするためには、エクスポートしたテーブルに BigQuery の行レベルや行レベルの権限を適用しないでください。

仮想テーブル

このセクションでは、BigQuery ソースを使用した仮想テーブルに関する追加の詳細を提供します。このセクションは、Foundry データセットへの同期時には適用されません。

仮想テーブルの機能	ステータス
ソース形式	🟢 一般提供: テーブル、ビュー、マテリアライズドビュー
手動登録	🟢 一般提供
自動登録	🟢 一般提供
Pushdown計算	🟢 一般提供; BigQuery Spark コネクタ経由で利用可能
インクリメンタルパイプラインのサポート	🟢 一般提供: `APPEND` のみ

仮想テーブルにバックアップされたインクリメンタルパイプラインは、BigQuery が UPDATE や DELETE の変更情報を提供しないため、APPEND-only のソーステーブル上に構築することが重要です。詳細は公式の BigQuery ドキュメンテーションを参照してください。

仮想テーブルを使用するときは、次のソース設定要件を覚えておいてください：

ソースを直接接続として設定する必要があります。仮想テーブルは中間エージェントの使用をサポートしていません。
サービスアカウントキーファイルの資格情報を使用します。インスタンスベースの認証は、仮想テーブルではサポートされていません。
一時テーブルを有効にし、BigQuery ビューを登録するためには、関連する役割を認証資格情報に追加する必要があります。

詳細については、上記の接続詳細および一時テーブルセクションを参照してください。

トラブルシューティング

Not found: Dataset `<dataset>` was not found in location `<location>`

BigQueryは、クエリが実行される場所を、クエリで使用される入力か、クエリの結果が保存される場所に基づいて決定します。一時テーブルが使用されると、出力は一時テーブルの一時テーブルデータセットに設定され、このデータセットの場所がクエリが実行される場所を決定します。同期のすべての入力と一時テーブルデータセットが同じ地域にあることを確認します。**データセットを自動作成する。**設定が有効になっている場合、Google Cloud コンソールまたは Google の SDK/API を使用して、Palantir_temporary_tables というデータセットの場所を確認します。

gRPC message exceeds maximum size

JSON 列などの大量のコンテンツを含むデータを同期する場合、上記のエラーで転送が失敗する可能性があります。GRPC Settings の BigQuery の Maximum inbound message sizeを調整して、単一の API コールでのデータ転送量を増やします。ただし、単一のコールでは複数の行を取得するので、最大の行サイズに設定するだけでは不十分かもしれません。