스키마 구성

스키마 구성 (Schema Configuration)

Apache Pinot 스키마 구성 레퍼런스 문서예요.

출처: 문서

본문

이 페이지는 Pinot 스키마 JSON의 평면 레퍼런스예요. 최상위 스키마 객체, 필드 스펙 테이블, null 처리 규칙, 날짜-시간 형식, MAP 및 OPEN_STRUCT 지원, 고급 컬럼 옵션을 한 곳에 모아 담고 있어요.

핵심 영역 (Key Areas)

영역	다루는 내용	이동
Schema object	최상위 스키마 필드와 완전한 예시	Schema object
Field specs	차원, 메트릭, 날짜-시간 컬럼 정의	Field specs
Null handling	`enableColumnBasedNullHandling`과 기본 null 값	Null handling
Complex fields	`MAP` 및 `OPEN_STRUCT` 컬럼 + `childFieldSpecs`	ComplexFieldSpecs
Date-time formats	새 형식과 레거시 형식 문법	Date-time formats

스키마 객체 (Schema object)

Pinot 스키마는 테이블의 컬럼(필드)을 정의하는 JSON 문서예요. 각 테이블은 하나의 스키마를 가지며 스키마 이름은 테이블 이름과 일치해야 해요(유형 접미사 제외).

최상위 스키마 객체의 주요 필드는 다음과 같아요:

필드	설명
schemaName	스키마의 이름. 테이블 이름과 일치해야 해요(예: `myTable`).
schemaType	스키마 유형. 보통 `PINOT`이며, `MAP`/`OPEN_STRUCT` 컬럼을 포함할 때 `PINOT`(concrete) 또는 `PINOT_LITE`일 수 있어요.
dimensionFieldSpecs	차원 컬럼 정의 목록.
metricFieldSpecs	메트릭 컬럼 정의 목록.
dateTimeFieldSpecs	날짜-시간 컬럼 정의 목록.
complexFieldSpecs	`MAP` 및 `OPEN_STRUCT` 같은 복합 컬럼 정의 목록.
primaryKeyColumns	기본 키로 사용할 컬럼 이름 목록. upsert 테이블에 필수.
enableColumnBasedNullHandling	컬럼별 null 처리를 활성화할지 여부. 기본 `false`.

필드 스펙 (Field specs)

각 필드 스펙(FieldSpec)에는 name, dataType이 있으며 유형에 따라 singleValueField, defaultNullValue, maxLength 등이 있습니다.

차원/메트릭/날짜-시간 필드 스펙 공통 속성

속성	설명
name	컬럼(필드) 이름. 스키마 내에서 고유해야 해요.
dataType	필드의 데이터 타입. 지원 값: `INT`, `LONG`, `FLOAT`, `DOUBLE`, `BOOLEAN`, `TIMESTAMP`, `STRING`, `BYTES`, `BIG_DECIMAL`, `JSON`, `MAP`, `OPEN_STRUCT` 등.
singleValueField	단일 값 필드인지 여부. `false`면 다중 값(MV) 필드. 기본 `true`.
defaultNullValue	필드의 null 대체 기본값.

Date-time 필드 스펙

날짜-시간 필드는 시간 컬럼으로 사용되며 다음 속성을 가져요:

속성	설명
name	컬럼 이름.
dataType	`TIMESTAMP` 또는 숫자 타입. `TIMESTAMP`는 표준이고 기존 형식은 `INT`/`LONG`에 `EPOCH`/`SIMPLEDATE` 형식.
format	형식 문자열, 예: `1:MILLISECONDS:EPOCH`(기존), 또는 `EPOCH
granularity	세분성, 예: `1:MILLISECONDS`.
dateTimeFormat (legacy)	레거시 구간-콜론 형식 지정.
dateTimeType (legacy)	레거시 형식의 시간 유형.

Null handling

Pinot은 기본적으로 모든 컬럼에 대해 단일 전역 null 값 처리 모드를 사용해요. enableColumnBasedNullHandling을 true로 설정하면 컬럼별로 null 값을 저장하고 처리하는 정밀한 방법을 활성화할 수 있어요.

속성	설명
enableColumnBasedNullHandling	`true`이면 null 값이 컬럼에 명시적으로 저장되고 쿼리에서 `IS NULL`/`IS NOT NULL` 연산자와 null 안전 함수를 사용할 수 있어요.
defaultNullValue	컬럼 기반 null 처리를 사용하지 않을 때 null 대신 저장되는 기본 값.

자세한 내용은 null value support를 참고하세요.

ComplexFieldSpecs (복합 필드)

Pinot은 컬럼이 반구조화 또는 중첩 데이터를 저장할 수 있게 MAP과 OPEN_STRUCT 데이터 타입을 지원해요.

MAP: 키-값 쌍의 컬렉션. childFieldSpecs로 키-값 필드를 정의해요. 일반적으로 MAP<String, T> 로 구성돼요.

OPEN_STRUCT: 반구조화 객체를 하나의 컬럼에 저장하지만 자주 사용하는 키를 표준 Pinot 컬럼으로 구체화할 수 있어요. dense 키는 <column>$<key> 자식 컬럼이 되고, 나머지 키는 <column>$__sparse__ 희소 JSON 컬럼으로 기록돼요.

속성	설명
name	복합 필드 이름.
dataType	`MAP` 또는 `OPEN_STRUCT`.
childFieldSpecs	복합 필드의 자식 필드 정의 목록. 각 자식은 `name`, `dataType`(및 선택적 `singleValueField`, `defaultNullValue`)를 가짐.
fieldsNotToIndex	인덱싱에서 제외할 자식 필드 이름 목록.

Date-time formats

Pinot은 새 형식 문법과 레거시 구간-콜론 문법을 지원해요.

새 형식: EPOCH|TIME_UNIT 형식, 예: EPOCH|MILLISECONDS, EPOCH|SECONDS. TIMESTAMP 타입은 내부적으로 마이크로초 에포크로 저장돼요.

레거시 형식: NUMBER_OF_UNITS:UNIT:TYPE 형식, 예: 1:MILLISECONDS:EPOCH 또는 1:DAYS:SIMPLE_DATE_FORMAT:yyyyMMdd. 구간은 시간 계산에 사용되고 기본 단위는 저장 단위예요.

고급 컬럼 옵션

옵션	설명
maxLength	`STRING` 및 `BYTES` 컬럼의 최대 길이. 고정 길이 사전/length-preprended 인덱스에 사용.
singleValueField	필드가 단일 값(MV가 아닌)인지 여부.
virtualColumnProvider	가상 컬럼 공급자 클래스(예: `$docId`, `$segmentName` 같은 특수 컬럼).
&& (물리적)	특수 컬럼용으로 `metadataManagerProvider` 등의 옵션.

자세한 내용과 완전한 스키마 예시는 Pinot schema 페이지를 참고하세요.

스키마 구성