COPIAR PARA (Transact-SQL)

Aplica-se a:Azure Synapse Analytics

• Inicia um teste gratuito Fabric.
• Assistente de Migração para Fabric Data Warehouse.

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

Use COPY para as seguintes capacidades:

• Use utilizadores com privilégios mais baixos para carregar dados sem necessidade de permissões CONTROL rigorosas no armazém de dados.
• Execute uma única instrução T-SQL sem ter que criar nenhum outro objeto de banco de dados.
• Analisar e carregar corretamente ficheiros CSV onde os delimitadores (string, field, row) sejam escapados dentro de colunas delimitadas por strings.
• Especifique um modelo de permissões mais fino sem expor chaves de conta de armazenamento usando Assinaturas de Acesso Partilhado (SAS).
• Use uma conta de armazenamento diferente para a ERRORFILE localização (REJECTED_ROW_LOCATION).
• Personalize os valores padrão para cada coluna de destino e especifique 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 ficheiros CSV.
• Use formatos SQL Server Date para ficheiros CSV.
• Especifique curingas e vários arquivos no caminho do local de armazenamento.
• A descoberta automática de esquemas simplifica o processo de definição e mapeamento dos dados de origem em tabelas alvo.
• O processo automático de criação de tabelas cria automaticamente as tabelas e funciona em conjunto com a descoberta automática de esquemas.
• Carregar diretamente tipos de dados complexos a partir de ficheiros Parquet, como Mapas e Listas, em colunas de string, sem usar outras ferramentas para pré-processar os dados.

Para exemplos abrangentes e inicios rápidos usando a COPY declaração, veja:

• 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

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 para o usuário que executa a operação for o esquema da tabela especificada. Se não especificar o esquema, e o esquema padrão do utilizador que realiza a COPY operação for diferente do esquema da tabela especificada, a COPY operação é cancelada e uma mensagem de erro é devolveda.

nome_da_tabela

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 não especificas uma lista de colunas, COPY mapeia as colunas com base na ordem de origem e alvo: o campo de entrada 1 vai para a coluna alvo 1, o campo 2 vai para a coluna 2, e assim sucessivamente.

Localizações externas

O local onde os ficheiros que contêm os dados são estacionados. Atualmente, Azure Data Lake Storage (ADLS) Gen2 e Armazenamento de Blobs do Azure 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\>

• 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 especificar uma pasta, COPY recupera todos os ficheiros da pasta e de todas as suas subpastas. COPY ignora pastas ocultas e não devolve ficheiros que comecem por sublinhado (_) ou ponto (.), a menos que esteja explicitamente especificado no caminho. Esse comportamento é o mesmo mesmo ao especificar um caminho com um curinga.

Pode incluir wildcards no caminho onde:

• A correspondência de nome de caminho curinga diferencia maiúsculas de minúsculas
• Podes escapar a um coringa usando a personagem com barra inversa (\)
• A expansão 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

Pode especificar múltiplas localizações de ficheiros apenas a partir da mesma conta de armazenamento e contentor através 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 ficheiro de valores separados por vírgulas compatível com a norma 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 apenas a ficheiros Parquet e ORC. Especifica o nome do objeto de formato de ficheiro externo que armazena o tipo de ficheiro e o método de compressão dos dados externos. Para criar um formato de arquivo externo, use CREATE EXTERNAL FILE FORMAT.

CREDENCIAL (IDENTIDADE = '', 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
de Armazenamento de Blob do Azure	SAS/MSI/SERVICE PRINCIPAL/CHAVE/Entra	SAS/KEY	SAS/KEY
Azure Data Lake Gen2	SAS/MSI/SERVICE PRINCIPAL/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 do local externo é necessário para esse método de autenticação.

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

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

  • 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: Microsoft Entra chave principal do serviço de aplicação

• 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

  • IDENTITY: Uma constante com um valor de Storage Account Key
  • SECRET: Chave da conta de armazenamento

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

  • IDENTITY: Uma constante com um valor de Managed Identity

• 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 Synapse Workspace, este papel RBAC não é obrigatório, mas a identidade gerida requer permissões de Controlo de Acesso List (ACL) nos objetos de destino para permitir o acesso de leitura aos ficheiros fonte.

• Autenticando com um usuário do Microsoft Entra

  • CREDENCIAL não é obrigató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 Aplica-se apenas ao CSV. Especifica o diretório dentro da COPY instrução onde estão escritas as linhas rejeitadas e o correspondente ficheiro de erro. Podes especificar o caminho completo a partir da conta de armazenamento ou o caminho relativo ao contentor. Se o caminho especificado não existir, o armazém cria 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 location.

Dentro deste diretório, o armazém cria uma pasta com base no momento de submissão do carregamento no formato YearMonthDay -HourMinuteSecond (por exemplo, 20180330-173205). Nesta pasta, o processo escreve dois tipos de ficheiros: o ficheiro razão (erro) e o ficheiro de dados (linha). Cada ficheiro antepõe o queryID, distributionID, e um GUID do ficheiro. 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, COPY usa ERRORFILE_CREDENTIAL para se ligar a esse armazenamento. Caso contrário, utiliza o valor que especifica para CREDENTIAL. Quando usa a mesma credencial para os dados de origem e ERRORFILE, as restrições que também se aplicam se ERRORFILE_CREDENTIAL aplicam.

ERRORFILE_CREDENTIAL = (IDENTIDADE = '', SECRET = '')

ERRORFILE_CREDENTIAL Aplica-se apenas a ficheiros CSV. A fonte de dados e os métodos de autenticação suportados são:

• Armazenamento de Blobs do Azure: SAS, service principal, or Microsoft Entra

• Azure Data Lake Gen2: SAS, MSI, service principal, or Microsoft Entra

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

  • 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: LER, LISTAR, ESCREVER, CRIAR, EXCLUIR

• Autenticação com Entidades de Serviço

  • IDENTITY: <ClientID>@<OAuth_2.0_Token_EndPoint>
  • SECRET: Microsoft Entra chave principal do serviço de aplicação

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

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

  • IDENTITY: Uma constante com um valor de Managed Identity

• 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

  • CREDENTIAL não é obrigatório

• 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

Usar uma chave de conta de armazenamento não ERRORFILE_CREDENTIAL é suportado.

MAXERRORS = max_errors

MAXERRORS especifica o número máximo de linhas de rejeição permitidas na carga antes de a operação COPY falhar. Cada linha que a operação COPY não pode importar é ignorada e contada como um erro. Se não especificar um valor para o número máximo de erros, o padrão é 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 dado (por exemplo, binário Parquet para inteiro SQL) ainda causam COPY INTO falha, ignorando MAXERRORS.

COMPRESSÃO = { 'DefaultCodec ' | 'Snappy' | 'GZIP' | 'NENHUMA'}

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

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

O comando COPY deteta automaticamente o tipo de compressão com base na extensão do ficheiro quando não especificas este parâmetro:

• .gz - GZIP
• .snappy - Ágil
• .deflate - DefaultCodec (somente Parquet e ORC)

O comando COPY exige que os ficheiros gzip não contenham lixo residual 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 deste formato, como a presença de dados não-gzip a seguir, resulta na falha do comando COPY. Para garantir que o COPY corre bem, certifique-se de que não há lixo a seguir no final dos ficheiros gzip.

FIELDQUOTE = 'field_quote'

FIELDQUOTE aplica-se ao CSV e especifica um único carácter que é usado como aspas (delimitador de string) no ficheiro CSV. Se não especificar este valor, o carácter de aspas (") é usado como o carácter de aspas definido na norma RFC 4180. A notação hexadecimal também é suportada para FIELDQUOTE. Caracteres ASCII estendidos e multibyte não são suportados com UTF-8 para FIELDQUOTE.

FIELDTERMINATOR = 'field_terminator'

FIELDTERMINATOR Aplica-se apenas ao CSV. Especifica o terminador de campo que é usado no ficheiro CSV. Pode especificar o terminador de campo usando notação hexadecimal. O terminador de campo pode ser multicarácter. O terminador de campo por defeito é um (,). Caracteres ASCII estendidos e multibyte não são suportados com UTF-8 para FIELDTERMINATOR.

ROWTERMINATOR = 'row_terminator'

ROWTERMINATOR Aplica-se apenas ao CSV. Especifica o terminador de linha usado no ficheiro CSV. Pode especificar o terminador de linha usando notação hexadecimal. O terminador de linha pode ser multicarácter. 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 linhas multicaracteres em hexadecimal, não especifique 0x entre cada caractere.

Caracteres ASCII estendidos e multibyte não são suportados com UTF-8 para ROWTERMINATOR.

PRIMEIRA LINHA = First_row_int

FIRSTROW aplica-se ao CSV e especifica o número da linha que é lido primeiro em todos os ficheiros para o comando COPY. Os valores começam em 1, que é o valor padrão. Se definires o valor para 2, a primeira linha de cada ficheiro (linha de cabeçalho) é ignorada quando os dados são carregados. As linhas são ignoradas com base na existência de terminadores de linha.

DATEFORMAT = { 'mdy' | 'dmy' | 'ymd' | 'ydm' | 'myd' | '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'

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

IDENTITY_INSERT = 'ON' | 'DESLIGADO'

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

• Se IDENTITY_INSERT for DESLIGADO, e a tabela tiver uma coluna identidade
  • Deve especificar uma lista de colunas que não associe um campo de entrada à coluna identidade.
• Se IDENTITY_INSERT for ON, e a tabela tiver uma coluna identidade
  • Se passar uma lista de colunas, ela deve mapear um campo de entrada para a coluna identidade.
• O valor padrão não é suportado para a coluna IDENTIDADE na lista de colunas.
• Podes pôr IDENTITY_INSERT apenas uma mesa de cada vez.

O Azure Synapse Analytics atribui 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 em conjunto com a descoberta automática de esquemas. AUTO_CREATE_TABLE está disponível apenas para ficheiros Parquet em Azure Synapse Analytics.

• ON: Permite a criação automática de tabelas. O COPY INTO processo cria automaticamente uma nova tabela ao descobrir a estrutura do ficheiro a ser carregado. Também pode usá-lo com tabelas pré-existentes para tirar partido da descoberta automática de esquemas dos ficheiros Parquet.
• OFF: A criação automática de tabelas não está ativada. Default.

Permissions

O utilizador que executa o comando COPY deve ter as seguintes permissões:

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

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];

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 ficheiros fonte ou parâmetros (como ROWTERMINATOR ou FIELDTERMINATOR) que utilizam caracteres inválidos e causem resultados inesperados, como corrupção de dados ou outras falhas. Certifique-se de que os seus ficheiros de origem e parâmetros cumprem UTF-8 ou UTF-16 antes de invocar a COPY instrução.

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

Para garantir uma execução fiável, não altere os ficheiros de origem e pastas durante a COPY INTO operação.

• Modificar, excluir ou substituir quaisquer 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 inconsistentes.
• 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 é truncado, não arredondado, para tipos numéricos, de data e de tempo.

Examples

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

O exemplo seguinte mostra a forma mais simples do COPY comando, que carrega dados a partir de uma conta pública de armazenamento. Neste exemplo, os COPY valores predefinidos da declaração correspondem ao formato do ficheiro 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

• COMPRESSION O padrão é não comprimido

• FIELDQUOTE = '"'

• FIELDTERMINATOR = ','

• ROWTERMINATOR = '\n'

• FIRSTROW = 1

• ENCODING = 'UTF8'

• FILE_TYPE = 'CSV'

• IDENTITY_INSERT = 'DESLIGADO'

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

O exemplo seguinte carrega ficheiros que usam o avanço de linha como 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>'),
    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'
)

FAQ

Como é que o desempenho do comando COPY se compara ao do PolyBase?

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

• O armazém não pode dividir automaticamente ficheiros comprimidos. Para o melhor desempenho de carregamento, considere dividir a sua entrada em vários ficheiros ao carregar CSVs comprimidos.

• O armazém pode dividir automaticamente ficheiros CSV grandes e não comprimidos para carregamento paralelo, por isso normalmente não precisas de dividir manualmente ficheiros CSV não comprimidos. Em certos casos em que a divisão automática de ficheiros não é viável devido às características dos dados, dividir manualmente CSVs grandes pode ainda beneficiar o desempenho.

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

A tabela seguinte descreve o número de ficheiros que deve utilizar. Quando atinges o número recomendado de ficheiros, obténs melhor desempenho com ficheiros maiores. O número de ficheiros é determinado pelo número de nós de computação multiplicado por 60. Por exemplo, a 6000 DWU, tens 12 nós de computação, por isso tens 12 * 60 = 720 partições. Para uma experiência simples de divisão de ficheiros, veja Como maximizar o débito de carga COPY com divisões de ficheiros.

DWU	Número de ficheiros
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 precisas de dividir ficheiros Parquet e ORC porque o comando COPY divide automaticamente os ficheiros. Para melhor desempenho, os ficheiros Parquet e ORC na conta de armazenamento do Azure devem ter 256 MB ou mais.

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 melhor desempenho, use ficheiros com pelo menos 4 MB. Além disso, limite a contagem de arquivos de origem a um máximo de 5.000 arquivos para um melhor desempenho.

Existem problemas conhecidos com a instrução COPY?

Se tiver um espaço de trabalho Azure Synapse que criou antes de 7 de dezembro de 2020, pode deparar-se com uma mensagem de erro semelhante ao autenticar usando Identidade Gerida: com.microsoft.sqlserver.jdbc.SQLServerException: Managed Service Identity isn't enabled on this server. Please enable Managed Service Identity and try again.

Para contornar este problema, volte a registar a identidade gerida do espaço de trabalho:

1. Instale o Azure PowerShell. Ver Instalar PowerShell.
2. Registe a identidade gerida 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

Aplica-se a:Warehouse no Microsoft Fabric

Este artigo explica como usar a instrução COPY no Warehouse in Microsoft Fabric para carregar a partir de contas de armazenamento externas. A instrução COPY oferece a maior flexibilidade para a ingestão de dados de alto débito no seu Warehouse em Microsoft Fabric, e serve como estratégia para Ingerir dados no seu Warehouse em Microsoft Fabric.

Em Fabric Data Warehouse, a instrução COPY suporta atualmente formatos de ficheiro CSV, JSONL e PARQUET. Para fontes de dados, são suportadas contas Azure Data Lake Storage Gen2 e fontes OneLake.

Para mais informações sobre como usar COPY INTO no seu Warehouse no Microsoft Fabric, consulte Ingest data into your Warehouse no Microsoft Fabric usando a instrução COPY.

Por defeito, COPY INTO autentica-se como o utilizador Microsoft Entra ID executante.

Use COPY para as seguintes capacidades:

• Use utilizadores com privilégios mais baixos para carregar dados sem necessidade de permissões CONTROL rigorosas no armazém.
• Execute uma única instrução T-SQL sem ter que criar nenhum outro objeto de banco de dados.
• Analise e carregue corretamente os arquivos CSV onde delimitadores (string, field, row) são escapados dentro de colunas delimitadas por cadeia de caracteres.
• Analisar e carregar corretamente ficheiros JSONL onde cada linha é um objeto JSON válido e os campos são mapeados usando expressões de caminho JSON.
• Especifique um modelo de permissões mais fino sem expor chaves de conta de armazenamento usando Assinaturas de Acesso Partilhado (SAS).
• Use uma conta de armazenamento diferente para a ERRORFILE localização (REJECTED_ROW_LOCATION).
• Personalize os valores padrão para cada coluna de destino e especifique 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 ficheiros CSV.
• Especifique curingas e vários arquivos no caminho do local de armazenamento.
• Para mais informações sobre opções de ingestão de dados e boas práticas, consulte Ingest data into your 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 depósito atual para o usuário que executa a operação for o depósito da tabela especificada. Se não especificares o armazém, e o esquema e a tabela especificados não existirem no armazém atual, COPY falha e aparece uma mensagem de erro.

schema_name

Opcional se o esquema padrão para o usuário que executa a operação for o esquema da tabela especificada. Se não especificar o esquema, e o esquema padrão do utilizador que realiza a COPY operação for diferente do esquema da tabela especificada, COPY é cancelado e é devolvida uma mensagem de erro.

nome_da_tabela

O nome da tabela para COPY os dados. A tabela de destino já deve existir no armazém.

(column_list)

Uma lista opcional de colunas usada para mapear campos de dados de origem para colunas de tabela alvo durante o carregamento de dados.

column_list devem ser colocados entre parênteses e delimitados 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 ficheiro de entrada. O valor padrão aplica-se a todos os formatos de arquivo. COPY tenta carregar NULL a partir do ficheiro de entrada quando uma coluna é omitida da lista de colunas ou quando há um campo de ficheiro de entrada vazio. O valor padrão é precedido pela palavra-chave 'default'
• Field_number - Aplica-se apenas a ficheiros CSV. Especifica a posição ordinal do campo nos dados de entrada. A indexação de campo começa em 1.
• JSON_path - Aplica-se apenas a ficheiros JSONL. Especifica uma expressão de caminho JSON que identifica o campo a extrair de cada objeto JSON (por exemplo, $.CustomerName).

Quando não especificas column_list, COPY mapeia colunas com base na ordem de origem e alvo: o campo de entrada 1 vai para a coluna alvo 1, o campo 2 vai para a coluna 2, e assim sucessivamente.

Quando não especificas uma lista de colunas, COPY mapeia as colunas com base na ordem de origem e alvo: o campo de entrada 1 vai para a coluna alvo 1, o campo 2 vai para a coluna 2, e assim sucessivamente.

Localização externa

Especifica onde os ficheiros que contêm os dados estão estacionados. Atualmente, Azure Data Lake Storage (ADLS) Gen2, Armazenamento de Blobs do Azure e OneLake 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\>
• Localização externa do OneLake: https://onelake.dfs.fabric.microsoft.com/<workspaceId>/<lakehouseId>/Files/

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

• 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 especificar uma pasta, COPY recupera todos os ficheiros da pasta e de todas as suas subpastas. COPY ignora pastas ocultas e não devolve ficheiros que comecem por sublinhado (_) ou ponto (.), a menos que esteja explicitamente especificado no caminho. Esse comportamento é o mesmo mesmo ao especificar um caminho com um curinga.

Curingas podem ser incluídos no caminho onde

• A correspondência de nome de caminho curinga diferencia maiúsculas de minúsculas
• Podes escapar a um coringa usando a personagem com barra inversa (\)

Pode especificar múltiplas localizações de ficheiros apenas a partir da mesma conta de armazenamento e contentor através 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 de de firewall

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

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

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

FILE_TYPE especifica o formato dos dados externos.

• CSV: Especifica um ficheiro de valores separados por vírgulas compatível com a norma RFC 4180 .
• JSONL: Especifica um ficheiro JSON (JSON Lines) delimitado por novas linhas, onde cada linha é um objeto JSON válido.
• PARQUET: Especifica um formato Parquet.

CREDENCIAL (IDENTIDADE = '', SECRET = '')

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

No Data Warehouse da malha:

• COPY INTO não é suportado onde o acesso público está desativado.
• Para contas de armazenamento público, os mecanismos de autenticação suportados são Microsoft Entra ID, Assinatura de Acesso Compartilhado (SAS) ou Chave de Conta de Armazenamento (SAK).
• Para contas de armazenamento público atrás de um firewall, a autenticação do Microsoft Entra ID é o único método de autenticação suportado. COPY INTO usar o OneLake como fonte suporta apenas a autenticação EntraID.

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

• Autenticação com Assinatura de Acesso Compartilhado (SAS)
  • IDENTITY: Uma constante com 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 valor de Storage Account Key.
  • SECRET: Chave da conta de armazenamento.

ERRORFILE = Localização do Diretório

ERRORFILE Aplica-se ao CSV e JSONL. Especifica o diretório onde as linhas rejeitadas e o arquivo de erro correspondente devem ser gravados. Podes especificar o caminho completo a partir da conta de armazenamento ou o caminho relativo ao contentor. Se o caminho especificado não existir, o sistema cria um em teu 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.

Dentro deste diretório, o armazém cria uma pasta com base no momento de submissão do carregamento no formato YearMonthDay -HourMinuteSecond (por exemplo, 20180330-173205). Nesta pasta, o armazém cria uma pasta com o ID da instrução e, sob essa pasta, são escritos dois tipos de ficheiros: um erro. Json contendo as razões de rejeição e um ficheiro row.csv contendo as linhas rejeitadas.

Se ERRORFILE tiver o caminho completo da conta de armazenamento definido, então o ERRORFILE_CREDENTIAL é usado para se ligar a esse armazenamento. Caso contrário, o valor mencionado para CREDENTIAL é usado. Quando a mesma credencial usada para os dados de origem é usada para ERRORFILE, também se aplicam restrições ERRORFILE_CREDENTIAL que se 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 a utilização da ERRORFILE opção neste cenário, também é necessário especificar o MAXERROR parâmetro. Se ERRORFILE tiver o caminho completo da conta de armazenamento definido, então o ERRORFILE_CREDENTIAL é usado para se ligar a esse armazenamento. Caso contrário, o valor mencionado para CREDENTIAL é usado.

ERRORFILE_CREDENTIAL = (IDENTIDADE = '', SECRET = '')

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

• Autenticação com assinaturas de acesso compartilhado (SAS)
  • 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: LER, LISTAR, ESCREVER, CRIAR, EXCLUIR

MAXERRORS = max_errors

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

Em Fabric Data Warehouse, não podes usar MAXERRORS quando FILE_TYPE é PARQUET.

COMPRESSÃO = { 'Snappy' | 'GZIP' | 'NENHUMA'}

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

• O CSV suporta GZIP.
• Parquet suporta GZIP e Snappy.
• Não suportado para JSONL

O COPY comando deteta automaticamente o tipo de compressão com base na extensão do ficheiro quando este parâmetro não é especificado:

• .gz - GZIP

O carregamento de ficheiros comprimidos é atualmente suportado apenas com o parser versão 1.0.

O COPY comando exige que os ficheiros gzip não contenham lixo residual 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 deste formato, como a presença de dados posteriores não gzip, resulta na falha do COPY comando. Para garantir COPY que as execuções correm bem, certifica-te de que não há lixo residual no final dos ficheiros gzip.

FIELDQUOTE = 'field_quote'

FIELDQUOTE Aplica-se apenas ao CSV. Especifica um único caractere que é usado como o caractere de aspas (delimitador de cadeia de caracteres) no arquivo CSV. Se não especificar FIELDQUOTE, o carácter de aspas (") é usado como o carácter de aspas conforme definido na norma RFC 4180. A notação hexadecimal também é suportada para FIELDQUOTE. Caracteres ASCII estendidos e multibyte não são suportados com UTF-8 para FIELDQUOTE.

FIELDTERMINATOR = 'field_terminator'

FIELDTERMINATOR Aplica-se apenas ao CSV. Especifica o terminador de campo usado no arquivo CSV. Também podes especificar o terminador de campo usando notação hexadecimal. O terminador de campo pode ser multicarácter. O terminador de campo padrão é um (,). Caracteres ASCII estendidos e multibytes não são suportados com UTF-8 para FIELDTERMINATOR.

ROWTERMINATOR = 'row_terminator'

ROWTERMINATOR Aplica-se apenas ao CSV. Especifica o terminador de linha usado no arquivo CSV. Pode especificar o terminador de linha usando notação hexadecimal. O terminador de linha pode ser multicarácter. Os terminadores padrão são \r\n, \ne \r.

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

Caracteres ASCII estendidos e multibyte não são suportados com UTF-8 para ROWTERMINATOR.

PRIMEIRA LINHA = First_row_int

FIRSTROW Aplica-se apenas ao CSV. Especifica o número da linha que é lido primeiro em todos os ficheiros do COPY comando. Os valores começam em 1, que é o valor padrão. Se definires o valor para 2, a primeira linha de cada ficheiro (linha de cabeçalho) é ignorada quando os dados são carregados. As linhas são ignoradas com base na existência de terminadores de linha.

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

DATEFORMAT aplica-se a CSV e JSONL. 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). O DATEFORMAT dentro do COPY comando tem prioridade sobre o DATEFORMAT configurado ao nível da sessão.

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

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

PARSER_VERSION = { '1.0' | '2.0' }

PARSER_VERSION Aplica-se apenas a ficheiros CSV. O valor padrão é 2.0. PARSER_VERSION especifica o analisador de ficheiros usado para a ingestão quando o tipo de ficheiro de origem é CSV. O analisador 2.0 oferece melhor desempenho para ingestão de arquivos CSV.

O Parser versão 2.0 tem as seguintes limitações:

• Ficheiros CSV comprimidos não são suportados.
• Ficheiros com codificação UTF-16 não são suportados.
• Multipersonagem ou multibyte ROWTERMINATOR, FIELDTERMINATOR, ou FIELDQUOTE não é suportado. No entanto, \r\n é aceite como padrão ROWTERMINATOR.

Quando usas o parser versão 1.0 com ficheiros UTF-8, terminadores multibyte e multicarácter não são suportados para FIELDTERMINATOR.

A versão 1.0 do analisador está disponível apenas para compatibilidade retroativa. Usa-o apenas quando encontrares estas limitações.

MATCH_COLUMN_COUNT = { 'ON' | 'DESLIGADO' }

MATCH_COLUMN_COUNT Aplica-se apenas a ficheiros CSV. O valor predefinido é OFF. Especifica se o COPY comando deve verificar se as linhas de contagem de colunas nos ficheiros de origem correspondem à contagem de colunas da tabela de destino. O seguinte comportamento se aplica:

• Se MATCH_COLUMN_COUNT é OFF:
  • O comando ignora o excesso de colunas 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 a uma coluna não anulável, o COPY comando falha.
• Se MATCH_COLUMN_COUNT é ON:
  • O COPY comando verifica se a contagem de colunas em cada linha de cada ficheiro da fonte corresponde à contagem de colunas da tabela de destino.
• Se houver um desajuste no número de colunas, o COPY comando falha.

Use COPY INTO com o OneLake

Use COPY INTO para carregar dados diretamente a partir de ficheiros armazenados no Fabric OneLake, sob itens existentes. Este método elimina a necessidade de contas externas de staging, como ADLS Gen2 ou Armazenamento de Blobs, e permite a ingestão nativa SaaS governada pelo espaço de trabalho através das permissões do Fabric. Esta funcionalidade suporta:

• Ler a partir de qualquer local dentro de um Workspace e de um Item
• Cargas do espaço de trabalho para o armazém dentro do mesmo locatário
• Aplicação nativa de identidade usando o 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, deve ser concedida a membro de um papel de espaço de trabalho através de Gerir acesso no Espaço de Trabalho, pelo menos com o papel de Visualizador. Alternativamente, pode partilhar o acesso ao armazém com um utilizador através de Item Permissions no portal Fabric, com pelo menos permissões de leitura. Para se alinhar com o princípio do menor privilégio, permissão de Ler é suficiente.

Permissões do plano de dados

Depois de conceder permissões no plano de controlo através de funções de workspace ou de items, se o utilizador só tiver permissões de leitura ao nível do plano de dados, conceda também permissões ao utilizador INSERT usando ADMINISTER DATABASE BULK OPERATIONS comandos T-SQL.

Por exemplo, o script T-SQL seguinte concede estas permissões a um utilizador individual usando o seu Microsoft Entra ID.

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

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

Quando usar a opção de ficheiro de erro, o utilizador deve ter a permissão mínima do Armazenamento de Blobs Contributor no contentor da Conta de Armazenamento.

Quando usa o OneLake como fonte, o utilizador deve ter permissões de Contribuidor ou superiores tanto no espaço de trabalho de origem (onde a Casa do Lago está localizado) como no espaço de trabalho alvo (onde o Armazém se encontra). Os papéis de espaço de trabalho Microsoft Entra ID e Fabric governam todos os acessos.

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 usar ficheiros fonte ou parâmetros (como ROWTERMINATOR ou FIELDTERMINATOR) que contenham caracteres inválidos, a COPY instrução pode interpretá-los incorretamente e causar resultados inesperados, como corrupção de dados ou outras falhas. Antes de invocar a COPY instrução, certifique-se de que os seus ficheiros fonte e parâmetros estão em conformidade com UTF-8 ou UTF-16.

A COPY INTO declaração tem restrições quanto ao tamanho das colunas individuais varchar(max) e varbinary(max ), bem como ao tamanho total da linha que 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 16 MB.

Para garantir uma execução fiável, não altere os ficheiros de origem e pastas durante a COPY INTO operação.

• Modificar, excluir ou substituir quaisquer 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 inconsistentes.
• 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 é truncado, não arredondado, para tipos numéricos, de data e de tempo.

Limitações para OneLake como fonte

• Apenas a autenticação Microsoft Entra ID é suportada. Outros métodos de autenticação, como tokens SAS, chaves partilhadas ou strings de ligação, não são permitidos.

• Os itens de armazém não são suportados como locais de origem. Os ficheiros devem originar-se de outros itens Fabric que expõem ficheiros através do armazenamento OneLake.

• Os caminhos do OneLake devem usar IDs de espaço de trabalho e depósito. Nomes amigáveis para espaços de trabalho ou Casas do Lago não são suportados neste momento.

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

Examples

Para mais informações sobre como usar COPY INTO no seu Warehouse no Microsoft Fabric, consulte Ingest data into your Warehouse no Microsoft Fabric usando a instrução COPY.

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

O exemplo seguinte mostra a forma mais simples do COPY comando, que carrega dados a partir de uma conta pública de armazenamento. Neste exemplo, os COPY valores predefinidos da declaração correspondem ao formato do ficheiro 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 é não comprimido)

• FIELDQUOTE = '"'

• FIELDTERMINATOR = ','

• ROWTERMINATOR = '\n'

  Important

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

• FIRSTROW = 1

• ENCODING = 'UTF8'

• FILE_TYPE = 'CSV'

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

O exemplo seguinte carrega ficheiros que usam o avanço de linha como 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>'),
    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 autenticados por meio da Chave de Conta de Armazenamento (SAK)

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. Pavimento de carga

Este exemplo utiliza um coringa para carregar todos os ficheiros Parquet sob uma pasta usando o Entra ID do utilizador executante.

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

E. Carregar JSONL

Este exemplo utiliza um coringa para carregar todos os ficheiros JSONL sob uma pasta, usando o Entra ID do utilizador executante.

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

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

O exemplo seguinte mostra um ficheiro JSON Lines (JSONL), onde 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, podes mapear colunas de tabelas para campos JSON específicos usando expressões de caminho JSON. Este mapeamento permite-lhe ingerir apenas os campos necessários a partir 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 múltiplos ficheiros

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. Dados de carregamento 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 depósito no Microsoft Fabric
• Ingerir dados em seu Armazém usando a instrução COPY