Carregar dados usando COPY INTO com volumes do Catálogo do Unity ou locais externos

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

As etapas neste artigo pressupõem que o administrador configurou um volume do Catálogo do 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 uma entidade de serviço, confira Carregar dados usando COPY INTO com uma entidade de serviço ou Tutorial: COPY INTO com o Spark SQL. Se o administrador lhe deu credenciais temporárias (um token SAS de Blob), siga as etapas em Carregar dados usando COPY INTO com credenciais temporárias em vez disso.

O Databricks recomenda usar volumes para acessar arquivos no armazenamento em nuvem como parte do processo de ingestão usando COPY INTO. Para mais informações sobre as recomendações para o uso de volumes e locais externos, confira as melhores práticas do Catálogo Unity.

Antes de começar

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

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

• O caminho para os seus dados de origem na forma de uma URL de armazenamento de objetos na nuvem ou de um caminho de volume.

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

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

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

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

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

Carregar dados de um volume

Para carregar dados de um volume do Catálogo do Unity, você deve ter o privilégio READ VOLUME. Os privilégios de volume se aplicam 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 de esquema dbfs: também tem suporte com caminhos de volume (por exemplo, dbfs:/Volumes/...), mas Databricks recomenda usar o formato de caminho /Volumes/ mostrado acima.

Carregar dados usando um local externo

O exemplo a seguir carrega dados do ADLS em uma tabela usando locais externos do Catálogo do Unity 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 local externo

Os privilégios de localização externos se aplicam 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 nesse local externo não concedem 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

Você pode direcionar uma tabela do Catálogo do Unity usando um namespace de três níveis (<catalog_name>.<schema_name>.<table_name>). Use os comandos USE CATALOG <catalog_name> e USE SCHEMA <schema_name> para definir o catálogo e o esquema padrão para sua consulta ou notebook atual.

O exemplo a seguir carrega dados de um volume em uma tabela usando o namespace 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;

Você também pode definir o catálogo e o esquema padrão primeiro:

USE CATALOG quickstart_catalog;
USE SCHEMA quickstart_schema;

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