Carregue os dados através de volumes do Catálogo Unity ou de locais externos usando COPY INTO

Este artigo descreve como usar o comando COPY INTO para carregar dados de um contêiner do Azure Data Lake Storage (ADLS) em sua conta do Azure em uma tabela no Databricks SQL.

As etapas neste artigo pressupõem que seu administrador configurou um volume do Catálogo Unity ou um local externo para que você possa acessar seus arquivos de origem no ADLS. Se o administrador configurou um recurso de computação para usar um principal de serviço, consulte Carregar dados usando COPY INTO com um principal de serviço ou Tutorial: COPY INTO com Spark SQL como alternativa. Se o administrador lhe tiver fornecido credenciais temporárias (um token SAS de Blob), siga os passos indicados em Carregar dados utilizando COPY INTO com credenciais temporárias em vez disso.

O Databricks recomenda o uso de volumes para acessar arquivos no armazenamento em nuvem como parte do processo de ingestão usando COPY INTO. Para obter mais informações sobre recomendações para o uso de volumes e locais externos, consulte práticas recomendadas do Unity Catalog.

Antes de começar

Antes de usar COPY INTO para carregar dados de um volume do Catálogo Unity ou de um caminho de armazenamento de objetos na nuvem definido como um local externo do Catálogo Unity, você deve ter o seguinte:

• READ VOLUME privilégio num volume ou READ FILES privilégio num local externo. Para obter mais informações sobre como criar volumes, consulte O que são volumes do Catálogo Unity?. Para obter mais informações sobre como criar locais externos, consulte Visão geral de locais externos.

• O caminho para os dados de origem sob a forma de um URL de armazenamento de objetos em nuvem ou um caminho de volume.

  Exemplo de URL de armazenamento de objetos na nuvem: abfss://container@storageAccount.dfs.core.windows.net/raw-data/json.

  Exemplo de caminho do volume: /Volumes/quickstart_catalog/quickstart_schema/quickstart_volume/raw_data/json.

• O privilégio de USE SCHEMA no esquema que contém a tabela de destino.

• O privilégio associado ao USE CATALOG no catálogo pai.

Para mais informações sobre privilégios do Catálogo Unity, consulte a referência de privilégios do Catálogo Unity.

Carregar dados de um volume

Para carregar dados de um volume do Catálogo Unity, você deve ter o privilégio READ VOLUME. Os privilégios de volume aplicam-se a todos os diretórios aninhados no volume especificado.

Por exemplo, se você tiver acesso a um volume com o caminho /Volumes/quickstart_catalog/quickstart_schema/quickstart_volume/, os seguintes comandos serão válidos:

COPY INTO landing_table
FROM '/Volumes/quickstart_catalog/quickstart_schema/quickstart_volume/raw_data'
FILEFORMAT = PARQUET;

COPY INTO json_table
FROM '/Volumes/quickstart_catalog/quickstart_schema/quickstart_volume/raw_data/json'
FILEFORMAT = JSON;

O prefixo dbfs: scheme também é suportado com caminhos de volume (por exemplo, dbfs:/Volumes/...), mas o Databricks recomenda utilizar o formato de caminho /Volumes/ apresentado anteriormente.

Carregar dados usando um local externo

O exemplo seguinte carrega dados do ADLS para uma tabela usando localizações externas do Unity Catalog para fornecer acesso aos dados de origem.

COPY INTO my_json_data
FROM 'abfss://container@storageAccount.dfs.core.windows.net/jsonData'
FILEFORMAT = JSON;

Herança de privilégios de localização externa

Os privilégios de local externo aplicam-se a todos os diretórios aninhados no local especificado.

Por exemplo, se você tiver acesso a um local externo definido com a URL abfss://container@storageAccount.dfs.core.windows.net/raw-data, os seguintes comandos serão válidos:

COPY INTO landing_table
FROM 'abfss://container@storageAccount.dfs.core.windows.net/raw-data'
FILEFORMAT = PARQUET;

COPY INTO json_table
FROM 'abfss://container@storageAccount.dfs.core.windows.net/raw-data/json'
FILEFORMAT = JSON;

As permissões neste local externo não concedem quaisquer privilégios em diretórios acima ou paralelos ao local especificado. Por exemplo, nenhum dos seguintes comandos é válido:

COPY INTO parent_table
FROM 'abfss://container@storageAccount.dfs.core.windows.net'
FILEFORMAT = PARQUET;

COPY INTO sibling_table
FROM 'abfss://container@storageAccount.dfs.core.windows.net/json-data'
FILEFORMAT = JSON;

Namespace de três níveis para tabelas de destino

Pode direcionar uma tabela do Unity Catalog usando um namespace de três níveis (<catalog_name>.<schema_name>.<table_name>). Usa os USE CATALOG <catalog_name> comandos e USE SCHEMA <schema_name> para definir o catálogo e o esquema padrão para a tua consulta ou caderno atual.

O exemplo seguinte carrega dados de um volume para uma tabela usando o espaço de nomes de três níveis:

COPY INTO quickstart_catalog.quickstart_schema.landing_table
FROM '/Volumes/quickstart_catalog/quickstart_schema/quickstart_volume/raw_data'
FILEFORMAT = PARQUET;

Também pode definir primeiro o catálogo e o esquema padrão:

USE CATALOG quickstart_catalog;
USE SCHEMA quickstart_schema;

COPY INTO landing_table
FROM '/Volumes/quickstart_catalog/quickstart_schema/quickstart_volume/raw_data'
FILEFORMAT = PARQUET;