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_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);
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);
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);
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_add_named_parameter
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 name of the parameter
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_get_named_parameter
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 object
name
The name of the parameter
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