COPY INTO

適用対象:「はい」のチェック マーク Databricks SQL 「はい」のチェック マーク Databricks Runtime

ファイルの場所から Delta テーブルにデータを読み込みます。 これは再試行可能なべき等操作であり、ソースの場所にある既に読み込み済みのファイルはスキップされます。 これは、読み込まれた後でファイルが変更されている場合でも当てはまります。 例については、「COPY INTOを使用した一般的なデータ読み込みパターン」を参照してください。

構文

COPY INTO target_table [ BY POSITION | ( col_name [ , <col_name> ... ] ) ]
  FROM { source_clause |
         ( SELECT expression_list FROM source_clause ) }
  FILEFORMAT = data_source
  [ VALIDATE [ ALL | num_rows ROWS ] ]
  [ FILES = ( file_name [, ...] ) | PATTERN = glob_pattern ]
  [ FORMAT_OPTIONS ( { data_source_reader_option = value } [, ...] ) ]
  [ COPY_OPTIONS ( { copy_option = value } [, ...] ) ]

source_clause
  source [ WITH ( [ CREDENTIAL { credential_name |
                                 (temporary_credential_options) } ]
                  [ ENCRYPTION (encryption_options) ] ) ]

パラメーター

  • target_table

    既存の Delta テーブルを識別します。 target_tableには、時間指定やオプション指定を含めてはなりません。

    テーブル名が delta.`/path/to/table` のような場所の形式で指定されている場合、Unity カタログで、書き込み先の場所へのアクセスを管理できます。 外部の場所に書き込むには、次の方法があります。

    • 場所を外部の場所として定義し、その外部の場所に対する WRITE FILES アクセス許可を取得する。
    • WRITE FILES を使って、指定したストレージ資格情報に対し、場所への書き込み認可を与える COPY INTO delta.`/some/location` WITH (CREDENTIAL <named-credential>) アクセス許可を付与する

    詳細については、「 Unity カタログを使用してクラウド オブジェクト ストレージに接続 する」を参照してください。

  • BY POSITION |( col_name [ , <col_name> ... ] )

    ソース列とターゲット テーブル列を序数位置で照合します。 一致する列の型キャストは自動的に行われます。

    このパラメーターは、ヘッダーなしの CSV ファイル形式でのみサポートされます。 FILEFORMAT = CSV を指定する必要があります。 FORMAT_OPTIONS も ("headers" = "false") に設定する必要があります (既定値は FORMAT_OPTIONS ("headers" = "false"))。

    構文オプション 1: BY POSITION

    • ソース列とターゲット テーブル列を自動的に序数位置で照合します。
      • 既定の名前の照合は、照合には使用されません。
      • ターゲット テーブルの IDENTITY 列と GENERATED 列は、ソース列と照合されるときに無視されます。
      • ソース列の数がフィルター処理されたターゲット テーブル列と等しくない場合、 COPY INTO はエラーを発生させます。

    構文オプション 2: ( col_name [ , <col_name> ... ] )

    • ソース列を、かっこで囲まれコンマで区切られたターゲットテーブルの列名リストを用いて、相対的な序数位置に基づき指定されたターゲットテーブルの列と対応させます。
      • 元のテーブルの列の順序と列名は、照合には使用されません。
      • IDENTITY 列と GENERATED 列は列名リストに指定できません。それ以外の場合、COPY INTO はエラーを発生させます。
      • 指定した列は複製できません。
      • ソース列の数が指定したテーブル列と等しくない場合、 COPY INTO エラーが発生します。
      • 列名リストに指定されていない列の場合、COPY INTO は既定値 (存在する場合) を割り当てます。それ以外の場合、NULL を割り当てます。 列が null 許容でない場合、COPY INTO はエラーを発生させます。

  • source

    データの読み込み元となるファイルの場所。 この場所にあるファイルの形式は FILEFORMAT で指定する必要があります。 場所は URI の形式で提供されています。

    ソースの場所へのアクセスは、次の方法で提供されます。

    • credential_name

      保存場所へのアクセスまたは書き込みに使用される資格情報の名前 (省略可能)。 この資格情報は、ファイルの場所が外部の場所に含まれていない場合にのみ使用します。 「credential_name」を参照してください。

    • インライン一時資格情報。

    • ソースの場所を外部の場所として定義し、Unity カタログを通じて外部の場所に対する READ FILES アクセス許可を取得する。
    • Unity カタログを通じて場所から読み取る認可を与える READ FILES アクセス許可を持つ名前付きストレージ資格情報を使用する。

    パスが、使用するアクセス許可を持つ外部の場所として既に定義されている場合は、インラインまたは名前付き資格情報を指定する必要はありません。 詳細については、 外部の場所の概要 を参照してください。

    注

    ソース ファイルのパスがルート パスである場合は、ファイル パスの末尾にスラッシュ (/) を追加してください。例: s3://my-bucket/。

    指定できる資格情報のオプションは次のとおりです。

    • AZURE_SAS_TOKEN ADLS と Azure Blob Storage の場合
    • AWS_ACCESS_KEY、AWS_SECRET_KEY、および AWS_SESSION_TOKEN: AWS S3 の場合

    指定できる暗号化オプションは次のとおりです。

    • TYPE = 'AWS_SSE_C' および MASTER_KEY: AWS S3 の場合

「一時的な資格情報で COPY INTO を使用してデータを読み込む」を参照してください。

  • SELECT expression_list

    Delta テーブルにコピーする前に、指定された列または式をソース データから選択します。 式には、ウィンドウ操作など、SELECT ステートメントで使用する任意の式を指定できます。 集計式はグローバル集計に対してのみ使用できます。この構文で列に対して GROUP BY を使用することはできません。

  • FILEFORMAT = data_source

    読み込むソース ファイルの形式。 CSV、JSON、AVRO、ORC、PARQUET、TEXT、BINARYFILE のいずれかです。

  • VALIDATE

    適用対象:check marked yes Databricks SQL 「はい」のチェック マーク Databricks Runtime 10.4 LTS 以降

    テーブルに読み込まれるデータは検証されますが、テーブルには書き込まれません。 次のような検証が行われます。

    • データを解析できるかどうか。
    • スキーマがテーブルのものと一致するかどうか、またはスキーマを展開する必要があるかどうか。
    • NULL 値の許容と CHECK 制約がすべて満たされているかどうか。

    既定では、読み込まれるすべてのデータが検証されます。 ROWS のように、VALIDATE 15 ROWS キーワードを使用して、検証する行数を指定できます。 COPY INTO キーワードで 50 未満の数値を使用すると、ROWS ステートメントから、50 行以下のデータのプレビューが返されます。

  • FILES

    読み込むファイル名の一覧。1000 ファイルの制限あり。 PATTERN で指定できません。

  • PATTERN

    ソース ディレクトリから読み込むファイルを識別する glob パターン。 FILES で指定できません。

    パターン 説明
    ? 任意の 1 文字と一致します
    * 0文字以上の任意の文字列と一致します
    [abc] 文字セット {a, b, c} の 1 文字と一致します。
    [a-z] 文字範囲 {a…z} の 1 文字と一致します。
    [^a] 文字セットまたは範囲 {a} からのものではない 1 文字と一致します。 ^ 文字は左角かっこのすぐ右側に表示されることに注意してください。
    {ab,cd} 文字列セット {ab, cd} の文字列と一致します。
    {ab,c{de, fh}} 文字列セット {ab, cde, cfh} の文字列と一致します。

  • FORMAT_OPTIONS

    指定した形式について Apache Spark データ ソース リーダーに渡されるオプション。 各ファイル形式については、「形式のオプション」を参照してください。

  • COPY_OPTIONS

    COPY INTO コマンドの操作を制御するオプション。

    • force: ブール値、既定値は false。 trueに設定すると、べき等性が無効になり、ファイルは以前に読み込まれたかどうかに関係なく読み込まれます。
    • mergeSchema: ブール値、既定値は false。 true に設定すると、受信データに応じてスキーマを展開できます。

COPY INTO を同時に呼び出す

COPY INTO は、同じテーブルに対する同時呼び出しをサポートします。 が異なる入力ファイルのセットに対して同時に呼び出される限り、各呼び出しは最終的に成功する必要があります。さもなければ、トランザクションの競合が発生します。 COPY INTO パフォーマンスを向上させるために同時に呼び出すことはできません。通常、複数のファイルを含む 1 つの COPY INTO コマンドは、それぞれ 1 つのファイルで同時実行 COPY INTO コマンドを実行するよりも優れたパフォーマンスを発揮します。 COPY INTO は、次の場合に同時に呼び出すことができます。

  • 複数のデータ プロデューサーは、簡単に調整する方法がなく、1 回の呼び出しを行うことはできません。
  • 非常に大きなディレクトリをサブディレクトリによって取り込むことができる場合。 非常に多くのファイルを含むディレクトリを取り込む場合、Databricks では可能な限り 自動ローダー を使用することをお勧めします。

ファイル メタデータへのアクセス

ファイル ベースのデータ ソースのメタデータにアクセスする方法については、「ファイル メタデータ列」を参照してください。

フォーマットオプション

各ファイル形式 (JSON、CSV、XML、Parquet、Avro、テキスト、ORC、バイナリ) に固有のオプションについては、「 DataFrameReader オプション」を参照してください。

  • Last updated on