C API - Table Functions
Version 0.4.0

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_function(duckdb_table_function table_function, duckdb_table_function_t function);
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_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);
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_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_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_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_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_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_bind_set_init_data during the bind.

Syntax


void *duckdb_function_get_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