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

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

COPY INTOを使用するための多くのオプションがあります。また、これらのパターンと組み合わせて 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 データを読み込む

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

COPY INTO my_json_data
  FROM 's3://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 's3://my-bucket/jsonData'
  FILEFORMAT = JSON
  FILES = ('f1.json', 'f2.json', 'f3.json', 'f4.json', 'f5.json')

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

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

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

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

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

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

-- The example below loads CSV files without headers in S3 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 's3://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_OPTIONSfalseできます。

CSV スキーマの推論と進化

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

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

CREATE TABLE IF NOT EXISTS my_pipe_data;

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

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

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

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 以降で使用できます。