C API 타입

C API 타입 (Types)

DuckDB는 강타입(strongly typed) 데이터베이스 시스템이에요. 그래서 모든 열에는 단일 타입이 지정돼요. 이 타입은 열 전체에 걸쳐 일정해요. 즉 INTEGER 열로 표시된 열에는 INTEGER 값만 들어간다는 뜻이에요.

DuckDB는 복합 타입(composite type)의 열도 지원해요. 예를 들어 정수 배열(INTEGER[])을 정의할 수 있고, 임의의 struct(ROW(i INTEGER, j VARCHAR))로 타입을 정의할 수도 있어요. 이런 이유로 네이티브 DuckDB 타입 객체는 단순한 enum이 아니라, 잠재적으로 중첩될 수 있는 클래스예요.

C API의 타입은 enum(duckdb_type)과 복합 클래스(duckdb_logical_type)로 모델링돼요. 대부분의 기본 타입(예: 정수, varchar)에는 enum으로 충분해요. 리스트, struct, decimal 같은 더 복잡한 타입에는 logical type을 사용해야 해요.

typedef enum DUCKDB_TYPE {
  DUCKDB_TYPE_INVALID = 0,
  DUCKDB_TYPE_BOOLEAN = 1,
  DUCKDB_TYPE_TINYINT = 2,
  DUCKDB_TYPE_SMALLINT = 3,
  DUCKDB_TYPE_INTEGER = 4,
  DUCKDB_TYPE_BIGINT = 5,
  DUCKDB_TYPE_UTINYINT = 6,
  DUCKDB_TYPE_USMALLINT = 7,
  DUCKDB_TYPE_UINTEGER = 8,
  DUCKDB_TYPE_UBIGINT = 9,
  DUCKDB_TYPE_FLOAT = 10,
  DUCKDB_TYPE_DOUBLE = 11,
  DUCKDB_TYPE_TIMESTAMP = 12,
  DUCKDB_TYPE_DATE = 13,
  DUCKDB_TYPE_TIME = 14,
  DUCKDB_TYPE_INTERVAL = 15,
  DUCKDB_TYPE_HUGEINT = 16,
  DUCKDB_TYPE_UHUGEINT = 32,
  DUCKDB_TYPE_VARCHAR = 17,
  DUCKDB_TYPE_BLOB = 18,
  DUCKDB_TYPE_DECIMAL = 19,
  DUCKDB_TYPE_TIMESTAMP_S = 20,
  DUCKDB_TYPE_TIMESTAMP_MS = 21,
  DUCKDB_TYPE_TIMESTAMP_NS = 22,
  DUCKDB_TYPE_ENUM = 23,
  DUCKDB_TYPE_LIST = 24,
  DUCKDB_TYPE_STRUCT = 25,
  DUCKDB_TYPE_MAP = 26,
  DUCKDB_TYPE_ARRAY = 33,
  DUCKDB_TYPE_UUID = 27,
  DUCKDB_TYPE_UNION = 28,
  DUCKDB_TYPE_BIT = 29,
  DUCKDB_TYPE_TIME_TZ = 30,
  DUCKDB_TYPE_TIMESTAMP_TZ = 31,
} duckdb_type;

출처: 문서

본문

함수 (Functions)

결과에서 열의 enum 타입은 duckdb_column_type 함수로 얻을 수 있고, 열의 logical type은 duckdb_column_logical_type 함수로 얻을 수 있어요.

duckdb_value

duckdb_value 함수는 필요에 따라 값을 자동 캐스팅해요. 예를 들어 duckdb_value_int32 타입 열에 duckdb_value_double을 사용해도 문제없어요. 값이 자동 캐스팅되어 double로 반환돼요. 다만 특정 경우에는 캐스트가 실패할 수 있다는 점에 유의해요. 예를 들어 duckdb_value_int8을 요청했는데 값이 int8에 맞지 않으면 그런 일이 생길 수 있어요. 이 경우 기본값(보통 0 또는 nullptr)이 반환돼요. 해당 값이 NULL일 때도 같은 기본값이 반환돼요.

특정 값이 NULL인지 아닌지는 duckdb_value_is_null 함수로 확인할 수 있어요.

자동 캐스팅 규칙의 예외는 duckdb_value_varchar_internal 함수예요. 이 함수는 자동 캐스팅하지 않고 VARCHAR 열에서만 동작해요. 이 함수가 존재하는 이유는 결과를 해제(free)할 필요가 없기 때문이에요.

duckdb_value_varchar와 duckdb_value_blob은 결과물을 duckdb_free로 해제해야 해요.

duckdb_fetch_chunk

duckdb_fetch_chunk 함수는 DuckDB 결과 집합에서 데이터 청크를 읽는 데 사용할 수 있고, C API로 DuckDB 결과에서 데이터를 읽는 가장 효율적인 방법이에요. 또한 특정 타입의 데이터를 DuckDB 결과에서 읽는 유일한 방법이기도 해요. 예를 들어 duckdb_value 함수들은 복합 타입(리스트나 struct)이나 enum·decimal 같은 더 복잡한 타입의 구조적 읽기를 지원하지 않아요.

데이터 청크에 대한 자세한 내용은 데이터 청크 문서를 참고해요.

API 참조 개요 (API Reference Overview)

이 섹션은 스크립트(scripts/generate_c_api_docs.py)로 생성되며, 각 함수의 시그니처와 설명·파라미터·반환값을 담고 있어요. 주요 그룹은 다음과 같아요:

• 결과 관련: duckdb_result_get_chunk, duckdb_result_is_streaming, duckdb_result_chunk_count, duckdb_result_return_type
• 날짜·시간·타임스탬프 헬퍼 (Date Time Timestamp Helpers): duckdb_from_date, duckdb_to_date, duckdb_is_finite_date, duckdb_from_time, duckdb_create_time_tz, duckdb_from_time_tz, duckdb_to_time, duckdb_from_timestamp, duckdb_to_timestamp, duckdb_is_finite_timestamp, duckdb_is_finite_timestamp_s, duckdb_is_finite_timestamp_ms, duckdb_is_finite_timestamp_ns
• Hugeint 헬퍼 (Hugeint Helpers): duckdb_hugeint_to_double, duckdb_double_to_hugeint
• Decimal 헬퍼 (Decimal Helpers): duckdb_double_to_decimal, duckdb_decimal_to_double
• Logical Type 인터페이스 (Logical Type Interface): duckdb_create_logical_type, duckdb_logical_type_get_alias, duckdb_logical_type_set_alias, duckdb_create_list_type, duckdb_create_array_type, duckdb_create_map_type, duckdb_create_union_type, duckdb_create_struct_type, duckdb_create_enum_type, duckdb_create_decimal_type, duckdb_get_type_id, duckdb_decimal_width, duckdb_decimal_scale, duckdb_decimal_internal_type, duckdb_enum_internal_type, duckdb_enum_dictionary_size, duckdb_enum_dictionary_value, duckdb_list_type_child_type, duckdb_array_type_child_type, duckdb_array_type_array_size, duckdb_map_type_key_type, duckdb_map_type_value_type, duckdb_struct_type_child_count, duckdb_struct_type_child_name, duckdb_struct_type_child_type, duckdb_union_type_member_count, duckdb_union_type_member_name, duckdb_union_type_member_type, duckdb_destroy_logical_type, duckdb_register_logical_type

이 자동 생성 참조의 대표적인 함수 설명 몇 개를 살펴볼게요.

duckdb_result_get_chunk

경고 Deprecation 공지. 이 메서드는 향후 릴리스에서 제거될 예정이에요.

duckdb_result에서 데이터 청크를 가져와요. 이 함수는 결과가 소진될 때까지 반복 호출해야 해요.

결과는 duckdb_destroy_data_chunk로 파괴해야 해요.

이 함수는 모든 duckdb_value 함수와 duckdb_column_data·duckdb_nullmask_data 함수를 대체해요. 성능이 훨씬 좋으므로 새 코드베이스에서는 이 함수를 선호해야 해요.

이 함수를 사용하면 다른 결과 함수는 사용할 수 없고 그 반대도 마찬가지예요(즉, 이 함수를 레거시 결과 함수와 섞을 수 없어요).

결과에 청크가 몇 개 있는지 알아내려면 duckdb_result_chunk_count를 사용해요.

duckdb_data_chunk duckdb_result_get_chunk(duckdb_result result, idx_t chunk_index);

파라미터:

• result: 데이터 청크를 가져올 결과 객체.
• chunk_index: 가져올 청크 인덱스.

반환값: 결과 데이터 청크. 청크 인덱스가 범위를 벗어나면 NULL을 반환해요.

duckdb_result_return_type

주어진 결과의 return_type을 반환하고, 오류가 있으면 DUCKDB_RETURN_TYPE_INVALID를 반환해요.

duckdb_result_type duckdb_result_return_type(duckdb_result result);

파라미터:

• result: 결과 객체.

반환값: return_type.

duckdb_from_date

duckdb_date 객체를 연·월·일로 분해해요(duckdb_date_struct로 저장).

duckdb_date_struct duckdb_from_date(duckdb_date date);

파라미터:

• date: DUCKDB_TYPE_DATE 열에서 얻은 날짜 객체.

반환값: 분해된 요소를 가진 duckdb_date_struct.

duckdb_to_date

연·월·일(duckdb_date_struct)로 duckdb_date를 재구성해요.

duckdb_date duckdb_to_date(duckdb_date_struct date);

파라미터:

• date: duckdb_date_struct에 저장된 연·월·일.

반환값: duckdb_date 요소.

duckdb_is_finite_date

duckdb_date가 유한(finite) 값인지 검사해요.

bool duckdb_is_finite_date(duckdb_date date);

파라미터:

• date: DUCKDB_TYPE_DATE 열에서 얻은 날짜 객체.

반환값: 날짜가 유한하면 true, ±무한이면 false.

duckdb_from_time_tz

TIME_TZ 객체를 micros와 타임존 오프셋으로 분해해요. micros를 시·분·초·마이크로초로 더 분해하려면 duckdb_from_time을 사용해요.

duckdb_time_tz_struct duckdb_from_time_tz(duckdb_time_tz micros);

파라미터:

• micros: DUCKDB_TYPE_TIME_TZ 열에서 얻은 시간 객체.

duckdb_create_logical_type

주어진 타입으로 logical type을 생성해요.

duckdb_logical_type duckdb_create_logical_type(duckdb_type type);

duckdb_get_type_id

logical type의 duckdb_type id를 반환해요.

duckdb_type duckdb_get_type_id(duckdb_logical_type type);

파라미터:

• type: logical type 객체.

duckdb_destroy_logical_type

logical type을 파괴하고 해당 타입에 할당된 모든 메모리를 해제해요.

void duckdb_destroy_logical_type(duckdb_logical_type *type);

파라미터:

• type: 파괴할 logical type.

duckdb_register_logical_type

주어진 연결 내에서 커스텀 타입을 등록해요. 타입에는 별칭(alias)이 있어야 해요.

duckdb_state duckdb_register_logical_type(duckdb_connection con, duckdb_logical_type type, duckdb_create_type_info info);

파라미터:

• con: 사용할 연결.
• type: 등록할 커스텀 타입.

반환값: 등록 성공 여부.

이 자동 생성 API 참조의 나머지 함수들도 같은 패턴을 따라요: 각 함수는 시그니처, 설명, 파라미터, 반환값을 담고 있어요. 전체 세부 사항은 공식 C API 참조에서 확인할 수 있어요.

더 알아보기 (Learn more)

• C API 개요
• 데이터 청크 (Data Chunk)
• C API 값 (Value)