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 Overview
duckdb_table_function duckdb_create_table_function(void);
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);
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);
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);
idx_t duckdb_table_function_bind_get_result_column_count(duckdb_bind_info info);
const char *duckdb_table_function_bind_get_result_column_name(duckdb_bind_info info, idx_t col_idx);
duckdb_logical_type duckdb_table_function_bind_get_result_column_type(duckdb_bind_info info, idx_t col_idx);
duckdb_create_table_function
Stable since 0.3.3.
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(void);
Return Value
The table function object.
duckdb_destroy_table_function
Stable since 0.3.3.
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
Stable since 0.3.3.
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 functionname: The name of the table function
duckdb_table_function_add_parameter
Stable since 0.3.3.
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 parameter type. Cannot contain INVALID.
duckdb_table_function_add_named_parameter
Stable since 0.8.0.
Adds a named parameter to the table function.
Syntax
void duckdb_table_function_add_named_parameter(
duckdb_table_function table_function,
const char *name,
duckdb_logical_type type
);
Parameters
table_function: The table function.name: The parameter name.type: The parameter type. Cannot contain INVALID.
duckdb_table_function_set_extra_info
Stable since 0.3.3.
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 functionextra_info: The extra informationdestroy: The callback that will be called to destroy the extra information (if any)
duckdb_table_function_set_bind
Stable since 0.3.3.
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 functionbind: The bind function
duckdb_table_function_set_init
Stable since 0.3.3.
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 functioninit: The init function
duckdb_table_function_set_local_init
Stable since 0.4.0.
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 functioninit: The init function
duckdb_table_function_set_function
Stable since 0.3.3.
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 functionfunction: The function
duckdb_table_function_supports_projection_pushdown
Stable since 0.3.3.
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 functionpushdown: True if the table function supports projection pushdown, false otherwise.
duckdb_register_table_function
Stable since 0.3.3.
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
Return Value
Whether or not the registration was successful.
duckdb_bind_get_extra_info
Stable since 0.3.3.
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
Return Value
The extra info
duckdb_table_function_get_client_context
Stable since 1.5.6.
Retrieves the client context of the bind info of a table function.
Syntax
void duckdb_table_function_get_client_context(
duckdb_bind_info info,
duckdb_client_context *out_context
);
Parameters
info: The bind info object of the table function.out_context: The client context of the bind info. Must be destroyed withduckdb_destroy_client_context. (out)
duckdb_bind_add_result_column
Stable since 0.3.3.
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 table function's bind info.name: The column name.type: The logical column type.
duckdb_bind_get_parameter_count
Stable since 0.3.3.
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
Return Value
The number of parameters
duckdb_bind_get_parameter
Stable since 0.3.3.
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 objectindex: The index of the parameter to get
Return Value
The value of the parameter. Must be destroyed with duckdb_destroy_value.
duckdb_bind_get_named_parameter
Stable since 0.8.0.
Retrieves a named parameter with the given name.
The result must be destroyed with duckdb_destroy_value.
Syntax
duckdb_value duckdb_bind_get_named_parameter(
duckdb_bind_info info,
const char *name
);
Parameters
info: The info objectname: The name of the parameter
Return Value
The value of the parameter. Must be destroyed with duckdb_destroy_value.
duckdb_bind_set_bind_data
Stable since 0.3.3.
Sets the user-provided bind data in the bind object of the table function. 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 bind info of the table function.bind_data: The bind data object.destroy: The callback to destroy the bind data (if any).
duckdb_bind_set_cardinality
Stable since 0.5.0.
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
Stable since 0.3.3.
Report that an error has occurred while calling bind on a table function.
Syntax
void duckdb_bind_set_error(
duckdb_bind_info info,
const char *error
);
Parameters
info: The info objecterror: The error message
duckdb_init_get_extra_info
Stable since 0.3.3.
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
Return Value
The extra info
duckdb_init_get_bind_data
Stable since 0.3.3.
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
Return Value
The bind data object
duckdb_init_set_init_data
Stable since 0.3.3.
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 objectinit_data: The init data object.destroy: The callback that will be called to destroy the init data (if any)
duckdb_init_get_column_count
Stable since 0.3.3.
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
Return Value
The number of projected columns.
duckdb_init_get_column_index
Stable since 0.3.3.
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 objectcolumn_index: The index at which to get the projected column index, from 0..duckdb_init_get_column_count(info)
Return Value
The column index of the projected column.
duckdb_init_set_max_threads
Stable since 0.4.0.
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 objectmax_threads: The maximum amount of threads that can process this table function
duckdb_init_set_error
Stable since 0.3.3.
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 objecterror: The error message
duckdb_function_get_extra_info
Stable since 0.3.3.
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
Return Value
The extra info
duckdb_function_get_bind_data
Stable since 0.3.3.
Gets the table function's bind data set by duckdb_bind_set_bind_data.
Note that the bind data is read-only. For tracking state, use the init data instead.
Syntax
void *duckdb_function_get_bind_data(
duckdb_function_info info
);
Parameters
info: The function info object.
Return Value
The bind data object.
duckdb_function_get_init_data
Stable since 0.3.3.
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
Return Value
The init data object
duckdb_function_get_local_init_data
Stable since 0.4.0.
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
Return Value
The init data object
duckdb_function_set_error
Stable since 0.3.3.
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 objecterror: The error message
duckdb_table_function_bind_get_result_column_count
Stable since 1.5.6.
Retrieves the number of result columns of a table function.
If the table function is used in a COPY ... FROM statement, this can be used to retrieve the number of columns in the target table at the start of the bind callback.
Syntax
idx_t duckdb_table_function_bind_get_result_column_count(
duckdb_bind_info info
);
Parameters
info: The bind info provided to the bind function
Return Value
The number of result columns.
duckdb_table_function_bind_get_result_column_name
Stable since 1.5.6.
Retrieves the name of a result column of a table function.
If the table function is used in a COPY ... FROM statement, this can be used to retrieve the names of the columns in the target table at the start of the bind callback.
The result is valid for the duration of the bind callback or until the next call to duckdb_bind_add_result_column, so it must not be destroyed.
Syntax
const char *duckdb_table_function_bind_get_result_column_name(
duckdb_bind_info info,
idx_t col_idx
);
Parameters
info: The bind info provided to the bind functioncol_idx: The index of the result column to retrieve the name for
Return Value
The name of the result column.
duckdb_table_function_bind_get_result_column_type
Stable since 1.5.6.
Retrieves the type of a result column of a table function.
If the table function is used in a COPY ... FROM statement, this can be used to retrieve the types of the columns in the target table at the start of the bind callback.
The result must be destroyed with duckdb_destroy_logical_type.
Syntax
duckdb_logical_type duckdb_table_function_bind_get_result_column_type(
duckdb_bind_info info,
idx_t col_idx
);
Parameters
info: The bind info provided to the bind functioncol_idx: The index of the result column to retrieve the type for
Return Value
The type of the result column.