次の方法で共有


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

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 コマンドを実行するユーザーには次の権限が必要です。

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
    

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

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

Microsoft Fabric では、現在、COPY (Transact-SQL) ステートメントで PARQUET および CSV ファイル形式がサポートされています。 データ ソースについては、Azure Data Lake Storage Gen2 アカウントのみがサポートされています。

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

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

Note

Azure Synapse Analytics の場合は、「Azure Synapse Analytics の COPY INTO」を参照してください。

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

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

構文

COPY INTO [ warehouse_name. ] [ schema_name. ] table_name
[ (Column_list) ]
FROM '<external_location>' [ , ...n ]
WITH
 (
 [ FILE_TYPE = { 'CSV' | '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 ]
 [ , ENCODING = { 'UTF8' | 'UTF16' } ]
 [ , PARSER_VERSION = { '1.0' | '2.0' } ]
)

引数

warehouse_name

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

schema_name

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

table_name

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

(column_list)

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

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

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

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

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

注意

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

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

外部の場所

Note

Fabric OneLake パスは現在サポートされていません。サポートされているのは BLOB ストレージ アカウントと ADLS Gen2 ストレージ アカウントのみです。

データを含むファイルがステージングされる場所を指定します。 現在、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\>

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

Note

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

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

  • Container - BLOB コンテナー名

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

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

  • ワイルドカード パス名の一致では、大文字と小文字が区別されます
  • ワイルドカードをエスケープするには、バックスラッシュ (\) を使用します

注意

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

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

  • 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 の場所にあるファイルにアクセスするには、次の前提条件が適用されます。

FILE_TYPE = { 'CSV' | 'PARQUET' }

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

  • CSV: RFC 4180 標準に準拠しているコンマ区切り値ファイルを指定します。
  • PARQUET: Parquet 形式を指定します。

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

CREDENTIAL は、外部ストレージ アカウントにアクセスするための認証メカニズムを指定します。 Microsoft Fabric のウェアハウスでは、サポートされている認証メカニズムは Shared Access Signature (SAS) およびストレージ アカウント キー (SAK) のみです。 ユーザーの EntraID 認証は既定で、資格情報を指定する必要はありません。

Note

パブリック ストレージ アカウントを使用する場合、CREDENTIAL を指定する必要はありません。 既定では、実行中のユーザーの Entra ID が使用されます。

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

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

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

ERRORFILE = Directory Location

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

Note

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

このディレクトリ内には、YearMonthDay -HourMinuteSecond (例: 20180330-173205) のロード サブミッション時間に基づいて作成されたフォルダーがあります。 このフォルダーに、ステートメント ID が付いたフォルダーが作成され、そのフォルダー内に、2 種類のファイル (拒否の理由を含む error.Json ファイルと 拒否された行を含む row.csv ファイル) が書き込まれます。

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

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

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

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

注意

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

MAXERRORS = max_errors

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

Microsoft Fabric では、FILE_TYPEが 'PARQUET' の場合、MAXERRORS を使用できません。

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

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

  • CSV は GZIP をサポートしています
  • Parquet は GZIP および Snappy をサポートしています

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

  • .gz - GZIP

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

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 ではサポートされていません。

ROWTERMINATOR = 'row_terminator'

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

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

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

FIRSTROW = First_row_int

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

ENCODING = 'UTF8' | 'UTF16'

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

PARSER_VERSION = { '1.0' |'2.0' }

PARSER_VERSION は CSV にのみ適用されます。 既定値は 2.0 です。 ソース ファイルの種類が 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' を使用します。

解説

ウェアハウスの COPY INTO では、日付文字列を解釈するための日付形式を設定できません。 既定では、すべての日付が month-day-year 形式と見なされます。 異なる日付形式の CSV ファイルを取り込むには、SET DATEFORMAT を使用して、セッション レベルで目的の日付形式を指定します。 詳細については、「SET DATEFORMAT (Transact-SQL)」を参照してください。

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

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

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

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

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

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

  • MAXERRORS = 0

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

  • FIELDQUOTE = '"'

  • FIELDTERMINATOR = ','

  • ROWTERMINATOR = '\n'

重要

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

  • FIRSTROW = 1

  • ENCODING = 'UTF8'

  • FILE_TYPE = 'CSV'

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',
    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>'),
    --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 を読み込む

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

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

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

よく寄せられる質問

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

特にファイルの数が少ない場合は、大きな CSV ファイルを分割することを検討してください。ただし、パフォーマンスを向上させるために、ファイルはそれぞれ 4 MB 以上にしてください。

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

特にファイルの数が少ない場合は、大きな Parquet ファイルを分割することを検討してください。

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

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

資格情報を指定しない場合、どのような認証方法が使用されますか?

既定では、 COPY INTRO は実行中のユーザーの Entra ID を使用します。