# Google Bigquery Import Integration V2 [Google BigQuery Export Integration V2の詳細はこちら](/ja/int/google-bigquery-export-integration-v2) Google BigQuery V2のインテグレーションにより、BigQueryテーブルまたはクエリ結果からTreasure Dataにデータをインポートすることができます。 ## 前提条件 - Treasure Dataの基本的な知識 - Google Cloud Platform(BigQuery、Cloud Storage、IAM)の基本的な知識 ## 制限事項 - このコネクタではOAuthはサポートされなくなりました。JSON keyfileのみサポートされています。 - データセットがUSまたはEUマルチリージョン以外の場所にある場合は、ロケーションを指定する必要があります。指定しない場合、TDのジョブは「Cannot find job_id xxxxx」というエラーで失敗します。 - このコネクタは[外部テーブル](https://cloud.google.com/bigquery/external-data-sources)のインポートをサポートしていません。 - ビューからのインポートは、tableではなくqueryのインポートタイプを使用する必要があります。 - テーブルまたはクエリにRange型のフィールドが含まれている場合、GCSへのエクスポートは使用できません。使用すると「Unsupported type for JSON export: RANGE」というエラーが発生します。 - **Require partition filter**オプションが有効になっているパーティションテーブルからqueryタイプでインポートする場合、SQL文のWHERE句にパーティションフィールドを含める必要があります。含めないと、「Cannot query over table 'xxxxx' without a filter over column(s) '{partition field}' that can be used for partition elimination」というエラーが返されます。 - queryタイプのインポートでlegacyを使用する場合、`INTERVAL、TIMESTAMP(12)、JSON、またはRANGE`のデータ型のフィールドを含むソーステーブルはサポートされず、「Querying tables with INTERVAL, TIMESTAMP(12), JSON, or RANGE type is not supported in Legacy SQL」というエラーが返されます。 - **Require partition filter**オプションが有効になっているPartition Tableは、インポートモードtableでは増分インポートをサポートしていませんが、インポートモードqueryではサポートしています。 ## 権限とロール このデータコネクタを使用するには、認証されたアカウント(サービスアカウント)に以下の権限またはIAMロールが必要です。 | **カテゴリ** | **必要な権限** | **最小IAMロール** | | --- | --- | --- | | **テーブルロードを使用する場合** | - bigquery.tables.get - bigquery.tables.getData | - BigQuery Data Viewer | | **クエリロードを使用する場合** | - bigquery.jobs.create | - BigQuery Job User | | **"Import Large Dataset"を使用する場合** | - bigquery.tables.export - bigquery.tables.delete - storage.buckets.get - storage.objects.list - storage.objects.create - storage.objects.delete - storage.objects.get | - BigQuery Data Editor - Storage Legacy Bucket Writer - Storage Legacy Object Reader | IAMの権限とロールの詳細については、Google Cloudのドキュメントを参照してください:[BigQuery](https://cloud.google.com/bigquery/docs/access-control)および[Cloud Storage](https://cloud.google.com/storage/docs/access-control/iam-roles) ## TD Consoleを使用する ### 新しい認証を作成する 1. **Integrations Hub** > **Catalog**に移動します。 2. **Google BigQuery**を検索して選択します。 3. ダイアログが開きます。**JSON keyfile**のみがサポートされています。 ![](/assets/screenshot-2025-06-19-at-19.36.07.72bff3697a33d042c422ef4851450b60f0c04ea69082df8ca3d3924e42c846f9.743d8bf4.png) 4. サービスアカウントキーのJSON文字列を「JSON keyfile」セクションに入力します。 5. 新しいサービスアカウントキーの作成については、[Google Cloudのドキュメント](https://cloud.google.com/iam/docs/creating-managing-service-account-keys)を参照してください。 ### クエリを検証する SQL結果をロードする場合は、「Query statement」を選択し、「SQL statement」にSQLクエリを入力します。 転送を作成する前に、BigQuery Web UIでクエリが有効であることを確認してください。[https://cloud.google.com/bigquery/quickstart-web-ui](https://cloud.google.com/bigquery/quickstart-web-ui) ### 新しい転送を作成する 接続を作成すると、自動的にAuthenticationsタブに移動します。作成した接続を探してSourceを選択します。 #### Fetch from インポートするデータソースを設定します。 Google Cloud PlatformプロジェクトのIDを「Project ID」に入力します。 テーブルを保存するデータセット名を入力します。 #### Import Types インポートのタイプを選択します。テーブル全体をロードする(**table loading**)か、SQL結果をロードする(**query loading**)かを選択します。 #### Table Loading テーブル全体をロードする場合は、「Table」を選択し、エクスポートしたい「Table name」を入力します。 マテリアライズドビューをロードする場合は、代わりに「Query Statement」を選択してください。 ![](/assets/screenshot-2025-06-19-at-19.45.09.e970ef1f4a21796c734e018a235d92aaf68068158b17b6041490dab27aaca6f3.743d8bf4.png) #### Query Loading SQL結果をロードする場合は、「Query statement」を選択し、「SQL statement」にSQLクエリを入力します。 ![](/assets/screenshot-2025-06-19-at-19.46.50.00c1474f54b84589a4ad38635d7da6d358a48a2b586b80a8356c27a183403ed0.743d8bf4.png) デフォルトのSQL方言は[Standard SQL](https://cloud.google.com/bigquery/docs/reference/standard-sql/)です。[Legacy SQL](https://cloud.google.com/bigquery/docs/reference/legacy-sql)を使用する場合は、**Use Legacy SQL**をチェックしてください。 デフォルトでは、このコネクタは特定の条件下で[キャッシュされた結果](https://cloud.google.com/bigquery/docs/cached-results)を使用します。キャッシュを無効にする場合は、**Use Cached Results**のチェックを外してください。 User Defined Function List: クエリで使用する関数 ![](/assets/screenshot-2025-06-19-at-20.20.11.64913b55b52cfa6d9211513592169ef61dd410afcb41757d319fd39ff24d1700.113453a0.png) Legacy SQLの場合は以下に従ってください:[https://cloud.google.com/bigquery/docs/user-defined-functions-legacy#register](https://cloud.google.com/bigquery/docs/user-defined-functions-legacy#register) Standard SQLの場合は以下に従ってください:[https://cloud.google.com/bigquery/docs/user-defined-functions#sql-udf-structure](https://cloud.google.com/bigquery/docs/user-defined-functions#sql-udf-structure) UDFがすでに存在する場合、クエリはエラーになる可能性があります。 ### Data Location データがUSまたはEUマルチリージョン以外の場所にある場合は、ロケーションを指定する必要があります。 データがasia-northeast1リージョンにある場合は、ロケーションを指定する必要があります。 ロケーションの詳細については、[Google Cloudのドキュメント](https://cloud.google.com/bigquery/docs/dataset-locations)を参照してください。 ### インクリメンタルローディング インクリメンタルローディングは、自動増分ID列や作成日のタイムスタンプ列など、増加する一意の列を使用して、前回の実行後の新しいレコードのみをロードできます。 これを有効にするには、**Incremental Loading** をチェックし、「Incremental Column Name」に増分する列名を指定します。 インクリメンタル列としてサポートされているのは、INTEGER型とTIMESTAMP型のみです。 #### 動作の仕組み このコネクタは、インクリメンタル列で順序付けられた最新のレコードである「最終レコード」を記録します。次回の実行時には、最終レコードを使用して以下のルールで構築されたクエリを実行してレコードをロードします。 テーブルローディングの場合、すべてのフィールドがWHERE句で選択されます。 ```sql SELECT * FROM `${dataset}.${table}` WHERE ${incremental_column} > ${value_of_last_record} ``` クエリローディングの場合、生のクエリがWHERE句でラップされます。 ```sql SELECT * FROM (${query}) embulk_incremental_ WHERE ${incremental_column} > ${value_of_last_record} ``` ### 大規模データセットのインポート 大規模なデータセット(ベンチマークとして500MB以上)をロードする場合は、この「Import Large Dataset」オプションの使用を推奨します。このオプションは、データをGCS(Google Cloud Storage)オブジェクトとしてエクスポートし、複数のタスクでデータをロードします。そのため、ロードが高速化されます。 このオプションを有効にするには、**Import Large Dataset** をチェックし、「GCS bucket」と「GCS path prefix」を指定します。 #### 動作の仕組み - クエリ(クエリローディングまたはインクリメンタルローディング付きのテーブルローディング)を実行すると、クエリ結果はデータセット設定内の一時的なBigQueryテーブルにエクスポートされます。 - その後、一時テーブルは、パスプレフィックスを使用してGoogle Cloud Storageバケットに「*gs://my-bucket/data-connector/result-[12桁の数字].jsonl.gz*」としてgzip圧縮された[JSON Lines](http://jsonlines.org/)ファイルとしてエクスポートされます。ファイルの数は結果データのサイズによって異なります。 - インクリメンタルローディングなしのテーブルローディングの場合、ソーステーブル内のすべてのデータが直接GCSにエクスポートされます。 - 完了後、一時テーブルとGCSオブジェクトは削除されます。 #### 一時リソースのデータロケーション - データセットが「US」に設定されていない場合、GCSバケットもテーブルと同じロケーションにある必要があります。米国ベースのデータセットから別のリージョンのCloud Storageバケットにデータをエクスポートできます。詳細については、Google Cloudの[エクスポート制限ドキュメント](https://cloud.google.com/bigquery/docs/exporting-data#export_limitations)を参照してください。 ### Data Preview インポートを実行する前に、Generate Preview を選択してデータの[プレビュー](/products/customer-data-platform/integration-hub/batch/import/previewing-your-source-data)を表示できます。Data preview はオプションであり、選択した場合はダイアログの次のページに安全にスキップできます。 1. **Next** を選択します。Data Preview ページが開きます。 2. データをプレビューする場合は、**Generate Preview** を選択します。 3. データを確認します。 ### Data Placement データの配置について、データを配置したいターゲット database と table を選択し、インポートを実行する頻度を指定します。 1. **Next** を選択します。Storage の下で、インポートされたデータを配置する新しい database を作成するか、既存の database を選択し、新しい table を作成するか、既存の table を選択します。 2. **Database** を選択 > **Select an existing** または **Create New Database** を選択します。 3. オプションで、database 名を入力します。 4. **Table** を選択 > **Select an existing** または **Create New Table** を選択します。 5. オプションで、table 名を入力します。 6. データをインポートする方法を選択します。 - **Append** (デフォルト) - データインポートの結果は table に追加されます。 table が存在しない場合は作成されます。 - **Always Replace** - 既存の table の全体の内容をクエリの結果出力で置き換えます。table が存在しない場合は、新しい table が作成されます。 - **Replace on New Data** - 新しいデータがある場合のみ、既存の table の全体の内容をクエリの結果出力で置き換えます。 7. **Timestamp-based Partition Key** 列を選択します。 デフォルトキーとは異なるパーティションキーシードを設定したい場合は、long または timestamp 列をパーティショニング時刻として指定できます。デフォルトの時刻列として、add_time フィルターで upload_time を使用します。 8. データストレージの **Timezone** を選択します。 9. **Schedule** の下で、このクエリを実行するタイミングと頻度を選択できます。 #### 一度だけ実行 1. **Off** を選択します。 2. **Scheduling Timezone** を選択します。 3. **Create & Run Now** を選択します。 #### 定期的に繰り返す 1. **On** を選択します。 2. **Schedule** を選択します。UI では、*@hourly*、*@daily*、*@monthly*、またはカスタム *cron* の 4 つのオプションが提供されます。 3. **Delay Transfer** を選択して、実行時間の遅延を追加することもできます。 4. **Scheduling Timezone** を選択します。 5. **Create & Run Now** を選択します。 転送が実行された後、**Data Workbench** > **Databases** で転送の結果を確認できます。 ## データ変換 BigQueryのデータ型は、次の表に示すように、対応するTreasure Dataの型に自動的に変換されます。テーブルまたはクエリ結果のスキーマにサポートされていない型が含まれている場合、エラーが発生します。 | BigQuery | Treasure Data | | --- | --- | | STRING | string | | BYTES | string | | INTERVAL | string | | RANGE | string | | GEOGRAPHY | string | | INTEGER | long | | FLOAT | double | | NUMERIC | string | | BIGNUMERIC | string | | BOOLEAN | long (trueは1、falseは0) | | TIMESTAMP | string (yyyy-MM-dd HH:mm:ss.SSS) | | DATE | string | | TIME | string | | DATETIME | string | | RECORD | string (JSONとして) | | REPEATED (PRIMITIVE or RECORD) | string (JSONとして) | ## クォータと制限 [BigQueryとCloud Storage](https://cloud.google.com/bigquery/quotas)のすべてのクォータと制限は、GCPプロジェクトに適用されます。 ## CLI経由でBigQueryコネクタを使用する 必要に応じて、[TD Toolbelt](https://toolbelt.treasuredata.com/)経由でコネクタを使用できます。 CLI上で[TDツールベルト](https://api-docs.treasuredata.com/en/tools/cli/quickstart/)をセットアップします。 ### 設定ファイルの作成 ここでは「config.yml」と呼ばれる設定YAMLファイルを作成します。 - GCSへのエクスポートとインクリメンタルを使用したテーブルからのインポート例 ```yaml in: type: bigquery_v2 json_keyfile: content: | { xxxxxxxx } project_id: xxxx dataset: xxx import_type: table table: xxxx location: US export_to_gcs: true gcs_bucket: xxxx gcs_path_prefix: xxxx incremental: true incremental_column: xxx ``` ### ユーザー定義関数と GCS へのエクスポートおよび差分インポートを使用したクエリからのインポートの例 ```yaml in: type: bigquery_v2 json_keyfile: content: | { xxxxxxxx } project_id: xxxx dataset: xxx import_type: query query: xxxxxxx location: US udf: - function: | CREATE TEMP FUNCTION addTwo(x INT64) RETURNS INT64 AS ( x + 2 ) - function: | CREATE TEMP FUNCTION addTwo(x INT64) RETURNS INT64 AS ( x + 2 ) location: US export_to_gcs: true gcs_bucket: xxxx gcs_path_prefix: xxxx incremental: true incremental_column: xxx ``` ### パラメータ | 名前 | 説明 | タイプ | 値 | デフォルト値 | 必須 | | --- | --- | --- | --- | --- | --- | | type | コネクタタイプ | string | bigquery_v2 | N/A | Yes | | json_keyfile | Google サービスアカウント JSON キー | content プロパティを持つオブジェクト 例: json_keyfile: content: | xxxxxxxx | N/A | N/A | | project_id | BigQuery プロジェクト ID | string | N/A | N/A | Yes | | dataset | BigQuery データセット | string | N/A | N/A | Yes | | import_type | ソースインポート | string | サポートされる値: - table - query | table | Yes | | table | テーブル名 | string | N/A | N/A | import_type が table の場合は Yes | | query | SQL ステートメント | string | N/A | N/A | import_type が query の場合は Yes | | udf | ユーザー定義関数リスト | 関数の配列 例: udf: - function: | xxxxxxx - function: | xxxxxxxxx | N/A | | use_legacy_sql | レガシー SQL ダイアレクトを使用 | boolean | true/false | false | No | | use_query_cache | キャッシュされた結果を使用 | boolean | true/false | true | No | | location | データセットのロケーション(リージョン) | string | サポートされる値: UNSPECIFIED および以下のリストの値 https://cloud.google.com/bigquery/docs/dataset-location | UNSPECIFIED | No | | incremental | 差分読み込みを有効にするかどうか | boolean | true/false | false | No | | incremental_column | 差分読み込み用のカラム名 | string | N/A | N/A | incremental が true の場合は Yes | | export_to_gcs | GCS へのエクスポート機能を使用するかどうか | boolean | true/false | true | No | | gcs_bucket | 結果をエクスポートする GCS バケット | string | N/A | N/A | export_to_gcs が true の場合は Yes | | gcs_path_prefix | GCS ファイルのファイルパスのプレフィックス | string | N/A | N/A | export_to_gcs が true の場合は Yes | (オプション) プレビュー td [td connector:preview](https://api-docs.treasuredata.com/en/tools/cli/api/#td-connector-preview) コマンドを実行して、設定ファイルを検証します ```bash td connector:preview config.yml ``` ### 新しいコネクタセッションの作成 [td connector:create](https://api-docs.treasuredata.com/en/tools/cli/api/#td-connector-create) を実行します。 次の例では、BigQuery コネクタを使用した日次インポートセッションが作成されます。 ```bash $ td connector:create daily_bigquery_import \ "10 0 * * *" td_sample_db td_sample_table config.yml Name : daily_bigquery_import Cron : 10 0 * * * Timezone : UTC Delay : 0 Database : td_sample_db Table : td_sample_table Config --- in: ... ``` ### データパーティションキー コネクタセッションでは、結果データ内に少なくとも 1 つのタイムスタンプカラムがデータパーティションキーとして使用される必要があり、デフォルトでは最初のタイムスタンプカラムがキーとして選択されます。カラムを明示的に指定する場合は、"**--time-column**" オプションを使用します。 ```bash $ td connector:create --time-column created_at \ daily_bigquery_import ... ``` 結果データにタイムスタンプカラムがない場合は、次のようにフィルタ設定を追加して "**time**" カラムを追加します。 ```yaml in: type: bigquery ... filters: - type: add_time from_value: mode: upload_time to_column: name: time out: type: td ```