Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs
49.6kGet Started

RowBinaryWithNamesAndTypesAndDefaults

View as MarkdownEdit this pageReport an issueSet up docs MCP
Entrada Saída Alias
✔ ✗

Descrição

Semelhante ao formato RowBinaryWithNamesAndTypes, mas com um byte extra antes de cada célula que indica se o valor DEFAULT da coluna deve ser usado — exatamente como no formato RowBinaryWithDefaults. Essa combinação oferece suporte a INSERTs com evolução de esquema: quem grava pode omitir colunas do cabeçalho (elas recebem o DEFAULT da coluna de destino) e, para qualquer coluna que enviar, pode marcar células individuais como "usar o DEFAULT da coluna" sem confundir isso com NULL.

Este formato é apenas de entrada.

Formato de transmissão

O cabeçalho é idêntico ao de RowBinaryWithNamesAndTypes:

  1. Um VarUInt com o número de colunas N.
  2. N Strings prefixadas pelo comprimento com os nomes das colunas.
  3. N tipos de coluna — nomes textuais ou codificação binária compacta, controlados pelas configurações output_format_binary_encode_types_in_binary_format / input_format_binary_decode_types_in_binary_format.

Após o cabeçalho, cada linha é composta por N células. Para cada célula:

  • Um único byte marcador UInt8.
    • 0x01 — usa a expressão DEFAULT da coluna de destino. Nenhum byte de valor vem em seguida.
    • 0x00 — um valor vem em seguida, serializado pelo serializador RowBinary do tipo da coluna. Para Nullable(T), os bytes do valor começam com o byte nulo de Nullable (0 para não nulo, 1 para NULL) e, em seguida, vêm o valor interno, se não for nulo.

Valores padrão vs NULL

O marcador de valor padrão por célula e o byte nulo interno de Nullable são independentes. Uma coluna Nullable(UInt32) DEFAULT 42 pode ser enviada de três formas diferentes por linha:

Bytes Significado
01 Use DEFAULT 42.
00 01 Caminho do valor, depois NULL via o tipo Nullable.
00 00 … Caminho do valor, depois um valor interno não nulo.

Evolução do esquema

Caso Comportamento
Coluna totalmente ausente do cabeçalho do arquivo Preenchida no destino via insertDefaultsForNotSeenColumns; condicionada por defaults_for_omitted_fields.
Coluna presente no cabeçalho, marcador de célula 0x01 insertDefault por linha.
Coluna presente no cabeçalho, marcador de célula 0x00 O valor é processado normalmente.
Coluna extra no cabeçalho, ausente na tabela de destino Descartada silenciosamente quando input_format_skip_unknown_fields = 1 (o marcador é consumido primeiro; se 0x01, nada mais; se 0x00, o valor tipado é processado e descartado).

Exemplo de uso

Querysql
SELECT * FROM format(
    'RowBinaryWithNamesAndTypesAndDefaults',
    'x Nullable(UInt32) DEFAULT 42',
    unhex('01' || '0178' || '10' || hex('Nullable(UInt32)') || '01')
);
Responseresponse
┌──x─┐
│ 42 │
└────┘
  • O cabeçalho contém uma coluna chamada x do tipo Nullable(UInt32).
  • A única célula usa o marcador 0x01, que significa "usar DEFAULT 42".

Configurações de formato

As configurações a seguir são comuns a todos os formatos do tipo RowBinary.

Configuração Descrição Padrão
format_binary_max_string_size O tamanho máximo permitido para String no formato RowBinary. 1GiB
output_format_binary_encode_types_in_binary_format Permite escrever tipos no cabeçalho usando codificação binária, em vez de strings com nomes de tipos, no formato de saída RowBinaryWithNamesAndTypes. false
input_format_binary_decode_types_in_binary_format Permite ler tipos no cabeçalho usando codificação binária, em vez de strings com nomes de tipos, no formato de entrada RowBinaryWithNamesAndTypes. false
output_format_binary_write_json_as_string Permite escrever valores do tipo de dado JSON como valores JSON String no formato de saída RowBinary. false
input_format_binary_read_json_as_string Permite ler valores do tipo de dado JSON como valores JSON String no formato de entrada RowBinary. false
Navigation