Search Shortcut cmd + k | ctrl + k
Search cmd+k ctrl+k
Dark Mode
1.1 (stable)
Table Functions

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

</code></pre></div></div>

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

</code></pre></div></div>

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

</code></pre></div></div>

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.

Return Value

The table function object.

Syntax
duckdb_table_function duckdb_create_table_function(
  
);


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 parameter type. Cannot contain INVALID.


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 parameter name.
  • type: The parameter type. Cannot contain INVALID.


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
Return Value

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
Return Value

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 table function's bind info.
  • name: The column name.
  • type: The logical column type.


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
Return Value

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
Return Value

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
Return Value

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
  • bind_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
Return Value

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
Return Value

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
  • init_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
Return Value

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)
Return Value

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
Return Value

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
Return Value

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
Return Value

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
Return Value

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