COPIAR PARA (Transact-SQL)

Aplica-se a:Azure Synapse Analytics

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

Observação

Para Warehouse no Microsoft Fabric, visite COPY INTO.

Use COPY para os seguintes recursos:

• Use usuários com privilégios mais baixos para carregar sem precisar de permissões rígidas de CONTROLE no data warehouse
• Execute uma única instrução T-SQL sem ter que criar nenhum outro objeto de banco de dados
• Analise e carregue corretamente arquivos CSV onde delimitadores (string, field, row) são escapados dentro de colunas delimitadas por cadeia de caracteres
• Especifique um modelo de permissão mais fino sem expor chaves de conta de armazenamento usando Assinaturas de Acesso de Compartilhamento (SAS)
• Usar uma conta de armazenamento diferente para o local ERRORFILE (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
• Especifique um terminador de linha personalizado, terminador de campo e cotação de campo para arquivos CSV
• Usar formatos de data do SQL Server para arquivos CSV
• Especificar curingas 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 automático de criação de tabelas cria automaticamente as tabelas e funciona em conjunto com a descoberta automática de esquemas
• Carregue diretamente tipos de dados complexos de arquivos Parquet, como Mapas e Listas, em colunas de cadeia de caracteres, sem usar outras ferramentas para pré-processar os dados

Observação

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

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

• Guia de início rápido: carregar dados em massa usando a instrução COPY
• Guia de início rápido: exemplos usando a instrução COPY e seus métodos de autenticação suportados
• Guia de início rápido: criando a instrução COPY usando a interface do usuário avançada do Synapse Studio

Observação

Microsoft Entra ID era anteriormente conhecido como Azure Ative Directory (Azure AD).

Sintaxe

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

Argumentos

schema_name

Opcional se o esquema padrão para o usuário que executa a operação for o esquema da tabela especificada. Se 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, COPY será cancelado e uma mensagem de erro será retornada.

table_name

O nome da tabela para COPIAR dados. A tabela de destino pode ser uma tabela temporária ou permanente e já deve existir no banco de dados. Para o modo de deteção automática de esquema, não forneça uma lista de colunas.

(column_list)

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

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

column_list devem ser colocados entre parênteses e delimitados por vírgulas. A lista de colunas tem o seguinte formato:

[(Column_name [Default_value padrão] [Field_number] [,... n])]

• Column_name - o nome da coluna na tabela de destino.
• Default_value - o valor padrão que substitui qualquer valor NULL no arquivo de entrada. O valor padrão aplica-se a todos os formatos de arquivo. COPY tenta carregar NULL do arquivo de entrada quando uma coluna é omitida da lista de colunas ou quando há 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 que é mapeado para a coluna de destino.
• A indexação de campo começa em 1.

Quando uma lista de colunas não é especificada, COPY mapeia colunas com base na ordem de origem e destino: o campo de entrada 1 vai para a coluna de destino 1, o campo 2 vai para a coluna 2, etc.

Localizações externas

É onde os arquivos que contêm os dados são preparados. Atualmente, o Azure Data Lake Storage (ADLS) Gen2 e o Azure Blob Storage são suportados:

• de localização externa para armazenamento de Blob: https://<account\>.blob.core.windows.net/<container\>/<path\>
• de localização externa para ADLS Gen2: https://<account\>.dfs.core.windows.net/<container\>/<path\>

Observação

O ponto de extremidade .blob também está disponível para 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

• Container - O nome do contêiner de blob

• Caminho - o caminho da pasta ou do arquivo para os dados. A localização começa a partir do contentor. Se uma pasta for especificada, COPY recuperará todos os arquivos da pasta e todas as suas subpastas. COPY ignora pastas ocultas e não retorna arquivos que começam com um sublinhado (_) ou um ponto (.), a menos que explicitamente especificado no caminho. Esse comportamento é o mesmo mesmo ao especificar um caminho com um curinga.

Os curingas podem ser incluídos no caminho onde

• A correspondência de nome de caminho curinga diferencia maiúsculas de minúsculas
• Curinga pode ser escapado usando o caractere de barra invertida (\)
• A expansão curinga é aplicada recursivamente. Por exemplo, todos os arquivos CSV em Customer1 (incluindo subdiretórios de Customer1) são carregados no seguinte exemplo: Account/Container/Customer1/*.csv

Observação

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 arquivos só podem ser especificados a partir da mesma conta de armazenamento e contêiner por meio de uma lista separada por vírgula, 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írgulas compatível com o padrão de RFC 4180 .
• PARQUET: Especifica um formato Parquet.
• ORC: Especifica um formato ORC (Optimized Row Columnar).

Observação

O tipo de arquivo 'Delimited Text' no PolyBase é substituído pelo formato de arquivo 'CSV', onde o delimitador de vírgula padrão pode ser configurado através do parâmetro FIELDTERMINATOR.

FILE_FORMAT = external_file_format_name

FILE_FORMAT se aplica apenas 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 para os dados externos. Para criar um formato de arquivo externo, use CREATE EXTERNAL FILE FORMAT.

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

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

	CSV	Parquet	ORC
de Armazenamento de Blob do Azure	SAS/MSI/ENTIDADE DE SERVIÇO/CHAVE/AAD	SAS/CHAVE	SAS/CHAVE
Azure Data Lake Gen2	SAS/MSI/ENTIDADE DE SERVIÇO/CHAVE/AAD	SAS (blob 1 )/MSI (dfs 2 )/ENTIDADE DE SERVIÇO/CHAVE/AAD	SAS (blob 1 )/MSI (dfs 2 )/ENTIDADE DE SERVIÇO/CHAVE/AAD

1: O ponto de extremidade .blob (.blob.core.windows.net) no caminho do local externo é necessário para esse método de autenticação.

2: O ponto de extremidade .dfs (.dfs.core.windows.net) no caminho do local externo é necessário para esse método de autenticação.

Observação

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

• Autenticação com assinaturas de acesso compartilhado (SAS)

  • IDENTIDADE: Uma constante com um valor de 'Assinatura de Acesso Compartilhado'
  • SEGREDO: A assinatura de acesso compartilhadofornece 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

  • IDENTIDADE: <ClientID>@<OAuth_2.0_Token_EndPoint>
  • SECRET: Chave principal do serviço de aplicativo Microsoft Entra
  • Funções RBAC mínimas necessárias: contribuidor de dados de blob de armazenamento, contribuidor de dados de blob de armazenamento, proprietário de dados de blob de armazenamento ou leitor de dados de blob de armazenamento

• Autenticação com chave de conta de armazenamento

  • IDENTIDADE: Uma constante com um valor de 'Chave de Conta de Armazenamento'
  • SECRET: Chave da conta de armazenamento

• Autenticação com de identidade gerenciada (pontos de extremidade de serviço VNet)

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

• Autenticando com um usuário do Microsoft Entra

  • CREDENCIAL não é necessária
  • Funções RBAC mínimas necessárias: contribuidor de dados de blob de armazenamento ou proprietário de dados de blob de armazenamento para o usuário do Microsoft Entra

ERRORFILE = Localização do Diretório

ERRORFILE só se aplica ao CSV. Especifica o diretório dentro da instrução COPY onde as linhas rejeitadas e o arquivo de erro correspondente devem ser gravados. O caminho completo da conta de armazenamento pode ser especificado ou o caminho relativo ao 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 location.

Observação

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

Dentro deste diretório, há uma pasta criada com base no tempo de envio de carregamento no formato YearMonthDay -HourMinuteSecond (Ex. 20180330-173205). Nesta pasta, dois tipos de arquivos são gravados, o arquivo de motivo (Erro) e o arquivo de dados (Linha), cada um pré-anexado com o queryID, distributionID e um guid de arquivo. Como os dados e o motivo estão em arquivos separados, os arquivos correspondentes têm um prefixo correspondente.

Se ERRORFILE tiver o caminho completo da conta de armazenamento definido, o ERRORFILE_CREDENTIAL será usado 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 = (IDENTITY= '', SECRET = '')

ERRORFILE_CREDENTIAL só se aplica a arquivos CSV. A fonte de dados e os métodos de autenticação suportados são:

• Armazenamento de Blobs do Azure - SAS/SERVICE PRINCIPAL/AAD

• Azure Data Lake Gen2 - SAS/MSI/SERVICE PRINCIPAL/AAD

• Autenticação com assinaturas de acesso compartilhado (SAS)

  • IDENTIDADE: Uma constante com um valor de 'Assinatura de Acesso Compartilhado'
  • SEGREDO: A assinatura de acesso compartilhadofornece acesso delegado aos recursos em sua conta de armazenamento.
  • Permissões mínimas necessárias: LER, LISTAR, ESCREVER, CRIAR, EXCLUIR

• Autenticação com Entidades de Serviço

  • IDENTIDADE: <ClientID>@<OAuth_2.0_Token_EndPoint>
  • SECRET: Chave principal do serviço de aplicativo Microsoft Entra
  • Funções RBAC mínimas necessárias: contribuidor de dados de blob de armazenamento ou proprietário de dados de blob de armazenamento

Observação

Usar o ponto de extremidade de token OAuth 2.0 V1

• Autenticação com de identidade gerenciada (pontos de extremidade de serviço VNet)

  • IDENTIDADE: Uma constante com um valor de 'Identidade Gerenciada'
  • Funções RBAC mínimas necessárias: contribuidor de dados de blob de armazenamento ou proprietário de dados de blob de armazenamento para o servidor de Banco de dados SQL registrado do Microsoft Entra

• Autenticando com um usuário do Microsoft Entra

  • CREDENCIAL não é necessária
  • Funções RBAC mínimas necessárias: contribuidor de dados de blob de armazenamento ou proprietário de dados de 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.

Observação

Se você estiver usando a mesma conta de armazenamento para seu ERRORFILE e especificando o caminho ERRORFILE relativo à raiz do contêiner, não será necessário especificar o 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á 0.

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 fazem com que COPY INTO falhe, ignorando MAXERRORS.

COMPRESSÃO = { 'DefaultCodec ' | 'Rápido' | 'GZIP' | 'NENHUMA'}

COMPACTAÇÃO é opcional e especifica o método de compactação de dados para os dados externos.

• CSV suporta GZIP
• Parquet suporta GZIP e Snappy
• ORC suporta DefaultCodec e Snappy.
• Zlib é a compressão padrão para ORC

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

• .gz - GZIP
• .snappy – Snappy
• .deflate - DefaultCodec (apenas Parquet e ORC)

O comando COPY requer que os arquivos gzip não contenham lixo à direita para funcionar normalmente. O formato gzip requer estritamente que os arquivos sejam compostos por membros válidos sem qualquer 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 ao CSV e especifica um único caractere que é usado como o caractere de aspas (delimitador de cadeia de caracteres) no arquivo CSV. Se não for especificado, o caractere de aspas (") é usado como o caractere de aspas conforme definido no padrão RFC 4180. A notação hexadecimal também é suportada para FIELDQUOTE. ASCII estendido e caracteres de vários bytes não são suportados com UTF-8 para FIELDQUOTE.

Observação

Os caracteres FIELDQUOTE são escapados em colunas de cadeia de caracteres onde há a presença de um duplo FIELDQUOTE (delimitador).

FIELDTERMINATOR = 'field_terminator'

FIELDTERMINATOR Aplica-se apenas ao CSV. Especifica o terminador de campo usado no arquivo CSV. O terminador de campo pode ser especificado usando notação hexadecimal. O terminador de campo pode ser multi-caractere. O terminador de campo padrão é um (,). ASCII estendido e caracteres multibyte não são suportados com UTF-8 para FIELDTERMINATOR.

TERMINADOR DE LINHA = 'row_terminator'

ROW TERMINATOR Aplica-se apenas ao CSV. Especifica o terminador de linha usado no arquivo CSV. O terminador de linha pode ser especificado usando notação hexadecimal. O terminador de linha pode ser multi-caractere. Por padrão, o terminador de linha é \r\n.

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

ASCII estendido e caracteres de vários bytes não são suportados com UTF-8 para ROW TERMINATOR.

PRIMEIRA LINHA = First_row_int

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

DATEFORMAT = { 'mdy' | 'DMY' | «YMD» | «YDM» | 'meu' | 'dym' }

DATEFORMAT só se aplica ao CSV e especifica o formato de data do mapeamento de data para formatos de data do SQL Server. Para obter uma visão geral de todos os tipos e funções de dados de data e hora Transact-SQL, consulte Tipos de dados e funções de data e hora (Transact-SQL). DATEFORMAT dentro do comando COPY tem precedência sobre DATEFORMAT configurado no nível de sessão.

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

CODIFICAÇÃO só se aplica ao CSV. O padrão é UTF8. Especifica o padrão de codificação de dados para os arquivos carregados pelo comando COPY.

IDENTITY_INSERT = «LIGADO» | 'OFF'

IDENTITY_INSERT especifica se o valor ou valores de identidade no arquivo de dados importado devem ser usados para a coluna de identidade. Se IDENTITY_INSERT estiver DESATIVADO (padrão), os valores de identidade para esta coluna serão verificados, mas não importados. O Azure Synapse Analytics atribui automaticamente valores exclusivos com base nos valores de semente e incremento especificados durante a criação da tabela. Observe o seguinte comportamento com o comando COPY:

• Se IDENTITY_INSERT estiver DESATIVADO e a tabela tiver uma coluna de identidade
  • Deve ser especificada uma lista de colunas que não mapeie um campo de entrada para a coluna de identidade.
• Se IDENTITY_INSERT estiver ATIVADO 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 é suportado para a COLUNA IDENTITY na lista de colunas.
• IDENTITY_INSERT só pode ser definido para uma mesa de cada vez.

AUTO_CREATE_TABLE = { 'ON' | 'OFF' }

AUTO_CREATE_TABLE especifica se a tabela pode ser criada automaticamente trabalhando em conjunto com a descoberta automática de esquema. Está disponível apenas para ficheiros Parquet.

• ON: Permite a criação automática de tabelas. O processo COPY INTO cria uma nova tabela automaticamente, descobrindo a estrutura do arquivo a ser carregado. Também pode ser usado com tabelas preexistentes para aproveitar a descoberta automática de esquema de arquivos Parquet.
• OFF: A criação automática de tabelas não está ativada. Inadimplência.

Observação

A criação automática de tabelas funciona em conjunto com a descoberta automática de esquemas. A criação automática de tabelas NÃO está habilitada por padrão.

Não carregue em tabelas distribuídas por hash a partir de arquivos Parquet usando COPY INTO com AUTO_CREATE_TABLE = 'ON'.

Se os arquivos Parquet devem ser carregados em tabelas distribuídas por hash usando COPY INTO, carregue-o em uma tabela de preparo round robin seguida por INSERT ... SELECT dessa tabela para a tabela distribuída de hash de destino.

Permissões

O usuário que executa o comando COPY deve ter as seguintes permissões:

• ADMINISTRAR OPERAÇÕES EM MASSA DE BANCO DE DADOS
• INSERIR

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

Além disso, se o usuário que executa o comando COPY também pretende gerar uma nova tabela e carregar dados nela, eles exigem as 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 de 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];

Comentários

A instrução COPY aceita apenas caracteres UTF-8 e UTF-16 válidos para dados de linha e parâmetros de comando. Arquivos de origem ou parâmetros (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 e parâmetros de origem são compatíveis com UTF-8 ou UTF-16 antes de invocar a instrução COPY.

Exemplos

Um. Carregar a partir de uma conta de armazenamento público

O exemplo a seguir é a forma mais simples do comando COPY, que carrega dados de uma conta de armazenamento público. Neste exemplo, os padrões da instrução COPY correspondem ao formato do arquivo csv do 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 = Sessão DATEFORMAT

• MAXERRORS = 0

• O padrão de COMPRESSÃO é descompactado

• FIELDQUOTE = '"'

• FIELDTERMINATOR = ',;

• ROWTERMINATOR = '\n'

Importante

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

• PRIMEIRA LINHA = 1

• CODIFICAÇÃO = «UTF8»

• FILE_TYPE = «CSV»

• IDENTITY_INSERT = 'DESLIGADO'

B. Carregar autenticação via Share Access Signature (SAS)

O exemplo a seguir carrega arquivos que usam o feed de linha como um terminador de linha, como uma saída UNIX. Este exemplo também usa uma chave SAS para autenticar 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 autenticados via Chave de 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 do 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. Carregar 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 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 deteçã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 tem melhor desempenho dependendo da sua carga de trabalho.

• Os ficheiros comprimidos não podem ser divididos automaticamente. Para obter o melhor desempenho de carregamento, considere dividir sua entrada em vários arquivos ao carregar CSVs compactados.

• Grandes arquivos CSV não compactados podem ser divididos e carregados em paralelo automaticamente, portanto, não há necessidade de dividir manualmente arquivos CSV não compactados na maioria dos casos. Em certos casos em que a divisão automática de arquivos não é viável devido às características dos dados, a divisão manual de CSVs grandes ainda pode beneficiar o desempenho.

Qual é a orientação de divisão de arquivos para o comando COPY carregando arquivos CSV compactados?

As orientações sobre o número de ficheiros são apresentadas no quadro seguinte. Uma vez atingido o número recomendado de ficheiros, terá um melhor desempenho quanto maiores forem os ficheiros. O número de arquivos é determinado pelo número de nós de computação multiplicado por 60. Por exemplo, em 6000DWU temos 12 nós de computação e 12*60 = 720 partições. Para obter uma experiência simples de divisão de arquivos, consulte Como maximizar a taxa de transferência de carga COPY com divisões de arquivos.

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

Qual é a orientação de divisão de arquivos para o comando COPY carregando arquivos Parquet ou ORC?

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

Existem limitações quanto ao número ou tamanho dos ficheiros?

Não há limitações quanto ao número ou tamanho dos ficheiros; no entanto, para um melhor desempenho, recomendamos ficheiros com pelo menos 4 MB.

Existem problemas conhecidos com a instrução COPY?

Se você tiver um espaço de trabalho do Azure Synapse que foi 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 espaço de trabalho:

1. Instale o Azure PowerShell. Consulte Instalar o PowerShell.
2. Registre a identidade gerenciada do seu espaço de trabalho 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