테이블 함수

테이블 함수 API는 DuckDB 내에서 쿼리의 FROM 절에서 호출할 수 있는 테이블 함수를 정의할 때 사용해요. C API로 직접 확장 기능을 만들 때 아주 유용하답니다.

출처: 문서

본문

이 문서는 C API의 테이블 함수 관련 함수들(bind, init, 실행)의 전체 시그니처와 각 파라미터·반환값을 정리한 레퍼런스예요.

API 레퍼런스 개요

duckdb_table_function duckdb_create_table_function();
void duckdb_destroy_table_function(duckdb_table_function *table_function);
void duckdb_table_function_set_name(duckdb_table_function table_function, const char *name);
void duckdb_table_function_add_parameter(duckdb_table_function table_function, duckdb_logical_type type);
void duckdb_table_function_add_named_parameter(duckdb_table_function table_function, const char *name, duckdb_logical_type type);
void duckdb_table_function_set_extra_info(duckdb_table_function table_function, void *extra_info, duckdb_delete_callback_t destroy);
void duckdb_table_function_set_bind(duckdb_table_function table_function, duckdb_table_function_bind_t bind);
void duckdb_table_function_set_init(duckdb_table_function table_function, duckdb_table_function_init_t init);
void duckdb_table_function_set_local_init(duckdb_table_function table_function, duckdb_table_function_init_t init);
void duckdb_table_function_set_function(duckdb_table_function table_function, duckdb_table_function_t function);
void duckdb_table_function_supports_projection_pushdown(duckdb_table_function table_function, bool pushdown);
duckdb_state duckdb_register_table_function(duckdb_connection con, duckdb_table_function function);

테이블 함수 Bind

void *duckdb_bind_get_extra_info(duckdb_bind_info info);
void duckdb_table_function_get_client_context(duckdb_bind_info info, duckdb_client_context *out_context);
void duckdb_bind_add_result_column(duckdb_bind_info info, const char *name, duckdb_logical_type type);
idx_t duckdb_bind_get_parameter_count(duckdb_bind_info info);
duckdb_value duckdb_bind_get_parameter(duckdb_bind_info info, idx_t index);
duckdb_value duckdb_bind_get_named_parameter(duckdb_bind_info info, const char *name);
void duckdb_bind_set_bind_data(duckdb_bind_info info, void *bind_data, duckdb_delete_callback_t destroy);
void duckdb_bind_set_cardinality(duckdb_bind_info info, idx_t cardinality, bool is_exact);
void duckdb_bind_set_error(duckdb_bind_info info, const char *error);

테이블 함수 Init

void *duckdb_init_get_extra_info(duckdb_init_info info);
void *duckdb_init_get_bind_data(duckdb_init_info info);
void duckdb_init_set_init_data(duckdb_init_info info, void *init_data, duckdb_delete_callback_t destroy);
idx_t duckdb_init_get_column_count(duckdb_init_info info);
idx_t duckdb_init_get_column_index(duckdb_init_info info, idx_t column_index);
void duckdb_init_set_max_threads(duckdb_init_info info, idx_t max_threads);
void duckdb_init_set_error(duckdb_init_info info, const char *error);

테이블 함수

void *duckdb_function_get_extra_info(duckdb_function_info info);
void *duckdb_function_get_bind_data(duckdb_function_info info);
void *duckdb_function_get_init_data(duckdb_function_info info);
void *duckdb_function_get_local_init_data(duckdb_function_info info);
void duckdb_function_set_error(duckdb_function_info info, const char *error);

`duckdb_create_table_function`

새 빈 테이블 함수를 생성해요.

반환값은 duckdb_destroy_table_function으로 파괴해야 해요.

반환값

테이블 함수 객체.

문법

duckdb_table_function duckdb_create_table_function(
  
);

`duckdb_destroy_table_function`

주어진 테이블 함수 객체를 파괴해요.

문법

void duckdb_destroy_table_function(
  duckdb_table_function *table_function
);

파라미터

table_function: 파괴할 테이블 함수

`duckdb_table_function_set_name`

주어진 테이블 함수의 이름을 설정해요.

문법

void duckdb_table_function_set_name(
  duckdb_table_function table_function,
  const char *name
);

파라미터

table_function: 테이블 함수
name: 테이블 함수의 이름

`duckdb_table_function_add_parameter`

테이블 함수에 파라미터를 추가해요.

문법

void duckdb_table_function_add_parameter(
  duckdb_table_function table_function,
  duckdb_logical_type type
);

파라미터

table_function: 테이블 함수.
type: 파라미터 타입. INVALID를 포함할 수 없음.

`duckdb_table_function_add_named_parameter`

테이블 함수에 명명된 파라미터를 추가해요.

문법

void duckdb_table_function_add_named_parameter(
  duckdb_table_function table_function,
  const char *name,
  duckdb_logical_type type
);

파라미터

table_function: 테이블 함수.
name: 파라미터 이름.
type: 파라미터 타입. INVALID를 포함할 수 없음.

`duckdb_table_function_set_extra_info`

테이블 함수에 바인딩 중 등에 가져올 수 있는 추가 정보를 할당해요.

문법

void duckdb_table_function_set_extra_info(
  duckdb_table_function table_function,
  void *extra_info,
  duckdb_delete_callback_t destroy
);

파라미터

table_function: 테이블 함수
extra_info: 추가 정보
destroy: 추가 정보를 파괴하기 위해 호출될 콜백 (있을 경우)

`duckdb_table_function_set_bind`

테이블 함수의 bind 함수를 설정해요.

문법

void duckdb_table_function_set_bind(
  duckdb_table_function table_function,
  duckdb_table_function_bind_t bind
);

파라미터

table_function: 테이블 함수
bind: bind 함수

`duckdb_table_function_set_init`

테이블 함수의 init 함수를 설정해요.

문법

void duckdb_table_function_set_init(
  duckdb_table_function table_function,
  duckdb_table_function_init_t init
);

파라미터

table_function: 테이블 함수
init: init 함수

`duckdb_table_function_set_local_init`

테이블 함수의 스레드 로컬 init 함수를 설정해요.

문법

void duckdb_table_function_set_local_init(
  duckdb_table_function table_function,
  duckdb_table_function_init_t init
);

파라미터

table_function: 테이블 함수
init: init 함수

`duckdb_table_function_set_function`

테이블 함수의 메인 함수를 설정해요.

문법

void duckdb_table_function_set_function(
  duckdb_table_function table_function,
  duckdb_table_function_t function
);

파라미터

table_function: 테이블 함수
function: 함수

`duckdb_table_function_supports_projection_pushdown`

주어진 테이블 함수가 프로젝션 푸시다운을 지원하는지 여부를 설정해요.

true로 설정하면 시스템이 init 단계에서 duckdb_init_get_column_count와 duckdb_init_get_column_index 함수를 통해 모든 필수 컬럼 목록을 제공해요. false(기본값)로 설정하면 모든 컬럼이 투영될 것으로 기대해요.

문법

void duckdb_table_function_supports_projection_pushdown(
  duckdb_table_function table_function,
  bool pushdown
);

파라미터

table_function: 테이블 함수
pushdown: 테이블 함수가 프로젝션 푸시다운을 지원하면 true, 그렇지 않으면 false.

`duckdb_register_table_function`

주어진 연결 내에 테이블 함수 객체를 등록해요.

이 함수는 최소한 이름, bind 함수, init 함수, 메인 함수가 필요해요.

함수가 불완전하거나 이 이름의 함수가 이미 존재하면 DuckDBError가 반환돼요.

문법

duckdb_state duckdb_register_table_function(
  duckdb_connection con,
  duckdb_table_function function
);

파라미터

con: 등록할 연결.
function: 함수 포인터

반환값

등록이 성공했는지 여부.

`duckdb_bind_get_extra_info`

duckdb_table_function_set_extra_info에서 설정한 함수의 추가 정보를 검색해요.

문법

void *duckdb_bind_get_extra_info(
  duckdb_bind_info info
);

파라미터

info: info 객체

반환값

추가 정보

`duckdb_table_function_get_client_context`

테이블 함수의 bind info의 클라이언트 컨텍스트를 검색해요.

문법

void duckdb_table_function_get_client_context(
  duckdb_bind_info info,
  duckdb_client_context *out_context
);

파라미터

info: 테이블 함수의 bind info 객체.
out_context: bind info의 클라이언트 컨텍스트. duckdb_destroy_client_context로 파괴해야 해요.

`duckdb_bind_add_result_column`

테이블 함수의 출력에 결과 컬럼을 추가해요.

문법

void duckdb_bind_add_result_column(
  duckdb_bind_info info,
  const char *name,
  duckdb_logical_type type
);

파라미터

info: 테이블 함수의 bind info.
name: 컬럼 이름.
type: 논리 컬럼 타입.

`duckdb_bind_get_parameter_count`

함수의 일반(비-명명) 파라미터 수를 검색해요.

문법

idx_t duckdb_bind_get_parameter_count(
  duckdb_bind_info info
);

파라미터

info: info 객체

반환값

파라미터 수

`duckdb_bind_get_parameter`

주어진 인덱스의 파라미터를 검색해요.

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

문법

duckdb_value duckdb_bind_get_parameter(
  duckdb_bind_info info,
  idx_t index
);

파라미터

info: info 객체
index: 가져올 파라미터의 인덱스

반환값

파라미터의 값. duckdb_destroy_value로 파괴해야 해요.

`duckdb_bind_get_named_parameter`

주어진 이름의 명명된 파라미터를 검색해요.

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

문법

duckdb_value duckdb_bind_get_named_parameter(
  duckdb_bind_info info,
  const char *name
);

파라미터

info: info 객체
name: 파라미터 이름

반환값

파라미터의 값. duckdb_destroy_value로 파괴해야 해요.

`duckdb_bind_set_bind_data`

테이블 함수의 bind 객체에 사용자 제공 bind 데이터를 설정해요. 이 객체는 실행 중에 다시 검색할 수 있어요.

문법

void duckdb_bind_set_bind_data(
  duckdb_bind_info info,
  void *bind_data,
  duckdb_delete_callback_t destroy
);

파라미터

info: 테이블 함수의 bind info.
bind_data: bind 데이터 객체.
destroy: bind 데이터를 파괴할 콜백 (있을 경우).

`duckdb_bind_set_cardinality`

최적화에 사용되는 테이블 함수의 카디널리티 추정치를 설정해요.

문법

void duckdb_bind_set_cardinality(
  duckdb_bind_info info,
  idx_t cardinality,
  bool is_exact
);

파라미터

info: bind 데이터 객체.
is_exact: 카디널리티 추정치가 정확한지, 아니면 근사치인지 여부

`duckdb_bind_set_error`

테이블 함수에 bind를 호출하는 동안 오류가 발생했음을 보고해요.

문법

void duckdb_bind_set_error(
  duckdb_bind_info info,
  const char *error
);

파라미터

info: info 객체
error: 오류 메시지

`duckdb_init_get_extra_info`

duckdb_table_function_set_extra_info에서 설정한 함수의 추가 정보를 검색해요.

문법

void *duckdb_init_get_extra_info(
  duckdb_init_info info
);

파라미터

info: info 객체

반환값

추가 정보

`duckdb_init_get_bind_data`

bind 중에 duckdb_bind_set_bind_data가 설정한 bind 데이터를 가져와요.

bind 데이터는 읽기 전용으로 간주해야 한다는 점에 주의하세요. 상태 추적에는 대신 init 데이터를 사용하세요.

문법

void *duckdb_init_get_bind_data(
  duckdb_init_info info
);

파라미터

info: info 객체

반환값

bind 데이터 객체

`duckdb_init_set_init_data`

init 객체에 사용자 제공 init 데이터를 설정해요. 이 객체는 실행 중에 다시 검색할 수 있어요.

문법

void duckdb_init_set_init_data(
  duckdb_init_info info,
  void *init_data,
  duckdb_delete_callback_t destroy
);

파라미터

info: info 객체
init_data: init 데이터 객체.
destroy: init 데이터를 파괴하기 위해 호출될 콜백 (있을 경우)

`duckdb_init_get_column_count`

투영된 컬럼 수를 반환해요.

이 함수는 프로젝션 푸시다운이 활성화된 경우 어떤 컬럼을 내보낼지 알아내기 위해 사용해야 해요.

문법

idx_t duckdb_init_get_column_count(
  duckdb_init_info info
);

파라미터

info: info 객체

반환값

투영된 컬럼 수.

`duckdb_init_get_column_index`

지정된 위치의 투영된 컬럼의 컬럼 인덱스를 반환해요.

이 함수는 프로젝션 푸시다운이 활성화된 경우 어떤 컬럼을 내보낼지 알아내기 위해 사용해야 해요.

문법

idx_t duckdb_init_get_column_index(
  duckdb_init_info info,
  idx_t column_index
);

파라미터

info: info 객체
column_index: 투영된 컬럼 인덱스를 가져올 위치, 0..duckdb_init_get_column_count(info)

반환값

투영된 컬럼의 컬럼 인덱스.

`duckdb_init_set_max_threads`

이 테이블 함수를 병렬로 처리할 수 있는 스레드 수를 설정해요 (기본값: 1)

문법

void duckdb_init_set_max_threads(
  duckdb_init_info info,
  idx_t max_threads
);

파라미터

info: info 객체
max_threads: 이 테이블 함수를 처리할 수 있는 최대 스레드 수

`duckdb_init_set_error`

init 호출 중에 오류가 발생했음을 보고해요.

문법

void duckdb_init_set_error(
  duckdb_init_info info,
  const char *error
);

파라미터

info: info 객체
error: 오류 메시지

`duckdb_function_get_extra_info`

duckdb_table_function_set_extra_info에서 설정한 함수의 추가 정보를 검색해요.

문법

void *duckdb_function_get_extra_info(
  duckdb_function_info info
);

파라미터

info: info 객체

반환값

추가 정보

`duckdb_function_get_bind_data`

duckdb_bind_set_bind_data가 설정한 테이블 함수의 bind 데이터를 가져와요.

bind 데이터는 읽기 전용이라는 점에 주의하세요. 상태 추적에는 대신 init 데이터를 사용하세요.

문법

void *duckdb_function_get_bind_data(
  duckdb_function_info info
);

파라미터

info: 함수 info 객체.

반환값

bind 데이터 객체.

`duckdb_function_get_init_data`

init 중에 duckdb_init_set_init_data가 설정한 init 데이터를 가져와요.

문법

void *duckdb_function_get_init_data(
  duckdb_function_info info
);

파라미터

info: info 객체

반환값

init 데이터 객체

`duckdb_function_get_local_init_data`

local_init 중에 duckdb_init_set_init_data가 설정한 스레드 로컬 init 데이터를 가져와요.

문법

void *duckdb_function_get_local_init_data(
  duckdb_function_info info
);

파라미터

info: info 객체

반환값

init 데이터 객체

`duckdb_function_set_error`

함수를 실행하는 동안 오류가 발생했음을 보고해요.

문법

void duckdb_function_set_error(
  duckdb_function_info info,
  const char *error
);

파라미터

info: info 객체
error: 오류 메시지

더 알아보기 (Learn more)

C 클라이언트 전반은 clients/c/overview 문서를 참고해 주세요.