Table Functions

Search Shortcut cmd + k | ctrl + k

Documentation / Client APIs / C

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

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

`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`

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

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

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)

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

void *duckdb_function_get_bind_data(
  duckdb_function_info info
);

Parameters

info: The info object

void *duckdb_function_get_init_data(
  duckdb_function_info info
);

Parameters

info: The info object

void *duckdb_function_get_local_init_data(
  duckdb_function_info info
);

Parameters

info: The info object

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

Parameters

info: The info object
error: The error message

About this page

In this article