COPY INTO (Transact-SQL)

適用対象: Azure Synapse Analytics

この記事では、Azure Synapse Analytics で COPY ステートメントを使用して、外部ストレージ アカウントからの読み込みを行う方法について説明します。 COPY ステートメントを使用すると、Azure Synapse Analytics への高スループットのデータ インジェストで最大の柔軟性が確保されます。

注意

Microsoft Fabric のウェアハウスの場合は、「COPY INTO」にアクセスしてください。

次の機能に COPY を使用します。

• データ ウェアハウスに対する厳格な CONTROL アクセス許可を使用せずに、低い特権のユーザーを使用して読み込むことができます。
• 他のデータベース オブジェクトを作成することなく、1 つの T-SQL ステートメントを実行できます
• 区切り記号 (文字列、フィールド、行) が文字列で区切られた "列" 内でエスケープされている CSV ファイルを適切に解析して読み込むことができます
• Shared Access Signature (SAS) を使用してストレージ アカウント キーを公開しなくても、より洗練されたアクセス許可モデルを指定できます。
• ERRORFILE の場所 (REJECTED_ROW_LOCATION) として異なるストレージ アカウントを使用できます。
• ターゲット列ごとに既定値をカスタマイズし、特定のターゲット列に読み込むソース データ フィールドを指定できます。
• CSV ファイルのカスタム行ターミネータ、フィールド ターミネータ、フィールド引用符を指定する
• CSV ファイルで SQL Server の日付形式を使用する
• 保存場所のパスにワイルドカードや複数のファイルを指定できます。
• スキーマの自動検出を使用すると、ソース データを定義してターゲット テーブルにマッピングするプロセスを簡略化できます
• 自動テーブル作成プロセスを使用すると、テーブルが自動的に作成されます。このプロセスは、自動スキーマ検出と共に機能します
• 他のツールを使用してデータを前処理することなく、マップやリストなどの Parquet ファイルから文字列列に複雑なデータ型を直接読み込む

Note

Parquet ファイルから複雑なデータ型を読み込むには、 AUTO_CREATE_TABLEを使用してテーブルの自動作成を有効にする必要があります。

COPY ステートメントを使用した包括的な例とクイックスタートについては、次のドキュメントを参照してください。

• クイック スタート: COPY ステートメントを使用してデータを一括読み込みする
• クイック スタート: COPY ステートメントとそのサポートされている認証方法の使用例
• クイック スタート: 機能が豊富な Synapse Studio UI を使用して COPY ステートメントを作成する

Note

Microsoft Entra ID の、旧称は Azure Active Directory（Azure AD）です。

構文

COPY INTO [ schema. ] table_name
[ (Column_list) ]
FROM '<external_location>' [ , ...n ]
WITH
 (
 [ FILE_TYPE = { 'CSV' | 'PARQUET' | 'ORC' } ]
 [ , FILE_FORMAT = EXTERNAL FILE FORMAT OBJECT ]
 [ , CREDENTIAL = (AZURE CREDENTIAL) ]
 [ , ERRORFILE = ' [ http(s)://storageaccount/container ] /errorfile_directory [ / ] ] '
 [ , ERRORFILE_CREDENTIAL = (AZURE CREDENTIAL) ]
 [ , MAXERRORS = max_errors ]
 [ , COMPRESSION = { 'Gzip' | 'DefaultCodec' | 'Snappy' } ]
 [ , FIELDQUOTE = 'string_delimiter' ]
 [ , FIELDTERMINATOR =  'field_terminator' ]
 [ , ROWTERMINATOR = 'row_terminator' ]
 [ , FIRSTROW = first_row ]
 [ , DATEFORMAT = 'date_format' ]
 [ , ENCODING = { 'UTF8' | 'UTF16' } ]
 [ , IDENTITY_INSERT = { 'ON' | 'OFF' } ]
 [ , AUTO_CREATE_TABLE = { 'ON' | 'OFF' } ]
)

引数

schema_name

操作を実行するユーザーの既定のスキーマが、指定したテーブルのスキーマと同じ場合は省略可能です。 schemaが指定されておらず、COPY 操作を実行するユーザーの既定のスキーマが指定されたテーブルのスキーマと異なる場合、COPY は取り消され、エラー メッセージが返されます。

table_name

データの COPY 先のテーブルの名前。 ターゲット テーブルは、一時テーブルまたはパーマネント テーブルであり、データベースに既に存在している必要があります。 自動スキーマ検出モードの場合は、列リストを指定しないでください。

(column_list)

データ読み込み時のソース データ フィールドからターゲット テーブル列へのマッピングに使用される 1 つ以上の列のリスト。このリストは省略可能です。

AUTO_CREATE_TABLE = 'ON' の場合は、column_list を指定しないでください。

column_list はかっこで囲み、コンマで区切る必要があります。 列リストの形式は次のとおりです。

[(Column_name [default Default_value] [Field_number] [,...n])]

• Column_name - ターゲット テーブルの列の名前。
• Default_value - 入力ファイルのすべての NULL 値がこの既定値に置き換えられます。 既定値はすべてのファイル形式に適用されます。 COPY によって入力ファイルから NULL の読み込みが試行されるのは、列リストに省略されている列がある場合、または入力ファイルに空フィールドがある場合です。 既定値の前にキーワード "default" を指定します
• Field_number - ターゲット列にマップされる入力ファイルのフィールド番号。
• フィールドのインデックスは 1 から開始されます。

列リストが指定されていない場合、COPY では、ソースとターゲットの順序に基づいて列がマップされます。入力フィールド 1 はターゲット列 1 に、フィールド 2 は列 2 に、以降同様にマップされます。

外部の場所

データを含むファイルがステージングされる場所です。 現在、Azure Data Lake Storage (ADLS) Gen2 と Azure Blob Storage がサポートされています。

• Blob Storage の "外部の場所": https://<account\>.blob.core.windows.net/<container\>/<path\>
• ADLS Gen2 の "外部の場所": https://<account\>.dfs.core.windows.net/<container\>/<path\>

Note

.blob エンドポイントは ADLS Gen2 にも使用でき、現在最高のパフォーマンスを実現しています。 お使いの認証方法で .dfs が必要ない場合、.blob エンドポイントを使用します。

• Account - ストレージ アカウント名

• Container - BLOB コンテナー名

• Path - データのフォルダーまたはファイルのパス。 場所はコンテナーから始まります。 フォルダーが指定されている場合は、そのフォルダーとそのサブフォルダーにあるすべてのファイルが、COPY によって取得されます。 隠しフォルダーは無視され、アンダースコア (_) またはピリオド (.) で始まるファイルは返されません (パスで明示的に指定されている場合を除く)。 この動作は、ワイルドカードを使ってパスを指定した場合も同じです。

パスにはワイルドカードを含めることができます

• ワイルドカード パス名の一致では、大文字と小文字が区別されます
• ワイルドカードをエスケープするには、円記号 (\) を使用します
• ワイルドカードの展開は再帰的に適用されます。 たとえば、次のようにパスを指定すると、Customer1 (Customer1 のサブディレクトリを含む) の下にある CSV ファイルすべてが読み込まれます: Account/Container/Customer1/*.csv

注意

最適なパフォーマンスを得るには、多くのファイルに展開されるワイルドカードは指定しないでください。 可能な場合は、ワイルドカードではなく、複数のファイルの場所をリストを使って指定します。

複数のファイルの場所を指定するには、次のようなコンマ区切りのリストを使用して、同じストレージ アカウントおよびコンテナーから指定する必要があります。

• https://<account>.blob.core.windows.net/<container\>/<path\>, https://<account\>.blob.core.windows.net/<container\>/<path\>

FILE_TYPE = { 'CSV' | 'PARQUET' | 'ORC' }

FILE_TYPE により、外部データの形式が指定されます。

• CSV: RFC 4180 標準に準拠しているコンマ区切り値ファイルを指定します。
• PARQUET: Parquet 形式を指定します。
• ORC: 最適化行多桁式 (ORC) 形式を指定します。

注意

PolyBase のファイルの種類である "区切りテキスト" は "CSV" ファイル形式に置き換えられています。このファイル形式で既定のコンマ区切り記号を構成するには、FIELDTERMINATOR パラメーターを使用します。

FILE_FORMAT = external_file_format_name

FILE_FORMAT は Parquet ファイルおよび ORC ファイルにのみ適用され、外部データのファイルの種類と圧縮方法を格納する外部ファイル形式オブジェクトの名前を指定します。 外部ファイル形式を作成するには、CREATE EXTERNAL FILE FORMAT を使用します。

CREDENTIAL (IDENTITY = '', SECRET = '')

CREDENTIAL は、外部ストレージ アカウントにアクセスするための認証メカニズムを指定します。 認証方法を次に示します。

	CSV	Parquet	ORC
Azure Blob Storage	SAS/MSI/サービス プリンシパル/キー/AAD	SAS/キー	SAS/キー
Azure Data Lake Gen2	SAS/MSI/サービス プリンシパル/キー/AAD	SAS (blob 1 )/MSI (dfs 2 )/SERVICE PRINCIPAL/KEY/AAD	SAS (blob 1 )/MSI (dfs 2 )/SERVICE PRINCIPAL/KEY/AAD

1:この認証方法には、お使いの外部のロケーション パスに .blob エンドポイント ( .blob.core.windows.net) が必要です。

2:この認証方法には、お使いの外部のロケーション パスに .dfs エンドポイント ( .dfs.core.windows.net) が必要です。

Note

• Microsoft Entra ID またはパブリック ストレージ アカウントを使用して認証する場合、CREDENTIAL を指定する必要はありません。
• ストレージ アカウントが VNet に関連付けられている場合は、マネージド ID を使用して認証する必要があります。

• Shared Access Signatures (SAS) を使用した認証

  • IDENTITY: "Shared Access Signature" の値が含まれている定数
  • SECRET: 共有アクセス署名 ストレージ アカウント内のリソースへの委任されたアクセスを提供します。
  • 最低限必要な権限: READ および LIST

• サービス プリンシパルを使用した認証

  • IDENTITY: <ClientID>@<OAuth_2.0_Token_EndPoint>
  • SECRET: Microsoft Entra アプリケーション サービス プリンシパル キー
  • 最低限必要な RBAC ロール: ストレージ BLOB データ共同作成者、ストレージ BLOB データ所有者、またはストレージ BLOB データ閲覧者

• ストレージ アカウント キーを使用した認証

  • IDENTITY: "ストレージ アカウント キー" の値が含まれている定数
  • SECRET: ストレージ アカウント キー

• マネージド ID (VNet サービス エンドポイント) を使用した認証

  • IDENTITY: "マネージド ID" の値が含まれている定数
  • 必要な最小 RBAC ロール: Azure の Microsoft Entra 登録済み logical サーバーのストレージ BLOB データ共同作成者またはストレージ BLOB データ所有者。 Synapse ワークスペースに関連付けられていない専用 SQL プール (旧称 SQL DW) を使用する場合、この RBAC ロールは必要ありませんが、マネージド ID には、ソース ファイルへの読み取りアクセスを有効にするために、ターゲット オブジェクトに対するアクセス制御リスト (ACL) アクセス許可が必要です

• Microsoft Entra ユーザーによる認証

  • CREDENTIAL は必要ありません
  • 最低限必要な RBAC ロール: Microsoft Entra ユーザーのストレージ BLOB データ共同作成者またはストレージ BLOB データ所有者

ERRORFILE = Directory Location

ERRORFILE は CSV にのみ適用されます。 COPY ステートメント内でディレクトリを指定します。拒否された行と該当するエラー ファイルがそこに書き込まれます。 ストレージ アカウントからの完全なパスを指定することも、コンテナーを基準とした相対パスを指定することもできます。 指定したパスが存在しない場合は、自動的に作成されます。 "_rejectedrows" という名前で子ディレクトリが作成されます。 "_" 文字があることで、場所パラメーターで明示的に指定されない限り、他のデータ処理ではこのディレクトリがエスケープされます。

Note

相対パスが ERRORFILE に渡されると、パスは external_location で指定されたコンテナー パスに対する相対パスになります。

このディレクトリ内には、YearMonthDay -HourMinuteSecond (例: 20180330-173205) のロード サブミッション時間に基づいて作成されたフォルダーがあります。 このフォルダーには、理由 (エラー) ファイルとデータ (行) ファイルの 2 種類のファイルが書き込まれ、それぞれ queryID、distributionID、ファイル GUID が事前に追加されています。 データと理由が別々のファイル内にあり、対応するファイルはプレフィックスが一致しています。

ERRORFILE でストレージ アカウントの完全なパスが定義されている場合、そのストレージへの接続には ERRORFILE_CREDENTIAL が使用されます。 それ以外の場合は、CREDENTIAL に指定された値が使用されます。 ソース データに使用されるのと同じ資格情報が ERRORFILE に使用されている場合、ERRORFILE_CREDENTIALに適用される制限も適用されます

ERRORFILE_CREDENTIAL = (IDENTITY= '', SECRET = '')

ERRORFILE_CREDENTIAL は、CSV ファイルにのみ適用されます。 サポートされているデータ ソースと認証方法は次のとおりです。

• Azure Blob Storage - SAS/サービス プリンシパル/AAD

• Azure Data Lake Gen2 - SAS/MSI/サービス プリンシパル/AAD

• Shared Access Signatures (SAS) を使用した認証

  • IDENTITY: "Shared Access Signature" の値が含まれている定数
  • SECRET: 共有アクセス署名 ストレージ アカウント内のリソースへの委任されたアクセスを提供します。
  • 最低限必要な権限: READ、LIST、WRITE、CREATE、DELETE

• サービス プリンシパルを使用した認証

  • IDENTITY: <ClientID>@<OAuth_2.0_Token_EndPoint>
  • SECRET: Microsoft Entra アプリケーション サービス プリンシパル キー
  • 最低限必要な RBAC ロール: ストレージ BLOB データ共同作成者またはストレージ BLOB データ所有者

注意

OAuth 2.0 トークン エンドポイント V1 を使用してください

• マネージド ID (VNet サービス エンドポイント) を使用した認証

  • IDENTITY: "マネージド ID" の値が含まれている定数
  • 最低限必要な RBAC ロール: Microsoft Entra 登録済み SQL Database サーバーのストレージ BLOB データ共同作成者またはストレージ BLOB データ所有者

• Microsoft Entra ユーザーによる認証

  • CREDENTIAL は必要ありません
  • 最低限必要な RBAC ロール: Microsoft Entra ユーザーのストレージ BLOB データ共同作成者またはストレージ BLOB データ所有者

ERRORFILE_CREDENTIALでのストレージ アカウント キーの使用はサポートされていません。

Note

ご自身の ERRORFILE に同じストレージ アカウントを使用し、コンテナーのルートを基準とした ERRORFILE パスを指定している場合は、ERROR_CREDENTIAL を指定する必要はありません。

MAXERRORS = max_errors

MAXERRORS は、COPY 操作が失敗するまでのロードで許可される拒否行の最大数を指定します。 COPY 操作でインポートできない行は無視され、それぞれ 1 つのエラーとしてカウントされます。 max_errors が指定されていない場合、既定値は 0 です。

MAXERRORS をAUTO_CREATE_TABLEと共に使用することはできません。

FILE_TYPEが 'PARQUET' の場合、データ型変換エラー (Parquet バイナリから SQL 整数など) によって引き起こされる例外は引き続き COPY INTO に失敗し、MAXERRORSを無視します。

COMPRESSION = { 'DefaultCodec ' | 'Snappy' | 'GZIP' | 'NONE'}

COMPRESSION は省略可能で、外部データのデータ圧縮方法を指定します。

• CSV は GZIP をサポートしています
• Parquet は GZIP および Snappy をサポートしています
• ORC は DefaultCodec および Snappy をサポートしています。
• Zlib は ORC の既定の圧縮です

このパラメーターが指定されていない場合、COPY コマンドでは、ファイル名拡張子に基づいて圧縮の種類が自動検出されます。

• .gz - GZIP
• .snappy - Snappy
• .deflate - DefaultCodec (Parquet および ORC のみ)

COPY コマンドでは、正常に動作するために gzip ファイルに末尾のガベージが含まれていない必要があります。 gzip 形式では、ファイルの前、間、または後に追加情報を追加せずに、有効なメンバーで構成することが厳密に必要です。 末尾に gzip 以外のデータが存在するなど、この形式から逸脱すると、COPY コマンドが失敗します。 COPY がこれらのファイルを正常に処理できるように、gzip ファイルの末尾に末尾のガベージがないことを確認してください。

FIELDQUOTE = 'field_quote'

FIELDQUOTE は CSV に適用され、CSV ファイルで引用符文字 (文字列の区切り記号) として使用される 1 バイト文字を指定します。 指定されていない場合は、RFC 4180 標準の定義に従って引用符文字 (") が引用符文字として使用されます。 FIELDQUOTE では 16 進表記もサポートされています。 拡張 ASCII 文字とマルチバイト文字は、FIELDQUOTE の UTF-8 ではサポートされていません。

Note

FIELDQUOTE 文字は、2 バイト FIELDQUOTE (区切り記号) が存在する文字列型の列ではエスケープされます。

FIELDTERMINATOR = 'field_terminator'

FIELDTERMINATOR は CSV にのみ適用されます。 CSV ファイルで使用されるフィールド ターミネータを指定します。 フィールド ターミネータは、16 進数表記を使用して指定できます。 フィールド ターミネータにはマルチ文字を使用できます。 既定のフィールド ターミネータは (,) です。 拡張 ASCII 文字とマルチバイト文字は、FIELDTERMINATOR の UTF-8 ではサポートされていません。

ROW TERMINATOR = 'row_terminator'

ROW TERMINATOR は CSV にのみ適用されます。 CSV ファイルで使用される行ターミネータを指定します。 行ターミネータは、16 進数表記を使用して指定できます。 行ターミネータにはマルチ文字を使用できます。 既定では、行ターミネータは \r\n です。

COPY コマンドでは、\n (改行) を指定すると、その前に \r 文字が付けられ、\r\n になります。 \n 文字のみを指定するには、16 進数表記 (0x0A) を使用します。 マルチ文字の行ターミネータを 16 進数で指定する場合は、各文字の間で 0x を指定しないでください。

拡張 ASCII 文字とマルチバイト文字は、ROW TERMINATOR の UTF-8 ではサポートされていません。

FIRSTROW = First_row_int

FIRSTROW は CSV に適用され、COPY コマンドに対して、すべてのファイルで最初に読み取られる行番号を指定します。 値は 1 から始まり、これが既定値です。 2 に設定すると、データが読み込まれるときに、すべてのファイルの最初の行 (ヘッダー行) がスキップされます。 行は、行ターミネータの存在に基づいてスキップされます。

DATEFORMAT = { 'mdy' | 'dmy' | 'ymd' | 'ydm' | 'myd' | 'dym' }

DATEFORMAT は CSV にのみ適用され、SQL Server 日付形式に対する日付の日付形式のマッピングを指定します。 Transact-SQL の日付と時刻のデータ型および関数の概要については、「日付と時刻のデータ型および関数 (Transact-SQL)」を参照してください。 COPY コマンド内の DATEFORMAT は、セッション レベルで構成された DATEFORMAT よりも優先されます。

ENCODING = 'UTF8' | 'UTF16'

ENCODING は CSV にのみ適用されます。 既定値は UTF8 です。 COPY コマンドによって読み込まれたファイルのデータ エンコード標準を指定します。

IDENTITY_INSERT = 'ON' | 'OFF'

IDENTITY_INSERT は、インポートしたデータ ファイルの ID 値 (複数可) を ID 列に使用するかどうかを指定します。 IDENTITY_INSERT が OFF (既定値) の場合、この列の ID 値は検証されますが、インポートされません。 テーブル作成時に指定されたシード値と増分値に基づいて、一意の値が Azure Synapse Analytics によって自動的に割り当てられます。 COPY コマンドによる次の動作に注意してください。

• IDENTITY_INSERTが OFF で、テーブルに ID 列がある場合
  • 入力フィールドを ID 列にマップしない列リストを指定する必要があります。
• IDENTITY_INSERTが ON で、テーブルに ID 列がある場合
  • 列リストが渡された場合、入力フィールドを ID 列にマップする必要があります。
• 列リストの IDENTITY COLUMN に対して既定値がサポートされない。
• IDENTITY_INSERT は一度に 1 つのテーブルに対してのみ設定できる。

AUTO_CREATE_TABLE = { 'ON' | 'OFF' }

AUTO_CREATE_TABLE では、自動スキーマ検出と共に使用して、テーブルを自動的に作成できるようにするかどうかを指定します。 Parquet ファイルでのみ使用できます。

• ON: テーブルの自動作成を有効にします。 COPY INTO プロセスでは、読み込むファイルの構造を検出することで、新しいテーブルが自動的に作成されます。 既存のテーブルと共に使って、Parquet ファイルの自動スキーマ検出を利用することもできます。
• OFF: テーブルの自動作成が有効ではありません。 既定値。

注意

自動テーブル作成は自動スキーマ検出と共に機能します。 自動テーブル作成は既定では有効になりません。

COPY INTO と AUTO_CREATE_TABLE = 'ON' を使って Parquet ファイルからハッシュ分散テーブルへの読み込みは行わないでください。

COPY INTO を使用して Parquet ファイルをハッシュ分散テーブルに読み込む場合は、ラウンド ロビン ステージング テーブルに読み込んだ後、そのテーブルからの INSERT ... SELECT によって対象のハッシュ分散テーブルに読み込みます。

アクセス許可

COPY コマンドを実行するユーザーには次の権限が必要です。

• ADMINISTER DATABASE BULK OPERATIONS
• INSERT

INSERT 権限および ADMINISTER BULK OPERATIONS 権限が必要です。 Azure Synapse Analytics では、INSERT および ADMINISTER DATABASE BULK OPERATIONS 権限が必要です。

さらに、COPY コマンドを実行するユーザーが新しいテーブルを生成してデータを読み込む場合は、CREATE TABLE および ALTER ON SCHEMA 権限が必要です。

たとえば、mike@contoso.com が COPY を使用して HR スキーマに新しいテーブルを作成し、Parquet ファイルからデータを挿入できるようにするには、次の Transact-SQL サンプルを使用します。

GRANT ADMINISTER DATABASE BULK OPERATIONS to [mike@contoso.com];
GRANT INSERT to [mike@contoso.com];

GRANT CREATE TABLE to [mike@contoso.com];
GRANT ALTER on SCHEMA::HR to [mike@contoso.com];

解説

COPY ステートメントは、行データおよびコマンド パラメーターに対して UTF-8 および UTF-16 の有効な文字のみを受け入れます。 無効な文字を使用するソース ファイルまたはパラメーター (ROW TERMINATOR や FIELD TERMINATOR など) は、COPY ステートメントによって正しく解釈されない可能性があり、データの破損やその他の失敗などの予期しない結果が発生する可能性があります。 COPY ステートメントを呼び出す前に、ソース ファイルとパラメーターが UTF-8 または UTF-16 に準拠していることを確認してください。

例

A. パブリック ストレージ アカウントから読み込む

次の例は COPY コマンドの最も単純な形式で、パブリック ストレージ アカウントからデータを読み込みます。 この例では、COPY ステートメントの既定値は、行項目 csv ファイルの形式と一致しています。

COPY INTO dbo.[lineitem]
FROM 'https://unsecureaccount.blob.core.windows.net/customerdatasets/folder1/lineitem.csv'
WITH (FIELDTERMINATOR = '|')

COPY コマンドの既定値を次に示します。

• DATEFORMAT = Session DATEFORMAT

• MAXERRORS = 0

• COMPRESSION の既定値は圧縮解除です

• FIELDQUOTE = '"'

• FIELDTERMINATOR = ','

• ROWTERMINATOR = '\n'

重要

COPY では、\n は内部的には \r\n として扱われます。 詳細については、ROWTERMINATOR セクションを参照してください。

• FIRSTROW = 1

• ENCODING = 'UTF8'

• FILE_TYPE = 'CSV'

• IDENTITY_INSERT = 'OFF'

B. Shared Access Signature (SAS) を介して認証を読み込む

次の例では、UNIX 出力などのように、改行を行ターミネータとして使用するファイルを読み込みます。 また、この例では SAS キーを使って Azure Blob Storage に対する認証を行います。

COPY INTO test_1
FROM 'https://myaccount.blob.core.windows.net/myblobcontainer/folder1/'
WITH (
    FILE_TYPE = 'CSV',
    CREDENTIAL=(IDENTITY= 'Shared Access Signature', SECRET='<Your_SAS_Token>'),
    --CREDENTIAL should look something like this:
    --CREDENTIAL=(IDENTITY= 'Shared Access Signature', SECRET='?sv=2018-03-28&ss=bfqt&srt=sco&sp=rl&st=2016-10-17T20%3A14%3A55Z&se=2021-10-18T20%3A19%3A00Z&sig=IEoOdmeYnE9%2FKiJDSHFSYsz4AkNa%2F%2BTx61FuQ%2FfKHefqoBE%3D'),
    FIELDQUOTE = '"',
    FIELDTERMINATOR=';',
    ROWTERMINATOR='0X0A',
    ENCODING = 'UTF8',
    DATEFORMAT = 'ymd',
    MAXERRORS = 10,
    ERRORFILE = '/errorsfolder',--path starting from the storage container
    IDENTITY_INSERT = 'ON'
)

C. ストレージ アカウント キーを介して認証を行い、既定値が含まれる列リストを使用して読み込む

この例では、既定値が含まれる列リストを指定してファイルを読み込みます。

--Note when specifying the column list, input field numbers start from 1
COPY INTO test_1 (Col_one default 'myStringDefault' 1, Col_two default 1 3)
FROM 'https://myaccount.blob.core.windows.net/myblobcontainer/folder1/'
WITH (
    FILE_TYPE = 'CSV',
    CREDENTIAL=(IDENTITY= 'Storage Account Key', SECRET='<Your_Account_Key>'),
    --CREDENTIAL should look something like this:
    --CREDENTIAL=(IDENTITY= 'Storage Account Key', SECRET='x6RWv4It5F2msnjelv3H4DA80n0PQW0daPdw43jM0nyetx4c6CpDkdj3986DX5AHFMIf/YN4y6kkCnU8lb+Wx0Pj+6MDw=='),
    FIELDQUOTE = '"',
    FIELDTERMINATOR=',',
    ROWTERMINATOR='0x0A',
    ENCODING = 'UTF8',
    FIRSTROW = 2
)

D. 既存のファイル形式オブジェクトを使用して Parquet または ORC を読み込む

この例では、ワイルドカードを使って、フォルダーにあるすべての Parquet ファイルを読み込みます。

COPY INTO test_parquet
FROM 'https://myaccount.blob.core.windows.net/myblobcontainer/folder1/*.parquet'
WITH (
    FILE_FORMAT = myFileFormat,
    CREDENTIAL=(IDENTITY= 'Shared Access Signature', SECRET='<Your_SAS_Token>')
)

E. ワイルドカードと複数のファイルを指定して読み込む

COPY INTO t1
FROM
'https://myaccount.blob.core.windows.net/myblobcontainer/folder0/*.txt',
    'https://myaccount.blob.core.windows.net/myblobcontainer/folder1'
WITH (
    FILE_TYPE = 'CSV',
    CREDENTIAL=(IDENTITY= '<client_id>@<OAuth_2.0_Token_EndPoint>',SECRET='<key>'),
    FIELDTERMINATOR = '|'
)

F. MSI 資格情報を使用して読み込む

COPY INTO dbo.myCOPYDemoTable
FROM 'https://myaccount.blob.core.windows.net/myblobcontainer/folder0/*.txt'
WITH (
    FILE_TYPE = 'CSV',
    CREDENTIAL = (IDENTITY = 'Managed Identity'),
    FIELDQUOTE = '"',
    FIELDTERMINATOR=','
)

G. 自動スキーマ検出を使用して読み込む

COPY INTO [myCOPYDemoTable]
FROM 'https://myaccount.blob.core.windows.net/customerdatasets/folder1/lineitem.parquet'
WITH (
    FILE_TYPE = 'Parquet',
    CREDENTIAL = ( IDENTITY = 'Shared Access Signature',  SECRET='<key>'),
    AUTO_CREATE_TABLE = 'ON'
)

よく寄せられる質問

PolyBase と比較した場合の COPY コマンドのパフォーマンスについて教えてください。

ワークロードによっては、COPY コマンドのパフォーマンスが向上します。

• 圧縮ファイルは、自動分割できません。 読み込みで最高のパフォーマンスを得るには、圧縮されている CSV を読み込むときに、入力を複数のファイルに分割することを検討してください。

• 大きな圧縮されていない CSV ファイルの分割と並列読み込みは自動で行うことができるため、多くの場合、圧縮されていない CSV ファイルを手動で分割する必要はありません。 データの特性のためにファイルを自動分割できないときは、手動で大きな CSV を分割するとパフォーマンスが向上する場合があります。

圧縮されている CSV ファイルを読み込む COPY コマンドに関するファイルの分割ガイダンスについて教えてください。

ファイル数に関するガイダンスを、次の表で説明します。 推奨されるファイル数に到達すると、大きいファイル程パフォーマンスが向上します。 ファイルの数は、コンピューティング ノードの数に 60 を乗算した数によって決まります。 たとえば、6000DWU では、12 個のコンピューティング ノードと 12*60 = 720 個のパーティションがあります。 単純なファイル分割エクスペリエンスについては、「ファイル分割を使用して全体的に COPY 読み込みスループットを最大化する方法」を参照してください。

DWU	#Files
100	60
200	60
300	60
400	60
500	60
1,000	120
1,500	180
2,000	240
2,500	300
3,000	360
5,000	600
6,000	720
7,500	900
10,000	1200
15,000	1800
30,000	3600

Parquet ファイルまたは ORC ファイルを読み込む COPY コマンドに関するファイルの分割ガイダンスについて教えてください。

COPY コマンドによって自動的にファイルが分割されるため、Parquet ファイルと ORC ファイルを分割する必要はありません。 最適なパフォーマンスを得るには、Azure ストレージ アカウントの Parquet ファイルと ORC ファイルが 256 MB 以上である必要があります。

ファイルの数やサイズに制限はありますか?

ファイルの数やサイズに制限はありません。ただし、最適なパフォーマンスを得るには、少なくとも 4 MB のファイルを使用することをお勧めします。

COPY ステートメントに既知の問題はありますか?

2020 年 12 月 7 日より前に作成された Azure Synapse ワークスペースがある場合は、マネージド ID を使用して認証すると、同様のエラー メッセージが表示されることがあります: com.microsoft.sqlserver.jdbc.SQLServerException: Managed Service Identity has not been enabled on this server. Please enable Managed Service Identity and try again.

この問題を回避するには、次の手順に従って、ワークスペースのマネージド ID を再登録します。

1. Azure PowerShell をインストールします。 PowerShell のインストールに関する記事を参照してください。
2. PowerShell を使用してワークスペースのマネージド ID を登録します。

   Connect-AzAccount
   Select-AzSubscription -SubscriptionId <subscriptionId>
   Set-AzSqlServer -ResourceGroupName your-database-server-resourceGroup -ServerName your-SQL-servername -AssignIdentity
   

関連するコンテンツ

• Azure Synapse Analytics で概要を読み込む