Criar tabelas Delta externas a partir de clientes externos
Visualização
Esse recurso está em Public Preview.
Esta página fornece informações sobre como criar tabelas externas d Unity Catalog, suportadas por Delta Lake, a partir de clientes e sistemas externos.
A Databricks recomenda o uso do Apache Spark para criar tabelas externas, a fim de garantir que as definições das colunas estejam em um formato compatível com o Apache Spark. A API não valida a correção da especificação da coluna. Se a especificação não for compatível com o Apache Spark, o Databricks Runtime poderá não conseguir ler as tabelas.
Requisitos
-
Ative o acesso externo a dados para sua metastore. Consulte Habilitar o acesso externo a dados no metastore.
-
Conceda ao responsável pela configuração da integração os seguintes privilégios
EXTERNAL USE SCHEMA
privilégio no esquema que contém os objetos.EXTERNAL USE LOCATION
privilégio no local externo que contém o caminho. Consulte Conceder privilégios de administrador principal do Unity Catalog.CREATE TABLE
permissão na tabela,CREATE EXTERNAL TABLE
no local externo,USE CATALOG
no catálogo principal eUSE SCHEMA
no esquema principal.
Consulte Conceder privilégios de administrador principal do Unity Catalog.
É possível criar tabelas externas utilizando o Apache Spark, a API do Unity Catalog ou outros clientes externos.
Criar tabelas Delta utilizando o Apache Spark
A seguir, apresentamos um exemplo das configurações necessárias para configurar o Apache Spark para criar tabelas Delta externas do Unity Catalog:
"spark.sql.extensions": "io.delta.sql.DeltaSparkSessionExtension",
"spark.sql.catalog.spark_catalog": "io.unitycatalog.spark.UCSingleCatalog",
"spark.hadoop.fs.s3.impl": "org.apache.hadoop.fs.s3a.S3AFileSystem",
"spark.sql.catalog.<uc-catalog-name>": "io.unitycatalog.spark.UCSingleCatalog",
"spark.sql.catalog.<uc-catalog-name>.uri": "<workspace-url>/api/2.1/unity-catalog",
"spark.sql.catalog.<uc-catalog-name>.token": "<token>",
"spark.sql.defaultCatalog": "<uc-catalog-name>",
Substitua as seguintes variáveis:
<uc-catalog-name>
: O nome do catálogo no Unity Catalog que contém suas tabelas.<workspace-url>
URL do Databricks workspace.<token>
: tokens OAuth para o principal que configura a integração.
Para que o Apache Spark e o Delta Lake funcionem em conjunto com o Unity Catalog, é necessário ter pelo menos o Apache Spark 3.5.3. e Delta Lake 3.2.1.
Inclua as seguintes dependências ao iniciar o Apache Spark:
--packages "org.apache.hadoop:hadoop-aws:3.3.4,\
io.delta:delta-spark_2.12:3.2.1,\
io.unitycatalog:unitycatalog-spark_2.12:0.2.0"
Agora é possível criar tabelas externas utilizando SQL:
CREATE TABLE <uc-catalog-name>.<schema-name>.<table-name> (id INT, desc STRING)
USING delta
LOCATION <path>;
Criar tabelas Delta utilizando a API
Para criar uma tabela Delta externa usando a API REST do Unity Catalog, siga estas etapas:
Passo 1: Efetue uma solicitação POST para a API Criar tabela
Utilize a seguinte solicitação API para registrar os metadados da tabela em Unity Catalog:
curl --location --request POST 'https://<workspace-url>/api/2.0/unity-catalog/tables/' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
"name": "<table-name>",
"catalog_name": "<uc-catalog-name>",
"schema_name": "<schema-name>",
"table_type": "EXTERNAL",
"data_source_format": "DELTA",
"storage_location": "<path>",
"columns": [
{
"name": "id",
"type_name": "LONG",
"type_text": "bigint",
"type_json": "\"long\"",
"type_precision": 0,
"type_scale": 0,
"position": 0,
"nullable": true
},
{
"name": "name",
"type_name": "STRING",
"type_text": "string",
"type_json": "\"string\"",
"type_precision": 0,
"type_scale": 0,
"position": 1,
"nullable": true
}
]
}'
Substitua as seguintes variáveis:
<workspace-url>
: URL do Databricks workspace<token>
: tokens para o principal que realiza a chamada " API "<uc-catalog-name>
: Nome do catálogo no Unity Catalog que conterá a tabela externa<schema-name>
: Nome do esquema no catálogo em que a tabela será criada<table-name>
: Nome da tabela externa<path>
: caminho totalmente qualificado para os dados da tabela
Passo 2: Inicialize a localização da tabela Delta
A chamada “ API ” registra a tabela em :[UC], mas não cria os arquivos “ Delta ” no local de armazenamento. Para inicializar a localização da tabela, crie uma tabela Delta vazia utilizando o Spark:
O esquema utilizado nesta etapa deve corresponder exatamente às definições de coluna fornecidas na solicitação da API.
from pyspark.sql.types import StructType, StructField, StringType, LongType
# Define schema matching your API call
schema = StructType([
StructField("id", LongType(), True),
StructField("name", StringType(), True)
])
# Create an empty DataFrame and initialize the Delta table
empty_df = spark.createDataFrame([], schema)
empty_df.write \
.format("delta") \
.mode("overwrite") \
.save("<path>")
A API Criar Tabela para clientes externos apresenta as seguintes limitações:
-
Apenas tabelas Delta externas são suportadas (
"table_type": "EXTERNAL"
e"data_source_format": "DELTA"
). -
Somente os seguintes campos são permitidos:
name
catalog_name
schema_name
table_type
data_source_format
columns
storage_location
properties
-
As máscaras de coluna não são suportadas.