Cloud Storage から CSV ファイルを読み込む
Cloud Storage から CSV データを読み込む際は、データを新しいテーブルまたはパーティションに読み込む、データを既存のテーブルまたはパーティションに追加する、または既存のテーブルまたはパーティションを上書きすることが可能です。BigQuery に読み込まれたデータは Capacitor の列型(BigQuery のストレージ形式)に変換されます。
Cloud Storage から BigQuery のテーブルにデータを読み込むとき、読み込み先のテーブルを含むデータセットは Cloud Storage バケットと同じリージョンまたはマルチリージョン ロケーションに存在している必要があります。
ローカル ファイルから CSV データを読み込む方法については、ローカル データソースから BigQuery にデータを読み込むをご覧ください。
使ってみる
Google Cloud を初めて使用される方は、アカウントを作成して、実際のシナリオでの BigQuery のパフォーマンスを評価してください。新規のお客様には、ワークロードの実行、テスト、デプロイに使用できる無料クレジット $300 分を差し上げます。
BigQuery の無料トライアル制限事項
CSV ファイルを BigQuery に読み込む場合は、次の点に注意してください。
- CSV ファイルはネストされたデータや繰り返しデータに対応していません。
- gzip 圧縮を使用した場合、BigQuery はデータを並列で読み取ることができません。圧縮された CSV データを BigQuery に読み込む場合は、圧縮されていないデータを読み込むよりも時間がかかります。圧縮データと非圧縮データを読み込むをご覧ください。
- 同じ読み込みジョブに圧縮ファイルと非圧縮ファイルの両方を含めることはできません。
- gzip ファイルの最大サイズは 4 GB です。
- CSV データまたは JSON データを読み込む場合、
DATE
列の値に区切りとしてダッシュ(-
)を使用し、YYYY-MM-DD
(年-月-日)の形式にする必要があります。 - JSON または CSV データを読み込む場合、
TIMESTAMP
列のタイムスタンプ値の日付部分の区切りにはダッシュ(-
)を使用し、日付はYYYY-MM-DD
(年-月-日)の形式にする必要があります。タイムスタンプの時間部分hh:mm:ss
(時-分-秒)には、区切りとしてコロン(:
)を使用します。
必要な権限
BigQuery にデータを読み込むには、読み込みジョブを実行する権限が必要です。また、新規または既存の BigQuery テーブルやパーティションへのデータの読み込みが可能な権限も必要です。Cloud Storage からデータを読み込む場合は、データを含むバケットに対するアクセス権限も必要です。
BigQuery の権限
BigQuery にデータを読み込むには、少なくとも以下の権限が必要です。これらの権限は、データを新しいテーブルまたはパーティションに読み込む場合や、テーブルまたはパーティションに対してデータの追加や上書きを行う場合に必要になります。
bigquery.tables.create
bigquery.tables.updateData
bigquery.jobs.create
bigquery.tables.create
権限および bigquery.tables.updateData
権限はいずれも、事前定義された以下の IAM ロールに含まれています。
bigquery.dataEditor
bigquery.dataOwner
bigquery.admin
次の事前定義済みの IAM ロールには bigquery.jobs.create
権限が含まれています。
bigquery.user
bigquery.jobUser
bigquery.admin
また、bigquery.datasets.create
権限を持つユーザーがデータセットを作成すると、そのデータセットに対する bigquery.dataOwner
アクセス権がユーザーに付与されます。bigquery.dataOwner
アクセス権により、読み込みジョブを使用してデータセット内のテーブルを作成または更新できます。
BigQuery での IAM ロールと権限の詳細については、アクセス制御をご覧ください。
Cloud Storage の権限
Cloud Storage バケットからデータを読み込むには、storage.objects.get
権限が付与されている必要があります。URI のワイルドカードを使用する場合は storage.objects.list
権限も必要です。
IAM 事前定義ロール storage.objectViewer
が付与されると、storage.objects.get
権限と storage.objects.list
権限の両方が与えられます。
CSV データをテーブルに読み込む
CSV データを Cloud Storage から新しい BigQuery テーブルに読み込むには、次の方法を使用します。
- Cloud Console を使用する
bq
コマンドライン ツールのbq load
コマンドを使用するjobs.insert
API メソッドを呼び出してload
ジョブを構成する- クライアント ライブラリを使用する
CSV データを Cloud Storage から新しい BigQuery テーブルに読み込むには:
Console
Cloud Console で [BigQuery] ページを開きます。
[エクスプローラ] パネルでプロジェクトを展開し、データセットを選択します。
詳細パネルで「テーブルを作成」をクリックします。
[テーブルの作成] ページの [ソース] セクションで、次の操作を行います。
[テーブルの作成元] で [Cloud Storage] を選択します。
ソース フィールドで Cloud Storage URI を参照するかまたは入力します。Cloud Console で複数の URI を指定することはできませんが、ワイルドカードはサポートされています。Cloud Storage バケットは、作成するテーブルを含むデータセットと同じロケーションに存在する必要があります。
[ファイル形式] で [CSV] を選択します。
[テーブルの作成] ページの [送信先] セクションで、次の操作を行います。
[データセット名] で、該当するデータセットを選択します。
[テーブルタイプ] が [ネイティブ テーブル] に設定されていることを確認します。
[テーブル名] に、BigQuery で作成するテーブルの名前を入力します。
[スキーマ] セクションの [自動検出] で、[スキーマと入力パラメータ] をオンにしてスキーマの自動検出を有効にします。次の方法でスキーマ定義を手動で入力することもできます。
[テキストとして編集] を有効にし、テーブル スキーマを JSON 配列として入力します。
[フィールドを追加] を使用して、スキーマを手動で入力します。
(省略可)テーブルを分割するには、[パーティションとクラスタの設定] で次のオプションを選択します。
- パーティション分割テーブルを作成するには、[パーティショニングなし] をクリックして [フィールドにより分割] を選択し、
DATE
またはTIMESTAMP
の列を選択します。スキーマにDATE
またはTIMESTAMP
の列が含まれていない場合、このオプションは使用できません。 - 取り込み時間パーティション分割テーブルを作成するには、[パーティショニングなし] をクリックして [取り込み時間により分割] を選択します。
- パーティション分割テーブルを作成するには、[パーティショニングなし] をクリックして [フィールドにより分割] を選択し、
(省略可)クエリを実行するパーティションを指定する
WHERE
句の使用を必須にするには、[パーティショニング フィルタ] で [パーティション フィルタを要求] ボックスをクリックします。パーティション フィルタを必須にすると、コストが削減され、パフォーマンスが向上する場合があります。詳細については、パーティション分割テーブルのクエリをご覧ください。[パーティショニングなし] を選択している場合、このオプションは使用できません。(省略可)テーブルをクラスタ化するには、[クラスタリング順序] ボックスに 1~4 個のフィールド名を入力します。
(省略可)[詳細オプション] をクリックします。
- [書き込み設定] で、[空の場合に書き込む] を選択したままにします。これにより、新しいテーブルが作成され、データが読み込まれます。
- [許可されているエラー数] で、デフォルト値の
0
を使用するか、無視できる最大行数を入力します。エラーを含む行数がこの値を超えると、ジョブはinvalid
メッセージを出して失敗します。 - テーブルのスキーマに存在しない行の値を無視するには、[不明な値] で [不明な値を無視する] をオンにします。
- [フィールド区切り文字] で、CSV ファイル内のセルの区切り文字を選択します。[カンマ]、[タブ]、[パイプ]、[カスタム] のいずれかを選択します。[カスタム] を選択した場合、[カスタムのフィールド区切り文字] ボックスに区切り文字を入力します。デフォルト値はカンマです。
- [スキップするヘッダー行] で、CSV ファイルでスキップするヘッダーの行数を入力します。デフォルト値は
0
です。 - 引用符で囲まれた改行を使用する場合は、[引用符で囲まれた改行を許可する] をオンにして、改行文字を含む引用符で囲まれたデータ セクションを CSV ファイルで許可します。デフォルト値は
false
です。 - ジャグ行を使用する場合、[ジャグ行を許可する] をオンにして、CSV ファイルで末尾のオプションの列が欠落している行を許可します。欠損値は null として扱われます。オフの場合、末尾の列が欠落しているレコードは不良レコードとして処理され、不良レコードが多すぎる場合はジョブの結果内で無効なエラーが返されます。デフォルト値は
false
です。 - Cloud Key Management Service 鍵を使用するには、[暗号化] で [お客様が管理する鍵] クリックします。[Google が管理する鍵] の設定をそのままにすると、BigQuery は保存されているデータを暗号化します。
[テーブルを作成] をクリックします。
bq
bq load
コマンドを使用します。--source_format
フラグを使用して CSV
を指定し、Cloud Storage URI を設定します。単一の URI、URI のカンマ区切りのリスト、ワイルドカードを含む URI を指定できます。スキーマをインラインまたはスキーマ定義ファイルで指定するか、スキーマ自動検出を使用します。
(省略可)--location
フラグを指定して、その値をロケーションに設定します。
次のフラグを使用することもできます。
--allow_jagged_rows
: 指定すると、CSV ファイルで末尾のオプションの列が欠落している行を受け入れます。欠損値は null として扱われます。オフの場合、末尾の列が欠落しているレコードは不良レコードとして処理され、不良レコードが多すぎる場合はジョブの結果内で無効なエラーが返されます。デフォルト値はfalse
です。--allow_quoted_newlines
: 指定すると、改行文字を含む引用符で囲まれたデータ セクションが CSV ファイルで許可されます。デフォルト値はfalse
です。--field_delimiter
: データ内の列間の境界を示す文字。タブ区切り文字には\t
とtab
の両方を使用できます。デフォルト値は,
です。--null_marker
: CSV データの NULL 値を表すオプションのカスタム文字列。--skip_leading_rows
: CSV ファイルの先頭でスキップするヘッダーの行数を指定します。デフォルト値は0
です。--quote
: レコードを囲むために使用する引用符。デフォルト値は"
です。引用符を使用しない場合は、空の文字列を使用します。--max_bad_records
: ジョブ全体が失敗する前に許容される不良レコードの最大数を指定する整数。デフォルト値は0
です。--max_bad_records
の値にかかわらず、最大で 5 つの任意のタイプのエラーが返されます。--ignore_unknown_values
: 指定すると、CSV または JSON データで認識されない余分な値が許可され、無視されます。--autodetect
: 指定すると、CSV および JSON データのスキーマ自動検出が有効になります。--time_partitioning_type
: テーブルでの時間ベースのパーティショニングを有効にし、パーティション タイプを設定します。有効な値はHOUR
、DAY
、MONTH
、YEAR
です。DATE
、DATETIME
、TIMESTAMP
列でパーティション分割されたテーブルを作成する場合、このフラグは省略可能です。時間ベースのパーティショニングのデフォルト パーティション タイプはDAY
です。--time_partitioning_expiration
: 時間ベースのパーティションを削除する必要があるタイミングを指定する整数(秒単位)。パーティションの日付(UTC)に、この整数値を足した値が有効期限になります。--time_partitioning_field
: パーティション分割テーブルの作成に使用されるDATE
またはTIMESTAMP
の列。この値を指定せずに時間ベースのパーティショニングを有効にすると、取り込み時間パーティション分割テーブルが作成されます。--require_partition_filter
: 有効にすると、クエリの実行時にWHERE
句でパーティションを指定するようユーザーに求めます。パーティション フィルタを必須にすると、コストが削減され、パフォーマンスが向上する場合があります。詳細については、パーティション分割テーブルのクエリをご覧ください。--clustering_fields
: クラスタ化テーブルの作成に使用する列名のカンマ区切りのリスト。最大 4 個の列名を指定できます。--destination_kms_key
: テーブルデータの暗号化に使用される Cloud KMS 鍵。bq load
コマンドについて詳しくは、以下をご覧ください。パーティション分割テーブルの詳細については、以下をご覧ください。
クラスタ化テーブルの詳細については、以下をご覧ください。
テーブルの暗号化の詳細については、以下をご覧ください。
CSV データを BigQuery に読み込むには、次のコマンドを入力します。
bq --location=location load \ --source_format=format \ dataset.table \ path_to_source \ schema
ここで
- location はロケーションです。
--location
フラグは省略可能です。たとえば、BigQuery を東京リージョンで使用している場合は、このフラグの値をasia-northeast1
に設定します。.bigqueryrc ファイルを使用してロケーションのデフォルト値を設定できます。 - format は
CSV
です。 - dataset は既存のデータセットです。
- table は、データの読み込み先のテーブル名です。
- path_to_source は、完全修飾の Cloud Storage URI または URI のカンマ区切りのリストです。ワイルドカードもサポートされます。
- schema は有効なスキーマです。スキーマはローカルの JSON ファイルにすることも、コマンドの一部としてインラインで入力することもできます。また、スキーマ定義を指定する代わりに、
--autodetect
フラグを使用することもできます。
例:
次のコマンドは、gs://mybucket/mydata.csv
から mydataset
内の mytable
というテーブルにデータを読み込みます。スキーマは、myschema.json
という名前のローカル スキーマ ファイルで定義されています。
bq load \
--source_format=CSV \
mydataset.mytable \
gs://mybucket/mydata.csv \
./myschema.json
次のコマンドは、gs://mybucket/mydata.csv
から mydataset
内の mytable
というテーブルにデータを読み込みます。スキーマは、myschema.json
という名前のローカル スキーマ ファイルで定義されています。CSV ファイルには、2 行のヘッダーが含まれています。--skip_leading_rows
を指定していない場合、ファイルにヘッダーが含まれていないと想定されます。
bq load \
--source_format=CSV \
--skip_leading_rows=2
mydataset.mytable \
gs://mybucket/mydata.csv \
./myschema.json
次のコマンドは、gs://mybucket/mydata.csv
から mydataset
内の mytable
という取り込み時間パーティション分割テーブルにデータを読み込みます。スキーマは、myschema.json
という名前のローカル スキーマ ファイルで定義されています。
bq load \
--source_format=CSV \
--time_partitioning_type=DAY \
mydataset.mytable \
gs://mybucket/mydata.csv \
./myschema.json
次のコマンドは、gs://mybucket/mydata.csv
からデータを読み込んで mydataset
内の mytable
というパーティション分割テーブルに追加します。テーブルは mytimestamp
列で分割されます。スキーマは、myschema.json
という名前のローカル スキーマ ファイルで定義されています。
bq load \
--source_format=CSV \
--time_partitioning_field mytimestamp \
mydataset.mytable \
gs://mybucket/mydata.csv \
./myschema.json
次のコマンドは、gs://mybucket/mydata.csv
から mydataset
内の mytable
というテーブルにデータを読み込みます。スキーマは自動検出されます。
bq load \
--autodetect \
--source_format=CSV \
mydataset.mytable \
gs://mybucket/mydata.csv
次のコマンドは、gs://mybucket/mydata.csv
から mydataset
内の mytable
というテーブルにデータを読み込みます。スキーマは、field:data_type,field:data_type
の形式でインラインで定義されます。
bq load \
--source_format=CSV \
mydataset.mytable \
gs://mybucket/mydata.csv \
qtr:STRING,sales:FLOAT,year:STRING
次のコマンドは、gs://mybucket/
の複数のファイルから mydataset
内の mytable
という名前のテーブルにデータを読み込みます。Cloud Storage の URI ではワイルドカードを使用しています。スキーマは自動検出されます。
bq load \
--autodetect \
--source_format=CSV \
mydataset.mytable \
gs://mybucket/mydata*.csv
次のコマンドは、gs://mybucket/
の複数のファイルから mydataset
内の mytable
という名前のテーブルにデータを読み込みます。このコマンドでは、Cloud Storage の URI のカンマ区切りのリストをワイルドカード付きで使用しています。スキーマは、myschema.json
という名前のローカル スキーマ ファイルで定義されています。
bq load \
--source_format=CSV \
mydataset.mytable \
"gs://mybucket/00/*.csv","gs://mybucket/01/*.csv" \
./myschema.json
API
Cloud Storage のソースデータを参照する
load
ジョブを作成します。(省略可)ジョブリソースの
jobReference
セクションにあるlocation
プロパティでロケーションを指定します。source URIs
プロパティは、完全修飾のgs://bucket/object
の形式にする必要があります。各 URI にワイルドカード文字「*」を 1 つ含めることができます。sourceFormat
プロパティをCSV
に設定して、CSV データ形式を指定します。ジョブのステータスを確認するには、
jobs.get(job_id*)
を呼び出します。ここで、job_id は、最初のリクエストによって返されたジョブの ID です。status.state = DONE
である場合、ジョブは正常に完了しています。status.errorResult
プロパティが存在する場合は、リクエストが失敗したことを意味し、該当するオブジェクトにエラーを説明する情報が格納されます。リクエストが失敗した場合、テーブルは作成されず、データは読み込まれません。status.errorResult
が存在しない場合、ジョブは正常に完了していますが、一部の行のインポートで問題があったなど、致命的でないエラーが発生した可能性があります。致命的でないエラーは、返されたジョブ オブジェクトのstatus.errors
プロパティに格納されています。
API に関する注:
読み込みジョブはアトミックで整合性があります。読み込みジョブが失敗した場合、データは一切利用できず、読み込みジョブが成功した場合はすべてのデータが利用可能になります。
おすすめの方法として、
jobs.insert
を呼び出して読み込みジョブを作成する際に、一意の ID を生成して、その ID をjobReference.jobId
として渡すようにします。この手法を使用すると、ネットワーク障害時にクライアントは既知のジョブ ID を使ってポーリングまたは再試行できるので、頑健性が向上します。同じジョブ ID に対して
jobs.insert
を呼び出しても結果は同じになります。同じジョブ ID で何回でも再試行できますが、成功するのは、その中で 1 回だけです。
C#
このサンプルを試す前に、BigQuery クイックスタート: クライアント ライブラリの使用の C# の設定手順を実施してください。詳細については、BigQuery C# API のリファレンス ドキュメントをご覧ください。
Go
このサンプルを試す前に、BigQuery クイックスタート: クライアント ライブラリの使用の Go の手順に従って設定を行ってください。詳細については、BigQuery Go API のリファレンス ドキュメントをご覧ください。
Java
このサンプルを試す前に、BigQuery クイックスタート: クライアント ライブラリの使用の Java の設定手順を実施してください。詳細については、BigQuery Java API のリファレンス ドキュメントをご覧ください。
Node.js
このサンプルを試す前に、BigQuery クイックスタート: クライアント ライブラリの使用の Node.js の設定手順を実施してください。詳細については、BigQuery Node.js API のリファレンス ドキュメントをご覧ください。
PHP
このサンプルを試す前に、BigQuery クイックスタート: クライアント ライブラリの使用にある PHP 向けの手順に従って設定を行ってください。詳細については、BigQuery PHP API のリファレンス ドキュメントをご覧ください。
Python
このサンプルを試す前に、BigQuery クイックスタート: クライアント ライブラリの使用の Python の手順に従って設定を行ってください。詳細については、BigQuery Python API のリファレンス ドキュメントをご覧ください。
Client.load_table_from_uri() メソッドを使用して、Cloud Storage にある CSV ファイルからデータを読み込みます。LoadJobConfig.schema プロパティの値を SchemaField オブジェクトのリストに設定することで、スキーマ定義を明示的に指定します。
Ruby
このサンプルを試す前に、BigQuery クイックスタート: クライアント ライブラリの使用で説明している Ruby 向けの手順に沿って設定を行ってください。詳細については、BigQuery Ruby API のリファレンス ドキュメントをご覧ください。
CSV データを列ベースの時間パーティショニングを使用するテーブルに読み込む
CSV データを Cloud Storage から列ベースの時間パーティショニングを使用する BigQuery テーブルに読み込むには:
Go
このサンプルを試す前に、BigQuery クイックスタート: クライアント ライブラリの使用の Go の手順に従って設定を行ってください。詳細については、BigQuery Go API のリファレンス ドキュメントをご覧ください。
Java
このサンプルを試す前に、BigQuery クイックスタート: クライアント ライブラリの使用の Java の設定手順を実施してください。詳細については、BigQuery Java API のリファレンス ドキュメントをご覧ください。
Node.js
このサンプルを試す前に、BigQuery クイックスタート: クライアント ライブラリの使用の Node.js の設定手順を実施してください。詳細については、BigQuery Node.js API のリファレンス ドキュメントをご覧ください。
Python
このサンプルを試す前に、BigQuery クイックスタート: クライアント ライブラリの使用の Python の手順に従って設定を行ってください。詳細については、BigQuery Python API のリファレンス ドキュメントをご覧ください。
CSV データをテーブルに追加、または CSV データでテーブルを上書きする
テーブルに追加のデータを読み込むには、ソースファイルを使用するか、クエリ結果を追加します。
Cloud Console では、[書き込み設定] オプションを使用して、ソースファイルやクエリ結果からデータを読み込むときに行う操作を指定します。
追加のデータをテーブルに読み込む場合、以下のオプションがあります。
Console のオプション | bq ツールのフラグ |
BigQuery API のプロパティ | 説明 |
---|---|---|---|
Write if empty | なし | WRITE_EMPTY |
テーブルが空の場合にのみデータを書き込みます。 |
テーブルに追加する | --noreplace または --replace=false (--[no]replace を指定しない場合、デフォルトは追加) |
WRITE_APPEND |
(デフォルト)テーブルの末尾にデータを追加します。 |
テーブルを上書きする | --replace または --replace=true |
WRITE_TRUNCATE |
新しいデータを書き込む前に、テーブル内の既存のデータをすべて消去します。この操作を行うと、テーブル スキーマと Cloud KMS 鍵も削除されます。 |
既存のテーブルにデータを読み込む場合、読み込みジョブでデータの追加やテーブルの上書きを行うことができます。
次の方法でテーブルを追加または上書きできます。
- Cloud Console を使用する
bq
コマンドライン ツールのbq load
コマンドを使用するjobs.insert
API メソッドを呼び出してload
ジョブを構成する- クライアント ライブラリを使用する
Console
Cloud Console で [BigQuery] ページを開きます。
[エクスプローラ] パネルでプロジェクトを展開し、データセットを選択します。
詳細パネルで「テーブルを作成」をクリックします。
[テーブルの作成] ページの [ソース] セクションで、次の操作を行います。
[テーブルの作成元] で [Cloud Storage] を選択します。
ソース フィールドで Cloud Storage URI を参照するかまたは入力します。Cloud Console で複数の URI を指定することはできませんが、ワイルドカードはサポートされています。Cloud Storage バケットは、データを追加または上書きするテーブルを含むデータセットと同じロケーションに存在している必要があります。
[ファイル形式] で [CSV] を選択します。
[テーブルの作成] ページの [送信先] セクションで、次の操作を行います。
[データセット名] で、該当するデータセットを選択します。
[テーブル名] フィールドに、BigQuery で追加または上書きするテーブルの名前を入力します。
[テーブルタイプ] が [ネイティブ テーブル] に設定されていることを確認します。
[スキーマ] セクションの [自動検出] で、[スキーマと入力パラメータ] をオンにしてスキーマの自動検出を有効にします。次の方法でスキーマ定義を手動で入力することもできます。
[テキストとして編集] を有効にし、テーブル スキーマを JSON 配列として入力します。
[フィールドを追加] を使用して、スキーマを手動で入力します。
[パーティションとクラスタの設定] はデフォルト値のままにします。追加や上書きではテーブルをパーティション分割テーブルまたはクラスタ化テーブルに変換できません。Cloud Console では、読み込みジョブでパーティション分割テーブルやクラスタ化テーブルの追加または上書きを行うことはできません。
[詳細オプション] をクリックします。
- [書き込み設定] で、[テーブルに追加する] または [テーブルを上書きする] を選択します。
- [許可されているエラー数] で、デフォルト値の
0
を使用するか、無視できる最大行数を入力します。エラーを含む行数がこの値を超えると、ジョブはinvalid
メッセージを出して失敗します。 - テーブルのスキーマに存在しない行の値を無視するには、[不明な値] で [不明な値を無視する] をオンにします。
- [フィールド区切り文字] で、CSV ファイル内のセルの区切り文字を選択します。[カンマ]、[タブ]、[パイプ]、[カスタム] のいずれかを選択します。[カスタム] を選択した場合、[カスタムのフィールド区切り文字] ボックスに区切り文字を入力します。デフォルト値はカンマです。
- [スキップするヘッダー行] で、CSV ファイルでスキップするヘッダーの行数を入力します。デフォルト値は
0
です。 - 引用符で囲まれた改行を使用する場合は、[引用符で囲まれた改行を許可する] をオンにして、改行文字を含む引用符で囲まれたデータ セクションを CSV ファイルで許可します。デフォルト値は
false
です。 - ジャグ行を使用する場合、[ジャグ行を許可する] をオンにして、CSV ファイルで末尾のオプションの列が欠落している行を許可します。欠損値は null として扱われます。オフの場合、末尾の列が欠落しているレコードは不良レコードとして処理され、不良レコードが多すぎる場合はジョブの結果内で無効なエラーが返されます。デフォルト値は
false
です。 Cloud Key Management Service 鍵を使用するには、[暗号化] で [お客様が管理する鍵] クリックします。[Google が管理する鍵] の設定をそのままにすると、BigQuery は保存されているデータを暗号化します。
[テーブルを作成] をクリックします。
bq
bq load
コマンドを使用します。--source_format
フラグを使用して CSV
を指定し、Cloud Storage URI を設定します。単一の URI、URI のカンマ区切りのリスト、ワイルドカードを含む URI を指定できます。
スキーマをインラインまたはスキーマ定義ファイルで指定するか、スキーマ自動検出を使用します。
テーブルを上書きするには、--replace
フラグを指定します。テーブルにデータを追加するには、--noreplace
フラグを使用します。フラグを指定しない場合、デフォルトではデータが追加されます。
テーブルを追加または上書きするときに、テーブルのスキーマを変更できます。読み込みオペレーションでサポートされるスキーマの変更については、テーブル スキーマの変更をご覧ください。
(省略可)--location
フラグを指定して、その値をロケーションに設定します。
次のフラグを使用することもできます。
--allow_jagged_rows
: 指定すると、CSV ファイルで末尾のオプションの列が欠落している行を受け入れます。欠損値は null として扱われます。オフの場合、末尾の列が欠落しているレコードは不良レコードとして処理され、不良レコードが多すぎる場合はジョブの結果内で無効なエラーが返されます。デフォルト値はfalse
です。--allow_quoted_newlines
: 指定すると、改行文字を含む引用符で囲まれたデータ セクションが CSV ファイルで許可されます。デフォルト値はfalse
です。--field_delimiter
: データ内の列間の境界を示す文字。タブ区切り文字には\t
とtab
の両方を使用できます。デフォルト値は,
です。--null_marker
: CSV データの NULL 値を表すオプションのカスタム文字列。--skip_leading_rows
: CSV ファイルの先頭でスキップするヘッダーの行数を指定します。デフォルト値は0
です。--quote
: レコードを囲むために使用する引用符。デフォルト値は"
です。引用符を使用しない場合は、空の文字列を使用します。--max_bad_records
: ジョブ全体が失敗する前に許容される不良レコードの最大数を指定する整数。デフォルト値は0
です。--max_bad_records
の値にかかわらず、最大で 5 つの任意のタイプのエラーが返されます。--ignore_unknown_values
: 指定すると、CSV または JSON データで認識されない余分な値が許可され、無視されます。--autodetect
: 指定すると、CSV および JSON データのスキーマ自動検出が有効になります。--destination_kms_key
: テーブルデータの暗号化に使用される Cloud KMS 鍵。
bq --location=location load \ --[no]replace \ --source_format=format \ dataset.table \ path_to_source \ schema
ここで
- location はロケーションです。
--location
フラグは省略可能です。.bigqueryrc ファイルを使用してロケーションのデフォルト値を設定できます。 - format は
CSV
です。 - dataset は既存のデータセットです。
- table は、データの読み込み先のテーブル名です。
- path_to_source は、完全修飾の Cloud Storage URI または URI のカンマ区切りのリストです。ワイルドカードもサポートされます。
- schema は有効なスキーマです。スキーマはローカルの JSON ファイルにすることも、コマンドの一部としてインラインで入力することもできます。また、スキーマ定義を指定する代わりに、
--autodetect
フラグを使用することもできます。
例:
次のコマンドは、gs://mybucket/mydata.csv
からデータを読み込んで mydataset
内の mytable
というテーブルを上書きします。スキーマはスキーマ自動検出を使用して定義されます。
bq load \
--autodetect \
--replace \
--source_format=CSV \
mydataset.mytable \
gs://mybucket/mydata.csv
次のコマンドは、gs://mybucket/mydata.csv
からデータを読み込んで mydataset
内の mytable
というテーブルに追加します。スキーマは、JSON スキーマ ファイル myschema.json
を使用して定義されます。
bq load \
--noreplace \
--source_format=CSV \
mydataset.mytable \
gs://mybucket/mydata.csv \
./myschema.json
API
Cloud Storage のソースデータを参照する
load
ジョブを作成します。(省略可)ジョブリソースの
jobReference
セクションにあるlocation
プロパティでロケーションを指定します。source URIs
プロパティは、完全修飾のgs://bucket/object
の形式にする必要があります。複数の URI をカンマ区切りのリストとして含めることができます。ワイルドカードも使用できます。configuration.load.sourceFormat
プロパティをCSV
に設定して、データ形式を指定します。configuration.load.writeDisposition
プロパティをWRITE_TRUNCATE
またはWRITE_APPEND
に設定して、書き込み設定を指定します。
Go
このサンプルを試す前に、BigQuery クイックスタート: クライアント ライブラリの使用の Go の手順に従って設定を行ってください。詳細については、BigQuery Go API のリファレンス ドキュメントをご覧ください。
Java
このサンプルを試す前に、BigQuery クイックスタート: クライアント ライブラリの使用の Java の設定手順を実施してください。詳細については、BigQuery Java API のリファレンス ドキュメントをご覧ください。
Node.js
このサンプルを試す前に、BigQuery クイックスタート: クライアント ライブラリの使用の Node.js の設定手順を実施してください。詳細については、BigQuery Node.js API のリファレンス ドキュメントをご覧ください。
既存のテーブルの行を置換するには、metadata
パラメータの writeDisposition
値を 'WRITE_TRUNCATE'
に設定します。
このサンプルを試す前に、BigQuery クイックスタート: クライアント ライブラリの使用にある PHP 向けの手順に従って設定を行ってください。詳細については、BigQuery PHP API のリファレンス ドキュメントをご覧ください。
Python
このサンプルを試す前に、BigQuery クイックスタート: クライアント ライブラリの使用の Python の手順に従って設定を行ってください。詳細については、BigQuery Python API のリファレンス ドキュメントをご覧ください。
既存テーブルの行を置換するには、LoadJobConfig.write_disposition プロパティを SourceFormat の定数 WRITE_TRUNCATE
に設定します。
Hive パーティション分割 CSV データの読み込み
BigQuery では、Cloud Storage に保管されている Hive パーティション分割 CSV データを読み取り可能であり、宛先 BigQuery マネージド テーブルの列として Hive パーティショニング列を取り込みます。詳しくは、Cloud Storage からの外部パーティション分割データの読み取りをご覧ください。
CSV データの読み込みの詳細
このセクションでは、BigQuery によりさまざまな CSV のフォーマットのオプションを処理する方法について説明します。
エンコード
BigQuery に読み込む CSV データは UTF-8 でエンコードされている必要があります。CSV ファイルに ISO-8859-1(Latin-1 とも呼ばれます)形式でエンコードされたデータが含まれている場合は、BigQuery でデータを UTF-8 に正しく変換できるよう、エンコードを明示的に指定する必要があります。
エンコードを指定しない場合、または CSV ファイルが UTF-8 でエンコードされていないときに UTF-8 エンコードを指定した場合、BigQuery はデータを UTF-8 に変換しようとします。通常、データは正常に読み込まれますが、バイトごとには期待どおりの結果が得られない場合があります。これを回避するには、--encoding
フラグを使用して、正しいエンコードを指定します。
BigQuery が ASCII 0
文字以外の文字を変換できない場合、BigQuery は文字を標準の Unicode 置換文字 � に変換します。
フィールド区切り文字
CSV ファイル内の区切り文字には、任意の 1 バイト文字を使用できます。ソースファイルが ISO-8859-1 エンコードを使用する場合、任意の文字を区切り文字に使用できます。ソースファイルが UTF-8 エンコードを使用している場合、10 進数の範囲 1~127(U+0001~U+007F)の任意の文字を変更せずに使用できます。この範囲外の ISO-8859-1 文字を区切り文字として挿入すると、BigQuery がそれを適切に解釈します。ただし、マルチバイト文字を区切り文字として使用すると、一部のバイトが誤ってフィールド値の一部として解釈されます。
通常は、タブ、パイプ、カンマなどの標準的な区切り文字を使用することをおすすめします。デフォルトはカンマです。
データ型
Boolean。BigQuery は、ブール値データとして 1 または 0、true または false、t または f、yes または no、y または n(すべて大文字と小文字の区別なし)の任意のペアを解析できます。スキーマ autodetection は、これらのうち 0 と 1 以外を自動的に検出します。
Date。DATE 型の列は YYYY-MM-DD
の形式にする必要があります。
Datetime。DATETIME 型の列は YYYY-MM-DD
HH:MM:SS[.SSSSSS]
の形式にする必要があります。
Time。TIME 型の列は HH:MM:SS[.SSSSSS]
の形式にする必要があります。
Timestamp。BigQuery はさまざまなタイムスタンプ形式に対応しています。タイムスタンプには日付の部分と時刻の部分を含める必要があります。
日付の部分は
YYYY-MM-DD
型またはYYYY/MM/DD
型にできます。タイムスタンプ部分は、
HH:MM[:SS[.SSSSSS]]
型にする必要があります(秒数と 1 秒未満の秒数は省略可能です)。日付と時刻はスペースまたは「T」で区切る必要があります。
必要に応じて、日付と時刻の後に UTC オフセットまたは UTC ゾーン指定子(
Z
)を追加できます。詳細については、タイムゾーンをご覧ください。
有効なタイムスタンプ値の例は次のとおりです。
- 2018-08-19 12:11
- 2018-08-19 12:11:35
- 2018-08-19 12:11:35.22
- 2018/08/19 12:11
- 2018-07-05 12:54:00 UTC
- 2018-08-19 07:11:35.220 -05:00
- 2018-08-19T12:11:35.220Z
スキーマを指定すると、BigQuery はタイムスタンプ値として Unix エポック時間も指定できます。ただし、スキーマの自動検出ではこのケースは検出されず、値は数値型または文字列型として扱われます。
Unix エポック タイムスタンプ値の例:
- 1534680695
- 1.534680695e11
CSV のオプション
BigQuery による CSV データの解析方法を変更するには、Cloud Console、bq
コマンドライン ツール、または API で追加のオプションを指定します。
CSV 形式の詳細については、RFC 4180 をご覧ください。
CSV のオプション | Console のオプション | bq ツールのフラグ |
BigQuery API のプロパティ | 説明 |
---|---|---|---|---|
フィールド区切り文字 | フィールド区切り文字: カンマ、タブ、パイプ、カスタム | -F または --field_delimiter |
fieldDelimiter |
(省略可)CSV ファイル内のフィールド区切り文字。区切り文字には、ISO-8859-1 の任意の 1 バイト文字を使用できます。BigQuery は文字列を ISO-8859-1 エンコードに変換し、エンコードされた文字列の先頭バイトを使用してデータを未加工のバイナリ状態で分割します。また、BigQuery はタブ区切りを示すエスケープ シーケンス「\t」もサポートしています。デフォルト値はカンマ(,)です。 |
ヘッダー行 | スキップするヘッダー行 | --skip_leading_rows |
skipLeadingRows |
(省略可)ソースデータ内のヘッダー行の数を示す整数。 |
許可されている不良レコード数 | 許容されるエラー数 | --max_bad_records |
maxBadRecords |
(オプション)BigQuery でジョブの実行時に無視できる不良レコードの最大数。不良レコードの数がこの値を超えると、ジョブ結果で「無効」エラーが返されます。デフォルト値は 0 で、すべてのレコードが有効である必要があります。 |
改行文字 | 引用符で囲まれた改行を許可する | --allow_quoted_newlines |
allowQuotedNewlines |
(省略可)改行文字を含む引用符で囲まれたデータ セクションを CSV ファイルで許可するかどうかを指定します。デフォルト値は false です。 |
カスタム Null 値 | なし | --null_marker |
nullMarker |
(省略可)CSV ファイル内で null 値を表す文字列を指定します。たとえば、「\N」を指定すると、BigQuery に CSV ファイルが読み込まれるときに「\N」が null 値として解釈されます。デフォルト値は空の文字列です。このプロパティにカスタム値を設定すると、STRING と BYTE を除くすべてのデータ型で、空の文字列がある場合にエラーがスローされます。STRING 列と BYTE 列では、空の文字列は空の値として解釈されます。 |
末尾のオプションの列 | ジャグ行を許可する | --allow_jagged_rows |
allowJaggedRows |
(省略可)末尾のオプションの列が欠落している行を受け入れます。欠損値は null として扱われます。false の場合、末尾の列が欠落しているレコードは不良レコードとして処理され、不良レコードが多すぎる場合はジョブの結果内で無効なエラーが返されます。デフォルト値は false です。これは CSV のみに適用され、他の形式では無視されます。 |
不明な値 | 不明な値を無視 | --ignore_unknown_values |
ignoreUnknownValues |
(省略可)テーブル スキーマで示されていない余分な値を許可するかどうかを指定します。true の場合、余分な値は無視されます。false の場合、余分な列を含むレコードは不良レコードとして処理され、不良レコードが多すぎる場合はジョブの結果内で無効なエラーが返されます。デフォルト値は false です。何が余分な値として扱われるかは、sourceFormat プロパティによって決まります。
|
引用符 | なし | --quote |
quote |
(省略可)CSV ファイル内のデータ セクションを囲む引用符として使用される値。BigQuery は文字列を ISO-8859-1 エンコードに変換し、エンコードされた文字列の先頭バイトを使用してデータを未加工のバイナリ状態で分割します。デフォルト値は二重引用符('"')です。データに引用符で囲まれたセクションが含まれていない場合は、このプロパティの値を空の文字列に設定します。データに引用符で囲まれた改行文字が含まれている場合は、allowQuotedNewlines プロパティの値を true に設定する必要もあります。引用符で囲まれた値の中に特定の引用符を含めるには、その前に引用符を追加します。たとえば、デフォルトの「"」をエスケープするには、「""」を使用します。 |
エンコード | なし | -E または --encoding |
encoding |
(省略可)データの文字エンコード。サポートされている値は UTF-8 と ISO-8859-1 です。デフォルト値は UTF-8 です。BigQuery は、quote プロパティと fieldDelimiter プロパティの値を使用して未加工のバイナリデータを分割してからデータをデコードします。 |