COPY (Transact-SQL)COPY (Transact-SQL)

適用対象:Applies to: はいAzure Synapse AnalyticsAzure Synapse AnalyticsyesAzure Synapse AnalyticsAzure Synapse Analytics適用対象:Applies to: はいAzure Synapse AnalyticsAzure Synapse AnalyticsyesAzure Synapse AnalyticsAzure Synapse Analytics

この記事では、Azure Synapse Analytics (SQL Data Warehouse)Azure Synapse Analytics (SQL Data Warehouse) で COPY ステートメントを使用して、外部ストレージ アカウントからの読み込みを行う方法について説明します。This article explains how to use the COPY statement in Azure Synapse Analytics (SQL Data Warehouse)Azure Synapse Analytics (SQL Data Warehouse) for loading from external storage accounts. COPY ステートメントを使用すると、Azure Synapse Analytics (SQL Data Warehouse)Azure Synapse Analytics (SQL Data Warehouse) への高スループットのデータ インジェストで最大の柔軟性が確保されます。The COPY statement provides the most flexibility for high-throughput data ingestion into Azure Synapse Analytics (SQL Data Warehouse)Azure Synapse Analytics (SQL Data Warehouse). 次の機能に COPY を使用します。Use COPY for the following capabilities:

  • データ ウェアハウスに対する厳格な CONTROL アクセス許可を使用せずに、低い特権のユーザーを使用して読み込むことができます。Use lower privileged users to load without needing strict CONTROL permissions on the data warehouse
  • 追加のデータベース オブジェクトを作成することなく、1 つの T-SQL ステートメントを実行できます。Execute a single T-SQL statement without having to create any additional database objects
  • 区切り記号 (文字列、フィールド、行) 文字列で区切られた列内でエスケープされている CSV ファイルを適切に解析して読み込むことができます。Properly parse and load CSV files where delimiters (string, field, row) are escaped within string delimited columns
  • Shared Access Signature (SAS) を使用してストレージ アカウント キーを公開しなくても、より洗練されたアクセス許可モデルを指定できます。Specify a finer permission model without exposing storage account keys using Share Access Signatures (SAS)
  • ERRORFILE の場所 (REJECTED_ROW_LOCATION) として異なるストレージ アカウントを使用できます。Use a different storage account for the ERRORFILE location (REJECTED_ROW_LOCATION)
  • ターゲット列ごとに既定値をカスタマイズし、特定のターゲット列に読み込むソース データ フィールドを指定できます。Customize default values for each target column and specify source data fields to load into specific target columns
  • CSV ファイルのカスタム行ターミネータを指定できます。Specify a custom row terminator for CSV files
  • CSV ファイルで SQL Server の日付形式を活用できます。Leverage SQL Server Date formats for CSV files
  • 保存場所のパスにワイルドカードや複数のファイルを指定できます。Specify wildcards and multiple files in the storage location path

COPY ステートメントを使用した包括的な例とクイックスタートについては、次のドキュメントを参照してください。Visit the following documentation for comprehensive examples and quickstarts using the COPY statement:

構文Syntax

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'}]
)

引数Arguments

schema_nameschema_name
操作を実行するユーザーの既定のスキーマが、指定したテーブルのスキーマと同じ場合は省略可能です。Is optional if the default schema for the user performing the operation is the schema of the specified table. "スキーマ" を指定せず、さらに COPY 操作を実行するユーザーの既定のスキーマが、指定したテーブルのスキーマと異なる場合、COPY は取り消され、エラー メッセージが返されます。If schema is not specified, and the default schema of the user performing the COPY operation is different from the specified table, COPY will be canceled, and an error message will be returned.

table_nametable_name
データの COPY 先のテーブルの名前です。Is the name of the table to COPY data into. ターゲット テーブルは、一時テーブルまたはパーマネント テーブルであり、データベースに既に存在している必要があります。The target table can be a temporary or permanent table and must already exist in the database.

(column_list)(column_list)
データ読み込み時のソース データ フィールドからターゲット テーブル列へのマッピングに使用される 1 つ以上の列のリストです。このリストは省略可能です。Is an optional list of one or more columns used to map source data fields to target table columns for loading data. column_list はかっこで囲み、コンマで区切る必要があります。column_list must be enclosed in parentheses and delimited by commas. 列リストの形式は次のとおりです。The column list is of the following format:

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

  • Column_name - ターゲット テーブルの列の名前。Column_name - the name of the column in the target table.
  • Default_value - 入力ファイルの任意の NULL 値がこの既定値に置き換えられます。Default_value - the default value that will replace any NULL value in the input file. 既定値はすべてのファイル形式に適用されます。Default value applies to all file formats. COPY によって入力ファイルから NULL の読み込みが試行されるのは、列リストに省略されている列がある場合、または入力ファイルに空フィールドがある場合です。COPY will attempt to load NULL from the input file when a column is omitted from the column list or when there is an empty input file field.
  • Field_number - ターゲット列の名前にマップされる入力ファイル フィールド番号。Field_number - the input file field number that will be mapped to the target column name.
  • フィールドのインデックスは 1 から開始されます。The field indexing starts at 1.

列リストが指定されていない場合、COPY では、ソースとターゲットの順序性に基づいて列がマップされます。入力フィールド 1 はターゲット列 1 に、フィールド 2 は列 2 に、以降同様にマップされます。When a column list is not specified, COPY will map columns based on the source and target ordinality: Input field 1 will go to target column 1, field 2 will go to column 2, etc.

External locations(s)External locations(s)
データを含むファイルがステージングされる場所です。Is where the files containing the data is staged. 現在、Azure Data Lake Storage (ADLS) Gen2 と Azure Blob Storage がサポートされています。Currently Azure Data Lake Storage (ADLS) Gen2 and Azure Blob Storage are supported:

  • Blob Storage の External location: https://.blob.core.windows.net//External location for Blob Storage: https://.blob.core.windows.net//
  • ADLS Gen2 の External location: https://.External location for ADLS Gen2: https://. dfs.core.windows.net//dfs.core.windows.net//

注意

.blob エンドポイントは ADLS Gen2 にも使用でき、現在最高のパフォーマンスを実現しています。The .blob endpoint is available for ADLS Gen2 as well and currently yields the best performance. お使いの認証方法で .dfs が必要ない場合、.blob エンドポイントを使用します。Use the .blob endpoint when .dfs is not required for your authentication method.

  • Account - ストレージ アカウント名Account - The storage account name

  • Container - BLOB コンテナー名Container - The blob container name

  • Path - データのフォルダーまたはファイルのパス。Path - the folder or file path for the data. 場所はコンテナーから始まります。The location starts from the container. フォルダーが指定されている場合は、そのフォルダーとそのサブフォルダーにあるすべてのファイルが、COPY によって取得されます。If a folder is specified, COPY will retrieve all files from the folder and all its subfolders. 隠しフォルダーは無視され、アンダースコア () またはピリオド (.) で始まるファイルは返されません (パスで明示的に指定されている場合を除く)。COPY ignores hidden folders and doesn't return files that begin with an underline () or a period (.) unless explicitly specified in the path. この動作は、ワイルドカードを使ってパスを指定した場合も同じです。This behavior is the same even when specifying a path with a wildcard.

パスにはワイルドカードを含めることができますWildcards cards can be included in the path where

  • ワイルドカード パス名の一致では、大文字と小文字が区別されますWildcard path name matching is case-sensitive
  • ワイルドカードをエスケープするには、円記号 (\) を使用しますWildcard can be escaped using the backslash character (\)
  • ワイルドカードの展開は再帰的に適用されます。Wildcard expansion is applied recursively. たとえば、次のようにパスを指定すると、Customer1 (Customer1 のサブディレクトリを含む) の下にある CSV ファイルすべてが読み込まれます: Account/Container/Customer1/*.csvFor instance, all CSV files under Customer1 (including subdirectories of Customer1 will be loaded in the following example: ‘Account/Container/Customer1/*.csv’

注意

最適なパフォーマンスを得るには、多くのファイルに展開されるワイルドカードは指定しないでください。For best performance, avoid specifying wildcards that would expand over a larger number of files. 可能な場合は、ワイルドカードではなく、複数のファイルの場所をリストを使って指定します。If possible, list multiple file locations instead of specifying wildcards.

複数のファイルの場所を指定するには、次のようなコンマ区切りのリストを使用して、同じストレージ アカウントおよびコンテナーから指定する必要があります。Multiple file locations can only be specified from the same storage account and container via a comma-separated list such as:

  • https://.blob.core.windows.net//、 https://.blob.core.windows.net// など‘https://.blob.core.windows.net//’, ‘https://.blob.core.windows.net//’…

FILE_TYPE = { ‘CSV’ | ‘PARQUET’ | ‘ORC’ }FILE_TYPE = { ‘CSV’ | ‘PARQUET’ | ‘ORC’ }
FILE_TYPE により、外部データの形式が指定されます。FILE_TYPE specifies the format of the external data.

  • CSV: RFC 4180 標準に準拠しているコンマ区切り値ファイルを指定します。CSV: Specifies a comma-separated values file compliant to the RFC 4180 standard.
  • PARQUET: Parquet 形式を指定します。PARQUET: Specifies a Parquet format.
  • ORC: 最適化行多桁式 (ORC) 形式を指定します。ORC: Specifies an Optimized Row Columnar (ORC) format.

注意

Polybase のファイルの種類である "区切りテキスト" は "CSV" ファイル形式に置き換えられています。このファイル形式で既定のコンマ区切り記号を構成するには、FIELDTERMINATOR パラメーターを使用します。The file type 'Delimited Text' in Polybase is replaced by the ‘CSV’ file format where the default comma delimiter can be configured via the FIELDTERMINATOR parameter.

FILE_FORMAT = external_file_format_nameFILE_FORMAT = external_file_format_name
FILE_FORMAT は Parquet ファイルおよび ORC ファイルにのみ適用され、外部データのファイルの種類と圧縮方法を格納する外部ファイル形式オブジェクトの名前を指定します。FILE_FORMAT applies to Parquet and ORC files only and specifies the name of the external file format object that stores the file type and compression method for the external data. 外部ファイル形式を作成するには、CREATE EXTERNAL FILE FORMAT を使用します。To create an external file format, use CREATE EXTERNAL FILE FORMAT.

CREDENTIAL (IDENTITY = ‘’, SECRET = ‘’)CREDENTIAL (IDENTITY = ‘’, SECRET = ‘’)
CREDENTIAL は、外部ストレージ アカウントにアクセスするための認証メカニズムを指定します。CREDENTIAL specifies the authentication mechanism to access the external storage account. 認証方法を次に示します。Authentication methods are:

CSVCSV ParquetParquet ORCORC
Azure Blob StorageAzure blob storage SAS/MSI/サービス プリンシパル/キー/AADSAS/MSI/SERVICE PRINCIPAL/KEY/AAD SAS/キーSAS/KEY SAS/キーSAS/KEY
Azure Data Lake Gen2Azure Data Lake Gen2 SAS/MSI/サービス プリンシパル/キー/AADSAS/MSI/SERVICE PRINCIPAL/KEY/AAD SAS (BLOB1)/MSI (dfs2)/サービス プリンシパル/キー/AADSAS (blob1)/MSI (dfs2)/SERVICE PRINCIPAL/KEY/AAD SAS (BLOB1)/MSI (dfs2)/サービス プリンシパル/キー/AADSAS (blob1)/MSI (dfs2)/SERVICE PRINCIPAL/KEY/AAD

1:この認証方法には、お使いの外部のロケーション パスに .blob エンドポイント ( .blob.core.windows.net) が必要です。1: The .blob endpoint (.blob.core.windows.net) in your external location path is required for this authentication method.

2:この認証方法には、お使いの外部のロケーション パスに .dfs エンドポイント ( .dfs.core.windows.net) が必要です。2: The .dfs endpoint (.dfs.core.windows.net) in your external location path is required for this authentication method.

注意

  • AAD またはパブリック ストレージ アカウントを使用して認証する場合は、CREDENTIAL を指定する必要はありません。When authenticating using AAD or to a public storage account, CREDENTIAL does not need to be specified.
  • ストレージ アカウントが VNet に関連付けられている場合は、MSI (マネージド ID) を使用して認証する必要があります。If your storage account is associated with a VNet, you must authenticate using MSI (Managed Identity).
  • Shared Access Signatures (SAS) を使用した認証Authenticating with Shared Access Signatures (SAS)

    • IDENTITY: "Shared Access Signature" の値が含まれている定数IDENTITY: A constant with a value of ‘Shared Access Signature’
    • SECRET: Shared Access Signature "を使用すると、ストレージ アカウント内のリソースへの委任アクセスが可能になります。 "SECRET: The shared access signature provides delegated access to resources in your storage account.
    • 最低限必要な権限: READ および LISTMinimum permissions required: READ and LIST
  • サービス プリンシパルを使用した認証Authenticating with Service Principals

    • IDENTITY: @<OAuth_2.0_Token_EndPoint>IDENTITY: @<OAuth_2.0_Token_EndPoint>
    • SECRET: AAD サービス プリンシパル アプリケーション キーSECRET: AAD Application Service Principal key
    • 最低限必要な RBAC ロール: ストレージ BLOB データ共同作成者、ストレージ BLOB データ所有者、またはストレージ BLOB データ閲覧者Minimum RBAC roles required: Storage blob data contributor, Storage blob data contributor, Storage blob data owner, or Storage blob data reader
  • ストレージ アカウント キーを使用した認証Authenticating with Storage account key

    • IDENTITY: "ストレージ アカウント キー" の値が含まれている定数IDENTITY: A constant with a value of ‘Storage Account Key’
    • SECRET: ストレージ アカウント キーSECRET: Storage account key
  • マネージド ID (VNet サービス エンドポイント) を使用した認証Authenticating with Managed Identity (VNet Service Endpoints)

    • IDENTITY: "マネージド ID" の値が含まれている定数IDENTITY: A constant with a value of ‘Managed Identity’
    • 最低限必要な RBAC ロール: AAD 登録済み SQL Database サーバーに対するストレージ BLOB データ共同作成者またはストレージ BLOB データ所有者Minimum RBAC roles required: Storage blob data contributor or Storage blob data owner for the AAD registered SQL Database server
  • AAD ユーザーを使用した認証Authenticating with an AAD user

    • CREDENTIAL は必須ではありませんCREDENTIAL is not required
    • 最低限必要な RBAC ロール: AAD ユーザーに対するストレージ BLOB データ共同作成者またはストレージ BLOB データ所有者Minimum RBAC roles required: Storage blob data contributor or Storage blob data owner for the AAD user

ERRORFILE = Directory LocationERRORFILE = Directory Location
ERRORFILE は CSV にのみ適用されます。ERRORFILE only applies to CSV. COPY ステートメント内でディレクトリを指定します。拒否された行と該当するエラー ファイルがそこに書き込まれます。Specifies the directory within the COPY statement where the rejected rows and the corresponding error file should be written. ストレージ アカウントからの完全なパスを指定することも、コンテナーを基準とした相対パスを指定することもできます。The full path from the storage account can be specified or the path relative to the container can be specified. 指定したパスが存在しない場合は、自動的に作成されます。If the specified path doesn't exist, one will be created on your behalf. "rejectedrows" という名前で子ディレクトリが作成されます。" " 文字があることで、場所パラメーターで明示的に指定されない限り、他のデータ処理ではこのディレクトリがエスケープされます。A child directory is created with the name "rejectedrows". The "" character ensures that the directory is escaped for other data processing unless explicitly named in the location parameter.

このディレクトリ内には、YearMonthDay -HourMinuteSecond (例:Within this directory, there's a folder created based on the time of load submission in the format YearMonthDay -HourMinuteSecond (Ex. 20180330-173205) のロード サブミッション時間に基づいて作成されたフォルダーがあります。20180330-173205). このフォルダーには、理由 (エラー) ファイルとデータ (行) ファイルの 2 種類のファイルが書き込まれ、それぞれ queryID、distributionID、ファイル GUID が事前に追加されています。In this folder, two types of files are written, the reason (Error) file and the data (Row) file each pre-appending with the queryID, distributionID, and a file guid. データと理由が別々のファイル内にあり、対応するファイルはプレフィックスが一致しています。Because the data and the reason are in separate files, corresponding files have a matching prefix.

ERRORFILE でストレージ アカウントの完全なパスが定義されている場合、そのストレージへの接続には ERRORFILE_CREDENTIAL が使用されます。If ERRORFILE has the full path of the storage account defined, then the ERRORFILE_CREDENTIAL will be used to connect to that storage. それ以外の場合は、CREDENTIAL に指定された値が使用されます。Otherwise, the value mentioned for CREDENTIAL will be used.

ERRORFILE_CREDENTIAL = (IDENTITY= ‘’, SECRET = ‘’)ERRORFILE_CREDENTIAL = (IDENTITY= ‘’, SECRET = ‘’)
ERRORFILE_CREDENTIAL は、CSV ファイルにのみ適用されます。ERRORFILE_CREDENTIAL only applies to CSV files. サポートされているデータ ソースと認証方法は次のとおりです。Supported data source and authentication methods are:

  • Azure Blob Storage - SAS/サービス プリンシパル/キー/AADAzure Blob Storage - SAS/SERVICE PRINCIPAL/KEY/AAD

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

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

    • IDENTITY: "Shared Access Signature" の値が含まれている定数IDENTITY: A constant with a value of ‘Shared Access Signature’
    • SECRET: Shared Access Signature "を使用すると、ストレージ アカウント内のリソースへの委任アクセスが可能になります。 "SECRET: The shared access signature provides delegated access to resources in your storage account.
    • 最低限必要な権限: READ、LIST、WRITE、CREATE、DELETEMinimum permissions required: READ, LIST, WRITE, CREATE, DELETE
  • サービス プリンシパルを使用した認証Authenticating with Service Principals

    • IDENTITY: @<OAuth_2.0_Token_EndPoint>IDENTITY: @<OAuth_2.0_Token_EndPoint>
    • SECRET: AAD サービス プリンシパル アプリケーション キーSECRET: AAD Application Service Principal key
    • 最低限必要な RBAC ロール: ストレージ BLOB データ共同作成者またはストレージ BLOB データ所有者Minimum RBAC roles required: Storage blob data contributor or Storage blob data owner

注意

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

  • ストレージ アカウント キーを使用した認証Authenticating with Storage account key

    • IDENTITY: "ストレージ アカウント キー" の値が含まれている定数IDENTITY: A constant with a value of ‘Storage Account Key’
    • SECRET: ストレージ アカウント キーSECRET: Storage account key
  • マネージド ID (VNet サービス エンドポイント) を使用した認証Authenticating with Managed Identity (VNet Service Endpoints)

    • IDENTITY: "マネージド ID" の値が含まれている定数IDENTITY: A constant with a value of ‘Managed Identity’
    • 最低限必要な RBAC ロール: AAD 登録済み SQL Database サーバーに対するストレージ BLOB データ共同作成者またはストレージ BLOB データ所有者Minimum RBAC roles required: Storage blob data contributor or Storage blob data owner for the AAD registered SQL Database server
  • AAD ユーザーを使用した認証Authenticating with an AAD user

    • CREDENTIAL は必須ではありませんCREDENTIAL is not required
    • 最低限必要な RBAC ロール: AAD ユーザーに対するストレージ BLOB データ共同作成者またはストレージ BLOB データ所有者Minimum RBAC roles required: Storage blob data contributor or Storage blob data owner for the AAD user

注意

ご自身の ERRORFILE に同じストレージ アカウントを使用し、コンテナーのルートを基準とした ERRORFILE パスを指定している場合は、ERROR_CREDENTIAL を指定する必要はありません。If you are using the same storage account for your ERRORFILE and specifying the ERRORFILE path relative to the root of the container, you do not need to specify the ERROR_CREDENTIAL.

MAXERRORS = max_errorsMAXERRORS = max_errors
MAXERRORS では、読み込みで拒否できる行の最大数を指定します。この最大数に達すると、COPY 操作は取り消されます。MAXERRORS specifies the maximum number of reject rows allowed in the load before the COPY operation is canceled. COPY 操作でインポートできない行は無視され、それぞれ 1 つのエラーとしてカウントされます。Each row that cannot be imported by the COPY operation is ignored and counted as one error. max_errors が指定されていない場合、既定値は 0 です。If max_errors is not specified, the default is 0.

COMPRESSION = { 'DefaultCodec '| ’Snappy’ | ‘GZIP’ | ‘NONE’}COMPRESSION = { 'DefaultCodec '| ’Snappy’ | ‘GZIP’ | ‘NONE’}
COMPRESSION は省略可能で、外部データのデータ圧縮方法を指定します。COMPRESSION is optional and specifies the data compression method for the external data.

  • CSV は GZIP をサポートしていますCSV supports GZIP
  • Parquet は GZIP および Snappy をサポートしていますParquet supports GZIP and Snappy
  • ORC は DefaultCodec および Snappy をサポートしています。ORC supports DefaultCodec and Snappy.
  • Zlib は ORC の既定の圧縮ですZlib is the default compression for ORC

このパラメーターが指定されていない場合、COPY コマンドでは、ファイル名拡張子に基づいて圧縮の種類が自動検出されます。The COPY command will autodetect the compression type based on the file extension when this parameter is not specified:

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

FIELDQUOTE = 'field_quote'FIELDQUOTE = 'field_quote'
FIELDQUOTE は CSV に適用され、CSV ファイルで引用符文字 (文字列の区切り記号) として使用される 1 バイト文字を指定します。FIELDQUOTE applies to CSV and specifies a single character that will be used as the quote character (string delimiter) in the CSV file. 指定されていない場合は、RFC 4180 標準の定義に従って引用符文字 (") が引用符文字として使用されます。If not specified, the quote character (") will be used as the quote character as defined in the RFC 4180 standard. FIELDQUOTE の UTF-8 では、拡張 ASCII およびマルチバイト文字はサポートされていません。Extended ASCII and multi-byte characters and are not supported with UTF-8 for FIELDQUOTE.

注意

FIELDQUOTE 文字は、2 バイト FIELDQUOTE (区切り記号) が存在する文字列型の列ではエスケープされます。FIELDQUOTE characters are escaped in string columns where there is a presence of a double FIELDQUOTE (delimiter).

FIELDTERMINATOR = 'field_terminator’FIELDTERMINATOR = 'field_terminator’
FIELDTERMINATOR は CSV にのみ適用されます。FIELDTERMINATOR Only applies to CSV. CSV ファイルで使用されるフィールド ターミネータを指定します。Specifies the field terminator that will be used in the CSV file. フィールド ターミネータは、16 進数表記を使用して指定できます。The field terminator can be specified using hexadecimal notation. フィールド ターミネータにはマルチ文字を使用できます。The field terminator can be multi-character. 既定のフィールド ターミネータは (,) です。The default field terminator is a (,). FIELDTERMINATOR の UTF-8 では、拡張 ASCII およびマルチバイト文字はサポートされていません。Extended ASCII and multi-byte characters and are not supported with UTF-8 for FIELDTERMINATOR.

ROW TERMINATOR = 'row_terminator'ROW TERMINATOR = 'row_terminator'
ROW TERMINATOR は CSV にのみ適用されます。ROW TERMINATOR Only applies to CSV. CSV ファイルで使用される行ターミネータを指定します。Specifies the row terminator that will be used in the CSV file. 行ターミネータは、16 進数表記を使用して指定できます。The row terminator can be specified using hexadecimal notation. 行ターミネータにはマルチ文字を使用できます。The row terminator can be multi-character. 既定では、行ターミネータは \r\n です。By default, the row terminator is \r\n.

COPY コマンドでは、\n (改行) を指定すると、その前に \r 文字が付けられ、\r\n になります。The COPY command prefixes the \r character when specifying \n (newline) resulting in \r\n. \n 文字のみを指定するには、16 進数表記 (0x0A) を使用します。To specify only the \n character, use hexadecimal notation (0x0A). マルチ文字の行ターミネータを 16 進数で指定する場合は、各文字の間で 0x を指定しないでください。When specifying multi-character row terminators in hexadecimal, do not specify 0x between each character.

ROW TERMINATOR の UTF-8 では、拡張 ASCII およびマルチバイト文字はサポートされていません。Extended ASCII and multi-byte characters and are not supported with UTF-8 for ROW TERMINATOR.

FIRSTROW = First_row_intFIRSTROW = First_row_int
FIRSTROW は CSV に適用され、COPY コマンドに対して、すべてのファイルで最初に読み取られる行番号を指定します。FIRSTROW applies to CSV and specifies the row number that is read first in all files for the COPY command. 値は 1 から始まり、これが既定値です。Values start from 1, which is the default value. 2 に設定すると、データが読み込まれるときに、すべてのファイルの最初の行 (ヘッダー行) がスキップされます。If the value is set to two, the first row in every file (header row) is skipped when the data is loaded. 行は、行ターミネータの存在に基づいてスキップされます。Rows are skipped based on the existence of row terminators.

DATEFORMAT = { ‘mdy’ | ‘dmy’ | ‘ymd’ | ‘ydm’ | ‘myd’ | ‘dym’ }DATEFORMAT = { ‘mdy’ | ‘dmy’ | ‘ymd’ | ‘ydm’ | ‘myd’ | ‘dym’ }
DATEFORMAT は CSV にのみ適用され、SQL Server 日付形式に対する日付の日付形式のマッピングを指定します。DATEFORMAT only applies to CSV and specifies the date format of the date mapping to SQL Server date formats. Transact-SQL の日付と時刻のデータ型および関数の概要については、「日付と時刻のデータ型および関数 (Transact-SQL)」を参照してください。For an overview of all Transact-SQL date and time data types and functions, see Date and Time Data Types and Functions (Transact-SQL). COPY コマンド内の DATEFORMAT は、セッション レベルで構成された DATEFORMAT よりも優先されます。DATEFORMAT within the COPY command takes precedence over DATEFORMAT configured at the session level.

ENCODING = ‘UTF8’ | ‘UTF16’ENCODING = ‘UTF8’ | ‘UTF16’
ENCODING は CSV にのみ適用されます。ENCODING only applies to CSV. 既定値は UTF8 です。Default is UTF8. COPY コマンドによって読み込まれたファイルのデータ エンコード標準を指定します。Specifies the data encoding standard for the files loaded by the COPY command.

IDENTITY_INSERT = ‘ON’ | ‘OFF’IDENTITY_INSERT = ‘ON’ | ‘OFF’
IDENTITY_INSERT は、インポートしたデータ ファイルの ID 値 (複数可) を ID 列に使用するかどうかを指定します。IDENTITY_INSERT specifies whether the identity value or values in the imported data file are to be used for the identity column. IDENTITY_INSERT が OFF (既定値) の場合、この列の ID 値は検証されますが、インポートされません。If IDENTITY_INSERT is OFF (default), the identity values for this column are verified, but not imported. テーブル作成時に指定されたシード値と増分値に基づいて、固有の値が SQL DW によって自動的に割り当てられます。SQL DW will automatically assign unique values based on the seed and increment values specified during table creation. COPY コマンドによる次の動作に注意してください。Note the following behavior with the COPY command:

  • IDENTITY_INSERT が OFF で、テーブルに ID 列がある場合If IDENTITY_INSERT is OFF, and table has an identity column
    • 入力フィールドを ID 列にマップしない列リストを指定する必要があります。A column list must be specified which does not map an input field to the identity column.
  • IDENTITY_INSERT が ON で、テーブルに ID 列がある場合If IDENTITY_INSERT is ON, and table has an identity column
    • 列リストが渡された場合、入力フィールドを ID 列にマップする必要があります。If a column list is passed, it must map an input field to the identity column.
  • 列リストの IDENTITY COLUMN に対して既定値がサポートされない。Default value is not supported for the IDENTITY COLUMN in the column list.
  • IDENTITY_INSERT は一度に 1 つのテーブルに対してのみ設定できる。IDENTITY_INSERT can only be set for one table at a time.

アクセス許可Permissions

コピー コマンドを実行するユーザーには次の権限が必要です。The user executing the Copy Command must have the following permissions:

INSERT 権限および ADMINISTER BULK OPERATIONS 権限が必要です。Requires INSERT and ADMINISTER BULK OPERATIONS permissions. Azure Synapse Analytics (SQL Data Warehouse)Azure Synapse Analytics (SQL Data Warehouse) では、INSERT および ADMINISTER DATABASE BULK OPERATIONS 権限が必要です。In Azure Synapse Analytics (SQL Data Warehouse)Azure Synapse Analytics (SQL Data Warehouse), INSERT, and ADMINISTER DATABASE BULK OPERATIONS permissions are required.

Examples

A.A. パブリック ストレージ アカウントから読み込むLoad from a public storage account

次の例は COPY コマンドの最も単純な形式で、パブリック ストレージ アカウントからデータを読み込みます。The following example is the simplest form of the COPY command, which loads data from a public storage account. この例では、COPY ステートメントの既定値は、行項目 csv ファイルの形式と一致しています。For this example, the COPY statement's defaults match the format of the line item csv file.

COPY INTO dbo.[lineitem] FROM 'https://unsecureaccount.blob.core.windows.net/customerdatasets/folder1/lineitem.csv'

COPY コマンドの既定値を次に示します。The default values of the COPY command are:

  • DATEFORMAT = Session DATEFORMATDATEFORMAT = Session DATEFORMAT

  • MAXERRORS = 0MAXERRORS = 0

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

  • FIELDQUOTE = “”FIELDQUOTE = “”

  • FIELDTERMINATOR = “,”FIELDTERMINATOR = “,”

  • ROWTERMINATOR = ‘\n'ROWTERMINATOR = ‘\n'

重要

内部的には COPY では ' \n ' が ' \r\n ' として処理されます。COPY treats ‘\n’ as ‘\r\n’ internally. 詳細については、ROWTERMINATOR セクションを参照してください。For more information, see the ROWTERMINATOR section.

  • FIRSTROW = 1FIRSTROW = 1

  • ENCODING = ‘UTF8’ENCODING = ‘UTF8’

  • FILE_TYPE = ‘CSV’FILE_TYPE = ‘CSV’

  • IDENTITY_INSERT = ‘OFF’IDENTITY_INSERT = ‘OFF’

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

次の例では、UNIX 出力などのように、改行を行ターミネータとして使用するファイルを読み込みます。The following example loads files that use the line feed as a row terminator such as a UNIX output. また、SAS キーを使用して Azure Blob Storage に対して認証を行います。This example also uses a SAS key to authenticate to 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.C. ストレージ アカウント キーを介して認証を行い、既定値が含まれる列リストを使用して読み込むLoad with a column list with default values authenticating via Storage Account Key

この例では、既定値が含まれる列リストを指定してファイルを読み込みます。This example loads files specifying a column list with default values.

--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.D. 既存のファイル形式オブジェクトを使用して Parquet または ORC を読み込むLoad Parquet or ORC using existing file format object

この例では、ワイルドカードを使用して、フォルダーにあるすべての parquet ファイルを読み込みます。This example uses a wildcard to load all parquet files under a folder.

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.E. ワイルドカードと複数のファイルを指定して読み込むLoad specifying wild cards and multiple files

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.F. MSI 資格情報を使用して読み込むLoad using MSI credentials

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

よく寄せられる質問FAQ

PolyBase と比較した場合の COPY コマンドのパフォーマンスについて教えてください。What is the performance of the COPY command compared to PolyBase?

ワークロードによっては、COPY コマンドのパフォーマンスが向上します。The COPY command will have better performance depending on your workload. 最適な読み込みパフォーマンスを得るには、CSV の読み込み時に複数のファイルに入力を分割することを検討してください。For best loading performance, consider splitting your input into multiple files when loading CSV.

CSV ファイルを読み込む COPY コマンドに関するファイルの分割ガイダンスについて教えてください。What is the file splitting guidance for the COPY command loading CSV files?

ファイル数に関するガイダンスを、次の表で説明します。Guidance on the number of files is outlined in the table below. 推奨されるファイル数に到達すると、大きいファイル程パフォーマンスが向上します。Once the recommended number of files are reached, you will have better performance the larger the files. 単純なファイル分割エクスペリエンスについては、次のドキュメントを参照してください。For a simple file splitting experience, refer to the following documentation.

DWUDWU #Files#Files
100100 6060
200200 6060
300300 6060
400400 6060
500500 6060
1,0001,000 120120
1,5001,500 180180
2,0002,000 240240
2,5002,500 300300
3,0003,000 360360
5,0005,000 600600
6,0006,000 720720
7,5007,500 900900
10,00010,000 12001200
15,00015,000 18001800
30,00030,000 36003600

Parquet ファイルまたは ORC ファイルを読み込む COPY コマンドに関するファイルの分割ガイダンスについて教えてください。What is the file splitting guidance for the COPY command loading Parquet or ORC files?

COPY コマンドによって自動的にファイルが分割されるため、Parquet ファイルと ORC ファイルを分割する必要はありません。There is no need to split Parquet and ORC files because the COPY command will automatically split files. 最適なパフォーマンスを得るには、Azure ストレージ アカウントの Parquet ファイルと ORC ファイルが 256MB 以上である必要があります。Parquet and ORC files in the Azure storage account should be 256MB or larger for best performance.

ファイルの数やサイズに制限はありますか?Are there any limitations on the number or size of files?

ファイルの数やサイズに制限はありません。ただし、最適なパフォーマンスを得るには、少なくとも 4 MB のファイルを使用することをお勧めします。There are no limitations on the number or size of files; however, for best performance, we recommend files that are at least 4MB.

Synapse ワークスペース (プレビュー) を使用した場合、COPY には何か制限がありますか?Are there any limitations with COPY using Synapse workspaces (preview)?

マネージド ID (MSI) を使用する認証は、COPY ステートメントまたは PolyBase (パイプラインで使用する場合を含む) ではサポートされていません。Authenticating using Managed Identity (MSI) is not supported with the COPY statement or PolyBase (including when used in pipelines). 次のようなエラー メッセージが表示されることがあります。You may run into a similiar error message:

com.microsoft.sqlserver.jdbc.SQLServerException: マネージド サービス ID はこのサーバーでは有効にされていません。マネージド サービス ID を有効にして、もう一度お試しください。com.microsoft.sqlserver.jdbc.SQLServerException: Managed Service Identity has not been enabled on this server. Please enable Managed Service Identity and try again.

ストレージ アカウントが VNet に関連付けられている場合、MSI 認証が必要です。MSI authentication is required when the storage account is associated with a VNet. ストレージ アカウントが VNet に関連付けられている場合は、COPY または PolyBase ではなく、BCP の一括挿入を使用してデータを読み込む必要があります。You must use BCP/Bulk insert to load data instead of COPY or PolyBase if your storage account is attached to a VNet.

この制限は、Synapse ワークスペース (プレビュー) に属する SQL プールにのみ適用されます。This limitation is only applicable to SQL pools belonging to a Synapse workspace (preview). 今後のリリースでは、Synapse ワークスペースで MSI がサポートされるようになります。We will enable MSI support in Synapse workspaces in an upcoming release.

フィードバックや問題は、配布リストの sqldwcopypreview@service.microsoft.com までお寄せください。Please send any feedback or issues to the following distribution list: sqldwcopypreview@service.microsoft.com

関連項目See also

Azure Synapse Analytics (SQL Data Warehouse)Azure Synapse Analytics (SQL Data Warehouse) で概要を読み込むLoading overview with Azure Synapse Analytics (SQL Data Warehouse)Azure Synapse Analytics (SQL Data Warehouse)