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

Artigo
11/07/2024

Saiba como usar o COPY INTO para ingerir dados em tabelas externas ou gerenciadas pelo Catálogo do Unity de qualquer origem e formato de arquivo compatíveis com COPY INTO. O Catálogo do Unity adiciona novas opções para configurar o acesso seguro a dados brutos. Você pode usar volumes do Catálogo do Unity ou locais externos para acessar dados no armazenamento de objetos de nuvem.

O Databricks recomenda usar 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 usar volumes e locais externos, confira Práticas recomendadas do Catálogo do Unity.

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

As etapas neste artigo pressupõem que seu administrador configurou um volume ou local externo do Catálogo do Unity para que você possa acessar seus arquivos de origem no ADLS Gen2. 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.

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 na nuvem definido como um local externo do Catálogo do Unity, você precisará 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 a criação de locais externos, veja Criar um local externo para conectar o armazenamento em nuvem ao Azure Databricks.
O caminho para os dados de origem na forma de uma URL de armazenamento de objetos de nuvem ou 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 USE CATALOG do privilégio no catálogo pai.

Para obter mais informações sobre os privilégios do Catálogo do Unity, confira Privilégios e objetos protegíveis 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;

Opcionalmente, você também pode usar um caminho de volume com o esquema dbfs. Por exemplo, os seguintes comandos também são válidos:

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

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

Carregar dados usando um local externo

O exemplo a seguir carrega dados do ADLS Gen2 em uma tabela usando locais externos do Catálogo do Unity para fornecer acesso ao código-fonte.

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

Herança de privilégio do 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 's3://landing-bucket'
FILEFORMAT = PARQUET;

COPY INTO sibling_table
FROM 's3://landing-bucket/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 identificador de três camadas (<catalog_name>.<database_name>.<table_name>). Você pode usar os comandos USE CATALOG <catalog_name> e USE <database_name> para definir o catálogo e o banco de dados padrão para sua consulta ou notebook atual.

Compartilhar via