コピー先 (Transact-SQL)

Tip

Microsoft Fabric Data Warehouse は、将来のアーキテクチャ、組み込みの AI、および新機能を備えた、Data Lake 基盤上のエンタープライズ規模のリレーショナルウェアハウスです。データウェアハウスを初めて使用する場合は、Fabric Data Warehouseから始めます。既存の dedicated SQL プールワークロードは、Fabric にアップグレードして、データサイエンス、リアルタイム分析、レポートの新機能にアクセスできます。

Fabric無料試用版を開始します。
Fabric Data Warehouse の移行アシスタント。

この記事では、Azure Synapse Analyticsで COPY ステートメントを使用して外部ストレージアカウントからデータを読み込む方法について説明します。 COPY文は、Azure Synapse Analyticsへの高スループットデータ取り込みに最も柔軟性を提供します。

Note

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ステートメントを使用した包括的な例とクイックスタートについては、次を参照してください。

Note

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

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' } ]
 [ , AUTO_CREATE_TABLE = { 'ON' | 'OFF' } ]
)

Arguments

schema_name

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

テーブル名

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

(column_list)

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

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

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

[(Column_name [既定の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 はフォルダーとそのすべてのサブフォルダーからすべてのファイルを取得します。 COPY は非表示のフォルダーを無視し、パスで明示的に指定しない限り、下線 (_) またはピリオド (.) で始まるファイルを返しません。この動作は、ワイルドカードを使ってパスを指定した場合も同じです。

次の場所のパスにワイルドカードを含めることができます。

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

Note

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

次のようなコンマ区切りのリストを使用して、同じストレージアカウントとコンテナーからのみ複数のファイルの場所を指定できます。

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) 形式を指定します。

Note

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/サービスプリンシパル/キー/Entra	SAS/KEY	SAS/KEY
Azure Data Lake Gen2	SAS/MSI/サービスプリンシパル/キー/Entra	SAS (BLOB ¹)/MSI (dfs ²)/サービスプリンシパル/KEY/Entra	SAS (BLOB ¹)/MSI (dfs ²)/サービスプリンシパル/KEY/Entra

¹ この認証方法には、外部の場所パスの blob エンドポイント (.blob.core.windows.net) が必要です。

² この認証方法には、外部の場所パスの 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: 値が ᠒の定数 Storage Account Key
- SECRET: ストレージアカウントキー
マネージド ID (VNet サービスエンドポイント) を使用した認証
- IDENTITY: 値が ᠒の定数 Managed Identity
必要な最小 RBAC ロール: Azure の Microsoft Entra 登録済み logical サーバーのストレージ BLOB データ共同作成者またはストレージ BLOB データ所有者。 Synapse ワークスペースに関連付けられていない専用 SQL プール (旧称 SQL DW) を使用する場合、この RBAC ロールは必要ありませんが、マネージド ID には、ソースファイルへの読み取りアクセスを有効にするために、ターゲットオブジェクトに対するAccess Controlリスト (ACL) アクセス許可が必要です。
Microsoft Entra ユーザーによる認証
- CREDENTIAL は必要ありません
最低限必要な RBAC ロール: Microsoft Entra ユーザーのストレージ BLOB データ共同作成者またはストレージ BLOB データ所有者

ERRORFILE = ディレクトリの場所

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

Note

ERRORFILEに相対パスを渡すときは、external_locationで指定したコンテナーパスを基準にして相対パスにします。

このディレクトリ内では、 YearMonthDay -HourMinuteSecond 形式 (たとえば、 20180330-173205) で、読み込み送信の時刻に基づいてフォルダーが作成されます。このフォルダーでは、プロセスによって、理由 (エラー) ファイルとデータ (行) ファイルの 2 種類のファイルが書き込まれます。各ファイルには、 queryID、 distributionID、およびファイル GUID が付加されます。データと理由が別々のファイル内にあり、対応するファイルはプレフィックスが一致しています。

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

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

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

Azure Blob Storage: SAS、サービスプリンシパル、またはMicrosoft Entra
Azure Data Lake Gen2: SAS、MSI、サービスプリンシパル、またはMicrosoft Entra
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 データ所有者

Note

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

マネージド ID (VNet サービスエンドポイント) を使用した認証
- IDENTITY: 値が ᠒の定数 Managed Identity
最低限必要な RBAC ロール: Microsoft Entra 登録済み SQL Database サーバーのストレージ BLOB データ共同作成者またはストレージ BLOB データ所有者
Microsoft Entra ユーザーによる認証
- CREDENTIAL は必須ではありません
最低限必要な RBAC ロール: Microsoft Entra ユーザーのストレージ BLOB データ共同作成者またはストレージ BLOB データ所有者

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

Note

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

MAXERRORS = max_errors

MAXERRORS は、COPY 操作が失敗する前に読み込みで許可される拒否行の最大数を指定します。 COPY 操作でインポートできない行は無視され、それぞれ 1 つのエラーとしてカウントされます。エラーの最大数の値を指定しない場合、既定値は 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 - てきぱき
.deflate - DefaultCodec (Parquet と ORC のみ)

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

FIELDQUOTE = 'field_quote'

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

Note

FIELDQUOTE 文字は、二重 FIELDQUOTE (区切り記号) が存在する文字列列でエスケープされます。

フィールドターミネーター = 'field_terminator'

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

ROWTERMINATOR = 'row_terminator'

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

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

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

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 値は検証されますが、インポートされません。 COPY コマンドによる次の動作に注意してください。

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

テーブル作成時に指定されたシード値と増分値に基づいて、一意の値が Azure Synapse Analytics によって自動的に割り当てられます。

AUTO_CREATE_TABLE = { 'ON' |'OFF' }

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

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

Note

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

Permissions

COPY コマンドを実行するユーザーには、次のアクセス許可が必要です。

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];

Remarks

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

MAXDOP クエリヒントは、COPY INTOではサポートされていません。

確実に実行できるように、 COPY INTO 操作中にソースファイルとフォルダーを変更しないでください。

コマンドの実行中に参照されているファイルまたはフォルダーを変更、削除、または置き換えると、操作が失敗したり、データインジェストに不整合が生じたりする可能性があります。
COPY INTOを実行する前に、すべてのソースデータが安定しており、プロセス中に変更されていないことを確認します。

ソースデータの有効桁数が変換先列の定義よりも大きい場合、数値、日付、および時刻型の場合、値は丸められずに切り捨てられます。

Examples

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

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

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

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

DATEFORMAT = セッション DATEFORMAT
MAXERRORS = 0
COMPRESSION デフォルトは非圧縮です
FIELDQUOTE = '"'
FIELDTERMINATOR = ','
ROWTERMINATOR = '\n'

Important

COPY \nを内部的に\r\nとして扱う。詳細については、「ROWTERMINATOR」のセクションを参照してください。

FIRSTROW = 1
ENCODING = 'UTF8'
FILE_TYPE = 'CSV'
IDENTITY_INSERT = 'OFF'

次の例では、行ターミネータとして行フィードを使用するファイル (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>'),
    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'
)

FAQ

COPY コマンドのパフォーマンスと PolyBase の比較

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

ウェアハウスは、圧縮ファイルを自動的に分割することはできません。読み込みパフォーマンスを最大限に高めるには、圧縮 CSV を読み込むときに入力を複数のファイルに分割することを検討してください。
ウェアハウスは、大きな圧縮されていない CSV ファイルを自動的に分割して並列読み込みを行うことができるため、通常、圧縮されていない CSV ファイルを手動で分割する必要はありません。データ特性のために自動ファイル分割が不可能な場合でも、大きな CSV を手動で分割するとパフォーマンスが向上する可能性があります。

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

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

DWU	ファイルの数
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 以上のファイルを使用してください。また、パフォーマンスを向上させるために、ソースファイルの数を最大 5,000 ファイルに制限します。

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

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

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

Azure PowerShell をインストールします。 PowerShell のインストールを参照してください。

PowerShell を使用してワークスペースのマネージド ID を登録します。

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

Azure Synapse Analytics で概要を読み込む

適用対象:Microsoft Fabric のウェアハウス

この記事では、外部ストレージアカウントから読み込むためのMicrosoft Fabricで Warehouse の COPY ステートメントを使用する方法について説明します。ステートメントは、Microsoft Fabricのウェアハウスへの高スループットのデータインジェストに最も柔軟性を提供し、Microsoft Fabric のウェアハウスにデータを<する戦略として>します。

Fabric Data Warehouseでは、現在、COPY ステートメントは CSV、JSONL、PARQUET ファイル形式をサポートしています。データソースでは、Azure Data Lake Storage Gen2 アカウントと OneLake ソースがサポートされています。

Microsoft Fabric のウェアハウスで COPY INTO を使用する方法の詳細については、「 COPY ステートメントを使用して Microsoft Fabric のウェアハウスにデータを取り込む」を参照してください。

既定では、COPY INTOは実行中のMicrosoft Entra ID ユーザーとして認証されます。

以下の機能のために COPY をご利用ください:

低い特権を持つユーザーを使用して、ウェアハウスに対する厳密な CONTROL アクセス許可を必要とせずにデータを読み込みます。
他のデータベースオブジェクトを作成することなく、1 つの T-SQL ステートメントを実行します。
区切り記号 (文字列、フィールド、行) が文字列で区切られた列内でエスケープされている CSV ファイルを適切に解析して読み込みます。
各行が有効な JSON オブジェクトであり、フィールドが JSON パス式を使用してマップされている JSONL ファイルを適切に解析して読み込みます。
Shared Access Signature (SAS) を使用してストレージアカウントキーを公開せずに、より細かいアクセス許可モデルを指定します。
ERRORFILEの場所は別のストレージアカウント(REJECTED_ROW_LOCATION)を使ってください。
ターゲット列ごとに既定値をカスタマイズし、特定のターゲット列に読み込むソースデータフィールドを指定できます。
CSVファイル用にカスタム行の終端、フィールド終端、フィールド引用符を指定します。
保存場所のパスにワイルドカードや複数のファイルを指定できます。
データインジェストオプションとベストプラクティスの詳細については、 COPY ステートメントを使用して Microsoft Fabric のウェアハウスにデータを取り込む方法に関する説明を参照してください。

Syntax

COPY INTO [ warehouse_name. ] [ schema_name. ] table_name
[ (Column_list) ]
FROM '<external_location>' [ , ...n ]
WITH
 (
 [ FILE_TYPE = { 'CSV' | 'JSONL' | 'PARQUET' } ]
 [ , CREDENTIAL = (AZURE CREDENTIAL) ]
 [ , ERRORFILE = ' [ http(s)://storageaccount/container ] /errorfile_directory [ / ] ] '
 [ , ERRORFILE_CREDENTIAL = (AZURE CREDENTIAL) ]
 [ , MAXERRORS = max_errors ]
 [ , COMPRESSION = { 'Gzip' | 'Snappy' } ]
 [ , FIELDQUOTE = 'string_delimiter' ]
 [ , FIELDTERMINATOR =  'field_terminator' ]
 [ , ROWTERMINATOR = 'row_terminator' ]
 [ , FIRSTROW = first_row ]
 [ , DATEFORMAT = 'date_format' ]
 [ , ENCODING = { 'UTF8' | 'UTF16' } ]
 [ , PARSER_VERSION = { '1.0' | '2.0' } ]
 [ , MATCH_COLUMN_COUNT = { 'ON' | 'OFF' } ]
)

Arguments

warehouse_name

ユーザーが操作を実行している現在のウェアハウスが、指定したテーブルのウェアハウスである場合は省略可能です。 ウェアハウスを指定せず、指定したスキーマとテーブルが現在のウェアハウスに存在しない場合、COPYは失敗し、エラーメッセージが返されます。

schema_name

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

テーブル名

データを COPY するテーブルの名前。ターゲットテーブルは、ウェアハウスに既に存在している必要があります。

(column_list)

データの読み込み中にソースデータフィールドをターゲットテーブル列にマップするために使用される列の省略可能なリスト。

column_list はかっこで囲み、コンマで区切る必要があります。構文は次のとおりです。

[(Column_name [既定のDefault_value] [Field_number |JSON_path] [,...n])]

Column_name - ターゲットテーブルの列の名前。
Default_value - 入力ファイルの NULL 値を置き換えるデフォルトの値です。既定値はすべてのファイル形式に適用されます。 COPY カラムリストからカラムが省略されているか、入力ファイルフィールドが空の場合に入力ファイルから NULL を読み込もうとします。既定値の前にキーワード 'default' を指定します
Field_number - CSV ファイルにのみ適用されます。入力データ内のフィールドの序数位置を指定します。フィールドのインデックスは 1 から開始されます。
JSON_path - JSONL ファイルにのみ適用されます。各 JSON オブジェクトから抽出するフィールドを識別する JSON パス式を指定します (例: $.CustomerName)。

column_listを指定しない場合、COPYはソースとターゲットの順序に基づいて列をマップします。入力フィールド 1 はターゲット列 1 に、フィールド 2 は列 2 に移動します。

Note

Microsoft Fabric のウェアハウスで Parquet ファイルを使用しているとき、列名はソースとコピー先で正確に一致する必要があります。ターゲットテーブル内の列の名前が Parquet ファイルの列名と異なる場合、ターゲットテーブルの列には NULL が入力されます。

外部の場所

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

Blob Storage の "外部の場所": https://<account\>.blob.core.windows.net/<container\>/<path\>
ADLS Gen2 の "外部の場所": https://<account\>.dfs.core.windows.net/<container\>/<path\>
OneLake の外部の場所:https://onelake.dfs.fabric.microsoft.com/<workspaceId>/<lakehouseId>/Files/

Azure Data Lake Storage (ADLS) Gen2 では、Azure Blob Storage (レガシ) よりも優れたパフォーマンスが提供されます。可能な限り、ADLS Gen2 アカウントの使用を検討してください。

Note

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

Account - ストレージアカウント名
Container - BLOB コンテナー名
Path - データのフォルダーまたはファイルのパス。場所はコンテナーから始まります。フォルダーを指定すると、 COPY はフォルダーとそのすべてのサブフォルダーからすべてのファイルを取得します。 COPY は非表示のフォルダーを無視し、パスで明示的に指定しない限り、下線 (_) またはピリオド (.) で始まるファイルを返しません。この動作は、ワイルドカードを使ってパスを指定した場合も同じです。

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

ワイルドカードパス名の一致では、大文字と小文字が区別されます
円記号 (\) を使用してワイルドカードをエスケープできます。

Note

次のようなコンマ区切りのリストを使用して、同じストレージアカウントとコンテナーからのみ複数のファイルの場所を指定できます。

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

ファイアウォールの内側の外部の場所

ファイアウォールの背後にある Azure Data Lake Storage (ADLS) Gen2 と Azure Blob Storage の場所にあるファイルにアクセスするには、次の前提条件が適用されます。

ウェアハウスをホストするワークスペースの ワークスペース ID をプロビジョニングする必要があります。ワークスペース ID を設定する方法の詳細については、「 Workspace ID」を参照してください。
Entra ID アカウントでワークスペース ID を使用できる必要があります。
Entra ID アカウントは、 Azure ロールベースのアクセス制御 (RBAC) または data lake ACL を使用して、基になるファイルにアクセスできる必要があります。
ウェアハウスをホストする Fabric ワークスペースは、 リソースインスタンスルールとして追加する必要があります。リソースインスタンスルールを使用して Fabric ワークスペースを追加する方法の詳細については、「リソースインスタンスルールを参照してください。

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

FILE_TYPE は、外部データの形式を指定します。

CSV: RFC 4180 標準に準拠したコンマ区切り値ファイルを指定します。
JSONL: 改行で区切られた JSON (JSON Lines) ファイルを指定します。各行は有効な JSON オブジェクトです。
PARQUET: Parquet 形式を指定します。

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

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

Fabric Data Warehouse の場合:

COPY INTO は、パブリックアクセスが無効になっている場合はサポートされていません。
パブリックストレージアカウントの場合、サポートされている認証メカニズムは、Microsoft Entra ID、Shared Access Signature (SAS)、またはストレージアカウントキー (SAK) です。
ファイアウォールの内側にあるパブリックストレージアカウントの場合、サポートされている認証方法は Microsoft Entra ID のみです。 COPY INTO OneLake をソースとして使用すると、EntraID 認証のみがサポートされます。

ユーザーのMicrosoft Entra ID認証は既定です。資格情報を指定する必要はありません。

Shared Access Signature (SAS) を使用した認証
- IDENTITY: Shared Access Signatureの値を持つ定数。
- SECRET: 共有アクセス署名は、ストレージアカウント内のリソースへの委任されたアクセスを提供します。
- 必要な最小権限: READ と LIST。
ストレージアカウントキーを使用した認証
- IDENTITY: Storage Account Keyの値を持つ定数。
- SECRET: ストレージアカウントキー。

ERRORFILE = ディレクトリの場所

ERRORFILE は CSV と JSONL に適用されます。拒否された行と該当するエラーファイルが書き込まれるディレクトリを指定します。ストレージアカウントからの完全なパス、またはコンテナーに対する相対パスを指定できます。指定されたパスが存在しない場合、システムはユーザーに代わってパスを作成します。子ディレクトリは、 _rejectedrowsという名前で作成されます。 _文字を指定すると、location パラメーターに明示的に名前を付けない限り、他のデータ処理でディレクトリがエスケープされます。

Note

ERRORFILEに相対パスを渡すときは、external_locationで指定したコンテナーパスを基準にして相対パスにします。

このディレクトリ内では、 YearMonthDay -HourMinuteSecond 形式 (たとえば、 20180330-173205) で、読み込み送信の時刻に基づいてフォルダーが作成されます。このフォルダーでは、ウェアハウスによってステートメント ID を持つフォルダーが作成され、そのフォルダーの下に、エラーという 2 種類のファイルが書き込まれます。拒否の理由を含む Json ファイルと、拒否された行を含む row.csv ファイル。

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

ファイアウォールで保護された Azure Storage アカウントを使用する場合、エラーファイルはストレージアカウントパスで指定されたのと同じコンテナーに作成されます。このシナリオで ERRORFILE オプションの使用を検討する場合は、 MAXERROR パラメーターを指定する必要もあります。 ERRORFILEにストレージアカウントの完全なパスが定義されている場合は、そのストレージへの接続にERRORFILE_CREDENTIALが使用されます。それ以外の場合は、 CREDENTIAL に記載されている値が使用されます。

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

ERRORFILE_CREDENTIAL は、CSV ファイルと JSONL ファイルに適用されます。 Microsoft Fabric のウェアハウスでは、サポートされている認証メカニズムは Shared Access Signature (SAS) のみです。

Shared Access Signature (SAS) を使用した認証
- IDENTITY: 値が ᠒の定数 Shared Access Signature
- SECRET: 共有アクセス署名は、ストレージアカウント内のリソースへの委任されたアクセスを提供します。
最低限必要な権限: READ、LIST、WRITE、CREATE、DELETE

Note

MAXERRORS = max_errors

MAXERRORS は CSV と JSONL に適用されます。 COPY操作が失敗するまでの読み込みで許可される拒否行の最大数を指定します。 COPY操作でインポートできない行は無視され、エラーとしてカウントされます。エラーの最大数を指定しない場合、既定値は 0 です。

Fabric Data Warehouseでは、FILE_TYPE が PARQUET の場合、MAXERRORS を使用することはできません。

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

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

CSV では GZIP がサポートされます。
Parquet では、GZIP と Snappy がサポートされます。
JSONL ではサポートされていません

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

.gz - Gzip

圧縮ファイルの読み込みは現在、パーサーバージョン 1.0 でのみサポートされています。

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

FIELDQUOTE = 'field_quote'

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

Note

FIELDQUOTE 文字は、二重 FIELDQUOTE (区切り記号) が存在する文字列列でエスケープされます。

フィールドターミネーター = 'field_terminator'

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

ROWTERMINATOR = 'row_terminator'

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

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

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

FIRSTROW = First_row_int

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

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

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

ENCODING = 'UTF8' |'UTF16'

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

PARSER_VERSION = { '1.0' |'2.0' }

PARSER_VERSION は CSV ファイルにのみ適用されます。既定値は 2.0 です。 PARSER_VERSION は、ソースファイルの種類が CSV の場合にインジェストに使用されるファイルパーサーを指定します。 2.0 パーサーは、CSV ファイルの取り込みのパフォーマンスを向上させます。

パーサーバージョン 2.0 には、次の制限があります。

圧縮された CSV ファイルはサポートされていません。
UTF-16 エンコードのファイルはサポートされていません。
マルチ文字またはマルチバイトの ROWTERMINATOR、 FIELDTERMINATOR、または FIELDQUOTE はサポートされていません。しかし、 \r\n はデフォルトの ROWTERMINATORとして受け入れられています。

UTF-8 ファイルでパーサーバージョン 1.0 を使用する場合、マルチバイトターミネータとマルチ文字ターミネータは FIELDTERMINATORではサポートされません。

パーサーバージョン 1.0 は、下位互換性のためにのみ使用できます。これらの制限が発生した場合にのみ使用してください。

Note

圧縮された CSV ファイルまたは UTF-16 エンコードのファイルで COPY INTO を使用すると、 COPY INTO 自動的に PARSER_VERSION 1.0 に切り替わるので、ユーザー操作は必要ありません。 FIELDTERMINATORまたはROWTERMINATORのマルチ文字ターミネータの場合、COPY INTO ステートメントは失敗します。マルチ文字区切り記号が必要な場合は、 PARSER_VERSION = '1.0' を使用します。

MATCH_COLUMN_COUNT = { 'ON' |'OFF' }

MATCH_COLUMN_COUNT は CSV ファイルにのみ適用されます。既定値は OFF です。 COPY コマンドで、ソースファイル内の列数行がコピー先テーブルの列数と一致するかどうかを確認するかどうかを指定します。次の動作が適用されます。

MATCH_COLUMN_COUNTがOFFの場合:
- このコマンドは、ソース行の列を超える列を無視します。
  - このコマンドは、列数が少ない行に対して null 許容列に NULL 値を挿入します。
- null 非許容列に値が指定されていない場合、 COPY コマンドは失敗します。
MATCH_COLUMN_COUNTがONの場合:
- COPYコマンドは、ソースからの各ファイルの各行の列数が宛先テーブルの列数と一致しているかを確認します。
列数が一致しない場合、 COPY コマンドは失敗します。

Note

MATCH_COLUMN_COUNT は、 MAXERRORSとは別に動作します。列数の不一致により、MAXERRORSに関係なくCOPY INTOが失敗します。

OneLake で COPY INTO を使用する

COPY INTO を使用して、Fabric OneLake に格納されているファイルから既存の項目の下にデータを直接読み込みます。この方法により、ADLS Gen2 や Blob Storage などの外部ステージングアカウントが不要になり、Fabricアクセス許可を使用してワークスペースで管理される SaaS ネイティブインジェストが可能になります。この機能では、次の機能がサポートされます。

ワークスペースとアイテム内の任意の場所からの読み取り
ワークスペースからウェアハウスへの読み込み (同じテナント内)
Microsoft Entra IDを使用したネイティブ ID の適用

Example:

COPY INTO t1
FROM 'https://onelake.dfs.fabric.microsoft.com/<workspaceId>/<lakehouseId>/Files/*.csv'
WITH (
    FILE_TYPE = 'CSV',
    FIRSTROW = 2
);

Permissions

コントロールプレーンのアクセス許可

COPY INTO コマンドを実行するには、少なくともビューアーロールを持つワークスペースの管理アクセス権を使用して、ワークスペースロールのメンバーシップを付与する必要があります。または、Fabric ポータルの Item Permissions を介して、少なくとも読み取りアクセス許可を持つユーザーとウェアハウスアクセスを共有することもできます。最小特権の原則に合わせるには、読み取りアクセス許可で十分です。

データプレーンのアクセス許可

ワークスペースロールまたは項目のアクセス許可を使用してコントロールプレーンのアクセス許可を付与した後、ユーザーがデータプレーンレベルで読み取りアクセス許可のみを持っている場合は、T-SQL コマンドを使用してユーザーに INSERT と ADMINISTER DATABASE BULK OPERATIONS のアクセス許可も付与します。

たとえば、次の T-SQL スクリプトは、Microsoft Entra IDを使用して個々のユーザーにこれらのアクセス許可を付与します。

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

GRANT INSERT to [mike@contoso.com];
GO

エラーファイルオプションを使用する場合、ユーザーはストレージアカウントコンテナーの共同作成者Blob Storage最小限のアクセス許可を持っている必要があります。

ソースとして OneLake を使用する場合、ユーザーはソース ワークスペース (Lakehouse が配置されている場所) とターゲット ワークスペース (Warehouse が存在する場所) の両方に対する共同作成者以上のアクセス許可を持っている必要があります。 Microsoft Entra IDとFabricワークスペースロールは、すべてのアクセスを制御します。

Remarks

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

COPY INTO ステートメントには、個々の varchar(max) 列と varbinary(max) 列のサイズと、取り込むことができる行の合計サイズに制限があります。

Parquet: 最大 varchar(max)/varbinary(max) 列サイズ 16 MB、最大行サイズ 1 GB。
CSV および JSONL: 最大 varchar(max)/varbinary(max) 列サイズ 1 MB、最大行サイズ 16 MB。

確実に実行できるように、 COPY INTO 操作中にソースファイルとフォルダーを変更しないでください。

コマンドの実行中に参照されているファイルまたはフォルダーを変更、削除、または置き換えると、操作が失敗したり、データインジェストに不整合が生じたりする可能性があります。
COPY INTOを実行する前に、すべてのソースデータが安定していて、プロセス中に変更されていないことを確認します。

ソースデータの有効桁数が変換先列の定義よりも大きい場合、数値、日付、および時刻型の場合、値は丸められずに切り捨てられます。

ソースとしての OneLake の制限事項

Microsoft Entra ID 認証のみサポートしています。 SAS トークン、共有キー、接続文字列などの他の認証方法は許可されません。
倉庫アイテム は、ソースの場所としてサポートされていません。ファイルは、OneLake ストレージを介してファイルを公開する他の Fabric 項目から生成される必要があります。
OneLake パスでは、ワークスペース ID とウェアハウス ID を使用する必要があります。 現時点では、ワークスペースまたは Lakehouse のフレンドリ名はサポートされていません。
共同作成者のアクセス許可は、両方のワークスペースで必要です。 実行中のユーザーは、ソースの Lakehouse ワークスペースとターゲット Warehouse ワークスペースに対して、少なくとも共同作成者ロールを持っている必要があります。

Examples

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

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

COPYコマンドのデフォルト値は以下の通りです:

MAXERRORS = 0
COMPRESSION (既定値は非圧縮)
FIELDQUOTE = '"'
FIELDTERMINATOR = ','
ROWTERMINATOR = '\n'

Important

COPY \nを内部的に\r\nとして扱う。詳細については、「ROWTERMINATOR」のセクションを参照してください。
FIRSTROW = 1
ENCODING = 'UTF8'
FILE_TYPE = 'CSV'

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>'),
    FIELDQUOTE = '"',
    FIELDTERMINATOR = ';',
    ROWTERMINATOR = '0X0A',
    ENCODING = 'UTF8',
    MAXERRORS = 10,
    ERRORFILE = '/errorsfolder'--path starting from the storage container
)

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

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

--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>'),
    FIELDQUOTE = '"',
    FIELDTERMINATOR=',',
    ROWTERMINATOR='0x0A',
    ENCODING = 'UTF8',
    FIRSTROW = 2
)

D. Parquet を読み込む

この例では、実行中のユーザーのEntra IDを使用して、ワイルドカードを使用してフォルダーのすべての Parquet ファイルを読み込みます。

COPY INTO test_parquet
FROM 'https://myaccount.blob.core.windows.net/myblobcontainer/folder1/*.parquet'
WITH (
    FILE_TYPE = 'PARQUET'
)

E. JSONL を読み込む

この例では、ワイルドカードを使用して、実行中のユーザーのEntra IDを使用してフォルダーの下にあるすべての JSONL ファイルを読み込みます。

COPY INTO test_jsonl
FROM 'https://myaccount.blob.core.windows.net/myblobcontainer/folder1/*.jsonl'
WITH (
    FILE_TYPE = 'JSONL'
)

F. JSONL ドキュメントのフィールドパスに列名をマップする

次の例は、各行が 1 つの JSON オブジェクトを表す JSON Lines (JSONL) ファイルを示しています。

{"CountryKey": 0, "CountryName": "ALGERIA", "RegionID": 0, "Population": 34800000}
{"CountryKey": 1, "CountryName": "ARGENTINA", "RegionID": 1, "Population": 46044703}
{"CountryKey": 2, "CountryName": "BRAZIL", "RegionID": 1, "Population": 203080756}

COPY INTOでは、JSON パス式を使用してテーブル列を特定の JSON フィールドにマップできます。このマッピングを使用すると、ソースデータから必須フィールドのみを取り込めます。

COPY INTO Countries (
  CountryID '$.CountryKey', 
  CountryName '$.CountryName', 
  RegionID '$.RegionKey', 
  Population '$.Population'
)
FROM 'https://myaccount.blob.core.windows.net/myblobcontainer/folder1/countries.jsonl'
WITH (   
    FILE_TYPE = 'JSONL' 
)

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

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= 'Shared Access Signature', SECRET='<Your_SAS_Token>')
    FIELDTERMINATOR = '|'
)

H. OneLake からデータを読み込む

COPY INTO t1
FROM 'https://onelake.dfs.fabric.microsoft.com/<workspaceId>/<lakehouseId>/Files/*.csv'
WITH (
    FILE_TYPE = 'CSV',
    FIRSTROW = 2
);

フィードバック

このページはお役に立ちましたか?

Last updated on 2026-05-04

コピー先 (Transact-SQL)

Syntax

Arguments

schema_name

テーブル名

(column_list)

外部の場所

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

FILE_FORMAT = external_file_format_name

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

ERRORFILE = ディレクトリの場所

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

MAXERRORS = max_errors

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

FIELDQUOTE = 'field_quote'

フィールドターミネーター = 'field_terminator'

ROWTERMINATOR = 'row_terminator'

FIRSTROW = First_row_int

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

ENCODING = 'UTF8' |'UTF16'

IDENTITY_INSERT = 'ON' |'OFF'

AUTO_CREATE_TABLE = { 'ON' |'OFF' }

Permissions

Remarks

Examples

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

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

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

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

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

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

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

FAQ

COPY コマンドのパフォーマンスと PolyBase の比較

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

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

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

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

関連コンテンツ

Syntax

Arguments

warehouse_name

schema_name

テーブル名

(column_list)

外部の場所

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

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

ERRORFILE = ディレクトリの場所

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

MAXERRORS = max_errors

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

FIELDQUOTE = 'field_quote'

フィールドターミネーター = 'field_terminator'

ROWTERMINATOR = 'row_terminator'

FIRSTROW = First_row_int

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

ENCODING = 'UTF8' |'UTF16'

PARSER_VERSION = { '1.0' |'2.0' }

MATCH_COLUMN_COUNT = { 'ON' |'OFF' }

OneLake で COPY INTO を使用する

Permissions

コントロール プレーンのアクセス許可

データ プレーンのアクセス許可

Remarks

ソースとしての OneLake の制限事項

Examples

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

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

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

D. Parquet を読み込む

E. JSONL を読み込む

F. JSONL ドキュメントのフィールド パスに列名をマップする

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

H. OneLake からデータを読み込む

関連コンテンツ

フィードバック

その他のリソース

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

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

コントロールプレーンのアクセス許可

データプレーンのアクセス許可

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

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

F. JSONL ドキュメントのフィールドパスに列名をマップする