`COPY INTO` を使用した一般的なデータ読み込みパターン

COPY INTO を使用してファイルソースから Delta Lake にデータを読み込むための一般的なパターンについて説明します。

COPY INTOを使用するための多くのオプションがあります。

すべてのオプションの完全なリファレンスについては、 COPY INTO を参照してください。

`COPY INTO` のターゲットテーブルの作成

COPY INTO 既存の Delta テーブルをターゲットにする必要があります。

CREATE TABLE IF NOT EXISTS my_table
[(col_1 col_1_type, col_2 col_2_type, ...)]
[COMMENT <table-description>]
[TBLPROPERTIES (<table-properties>)];

Databricks Runtime 11.3 LTS 以降では、スキーマの進化をサポートする形式では、これらのテーブルのスキーマの設定はオプションです。詳細については、COPY INTO を使用したスキーマの推論と進化を参照してください。

`COPY INTO` を使用して JSON データを読み込む

次の例では、Google Cloud Storage(GCS)の 5 つのファイルから JSON データを Delta テーブル my_json_dataに読み込みます。このテーブルは、 COPY INTO を実行する前に作成する必要があります。いずれかのファイルから既にデータが読み込まれている場合、そのファイルのデータは再読み込みされません。

COPY INTO my_json_data
  FROM 'gs://my-bucket/jsonData'
  FILEFORMAT = JSON
  FILES = ('f1.json', 'f2.json', 'f3.json', 'f4.json', 'f5.json')

-- The second execution will not copy any data since the first command already loaded the data
COPY INTO my_json_data
  FROM 'gs://my-bucket/jsonData'
  FILEFORMAT = JSON
  FILES = ('f1.json', 'f2.json', 'f3.json', 'f4.json', 'f5.json')

`COPY INTO` を使用した Avro データの読み込み

次の例では、 SELECT ステートメントの一部として追加の SQL 式を使用して GCS に Avro データをロードします。

COPY INTO my_delta_table
  FROM (SELECT to_date(dt) dt, event as measurement, quantity::double
          FROM 'gs://my-bucket/avroData')
  FILEFORMAT = AVRO

`COPY INTO` を使用してCSVファイルをロードする

次の例では、 gs://bucket/base/path/folder1 の下の GCS から Delta テーブルに CSV ファイルを読み込みます。

COPY INTO target_table
  FROM (SELECT key, index, textData, 'constant_value'
          FROM 'gs://bucket/base/path')
  FILEFORMAT = CSV
  PATTERN = 'folder1/file_[a-g].csv'
  FORMAT_OPTIONS('header' = 'true')

-- The example below loads CSV files without headers in GCS using COPY INTO.
-- By casting the data and renaming the columns, you can put the data in the schema you want
COPY INTO target_table
  FROM (SELECT _c0::bigint key, _c1::int index, _c2 textData
        FROM 'gs://bucket/base/path')
  FILEFORMAT = CSV
  PATTERN = 'folder1/file_[a-g].csv'

`COPY INTO` を使用したスキーマの推論と進化

このセクションでは、 COPY INTOを使用した一般的なスキーマ推論および進化設定の例を示します。

構文

COPY INTO my_table
FROM '/path/to/files'
FILEFORMAT = <format>
FORMAT_OPTIONS ('inferSchema' = 'true', `mergeSchema` = `true`)
COPY_OPTIONS ('mergeSchema' = 'true');

次の FORMAT_OPTIONS を使用して、入力スキーマを自動的に推論できます COPY INTO。

inferSchema: 解析されたレコードのデータ型を推測するか、すべての列が StringTypeであると仮定するか。
mergeSchema: 複数のソースファイル間でスキーマを推論し、各ソースファイルのスキーマをマージするかどうか。

ソースファイルのスキーマが同じ場合、 Databricks FORMAT_OPTIONS (false) の mergeSchema にデフォルト設定を使用することをお勧めします。

ターゲットスキーマを COPY INTOで進化させるために、次のCOPY_OPTIONSを使用できます。

mergeSchema: 入力スキーマに基づいてターゲット Delta テーブルのスキーマを進化させるかどうか。

入力スキーマとターゲットスキーマが同じ場合は、mergeSchemaCOPY_OPTIONSでfalseできます。

CSV スキーマの推論と進化

次の例では、 my_pipe_data というスキーマレス Delta テーブルを作成し、ヘッダーを使用してパイプ区切りの CSV を読み込みます。

mergeSchema は、入力ファイルにヘッダーまたは区切り文字の違いがある可能性があるため、FORMAT_OPTIONSでtrueされます。

CREATE TABLE IF NOT EXISTS my_pipe_data;

COPY INTO my_pipe_data
  FROM 'gs://my-bucket/pipeData'
  FILEFORMAT = CSV
  FORMAT_OPTIONS ('mergeSchema' = 'true',
                  'delimiter' = '|',
                  'header' = 'true')
  COPY_OPTIONS ('mergeSchema' = 'true');

データのロード中に破損したファイルを無視する

読み込み中のデータが破損の問題で読み取れない場合は、FORMAT_OPTIONSで ignoreCorruptFiles を true に設定することで、それらのファイルをスキップできます。

COPY INTO コマンドの結果は、num_skipped_corrupt_files 列の破損が原因でスキップされたファイルの数を返します。このメトリクスは、 Delta テーブルでDESCRIBE HISTORYを実行した後、numSkippedCorruptFilesの下のoperationMetrics列にも表示されます。

破損したファイルは COPY INTOによって追跡されないため、破損が修正された場合は、後続の実行で再読み込みできます。 VALIDATEモードでCOPY INTOを実行すると、どのファイルが破損しているかを確認できます。

COPY INTO my_table
FROM '/path/to/files'
FILEFORMAT = <format>
[VALIDATE ALL]
FORMAT_OPTIONS ('ignoreCorruptFiles' = 'true')

注：

ignoreCorruptFiles は、Databricks Runtime 11.3 LTS 以降で使用できます。

COPY INTO を使用した一般的なデータ読み込みパターン

COPY INTO のターゲットテーブルの作成

COPY INTO を使用して JSON データを読み込む

COPY INTO を使用した Avro データの読み込み

COPY INTO を使用してCSVファイルをロードする

COPY INTO を使用したスキーマの推論と進化

構文