设置数据流

流是一种外部流式数据源,例如 Apache Kafka。 流存储连接详细信息、身份验证、架构和引入配置。 创建流后,可以使用 功能视图 定义来引用它,以创建实时流式处理功能。

流具有三部分名称(catalog.schema.stream_name)。 对流的访问权限由其关联的引入表决定。 详情请参见 “摄入与回填 ”。

要求

  • 对于运行笔记本命令:无服务器或运行 Databricks Runtime 17.0 ML 或更高版本的经典计算群集。
  • 必须安装 feature-engineering-client Python 包 0.18.0 或更高版本。

连接到流源

在定义流式特征之前,连接并测试流式 Lakeflow 管道到你的 Kafka 代理的连接。 功能商店依赖于无服务器SDP,这意味着你需要一个机制将经典计算(代理或终端)连接到Databricks的无服务器计算。 这可以通过privatelink等产品实现,或者允许你的经典计算系统从公共互联网访问。

创建流

用于 create_stream() 创建新的流。 流需要四个配置组件:

  • 源代码配置:指定流媒体平台及特定来源细节,例如Kafka源的主题订阅。
  • 连接配置:指定如何连接到流平台并进行身份验证,包括引导服务器和凭据。
  • 架构配置:定义消息键和值的结构。
  • 引入配置:指定流数据引入的位置和方式。 详情请参见 “摄入与回填 ”。

有关特定于源的 source_config 和连接设置,以及完整的 create_stream() 示例,请参见 Apache Kafka。 模式和摄取选项在多个来源之间共享。

阿帕奇·卡夫卡

要从 Apache Kafka 进行流式传输,请使用 KafkaStreamConfig 作为源配置,并使用 Unity Catalog 连接进行身份验证。 有关 Kafka 连接,请参阅 在无服务器计算上流式传输和连接到 Apache Kafka。

from databricks.feature_engineering import FeatureEngineeringClient
from databricks.feature_engineering.entities import (
    KafkaStreamConfig,
    KafkaSubscriptionMode,
    StreamConnectionConfig,
    DirectSchemas,
    SchemaConfig,
    IngestionConfig,
    IngestionDestination,
    StreamBackfillSource,
)

client = FeatureEngineeringClient()

stream = client.create_stream(
    name="my_catalog.my_schema.my_stream",
    source_config=KafkaStreamConfig(
        subscription_mode=KafkaSubscriptionMode(subscribe="events-topic"),
    ),
    connection_config=StreamConnectionConfig(
        uc_connection_name="my-kafka-connection"
    ),
    schema_config=DirectSchemas(
        payload_schema=SchemaConfig(
            json_schema=(
                '{'
                '  "type": "object",'
                '  "properties": {'
                '    "transaction_id": {"type": "string"},'
                '    "user_id": {"type": "string"},'
                '    "amount": {"type": "number"},'
                '    "event_time": {"type": "string", "format": "date-time"}'
                '  }'
                '}'
            )
        ),
    ),
    ingestion_config=IngestionConfig(
        ingestion_destination=IngestionDestination(
            delta_table_name="my_catalog.my_schema.events_ingestion"
        ),
    ),
)

卡夫卡订阅模式

订阅模式指定了流如何选择要使用的 Kafka 主题。 支持三种模式:

模式 Description 示例:
subscribe 以逗号分隔的主题名称列表 KafkaSubscriptionMode(subscribe="topic1,topic2")
subscribe_pattern Java正则表达式模式匹配主题名称 KafkaSubscriptionMode(subscribe_pattern="events-.*")
assign 用于指定主题-分区分配的 JSON KafkaSubscriptionMode(assign='{"my-topic": [0, 1, 2]}')

卡夫卡认证

使用 Unity 目录连接对 Kafka 群集进行身份验证。 这是用于托管身份验证的推荐方法。 若要创建连接,请参阅 “创建连接”。 流的创建者必须对该连接具有 USE CONNECTION。 任何使用流作为来源具体化功能的用户,还必须对该连接上具有 USE CONNECTION。

connection_config = StreamConnectionConfig(
    uc_connection_name="my-kafka-connection"
)

该连接支持IAM(服务凭证)和SASL认证。

IAM(服务凭证)

使用 Unity Catalog 服务凭据进行身份验证,例如使用 IAM 连接到 Amazon MSK。 若要创建服务凭据,请参阅 “创建服务凭据”。 使用 credential 选项设置服务凭证名称:

CREATE CONNECTION IF NOT EXISTS `my-kafka-connection`
TYPE KAFKA
OPTIONS (
    bootstrap_servers '<bootstrap_servers>',
    credential '<service_credential>'
)

除了连接上的 USE CONNECTION 之外,使用服务凭据的身份还需要在该连接上具有 ACCESS。 向流的创建者以及所有通过流具体化特征的标识,授予对引用服务凭据的 ACCESS 权限。 请参阅 授予使用服务凭据访问外部云服务的权限。

SASL

SASL 认证使用用户名和密码。 将 sasl_mechanism 设置为以下选项之一:

  • PLAIN
  • SCRAM-SHA-256
  • SCRAM-SHA-512

使用 user 和 password 选项提供凭证。 连接会安全地存储这些凭证。

以下示例使用 SASL/SCRAM。 对于 SASL/PLAIN,将 sasl_mechanism 设置为 PLAIN。

CREATE CONNECTION IF NOT EXISTS `my-kafka-connection`
TYPE KAFKA
OPTIONS (
    bootstrap_servers '<bootstrap_servers>',
    sasl_mechanism 'SCRAM-SHA-512',
    user '<username>',
    password '<password>'
)

直接 mTLS

对于直接 mTLS 身份验证,请提供存储在 Unity Catalog 卷上的密钥存储和信任存储文件,并通过 Databricks 机密范围引用密码。 有关使用 Kafka 进行 SSL 身份验证的详细信息,请参阅使用 SSL 将Azure Databricks连接到 Kafka。

from databricks.feature_engineering.entities import (
    DirectMtlsConfig,
    MtlsConfig,
    SecretScopeReference,
)

connection_config = DirectMtlsConfig(
    bootstrap_servers="broker1:9092,broker2:9092",
    mtls_config=MtlsConfig(
        keystore_location="/Volumes/my_catalog/my_schema/my_volume/keystore.jks",
        keystore_password_ref=SecretScopeReference(
            scope="my_scope", key="keystore_password"
        ),
        key_password_ref=SecretScopeReference(
            scope="my_scope", key="key_password"
        ),
        truststore_location="/Volumes/my_catalog/my_schema/my_volume/truststore.jks",
        truststore_password_ref=SecretScopeReference(
            scope="my_scope", key="truststore_password"
        ),
    ),
)

架构配置

定义消息键和值的结构,使摄取和特征定义能够读取单个字段。 对于 Kafka 源,payload_schema 对应于 Kafka 消息值(即 Kafka 键值模型中的 value),而 key_schema 对应于 Kafka 消息键。 必须至少提供 payload_schema 或 key_schema 其中之一。

每种 SchemaConfig 格式接受三种格式之一,匹配源的串行信息方式: json_schema、、 avro_schema或 proto_schema。 如果没有为密钥或有效负载提供架构,则它被视为一个简单的字符串。

本节的代码示例使用了与 DirectSchemas内联声明的模式,其中模式以字符串形式提供。 如需使用外部模式注册表管理模式,请参见 “模式注册表 ”详细说明。

JSON 架构

向json_schema提供一个JSON Schema字符串。

schema_config = DirectSchemas(
    payload_schema=SchemaConfig(
        json_schema=(
            '{'
            '  "type": "object",'
            '  "properties": {'
            '    "user_id": {"type": "string"},'
            '    "amount": {"type": "number"},'
            '    "event_time": {"type": "string"}'
            '  }'
            '}'
        )
    ),
    key_schema=SchemaConfig(
        json_schema='{"type": "string"}'
    ),
)

Avro 架构

为 avro_schema 提供一个 Avro 架构字符串。 支持Avro逻辑类型,包括timestamp-millis、和datedecimal。

schema_config = DirectSchemas(
    payload_schema=SchemaConfig(
        avro_schema=(
            '{'
            '  "type": "record",'
            '  "name": "Event",'
            '  "fields": ['
            '    {"name": "user_id", "type": "string"},'
            '    {"name": "amount", "type": "double"},'
            '    {"name": "event_time",'
            '     "type": {"type": "long", "logicalType": "timestamp-millis"}}'
            '  ]'
            '}'
        )
    ),
)

Protobuf 架构

提供 ProtoSchemaSpec 到 proto_schema,其中包含协议缓冲区.proto源文本和有效负载消息名称。 从 ProtoSchemaSpec 导入 databricks.feature_engineering.entities。

message_name 必须是完全限定消息名称,包括在 .proto 文本中声明的 package(例如,com.example.Event,而不是 Event)。 支持proto2和proto3语法。

google.protobuf.Timestamp 以及标量包装器类型(如 StringValue、Int32Value 等)均受支持,且其导入会被自动解析。 其他常见类型,如 Duration、 Struct和 Any,则被拒绝;将这些值编码为支持的标量或消息。 fixed32 fixed64标量类型和map非字符串键也不被支持。

from databricks.feature_engineering.entities import ProtoSchemaSpec

schema_config = DirectSchemas(
    payload_schema=SchemaConfig(
        proto_schema=ProtoSchemaSpec(
            schema_text=(
                'syntax = "proto3";\n'
                'package com.example;\n'
                'import "google/protobuf/timestamp.proto";\n'
                'message Event {\n'
                '  string user_id = 1;\n'
                '  double amount = 2;\n'
                '  google.protobuf.Timestamp event_time = 3;\n'
                '}'
            ),
            message_name="com.example.Event",
        )
    ),
)

使用模式解码数据

Databricks 用 Spark from_json的 、 from_avro和 from_protobuf 函数对每个消息进行解码。 无论是以内联方式声明架构,还是从架构注册表中解析架构,以下行为均适用:

  • 格式错误的记录。 解码使用模式 PERMISSIVE ,即与模式不匹配的记录会解码为空值,而不是导致流失败。
  • Avro工会。 多个记录类型的并集解码为一个结构体,每个记录类型只有一个字段,每个字段以其 Avro 记录命名。
  • Protobuf类型。 无符号整数会解码为更宽的有符号类型(例如,uint32 到 BIGINT,以及 uint64 到 DECIMAL(20,0)),枚举字段会解码为其字符串名称,而标量包装类型(例如 StringValue 和 Int32Value)会解码为所包装类型的可空列。

架构注册表

模式注册库存储流媒体生产者和消费者使用的版本模式,随着模式演变,强制执行兼容性规则。 当配置外部模式注册表时,功能库会读取该模式并用它来解码流式消息。 使用模式注册表时,无需在 Stream 上内联声明该模式。

模式注册表支持存在以下限制:

  • 仅支持 Kafka Streams。
  • 仅支持 Confluent Schema Registry
  • 仅支持 Avro 和 Protobuf 格式。 要读取 JSON 消息,可以直接声明 schema inline。 参见 JSON 模式。
  • 每个流都恰好连接到一个用于存放消息值的 Confluent 主题,以及一个用于存放消息键的主题(如果提供了消息键)。 包含多个模式记录的流主题不支持配置。 如果你的流连接的主题包含多个模式,不匹配该主题模式的记录会 被解码为空。

连接到模式注册表

在 Kafka Unity Catalog 连接上以选项形式提供注册表连接详细信息,并将注册表 API 机密存储在 Azure Databricks 机密范围中。 Stream 的运行身份必须对机密范围具有 READ 权限,因为摄取管道会在运行时读取该机密。 关于如何创建和配置连接,请参见 创建连接。

在用于认证的连接中添加 schema_registry_url、 schema_registry_api_key和 schema_registry_api_secret 选项。 以下示例创建了一个 Kafka 连接,该连接通过 Unity Catalog 服务凭证向代理认证,并通过 API 密钥向注册表进行认证:

CREATE CONNECTION IF NOT EXISTS `my-kafka-connection`
TYPE KAFKA
OPTIONS (
    bootstrap_servers '<bootstrap_servers>',
    credential '<service_credential>',
    schema_registry_url 'https://<registry-host>',
    schema_registry_api_key '<registry_api_key>',
    schema_registry_api_secret secret('<scope>', '<key>')
)

将 Kafka 连接上的 选项和 Stream 上的 schema_registry_api_secret 引用都设置为同一个机密。

创建使用架构注册表的流

将a SchemaRegistryConfig 传递为 schema_config。 使用 api_secret_ref 引用注册表 API 密钥,并对消息值使用 payload_schema_locator 标识主题和格式,或对消息键使用 key_schema_locator。 至少必须提供一个定位器。

请注意这里与 模式配置 部分中直接模式示例的区别。 使用架构注册表时,你无需在 Streamschema_config中内联提供架构。 相反,你指定一个 SchemaRegistryConfig 来识别注册表中的模式。

from databricks.feature_engineering import FeatureEngineeringClient
from databricks.feature_engineering.entities import (
    KafkaStreamConfig,
    KafkaSubscriptionMode,
    StreamConnectionConfig,
    SchemaRegistryConfig,
    SchemaLocator,
    SchemaLocatorConfluentSchema,
    SchemaLocatorFormat,
    SecretScopeReference,
    IngestionConfig,
    IngestionDestination,
)

client = FeatureEngineeringClient()

stream = client.create_stream(
    name="my_catalog.my_schema.my_stream",
    source_config=KafkaStreamConfig(
        subscription_mode=KafkaSubscriptionMode(subscribe="transactions"),
    ),
    connection_config=StreamConnectionConfig(
        uc_connection_name="my-kafka-connection"
    ),
    schema_config=SchemaRegistryConfig(
        api_secret_ref=SecretScopeReference(
            scope="my_scope", key="sr_api_secret"
        ),
        payload_schema_locator=SchemaLocator(
            confluent_schema=SchemaLocatorConfluentSchema(
                subject="transactions-value"
            ),
            format=SchemaLocatorFormat.FORMAT_AVRO,
        ),
    ),
    ingestion_config=IngestionConfig(
        ingestion_destination=IngestionDestination(
            delta_table_name="my_catalog.my_schema.transactions_ingestion"
        ),
    ),
)

Confluent subject 是一个命名作用域,schema 的版本历史在该作用域下注册,并在此强制执行兼容性检查。 将 subject 设置为相关作用域的名称,该名称通常由 主题名称策略确定:

  • TopicNameStrategy(默认,从主题名称派生主题):<topic>-value 用于值,<topic>-key 用于键。 例如,主题 transactions 的值模式使用主语 transactions-value。
  • RecordNameStrategy (从模式的记录名称衍生主体,独立于主题):完全限定的记录名称,例如 com.example.Payment。 对于 Avro,这是记录的命名空间和名称;对于 Protobuf,这是消息的包和名称。
  • TopicRecordNameStrategy (结合主题名和记录名): <topic>-<fully-qualified-record-name>,例如 transactions-com.example.Payment。

format 必需。 将其设置为 SchemaLocatorFormat.FORMAT_AVRO 或 SchemaLocatorFormat.FORMAT_PROTOBUF,以匹配主题的序列化方式。

架构演变

摄取管道在启动时会解析该主题的当前架构。 当你在模式注册表中注册一个向后兼容的新模式版本时,运行中的流水线仍会继续使用最初的版本。

对于由架构注册表支持的 Stream,引入管道每隔几小时会自动重启。 每次重启时,它会采用主题的最新架构版本,新字段或已更改的字段会出现在引入表中。

使用直接架构而非架构注册表的 Stream 使用 update_stream 演变其架构。 请参阅 更新 Stream。

关于流水线如何处理与当前模式不匹配的记录,请参见 “利用模式解码数据”。

按类型筛选记录

无论你是直接指定架构还是使用架构注册表,Stream 都使用单个键架构和值架构(如果提供)解码每条记录。 由于一个主题可以包含多种类型的记录,且 Stream 可以订阅多个主题,因此请使用 record_type_filter 选择该主题中哪些记录属于此 Stream。

提供一个使用点表示法引用已解码字段的 SQL 表达式,例如 value.event_type = 'transaction'。 不符合筛选条件的记录将被忽略。 它们不会写入引入表,也不会用于物化。 若要为其他记录类型创建 Stream,请使用不同的 record_type_filter 创建单独的 Stream。

stream = client.create_stream(
    name="my_catalog.my_schema.my_stream",
    # ...source, connection, schema, and ingestion config...
    record_type_filter="value.event_type = 'transaction'",
)

即使没有 record_type_filter,解码也不会导致 Stream 失败。 与配置的架构不匹配的记录会被宽松解码。 记录以下列方式之一解码:

  • 解码为一行,对于架构预期但记录省略的字段使用 NULL 值(JSON、Avro 和 Protobuf)。
  • 解码为一行,其中包含属于其他记录类型的值(仅 Avro 和 Protobuf)。

若要确定引入表中的行是否属于预期的记录类型,请使用以下检查之一:

  • 检查某个字段是否等于预期值,例如 value.event_type = 'transaction'(Avro 和 Protobuf 首选)。
  • 检查某个字段是否为非 NULL,例如 value.activity_id IS NOT NULL。

当该主题中不同记录类型之间的模式差异很大,或者你希望独立控制对每种记录类型的访问权限时,建议将 record_type_filter 与独立的 Streams 配合使用。 为控制成本,Databricks 建议你保留少量 Stream,因为每个 Stream 都有单独的引入管道和引入表。 每个 Stream 在物化时还使用单独的计算资源。 可以使用特征专用的筛选器进行物化。

record_type_filter 不同于特征的 filter_condition。 record_type_filter 在 Stream 上设置,控制哪些记录被引入并提供给使用该 Stream 作为源的所有特征;而 filter_condition 在单个特征上设置,在聚合之前筛选行。 有关 filter_condition 的更多详细信息,请参阅 流式处理源上的筛选条件。

吞食与回填

该 ingestion_config 参数配置如何捕获和存储流数据以供训练和服务。

对流的访问受引入表控制:

  • 对引入表的 SELECT 权限将授予对流的读取访问权限。
  • 对引入表的 MANAGE 权限将授予删除访问权限。

有关表权限的更多信息,请参阅 表 和 Unity Catalog 权限参考。

摄取管道

当流被创建时,Databricks 会启动一个受管理的导入流水线,持续从源流读取消息并将其写入 Delta 表(即摄取表)。 流水线从源头的最新位置开始,持续运行,只捕获流创建后到达的新消息。 此引入表用于使用流式处理特征进行训练。 删除流后,也会删除其引入管道和引入表。

摄取目标

ingestion_destination 指定用于写入流数据的三部分 Delta 表名称。

ingestion_config = IngestionConfig(
    ingestion_destination=IngestionDestination(
        delta_table_name="my_catalog.my_schema.events_ingestion"
    ),
)

数据引入表架构

摄取表包含消息数据和元数据列。 每个数据源都存在通用列;kafka_* 列仅存在于 Kafka 流中。

列 类型 Source Description
key 各不相同(从 key_schema 起) Common 消息密钥,按照你提供的模式结构化。
value 各不相同(从 payload_schema 起) Common 消息值(负载),按你提供的架构进行结构化。
stream_record_timestamp TIMESTAMP Common 记录的时间戳。 对于前向填充数据,这是源导入时间戳。 回填数据由客户提供。
record_source STRING Common 要么是 "stream"(从实时流向前填充),要么是 "backfill"(来自回填源)。
kafka_topic STRING Kafka 作为所用记录来源的 Kafka 主题。
kafka_partition INT Kafka 作为所用记录来源的 Kafka 分区。
kafka_offset LONG Kafka 记录在其所属分区中的 Kafka 偏移量。

回填源

由于前向填充流水线从源中的最新位置开始,因此无法捕获在流创建之前就已存在的消息。 若要为训练提供历史数据覆盖范围,请配置可选的回填源。

配置回填源后,Databricks 会运行一次性 MERGE INTO 作业,该作业使用 record_source="backfill" 将回填行复制到引入表中。 MERGE 仅在重叠检查器确认回填源和前填充流具有重叠时间戳之后才会运行(请参阅 回填和实时流数据之间的重叠)。 如果在 2 天内未满足重叠条件,则 MERGE 仍会运行以避免无限期阻塞。

回填表必须包含一个名为 stream_record_timestamp、类型为 TIMESTAMP 且采用 UTC 时区的列。 如果回填源中存在其他元数据列,则原样传递;否则将其设为 NULL。 对于卡夫卡,这些分别是 kafka_topic、 kafka_partition和 kafka_offset。

from databricks.feature_engineering.entities import StreamBackfillSource

ingestion_config = IngestionConfig(
    ingestion_destination=IngestionDestination(
        delta_table_name="my_catalog.my_schema.events_ingestion"
    ),
    backfill_source=StreamBackfillSource(
        delta_table_name="my_catalog.my_schema.historical_events"
    ),
)

回填和实时流数据之间的重叠

在回填表和引入表之间运行 MERGE 之前,会先进行重叠检查,比较这两个表中的时间戳:

  • 回填最大值:回填源中的最大值 stream_record_timestamp 。
  • 引入最小值:引入表中的最小 stream_record_timestamp 行数(record_source="stream")。

只有回填的最新时间戳至少比引入表中最早的时间戳晚 1 小时,MERGE 才会继续执行。 这种重叠机制可确保引入表中没有间隙。 如果在 2 天内未满足重叠条件,则 MERGE 仍会运行以避免无限期阻塞。

由于摄取流水线从源中的最新位置开始,因此它只能捕获在流创建之后到达的消息。 回填源必须包含延伸到引入时间范围内的数据,而不只是到流创建时间为止。

例如,如果你在下午 3:00 创建流,则前向填充管道会从下午 3:00 起开始读取消息。 回填源必须包含时间戳截至至少下午4:00的数据(即比前向填充开始时间晚1小时),才能通过重叠检查。 这意味着你应在下午4:00之后更新回填表,以确保摄取表不会出现空档。

重复数据删除

使用 deduplication_columns 指定列路径,以便在引入过程中识别回填数据与向前填充流数据之间的重复行。 对嵌套字段使用点表示法(例如 "value.user_id")。

根据您的数据选择去重列:

  • 如果流中的每个记录都包含唯一标识符(例如), value.transaction_id请使用该列进行重复数据删除。
  • 如果回填源包含 kafka_partition 和 kafka_offset 列,请使用这些列来唯一标识每条记录。
  • 如果未指定去重列,则默认去重键为 key、value 和 stream_record_timestamp 的完整组合。 不建议这样做,因为这种严格的条件匹配很容易导致重复项。
ingestion_config = IngestionConfig(
    ingestion_destination=IngestionDestination(
        delta_table_name="my_catalog.my_schema.events_ingestion"
    ),
    deduplication_columns=["value.transaction_id"],
)

成本归因

在 IngestionConfig 上设置 tags 和 budget_policy_id,以标明 Stream 托管引入成本的归属。 Azure Databricks 会在创建 Stream 时,将这些设置应用于摄取 Lakeflow 管道及其向前填充和回填作业。

例如,标签限制以及如何查询带属性的支出,请参见 “带有标签和无服务器使用策略的属性成本”。

从 Stream 中排除列

使用 excluded_columns 从 Stream 中删除你不想引入的特定列。 被排除的列不会写入引入表,也不能被特征引用或在训练中使用。

使用点表示法指定消息键或值中的每一列,例如 value.user.email 或 key.account_id。 这些列在引入、回填和物化过程中从已解码的 key 和 value 中删除。 如果某个路径指向一个结构,其所有嵌套字段也会被删除(例如,value.address 还会删除 value.address.city 和 value.address.zip)。

stream = client.create_stream(
    name="my_catalog.my_schema.my_stream",
    # ...source, connection, schema, and ingestion config...
    excluded_columns=["value.user.email", "value.user.ssn"],
)

使用直接架构时,被排除的列必须已存在于键或值架构中,否则 create_stream 会失败。 使用架构注册表时,你可以在某个列存在之前排除它。 排除列也不能是去重列,因为去重列必须用于识别重复行。 引用被排除列的任何特征(例如将该列用作实体、时序或输入)都无法创建。

你可以在创建后使用 update_stream 更改 Stream 的排除列,使用直接架构和由架构注册表支持的 Stream 均可。 有关更多详细信息,请参阅 更新 Stream。

管理流

获取流

stream = client.get_stream(name="my_catalog.my_schema.my_stream")

列出流

streams = client.list_streams(
    catalog_name="my_catalog",
    schema_name="my_schema",
    max_results=50,
    include_schemas=False,
)

将 include_schemas=True 设置为包含完整的架构模式详情。 架构可能很庞大,因而导致操作长时间运行。 若要单独检索架构,请使用 get_stream。

更新 Stream

使用 update_stream 在创建后更改 Stream。 传递 schema_config 以演变直接架构,传递 excluded_columns 以更改要删除的列,或同时传递两者。 不支持更新其他字段。 改为创建新的 Stream。

更新 Stream 会重启其引入管道,以使更改生效。 引入通常会在几分钟内恢复。

演变直接架构

对于使用直接架构的 Stream,将 DirectSchemas 传递给 schema_config。 设置 payload_schema、key_schema 或同时设置两者。 未设置的一侧保持不变。 由架构注册表支持的 Stream 拒绝 schema_config 更新,必须改为通过注册表演变。

from databricks.feature_engineering.entities import DirectSchemas, SchemaConfig

stream = client.update_stream(
    name="my_catalog.my_schema.my_stream",
    schema_config=DirectSchemas(
        payload_schema=SchemaConfig(
            json_schema=(
                '{'
                '  "type": "object",'
                '  "properties": {'
                '    "user_id": {"type": "string"},'
                '    "amount": {"type": "number"},'
                '    "event_time": {"type": "string"},'
                '    "channel": {"type": "string"}'
                '  }'
                '}'
            )
        ),
    ),
)

模式更新必须向后兼容,以便正在运行的导入流水线能够持续解码现有记录并写入摄取表。 任何其他更改都会被拒绝。

允许的操作取决于格式:

  • JSON 和 Protobuf:添加可选字段、删除字段以及加宽字段类型(例如从 int 到 bigint)。 Protobuf 还允许重新排序字段。
  • Avro:仅允许将 int 加宽为 long,以及删除没有后续字段读取其字节的尾部字段。 若要更自由地演变 Avro 架构,请改用由架构注册表支持的 Stream。

添加字段会扩展引入表中已解码的 key 和 value 结构。 更新之前写入的行保持其原始结构,对于这些较早的行,新增字段的读取结果为 NULL。 移除和类型更改仅对更新后被摄取的记录生效。

更改排除列

将完整的新列路径集传递给 excluded_columns,这会替换现有集。 传递空列表([])以清除所有排除。 有关此行为的详细信息,请参阅 从 Stream 中排除列。

stream = client.update_stream(
    name="my_catalog.my_schema.my_stream",
    excluded_columns=["value.user.email", "value.user.ssn"],
)

更改排除列仅对后续数据生效。 新排除的列将停止写入(显示为 NULL),新包含的列将开始填充后续数据,而之前写入的行保持原样。 若要确保新列始终不会被引入:

  • 架构注册表:先将该列添加到 excluded_columns,等待引入管道重启,然后在注册表中注册新的架构版本。
  • 直接架构:在同一个 update_stream 调用中将该列添加到 schema_config 和 excluded_columns。

删除流

删除流也会删除其引入管道和引入表。

Warning

引用已删除流的任何模型或功能将不再有权访问基础流数据。 如果需要此数据,但不再需要流,请在删除之前创建引入表的副本。

client.delete_stream(name="my_catalog.my_schema.my_stream")

示例笔记本

有关创建流、定义流功能并部署到服务终结点的端到端示例,请参阅以下笔记本:

流式处理特征视图快速入门笔记本

获取笔记本