COPIAR EM (Transact-SQL)

Aplica-se a:Azure Synapse Analytics

Este artigo explica como usar a instrução COPY em Azure Synapse Analytics para carregar dados 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.

Use COPY para as seguintes capacidades:

• Use usuários com privilégios mais baixos para carregar dados sem precisar 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.
• Analise e carregue corretamente arquivos CSV em que delimitadores (cadeia de caracteres, campo, linha) são escapados dentro de colunas delimitadas por cadeia de caracteres.
• Especifique um modelo de permissão mais fino sem expor as chaves da conta de armazenamento usando SAS (Assinaturas de Acesso Compartilhado).
• Use uma conta de armazenamento diferente para a ERRORFILE localização (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, um terminador de campo e uma citação de campo para arquivos CSV.
• Use formatos de data 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 de tabela 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 cadeia de caracteres, sem usar outras ferramentas para pré-processar os dados.

Para obter exemplos abrangentes e inícios rápidos usando a instrução COPY , consulte:

• 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

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 você não especificar o esquema e o esquema padrão do usuário que executa a COPY operação for diferente do esquema da tabela especificada, a COPY operação será cancelada e uma mensagem de erro será retornada.

nome_da_tabela

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 você não especifica uma lista de colunas, 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 e assim por diante.

Locais externos

O local em que os arquivos que contêm os dados são preparados. Atualmente, há suporte para Azure Data Lake Storage (ADLS) Gen2 e Armazenamento de Blobs do Azure:

• 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\>

• 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 você especificar uma pasta, 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 período (.) a menos que especificado explicitamente no caminho. Esse comportamento permanece mesmo quando é especificado um caminho com um curinga.

Você pode incluir curingas no caminho em que:

• A correspondência do nome de caminho curinga diferencia maiúsculas de minúsculas
• Você pode escapar de um 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

Você pode especificar vários locais de arquivo somente da 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írgulas em conformidade com o padrão RFC 4180 .
• PARQUET: especifica um formato Parquet.
• ORC: Especifica um formato ORC (Optimized Row Columnar).

FILE_FORMAT = external_file_format_name

FILE_FORMAT aplica-se somente aos arquivos Parquet e ORC. Ele 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 = '')

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.

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

  • IDENTITY: uma constante com um valor de Shared Access Signature
  • SECRET: a assinatura de acesso 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: <ClientID>@<OAuth_2.0_Token_EndPoint>
  • SECRET: chave da entidade de serviço de 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 um valor de Storage Account Key
  • SECRET: chave da conta de armazenamento

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

  • IDENTITY: uma constante com um valor de Managed Identity

• 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 apenas ao CSV. Ele especifica o diretório dentro da COPY instrução em que as linhas rejeitadas e o arquivo de erro correspondente são gravados. Você pode especificar o caminho completo da conta de armazenamento ou do caminho relativo ao contêiner. Se o caminho especificado não existir, o armazém criará um. 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.

Nesse diretório, o warehouse cria uma pasta com base no tempo de envio de carga no formato YearMonthDay -HourMinuteSecond (por exemplo, 20180330-173205). Nessa pasta, o processo grava dois tipos de arquivos: o arquivo motivo (erro) e o arquivo de dados (linha). Cada arquivo anexa o queryIDdistributionIDGUID de arquivo e de 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, COPY será usado ERRORFILE_CREDENTIAL para se conectar a esse armazenamento. Caso contrário, ele usará o valor especificado para CREDENTIAL. Quando você usa a mesma credencial para os dados de origem e ERRORFILErestrições que se aplicam a ERRORFILE_CREDENTIAL também se aplicam.

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

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, entidade de serviço ou Microsoft Entra

• Azure Data Lake Gen2: SAS, MSI, entidade de serviço ou Microsoft Entra

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

  • IDENTITY: uma constante com um valor de Shared Access Signature
  • SECRET: a assinatura de acesso 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: <ClientID>@<OAuth_2.0_Token_EndPoint>
  • SECRET: chave da entidade de serviço de 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

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

  • IDENTITY: uma constante com um valor de Managed Identity

• 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

  • CREDENTIAL não é necessário

• 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 ERRORFILE_CREDENTIAL conta de armazenamento.

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 a operação COPY não puder importar é ignorada e contada como um erro. Se você não especificar um valor para o número máximo de erros, 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 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.

• O 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 para ORC.

O comando COPYetiza automaticamente o tipo de compactação com base na extensão de arquivo quando você não especifica este parâmetro:

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

O comando COPY exige 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, resulta na falha do comando COPY. Para garantir que o COPY seja executado com êxito, verifique se não há lixo à direita no final dos arquivos gzip.

FIELDQUOTE = 'field_quote'

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

FIELDTERMINATOR = 'field_terminator'

FIELDTERMINATOR aplica-se apenas ao CSV. Especifica o terminador de campo usado no arquivo CSV. Você pode especificar o terminador de campo usando notação hexadecimal. O terminador de campo pode ser multicaracter. O terminador de campo padrão é um (,). Não há suporte para caracteres ASCII e multibyte estendidos com UTF-8 para FIELDTERMINATOR.

ROWTERMINATOR = 'row_terminator'

ROWTERMINATOR aplica-se apenas ao CSV. Especifica o terminador de linha usado no arquivo CSV. Você pode especificar o terminador de linha usando notação hexadecimal. O terminador de linha pode ser multicaracter. 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 multicaracter em hexadecimal, não especifique 0x entre cada caractere.

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

FIRSTROW = First_row_int

FIRSTROW aplica-se ao CSV e especifica o número de linha que é lido primeiro em todos os arquivos para o comando COPY. Os valores começam de 1, que é o valor padrão. Se você definir o valor como 2, 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 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 apenas 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' | 'OFF'

IDENTITY_INSERT especifica se o valor de identidade ou os valores no arquivo de dados importado devem ser usados para a coluna de identidade. Se IDENTITY_INSERT for OFF (padrão), os valores de identidade dessa 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
  • Você deve especificar uma lista de colunas que não mapeie um campo de entrada para a coluna de identidade.
• Se IDENTITY_INSERT estiver ON e a tabela tiver uma coluna de identidade
  • Se você passar uma lista de colunas, ela deverá mapear um campo de entrada para a coluna de identidade.
• Não há suporte para o valor padrão para a coluna IDENTITY na lista de colunas.
• Você pode definir IDENTITY_INSERT para apenas uma tabela de cada 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' | 'OFF' }

AUTO_CREATE_TABLE especifica se a tabela pode ser criada automaticamente trabalhando junto com a descoberta automática de esquema. AUTO_CREATE_TABLE está disponível somente para arquivos Parquet em Azure Synapse Analytics.

• LIGADO: habilita a criação automática de tabela. O COPY INTO processo cria automaticamente uma nova tabela descobrindo a estrutura do arquivo a ser carregado. Você também pode usá-lo 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.

Permissions

O usuário que executa o comando COPY 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 COPY instrução aceita apenas caracteres válidos UTF-8 e UTF-16 para dados de linha e parâmetros de comando. A COPY instrução pode interpretar incorretamente arquivos ou parâmetros de origem (como ROWTERMINATOR ou FIELDTERMINATOR) que usam caracteres inválidos e causam resultados inesperados, como corrupção de dados ou outras falhas. Certifique-se de que seus arquivos fonte e parâmetros estejam em conformidade com UTF-8 ou UTF-16 antes de invocar a COPY instrução.

A MAXDOP dica de consulta não tem suporte com COPY INTO.

Para garantir a execução confiável, não altere os arquivos e pastas de origem durante 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.

Se os dados de origem tiverem maior precisão do que a definição da coluna de destino, o valor será truncado, não arredondado, para tipos numéricos, de data e de hora.

Examples

A. Carregar de uma conta de armazenamento público

O exemplo a seguir mostra a forma mais simples do COPY comando, que carrega dados de uma conta de armazenamento pública. Para este exemplo, os COPY padrões da instrução 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 = DATEFORMAT da Sessão

• MAXERRORS = 0

• COMPRESSION O padrão é não comprimido

• FIELDQUOTE = '"'

• FIELDTERMINATOR = ','

• ROWTERMINATOR = '\n'

• FIRSTROW = 1

• ENCODING = 'UTF8'

• FILE_TYPE = 'CSV'

• IDENTITY_INSERT = 'OFF'

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

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

Como o desempenho do comando COPY se compara ao PolyBase?

O desempenho do comando COPY pode ser melhor dependendo da carga de trabalho.

• O warehouse não pode dividir arquivos compactados automaticamente. Para obter o melhor desempenho de carregamento, considere dividir sua entrada em vários arquivos ao carregar CSVs compactados.

• O warehouse pode dividir automaticamente grandes arquivos CSV não compactados para carregamento paralelo, portanto, você geralmente não precisa dividir manualmente arquivos CSV descompactados. 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?

A tabela a seguir descreve o número de arquivos que você deve usar. Quando você atinge o número recomendado de arquivos, obtém um melhor desempenho com arquivos maiores. O número de arquivos é determinado pelo número de nós de computação multiplicado por 60. Por exemplo, em 6000 DWU, você tem 12 nós de computação, portanto, você tem 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 arquivo.

DWU	Número de arquivos
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?

Você não precisa dividir arquivos Parquet e ORC porque o comando COPY divide automaticamente os arquivos. Para obter melhor desempenho, os arquivos Parquet e ORC na conta de armazenamento Azure devem ter 256 MB ou mais.

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

Não há limitações no número ou tamanho dos arquivos. No entanto, para obter melhor desempenho, use arquivos com 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 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 isn't enabled on this server. Please enable Managed Service Identity and try again.

Para solucionar esse problema, registre novamente a identidade gerenciada do workspace:

1. Instale o PowerShell do Azure. Consulte 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

Aplica-se a:Depósito no Microsoft Fabric

Este artigo explica como usar a instrução COPY no Warehouse em Microsoft Fabric para carregamento 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 em seu Warehouse em Microsoft Fabric e é como estratégia para Ingest dados em seu Warehouse em Microsoft Fabric.

No Fabric Data Warehouse, a instrução COPY atualmente dá suporte a formatos de arquivo CSV, JSONL e PARQUET. Para fontes de dados, há suporte para contas de Azure Data Lake Storage Gen2 e fontes do OneLake.

Para obter mais informações sobre como usar COPY INTO em seu Warehouse no Microsoft Fabric, consulte Ingerir dados em seu Warehouse no Microsoft Fabric usando a instrução COPY.

Por padrão, COPY INTO autentica como o usuário Microsoft Entra ID em execução.

Use COPY para as seguintes capacidades:

• Use usuários com privilégios mais baixos para carregar dados sem precisar de permissões CONTROL estritas no 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 dentro de colunas delimitadas por cadeia de caracteres.
• Analise e carregue corretamente arquivos JSONL em que cada linha é um objeto JSON válido e os campos são mapeados usando expressões de caminho JSON.
• Especifique um modelo de permissão mais fino sem expor as chaves da conta de armazenamento usando SAS (Assinaturas de Acesso Compartilhado).
• Use uma conta de armazenamento diferente para a ERRORFILE localização (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, um terminador de campo e uma citação de campo para arquivos CSV.
• Especificar caracteres curinga e vários arquivos no caminho do local de armazenamento.
• Para obter mais informações sobre as opções de ingestão de dados e as práticas recomendadas, consulte Ingestão de dados em seu Warehouse no Microsoft Fabric usando a instrução COPY.

Syntax

COPY INTO [ warehouse_name. ] [ schema_name. ] table_name
[ (Column_list) ]
FROM '<external_location>' [ , ...n ]
WITH
 (
 [ FILE_TYPE = { 'CSV' | 'JSONL' | '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

Opcional se o warehouse atual do usuário que executa a operação for o warehouse da tabela especificada. Se você não especificar o warehouse e o esquema e a tabela especificados não existirem no warehouse atual, COPY falhará e uma mensagem de erro será retornada.

schema_name

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

nome_da_tabela

O nome da tabela para COPY dados. A tabela de destino já deve existir no warehouse.

(column_list)

Uma lista opcional de colunas usadas para mapear campos de dados de origem para colunas de tabela de destino durante a carga de dados.

column_list deve ser colocada entre parênteses e separada por vírgulas. A sintaxe é:

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

• Column_name – é o nome da coluna na tabela de destino.
• Default_value - o valor padrão que substitui qualquer NULL valor no arquivo de entrada. O valor padrão se aplica a todos os formatos de arquivo. COPY Tenta carregar NULL a partir 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 é precedido pela palavra-chave "default"
• Field_number – aplica-se somente a arquivos CSV. Especifica a posição ordinal do campo nos dados de entrada. A indexação de campos começa em 1.
• JSON_path – aplica-se somente a arquivos JSONL. Especifica uma expressão de caminho JSON que identifica o campo a ser extraído de cada objeto JSON (por exemplo, $.CustomerName).

Quando você não especifica column_list, 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 e assim por diante.

Quando você não especifica uma lista de colunas, 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 e assim por diante.

Local externo

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

• 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\>
• Local externo para o OneLake: https://onelake.dfs.fabric.microsoft.com/<workspaceId>/<lakehouseId>/Files/

O ADLS (Azure Data Lake Storage) Gen2 oferece melhor desempenho do que Armazenamento de Blobs do Azure (herdado). Considere usar uma conta do ADLS Gen2 sempre que possível.

• 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 você especificar uma pasta, 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 período (.) a menos que especificado explicitamente no caminho. Esse comportamento permanece mesmo quando é especificado um caminho com um curinga.

Curingas podem ser incluídos no caminho em que

• A correspondência do nome de caminho curinga diferencia maiúsculas de minúsculas
• Você pode escapar de um curinga usando o caractere de barra invertida (\)

Você pode especificar vários locais de arquivo somente da 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>

Locais externos atrás do firewall

Para acessar arquivos no Azure Data Lake Storage (ADLS) Gen2 e locais do Armazenamento de Blobs do Azure que estão por trás de um firewall, os seguintes pré-requisitos se aplicam:

• Uma identidade de workspace para o workspace que hospeda seu warehouse deve ser provisionada. Para obter mais informações sobre como configurar uma identidade de workspace, consulte Identidade do workspace.
• Sua conta do Entra ID deve ser capaz de usar a identidade do espaço de trabalho.
• Sua conta de ID do Entra deve ter acesso aos arquivos subjacentes por meio do RBAC (controle de acesso baseado em função) do Azure ou ACLs de data lake.
• Seu workspace do Fabric que hospeda o warehouse deve ser adicionado como uma regra de instância de recurso. Para obter mais informações sobre como adicionar seu espaço de trabalho do Fabric com uma regra de instância de recurso, consulte Regra de instância de recurso.

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

FILE_TYPE especifica o formato dos dados externos.

• CSV: especifica um arquivo de valores separados por vírgulas em conformidade com o padrão RFC 4180 .
• JSONL: Especifica um arquivo JSON (Linhas JSON) delimitado por nova linha, em que cada linha é um objeto JSON válido.
• PARQUET: especifica um formato Parquet.

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

CREDENTIAL Especifica o mecanismo de autenticação para acessar a conta de armazenamento externo.

No Fabric Data Warehouse:

• COPY INTO não há suporte para o local em que o acesso público está desabilitado.
• Para contas de armazenamento público, os mecanismos de autenticação com suporte são ID do Microsoft Entra, SAS (Assinatura de Acesso Compartilhado) ou SAK (Chave da Conta de Armazenamento).
• Para contas de armazenamento público atrás de um firewall, a autenticação de ID do Microsoft Entra é o único método de autenticação com suporte. COPY INTO usar o OneLake como origem dá suporte apenas à autenticação EntraID.

A autenticação Microsoft Entra ID do usuário é padrão. Nenhuma credencial precisa ser especificada.

• Autenticação com SAS (Assinatura de Acesso Compartilhado)
  • IDENTITY: uma constante com um valor de Shared Access Signature.
  • SECRET: a assinatura de acesso compartilhado fornece acesso delegado aos recursos em sua conta de armazenamento.
  • Permissões mínimas necessárias: READ e LIST.
• Autenticação com chave de conta de armazenamento
  • IDENTITY: uma constante com um valor de Storage Account Key.
  • SECRET: Chave da conta de armazenamento.

ERRORFILE = Local do diretório

ERRORFILE aplica-se a CSV e JSONL. Especifica o diretório em que as linhas rejeitadas e o arquivo de erro correspondente devem ser gravados. Você pode especificar o caminho completo da conta de armazenamento ou do caminho relativo ao contêiner. Se o caminho especificado não existir, o sistema criará um 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.

Nesse diretório, o warehouse cria uma pasta com base no tempo de envio de carga no formato YearMonthDay -HourMinuteSecond (por exemplo, 20180330-173205). Nessa pasta, o warehouse cria uma pasta com a ID da instrução e, nessa pasta, dois tipos de arquivos são gravados: um erro. Arquivo Json que contém os motivos de rejeição e um arquivo row.csv que contém as linhas rejeitadas.

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

Ao usar uma Conta de Armazenamento do Azure protegida por firewall, o arquivo de erro é criado no mesmo contêiner especificado no caminho da conta de armazenamento. Ao considerar o uso da opção ERRORFILE nesse cenário, também é necessário especificar o MAXERROR parâmetro. Se ERRORFILE tiver o caminho completo da conta de armazenamento definido, ele ERRORFILE_CREDENTIAL será usado para se conectar a esse armazenamento. Caso contrário, o valor mencionado será CREDENTIAL usado.

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

ERRORFILE_CREDENTIAL aplica-se a arquivos CSV e JSONL. No Warehouse no Microsoft Fabric, o único mecanismo de autenticação com suporte é SAS (Assinatura de Acesso Compartilhado).

• Autenticação com SAS (Assinaturas de Acesso Compartilhado)
  • IDENTITY: uma constante com um valor de Shared Access Signature
  • SECRET: a assinatura de acesso compartilhado fornece acesso delegado aos recursos em sua conta de armazenamento.
• Permissões mínimas necessárias: READ, LIST, WRITE, CREATE, DELETE

MAXERRORS = max_errors

MAXERRORS aplica-se a CSV e JSONL. Especifica o número máximo de linhas de rejeição permitidas na carga antes que a COPY operação falhe. Cada linha que a COPY operação não pode importar é ignorada e contada como um erro. Se você não especificar um número máximo de erros, o padrão será 0.

Em Fabric Data Warehouse, você não pode usar MAXERRORS quando FILE_TYPE é PARQUET.

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

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

• O CSV dá suporte a GZIP.
• Parquet dá suporte a GZIP e Snappy.
• Não há suporte para JSONL

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

• .gz - GZIP

Atualmente, o carregamento de arquivos compactados só tem suporte com o analisador versão 1.0.

O COPY comando 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, resulta na falha do COPY comando. Para garantir COPY que seja executado com êxito, verifique se não há lixo à direita no final dos arquivos gzip.

FIELDQUOTE = 'field_quote'

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

FIELDTERMINATOR = 'field_terminator'

FIELDTERMINATOR aplica-se apenas ao CSV. Especifica o terminador de campo que será usado no arquivo CSV. Você também pode especificar o terminador de campo usando notação hexadecimal. O terminador de campo pode ser multicaracter. O terminador de campo padrão é um (,). Não há suporte para caracteres ASCII e multibyte estendidos com UTF-8 para FIELDTERMINATOR.

ROWTERMINATOR = 'row_terminator'

ROWTERMINATOR aplica-se apenas ao CSV. Especifica o terminador de linha que será usado no arquivo CSV. Você pode especificar o terminador de linha usando notação hexadecimal. O terminador de linha pode ser multicaracter. Os terminadores padrão são \r\n, \ne \r.

O COPY comando prefixa o \r caractere 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 multicaracter em hexadecimal, não especifique 0x entre cada caractere.

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

FIRSTROW = First_row_int

FIRSTROW aplica-se apenas ao CSV. Especifica o número da linha que é lido primeiro em todos os arquivos do COPY comando. Os valores começam de 1, que é o valor padrão. Se você definir o valor como 2, 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 linhas.

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

DATEFORMAT aplica-se a CSV e JSONL. Especifica o formato de data do mapeamento de data para SQL Server formatos de data. 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 dentro do COPY comando tem precedência sobre DATEFORMAT configurado no nível da sessão.

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

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

PARSER_VERSION = { '1.0' | '2.0' }

PARSER_VERSION aplica-se somente a arquivos CSV. O valor padrão é 2.0. PARSER_VERSION especifica o analisador de arquivos usado para ingestão quando o tipo de arquivo de origem é CSV. O analisador 2.0 oferece desempenho aprimorado para ingestão de arquivos CSV.

A versão 2.0 do analisador tem as seguintes limitações:

• Não há suporte para arquivos CSV compactados.
• Não há suporte para arquivos com codificação UTF-16.
• Multicaracter ou multibyte ROWTERMINATOR, FIELDTERMINATORou FIELDQUOTE não tem suporte. No entanto, \r\n é aceito como padrão ROWTERMINATOR.

Quando você usa o analisador versão 1.0 com arquivos UTF-8, terminadores multibyte e multicaracter não são compatíveis FIELDTERMINATORcom .

O Analisador versão 1.0 está disponível apenas para compatibilidade com versões anteriores. Use-o somente quando encontrar essas limitações.

MATCH_COLUMN_COUNT = { 'ON' | 'DESLIGADO' }

MATCH_COLUMN_COUNT aplica-se somente a arquivos CSV. O valor padrão é OFF. Ele especifica se o COPY comando deve verificar se as linhas de contagem de colunas nos arquivos de origem correspondem à contagem de colunas da tabela de destino. O seguinte comportamento se aplica:

• Se MATCH_COLUMN_COUNT for OFF:
  • O comando ignora colunas excedidos das linhas de origem.
    • O comando insere NULL valores em colunas anuláveis para linhas com menos colunas.
  • Se um valor não for fornecido para uma coluna não anulável, o COPY comando falhará.
• Se MATCH_COLUMN_COUNT for ON:
  • O COPY comando verifica se a contagem de colunas em cada linha de cada arquivo da fonte corresponde à contagem de colunas da tabela de destino.
• Se houver uma incompatibilidade de contagem de colunas, o COPY comando falhará.

Usar COPY INTO com o OneLake

Use COPY INTO para carregar dados diretamente de arquivos armazenados no Fabric OneLake, em itens existentes. Esse método elimina a necessidade de contas de preparo externas, como o ADLS Gen2 ou Armazenamento de Blobs, e permite a ingestão nativa de SaaS governada por workspace usando permissões Fabric. Essa funcionalidade dá suporte a:

• Lendo de qualquer local dentro de um Workspace e um Item
• Cargas de workspace para warehouse dentro do mesmo locatário
• Imposição de identidade nativa usando Microsoft Entra ID

Example:

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

Permissions

Permissões do plano de controle

Para executar o COPY INTO comando, você deve receber a associação a uma função de workspace por meio de Gerenciar o acesso no Workspace, com pelo menos a função Visualizador. Como alternativa, você pode compartilhar o acesso ao warehouse com um usuário por meio de permissões Item no portal Fabric, com pelo menos permissões de leitura. Para se alinhar ao princípio do privilégio mínimo, permissão Leitura é suficiente.

Permissões do plano de dados

Depois de conceder permissões de plano de controle por meio de funções de workspace ou permissões de item, se o usuário tiver permissões de leitura apenas no nível do plano de dados, também conceda ao usuário INSERT e ADMINISTER DATABASE BULK OPERATIONS permissões usando comandos T-SQL.

Por exemplo, o script T-SQL a seguir concede essas permissões a um usuário individual usando seus Microsoft Entra ID.

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

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

Quando você usa a opção de arquivo de erro, o usuário deve ter a permissão mínima de Armazenamento de Blobs Colaborador no contêiner da Conta de Armazenamento.

Quando você usa o OneLake como origem, o usuário deve ter permissões colaborador ou superior no workspace de origem (onde o Lakehouse está localizado) e no workspace de destino (onde reside o Warehouse). Microsoft Entra ID e Fabric funções de workspace regem todo o acesso.

Remarks

A COPY instrução aceita apenas caracteres válidos UTF-8 e UTF-16 para dados de linha e parâmetros de comando. Se você usar arquivos ou parâmetros de origem (como ROWTERMINATOR ou FIELDTERMINATOR) que contenham caracteres inválidos, a COPY instrução poderá interpretá-los incorretamente e causar resultados inesperados, como dados corrompidos ou outras falhas. Antes de invocar a COPY instrução, verifique se os arquivos e parâmetros de origem são compatíveis com UTF-8 ou UTF-16.

A COPY INTO instrução tem restrições sobre o tamanho de colunas varchar(max) individuais e varbinary(max), bem como sobre o tamanho total da linha que você pode ingerir.

• Parquet: tamanho máximo da coluna varchar(max)/varbinary(max) 16 MB, tamanho máximo da linha 1 GB.
• CSV e JSONL: tamanho máximo da coluna varchar(max)/varbinary(max) 1 MB, tamanho máximo da linha de 16 MB.

Para garantir a execução confiável, não altere os arquivos e pastas de origem durante 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 são alterados durante o processo.

Se os dados de origem tiverem maior precisão do que a definição da coluna de destino, o valor será truncado, não arredondado, para tipos numéricos, de data e de hora.

Limitações do OneLake como origem

• Somente a autenticação da ID do Microsoft Entra tem suporte. Outros métodos de autenticação, como tokens SAS, chaves compartilhadas ou cadeias de conexão, não são permitidos.

• Não há suporte para itens de warehouse como locais de origem. Os arquivos devem ter origem em outros itens do Fabric que expõem arquivos por meio do armazenamento do OneLake.

• Os caminhos do OneLake devem usar IDs de workspace e de armazém. Não há suporte para nomes amigáveis para workspaces ou Lakehouses no momento.

• As permissões de colaborador são necessárias em ambos os workspaces. O usuário em execução deve ter pelo menos a função colaborador no workspace do Lakehouse de origem e no workspace do Warehouse de destino.

Examples

Para obter mais informações sobre como usar COPY INTO em seu Warehouse no Microsoft Fabric, consulte Ingerir dados em seu Warehouse no Microsoft Fabric usando a instrução COPY.

A. Carregar de uma conta de armazenamento público

O exemplo a seguir mostra a forma mais simples do COPY comando, que carrega dados de uma conta de armazenamento pública. Para este exemplo, os COPY padrões da instrução 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'

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

• MAXERRORS = 0

• COMPRESSION (o padrão é descompactado)

• FIELDQUOTE = '"'

• FIELDTERMINATOR = ','

• ROWTERMINATOR = '\n'

  Important

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

• FIRSTROW = 1

• ENCODING = 'UTF8'

• FILE_TYPE = 'CSV'

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

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 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>'),
    FIELDQUOTE = '"',
    FIELDTERMINATOR = ';',
    ROWTERMINATOR = '0X0A',
    ENCODING = 'UTF8',
    MAXERRORS = 10,
    ERRORFILE = '/errorsfolder'--path starting from the storage container
)

C. Carregar com uma lista de colunas com valores padrão, autenticando por meio da SAK (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>'),
    FIELDQUOTE = '"',
    FIELDTERMINATOR=',',
    ROWTERMINATOR='0x0A',
    ENCODING = 'UTF8',
    FIRSTROW = 2
)

D. Carregar Parquet

Este exemplo usa um curinga para carregar todos os arquivos Parquet em uma pasta usando o Entra ID do usuário em execução.

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

E. Carregar JSONL

Este exemplo usa um curinga para carregar todos os arquivos JSONL em uma pasta usando o Entra ID do usuário em execução.

COPY INTO test_jsonl
FROM 'https://myaccount.blob.core.windows.net/myblobcontainer/folder1/*.jsonl'
WITH (
    FILE_TYPE = 'JSONL'
)

F. Mapear nomes de coluna para caminhos de campo em documentos JSONL

O exemplo a seguir mostra um arquivo JSONL (Linhas JSON), em que cada linha representa um único objeto JSON:

{"CountryKey": 0, "CountryName": "ALGERIA", "RegionID": 0, "Population": 34800000}
{"CountryKey": 1, "CountryName": "ARGENTINA", "RegionID": 1, "Population": 46044703}
{"CountryKey": 2, "CountryName": "BRAZIL", "RegionID": 1, "Population": 203080756}

Em COPY INTO, você pode mapear colunas de tabela para campos JSON específicos usando expressões de caminho JSON. Esse mapeamento permite ingerir apenas os campos necessários dos dados de origem.

COPY INTO Countries (
  CountryID '$.CountryKey', 
  CountryName '$.CountryName', 
  RegionID '$.RegionKey', 
  Population '$.Population'
)
FROM 'https://myaccount.blob.core.windows.net/myblobcontainer/folder1/countries.jsonl'
WITH (   
    FILE_TYPE = 'JSONL' 
)

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

H. Carregar dados do OneLake

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

Conteúdo relacionado

• Ingerir dados em seu Warehouse no Microsoft Fabric
• Ingerir dados em seu Warehouse usando a instrução COPY