C API - Table Functions
Version current

The table function API can be used to define a table function that can then be called from within DuckDB in the FROM clause of a query.

API Reference

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_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);

Table Function Bind

void *duckdb_bind_get_extra_info(duckdb_bind_info info);
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);
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);

Table Function 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);

Table Function

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


Creates a new empty table function.

The return value should be destroyed with duckdb_destroy_table_function.

Syntax


duckdb_table_function duckdb_create_table_function(
  
);

Parameters


  • returns

The table function object.


duckdb_destroy_table_function


Destroys the given table function object.

Syntax


void duckdb_destroy_table_function(
  duckdb_table_function *table_function
);

Parameters


  • table_function

The table function to destroy


duckdb_table_function_set_name


Sets the name of the given table function.

Syntax


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

Parameters


  • table_function

The table function

  • name

The name of the table function


duckdb_table_function_add_parameter


Adds a parameter to the table function.

Syntax


void duckdb_table_function_add_parameter(
  duckdb_table_function table_function,
  duckdb_logical_type type
);

Parameters


  • table_function

The table function

  • type

The type of the parameter to add.


duckdb_table_function_set_extra_info


Assigns extra information to the table function that can be fetched during binding, etc.

Syntax


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

Parameters


  • table_function

The table function

  • extra_info

The extra information

  • destroy

The callback that will be called to destroy the bind data (if any)


duckdb_table_function_set_bind


Sets the bind function of the table function

Syntax


void duckdb_table_function_set_bind(
  duckdb_table_function table_function,
  duckdb_table_function_bind_t bind
);

Parameters


  • table_function

The table function

  • bind

The bind function


duckdb_table_function_set_init


Sets the init function of the table function

Syntax


void duckdb_table_function_set_init(
  duckdb_table_function table_function,
  duckdb_table_function_init_t init
);

Parameters


  • table_function

The table function

  • init

The init function


duckdb_table_function_set_local_init


Sets the thread-local init function of the table function

Syntax


void duckdb_table_function_set_local_init(
  duckdb_table_function table_function,
  duckdb_table_function_init_t init
);

Parameters


  • table_function

The table function

  • init

The init function


duckdb_table_function_set_function


Sets the main function of the table function

Syntax


void duckdb_table_function_set_function(
  duckdb_table_function table_function,
  duckdb_table_function_t function
);

Parameters


  • table_function

The table function

  • function

The function


duckdb_table_function_supports_projection_pushdown


Sets whether or not the given table function supports projection pushdown.

If this is set to true, the system will provide a list of all required columns in the init stage through the duckdb_init_get_column_count and duckdb_init_get_column_index functions. If this is set to false (the default), the system will expect all columns to be projected.

Syntax


void duckdb_table_function_supports_projection_pushdown(
  duckdb_table_function table_function,
  bool pushdown
);

Parameters


  • table_function

The table function

  • pushdown

True if the table function supports projection pushdown, false otherwise.


duckdb_register_table_function


Register the table function object within the given connection.

The function requires at least a name, a bind function, an init function and a main function.

If the function is incomplete or a function with this name already exists DuckDBError is returned.

Syntax


duckdb_state duckdb_register_table_function(
  duckdb_connection con,
  duckdb_table_function function
);

Parameters


  • con

The connection to register it in.

  • function

The function pointer

  • returns

Whether or not the registration was successful.


duckdb_bind_get_extra_info


Retrieves the extra info of the function as set in duckdb_table_function_set_extra_info

Syntax


void *duckdb_bind_get_extra_info(
  duckdb_bind_info info
);

Parameters


  • info

The info object

  • returns

The extra info


duckdb_bind_add_result_column


Adds a result column to the output of the table function.

Syntax


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

Parameters


  • info

The info object

  • name

The name of the column

  • type

The logical type of the column


duckdb_bind_get_parameter_count


Retrieves the number of regular (non-named) parameters to the function.

Syntax


idx_t duckdb_bind_get_parameter_count(
  duckdb_bind_info info
);

Parameters


  • info

The info object

  • returns

The number of parameters


duckdb_bind_get_parameter


Retrieves the parameter at the given index.

The result must be destroyed with duckdb_destroy_value.

Syntax


duckdb_value duckdb_bind_get_parameter(
  duckdb_bind_info info,
  idx_t index
);

Parameters


  • info

The info object

  • index

The index of the parameter to get

  • returns

The value of the parameter. Must be destroyed with duckdb_destroy_value.


duckdb_bind_set_bind_data


Sets the user-provided bind data in the bind object. This object can be retrieved again during execution.

Syntax


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

Parameters


  • info

The info object

  • extra_data

The bind data object.

  • destroy

The callback that will be called to destroy the bind data (if any)


duckdb_bind_set_cardinality


Sets the cardinality estimate for the table function, used for optimization.

Syntax


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

Parameters


  • info

The bind data object.

  • is_exact

Whether or not the cardinality estimate is exact, or an approximation


duckdb_bind_set_error


Report that an error has occurred while calling bind.

Syntax


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

Parameters


  • info

The info object

  • error

The error message


duckdb_init_get_extra_info


Retrieves the extra info of the function as set in duckdb_table_function_set_extra_info

Syntax


void *duckdb_init_get_extra_info(
  duckdb_init_info info
);

Parameters


  • info

The info object

  • returns

The extra info


duckdb_init_get_bind_data


Gets the bind data set by duckdb_bind_set_bind_data during the bind.

Note that the bind data should be considered as read-only. For tracking state, use the init data instead.

Syntax


void *duckdb_init_get_bind_data(
  duckdb_init_info info
);

Parameters


  • info

The info object

  • returns

The bind data object


duckdb_init_set_init_data


Sets the user-provided init data in the init object. This object can be retrieved again during execution.

Syntax


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

Parameters


  • info

The info object

  • extra_data

The init data object.

  • destroy

The callback that will be called to destroy the init data (if any)


duckdb_init_get_column_count


Returns the number of projected columns.

This function must be used if projection pushdown is enabled to figure out which columns to emit.

Syntax


idx_t duckdb_init_get_column_count(
  duckdb_init_info info
);

Parameters


  • info

The info object

  • returns

The number of projected columns.


duckdb_init_get_column_index


Returns the column index of the projected column at the specified position.

This function must be used if projection pushdown is enabled to figure out which columns to emit.

Syntax


idx_t duckdb_init_get_column_index(
  duckdb_init_info info,
  idx_t column_index
);

Parameters


  • info

The info object

  • column_index

The index at which to get the projected column index, from 0..duckdb_init_get_column_count(info)

  • returns

The column index of the projected column.


duckdb_init_set_max_threads


Sets how many threads can process this table function in parallel (default: 1)

Syntax


void duckdb_init_set_max_threads(
  duckdb_init_info info,
  idx_t max_threads
);

Parameters


  • info

The info object

  • max_threads

The maximum amount of threads that can process this table function


duckdb_init_set_error


Report that an error has occurred while calling init.

Syntax


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

Parameters


  • info

The info object

  • error

The error message


duckdb_function_get_extra_info


Retrieves the extra info of the function as set in duckdb_table_function_set_extra_info

Syntax


void *duckdb_function_get_extra_info(
  duckdb_function_info info
);

Parameters


  • info

The info object

  • returns

The extra info


duckdb_function_get_bind_data


Gets the bind data set by duckdb_bind_set_bind_data during the bind.

Note that the bind data should be considered as read-only. For tracking state, use the init data instead.

Syntax


void *duckdb_function_get_bind_data(
  duckdb_function_info info
);

Parameters


  • info

The info object

  • returns

The bind data object


duckdb_function_get_init_data


Gets the init data set by duckdb_init_set_init_data during the init.

Syntax


void *duckdb_function_get_init_data(
  duckdb_function_info info
);

Parameters


  • info

The info object

  • returns

The init data object


duckdb_function_get_local_init_data


Gets the thread-local init data set by duckdb_init_set_init_data during the local_init.

Syntax


void *duckdb_function_get_local_init_data(
  duckdb_function_info info
);

Parameters


  • info

The info object

  • returns

The init data object


duckdb_function_set_error


Report that an error has occurred while executing the function.

Syntax


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

Parameters


  • info

The info object

  • error

The error message