`COPY INTO`

Aplica-se a: marcado como sim Databricks SQL Databricks Runtime

Carrega dados de um local de arquivo em uma tabela Delta. Esta é uma operação repetível e idempotente — Os ficheiros no local de origem que já foram carregados são ignorados. Isso é verdade mesmo se os arquivos foram modificados desde que foram carregados. Para obter exemplos, consulte Padrões comuns de carregamento de dados usando COPY INTO.

Sintaxe

COPY INTO target_table [ BY POSITION | ( col_name [ , <col_name> ... ] ) ]
  FROM { source_clause |
         ( SELECT expression_list FROM source_clause ) }
  FILEFORMAT = data_source
  [ VALIDATE [ ALL | num_rows ROWS ] ]
  [ FILES = ( file_name [, ...] ) | PATTERN = glob_pattern ]
  [ FORMAT_OPTIONS ( { data_source_reader_option = value } [, ...] ) ]
  [ COPY_OPTIONS ( { copy_option = value } [, ...] ) ]

source_clause
  source [ WITH ( [ CREDENTIAL { credential_name |
                                 (temporary_credential_options) } ]
                  [ ENCRYPTION (encryption_options) ] ) ]

Parâmetros

target_table

Identifica uma tabela Delta existente. O target_table não deve incluir uma especificação temporal ou uma especificação de opções.

Se o nome da tabela for fornecido na forma de uma localização, como: delta.`/path/to/table` , o Unity Catalog pode controlar o acesso às localizações para os quais se está a escrever. Você pode escrever num local externo através de:
- Definir o local como um local externo e ter WRITE FILES permissões nesse local externo.
- Ter permissões WRITE FILES numa credencial de armazenamento nomeada que forneçam autorização para escrever num local usando: COPY INTO delta.`/some/location` WITH (CREDENTIAL <named-credential>)
Consulte Conectar-se ao armazenamento de objetos na nuvem usando o Unity Catalog para obter mais detalhes.
BY POSITION | ( col_name [ , <col_name> ... ] )

Faz a correspondência entre as colunas de origem e as colunas da tabela de destino por posição ordinal. A conversão de tipo das colunas correspondentes é feita automaticamente.

Este parâmetro só é suportado para o formato de arquivo CSV sem cabeçalho. Você deve especificar FILEFORMAT = CSV. FORMAT_OPTIONS também deve ser definido como ("headers" = "false") (FORMAT_OPTIONS ("headers" = "false") é o padrão).

Sintaxe opção 1: BY POSITION
- Faz a correspondência entre as colunas de origem e as colunas da tabela de destino por posição ordinal automaticamente.
  - A correspondência de nome padrão não é utilizada para esse fim.
  - IDENTITY colunas e GENERATED colunas da tabela de destino são ignoradas durante o processo de correspondência com as colunas de origem.
  - Se o número de colunas de origem não for igual às colunas filtradas da tabela de destino, COPY INTO gerará um erro.
Sintaxe opção 2: ( col_name [ , <col_name> ... ] )
- Faz a correspondência entre colunas de origem e as colunas da tabela de destino especificadas por posição ordinal relativa usando uma lista de nomes de colunas da tabela de destino entre parênteses, separada por vírgula.
  - A ordem e os nomes originais das colunas da tabela não são usados para fazer a correspondência.
  - IDENTITY colunas e GENERATED colunas não podem ser especificadas na lista de nomes de colunas, caso contrário, COPY INTO gera um erro.
  - As colunas especificadas não podem ser duplicadas.
  - Quando o número de colunas de origem não é igual às colunas da tabela especificadas, COPY INTO gera um erro.
  - Para as colunas que não são especificadas na lista de nomes de colunas, COPY INTO atribui valores padrão, se houver, e atribui NULL o contrário. Se qualquer coluna não for anulável, COPY INTO gerará um erro.
source

O local do arquivo a partir do qual os dados serão carregados. Os arquivos neste local devem ter o formato especificado em FILEFORMAT. O local é fornecido na forma de um URI.

O acesso ao local de origem pode ser fornecido através de:
- credential_name
  
  Nome opcional da credencial usada para acessar ou gravar no local de armazenamento. Você usa essa credencial somente se o local do arquivo não estiver incluído em um local externo. Ver credential_name.
- Credenciais temporárias em linha.
- Definir o local de origem como um local externo e ter READ FILES permissões no local externo através do Unity Catalog.
- Usando uma credencial de armazenamento nomeada com permissões READ FILES que fornecem autorização para ler de um local através do Unity Catalog.
Você não precisará fornecer credenciais embutidas ou nomeadas se o caminho já estiver definido como um local externo que você tenha permissões para usar. Consulte Visão geral de locais externos para obter mais detalhes.

Nota

Se o caminho do arquivo de origem for um caminho raiz, adicione uma barra (/) no final do caminho do arquivo, por exemplo, s3://my-bucket/.

As opções de credenciais aceites são:
- AZURE_SAS_TOKEN para ADLS e Armazenamento de Blobs do Azure
- AWS_ACCESS_KEY, AWS_SECRET_KEYe AWS_SESSION_TOKEN para o AWS S3
As opções de encriptação aceites são:
- TYPE = 'AWS_SSE_C'e MASTER_KEY para o AWS S3

Consulte Carregar dados usando COPY INTO com credenciais temporárias.

SELECT expression_list

Seleciona as colunas ou expressões especificadas dos dados de origem antes de copiar para a tabela Delta. As expressões podem ser qualquer coisa utilizada com instruções SELECT, incluindo operações de janela. Você pode usar expressões de agregação somente para agregações globais – não é possível GROUP BY em colunas com essa sintaxe.
FILEFORMAT = data_source

O formato dos arquivos de origem a serem carregados. Um dos CSV, JSON, AVRO, ORC, PARQUET, TEXT, BINARYFILE.
VALIDATE

Aplica-se a: Databricks SQL Databricks Runtime 10.4 LTS e superior

Os dados a serem carregados em uma tabela são validados, mas não gravados na tabela. Essas validações incluem:
- Se os dados podem ser analisados.
- Se o esquema corresponde ao da tabela ou se o esquema precisa ser evoluído.
- Se todas as restrições de anulabilidade e verificação são atendidas.
O padrão é validar todos os dados que serão carregados. Você pode fornecer várias linhas a serem validadas com a ROWS palavra-chave, como VALIDATE 15 ROWS. A instrução COPY INTO retorna uma visualização dos dados de 50 linhas ou menos quando um número menor que 50 é utilizado com a palavra-chave ROWS.
FILES

Uma lista de nomes de ficheiros a carregar, com um limite de 1000 ficheiros. Não pode ser especificado com PATTERN.

PATTERN

Um padrão glob que identifica os arquivos a serem carregados a partir do diretório de origem. Não pode ser especificado com FILES.

Padrão	Descrição
`?`	Corresponde a qualquer caractere
`*`	Corresponde a zero caracteres ou mais
`[abc]`	Corresponde a um único caractere do conjunto de caracteres {a,b,c}.
`[a-z]`	Corresponde a um único caractere do intervalo de caracteres {a... z}.
`[^a]`	Corresponde a um único caractere que não é do conjunto de caracteres ou intervalo {a}. Note que o caractere `^` deve ocorrer imediatamente à direita do colchete de abertura.
`{ab,cd}`	Corresponde a uma string do conjunto de strings {ab, cd}.
`{ab,c{de, fh}}`	Corresponde a uma string do conjunto de strings {ab, cde, cfh}.

FORMAT_OPTIONS

Opções a serem passadas para o leitor de fonte de dados Apache Spark para o formato especificado. Consulte Opções de formato para cada formato de arquivo.
COPY_OPTIONS

Opções para controlar o funcionamento do COPY INTO comando.
- force: booleano, padrão false. Se definido como true, a idempotência é desativada e os arquivos são carregados independentemente de já terem sido carregados anteriormente.
- mergeSchema: booleano, padrão false. Se definido como true, o esquema pode ser evoluído de acordo com os dados recebidos.

Invoque `COPY INTO` simultaneamente

COPY INTO suporta invocações simultâneas na mesma tabela. Contanto que COPY INTO seja invocado simultaneamente em conjuntos distintos de arquivos de entrada, cada invocação deve eventualmente ser bem-sucedida, caso contrário, você terá um conflito de transação. COPY INTO não devem ser invocados simultaneamente para melhorar o desempenho; Um único COPY INTO comando com vários arquivos normalmente tem um desempenho melhor do que executar comandos simultâneos COPY INTO com um único arquivo cada. COPY INTO pode ser chamado simultaneamente quando:

Vários produtores de dados não têm uma maneira fácil de coordenar e não podem fazer uma única invocação.
Quando um diretório muito grande pode ser processado subdiretório por subdiretório. Ao ingerir diretórios com um número muito grande de arquivos, o Databricks recomenda o uso do Auto Loader quando possível.

Aceder aos metadados do ficheiro

Para saber como acessar metadados para fontes de dados baseadas em arquivo, consulte Coluna de metadados de arquivo.

Opções de formato

Para opções específicas para cada formato de ficheiro (JSON, CSV, XML, Parquet, Avro, texto, ORC e binário), consulte opções DataFrameReader.

Comentários

Esta página foi útil?

Last updated on 2026-06-01

COPY INTO