Criar tabelas no Catálogo do Unity

  • Artigo

Este artigo apresenta o conceito de tabelas gerenciadas e externas e descreve como criar tabelas no Catálogo do Unity.

Observação

Ao criar uma tabela, lembre-se de referenciar um catálogo que é regido pelo Catálogo do Unity ou definir o catálogo padrão para um catálogo que é regido pelo Catálogo do Unity. Confira Gerenciar o catálogo padrão.

O catálogo hive_metastore aparece no Catalog Explorer, mas não é considerado controlado pelo Catálogo do Unity. Ele é gerenciado pelo metastore do Hive do workspace do Azure Databricks. Todos os outros catálogos listados são regidos pelo Catálogo do Unity.

Você pode usar a interface de atualização de tabela do Catálogo do Unity para atualizar tabelas existentes registradas no metastore do Hive para o Catálogo do Unity. Confira Atualizar tabelas e exibições no Catálogo do Unity.

Tabelas gerenciadas

As tabelas gerenciadas são a maneira padrão de criar tabelas no Catálogo do Unity. O Catálogo do Unity gerencia o ciclo de vida e o layout de arquivo dessas tabelas. Você não deve usar ferramentas fora do Azure Databricks para manipular arquivos diretamente nessas tabelas.

As tabelas gerenciadas são armazenadas no armazenamento gerenciado, no nível de metastore, catálogo ou esquema, dependendo de como o esquema e o catálogo são configurados. Consulte Especificar um local de armazenamento gerenciado no catálogo do Unity.

As tabelas gerenciadas sempre usam o formato de tabela Delta.

Quando uma tabela gerenciada é removida, os dados subjacentes dela são excluídos do seu locatário de nuvem dentro de 30 dias.

Tabelas externas

Tabelas externas são tabelas cujos dados são armazenados fora do local de armazenamento gerenciado especificado para o metastore, catálogo ou esquema. Use tabelas externas somente quando precisar de acesso direto aos dados fora de clusters do Azure Databricks ou de SQL warehouses do Databricks.

Quando você executa DROP TABLE em uma tabela externa, o Catálogo do Unity não exclui os dados subjacentes. Para remover uma tabela, você deve ser seu proprietário. Você pode gerenciar privilégios em tabelas externas e usá-los em consultas da mesma maneira que as tabelas gerenciadas. Para criar uma tabela externa no SQL, especifique um caminho LOCATION na instrução CREATE TABLE. As tabelas externas podem usar os seguintes formatos de arquivos:

  • DELTA
  • CSV
  • JSON
  • AVRO
  • PARQUET
  • ORC
  • TEXT

Para gerenciar o acesso ao armazenamento em nuvem subjacente para uma tabela externa, você precisa configurar as credenciais de armazenamento e locais externos.

Para saber mais, confira Criar uma tabela externa.

Requisitos

Você deve ter o privilégio CREATE TABLE no esquema no qual deseja criar a tabela, bem como o privilégio USE SCHEMA no esquema e o privilégio USE CATALOG no catálogo pai.

Para obter requisitos adicionais para criar uma tabela externa, consulte Criar uma tabela externa.

Criar uma tabela gerenciada

Para criar uma tabela gerenciada, execute o comando SQL comando a seguir. Você também pode usar o notebook de exemplo para criar uma tabela. Os itens entre colchetes são opcionais. Substitua os valores de espaço reservado:

  • <catalog-name>: o nome do catálogo que conterá a tabela..

    Esse não pode ser o catálogo hive_metastore criado automaticamente para o metastore do Hive associado ao workspace do Azure Databricks. Você poderá remover o nome do catálogo se estiver criando a tabela no catálogo padrão do workspace.

  • <schema-name>: o nome do esquema que conterá a tabela..

  • <table-name>: O nome do catálogo.

  • <column-specification>: o nome e o tipo de dados para cada coluna.

SQL

CREATE TABLE <catalog-name>.<schema-name>.<table-name>
(
  <column-specification>
);

Python

spark.sql("CREATE TABLE <catalog-name>.<schema-name>.<table-name> "
  "("
  "  <column-specification>"
  ")")

R

library(SparkR)

sql(paste("CREATE TABLE <catalog-name>.<schema-name>.<table-name> ",
  "(",
  "  <column-specification>",
  ")",
  sep = ""))

Scala

spark.sql("CREATE TABLE <catalog-name>.<schema-name>.<table-name> " +
  "(" +
  "  <column-specification>" +
  ")")

Você também pode criar uma tabela gerenciada usando o provedor do Databricks Terraform e databricks_table. Você pode recuperar uma lista de nomes completos da tabela usando databricks_tables.

Por exemplo, para criar a tabela main.default.department e inserir cinco linhas nele:

SQL

CREATE TABLE main.default.department
(
  deptcode  INT,
  deptname  STRING,
  location  STRING
);

INSERT INTO main.default.department VALUES
  (10, 'FINANCE', 'EDINBURGH'),
  (20, 'SOFTWARE', 'PADDINGTON'),
  (30, 'SALES', 'MAIDSTONE'),
  (40, 'MARKETING', 'DARLINGTON'),
  (50, 'ADMIN', 'BIRMINGHAM');

Python

spark.sql("CREATE TABLE main.default.department "
  "("
  "  deptcode  INT,"
  "  deptname  STRING,"
  "  location  STRING"
  ")"
  "INSERT INTO main.default.department VALUES "
  "  (10, 'FINANCE', 'EDINBURGH'),"
  "  (20, 'SOFTWARE', 'PADDINGTON'),"
  "  (30, 'SALES', 'MAIDSTONE'),"
  "  (40, 'MARKETING', 'DARLINGTON'),"
  "  (50, 'ADMIN', 'BIRMINGHAM')")

R

library(SparkR)

sql(paste("CREATE TABLE main.default.department ",
  "(",
  "  deptcode  INT,",
  "  deptname  STRING,",
  "  location  STRING",
  ")",
  "INSERT INTO main.default.department VALUES ",
  "  (10, 'FINANCE', 'EDINBURGH'),",
  "  (20, 'SOFTWARE', 'PADDINGTON'),",
  "  (30, 'SALES', 'MAIDSTONE'),",
  "  (40, 'MARKETING', 'DARLINGTON'),",
  "  (50, 'ADMIN', 'BIRMINGHAM')",
  sep = ""))

Scala

spark.sql("CREATE TABLE main.default.department " +
  "(" +
  "  deptcode  INT," +
  "  deptname  STRING," +
  "  location  STRING" +
  ")" +
  "INSERT INTO main.default.department VALUES " +
  "  (10, 'FINANCE', 'EDINBURGH')," +
  "  (20, 'SOFTWARE', 'PADDINGTON')," +
  "  (30, 'SALES', 'MAIDSTONE')," +
  "  (40, 'MARKETING', 'DARLINGTON')," +
  "  (50, 'ADMIN', 'BIRMINGHAM')")

Notebook de exemplo: criar tabelas gerenciadas

Você pode usar os notebooks de exemplo a seguir para criar um catálogo, um esquema e uma tabela e gerenciar permissões neles.

Criar e gerenciar uma tabela no Unity Catalog usando o notebook Python

Obter notebook

Criar e gerenciar uma tabela no Unity Catalog usando o notebook SQL

Obter notebook

Remover uma tabela gerenciada

Você deve ser o proprietário da tabela para remover uma tabela. Para remover uma tabela gerenciada, execute o seguinte comando SQL:

DROP TABLE IF EXISTS catalog_name.schema_name.table_name;

Quando uma tabela gerenciada é removida, os dados subjacentes dela são excluídos do seu locatário de nuvem dentro de 30 dias.

Criar uma tabela externa

Os dados em uma tabela externa são armazenados em um caminho em seu locatário de nuvem. Para trabalhar com tabelas externas, o Catálogo do Unity apresenta dois objetos para acessar e trabalhar com o armazenamento em nuvem externo:

  • Uma credencial de armazenamento contém um método de autenticação para acessar um local de armazenamento em nuvem. A credencial de armazenamento não contém um mapeamento para o caminho ao qual ela concede acesso. Credenciais de armazenamento são controladas por acesso para determinar quais usuários podem usá-las.
  • Um local externo mapeia uma credencial de armazenamento com um caminho de armazenamento em nuvem ao qual ela concede acesso. O local externo concede acesso somente a esse caminho de armazenamento em nuvem e ao respectivo conteúdo. Locais externos são controlados por acesso para determinar quais usuários podem usá-los. Um local externo é usado automaticamente quando o comando SQL contém uma cláusula LOCATION.

Requisitos

Para criar uma tabela externa, você deve ter:

  • O privilégio CREATE EXTERNAL TABLE em um local externo, que concede acesso ao LOCATION pela tabela externa.
  • A permissão USE SCHEMA no esquema pai da tabela.
  • A permissão USE CATALOG no catálogo pai da tabela.
  • A permissão CREATE TABLE no esquema pai da tabela.

Os locais externos e as credenciais de armazenamento são armazenados no nível do metastore, em vez de em um catálogo. Para criar uma credencial de armazenamento, você deve ser um administrador de conta ou ter o privilégio CREATE STORAGE CREDENTIAL. Para criar um local externo, você deve ser o administrador do metastore ou ter o privilégio CREATE EXTERNAL LOCATION. Confira Conectar-se ao armazenamento de objetos de nuvem usando o Catálogo do Unity.

Criar uma tabela

Use um dos exemplos de comando a seguir em um notebook ou no editor de consultas SQL para criar uma tabela externa.

Você também pode usar um notebook de exemplo para criar a credencial de armazenamento, o local externo e a tabela externa e também gerenciar permissões para eles.

Nos seguintes exemplos, substitua os valores de espaço reservado:

  • <catalog>: O nome do catálogo que conterá a tabela.

    Esse não pode ser o catálogo hive_metastore criado automaticamente para o metastore do Hive associado ao workspace do Azure Databricks. Você poderá remover o nome do catálogo se estiver criando a tabela no catálogo padrão do workspace.

  • <schema>: O nome do esquema que conterá a tabela.

  • <table-name>: O nome do catálogo.

  • <column-specification>: o nome e o tipo de dados para cada coluna.

  • <bucket-path>: o caminho para o bucket de armazenamento em nuvem onde a tabela será criada.

  • <table-directory>: Um diretório em que a tabela será criada. Use um diretório exclusivo para cada tabela.

Importante

Depois que uma tabela é criada em um caminho, os usuários não podem mais acessar diretamente os arquivos nesse caminho do Azure Databricks, mesmo que tenham concedido privilégios em um local externo ou uma credencial de armazenamento para fazer isso. Isso é para garantir que os usuários não possam burlar os controles de acesso aplicados às tabelas lendo os arquivos do seu locatário de nuvem diretamente.

SQL

CREATE TABLE <catalog>.<schema>.<table-name>
(
  <column-specification>
)
LOCATION 'abfss://<bucket-path>/<table-directory>';

Python

spark.sql("CREATE TABLE <catalog>.<schema>.<table-name> "
  "("
  "  <column-specification>"
  ") "
  "LOCATION 'abfss://<bucket-path>/<table-directory>'")

R

library(SparkR)

sql(paste("CREATE TABLE <catalog>.<schema>.<table-name> ",
  "(",
  "  <column-specification>",
  ") ",
  "LOCATION 'abfss://<bucket-path>/<table-directory>'",
  sep = ""))

Scala

spark.sql("CREATE TABLE <catalog>.<schema>.<table-name> " +
  "(" +
  "  <column-specification>" +
  ") " +
  "LOCATION 'abfss://<bucket-path>/<table-directory>'")

O catálogo do Unity verifica se você tem as seguintes permissões:

  • CREATE EXTERNAL TABLE no local externo que faz referência ao caminho de armazenamento em nuvem que você especificar.
  • CREATE TABLE no esquema pai.
  • USE SCHEMA no esquema pai.
  • USE CATALOG no catálogo pai.

Se você fizer isso, a tabela externa é criada. Caso contrário, ocorrerá um erro, e a tabela externa não será criada.

Observação

Em vez disso, você pode migrar uma tabela externa existente no metastore do Hive para o Catálogo do Unity, sem duplicar os dados. Confira Atualizar uma única tabela externa no Catálogo do Unity.

Você também pode criar uma tabela externa usando o provedor Databricks Terraform e databricks_table. Você pode recuperar uma lista de nomes completos da tabela usando databricks_tables.

Notebook de exemplo: criar tabelas externas

Você pode usar o notebook de exemplo a seguir para criar um catálogo, um esquema e uma tabela externa e gerenciar permissões neles.

Criar e gerenciar uma tabela externa no notebook do Unity Catalog

Obter notebook

Criar uma tabela com base em arquivos armazenados em seu locatário de nuvem

Você pode preencher uma tabela gerenciada ou externa com registros de arquivos armazenados em seu locatário de nuvem. O Catálogo do Unity lê os arquivos nesse local e insere seu conteúdo na tabela. No Catálogo do Unity, isso é chamado de acesso baseado em caminho.

Você pode seguir os exemplos nesta seção ou usar a interface do usuário para adicionar dados.

Explorar o conteúdo dos arquivos

Para explorar os dados armazenados em um local externo antes de criar tabelas a partir desses dados, você pode utilizar o Catalog Explorer ou os seguintes comandos.

Permissões necessárias: você deve ter a permissão READ FILES no local externo associado ao caminho do armazenamento em nuvem para retornar uma lista de arquivos de dados nesse local.

Sql

  1. Listar os arquivos em um caminho de armazenamento em nuvem:

    LIST 'abfss://<path-to-files>';

  2. Consulte os dados nos arquivos em um determinado caminho:

    SELECT * FROM <format>.`abfss://<path-to-files>`;

Python

  1. Listar os arquivos em um caminho de armazenamento em nuvem:

    display(spark.sql("LIST 'abfss://<path-to-files>'"))

  2. Consulte os dados nos arquivos em um determinado caminho:

    display(spark.read.load("abfss://<path-to-files>"))

R

  1. Listar os arquivos em um caminho de armazenamento em nuvem:

    library(SparkR)

display(sql("LIST 'abfss://<path-to-files>'"))

  2. Consulte os dados nos arquivos em um determinado caminho:

    library(SparkR)

display(loadDF("abfss://<path-to-files>"))

Scala

  1. Listar os arquivos em um caminho de armazenamento em nuvem:

    display(spark.sql("LIST 'abfss://<path-to-files>'"))

  2. Consulte os dados nos arquivos em um determinado caminho:

    display(spark.read.load("abfss://<path-to-files>"))

Criar uma tabela via arquivos

Siga os exemplos nesta seção para criar uma nova tabela e preenchê-la com arquivos de dados em seu locatário de nuvem.

Observação

Em vez disso, você pode migrar uma tabela externa existente no metastore do Hive para o Catálogo do Unity, sem duplicar os dados. Confira Atualizar uma única tabela externa no Catálogo do Unity.

Importante

  • Quando você cria uma tabela usando esse método, o caminho de armazenamento é lido apenas uma vez, para evitar a duplicação de registros. Se você quiser ler novamente o conteúdo do diretório, deverá descartar e recriar a tabela. Para uma tabela existente, você pode inserir registros de um caminho de armazenamento.
  • O caminho de bucket em que você cria uma tabela também não pode ser usado para ler ou gravar arquivos de dados.
  • Somente os arquivos no diretório exato são lidos; a leitura não é recursiva.
  • As seguintes permissões são necessárias:
    • USE CATALOG no catálogo pai e USE SCHEMA no esquema.
    • CREATE TABLE no esquema pai.
    • READ FILES no local externo associado ao caminho de bucket em que os arquivos estão localizados, ou diretamente na credencial de armazenamento, se você não estiver usando um local externo.
    • Se você estiver criando uma tabela externa, precisará CREATE EXTERNAL TABLE no caminho do bucket em que a tabela será criada.

Para criar uma nova tabela gerenciada e preenchê-la com dados no armazenamento em nuvem, use os exemplos a seguir.

SQL

CREATE TABLE <catalog>.<schema>.<table-name>
(
  <column-specification>
)
SELECT * from <format>.`abfss://<path-to-files>`;

Python

spark.sql("CREATE TABLE <catalog>.<schema>.<table-name> "
  "( "
  "  <column-specification> "
  ") "
  "SELECT * from <format>.`abfss://<path-to-files>`")

R

library(SparkR)

sql(paste("CREATE TABLE <catalog>.<schema>.<table-name> ",
  "( ",
  "  <column-specification> ",
  ") ",
  "SELECT * from <format>.`abfss://<path-to-files>`",
  sep = ""))

Scala

spark.sql("CREATE TABLE <catalog>.<schema>.<table-name> " +
  "( " +
  "  <column-specification> " +
  ") " +
  "SELECT * from <format>.`abfss://<path-to-files>`")

Para criar uma tabela externa e preenchê-la com dados no armazenamento em nuvem, adicione uma cláusula LOCATION:

SQL

CREATE TABLE <catalog>.<schema>.<table-name>
(
    <column-specification>
)
USING <format>
LOCATION 'abfss://<table-location>'
SELECT * from <format>.`abfss://<path-to-files>`;

Python

spark.sql("CREATE TABLE <catalog>.<schema>.<table-name> "
  "( "
  "  <column-specification> "
  ") "
  "USING <format> "
  "LOCATION 'abfss://<table-location>' "
  "SELECT * from <format>.`abfss://<path-to-files>`")

R

library(SparkR)

sql(paste("CREATE TABLE <catalog>.<schema>.<table-name> ",
  "( ",
  "  <column-specification> ",
  ") ",
  "USING <format> ",
  "LOCATION 'abfss://<table-location>' ",
  "SELECT * from <format>.`abfss://<path-to-files>`",
  sep = ""))

Scala

spark.sql("CREATE TABLE <catalog>.<schema>.<table-name> " +
  "( " +
  "  <column-specification> " +
  ") " +
  "USING <format> " +
  "LOCATION 'abfss://<table-location>' " +
  "SELECT * from <format>.`abfss://<path-to-files>`")

Inserir registros de um caminho em uma tabela existente

Para inserir registros de um caminho de bucket em uma tabela existente, use o comando COPY INTO. Nos seguintes exemplos, substitua os valores de espaço reservado:

  • <catalog>: O nome do catálogo pai da tabela.
  • <schema>: O nome do esquema pai da tabela.
  • <path-to-files>: O caminho de bucket que contém os arquivos de dados.
  • <format>: o formato dos arquivos, por exemplo delta.
  • <table-location>: O caminho de bucket em que a tabela será criada.

Importante

  • Quando você insere registros em uma tabela usando esse método, o caminho de bucket que você fornece é somente leitura uma vez, para evitar a duplicação de registros.
  • O caminho de bucket em que você cria uma tabela também não pode ser usado para ler ou gravar arquivos de dados.
  • Somente os arquivos no diretório exato são lidos; a leitura não é recursiva.
  • As seguintes permissões são necessárias:
    • USE CATALOG no catálogo pai e USE SCHEMA no esquema.
    • MODIFY na tabela.
    • READ FILES no local externo associado ao caminho de bucket em que os arquivos estão localizados, ou diretamente na credencial de armazenamento, se você não estiver usando um local externo.
    • Para inserir registros em uma tabela externa, você precisará CREATE EXTERNAL TABLE no caminho de bucket em que a tabela está localizada.

Para inserir registros de arquivos em um caminho de bucket em uma tabela gerenciada, usando um local externo para ler do caminho de bucket:

SQL

COPY INTO <catalog>.<schema>.<table>
FROM (
  SELECT *
  FROM 'abfss://<path-to-files>'
)
FILEFORMAT = <format>;

Python

spark.sql("COPY INTO <catalog>.<schema>.<table> "
  "FROM ( "
  "  SELECT * "
  "  FROM 'abfss://<path-to-files>' "
  ") "
  "FILEFORMAT = <format>")

R

library(SparkR)

sql(paste("COPY INTO <catalog>.<schema>.<table> ",
  "FROM ( ",
  "  SELECT * ",
  "  FROM 'abfss://<path-to-files>' ",
  ") ",
  "FILEFORMAT = <format>",
  sep = ""))

Scala

spark.sql("COPY INTO <catalog>.<schema>.<table> " +
  "FROM ( " +
  "  SELECT * " +
  "  FROM 'abfss://<path-to-files>' " +
  ") " +
  "FILEFORMAT = <format>")

Para inserir em uma tabela externa, adicione uma cláusula LOCATION:

SQL

COPY INTO <catalog>.<schema>.<table>
LOCATION 'abfss://<table-location>'
FROM (
  SELECT *
  FROM 'abfss://<path-to-files>'
)
FILEFORMAT = <format>;

Python

spark.sql("COPY INTO <catalog>.<schema>.<table> "
  "LOCATION 'abfss://<table-location>' "
  "FROM ( "
  "  SELECT * "
  "  FROM 'abfss://<path-to-files>' "
  ") "
  "FILEFORMAT = <format>")

R

library(SparkR)

sql(paste("COPY INTO <catalog>.<schema>.<table> ",
  "LOCATION 'abfss://<table-location>' ",
  "FROM ( ",
  "  SELECT * ",
  "  FROM 'abfss://<path-to-files>' ",
  ") ",
  "FILEFORMAT = <format>",
  sep = ""))

Scala

spark.sql("COPY INTO <catalog>.<schema>.<table> " +
  "LOCATION 'abfss://<table-location>' " +
  "FROM ( " +
  "  SELECT * " +
  "  FROM 'abfss://<path-to-files>' " +
  ") " +
  "FILEFORMAT = <format>")

Adicionar comentários a uma tabela

Como proprietário de tabela ou usuário com o privilégio MODIFY em uma tabela, você pode adicionar comentários a uma tabela e nas suas colunas. Você pode adicionar comentários usando a seguinte funcionalidade:

  • O comando COMMENT ON. Essa opção não dá suporte a comentários de coluna.
  • A opção COMMENT quando você usa os comandos CREATE TABLE e ALTER TABLE. Essa opção dá suporte a comentários de coluna.
  • O campo de comentário “manual” no Gerenciador de Catálogos. Essa opção dá suporte a comentários de coluna. Confira Documentar dados no Gerenciador de Catálogos usando comentários de markdown.
  • Comentários gerados por IA (também conhecidos como documentação gerada por IA) no Gerenciador de Catálogos. Você pode exibir um comentário sugerido por um LLM (modelo de linguagem grande) que leva em conta os metadados da tabela, como os nomes do esquema e da coluna da tabela, e editar ou aceitar o comentário como está para adicioná-lo. Confira, Adicionar comentários gerados por IA em uma tabela.

Próximas etapas