使用同步表提供湖仓数据

同步表允许您通过 Lakebase Postgres 提供来自 Unity 目录的分析级数据。 Unity 目录表同步到 Postgres,以便应用程序可以直接以低延迟查询 Lakehouse 数据。 这一过程通常被称为反向提取、转化和装载(ETL)。 数据湖仓针对分析和数据增强进行了优化,而 Lakebase 则专为需要快速查找式查询和完整 ACID 事务的运营工作负载而设计。 同步表通过保持数据随时可用以用于实时应用,弥合分析存储与运营系统之间的差距。

显示从 Lakehouse 到 Lakebase 到应用程序的数据流的体系结构图

示例用例

你可以将同步表用于数据服务的用例,例如:

  • 向 Databricks 应用传送新用户档案的个性化引擎
  • 提供湖屋中计算的模型预测或特征值的应用程序
  • 面向客户的仪表板,实时展示 KPI
  • 为立即行动提供风险评分的欺诈检测服务
  • 支持从湖屋数据中提供增强型客户记录的工具

支持的源

已同步的表格支持以下 Unity Catalog 源类型:

  • 托管表和外部 Delta 表
  • 托管表和外部 Iceberg 表
  • 视图和具体化视图

工作原理

Databricks 同步表会在 Lakebase 中创建 Unity Catalog 数据的托管副本。 创建同步表时,将得到:

  1. Unity Catalog 中引用同步管道的同步表
  2. Lakebase 中的 Postgres 表 (应用程序可查询的只读表)

显示同步表中三表关系的关系图

例如,可以将黄金表、工程特征或 ML 输出从 analytics.gold.user_profiles 同步到新的同步表 analytics.gold.user_profiles_synced 中。 在 Postgres 中,Unity 目录架构名称将成为 Postgres 架构名称,因此如下所示 gold.user_profiles_synced:

SELECT * FROM gold.user_profiles_synced WHERE user_id = 12345;

应用程序使用标准 Postgres 驱动程序连接,并查询同步数据以及它们自己的操作状态,处理同一数据库中自己表上的插入、更新和删除。

同步管道使用托管的 Lakeflow 管道,根据源表中的更改持续更新 Unity Catalog 同步表和 Postgres 表。 每个同步最多可以使用 16 个到 Lakebase 数据库的连接。 连接限制取决于计算大小。 请参阅计算规格。

警告

尽管可以直接在 Postgres 中修改同步表,但Azure Databricks严格建议只运行读取查询来保护源的数据完整性。 有关同步表支持的操作,请参阅 Postgres 中已同步表上允许的操作。

通过LTAP直接写入的加速同步

重要

LTAP Direct Writes 目前处于 测试阶段。 通常有同步表可用。

LTAP 直接写入是一个可选的同步表设置,可加快大负载的速度。 它是 LTAP架构的一部分。 它默认关闭,你可以在创建同步表对话框的同步设置下选择 LTAP Direct Writes,为每个同步表单独启用。 启用后,它会直接把数据写入支持你 Lakebase 分支的存储层,而不是通过实时计算端点进行批量写入,这样加载完成得更快,运行时不会给端点增加查询负载。

LTAP 直接写入加速的过程取决于同步模式:

  • 所有模式:初始加载。 每个同步表都从加载完整的源代码开始,第一次加载使用LTAP直接写入。
  • 快照:每次后续同步,因为 快照 模式每次都会进行一次完整刷新。
  • 触发式和连续:仅适用于初始加载。 后续更新通过变更数据流逐步应用,而非批量加载。

注释

运行 Postgres 16、17 或 18 的 Lakebase 项目支持 LTAP Direct Writes。 在创建同步表时选择 LTAP Direct Writes,因此无法将其添加到现有同步表。 若要对现有同步表使用 LTAP Direct Writes,请删除该同步表并创建一个新的同步表。

如果你没有看到 LTAP 直接写入 复选框,工作区管理员必须从 预览页面 启用 LTAP 直接写入 预览。

同步模式

根据应用程序需求选择正确的同步模式:

模式 说明 何时使用 性能
快照 所有数据的一次性副本 源文件每个周期会更改 >10% 的行 如果修改 >10% 源数据,则效率更高 10 倍
引发 按需或间隔运行的计划更新 源数据行按已知频率发生变化。 每次刷新都会传播插入、更新和删除操作。 良好的成本/滞后平衡。 如果以 <5 分钟为间隔运行,成本较高
连续的 秒级延迟的实时流传输 更改必须几乎实时地显示在 Lakebase 中 滞后时间最低,成本最高。 最小 15 秒间隔

在 创建同步表 对话框中,快照 和 触发 都是 按需 同步模式,可在 高级设置 下使用,而 连续 是单独的模式。

源要求取决于同步模式:

  • 快照每次同步时都会复制所有数据,因此源端只需要支持 SELECT *。
  • 触发 和 连续 以增量方式应用行级变更,因此源端必须提供变更数据流。 在源端启用写入时 变更数据流 ,或使用自动变更数据流。 如果触发源或连续源没有变更数据馈送,界面会显示一条警告,并给出需要运行的确切 ALTER TABLE 命令。

自动变更数据源 在读取时计算行级变更,而无需在源端输入写入时的变更数据。 这使得更多源类型,包括受管理的 Apache Iceberg v3 表,在 触发 或 连续 模式下同步。 关于自动变更数据流支持的源类型,请参见 自动变更数据流 文档。

创建同步表

先决条件

您需要:

  • 启用了 Lakebase 的 Databricks 工作区。
  • Lakebase 项目(请参阅 创建项目)。
  • 一个待同步的 Unity Catalog 表。
  • 创建同步表的权限。 你需要在使用的任何模式上具有USE_SCHEMA和CREATE_TABLE权限。 若要授予这些权限,请参阅 在 Unity Catalog 中管理权限。

对于 触发 模式或 连续 模式,源必须提供变更数据流。 要么在符合条件的Delta Lake源表上启用遗留变更数据流,要么对如托管的Apache Iceberg v3表等源使用 自动变更数据流 。

要在 Delta 源表上启用写入时变更数据馈送,请运行以下命令:

ALTER TABLE your_catalog.your_schema.your_table
SET TBLPROPERTIES (delta.enableChangeDataFeed = true)

在创建同步表之前,请先查看以下内容:

  • 来源:支持的源类型列于 支持的来源中。
  • 名称和限制:命名规则、连接使用量和每个源的限制列在 容量规划中。
  • 列类型:类型映射、不支持类型和导致同步失败的字符在 数据类型和兼容性中有所涵盖。
  • 创建者身份:创建同步表的身份会被授予对该表的访问权限,之后无法更改该访问权限的授予对象。 查看 创建同步表的用户的访问权限。

UI

  1. 在 Lakehouse 中,转到工作区侧边栏的 目录,并选择你要同步的 Unity Catalog 表。

    Catalog Explorer 中显示所选表

  2. 从表详细信息视图中单击“ 创建>同步表 ”。

    “创建”按钮的下拉菜单中显示“已同步表”选项

  3. 在“创建同步表”对话框中,配置以下部分,然后单击创建:

    Destination

    • 名称:选择同步表的目录和架构,然后输入表名。 这会同时创建 Unity 目录同步表和可以查询的 Postgres 表。 目录和架构列表仅包含你具有 USE_SCHEMA 和 CREATE_TABLE 权限的 Unity Catalog 架构。 如果未看到所需的架构,请与目录管理员确认权限。
    • Lakebase Postgres 数据库:将 数据库类型 设置为 自动缩放,然后选择你的 项目、分支 和 Postgres 数据库。

    同步设置

    • 同步模式:选择 按需 或 连续。 对于按需,展开高级设置,并选择快照或触发。 有关指南,请参阅 同步模式。
    • LTAP Direct Writes:(可选)选中此复选框以加速初始加载。 运行 Postgres 16、17 或 18 的 Lakebase 项目支持此选项。 如果没有看到该复选框,工作区管理员必须在Previews 页面启用LTAP Direct Writes预览。 请参阅 使用 LTAP Direct Writes 加速同步。

    管道设置

    • 管道:选择“新建”为此同步表创建管道,或选择使用现有以重复使用现有管道。
    • 无服务器使用策略:(可选)为同步管道选择一个无服务器使用策略。

    架构

    • 主键:验证主键(通常自动检测)。 如果每个主键值在源中都是唯一的,请保持选中 唯一。 如果主键值可以重复,请取消选中 唯一,并设置 时序键。 创建同步表后,你不能更改主键或时间序列键。

      重要

      同步表中主键的列不允许为空。 主键列中为 null 的行 将从同步中排除。

    • 时间序列键:(可选)当主键值在源数据中可能重复时,选择一列来配置去重。 同步后的表中,对于每个主键,仅包含时间序列键值最新的那一行。 有关没有时间序列键的故障模式,请参阅 重复键。

    • 自定义列类型:(可选)覆盖源列到 Postgres 类型的映射方式。 如果你将列映射到 vector 或 halfvec,先在目标数据库中安装矢量扩展。 请参阅 自定义类型映射。

    如果你选择了 触发 或 连续 且尚未启用更改数据馈送,你将看到一条警告,其中包含要运行的确切命令。

  4. 监控目录中的同步表。 “ 概述 ”选项卡显示同步状态、配置、管道状态和上次同步时间戳。 立即同步以进行手动刷新。

CLI

databricks postgres create-synced-table my-catalog.sales.orders \
  --json '{
    "spec": {
      "source_table_full_name": "main.sales.orders",
      "branch": "projects/my-project/branches/production",
      "primary_key_columns": ["order_id"],
      "scheduling_policy": "SNAPSHOT",
      "postgres_database": "mydb",
      "create_database_objects_if_missing": true
    }
  }'

SYNCED_TABLE_ID位置参数使用格式 catalog.schema.table。 在 Postgres 中,表{table}是在模式{schema}中创建的,位于你用postgres_database设置的数据库中(此处为mydb)。 该命令会等待操作默认完成。 有关所有可用选项,请参阅 databricks postgres create-synced-table。

要覆盖默认的列类型映射,请将 type_overrides 添加到 spec 中。 请参阅 自定义类型映射。

Python SDK

from databricks.sdk import WorkspaceClient
from databricks.sdk.service.postgres import (
    SyncedTable,
    SyncedTableSyncedTableSpec,
    SyncedTableSyncedTableSpecSyncedTableSchedulingPolicy,
)

w = WorkspaceClient()

synced_table = w.postgres.create_synced_table(
    synced_table=SyncedTable(spec=SyncedTableSyncedTableSpec(
        source_table_full_name="main.sales.orders",
        branch="projects/my-project/branches/production",
        primary_key_columns=["order_id"],
        scheduling_policy=SyncedTableSyncedTableSpecSyncedTableSchedulingPolicy.SNAPSHOT,
        postgres_database="mydb",
        create_database_objects_if_missing=True,
    )),
    synced_table_id="my-catalog.sales.orders",
).wait()

print(f"Synced table created: {synced_table.name}")

synced_table_id 使用 catalog.schema.table 格式,并成为 Unity Catalog 的同步表名称。 在 Postgres 中,表{table}是在模式{schema}中创建的,位于你用postgres_database设置的数据库中(此处为mydb)。

Java SDK

import com.databricks.sdk.WorkspaceClient;
import com.databricks.sdk.service.postgres.*;
import java.util.List;

WorkspaceClient w = new WorkspaceClient();

SyncedTable syncedTable = w.postgres().createSyncedTable(
    new CreateSyncedTableRequest()
        .setSyncedTableId("my-catalog.sales.orders")
        .setSyncedTable(new SyncedTable()
            .setSpec(new SyncedTableSyncedTableSpec()
                .setSourceTableFullName("main.sales.orders")
                .setBranch("projects/my-project/branches/production")
                .setPrimaryKeyColumns(List.of("order_id"))
                .setSchedulingPolicy(SyncedTableSyncedTableSpecSyncedTableSchedulingPolicy.SNAPSHOT)
                .setPostgresDatabase("mydb")
                .setCreateDatabaseObjectsIfMissing(true))))
    .waitForCompletion();

System.out.println("Synced table created: " + syncedTable.getName());

curl

curl -X POST "https://your-workspace.cloud.databricks.com/api/2.0/postgres/synced_tables?synced_table_id=my-catalog.sales.orders" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "spec": {
      "source_table_full_name": "main.sales.orders",
      "branch": "projects/my-project/branches/production",
      "primary_key_columns": ["order_id"],
      "scheduling_policy": "SNAPSHOT",
      "postgres_database": "mydb",
      "create_database_objects_if_missing": true
    }
  }'

这将返回一个长时间运行的操作。 轮询返回的 name 字段,直到 done: true。 请参阅 长时间运行的操作。 有关身份验证设置,请参阅 “身份验证”。

计划或触发后续同步

创建同步表时,初始加载会自动运行。 之后,同步的运行方式取决于同步模式:

  • 连续 模式会实时传输变化。 你不需要触发同步。
  • 快照 和 触发 模式只有在触发时才同步。 要手动运行同步,请在“目录”中打开同步表,然后单击“概述”选项卡上的“立即同步”。要自动运行同步,请将同步表的管道作为数据库表同步管道任务添加到 Lakeflow 作业中的作业,然后使用以下触发器之一配置该作业:

源表更新时触发

当源 Unity Catalog 表更新时触发该作业。 在触发式模式下,仅增量应用新变更,可在避免“连续”模式始终在线成本的同时,提供近乎实时的数据新鲜度。

  1. 在您的工作区中,单击工作流图标,在侧栏中选择作业和管道。
  2. 单击“ 创建作业 ”或打开现有作业。
  3. 在“ 任务 ”选项卡上,单击“ + 添加其他任务类型”。
  4. 在 引入和转换下,选择 “数据库表同步”管道。
  5. 在 “管道 ”字段中,选择与同步表关联的管道。
  6. 在 “计划和触发器”下,单击“ 添加触发器”。
  7. 选择 “表更新 ”作为触发器类型。
  8. 在 “表”下,选择要监视的源 Unity 目录表。
  9. 单击“ 保存”。

按计划触发

按固定频率执行同步。 非常适合 快照 模式,其中夜间或每周完全刷新通常是最有效的模式。

  1. 在您的工作区中,单击工作流图标,在侧栏中选择作业和管道。
  2. 单击“ 创建作业 ”或打开现有作业。
  3. 在“ 任务 ”选项卡上,单击“ + 添加其他任务类型”。
  4. 在 引入和转换下,选择 “数据库表同步”管道。
  5. 在 “管道 ”字段中,选择与同步表关联的管道。
  6. 在 “计划和触发器”下,单击“ 添加触发器”。
  7. 选择 已计划 作为触发类型。
  8. 设置 cron 计划和时区,然后单击“ 保存”。

检查同步状态

检查同步表的当前状态和上次同步时间:

注释

在同步过程中,流水线在报告 INITIALIZING 事件的同时执行所有数据处理。 大型同步可为整个运行报告 INITIALIZING。 这是意料之中的,并不意味着流程就停滞不前。

UI

在 “目录”中,导航到同步表并选择“ 概述 ”选项卡。它显示当前同步状态、管道状态和上次同步时间戳。

Python SDK

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()

table = w.postgres.get_synced_table("synced_tables/my-catalog.sales.orders")
print(f"State: {table.status.detailed_state}")
print(f"Last sync: {table.status.last_sync_time}")
print(f"Message: {table.status.message}")

Java SDK

import com.databricks.sdk.WorkspaceClient;
import com.databricks.sdk.service.postgres.SyncedTable;

WorkspaceClient w = new WorkspaceClient();

SyncedTable table = w.postgres().getSyncedTable("synced_tables/my-catalog.sales.orders");
System.out.println("State: " + table.getStatus().getDetailedState());
System.out.println("Last sync: " + table.getStatus().getLastSyncTime());
System.out.println("Message: " + table.getStatus().getMessage());

curl

curl "https://your-workspace.cloud.databricks.com/api/2.0/postgres/synced_tables/my-catalog.sales.orders" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}"

查看同步表谱系

当你创建同步表时,Unity Catalog 会记录从源表到同步表的世系,并将同步管道作为关联实体。 利用数据沿袭追踪同步表中数据的来源,或者在更改源表之前找出哪些同步表依赖于源表。

同步表谱系存在以下限制:

  • 数据血缘仅限于表级。 不会记录列级血缘。
  • 世系止于 Unity Catalog 同步表。 Lakebase 中的 Postgres 表不会出现在谱系图中,应用程序对 Postgres 表运行的查询也不会被记录。
  • 同步表创建时会记录血缘关系。 在提供世系支持之前创建的同步表不会显示世系。 要记录旧同步表的世系,先删除该表然后再重新创建。 重新创建同步表时会执行完整的初始同步。
  • 世系按表名匹配。 如果你重新创建同名的同步表,世系还可以显示已删除同步表的同步管道。
  • 如果同步表也出现在数据库目录中(参见目录集成),世系只会显示在创建时所在目录中的同步表上。

UI

  1. 在你的工作区中,点击数据图标。目录。

  2. 搜索或浏览你的同步表或其源表。

  3. 选择“ 血缘” 标签。源表会作为上游表出现。 同步流水线在两个方向上都显示为 已同步表 流水线条目:上游是因为它会写入已同步表,下游则是因为同步运行会从已同步表中读取。 流水线条目是与数据血缘关联的资产,而不是附加表。

    Lineage 标签页,用于同步表,显示上游源表和同步流水线

  4. 要查看交互式图表,请点击查看沿袭图。 图中显示了源表通过同步流水线连接到同步表。 消费者节点将读取同步表的 Azure Databricks 资产分组,如笔记本、作业和同步流水线。 查询 Postgres 表的应用程序未显示。

    血缘图显示源表连接到同步表

系统表

查询 system.access.table_lineage 系统表。 同步表的血缘记录中,target_type 为 PIPELINE,TABLE 为 entity_type,并且 entity_id 是同步流水线的 ID。 世系会立即出现在目录资源管理器中,但新记录可能需要一些时间才会出现在系统表中。

要查找同步表的来源:

SELECT DISTINCT source_table_full_name, entity_id AS pipeline_id
FROM system.access.table_lineage
WHERE target_table_full_name = 'analytics.gold.user_profiles_synced';

要查找所有依赖源表的同步表,例如在更改源表的模式之前:

SELECT DISTINCT l.target_table_full_name, l.entity_id AS pipeline_id
FROM system.access.table_lineage l
JOIN system.information_schema.tables t
  ON l.target_table_full_name = concat_ws('.', t.table_catalog, t.table_schema, t.table_name)
WHERE l.source_table_full_name = 'analytics.gold.user_profiles'
  AND l.entity_type = 'PIPELINE'
  AND t.data_source_format = 'POSTGRESQL_FORMAT';

同步表的 data_source_format 为 POSTGRESQL_FORMAT,因此该联接将结果限制为同步表。 每个同步还会记录同步管道对源表的读取,且 target_table_full_name 为空。 连接排除了这些记录。 系统表还可以包含同一血缘的重复记录,因此两个查询都使用 DISTINCT。

有关数据沿袭要求、权限和保留的详细信息,请参见 Unity Catalog 中的数据沿袭。 有关完整的系统表模式,请参见 Lineage 系统表参考。

数据类型和兼容性

创建同步表时,Unity 目录数据类型将映射到 Postgres 类型。 复杂类型(ARRAY、MAP、STRUCT)和VARIANT以JSONB形式存储在Postgres中。

源列类型 Postgres 列类型
BIGINT BIGINT
BINARY BYTEA
BOOLEAN BOOLEAN
DATE DATE
DECIMAL(p, s) NUMERIC
DOUBLE 双精度
FLOAT real
INT INTEGER
INTERVAL INTERVAL
SMALLINT SMALLINT
STRING TEXT
TIMESTAMP 时间戳与时区
TIMESTAMP_NTZ 无时区时间戳
TINYINT SMALLINT
ARRAY<元素类型> JSONB
MAP<keyType,valueType> JSONB
STRUCT<fieldName:fieldType[, ...]> JSONB
VARIANT JSONB

注释

不支持 GEOGRAPHY、GEOMETRY 和 OBJECT 类型。

自定义类型映射

当你创建同步表时,可以使用 type_overrides 针对特定列覆盖默认的 Delta 到 Postgres 的类型映射。

注释

vector和halfvec类型需要目标数据库中的向量扩展。 创建同步表不会安装扩展,所以在创建同步表之前先安装一个。 使用 lakebase_vector,它通过Lakebase Search添加人工神经网络向量搜索,并将 pgvector 作为依赖安装:

CREATE EXTENSION IF NOT EXISTS lakebase_vector CASCADE;

要在不使用 Lakebase Search 的情况下使用 vector 和 halfvec 类型,请通过 CREATE EXTENSION IF NOT EXISTS vector; 单独安装 pgvector。 该 varchar 类型不需要扩展。

源列类型 Postgres 类型 Size 定义 (pg_type) 示例用例
ARRAY<FLOAT>、ARRAY<DOUBLE> vector(n) 嵌入维度 PG_SPECIFIC_TYPE_VECTOR 将嵌入存储为vector替代JSONB,准备与lakebase_vector进行相似性搜索
ARRAY<FLOAT>、ARRAY<DOUBLE> halfvec(n) 嵌入维度 PG_SPECIFIC_TYPE_HALFVEC 半精度嵌入,存储空间约为 vector 的一半
STRING varchar(n) 最大长度 PG_SPECIFIC_TYPE_VARCHAR 映射为有长度限制的 varchar,而不是默认的 TEXT

注释

此表中的每种类型都需要 size。 有效的范围有:

  • vector 以及 halfvec:1到16,000,即嵌入维数。
  • varchar:1到10,485,760,最大字符长度。

自定义类型映射可以在创建同步表时配置。 在界面中,在“创建同步表”对话框的架构下使用自定义列类型。 在API、CLI和Databricks SDK中,可以使用 type_overrides。

对于源表 main.docs.chunks(id BIGINT, title STRING, embedding ARRAY<FLOAT>),以下内容在 Postgres 中将 title 映射到 embedding,并将 varchar(256) 映射到 vector(1024):

databricks postgres create-synced-table main.docs.chunks_pg \
  --json '{
    "spec": {
      "source_table_full_name": "main.docs.chunks",
      "branch": "projects/my-project/branches/production",
      "primary_key_columns": ["id"],
      "scheduling_policy": "SNAPSHOT",
      "postgres_database": "mydb",
      "create_database_objects_if_missing": true,
      "type_overrides": [
        { "column_name": "title", "pg_type": "PG_SPECIFIC_TYPE_VARCHAR", "size": 256 },
        { "column_name": "embedding", "pg_type": "PG_SPECIFIC_TYPE_VECTOR", "size": 1024 }
      ]
    }
  }'

如果没有重写,title 将是 TEXT,embedding 将是 JSONB。

处理无效字符

在 Unity Catalog 的 STRING、ARRAY、MAP 或 STRUCT 列中,某些字符(如 null 字节(0x00))是允许的,但在 Postgres 的 TEXT 或 JSONB 列中则不支持。 这可能会导致同步失败,并出现如下错误:

ERROR: invalid byte sequence for encoding "UTF8": 0x00
ERROR: unsupported Unicode escape sequence DETAIL: \u0000 cannot be converted to text
  • 第一个错误发生在顶级字符串列中出现 null 字节时,该列直接映射到 Postgres TEXT。
  • 当嵌套在复杂类型(STRUCT、ARRAY 或 MAP)内部的字符串中出现空字节时,会发生第二个错误,该字符串会被序列化为 JSONB。 在序列化期间,所有字符串都会被转换为 Postgres TEXT 格式,其中 \u0000 是不允许的。

解决方案:

  • 清理字符串字段:在同步之前删除不受支持的字符。 对于“STRING”列中的null字节:

    SELECT REPLACE(column_name, CAST(CHAR(0) AS STRING), '') AS cleaned_column FROM your_table
    
  • 转换为 BINARY:对于需要保留原始字节的 STRING 列,请转换为 BINARY 类型。

容量规划

规划同步表实现时,请考虑以下资源要求:

  • 连接使用情况:每个同步表最多使用16个连接连接到你的Lakebase数据库,这些连接计入项目的连接限制。
  • 大小配额:所有同步表的逻辑数据总数计入分支 数据库存储配额。 如果需要更大的配额,请联系 Databricks 支持部门。 单个表没有配额,但对于需要刷新的表,Databricks 建议不超过 1 TB。
  • 完全刷新大小:触发完全刷新时,在新同步完成之前不会删除 Postgres 中的旧版本。 这两个版本在刷新期间暂时计入逻辑数据库大小配额。
  • 每个源的表数量:单个源表最多可同步到 20 个表。
  • 命名要求:数据库、架构和表名只能包含字母数字字符和下划线([A-Za-z0-9_]+)。
  • 源标识符指南:避免在源 Unity 目录表中的列名或表名中使用大写字母或特殊字符。 如果保留这些标识符,则必须在 Postgres 中引用这些标识符。
  • 架构演变:触发模式和连续模式仅支持累加架构更改(如添加列)。
  • 更改表定义:任何接口(UI、SDK、CLI、REST API、Terraform 或 DAB)都不支持更新同步表的定义。 要更改主键或时间序列键,或进行非加法模式的更改,请删除同步表并创建新表。
  • 重复键:如果两行在源表中具有相同的主键,则同步管道将失败,除非使用 时间顺序键配置重复数据删除。
  • API 幂等性:同步表 API 接口具有幂等性,因此在出现瞬时错误时请重试,以确保操作及时完成。
  • 更新速率:对于Lakebase,同步流水线支持连续和触发写入,每个容量单元(CU)约每秒150行,快照写入速度最高达每秒2000行。

Postgres 中同步表上允许的操作

Azure Databricks建议仅在 Postgres 中为同步表执行以下操作,以防止意外覆盖或数据不一致:

  • 只读查询
  • 创建索引(参见 向同步表添加索引)
  • 删除表(从 Unity Catalog 中删除此同步表以释放空间)

虽然可以通过其他方式修改 Postgres 中的同步表,但它会干扰同步管道。

向同步表添加索引

创建一个带有主键索引的同步表。 要添加其他索引,可以在表格存在后在Postgres中创建。 例如,为了支持对JSONB列的包含查询,比如从VARIANT源列同步的列,可以创建一个GIN索引:

CREATE INDEX orders_payload_gin ON sales.orders USING GIN (payload);

你在同步表上创建的索引在每次同步后仍会保留。 每次满载,包括每次 快照 同步和任何完整刷新,都会重建索引,所以每增加一个索引都会增加同步时间。 在 触发 和 连续 模式下,每个索引也会减缓增量更新。

要创建索引,你必须是同步表的所有者或创建者、databricks_superuser,或被添加为同步表管理员的用户。 参见 “管理同步表操作”。

创建索引时请记住以下几点:

  • 同步表是分区表。 Postgres 不支持在分区表上使用 CREATE INDEX CONCURRENTLY,所以请改用 CREATE INDEX。 CREATE INDEX 会阻止向该表写入,包括来自同步流水线的写入,直到构建完成。 如果构建过程超过20分钟,而同步处于等待状态,则同步会失败且不会自动重试。 查询仍然可以读取该表,除非全量加载正在等待替换为刷新后的数据。 对于大型表,当没有同步运行时创建索引。
  • 从Postgres客户端运行长索引构建。 在大表上建立索引可能需要很长时间。 用客户端(比如 psql )运行构建,而不是用 SQL 编辑器。

注释

如果同步表使用 LTAP 直接写入,则只有 B 树索引才能保留 LTAP 直接写入的后续全量加载。 其他索引类型,如GIN,则使这些加载使用标准同步路径。 初始负载不受影响。

所有权和权限

同步表由内部 databricks_writer_<dbid> 角色(而不是创建该表的用户)拥有,因为同步管道管理它(请参阅 Postgres 角色)。 仅所有者命令(例如配置行级别安全性)不能直接在同步表上运行。

注释

这是对 Postgres 一般规则的一个例外:如果你的 Azure Databricks 身份的登录名在 Postgres 中作为角色存在,则你自己创建的对象归你的 Azure Databricks 身份所有。 该管道会为你创建同步表。

创建同步表的用户的访问权限

创建同步表时,系统会自动向您的 Azure Databricks 身份授予使用该表的权限。 无需 databricks_superuser 执行任何操作。 你的标识在同步表上被授予以下特权:

Object 特权 Purpose
同步表 SELECT、DELETE、TRUNCATE 读取或清除表格
Schema USAGE、CREATE 使用架构并创建索引等对象

你未被授予 INSERT 或 UPDATE。 数据管道拥有该表的数据,因此直接写入的数据会在下次刷新时被覆盖。 DELETE 和 TRUNCATE 只会清除表格。 下一次刷新会从源重新填充表。

此访问权限源自您在该同步表上的 Unity Catalog 权限,并由 Unity Catalog 管理。 若要更改它,请更新用户的 Unity 目录权限。 你不能直接在 Postgres 中从 Azure Databricks 标识 REVOKE 它。

注释

此访问权限与创建该同步表的身份相关联。 更改管道的 运行身份 不会将其重新分配。 若要使用不同的所有者标识,请以该标识重新创建同步表。

管理同步表访问

创建同步表后, databricks_superuser 可以从 Postgres 读取同步表。 databricks_superuser 具有 pg_read_all_data,这使得该角色可以读取所有表。 它还具有 pg_write_all_data 权限,允许此角色写入所有表。 这意味着 databricks_superuser 也可以写入 Postgres 中的同步表。 如果你需要在目标表中进行紧急更改,Lakebase 支持这种写入行为。 但是,Azure Databricks建议改为在源表中进行修复。

  • databricks_superuser 还可以向其他用户授予这些权限。

    GRANT USAGE ON SCHEMA synced_table_schema TO user;
    
    GRANT SELECT ON synced_table_name TO user;
    
  • databricks_superuser 可以撤销这些特权:

    REVOKE USAGE ON SCHEMA synced_table_schema FROM user;
    
    REVOKE {SELECT | INSERT | UPDATE | DELETE} ON synced_table_name FROM user;
    

管理同步表操作

databricks_superuser 可以管理哪些用户有权对同步表执行特定操作。 同步表支持的操作包括:

  • CREATE INDEX
  • ALTER INDEX
  • DROP INDEX
  • DROP TABLE

已同步表的所有其他 DDL 操作都被拒绝。

若要向其他用户授予这些权限, databricks_superuser 必须先创建 databricks_auth以下扩展:

CREATE EXTENSION IF NOT EXISTS databricks_auth;

然后, databricks_superuser 可以添加用户来管理同步表:

SELECT databricks_synced_table_add_manager('"synced_table_schema"."synced_table"'::regclass, '[user]');

databricks_superuser 可以将用户从同步表的管理中删除。

SELECT databricks_synced_table_remove_manager('[table]', '[user]');

databricks_superuser 可以查看所有管理员:

SELECT * FROM databricks_synced_table_managers;

删除同步表

从 Unity 目录中删除同步表也会删除相应的 Postgres 表。

UI

在 “目录”中,找到已同步的表,单击 “Kebab”菜单图标。 菜单,然后选择“ 删除”。

Python SDK

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()

w.postgres.delete_synced_table("synced_tables/my-catalog.sales.orders").wait()

Java SDK

import com.databricks.sdk.WorkspaceClient;

WorkspaceClient w = new WorkspaceClient();

w.postgres().deleteSyncedTable("synced_tables/my-catalog.sales.orders").waitForCompletion();

curl

curl -X DELETE "https://your-workspace.cloud.databricks.com/api/2.0/postgres/synced_tables/my-catalog.sales.orders" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}"

目录集成

同步表可以在 Unity Catalog 的多个目录/catalog 中出现。 当你在标准目录中创建同步表,且其目标 Postgres 数据库也注册为数据库目录时,这种目录重复是预期的。 在这种情况下,同步表会出现在两个目录下。

同步到 Azure Databricks 外部的系统

若要将数据同步到非 Databricks 系统,请参阅 Partner Connect 反向 ETL 解决方案 ,例如人口普查或 Hightouch。

其他资源