包 io.delta.kernel

接口 TransactionBuilder

@Evolving public interface TransactionBuilder
用于创建 Transaction 以修改 Delta 表的构建器。
自
3.2.0

  • 方法详情

    • withSchema

      TransactionBuilder withSchema(Engine engine, StructType schema)
      设置表的模式。如果为模式演进在现有表上设置模式，则必须启用列映射。此 API 将保留字段元数据，例如字段 ID 和物理名称。如果未为字段指定字段元数据，则将其视为新列，并将指定新的 ID/物理名称。支持的可能模式演进包括列添加、删除、重命名和移动。如果执行模式演进，则实现必须执行以下验证
      • 不允许重复列
      • 列名仅包含有效字符
      • 支持数据类型
      • 未添加新的非空字段
      • 在新模式中保留物理列名的一致性
      • 无类型更改
      • 待办：在新模式中保留数组/映射类型的嵌套 ID
      • 待办：验证无效的字段重新排序
      参数
      engine - 要使用的 Engine 实例。
      schema - 表的新模式。
      返回
      更新后的 TransactionBuilder 实例。
      抛出
      KernelException - 如果未启用列映射
      IllegalArgumentException - 如果任何验证失败

    • withPartitionColumns

      TransactionBuilder withPartitionColumns(Engine engine, List<String> partitionColumns)
      创建新的分区表时，设置分区列的列表。
      参数
      engine - 要使用的 Engine 实例。
      partitionColumns - 表的分区列。这些应该是模式中列的子集。只允许顶级列进行分区。注意：集群列和分区列不能在同一张表中同时存在。
      返回
      更新后的 TransactionBuilder 实例。

    • withClusteringColumns

      TransactionBuilder withClusteringColumns(Engine engine, List<Column> clusteringColumns)
      创建新的集群表时，设置集群列的列表。
      参数
      engine - 要使用的 Engine 实例。
      clusteringColumns - 表的集群列。这些应该是模式中列的子集。允许对顶级列和嵌套列进行集群。注意：集群列和分区列不能在同一张表中同时存在。
      返回
      更新后的 TransactionBuilder 实例。

    • withTransactionId

      TransactionBuilder withTransactionId(Engine engine, String applicationId, long transactionVersion)
      为幂等写入设置事务标识符。增量处理系统（例如，流系统）使用自己的特定于应用程序的版本跟踪进度，需要记录已取得的进度，以避免在写入过程中出现故障和重试时重复数据。通过设置事务标识符，Delta 表可以确保具有相同标识符的数据不会被多次写入。有关更多信息，请参阅 Delta 协议部分事务标识符。
      参数
      engine - 要使用的 Engine 实例。
      applicationId - 写入表的应用程序 ID。
      transactionVersion - 事务的版本。对于相同的应用程序 ID，此值应随着每次写入而单调递增。
      返回
      更新后的 TransactionBuilder 实例。

    • withTableProperties

      TransactionBuilder withTableProperties(Engine engine, Map<String,String> properties)
      设置表的表属性。当表已包含具有相同键的属性时，如果其值不同，则会替换它。请注意，用户属性（不带“.delta”前缀的属性）区分大小写。Delta 属性不区分大小写，并在写入日志之前将其规范化为预期的大小写。
      参数
      engine - 要使用的 Engine 实例。
      properties - 要设置的表属性。这些是可用于配置表的键值对。这些属性存储在表元数据中。
      返回
      更新后的 TransactionBuilder 实例。
      自
      3.3.0

    • withTablePropertiesRemoved

      TransactionBuilder withTablePropertiesRemoved(Set<String> propertyKeys)
      取消设置表中提供的表属性。如果属性不存在，则此操作为空操作。目前，此功能仅支持用户属性（换句话说，不支持带有“delta.”前缀的属性）。如果在同一事务中同时设置和取消设置同一个键，则在调用build(Engine)时将抛出异常。请注意，用户属性（不带“.delta”前缀的属性）区分大小写。
      参数
      propertyKeys - 要取消设置的表属性键（从表属性中移除）
      返回
      更新后的 TransactionBuilder 实例。
      抛出
      IllegalArgumentException - 如果提供了“delta.”前缀的键

    • withMaxRetries

      TransactionBuilder withMaxRetries(int maxRetries)
      设置在检测到并发写入时重试事务的最大次数。默认为 200
      参数
      maxRetries - 重试次数
      返回
      更新后的 TransactionBuilder 实例

    • withLogCompactionInverval

      TransactionBuilder withLogCompactionInverval(int logCompactionInterval)
      设置日志压缩之间的提交次数。默认为 0（禁用）。有关更多信息，请参阅 Delta 协议部分日志压缩文件。
      参数
      logCompactionInterval - 日志压缩之间的提交次数
      返回
      更新后的 TransactionBuilder 实例

    • withDomainMetadataSupported

      TransactionBuilder withDomainMetadataSupported()
      如果该表尚未支持域元数据，则启用其支持。该表特性_必须_在表上受支持才能使用Transaction.addDomainMetadata(java.lang.String, java.lang.String)或Transaction.removeDomainMetadata(java.lang.String)添加或删除域元数据。有关表特性支持的更多详细信息，请参阅Delta Lake 如何管理特性兼容性？。

      有关如何使用域元数据的更多信息，请参阅 Delta 协议。这可能会破坏不支持域元数据特性的现有写入器；读取器将不受影响。

    • build

      Transaction build(Engine engine)
      构建事务。还会验证给定信息，以确保可以创建有效的事务。
      参数
      engine - 要使用的 Engine 实例。
      抛出
      ConcurrentTransactionException - 如果表已具有具有相同给定事务标识符的已提交事务。
      InvalidConfigurationValueException - 如果属性值无效。
      UnknownConfigurationException - 如果任何属性是TableConfig未知的。
      DomainDoesNotExistException - 如果删除最新版本的表中不存在的域
      TableAlreadyExistsException - 如果在调用Table.createTransactionBuilder(Engine, String, Operation)时提供的操作是 CREATE_TABLE 并且表已存在