COPIAR EM (Transact-SQL)

Aplica-se a:Azure Synapse Analytics

Este artigo explica como usar a COPY instrução no Azure Synapse Analytics para carregar a partir de contas de armazenamento externas. A COPY declaração oferece a maior flexibilidade para a ingestão de dados de alta taxa no Azure Synapse Analytics.

Note

Para o Warehouse no Microsoft Fabric, visite COPIAR PARA.

Use COPY para os seguintes recursos:

• Usar usuários com menor privilégio para carregar sem a necessidade de permissões CONTROL estritas no data warehouse
• Executar uma única instrução T-SQL sem precisar criar nenhum outro objeto de banco de dados
• Analisar e carregar corretamente os arquivos CSV nos quais os delimitadores (cadeia de caracteres, campo, linha) têm escape dentrode colunas delimitadas por cadeia de caracteres
• Especificar um modelo de permissão mais preciso sem expor as chaves de conta de armazenamento usando SAS (assinaturas de acesso compartilhado)
• Use uma conta de armazenamento diferente para o ERRORFILE local (REJECTED_ROW_LOCATION)
• Personalizar valores padrão para cada coluna de destino e especificar campos de dados de origem para carregar em colunas de destino específicas
• Especificar um terminador de linha personalizado, um terminador de campo e uma citação de campo para arquivos CSV
• Usar formatos de Data do SQL Server para arquivos CSV
• Especificar caracteres curinga e vários arquivos no caminho do local de armazenamento
• A descoberta automática de esquema simplifica o processo de definição e mapeamento de dados de origem em tabelas de destino
• O processo de criação automática cria automaticamente as tabelas e funciona junto com a descoberta automática de esquema
• Carregue diretamente tipos de dados complexos de arquivos Parquet, como Mapas e Listas, em colunas de string, sem usar outras ferramentas para pré-processar os dados

Note

Para carregar tipos de dados complexos de arquivos Parquet, a criação automática de tabelas deve ser ativada usando AUTO_CREATE_TABLEo .

Visite a seguinte documentação para obter exemplos abrangentes e guias de início rápido usando a instrução COPY:

• Início Rápido: dados de carregamento em massa usando a instrução COPY
• Início Rápido: exemplos usando a instrução COPY e métodos de autenticação compatíveis
• Início Rápido: criar a instrução COPY usando uma interface do usuário avançada do Synapse Studio

Note

O Microsoft Entra ID era conhecido como Azure Active Directory (Azure AD).

Syntax

COPY INTO [ schema. ] table_name
[ (Column_list) ]
FROM '<external_location>' [ , ...n ]
WITH
 (
 [ FILE_TYPE = { 'CSV' | 'PARQUET' | 'ORC' } ]
 [ , FILE_FORMAT = EXTERNAL FILE FORMAT OBJECT ]
 [ , CREDENTIAL = (AZURE CREDENTIAL) ]
 [ , ERRORFILE = ' [ http(s)://storageaccount/container ] /errorfile_directory [ / ] ] '
 [ , ERRORFILE_CREDENTIAL = (AZURE CREDENTIAL) ]
 [ , MAXERRORS = max_errors ]
 [ , COMPRESSION = { 'Gzip' | 'DefaultCodec' | 'Snappy' } ]
 [ , FIELDQUOTE = 'string_delimiter' ]
 [ , FIELDTERMINATOR =  'field_terminator' ]
 [ , ROWTERMINATOR = 'row_terminator' ]
 [ , FIRSTROW = first_row ]
 [ , DATEFORMAT = 'date_format' ]
 [ , ENCODING = { 'UTF8' | 'UTF16' } ]
 [ , IDENTITY_INSERT = { 'ON' | 'OFF' } ]
 [ , AUTO_CREATE_TABLE = { 'ON' | 'OFF' } ]
)

Arguments

schema_name

Opcional se o esquema padrão do usuário que está executando a operação for o esquema da tabela especificada. Se o esquema não for especificado e o esquema padrão do usuário que executa a operação COPY for diferente do esquema da tabela especificada, a operação COPY será cancelada e uma mensagem de erro será retornada.

table_name

O nome da tabela para a qual os dados serão copiados por meio da operação COPY. A tabela de destino pode ser uma tabela temporária ou permanente e já deve existir no banco de dados. Não forneça uma lista de colunas para o modo de detecção automática de esquema.

(column_list)

Uma lista opcional de uma ou mais colunas usadas para mapear campos de dados de origem para colunas da tabela de destino para carregar dados.

Não especifique um column_list quando AUTO_CREATE_TABLE = 'ON'.

column_list deve ser colocada entre parênteses e separada por vírgulas. A lista de colunas tem o formato a seguir:

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

• Column_name – é o nome da coluna na tabela de destino.
• Default_value – o valor padrão que substituirá qualquer valor NULL no arquivo de entrada. O valor padrão se aplica a todos os formatos de arquivo. COPY tentará carregar NULL do arquivo de entrada quando uma coluna for omitida da lista de colunas ou quando houver um campo de arquivo de entrada vazio. O valor padrão precede a palavra-chave "default"
• Field_number - o número do campo do arquivo de entrada mapeado para a coluna de destino.
• A indexação de campos começa em 1.

Quando uma lista de colunas não for especificada, COPY mapeará as colunas com base na ordinalidade da origem e do destino: o campo de entrada 1 vai para a coluna de destino 1, o campo 2 vai para a coluna 2 etc.

Locais externos

É onde os arquivos que contêm os dados são preparados. Atualmente, o ADLS (Azure Data Lake Storage) Gen2 e o Armazenamento de Blobs do Azure têm suporte:

• Local externo para o Armazenamento de Blobs: https://<account\>.blob.core.windows.net/<container\>/<path\>
• Local externo para o ADLS Gen2: https://<account\>.dfs.core.windows.net/<container\>/<path\>

Note

O .blob ponto de extremidade também está disponível para o ADLS Gen2 e atualmente produz o melhor desempenho. Use o ponto de extremidade .blob quando .dfs não for necessário para seu método de autenticação.

• Conta – o nome da conta de armazenamento

• Contêiner – o nome do contêiner de blobs

• Caminho – a pasta ou o caminho do arquivo para os dados. O local inicia do contêiner. Se uma pasta for especificada, COPY recuperará todos os arquivos da pasta e de todas as suas subpastas. COPY ignora pastas ocultas e não retorna arquivos que começam com um sublinhado (_) ou um ponto final (.), a menos que especificado explicitamente no caminho. Esse comportamento permanece mesmo quando é especificado um caminho com um curinga.

Cartões curingas podem ser incluídos no caminho em que

• A correspondência do nome de caminho curinga diferencia maiúsculas de minúsculas
• É possível efetuar o escape do curinga usando o caractere de barra invertida (\)
• A expansão do curinga é aplicada recursivamente. Por exemplo, todos os arquivos CSV em Customer1 (incluindo subdiretórios de Customer1) são carregados no exemplo a seguir: Account/Container/Customer1/*.csv

Note

Para obter o melhor desempenho, evite especificar curingas que se expandiriam em um número maior de arquivos. Se possível, liste vários locais de arquivo em vez de especificar curingas.

Vários locais de arquivo só podem ser especificados na mesma conta de armazenamento e contêiner por meio de uma lista separada por vírgulas, como:

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

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

FILE_TYPE especifica o formato dos dados externos.

• CSV: especifica um arquivo de valores separados por vírgula em conformidade com o padrão RFC 4180.
• PARQUET: especifica um formato Parquet.
• ORC: Especifica um formato ORC (Optimized Row Columnar).

Note

O tipo de arquivo "Texto Delimitado" no Polybase é substituído pelo formato de arquivo "CSV", no qual o delimitador de vírgula padrão pode ser configurado por meio do parâmetro FIELDTERMINATOR.

FILE_FORMAT = external_file_format_name

FILE_FORMAT aplica-se somente a arquivos Parquet e ORC e especifica o nome do objeto de formato de arquivo externo que armazena o tipo de arquivo e o método de compactação dos dados externos. Para criar um formato de arquivo externo, use CREATE EXTERNAL FILE FORMAT.

CREDENCIAL (IDENTITY = '', SECRET = '')

CREDENTIAL especifica o mecanismo de autenticação para acessar a conta de armazenamento externo. Os métodos de autenticação são:

	CSV	Parquet	ORC
Armazenamento de Blobs do Azure	SAS/MSI/PRINCIPAL DE SERVIÇO/CHAVE/Entra	SAS/KEY	SAS/KEY
Azure Data Lake Gen2	SAS/MSI/PRINCIPAL DE SERVIÇO/CHAVE/Entra	SAS (blob 1 )/MSI (dfs 2 )/PRINCIPAL DE SERVIÇO/CHAVE/Entra	SAS (blob 1 )/MSI (dfs 2 )/PRINCIPAL DE SERVIÇO/CHAVE/Entra

¹ o ponto de extremidade blob (.blob.core.windows.net) no caminho de localização externo é necessário para esse método de autenticação.

² o ponto de extremidade dfs (.dfs.core.windows.net) no caminho de localização externo é necessário para esse método de autenticação.

Note

• Ao autenticar usando a ID do Microsoft Entra ou em uma conta de armazenamento público, CREDENTIAL não precisa ser especificado.
• Se sua conta de armazenamento estiver associada a uma VNet, você deverá se autenticar usando uma identidade gerenciada.

• Autenticação com SAS (Assinaturas de Acesso Compartilhado)

  • IDENTITY: uma constante com um valor de "Assinatura de Acesso Compartilhado"
  • SECRET: a assinatura deacesso compartilhado fornece acesso delegado aos recursos em sua conta de armazenamento.

• Permissões mínimas necessárias: READ e LIST

• Autenticação com Entidades de Serviço

  • IDENTITY: <IDdoCliente>@<PontoDeExtremidade_do_Token_OAuth_2.0>
  • SEGREDO: chave da entidade de serviço do aplicativo Microsoft Entra

• Funções de RBAC mínimas necessárias: Colaborador de dados do blob de armazenamento, colaborador de dados do blob de armazenamento, proprietário de dados do blob de armazenamento ou leitor de dados do blob de armazenamento

• Autenticação com a chave da conta de armazenamento

  • IDENTITY: uma constante com o valor da "Chave de Conta de Armazenamento"

• SECRET: Chave de conta de armazenamento

• Autenticação com Identidade Gerenciada (Pontos de Extremidade de Serviço de VNet)

  • IDENTITY: uma constante com um valor de "Identidade Gerenciada"

• Funções RBAC mínimas necessárias: colaborador de dados do blob de armazenamento ou proprietário de dados do blob de armazenamento para o servidor lógico registrado do Microsoft Entra no Azure. Ao usar um pool de SQL dedicado (antigo SQL DW) que não está associado a um workspace do Synapse, essa função RBAC não é necessária, mas a identidade gerenciada requer permissões de ACL (Lista de Controle de Acesso) nos objetos de destino para habilitar o acesso de leitura aos arquivos de origem

• Autenticando com um usuário do Microsoft Entra

  • A CREDENCIAL não é necessária

• Funções RBAC mínimas necessárias: Colaborador de dados do blob de armazenamento ou Proprietário de dados do blob de armazenamento para o usuário do Microsoft Entra

ERRORFILE = local do diretório

ERRORFILE aplica-se somente ao CSV. Especifica o diretório na instrução COPY em que as linhas rejeitadas e o arquivo de erro correspondente devem ser gravados. O caminho completo da conta de armazenamento ou o caminho relativo do contêiner pode ser especificado. Se o caminho especificado não existir, um será criado em seu nome. Um diretório filho é criado com o nome _rejectedrows. O _ caractere garante que o diretório seja escapado para outro processamento de dados, a menos que explicitamente nomeado no parâmetro de localização.

Note

Quando um caminho relativo é passado para ERRORFILE, o caminho é relativo ao caminho do contêiner especificado em external_location.

Dentro desse diretório, há uma pasta criada com base na hora do envio do carregamento no formato YearMonthDay – HourMinuteSecond (por exemplo, 20180330-173205). Nessa pasta, dois tipos de arquivos são gravados, o arquivo de motivo (erro) e o arquivo de dados (linha), cada um anexado previamente com o queryID, o distributionID e um GUID do arquivo. Já que os dados e o motivo estão em arquivos separados, arquivos correspondentes têm um prefixo correspondente.

Se ERRORFILE tiver o caminho completo da conta de armazenamento definido, a ERRORFILE_CREDENTIAL será usada para se conectar a esse armazenamento. Caso contrário, o valor mencionado para CREDENTIAL será usado. Quando a mesma credencial usada para os dados de origem é usada para ERRORFILE, as restrições que se aplicam a ERRORFILE_CREDENTIAL também se aplicam

ERRORFILE_CREDENTIAL = (IDENTIDADE= '', SEGREDO = '')

ERRORFILE_CREDENTIAL aplica-se somente a arquivos CSV. As fontes de dados e os métodos de autenticação com suporte são:

• Armazenamento de Blobs do Azure – SAS/SERVICE PRINCIPAL/Entra

• Azure Data Lake Gen2 – SAS/MSI/SERVICE PRINCIPAL/Entra

• Autenticação com SAS (Assinaturas de Acesso Compartilhado)

  • IDENTITY: uma constante com um valor de "Assinatura de Acesso Compartilhado"
  • SECRET: a assinatura deacesso compartilhado fornece acesso delegado aos recursos em sua conta de armazenamento.

• Permissões mínimas necessárias: READ, LIST, WRITE, CREATE, DELETE

• Autenticação com Entidades de Serviço

  • IDENTITY: <IDdoCliente>@<PontoDeExtremidade_do_Token_OAuth_2.0>
  • SEGREDO: chave da entidade de serviço do aplicativo Microsoft Entra

• Funções de RBAC mínimas necessárias: colaborador de dados do blob de armazenamento ou proprietário de dados do blob de armazenamento

Note

Use o ponto de extremidade do token OAuth 2.0 V1

• Autenticação com Identidade Gerenciada (Pontos de Extremidade de Serviço de VNet)

  • IDENTITY: uma constante com um valor de "Identidade Gerenciada"

• Funções RBAC mínimas necessárias: colaborador de dados do blob de armazenamento ou proprietário de dados do blob de armazenamento para o servidor do Banco de Dados SQL registrado no Microsoft Entra

• Autenticando com um usuário do Microsoft Entra

  • A CREDENCIAL não é necessária

• Funções RBAC mínimas necessárias: Colaborador de dados do blob de armazenamento ou Proprietário de dados do blob de armazenamento para o usuário do Microsoft Entra

Não há suporte para o uso de uma chave de conta de armazenamento com ERRORFILE_CREDENTIAL.

Note

Se estiver usando a mesma conta de armazenamento para ERRORFILE e especificando o caminho de ERRORFILE relativo à raiz do contêiner, você não precisará especificar a ERROR_CREDENTIAL.

MAXERRORS = max_errors

MAXERRORS especifica o número máximo de linhas de rejeição permitidas na carga antes que a operação COPY falhe. Cada linha que não pode ser importada pela operação COPY é ignorada e contada como um erro. Se max_errors não for especificado, o padrão será zero.

MAXERRORS não pode ser usado com AUTO_CREATE_TABLE.

Quando FILE_TYPE é PARQUET, exceções causadas por erros de conversão de tipo de dados (por exemplo, binário parquet para inteiro sql) ainda causam COPY INTO falha, ignorando MAXERRORS.

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

COMPRESSION é opcional e especifica o método de compactação de dados para os dados externos.

• CSV dá suporte a GZIP
• Parquet dá suporte a GZIP e Snappy
• ORC dá suporte a DefaultCodec e Snappy.
• Zlib é a compactação padrão do ORC

O comando COPY detectará automaticamente o tipo de compactação com base na extensão do arquivo quando esse parâmetro não for especificado:

• .gz - GZIP
• .snappy - Rápido
• .deflate - DefaultCodec (somente Parquet e ORC)

O comando COPY requer que os arquivos gzip não contenham nenhum lixo à direita para operar normalmente. O formato gzip requer estritamente que os arquivos sejam compostos de membros válidos sem nenhuma informação adicional antes, entre ou depois deles. Qualquer desvio desse formato, como a presença de dados não gzip à direita, resultará na falha do comando COPY. Certifique-se de verificar se não há lixo à direita no final dos arquivos gzip para garantir que o COPY possa processar esses arquivos com êxito.

FIELDQUOTE = 'field_quote'

FIELDQUOTE aplica-se a CSV e especifica um único caractere que será usado como o caractere de aspas (delimitador de cadeia de caracteres) no arquivo CSV. Se não for especificado, o caractere de aspas (") será usado como o caractere de aspas, conforme definido no padrão RFC 4180. A notação hexadecimal também é suportada para FIELDQUOTE. Não há suporte para caracteres ASCII estendidos e multibyte com UTF-8 para FIELDQUOTE.

Note

O escape dos caracteres FIELDQUOTE é efetuado em colunas de cadeia de caracteres em que há a presença de um FIELDQUOTE (delimitador) duplo.

FIELDTERMINATOR = 'field_terminator'

FIELDTERMINATOR aplica-se somente ao CSV. Especifica o terminador de campo que será usado no arquivo CSV. O terminador de campo pode ser especificado usando a notação hexadecimal. O terminador de campo pode ter vários caracteres. O terminador de campo padrão é um (,). Não há suporte para caracteres ASCII estendidos e multibyte com UTF-8 para FIELDTERMINATOR.

TERMINADOR DE LINHA = 'row_terminator'

ROW TERMINATOR aplica-se somente ao CSV. Especifica o terminador de linha que será usado no arquivo CSV. O terminador de linha pode ser especificado usando a notação hexadecimal. O terminador de linha pode ter vários caracteres. Por padrão, o terminador de linha é \r\n.

O comando COPY prefixa o caractere \r ao especificar \n (nova linha), resultando em \r\n. Para especificar apenas o caractere \n, use a notação hexadecimal (0x0A). Ao especificar terminadores de linha de vários caracteres em formato hexadecimal, não especifique 0x entre cada caractere.

Não há suporte para caracteres ASCII estendidos e multibyte com UTF-8 para ROW TERMINATOR.

PRIMEIRA LINHA = First_row_int

FIRSTROW aplica-se a CSV e especifica o número da linha que é lida primeiro em todos os arquivos para o comando COPY. Os valores começam com 1, que é o valor padrão. Se o valor for definido como dois, a primeira linha em todos os arquivos (linha de cabeçalho) será ignorada quando os dados forem carregados. As linhas são ignoradas com base na existência de terminadores de linhas.

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

DATEFORMAT aplica-se somente ao CSV e especifica o formato de data do mapeamento de data dos formatos de data do SQL Server. Para ter uma visão geral de todas as funções e tipos de dados de data e hora do Transact-SQL, confira Funções e tipos de dados de data e hora (Transact-SQL). DATEFORMAT no comando COPY tem precedência sobre DATEFORMAT configurado no nível da sessão.

CODIFICAÇÃO = 'UTF8' | 'UTF16'

ENCODING aplica-se somente ao CSV. O padrão é UTF8. Especifica o padrão da codificação de dados para os arquivos carregados pelo comando COPY.

IDENTITY_INSERT = 'ON' | 'DESLIGADO'

IDENTITY_INSERT especifica se os valores de identidade no arquivo de dados importado devem ser usados para a coluna de identidade. Se o valor de IDENTITY_INSERT for OFF (padrão), os valores de identidade para essa coluna serão verificados, mas não importados. Observe o seguinte comportamento com o comando COPY:

• Se IDENTITY_INSERT estiver OFF e a tabela tiver uma coluna de identidade
  • Deverá ser especificada uma lista de colunas que não mapeia um campo de entrada para a coluna de identidade.
• Se IDENTITY_INSERT estiver ON e a tabela tiver uma coluna de identidade
  • Se uma lista de colunas for passada, ela deverá mapear um campo de entrada para a coluna de identidade.
• O valor padrão não tem suporte para IDENTITY COLUMN na lista de colunas.
• IDENTITY_INSERT só pode ser definida para uma tabela por vez.

O Azure Synapse Analytics atribuirá automaticamente valores exclusivos com base nos valores de semente e incremento especificados durante a criação da tabela.

AUTO_CREATE_TABLE = { 'ON' | 'DESLIGADO' }

AUTO_CREATE_TABLE especifica se a tabela pode ser criada automaticamente trabalhando junto com a descoberta automática de esquema. Ele está disponível apenas para arquivos Parquet.

• LIGADO: habilita a criação automática de tabela. O COPY INTO processo cria automaticamente uma nova tabela ao descobrir a estrutura do arquivo a ser carregado. Também pode ser usado com tabelas pré-existentes para aproveitar a descoberta automática de esquema de arquivos Parquet.
• OFF: a criação automática de tabela não está habilitada. Default.

Note

A criação automática de tabela funciona junto com a descoberta automática de esquema. A criação automática de tabela NÃO é habilitada por padrão.

Permissions

O usuário que executa o comando de cópia deve ter as seguintes permissões:

• ADMINISTRAR OPERAÇÕES EM MASSA DO BANCO DE DADOS
• INSERT

Requer as permissões INSERT e ADMINISTER BULK OPERATIONS. No Azure Synapse Analytics, são necessárias permissões de INSERT e ADMINISTER DATABASE BULK OPERATIONS.

Além disso, se o usuário que executa o comando COPY também pretende gerar uma nova tabela e carregar dados nela, ele exige permissões CREATE TABLE e ALTER ON SCHEMA.

Por exemplo, para permitir que mike@contoso.com use COPY para criar uma nova tabela no esquema HR e inserir os dados de um arquivo Parquet, use o seguinte exemplo 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

A instrução COPY aceita apenas caracteres válidos UTF-8 e UTF-16 para dados de linha e parâmetros de comando. Arquivos ou parâmetros de origem (como ROW TERMINATOR ou FIELD TERMINATOR) que usam caracteres inválidos podem ser interpretados incorretamente pela instrução COPY e causar resultados inesperados, como corrupção de dados ou outras falhas. Verifique se os arquivos de origem e os parâmetros estão em conformidade com UTF-8 ou UTF-16 antes de invocar a instrução COPY.

A MAXDOP dica de consulta não é suportada por COPY INTO.

Para garantir a execução confiável, os arquivos e pastas de origem devem permanecer inalterados durante toda a COPY INTO operação.

• Modificar, excluir ou substituir arquivos ou pastas referenciados enquanto o comando está em execução pode fazer com que a operação falhe ou resulte em ingestão de dados inconsistente.
• Antes de COPY INTOexecutar, verifique se todos os dados de origem estão estáveis e não serão alterados durante o processo.

Examples

A. Carregar de uma conta de armazenamento público

O exemplo a seguir é a forma mais simples do COPY comando, que carrega dados de uma conta pública de armazenamento. Para este exemplo, os padrões da instrução COPY correspondem ao formato do arquivo CSV de item de linha.

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

Os valores padrão do comando COPY são:

• DATEFORMAT = DATEFORMAT da sessão

• MAXERRORS = 0

• O padrão de COMPRESSION é descompactado

• CITAÇÃO CAMPO = '"'

• FIELDTERMINATOR = ','

• LINHATERMINADOR = '\n'

Important

COPY trata \n como \r\n internamente. Para obter mais informações, confira a seção ROWTERMINATOR.

• PRIMEIRA LINHA = 1

• CODIFICAÇÃO = 'UTF8'

• FILE_TYPE = 'CSV'

• IDENTITY_INSERT = 'DESLIGADO'

B. Autenticação de carga via SAS (Assinatura de Acesso Compartilhado)

O exemplo a seguir carrega arquivos que usam a alimentação de linha como um terminador de linha, como uma saída UNIX. Este exemplo também usa uma chave de SAS para autenticação no Armazenamento de Blobs do 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. Carregar com uma lista de colunas com valores padrão, autenticando por meio da Chave da Conta de Armazenamento

Este exemplo carrega arquivos especificando uma lista de colunas com valores padrão.

--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. Carregar Parquet ou ORC usando o objeto de formato de arquivo existente

Este exemplo usa um curinga para carregar todos os arquivos Parquet em uma pasta.

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. Carga especificando curingas e vários arquivos

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. Carregar usando credenciais do 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. Carregar usando a detecção automática de esquema

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

perguntas frequentes

Qual é o desempenho do comando COPY em comparação com o PolyBase?

O comando COPY terá um desempenho melhor dependendo da carga de trabalho.

• Os arquivos compactados não podem ser divididos automaticamente. Para obter o melhor desempenho de carregamento possível, considere a possibilidade de dividir a entrada em vários arquivos ao carregar CSVs compactados.

• Os arquivos CSV grandes não compactados podem ser divididos e carregados em paralelo de modo automático. Portanto, não é necessário dividir manualmente arquivos CSV não compactados na maioria dos casos. Em determinados casos em que a divisão automática de arquivos não é viável devido a características de dados, a divisão manual de grandes CSVs ainda pode beneficiar o desempenho.

Quais são as diretrizes de divisão de arquivo para o comando COPY que carrega arquivos CSV compactados?

As diretrizes referentes ao número de arquivos são descritas na tabela a seguir. Depois que o número recomendado de arquivos for atingido, você terá um desempenho melhor quanto maior os arquivos. O número de arquivos é determinado pelo número de nós de computação multiplicados por 60. Por exemplo, em 6000DWU, temos 12 nós de computação, e 12 x 60 = 720 partições. Para ver uma experiência simples de divisão de arquivos, confira Como maximizar a taxa de transferência de carregamento COPY com divisões de arquivo.

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

Quais são as diretrizes de divisão de arquivo para o comando COPY que carrega arquivos Parquet ou ORC?

Não há necessidade de dividir arquivos Parquet e ORC, porque o comando COPY dividirá os arquivos automaticamente. Os arquivos Parquet e ORC na conta de armazenamento do Azure devem ter 256 MB ou mais ter um desempenho ideal.

Há alguma limitação quanto ao número ou ao tamanho dos arquivos?

Não há limitações quanto ao número ou tamanho dos arquivos. No entanto, para obter o melhor desempenho, recomendamos que os arquivos tenham pelo menos 4 MB. Além disso, limite a contagem de arquivos de origem a um máximo de 5.000 arquivos para melhor desempenho.

Há algum problema conhecido com a instrução COPY?

Se você tiver um workspace do Azure Synapse criado antes de 7 de dezembro de 2020, poderá encontrar uma mensagem de erro semelhante ao autenticar usando a Identidade Gerenciada: com.microsoft.sqlserver.jdbc.SQLServerException: Managed Service Identity has not been enabled on this server. Please enable Managed Service Identity and try again.

Siga estas etapas para contornar esse problema registrando novamente a identidade gerenciada do workspace:

1. Instale o PowerShell do Azure. Veja Instalar o PowerShell.
2. Registre a identidade gerenciada do workspace usando o PowerShell:

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

Conteúdo relacionado

• Visão geral do carregamento com o Azure Synapse Analytics