Criar tabelas no Unity Catalog

Este artigo apresenta o conceito de gerenciar e tabelas externas no Unity Catalog e descreve como criar tabelas no Unity Catalog.

Observação

Ao criar uma tabela, certifique-se de fazer referência a um catálogo governado pelo Unity Catalog ou de definir o catálogodefault como um catálogo governado pelo Unity Catalog. Consulte gerenciamento do catálogo padrão.

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

O senhor pode usar a interface de atualização de tabela Unity Catalog para atualizar as tabelas existentes registradas no site Hive metastore para Unity Catalog. Consulte Upgrade Hive tables and view to Unity Catalog.

Tabelas gerenciadas

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

gerenciar tabelas são armazenadas em gerenciar storage, no nível metastore, catálogo ou esquema, dependendo de como o esquema e o catálogo estão configurados. Consulte Especificar um local de armazenamento de gerenciamento no Catálogo do Unity.

As tabelas gerenciadas sempre usam o formato de tabela Delta.

Quando uma tabela gerenciada é descartada, seus dados subjacentes são excluídos de seu locatário de nuvem em 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 dos clusters do Databricks ou SQL warehouses do Databricks.

Quando você executa DROP TABLE em uma tabela externa, o Unity Catalog não exclui os dados subjacentes. Para descartar uma tabela, você deve ser o proprietário. Você pode gerenciar privilégios em tabelas externas e usá-los em consultas da mesma forma que as tabelas gerenciadas. Para criar uma tabela externa com SQL, especifique um caminho LOCATION em sua instrução CREATE TABLE . Tabelas externas podem usar os seguintes formatos de arquivo:

  • DELTA

  • CSV

  • JSON

  • AVRO

  • PARQUET

  • ORC

  • TEXT

Para gerenciar o acesso ao armazenamento clouds subjacente para uma tabela externa, você deve configurar credenciais de armazenamento e locais externos.

Para saber mais, consulte 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.

Se você for criar uma tabela externa, consulte Criar uma tabela externa para requisitos adicionais.

Criar uma mesa gerenciadora

Para criar uma tabela gerencial, execute o seguinte comando SQL. 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.

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

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

  • <table-name>: Um nome para a tabela.

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

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

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

library(SparkR)

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

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

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

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

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');

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')")

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 = ""))

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 gerenciais

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

Crie e gerencie uma tabela no Unity Catalog usando Python Notebook

Abra o bloco de anotações em outra guia

Crie e gerencie uma tabela no Unity Catalog usando o SQL Notebook

Abra o bloco de anotações em outra guia

Solte uma mesa gerenciadora

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

DROP TABLE IF EXISTS catalog_name.schema_name.table_name;

Quando uma tabela gerenciada é descartada, seus dados subjacentes são excluídos de seu locatário de nuvem em 30 dias.

Criar uma tabela externa

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

  • Uma credencial de armazenamento contém um método de autenticação para acessar um local de armazenamento cloud . A credencial de armazenamento não contém um mapeamento para o caminho ao qual concede acesso. As credenciais de armazenamento são controladas por acesso para determinar quais usuários podem usar a credencial.

  • Um local externo mapeia uma credencial de armazenamento com um caminho de armazenamento cloud ao qual concede acesso. O local externo concede acesso apenas a esse caminho de armazenamento cloud e seu conteúdo. Os locais externos têm acesso controlado para determinar quais usuários podem usá-los. Um local externo é usado automaticamente quando seu 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 acessado 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.

Locais externos e credenciais de armazenamento são armazenados no nível do metastore, e não em um catálogo. Para criar uma credencial de armazenamento, você deve ser administrador account 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 . Consulte Conectar-se ao armazenamento de objetos clouds usando o Unity Catalog.

Criar uma tabela

Use um dos seguintes exemplos de comando em um Notebook ou no editor query SQL para criar uma tabela externa.

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

Nos exemplos a seguir, substitua os valores nos espaços reservados:

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

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

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

  • <table-name>: Um nome para a tabela.

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

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

  • <table-directory>: diretório onde 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 Databricks, mesmo que tenham recebido privilégios em um local externo ou credencial de armazenamento para fazer isso. O objetivo é garantir que os usuários não possam burlar os controles de acesso aplicados às tabelas lendo arquivos diretamente de seu locatário de nuvem.

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

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

library(SparkR)

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

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

O Unity Catalog verifica se você tem as seguintes permissões:

  • CREATE EXTERNAL TABLE no local externo que faz referência ao caminho de armazenamento em nuvem especificado.

  • CREATE TABLE no esquema pai.

  • USE SCHEMA no esquema pai.

  • USE CATALOG no catálogo pai.

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

Observação

Em vez disso, o senhor pode migrar uma tabela externa existente no site Hive metastore para Unity Catalog sem duplicar seus dados. Consulte Atualização de uma única tabela Hive para uma tabela externa do Unity Catalog usando o assistente de atualização.

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

Notebook de exemplo: criar tabelas externas

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

Crie e gerencie uma tabela externa no Unity Catalog Notebook

Abra o bloco de anotações em outra guia

Crie uma tabela de 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 Unity Catalog lê os arquivos naquele local e insere seu conteúdo na tabela. No Unity Catalog, chama-se de acesso baseado em caminho.

Você pode seguir os exemplos nesta seção ou usar a IU de adição de dados.

Explorar o conteúdo dos arquivos

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

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

Crie uma tabela a partir dos arquivos

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

Observação

Em vez disso, o senhor pode migrar uma tabela externa existente no site Hive metastore para Unity Catalog sem duplicar seus dados. Consulte Atualização de uma única tabela Hive para uma tabela externa do Unity Catalog usando o assistente de atualização.

Importante

  • Quando você cria uma tabela com esse método, o caminho de armazenamento é lido apenas uma vez para evitar a duplicação de registros. Se você deseja reler o conteúdo do diretório, deve eliminar e recriar a tabela. Para uma tabela existente, você pode inserir registros de um caminho de armazenamento.

  • O caminho do bucket no qual 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.

  • Você deve ter as seguintes permissões:

    • USE CATALOG no catálogo pai e USE SCHEMA no esquema.

    • CREATE TABLE no esquema pai.

    • READ FILES no local externo associado ao caminho do bucket onde 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á de CREATE EXTERNAL TABLE no caminho do bucket em que a tabela será criada.

Para criar uma nova tabela gerencial e preenchê-la com dados em seu armazenamento cloud , use os exemplos a seguir.

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

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

library(SparkR)

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

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

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

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

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

library(SparkR)

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

spark.sql("CREATE TABLE <catalog>.<schema>.<table-name> " +
  "( " +
  "  <column-specification> " +
  ") " +
  "USING <format> " +
  "LOCATION 'gs://<table-location>' " +
  "SELECT * from <format>.`s3://<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 exemplos a seguir, 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 do bucket que contém os arquivos de dados.

  • <format>: O formato dos arquivos, por exemplo delta.

  • <table-location>: o caminho do bucket onde a tabela será criada.

Importante

  • Quando você insere registros em uma tabela utilizando esse método, o caminho do bucket informado é lido apenas uma vez para evitar a duplicação de registros.

  • O caminho do bucket no qual 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.

  • Você deve ter as seguintes permissões:

    • USE CATALOG no catálogo pai e USE SCHEMA no esquema.

    • MODIFY na tabela.

    • READ FILES no local externo associado ao caminho do bucket onde 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ê precisa de CREATE EXTERNAL TABLE no caminho do bucket onde a tabela está localizada.

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

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

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

library(SparkR)

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

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

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

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

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

library(SparkR)

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

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

Adicionar comentários a uma tabela

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

  • O comando COMMENT ON . Esta opção não oferece suporte a comentários de coluna.

  • A opção COMMENT quando você usa os comandos CREATE TABLE e ALTER TABLE . Esta opção oferece suporte a comentários de coluna.

  • O campo de comentário “manual” no Catalog Explorer. Esta opção oferece suporte a comentários de coluna. Consulte Dados do documento no Catalog Explorer usando comentários de redução.

  • Comentários gerados por IA (também conhecidos como documentação gerada por IA) no Catalog Explorer. Você pode view um comentário sugerido por um modelo de linguagem grande (LLM) que leva em account os metadados da tabela, como o esquema da tabela e os nomes das colunas, e editar ou aceitar o comentário como está para adicioná-lo. Consulte Adicionar comentários gerados por IA a uma tabela.