RowBinaryWithNamesAndTypesAndDefaults

RowBinaryWithNamesAndTypesAndDefaults 格式文档

输入	输出	别名
✔	✗

​

说明

与 RowBinaryWithNamesAndTypes 格式类似，但在每个单元前会额外增加一个字节，用于指示是否应使用该列的 DEFAULT 值——这与 RowBinaryWithDefaults 格式中的行为完全一致。这种组合支持 schema 演进中的 INSERT：写入端可以在请求头中省略某些列 (这些列将使用目标列的 DEFAULT) ，并且对于它实际发送的任意列，还可以将单个单元标记为“使用该列的 DEFAULT”，而不会与 NULL 混淆。

此格式仅用于输入。

​

传输格式

请求头与 RowBinaryWithNamesAndTypes 完全相同：

1. 一个表示列数 N 的 VarUInt。
2. N 个带长度前缀的列名 String。
3. N 个列类型——可以是文本名称，也可以是紧凑的二进制编码，具体由 output_format_binary_encode_types_in_binary_format / input_format_binary_decode_types_in_binary_format 设置控制。

在请求头之后，每一行由 N 个单元组成。对于每个单元：

• 一个 UInt8 标记字节。
  • 0x01 — 使用目标列的 DEFAULT 表达式，后面不跟任何值字节。
  • 0x00 — 后面跟一个值，并通过该列类型的 RowBinary 序列化器进行序列化。对于 Nullable(T)，值字节以 Nullable 的 NULL 字节开头 (非空时为 0，NULL 时为 1) ；如果非空，后面再跟内部值。

​

默认值与 NULL

每个单元的默认值标记与 Nullable 内置的 null byte 是彼此独立的。Nullable(UInt32) DEFAULT 42 列在每一行中可以通过三种不同的方式发送：

字节	含义
01	使用 DEFAULT 42。
00 01	走值路径，然后通过 Nullable 类型表示 NULL。
00 00 …	走值路径，然后是一个非 NULL 的内部值。

​

schema 演进

情况	行为
列在文件请求头中完全缺失	通过 insertDefaultsForNotSeenColumns 在目标端补齐；受 defaults_for_omitted_fields 控制。
列存在于文件请求头中，单元标记为 0x01	对每一行执行 insertDefault。
列存在于文件请求头中，单元标记为 0x00	正常解析该值。
文件请求头中存在额外的列，但目标表中不存在	当 input_format_skip_unknown_fields = 1 时会静默丢弃 (会先读取该标记；如果是 0x01，则不做其他处理；如果是 0x00，则会解析类型化的值并将其丢弃) 。

​

使用示例

Query

SELECT * FROM format(
    'RowBinaryWithNamesAndTypesAndDefaults',
    'x Nullable(UInt32) DEFAULT 42',
    unhex('01' || '0178' || '10' || hex('Nullable(UInt32)') || '01')
);

Response

┌──x─┐
│ 42 │
└────┘

• 请求头包含一列，名为 x，类型为 Nullable(UInt32)。
• 该单元使用标记 0x01，表示“使用 DEFAULT 42”。

​

格式设置

以下设置适用于所有 RowBinary 类型的格式。

Setting	Description	Default
format_binary_max_string_size	RowBinary 格式中 String 的最大允许大小。	1GiB
output_format_binary_encode_types_in_binary_format	允许在请求头中使用binary encoding写入类型，而不是在RowBinaryWithNamesAndTypes输出格式中使用包含类型名称的字符串。	false
input_format_binary_decode_types_in_binary_format	允许在请求头中使用binary encoding读取类型，而不是在RowBinaryWithNamesAndTypes输入格式中使用包含类型名称的字符串。	false
output_format_binary_write_json_as_string	允许在RowBinary输出格式中，将JSON数据类型的值写为 JSON String 值。	false
input_format_binary_read_json_as_string	允许在RowBinary输入格式中，将JSON数据类型的值读取为 JSON String 值。	false