COPY INTO

Aplica-se a: SQL do Databricks Runtime do Databricks

Carrega dados de um local de arquivo em uma tabela Delta. Essa é uma operação que pode ser repetida e idempotente—os arquivos no local de origem que já foram carregados são ignorados. Isso é verdade mesmo que os arquivos tenham sido 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 do Delta existente. O target_table não deve incluir uma especificação temporal ou especificação de opções.

  Se o nome da tabela for fornecido na forma de um local, como: delta.`/path/to/table` , o Catálogo do Unity poderá controlar o acesso aos locais aos quais estão sendo gravados. Você pode gravar em um local externo:

  • Definindo o local como um local externo e tendo permissões WRITE FILES nesse local externo.
  • Ter permissões WRITE FILES em uma credencial de armazenamento nomeada que fornecem autorização para gravar em um local usando: COPY INTO delta.`/some/location` WITH (CREDENTIAL <named-credential>)

  Consulte Conectar-se ao armazenamento de objetos de nuvem usando o Catálogo do Unity para obter mais detalhes.

• BY POSITION | ( col_name [ , <col_name> ... ] )

  Corresponde as colunas de origem a colunas de tabela de destino por posição ordinal. A conversão de tipo das colunas correspondentes é feita automaticamente.

  Esse parâmetro só tem suporte para o formato de arquivo CSV sem cabeçalho. É preciso especificar FILEFORMAT = CSV. FORMAT_OPTIONS também deve ser definido como ("headers" = "false") (FORMAT_OPTIONS ("headers" = "false") é o padrão).

  Opção de sintaxe 1: BY POSITION

  • Corresponde as colunas de origem a colunas de tabela de destino por posição ordinal automaticamente.
    • A correspondência de nome padrão não é usada para correspondência.
    • As colunas IDENTITY e GENERATED da tabela de destino são ignoradas ao corresponder às colunas de origem.
    • Se o número de colunas de origem não for igual às colunas de tabela de destino filtradas, COPY INTO gerará um erro.

  Opção de sintaxe 2: ( col_name [ , <col_name> ... ] )

  • Corresponde as colunas de origem às colunas de tabela de destino especificadas por posição ordinal relativa usando uma lista de nomes de coluna de tabela de destino entre parênteses, separadas por vírgula.
    • Os nomes de coluna e ordem da coluna da tabela original não são usados para correspondência.
    • As colunas IDENTITY e GENERATED não podem ser especificadas na lista de nomes de coluna, caso contrário, COPY INTO gerará um erro.
    • As colunas especificadas não podem ser duplicadas.
    • Quando o número de colunas de origem não é igual às colunas de tabela especificadas, COPY INTO gera um erro.
    • Para as colunas que não são especificadas na lista de nomes de coluna, COPY INTO atribui valores padrão, se houver. Caso contrário, atribui NULL. Se qualquer coluna não for anulável, COPY INTO gerará um erro.

• source

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

  O acesso ao local de origem pode ser fornecido por meio de:

  • credential_name

    Nome opcional da credencial usada para acessar ou gravar no local de armazenamento. Você usará essa credencial somente se o local do arquivo não estiver incluído em um local externo. Confira credential_name.

  • Credenciais temporárias embutidas.

  • Definindo o local de origem como um local externo e tendo permissões READ FILES no local externo por meio do Catálogo do Unity.
  • Usando uma credencial de armazenamento nomeada com permissões READ FILES que fornecem autorização para leitura de um local por meio do Catálogo do Unity.

  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. Confira a visão geral de locais externos para obter mais detalhes.

  Observação

  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 aceitas são:

  • AZURE_SAS_TOKEN para o ADLS e o Armazenamento de Blobs do Azure
  • AWS_ACCESS_KEY, AWS_SECRET_KEY e AWS_SESSION_TOKEN para AWS S3

  As opções de criptografia aceitas são:

  • TYPE = 'AWS_SSE_C' e MASTER_KEY para 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 que você use 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. Uma opção entre CSV, JSON, AVRO, ORC, PARQUET, TEXT e BINARYFILE.

• VALIDATE

  Aplica-se a: SQL do Databricks Databricks Runtime 10.4 LTS e versões posteriores

  Os dados que serão 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 desenvolvido.
  • Se todas as restrições de nulidade e verificação são atendidas.

  O padrão é validar todos os dados que devem ser carregados. Você pode fornecer um número de linhas a serem validadas com a palavra-chave ROWS, como VALIDATE 15 ROWS. A instrução COPY INTO retorna uma versão prévia dos dados de 50 linhas ou menos quando um número menor que 50 é usado com a palavra-chave ROWS).

• FILES

  Uma lista de nomes de arquivos a serem carregados, com um limite de 1.000 arquivos. Não pode ser especificado com PATTERN.

• PATTERN

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

  Padrão	Descrição
  ?	Corresponde a qualquer caractere único
  *	Corresponde a zero ou mais caracteres
  [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 do intervalo {a}. Observe que o caractere ^ deve ocorrer imediatamente à direita do colchete de abertura.
  {ab,cd}	Corresponde a uma cadeia de caracteres do conjunto de cadeias de caracteres {ab, cd}.
  {ab,c{de, fh}}	Corresponde a uma cadeia de caracteres do conjunto de cadeias de caracteres {ab, cde, cfh}.

• FORMAT_OPTIONS

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

• COPY_OPTIONS

  Opções para controlar a operação do comando COPY INTO.

  • force: booliano, padrão false. Se definido como true, a idempotência será desativada, e os arquivos serão carregados mesmo que já tenham sido anteriormente carregados.
  • mergeSchema: booliano, padrão false. Se definido como true, o esquema pode ser desenvolvido de acordo com os dados de entrada.

Invocar COPY INTO simultaneamente

COPY INTO dá suporte a invocações simultâneas na mesma tabela. Desde que COPY INTO seja invocado simultaneamente em conjuntos distintos de arquivos de entrada, cada invocação deverá eventualmente ser bem-sucedida, caso contrário, você obterá um conflito de transação. COPY INTO não deve ser invocado 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 ingerido pelo subdiretório. Ao ingerir diretórios com um número muito grande de arquivos, o Databricks recomenda usar o Carregador Automático quando possível.

Acessar metadados de arquivo

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

Opções de formato

• Opções genéricas
• Opções JSON
• Opções CSV
• Opções XML
• Opções PARQUET
• Opções AVRO
• Opções BINARYFILE
• Opções TEXT
• Opções ORC

Opções genéricas

As opções a seguir se aplicam a todos os formatos de arquivo.

JSON opções

CSV opções

XML opções

PARQUET opções

AVRO opções

BINARYFILE opções

Os arquivos binários não têm nenhuma opção de configuração adicional.

TEXT opções

ORC opções

Artigos relacionados

• Credenciais
• EXCLUIR
• INSERT
• FUNDIR
• PARTITION
• consulta
• UPDATE
• Comece a usar COPY INTO para carregar dados