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 アクセス許可を取得する。
  • COPY INTO delta.`/some/location` WITH (CREDENTIAL <named-credential>) を使用して、場所への書き込み認可を与える、名前付きストレージの資格情報に対する WRITE FILES アクセス許可を取得する。

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

• 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 アクセス許可を持つ名前付きストレージ資格情報を使用する。

  パスが外部の場所として既に定義されており、使用するアクセス許可がある場合は、インラインまたは名前付き資格情報を指定する必要はありません。 詳細については、「クラウド ストレージを Azure Databricks に接続するための外部の場所を作成する」を参照してください。

  Note

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

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

  • AZURE_SAS_TOKEN: ADLS Gen2 および 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

  適用対象: Databricks SQL Databricks Runtime 10.4 LTS 以降

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

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

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

• FILES

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

• PATTERN

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

  Pattern	説明
  ?	任意の 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個別の入力ファイルのセットに対して同時に呼び出される限り、各呼び出しは最終的に成功し、それ以外の場合はトランザクションの競合が発生します。 COPY INTO パフォーマンスを向上させるために同時に呼び出すことはできません。通常、複数のファイルを含む 1 つの COPY INTO コマンドは、それぞれ 1 つのファイルで同時実行 COPY INTO コマンドを実行するよりも優れたパフォーマンスを発揮します。 COPY INTO は、次の場合に同時に呼び出すことができます。

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

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

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

形式のオプション

• 共通オプション
• JSON オプション
• CSV オプション
• XML オプション
• PARQUET オプション
• AVRO オプション
• BINARYFILE オプション
• TEXT オプション
• ORC オプション

共通オプション

次のオプションは、すべてのファイル形式に適用されます。

JSON のオプション

CSV のオプション

XML オプション

PARQUET オプション

AVRO のオプション

BINARYFILE のオプション

バイナリ ファイルには、追加の構成オプションはありません。

TEXT のオプション

ORC のオプション

関連記事

• 資格情報
• DELETE
• INSERT
• MERGE
• PARTITION
• query
• UPDATE
• COPY INTO を使用してデータを読み込む