Criar e trabalhar com volumes

Este artigo apresenta volumes, que são objetos Unity Catalog que permitem a governança sobre dataset não tabulares. Também descreve como criar, gerenciar e trabalhar com volumes.

Para obter detalhes sobre o upload e o gerenciamento de arquivos em volumes, consulte upload files to a Unity Catalog volume e File management operações for Unity Catalog volumes.

Observação

Ao trabalhar com volumes, o senhor deve usar um SQL warehouse ou um cluster que execute o Databricks Runtime 13.3 LTS ou superior, a menos que esteja usando as UIs do Databricks, como o Catalog Explorer.

O que são volumes Unity Catalog ?

Volumes são objetos do Unity Catalog que representam um volume lógico de armazenamento em um local de armazenamento de objetos na nuvem. Os volumes oferecem recursos para acessar, armazenar, controlar e organizar arquivos. Enquanto as tabelas fornecem governança sobre o conjunto de dados tabulares, os volumes adicionam governança sobre o conjunto de dados não tabulares. O senhor pode usar volumes para armazenar e acessar arquivos em qualquer formato, inclusive dados estruturados, semiestruturados e não estruturados.

Importante

Você não pode usar volumes como local para tabelas. Os volumes destinam-se apenas ao acesso a dados baseado em caminho. Use tabelas para armazenar dados tabulares com o Unity Catalog.

O que é um volume de gerenciamento?

Um volume gerenciado é um volume de armazenamento governado pelo Unity Catalog criado dentro do local de armazenamento default do esquema que o contém. gerenciar volumes permite a criação de armazenamento controlado para trabalhar com arquivos sem a sobrecarga de locais externos e credenciais de armazenamento. Você não precisa especificar um local ao criar um volume gerenciado, e todo acesso a arquivos para dados em volumes gerenciados é através de caminhos gerenciados pelo Unity Catalog. Consulte Qual caminho é usado para acessar arquivos em um volume?.

Quando você exclui um volume de gerenciamento, os arquivos armazenados nesse volume também são excluídos do seu clouds tenant dentro de 30 dias.

O que é um volume externo?

Um volume externo é um volume de armazenamento regido pelo Unity Catalog registrado em um diretório em um local externo usando credenciais de armazenamento regido pelo Unity Catalog. Os volumes externos permitem que você adicione a governança de dados Unity Catalog aos diretórios de armazenamento de objetos cloud existentes. Alguns casos de uso para volumes externos incluem o seguinte:

Adicionando governança a arquivos de dados sem migração.
Governar arquivos produzidos por outros sistemas que devem ser ingeridos ou acessados pelo Databricks.
Governar dados produzidos por Databricks que devem ser acessados diretamente do armazenamento de objetos clouds por outros sistemas.

Os volumes externos devem ser diretórios dentro de locais externos governados pelas credenciais de armazenamento do Unity Catalog. O Unity Catalog não gerencia o ciclo de vida ou disposição dos arquivos em volumes externos. Quando você elimina um volume externo, o Unity Catalog não exclui os dados subjacentes.

Observação

Quando o senhor define um volume, o acesso do URI de nuvens aos dados no caminho do volume é regido pelas permissões do volume.

Qual caminho é usado para acessar arquivos em um volume?

O caminho para acessar volumes é o mesmo, quer você use Apache Spark, SQL, Python ou outras linguagens e bibliotecas. Isso difere dos padrões de acesso herdados para arquivos no armazenamento de objetos vinculados a um workspace do Databricks.

O caminho para acessar arquivos em volumes utiliza o seguinte formato:

/Volumes/<catalog>/<schema>/<volume>/<path>/<file-name>

O Databricks também oferece suporte a um esquema dbfs:/ opcional ao trabalhar com Apache Spark, portanto, o seguinte caminho também funciona:

dbfs:/Volumes/<catalog>/<schema>/<volume>/<path>/<file-name>

A sequência /<catalog>/<schema>/<volume> no caminho corresponde aos três nomes de objetos Unity Catalog associados ao arquivo. Esses elementos de caminho são somente leitura e não podem ser gravados diretamente pelos usuários, o que significa que não é possível criar ou excluir esses diretórios usando operações do sistema de arquivos. Eles são gerenciados automaticamente e mantidos em sincronia com as entidades UC correspondentes.

Observação

Você também pode acessar dados em volumes externos usando URIs de armazenamento em nuvem.

Quais são os privilégios para volumes?

Os volumes usam o mesmo modelo básico de privilégios das tabelas, mas enquanto os privilégios para tabelas se concentram na concessão de acesso para consultar e manipular linhas em uma tabela, os privilégios para volumes se concentram no trabalho com arquivos. Como tal, os volumes introduzem os seguintes privilégios:

Consulte privilégios e objetos protegidos do Unity Catalog.

Quem pode gerenciar privilégios de volume?

Você deve ter privilégios de proprietário em um volume para gerenciar privilégios de volume ou descartar volumes. Cada objeto no Unity Catalog só pode ter um principal atribuído como proprietário e, embora a propriedade não seja transmitida em cascata (ou seja, o proprietário de um catálogo não se torna automaticamente o proprietário de todos os objetos nesse catálogo), os privilégios associados à propriedade se aplicam para todos os objetos contidos em um objeto.

Isso significa que para volumes do Unity Catalog, os seguintes principais podem gerenciar privilégios de volume:

O proprietário do catálogo pai.
O proprietário do esquema pai.
O proprietário do volume.

Embora cada objeto só possa ter um único proprietário, a Databricks recomenda atribuir a propriedade da maioria dos objetos a um grupo em vez de a um utilizador individual. A propriedade inicial de qualquer objeto é atribuída ao usuário que cria esse objeto. Consulte gerenciamento da propriedade de objetos do Catálogo do Unity.

Crie um volume de gerenciamento

Você deve ter as seguintes permissões para criar um volume de gerenciamento:

Recursos	Permissões necessárias
Esquema	`USE SCHEMA`, `CREATE VOLUME`
Catálogo	`USE CATALOG`

Para criar um volume de gerenciamento, utilize a seguinte sintaxe:

CREATE VOLUME <catalog>.<schema>.<volume-name>;

Para criar um volume de gerenciamento no Catalog Explorer:

No seu workspace do Databricks, clique em Catálogo.
Pesquise ou procure o esquema ao qual deseja adicionar o volume e selecione-o.
Clique no botão Criar volume . (Você deve ter privilégios suficientes.)
Insira um nome para o volume.
Forneça um comentário (opcional).
Clique em Criar.

Crie um volume externo

Você deve ter as seguintes permissões para criar um volume externo:

Recursos	Permissões necessárias
Localização externa	`CREATE EXTERNAL VOLUME`
Esquema	`USE SCHEMA`, `CREATE VOLUME`
Catálogo	`USE CATALOG`

Para criar um volume externo, especifique um caminho dentro de um local externo usando a seguinte sintaxe:

CREATE EXTERNAL VOLUME <catalog>.<schema>.<external-volume-name>
LOCATION 'gcs://<external-location-bucket-path>/<directory>';

Para criar um volume externo no Catalog Explorer:

No seu workspace do Databricks, clique em Catálogo.
Pesquise ou procure o esquema ao qual deseja adicionar o volume e selecione-o.
Clique no botão Criar volume . (Você deve ter privilégios suficientes.)
Insira um nome para o volume.
Escolha um local externo para criar o volume.
Edite o caminho para refletir o subdiretório onde você deseja criar o volume.
Forneça um comentário (opcional).
Clique em Criar.

Abaixe um volume

Somente usuários com privilégios de proprietário podem descartar um volume. Consulte Quem pode gerenciar privilégios de volume?.

Use a seguinte sintaxe para eliminar um volume:

DROP VOLUME IF EXISTS <volume-name>;

Quando você elimina um volume de gerenciamento, o Databricks exclui os dados subjacentes em 30 dias. Ao descartar um volume externo, você remove o volume do Unity Catalog , mas os dados subjacentes permanecem inalterados no local externo.

Ler arquivos em um volume

Você deve ter as seguintes permissões para view o conteúdo de um volume ou acessar arquivos armazenados em volumes:

Recursos	Permissões necessárias
Volume	`READ`
Esquema	`USE SCHEMA`
Catálogo	`USE CATALOG`

Você interage com o conteúdo dos volumes usando caminhos. Consulte Qual caminho é usado para acessar arquivos em um volume?.

Criar, excluir e executar outras operações de gerenciamento de arquivos em um volume

Você deve ter as seguintes permissões para executar operações de gerenciamento de arquivos em arquivos armazenados em volumes:

Recursos	Permissões necessárias
Volume	`READ`, `WRITE`
Esquema	`USE SCHEMA`
Catálogo	`USE CATALOG`

Você pode executar operações de gerenciamento de arquivos em volumes com as seguintes ferramentas:

O Catalog Explorer fornece muitas opções de UI para tarefas de gerenciamento de arquivos. Consulte O que é o Catalog Explorer?.
Databricks russas fs comando. Veja Sistema de arquivos russos (dbutils.fs).
O comando mágico %fs fornece a mesma funcionalidade que dbutils.fs.
upload de arquivos para a UI do volume. Consulte Fazer upload de arquivos para um volume do Unity Catalog.
Comando de código aberto como os.listdir().
Alguns comandos bash são suportados. %sh cp é suportado, mas %sh mv não.

Para obter detalhes completos sobre a interação programática com arquivos em volumes, consulte Trabalhar com arquivos em volumes do Unity Catalog.

Exemplo Notebook: Criar e trabalhar com volumes

O Notebook a seguir demonstra a sintaxe SQL básica para criar e interagir com volumes do Unity Catalog.

Tutorial: Notebookde volumes do Catálogo Unity

Abra o bloco de anotações em outra guia

Caminhos reservados para volumes

Volumes apresenta os seguintes caminhos reservados usados para acessar volumes:

dbfs:/Volumes
/Volumes

Observação

Os caminhos também são reservados para possíveis erros de digitação para esses caminhos das APIs Apache Spark e dbutils, incluindo /volumes, /Volume, /volume, sejam ou não precedidos por dbfs:/. O caminho /dbfs/Volumes também está reservado, mas não pode ser utilizado para acessar volumes.

Os volumes são compatíveis apenas com o Databricks Runtime 13.3 LTS e acima. Em Databricks Runtime 12.2 LTS e abaixo, as operações contra caminhos /Volumes podem ser bem-sucedidas, mas podem gravar dados em discos de armazenamento efêmeros anexados a compute clusters em vez de persistir os dados em volumes Unity Catalog, conforme esperado.

Importante

Se você tiver dados pré-existentes armazenados em um caminho reservado na DBFS root, poderá registrar um tíquete de suporte para obter acesso temporário a esses dados e movê-los para outro local.

Limitações

Você deve usar compute habilitada para o Unity Catalog para interagir com os volumes do Unity Catalog. Os volumes não suportam todas as cargas de trabalho.

Observação

Os volumes não suportam o comando dbutils.fs distribuído ao executor.

Aplicam-se as seguintes limitações:

No Databricks Runtime 14.3 LTS e acima:

Em clusters de usuários únicos, não é possível acessar volumes de threads e subprocessos no Scala.

No Databricks Runtime 14.2 e abaixo:

Na compute configurada com modo de acesso compartilhado, não é possível usar UDFs para acessar volumes.
- Tanto Python quanto Scala têm acesso ao FUSE pelo driver, mas não pelo executor.
- O código Scala que executa operações de E/S pode ser executado no driver, mas não no executor.
Na compute configurada com modo de acesso de usuário único, não há suporte para FUSE no Scala, código Scala IO acessando caminhos de volume de uso de dados ou Scala UDFs. UDFs Python são suportados no modo de acesso de usuário único.

Em todas as versões compatíveis do Databricks Runtime:

Os UDFs do Unity Catalog não suportam o acesso a caminhos de arquivos de volume.
O senhor não pode acessar volumes de RDDs.
O senhor não pode usar o spark-submit com JARs armazenados em um volume.
O senhor não pode definir dependências para outras bibliotecas acessadas por meio de caminhos de volume dentro de um arquivo Wheel ou JAR.
O senhor não pode listar objetos do Unity Catalog usando os padrões /Volumes/<catalog-name> ou /Volumes/<catalog-name>/<schema-name>. O senhor deve usar um caminho totalmente qualificado que inclua um nome de volume.
O endpoint DBFS para a API REST não suporta caminhos de volumes.
Os volumes são excluídos dos resultados da pesquisa global no workspace do Databricks.
Não é possível especificar volumes como destino para clusters logs entrega .
%sh mv não é compatível com a movimentação de arquivos entre volumes. Use dbutils.fs.mv ou %sh cp .

Você não pode criar um sistema de arquivos Hadoop personalizado com volumes, o que significa que o seguinte não é suportado:

import org.apache.hadoop.fs.Path
val path =  new Path("dbfs:/Volumes/main/default/test-volume/file.txt")
val fs = path.getFileSystem(sc.hadoopConfiguration)
fs.listStatus(path)