입력 포맷 설정
입력 포맷 설정 (Input format settings)
이 설정들은 ClickHouse가 데이터를 읽을 때 각 입력 포맷의 동작을 세밀하게 조정해요. 텍스트 포맷(CSV, TSV 등), JSON 계열, ORC·Parquet·Arrow 같은 컬럼 포맷, 그리고 Native 포맷의 읽기 방식과 스키마 추론 동작을 제어해요.
출처: 문서
본문
이 설정들은 ClickHouse 소스에서 자동 생성됐어요.
input_format_allow_errors_num
텍스트 포맷(CSV, TSV 등)에서 읽을 때 허용 가능한 오류의 최대 수를 설정해요.
기본값은 0이에요.
항상 input_format_allow_errors_ratio와 함께 쌍으로 설정하세요.
행을 읽는 중 오류가 발생했지만 오류 카운터가 여전히 input_format_allow_errors_num보다 작으면, ClickHouse는 그 행을 무시하고 다음 행으로 넘어가요.
input_format_allow_errors_num과 input_format_allow_errors_ratio가 모두 초과되면 ClickHouse가 예외를 던져요.
input_format_allow_errors_ratio
텍스트 포맷(CSV, TSV 등)에서 읽을 때 허용되는 오류의 최대 비율을 설정해요. 오류 비율은 0에서 1 사이의 부동소수점 숫자로 설정돼요.
기본값은 0이에요.
항상 input_format_allow_errors_num과 함께 쌍으로 설정하세요.
행을 읽는 중 오류가 발생했지만 오류 카운터가 여전히 input_format_allow_errors_ratio보다 작으면, ClickHouse는 그 행을 무시하고 다음 행으로 넘어가요.
input_format_allow_errors_num과 input_format_allow_errors_ratio가 모두 초과되면 ClickHouse가 예외를 던져요.
input_format_allow_seeks
ORC, Parquet, Arrow 입력 포맷을 읽는 동안 시크(seek, 또는 범위 읽기)를 허용할지 설정해요. 활성화되고 소스가 지원하면(예: 로컬 파일, S3, 범위 지원과 알려진 크기가 있는 HTTP), ClickHouse는 필요한 바이트 범위만 읽고 메모리를 덜 사용할 수 있어요. 비활성화되거나, 소스가 시크를 지원하지 않으면(예: 파일 크기 없음, 비시크 가능 스트림), 일부 리더는 전체 파일을 메모리에 로드하는 것으로 폴백할 수 있어요. 기본적으로 활성화돼요.
input_format_arrow_allow_missing_columns
Arrow 입력 포맷을 읽을 때 누락된 컬럼을 허용해요.
input_format_arrow_case_insensitive_column_matching
Arrow 컬럼을 CH 컬럼과 일치시킬 때 대소문자를 무시해요.
input_format_arrow_skip_columns_with_unsupported_types_in_schema_inference
Arrow 포맷의 스키마 추론 중 지원되지 않는 타입의 컬럼을 건너뛰어요.
input_format_avro_allow_missing_fields
Avro/AvroConfluent 포맷: 스키마에서 필드를 찾지 못하면 오류 대신 기본값을 사용해요.
input_format_avro_null_as_default
Avro/AvroConfluent 포맷: null이면서 non-Nullable 컬럼인 경우 기본을 삽입해요.
input_format_binary_decode_types_in_binary_format
RowBinaryWithNamesAndTypes 입력 포맷에서 타입 이름 대신 이진 형식으로 데이터 타입을 읽어요.
input_format_binary_max_type_complexity
이진 타입을 디코딩할 때 최대 타입 노드 수(깊이가 아니라 총 개수)를 설정해요. Map(String, UInt32) = 3 노드. 악의적인 입력으로부터 보호해요. 0 = 무제한.
input_format_binary_read_json_as_string
RowBinary 입력 포맷에서 JSON 데이터 타입의 값을 JSON 문자열 값으로 읽어요.
input_format_bson_skip_fields_with_unsupported_types_in_schema_inference
BSON 포맷의 스키마 추론 중 지원되지 않는 타입의 필드를 건너뛰어요.
input_format_capn_proto_skip_fields_with_unsupported_types_in_schema_inference
CapnProto 포맷의 스키마 추론 중 지원되지 않는 타입의 컬럼을 건너뛰어요.
input_format_column_name_matching_mode
여러 포맷(JSONEachRow, CSVWithNames, JSONColumns, BSONEachRow, RowBinaryWithNames 등에 국한되지 않음)을 통해 데이터를 수집할 때 컬럼 이름 일치 모드를 정의해요. 지원되는 모드:
- match_case: 대소문자 구분해서 일치
- ignore_case: 대소문자 구분 없이 일치
- auto: 먼저 대소문자 구분 일치를 시도하고, 실패하면 대소문자 구분 없이 일치를 시도.
input_format_connection_handling
이 옵션이 활성화되면, 연결이 예기치 않게 닫혀도 버퍼에 남은 데이터가 오류로 처리되지 않고 파싱되어 처리돼요.
주의
이 옵션을 활성화하면 병렬 파싱이 비활성화되고 중복 제거가 불가능해져요.
input_format_csv_allow_cr_end_of_line
true로 설정하면, 줄 끝에 \n이 뒤따르지 않는 \r이 허용돼요.
input_format_csv_allow_variable_number_of_columns
CSV 입력에서 (파일이 예상보다 많은 컬럼을 가지면) 추가 컬럼을 무시하고, CSV 입력의 누락 필드를 기본값으로 처리해요.
input_format_csv_allow_whitespace_or_tab_as_delimiter
CSV 문자열에서 필드 구분자로 공백과 탭(\t)을 사용할 수 있게 해요.
input_format_csv_arrays_as_nested_csv
CSV에서 Array를 읽을 때, 그 요소가 중첩 CSV로 직렬화된 뒤 문자열로 들어갔다고 기대해요. 예: "[\\"Hello\\", \\"world\\", \\"42\\" TV\\"]". 배열 주위의 중괄호는 생략할 수 있어요.
input_format_csv_deserialize_separate_columns_into_tuple
true로 설정하면, CSV 포맷으로 작성된 별도의 컬럼들이 Tuple 컬럼으로 역직렬화될 수 있어요.
이것은 맨몸 Tuple에만 적용돼요. Nullable(Tuple)은 항상 단일 CSV 필드로 작성되며(참조) 마찬가지로 단일 필드에서만 다시 읽혀요. 이 설정과 무관하게 별도 컬럼에서 읽지 않아요. 선두 \N 필드가 모호하기 때문에(튜플의 외부 NULL이거나 첫 요소의 NULL일 수 있음) Nullable(Tuple)에는 별도-컬럼 파싱이 지원되지 않아요.
맨몸 Tuple이 요소당 하나의 필드를 차지하므로, 직접 최상위 요소의 필드에 있는 \N은 그 요소이지 전체 컬럼이 아니에요. 따라서 NULL 처리가 그 요소에 적용돼요. 전체 튜플에 대해 단일 필드를 공급하는 행은 나머지 요소가 부족해 컬럼 기본값을 취하는 대신 거부돼요. 그런 필드를 다시 전체 컬럼으로 읽으려면 이 설정을 0으로 설정하세요. 중첩 Tuple의 요소 필드에 있는 \N은 여전히 그 전체 중첩 요소로 읽혀요.
input_format_csv_detect_header
CSV 포맷에서 이름과 타입이 있는 헤더를 자동 감지해요.
input_format_csv_empty_as_default
CSV 입력의 빈 필드를 기본값으로 처리해요.
input_format_csv_enum_as_number
CSV 포맷에서 삽입된 enum 값을 enum 인덱스로 처리해요.
input_format_csv_missing_nullable_as_empty_string
CSV의 누락 값에서 Nullable(String)을 읽는 방식을 제어해요. 누락 값은 따옴표로 둘러싸이지 않은, 쉼표 사이/앞/뒤의 빈 공간이에요. 이 설정이 활성화되면, input_format_csv_empty_as_default의 값과 무관하게 Nullable(String)의 누락 값은 NULL이 아니라 빈 String으로 해석돼요.
input_format_csv_skip_first_lines
CSV 포맷 데이터의 시작에서 지정된 수의 줄을 건너뛰어요.
input_format_csv_skip_trailing_empty_lines
CSV 포맷의 후행 빈 줄을 건너뛰어요.
input_format_csv_trim_whitespaces
CSV 문자열의 시작과 끝에서 공백과 탭(\t) 문자를 잘라내요.
input_format_csv_try_infer_numbers_from_strings
활성화되면, 스키마 추론 중 ClickHouse가 문자열 필드에서 숫자를 추론하려고 시도해요. 인용된 UInt64 숫자가 포함된 CSV 데이터에 유용할 수 있어요.
기본적으로 비활성화돼요.
input_format_csv_try_infer_strings_from_quoted_tuples
입력 데이터의 인용된 튜플을 String 타입의 값으로 해석해요.
input_format_csv_use_best_effort_in_schema_inference
CSV 포맷에서 스키마를 추론할 때 몇 가지 트릭과 휴리스틱을 사용해요.
input_format_csv_use_default_on_bad_values
CSV 필드 역직렬화가 잘못된 값에서 실패할 때 컬럼에 기본값을 설정하는 것을 허용해요.
input_format_custom_allow_variable_number_of_columns
CustomSeparated 입력에서 (파일이 예상보다 많은 컬럼을 가지면) 추가 컬럼을 무시하고, CustomSeparated 입력의 누락 필드를 기본값으로 처리해요.
input_format_custom_detect_header
CustomSeparated 포맷에서 이름과 타입이 있는 헤더를 자동 감지해요.
input_format_custom_skip_trailing_empty_lines
CustomSeparated 포맷의 후행 빈 줄을 건너뛰어요.
input_format_defaults_for_omitted_fields
INSERT 쿼리를 수행할 때, 생략된 입력 컬럼 값을 해당 컬럼의 기본값으로 대체해요. 이 옵션은 JSONEachRow(및 다른 JSON 포맷)와 WithNames/WithNamesAndTypes 접미사가 있는 포맷들에 적용돼요.
주의
이 옵션이 활성화되면, 확장 테이블 메타데이터가 서버에서 클라이언트로 전송돼요. 서버에 추가 계산 자원을 소비하고 성능을 낮출 수 있어요.
가능한 값:
- 0 — 비활성화.
- 1 — 활성화.
input_format_force_null_for_omitted_fields
생략된 필드를 null 값으로 강제 초기화해요.
input_format_geojson_unsupported_geometry_handling
GeoJSON 입력을 읽는 동안 ClickHouse의 Geometry 타입으로 나타낼 수 없는 유효한 GeoJSON 지오메트리 타입(예: GeometryCollection)을 geometry 컬럼에 저장해야 할 때 어떤 일이 일어날지 제어해요.
가능한 값:
'throw'(기본값) — 예외를 던져요.'null'—geometry컬럼에 대해NULL값을 삽입하고 파싱을 계속해요.
이것은 geometry 컬럼이 구체화될 때만 적용돼요. 요청된 출력 컬럼이 아닐 때는 그런 지오메트리가 잘 형성되었는지만 검증되고 처리를 트리거하지 않아요.
input_format_hive_text_allow_variable_number_of_columns
Hive Text 입력에서 (파일이 예상보다 많은 컬럼을 가지면) 추가 컬럼을 무시하고, Hive Text 입력의 누락 필드를 기본값으로 처리해요.
input_format_hive_text_collection_items_delimiter
Hive Text File에서 컬렉션(배열 또는 맵) 항목 사이의 구분자.
input_format_hive_text_fields_delimiter
Hive Text File에서 필드 사이의 구분자.
input_format_hive_text_map_keys_delimiter
Hive Text File에서 맵 키/값 쌍 사이의 구분자.
input_format_import_nested_json
중첩 객체를 가진 JSON 데이터의 삽입을 활성화하거나 비활성화해요.
지원되는 포맷:
가능한 값:
- 0 — 비활성화.
- 1 — 활성화.
또한 참조:
JSONEachRow포맷과 함께 input_format_import_nested_json.
input_format_ipv4_default_on_conversion_error
IPv4의 역직렬화는 변환 오류 시 예외를 던지는 대신 기본값을 사용해요.
기본적으로 비활성화돼요.
input_format_ipv6_default_on_conversion_error
IPv6의 역직렬화는 변환 오류 시 예외를 던지는 대신 기본값을 사용해요.
기본적으로 비활성화돼요.
input_format_json_compact_allow_variable_number_of_columns
JSONCompact/JSONCompactEachRow 입력 포맷의 행에서 가변 컬럼 수를 허용해요. 예상보다 많은 컬럼을 가진 행의 추가 컬럼을 무시하고, 누락된 컬럼을 기본값으로 처리해요.
기본적으로 비활성화돼요.
input_format_json_defaults_for_missing_elements_in_named_tuple
명명된 튜플을 파싱하는 동안 JSON 객체에서 누락된 요소에 대해 기본값을 삽입해요.
이 설정은 input_format_json_named_tuples_as_objects 설정이 활성화일 때만 작동해요.
기본적으로 활성화돼요.
input_format_json_empty_as_default
활성화되면, JSON의 빈 입력 필드를 기본값으로 대체해요. 복잡한 기본 표현식의 경우 input_format_defaults_for_omitted_fields도 활성화해야 해요.
가능한 값:
- 0 — 비활성화.
- 1 — 활성화.
input_format_json_ignore_unknown_keys_in_named_tuple
명명된 튜플에 대해 json 객체의 알 수 없는 키를 무시해요.
기본적으로 활성화돼요.
input_format_json_ignore_unnecessary_fields
불필요한 필드를 무시하고 파싱하지 않아요. 이를 활성화하면 잘못된 형식 또는 중복 필드가 있는 json 문자열에서 예외가 발생하지 않을 수 있어요.
input_format_json_infer_array_of_dynamic_from_array_of_different_types
활성화되면, 스키마 추론 중 ClickHouse가 서로 다른 데이터 타입의 값을 가진 JSON 배열에 대해 Array(Dynamic) 타입을 사용해요.
예시:
SET input_format_json_infer_array_of_dynamic_from_array_of_different_types=1;
DESC format(JSONEachRow, '{"a" : [42, "hello", [1, 2, 3]]}');
┌─name─┬─type───────────┐
│ a │ Array(Dynamic) │
└──────┴────────────────┘
SET input_format_json_infer_array_of_dynamic_from_array_of_different_types=0;
DESC format(JSONEachRow, '{"a" : [42, "hello", [1, 2, 3]]}');
┌─name─┬─type─────────────────────────────────────────────────────────────┐
│ a │ Tuple(Nullable(Int64), Nullable(String), Array(Nullable(Int64))) │
└──────┴──────────────────────────────────────────────────────────────────┘
기본적으로 활성화돼요.
input_format_json_infer_incomplete_types_as_strings
스키마 추론 중 데이터 샘플에 Null/{}/[]만 포함된 JSON 키에 대해 String 타입을 사용할 수 있게 해요.
JSON 포맷에서 어떤 값이든 String으로 읽을 수 있으므로, 알 수 없는 타입의 키에 String 타입을 사용하면 first 25000 rows of data, most likely this column contains only Nulls or empty Arrays/Maps during schema inference 같은 오류를 피할 수 있어요.
예시:
SET input_format_json_infer_incomplete_types_as_strings = 1, input_format_json_try_infer_named_tuples_from_objects = 1;
DESCRIBE format(JSONEachRow, '{"obj" : {"a" : [1,2,3], "b" : "hello", "c" : null, "d" : {}, "e" : []}}');
SELECT * FROM format(JSONEachRow, '{"obj" : {"a" : [1,2,3], "b" : "hello", "c" : null, "d" : {}, "e" : []}}');
결과:
┌─name─┬─type───────────────────────────────────────────────────────────────────────────────────────────────────────────────────┬─default_type─┬─default_expression─┬─comment─┬─codec_expression─┬─ttl_expression─┐
│ obj │ Tuple(a Array(Nullable(Int64)), b Nullable(String), c Nullable(String), d Nullable(String), e Array(Nullable(String))) │ │ │ │ │ │
└──────┴────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┴──────────────┴────────────────────┴─────────┴──────────────────┴────────────────┘
┌─obj────────────────────────────┐
│ ([1,2,3],'hello',NULL,'{}',[]) │
└────────────────────────────────┘
기본적으로 활성화돼요.
input_format_json_map_as_array_of_tuples
맵 컬럼을 튜플의 JSON 배열로 역직렬화해요.
기본적으로 비활성화돼요.
input_format_json_max_depth
JSON에서 필드의 최대 깊이. 엄격한 제한이 아니며 정밀하게 적용될 필요는 없어요.
input_format_json_max_object_size
단일 JSON 객체의 허용 최대 크기(바이트). 이 제한을 초과하는 객체는 손상되었을 가능성이 높은 것으로 거부돼요. 이는 손상된 JSON 문서가 단일 객체로 파싱될 때 메모리 고갈을 보호해요. 같은 제한이 병렬 및 비병렬 파싱 경로 모두에 적용돼요. 검사를 비활성화하려면 0으로 설정하세요.
input_format_json_max_string_column_growth_step
문자열에서 JSON을 파싱하면서 JSON 컬럼의 내부 String 버퍼를 만들 때, 2의 거듭제곱 성장을 이 바이트 수에 상한을 정해요: 예약된 크기가 이 값에 도달하면 버퍼는 두 배가 아니라 이 크기의 증분으로 성장해요. 이는 큰 JSON 컬럼의 과할당을 제한해요. 0은 무제한(순수 두 배)을 뜻해요.
input_format_json_named_tuples_as_objects
명명된 튜플 컬럼을 JSON 객체로 파싱해요.
기본적으로 활성화돼요.
input_format_json_read_arrays_as_strings
JSON 입력 포맷에서 JSON 배열을 문자열로 파싱하는 것을 허용해요.
예시:
SET input_format_json_read_arrays_as_strings = 1;
SELECT arr, toTypeName(arr), JSONExtractArrayRaw(arr)[3] from format(JSONEachRow, 'arr String', '{"arr" : [1, "Hello", [1,2,3]]}');
결과:
┌─arr───────────────────┬─toTypeName(arr)─┬─arrayElement(JSONExtractArrayRaw(arr), 3)─┐
│ [1, "Hello", [1,2,3]] │ String │ [1,2,3] │
└───────────────────────┴─────────────────┴───────────────────────────────────────────┘
기본적으로 활성화돼요.
input_format_json_read_bools_as_numbers
JSON 입력 포맷에서 불리언을 숫자로 파싱하는 것을 허용해요.
기본적으로 활성화돼요.
input_format_json_read_bools_as_strings
JSON 입력 포맷에서 불리언을 문자열로 파싱하는 것을 허용해요.
기본적으로 활성화돼요.
input_format_json_read_numbers_as_strings
JSON 입력 포맷에서 숫자를 문자열로 파싱하는 것을 허용해요.
기본적으로 활성화돼요.
input_format_json_read_objects_as_strings
JSON 입력 포맷에서 JSON 객체를 문자열로 파싱하는 것을 허용해요.
예시:
SET input_format_json_read_objects_as_strings = 1;
CREATE TABLE test (id UInt64, obj String, date Date) ENGINE=Memory();
INSERT INTO test FORMAT JSONEachRow {"id" : 1, "obj" : {"a" : 1, "b" : "Hello"}, "date" : "2020-01-01"};
SELECT * FROM test;
결과:
┌─id─┬─obj──────────────────────┬───────date─┐
│ 1 │ {"a" : 1, "b" : "Hello"} │ 2020-01-01 │
└────┴──────────────────────────┴────────────┘
기본적으로 활성화돼요.
input_format_json_throw_on_bad_escape_sequence
JSON 입력 포맷에서 JSON 문자열에 잘못된 이스케이프 시퀀스가 있으면 예외를 던져요. 비활성화되면 잘못된 이스케이프 시퀀스가 데이터에 그대로 남아요.
기본적으로 활성화돼요.
input_format_json_try_infer_named_tuples_from_objects
활성화되면, 스키마 추론 중 ClickHouse가 JSON 객체에서 명명된 Tuple을 추론하려고 시도해요. 결과 명명된 Tuple은 샘플 데이터의 모든 해당 JSON 객체의 모든 요소를 포함해요.
예시:
SET input_format_json_try_infer_named_tuples_from_objects = 1;
DESC format(JSONEachRow, '{"obj" : {"a" : 42, "b" : "Hello"}}, {"obj" : {"a" : 43, "c" : [1, 2, 3]}}, {"obj" : {"d" : {"e" : 42}}}')
결과:
┌─name─┬─type───────────────────────────────────────────────────────────────────────────────────────────────┬─default_type─┬─default_expression─┬─comment─┬─codec_expression─┬─ttl_expression─┐
│ obj │ Tuple(a Nullable(Int64), b Nullable(String), c Array(Nullable(Int64)), d Tuple(e Nullable(Int64))) │ │ │ │ │ │
└──────┴────────────────────────────────────────────────────────────────────────────────────────────────────┴──────────────┴────────────────────┴─────────┴──────────────────┴────────────────┘
기본적으로 활성화돼요.
input_format_json_try_infer_numbers_from_strings
활성화되면, 스키마 추론 중 ClickHouse가 문자열 필드에서 숫자를 추론하려고 시도해요. 인용된 UInt64 숫자가 포함된 JSON 데이터에 유용할 수 있어요.
기본적으로 비활성화돼요.
input_format_json_use_string_type_for_ambiguous_paths_in_named_tuples_inference_from_objects
객체에서 명명된 튜플 추론 중 모호한 path가 있는 경우 예외 대신 String 타입을 사용해요.
input_format_json_validate_types_from_metadata
JSON/JSONCompact/JSONColumnsWithMetadata 입력 포맷의 경우, 이 설정이 1이면 입력 데이터의 메타데이터 타입이 테이블의 해당 컬럼 타입과 비교돼요.
기본적으로 활성화돼요.
input_format_max_block_size_bytes
입력 포맷에서 데이터를 파싱하는 동안 형성되는 블록의 크기(바이트)를 제한해요. 블록이 ClickHouse 쪽에서 형성되는 행 기반 입력 포맷에 사용돼요. 0은 바이트 제한이 없음을 뜻해요.
input_format_max_block_wait_ms
행 기반 입력 포맷에서 파싱 중 블록을 내보내기 전에 기다리는 최대 시간(밀리초)을 제한해요. 0은 제한이 없음을 뜻해요.
주의
이 옵션은
input_format_connection_handling이 활성화일 때만 작동해요. 값을 설정하는 것도 병렬 파싱을 비활성화하고 중복 제거를 불가능하게 해요.
주의
스트리밍 삽입의 경우
min_insert_block_size_rows=0과min_insert_block_size_bytes=0도 설정해야 해요. 그렇지 않으면 파싱된 블록이 블록 스쿼싱 단계에 의해 그 임계값에 도달할 때까지 메모리에 누적되어 적시 삽입을 막을 수 있어요.
예시: Wikipedia 최근 변경 사항을 ClickHouse로 스트리밍
clickhouse-client --query 'CREATE TABLE wikipedia_edits (data JSON)'
curl -sS --globoff -H 'Accept: application/json' --no-buffer \
'https://stream.wikimedia.org/v2/stream/recentchange' \
| clickhouse-client \
--query 'INSERT INTO wikipedia_edits FORMAT JSONAsObject' \
--input_format_max_block_wait_ms 1000 \
--input_format_connection_handling 1 \
--min_insert_block_size_rows 0 \
--min_insert_block_size_bytes 0
input_format_max_bytes_to_read_for_schema_inference
자동 스키마 추론을 위해 읽을 최대 데이터 양(바이트).
input_format_max_rows_to_read_for_schema_inference
자동 스키마 추론을 위해 읽을 최대 데이터 행.
input_format_msgpack_number_of_columns
삽입된 MsgPack 데이터의 컬럼 수. 데이터에서 자동 스키마 추론을 위해 사용돼요.
input_format_mysql_dump_map_column_names
MySQL 덤프의 테이블 컬럼과 ClickHouse 테이블 컬럼을 이름으로 일치시켜요.
input_format_mysql_dump_table_name
데이터를 읽을 MySQL 덤프의 테이블 이름.
input_format_native_allow_types_conversion
Native 입력 포맷에서 데이터 타입 변환을 허용해요.
input_format_native_decode_types_in_binary_format
Native 입력 포맷에서 타입 이름 대신 이진 형식으로 데이터 타입을 읽어요.
input_format_null_as_default
NULL 필드의 데이터 타입이 nullable하지 않으면 해당 필드를 기본값으로 초기화할지 활성화/비활성화해요. 컬럼 타입이 nullable하지 않고 이 설정이 비활성화면, NULL 삽입이 예외를 발생시켜요. 컬럼 타입이 nullable이면, 이 설정과 무관하게 NULL 값이 그대로 삽입돼요.
이 설정은 대부분의 입력 포맷에 적용돼요.
복잡한 기본 표현식의 경우 input_format_defaults_for_omitted_fields도 활성화해야 해요.
가능한 값:
- 0 — nullable하지 않은 컬럼에 NULL을 삽입하면 예외가 발생해요.
- 1 — NULL 필드가 컬럼 기본값으로 초기화돼요.
input_format_orc_allow_missing_columns
ORC 입력 포맷을 읽을 때 누락된 컬럼을 허용해요.
input_format_orc_case_insensitive_column_matching
ORC 컬럼을 CH 컬럼과 일치시킬 때 대소문자를 무시해요.
input_format_orc_dictionary_as_low_cardinality
ORC 파일을 읽는 동안 ORC 딕셔너리 인코딩 컬럼을 LowCardinality 컬럼으로 취급해요.
input_format_orc_filter_push_down
ORC 파일을 읽을 때, ORC 메타데이터의 WHERE/PREWHERE 표현식, min/max 통계 또는 bloom filter를 기반으로 전체 stripe 또는 행 그룹을 건너뛰어요.
input_format_orc_reader_time_zone_name
ORC 행 리더의 시간대 이름, 기본 ORC 행 리더의 시간대는 GMT예요.
input_format_orc_row_batch_size
ORC stripe를 읽을 때 배치 크기.
input_format_orc_skip_columns_with_unsupported_types_in_schema_inference
ORC 포맷의 스키마 추론 중 지원되지 않는 타입의 컬럼을 건너뛰어요.
input_format_parallel_parsing
데이터 포맷의 순서 보존 병렬 파싱을 활성화 또는 비활성화해요. TabSeparated (TSV), TSKV, CSV, JSONEachRow 포맷에 대해서만 지원돼요.
가능한 값:
- 1 — 활성화.
- 0 — 비활성화.
input_format_parquet_allow_geoparquet_parser
geo 컬럼 파서를 사용해 Array(UInt8)를 Point/MultiPoint/Linestring/Polygon/MultiLineString/MultiPolygon 타입으로 변환해요.
input_format_parquet_allow_missing_columns
Parquet 입력 포맷을 읽을 때 누락된 컬럼을 허용해요.
input_format_parquet_bloom_filter_push_down
Parquet 파일을 읽을 때, Parquet 메타데이터의 WHERE 표현식과 bloom filter를 기반으로 전체 행 그룹을 건너뛰어요.
input_format_parquet_case_insensitive_column_matching
Parquet 컬럼을 CH 컬럼과 일치시킬 때 대소문자를 무시해요.
input_format_parquet_dictionary_filter_push_down
Parquet 파일(reader v3)을 읽을 때, 컬럼 청크의 모든 데이터 페이지가 딕셔너리 인코딩되면 WHERE/PREWHERE 표현식과 딕셔너리 페이지 내용을 기반으로 전체 행 그룹을 건너뛰어요. 값은 이 최적화가 적용되는 최대 딕셔너리 페이지 크기(바이트)이며, 0으로 설정하면 비활성화돼요. 둘 다 사용 가능할 때 bloom filter보다 우선해요.
input_format_parquet_enable_json_parsing
Parquet 파일을 읽을 때, JSON 컬럼을 ClickHouse JSON Column으로 파싱해요.
input_format_parquet_enable_row_group_prefetch
parquet 파싱 중 행 그룹 프리페치를 활성화해요. 현재 단일 스레드 파싱만 프리페치할 수 있어요.
input_format_parquet_filter_push_down
Parquet 파일을 읽을 때, Parquet 메타데이터의 WHERE/PREWHERE 표현식과 min/max 통계를 기반으로 전체 행 그룹을 건너뛰어요.
input_format_parquet_local_file_min_bytes_for_seek
Parquet 입력 포맷에서 read with ignore 대신 seek을 수행하기 위한 로컬 읽기(파일)에 필요한 최소 바이트.
input_format_parquet_local_time_as_utc
isAdjustedToUTC=false인 Parquet 타임스탬프에 스키마 추론이 사용하는 데이터 타입을 결정해요. true: DateTime64(…, 'UTC'), false: DateTime64(…). ClickHouse에는 로컬 벽시계 시간 데이터 타입이 없으므로 어느 동작도 완전히 올바르지 않아요. 직관에 반하지만 'true'가 덜 틀린 옵션일 가능성이 커요. 'UTC' 타임스탬프를 String으로 포맷하면 올바른 로컬 시간의 표현이 만들어지기 때문이에요.
input_format_parquet_max_block_size
parquet 리더의 최대 블록 크기.
input_format_parquet_memory_high_watermark
Parquet reader v3의 대략적인 메모리 제한. 병렬로 읽을 수 있는 행 그룹 또는 컬럼 수를 제한해요. 하나의 쿼리에서 여러 파일을 읽을 때 제한은 그 파일들에 걸친 총 메모리 사용에 있어요.
input_format_parquet_memory_low_watermark
메모리 사용량이 이 임계값보다 낮으면 더 적극적으로 프리페치를 예약해요. 예를 들어 네트워크를 통해 읽을 작은 bloom filter가 많을 때 유용할 수 있어요.
input_format_parquet_page_filter_push_down
컬럼 인덱스의 min/max 값을 사용해 페이지를 건너뛰어요.
input_format_parquet_prefer_block_bytes
parquet 리더가 출력하는 평균 블록 바이트.
input_format_parquet_preserve_order
Parquet 파일에서 읽을 때 행 재정렬을 피해요. 행 순서가 일반적으로 보장되지 않고 쿼리 파이프라인의 다른 부분이 그것을 깨뜨릴 수 있으므로 권장되지 않아요. 대신 ORDER BY _row_number를 사용하세요.
input_format_parquet_skip_columns_with_unsupported_types_in_schema_inference
Parquet 포맷의 스키마 추론 중 지원되지 않는 타입의 컬럼을 건너뛰어요.
input_format_parquet_spatial_filter_push_down
GeoParquet 파일을 읽을 때, WHERE 절의 공간 술어와 Parquet 메타데이터의 지오메트리 경계 상자 통계(geospatial_statistics.bbox 또는 covering.bbox 컬럼)를 기반으로, input_format_parquet_page_filter_push_down과 함께 전체 행 그룹과 개별 페이지를 건너뛰어요.
input_format_parquet_use_offset_index
페이지 필터링이 사용되지 않을 때 parquet 파일에서 페이지가 읽히는 방식에 대한 사소한 조정.
input_format_parquet_verify_checksums
parquet 파일을 읽을 때 페이지 체크섬을 검증해요.
input_format_protobuf_flatten_google_wrappers
일반 비중첩 컬럼에 Google 래퍼를 활성화해요, 예: String 컬럼 'str'에 대해 google.protobuf.StringValue 'str'. Nullable 컬럼에서는 빈 래퍼가 기본값으로, 누락이 null로 인식돼요.
input_format_protobuf_oneof_presence
특수 컬럼에 enum 값을 설정하는 방식으로 protobuf oneof의 어떤 필드가 발견됐는지 표시해요.
input_format_protobuf_skip_fields_with_unsupported_types_in_schema_inference
Protobuf 포맷의 스키마 추론 중 지원되지 않는 타입의 필드를 건너뛰어요.
input_format_read_datetime_number_as_raw_value
DateTime/DateTime64 컬럼에 대해 맨몸의 따옴표 없는 정수를 초 단위 Unix 타임스탬프 대신 원시 밑바탕 값으로 읽어요 — DateTime은 초, DateTime64는 컬럼 정밀도의 틱.
기본적으로 비활성화: 따옴표 없는 숫자는 (선택적 하위 초 정밀도를 가진) 초 단위 Unix 타임스탬프이며, Values 포맷, CAST, toDateTime64와 일치해요. 26.7 이하 버전의 동작을 복원하려면 활성화(또는 SET compatibility = '26.7')하세요. 그 버전에서는 DateTime64 컬럼에 공급된 맨몸의 따옴표 없는 정수가 원시 배율 값(틱)으로 해석됐어요. 레거시 경로는 그러한 맨몸 정수만 받아들여요: 설정이 활성화되면, 분수 또는 지수 부분이 있는 숫자는 행 입력 경로에서 거부되고(26.8 이전처럼), JSONExtract과 typed JSON 타입에서는 분수 숫자가 DateTime64에 대해 여전히 초로 읽히고 DateTime에 대해 거부돼요(역시 26.8 이전처럼). Values 포맷 자체에서는 스트리밍 파서가 거부하는 숫자가 SQL 표현식 평가로 폴백되어 초로 읽혀요 — 26.8 이전과 이 설정이 활성화된 경우 모두. 따라서 분수 숫자에 대한 Values 동작은 모든 구성에서 같아요.
이 설정은 JSON, Values/Quoted, JSONExtract/typed JSON 경로만 다뤄요(Quoted 경로는 Quoted 이스케이프 규칙으로 필드를 파싱하는 모든 포맷을 다뤄요: Values, MySQLDump, Quoted 필드 이스케이프로 구성된 Template/CustomSeparated/Regexp). 탭 분리, CSV 및 기타 이스케이프/전체 텍스트 포맷은 영향을 받지 않아요: 거기서는 큰 따옴표 없는 DateTime64 숫자가 여전히 틱으로 읽혀요.
input_format_record_errors_file_path
텍스트 포맷(CSV, TSV)을 읽는 동안 오류를 기록하는 데 사용되는 파일의 경로.
input_format_skip_unknown_fields
추가 데이터 삽입 건너뛰기를 활성화 또는 비활성화해요.
데이터를 쓸 때, 입력 데이터에 대상 테이블에 존재하지 않는 컬럼이 포함되어 있으면 ClickHouse가 예외를 던져요. 건너뛰기가 활성화되면 ClickHouse는 추가 데이터를 삽입하지 않고 예외도 던지지 않아요.
지원되는 포맷:
- JSONEachRow (및 다른 JSON 포맷)
- BSONEachRow (및 다른 JSON 포맷)
- TSKV
WithNames/WithNamesAndTypes접미사가 있는 모든 포맷- MySQLDump
- Native
가능한 값:
- 0 — 비활성화.
- 1 — 활성화.
input_format_try_infer_dates
활성화되면, ClickHouse가 텍스트 포맷의 스키마 추론에서 문자열 필드에서 타입 Date를 추론하려고 시도해요. 입력 데이터의 컬럼의 모든 필드가 날짜로 성공적으로 파싱되면 결과 타입은 Date, 적어도 하나의 필드가 날짜로 파싱되지 않으면 결과 타입은 String이에요.
기본적으로 활성화돼요.
input_format_try_infer_datetimes
활성화되면, ClickHouse가 텍스트 포맷의 스키마 추론에서 문자열 필드에서 타입 DateTime64를 추론하려고 시도해요. 입력 데이터의 컬럼의 모든 필드가 datetime으로 성공적으로 파싱되면 결과 타입은 DateTime64, 적어도 하나의 필드가 datetime으로 파싱되지 않으면 결과 타입은 String이에요.
기본적으로 활성화돼요.
input_format_try_infer_datetimes_only_datetime64
input_format_try_infer_datetimes가 활성화될 때, DateTime 타입이 아닌 DateTime64만 추론해요.
input_format_try_infer_exponent_floats
텍스트 포맷의 스키마 추론에서 지수 표기법의 실수를 추론하려고 시도해요(지수 숫자가 항상 추론되는 JSON 제외).
input_format_try_infer_integers
활성화되면, ClickHouse가 텍스트 포맷의 스키마 추론에서 실수 대신 정수를 추론하려고 시도해요. 입력 데이터의 컬럼의 모든 숫자가 정수이면 결과 타입은 Int64, 적어도 하나의 숫자가 실수이면 결과 타입은 Float64예요.
기본적으로 활성화돼요.
input_format_try_infer_variants
활성화되면, 컬럼/배열 요소에 대해 하나 이상의 가능한 타입이 있을 때 ClickHouse가 텍스트 포맷의 스키마 추론에서 Variant 타입을 추론하려고 시도해요.
가능한 값:
- 0 — 비활성화.
- 1 — 활성화.
input_format_tsv_allow_variable_number_of_columns
TSV 입력에서 (파일이 예상보다 많은 컬럼을 가지면) 추가 컬럼을 무시하고, TSV 입력의 누락 필드를 기본값으로 처리해요.
input_format_tsv_crlf_end_of_line
true로 설정하면, file 함수가 \n 대신 \r\n으로 TSV 포맷을 읽어요.
input_format_tsv_detect_header
TSV 포맷에서 이름과 타입이 있는 헤더를 자동 감지해요.
input_format_tsv_empty_as_default
TSV 입력의 빈 필드를 기본값으로 처리해요.
input_format_tsv_enum_as_number
TSV 포맷에서 삽입된 enum 값을 enum 인덱스로 처리해요.
input_format_tsv_skip_first_lines
TSV 포맷 데이터의 시작에서 지정된 수의 줄을 건너뛰어요.
input_format_tsv_skip_trailing_empty_lines
TSV 포맷의 후행 빈 줄을 건너뛰어요.
input_format_tsv_use_best_effort_in_schema_inference
TSV 포맷에서 스키마를 추론할 때 몇 가지 트릭과 휴리스틱을 사용해요.
input_format_values_accurate_types_of_literals
Values 포맷: 템플릿을 사용해 표현식을 파싱하고 해석할 때, 리터럴의 실제 타입을 확인해 가능한 오버플로와 정밀도 문제를 피해요.
input_format_values_deduce_templates_of_expressions
Values 포맷: 필드가 스트리밍 파서로 파싱될 수 없으면, SQL 파서를 실행하고, SQL 표현식의 템플릿을 유도하고, 템플릿을 사용해 모든 행을 파싱한 다음 모든 행에 대해 표현식을 해석해요.
input_format_values_interpret_expressions
Values 포맷: 필드가 스트리밍 파서로 파싱될 수 없으면, SQL 파서를 실행하고 그것을 SQL 표현식으로 해석하려고 시도해요.
input_format_with_names_use_header
데이터를 삽입할 때 컬럼 순서 확인을 활성화 또는 비활성화해요.
삽입 성능을 높이려면, 입력 데이터의 컬럼 순서가 대상 테이블과 같다고 확신한다면 이 확인을 비활성화하는 것을 권장해요.
지원되는 포맷:
- CSVWithNames
- CSVWithNamesAndTypes
- TabSeparatedWithNames
- TabSeparatedWithNamesAndTypes
- JSONCompactEachRowWithNames
- JSONCompactEachRowWithNamesAndTypes
- JSONCompactStringsEachRowWithNames
- JSONCompactStringsEachRowWithNamesAndTypes
- RowBinaryWithNames
- RowBinaryWithNamesAndTypes
- CustomSeparatedWithNames
- CustomSeparatedWithNamesAndTypes
가능한 값:
- 0 — 비활성화.
- 1 — 활성화.
input_format_with_types_use_header
포맷 파서가 입력 데이터의 데이터 타입이 대상 테이블의 데이터 타입과 일치하는지 확인할지 여부를 제어해요.
지원되는 포맷:
- CSVWithNamesAndTypes
- TabSeparatedWithNamesAndTypes
- JSONCompactEachRowWithNamesAndTypes
- JSONCompactStringsEachRowWithNamesAndTypes
- RowBinaryWithNamesAndTypes
- CustomSeparatedWithNamesAndTypes
가능한 값:
- 0 — 비활성화.
- 1 — 활성화.