COPY INTO (Transact-SQL)

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

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

Примечание.

Для хранилища в Microsoft Fabric посетите раздел COPY INTO.

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

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

Примечание.

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

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

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

Примечание.

Идентификатор Microsoft Entra ранее был известен как 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

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

Внешние расположения

Места размещения файлов, содержащих данные. Сейчас поддерживаются 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\>

Примечание.

Конечная точка .blob доступна для ADLS 2-го поколения и в настоящее время обеспечивает наилучшую производительность. Используйте конечную точку .blob, если для способа проверки подлинности не требуется .dfs.

• 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).

Примечание.

Тип файла "текст с разделителями" в PolyBase заменен форматом файла CSV, в котором разделитель-запятую по умолчанию можно настроить с помощью параметра FIELDTERMINATOR.

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/AAD	SAS/KEY	SAS/KEY
Azure Data Lake 2-го поколения	SAS/MSI/SERVICE PRINCIPAL/KEY/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) во внешнем пути расположения.

Примечание.

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

• Проверка подлинности на основе подписанных 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 = Directory Location

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

Примечание.

При передаче относительного пути в ERRORFILE путь относительно пути контейнера, указанного в external_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/AAD

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

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

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

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

  • IDENTITY: <ClientID>@<OAuth_2.0_Token_EndPoint>
  • СЕКРЕТ: ключ субъекта-службы приложения Microsoft Entra
  • Минимальные роли RBAC: участник данных BLOB-объектов хранилища или владелец данных BLOB-объектов хранилища

Примечание.

Используйте конечную точку токена OAuth 2.0 V1.

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

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

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

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

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

Примечание.

Если вы используете ту же учетную запись хранения для ERRORFILE и указываете путь ERRORFILE относительно корня контейнера, указывать ERROR_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 — 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.

Примечание.

Символы FIELDQUOTE экранируются в строковых столбцах, где есть двойной символ 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 (по умолчанию), значения идентификаторов для этого столбца проверяются, но не импортируются. Azure Synapse Analytics автоматически назначает уникальные значения на основе начальных и добавочных значений, указанных во время создания таблицы. Обратите внимание на следующее поведение команды COPY.

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

AUTO_CREATE_TABLE = { "ON" | "OFF" }

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

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

Примечание.

Автоматическое создание таблиц выполняется вместе с автоматическим обнаружением схемы. Автоматическое создание таблиц НЕ включено по умолчанию.

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

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

Разрешения

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

• ADMINISTER DATABASE BULK OPERATIONS
• 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];

Замечания

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

Примеры

А. Загрузка из общедоступной учетной записи хранения

В следующем примере показана простейшая форма команды 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. Загрузка с проверкой подлинности с помощью подписи общего доступа (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>')
)

Е. Загрузка с указанием подстановочных знаков и нескольких файлов

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

Вопросы и ответы

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

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

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

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

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

Руководство по количеству файлов описано в следующей таблице. После достижения рекомендуемого количества файлов у вас будет более высокая производительность. Количество файлов определяется числом вычислительных узлов, умноженных на 60. Например, в 6000DWU у нас есть 12 вычислительных узлов и 12*60 = 720 секций. Чтобы получить простую возможность разделения файлов, см. инструкции по максимальной пропускной способности загрузки COPY с разделением файлов.

DWU	Количество файлов
100	60
200	60
300	60
400	60
500	60
1,000	120
1500	180
2 000	240
2500	300
3,000	360
5,000	600
6000	720
7500	900
10,000	1200
15 000	1800
30,000	3600

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

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

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

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

Существуют ли известные проблемы с инструкцией 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
   

Связанный контент

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