Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs
49.6kGet Started

RowBinaryWithNamesAndTypesAndDefaults

View as MarkdownEdit this pageReport an issueSet up docs MCP
입력 출력 별칭
✔ ✗

설명

RowBinaryWithNamesAndTypes 포맷과 유사하지만, 각 셀 앞에 해당 컬럼의 DEFAULT 값을 사용해야 하는지를 나타내는 바이트가 추가로 붙습니다. 이는 RowBinaryWithDefaults 포맷과 정확히 동일한 방식입니다. 이 조합은 스키마가 변경되는 INSERT를 지원합니다. 즉, writer는 헤더에서 컬럼을 생략할 수 있으며(이 경우 대상 컬럼의 DEFAULT가 적용됨), 전송하는 컬럼에 대해서도 개별 셀마다 "컬럼의 DEFAULT 사용"으로 표시할 수 있으므로 이를 NULL과 혼동하지 않습니다.

이 포맷은 입력 전용입니다.

Wire 형식

헤더는 RowBinaryWithNamesAndTypes와 동일합니다.

  1. 컬럼 수 N을 나타내는 VarUInt
  2. 컬럼 이름을 담은 길이 접두사 방식의 String N개
  3. N개의 컬럼 타입 — 텍스트 이름 또는 압축 바이너리 인코딩 중 하나이며, output_format_binary_encode_types_in_binary_format / input_format_binary_decode_types_in_binary_format 설정으로 제어됩니다.

헤더 다음에는 각 행이 N개의 셀로 구성됩니다. 각 셀은 다음과 같습니다.

  • UInt8 마커 바이트 1개
    • 0x01 — 대상 컬럼의 DEFAULT 표현식을 사용합니다. 뒤에 값 바이트는 오지 않습니다.
    • 0x00 — 값이 뒤따르며, 컬럼 타입의 RowBinary 직렬화기를 사용해 직렬화됩니다. Nullable(T)의 경우 값 바이트는 Nullable 널 바이트(널이 아니면 0, NULL이면 1)로 시작하고, 널이 아닌 경우 그 뒤에 내부 값이 옵니다.

기본값 vs NULL

셀별 기본 마커와 Nullable의 내장 널 바이트는 서로 독립적으로 동작합니다. Nullable(UInt32) DEFAULT 42 컬럼은 각 행마다 세 가지 방식으로 전송될 수 있습니다:

바이트 의미
01 DEFAULT 42를 사용합니다.
00 01 값 경로를 따른 뒤 Nullable 타입을 통해 NULL을 나타냅니다.
00 00 … 값 경로를 따른 뒤 null이 아닌 내부 값을 나타냅니다.

스키마 진화

Case Behavior
파일 헤더에 컬럼이 아예 없음 insertDefaultsForNotSeenColumns를 통해 대상에 기본값이 채워지며, defaults_for_omitted_fields의 적용을 받습니다.
헤더에 컬럼이 있고, 셀 마커가 0x01임 각 행에 insertDefault가 적용됩니다.
헤더에 컬럼이 있고, 셀 마커가 0x00임 값이 정상적으로 파싱됩니다.
헤더에 추가 컬럼이 있지만 대상 테이블에는 없음 input_format_skip_unknown_fields = 1이면 조용히 삭제됩니다(먼저 마커를 읽습니다. 0x01이면 그 외에는 아무 작업도 하지 않고, 0x00이면 타입에 맞는 값을 파싱한 후 버립니다).

사용 예시

Querysql
SELECT * FROM format(
    'RowBinaryWithNamesAndTypesAndDefaults',
    'x Nullable(UInt32) DEFAULT 42',
    unhex('01' || '0178' || '10' || hex('Nullable(UInt32)') || '01')
);
Responseresponse
┌──x─┐
│ 42 │
└────┘
  • 헤더에는 Nullable(UInt32) 타입의 x라는 컬럼이 하나 있습니다.
  • 단일 셀은 0x01 마커를 사용하며, 이는 "DEFAULT 42를 사용"함을 의미합니다.

포맷 설정

다음 설정은 모든 RowBinary 계열 포맷에 공통으로 적용됩니다.

설정 설명 기본값
format_binary_max_string_size RowBinary 포맷에서 String에 허용되는 최대 크기입니다. 1GiB
output_format_binary_encode_types_in_binary_format RowBinaryWithNamesAndTypes 출력 형식에서 헤더의 타입을 타입 이름 문자열 대신 binary encoding으로 기록할 수 있습니다. false
input_format_binary_decode_types_in_binary_format RowBinaryWithNamesAndTypes 입력 형식에서 헤더의 타입을 타입 이름 문자열 대신 binary encoding으로 읽을 수 있습니다. 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
Navigation