COPY INTO (Transact-SQL)

Область применения:Azure Synapse Analytics

В этой статье объясняется, как использовать инструкцию COPY в Azure Synapse Analytics для загрузки из внешних учетных записей хранения. Инструкция COPY обеспечивает наибольшую гибкость приема данных с высокой пропускной способностью в Azure Synapse Analytics.

COPY предоставляет следующие возможности:

• выполнять загрузку пользователям с более низкими привилегиями, без ограничения разрешений на управление хранилищем данных;
• Выполнение одной инструкции T-SQL без необходимости создавать другие объекты базы данных
• Правильное синтаксический анализ и загрузка CSV-файлов, где разделители (строка, поле, строка) экранируются в столбцах с разделителями строк
• указывать более детализированную модель разрешений без предоставления ключей учетной записи хранения с помощью подписанных URL-адресов (SAS);
• использовать другую учетную запись хранения для расположения ERRORFILE (REJECTED_ROW_LOCATION);
• Настроить значения по умолчанию для каждого целевого столбца и указать поля исходных данных для загрузки в определенные целевые столбцы.
• Указание пользовательского конца строки, конца поля и кавычки полей для CSV-файлов
• Использование форматов даты SQL Server для CSV-файлов
• Указать подстановочные знаки и несколько файлов в пути места хранения.
• Автоматическое обнаружение схемы упрощает процесс определения и сопоставления исходных данных с целевыми таблицами.
• Процесс автоматического создания таблиц автоматически создает таблицы и работает вместе с автоматическим обнаружением схемы.
• Прямая загрузка сложных типов данных из файлов Parquet, таких как Карты и списки, в строковые столбцы без использования других средств для предварительной обработки данных

Подробные примеры и краткие руководства по использованию инструкции COPY см. в следующей документации.

• Краткое руководство. Массовая загрузка данных с помощью инструкции COPY
• Краткое руководство. Примеры использования инструкции COPY и поддерживаемых методов проверки подлинности
• Краткое руководство. Создание инструкции COPY с помощью полнофункционального пользовательского интерфейса Synapse Studio

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 отменяется и возвращается сообщение об ошибке.

table_name

Имя таблицы для копирования данных. Целевой таблицей может быть временная или постоянная таблица, которая уже должна существовать в базе данных. Для режима автоматического обнаружения схем не укажите список столбцов.

(column_list)

Необязательный список одного или нескольких столбцов, используемых для сопоставления полей исходных данных с целевыми столбцами таблицы для загрузки данных.

Не указывайте column_list , когда AUTO_CREATE_TABLE = 'ON'.

Список column_list должен быть заключен в круглые скобки, а его элементы должны разделяться запятыми. Список столбцов указывается в следующем формате:

[(имя_столбца [значение_по_умолчанию] [номер_поля] [,...n])]

• Column_name — имя столбца в целевой таблице.
• Default_value — значение по умолчанию, заменяющее любое значение NULL в входном файле. Значение по умолчанию применяется ко всем форматам файлов. COPY пытается загрузить ЗНАЧЕНИЕ NULL из входного файла, если столбец опущен из списка столбцов или когда есть пустое поле входного файла. Значение по умолчанию предшествует ключевому слову default
• Field_number — номер поля входного файла, сопоставленного с целевым столбцом.
• Индексирование полей начинается с 1.

Если список столбцов не указан, copy сопоставляет столбцы на основе исходного и целевого порядка: поле ввода 1 переходит в целевой столбец 1, поле 2 переходит к столбцу 2 и т. д.

External locations

Места размещения файлов, содержащих данные. Сейчас поддерживаются Azure Data Lake Storage (ADLS) 2-го поколения и хранилище BLOB-объектов Azure:

• Внешнее расположение для хранилища BLOB-объектов: https://<account\>.blob.core.windows.net/<container\>/<path\>
• Внешнее расположение для ADLS 2-го поколения: https://<account\>.dfs.core.windows.net/<container\>/<path\>

• Account — имя учетной записи хранения.

• Container — имя контейнера BLOB-объектов.

• Path — путь к папке или файлу данных. Расположение начинается с контейнера. Если указана папка, COPY извлекает все файлы из папки и всех ее вложенных папок. COPY игнорирует скрытые папки и не возвращает файлы, начинающиеся с подчеркивания (_) или точки (.), если в пути явно не указано. Так происходит даже при указании пути с подстановочным знаком.

Подстановочные знаки можно указывать в пути, где

• при сопоставлении имени пути с подстановочными знаками учитывается регистр;
• подстановочный знак может быть экранирован с помощью символа обратной косой черты (\);
• расширение подстановочных знаков применяется рекурсивно. Например, все CSV-файлы Customer1 в (включая подкаталоги Customer1) загружаются в следующем примере: 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).

FILE_FORMAT = external_file_format_name

FILE_FORMAT применяется только к файлам Parquet и ORC и задает имя объекта формата внешнего файла, который хранит тип файла и метод сжатия внешних данных. Чтобы создать формат внешнего файла, используйте CREATE EXTERNAL FILE FORMAT.

CREDENTIAL (IDENTITY = ', SECRET = ')

CREDENTIAL задает механизм проверки подлинности для доступа к внешней учетной записи хранения. Ниже приведены методы проверки подлинности.

	CSV	Parquet	ORC
Хранилище BLOB-объектов Azure	SAS/MSI/SERVICE PRINCIPAL/KEY/Entra	SAS/KEY	SAS/KEY
Azure Data Lake 2-го поколения	SAS/MSI/SERVICE PRINCIPAL/KEY/Entra	SAS (BLOB-объект 1 )/MSI (dfs 2 )/SERVICE PRINCIPAL/KEY/Entra	SAS (BLOB-объект 1 )/MSI (dfs 2 )/SERVICE PRINCIPAL/KEY/Entra

¹ для этого метода проверки подлинности требуется конечная точка blob (.blob.core.windows.net) в пути к внешнему расположению.

² для этого метода проверки подлинности требуется конечная точка dfs (.dfs.core.windows.net) в пути к внешнему расположению.

• Проверка подлинности на основе подписанных URL-адресов (SAS)

  • IDENTITY: константа со значением подписанного URL-адреса
  • СЕКРЕТ. Подписанный URL-адрес предоставляет делегированный доступ к ресурсам в учетной записи хранения.

• Минимальные разрешения: READ и LIST

• Проверка подлинности с помощью субъектов-служб

  • IDENTITY: <ClientID>@<OAuth_2.0_Token_EndPoint>
  • СЕКРЕТ: ключ субъекта-службы приложения Microsoft Entra

• Минимальные роли RBAC: участник данных BLOB-объектов хранилища, участник данных BLOB-объектов хранилища, владелец данных BLOB-объектов хранилища или средство чтения данных BLOB-объектов хранилища

• Проверка подлинности с помощью ключа учетной записи хранения

  • IDENTITY: константа со значением ключа учетной записи хранения

• СЕКРЕТ: ключ учетной записи хранения

• Проверка подлинности с помощью управляемого удостоверения (конечные точки службы виртуальной сети)

  • IDENTITY: константа со значением управляемого удостоверения

• Минимальные роли RBAC: участник данных BLOB-объектов хранилища или владелец данных BLOB-объектов хранилища для зарегистрированного логического сервера Microsoft Entra в Azure. При использовании выделенного пула SQL (ранее — хранилище данных SQL), не связанного с рабочей областью Synapse, эта роль RBAC не требуется, но управляемое удостоверение требует разрешений контроль доступа List (ACL) для целевых объектов для включения доступа на чтение к исходным файлам.

• Проверка подлинности с помощью пользователя Microsoft Entra

  • CREDENTIAL не требуется

• Минимальные роли RBAC: участник данных BLOB-объектов хранилища или владелец данных BLOB-объектов хранилища для пользователя Microsoft Entra

ERRORFILE = расположение каталога

ERRORFILE применяется только к CSV-файлам. Указывает каталог в инструкции COPY, в который должны записываться отклоненные строки и соответствующий файл ошибок. Можно указать полный путь из учетной записи хранения или путь относительно контейнера. Если указанный путь не существует, он создается от вашего имени. Создается дочерний каталог с именем "_rejectedrows". Благодаря наличию символа "_" каталог исключается из других процессов обработки данных, если не указан в явном виде в параметре LOCATION.

В этом каталоге создается папка, имя которой соответствует времени отправки загруженных данных в формате "ГодМесяцДень-ЧасМинутаСекунда" (например, 20180330-173205). В этой папке записываются два типа файлов, файл причины (ошибка) и файл данных (строка) каждого предварительного приложения с помощью queryID, distributionID и guid файла. Так как данные и причина хранятся в отдельных файлах, эти файлы имеют соответствующие префиксы.

Если ERRORFILE имеет полный путь к учетной записи хранения, ERRORFILE_CREDENTIAL используется для подключения к хранилищу. В противном случае используется значение, указанное для CREDENTIAL. Если те же учетные данные, используемые для исходных данных, используются для ERRORFILE, ограничения, применяемые к ERRORFILE_CREDENTIAL также применяются

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

ERRORFILE_CREDENTIAL применяется только к CSV-файлам. Поддерживаемые источники данных и методы проверки подлинности:

• Хранилище BLOB-объектов Azure — SAS/SERVICE PRINCIPAL/Entra

• Azure Data Lake 2-го поколения — SAS/MSI/SERVICE PRINCIPAL/Entra

• Проверка подлинности на основе подписанных URL-адресов (SAS)

  • IDENTITY: константа со значением подписанного URL-адреса
  • СЕКРЕТ. Подписанный URL-адрес предоставляет делегированный доступ к ресурсам в учетной записи хранения.

• Минимальные разрешения: READ, LIST, WRITE, CREATE, DELETE

• Проверка подлинности с помощью субъектов-служб

  • IDENTITY: <ClientID>@<OAuth_2.0_Token_EndPoint>
  • СЕКРЕТ: ключ субъекта-службы приложения Microsoft Entra

• Минимальные роли RBAC: участник данных BLOB-объектов хранилища или владелец данных BLOB-объектов хранилища

• Проверка подлинности с помощью управляемого удостоверения (конечные точки службы виртуальной сети)

  • IDENTITY: константа со значением управляемого удостоверения

• Минимальные роли RBAC: участник данных BLOB-объектов хранилища или владелец данных BLOB-объектов хранилища для зарегистрированного База данных SQL сервера Microsoft Entra

• Проверка подлинности с помощью пользователя Microsoft Entra

  • CREDENTIAL не требуется

• Минимальные роли RBAC: участник данных BLOB-объектов хранилища или владелец данных BLOB-объектов хранилища для пользователя Microsoft Entra

Использование ключа учетной записи хранения с ERRORFILE_CREDENTIAL не поддерживается.

MAXERRORS = max_errors

MAXERRORS указывает максимальное число строк отклонения, разрешенных в нагрузке до сбоя операции COPY. Каждая строка, которую невозможно импортировать операцией COPY, игнорируется и считается одной ошибкой. Если 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 - Живой
• .deflate - DefaultCodec (только Parquet и ORC)

Команда COPY требует, чтобы файлы gzip не содержали конечный мусор для нормальной работы. Формат gzip строго требует, чтобы файлы были состоят из допустимых членов без дополнительных сведений до, между ними или после них. Любое отклонение от этого формата, например наличие конечных данных, отличных от gzip, приведет к сбою команды COPY. Убедитесь, что в конце файлов gzip нет конечного мусора, чтобы убедиться, что COPY может успешно обработать эти файлы.

FIELDQUOTE = "field_quote"

FIELDQUOTE применяется к CSV-файлу и задает один символ, используемый в качестве символа кавычки (разделителя строк) в CSV-файле. Если не указано, символ кавычки (") используется в качестве символа кавычки, как определено в стандарте RFC 4180. Шестнадцатеричная нотация также поддерживается для FIELDQUOTE. Расширенные символы ASCII и многобайтовые символы не поддерживаются с UTF-8 для FIELDQUOTE.

FIELDTERMINATOR = "field_terminator"

FIELDTERMINATOR применяется только к CSV-файлам. Указывает конечный элемент поля, используемый в CSV-файле. Признак конца поля можно указать в шестнадцатеричном представлении. Признак конца поля может состоять из нескольких символов. Признак конца поля по умолчанию — (,). Расширенные символы ASCII и многобайтовые символы не поддерживаются в UTF-8 для FIELDTERMINATOR.

ROW TERMINATOR = "row_terminator"

ROW TERMINATOR применяется только к CSV-файлам. Указывает терминатор строки, используемый в CSV-файле. Признак конца строки можно указать в шестнадцатеричном представлении. Признак конца строки может состоять из нескольких символов. По умолчанию терминатор строки имеет значение \r\n.

Команда COPY префиксирует \r символ при указании \n (newline) в результате \r\n. Чтобы указать только \n символ, используйте шестнадцатеричную нотацию (0x0A). При указании терминаторов строк с несколькими символами в шестнадцатеричном режиме не указывайте 0x между каждым символом.

Расширенные символы ASCII и многобайтовые символы не поддерживаются с UTF-8 для ROW TERMINATOR.

FIRSTROW = First_row_int

FIRSTROW применяется к CSV-файлам и указывает номер строки, которая считывается первой во всех файлах для команды COPY. Значения начинаются с 1. 1 — значение по умолчанию. Если задано значение 2, первая строка в каждом файле (строка заголовка) при загрузке данных пропускается. Строки пропускаются по признакам конца строк.

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

DATEFORMAT применяется только к CSV-файлам и задает формат даты для сопоставления с форматами дат SQL Server. Обзор всех типов данных и функций даты и времени в языке Transact-SQL см. в статье Типы данных и функции даты и времени (Transact-SQL). Параметр DATEFORMAT в команде COPY имеет более высокий приоритет, чем параметр DATEFORMAT, настроенный на уровне сеанса.

ENCODING = "UTF8" | "UTF16"

ENCODING применяется только к CSV-файлам. По умолчанию используется UTF8. Задает стандарт кодирования данных для файлов, загруженных командой COPY.

IDENTITY_INSERT = "ON" | "OFF"

IDENTITY_INSERT указывает, будет ли значение или значения идентификаторов в файле импортированных данных использоваться для столбца идентификаторов. Если параметру IDENTITY_INSERT задано значение OFF (по умолчанию), значения идентификаторов для этого столбца проверяются, но не импортируются. Обратите внимание на следующее поведение команды COPY.

• Если IDENTITY_INSERT имеет значение OFF, а таблица содержит столбец удостоверений
  • Необходимо указать список столбцов, который не сопоставляет поле ввода с столбцом удостоверений.
• Если IDENTITY_INSERT имеет значение ON, а таблица содержит столбец удостоверений
  • передаваемый список столбцов должен сопоставлять поле ввода со столбцом идентификаторов.
• Значение по умолчанию не поддерживается для СТОЛБЦА IDENTITY в списке столбцов.
• IDENTITY_INSERT задается только для одной таблицы за раз.

Azure Synapse Analytics автоматически назначает уникальные значения на основе начальных и добавочных значений, указанных во время создания таблицы.

AUTO_CREATE_TABLE = { "ON" | "OFF" }

AUTO_CREATE_TABLE указывает, можно ли автоматически создать таблицу вместе с автоматическим обнаружением схемы. Он доступен только для файлов Parquet.

• ON — включает автоматическое создание таблиц. Процесс COPY INTO автоматически создает новую таблицу, обнаружив структуру файла, которую нужно загрузить. Также можно использовать с предварительно созданными таблицами, чтобы воспользоваться преимуществами автоматического обнаружения схем файлов Parquet.
• OFF: автоматическое создание таблицы не включено. Default.

Не загружайтесь в хэш-распределенные таблицы из файлов Parquet с помощью COPY INTOAUTO_CREATE_TABLE = 'ON'.

Если файлы Parquet необходимо загрузить в хэш-распределенные таблицы с помощью COPY INTO, загрузите его в промежуточную таблицу круглого перебора, за которой следует INSERT ... SELECT из этой таблицы в целевую распределенную хэш-таблицу.

Permissions

Пользователь, выполняющий команду COPY, должен иметь следующие разрешения:

• АДМИНИСТРИРОВАНИЕ МАССОВЫХ ОПЕРАЦИЙ БАЗЫ ДАННЫХ
• INSERT

Требует разрешений INSERT и ADMINISTER BULK OPERATIONS. В Azure Synapse Analytics, INSERT и MANAGEMENT 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 для параметров строк и команд. Исходные файлы или параметры (например, ROW TERMINATOR или FIELD TERMINATOR), которые используют недопустимые символы, могут интерпретироваться неправильно инструкцией COPY и вызывать непредвиденные результаты, такие как повреждение данных или другие сбои. Перед вызовом инструкции COPY убедитесь, что исходные файлы и параметры соответствуют UTF-8 или UTF-16.

Examples

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"

• FIRSTROW = 1

• ENCODING = "UTF8"

• FILE_TYPE = "CSV"

• IDENTITY_INSERT = "OFF"

B. Загрузка с проверкой подлинности с помощью подписи общего доступа (SAS)

В следующем примере производится загрузка файлов, в которых в качестве признака конца строки используется символ перевода строки, как в файлах UNIX. В этом примере также используется ключ SAS для проверки подлинности в Хранилище BLOB-объектов Azure.

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

FAQ

Какова производительность команды COPY по сравнению с PolyBase?

Команда COPY имеет более высокую производительность в зависимости от рабочей нагрузки.

• Сжатые файлы нельзя разделить автоматически. Для повышения производительности загрузки рекомендуется разделить входные данные на несколько файлов при загрузке сжатых CSV.

• Большие несжатые CSV-файлы могут быть разделены и загружены параллельно автоматически, поэтому в большинстве случаев не требуется вручную разделять несжатые CSV-файлы. В некоторых случаях, когда автоматическое разделение файлов невозможно из-за характеристик данных, разделение больших CSV вручную может по-прежнему повысить производительность.

Что такое руководство по разделиванию файлов для команды COPY, загружающей сжатые CSV-файлы?

Руководство по количеству файлов описано в следующей таблице. После достижения рекомендуемого количества файлов у вас будет более высокая производительность. Количество файлов определяется числом вычислительных узлов, умноженных на 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

Каковы рекомендации по разделению файлов при использовании команды COPY для загрузки файлов Parquet или ORC?

Не нужно разделять файлы Parquet и ORC, так как команда COPY автоматически разбивает файлы. Для оптимальной производительности файлы Parquet и ORC в учетной записи хранения Azure должны иметь размер не менее 256 МБ.

Есть ли ограничения на число или размер файлов?

Ограничение на количество или размер файлов отсутствует, но для обеспечения оптимальной производительности мы рекомендуем использовать файлы размером не менее 4 МБ. Кроме того, ограничение количества исходных файлов не более 5000 файлов для повышения производительности.

Существуют ли известные проблемы с инструкцией COPY?

Если у вас есть рабочая область Azure Synapse, созданная до 7 декабря 2020 г., при проверке подлинности с помощью управляемого удостоверения может возникнуть аналогичное сообщение об ошибке: com.microsoft.sqlserver.jdbc.SQLServerException: Managed Service Identity has not been enabled on this server. Please enable Managed Service Identity and try again.

Чтобы обойти эту ошибку, повторно зарегистрируйте управляемое удостоверение рабочей области, выполнив указанные ниже действия.

1. Установите Azure PowerShell. См. раздел Установка PowerShell.
2. Зарегистрируйте управляемое удостоверение рабочей области с помощью PowerShell:

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

Related content

• Обзор загрузки с помощью Azure Synapse Analytics

Область применения:хранилище в Microsoft Fabric

В этой статье объясняется, как использовать инструкцию COPY в хранилище в Microsoft Fabric для загрузки из внешних учетных записей хранения. Инструкция COPY обеспечивает большую гибкость приема данных с высокой пропускной способностью в хранилище и является стратегией приема данных в хранилище.

В Microsoft Fabric инструкция COPY (Transact-SQL) в настоящее время поддерживает форматы ФАЙЛОВ PARQUET и CSV. Для источников данных поддерживаются учетные записи Azure Data Lake Storage 2-го поколения и источники OneLake.

Дополнительные сведения об использовании COPY INTO в хранилище в Microsoft Fabric см. в разделе "Прием данных в хранилище" с помощью инструкции COPY.

По умолчанию COPY INTO будет проходить проверку подлинности в качестве пользователя идентификатора записи.

COPY предоставляет следующие возможности:

• Используйте более низкие привилегии пользователей для загрузки без необходимости строгих разрешений CONTROL в хранилище данных.
• Выполните одну инструкцию T-SQL, не создавая другие объекты базы данных.
• Правильно проанализировать и загрузить CSV-файлы, где разделители (строка, поле, строка) экранируются в столбцах с разделителями строк.
• Укажите более детальную модель разрешений без предоставления ключей учетной записи хранения с помощью подписанных URL-адресов (SAS).
• Используйте другую учетную запись хранения для расположения ERRORFILE (REJECTED_ROW_LOCATION).
• Настройте значения по умолчанию для каждого целевого столбца и укажите поля исходных данных для загрузки в определенные целевые столбцы.
• Указание пользовательского конца строки, конца поля и кавычки полей для CSV-файлов
• Укажите подстановочные знаки и несколько файлов в пути расположения хранилища.
• Дополнительные сведения о параметрах приема данных и рекомендациях см. в разделе "Прием данных в хранилище" с помощью инструкции COPY.

Syntax

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 ]
 [ , DATEFORMAT = 'date_format' ]
 [ , ENCODING = { 'UTF8' | 'UTF16' } ]
 [ , PARSER_VERSION = { '1.0' | '2.0' } ]
 [ , MATCH_COLUMN_COUNT = { 'ON' | 'OFF' } ]
)

Arguments

warehouse_name

Необязательно, если текущее хранилище для пользователя, выполняющего операцию, является хранилищем указанной таблицы. Если хранилище не указано, и указанная схема и таблица не существуют в текущем хранилище, копирование завершается ошибкой, а возвращается сообщение об ошибке.

schema_name

Необязательный вариант, если схема по умолчанию для пользователя, выполняющего операцию, является схемой указанной таблицы. Если схема не указана, а схема по умолчанию для пользователя, выполняющего операцию COPY, отличается от схемы указанной таблицы, COPY отменяется и возвращается сообщение об ошибке.

table_name

Имя таблицы для копирования данных. Целевая таблица уже должна существовать в хранилище.

(column_list)

Необязательный список одного или нескольких столбцов, используемых для сопоставления полей исходных данных с целевыми столбцами таблицы для загрузки данных.

Список column_list должен быть заключен в круглые скобки, а его элементы должны разделяться запятыми. Список столбцов указывается в следующем формате:

[(имя_столбца [значение_по_умолчанию] [номер_поля] [,...n])]

• Column_name — имя столбца в целевой таблице.
• Default_value — значение по умолчанию, заменяющее любое значение NULL в входном файле. Значение по умолчанию применяется ко всем форматам файлов. COPY пытается загрузить ЗНАЧЕНИЕ NULL из входного файла, если столбец опущен из списка столбцов или когда есть пустое поле входного файла. Перед значением по умолчанию указывается ключевое слово "default".
• Field_number — номер поля входного файла, сопоставленного с целевым столбцом.
• Индексирование полей начинается с 1.

Если column_list не задано, copy сопоставляет столбцы на основе исходного и целевого порядка: поле ввода 1 переходит в целевой столбец 1, поле 2 переходит к столбцу 2 и т. д.

Если список столбцов не указан, copy сопоставляет столбцы на основе исходного и целевого порядка: поле ввода 1 переходит в целевой столбец 1, поле 2 переходит к столбцу 2 и т. д.

External location

Указывает, где хранятся файлы, содержащие данные. В настоящее время azure Data Lake Storage (ADLS) 2-го поколения, хранилище BLOB-объектов Azure и OneLake (предварительная версия) поддерживаются:

• Внешнее расположение для хранилища BLOB-объектов: https://<account\>.blob.core.windows.net/<container\>/<path\>
• Внешнее расположение для ADLS 2-го поколения: https://<account\>.dfs.core.windows.net/<container\>/<path\>
• Внешнее расположение для OneLake (предварительная версия): https://onelake.dfs.fabric.microsoft.com/<workspaceId>/<lakehouseId>/Files/

Azure Data Lake Storage (ADLS) 2-го поколения обеспечивает более высокую производительность, чем Хранилище BLOB-объектов Azure (устаревшая версия). По возможности рекомендуется использовать учетную запись ADLS 2-го поколения.

• Account — имя учетной записи хранения.

• Container — имя контейнера BLOB-объектов.

• Path — путь к папке или файлу данных. Расположение начинается с контейнера. Если указана папка, COPY извлекает все файлы из папки и всех ее вложенных папок. COPY игнорирует скрытые папки и не возвращает файлы, которые начинаются с символа подчеркивания (_) или точки (.), если это явно не указано в пути. Так происходит даже при указании пути с подстановочным знаком.

Подстановочные знаки можно включить в путь, где

• при сопоставлении имени пути с подстановочными знаками учитывается регистр;
• подстановочный знак можно экранировать с помощью символа обратной косой черты (\)

Их можно указать только из одной учетной записи хранения и контейнера в виде списка с разделителями-запятыми, например:

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

Внешние расположения за брандмауэром

Чтобы получить доступ к файлам в azure Data Lake Storage (ADLS) 2-го поколения и расположениях хранилища BLOB-объектов Azure, которые находятся за брандмауэром, применяются следующие предварительные требования:

• Необходимо подготовить удостоверение рабочей области для рабочей области, в котором размещено ваше хранилище. Дополнительные сведения о настройке удостоверения рабочей области см. в разделе "Удостоверение рабочей области".
• Учетная запись идентификатора записи должна иметь возможность использовать удостоверение рабочей области.
• Учетная запись идентификатора записи должна иметь доступ к базовым файлам с помощью управления доступом на основе ролей Azure (RBAC) или ACL озера данных.
• Рабочая область Fabric, на котором размещено хранилище, должна быть добавлена в качестве правила экземпляра ресурса. Дополнительные сведения о добавлении рабочей области Fabric с правилом экземпляра ресурса см. в разделе "Правило экземпляра ресурса".

FILE_TYPE = { "CSV" | 'PARQUET' }

FILE_TYPE задает формат внешних данных.

• CSV: указывает файл значений, разделенный запятыми, соответствующий стандарту RFC 4180 .
• PARQUET: задает формат Parquet.

CREDENTIAL (IDENTITY = ', SECRET = ')

CREDENTIAL задает механизм проверки подлинности для доступа к внешней учетной записи хранения. В хранилище в Microsoft Fabric поддерживаются только поддерживаемые механизмы проверки подлинности: подписанный URL-адрес (SAS) и ключ учетной записи хранения (SAK).

Проверка подлинности EntraID пользователя по умолчанию не требуется указывать. COPY INTO с помощью OneLake в качестве источника поддерживает только проверку подлинности EntraID.

• Проверка подлинности с помощью подписанного URL-адреса (SAS)

  • IDENTITY: константа со значением подписанного URL-адреса
  • СЕКРЕТ. Подписанный URL-адрес предоставляет делегированный доступ к ресурсам в учетной записи хранения.

• Минимальные разрешения: READ и LIST

• Проверка подлинности с помощью ключа учетной записи хранения

  • IDENTITY: константа со значением ключа учетной записи хранения

• СЕКРЕТ: ключ учетной записи хранения

ERRORFILE = расположение каталога

ERRORFILE применяется только к CSV-файлам. Указывает каталог, в котором должны быть записаны отклоненные строки и соответствующий файл ошибки. Можно указать полный путь из учетной записи хранения или путь относительно контейнера. Если указанный путь не существует, он создается от вашего имени. Создается дочерний каталог с именем "_rejectedrows". Благодаря наличию символа "_" каталог исключается из других процессов обработки данных, если не указан в явном виде в параметре LOCATION.

В этом каталоге существует папка, созданная на основе времени отправки нагрузки в формате YearMonthDay -HourMinuteSecond (например, 20180330-173205). В этой папке создается папка с идентификатором инструкции и в этой папке записываются два типа файлов: ошибка. Json-файл, содержащий причины отклонения, и файл row.csv, содержащий отклоненные строки.

Если ERRORFILE имеет полный путь к учетной записи хранения, ERRORFILE_CREDENTIAL используется для подключения к хранилищу. В противном случае используется значение, указанное для CREDENTIAL. Если те же учетные данные, используемые для исходных данных, используются для ERRORFILE, ограничения, применяемые к ERRORFILE_CREDENTIAL также применяются.

При использовании защищенной учетной записи хранения Azure брандмауэра файл ошибки будет создан в том же контейнере, указанном в пути учетной записи хранения. При использовании параметра ERRORFILES в этом сценарии также необходимо указать параметр MAXERROR. Если ERRORFILE имеет полный путь к учетной записи хранения, ERRORFILE_CREDENTIAL используется для подключения к хранилищу. В противном случае используется значение, указанное для CREDENTIAL.

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

ERRORFILE_CREDENTIAL применяется только к CSV-файлам. В хранилище в Microsoft Fabric единственным поддерживаемым механизмом проверки подлинности является подписанный URL-адрес (SAS).

• Проверка подлинности с помощью подписанных URL-адресов (SAS)
  • IDENTITY: константа со значением подписанного URL-адреса
  • СЕКРЕТ. Подписанный URL-адрес предоставляет делегированный доступ к ресурсам в учетной записи хранения.
• Минимальные разрешения: READ, LIST, WRITE, CREATE, DELETE

MAXERRORS = max_errors

MAXERRORS указывает максимальное число строк отклонения, разрешенных в нагрузке до сбоя операции COPY. Каждая строка, которую операция COPY не может импортировать, игнорируется и считается одной ошибкой. Если max_errors не задано, значение по умолчанию равно 0.

В Microsoft Fabric невозможно использовать MAXERRORS , если FILE_TYPE — PARQUET.

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

COMPRESSION является необязательным и задает метод сжатия данных для внешних данных.

• CSV-файлы поддерживают GZIP.
• Parquet поддерживает GZIP и Snappy.

Команда COPY автоматически определяет тип сжатия на основе расширения файла, если этот параметр не указан:

• .gz - GZIP

Загрузка сжатых файлов в настоящее время поддерживается только с PARSER_VERSION 1.0.

Команда COPY требует, чтобы файлы gzip не содержали конечный мусор для нормальной работы. Формат gzip строго требует, чтобы файлы были состоят из допустимых членов без дополнительных сведений до, между ними или после них. Любое отклонение от этого формата, например наличие конечных данных, отличных от gzip, приведет к сбою команды COPY. Убедитесь, что в конце файлов gzip нет конечного мусора, чтобы убедиться, что COPY может успешно обработать эти файлы.

FIELDQUOTE = "field_quote"

FIELDQUOTE применяется только к CSV-файлу. Указывает один символ, используемый в качестве символа кавычки (разделителя строк) в CSV-файле. Если не указано, символ кавычки (") используется в качестве символа кавычки, как определено в стандарте RFC 4180. Шестнадцатеричная нотация также поддерживается для FIELDQUOTE. Расширенные символы ASCII и многобайтовые символы не поддерживаются с UTF-8 для FIELDQUOTE.

FIELDTERMINATOR = "field_terminator"

FIELDTERMINATOR применяется только к CSV-файлу. Указывает конечный элемент поля, используемый в CSV-файле. Терминатор поля также можно указать с помощью шестнадцатеричной нотации. Признак конца поля может состоять из нескольких символов. Признак конца поля по умолчанию — (,). Расширенные символы ASCII и многобайтовые символы не поддерживаются в UTF-8 для FIELDTERMINATOR.

ROWTERMINATOR = "row_terminator"

ROWTERMINATOR применяется только к CSV-файлу. Указывает терминатор строки, используемый в CSV-файле. Признак конца строки можно указать в шестнадцатеричном представлении. Признак конца строки может состоять из нескольких символов. Терминаторы по умолчанию: \r\n, \nи \r.

Команда COPY префиксирует \r символ при указании \n (newline) в результате \r\n. Чтобы указать только \n символ, используйте шестнадцатеричную нотацию (0x0A). При указании терминаторов строк с несколькими символами в шестнадцатеричном режиме не указывайте 0x между каждым символом.

Расширенные символы ASCII и многобайтовые символы не поддерживаются в UTF-8 для ROWTERMINATOR.

FIRSTROW = First_row_int

FIRSTROW применяется только к CSV-файлу. Указывает номер строки, который сначала считывается во всех файлах команды COPY. Значения начинаются с 1. 1 — значение по умолчанию. Если задано значение 2, первая строка в каждом файле (строка заголовка) при загрузке данных пропускается. Строки пропускаются по признакам конца строк.

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

DATEFORMAT применяется только к CSV-файлам и задает формат даты для сопоставления с форматами дат SQL Server. Обзор всех типов данных и функций даты и времени в языке Transact-SQL см. в статье Типы данных и функции даты и времени (Transact-SQL). Параметр DATEFORMAT в команде COPY имеет более высокий приоритет, чем параметр DATEFORMAT, настроенный на уровне сеанса.

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 не поддерживаются
• Multicharacter или multibyte ROWTERMINATOR, FIELDTERMINATOR или FIELDQUOTE не поддерживается. Однако "\r\n" принимается как rowTERMINATOR по умолчанию

При использовании синтаксического анализатора версии 1.0 с файлами UTF-8 многобайтовые и многофакторные терминаторы не поддерживаются для FIELDTERMINATOR.

Средство синтаксического анализа версии 1.0 доступно только для обратной совместимости и должно использоваться только в случае возникновения этих ограничений.

MATCH_COLUMN_COUNT = { ON | 'OFF' }

MATCH_COLUMN_COUNT применяется только к CSV- файлу. По умолчанию используется OFF. Указывает, должна ли команда COPY проверить, совпадает ли количество строк столбцов в исходных файлах с числом столбцов целевой таблицы. Применяется следующее поведение:

• Если MATCH_COLUMN_COUNTOFF:
  • Превышение столбцов из исходных строк игнорируется.
  • Строки с меньшим количеством столбцов вставляются в столбцы, допускающие значение NULL.
  • Если значение не предоставляется столбцу без значения NULL, команда COPY завершается ошибкой.
• Если MATCH_COLUMN_COUNTON:
  • Команда COPY проверяет, соответствует ли число столбцов каждой строке в каждом файле из источника счетчику столбцов целевой таблицы.
• Если имеется несоответствие счетчика столбцов, команда COPY завершается ошибкой.

Использование COPY INTO с OneLake

Вы можете использовать COPY INTO для загрузки данных непосредственно из файлов, хранящихся в Fabric OneLake, в частности из папки "Файлы " в Fabric Lakehouse. Это устраняет потребность во внешних промежуточных учетных записях (таких как ADLS 2-го поколения или хранилище BLOB-объектов) и обеспечивает прием, управляемый рабочей областью, с помощью разрешений Fabric. Эта функция поддерживает следующие возможности:

• Чтение папок Files в Lakehouses
• Загрузка рабочей области в хранилище в одном клиенте
• Принудительное применение собственных удостоверений с помощью идентификатора Microsoft Entra

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 с разрешениями на чтение по крайней мере. Чтобы соответствовать принципу наименьшей привилегии, достаточно разрешения на чтение.

Разрешения плоскости данных

После предоставления пользователю разрешений уровня управления с помощью ролей рабочей области или разрешений элемента, если у них есть разрешения только на чтение на уровне плоскости данных , пользователю также следует предоставить INSERT и ADMINISTER DATABASE BULK OPERATIONS разрешения через команды T-SQL.

Например, следующий скрипт T-SQL предоставляет эти разрешения отдельному пользователю с помощью идентификатора Microsoft Entra.

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

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

При использовании параметра ErrorFile пользователь должен иметь минимальное разрешение участника хранилища BLOB-объектов в контейнере учетной записи хранения.

При использовании OneLake в качестве источника пользователь должен иметь разрешения участника или более высокого уровня в исходной рабочей области (где находится Lakehouse) и целевой рабочей области (где находится хранилище). Все доступ регулируется с помощью ролей рабочей области Microsoft Entra ID и Fabric.

Remarks

Инструкция COPY принимает только допустимые символы UTF-8 и UTF-16 для параметров строк и команд. Исходные файлы или параметры (например ROW TERMINATOR , или FIELD TERMINATOR) которые используют недопустимые символы, могут интерпретироваться неправильно инструкцией COPY и вызывать непредвиденные результаты, такие как повреждение данных или другие сбои. Перед вызовом инструкции COPY убедитесь, что исходные файлы и параметры соответствуют UTF-8 или UTF-16.

Ограничения для OneLake в качестве источника

Хранилище Fabric OneLake в качестве источника для обоих COPY INTO и OPENROWSET(BULK) является предварительной версией.

• Поддерживается только проверка подлинности идентификатора Microsoft Entra. Другие методы проверки подлинности, такие как маркеры SAS, общие ключи или строки подключения, запрещены.

• Files В качестве источника поддерживается только папка Lakehouse. Доступ к вложенным папкам, сочетаниям клавиш или другим расположениям OneLake в настоящее время недоступен.

• Пути OneLake должны использовать идентификаторы рабочей области и хранилища. Понятные имена рабочих областей или Lakehouse в настоящее время не поддерживаются.

• Разрешения участника необходимы для обеих рабочих областей. Выполняющий пользователь должен иметь по крайней мере роль участника в исходной рабочей области Lakehouse и целевой рабочей области Хранилища.

Examples

Дополнительные сведения об использовании COPY INTO в хранилище в Microsoft Fabric см. в разделе "Прием данных в хранилище" с помощью инструкции 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"

• FIRSTROW = 1

• ENCODING = "UTF8"

• FILE_TYPE = "CSV"

B. Загрузка с проверкой подлинности с помощью подписи общего доступа (SAS)

В следующем примере производится загрузка файлов, в которых в качестве признака конца строки используется символ перевода строки, как в файлах UNIX. В этом примере также используется ключ SAS для проверки подлинности в Хранилище BLOB-объектов Azure.

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. Load Parquet

В этом примере используется подстановочный знак для загрузки всех файлов 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 = '|'
)

F. Загрузка данных из OneLake (общедоступная предварительная версия)

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

FAQ

Что такое руководство по разделиванию файлов для команды COPY, загружающей сжатые CSV-файлы?

Рекомендуется разделить большие CSV-файлы, особенно если количество файлов невелико, но при этом файлы сохраняются не менее 4 МБ для повышения производительности.

Что такое руководство по разделиванию файлов для команды COPY, загружающей файлы Parquet?

Рекомендуется разделить большие файлы Parquet, особенно если количество файлов невелико.

Есть ли ограничения на число или размер файлов?

Ограничение на количество или размер файлов отсутствует, но для обеспечения оптимальной производительности мы рекомендуем использовать файлы размером не менее 4 МБ.

Какой метод проверки подлинности используется, если не указать учетные данные?

По умолчанию COPY INTRO будет использоваться идентификатор записи пользователя.

Related content

• Прием данных в хранилище в Microsoft Fabric
• Прием данных в хранилище с помощью инструкции COPY