Sincronizar dados das tabelas do Unity Catalog com uma instância de banco de dados
Visualização
Esse recurso está em Public Preview nas seguintes regiões: us-east-1
, us-west-2
, eu-west-1
, ap-southeast-1
, ap-southeast-2
, eu-central-1
, us-east-2
, ap-south-1
.
Esta página descreve como criar e gerenciar uma tabela sincronizada. Uma tabela sincronizada é uma tabela Postgres somente de leitura do Unity Catalog que sincroniza automaticamente os dados de uma tabela do Unity Catalog com a instância do banco de dados do Lakebase. A sincronização de uma tabela Unity Catalog no Postgres permite consultas de leitura de baixa latência e oferece suporte à união em tempo de consulta com outras tabelas do Postgres.
A sincronização é tratada por um gerenciador LakeFlow declarativo pipeline que atualiza continuamente a tabela do Postgres com as alterações da tabela de origem. Após a criação, as tabelas sincronizadas podem ser consultadas diretamente usando as ferramentas do Postgres.
As características key das tabelas sincronizadas são as seguintes:
- Somente leitura no Postgres para manter a integridade dos dados com a fonte
- Sincronizado automaticamente usando o gerenciar LakeFlow Pipeline declarativo
- Pode ser consultado por meio de interfaces padrão do PostgreSQL
- gerenciar por meio do site Unity Catalog para governança e gerenciamento do ciclo de vida
Antes de começar
- O senhor tem uma tabela do Unity Catalog em qualquer catálogo.
- Você tem permissões
CAN USE
na instância do banco de dados.
Crie uma tabela sincronizada
- UI
- curl
Para sincronizar uma tabela do Unity Catalog com o Postgres, faça o seguinte:
-
Clique em Catalog na barra lateral workspace.
-
Encontre e selecione a tabela do Unity Catalog na qual o senhor deseja criar uma tabela sincronizada.
-
Clique em Criar tabela sincronizada >.
-
Selecione seu catálogo, esquema e insira um nome de tabela para a nova tabela sincronizada.
- Tabelas sincronizadas também podem ser criadas em catálogos padrão, com algumas configurações adicionais. Selecione seu catálogo padrão, um esquema e insira um nome de tabela para a tabela sincronizada recém-criada.
-
Selecione uma instância de banco de dados e insira o nome do banco de dados Postgres no qual criar a tabela sincronizada. O campo do banco de dados Postgres será default para o catálogo de destino selecionado no momento. Se não houver um banco de dados Postgres com esse nome, o Databricks criará um novo.
-
Selecione uma chave primária . É necessário um site primário,key pois ele permite o acesso eficiente às linhas para leituras, atualizações e exclusões.
-
Opcionalmente, selecione uma chave Timeseries . Se duas linhas tiverem o mesmo primário key na tabela de origem, use uma chave Timeseries para configurar a deduplicação.
-
Selecione o modo de sincronização entre Snapshot , Triggered e Continuous . Para todos os modos de sincronização, toda a tabela de origem é lida e gravada no Postgres.
Política
Descrição
Snapshot
A pipeline execução uma vez para tirar um Snapshot da tabela de origem e copiá-lo para a tabela sincronizada. As alterações subsequentes na tabela de origem são refletidas automaticamente na tabela sincronizada, tirando um novo Snapshot da origem e criando uma nova cópia. O conteúdo da tabela sincronizada é atualizado atomicamente.
Acionado
A pipeline execução uma vez para criar uma cópia inicial do Snapshot da tabela de origem na tabela sincronizada. Diferentemente do modo de sincronização Snapshot, quando a tabela sincronizada é atualizada, somente as alterações desde a última execução do pipeline são recuperadas e aplicadas à tabela sincronizada. O incremental refresh pode ser acionado manualmente ou automaticamente de acordo com um programa.
Contínuo
O pipeline executa continuamente. As alterações subsequentes na tabela de origem são aplicadas de forma incremental à tabela sincronizada no modo de transmissão de tempo real. Não é necessário acessar o site refresh manualmente.
Para oferecer suporte ao modo de sincronização acionada ou contínua , a tabela de origem deve ter a opção Alterar feed de dados ativada.
-
Escolha se o senhor deseja criar essa tabela sincronizada a partir de um pipeline novo ou existente.
- Ao criar um novo pipeline e usar um catálogo gerenciar, o senhor precisa escolher o local de armazenamento para a tabela de preparação. Se estiver usando um catálogo padrão, a tabela intermediária será automaticamente armazenada no catálogo.
- Se estiver usando um pipeline existente, verifique se o novo modo de sincronização corresponde ao modo do pipeline.
-
Depois que o status da tabela sincronizada for Online , acesse log in na instância do banco de dados e consulte a tabela recém-criada. Consulte sua tabela usando o editorSQL, ferramentas externas ou o Notebook.
Crie uma tabela sincronizada em um catálogo de banco de dados.
export CATALOG_NAME=<Database catalog>
export SRC_TBL="source_catalog.source_schema.source_table"
export DEST_TBL="$CATALOG_NAME.some_schema.synced_table"
export PKS='["id"]'
export ST_CATALOG = "storage_catalog"
export ST_SCHEMA = "storage_schema"
curl -X POST https://$WORKSPACE/api/2.0/database/synced_tables \
-H "Content-Type: text/json" \
-H "Authorization: Bearer ${DATABRICKS_TOKEN}" \
--data-binary @- << EOF
{
"name": "$DEST_TBL",
"spec": {
"source_table_full_name": "$SRC_TBL",
"primary_key_columns": $PKS,
"scheduling_policy": "TRIGGERED",
},
"new_pipeline_spec": {
"storage_catalog": "$ST_CATALOG",
"storage_schema": "$ST_SCHEMA",
}
}
EOF
Crie uma tabela sincronizada em um catálogo padrão do Unity Catalog.
export CATALOG_NAME=<Standard catalog>
export DATABASE_INSTANCE=<database instance>
export POSTGRES_DATABASE=$CATALOG_NAME
export SRC_TBL="source_catalog.source_schema.source_table"
export DEST_TBL="$CATALOG_NAME.some_schema.sync_table"
export PKS='["id"]'
export ST_CATALOG = "storage_catalog"
export ST_SCHEMA = "storage_schema"
curl -X POST https://$WORKSPACE/api/2.0/database/synced_tables \
-H "Content-Type: text/json" \
-H "Authorization: Bearer ${DATABRICKS_TOKEN}" \
--data-binary @- << EOF
{
"name": "$DEST_TBL",
"database_instance_name": "$DATABASE_INSTANCE",
"logical_database_name": "$POSTGRES_DATABASE",
"spec": {
"source_table_full_name": "$SRC_TBL",
"primary_key_columns": $PKS,
"scheduling_policy": "TRIGGERED",
},
"new_pipeline_spec": {
"storage_catalog": "$ST_CATALOG",
"storage_schema": "$ST_SCHEMA",
}
}
EOF
Verifique o status de uma tabela sincronizada.
export SYNCEDTABLE='pg_db.silver.sbtest1_online'
curl --request GET \
"https://e2-dogfood.staging.cloud.databricks.com/api/2.0/database/synced_tables/$SYNCEDTABLE" \
--header "Authorization: Bearer dapi..."
Operações suportadas
Somente um conjunto limitado de operações é suportado no lado do Postgres para tabelas sincronizadas:
- Consultas somente para leitura
- Criação de índices
- Eliminar a tabela (para liberar espaço depois de remover a tabela sincronizada do Unity Catalog)
Embora o senhor possa modificar essa tabela de outras maneiras, ela interfere no pipeline de sincronização.
Excluir uma tabela sincronizada
Para excluir uma tabela sincronizada, o senhor deve excluí-la do Unity Catalog e, em seguida, soltar a tabela na instância do banco de dados. A exclusão da tabela sincronizada do site Unity Catalog cancela o registro da tabela e interrompe qualquer atualização de dados. No entanto, a tabela permanece no banco de dados Postgres subjacente. Para liberar espaço na instância do banco de dados, conecte-se à instância e use o comando DROP TABLE
.
-
Clique em Catalog na barra lateral workspace.
-
Encontre e selecione a tabela sincronizada que você deseja excluir.
-
Clique em
> Excluir .
-
Conecte-se à instância com
psql
, o editor SQL ou a partir de um Notebook. -
Eliminar a tabela usando o PostgreSQL.
SQLDROP TABLE synced_table_database.synced_table_schema.synced_table
Propriedade e permissões
Se você criar um novo banco de dados, esquema ou tabela Postgres, a propriedade do Postgres será definida da seguinte forma:
- A propriedade é atribuída ao usuário que cria o banco de dados, o esquema ou a tabela, se o login do Databricks existir como uma função no Postgres. Para adicionar uma função de identidade do Databricks no Postgres, consulte Criar e gerenciar funções do Postgres para identidades do Databricks.
- Caso contrário, a propriedade é atribuída ao proprietário do objeto pai no Postgres (normalmente o
databricks_superuser
).
gerenciar o acesso à tabela sincronizada
Depois que uma tabela sincronizada é criada, o databricks_superuser
pode READ
uma tabela sincronizada do Postgres. O databricks_superuser
tem privilégios pg_read_all_data
e pg_write_all_data
:
-
O
databricks_superuser
também pode conceder esses privilégios a outros usuários:SQLGRANT USAGE ON SCHEMA synced_table_schema TO user;
SQLGRANT SELECT ON synced_table_name TO user;
-
O
databricks_superuser
pode revogar esses privilégios:SQLREVOKE USAGE ON SCHEMA synced_table_schema FROM user;
SQLREVOKE {SELECT | INSERT | UPDATE | DELETE} ON synced_table_name FROM user;
gerenciar operações de tabela sincronizada
O site databricks_superuser
pode gerenciar quais usuários estão autorizados a realizar operações específicas em uma tabela sincronizada. As operações suportadas para tabelas sincronizadas são as seguintes:
CREATE INDEX
ALTER INDEX
DROP INDEX
DROP TABLE
Todas as outras operações DDL são negadas para tabelas sincronizadas.
Para conceder esses privilégios a usuários adicionais, o databricks_superuser
deve primeiro criar uma extensão em databricks_auth
:
CREATE EXTENSION IF NOT EXISTS databricks_auth;
Em seguida, o databricks_superuser
pode adicionar um usuário para gerenciar uma tabela sincronizada:
SELECT databricks_synced_table_add_manager('"synced_table_schema"."synced_table"'::regclass, '[user]');
O databricks_superuser
pode remover um usuário do gerenciamento de uma tabela sincronizada:
SELECT databricks_synced_table_remove_manager('[table]', '[user]');
O site databricks_superuser
pode view todos os gerentes:
SELECT * FROM databricks_synced_table_managers;
Manipular caracteres inválidos
Certos caracteres, como o byte nulo (0x00), são permitidos nas colunas STRING
, ARRAY
, MAP
ou STRUCT
nas tabelas Delta, mas não são compatíveis com as colunas TEXT
ou JSONB
do Postgres. Como resultado, a sincronização desses dados do Delta para o Postgres pode levar a falhas de inserção com erros:
org.postgresql.util.PSQLException: ERROR: invalid byte sequence for encoding "UTF8": 0x00
org.postgresql.util.PSQLException: ERROR: unsupported Unicode escape sequence DETAIL: \u0000 cannot be converted to text.
- O primeiro erro ocorre quando um byte nulo aparece em uma coluna de strings de nível superior, que mapeia diretamente para o Postgres
TEXT
. - O segundo erro ocorre quando um byte nulo aparece em uma cadeia de caracteres aninhada dentro de um tipo complexo (
STRUCT
,ARRAY
, ouMAP
), que Databricks serializa comoJSONB
. Durante a serialização, todas as strings são convertidas para PostgresTEXT
, onde\u0000
não é permitido.
Como resolver:
Você pode resolver esse problema de uma das seguintes maneiras:
-
Sanitizar campos de strings
Remova ou substitua caracteres não suportados de todos os campos de strings, inclusive aqueles dentro de tipos complexos, antes de sincronizar com o Postgres.
Para remover bytes nulos de uma coluna
STRING
de nível superior, use a funçãoREPLACE
:SQLSELECT REPLACE(column_name, CAST(CHAR(0) AS STRING), '') AS cleaned_column FROM your_table;
-
Converter em binário (somente para colunas
STRING
)Se for necessário preservar o conteúdo bruto de bytes, converta as colunas
STRING
afetadas emBINARY
.
Limitações e considerações
Limitações de nomenclatura e identificador
- Caracteres permitidos: Os nomes de bancos de dados, esquemas e tabelas do Postgres para tabelas sincronizadas só podem conter caracteres alfanuméricos e sublinhado (
[A-Za-z0-9_]+
). Não há suporte para hífens (-
) e outros caracteres especiais. - Identificadores de colunas e tabelas: Evite usar letras maiúsculas ou caracteres especiais em nomes de colunas ou tabelas na tabela de origem do Unity Catalog. Se mantidos, você precisará citar esses identificadores ao referenciá-los no Postgres.
desempenho e sincronização
- Velocidade de sincronização: A sincronização de dados em tabelas sincronizadas pode ser mais lenta do que gravar dados diretamente na instância do banco de dados com um cliente PostgreSQL nativo devido ao processamento adicional. O modo de sincronização contínua atualiza os dados da tabela gerenciar Unity Catalog para a tabela sincronizada em um intervalo mínimo de 15 segundos.
- Uso da conexão: Cada sincronização de tabela pode usar até 16 conexões com a instância do banco de dados, que contam para o limite de conexão da instância.
- Idempotência da API: As APIs de tabela sincronizada são idempotentes e podem precisar ser repetidas se ocorrerem erros para garantir operações oportunas.
- Alterações de esquema: Para tabelas sincronizadas no modo
Triggered
ouContinuous
, somente alterações de esquema aditivas (por exemplo, adição de uma nova coluna) das tabelas do Unity Catalog são refletidas na tabela sincronizada. - Chave duplicada: Se duas linhas tiverem a mesma chave primária key na tabela de origem, a sincronização pipeline falhará, a menos que o senhor configure a deduplicação usando uma chave Timeseries. No entanto, o uso de uma chave Timeseries tem uma penalidade de desempenho.
- Taxa de atualização: O pipeline de sincronização suporta gravações contínuas de aproximadamente 1.200 linhas por segundo por Unidade de Capacidade (CU) e gravações em massa de até 15.000 linhas por segundo por CU.
Capacidade e limites
-
Limites da tabela:
- Limite de 20 tabelas sincronizadas por tabela de origem.
- Cada sincronização de tabela pode usar até 16 conexões de banco de dados.
-
Limites de tamanho e refresh completo:
- Se o senhor preencherrefresh uma tabela sincronizada, a versão antiga no Postgres não será excluída até que a nova tabela seja sincronizada. Ambas as versões contam temporariamente para o limite de tamanho do banco de dados lógico durante o refresh.
- Cada tabela sincronizada pode ter até 2 TB. Se o senhor precisar de atualização em vez de recriação completa da tabela, o limite será de 1 TB.
- Se o tamanho da tabela do Unity Catalog não compactado e em formato de linha exceder o limite de tamanho da instância do banco de dados (2 TB), a sincronização falhará. Você deve descartar a tabela sincronizada no Postgres antes de escrever mais na instância.
Integração de catálogos
- Duplicação de catálogo: A criação de uma tabela sincronizada em um catálogo padrão direcionado a um banco de dados Postgres que também esteja registrado como um catálogo de banco de dados separado fará com que a tabela sincronizada apareça no Unity Catalog nos catálogos padrão e de banco de dados.