Appender

Appender

Appender는 C 인터페이스에서 DuckDB로 데이터를 로드하는 가장 효율적인 방법이에요. 빠른 데이터 로딩에 권장되며, 준비된(prepared) statement나 개별 INSERT INTO 문보다 훨씬 빨라요.

출처: 문서

본문

Appender는 C 인터페이스에서 DuckDB로 데이터를 로드하는 가장 효율적인 방법이며, 빠른 데이터 로딩에 권장돼요. appender는 준비된(prepared) statement나 개별 INSERT INTO 문보다 훨씬 빨라요.

추가는 행 단위(row-wise) 형식으로 이뤄져요. 모든 컬럼에 대해 duckdb_append_[type] 호출을 한 뒤, duckdb_appender_end_row를 호출해 행을 마무리해요. 모든 행을 추가한 후에는 duckdb_appender_destroy를 사용해 appender를 마무리하고 결과 메모리를 정리해요.

duckdb_appender_destroy는 함수가 DuckDBError를 반환하더라도 항상 결과 appender에 호출해야 한다는 점에 주의해요.

예제

duckdb_query(con, "CREATE TABLE people (id INTEGER, name VARCHAR)", NULL);

duckdb_appender appender;
if (duckdb_appender_create(con, NULL, "people", &appender) == DuckDBError) {
  // handle error
}
// append the first row (1, Mark)
duckdb_append_int32(appender, 1);
duckdb_append_varchar(appender, "Mark");
duckdb_appender_end_row(appender);

// append the second row (2, Hannes)
duckdb_append_int32(appender, 2);
duckdb_append_varchar(appender, "Hannes");
duckdb_appender_end_row(appender);

// finish appending and flush all the rows to the table
duckdb_appender_destroy(&appender);

API 레퍼런스 개요

duckdb_appender_create

appender 객체를 생성해요. 객체는 duckdb_appender_destroy로 파괴해야 해요.

  • 시그니처: duckdb_state duckdb_appender_create(duckdb_connection connection, const char *schema, const char *table, duckdb_appender *out_appender)
  • 파라미터:
    • connection: appender를 생성할 커넥션 컨텍스트
    • schema: 추가할 테이블의 스키마, 기본 스키마라면 nullptr
    • table: 추가할 테이블명
    • out_appender: 생성된 appender 객체
  • 반환값: 성공 시 DuckDBSuccess, 실패 시 DuckDBError

duckdb_appender_create_ext

appender 객체를 생성해요. 객체는 duckdb_appender_destroy로 파괴해야 해요.

  • 시그니처: duckdb_state duckdb_appender_create_ext(duckdb_connection connection, const char *catalog, const char *schema, const char *table, duckdb_appender *out_appender)
  • 파라미터: connection, catalog(기본 카탈로그라면 nullptr), schema(기본 스키마라면 nullptr), table, out_appender
  • 반환값: 성공 시 DuckDBSuccess, 실패 시 DuckDBError

duckdb_appender_create_query

추가된 데이터로 주어진 쿼리를 실행하는 appender 객체를 생성해요. 객체는 duckdb_appender_destroy로 파괴해야 해요.

  • 시그니처: duckdb_state duckdb_appender_create_query(duckdb_connection connection, const char *query, idx_t column_count, duckdb_logical_type *types, const char *table_name, const char **column_names, duckdb_appender *out_appender)
  • 파라미터:
    • connection: appender를 생성할 커넥션 컨텍스트
    • query: 실행할 쿼리. INSERT, DELETE, UPDATE 또는 MERGE INTO 문일 수 있음
    • column_count: 추가할 컬럼 수
    • types: 추가할 컬럼의 타입
    • table_name: (선택) 추가된 데이터를 참조하는 테이블명, 기본값 "appended_data"
    • column_names: (선택) 컬럼 이름 목록, 기본값 "col1", "col2", ...
    • out_appender: 생성된 appender 객체
  • 반환값: 성공 시 DuckDBSuccess, 실패 시 DuckDBError

duckdb_appender_column_count

appender에 속한 컬럼 수를 반환해요. 활성 컬럼 목록이 없으면 테이블의 물리적 컬럼 수와 같아요.

  • 시그니처: idx_t duckdb_appender_column_count(duckdb_appender appender)
  • 파라미터: appender — 컬럼 수를 구할 appender
  • 반환값: 데이터 청크의 컬럼 수

duckdb_appender_column_type

지정한 인덱스의 컬럼 타입을 반환해요. 활성 컬럼 목록의 타입이거나 수신 테이블의 컬럼 타입이에요. 결과 타입은 duckdb_destroy_logical_type로 파괴해야 해요.

  • 시그니처: duckdb_logical_type duckdb_appender_column_type(duckdb_appender appender, idx_t col_idx)
  • 파라미터: appender, col_idx(타입을 구할 컬럼 인덱스)
  • 반환값: 컬럼의 duckdb_logical_type

duckdb_appender_error

경고 폐기 예정 공지. 이 메서드는 향후 릴리스에서 제거될 예정이에요. duckdb_appender_error_data를 사용해요.

appender와 연관된 오류 메시지를 반환해요. 오류 메시지가 없으면 nullptr을 반환해요. 오류 메시지는 해제하면 안 되며, duckdb_appender_destroy 호출 시 할당이 해제돼요.

  • 시그니처: const char *duckdb_appender_error(duckdb_appender appender)
  • 반환값: 오류 메시지, 없으면 nullptr

duckdb_appender_error_data

appender와 연관된 오류 데이터를 반환해요. duckdb_destroy_error_data로 파괴해야 해요.

  • 시그니처: duckdb_error_data duckdb_appender_error_data(duckdb_appender appender)
  • 반환값: 오류 데이터

duckdb_appender_flush

appender를 테이블로 flush해 appender의 캐시를 비워요. 데이터를 flush할 때 제약 위반이나 다른 오류가 발생하면 모든 데이터가 무효화되고 이 함수는 DuckDBError를 반환해요. 더 이상 값을 추가할 수 없어요. 오류 데이터를 얻으려면 duckdb_appender_error_data를 호출한 뒤 무효화된 appender를 파괴하기 위해 duckdb_appender_destroy를 호출해요.

  • 시그니처: duckdb_state duckdb_appender_flush(duckdb_appender appender)
  • 반환값: 성공 시 DuckDBSuccess, 실패 시 DuckDBError

duckdb_appender_close

모든 중간 상태를 flush하고 추가를 마무리해 appender를 닫아요. 데이터를 flush할 때 제약 위반이나 다른 오류가 발생하면 모든 데이터가 무효화되고 이 함수는 DuckDBError를 반환해요. 오류 데이터를 얻으려면 duckdb_appender_error_data를 호출한 뒤 무효화된 appender를 파괴하기 위해 duckdb_appender_destroy를 호출해요.

  • 시그니처: duckdb_state duckdb_appender_close(duckdb_appender appender)
  • 반환값: 성공 시 DuckDBSuccess, 실패 시 DuckDBError

duckdb_appender_destroy

모든 중간 상태를 테이블로 flush하고 appender를 파괴해 닫아요. 이 함수는 appender와 연관된 모든 메모리를 할당 해제해요. 데이터를 flush할 때 제약 위반이 발생하면 모든 데이터가 무효화되고 이 함수는 DuckDBError를 반환해요. appender 파괴로 인해 duckdb_appender_error로 특정 오류 메시지를 얻는 것은 더 이상 불가능해요. 따라서 특정 오류에 대한 통찰이 필요하면 appender를 파괴하기 전에 duckdb_appender_close를 호출해요.

  • 시그니처: duckdb_state duckdb_appender_destroy(duckdb_appender *appender)
  • 반환값: 성공 시 DuckDBSuccess, 실패 시 DuckDBError

duckdb_appender_add_column

appender의 활성 컬럼 목록에 컬럼을 추가해요. 이전의 모든 데이터를 즉시 flush해요. 활성 컬럼 목록은 데이터를 flush할 때 기대되는 모든 컬럼을 지정해요. 비활성 컬럼은 기본값 또는 NULL로 채워져요.

  • 시그니처: duckdb_state duckdb_appender_add_column(duckdb_appender appender, const char *name)
  • 반환값: 성공 시 DuckDBSuccess, 실패 시 DuckDBError

duckdb_appender_clear_columns

appender의 활성 컬럼 목록에서 모든 컬럼을 제거하고 모든 컬럼을 활성으로 취급하도록 리셋해요. 이전의 모든 데이터를 즉시 flush해요.

  • 시그니처: duckdb_state duckdb_appender_clear_columns(duckdb_appender appender)
  • 반환값: 성공 시 DuckDBSuccess, 실패 시 DuckDBError

duckdb_appender_begin_row

하위 호환성 이유로 제공되는 nop 함수예요. 아무것도 하지 않아요. duckdb_appender_end_row만 필요해요.

  • 시그니처: duckdb_state duckdb_appender_begin_row(duckdb_appender appender)

duckdb_appender_end_row

현재 행의 추가를 마무리해요. end_row 호출 후 다음 행을 추가할 수 있어요.

  • 시그니처: duckdb_state duckdb_appender_end_row(duckdb_appender appender)
  • 파라미터: appender
  • 반환값: 성공 시 DuckDBSuccess, 실패 시 DuckDBError

duckdb_append_default

appender에 DEFAULT 값을 추가해요 (컬럼에 DEFAULT가 없으면 NULL).

  • 시그니처: duckdb_state duckdb_append_default(duckdb_appender appender)

duckdb_append_default_to_chunk

지정한 appender에서 생성된 청크의 지정한 행·컬럼에 DEFAULT 값을 추가해요 (컬럼에 DEFAULT가 없으면 NULL). 컬럼의 기본값은 상수여야 해요. nextval('seq')나 random() 같은 비결정적 표현식은 지원되지 않아요.

  • 시그니처: duckdb_state duckdb_append_default_to_chunk(duckdb_appender appender, duckdb_data_chunk chunk, idx_t col, idx_t row)
  • 파라미터: appender(기본값을 가져올 appender), chunk(기본값을 추가할 데이터 청크), col(추가할 청크 컬럼 인덱스), row(추가할 청크 행 인덱스)
  • 반환값: 성공 시 DuckDBSuccess, 실패 시 DuckDBError

duckdb_append_bool

appender에 bool 값을 추가해요. 시그니처: duckdb_state duckdb_append_bool(duckdb_appender appender, bool value)

duckdb_append_int8

appender에 int8_t 값을 추가해요. 시그니처: duckdb_state duckdb_append_int8(duckdb_appender appender, int8_t value)

duckdb_append_int16

appender에 int16_t 값을 추가해요. 시그니처: duckdb_state duckdb_append_int16(duckdb_appender appender, int16_t value)

duckdb_append_int32

appender에 int32_t 값을 추가해요. 시그니처: duckdb_state duckdb_append_int32(duckdb_appender appender, int32_t value)

duckdb_append_int64

appender에 int64_t 값을 추가해요. 시그니처: duckdb_state duckdb_append_int64(duckdb_appender appender, int64_t value)

duckdb_append_hugeint

appender에 duckdb_hugeint 값을 추가해요. 시그니처: duckdb_state duckdb_append_hugeint(duckdb_appender appender, duckdb_hugeint value)

duckdb_append_uint8

appender에 uint8_t 값을 추가해요. 시그니처: duckdb_state duckdb_append_uint8(duckdb_appender appender, uint8_t value)

duckdb_append_uint16

appender에 uint16_t 값을 추가해요. 시그니처: duckdb_state duckdb_append_uint16(duckdb_appender appender, uint16_t value)

duckdb_append_uint32

appender에 uint32_t 값을 추가해요. 시그니처: duckdb_state duckdb_append_uint32(duckdb_appender appender, uint32_t value)

duckdb_append_uint64

appender에 uint64_t 값을 추가해요. 시그니처: duckdb_state duckdb_append_uint64(duckdb_appender appender, uint64_t value)

duckdb_append_uhugeint

appender에 duckdb_uhugeint 값을 추가해요. 시그니처: duckdb_state duckdb_append_uhugeint(duckdb_appender appender, duckdb_uhugeint value)

duckdb_append_float

appender에 float 값을 추가해요. 시그니처: duckdb_state duckdb_append_float(duckdb_appender appender, float value)

duckdb_append_double

appender에 double 값을 추가해요. 시그니처: duckdb_state duckdb_append_double(duckdb_appender appender, double value)

duckdb_append_date

appender에 duckdb_date 값을 추가해요. 시그니처: duckdb_state duckdb_append_date(duckdb_appender appender, duckdb_date value)

duckdb_append_time

appender에 duckdb_time 값을 추가해요. 시그니처: duckdb_state duckdb_append_time(duckdb_appender appender, duckdb_time value)

duckdb_append_timestamp

appender에 duckdb_timestamp 값을 추가해요. 시그니처: duckdb_state duckdb_append_timestamp(duckdb_appender appender, duckdb_timestamp value)

duckdb_append_interval

appender에 duckdb_interval 값을 추가해요. 시그니처: duckdb_state duckdb_append_interval(duckdb_appender appender, duckdb_interval value)

duckdb_append_varchar

appender에 varchar 값을 추가해요. 시그니처: duckdb_state duckdb_append_varchar(duckdb_appender appender, const char *val)

duckdb_append_varchar_length

appender에 varchar 값을 추가해요. 시그니처: duckdb_state duckdb_append_varchar_length(duckdb_appender appender, const char *val, idx_t length)

duckdb_append_blob

appender에 blob 값을 추가해요. 시그니처: duckdb_state duckdb_append_blob(duckdb_appender appender, const void *data, idx_t length)

duckdb_append_null

appender에 NULL 값을 추가해요 (어떤 타입이든). 시그니처: duckdb_state duckdb_append_null(duckdb_appender appender)

duckdb_append_value

appender에 duckdb_value를 추가해요. 시그니처: duckdb_state duckdb_append_value(duckdb_appender appender, duckdb_value value)

duckdb_append_data_chunk

미리 채워진 데이터 청크를 지정한 appender에 추가해요. 데이터 청크 타입이 활성 appender 타입과 일치하지 않으면 casting을 시도해요.

  • 시그니처: duckdb_state duckdb_append_data_chunk(duckdb_appender appender, duckdb_data_chunk chunk)
  • 파라미터: appender(추가할 appender), chunk(추가할 데이터 청크)
  • 반환값: 성공 시 DuckDBSuccess, 실패 시 DuckDBError

더 알아보기 (Learn more)

  • C API 문서에서 DuckDB C 인터페이스를 더 자세히 살펴볼 수 있어요.