From 90ea9e5c79bda531775890ac07089dba89565846 Mon Sep 17 00:00:00 2001 From: GitHub Actions Date: Mon, 10 Jul 2023 05:07:36 +0000 Subject: [PATCH 01/12] chore: auto update docs --- data/search_data.json | 82 +++++++++++++++++++++++++----- docs/api/c/api.md | 68 +++++++++++++++++++++++++ docs/api/c/prepared.md | 68 +++++++++++++++++++++++++ docs/api/python/reference/index.md | 38 +++++++++----- docs/sql/configuration.md | 6 ++- 5 files changed, 234 insertions(+), 28 deletions(-) diff --git a/data/search_data.json b/data/search_data.json index f4d4be57128..127bbb6f124 100644 --- a/data/search_data.json +++ b/data/search_data.json @@ -1,5 +1,12 @@ { "data": [ + { + "title": "", + "text": "-", + "category": "Nested Functions", + "url": "/docs/sql/functions/nested", + "blurb": "-" + }, { "title": "!", "text": "! - factorial of x. computes the product of the current integer and all integers below it", @@ -156,7 +163,7 @@ }, { "title": "C API - Complete API", - "text": "api reference open connect syntax path to the database file on disk or nullptr or memory to open an in-memory database out_database the result database object returns duckdbsuccess on success or duckdberror on failure duckdb_open_ext extended version of duckdb_open creates a new database or opens an existing database file stored at the the given path syntax path to the database file on disk or nullptr or memory to open an in-memory database out_database the result database object config optional configuration used to start up the database system out_error if set and the function returns duckdberror this will contain the reason why the start-up failed note that the error must be freed using duckdb_free returns duckdbsuccess on success or duckdberror on failure duckdb_close closes the specified database and de-allocates all memory allocated for that database this should be called after you are done with any database allocated through duckdb_open note that failing to call duckdb_close in case of e g a program crash will not cause data corruption still it is recommended to always correctly close a database object after you are done with it syntax the database object to shut down duckdb_connect opens a connection to a database connections are required to query the database and store transactional state associated with the connection the instantiated connection should be closed using duckdb_disconnect syntax the database file to connect to out_connection the result connection object returns duckdbsuccess on success or duckdberror on failure duckdb_disconnect closes the specified connection and de-allocates all memory allocated for that connection syntax the connection to close duckdb_library_version returns the version of the linked duckdb with a version postfix for dev versions usually used for developing c extensions that must return this for a compatibility check syntax duckdb_create_config initializes an empty configuration object that can be used to provide start-up options for the duckdb instance through duckdb_open_ext this will always succeed unless there is a malloc failure syntax the result configuration object returns duckdbsuccess on success or duckdberror on failure duckdb_config_count this returns the total amount of configuration options available for usage with duckdb_get_config_flag this should not be called in a loop as it internally loops over all the options syntax the amount of config options available duckdb_get_config_flag obtains a human-readable name and description of a specific configuration option this can be used to e g display configuration options this will succeed unless index is out of range i e duckdb_config_count the result name or description must not be freed syntax the index of the configuration option between 0 and duckdb_config_count out_name a name of the configuration flag out_description a description of the configuration flag returns duckdbsuccess on success or duckdberror on failure duckdb_set_config sets the specified option for the specified configuration the configuration option is indicated by name to obtain a list of config options see duckdb_get_config_flag in the source code configuration options are defined in config cpp this can fail if either the name is invalid or if the value provided for the option is invalid syntax the configuration object to set the option on name the name of the configuration flag to set option the value to set the configuration flag to returns duckdbsuccess on success or duckdberror on failure duckdb_destroy_config destroys the specified configuration option and de-allocates all memory allocated for the object syntax the configuration object to destroy duckdb_query executes a sql query within a connection and stores the full materialized result in the out_result pointer if the query fails to execute duckdberror is returned and the error message can be retrieved by calling duckdb_result_error note that after running duckdb_query duckdb_destroy_result must be called on the result object even if the query fails otherwise the error stored within the result will not be freed correctly syntax the connection to perform the query in query the sql query to run out_result the query result returns duckdbsuccess on success or duckdberror on failure duckdb_destroy_result closes the result and de-allocates all memory allocated for that connection syntax the result to destroy duckdb_column_name returns the column name of the specified column the result should not need be freed the column names will automatically be destroyed when the result is destroyed returns null if the column is out of range syntax the result object to fetch the column name from col the column index returns the column name of the specified column duckdb_column_type returns the column type of the specified column returns duckdb_type_invalid if the column is out of range syntax the result object to fetch the column type from col the column index returns the column type of the specified column duckdb_column_logical_type returns the logical column type of the specified column the return type of this call should be destroyed with duckdb_destroy_logical_type returns null if the column is out of range syntax the result object to fetch the column type from col the column index returns the logical column type of the specified column duckdb_column_count returns the number of columns present in a the result object syntax the result object returns the number of columns present in the result object duckdb_row_count returns the number of rows present in a the result object syntax the result object returns the number of rows present in the result object duckdb_rows_changed returns the number of rows changed by the query stored in the result this is relevant only for insert update delete queries for other queries the rows_changed will be 0 syntax the result object returns the number of rows changed duckdb_column_data deprecated prefer using duckdb_result_get_chunk instead returns the data of a specific column of a result in columnar format the function returns a dense array which contains the result data the exact type stored in the array depends on the corresponding duckdb_type as provided by duckdb_column_type for the exact type by which the data should be accessed see the comments in the types section or the duckdb_type enum for example for a column of type duckdb_type_integer rows can be accessed in the following manner int32_t data int32_t duckdb_column_data result 0 printf data for row d d n row data row syntax the result object to fetch the column data from col the column index returns the column data of the specified column duckdb_nullmask_data deprecated prefer using duckdb_result_get_chunk instead returns the nullmask of a specific column of a result in columnar format the nullmask indicates for every row whether or not the corresponding row is null if a row is null the values present in the array provided by duckdb_column_data are undefined int32_t data int32_t duckdb_column_data result 0 bool nullmask duckdb_nullmask_data result 0 if nullmask row printf data for row d null n row else printf data for row d d n row data row syntax the result object to fetch the nullmask from col the column index returns the nullmask of the specified column duckdb_result_error returns the error message contained within the result the error is only set if duckdb_query returns duckdberror the result of this function must not be freed it will be cleaned up when duckdb_destroy_result is called syntax the result object to fetch the error from returns the error of the result duckdb_result_get_chunk fetches a data chunk from the duckdb_result this function should be called repeatedly until the result is exhausted the result must be destroyed with duckdb_destroy_data_chunk this function supersedes all duckdb_value functions as well as the duckdb_column_data and duckdb_nullmask_data functions it results in significantly better performance and should be preferred in newer code-bases if this function is used none of the other result functions can be used and vice versa i e this function cannot be mixed with the legacy result functions use duckdb_result_chunk_count to figure out how many chunks there are in the result syntax the result object to fetch the data chunk from chunk_index the chunk index to fetch from returns the resulting data chunk returns null if the chunk index is out of bounds duckdb_result_is_streaming checks if the type of the internal result is streamqueryresult syntax the result object to check returns whether or not the result object is of the type streamqueryresult duckdb_result_chunk_count returns the number of data chunks present in the result syntax the result object returns number of data chunks present in the result duckdb_value_boolean syntax the boolean value at the specified location or false if the value cannot be converted duckdb_value_int8 syntax the int8_t value at the specified location or 0 if the value cannot be converted duckdb_value_int16 syntax the int16_t value at the specified location or 0 if the value cannot be converted duckdb_value_int32 syntax the int32_t value at the specified location or 0 if the value cannot be converted duckdb_value_int64 syntax the int64_t value at the specified location or 0 if the value cannot be converted duckdb_value_hugeint syntax the duckdb_hugeint value at the specified location or 0 if the value cannot be converted duckdb_value_decimal syntax the duckdb_decimal value at the specified location or 0 if the value cannot be converted duckdb_value_uint8 syntax the uint8_t value at the specified location or 0 if the value cannot be converted duckdb_value_uint16 syntax the uint16_t value at the specified location or 0 if the value cannot be converted duckdb_value_uint32 syntax the uint32_t value at the specified location or 0 if the value cannot be converted duckdb_value_uint64 syntax the uint64_t value at the specified location or 0 if the value cannot be converted duckdb_value_float syntax the float value at the specified location or 0 if the value cannot be converted duckdb_value_double syntax the double value at the specified location or 0 if the value cannot be converted duckdb_value_date syntax the duckdb_date value at the specified location or 0 if the value cannot be converted duckdb_value_time syntax the duckdb_time value at the specified location or 0 if the value cannot be converted duckdb_value_timestamp syntax the duckdb_timestamp value at the specified location or 0 if the value cannot be converted duckdb_value_interval syntax the duckdb_interval value at the specified location or 0 if the value cannot be converted duckdb_value_varchar syntax use duckdb_value_string instead this function does not work correctly if the string contains null bytes returns the text value at the specified location as a null-terminated string or nullptr if the value cannot be converted the result must be freed with duckdb_free duckdb_value_varchar_internal syntax use duckdb_value_string_internal instead this function does not work correctly if the string contains null bytes returns the char value at the specified location only works on varchar columns and does not auto-cast if the column is not a varchar column this function will return null the result must not be freed duckdb_value_string_internal syntax use duckdb_value_string_internal instead this function does not work correctly if the string contains null bytes returns the char value at the specified location only works on varchar columns and does not auto-cast if the column is not a varchar column this function will return null the result must not be freed duckdb_value_blob syntax the duckdb_blob value at the specified location returns a blob with blob data set to nullptr if the value cannot be converted the resulting blob data must be freed with duckdb_free duckdb_value_is_null syntax returns true if the value at the specified index is null and false otherwise duckdb_malloc allocate size bytes of memory using the duckdb internal malloc function any memory allocated in this manner should be freed using duckdb_free syntax the number of bytes to allocate returns a pointer to the allocated memory region duckdb_free free a value returned from duckdb_malloc duckdb_value_varchar or duckdb_value_blob syntax the memory region to de-allocate duckdb_vector_size the internal vector size used by duckdb this is the amount of tuples that will fit into a data chunk created by duckdb_create_data_chunk syntax the vector size duckdb_string_is_inlined whether or not the duckdb_string_t value is inlined this means that the data of the string does not have a separate allocation syntax duckdb_from_date decompose a duckdb_date object into year month and date stored as duckdb_date_struct syntax the date object as obtained from a duckdb_type_date column returns the duckdb_date_struct with the decomposed elements duckdb_to_date re-compose a duckdb_date from year month and date duckdb_date_struct syntax the year month and date stored in a duckdb_date_struct returns the duckdb_date element duckdb_from_time decompose a duckdb_time object into hour minute second and microsecond stored as duckdb_time_struct syntax the time object as obtained from a duckdb_type_time column returns the duckdb_time_struct with the decomposed elements duckdb_to_time re-compose a duckdb_time from hour minute second and microsecond duckdb_time_struct syntax the hour minute second and microsecond in a duckdb_time_struct returns the duckdb_time element duckdb_from_timestamp decompose a duckdb_timestamp object into a duckdb_timestamp_struct syntax the ts object as obtained from a duckdb_type_timestamp column returns the duckdb_timestamp_struct with the decomposed elements duckdb_to_timestamp re-compose a duckdb_timestamp from a duckdb_timestamp_struct syntax the de-composed elements in a duckdb_timestamp_struct returns the duckdb_timestamp element duckdb_hugeint_to_double converts a duckdb_hugeint object as obtained from a duckdb_type_hugeint column into a double syntax the hugeint value returns the converted double element duckdb_double_to_hugeint converts a double value to a duckdb_hugeint object if the conversion fails because the double value is too big the result will be 0 syntax the double value returns the converted duckdb_hugeint element duckdb_double_to_decimal converts a double value to a duckdb_decimal object if the conversion fails because the double value is too big or the width scale are invalid the result will be 0 syntax the double value returns the converted duckdb_decimal element duckdb_decimal_to_double converts a duckdb_decimal object as obtained from a duckdb_type_decimal column into a double syntax the decimal value returns the converted double element duckdb_prepare create a prepared statement object from a query note that after calling duckdb_prepare the prepared statement should always be destroyed using duckdb_destroy_prepare even if the prepare fails if the prepare fails duckdb_prepare_error can be called to obtain the reason why the prepare failed syntax the connection object query the sql query to prepare out_prepared_statement the resulting prepared statement object returns duckdbsuccess on success or duckdberror on failure duckdb_destroy_prepare closes the prepared statement and de-allocates all memory allocated for the statement syntax the prepared statement to destroy duckdb_prepare_error returns the error message associated with the given prepared statement if the prepared statement has no error message this returns nullptr instead the error message should not be freed it will be de-allocated when duckdb_destroy_prepare is called syntax the prepared statement to obtain the error from returns the error message or nullptr if there is none duckdb_nparams returns the number of parameters that can be provided to the given prepared statement returns 0 if the query was not successfully prepared syntax the prepared statement to obtain the number of parameters for duckdb_param_type returns the parameter type for the parameter at the given index returns duckdb_type_invalid if the parameter index is out of range or the statement was not successfully prepared syntax the prepared statement param_idx the parameter index returns the parameter type duckdb_clear_bindings clear the params bind to the prepared statement syntax duckdb_bind_boolean binds a bool value to the prepared statement at the specified index syntax duckdb_bind_int8 binds an int8_t value to the prepared statement at the specified index syntax duckdb_bind_int16 binds an int16_t value to the prepared statement at the specified index syntax duckdb_bind_int32 binds an int32_t value to the prepared statement at the specified index syntax duckdb_bind_int64 binds an int64_t value to the prepared statement at the specified index syntax duckdb_bind_hugeint binds an duckdb_hugeint value to the prepared statement at the specified index syntax duckdb_bind_decimal binds a duckdb_decimal value to the prepared statement at the specified index syntax duckdb_bind_uint8 binds an uint8_t value to the prepared statement at the specified index syntax duckdb_bind_uint16 binds an uint16_t value to the prepared statement at the specified index syntax duckdb_bind_uint32 binds an uint32_t value to the prepared statement at the specified index syntax duckdb_bind_uint64 binds an uint64_t value to the prepared statement at the specified index syntax duckdb_bind_float binds an float value to the prepared statement at the specified index syntax duckdb_bind_double binds an double value to the prepared statement at the specified index syntax duckdb_bind_date binds a duckdb_date value to the prepared statement at the specified index syntax duckdb_bind_time binds a duckdb_time value to the prepared statement at the specified index syntax duckdb_bind_timestamp binds a duckdb_timestamp value to the prepared statement at the specified index syntax duckdb_bind_interval binds a duckdb_interval value to the prepared statement at the specified index syntax duckdb_bind_varchar binds a null-terminated varchar value to the prepared statement at the specified index syntax duckdb_bind_varchar_length binds a varchar value to the prepared statement at the specified index syntax duckdb_bind_blob binds a blob value to the prepared statement at the specified index syntax duckdb_bind_null binds a null value to the prepared statement at the specified index syntax duckdb_execute_prepared executes the prepared statement with the given bound parameters and returns a materialized query result this method can be called multiple times for each prepared statement and the parameters can be modified between calls to this function syntax the prepared statement to execute out_result the query result returns duckdbsuccess on success or duckdberror on failure duckdb_execute_prepared_arrow executes the prepared statement with the given bound parameters and returns an arrow query result syntax the prepared statement to execute out_result the query result returns duckdbsuccess on success or duckdberror on failure duckdb_extract_statements extract all statements from a query note that after calling duckdb_extract_statements the extracted statements should always be destroyed using duckdb_destroy_extracted even if no statements were extracted if the extract fails duckdb_extract_statements_error can be called to obtain the reason why the extract failed syntax the connection object query the sql query to extract out_extracted_statements the resulting extracted statements object returns the number of extracted statements or 0 on failure duckdb_prepare_extracted_statement prepare an extracted statement note that after calling duckdb_prepare_extracted_statement the prepared statement should always be destroyed using duckdb_destroy_prepare even if the prepare fails if the prepare fails duckdb_prepare_error can be called to obtain the reason why the prepare failed syntax the connection object extracted_statements the extracted statements object index the index of the extracted statement to prepare out_prepared_statement the resulting prepared statement object returns duckdbsuccess on success or duckdberror on failure duckdb_extract_statements_error returns the error message contained within the extracted statements the result of this function must not be freed it will be cleaned up when duckdb_destroy_extracted is called syntax the extracted statements to fetch the error from returns the error of the extracted statements duckdb_destroy_extracted de-allocates all memory allocated for the extracted statements syntax the extracted statements to destroy duckdb_pending_prepared executes the prepared statement with the given bound parameters and returns a pending result the pending result represents an intermediate structure for a query that is not yet fully executed the pending result can be used to incrementally execute a query returning control to the client between tasks note that after calling duckdb_pending_prepared the pending result should always be destroyed using duckdb_destroy_pending even if this function returns duckdberror syntax the prepared statement to execute out_result the pending query result returns duckdbsuccess on success or duckdberror on failure duckdb_pending_prepared_streaming executes the prepared statement with the given bound parameters and returns a pending result this pending result will create a streaming duckdb_result when executed the pending result represents an intermediate structure for a query that is not yet fully executed note that after calling duckdb_pending_prepared_streaming the pending result should always be destroyed using duckdb_destroy_pending even if this function returns duckdberror syntax the prepared statement to execute out_result the pending query result returns duckdbsuccess on success or duckdberror on failure duckdb_destroy_pending closes the pending result and de-allocates all memory allocated for the result syntax the pending result to destroy duckdb_pending_error returns the error message contained within the pending result the result of this function must not be freed it will be cleaned up when duckdb_destroy_pending is called syntax the pending result to fetch the error from returns the error of the pending result duckdb_pending_execute_task executes a single task within the query returning whether or not the query is ready if this returns duckdb_pending_result_ready the duckdb_execute_pending function can be called to obtain the result if this returns duckdb_pending_result_not_ready the duckdb_pending_execute_task function should be called again if this returns duckdb_pending_error an error occurred during execution the error message can be obtained by calling duckdb_pending_error on the pending_result syntax the pending result to execute a task within returns the state of the pending result after the execution duckdb_execute_pending fully execute a pending query result returning the final query result if duckdb_pending_execute_task has been called until duckdb_pending_result_ready was returned this will return fast otherwise all remaining tasks must be executed first syntax the pending result to execute out_result the result object returns duckdbsuccess on success or duckdberror on failure duckdb_destroy_value destroys the value and de-allocates all memory allocated for that type syntax the value to destroy duckdb_create_varchar creates a value from a null-terminated string syntax the null-terminated string returns the value this must be destroyed with duckdb_destroy_value duckdb_create_varchar_length creates a value from a string syntax the text length the length of the text returns the value this must be destroyed with duckdb_destroy_value duckdb_create_int64 creates a value from an int64 syntax the bigint value returns the value this must be destroyed with duckdb_destroy_value duckdb_get_varchar obtains a string representation of the given value the result must be destroyed with duckdb_free syntax the value returns the string value this must be destroyed with duckdb_free duckdb_get_int64 obtains an int64 of the given value syntax the value returns the int64 value or 0 if no conversion is possible duckdb_create_logical_type creates a duckdb_logical_type from a standard primitive type the resulting type should be destroyed with duckdb_destroy_logical_type this should not be used with duckdb_type_decimal syntax the primitive type to create returns the logical type duckdb_create_list_type creates a list type from its child type the resulting type should be destroyed with duckdb_destroy_logical_type syntax the child type of list type to create returns the logical type duckdb_create_map_type creates a map type from its key type and value type the resulting type should be destroyed with duckdb_destroy_logical_type syntax the key type and value type of map type to create returns the logical type duckdb_create_union_type creates a union type from the passed types array the resulting type should be destroyed with duckdb_destroy_logical_type syntax the array of types that the union should consist of type_amount the size of the types array returns the logical type duckdb_create_decimal_type creates a duckdb_logical_type of type decimal with the specified width and scale the resulting type should be destroyed with duckdb_destroy_logical_type syntax the width of the decimal type scale the scale of the decimal type returns the logical type duckdb_get_type_id retrieves the type class of a duckdb_logical_type syntax the logical type object returns the type id duckdb_decimal_width retrieves the width of a decimal type syntax the logical type object returns the width of the decimal type duckdb_decimal_scale retrieves the scale of a decimal type syntax the logical type object returns the scale of the decimal type duckdb_decimal_internal_type retrieves the internal storage type of a decimal type syntax the logical type object returns the internal type of the decimal type duckdb_enum_internal_type retrieves the internal storage type of an enum type syntax the logical type object returns the internal type of the enum type duckdb_enum_dictionary_size retrieves the dictionary size of the enum type syntax the logical type object returns the dictionary size of the enum type duckdb_enum_dictionary_value retrieves the dictionary value at the specified position from the enum the result must be freed with duckdb_free syntax the logical type object index the index in the dictionary returns the string value of the enum type must be freed with duckdb_free duckdb_list_type_child_type retrieves the child type of the given list type the result must be freed with duckdb_destroy_logical_type syntax the logical type object returns the child type of the list type must be destroyed with duckdb_destroy_logical_type duckdb_map_type_key_type retrieves the key type of the given map type the result must be freed with duckdb_destroy_logical_type syntax the logical type object returns the key type of the map type must be destroyed with duckdb_destroy_logical_type duckdb_map_type_value_type retrieves the value type of the given map type the result must be freed with duckdb_destroy_logical_type syntax the logical type object returns the value type of the map type must be destroyed with duckdb_destroy_logical_type duckdb_struct_type_child_count returns the number of children of a struct type syntax the logical type object returns the number of children of a struct type duckdb_struct_type_child_name retrieves the name of the struct child the result must be freed with duckdb_free syntax the logical type object index the child index returns the name of the struct type must be freed with duckdb_free duckdb_struct_type_child_type retrieves the child type of the given struct type at the specified index the result must be freed with duckdb_destroy_logical_type syntax the logical type object index the child index returns the child type of the struct type must be destroyed with duckdb_destroy_logical_type duckdb_union_type_member_count returns the number of members that the union type has syntax the logical type union object returns the number of members of a union type duckdb_union_type_member_name retrieves the name of the union member the result must be freed with duckdb_free syntax the logical type object index the child index returns the name of the union member must be freed with duckdb_free duckdb_union_type_member_type retrieves the child type of the given union member at the specified index the result must be freed with duckdb_destroy_logical_type syntax the logical type object index the child index returns the child type of the union member must be destroyed with duckdb_destroy_logical_type duckdb_destroy_logical_type destroys the logical type and de-allocates all memory allocated for that type syntax the logical type to destroy duckdb_create_data_chunk creates an empty datachunk with the specified set of types syntax an array of types of the data chunk column_count the number of columns returns the data chunk duckdb_destroy_data_chunk destroys the data chunk and de-allocates all memory allocated for that chunk syntax the data chunk to destroy duckdb_data_chunk_reset resets a data chunk clearing the validity masks and setting the cardinality of the data chunk to 0 syntax the data chunk to reset duckdb_data_chunk_get_column_count retrieves the number of columns in a data chunk syntax the data chunk to get the data from returns the number of columns in the data chunk duckdb_data_chunk_get_vector retrieves the vector at the specified column index in the data chunk the pointer to the vector is valid for as long as the chunk is alive it does not need to be destroyed syntax the data chunk to get the data from returns the vector duckdb_data_chunk_get_size retrieves the current number of tuples in a data chunk syntax the data chunk to get the data from returns the number of tuples in the data chunk duckdb_data_chunk_set_size sets the current number of tuples in a data chunk syntax the data chunk to set the size in size the number of tuples in the data chunk duckdb_vector_get_column_type retrieves the column type of the specified vector the result must be destroyed with duckdb_destroy_logical_type syntax the vector get the data from returns the type of the vector duckdb_vector_get_data retrieves the data pointer of the vector the data pointer can be used to read or write values from the vector how to read or write values depends on the type of the vector syntax the vector to get the data from returns the data pointer duckdb_vector_get_validity retrieves the validity mask pointer of the specified vector if all values are valid this function might return null the validity mask is a bitset that signifies null-ness within the data chunk it is a series of uint64_t values where each uint64_t value contains validity for 64 tuples the bit is set to 1 if the value is valid i e not null or 0 if the value is invalid i e null validity of a specific value can be obtained like this idx_t entry_idx row_idx 64 idx_t idx_in_entry row_idx 64 bool is_valid validity_mask entry_idx 1 idx_in_entry alternatively the slower duckdb_validity_row_is_valid function can be used syntax the vector to get the data from returns the pointer to the validity mask or null if no validity mask is present duckdb_vector_ensure_validity_writable ensures the validity mask is writable by allocating it after this function is called duckdb_vector_get_validity will always return non-null this allows null values to be written to the vector regardless of whether a validity mask was present before syntax the vector to alter duckdb_vector_assign_string_element assigns a string element in the vector at the specified location syntax the vector to alter index the row position in the vector to assign the string to str the null-terminated string duckdb_vector_assign_string_element_len assigns a string element in the vector at the specified location syntax the vector to alter index the row position in the vector to assign the string to str the string str_len the length of the string in bytes duckdb_list_vector_get_child retrieves the child vector of a list vector the resulting vector is valid as long as the parent vector is valid syntax the vector returns the child vector duckdb_list_vector_get_size returns the size of the child vector of the list syntax the vector returns the size of the child list duckdb_list_vector_set_size sets the total size of the underlying child-vector of a list vector syntax the list vector size the size of the child list returns the duckdb state returns duckdberror if the vector is nullptr duckdb_list_vector_reserve sets the total capacity of the underlying child-vector of a list syntax the list vector required_capacity the total capacity to reserve return the duckdb state returns duckdberror if the vector is nullptr duckdb_struct_vector_get_child retrieves the child vector of a struct vector the resulting vector is valid as long as the parent vector is valid syntax the vector index the child index returns the child vector duckdb_validity_row_is_valid returns whether or not a row is valid i e not null in the given validity mask syntax the validity mask as obtained through duckdb_data_chunk_get_validity row the row index returns true if the row is valid false otherwise duckdb_validity_set_row_validity in a validity mask sets a specific row to either valid or invalid note that duckdb_data_chunk_ensure_validity_writable should be called before calling duckdb_data_chunk_get_validity to ensure that there is a validity mask to write to syntax the validity mask as obtained through duckdb_data_chunk_get_validity row the row index valid whether or not to set the row to valid or invalid duckdb_validity_set_row_invalid in a validity mask sets a specific row to invalid equivalent to duckdb_validity_set_row_validity with valid set to false syntax the validity mask row the row index duckdb_validity_set_row_valid in a validity mask sets a specific row to valid equivalent to duckdb_validity_set_row_validity with valid set to true syntax the validity mask row the row index duckdb_create_table_function creates a new empty table function the return value should be destroyed with duckdb_destroy_table_function syntax the table function object duckdb_destroy_table_function destroys the given table function object syntax the table function to destroy duckdb_table_function_set_name sets the name of the given table function syntax the table function name the name of the table function duckdb_table_function_add_parameter adds a parameter to the table function syntax 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 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 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 the table function bind the bind function duckdb_table_function_set_init sets the init function of the table function syntax the table function init the init function duckdb_table_function_set_local_init sets the thread-local init function of the table function syntax the table function init the init function duckdb_table_function_set_function sets the main function of the table function syntax 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 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 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 the info object returns the extra info duckdb_bind_add_result_column adds a result column to the output of the table function syntax 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 the info object returns the init data object duckdb_function_set_error report that an error has occurred while executing the function syntax the info object error the error message duckdb_add_replacement_scan add a replacement scan definition to the specified database syntax the database object to add the replacement scan to replacement the replacement scan callback extra_data extra data that is passed back into the specified callback delete_callback the delete callback to call on the extra data if any duckdb_replacement_scan_set_function_name sets the replacement function name to use if this function is called in the replacement callback the replacement scan is performed if it is not called the replacement callback is not performed syntax the info object function_name the function name to substitute duckdb_replacement_scan_add_parameter adds a parameter to the replacement scan function syntax the info object parameter the parameter to add duckdb_replacement_scan_set_error report that an error has occurred while executing the replacement scan syntax the info object error the error message duckdb_appender_create creates an appender object syntax the connection context to create the appender in schema the schema of the table to append to or nullptr for the default schema table the table name to append to out_appender the resulting appender object returns duckdbsuccess on success or duckdberror on failure duckdb_appender_error returns the error message associated with the given appender if the appender has no error message this returns nullptr instead the error message should not be freed it will be de-allocated when duckdb_appender_destroy is called syntax the appender to get the error from returns the error message or nullptr if there is none duckdb_appender_flush flush the appender to the table forcing the cache of the appender to be cleared and the data to be appended to the base table this should generally not be used unless you know what you are doing instead call duckdb_appender_destroy when you are done with the appender syntax the appender to flush returns duckdbsuccess on success or duckdberror on failure duckdb_appender_close close the appender flushing all intermediate state in the appender to the table and closing it for further appends this is generally not necessary call duckdb_appender_destroy instead syntax the appender to flush and close returns duckdbsuccess on success or duckdberror on failure duckdb_appender_destroy close the appender and destroy it flushing all intermediate state in the appender to the table and de-allocating all memory associated with the appender syntax the appender to flush close and destroy returns duckdbsuccess on success or duckdberror on failure duckdb_appender_begin_row a nop function provided for backwards compatibility reasons does nothing only duckdb_appender_end_row is required syntax duckdb_appender_end_row finish the current row of appends after end_row is called the next row can be appended syntax the appender returns duckdbsuccess on success or duckdberror on failure duckdb_append_bool append a bool value to the appender syntax duckdb_append_int8 append an int8_t value to the appender syntax duckdb_append_int16 append an int16_t value to the appender syntax duckdb_append_int32 append an int32_t value to the appender syntax duckdb_append_int64 append an int64_t value to the appender syntax duckdb_append_hugeint append a duckdb_hugeint value to the appender syntax duckdb_append_uint8 append a uint8_t value to the appender syntax duckdb_append_uint16 append a uint16_t value to the appender syntax duckdb_append_uint32 append a uint32_t value to the appender syntax duckdb_append_uint64 append a uint64_t value to the appender syntax duckdb_append_float append a float value to the appender syntax duckdb_append_double append a double value to the appender syntax duckdb_append_date append a duckdb_date value to the appender syntax duckdb_append_time append a duckdb_time value to the appender syntax duckdb_append_timestamp append a duckdb_timestamp value to the appender syntax duckdb_append_interval append a duckdb_interval value to the appender syntax duckdb_append_varchar append a varchar value to the appender syntax duckdb_append_varchar_length append a varchar value to the appender syntax duckdb_append_blob append a blob value to the appender syntax duckdb_append_null append a null value to the appender of any type syntax duckdb_append_data_chunk appends a pre-filled data chunk to the specified appender the types of the data chunk must exactly match the types of the table no casting is performed if the types do not match or the appender is in an invalid state duckdberror is returned if the append is successful duckdbsuccess is returned syntax the appender to append to chunk the data chunk to append returns the return state duckdb_query_arrow executes a sql query within a connection and stores the full materialized result in an arrow structure if the query fails to execute duckdberror is returned and the error message can be retrieved by calling duckdb_query_arrow_error note that after running duckdb_query_arrow duckdb_destroy_arrow must be called on the result object even if the query fails otherwise the error stored within the result will not be freed correctly syntax the connection to perform the query in query the sql query to run out_result the query result returns duckdbsuccess on success or duckdberror on failure duckdb_query_arrow_schema fetch the internal arrow schema from the arrow result syntax the result to fetch the schema from out_schema the output schema returns duckdbsuccess on success or duckdberror on failure duckdb_query_arrow_array fetch an internal arrow array from the arrow result this function can be called multiple time to get next chunks which will free the previous out_array so consume the out_array before calling this function again syntax the result to fetch the array from out_array the output array returns duckdbsuccess on success or duckdberror on failure duckdb_arrow_column_count returns the number of columns present in a the arrow result object syntax the result object returns the number of columns present in the result object duckdb_arrow_row_count returns the number of rows present in a the arrow result object syntax the result object returns the number of rows present in the result object duckdb_arrow_rows_changed returns the number of rows changed by the query stored in the arrow result this is relevant only for insert update delete queries for other queries the rows_changed will be 0 syntax the result object returns the number of rows changed duckdb_query_arrow_error returns the error message contained within the result the error is only set if duckdb_query_arrow returns duckdberror the error message should not be freed it will be de-allocated when duckdb_destroy_arrow is called syntax the result object to fetch the nullmask from returns the error of the result duckdb_destroy_arrow closes the result and de-allocates all memory allocated for the arrow result syntax the result to destroy duckdb_execute_tasks execute duckdb tasks on this thread will return after max_tasks have been executed or if there are no more tasks present syntax the database object to execute tasks for max_tasks the maximum amount of tasks to execute duckdb_create_task_state creates a task state that can be used with duckdb_execute_tasks_state to execute tasks until duckdb_finish_execution is called on the state duckdb_destroy_state should be called on the result in order to free memory syntax the database object to create the task state for returns the task state that can be used with duckdb_execute_tasks_state duckdb_execute_tasks_state execute duckdb tasks on this thread the thread will keep on executing tasks forever until duckdb_finish_execution is called on the state multiple threads can share the same duckdb_task_state syntax the task state of the executor duckdb_execute_n_tasks_state execute duckdb tasks on this thread the thread will keep on executing tasks until either duckdb_finish_execution is called on the state max_tasks tasks have been executed or there are no more tasks to be executed multiple threads can share the same duckdb_task_state syntax the task state of the executor max_tasks the maximum amount of tasks to execute returns the amount of tasks that have actually been executed duckdb_finish_execution finish execution on a specific task syntax the task state to finish execution duckdb_task_state_is_finished check if the provided duckdb_task_state has finished execution syntax the task state to inspect returns whether or not duckdb_finish_execution has been called on the task state duckdb_destroy_task_state destroys the task state returned from duckdb_create_task_state note that this should not be called while there is an active duckdb_execute_tasks_state running on the task state syntax the task state to clean up duckdb_execution_is_finished returns true if execution of the current query is finished syntax the connection on which to check duckdb_stream_fetch_chunk fetches a data chunk from the streaming duckdb_result this function should be called repeatedly until the result is exhausted the result must be destroyed with duckdb_destroy_data_chunk this function can only be used on duckdb_results created with duckdb_pending_prepared_streaming if this function is used none of the other result functions can be used and vice versa i e this function cannot be mixed with the legacy result functions or the materialized result functions it is not known beforehand how many chunks will be returned by this result syntax the result object to fetch the data chunk from returns the resulting data chunk returns null if the result has an error", + "text": "api reference open connect syntax path to the database file on disk or nullptr or memory to open an in-memory database out_database the result database object returns duckdbsuccess on success or duckdberror on failure duckdb_open_ext extended version of duckdb_open creates a new database or opens an existing database file stored at the the given path syntax path to the database file on disk or nullptr or memory to open an in-memory database out_database the result database object config optional configuration used to start up the database system out_error if set and the function returns duckdberror this will contain the reason why the start-up failed note that the error must be freed using duckdb_free returns duckdbsuccess on success or duckdberror on failure duckdb_close closes the specified database and de-allocates all memory allocated for that database this should be called after you are done with any database allocated through duckdb_open note that failing to call duckdb_close in case of e g a program crash will not cause data corruption still it is recommended to always correctly close a database object after you are done with it syntax the database object to shut down duckdb_connect opens a connection to a database connections are required to query the database and store transactional state associated with the connection the instantiated connection should be closed using duckdb_disconnect syntax the database file to connect to out_connection the result connection object returns duckdbsuccess on success or duckdberror on failure duckdb_disconnect closes the specified connection and de-allocates all memory allocated for that connection syntax the connection to close duckdb_library_version returns the version of the linked duckdb with a version postfix for dev versions usually used for developing c extensions that must return this for a compatibility check syntax duckdb_create_config initializes an empty configuration object that can be used to provide start-up options for the duckdb instance through duckdb_open_ext this will always succeed unless there is a malloc failure syntax the result configuration object returns duckdbsuccess on success or duckdberror on failure duckdb_config_count this returns the total amount of configuration options available for usage with duckdb_get_config_flag this should not be called in a loop as it internally loops over all the options syntax the amount of config options available duckdb_get_config_flag obtains a human-readable name and description of a specific configuration option this can be used to e g display configuration options this will succeed unless index is out of range i e duckdb_config_count the result name or description must not be freed syntax the index of the configuration option between 0 and duckdb_config_count out_name a name of the configuration flag out_description a description of the configuration flag returns duckdbsuccess on success or duckdberror on failure duckdb_set_config sets the specified option for the specified configuration the configuration option is indicated by name to obtain a list of config options see duckdb_get_config_flag in the source code configuration options are defined in config cpp this can fail if either the name is invalid or if the value provided for the option is invalid syntax the configuration object to set the option on name the name of the configuration flag to set option the value to set the configuration flag to returns duckdbsuccess on success or duckdberror on failure duckdb_destroy_config destroys the specified configuration option and de-allocates all memory allocated for the object syntax the configuration object to destroy duckdb_query executes a sql query within a connection and stores the full materialized result in the out_result pointer if the query fails to execute duckdberror is returned and the error message can be retrieved by calling duckdb_result_error note that after running duckdb_query duckdb_destroy_result must be called on the result object even if the query fails otherwise the error stored within the result will not be freed correctly syntax the connection to perform the query in query the sql query to run out_result the query result returns duckdbsuccess on success or duckdberror on failure duckdb_destroy_result closes the result and de-allocates all memory allocated for that connection syntax the result to destroy duckdb_column_name returns the column name of the specified column the result should not need be freed the column names will automatically be destroyed when the result is destroyed returns null if the column is out of range syntax the result object to fetch the column name from col the column index returns the column name of the specified column duckdb_column_type returns the column type of the specified column returns duckdb_type_invalid if the column is out of range syntax the result object to fetch the column type from col the column index returns the column type of the specified column duckdb_column_logical_type returns the logical column type of the specified column the return type of this call should be destroyed with duckdb_destroy_logical_type returns null if the column is out of range syntax the result object to fetch the column type from col the column index returns the logical column type of the specified column duckdb_column_count returns the number of columns present in a the result object syntax the result object returns the number of columns present in the result object duckdb_row_count returns the number of rows present in a the result object syntax the result object returns the number of rows present in the result object duckdb_rows_changed returns the number of rows changed by the query stored in the result this is relevant only for insert update delete queries for other queries the rows_changed will be 0 syntax the result object returns the number of rows changed duckdb_column_data deprecated prefer using duckdb_result_get_chunk instead returns the data of a specific column of a result in columnar format the function returns a dense array which contains the result data the exact type stored in the array depends on the corresponding duckdb_type as provided by duckdb_column_type for the exact type by which the data should be accessed see the comments in the types section or the duckdb_type enum for example for a column of type duckdb_type_integer rows can be accessed in the following manner int32_t data int32_t duckdb_column_data result 0 printf data for row d d n row data row syntax the result object to fetch the column data from col the column index returns the column data of the specified column duckdb_nullmask_data deprecated prefer using duckdb_result_get_chunk instead returns the nullmask of a specific column of a result in columnar format the nullmask indicates for every row whether or not the corresponding row is null if a row is null the values present in the array provided by duckdb_column_data are undefined int32_t data int32_t duckdb_column_data result 0 bool nullmask duckdb_nullmask_data result 0 if nullmask row printf data for row d null n row else printf data for row d d n row data row syntax the result object to fetch the nullmask from col the column index returns the nullmask of the specified column duckdb_result_error returns the error message contained within the result the error is only set if duckdb_query returns duckdberror the result of this function must not be freed it will be cleaned up when duckdb_destroy_result is called syntax the result object to fetch the error from returns the error of the result duckdb_result_get_chunk fetches a data chunk from the duckdb_result this function should be called repeatedly until the result is exhausted the result must be destroyed with duckdb_destroy_data_chunk this function supersedes all duckdb_value functions as well as the duckdb_column_data and duckdb_nullmask_data functions it results in significantly better performance and should be preferred in newer code-bases if this function is used none of the other result functions can be used and vice versa i e this function cannot be mixed with the legacy result functions use duckdb_result_chunk_count to figure out how many chunks there are in the result syntax the result object to fetch the data chunk from chunk_index the chunk index to fetch from returns the resulting data chunk returns null if the chunk index is out of bounds duckdb_result_is_streaming checks if the type of the internal result is streamqueryresult syntax the result object to check returns whether or not the result object is of the type streamqueryresult duckdb_result_chunk_count returns the number of data chunks present in the result syntax the result object returns number of data chunks present in the result duckdb_value_boolean syntax the boolean value at the specified location or false if the value cannot be converted duckdb_value_int8 syntax the int8_t value at the specified location or 0 if the value cannot be converted duckdb_value_int16 syntax the int16_t value at the specified location or 0 if the value cannot be converted duckdb_value_int32 syntax the int32_t value at the specified location or 0 if the value cannot be converted duckdb_value_int64 syntax the int64_t value at the specified location or 0 if the value cannot be converted duckdb_value_hugeint syntax the duckdb_hugeint value at the specified location or 0 if the value cannot be converted duckdb_value_decimal syntax the duckdb_decimal value at the specified location or 0 if the value cannot be converted duckdb_value_uint8 syntax the uint8_t value at the specified location or 0 if the value cannot be converted duckdb_value_uint16 syntax the uint16_t value at the specified location or 0 if the value cannot be converted duckdb_value_uint32 syntax the uint32_t value at the specified location or 0 if the value cannot be converted duckdb_value_uint64 syntax the uint64_t value at the specified location or 0 if the value cannot be converted duckdb_value_float syntax the float value at the specified location or 0 if the value cannot be converted duckdb_value_double syntax the double value at the specified location or 0 if the value cannot be converted duckdb_value_date syntax the duckdb_date value at the specified location or 0 if the value cannot be converted duckdb_value_time syntax the duckdb_time value at the specified location or 0 if the value cannot be converted duckdb_value_timestamp syntax the duckdb_timestamp value at the specified location or 0 if the value cannot be converted duckdb_value_interval syntax the duckdb_interval value at the specified location or 0 if the value cannot be converted duckdb_value_varchar syntax use duckdb_value_string instead this function does not work correctly if the string contains null bytes returns the text value at the specified location as a null-terminated string or nullptr if the value cannot be converted the result must be freed with duckdb_free duckdb_value_varchar_internal syntax use duckdb_value_string_internal instead this function does not work correctly if the string contains null bytes returns the char value at the specified location only works on varchar columns and does not auto-cast if the column is not a varchar column this function will return null the result must not be freed duckdb_value_string_internal syntax use duckdb_value_string_internal instead this function does not work correctly if the string contains null bytes returns the char value at the specified location only works on varchar columns and does not auto-cast if the column is not a varchar column this function will return null the result must not be freed duckdb_value_blob syntax the duckdb_blob value at the specified location returns a blob with blob data set to nullptr if the value cannot be converted the resulting blob data must be freed with duckdb_free duckdb_value_is_null syntax returns true if the value at the specified index is null and false otherwise duckdb_malloc allocate size bytes of memory using the duckdb internal malloc function any memory allocated in this manner should be freed using duckdb_free syntax the number of bytes to allocate returns a pointer to the allocated memory region duckdb_free free a value returned from duckdb_malloc duckdb_value_varchar or duckdb_value_blob syntax the memory region to de-allocate duckdb_vector_size the internal vector size used by duckdb this is the amount of tuples that will fit into a data chunk created by duckdb_create_data_chunk syntax the vector size duckdb_string_is_inlined whether or not the duckdb_string_t value is inlined this means that the data of the string does not have a separate allocation syntax duckdb_from_date decompose a duckdb_date object into year month and date stored as duckdb_date_struct syntax the date object as obtained from a duckdb_type_date column returns the duckdb_date_struct with the decomposed elements duckdb_to_date re-compose a duckdb_date from year month and date duckdb_date_struct syntax the year month and date stored in a duckdb_date_struct returns the duckdb_date element duckdb_from_time decompose a duckdb_time object into hour minute second and microsecond stored as duckdb_time_struct syntax the time object as obtained from a duckdb_type_time column returns the duckdb_time_struct with the decomposed elements duckdb_to_time re-compose a duckdb_time from hour minute second and microsecond duckdb_time_struct syntax the hour minute second and microsecond in a duckdb_time_struct returns the duckdb_time element duckdb_from_timestamp decompose a duckdb_timestamp object into a duckdb_timestamp_struct syntax the ts object as obtained from a duckdb_type_timestamp column returns the duckdb_timestamp_struct with the decomposed elements duckdb_to_timestamp re-compose a duckdb_timestamp from a duckdb_timestamp_struct syntax the de-composed elements in a duckdb_timestamp_struct returns the duckdb_timestamp element duckdb_hugeint_to_double converts a duckdb_hugeint object as obtained from a duckdb_type_hugeint column into a double syntax the hugeint value returns the converted double element duckdb_double_to_hugeint converts a double value to a duckdb_hugeint object if the conversion fails because the double value is too big the result will be 0 syntax the double value returns the converted duckdb_hugeint element duckdb_double_to_decimal converts a double value to a duckdb_decimal object if the conversion fails because the double value is too big or the width scale are invalid the result will be 0 syntax the double value returns the converted duckdb_decimal element duckdb_decimal_to_double converts a duckdb_decimal object as obtained from a duckdb_type_decimal column into a double syntax the decimal value returns the converted double element duckdb_prepare create a prepared statement object from a query note that after calling duckdb_prepare the prepared statement should always be destroyed using duckdb_destroy_prepare even if the prepare fails if the prepare fails duckdb_prepare_error can be called to obtain the reason why the prepare failed syntax the connection object query the sql query to prepare out_prepared_statement the resulting prepared statement object returns duckdbsuccess on success or duckdberror on failure duckdb_destroy_prepare closes the prepared statement and de-allocates all memory allocated for the statement syntax the prepared statement to destroy duckdb_prepare_error returns the error message associated with the given prepared statement if the prepared statement has no error message this returns nullptr instead the error message should not be freed it will be de-allocated when duckdb_destroy_prepare is called syntax the prepared statement to obtain the error from returns the error message or nullptr if there is none duckdb_nparams returns the number of parameters that can be provided to the given prepared statement returns 0 if the query was not successfully prepared syntax the prepared statement to obtain the number of parameters for duckdb_param_type returns the parameter type for the parameter at the given index returns duckdb_type_invalid if the parameter index is out of range or the statement was not successfully prepared syntax the prepared statement param_idx the parameter index returns the parameter type duckdb_clear_bindings clear the params bind to the prepared statement syntax duckdb_bind_boolean binds a bool value to the prepared statement at the specified index syntax duckdb_bind_int8 binds an int8_t value to the prepared statement at the specified index syntax duckdb_bind_int16 binds an int16_t value to the prepared statement at the specified index syntax duckdb_bind_int32 binds an int32_t value to the prepared statement at the specified index syntax duckdb_bind_int64 binds an int64_t value to the prepared statement at the specified index syntax duckdb_bind_hugeint binds an duckdb_hugeint value to the prepared statement at the specified index syntax duckdb_bind_decimal binds a duckdb_decimal value to the prepared statement at the specified index syntax duckdb_bind_uint8 binds an uint8_t value to the prepared statement at the specified index syntax duckdb_bind_uint16 binds an uint16_t value to the prepared statement at the specified index syntax duckdb_bind_uint32 binds an uint32_t value to the prepared statement at the specified index syntax duckdb_bind_uint64 binds an uint64_t value to the prepared statement at the specified index syntax duckdb_bind_float binds an float value to the prepared statement at the specified index syntax duckdb_bind_double binds an double value to the prepared statement at the specified index syntax duckdb_bind_date binds a duckdb_date value to the prepared statement at the specified index syntax duckdb_bind_time binds a duckdb_time value to the prepared statement at the specified index syntax duckdb_bind_timestamp binds a duckdb_timestamp value to the prepared statement at the specified index syntax duckdb_bind_interval binds a duckdb_interval value to the prepared statement at the specified index syntax duckdb_bind_varchar binds a null-terminated varchar value to the prepared statement at the specified index syntax duckdb_bind_varchar_length binds a varchar value to the prepared statement at the specified index syntax duckdb_bind_blob binds a blob value to the prepared statement at the specified index syntax duckdb_bind_null binds a null value to the prepared statement at the specified index syntax duckdb_execute_prepared executes the prepared statement with the given bound parameters and returns a materialized query result this method can be called multiple times for each prepared statement and the parameters can be modified between calls to this function syntax the prepared statement to execute out_result the query result returns duckdbsuccess on success or duckdberror on failure duckdb_execute_prepared_arrow executes the prepared statement with the given bound parameters and returns an arrow query result syntax the prepared statement to execute out_result the query result returns duckdbsuccess on success or duckdberror on failure duckdb_arrow_scan scans the arrow stream and creates a view with the given name syntax the connection on which to execute the scan table_name name of the temporary view to create arrow arrow stream wrapper returns duckdbsuccess on success or duckdberror on failure duckdb_arrow_array_scan scans the arrow array and creates a view with the given name syntax the connection on which to execute the scan table_name name of the temporary view to create arrow_schema arrow schema wrapper arrow_array arrow array wrapper out_stream output array stream that wraps around the passed schema for releasing deleting once done returns duckdbsuccess on success or duckdberror on failure duckdb_extract_statements extract all statements from a query note that after calling duckdb_extract_statements the extracted statements should always be destroyed using duckdb_destroy_extracted even if no statements were extracted if the extract fails duckdb_extract_statements_error can be called to obtain the reason why the extract failed syntax the connection object query the sql query to extract out_extracted_statements the resulting extracted statements object returns the number of extracted statements or 0 on failure duckdb_prepare_extracted_statement prepare an extracted statement note that after calling duckdb_prepare_extracted_statement the prepared statement should always be destroyed using duckdb_destroy_prepare even if the prepare fails if the prepare fails duckdb_prepare_error can be called to obtain the reason why the prepare failed syntax the connection object extracted_statements the extracted statements object index the index of the extracted statement to prepare out_prepared_statement the resulting prepared statement object returns duckdbsuccess on success or duckdberror on failure duckdb_extract_statements_error returns the error message contained within the extracted statements the result of this function must not be freed it will be cleaned up when duckdb_destroy_extracted is called syntax the extracted statements to fetch the error from returns the error of the extracted statements duckdb_destroy_extracted de-allocates all memory allocated for the extracted statements syntax the extracted statements to destroy duckdb_pending_prepared executes the prepared statement with the given bound parameters and returns a pending result the pending result represents an intermediate structure for a query that is not yet fully executed the pending result can be used to incrementally execute a query returning control to the client between tasks note that after calling duckdb_pending_prepared the pending result should always be destroyed using duckdb_destroy_pending even if this function returns duckdberror syntax the prepared statement to execute out_result the pending query result returns duckdbsuccess on success or duckdberror on failure duckdb_pending_prepared_streaming executes the prepared statement with the given bound parameters and returns a pending result this pending result will create a streaming duckdb_result when executed the pending result represents an intermediate structure for a query that is not yet fully executed note that after calling duckdb_pending_prepared_streaming the pending result should always be destroyed using duckdb_destroy_pending even if this function returns duckdberror syntax the prepared statement to execute out_result the pending query result returns duckdbsuccess on success or duckdberror on failure duckdb_destroy_pending closes the pending result and de-allocates all memory allocated for the result syntax the pending result to destroy duckdb_pending_error returns the error message contained within the pending result the result of this function must not be freed it will be cleaned up when duckdb_destroy_pending is called syntax the pending result to fetch the error from returns the error of the pending result duckdb_pending_execute_task executes a single task within the query returning whether or not the query is ready if this returns duckdb_pending_result_ready the duckdb_execute_pending function can be called to obtain the result if this returns duckdb_pending_result_not_ready the duckdb_pending_execute_task function should be called again if this returns duckdb_pending_error an error occurred during execution the error message can be obtained by calling duckdb_pending_error on the pending_result syntax the pending result to execute a task within returns the state of the pending result after the execution duckdb_execute_pending fully execute a pending query result returning the final query result if duckdb_pending_execute_task has been called until duckdb_pending_result_ready was returned this will return fast otherwise all remaining tasks must be executed first syntax the pending result to execute out_result the result object returns duckdbsuccess on success or duckdberror on failure duckdb_destroy_value destroys the value and de-allocates all memory allocated for that type syntax the value to destroy duckdb_create_varchar creates a value from a null-terminated string syntax the null-terminated string returns the value this must be destroyed with duckdb_destroy_value duckdb_create_varchar_length creates a value from a string syntax the text length the length of the text returns the value this must be destroyed with duckdb_destroy_value duckdb_create_int64 creates a value from an int64 syntax the bigint value returns the value this must be destroyed with duckdb_destroy_value duckdb_get_varchar obtains a string representation of the given value the result must be destroyed with duckdb_free syntax the value returns the string value this must be destroyed with duckdb_free duckdb_get_int64 obtains an int64 of the given value syntax the value returns the int64 value or 0 if no conversion is possible duckdb_create_logical_type creates a duckdb_logical_type from a standard primitive type the resulting type should be destroyed with duckdb_destroy_logical_type this should not be used with duckdb_type_decimal syntax the primitive type to create returns the logical type duckdb_create_list_type creates a list type from its child type the resulting type should be destroyed with duckdb_destroy_logical_type syntax the child type of list type to create returns the logical type duckdb_create_map_type creates a map type from its key type and value type the resulting type should be destroyed with duckdb_destroy_logical_type syntax the key type and value type of map type to create returns the logical type duckdb_create_union_type creates a union type from the passed types array the resulting type should be destroyed with duckdb_destroy_logical_type syntax the array of types that the union should consist of type_amount the size of the types array returns the logical type duckdb_create_decimal_type creates a duckdb_logical_type of type decimal with the specified width and scale the resulting type should be destroyed with duckdb_destroy_logical_type syntax the width of the decimal type scale the scale of the decimal type returns the logical type duckdb_get_type_id retrieves the type class of a duckdb_logical_type syntax the logical type object returns the type id duckdb_decimal_width retrieves the width of a decimal type syntax the logical type object returns the width of the decimal type duckdb_decimal_scale retrieves the scale of a decimal type syntax the logical type object returns the scale of the decimal type duckdb_decimal_internal_type retrieves the internal storage type of a decimal type syntax the logical type object returns the internal type of the decimal type duckdb_enum_internal_type retrieves the internal storage type of an enum type syntax the logical type object returns the internal type of the enum type duckdb_enum_dictionary_size retrieves the dictionary size of the enum type syntax the logical type object returns the dictionary size of the enum type duckdb_enum_dictionary_value retrieves the dictionary value at the specified position from the enum the result must be freed with duckdb_free syntax the logical type object index the index in the dictionary returns the string value of the enum type must be freed with duckdb_free duckdb_list_type_child_type retrieves the child type of the given list type the result must be freed with duckdb_destroy_logical_type syntax the logical type object returns the child type of the list type must be destroyed with duckdb_destroy_logical_type duckdb_map_type_key_type retrieves the key type of the given map type the result must be freed with duckdb_destroy_logical_type syntax the logical type object returns the key type of the map type must be destroyed with duckdb_destroy_logical_type duckdb_map_type_value_type retrieves the value type of the given map type the result must be freed with duckdb_destroy_logical_type syntax the logical type object returns the value type of the map type must be destroyed with duckdb_destroy_logical_type duckdb_struct_type_child_count returns the number of children of a struct type syntax the logical type object returns the number of children of a struct type duckdb_struct_type_child_name retrieves the name of the struct child the result must be freed with duckdb_free syntax the logical type object index the child index returns the name of the struct type must be freed with duckdb_free duckdb_struct_type_child_type retrieves the child type of the given struct type at the specified index the result must be freed with duckdb_destroy_logical_type syntax the logical type object index the child index returns the child type of the struct type must be destroyed with duckdb_destroy_logical_type duckdb_union_type_member_count returns the number of members that the union type has syntax the logical type union object returns the number of members of a union type duckdb_union_type_member_name retrieves the name of the union member the result must be freed with duckdb_free syntax the logical type object index the child index returns the name of the union member must be freed with duckdb_free duckdb_union_type_member_type retrieves the child type of the given union member at the specified index the result must be freed with duckdb_destroy_logical_type syntax the logical type object index the child index returns the child type of the union member must be destroyed with duckdb_destroy_logical_type duckdb_destroy_logical_type destroys the logical type and de-allocates all memory allocated for that type syntax the logical type to destroy duckdb_create_data_chunk creates an empty datachunk with the specified set of types syntax an array of types of the data chunk column_count the number of columns returns the data chunk duckdb_destroy_data_chunk destroys the data chunk and de-allocates all memory allocated for that chunk syntax the data chunk to destroy duckdb_data_chunk_reset resets a data chunk clearing the validity masks and setting the cardinality of the data chunk to 0 syntax the data chunk to reset duckdb_data_chunk_get_column_count retrieves the number of columns in a data chunk syntax the data chunk to get the data from returns the number of columns in the data chunk duckdb_data_chunk_get_vector retrieves the vector at the specified column index in the data chunk the pointer to the vector is valid for as long as the chunk is alive it does not need to be destroyed syntax the data chunk to get the data from returns the vector duckdb_data_chunk_get_size retrieves the current number of tuples in a data chunk syntax the data chunk to get the data from returns the number of tuples in the data chunk duckdb_data_chunk_set_size sets the current number of tuples in a data chunk syntax the data chunk to set the size in size the number of tuples in the data chunk duckdb_vector_get_column_type retrieves the column type of the specified vector the result must be destroyed with duckdb_destroy_logical_type syntax the vector get the data from returns the type of the vector duckdb_vector_get_data retrieves the data pointer of the vector the data pointer can be used to read or write values from the vector how to read or write values depends on the type of the vector syntax the vector to get the data from returns the data pointer duckdb_vector_get_validity retrieves the validity mask pointer of the specified vector if all values are valid this function might return null the validity mask is a bitset that signifies null-ness within the data chunk it is a series of uint64_t values where each uint64_t value contains validity for 64 tuples the bit is set to 1 if the value is valid i e not null or 0 if the value is invalid i e null validity of a specific value can be obtained like this idx_t entry_idx row_idx 64 idx_t idx_in_entry row_idx 64 bool is_valid validity_mask entry_idx 1 idx_in_entry alternatively the slower duckdb_validity_row_is_valid function can be used syntax the vector to get the data from returns the pointer to the validity mask or null if no validity mask is present duckdb_vector_ensure_validity_writable ensures the validity mask is writable by allocating it after this function is called duckdb_vector_get_validity will always return non-null this allows null values to be written to the vector regardless of whether a validity mask was present before syntax the vector to alter duckdb_vector_assign_string_element assigns a string element in the vector at the specified location syntax the vector to alter index the row position in the vector to assign the string to str the null-terminated string duckdb_vector_assign_string_element_len assigns a string element in the vector at the specified location syntax the vector to alter index the row position in the vector to assign the string to str the string str_len the length of the string in bytes duckdb_list_vector_get_child retrieves the child vector of a list vector the resulting vector is valid as long as the parent vector is valid syntax the vector returns the child vector duckdb_list_vector_get_size returns the size of the child vector of the list syntax the vector returns the size of the child list duckdb_list_vector_set_size sets the total size of the underlying child-vector of a list vector syntax the list vector size the size of the child list returns the duckdb state returns duckdberror if the vector is nullptr duckdb_list_vector_reserve sets the total capacity of the underlying child-vector of a list syntax the list vector required_capacity the total capacity to reserve return the duckdb state returns duckdberror if the vector is nullptr duckdb_struct_vector_get_child retrieves the child vector of a struct vector the resulting vector is valid as long as the parent vector is valid syntax the vector index the child index returns the child vector duckdb_validity_row_is_valid returns whether or not a row is valid i e not null in the given validity mask syntax the validity mask as obtained through duckdb_data_chunk_get_validity row the row index returns true if the row is valid false otherwise duckdb_validity_set_row_validity in a validity mask sets a specific row to either valid or invalid note that duckdb_data_chunk_ensure_validity_writable should be called before calling duckdb_data_chunk_get_validity to ensure that there is a validity mask to write to syntax the validity mask as obtained through duckdb_data_chunk_get_validity row the row index valid whether or not to set the row to valid or invalid duckdb_validity_set_row_invalid in a validity mask sets a specific row to invalid equivalent to duckdb_validity_set_row_validity with valid set to false syntax the validity mask row the row index duckdb_validity_set_row_valid in a validity mask sets a specific row to valid equivalent to duckdb_validity_set_row_validity with valid set to true syntax the validity mask row the row index duckdb_create_table_function creates a new empty table function the return value should be destroyed with duckdb_destroy_table_function syntax the table function object duckdb_destroy_table_function destroys the given table function object syntax the table function to destroy duckdb_table_function_set_name sets the name of the given table function syntax the table function name the name of the table function duckdb_table_function_add_parameter adds a parameter to the table function syntax 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 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 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 the table function bind the bind function duckdb_table_function_set_init sets the init function of the table function syntax the table function init the init function duckdb_table_function_set_local_init sets the thread-local init function of the table function syntax the table function init the init function duckdb_table_function_set_function sets the main function of the table function syntax 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 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 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 the info object returns the extra info duckdb_bind_add_result_column adds a result column to the output of the table function syntax 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 the info object returns the init data object duckdb_function_set_error report that an error has occurred while executing the function syntax the info object error the error message duckdb_add_replacement_scan add a replacement scan definition to the specified database syntax the database object to add the replacement scan to replacement the replacement scan callback extra_data extra data that is passed back into the specified callback delete_callback the delete callback to call on the extra data if any duckdb_replacement_scan_set_function_name sets the replacement function name to use if this function is called in the replacement callback the replacement scan is performed if it is not called the replacement callback is not performed syntax the info object function_name the function name to substitute duckdb_replacement_scan_add_parameter adds a parameter to the replacement scan function syntax the info object parameter the parameter to add duckdb_replacement_scan_set_error report that an error has occurred while executing the replacement scan syntax the info object error the error message duckdb_appender_create creates an appender object syntax the connection context to create the appender in schema the schema of the table to append to or nullptr for the default schema table the table name to append to out_appender the resulting appender object returns duckdbsuccess on success or duckdberror on failure duckdb_appender_error returns the error message associated with the given appender if the appender has no error message this returns nullptr instead the error message should not be freed it will be de-allocated when duckdb_appender_destroy is called syntax the appender to get the error from returns the error message or nullptr if there is none duckdb_appender_flush flush the appender to the table forcing the cache of the appender to be cleared and the data to be appended to the base table this should generally not be used unless you know what you are doing instead call duckdb_appender_destroy when you are done with the appender syntax the appender to flush returns duckdbsuccess on success or duckdberror on failure duckdb_appender_close close the appender flushing all intermediate state in the appender to the table and closing it for further appends this is generally not necessary call duckdb_appender_destroy instead syntax the appender to flush and close returns duckdbsuccess on success or duckdberror on failure duckdb_appender_destroy close the appender and destroy it flushing all intermediate state in the appender to the table and de-allocating all memory associated with the appender syntax the appender to flush close and destroy returns duckdbsuccess on success or duckdberror on failure duckdb_appender_begin_row a nop function provided for backwards compatibility reasons does nothing only duckdb_appender_end_row is required syntax duckdb_appender_end_row finish the current row of appends after end_row is called the next row can be appended syntax the appender returns duckdbsuccess on success or duckdberror on failure duckdb_append_bool append a bool value to the appender syntax duckdb_append_int8 append an int8_t value to the appender syntax duckdb_append_int16 append an int16_t value to the appender syntax duckdb_append_int32 append an int32_t value to the appender syntax duckdb_append_int64 append an int64_t value to the appender syntax duckdb_append_hugeint append a duckdb_hugeint value to the appender syntax duckdb_append_uint8 append a uint8_t value to the appender syntax duckdb_append_uint16 append a uint16_t value to the appender syntax duckdb_append_uint32 append a uint32_t value to the appender syntax duckdb_append_uint64 append a uint64_t value to the appender syntax duckdb_append_float append a float value to the appender syntax duckdb_append_double append a double value to the appender syntax duckdb_append_date append a duckdb_date value to the appender syntax duckdb_append_time append a duckdb_time value to the appender syntax duckdb_append_timestamp append a duckdb_timestamp value to the appender syntax duckdb_append_interval append a duckdb_interval value to the appender syntax duckdb_append_varchar append a varchar value to the appender syntax duckdb_append_varchar_length append a varchar value to the appender syntax duckdb_append_blob append a blob value to the appender syntax duckdb_append_null append a null value to the appender of any type syntax duckdb_append_data_chunk appends a pre-filled data chunk to the specified appender the types of the data chunk must exactly match the types of the table no casting is performed if the types do not match or the appender is in an invalid state duckdberror is returned if the append is successful duckdbsuccess is returned syntax the appender to append to chunk the data chunk to append returns the return state duckdb_query_arrow executes a sql query within a connection and stores the full materialized result in an arrow structure if the query fails to execute duckdberror is returned and the error message can be retrieved by calling duckdb_query_arrow_error note that after running duckdb_query_arrow duckdb_destroy_arrow must be called on the result object even if the query fails otherwise the error stored within the result will not be freed correctly syntax the connection to perform the query in query the sql query to run out_result the query result returns duckdbsuccess on success or duckdberror on failure duckdb_query_arrow_schema fetch the internal arrow schema from the arrow result syntax the result to fetch the schema from out_schema the output schema returns duckdbsuccess on success or duckdberror on failure duckdb_query_arrow_array fetch an internal arrow array from the arrow result this function can be called multiple time to get next chunks which will free the previous out_array so consume the out_array before calling this function again syntax the result to fetch the array from out_array the output array returns duckdbsuccess on success or duckdberror on failure duckdb_arrow_column_count returns the number of columns present in a the arrow result object syntax the result object returns the number of columns present in the result object duckdb_arrow_row_count returns the number of rows present in a the arrow result object syntax the result object returns the number of rows present in the result object duckdb_arrow_rows_changed returns the number of rows changed by the query stored in the arrow result this is relevant only for insert update delete queries for other queries the rows_changed will be 0 syntax the result object returns the number of rows changed duckdb_query_arrow_error returns the error message contained within the result the error is only set if duckdb_query_arrow returns duckdberror the error message should not be freed it will be de-allocated when duckdb_destroy_arrow is called syntax the result object to fetch the nullmask from returns the error of the result duckdb_destroy_arrow closes the result and de-allocates all memory allocated for the arrow result syntax the result to destroy duckdb_execute_tasks execute duckdb tasks on this thread will return after max_tasks have been executed or if there are no more tasks present syntax the database object to execute tasks for max_tasks the maximum amount of tasks to execute duckdb_create_task_state creates a task state that can be used with duckdb_execute_tasks_state to execute tasks until duckdb_finish_execution is called on the state duckdb_destroy_state should be called on the result in order to free memory syntax the database object to create the task state for returns the task state that can be used with duckdb_execute_tasks_state duckdb_execute_tasks_state execute duckdb tasks on this thread the thread will keep on executing tasks forever until duckdb_finish_execution is called on the state multiple threads can share the same duckdb_task_state syntax the task state of the executor duckdb_execute_n_tasks_state execute duckdb tasks on this thread the thread will keep on executing tasks until either duckdb_finish_execution is called on the state max_tasks tasks have been executed or there are no more tasks to be executed multiple threads can share the same duckdb_task_state syntax the task state of the executor max_tasks the maximum amount of tasks to execute returns the amount of tasks that have actually been executed duckdb_finish_execution finish execution on a specific task syntax the task state to finish execution duckdb_task_state_is_finished check if the provided duckdb_task_state has finished execution syntax the task state to inspect returns whether or not duckdb_finish_execution has been called on the task state duckdb_destroy_task_state destroys the task state returned from duckdb_create_task_state note that this should not be called while there is an active duckdb_execute_tasks_state running on the task state syntax the task state to clean up duckdb_execution_is_finished returns true if execution of the current query is finished syntax the connection on which to check duckdb_stream_fetch_chunk fetches a data chunk from the streaming duckdb_result this function should be called repeatedly until the result is exhausted the result must be destroyed with duckdb_destroy_data_chunk this function can only be used on duckdb_results created with duckdb_pending_prepared_streaming if this function is used none of the other result functions can be used and vice versa i e this function cannot be mixed with the legacy result functions or the materialized result functions it is not known beforehand how many chunks will be returned by this result syntax the result object to fetch the data chunk from returns the resulting data chunk returns null if the result has an error", "category": "C", "url": "/docs/api/c/api", "blurb": "API Reference Open/Connect Syntax Path to the database file on disk, or nullptr or :memory: to open an in-memory..." @@ -184,7 +191,7 @@ }, { "title": "C API - Prepared Statements", - "text": "a prepared statement is a parameterized query the query is prepared with question marks or dollar symbols 1 indicating the parameters of the query values can then be bound to these parameters after which the prepared statement can be executed using those parameters a single query can be prepared once and executed many times prepared statements are useful to easily supply parameters to functions while avoiding string concatenation sql injection attacks speeding up queries that will be executed many times with different parameters duckdb supports prepared statements in the c api with the duckdb_prepare method the duckdb_bind family of functions is used to supply values for subsequent execution of the prepared statement using duckdb_execute_prepared after we are done with the prepared statement it can be cleaned up using the duckdb_destroy_prepare method example duckdb_prepared_statement stmt duckdb_result result if duckdb_prepare con insert into integers values 1 2 stmt duckdberror handle error duckdb_bind_int32 stmt 1 42 the parameter index starts counting at 1 duckdb_bind_int32 stmt 2 43 null as second parameter means no result set is requested duckdb_execute_prepared stmt null duckdb_destroy_prepare stmt we can also query result sets using prepared statements if duckdb_prepare con select from integers where i stmt duckdberror handle error duckdb_bind_int32 stmt 1 42 duckdb_execute_prepared stmt result do something with result clean up duckdb_destroy_result result duckdb_destroy_prepare stmt after calling duckdb_prepare the prepared statement parameters can be inspected using duckdb_nparams and duckdb_param_type in case the prepare fails the error can be obtained through duckdb_prepare_error it is not required that the duckdb_bind family of functions matches the prepared statement parameter type exactly the values will be auto-cast to the required value as required for example calling duckdb_bind_int8 on a parameter type of duckdb_type_integer will work as expected do not use prepared statements to insert large amounts of data into duckdb instead it is recommended to use the appender api reference note that after calling duckdb_prepare the prepared statement should always be destroyed using duckdb_destroy_prepare even if the prepare fails if the prepare fails duckdb_prepare_error can be called to obtain the reason why the prepare failed syntax the connection object query the sql query to prepare out_prepared_statement the resulting prepared statement object returns duckdbsuccess on success or duckdberror on failure duckdb_destroy_prepare closes the prepared statement and de-allocates all memory allocated for the statement syntax the prepared statement to destroy duckdb_prepare_error returns the error message associated with the given prepared statement if the prepared statement has no error message this returns nullptr instead the error message should not be freed it will be de-allocated when duckdb_destroy_prepare is called syntax the prepared statement to obtain the error from returns the error message or nullptr if there is none duckdb_nparams returns the number of parameters that can be provided to the given prepared statement returns 0 if the query was not successfully prepared syntax the prepared statement to obtain the number of parameters for duckdb_param_type returns the parameter type for the parameter at the given index returns duckdb_type_invalid if the parameter index is out of range or the statement was not successfully prepared syntax the prepared statement param_idx the parameter index returns the parameter type duckdb_clear_bindings clear the params bind to the prepared statement syntax duckdb_bind_boolean binds a bool value to the prepared statement at the specified index syntax duckdb_bind_int8 binds an int8_t value to the prepared statement at the specified index syntax duckdb_bind_int16 binds an int16_t value to the prepared statement at the specified index syntax duckdb_bind_int32 binds an int32_t value to the prepared statement at the specified index syntax duckdb_bind_int64 binds an int64_t value to the prepared statement at the specified index syntax duckdb_bind_hugeint binds an duckdb_hugeint value to the prepared statement at the specified index syntax duckdb_bind_decimal binds a duckdb_decimal value to the prepared statement at the specified index syntax duckdb_bind_uint8 binds an uint8_t value to the prepared statement at the specified index syntax duckdb_bind_uint16 binds an uint16_t value to the prepared statement at the specified index syntax duckdb_bind_uint32 binds an uint32_t value to the prepared statement at the specified index syntax duckdb_bind_uint64 binds an uint64_t value to the prepared statement at the specified index syntax duckdb_bind_float binds an float value to the prepared statement at the specified index syntax duckdb_bind_double binds an double value to the prepared statement at the specified index syntax duckdb_bind_date binds a duckdb_date value to the prepared statement at the specified index syntax duckdb_bind_time binds a duckdb_time value to the prepared statement at the specified index syntax duckdb_bind_timestamp binds a duckdb_timestamp value to the prepared statement at the specified index syntax duckdb_bind_interval binds a duckdb_interval value to the prepared statement at the specified index syntax duckdb_bind_varchar binds a null-terminated varchar value to the prepared statement at the specified index syntax duckdb_bind_varchar_length binds a varchar value to the prepared statement at the specified index syntax duckdb_bind_blob binds a blob value to the prepared statement at the specified index syntax duckdb_bind_null binds a null value to the prepared statement at the specified index syntax duckdb_execute_prepared executes the prepared statement with the given bound parameters and returns a materialized query result this method can be called multiple times for each prepared statement and the parameters can be modified between calls to this function syntax the prepared statement to execute out_result the query result returns duckdbsuccess on success or duckdberror on failure duckdb_execute_prepared_arrow executes the prepared statement with the given bound parameters and returns an arrow query result syntax the prepared statement to execute out_result the query result returns duckdbsuccess on success or duckdberror on failure", + "text": "a prepared statement is a parameterized query the query is prepared with question marks or dollar symbols 1 indicating the parameters of the query values can then be bound to these parameters after which the prepared statement can be executed using those parameters a single query can be prepared once and executed many times prepared statements are useful to easily supply parameters to functions while avoiding string concatenation sql injection attacks speeding up queries that will be executed many times with different parameters duckdb supports prepared statements in the c api with the duckdb_prepare method the duckdb_bind family of functions is used to supply values for subsequent execution of the prepared statement using duckdb_execute_prepared after we are done with the prepared statement it can be cleaned up using the duckdb_destroy_prepare method example duckdb_prepared_statement stmt duckdb_result result if duckdb_prepare con insert into integers values 1 2 stmt duckdberror handle error duckdb_bind_int32 stmt 1 42 the parameter index starts counting at 1 duckdb_bind_int32 stmt 2 43 null as second parameter means no result set is requested duckdb_execute_prepared stmt null duckdb_destroy_prepare stmt we can also query result sets using prepared statements if duckdb_prepare con select from integers where i stmt duckdberror handle error duckdb_bind_int32 stmt 1 42 duckdb_execute_prepared stmt result do something with result clean up duckdb_destroy_result result duckdb_destroy_prepare stmt after calling duckdb_prepare the prepared statement parameters can be inspected using duckdb_nparams and duckdb_param_type in case the prepare fails the error can be obtained through duckdb_prepare_error it is not required that the duckdb_bind family of functions matches the prepared statement parameter type exactly the values will be auto-cast to the required value as required for example calling duckdb_bind_int8 on a parameter type of duckdb_type_integer will work as expected do not use prepared statements to insert large amounts of data into duckdb instead it is recommended to use the appender api reference note that after calling duckdb_prepare the prepared statement should always be destroyed using duckdb_destroy_prepare even if the prepare fails if the prepare fails duckdb_prepare_error can be called to obtain the reason why the prepare failed syntax the connection object query the sql query to prepare out_prepared_statement the resulting prepared statement object returns duckdbsuccess on success or duckdberror on failure duckdb_destroy_prepare closes the prepared statement and de-allocates all memory allocated for the statement syntax the prepared statement to destroy duckdb_prepare_error returns the error message associated with the given prepared statement if the prepared statement has no error message this returns nullptr instead the error message should not be freed it will be de-allocated when duckdb_destroy_prepare is called syntax the prepared statement to obtain the error from returns the error message or nullptr if there is none duckdb_nparams returns the number of parameters that can be provided to the given prepared statement returns 0 if the query was not successfully prepared syntax the prepared statement to obtain the number of parameters for duckdb_param_type returns the parameter type for the parameter at the given index returns duckdb_type_invalid if the parameter index is out of range or the statement was not successfully prepared syntax the prepared statement param_idx the parameter index returns the parameter type duckdb_clear_bindings clear the params bind to the prepared statement syntax duckdb_bind_boolean binds a bool value to the prepared statement at the specified index syntax duckdb_bind_int8 binds an int8_t value to the prepared statement at the specified index syntax duckdb_bind_int16 binds an int16_t value to the prepared statement at the specified index syntax duckdb_bind_int32 binds an int32_t value to the prepared statement at the specified index syntax duckdb_bind_int64 binds an int64_t value to the prepared statement at the specified index syntax duckdb_bind_hugeint binds an duckdb_hugeint value to the prepared statement at the specified index syntax duckdb_bind_decimal binds a duckdb_decimal value to the prepared statement at the specified index syntax duckdb_bind_uint8 binds an uint8_t value to the prepared statement at the specified index syntax duckdb_bind_uint16 binds an uint16_t value to the prepared statement at the specified index syntax duckdb_bind_uint32 binds an uint32_t value to the prepared statement at the specified index syntax duckdb_bind_uint64 binds an uint64_t value to the prepared statement at the specified index syntax duckdb_bind_float binds an float value to the prepared statement at the specified index syntax duckdb_bind_double binds an double value to the prepared statement at the specified index syntax duckdb_bind_date binds a duckdb_date value to the prepared statement at the specified index syntax duckdb_bind_time binds a duckdb_time value to the prepared statement at the specified index syntax duckdb_bind_timestamp binds a duckdb_timestamp value to the prepared statement at the specified index syntax duckdb_bind_interval binds a duckdb_interval value to the prepared statement at the specified index syntax duckdb_bind_varchar binds a null-terminated varchar value to the prepared statement at the specified index syntax duckdb_bind_varchar_length binds a varchar value to the prepared statement at the specified index syntax duckdb_bind_blob binds a blob value to the prepared statement at the specified index syntax duckdb_bind_null binds a null value to the prepared statement at the specified index syntax duckdb_execute_prepared executes the prepared statement with the given bound parameters and returns a materialized query result this method can be called multiple times for each prepared statement and the parameters can be modified between calls to this function syntax the prepared statement to execute out_result the query result returns duckdbsuccess on success or duckdberror on failure duckdb_execute_prepared_arrow executes the prepared statement with the given bound parameters and returns an arrow query result syntax the prepared statement to execute out_result the query result returns duckdbsuccess on success or duckdberror on failure duckdb_arrow_scan scans the arrow stream and creates a view with the given name syntax the connection on which to execute the scan table_name name of the temporary view to create arrow arrow stream wrapper returns duckdbsuccess on success or duckdberror on failure duckdb_arrow_array_scan scans the arrow array and creates a view with the given name syntax the connection on which to execute the scan table_name name of the temporary view to create arrow_schema arrow schema wrapper arrow_array arrow array wrapper out_stream output array stream that wraps around the passed schema for releasing deleting once done returns duckdbsuccess on success or duckdberror on failure", "category": "C", "url": "/docs/api/c/prepared", "blurb": "A prepared statement is a parameterized query. The query is prepared with question marks ( ? ) or dollar symbols ( $1..." @@ -352,7 +359,7 @@ }, { "title": "Configuration", - "text": "duckdb has a number of configuration options that can be used to change the behavior of the system the configuration options can be set using either the set statement or the pragma statement they can also be reset to their original values using the reset statement examples -- set the memory limit of the system to 10gb set memory_limit 10gb -- configure the system to use 1 thread set threads to 1 -- enable printing of a progress bar during long-running queries set enable_progress_bar true -- set the default null order to nulls last pragma default_null_order nulls_last -- show a list of all available settings select from duckdb_settings -- return the current value of a specific setting -- this example returns automatic select current_setting access_mode -- reset the memory limit of the system back to the default reset memory_limit configuration reference below is a list of all available settings name description input_type default_value ------------------------------------------ --------------------------------------------------------------------------------------------------------------------------------------------------------- ------------ -------------------------- calendar the current calendar varchar system locale calendar timezone the current time zone varchar system locale timezone access_mode access mode of the database automatic read_only or read_write varchar automatic allow_unsigned_extensions allow to load extensions with invalid or missing signatures boolean false arrow_large_buffer_size if arrow buffers for strings blobs uuids and bits should be exported using large buffers boolean false binary_as_string in parquet files interpret binary data as a string boolean checkpoint_threshold wal_autocheckpoint the wal size threshold at which to automatically trigger a checkpoint e g 1gb varchar 16 7mb custom_extension_repository overrides the custom endpoint for remote extension installation varchar default_collation the collation setting used when none is specified varchar default_null_order null_order null ordering used when none is specified nulls_first or nulls_last varchar nulls_last default_order the order type used when none is specified asc or desc varchar asc enable_external_access allow the database to access external state through e g loading installing modules copy to from csv readers pandas replacement scans etc boolean true enable_fsst_vectors allow scans on fsst compressed segments to emit compressed vectors to utilize late decompression boolean false enable_http_metadata_cache whether or not the global http metadata is used to cache http metadata boolean false enable_object_cache whether or not object cache is used to cache e g parquet metadata boolean false enable_profiling enables profiling and sets the output format json query_tree query_tree_optimizer varchar null enable_progress_bar enables the progress bar printing progress to the terminal for long queries boolean false enable_progress_bar_print controls the printing of the progress bar when enable_progress_bar is true boolean true experimental_parallel_csv whether or not to use the experimental parallel csv reader boolean null explain_output output of explain statements all optimized_only physical_only varchar physical_only extension_directory set the directory to store extensions in varchar external_threads the number of external threads that work on duckdb tasks bigint 0 file_search_path a comma separated list of directories to search for input files varchar force_download forces upfront download of file boolean 0 home_directory sets the home directory used by the system varchar http_retries http retries on i o error default 3 ubigint 3 http_retry_backoff backoff factor for exponentially increasing retry wait time default 4 float 4 http_retry_wait_ms time between retries default 100ms ubigint 100 http_timeout http timeout read write connection retry default 30000ms ubigint 30000 immediate_transaction_mode whether transactions should be started lazily when needed or immediately when begin transaction is called boolean false integer_division whether or not the operator defaults to integer division or to floating point division boolean 0 lock_configuration whether or not the configuration can be altered boolean false log_query_path specifies the path to which queries should be logged default empty string queries are not logged varchar null max_expression_depth the maximum expression depth limit in the parser warning increasing this setting and using very deep expressions might lead to stack overflow errors ubigint 1000 max_memory memory_limit the maximum memory of the system e g 1gb varchar 75 of ram ordered_aggregate_threshold the number of rows to accumulate before sorting used for tuning ubigint 262144 password the password to use ignored for legacy compatibility varchar null perfect_ht_threshold threshold in bytes for when to use a perfect hash table default 12 bigint 12 pivot_limit the maximum numer of pivot columns in a pivot statement default 100000 bigint 100000 preserve_identifier_case whether or not to preserve the identifier case instead of always lowercasing all non-quoted identifiers boolean true preserve_insertion_order whether or not to preserve insertion order if set to false the system is allowed to re-order any results that do not contain order by clauses boolean true profile_output profiling_output the file to which profile output should be saved or empty to print to the terminal varchar profiler_history_size sets the profiler history size bigint null profiling_mode the profiling mode standard or detailed varchar null progress_bar_time sets the time in milliseconds how long a query needs to take before we start printing a progress bar bigint 2000 s3_access_key_id s3 access key id varchar s3_endpoint s3 endpoint default s3 amazonaws com varchar s3 amazonaws com s3_region s3 region varchar s3_secret_access_key s3 access key varchar s3_session_token s3 session token varchar s3_uploader_max_filesize s3 uploader max filesize between 50gb and 5tb default 800gb varchar 800gb s3_uploader_max_parts_per_file s3 uploader max parts per file between 1 and 10000 default 10000 ubigint 10000 s3_uploader_thread_limit s3 uploader global thread limit default 50 ubigint 50 s3_url_compatibility_mode disable globs and query parameters on s3 urls boolean 0 s3_url_style s3 url style vhost default or path varchar vhost s3_use_ssl s3 use ssl default true boolean 1 schema sets the default search schema equivalent to setting search_path to a single value varchar main search_path sets the default search search path as a comma-separated list of values varchar temp_directory set the directory to which to write temp files varchar threads worker_threads the number of total threads used by the system bigint cores username user the username to use ignored for legacy compatibility varchar null", + "text": "duckdb has a number of configuration options that can be used to change the behavior of the system the configuration options can be set using either the set statement or the pragma statement they can also be reset to their original values using the reset statement examples -- set the memory limit of the system to 10gb set memory_limit 10gb -- configure the system to use 1 thread set threads to 1 -- enable printing of a progress bar during long-running queries set enable_progress_bar true -- set the default null order to nulls last pragma default_null_order nulls_last -- show a list of all available settings select from duckdb_settings -- return the current value of a specific setting -- this example returns automatic select current_setting access_mode -- reset the memory limit of the system back to the default reset memory_limit configuration reference below is a list of all available settings name description input_type default_value ------------------------------------------ --------------------------------------------------------------------------------------------------------------------------------------------------------- ------------ -------------------------- calendar the current calendar varchar system locale calendar timezone the current time zone varchar system locale timezone access_mode access mode of the database automatic read_only or read_write varchar automatic allocator_flush_threshold peak allocation threshold at which to flush the allocator after completing a task varchar 134 2mb allow_unsigned_extensions allow to load extensions with invalid or missing signatures boolean false arrow_large_buffer_size if arrow buffers for strings blobs uuids and bits should be exported using large buffers boolean false binary_as_string in parquet files interpret binary data as a string boolean checkpoint_threshold wal_autocheckpoint the wal size threshold at which to automatically trigger a checkpoint e g 1gb varchar 16 7mb custom_extension_repository overrides the custom endpoint for remote extension installation varchar default_collation the collation setting used when none is specified varchar default_null_order null_order null ordering used when none is specified nulls_first or nulls_last varchar nulls_last default_order the order type used when none is specified asc or desc varchar asc disabled_filesystems disable specific file systems preventing access e g localfilesystem varchar enable_external_access allow the database to access external state through e g loading installing modules copy to from csv readers pandas replacement scans etc boolean true enable_fsst_vectors allow scans on fsst compressed segments to emit compressed vectors to utilize late decompression boolean false enable_http_metadata_cache whether or not the global http metadata is used to cache http metadata boolean false enable_object_cache whether or not object cache is used to cache e g parquet metadata boolean false enable_profiling enables profiling and sets the output format json query_tree query_tree_optimizer varchar null enable_progress_bar enables the progress bar printing progress to the terminal for long queries boolean false enable_progress_bar_print controls the printing of the progress bar when enable_progress_bar is true boolean true experimental_parallel_csv whether or not to use the experimental parallel csv reader boolean null explain_output output of explain statements all optimized_only physical_only varchar physical_only extension_directory set the directory to store extensions in varchar external_threads the number of external threads that work on duckdb tasks bigint 0 file_search_path a comma separated list of directories to search for input files varchar force_download forces upfront download of file boolean 0 home_directory sets the home directory used by the system varchar http_retries http retries on i o error default 3 ubigint 3 http_retry_backoff backoff factor for exponentially increasing retry wait time default 4 float 4 http_retry_wait_ms time between retries default 100ms ubigint 100 http_timeout http timeout read write connection retry default 30000ms ubigint 30000 immediate_transaction_mode whether transactions should be started lazily when needed or immediately when begin transaction is called boolean false integer_division whether or not the operator defaults to integer division or to floating point division boolean 0 lock_configuration whether or not the configuration can be altered boolean false log_query_path specifies the path to which queries should be logged default empty string queries are not logged varchar null max_expression_depth the maximum expression depth limit in the parser warning increasing this setting and using very deep expressions might lead to stack overflow errors ubigint 1000 max_memory memory_limit the maximum memory of the system e g 1gb varchar 75 of ram ordered_aggregate_threshold the number of rows to accumulate before sorting used for tuning ubigint 262144 password the password to use ignored for legacy compatibility varchar null perfect_ht_threshold threshold in bytes for when to use a perfect hash table default 12 bigint 12 pivot_filter_threshold the threshold to switch from using filtered aggregates to list with a dedicated pivot operator bigint 10 pivot_limit the maximum number of pivot columns in a pivot statement default 100000 bigint 100000 prefer_range_joins force use of range joins with mixed predicates boolean false preserve_identifier_case whether or not to preserve the identifier case instead of always lowercasing all non-quoted identifiers boolean true preserve_insertion_order whether or not to preserve insertion order if set to false the system is allowed to re-order any results that do not contain order by clauses boolean true profile_output profiling_output the file to which profile output should be saved or empty to print to the terminal varchar profiler_history_size sets the profiler history size bigint null profiling_mode the profiling mode standard or detailed varchar null progress_bar_time sets the time in milliseconds how long a query needs to take before we start printing a progress bar bigint 2000 s3_access_key_id s3 access key id varchar s3_endpoint s3 endpoint default s3 amazonaws com varchar s3 amazonaws com s3_region s3 region varchar s3_secret_access_key s3 access key varchar s3_session_token s3 session token varchar s3_uploader_max_filesize s3 uploader max filesize between 50gb and 5tb default 800gb varchar 800gb s3_uploader_max_parts_per_file s3 uploader max parts per file between 1 and 10000 default 10000 ubigint 10000 s3_uploader_thread_limit s3 uploader global thread limit default 50 ubigint 50 s3_url_compatibility_mode disable globs and query parameters on s3 urls boolean 0 s3_url_style s3 url style vhost default or path varchar vhost s3_use_ssl s3 use ssl default true boolean 1 schema sets the default search schema equivalent to setting search_path to a single value varchar main search_path sets the default search search path as a comma-separated list of values varchar temp_directory set the directory to which to write temp files varchar threads worker_threads the number of total threads used by the system bigint cores username user the username to use ignored for legacy compatibility varchar null", "category": "SQL", "url": "/docs/sql/configuration", "blurb": "DuckDB has a number of configuration options that can be used to change the behavior of the system. The configuration..." @@ -373,7 +380,7 @@ }, { "title": "Copy", - "text": "examples -- read a csv file into the lineitem table - using auto-detected options copy lineitem from lineitem csv auto_detect true -- read a parquet file into the lineitem table copy lineitem from lineitem pq format parquet -- read a json file into the lineitem table - using auto-detected options copy lineitem from lineitem json format json auto_detect true -- write a table to a csv file copy lineitem to lineitem csv format csv delimiter header -- write the result of a query to a parquet file copy select l_orderkey l_partkey from lineitem to lineitem parquet compression zstd copy statements copy moves data between duckdb and external files copy from imports data into duckdb from an external file copy to writes data from duckdb to an external file the copy command can be used for csv parquet and json files copy from copy from imports data from an external file into an existing table the data is appended to whatever data is in the table already the amount of columns inside the file must match the amount of columns in the table table_name and the contents of the columns must be convertible to the column types of the table in case this is not possible an error will be thrown if a list of columns is specified copy will only copy the data in the specified columns from the file if there are any columns in the table that are not in the column list copy from will insert the default values for those columns -- copy the contents of a comma-separated file test csv without a header into the table test copy test from test csv -- copy the contents of a comma-separated file with a header into the category table copy category from categories csv header -- copy the contents of lineitem tbl into the lineitem table where the contents are delimited by a pipe character copy lineitem from lineitem tbl delimiter -- copy the contents of lineitem tbl into the lineitem table where the delimiter quote character and presence of a header are automatically detected copy lineitem from lineitem tbl auto_detect true -- read the contents of a comma-separated file names csv into the name column of the category table any other columns of this table are filled with their default value copy category name from names csv -- read the contents of a parquet file lineitem parquet into the lineitem table copy lineitem from lineitem parquet format parquet -- read the contents of a newline-delimited json file lineitem ndjson into the lineitem table copy lineitem from lineitem ndjson format json -- read the contents of a json file lineitem json into the lineitem table copy lineitem from lineitem json format json array true syntax copy to copy to exports data from duckdb to an external csv or parquet file it has mostly the same set of options as copy from however in the case of copy to the options specify how the file should be written to disk any file created by copy to can be copied back into the database by using copy from with a similar set of options the copy to function can be called specifying either a table name or a query when a table name is specified the contents of the entire table will be written into the resulting file when a query is specified the query is executed and the result of the query is written to the resulting file -- copy the contents of the lineitem table to the file lineitem tbl where the columns are delimited by a pipe character including a header line copy lineitem to lineitem tbl delimiter header -- copy the l_orderkey column of the lineitem table to the file orderkey tbl copy lineitem l_orderkey to orderkey tbl delimiter -- copy the result of a query to the file query csv including a header with column names copy select 42 as a hello as b to query csv with header 1 delimiter -- copy the result of a query to the parquet file query parquet copy select 42 as a hello as b to query parquet format parquet -- copy the result of a query to the newline-delimited json file query ndjson copy select 42 as a hello as b to query ndjson format json -- copy the result of a query to the json file query json copy select 42 as a hello as b to query json format json array true syntax copy options zero or more copy options may be provided as a part of the copy operation the with specifier is optional but if any options are specified the parentheses are required parameter values can be passed in with or without wrapping in single quotes any option that is a boolean can be enabled or disabled in multiple ways you can write true on or 1 to enable the option and false off or 0 to disable it the boolean value can also be omitted in which case true is assumed the below options are applicable to all formats written with copy name description type default --- --- ---- ---- allow_overwrite whether or not to allow overwriting a directory if one already exists only has an effect when used with partition_by bool false format specifies the copy function to use the default is selected from the file extension e g parquet results in a parquet file being written read if the file extension is unknown csv is selected available options are csv parquet and json varchar auto partition_by the columns to partition by using a hive partitioning scheme see the partitioned writes section varchar empty per_thread_output generate one file per thread rather than one file in total this allows for faster parallel writing bool false use_tmp_file whether or not to write to a temporary file first if the original file exists target csv tmp this prevents overwriting an existing file with a broken file in case the writing is cancelled bool auto csv options the below options are applicable when writing csv files name description type default --- --- ---- ---- compression the compression type for the file by default this will be detected automatically from the file extension e g file csv gz will use gzip file csv will use none options are none gzip zstd varchar auto force_quote the list of columns to always add quotes to even if not required varchar dateformat specifies the date format to use when writing dates see date format varchar empty delim or sep the character that is written to separate columns within each row varchar escape the character that should appear before a character that matches the quote value varchar header whether or not to write a header for the csv file bool false nullstr the string that is written to represent a null value varchar empty quote the quoting character to be used when a data value is quoted varchar timestampformat specifies the date format to use when writing timestamps see date format varchar empty parquet options the below options are applicable when writing parquet files name description type default --- --- ---- ---- compression the compression format to use uncompressed snappy gzip or zstd varchar snappy row_group_size the target size of each row-group bigint 122880 json options the below options are applicable when writing json files name description type default --- --- ---- ---- compression the compression type for the file by default this will be detected automatically from the file extension e g file csv gz will use gzip file csv will use none options are none gzip zstd varchar auto dateformat specifies the date format to use when writing dates see date format varchar empty timestampformat specifies the date format to use when writing timestamps see date format varchar empty array whether to write a json array if true a json array of records is written if false newline-delimited json is written bool false", + "text": "examples -- read a csv file into the lineitem table - using auto-detected options copy lineitem from lineitem csv auto_detect true -- read a parquet file into the lineitem table copy lineitem from lineitem pq format parquet -- read a json file into the lineitem table - using auto-detected options copy lineitem from lineitem json format json auto_detect true -- write a table to a csv file copy lineitem to lineitem csv format csv delimiter header -- write the result of a query to a parquet file copy select l_orderkey l_partkey from lineitem to lineitem parquet compression zstd copy statements copy moves data between duckdb and external files copy from imports data into duckdb from an external file copy to writes data from duckdb to an external file the copy command can be used for csv parquet and json files copy from copy from imports data from an external file into an existing table the data is appended to whatever data is in the table already the amount of columns inside the file must match the amount of columns in the table table_name and the contents of the columns must be convertible to the column types of the table in case this is not possible an error will be thrown if a list of columns is specified copy will only copy the data in the specified columns from the file if there are any columns in the table that are not in the column list copy from will insert the default values for those columns -- copy the contents of a comma-separated file test csv without a header into the table test copy test from test csv -- copy the contents of a comma-separated file with a header into the category table copy category from categories csv header -- copy the contents of lineitem tbl into the lineitem table where the contents are delimited by a pipe character copy lineitem from lineitem tbl delimiter -- copy the contents of lineitem tbl into the lineitem table where the delimiter quote character and presence of a header are automatically detected copy lineitem from lineitem tbl auto_detect true -- read the contents of a comma-separated file names csv into the name column of the category table any other columns of this table are filled with their default value copy category name from names csv -- read the contents of a parquet file lineitem parquet into the lineitem table copy lineitem from lineitem parquet format parquet -- read the contents of a newline-delimited json file lineitem ndjson into the lineitem table copy lineitem from lineitem ndjson format json -- read the contents of a json file lineitem json into the lineitem table copy lineitem from lineitem json format json array true syntax copy to copy to exports data from duckdb to an external csv or parquet file it has mostly the same set of options as copy from however in the case of copy to the options specify how the file should be written to disk any file created by copy to can be copied back into the database by using copy from with a similar set of options the copy to function can be called specifying either a table name or a query when a table name is specified the contents of the entire table will be written into the resulting file when a query is specified the query is executed and the result of the query is written to the resulting file -- copy the contents of the lineitem table to the file lineitem tbl where the columns are delimited by a pipe character including a header line copy lineitem to lineitem tbl delimiter header -- copy the l_orderkey column of the lineitem table to the file orderkey tbl copy lineitem l_orderkey to orderkey tbl delimiter -- copy the result of a query to the file query csv including a header with column names copy select 42 as a hello as b to query csv with header 1 delimiter -- copy the result of a query to the parquet file query parquet copy select 42 as a hello as b to query parquet format parquet -- copy the result of a query to the newline-delimited json file query ndjson copy select 42 as a hello as b to query ndjson format json -- copy the result of a query to the json file query json copy select 42 as a hello as b to query json format json array true syntax copy options zero or more copy options may be provided as a part of the copy operation the with specifier is optional but if any options are specified the parentheses are required parameter values can be passed in with or without wrapping in single quotes any option that is a boolean can be enabled or disabled in multiple ways you can write true on or 1 to enable the option and false off or 0 to disable it the boolean value can also be omitted in which case true is assumed the below options are applicable to all formats written with copy name description type default --- --- ---- ---- allow_overwrite whether or not to allow overwriting a directory if one already exists only has an effect when used with partition_by bool false format specifies the copy function to use the default is selected from the file extension e g parquet results in a parquet file being written read if the file extension is unknown csv is selected available options are csv parquet and json varchar auto partition_by the columns to partition by using a hive partitioning scheme see the partitioned writes section varchar empty per_thread_output generate one file per thread rather than one file in total this allows for faster parallel writing bool false use_tmp_file whether or not to write to a temporary file first if the original file exists target csv tmp this prevents overwriting an existing file with a broken file in case the writing is cancelled bool auto csv options the below options are applicable when writing csv files name description type default --- --- ---- ---- compression the compression type for the file by default this will be detected automatically from the file extension e g file csv gz will use gzip file csv will use none options are none gzip zstd varchar auto force_quote the list of columns to always add quotes to even if not required varchar dateformat specifies the date format to use when writing dates see date format varchar empty delim or sep the character that is written to separate columns within each row varchar escape the character that should appear before a character that matches the quote value varchar header whether or not to write a header for the csv file bool false nullstr the string that is written to represent a null value varchar empty quote the quoting character to be used when a data value is quoted varchar timestampformat specifies the date format to use when writing timestamps see date format varchar empty parquet options the below options are applicable when writing parquet files name description type default --- --- ---- ---- compression the compression format to use uncompressed snappy gzip or zstd varchar snappy row_group_size the target size of each row-group bigint 122880 field_ids the field_id for each column pass auto to attempt to infer automatically struct empty some examples of field_ids are -- assign field_ids automatically copy select 128 as i to my parquet field_ids auto -- sets the field_id of column i to 42 copy select 128 as i to my parquet field_ids i 42 -- sets the field_id of column i to 42 and column j to 43 copy select 128 as i 256 as j to my parquet field_ids i 42 j 43 -- sets the field_id of column my_struct to 43 -- and column i nested inside my_struct to 43 copy select i 128 as my_struct to my parquet field_ids my_struct __duckdb_field_id 42 i 43 -- sets the field_id of column my_list to 42 -- and column element default name of list child to 43 copy select 128 256 as my_list to my parquet field_ids my_list __duckdb_field_id 42 element 43 -- sets the field_id of colum my_map to 42 -- and columns key and value default names of map children to 43 and 44 copy select map key1 128 key2 256 my_map to my parquet field_ids my_map __duckdb_field_id 42 key 43 value 44 json options the below options are applicable when writing json files name description type default --- --- ---- ---- compression the compression type for the file by default this will be detected automatically from the file extension e g file csv gz will use gzip file csv will use none options are none gzip zstd varchar auto dateformat specifies the date format to use when writing dates see date format varchar empty timestampformat specifies the date format to use when writing timestamps see date format varchar empty array whether to write a json array if true a json array of records is written if false newline-delimited json is written bool false", "category": "Statements", "url": "/docs/sql/statements/copy", "blurb": "Examples -- read a CSV file into the lineitem table - using auto-detected options COPY lineitem FROM 'lineitem.csv'..." @@ -406,6 +413,13 @@ "url": "/docs/sql/statements/create_table", "blurb": "The CREATE TABLE statement creates a table in the catalog. Examples -- create a table with two integer columns (i and..." }, + { + "title": "Create Type", + "text": "the create type statement defines a new type in the catalog examples -- create a simple enum type create type mood as enum happy sad curious -- create a simple struct type create type many_things as struct k integer l varchar -- create a simple union type create type one_thing as union number integer string varchar -- create a type alias create type x_index as integer syntax create type defines a new data type available to this duckdb instance these new types can then be inspected in the duckdb_types table extending these custom types to support custom operators such as the postgres operator would require c development but that can be done in an extension", + "category": "Statements", + "url": "/docs/sql/statements/create_type", + "blurb": "The CREATE Type statement defines a new type in the catalog. Examples -- create a simple enum type CREATE TYPE mood..." + }, { "title": "Create View", "text": "the create view statement defines a new view in the catalog examples -- create a simple view create view v1 as select from tbl -- create a view or replace it if a view with that name already exists create or replace view v1 as select 42 -- create a view and replace the column names create view v1 a as select 42 syntax create view defines a view of a query the view is not physically materialized instead the query is run every time the view is referenced in a query create or replace view is similar but if a view of the same name already exists it is replaced if a schema name is given then the view is created in the specified schema otherwise it is created in the current schema temporary views exist in a special schema so a schema name cannot be given when creating a temporary view the name of the view must be distinct from the name of any other view or table in the same schema", @@ -674,14 +688,14 @@ }, { "title": "GROUP BY Clause", - "text": "the group by clause specifies which grouping columns should be used to perform any aggregations in the select clause if the group by clause is specified the query is always an aggregate query even if no aggregations are present in the select clause when a group by clause is specified all tuples that have matching data in the grouping columns i e all tuples that belong to the same group will be combined the values of the grouping columns themselves are unchanged and any other columns can be combined using an aggregate function such as count sum avg etc normally the group by clause groups along a single dimension using the grouping sets cube or rollup clauses it is possible to group along multiple dimensions see the grouping sets page for more information examples -- count the number of entries in the addresses table that belong to each different city select city count from addresses group by city -- compute the average income per city per street_name select city street_name avg income from addresses group by city street_name syntax", + "text": "the group by clause specifies which grouping columns should be used to perform any aggregations in the select clause if the group by clause is specified the query is always an aggregate query even if no aggregations are present in the select clause when a group by clause is specified all tuples that have matching data in the grouping columns i e all tuples that belong to the same group will be combined the values of the grouping columns themselves are unchanged and any other columns can be combined using an aggregate function such as count sum avg etc group by all use group by all to group by all columns in the select statement that are not wrapped in aggregate functions this simplifies the syntax by allowing the columns list to be maintained in a single location and prevents bugs by keeping the select granularity aligned to the group by granularity ex prevents any duplication see examples below and additional examples in the friendlier sql with duckdb blog post multiple dimensions normally the group by clause groups along a single dimension using the grouping sets cube or rollup clauses it is possible to group along multiple dimensions see the grouping sets page for more information examples -- count the number of entries in the addresses table that belong to each different city select city count from addresses group by city -- compute the average income per city per street_name select city street_name avg income from addresses group by city street_name group by all examples -- group by city and street_name to remove any duplicate values select city street_name from addresses group by all -- group by city street_name -- compute the average income per city per street_name -- since income is wrapped in an aggregate function do not include it in the group by select city street_name avg income from addresses group by all -- group by city street_name syntax", "category": "Query Syntax", "url": "/docs/sql/query_syntax/groupby", "blurb": "The GROUP BY clause specifies which grouping columns should be used to perform any aggregations in the SELECT clause...." }, { "title": "GROUPING SETS", - "text": "grouping sets rollup and cube can be used in the group by clause to perform a grouping over multiple dimensions within the same query examples -- compute the average income along the provided four different dimensions -- signifies the empty set i e computing an ungrouped aggregate select city street_name avg income from addresses group by grouping sets city street_name city street_name -- compute the average income along the same dimensions select city street_name avg income from addresses group by cube city street_name -- compute the average income along the dimensions city street_name city and select city street_name avg income from addresses group by rollup city street_name description grouping sets perform the same aggregate across different group by clauses in a single query create table students course varchar type varchar insert into students course type values cs bachelor cs bachelor cs phd math masters cs null cs null math null select course type count from students group by grouping sets course type course type course type count_star cs bachelor 2 cs phd 1 math masters 1 cs null 2 math null 1 cs null 5 math null 2 null bachelor 2 null phd 1 null masters 1 null null 3 null null 7 in the above query we group across four different sets course type course type and the empty group the result contains null for a group which is not in the grouping set for the result i e the above query is equivalent to the following union statement -- group by course type select course type count from students group by course type union all -- group by type select null as course type count from students group by type union all -- group by course select course null as type count from students group by course union all -- group by nothing select null as course null as type count from students cube and rollup are syntactic sugar to easily produce commonly used grouping sets the rollup clause will produce all sub-groups of a grouping set e g rollup country city zip produces the grouping sets country city zip country city country this can be useful for producing different levels of detail of a group by clause this produces n 1 grouping sets where n is the amount of terms in the rollup clause cube produces grouping sets for all combinations of the inputs e g cube country city zip will produce country city zip country city country zip city zip country city zip this produces 2 n grouping sets grouping alias grouping_id is a special aggregate function that can be used in combination with grouping sets the grouping function takes as parameters a group and returns 0 if the group is included in the grouping for that row or 1 otherwise this is primarily useful because the grouping columns by which we do not aggregate return null which is ambiguous with groups that are actually the value null the grouping or grouping_id function can be used to distinguish these two cases syntax", + "text": "grouping sets rollup and cube can be used in the group by clause to perform a grouping over multiple dimensions within the same query note that this syntax is not compatible with group by all examples -- compute the average income along the provided four different dimensions -- signifies the empty set i e computing an ungrouped aggregate select city street_name avg income from addresses group by grouping sets city street_name city street_name -- compute the average income along the same dimensions select city street_name avg income from addresses group by cube city street_name -- compute the average income along the dimensions city street_name city and select city street_name avg income from addresses group by rollup city street_name description grouping sets perform the same aggregate across different group by clauses in a single query create table students course varchar type varchar insert into students course type values cs bachelor cs bachelor cs phd math masters cs null cs null math null select course type count from students group by grouping sets course type course type course type count_star cs bachelor 2 cs phd 1 math masters 1 cs null 2 math null 1 cs null 5 math null 2 null bachelor 2 null phd 1 null masters 1 null null 3 null null 7 in the above query we group across four different sets course type course type and the empty group the result contains null for a group which is not in the grouping set for the result i e the above query is equivalent to the following union statement -- group by course type select course type count from students group by course type union all -- group by type select null as course type count from students group by type union all -- group by course select course null as type count from students group by course union all -- group by nothing select null as course null as type count from students cube and rollup are syntactic sugar to easily produce commonly used grouping sets the rollup clause will produce all sub-groups of a grouping set e g rollup country city zip produces the grouping sets country city zip country city country this can be useful for producing different levels of detail of a group by clause this produces n 1 grouping sets where n is the amount of terms in the rollup clause cube produces grouping sets for all combinations of the inputs e g cube country city zip will produce country city zip country city country zip city zip country city zip this produces 2 n grouping sets grouping alias grouping_id is a special aggregate function that can be used in combination with grouping sets the grouping function takes as parameters a group and returns 0 if the group is included in the grouping for that row or 1 otherwise this is primarily useful because the grouping columns by which we do not aggregate return null which is ambiguous with groups that are actually the value null the grouping or grouping_id function can be used to distinguish these two cases syntax", "category": "Query Syntax", "url": "/docs/sql/query_syntax/grouping_sets", "blurb": "GROUPING SETS , ROLLUP and CUBE can be used in the GROUP BY clause to perform a grouping over multiple dimensions..." @@ -709,7 +723,7 @@ }, { "title": "HTTPFS", - "text": "the httpfs extension is a loadable extension implementing a file system that allows reading remote writing remote files for pure http s only file reading is supported for object storage using the s3 api the httpfs extension supports reading writing globbing files some clients come prebundled with this extension in which case it s not necessary to first install or even load the extension depending on the client you use no action may be required or you might have to install httpfs on first use and use load httpfs at the start of every session http s with the httpfs extension it is possible to directly query files over http s this currently works for csv json and parquet files select from https domain tld file extension for csv files files will be downloaded entirely in most cases due to the row-based nature of the format for parquet files duckdb can use a combination of the parquet metadata and http range requests to only download the parts of the file that are actually required by the query for example the query select column_a from https domain tld file parquet will only read the parquet metadata and the data for the column_a column in some cases even no actual data needs to be read at all as they only require reading the metadata select count from https domain tld file parquet scanning multiple files over http s is also supported select from parquet_scan https domain tld file1 parquet https domain tld file2 parquet s3 the httpfs extension supports reading writing globbing files on object storage servers using the s3 api requirements the httpfs filesystem is tested with aws s3 minio google cloud and lakefs other services that implement the s3 api should also work but not all features may be supported below is a list of which parts of the s3 api are required for each httpfs feature feature required s3 api features --- --- public file reads http range requests private file reads secret key or session token authentication file glob listobjectv2 file writes multipart upload configuration to be able to read or write from s3 the correct region should be set set s3_region us-east-1 optionally the endpoint can be configured in case a non-aws object storage server is used set s3_endpoint domain tld port if the endpoint is not ssl-enabled then run set s3_use_ssl false switching between path-style and vhost-style urls is possible using set s3_url_style path however note that this may also require updating the endpoint for example for aws s3 it is required to change the endpoint to s3 region amazonaws com after configuring the correct endpoint and region public files can be read to also read private files authentication credentials can be added set s3_access_key_id aws access key id set s3_secret_access_key aws secret access key alternatively session tokens are also supported and can be used instead set s3_session_token aws session token per-request configuration aside from the global s3 configuration described above specific configuration values can be used on a per-request basis this allows for use of multiple sets of credentials regions etc these are used by including them on the s3 url as query parameters all the individual configuration values listed above can be set as query parameters for instance s3 bucket file parquet s3_access_key_id accesskey s3_secret_access_key secretkey or select from s3 bucket file parquet s3_region region s3_session_token session_token t1 inner join s3 bucket file csv s3_access_key_id accesskey s3_secret_access_key secretkey t2 reading reading files from s3 is now as simple as select from s3 bucket file extension multiple files are also possible for example select from parquet_scan s3 bucket file1 parquet s3 bucket file2 parquet glob file globbing is implemented using the listobjectv2 api call and allows to use filesystem-like glob patterns to match multiple files for example select from parquet_scan s3 bucket parquet this query matches all files in the root of the bucket with the parquet extension several features for matching are supported such as to match any number of any character for any single character or 0-9 for a single character in a range of characters select count from parquet_scan s3 bucket folder 100 t 0-9 parquet a useful feature when using globs is the filename option which adds a column with the file that a row originated from select from parquet_scan s3 bucket parquet filename 1 could for example result in column_a column_b filename --- --- --- 1 examplevalue1 s3 bucket file1 parquet 2 examplevalue1 s3 bucket file2 parquet hive partitioning duckdb also offers support for the hive partitioning scheme in the hive partitioning scheme data is partitioned in separate files the columns by which the data is partitioned are not actually in the files but are encoded in the file path so for example let us consider three parquet files hive paritioned by year s3 bucket year 2012 file parquet s3 bucket year 2013 file parquet s3 bucket year 2014 file parquet if scanning these files with the hive_partitioning option enabled select from parquet_scan s3 bucket file parquet hive_partitioning 1 could result in column_a column_b year --- --- --- 1 examplevalue1 2012 2 examplevalue2 2013 3 examplevalue3 2014 note that the year column does not actually exist in the parquet files it is parsed from the filenames within duckdb however these columns behave just like regular columns for example filters can be applied on hive partition columns select from parquet_scan s3 bucket file parquet hive_partitioning 1 where year 2013 writing writing to s3 uses the multipart upload api this allows duckdb to robustly upload files at high speed writing to s3 works for both csv and parquet copy table_name to s3 bucket file extension partioned copy to s3 also works copy table to s3 my-bucket partitioned format parquet partition_by part_col_a part_col_b an automatic check is performed for existing files directories which is currently quite conservative and on s3 will add a bit of latency to disable this check and force writing an allow_overwrite flag is added copy table to s3 my-bucket partitioned format parquet partition_by part_col_a part_col_b allow_overwrite true the naming scheme of the written files looks like this s3 my-bucket partitioned part_col_a val part_col_b val data_ thread_number parquet configuration some additional configuration options exist for the s3 upload though the default values should suffice for most use cases setting description --- --- s3_uploader_max_parts_per_file used for part size calculation see aws docs s3_uploader_max_filesize used for part size calculation see aws docs s3_uploader_thread_limit maximum number of uploader threads", + "text": "the httpfs extension is a loadable extension implementing a file system that allows reading remote writing remote files for pure http s only file reading is supported for object storage using the s3 api the httpfs extension supports reading writing globbing files some clients come prebundled with this extension in which case it s not necessary to first install or even load the extension depending on the client you use no action may be required or you might have to install httpfs on first use and use load httpfs at the start of every session http s with the httpfs extension it is possible to directly query files over http s this currently works for csv json and parquet files select from https domain tld file extension for csv files files will be downloaded entirely in most cases due to the row-based nature of the format for parquet files duckdb can use a combination of the parquet metadata and http range requests to only download the parts of the file that are actually required by the query for example the query select column_a from https domain tld file parquet will only read the parquet metadata and the data for the column_a column in some cases even no actual data needs to be read at all as they only require reading the metadata select count from https domain tld file parquet scanning multiple files over http s is also supported select from read_parquet https domain tld file1 parquet https domain tld file2 parquet -- parquet_scan is an alias of read_parquet so they are equivalent select from parquet_scan https domain tld file1 parquet https domain tld file2 parquet s3 the httpfs extension supports reading writing globbing files on object storage servers using the s3 api requirements the httpfs filesystem is tested with aws s3 minio google cloud and lakefs other services that implement the s3 api should also work but not all features may be supported below is a list of which parts of the s3 api are required for each httpfs feature feature required s3 api features --- --- public file reads http range requests private file reads secret key or session token authentication file glob listobjectv2 file writes multipart upload configuration to be able to read or write from s3 the correct region should be set set s3_region us-east-1 optionally the endpoint can be configured in case a non-aws object storage server is used set s3_endpoint domain tld port if the endpoint is not ssl-enabled then run set s3_use_ssl false switching between path-style and vhost-style urls is possible using set s3_url_style path however note that this may also require updating the endpoint for example for aws s3 it is required to change the endpoint to s3 region amazonaws com after configuring the correct endpoint and region public files can be read to also read private files authentication credentials can be added set s3_access_key_id aws access key id set s3_secret_access_key aws secret access key alternatively session tokens are also supported and can be used instead set s3_session_token aws session token per-request configuration aside from the global s3 configuration described above specific configuration values can be used on a per-request basis this allows for use of multiple sets of credentials regions etc these are used by including them on the s3 url as query parameters all the individual configuration values listed above can be set as query parameters for instance s3 bucket file parquet s3_access_key_id accesskey s3_secret_access_key secretkey or select from s3 bucket file parquet s3_region region s3_session_token session_token t1 inner join s3 bucket file csv s3_access_key_id accesskey s3_secret_access_key secretkey t2 reading reading files from s3 is now as simple as select from s3 bucket file extension multiple files are also possible for example select from read_parquet s3 bucket file1 parquet s3 bucket file2 parquet glob file globbing is implemented using the listobjectv2 api call and allows to use filesystem-like glob patterns to match multiple files for example select from read_parquet s3 bucket parquet this query matches all files in the root of the bucket with the parquet extension several features for matching are supported such as to match any number of any character for any single character or 0-9 for a single character in a range of characters select count from read_parquet s3 bucket folder 100 t 0-9 parquet a useful feature when using globs is the filename option which adds a column with the file that a row originated from select from read_parquet s3 bucket parquet filename 1 could for example result in column_a column_b filename --- --- --- 1 examplevalue1 s3 bucket file1 parquet 2 examplevalue1 s3 bucket file2 parquet hive partitioning duckdb also offers support for the hive partitioning scheme in the hive partitioning scheme data is partitioned in separate files the columns by which the data is partitioned are not actually in the files but are encoded in the file path so for example let us consider three parquet files hive paritioned by year s3 bucket year 2012 file parquet s3 bucket year 2013 file parquet s3 bucket year 2014 file parquet if scanning these files with the hive_partitioning option enabled select from read_parquet s3 bucket file parquet hive_partitioning 1 could result in column_a column_b year --- --- --- 1 examplevalue1 2012 2 examplevalue2 2013 3 examplevalue3 2014 note that the year column does not actually exist in the parquet files it is parsed from the filenames within duckdb however these columns behave just like regular columns for example filters can be applied on hive partition columns select from read_parquet s3 bucket file parquet hive_partitioning 1 where year 2013 writing writing to s3 uses the multipart upload api this allows duckdb to robustly upload files at high speed writing to s3 works for both csv and parquet copy table_name to s3 bucket file extension partioned copy to s3 also works copy table to s3 my-bucket partitioned format parquet partition_by part_col_a part_col_b an automatic check is performed for existing files directories which is currently quite conservative and on s3 will add a bit of latency to disable this check and force writing an allow_overwrite flag is added copy table to s3 my-bucket partitioned format parquet partition_by part_col_a part_col_b allow_overwrite true the naming scheme of the written files looks like this s3 my-bucket partitioned part_col_a val part_col_b val data_ thread_number parquet configuration some additional configuration options exist for the s3 upload though the default values should suffice for most use cases setting description --- --- s3_uploader_max_parts_per_file used for part size calculation see aws docs s3_uploader_max_filesize used for part size calculation see aws docs s3_uploader_thread_limit maximum number of uploader threads", "category": "Extensions", "url": "/docs/extensions/httpfs", "blurb": "The httpfs extension is a loadable extension implementing a file system that allows reading remote/writing remote..." @@ -723,10 +737,10 @@ }, { "title": "Hive Partitioning", - "text": "examples -- read data from a hive partitioned data set select from parquet_scan orders parquet hive_partitioning 1 -- write a table to a hive partitioned data set copy orders to orders format parquet partition_by year month hive partitioning hive partitionining is a partitioning strategy that is used to split a table into multiple files based on partition keys the files are organized into folders within each folder the partition key has a value that is determined by the name of the folder below is an example of a hive partitioned file hierarchy the files are partitioned on two keys year and month orders year 2021 month 1 file1 parquet file2 parquet month 2 file3 parquet year 2022 month 11 file4 parquet file5 parquet month 12 file6 parquet files stored in this hierarchy can be read using the hive_partitioning flag select from parquet_scan orders parquet hive_partitioning 1 when we specify the hive_partitioning flag the values of the columns will be read from the directories filter pushdown filters on the partition keys are automatically pushed down into the files this way the system skips reading files that are not necessary to answer a query for example consider the following query on the above dataset select from parquet_scan orders parquet hive_partitioning 1 where year 2022 and month 11 when executing this query only the following files will be read orders year 2022 month 11 file4 parquet file5 parquet autodetection by default the system tries to infer if the provided files are in a hive partitioned hierarchy and if so the hive_partitioning flag is enabled automatically the autodetection will look at the names of the folders and search for a key value pattern this behaviour can be overridden by setting the hive_partitioning flag manually writing partitioned files see the partitioned writes section", + "text": "examples -- read data from a hive partitioned data set select from read_parquet orders parquet hive_partitioning 1 -- parquet_scan is an alias of read_parquet so they are equivalent select from parquet_scan orders parquet hive_partitioning 1 -- write a table to a hive partitioned data set copy orders to orders format parquet partition_by year month hive partitioning hive partitionining is a partitioning strategy that is used to split a table into multiple files based on partition keys the files are organized into folders within each folder the partition key has a value that is determined by the name of the folder below is an example of a hive partitioned file hierarchy the files are partitioned on two keys year and month orders year 2021 month 1 file1 parquet file2 parquet month 2 file3 parquet year 2022 month 11 file4 parquet file5 parquet month 12 file6 parquet files stored in this hierarchy can be read using the hive_partitioning flag select from read_parquet orders parquet hive_partitioning 1 when we specify the hive_partitioning flag the values of the columns will be read from the directories filter pushdown filters on the partition keys are automatically pushed down into the files this way the system skips reading files that are not necessary to answer a query for example consider the following query on the above dataset select from read_parquet orders parquet hive_partitioning 1 where year 2022 and month 11 when executing this query only the following files will be read orders year 2022 month 11 file4 parquet file5 parquet autodetection by default the system tries to infer if the provided files are in a hive partitioned hierarchy and if so the hive_partitioning flag is enabled automatically the autodetection will look at the names of the folders and search for a key value pattern this behaviour can be overridden by setting the hive_partitioning flag manually writing partitioned files see the partitioned writes section", "category": "Partitioning", "url": "/docs/data/partitioning/hive_partitioning", - "blurb": "Examples -- read data from a hive partitioned data set SELECT * FROM parquet_scan('orders/*/*/*.parquet',..." + "blurb": "Examples -- read data from a hive partitioned data set SELECT * FROM read_parquet('orders/*/*/*.parquet',..." }, { "title": "IN Operator", @@ -912,7 +926,7 @@ }, { "title": "Nested Functions", - "text": "this section describes functions and operators for examining and manipulating nested values there are three nested data types lists structs and maps list functions in the descriptions l is the three element list 4 5 6 function description example result -------------------------------------------------- ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ ----------------------------------------- ------------------ list index bracket notation serves as an alias for list_extract l 3 6 list_extract list index extract the index th 1-based value from the list list_extract l 3 6 list_element list index alias for list_extract list_element l 3 6 array_extract list index alias for list_extract array_extract l 3 6 list begin end bracket notation with colon is an alias for list_slice missing arguments are interpreted as null s l 2 3 5 6 list_slice list begin end extract a sublist using slice conventions null s are interpreted as the bounds of the list negative values are accepted list_slice l 2 null 5 6 array_slice list begin end alias for list_slice array_slice l 2 null 5 6 array_pop_front list returns the list without the first element array_pop_front l 5 6 array_pop_back list returns the list without the last element array_pop_back l 4 5 list_value any create a list containing the argument values list_value 4 5 6 4 5 6 list_pack any alias for list_value list_pack 4 5 6 4 5 6 len list return the length of the list len 1 2 3 3 array_length list alias for len array_length 1 2 3 3 unnest list unnests a list by one level note that this is a special function that alters the cardinality of the result see the unnest page for more details unnest 1 2 3 1 2 3 list_concat list1 list2 concatenates two lists list_concat 2 3 4 5 6 2 3 4 5 6 list_cat list1 list2 alias for list_concat list_cat 2 3 4 5 6 2 3 4 5 6 array_concat list1 list2 alias for list_concat array_concat 2 3 4 5 6 2 3 4 5 6 array_cat list1 list2 alias for list_concat array_cat 2 3 4 5 6 2 3 4 5 6 list_prepend element list prepends element to list list_prepend 3 4 5 6 3 4 5 6 array_prepend element list alias for list_prepend array_prepend 3 4 5 6 3 4 5 6 array_push_front list element alias for list_prepend array_push_front l 3 3 4 5 6 list_append list element appends element to list list_append 2 3 4 2 3 4 array_append list element alias for list_append array_append 2 3 4 2 3 4 array_push_back list element alias for list_append array_push_back l 7 4 5 6 7 list_contains list element returns true if the list contains the element list_contains 1 2 null 1 true list_has list element alias for list_contains list_has 1 2 null 1 true array_contains list element alias for list_contains array_contains 1 2 null 1 true array_has list element alias for list_contains array_has 1 2 null 1 true list_position list element returns the index of the element if the list contains the element list_contains 1 2 null 2 2 list_indexof list element alias for list_position list_indexof 1 2 null 2 2 array_position list element alias for list_position array_position 1 2 null 2 2 array_indexof list element alias for list_position array_indexof 1 2 null 2 2 list_aggregate list name executes the aggregate function name on the elements of list see the list aggregates section for more details list_aggregate 1 2 null min 1 list_aggr list name alias for list_aggregate list_aggr 1 2 null min 1 array_aggregate list name alias for list_aggregate array_aggregate 1 2 null min 1 array_aggr list name alias for list_aggregate array_aggr 1 2 null min 1 list_sort list sorts the elements of the list see the sorting lists section for more details about the sorting order and the null sorting order list_sort 3 6 1 2 1 2 3 6 array_sort list alias for list_sort array_sort 3 6 1 2 1 2 3 6 list_reverse_sort list sorts the elements of the list in reverse order see the sorting lists section for more details about the null sorting order list_reverse_sort 3 6 1 2 6 3 2 1 array_reverse_sort list alias for list_reverse_sort array_reverse_sort 3 6 1 2 6 3 2 1 list_transform list lambda returns a list that is the result of applying the lambda function to each element of the input list see the lambda functions section for more details list_transform l x - x 1 5 6 7 array_transform list lambda alias for list_transform array_transform l x - x 1 5 6 7 list_apply list lambda alias for list_transform list_apply l x - x 1 5 6 7 array_apply list lambda alias for list_transform array_apply l x - x 1 5 6 7 list_filter list lambda constructs a list from those elements of the input list for which the lambda function returns true see the lambda functions section for more details list_filter l x - x 4 5 6 array_filter list lambda alias for list_filter array_filter l x - x 4 5 6 list_distinct list removes all duplicates and nulls from a list does not preserve the original order list_distinct 1 1 null -3 1 5 1 5 -3 array_distinct list alias for list_distinct array_distinct 1 1 null -3 1 5 1 5 -3 list_unique list counts the unique elements of a list list_unique 1 1 null -3 1 5 3 array_unique list alias for list_unique array_unique 1 1 null -3 1 5 3 list_any_value list returns the first non-null value in the list list_any_value null -3 -3 list comprehension python-style list comprehension can be used to compute expressions over elements in a list for example select lower x for x in strings from values hello world t strings -- hello world select upper x for x in strings if len x 0 from values hello world t strings -- hello world struct functions function description example result --- --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- --- --- struct entry dot notation serves as an alias for struct_extract i 3 s string s string struct entry bracket notation serves as an alias for struct_extract i 3 s string s string row any create a struct containing the argument values if the values are column references the entry name will be the column name otherwise it will be the string vn where n is the 1-based position of the argument row i i 4 i 4 i 3 v2 3 v3 0 struct_extract struct entry extract the named entry from the struct struct_extract s i 4 struct_pack name any create a struct containing the argument values the entry name will be the bound variable name struct_pack i 4 s string i 3 s string struct_insert struct name any add field s value s to an existing struct with the argument values the entry name s will be the bound variable name s struct_insert a 1 b 2 a 1 b 2 map functions function description example result --- --- --- --- map entry alias for element_at map 100 5 a b 100 a element_at map key return a list containing the value for a given key or an empty list if the key is not contained in the map the type of the key provided in the second parameter must match the type of the map s keys else an error is returned element_at map 100 5 42 43 100 42 map_extract map key alias of element_at return a list containing the value for a given key or an empty list if the key is not contained in the map the type of the key provided in the second parameter must match the type of the map s keys else an error is returned map_extract map 100 5 42 43 100 42 cardinality map return the size of the map or the number of entries in the map cardinality map 4 2 a b 2 map_from_entries struct k v returns a map created from the entries of the array map_from_entries k 5 v val1 k 3 v val2 5 val1 3 val2 map returns an empty map map map_keys map return a list of all keys in the map map_keys map 100 5 42 43 100 42 map_values map return a list of all values in the map map_values map 100 5 42 43 5 33 map_entries map return a list of struct k v for each key-value pair in the map map_entries map 100 5 42 43 k 100 v 42 k 5 v 43 union functions function description example result --- --- --- --- union tag dot notation serves as an alias for union_extract union_value k hello k string union_extract union tag extract the value with the named tags from the union null if the tag is not currently selected union_extract s k hello union_value tag any create a single member union containing the argument value the tag of the value will be the bound variable name union_value k hello hello union k varchar union_tag union retrieve the currently selected tag of the union as an enum union_tag union_value k foo k range functions the functions range and generate_series create a list of values in the range between start and stop the start parameter is inclusive for the range function the stop parameter is exclusive while for generate_series it is inclusive based on the number of arguments the following variants exist range start stop step range start stop range stop generate_series start stop step generate_series start stop generate_series stop the default value of start is 0 and the default value of step is 1 select range 5 -- 0 1 2 3 4 select range 2 5 -- 2 3 4 select range 2 5 3 -- 2 select generate_series 5 -- 0 1 2 3 4 5 select generate_series 2 5 -- 2 3 4 5 select generate_series 2 5 3 -- 2 5 date ranges are also supported select from range date 1992-01-01 date 1992-03-01 interval 1 month range 1992-01-01 00 00 00 1992-02-01 00 00 00 list aggregates the function list_aggregate allows the execution of arbitrary existing aggregate functions on the elements of a list its first argument is the list column its second argument is the aggregate function name e g min histogram or sum list_aggregate accepts additional arguments after the aggregate function name these extra arguments are passed directly to the aggregate function which serves as the second argument of list_aggregate select list_aggregate 1 2 -4 null min -- -4 select list_aggregate 2 4 8 42 sum -- 56 select list_aggregate 1 2 null 2 10 3 last -- 2 10 3 select list_aggregate 2 4 8 42 string_agg -- 2 4 8 42 the following is a list of existing rewrites rewrites simplify the use of the list aggregate function by only taking the list column as their argument list_avg list_var_samp list_var_pop list_stddev_pop list_stddev_samp list_sem list_approx_count_distinct list_bit_xor list_bit_or list_bit_and list_bool_and list_bool_or list_count list_entropy list_last list_first list_kurtosis list_min list_max list_product list_skewness list_sum list_string_agg list_mode list_median list_mad and list_histogram select list_min 1 2 -4 null -- -4 select list_sum 2 4 8 42 -- 56 select list_last 1 2 null 2 10 3 -- 2 10 3 array_to_string concatenates list array elements using an optional delimiter select array_to_string 1 2 3 - as str -- 1-2-3 -- this is equivalent to the following sql select list_aggr 1 2 3 string_agg - as str -- 1-2-3 sorting lists the function list_sort sorts the elements of a list either in ascending or descending order in addition it allows to provide whether null values should be moved to the beginning or to the end of the list by default if no modifiers are provided duckdb sorts asc nulls first i e the values are sorted in ascending order and null values are placed first this is identical to the default sort order of sqlite the default sort order can be changed using these pragma statements list_sort leaves it open to the user whether they want to use the default sort order or a custom order list_sort takes up to two additional optional parameters the second parameter provides the sort order and can be either asc or desc the third parameter provides the null sort order and can be either nulls first or nulls last -- default sort order and default null sort order select list_sort 1 3 null 5 null -5 ---- null null -5 1 3 5 -- only providing the sort order select list_sort 1 3 null 2 asc ---- null 1 2 3 -- providing the sort order and the null sort order select list_sort 1 3 null 2 desc nulls first ---- null 3 2 1 list_reverse_sort has an optional second parameter providing the null sort order it can be either nulls first or nulls last -- default null sort order select list_sort 1 3 null 5 null -5 ---- null null -5 1 3 5 -- providing the null sort order select list_reverse_sort 1 3 null 2 nulls last ---- 3 2 1 null lambda functions parameter1 parameter2 - expression if the lambda function has only one parameter then the brackets can be omitted the parameters can have any names param - param 1 duck - contains concat duck db duck x y - x y transform list_transform list lambda returns a list that is the result of applying the lambda function to each element of the input list the lambda function must have exactly one left-hand side parameter the return type of the lambda function defines the type of the list elements -- incrementing each list element by one select list_transform 1 2 null 3 x - x 1 ---- 2 3 null 4 -- transforming strings select list_transform duck a b duck - concat duck db ---- duckdb adb bdb -- combining lambda functions with other functions select list_transform 5 null 6 x - coalesce x 0 1 ---- 6 1 7 filter list_filter list lambda constructs a list from those elements of the input list for which the lambda function returns true the lambda function must have exactly one left-hand side parameter and its return type must be of type boolean -- filter out negative values select list_filter 5 -6 null 7 x - x 0 ---- 5 7 -- divisible by 2 and 5 select list_filter list_filter 2 4 3 1 20 10 3 30 x - x 2 0 y - y 5 0 ---- 20 10 30 -- in combination with range to construct lists select list_filter 1 2 3 4 x - x 1 from range 4 ---- 1 2 3 4 2 3 4 3 4 4 lambda functions can be arbitrarily nested -- nested lambda functions to get all squares of even list elements select list_transform list_filter 0 1 2 3 4 5 x - x 2 0 y - y y ---- 0 4 16 generate_subscripts the generate_subscript arr dim function generates indexes along the dim th dimension of array arr select generate_subscripts 4 5 6 1 as i i 1 2 3 related functions there are also aggregate functions list and histogram that produces lists and lists of structs unnest is used to unnest a list by one level", + "text": "this section describes functions and operators for examining and manipulating nested values there are three nested data types lists structs and maps list functions in the descriptions l is the three element list 4 5 6 function description example result -------------------------------------------------- ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ ----------------------------------------- ------------------ list index bracket notation serves as an alias for list_extract l 3 6 list_extract list index extract the index th 1-based value from the list list_extract l 3 6 list_element list index alias for list_extract list_element l 3 6 array_extract list index alias for list_extract array_extract l 3 6 list begin end bracket notation with colon is an alias for list_slice missing arguments are interpreted as null s l 2 3 5 6 list_slice list begin end extract a sublist using slice conventions null s are interpreted as the bounds of the list negative values are accepted list_slice l 2 null 5 6 array_slice list begin end alias for list_slice array_slice l 2 null 5 6 array_pop_front list returns the list without the first element array_pop_front l 5 6 array_pop_back list returns the list without the last element array_pop_back l 4 5 list_value any create a list containing the argument values list_value 4 5 6 4 5 6 list_pack any alias for list_value list_pack 4 5 6 4 5 6 len list return the length of the list len 1 2 3 3 array_length list alias for len array_length 1 2 3 3 unnest list unnests a list by one level note that this is a special function that alters the cardinality of the result see the unnest page for more details unnest 1 2 3 1 2 3 flatten list_of_lists concatenate a list of lists into a single list this only flattens one level of the list see examples flatten 1 2 3 4 1 2 3 4 list_concat list1 list2 concatenates two lists list_concat 2 3 4 5 6 2 3 4 5 6 list_cat list1 list2 alias for list_concat list_cat 2 3 4 5 6 2 3 4 5 6 array_concat list1 list2 alias for list_concat array_concat 2 3 4 5 6 2 3 4 5 6 array_cat list1 list2 alias for list_concat array_cat 2 3 4 5 6 2 3 4 5 6 list_prepend element list prepends element to list list_prepend 3 4 5 6 3 4 5 6 array_prepend element list alias for list_prepend array_prepend 3 4 5 6 3 4 5 6 array_push_front list element alias for list_prepend array_push_front l 3 3 4 5 6 list_append list element appends element to list list_append 2 3 4 2 3 4 array_append list element alias for list_append array_append 2 3 4 2 3 4 array_push_back list element alias for list_append array_push_back l 7 4 5 6 7 list_contains list element returns true if the list contains the element list_contains 1 2 null 1 true list_has list element alias for list_contains list_has 1 2 null 1 true array_contains list element alias for list_contains array_contains 1 2 null 1 true array_has list element alias for list_contains array_has 1 2 null 1 true list_intersect list1 list2 returns a list of all the elements that exist in both l1 and l2 without duplicates list_intersect 1 2 3 2 3 4 2 3 array_intersect list1 list2 alias for list_intersect array_intersect 1 2 3 2 3 4 2 3 list_has_any list1 list2 returns true if any elements exist is both lists list_has_any 1 2 3 2 3 4 true array_has_any list1 list2 alias for list_has_any array_has_any 1 2 3 2 3 4 true list_has_all list sub-list returns true if all elements of sub-list exist in list list_has_all l 4 6 true array_has_all list sub-list alias for list_has_all array_has_all l 4 6 true list_position list element returns the index of the element if the list contains the element list_contains 1 2 null 2 2 list_indexof list element alias for list_position list_indexof 1 2 null 2 2 array_position list element alias for list_position array_position 1 2 null 2 2 array_indexof list element alias for list_position array_indexof 1 2 null 2 2 list_aggregate list name executes the aggregate function name on the elements of list see the list aggregates section for more details list_aggregate 1 2 null min 1 list_aggr list name alias for list_aggregate list_aggr 1 2 null min 1 array_aggregate list name alias for list_aggregate array_aggregate 1 2 null min 1 array_aggr list name alias for list_aggregate array_aggr 1 2 null min 1 list_sort list sorts the elements of the list see the sorting lists section for more details about the sorting order and the null sorting order list_sort 3 6 1 2 1 2 3 6 array_sort list alias for list_sort array_sort 3 6 1 2 1 2 3 6 list_reverse_sort list sorts the elements of the list in reverse order see the sorting lists section for more details about the null sorting order list_reverse_sort 3 6 1 2 6 3 2 1 array_reverse_sort list alias for list_reverse_sort array_reverse_sort 3 6 1 2 6 3 2 1 list_transform list lambda returns a list that is the result of applying the lambda function to each element of the input list see the lambda functions section for more details list_transform l x - x 1 5 6 7 array_transform list lambda alias for list_transform array_transform l x - x 1 5 6 7 list_apply list lambda alias for list_transform list_apply l x - x 1 5 6 7 array_apply list lambda alias for list_transform array_apply l x - x 1 5 6 7 list_filter list lambda constructs a list from those elements of the input list for which the lambda function returns true see the lambda functions section for more details list_filter l x - x 4 5 6 array_filter list lambda alias for list_filter array_filter l x - x 4 5 6 list_distinct list removes all duplicates and nulls from a list does not preserve the original order list_distinct 1 1 null -3 1 5 1 5 -3 array_distinct list alias for list_distinct array_distinct 1 1 null -3 1 5 1 5 -3 list_unique list counts the unique elements of a list list_unique 1 1 null -3 1 5 3 array_unique list alias for list_unique array_unique 1 1 null -3 1 5 3 list_any_value list returns the first non-null value in the list list_any_value null -3 -3 list_resize list size value resizes the list to contain size elements initializes new elements with value or null if value is not set list_resize 1 2 3 5 0 1 2 3 0 0 array_resize list size value alias for list_resize array_resize 1 2 3 5 0 1 2 3 0 0 list operators the following operators are supported for lists operator description example result ---------- ------------------------------------------------------------------------------------------- ---------------------------- ----------------- alias for list_intersect 1 2 3 4 5 2 5 5 6 2 5 alias for list_has_all where the list on the right of the operator is the sublist 1 2 3 4 3 4 3 true alias for list_has_all where the list on the left of the operator is the sublist 1 4 1 2 3 4 true alias for list_concat 1 2 3 4 5 6 1 2 3 4 5 6 list comprehension python-style list comprehension can be used to compute expressions over elements in a list for example select lower x for x in strings from values hello world t strings -- hello world select upper x for x in strings if len x 0 from values hello world t strings -- hello world struct functions function description example result ------------------------------------------------------ --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ------------------------------------- ----------------------------- struct entry dot notation serves as an alias for struct_extract i 3 s string s string struct entry bracket notation serves as an alias for struct_extract i 3 s string s string row any create a struct containing the argument values if the values are column references the entry name will be the column name otherwise it will be the string vn where n is the 1-based position of the argument row i i 4 i 4 i 3 v2 3 v3 0 struct_extract struct entry extract the named entry from the struct struct_extract s i 4 struct_pack name any create a struct containing the argument values the entry name will be the bound variable name struct_pack i 4 s string i 3 s string struct_insert struct name any add field s value s to an existing struct with the argument values the entry name s will be the bound variable name s struct_insert a 1 b 2 a 1 b 2 map functions function description example result --- --- --- --- map entry alias for element_at map 100 5 a b 100 a element_at map key return a list containing the value for a given key or an empty list if the key is not contained in the map the type of the key provided in the second parameter must match the type of the map s keys else an error is returned element_at map 100 5 42 43 100 42 map_extract map key alias of element_at return a list containing the value for a given key or an empty list if the key is not contained in the map the type of the key provided in the second parameter must match the type of the map s keys else an error is returned map_extract map 100 5 42 43 100 42 cardinality map return the size of the map or the number of entries in the map cardinality map 4 2 a b 2 map_from_entries struct k v returns a map created from the entries of the array map_from_entries k 5 v val1 k 3 v val2 5 val1 3 val2 map returns an empty map map map_keys map return a list of all keys in the map map_keys map 100 5 42 43 100 42 map_values map return a list of all values in the map map_values map 100 5 42 43 5 33 map_entries map return a list of struct k v for each key-value pair in the map map_entries map 100 5 42 43 k 100 v 42 k 5 v 43 union functions function description example result ------------------------------------------ -------------------------------------------------------------------------------------------------------------------- ------------------------------------- ---------------------------- union tag dot notation serves as an alias for union_extract union_value k hello k string union_extract union tag extract the value with the named tags from the union null if the tag is not currently selected union_extract s k hello union_value tag any create a single member union containing the argument value the tag of the value will be the bound variable name union_value k hello hello union k varchar union_tag union retrieve the currently selected tag of the union as an enum union_tag union_value k foo k range functions the functions range and generate_series create a list of values in the range between start and stop the start parameter is inclusive for the range function the stop parameter is exclusive while for generate_series it is inclusive based on the number of arguments the following variants exist range start stop step range start stop range stop generate_series start stop step generate_series start stop generate_series stop the default value of start is 0 and the default value of step is 1 select range 5 -- 0 1 2 3 4 select range 2 5 -- 2 3 4 select range 2 5 3 -- 2 select generate_series 5 -- 0 1 2 3 4 5 select generate_series 2 5 -- 2 3 4 5 select generate_series 2 5 3 -- 2 5 date ranges are also supported select from range date 1992-01-01 date 1992-03-01 interval 1 month range 1992-01-01 00 00 00 1992-02-01 00 00 00 list aggregates the function list_aggregate allows the execution of arbitrary existing aggregate functions on the elements of a list its first argument is the list column its second argument is the aggregate function name e g min histogram or sum list_aggregate accepts additional arguments after the aggregate function name these extra arguments are passed directly to the aggregate function which serves as the second argument of list_aggregate select list_aggregate 1 2 -4 null min -- -4 select list_aggregate 2 4 8 42 sum -- 56 select list_aggregate 1 2 null 2 10 3 last -- 2 10 3 select list_aggregate 2 4 8 42 string_agg -- 2 4 8 42 the following is a list of existing rewrites rewrites simplify the use of the list aggregate function by only taking the list column as their argument list_avg list_var_samp list_var_pop list_stddev_pop list_stddev_samp list_sem list_approx_count_distinct list_bit_xor list_bit_or list_bit_and list_bool_and list_bool_or list_count list_entropy list_last list_first list_kurtosis list_min list_max list_product list_skewness list_sum list_string_agg list_mode list_median list_mad and list_histogram select list_min 1 2 -4 null -- -4 select list_sum 2 4 8 42 -- 56 select list_last 1 2 null 2 10 3 -- 2 10 3 array_to_string concatenates list array elements using an optional delimiter select array_to_string 1 2 3 - as str -- 1-2-3 -- this is equivalent to the following sql select list_aggr 1 2 3 string_agg - as str -- 1-2-3 sorting lists the function list_sort sorts the elements of a list either in ascending or descending order in addition it allows to provide whether null values should be moved to the beginning or to the end of the list by default if no modifiers are provided duckdb sorts asc nulls first i e the values are sorted in ascending order and null values are placed first this is identical to the default sort order of sqlite the default sort order can be changed using these pragma statements list_sort leaves it open to the user whether they want to use the default sort order or a custom order list_sort takes up to two additional optional parameters the second parameter provides the sort order and can be either asc or desc the third parameter provides the null sort order and can be either nulls first or nulls last -- default sort order and default null sort order select list_sort 1 3 null 5 null -5 ---- null null -5 1 3 5 -- only providing the sort order select list_sort 1 3 null 2 asc ---- null 1 2 3 -- providing the sort order and the null sort order select list_sort 1 3 null 2 desc nulls first ---- null 3 2 1 list_reverse_sort has an optional second parameter providing the null sort order it can be either nulls first or nulls last -- default null sort order select list_sort 1 3 null 5 null -5 ---- null null -5 1 3 5 -- providing the null sort order select list_reverse_sort 1 3 null 2 nulls last ---- 3 2 1 null lambda functions parameter1 parameter2 - expression if the lambda function has only one parameter then the brackets can be omitted the parameters can have any names param - param 1 duck - contains concat duck db duck x y - x y transform list_transform list lambda returns a list that is the result of applying the lambda function to each element of the input list the lambda function must have exactly one left-hand side parameter the return type of the lambda function defines the type of the list elements -- incrementing each list element by one select list_transform 1 2 null 3 x - x 1 ---- 2 3 null 4 -- transforming strings select list_transform duck a b duck - concat duck db ---- duckdb adb bdb -- combining lambda functions with other functions select list_transform 5 null 6 x - coalesce x 0 1 ---- 6 1 7 filter list_filter list lambda constructs a list from those elements of the input list for which the lambda function returns true the lambda function must have exactly one left-hand side parameter and its return type must be of type boolean -- filter out negative values select list_filter 5 -6 null 7 x - x 0 ---- 5 7 -- divisible by 2 and 5 select list_filter list_filter 2 4 3 1 20 10 3 30 x - x 2 0 y - y 5 0 ---- 20 10 30 -- in combination with range to construct lists select list_filter 1 2 3 4 x - x 1 from range 4 ---- 1 2 3 4 2 3 4 3 4 4 lambda functions can be arbitrarily nested -- nested lambda functions to get all squares of even list elements select list_transform list_filter 0 1 2 3 4 5 x - x 2 0 y - y y ---- 0 4 16 flatten the flatten function is a scalar function that converts a list of lists into a single list by concatenating each sub-list together note that this only flattens one level at a time not all levels of sub-lists -- convert a list of lists into a single list select flatten 1 2 3 4 ---- 1 2 3 4 -- if the list has multiple levels of lists -- only the first level of sub-lists is concatenated into a single list select flatten 1 2 3 4 5 6 7 8 ---- 1 2 3 4 5 6 7 8 in general the input to the flatten function should be a list of lists not a single level list however the behavior of the flatten function has specific behavior when handling empty lists and null values -- if the input list is empty return an empty list select flatten ---- -- if the entire input to flatten is null return null select flatten null ---- null -- if a list whose only entry is null is flattened return an empty list select flatten null ---- -- if the sub-list in a list of lists only contains null -- do not modify the sub-list -- note the extra set of parentheses vs the prior example select flatten null ---- null -- even if the only contents of each sub-list is null -- still concatenate them together -- note that no de-duplication occurs when flattening -- see list_distinct function for de-duplication select flatten null null ---- null null generate_subscripts the generate_subscript arr dim function generates indexes along the dim th dimension of array arr select generate_subscripts 4 5 6 1 as i i 1 2 3 related functions there are also aggregate functions list and histogram that produces lists and lists of structs unnest is used to unnest a list by one level", "category": "Functions", "url": "/docs/sql/functions/nested", "blurb": "This section describes functions and operators for examining and manipulating nested values. There are three nested..." @@ -975,10 +989,10 @@ }, { "title": "ORDER BY Clause", - "text": "order by is an output modifier logically it is applied at the very end of the query the order by clause sorts the rows on the sorting criteria in either ascending or descending order in addition every order clause can specify whether null values should be moved to the beginning or to the end by default if no modifiers are provided duckdb sorts asc nulls first i e the values are sorted in ascending order and null values are placed first this is identical to the default sort order of sqlite postgresql by default sorts in asc nulls last order the default sort order can be changed using the following pragma statements -- change the default null sorting order to either nulls first and nulls last pragma default_null_order nulls last -- change the default sorting order to either desc or asc pragma default_order desc text is sorted using the binary comparison collation by default which means values are sorted on their binary utf8 values while this works well for ascii text e g for english language data the sorting order can be incorrect for other languages for this purpose duckdb provides collations for more information on collations see the collation page examples -- select the addresses ordered by city name using the default null order and default order select from addresses order by city -- select the addresses ordered by city name in descending order with nulls at the end select from addresses order by city desc nulls last -- order by city and then by zip code both using the default orderings select from addresses order by city zip -- order by city using german collation rules select from addresses order by city collate de syntax", + "text": "order by is an output modifier logically it is applied near the very end of the query just prior to limit or offset if present the order by clause sorts the rows on the sorting criteria in either ascending or descending order in addition every order clause can specify whether null values should be moved to the beginning or to the end the order by clause may contain one or more expressions separated by commas an error will be thrown if no expressions are included since the order by clause should be removed in that situation the expressions may begin with either an arbitrary scalar expression which could be a column name a column position number ex 1 note that it is 1-indexed or the keyword all each expression can optionally be followed by an order modifier asc or desc default is asc and or a null order modifier nulls first or nulls last default is nulls last order by all the all keyword indicates that the output should be sorted by every column in order from left to right the direction of this sort may be modified using either order by all asc or order by all desc and or nulls first or nulls last note that all may not be used in combination with other expressions in the order by clause - it must be by itself see examples below null order modifier by default if no modifiers are provided duckdb sorts asc nulls last i e the values are sorted in ascending order and null values are placed last this is identical to the default sort order of postgresql note that this was a breaking change in version 0 8 0 prior to 0 8 0 duckdb sorted using asc nulls first the default sort order can be changed using the following pragma statements -- change the default null sorting order to either nulls first and nulls last pragma default_null_order nulls first -- change the default sorting order to either desc or asc pragma default_order desc collations text is sorted using the binary comparison collation by default which means values are sorted on their binary utf8 values while this works well for ascii text e g for english language data the sorting order can be incorrect for other languages for this purpose duckdb provides collations for more information on collations see the collation page examples all examples use this example table create or replace table addresses as select 123 quack blvd as address ducktown as city 11111 as zip union all select 111 duck duck goose ln ducktown 11111 union all select 111 duck duck goose ln duck town 11111 union all select 111 duck duck goose ln duck town 11111-0001 -- select the addresses ordered by city name using the default null order and default order select from addresses order by city -- select the addresses ordered by city name in descending order with nulls at the end select from addresses order by city desc nulls last -- order by city and then by zip code both using the default orderings select from addresses order by city zip -- order by city using german collation rules select from addresses order by city collate de order by all examples -- order from left to right by address then by city then by zip in ascending order select from addresses order by all address city zip ------------------------ ----------- ------------ 111 duck duck goose ln duck town 11111 111 duck duck goose ln duck town 11111-0001 111 duck duck goose ln ducktown 11111 123 quack blvd ducktown 11111 -- order from left to right by address then by city then by zip in descending order select from addresses order by all desc address city zip ------------------------ ----------- ------------ 123 quack blvd ducktown 11111 111 duck duck goose ln ducktown 11111 111 duck duck goose ln duck town 11111-0001 111 duck duck goose ln duck town 11111 syntax", "category": "Query Syntax", "url": "/docs/sql/query_syntax/orderby", - "blurb": "ORDER BY is an output modifier. Logically it is applied at the very end of the query. The ORDER BY clause sorts the..." + "blurb": "ORDER BY is an output modifier. Logically it is applied near the very end of the query (just prior to LIMIT or OFFSET..." }, { "title": "Parquet Export", @@ -1269,7 +1283,7 @@ }, { "title": "Spatial", - "text": "the spatial extension provides support for geospatial data processing in duckdb geometry type the core of the spatial extension is the geometry type if you re unfamiliar with geospatial data and gis tooling this type is probably works very different from what you d expect in short while the geometry type is a binary representation of geometry data made up out of sets of vertices pairs of x and y double precision floats it actually stores one of several geometry subtypes these are point linestring polygon as well as their collection equivalents multipoint multilinestring and multipolygon lastly there is geometrycollection which can contain any of the other subtypes as well as other geometrycollection s recursively this may seem strange at first since duckdb already have types like list struct and union which could be used in a similar way but the design and behaviour of the geometry type is actually based on the simple features geometry model which is a standard used by many other databases and gis software that said the spatial extension also includes a couple of experimental non-standard explicit geometry types such as point_2d linestring_2d polygon_2d and box_2d that are based on duckdbs native nested types such as structs and lists in theory it should be possible to optimize a lot of operations for these types much better than for the geometry type which is just a binary blob but only a couple functions are implemented so far all of these are implicitly castable to geometry but with a conversion cost so the geometry type is still the recommended type to use for now if you are planning to work with a lot of different spatial functions geometry is not currently capable of storing additional geometry types z m coordinates or srid information these features may be added in the future spatial scalar functions the spatial extension implements a large number of scalar functions and overloads most of these are implemented using the geos library but we d like to implement more of them natively in this extension to better utilize duckdb s vectorized execution and memory management the following symbols are used to indicate which implementation is used - geos - functions that are implemented using the geos library - duckdb - functions that are implemented natively in this extension that are capable of operating directly on the duckdb types - cast geometry - functions that are supported by implicitly casting to geometry and then using the geometry implementation the currently implemented spatial functions can roughly be categorized into the following groups geometry conversion convert between geometries and other formats scalar functions geometry point_2d linestring_2d polygon_2d box_2d --------------------------------- -------- -------- ------------- ---------- -------------- varchar st_ashexwkb geometry varchar st_astext geometry as polygon wkb_blob st_aswkb geometry geometry st_geomfromtext varchar as polygon geometry st_geomfromwkb blob as polygon varchar st_asgeojson varchar as polygon geometry construction construct new geometries from other geometries or other data scalar functions geometry point_2d linestring_2d polygon_2d box_2d ------------------------------------------------------ -------- -------- ------------- ---------- -------------- geometry st_point double double geometry st_convexhull geometry as polygon geometry st_boundary geometry as polygon geometry st_buffer geometry as polygon geometry st_centroid geometry geometry st_collect geometry geometry st_normalize geometry as polygon geometry st_simplifypreservetopology geometry double as polygon geometry st_simplify geometry double as polygon geometry st_union geometry geometry as polygon geometry st_intersection geometry geometry as polygon geometry st_makeline geometry geometry st_envelope geometry as polygon geometry st_flipcoordinates geometry geometry st_transform geometry varchar varchar spatial properties calculate and access spatial properties of geometries scalar functions geometry point_2d linestring_2d polygon_2d box_2d -------------------------------------- -------- -------- ------------- ---------- -------------- double st_area geometry boolean st_isclosed geometry as polygon boolean st_isempty geometry as polygon boolean st_isring geometry as polygon boolean st_issimple geometry as polygon boolean st_isvalid geometry as polygon double st_x geometry as polygon double st_y geometry as polygon geometrytype st_geometrytype geometry as polygon double st_length geometry as polygon spatial relationships compute relationships and spatial predicates between geometries scalar functions geometry point_2d linestring_2d polygon_2d box_2d ---------------------------------------------- -------- -------- ------------- ---------- -------------- boolean st_within geometry geometry or as polygon boolean st_touches geometry geometry as polygon boolean st_overlaps geometry geometry as polygon boolean st_contains geometry geometry or as polygon boolean st_coveredby geometry geometry as polygon boolean st_covers geometry geometry as polygon boolean st_crosses geometry geometry as polygon boolean st_difference geometry geometry as polygon boolean st_disjoint geometry geometry as polygon boolean st_intersects geometry geometry as polygon boolean st_equals geometry geometry as polygon double st_distance geometry geometry or or as polygon boolean st_dwithin geometry geometry double as polygon spatial table functions the spatial extension provides a st_read table function based on the gdal translator library to read spatial data from a variety of geospatial vector file formats as if they were duckdb tables st_read can take a number of optional arguments the full signature is st_read varchar sequential_layer_scan boolean spatial_filter wkb_blob open_options varchar layer varchar allowed_drivers varchar sibling_files varchar spatial_filter_box box_2d sequential_layer_scan default false if set to true the table function will scan through all layers sequentially and return the first layer that matches the given layer name this is required for some drivers to work properly e g the osm driver spatial_filter default null if set to a wkb blob the table function will only return rows that intersect with the given wkb geometry some drivers may support efficient spatial filtering natively in which case it will be pushed down otherwise the filtering is done by gdal which may be much slower open_options default a list of key-value pairs that are passed to the gdal driver to control the opening of the file e g the geojson driver supports a flatten_nested_attributes yes option to flatten nested attributes layer default null the name of the layer to read from the file if null the first layer is returned can also be a layer index starting at 0 allowed_drivers default a list of gdal driver names that are allowed to be used to open the file if empty all drivers are allowed sibling_files default a list of sibling files that are required to open the file e g the esri shapefile driver requires a shx file to be present although most of the time these can be discovered automatically spatial_filter_box default null if set to a box_2d the table function will only return rows that intersect with the given bounding box similar to spatial_filter note that gdal is single-threaded so this table function will not be able to make full use of parllelism we re planning to implement support for the most common vector formats natively in this extension with additional table functions in the future we currently support over 50 different formats you can generate the following table of supported gdal drivers youself by executing select from st_drivers short_name long_name can_create can_copy can_open help_url -------------- --------------------------------------------------- ---------- -------- -------- -------------------------------------------------- esri shapefile esri shapefile true false true https gdal org drivers vector shapefile html mapinfo file mapinfo file true false true https gdal org drivers vector mitab html uk ntf uk ntf false false true https gdal org drivers vector ntf html lvbag kadaster lv bag extract 2 0 false false true https gdal org drivers vector lvbag html s57 iho s-57 enc true false true https gdal org drivers vector s57 html dgn microstation dgn true false true https gdal org drivers vector dgn html ogr_vrt vrt - virtual datasource false false true https gdal org drivers vector vrt html memory memory true false true csv comma separated value csv true false true https gdal org drivers vector csv html gml geography markup language gml true false true https gdal org drivers vector gml html gpx gpx true false true https gdal org drivers vector gpx html kml keyhole markup language kml true false true https gdal org drivers vector kml html geojson geojson true false true https gdal org drivers vector geojson html geojsonseq geojson sequence true false true https gdal org drivers vector geojsonseq html esrijson esrijson false false true https gdal org drivers vector esrijson html topojson topojson false false true https gdal org drivers vector topojson html ogr_gmt gmt ascii vectors gmt true false true https gdal org drivers vector gmt html gpkg geopackage true true true https gdal org drivers vector gpkg html sqlite sqlite spatialite true false true https gdal org drivers vector sqlite html wasp wasp map format true false true https gdal org drivers vector wasp html openfilegdb esri filegdb true false true https gdal org drivers vector openfilegdb html dxf autocad dxf true false true https gdal org drivers vector dxf html cad autocad driver false false true https gdal org drivers vector cad html flatgeobuf flatgeobuf true false true https gdal org drivers vector flatgeobuf html geoconcept geoconcept true false true georss georss true false true https gdal org drivers vector georss html vfk czech cadastral exchange data format false false true https gdal org drivers vector vfk html pgdump postgresql sql dump true false false https gdal org drivers vector pgdump html osm openstreetmap xml and pbf false false true https gdal org drivers vector osm html gpsbabel gpsbabel true false true https gdal org drivers vector gpsbabel html wfs ogc wfs web feature service false false true https gdal org drivers vector wfs html oapif ogc api - features false false true https gdal org drivers vector oapif html edigeo french edigeo exchange format false false true https gdal org drivers vector edigeo html svg scalable vector graphics false false true https gdal org drivers vector svg html ods open document libreoffice openoffice spreadsheet true false true https gdal org drivers vector ods html xlsx ms office open xml spreadsheet true false true https gdal org drivers vector xlsx html elasticsearch elastic search true false true https gdal org drivers vector elasticsearch html carto carto true false true https gdal org drivers vector carto html amigocloud amigocloud true false true https gdal org drivers vector amigocloud html sxf storage and exchange format false false true https gdal org drivers vector sxf html selafin selafin true false true https gdal org drivers vector selafin html jml openjump jml true false true https gdal org drivers vector jml html plscenes planet labs scenes api false false true https gdal org drivers vector plscenes html csw ogc csw catalog service for the web false false true https gdal org drivers vector csw html vdv vdv-451 vdv-452 intrest data format true false true https gdal org drivers vector vdv html mvt mapbox vector tiles true false true https gdal org drivers vector mvt html ngw nextgis web true true true https gdal org drivers vector ngw html mapml mapml true false true https gdal org drivers vector mapml html tiger u s census tiger line false false true https gdal org drivers vector tiger html avcbin arc info binary coverage false false true https gdal org drivers vector avcbin html avce00 arc info e00 ascii coverage false false true https gdal org drivers vector avce00 html note that far from all of these drivers have been tested properly and some may require additional options to be passed to work as expected if you run into any issues please first consult the gdal docs spatial copy functions much like the st_read table function the spatial extension provides a gdal based copy function to export duckdb tables to different geospatial vector formats for example to export a table to a geojson file with generated bounding boxes you can use the following query copy table to some file path filename geojson with format gdal driver geojson layer_creation_options write_bbox yes format is the only required option and must be set to gdal to use the gdal based copy function driver is the gdal driver to use for the export see the table above for a list of available drivers layer_creation_options list of options to pass to the gdal driver see the gdal docs for the driver you are using for a list of available options extra information see the repo for the source code of the extension or the blog post", + "text": "the spatial extension provides support for geospatial data processing in duckdb geometry type the core of the spatial extension is the geometry type if you re unfamiliar with geospatial data and gis tooling this type is probably works very different from what you d expect in short while the geometry type is a binary representation of geometry data made up out of sets of vertices pairs of x and y double precision floats it actually stores one of several geometry subtypes these are point linestring polygon as well as their collection equivalents multipoint multilinestring and multipolygon lastly there is geometrycollection which can contain any of the other subtypes as well as other geometrycollection s recursively this may seem strange at first since duckdb already have types like list struct and union which could be used in a similar way but the design and behaviour of the geometry type is actually based on the simple features geometry model which is a standard used by many other databases and gis software that said the spatial extension also includes a couple of experimental non-standard explicit geometry types such as point_2d linestring_2d polygon_2d and box_2d that are based on duckdbs native nested types such as structs and lists in theory it should be possible to optimize a lot of operations for these types much better than for the geometry type which is just a binary blob but only a couple functions are implemented so far all of these are implicitly castable to geometry but with a conversion cost so the geometry type is still the recommended type to use for now if you are planning to work with a lot of different spatial functions geometry is not currently capable of storing additional geometry types z m coordinates or srid information these features may be added in the future spatial scalar functions the spatial extension implements a large number of scalar functions and overloads most of these are implemented using the geos library but we d like to implement more of them natively in this extension to better utilize duckdb s vectorized execution and memory management the following symbols are used to indicate which implementation is used - geos - functions that are implemented using the geos library - duckdb - functions that are implemented natively in this extension that are capable of operating directly on the duckdb types - cast geometry - functions that are supported by implicitly casting to geometry and then using the geometry implementation the currently implemented spatial functions can roughly be categorized into the following groups geometry conversion convert between geometries and other formats scalar functions geometry point_2d linestring_2d polygon_2d box_2d --------------------------------- -------- -------- ------------- ---------- -------------- varchar st_ashexwkb geometry varchar st_astext geometry as polygon wkb_blob st_aswkb geometry geometry st_geomfromtext varchar as polygon geometry st_geomfromwkb blob as polygon varchar st_asgeojson varchar as polygon geometry construction construct new geometries from other geometries or other data scalar functions geometry point_2d linestring_2d polygon_2d box_2d ------------------------------------------------------ -------- -------- ------------- ---------- -------------- geometry st_point double double geometry st_convexhull geometry as polygon geometry st_boundary geometry as polygon geometry st_buffer geometry as polygon geometry st_centroid geometry geometry st_collect geometry geometry st_normalize geometry as polygon geometry st_simplifypreservetopology geometry double as polygon geometry st_simplify geometry double as polygon geometry st_union geometry geometry as polygon geometry st_intersection geometry geometry as polygon geometry st_makeline geometry geometry st_envelope geometry as polygon geometry st_flipcoordinates geometry geometry st_transform geometry varchar varchar spatial properties calculate and access spatial properties of geometries scalar functions geometry point_2d linestring_2d polygon_2d box_2d -------------------------------------- -------- -------- ------------- ---------- -------------- double st_area geometry boolean st_isclosed geometry as polygon boolean st_isempty geometry as polygon boolean st_isring geometry as polygon boolean st_issimple geometry as polygon boolean st_isvalid geometry as polygon double st_x geometry as polygon double st_y geometry as polygon geometrytype st_geometrytype geometry as polygon double st_length geometry as polygon spatial relationships compute relationships and spatial predicates between geometries scalar functions geometry point_2d linestring_2d polygon_2d box_2d ---------------------------------------------- -------- -------- ------------- ---------- -------------- boolean st_within geometry geometry or as polygon boolean st_touches geometry geometry as polygon boolean st_overlaps geometry geometry as polygon boolean st_contains geometry geometry or as polygon boolean st_coveredby geometry geometry as polygon boolean st_covers geometry geometry as polygon boolean st_crosses geometry geometry as polygon boolean st_difference geometry geometry as polygon boolean st_disjoint geometry geometry as polygon boolean st_intersects geometry geometry as polygon boolean st_equals geometry geometry as polygon double st_distance geometry geometry or or as polygon boolean st_dwithin geometry geometry double as polygon spatial table functions the spatial extension provides a st_read table function based on the gdal translator library to read spatial data from a variety of geospatial vector file formats as if they were duckdb tables for example to create a new table from a geojson file you can use the following query create table table as select from st_read some file path filename json st_read can take a number of optional arguments the full signature is st_read varchar sequential_layer_scan boolean spatial_filter wkb_blob open_options varchar layer varchar allowed_drivers varchar sibling_files varchar spatial_filter_box box_2d sequential_layer_scan default false if set to true the table function will scan through all layers sequentially and return the first layer that matches the given layer name this is required for some drivers to work properly e g the osm driver spatial_filter default null if set to a wkb blob the table function will only return rows that intersect with the given wkb geometry some drivers may support efficient spatial filtering natively in which case it will be pushed down otherwise the filtering is done by gdal which may be much slower open_options default a list of key-value pairs that are passed to the gdal driver to control the opening of the file e g the geojson driver supports a flatten_nested_attributes yes option to flatten nested attributes layer default null the name of the layer to read from the file if null the first layer is returned can also be a layer index starting at 0 allowed_drivers default a list of gdal driver names that are allowed to be used to open the file if empty all drivers are allowed sibling_files default a list of sibling files that are required to open the file e g the esri shapefile driver requires a shx file to be present although most of the time these can be discovered automatically spatial_filter_box default null if set to a box_2d the table function will only return rows that intersect with the given bounding box similar to spatial_filter note that gdal is single-threaded so this table function will not be able to make full use of parllelism we re planning to implement support for the most common vector formats natively in this extension with additional table functions in the future we currently support over 50 different formats you can generate the following table of supported gdal drivers youself by executing select from st_drivers short_name long_name can_create can_copy can_open help_url -------------- --------------------------------------------------- ---------- -------- -------- -------------------------------------------------- esri shapefile esri shapefile true false true https gdal org drivers vector shapefile html mapinfo file mapinfo file true false true https gdal org drivers vector mitab html uk ntf uk ntf false false true https gdal org drivers vector ntf html lvbag kadaster lv bag extract 2 0 false false true https gdal org drivers vector lvbag html s57 iho s-57 enc true false true https gdal org drivers vector s57 html dgn microstation dgn true false true https gdal org drivers vector dgn html ogr_vrt vrt - virtual datasource false false true https gdal org drivers vector vrt html memory memory true false true csv comma separated value csv true false true https gdal org drivers vector csv html gml geography markup language gml true false true https gdal org drivers vector gml html gpx gpx true false true https gdal org drivers vector gpx html kml keyhole markup language kml true false true https gdal org drivers vector kml html geojson geojson true false true https gdal org drivers vector geojson html geojsonseq geojson sequence true false true https gdal org drivers vector geojsonseq html esrijson esrijson false false true https gdal org drivers vector esrijson html topojson topojson false false true https gdal org drivers vector topojson html ogr_gmt gmt ascii vectors gmt true false true https gdal org drivers vector gmt html gpkg geopackage true true true https gdal org drivers vector gpkg html sqlite sqlite spatialite true false true https gdal org drivers vector sqlite html wasp wasp map format true false true https gdal org drivers vector wasp html openfilegdb esri filegdb true false true https gdal org drivers vector openfilegdb html dxf autocad dxf true false true https gdal org drivers vector dxf html cad autocad driver false false true https gdal org drivers vector cad html flatgeobuf flatgeobuf true false true https gdal org drivers vector flatgeobuf html geoconcept geoconcept true false true georss georss true false true https gdal org drivers vector georss html vfk czech cadastral exchange data format false false true https gdal org drivers vector vfk html pgdump postgresql sql dump true false false https gdal org drivers vector pgdump html osm openstreetmap xml and pbf false false true https gdal org drivers vector osm html gpsbabel gpsbabel true false true https gdal org drivers vector gpsbabel html wfs ogc wfs web feature service false false true https gdal org drivers vector wfs html oapif ogc api - features false false true https gdal org drivers vector oapif html edigeo french edigeo exchange format false false true https gdal org drivers vector edigeo html svg scalable vector graphics false false true https gdal org drivers vector svg html ods open document libreoffice openoffice spreadsheet true false true https gdal org drivers vector ods html xlsx ms office open xml spreadsheet true false true https gdal org drivers vector xlsx html elasticsearch elastic search true false true https gdal org drivers vector elasticsearch html carto carto true false true https gdal org drivers vector carto html amigocloud amigocloud true false true https gdal org drivers vector amigocloud html sxf storage and exchange format false false true https gdal org drivers vector sxf html selafin selafin true false true https gdal org drivers vector selafin html jml openjump jml true false true https gdal org drivers vector jml html plscenes planet labs scenes api false false true https gdal org drivers vector plscenes html csw ogc csw catalog service for the web false false true https gdal org drivers vector csw html vdv vdv-451 vdv-452 intrest data format true false true https gdal org drivers vector vdv html mvt mapbox vector tiles true false true https gdal org drivers vector mvt html ngw nextgis web true true true https gdal org drivers vector ngw html mapml mapml true false true https gdal org drivers vector mapml html tiger u s census tiger line false false true https gdal org drivers vector tiger html avcbin arc info binary coverage false false true https gdal org drivers vector avcbin html avce00 arc info e00 ascii coverage false false true https gdal org drivers vector avce00 html note that far from all of these drivers have been tested properly and some may require additional options to be passed to work as expected if you run into any issues please first consult the gdal docs spatial copy functions much like the st_read table function the spatial extension provides a gdal based copy function to export duckdb tables to different geospatial vector formats for example to export a table to a geojson file with generated bounding boxes you can use the following query copy table to some file path filename geojson with format gdal driver geojson layer_creation_options write_bbox yes format is the only required option and must be set to gdal to use the gdal based copy function driver is the gdal driver to use for the export see the table above for a list of available drivers layer_creation_options list of options to pass to the gdal driver see the gdal docs for the driver you are using for a list of available options extra information see the repo for the source code of the extension or the blog post", "category": "Extensions", "url": "/docs/extensions/spatial", "blurb": "The spatial extension provides support for geospatial data processing in DuckDB. GEOMETRY type The core of the..." @@ -1491,6 +1505,13 @@ "url": "/docs/sql/functions/numeric", "blurb": "` - `" }, + { + "title": "`\\", + "text": "`\\ - \\", + "category": "Nested Functions", + "url": "/docs/sql/functions/nested", + "blurb": "`\\ - \\" + }, { "title": "abs", "text": "abs(x) - absolute value", @@ -1946,6 +1967,13 @@ "url": "/docs/sql/functions/numeric", "blurb": "factorial(x) - See ! operator. Computes the product of the current integer and all integers below it" }, + { + "title": "flatten", + "text": "flatten(list_of_lists) - concatenate a list of lists into a single list. this only flattens one level of the list (see examples ).", + "category": "Nested Functions", + "url": "/docs/sql/functions/nested", + "blurb": "flatten(list_of_lists) - Concatenate a list of lists into a single list. This only flattens one level of the list..." + }, { "title": "floor", "text": "floor(x) - rounds the number down", @@ -2254,6 +2282,27 @@ "url": "/docs/sql/functions/nested", "blurb": "list_filter(list, lambda) - Constructs a list from those elements of the input list for which the lambda function..." }, + { + "title": "list_has_all", + "text": "list_has_all(list, sub-list) - returns true if all elements of sub-list exist in list.", + "category": "Nested Functions", + "url": "/docs/sql/functions/nested", + "blurb": "list_has_all(list, sub-list) - Returns true if all elements of sub-list exist in list." + }, + { + "title": "list_has_any", + "text": "list_has_any(list1, list2) - returns true if any elements exist is both lists.", + "category": "Nested Functions", + "url": "/docs/sql/functions/nested", + "blurb": "list_has_any(list1, list2) - Returns true if any elements exist is both lists." + }, + { + "title": "list_intersect", + "text": "list_intersect(list1, list2) - returns a list of all the elements that exist in both l1 and l2, without duplicates.", + "category": "Nested Functions", + "url": "/docs/sql/functions/nested", + "blurb": "list_intersect(list1, list2) - Returns a list of all the elements that exist in both l1 and l2, without duplicates." + }, { "title": "list_position", "text": "list_position(list, element) - returns the index of the element if the list contains the element.", @@ -2268,6 +2317,13 @@ "url": "/docs/sql/functions/nested", "blurb": "list_prepend(element, list) - Prepends element to list." }, + { + "title": "list_resize", + "text": "list_resize(list, size [, value ]) - resizes the list to contain size elements. initializes new elements with value or null if value is not set.", + "category": "Nested Functions", + "url": "/docs/sql/functions/nested", + "blurb": "list_resize(list, size [, value ]) - Resizes the list to contain size elements. Initializes new elements with value..." + }, { "title": "list_reverse_sort", "text": "list_reverse_sort(list) - sorts the elements of the list in reverse order. see the sorting lists section for more details about the null sorting order.", diff --git a/docs/api/c/api.md b/docs/api/c/api.md index 2ec502d28d9..ece151e58ba 100644 --- a/docs/api/c/api.md +++ b/docs/api/c/api.md @@ -112,6 +112,8 @@ selected: API Reference duckdb_state duckdb_bind_null(duckdb_prepared_statement prepared_statement, idx_t param_idx); duckdb_state duckdb_execute_prepared(duckdb_prepared_statement prepared_statement, duckdb_result *out_result); duckdb_state duckdb_execute_prepared_arrow(duckdb_prepared_statement prepared_statement, duckdb_arrow *out_result); +duckdb_state duckdb_arrow_scan(duckdb_connection connection, const char *table_name, duckdb_arrow_stream arrow); +duckdb_state duckdb_arrow_array_scan(duckdb_connection connection, const char *table_name, duckdb_arrow_schema arrow_schema, duckdb_arrow_array arrow_array, duckdb_arrow_stream *out_stream); ### **Extract Statements** 
idx_t duckdb_extract_statements(duckdb_connection connection, const char *query, duckdb_extracted_statements *out_extracted_statements);
@@ -2118,6 +2120,72 @@ The query result.
 
 

 
+### duckdb_arrow_scan
+---
+Scans the Arrow stream and creates a view with the given name.
+
+#### Syntax
+---
+
duckdb_state duckdb_arrow_scan(
+  duckdb_connection connection,
+  const char *table_name,
+  duckdb_arrow_stream arrow
+);
+

+#### Parameters
+---
+* `connection`
+
+The connection on which to execute the scan.
+* `table_name`
+
+Name of the temporary view to create.
+* `arrow`
+
+Arrow stream wrapper.
+* `returns`
+
+`DuckDBSuccess` on success or `DuckDBError` on failure.
+
+

+
+### duckdb_arrow_array_scan
+---
+Scans the Arrow array and creates a view with the given name.
+
+#### Syntax
+---
+
duckdb_state duckdb_arrow_array_scan(
+  duckdb_connection connection,
+  const char *table_name,
+  duckdb_arrow_schema arrow_schema,
+  duckdb_arrow_array arrow_array,
+  duckdb_arrow_stream *out_stream
+);
+

+#### Parameters
+---
+* `connection`
+
+The connection on which to execute the scan.
+* `table_name`
+
+Name of the temporary view to create.
+* `arrow_schema`
+
+Arrow schema wrapper.
+* `arrow_array`
+
+Arrow array wrapper.
+* `out_stream`
+
+Output array stream that wraps around the passed schema, for releasing/deleting once done.
+* `returns`
+
+`DuckDBSuccess` on success or `DuckDBError` on failure.
+
+

+
 ### duckdb_extract_statements
 ---
 Extract all statements from a query.
diff --git a/docs/api/c/prepared.md b/docs/api/c/prepared.md
index 6096394fc0d..f1c64f109fc 100644
--- a/docs/api/c/prepared.md
+++ b/docs/api/c/prepared.md
@@ -76,6 +76,8 @@ It is not required that the `duckdb_bind` family of functions matches the prepar
 duckdb_state duckdb_bind_null(duckdb_prepared_statement prepared_statement, idx_t param_idx);
 duckdb_state duckdb_execute_prepared(duckdb_prepared_statement prepared_statement, duckdb_result *out_result);
 duckdb_state duckdb_execute_prepared_arrow(duckdb_prepared_statement prepared_statement, duckdb_arrow *out_result);
+duckdb_state duckdb_arrow_scan(duckdb_connection connection, const char *table_name, duckdb_arrow_stream arrow);
+duckdb_state duckdb_arrow_array_scan(duckdb_connection connection, const char *table_name, duckdb_arrow_schema arrow_schema, duckdb_arrow_array arrow_array, duckdb_arrow_stream *out_stream);
### duckdb_prepare --- @@ -560,3 +562,69 @@ The query result.
+### duckdb_arrow_scan +--- +Scans the Arrow stream and creates a view with the given name. + +#### Syntax +--- +
duckdb_state duckdb_arrow_scan(
+  duckdb_connection connection,
+  const char *table_name,
+  duckdb_arrow_stream arrow
+);
+
+#### Parameters +--- +* `connection` + +The connection on which to execute the scan. +* `table_name` + +Name of the temporary view to create. +* `arrow` + +Arrow stream wrapper. +* `returns` + +`DuckDBSuccess` on success or `DuckDBError` on failure. + +
+ +### duckdb_arrow_array_scan +--- +Scans the Arrow array and creates a view with the given name. + +#### Syntax +--- +
duckdb_state duckdb_arrow_array_scan(
+  duckdb_connection connection,
+  const char *table_name,
+  duckdb_arrow_schema arrow_schema,
+  duckdb_arrow_array arrow_array,
+  duckdb_arrow_stream *out_stream
+);
+
+#### Parameters +--- +* `connection` + +The connection on which to execute the scan. +* `table_name` + +Name of the temporary view to create. +* `arrow_schema` + +Arrow schema wrapper. +* `arrow_array` + +Arrow array wrapper. +* `out_stream` + +Output array stream that wraps around the passed schema, for releasing/deleting once done. +* `returns` + +`DuckDBSuccess` on success or `DuckDBError` on failure. + +
+ diff --git a/docs/api/python/reference/index.md b/docs/api/python/reference/index.md index da8560c4392..e4f6497f1f3 100644 --- a/docs/api/python/reference/index.md +++ b/docs/api/python/reference/index.md @@ -394,7 +394,7 @@ title: Python Client API
-from_query(self: duckdb.DuckDBPyConnection, query: str, alias: str = 'query_relation') → duckdb.DuckDBPyRelation +from_query(self: duckdb.DuckDBPyConnection, query: str, alias: str = '') → duckdb.DuckDBPyRelation

Run a SQL query. If it is a SELECT statement, create a relation object from the given SQL query, otherwise run the query as-is.

@@ -455,6 +455,15 @@ title: Python Client API
+
+
+interrupt(self: duckdb.DuckDBPyConnection) → None +
+
+

Interrupt pending operations

+
+
+
list_filesystems(self: duckdb.DuckDBPyConnection) → list @@ -502,7 +511,7 @@ title: Python Client API
-query(self: duckdb.DuckDBPyConnection, query: str, alias: str = 'query_relation') → duckdb.DuckDBPyRelation +query(self: duckdb.DuckDBPyConnection, query: str, alias: str = '') → duckdb.DuckDBPyRelation

Run a SQL query. If it is a SELECT statement, create a relation object from the given SQL query, otherwise run the query as-is.

@@ -591,7 +600,7 @@ title: Python Client API
-sql(self: duckdb.DuckDBPyConnection, query: str, alias: str = 'query_relation') → duckdb.DuckDBPyRelation +sql(self: duckdb.DuckDBPyConnection, query: str, alias: str = '') → duckdb.DuckDBPyRelation

Run a SQL query. If it is a SELECT statement, create a relation object from the given SQL query, otherwise run the query as-is.

@@ -2098,7 +2107,7 @@ title: Python Client API

Overloaded function.

    -

  1. from_query(query: str, alias: str = ‘query_relation’, connection: duckdb.DuckDBPyConnection = None) -> duckdb.DuckDBPyRelation

    2. +

  2. from_query(query: str, alias: str = ‘’, connection: duckdb.DuckDBPyConnection = None) -> duckdb.DuckDBPyRelation

Create a relation object from the given SQL query

    @@ -2186,6 +2195,15 @@ title: Python Client API
+
+
+duckdb.interrupt(connection: duckdb.DuckDBPyConnection = None) → None +
+
+

Interrupt pending operations

+
+
+
duckdb.limit(df: pandas.DataFrame, n: int, connection: duckdb.DuckDBPyConnection = None) → duckdb.DuckDBPyRelation @@ -2260,17 +2278,9 @@ title: Python Client API
-duckdb.query(*args, **kwargs) +duckdb.query(query: str, alias: str = '', connection: duckdb.DuckDBPyConnection = None) → duckdb.DuckDBPyRelation
-

Overloaded function.

-
    -

  1. query(query: str, alias: str = ‘query_relation’, connection: duckdb.DuckDBPyConnection = None) -> duckdb.DuckDBPyRelation

    2. -
-

Run a SQL query. If it is a SELECT statement, create a relation object from the given SQL query, otherwise run the query as-is.

-
    -

  1. query(query: str, alias: str = ‘query_relation’, connection: duckdb.DuckDBPyConnection = None) -> duckdb.DuckDBPyRelation

    2. -

Run a SQL query. If it is a SELECT statement, create a relation object from the given SQL query, otherwise run the query as-is.

@@ -2366,7 +2376,7 @@ title: Python Client API
-duckdb.sql(query: str, alias: str = 'query_relation', connection: duckdb.DuckDBPyConnection = None) → duckdb.DuckDBPyRelation +duckdb.sql(query: str, alias: str = '', connection: duckdb.DuckDBPyConnection = None) → duckdb.DuckDBPyRelation

Run a SQL query. If it is a SELECT statement, create a relation object from the given SQL query, otherwise run the query as-is.

diff --git a/docs/sql/configuration.md b/docs/sql/configuration.md index d493f1c7553..42b6a8c654c 100644 --- a/docs/sql/configuration.md +++ b/docs/sql/configuration.md @@ -38,6 +38,7 @@ Below is a list of all available settings. | Calendar | The current calendar | VARCHAR | System (locale) calendar | | TimeZone | The current time zone | VARCHAR | System (locale) timezone | | access_mode | Access mode of the database (**AUTOMATIC**, **READ_ONLY** or **READ_WRITE**) | VARCHAR | AUTOMATIC | +| allocator_flush_threshold | Peak allocation threshold at which to flush the allocator after completing a task. | VARCHAR | 134.2MB | | allow_unsigned_extensions | Allow to load extensions with invalid or missing signatures | BOOLEAN | FALSE | | arrow_large_buffer_size | If arrow buffers for strings, blobs, uuids and bits should be exported using large buffers | BOOLEAN | FALSE | | binary_as_string | In Parquet files, interpret binary data as a string. | BOOLEAN | | @@ -46,6 +47,7 @@ Below is a list of all available settings. | default_collation | The collation setting used when none is specified | VARCHAR | | | default_null_order, null_order | Null ordering used when none is specified (**NULLS_FIRST** or **NULLS_LAST**) | VARCHAR | NULLS_LAST | | default_order | The order type used when none is specified (**ASC** or **DESC**) | VARCHAR | ASC | +| disabled_filesystems | Disable specific file systems preventing access (e.g. LocalFileSystem) | VARCHAR | | | enable_external_access | Allow the database to access external state (through e.g. loading/installing modules, COPY TO/FROM, CSV readers, pandas replacement scans, etc) | BOOLEAN | TRUE | | enable_fsst_vectors | Allow scans on FSST compressed segments to emit compressed vectors to utilize late decompression | BOOLEAN | FALSE | | enable_http_metadata_cache | Whether or not the global http metadata is used to cache HTTP metadata | BOOLEAN | FALSE | @@ -73,7 +75,9 @@ Below is a list of all available settings. | ordered_aggregate_threshold | the number of rows to accumulate before sorting, used for tuning | UBIGINT | 262144 | | password | The password to use. Ignored for legacy compatibility. | VARCHAR | NULL | | perfect_ht_threshold | Threshold in bytes for when to use a perfect hash table (default: 12) | BIGINT | 12 | -| pivot_limit | The maximum numer of pivot columns in a pivot statement (default: 100000) | BIGINT | 100000 | +| pivot_filter_threshold | The threshold to switch from using filtered aggregates to LIST with a dedicated pivot operator | BIGINT | 10 | +| pivot_limit | The maximum number of pivot columns in a pivot statement (default: 100000) | BIGINT | 100000 | +| prefer_range_joins | Force use of range joins with mixed predicates | BOOLEAN | FALSE | | preserve_identifier_case | Whether or not to preserve the identifier case, instead of always lowercasing all non-quoted identifiers | BOOLEAN | TRUE | | preserve_insertion_order | Whether or not to preserve insertion order. If set to false the system is allowed to re-order any results that do not contain ORDER BY clauses. | BOOLEAN | TRUE | | profile_output, profiling_output | The file to which profile output should be saved, or empty to print to the terminal | VARCHAR | | From dc9760c3c7ccac34dc5f5a96436d05461fcb99d1 Mon Sep 17 00:00:00 2001 From: GitHub Actions Date: Mon, 31 Jul 2023 05:05:17 +0000 Subject: [PATCH 02/12] chore: auto update docs --- data/search_data.json | 8 +- docs/api/c/api.md | 41 +++ docs/api/c/connect.md | 41 +++ docs/api/python/reference/index.md | 503 ++++++++++++++--------------- 4 files changed, 337 insertions(+), 256 deletions(-) diff --git a/data/search_data.json b/data/search_data.json index 127bbb6f124..1baf1cbbbd7 100644 --- a/data/search_data.json +++ b/data/search_data.json @@ -163,7 +163,7 @@ }, { "title": "C API - Complete API", - "text": "api reference open connect syntax path to the database file on disk or nullptr or memory to open an in-memory database out_database the result database object returns duckdbsuccess on success or duckdberror on failure duckdb_open_ext extended version of duckdb_open creates a new database or opens an existing database file stored at the the given path syntax path to the database file on disk or nullptr or memory to open an in-memory database out_database the result database object config optional configuration used to start up the database system out_error if set and the function returns duckdberror this will contain the reason why the start-up failed note that the error must be freed using duckdb_free returns duckdbsuccess on success or duckdberror on failure duckdb_close closes the specified database and de-allocates all memory allocated for that database this should be called after you are done with any database allocated through duckdb_open note that failing to call duckdb_close in case of e g a program crash will not cause data corruption still it is recommended to always correctly close a database object after you are done with it syntax the database object to shut down duckdb_connect opens a connection to a database connections are required to query the database and store transactional state associated with the connection the instantiated connection should be closed using duckdb_disconnect syntax the database file to connect to out_connection the result connection object returns duckdbsuccess on success or duckdberror on failure duckdb_disconnect closes the specified connection and de-allocates all memory allocated for that connection syntax the connection to close duckdb_library_version returns the version of the linked duckdb with a version postfix for dev versions usually used for developing c extensions that must return this for a compatibility check syntax duckdb_create_config initializes an empty configuration object that can be used to provide start-up options for the duckdb instance through duckdb_open_ext this will always succeed unless there is a malloc failure syntax the result configuration object returns duckdbsuccess on success or duckdberror on failure duckdb_config_count this returns the total amount of configuration options available for usage with duckdb_get_config_flag this should not be called in a loop as it internally loops over all the options syntax the amount of config options available duckdb_get_config_flag obtains a human-readable name and description of a specific configuration option this can be used to e g display configuration options this will succeed unless index is out of range i e duckdb_config_count the result name or description must not be freed syntax the index of the configuration option between 0 and duckdb_config_count out_name a name of the configuration flag out_description a description of the configuration flag returns duckdbsuccess on success or duckdberror on failure duckdb_set_config sets the specified option for the specified configuration the configuration option is indicated by name to obtain a list of config options see duckdb_get_config_flag in the source code configuration options are defined in config cpp this can fail if either the name is invalid or if the value provided for the option is invalid syntax the configuration object to set the option on name the name of the configuration flag to set option the value to set the configuration flag to returns duckdbsuccess on success or duckdberror on failure duckdb_destroy_config destroys the specified configuration option and de-allocates all memory allocated for the object syntax the configuration object to destroy duckdb_query executes a sql query within a connection and stores the full materialized result in the out_result pointer if the query fails to execute duckdberror is returned and the error message can be retrieved by calling duckdb_result_error note that after running duckdb_query duckdb_destroy_result must be called on the result object even if the query fails otherwise the error stored within the result will not be freed correctly syntax the connection to perform the query in query the sql query to run out_result the query result returns duckdbsuccess on success or duckdberror on failure duckdb_destroy_result closes the result and de-allocates all memory allocated for that connection syntax the result to destroy duckdb_column_name returns the column name of the specified column the result should not need be freed the column names will automatically be destroyed when the result is destroyed returns null if the column is out of range syntax the result object to fetch the column name from col the column index returns the column name of the specified column duckdb_column_type returns the column type of the specified column returns duckdb_type_invalid if the column is out of range syntax the result object to fetch the column type from col the column index returns the column type of the specified column duckdb_column_logical_type returns the logical column type of the specified column the return type of this call should be destroyed with duckdb_destroy_logical_type returns null if the column is out of range syntax the result object to fetch the column type from col the column index returns the logical column type of the specified column duckdb_column_count returns the number of columns present in a the result object syntax the result object returns the number of columns present in the result object duckdb_row_count returns the number of rows present in a the result object syntax the result object returns the number of rows present in the result object duckdb_rows_changed returns the number of rows changed by the query stored in the result this is relevant only for insert update delete queries for other queries the rows_changed will be 0 syntax the result object returns the number of rows changed duckdb_column_data deprecated prefer using duckdb_result_get_chunk instead returns the data of a specific column of a result in columnar format the function returns a dense array which contains the result data the exact type stored in the array depends on the corresponding duckdb_type as provided by duckdb_column_type for the exact type by which the data should be accessed see the comments in the types section or the duckdb_type enum for example for a column of type duckdb_type_integer rows can be accessed in the following manner int32_t data int32_t duckdb_column_data result 0 printf data for row d d n row data row syntax the result object to fetch the column data from col the column index returns the column data of the specified column duckdb_nullmask_data deprecated prefer using duckdb_result_get_chunk instead returns the nullmask of a specific column of a result in columnar format the nullmask indicates for every row whether or not the corresponding row is null if a row is null the values present in the array provided by duckdb_column_data are undefined int32_t data int32_t duckdb_column_data result 0 bool nullmask duckdb_nullmask_data result 0 if nullmask row printf data for row d null n row else printf data for row d d n row data row syntax the result object to fetch the nullmask from col the column index returns the nullmask of the specified column duckdb_result_error returns the error message contained within the result the error is only set if duckdb_query returns duckdberror the result of this function must not be freed it will be cleaned up when duckdb_destroy_result is called syntax the result object to fetch the error from returns the error of the result duckdb_result_get_chunk fetches a data chunk from the duckdb_result this function should be called repeatedly until the result is exhausted the result must be destroyed with duckdb_destroy_data_chunk this function supersedes all duckdb_value functions as well as the duckdb_column_data and duckdb_nullmask_data functions it results in significantly better performance and should be preferred in newer code-bases if this function is used none of the other result functions can be used and vice versa i e this function cannot be mixed with the legacy result functions use duckdb_result_chunk_count to figure out how many chunks there are in the result syntax the result object to fetch the data chunk from chunk_index the chunk index to fetch from returns the resulting data chunk returns null if the chunk index is out of bounds duckdb_result_is_streaming checks if the type of the internal result is streamqueryresult syntax the result object to check returns whether or not the result object is of the type streamqueryresult duckdb_result_chunk_count returns the number of data chunks present in the result syntax the result object returns number of data chunks present in the result duckdb_value_boolean syntax the boolean value at the specified location or false if the value cannot be converted duckdb_value_int8 syntax the int8_t value at the specified location or 0 if the value cannot be converted duckdb_value_int16 syntax the int16_t value at the specified location or 0 if the value cannot be converted duckdb_value_int32 syntax the int32_t value at the specified location or 0 if the value cannot be converted duckdb_value_int64 syntax the int64_t value at the specified location or 0 if the value cannot be converted duckdb_value_hugeint syntax the duckdb_hugeint value at the specified location or 0 if the value cannot be converted duckdb_value_decimal syntax the duckdb_decimal value at the specified location or 0 if the value cannot be converted duckdb_value_uint8 syntax the uint8_t value at the specified location or 0 if the value cannot be converted duckdb_value_uint16 syntax the uint16_t value at the specified location or 0 if the value cannot be converted duckdb_value_uint32 syntax the uint32_t value at the specified location or 0 if the value cannot be converted duckdb_value_uint64 syntax the uint64_t value at the specified location or 0 if the value cannot be converted duckdb_value_float syntax the float value at the specified location or 0 if the value cannot be converted duckdb_value_double syntax the double value at the specified location or 0 if the value cannot be converted duckdb_value_date syntax the duckdb_date value at the specified location or 0 if the value cannot be converted duckdb_value_time syntax the duckdb_time value at the specified location or 0 if the value cannot be converted duckdb_value_timestamp syntax the duckdb_timestamp value at the specified location or 0 if the value cannot be converted duckdb_value_interval syntax the duckdb_interval value at the specified location or 0 if the value cannot be converted duckdb_value_varchar syntax use duckdb_value_string instead this function does not work correctly if the string contains null bytes returns the text value at the specified location as a null-terminated string or nullptr if the value cannot be converted the result must be freed with duckdb_free duckdb_value_varchar_internal syntax use duckdb_value_string_internal instead this function does not work correctly if the string contains null bytes returns the char value at the specified location only works on varchar columns and does not auto-cast if the column is not a varchar column this function will return null the result must not be freed duckdb_value_string_internal syntax use duckdb_value_string_internal instead this function does not work correctly if the string contains null bytes returns the char value at the specified location only works on varchar columns and does not auto-cast if the column is not a varchar column this function will return null the result must not be freed duckdb_value_blob syntax the duckdb_blob value at the specified location returns a blob with blob data set to nullptr if the value cannot be converted the resulting blob data must be freed with duckdb_free duckdb_value_is_null syntax returns true if the value at the specified index is null and false otherwise duckdb_malloc allocate size bytes of memory using the duckdb internal malloc function any memory allocated in this manner should be freed using duckdb_free syntax the number of bytes to allocate returns a pointer to the allocated memory region duckdb_free free a value returned from duckdb_malloc duckdb_value_varchar or duckdb_value_blob syntax the memory region to de-allocate duckdb_vector_size the internal vector size used by duckdb this is the amount of tuples that will fit into a data chunk created by duckdb_create_data_chunk syntax the vector size duckdb_string_is_inlined whether or not the duckdb_string_t value is inlined this means that the data of the string does not have a separate allocation syntax duckdb_from_date decompose a duckdb_date object into year month and date stored as duckdb_date_struct syntax the date object as obtained from a duckdb_type_date column returns the duckdb_date_struct with the decomposed elements duckdb_to_date re-compose a duckdb_date from year month and date duckdb_date_struct syntax the year month and date stored in a duckdb_date_struct returns the duckdb_date element duckdb_from_time decompose a duckdb_time object into hour minute second and microsecond stored as duckdb_time_struct syntax the time object as obtained from a duckdb_type_time column returns the duckdb_time_struct with the decomposed elements duckdb_to_time re-compose a duckdb_time from hour minute second and microsecond duckdb_time_struct syntax the hour minute second and microsecond in a duckdb_time_struct returns the duckdb_time element duckdb_from_timestamp decompose a duckdb_timestamp object into a duckdb_timestamp_struct syntax the ts object as obtained from a duckdb_type_timestamp column returns the duckdb_timestamp_struct with the decomposed elements duckdb_to_timestamp re-compose a duckdb_timestamp from a duckdb_timestamp_struct syntax the de-composed elements in a duckdb_timestamp_struct returns the duckdb_timestamp element duckdb_hugeint_to_double converts a duckdb_hugeint object as obtained from a duckdb_type_hugeint column into a double syntax the hugeint value returns the converted double element duckdb_double_to_hugeint converts a double value to a duckdb_hugeint object if the conversion fails because the double value is too big the result will be 0 syntax the double value returns the converted duckdb_hugeint element duckdb_double_to_decimal converts a double value to a duckdb_decimal object if the conversion fails because the double value is too big or the width scale are invalid the result will be 0 syntax the double value returns the converted duckdb_decimal element duckdb_decimal_to_double converts a duckdb_decimal object as obtained from a duckdb_type_decimal column into a double syntax the decimal value returns the converted double element duckdb_prepare create a prepared statement object from a query note that after calling duckdb_prepare the prepared statement should always be destroyed using duckdb_destroy_prepare even if the prepare fails if the prepare fails duckdb_prepare_error can be called to obtain the reason why the prepare failed syntax the connection object query the sql query to prepare out_prepared_statement the resulting prepared statement object returns duckdbsuccess on success or duckdberror on failure duckdb_destroy_prepare closes the prepared statement and de-allocates all memory allocated for the statement syntax the prepared statement to destroy duckdb_prepare_error returns the error message associated with the given prepared statement if the prepared statement has no error message this returns nullptr instead the error message should not be freed it will be de-allocated when duckdb_destroy_prepare is called syntax the prepared statement to obtain the error from returns the error message or nullptr if there is none duckdb_nparams returns the number of parameters that can be provided to the given prepared statement returns 0 if the query was not successfully prepared syntax the prepared statement to obtain the number of parameters for duckdb_param_type returns the parameter type for the parameter at the given index returns duckdb_type_invalid if the parameter index is out of range or the statement was not successfully prepared syntax the prepared statement param_idx the parameter index returns the parameter type duckdb_clear_bindings clear the params bind to the prepared statement syntax duckdb_bind_boolean binds a bool value to the prepared statement at the specified index syntax duckdb_bind_int8 binds an int8_t value to the prepared statement at the specified index syntax duckdb_bind_int16 binds an int16_t value to the prepared statement at the specified index syntax duckdb_bind_int32 binds an int32_t value to the prepared statement at the specified index syntax duckdb_bind_int64 binds an int64_t value to the prepared statement at the specified index syntax duckdb_bind_hugeint binds an duckdb_hugeint value to the prepared statement at the specified index syntax duckdb_bind_decimal binds a duckdb_decimal value to the prepared statement at the specified index syntax duckdb_bind_uint8 binds an uint8_t value to the prepared statement at the specified index syntax duckdb_bind_uint16 binds an uint16_t value to the prepared statement at the specified index syntax duckdb_bind_uint32 binds an uint32_t value to the prepared statement at the specified index syntax duckdb_bind_uint64 binds an uint64_t value to the prepared statement at the specified index syntax duckdb_bind_float binds an float value to the prepared statement at the specified index syntax duckdb_bind_double binds an double value to the prepared statement at the specified index syntax duckdb_bind_date binds a duckdb_date value to the prepared statement at the specified index syntax duckdb_bind_time binds a duckdb_time value to the prepared statement at the specified index syntax duckdb_bind_timestamp binds a duckdb_timestamp value to the prepared statement at the specified index syntax duckdb_bind_interval binds a duckdb_interval value to the prepared statement at the specified index syntax duckdb_bind_varchar binds a null-terminated varchar value to the prepared statement at the specified index syntax duckdb_bind_varchar_length binds a varchar value to the prepared statement at the specified index syntax duckdb_bind_blob binds a blob value to the prepared statement at the specified index syntax duckdb_bind_null binds a null value to the prepared statement at the specified index syntax duckdb_execute_prepared executes the prepared statement with the given bound parameters and returns a materialized query result this method can be called multiple times for each prepared statement and the parameters can be modified between calls to this function syntax the prepared statement to execute out_result the query result returns duckdbsuccess on success or duckdberror on failure duckdb_execute_prepared_arrow executes the prepared statement with the given bound parameters and returns an arrow query result syntax the prepared statement to execute out_result the query result returns duckdbsuccess on success or duckdberror on failure duckdb_arrow_scan scans the arrow stream and creates a view with the given name syntax the connection on which to execute the scan table_name name of the temporary view to create arrow arrow stream wrapper returns duckdbsuccess on success or duckdberror on failure duckdb_arrow_array_scan scans the arrow array and creates a view with the given name syntax the connection on which to execute the scan table_name name of the temporary view to create arrow_schema arrow schema wrapper arrow_array arrow array wrapper out_stream output array stream that wraps around the passed schema for releasing deleting once done returns duckdbsuccess on success or duckdberror on failure duckdb_extract_statements extract all statements from a query note that after calling duckdb_extract_statements the extracted statements should always be destroyed using duckdb_destroy_extracted even if no statements were extracted if the extract fails duckdb_extract_statements_error can be called to obtain the reason why the extract failed syntax the connection object query the sql query to extract out_extracted_statements the resulting extracted statements object returns the number of extracted statements or 0 on failure duckdb_prepare_extracted_statement prepare an extracted statement note that after calling duckdb_prepare_extracted_statement the prepared statement should always be destroyed using duckdb_destroy_prepare even if the prepare fails if the prepare fails duckdb_prepare_error can be called to obtain the reason why the prepare failed syntax the connection object extracted_statements the extracted statements object index the index of the extracted statement to prepare out_prepared_statement the resulting prepared statement object returns duckdbsuccess on success or duckdberror on failure duckdb_extract_statements_error returns the error message contained within the extracted statements the result of this function must not be freed it will be cleaned up when duckdb_destroy_extracted is called syntax the extracted statements to fetch the error from returns the error of the extracted statements duckdb_destroy_extracted de-allocates all memory allocated for the extracted statements syntax the extracted statements to destroy duckdb_pending_prepared executes the prepared statement with the given bound parameters and returns a pending result the pending result represents an intermediate structure for a query that is not yet fully executed the pending result can be used to incrementally execute a query returning control to the client between tasks note that after calling duckdb_pending_prepared the pending result should always be destroyed using duckdb_destroy_pending even if this function returns duckdberror syntax the prepared statement to execute out_result the pending query result returns duckdbsuccess on success or duckdberror on failure duckdb_pending_prepared_streaming executes the prepared statement with the given bound parameters and returns a pending result this pending result will create a streaming duckdb_result when executed the pending result represents an intermediate structure for a query that is not yet fully executed note that after calling duckdb_pending_prepared_streaming the pending result should always be destroyed using duckdb_destroy_pending even if this function returns duckdberror syntax the prepared statement to execute out_result the pending query result returns duckdbsuccess on success or duckdberror on failure duckdb_destroy_pending closes the pending result and de-allocates all memory allocated for the result syntax the pending result to destroy duckdb_pending_error returns the error message contained within the pending result the result of this function must not be freed it will be cleaned up when duckdb_destroy_pending is called syntax the pending result to fetch the error from returns the error of the pending result duckdb_pending_execute_task executes a single task within the query returning whether or not the query is ready if this returns duckdb_pending_result_ready the duckdb_execute_pending function can be called to obtain the result if this returns duckdb_pending_result_not_ready the duckdb_pending_execute_task function should be called again if this returns duckdb_pending_error an error occurred during execution the error message can be obtained by calling duckdb_pending_error on the pending_result syntax the pending result to execute a task within returns the state of the pending result after the execution duckdb_execute_pending fully execute a pending query result returning the final query result if duckdb_pending_execute_task has been called until duckdb_pending_result_ready was returned this will return fast otherwise all remaining tasks must be executed first syntax the pending result to execute out_result the result object returns duckdbsuccess on success or duckdberror on failure duckdb_destroy_value destroys the value and de-allocates all memory allocated for that type syntax the value to destroy duckdb_create_varchar creates a value from a null-terminated string syntax the null-terminated string returns the value this must be destroyed with duckdb_destroy_value duckdb_create_varchar_length creates a value from a string syntax the text length the length of the text returns the value this must be destroyed with duckdb_destroy_value duckdb_create_int64 creates a value from an int64 syntax the bigint value returns the value this must be destroyed with duckdb_destroy_value duckdb_get_varchar obtains a string representation of the given value the result must be destroyed with duckdb_free syntax the value returns the string value this must be destroyed with duckdb_free duckdb_get_int64 obtains an int64 of the given value syntax the value returns the int64 value or 0 if no conversion is possible duckdb_create_logical_type creates a duckdb_logical_type from a standard primitive type the resulting type should be destroyed with duckdb_destroy_logical_type this should not be used with duckdb_type_decimal syntax the primitive type to create returns the logical type duckdb_create_list_type creates a list type from its child type the resulting type should be destroyed with duckdb_destroy_logical_type syntax the child type of list type to create returns the logical type duckdb_create_map_type creates a map type from its key type and value type the resulting type should be destroyed with duckdb_destroy_logical_type syntax the key type and value type of map type to create returns the logical type duckdb_create_union_type creates a union type from the passed types array the resulting type should be destroyed with duckdb_destroy_logical_type syntax the array of types that the union should consist of type_amount the size of the types array returns the logical type duckdb_create_decimal_type creates a duckdb_logical_type of type decimal with the specified width and scale the resulting type should be destroyed with duckdb_destroy_logical_type syntax the width of the decimal type scale the scale of the decimal type returns the logical type duckdb_get_type_id retrieves the type class of a duckdb_logical_type syntax the logical type object returns the type id duckdb_decimal_width retrieves the width of a decimal type syntax the logical type object returns the width of the decimal type duckdb_decimal_scale retrieves the scale of a decimal type syntax the logical type object returns the scale of the decimal type duckdb_decimal_internal_type retrieves the internal storage type of a decimal type syntax the logical type object returns the internal type of the decimal type duckdb_enum_internal_type retrieves the internal storage type of an enum type syntax the logical type object returns the internal type of the enum type duckdb_enum_dictionary_size retrieves the dictionary size of the enum type syntax the logical type object returns the dictionary size of the enum type duckdb_enum_dictionary_value retrieves the dictionary value at the specified position from the enum the result must be freed with duckdb_free syntax the logical type object index the index in the dictionary returns the string value of the enum type must be freed with duckdb_free duckdb_list_type_child_type retrieves the child type of the given list type the result must be freed with duckdb_destroy_logical_type syntax the logical type object returns the child type of the list type must be destroyed with duckdb_destroy_logical_type duckdb_map_type_key_type retrieves the key type of the given map type the result must be freed with duckdb_destroy_logical_type syntax the logical type object returns the key type of the map type must be destroyed with duckdb_destroy_logical_type duckdb_map_type_value_type retrieves the value type of the given map type the result must be freed with duckdb_destroy_logical_type syntax the logical type object returns the value type of the map type must be destroyed with duckdb_destroy_logical_type duckdb_struct_type_child_count returns the number of children of a struct type syntax the logical type object returns the number of children of a struct type duckdb_struct_type_child_name retrieves the name of the struct child the result must be freed with duckdb_free syntax the logical type object index the child index returns the name of the struct type must be freed with duckdb_free duckdb_struct_type_child_type retrieves the child type of the given struct type at the specified index the result must be freed with duckdb_destroy_logical_type syntax the logical type object index the child index returns the child type of the struct type must be destroyed with duckdb_destroy_logical_type duckdb_union_type_member_count returns the number of members that the union type has syntax the logical type union object returns the number of members of a union type duckdb_union_type_member_name retrieves the name of the union member the result must be freed with duckdb_free syntax the logical type object index the child index returns the name of the union member must be freed with duckdb_free duckdb_union_type_member_type retrieves the child type of the given union member at the specified index the result must be freed with duckdb_destroy_logical_type syntax the logical type object index the child index returns the child type of the union member must be destroyed with duckdb_destroy_logical_type duckdb_destroy_logical_type destroys the logical type and de-allocates all memory allocated for that type syntax the logical type to destroy duckdb_create_data_chunk creates an empty datachunk with the specified set of types syntax an array of types of the data chunk column_count the number of columns returns the data chunk duckdb_destroy_data_chunk destroys the data chunk and de-allocates all memory allocated for that chunk syntax the data chunk to destroy duckdb_data_chunk_reset resets a data chunk clearing the validity masks and setting the cardinality of the data chunk to 0 syntax the data chunk to reset duckdb_data_chunk_get_column_count retrieves the number of columns in a data chunk syntax the data chunk to get the data from returns the number of columns in the data chunk duckdb_data_chunk_get_vector retrieves the vector at the specified column index in the data chunk the pointer to the vector is valid for as long as the chunk is alive it does not need to be destroyed syntax the data chunk to get the data from returns the vector duckdb_data_chunk_get_size retrieves the current number of tuples in a data chunk syntax the data chunk to get the data from returns the number of tuples in the data chunk duckdb_data_chunk_set_size sets the current number of tuples in a data chunk syntax the data chunk to set the size in size the number of tuples in the data chunk duckdb_vector_get_column_type retrieves the column type of the specified vector the result must be destroyed with duckdb_destroy_logical_type syntax the vector get the data from returns the type of the vector duckdb_vector_get_data retrieves the data pointer of the vector the data pointer can be used to read or write values from the vector how to read or write values depends on the type of the vector syntax the vector to get the data from returns the data pointer duckdb_vector_get_validity retrieves the validity mask pointer of the specified vector if all values are valid this function might return null the validity mask is a bitset that signifies null-ness within the data chunk it is a series of uint64_t values where each uint64_t value contains validity for 64 tuples the bit is set to 1 if the value is valid i e not null or 0 if the value is invalid i e null validity of a specific value can be obtained like this idx_t entry_idx row_idx 64 idx_t idx_in_entry row_idx 64 bool is_valid validity_mask entry_idx 1 idx_in_entry alternatively the slower duckdb_validity_row_is_valid function can be used syntax the vector to get the data from returns the pointer to the validity mask or null if no validity mask is present duckdb_vector_ensure_validity_writable ensures the validity mask is writable by allocating it after this function is called duckdb_vector_get_validity will always return non-null this allows null values to be written to the vector regardless of whether a validity mask was present before syntax the vector to alter duckdb_vector_assign_string_element assigns a string element in the vector at the specified location syntax the vector to alter index the row position in the vector to assign the string to str the null-terminated string duckdb_vector_assign_string_element_len assigns a string element in the vector at the specified location syntax the vector to alter index the row position in the vector to assign the string to str the string str_len the length of the string in bytes duckdb_list_vector_get_child retrieves the child vector of a list vector the resulting vector is valid as long as the parent vector is valid syntax the vector returns the child vector duckdb_list_vector_get_size returns the size of the child vector of the list syntax the vector returns the size of the child list duckdb_list_vector_set_size sets the total size of the underlying child-vector of a list vector syntax the list vector size the size of the child list returns the duckdb state returns duckdberror if the vector is nullptr duckdb_list_vector_reserve sets the total capacity of the underlying child-vector of a list syntax the list vector required_capacity the total capacity to reserve return the duckdb state returns duckdberror if the vector is nullptr duckdb_struct_vector_get_child retrieves the child vector of a struct vector the resulting vector is valid as long as the parent vector is valid syntax the vector index the child index returns the child vector duckdb_validity_row_is_valid returns whether or not a row is valid i e not null in the given validity mask syntax the validity mask as obtained through duckdb_data_chunk_get_validity row the row index returns true if the row is valid false otherwise duckdb_validity_set_row_validity in a validity mask sets a specific row to either valid or invalid note that duckdb_data_chunk_ensure_validity_writable should be called before calling duckdb_data_chunk_get_validity to ensure that there is a validity mask to write to syntax the validity mask as obtained through duckdb_data_chunk_get_validity row the row index valid whether or not to set the row to valid or invalid duckdb_validity_set_row_invalid in a validity mask sets a specific row to invalid equivalent to duckdb_validity_set_row_validity with valid set to false syntax the validity mask row the row index duckdb_validity_set_row_valid in a validity mask sets a specific row to valid equivalent to duckdb_validity_set_row_validity with valid set to true syntax the validity mask row the row index duckdb_create_table_function creates a new empty table function the return value should be destroyed with duckdb_destroy_table_function syntax the table function object duckdb_destroy_table_function destroys the given table function object syntax the table function to destroy duckdb_table_function_set_name sets the name of the given table function syntax the table function name the name of the table function duckdb_table_function_add_parameter adds a parameter to the table function syntax 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 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 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 the table function bind the bind function duckdb_table_function_set_init sets the init function of the table function syntax the table function init the init function duckdb_table_function_set_local_init sets the thread-local init function of the table function syntax the table function init the init function duckdb_table_function_set_function sets the main function of the table function syntax 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 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 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 the info object returns the extra info duckdb_bind_add_result_column adds a result column to the output of the table function syntax 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 the info object returns the init data object duckdb_function_set_error report that an error has occurred while executing the function syntax the info object error the error message duckdb_add_replacement_scan add a replacement scan definition to the specified database syntax the database object to add the replacement scan to replacement the replacement scan callback extra_data extra data that is passed back into the specified callback delete_callback the delete callback to call on the extra data if any duckdb_replacement_scan_set_function_name sets the replacement function name to use if this function is called in the replacement callback the replacement scan is performed if it is not called the replacement callback is not performed syntax the info object function_name the function name to substitute duckdb_replacement_scan_add_parameter adds a parameter to the replacement scan function syntax the info object parameter the parameter to add duckdb_replacement_scan_set_error report that an error has occurred while executing the replacement scan syntax the info object error the error message duckdb_appender_create creates an appender object syntax the connection context to create the appender in schema the schema of the table to append to or nullptr for the default schema table the table name to append to out_appender the resulting appender object returns duckdbsuccess on success or duckdberror on failure duckdb_appender_error returns the error message associated with the given appender if the appender has no error message this returns nullptr instead the error message should not be freed it will be de-allocated when duckdb_appender_destroy is called syntax the appender to get the error from returns the error message or nullptr if there is none duckdb_appender_flush flush the appender to the table forcing the cache of the appender to be cleared and the data to be appended to the base table this should generally not be used unless you know what you are doing instead call duckdb_appender_destroy when you are done with the appender syntax the appender to flush returns duckdbsuccess on success or duckdberror on failure duckdb_appender_close close the appender flushing all intermediate state in the appender to the table and closing it for further appends this is generally not necessary call duckdb_appender_destroy instead syntax the appender to flush and close returns duckdbsuccess on success or duckdberror on failure duckdb_appender_destroy close the appender and destroy it flushing all intermediate state in the appender to the table and de-allocating all memory associated with the appender syntax the appender to flush close and destroy returns duckdbsuccess on success or duckdberror on failure duckdb_appender_begin_row a nop function provided for backwards compatibility reasons does nothing only duckdb_appender_end_row is required syntax duckdb_appender_end_row finish the current row of appends after end_row is called the next row can be appended syntax the appender returns duckdbsuccess on success or duckdberror on failure duckdb_append_bool append a bool value to the appender syntax duckdb_append_int8 append an int8_t value to the appender syntax duckdb_append_int16 append an int16_t value to the appender syntax duckdb_append_int32 append an int32_t value to the appender syntax duckdb_append_int64 append an int64_t value to the appender syntax duckdb_append_hugeint append a duckdb_hugeint value to the appender syntax duckdb_append_uint8 append a uint8_t value to the appender syntax duckdb_append_uint16 append a uint16_t value to the appender syntax duckdb_append_uint32 append a uint32_t value to the appender syntax duckdb_append_uint64 append a uint64_t value to the appender syntax duckdb_append_float append a float value to the appender syntax duckdb_append_double append a double value to the appender syntax duckdb_append_date append a duckdb_date value to the appender syntax duckdb_append_time append a duckdb_time value to the appender syntax duckdb_append_timestamp append a duckdb_timestamp value to the appender syntax duckdb_append_interval append a duckdb_interval value to the appender syntax duckdb_append_varchar append a varchar value to the appender syntax duckdb_append_varchar_length append a varchar value to the appender syntax duckdb_append_blob append a blob value to the appender syntax duckdb_append_null append a null value to the appender of any type syntax duckdb_append_data_chunk appends a pre-filled data chunk to the specified appender the types of the data chunk must exactly match the types of the table no casting is performed if the types do not match or the appender is in an invalid state duckdberror is returned if the append is successful duckdbsuccess is returned syntax the appender to append to chunk the data chunk to append returns the return state duckdb_query_arrow executes a sql query within a connection and stores the full materialized result in an arrow structure if the query fails to execute duckdberror is returned and the error message can be retrieved by calling duckdb_query_arrow_error note that after running duckdb_query_arrow duckdb_destroy_arrow must be called on the result object even if the query fails otherwise the error stored within the result will not be freed correctly syntax the connection to perform the query in query the sql query to run out_result the query result returns duckdbsuccess on success or duckdberror on failure duckdb_query_arrow_schema fetch the internal arrow schema from the arrow result syntax the result to fetch the schema from out_schema the output schema returns duckdbsuccess on success or duckdberror on failure duckdb_query_arrow_array fetch an internal arrow array from the arrow result this function can be called multiple time to get next chunks which will free the previous out_array so consume the out_array before calling this function again syntax the result to fetch the array from out_array the output array returns duckdbsuccess on success or duckdberror on failure duckdb_arrow_column_count returns the number of columns present in a the arrow result object syntax the result object returns the number of columns present in the result object duckdb_arrow_row_count returns the number of rows present in a the arrow result object syntax the result object returns the number of rows present in the result object duckdb_arrow_rows_changed returns the number of rows changed by the query stored in the arrow result this is relevant only for insert update delete queries for other queries the rows_changed will be 0 syntax the result object returns the number of rows changed duckdb_query_arrow_error returns the error message contained within the result the error is only set if duckdb_query_arrow returns duckdberror the error message should not be freed it will be de-allocated when duckdb_destroy_arrow is called syntax the result object to fetch the nullmask from returns the error of the result duckdb_destroy_arrow closes the result and de-allocates all memory allocated for the arrow result syntax the result to destroy duckdb_execute_tasks execute duckdb tasks on this thread will return after max_tasks have been executed or if there are no more tasks present syntax the database object to execute tasks for max_tasks the maximum amount of tasks to execute duckdb_create_task_state creates a task state that can be used with duckdb_execute_tasks_state to execute tasks until duckdb_finish_execution is called on the state duckdb_destroy_state should be called on the result in order to free memory syntax the database object to create the task state for returns the task state that can be used with duckdb_execute_tasks_state duckdb_execute_tasks_state execute duckdb tasks on this thread the thread will keep on executing tasks forever until duckdb_finish_execution is called on the state multiple threads can share the same duckdb_task_state syntax the task state of the executor duckdb_execute_n_tasks_state execute duckdb tasks on this thread the thread will keep on executing tasks until either duckdb_finish_execution is called on the state max_tasks tasks have been executed or there are no more tasks to be executed multiple threads can share the same duckdb_task_state syntax the task state of the executor max_tasks the maximum amount of tasks to execute returns the amount of tasks that have actually been executed duckdb_finish_execution finish execution on a specific task syntax the task state to finish execution duckdb_task_state_is_finished check if the provided duckdb_task_state has finished execution syntax the task state to inspect returns whether or not duckdb_finish_execution has been called on the task state duckdb_destroy_task_state destroys the task state returned from duckdb_create_task_state note that this should not be called while there is an active duckdb_execute_tasks_state running on the task state syntax the task state to clean up duckdb_execution_is_finished returns true if execution of the current query is finished syntax the connection on which to check duckdb_stream_fetch_chunk fetches a data chunk from the streaming duckdb_result this function should be called repeatedly until the result is exhausted the result must be destroyed with duckdb_destroy_data_chunk this function can only be used on duckdb_results created with duckdb_pending_prepared_streaming if this function is used none of the other result functions can be used and vice versa i e this function cannot be mixed with the legacy result functions or the materialized result functions it is not known beforehand how many chunks will be returned by this result syntax the result object to fetch the data chunk from returns the resulting data chunk returns null if the result has an error", + "text": "api reference open connect syntax path to the database file on disk or nullptr or memory to open an in-memory database out_database the result database object returns duckdbsuccess on success or duckdberror on failure duckdb_open_ext extended version of duckdb_open creates a new database or opens an existing database file stored at the the given path syntax path to the database file on disk or nullptr or memory to open an in-memory database out_database the result database object config optional configuration used to start up the database system out_error if set and the function returns duckdberror this will contain the reason why the start-up failed note that the error must be freed using duckdb_free returns duckdbsuccess on success or duckdberror on failure duckdb_close closes the specified database and de-allocates all memory allocated for that database this should be called after you are done with any database allocated through duckdb_open note that failing to call duckdb_close in case of e g a program crash will not cause data corruption still it is recommended to always correctly close a database object after you are done with it syntax the database object to shut down duckdb_connect opens a connection to a database connections are required to query the database and store transactional state associated with the connection the instantiated connection should be closed using duckdb_disconnect syntax the database file to connect to out_connection the result connection object returns duckdbsuccess on success or duckdberror on failure duckdb_interrupt interrupt running query syntax the connection to interruot duckdb_query_progress get progress of the running query syntax the working connection returns -1 if no progress or a percentage of the progress duckdb_disconnect closes the specified connection and de-allocates all memory allocated for that connection syntax the connection to close duckdb_library_version returns the version of the linked duckdb with a version postfix for dev versions usually used for developing c extensions that must return this for a compatibility check syntax duckdb_create_config initializes an empty configuration object that can be used to provide start-up options for the duckdb instance through duckdb_open_ext this will always succeed unless there is a malloc failure syntax the result configuration object returns duckdbsuccess on success or duckdberror on failure duckdb_config_count this returns the total amount of configuration options available for usage with duckdb_get_config_flag this should not be called in a loop as it internally loops over all the options syntax the amount of config options available duckdb_get_config_flag obtains a human-readable name and description of a specific configuration option this can be used to e g display configuration options this will succeed unless index is out of range i e duckdb_config_count the result name or description must not be freed syntax the index of the configuration option between 0 and duckdb_config_count out_name a name of the configuration flag out_description a description of the configuration flag returns duckdbsuccess on success or duckdberror on failure duckdb_set_config sets the specified option for the specified configuration the configuration option is indicated by name to obtain a list of config options see duckdb_get_config_flag in the source code configuration options are defined in config cpp this can fail if either the name is invalid or if the value provided for the option is invalid syntax the configuration object to set the option on name the name of the configuration flag to set option the value to set the configuration flag to returns duckdbsuccess on success or duckdberror on failure duckdb_destroy_config destroys the specified configuration option and de-allocates all memory allocated for the object syntax the configuration object to destroy duckdb_query executes a sql query within a connection and stores the full materialized result in the out_result pointer if the query fails to execute duckdberror is returned and the error message can be retrieved by calling duckdb_result_error note that after running duckdb_query duckdb_destroy_result must be called on the result object even if the query fails otherwise the error stored within the result will not be freed correctly syntax the connection to perform the query in query the sql query to run out_result the query result returns duckdbsuccess on success or duckdberror on failure duckdb_destroy_result closes the result and de-allocates all memory allocated for that connection syntax the result to destroy duckdb_column_name returns the column name of the specified column the result should not need be freed the column names will automatically be destroyed when the result is destroyed returns null if the column is out of range syntax the result object to fetch the column name from col the column index returns the column name of the specified column duckdb_column_type returns the column type of the specified column returns duckdb_type_invalid if the column is out of range syntax the result object to fetch the column type from col the column index returns the column type of the specified column duckdb_column_logical_type returns the logical column type of the specified column the return type of this call should be destroyed with duckdb_destroy_logical_type returns null if the column is out of range syntax the result object to fetch the column type from col the column index returns the logical column type of the specified column duckdb_column_count returns the number of columns present in a the result object syntax the result object returns the number of columns present in the result object duckdb_row_count returns the number of rows present in a the result object syntax the result object returns the number of rows present in the result object duckdb_rows_changed returns the number of rows changed by the query stored in the result this is relevant only for insert update delete queries for other queries the rows_changed will be 0 syntax the result object returns the number of rows changed duckdb_column_data deprecated prefer using duckdb_result_get_chunk instead returns the data of a specific column of a result in columnar format the function returns a dense array which contains the result data the exact type stored in the array depends on the corresponding duckdb_type as provided by duckdb_column_type for the exact type by which the data should be accessed see the comments in the types section or the duckdb_type enum for example for a column of type duckdb_type_integer rows can be accessed in the following manner int32_t data int32_t duckdb_column_data result 0 printf data for row d d n row data row syntax the result object to fetch the column data from col the column index returns the column data of the specified column duckdb_nullmask_data deprecated prefer using duckdb_result_get_chunk instead returns the nullmask of a specific column of a result in columnar format the nullmask indicates for every row whether or not the corresponding row is null if a row is null the values present in the array provided by duckdb_column_data are undefined int32_t data int32_t duckdb_column_data result 0 bool nullmask duckdb_nullmask_data result 0 if nullmask row printf data for row d null n row else printf data for row d d n row data row syntax the result object to fetch the nullmask from col the column index returns the nullmask of the specified column duckdb_result_error returns the error message contained within the result the error is only set if duckdb_query returns duckdberror the result of this function must not be freed it will be cleaned up when duckdb_destroy_result is called syntax the result object to fetch the error from returns the error of the result duckdb_result_get_chunk fetches a data chunk from the duckdb_result this function should be called repeatedly until the result is exhausted the result must be destroyed with duckdb_destroy_data_chunk this function supersedes all duckdb_value functions as well as the duckdb_column_data and duckdb_nullmask_data functions it results in significantly better performance and should be preferred in newer code-bases if this function is used none of the other result functions can be used and vice versa i e this function cannot be mixed with the legacy result functions use duckdb_result_chunk_count to figure out how many chunks there are in the result syntax the result object to fetch the data chunk from chunk_index the chunk index to fetch from returns the resulting data chunk returns null if the chunk index is out of bounds duckdb_result_is_streaming checks if the type of the internal result is streamqueryresult syntax the result object to check returns whether or not the result object is of the type streamqueryresult duckdb_result_chunk_count returns the number of data chunks present in the result syntax the result object returns number of data chunks present in the result duckdb_value_boolean syntax the boolean value at the specified location or false if the value cannot be converted duckdb_value_int8 syntax the int8_t value at the specified location or 0 if the value cannot be converted duckdb_value_int16 syntax the int16_t value at the specified location or 0 if the value cannot be converted duckdb_value_int32 syntax the int32_t value at the specified location or 0 if the value cannot be converted duckdb_value_int64 syntax the int64_t value at the specified location or 0 if the value cannot be converted duckdb_value_hugeint syntax the duckdb_hugeint value at the specified location or 0 if the value cannot be converted duckdb_value_decimal syntax the duckdb_decimal value at the specified location or 0 if the value cannot be converted duckdb_value_uint8 syntax the uint8_t value at the specified location or 0 if the value cannot be converted duckdb_value_uint16 syntax the uint16_t value at the specified location or 0 if the value cannot be converted duckdb_value_uint32 syntax the uint32_t value at the specified location or 0 if the value cannot be converted duckdb_value_uint64 syntax the uint64_t value at the specified location or 0 if the value cannot be converted duckdb_value_float syntax the float value at the specified location or 0 if the value cannot be converted duckdb_value_double syntax the double value at the specified location or 0 if the value cannot be converted duckdb_value_date syntax the duckdb_date value at the specified location or 0 if the value cannot be converted duckdb_value_time syntax the duckdb_time value at the specified location or 0 if the value cannot be converted duckdb_value_timestamp syntax the duckdb_timestamp value at the specified location or 0 if the value cannot be converted duckdb_value_interval syntax the duckdb_interval value at the specified location or 0 if the value cannot be converted duckdb_value_varchar syntax use duckdb_value_string instead this function does not work correctly if the string contains null bytes returns the text value at the specified location as a null-terminated string or nullptr if the value cannot be converted the result must be freed with duckdb_free duckdb_value_varchar_internal syntax use duckdb_value_string_internal instead this function does not work correctly if the string contains null bytes returns the char value at the specified location only works on varchar columns and does not auto-cast if the column is not a varchar column this function will return null the result must not be freed duckdb_value_string_internal syntax use duckdb_value_string_internal instead this function does not work correctly if the string contains null bytes returns the char value at the specified location only works on varchar columns and does not auto-cast if the column is not a varchar column this function will return null the result must not be freed duckdb_value_blob syntax the duckdb_blob value at the specified location returns a blob with blob data set to nullptr if the value cannot be converted the resulting blob data must be freed with duckdb_free duckdb_value_is_null syntax returns true if the value at the specified index is null and false otherwise duckdb_malloc allocate size bytes of memory using the duckdb internal malloc function any memory allocated in this manner should be freed using duckdb_free syntax the number of bytes to allocate returns a pointer to the allocated memory region duckdb_free free a value returned from duckdb_malloc duckdb_value_varchar or duckdb_value_blob syntax the memory region to de-allocate duckdb_vector_size the internal vector size used by duckdb this is the amount of tuples that will fit into a data chunk created by duckdb_create_data_chunk syntax the vector size duckdb_string_is_inlined whether or not the duckdb_string_t value is inlined this means that the data of the string does not have a separate allocation syntax duckdb_from_date decompose a duckdb_date object into year month and date stored as duckdb_date_struct syntax the date object as obtained from a duckdb_type_date column returns the duckdb_date_struct with the decomposed elements duckdb_to_date re-compose a duckdb_date from year month and date duckdb_date_struct syntax the year month and date stored in a duckdb_date_struct returns the duckdb_date element duckdb_from_time decompose a duckdb_time object into hour minute second and microsecond stored as duckdb_time_struct syntax the time object as obtained from a duckdb_type_time column returns the duckdb_time_struct with the decomposed elements duckdb_to_time re-compose a duckdb_time from hour minute second and microsecond duckdb_time_struct syntax the hour minute second and microsecond in a duckdb_time_struct returns the duckdb_time element duckdb_from_timestamp decompose a duckdb_timestamp object into a duckdb_timestamp_struct syntax the ts object as obtained from a duckdb_type_timestamp column returns the duckdb_timestamp_struct with the decomposed elements duckdb_to_timestamp re-compose a duckdb_timestamp from a duckdb_timestamp_struct syntax the de-composed elements in a duckdb_timestamp_struct returns the duckdb_timestamp element duckdb_hugeint_to_double converts a duckdb_hugeint object as obtained from a duckdb_type_hugeint column into a double syntax the hugeint value returns the converted double element duckdb_double_to_hugeint converts a double value to a duckdb_hugeint object if the conversion fails because the double value is too big the result will be 0 syntax the double value returns the converted duckdb_hugeint element duckdb_double_to_decimal converts a double value to a duckdb_decimal object if the conversion fails because the double value is too big or the width scale are invalid the result will be 0 syntax the double value returns the converted duckdb_decimal element duckdb_decimal_to_double converts a duckdb_decimal object as obtained from a duckdb_type_decimal column into a double syntax the decimal value returns the converted double element duckdb_prepare create a prepared statement object from a query note that after calling duckdb_prepare the prepared statement should always be destroyed using duckdb_destroy_prepare even if the prepare fails if the prepare fails duckdb_prepare_error can be called to obtain the reason why the prepare failed syntax the connection object query the sql query to prepare out_prepared_statement the resulting prepared statement object returns duckdbsuccess on success or duckdberror on failure duckdb_destroy_prepare closes the prepared statement and de-allocates all memory allocated for the statement syntax the prepared statement to destroy duckdb_prepare_error returns the error message associated with the given prepared statement if the prepared statement has no error message this returns nullptr instead the error message should not be freed it will be de-allocated when duckdb_destroy_prepare is called syntax the prepared statement to obtain the error from returns the error message or nullptr if there is none duckdb_nparams returns the number of parameters that can be provided to the given prepared statement returns 0 if the query was not successfully prepared syntax the prepared statement to obtain the number of parameters for duckdb_param_type returns the parameter type for the parameter at the given index returns duckdb_type_invalid if the parameter index is out of range or the statement was not successfully prepared syntax the prepared statement param_idx the parameter index returns the parameter type duckdb_clear_bindings clear the params bind to the prepared statement syntax duckdb_bind_boolean binds a bool value to the prepared statement at the specified index syntax duckdb_bind_int8 binds an int8_t value to the prepared statement at the specified index syntax duckdb_bind_int16 binds an int16_t value to the prepared statement at the specified index syntax duckdb_bind_int32 binds an int32_t value to the prepared statement at the specified index syntax duckdb_bind_int64 binds an int64_t value to the prepared statement at the specified index syntax duckdb_bind_hugeint binds an duckdb_hugeint value to the prepared statement at the specified index syntax duckdb_bind_decimal binds a duckdb_decimal value to the prepared statement at the specified index syntax duckdb_bind_uint8 binds an uint8_t value to the prepared statement at the specified index syntax duckdb_bind_uint16 binds an uint16_t value to the prepared statement at the specified index syntax duckdb_bind_uint32 binds an uint32_t value to the prepared statement at the specified index syntax duckdb_bind_uint64 binds an uint64_t value to the prepared statement at the specified index syntax duckdb_bind_float binds an float value to the prepared statement at the specified index syntax duckdb_bind_double binds an double value to the prepared statement at the specified index syntax duckdb_bind_date binds a duckdb_date value to the prepared statement at the specified index syntax duckdb_bind_time binds a duckdb_time value to the prepared statement at the specified index syntax duckdb_bind_timestamp binds a duckdb_timestamp value to the prepared statement at the specified index syntax duckdb_bind_interval binds a duckdb_interval value to the prepared statement at the specified index syntax duckdb_bind_varchar binds a null-terminated varchar value to the prepared statement at the specified index syntax duckdb_bind_varchar_length binds a varchar value to the prepared statement at the specified index syntax duckdb_bind_blob binds a blob value to the prepared statement at the specified index syntax duckdb_bind_null binds a null value to the prepared statement at the specified index syntax duckdb_execute_prepared executes the prepared statement with the given bound parameters and returns a materialized query result this method can be called multiple times for each prepared statement and the parameters can be modified between calls to this function syntax the prepared statement to execute out_result the query result returns duckdbsuccess on success or duckdberror on failure duckdb_execute_prepared_arrow executes the prepared statement with the given bound parameters and returns an arrow query result syntax the prepared statement to execute out_result the query result returns duckdbsuccess on success or duckdberror on failure duckdb_arrow_scan scans the arrow stream and creates a view with the given name syntax the connection on which to execute the scan table_name name of the temporary view to create arrow arrow stream wrapper returns duckdbsuccess on success or duckdberror on failure duckdb_arrow_array_scan scans the arrow array and creates a view with the given name syntax the connection on which to execute the scan table_name name of the temporary view to create arrow_schema arrow schema wrapper arrow_array arrow array wrapper out_stream output array stream that wraps around the passed schema for releasing deleting once done returns duckdbsuccess on success or duckdberror on failure duckdb_extract_statements extract all statements from a query note that after calling duckdb_extract_statements the extracted statements should always be destroyed using duckdb_destroy_extracted even if no statements were extracted if the extract fails duckdb_extract_statements_error can be called to obtain the reason why the extract failed syntax the connection object query the sql query to extract out_extracted_statements the resulting extracted statements object returns the number of extracted statements or 0 on failure duckdb_prepare_extracted_statement prepare an extracted statement note that after calling duckdb_prepare_extracted_statement the prepared statement should always be destroyed using duckdb_destroy_prepare even if the prepare fails if the prepare fails duckdb_prepare_error can be called to obtain the reason why the prepare failed syntax the connection object extracted_statements the extracted statements object index the index of the extracted statement to prepare out_prepared_statement the resulting prepared statement object returns duckdbsuccess on success or duckdberror on failure duckdb_extract_statements_error returns the error message contained within the extracted statements the result of this function must not be freed it will be cleaned up when duckdb_destroy_extracted is called syntax the extracted statements to fetch the error from returns the error of the extracted statements duckdb_destroy_extracted de-allocates all memory allocated for the extracted statements syntax the extracted statements to destroy duckdb_pending_prepared executes the prepared statement with the given bound parameters and returns a pending result the pending result represents an intermediate structure for a query that is not yet fully executed the pending result can be used to incrementally execute a query returning control to the client between tasks note that after calling duckdb_pending_prepared the pending result should always be destroyed using duckdb_destroy_pending even if this function returns duckdberror syntax the prepared statement to execute out_result the pending query result returns duckdbsuccess on success or duckdberror on failure duckdb_pending_prepared_streaming executes the prepared statement with the given bound parameters and returns a pending result this pending result will create a streaming duckdb_result when executed the pending result represents an intermediate structure for a query that is not yet fully executed note that after calling duckdb_pending_prepared_streaming the pending result should always be destroyed using duckdb_destroy_pending even if this function returns duckdberror syntax the prepared statement to execute out_result the pending query result returns duckdbsuccess on success or duckdberror on failure duckdb_destroy_pending closes the pending result and de-allocates all memory allocated for the result syntax the pending result to destroy duckdb_pending_error returns the error message contained within the pending result the result of this function must not be freed it will be cleaned up when duckdb_destroy_pending is called syntax the pending result to fetch the error from returns the error of the pending result duckdb_pending_execute_task executes a single task within the query returning whether or not the query is ready if this returns duckdb_pending_result_ready the duckdb_execute_pending function can be called to obtain the result if this returns duckdb_pending_result_not_ready the duckdb_pending_execute_task function should be called again if this returns duckdb_pending_error an error occurred during execution the error message can be obtained by calling duckdb_pending_error on the pending_result syntax the pending result to execute a task within returns the state of the pending result after the execution duckdb_execute_pending fully execute a pending query result returning the final query result if duckdb_pending_execute_task has been called until duckdb_pending_result_ready was returned this will return fast otherwise all remaining tasks must be executed first syntax the pending result to execute out_result the result object returns duckdbsuccess on success or duckdberror on failure duckdb_destroy_value destroys the value and de-allocates all memory allocated for that type syntax the value to destroy duckdb_create_varchar creates a value from a null-terminated string syntax the null-terminated string returns the value this must be destroyed with duckdb_destroy_value duckdb_create_varchar_length creates a value from a string syntax the text length the length of the text returns the value this must be destroyed with duckdb_destroy_value duckdb_create_int64 creates a value from an int64 syntax the bigint value returns the value this must be destroyed with duckdb_destroy_value duckdb_get_varchar obtains a string representation of the given value the result must be destroyed with duckdb_free syntax the value returns the string value this must be destroyed with duckdb_free duckdb_get_int64 obtains an int64 of the given value syntax the value returns the int64 value or 0 if no conversion is possible duckdb_create_logical_type creates a duckdb_logical_type from a standard primitive type the resulting type should be destroyed with duckdb_destroy_logical_type this should not be used with duckdb_type_decimal syntax the primitive type to create returns the logical type duckdb_create_list_type creates a list type from its child type the resulting type should be destroyed with duckdb_destroy_logical_type syntax the child type of list type to create returns the logical type duckdb_create_map_type creates a map type from its key type and value type the resulting type should be destroyed with duckdb_destroy_logical_type syntax the key type and value type of map type to create returns the logical type duckdb_create_union_type creates a union type from the passed types array the resulting type should be destroyed with duckdb_destroy_logical_type syntax the array of types that the union should consist of type_amount the size of the types array returns the logical type duckdb_create_decimal_type creates a duckdb_logical_type of type decimal with the specified width and scale the resulting type should be destroyed with duckdb_destroy_logical_type syntax the width of the decimal type scale the scale of the decimal type returns the logical type duckdb_get_type_id retrieves the type class of a duckdb_logical_type syntax the logical type object returns the type id duckdb_decimal_width retrieves the width of a decimal type syntax the logical type object returns the width of the decimal type duckdb_decimal_scale retrieves the scale of a decimal type syntax the logical type object returns the scale of the decimal type duckdb_decimal_internal_type retrieves the internal storage type of a decimal type syntax the logical type object returns the internal type of the decimal type duckdb_enum_internal_type retrieves the internal storage type of an enum type syntax the logical type object returns the internal type of the enum type duckdb_enum_dictionary_size retrieves the dictionary size of the enum type syntax the logical type object returns the dictionary size of the enum type duckdb_enum_dictionary_value retrieves the dictionary value at the specified position from the enum the result must be freed with duckdb_free syntax the logical type object index the index in the dictionary returns the string value of the enum type must be freed with duckdb_free duckdb_list_type_child_type retrieves the child type of the given list type the result must be freed with duckdb_destroy_logical_type syntax the logical type object returns the child type of the list type must be destroyed with duckdb_destroy_logical_type duckdb_map_type_key_type retrieves the key type of the given map type the result must be freed with duckdb_destroy_logical_type syntax the logical type object returns the key type of the map type must be destroyed with duckdb_destroy_logical_type duckdb_map_type_value_type retrieves the value type of the given map type the result must be freed with duckdb_destroy_logical_type syntax the logical type object returns the value type of the map type must be destroyed with duckdb_destroy_logical_type duckdb_struct_type_child_count returns the number of children of a struct type syntax the logical type object returns the number of children of a struct type duckdb_struct_type_child_name retrieves the name of the struct child the result must be freed with duckdb_free syntax the logical type object index the child index returns the name of the struct type must be freed with duckdb_free duckdb_struct_type_child_type retrieves the child type of the given struct type at the specified index the result must be freed with duckdb_destroy_logical_type syntax the logical type object index the child index returns the child type of the struct type must be destroyed with duckdb_destroy_logical_type duckdb_union_type_member_count returns the number of members that the union type has syntax the logical type union object returns the number of members of a union type duckdb_union_type_member_name retrieves the name of the union member the result must be freed with duckdb_free syntax the logical type object index the child index returns the name of the union member must be freed with duckdb_free duckdb_union_type_member_type retrieves the child type of the given union member at the specified index the result must be freed with duckdb_destroy_logical_type syntax the logical type object index the child index returns the child type of the union member must be destroyed with duckdb_destroy_logical_type duckdb_destroy_logical_type destroys the logical type and de-allocates all memory allocated for that type syntax the logical type to destroy duckdb_create_data_chunk creates an empty datachunk with the specified set of types syntax an array of types of the data chunk column_count the number of columns returns the data chunk duckdb_destroy_data_chunk destroys the data chunk and de-allocates all memory allocated for that chunk syntax the data chunk to destroy duckdb_data_chunk_reset resets a data chunk clearing the validity masks and setting the cardinality of the data chunk to 0 syntax the data chunk to reset duckdb_data_chunk_get_column_count retrieves the number of columns in a data chunk syntax the data chunk to get the data from returns the number of columns in the data chunk duckdb_data_chunk_get_vector retrieves the vector at the specified column index in the data chunk the pointer to the vector is valid for as long as the chunk is alive it does not need to be destroyed syntax the data chunk to get the data from returns the vector duckdb_data_chunk_get_size retrieves the current number of tuples in a data chunk syntax the data chunk to get the data from returns the number of tuples in the data chunk duckdb_data_chunk_set_size sets the current number of tuples in a data chunk syntax the data chunk to set the size in size the number of tuples in the data chunk duckdb_vector_get_column_type retrieves the column type of the specified vector the result must be destroyed with duckdb_destroy_logical_type syntax the vector get the data from returns the type of the vector duckdb_vector_get_data retrieves the data pointer of the vector the data pointer can be used to read or write values from the vector how to read or write values depends on the type of the vector syntax the vector to get the data from returns the data pointer duckdb_vector_get_validity retrieves the validity mask pointer of the specified vector if all values are valid this function might return null the validity mask is a bitset that signifies null-ness within the data chunk it is a series of uint64_t values where each uint64_t value contains validity for 64 tuples the bit is set to 1 if the value is valid i e not null or 0 if the value is invalid i e null validity of a specific value can be obtained like this idx_t entry_idx row_idx 64 idx_t idx_in_entry row_idx 64 bool is_valid validity_mask entry_idx 1 idx_in_entry alternatively the slower duckdb_validity_row_is_valid function can be used syntax the vector to get the data from returns the pointer to the validity mask or null if no validity mask is present duckdb_vector_ensure_validity_writable ensures the validity mask is writable by allocating it after this function is called duckdb_vector_get_validity will always return non-null this allows null values to be written to the vector regardless of whether a validity mask was present before syntax the vector to alter duckdb_vector_assign_string_element assigns a string element in the vector at the specified location syntax the vector to alter index the row position in the vector to assign the string to str the null-terminated string duckdb_vector_assign_string_element_len assigns a string element in the vector at the specified location syntax the vector to alter index the row position in the vector to assign the string to str the string str_len the length of the string in bytes duckdb_list_vector_get_child retrieves the child vector of a list vector the resulting vector is valid as long as the parent vector is valid syntax the vector returns the child vector duckdb_list_vector_get_size returns the size of the child vector of the list syntax the vector returns the size of the child list duckdb_list_vector_set_size sets the total size of the underlying child-vector of a list vector syntax the list vector size the size of the child list returns the duckdb state returns duckdberror if the vector is nullptr duckdb_list_vector_reserve sets the total capacity of the underlying child-vector of a list syntax the list vector required_capacity the total capacity to reserve return the duckdb state returns duckdberror if the vector is nullptr duckdb_struct_vector_get_child retrieves the child vector of a struct vector the resulting vector is valid as long as the parent vector is valid syntax the vector index the child index returns the child vector duckdb_validity_row_is_valid returns whether or not a row is valid i e not null in the given validity mask syntax the validity mask as obtained through duckdb_data_chunk_get_validity row the row index returns true if the row is valid false otherwise duckdb_validity_set_row_validity in a validity mask sets a specific row to either valid or invalid note that duckdb_data_chunk_ensure_validity_writable should be called before calling duckdb_data_chunk_get_validity to ensure that there is a validity mask to write to syntax the validity mask as obtained through duckdb_data_chunk_get_validity row the row index valid whether or not to set the row to valid or invalid duckdb_validity_set_row_invalid in a validity mask sets a specific row to invalid equivalent to duckdb_validity_set_row_validity with valid set to false syntax the validity mask row the row index duckdb_validity_set_row_valid in a validity mask sets a specific row to valid equivalent to duckdb_validity_set_row_validity with valid set to true syntax the validity mask row the row index duckdb_create_table_function creates a new empty table function the return value should be destroyed with duckdb_destroy_table_function syntax the table function object duckdb_destroy_table_function destroys the given table function object syntax the table function to destroy duckdb_table_function_set_name sets the name of the given table function syntax the table function name the name of the table function duckdb_table_function_add_parameter adds a parameter to the table function syntax 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 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 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 the table function bind the bind function duckdb_table_function_set_init sets the init function of the table function syntax the table function init the init function duckdb_table_function_set_local_init sets the thread-local init function of the table function syntax the table function init the init function duckdb_table_function_set_function sets the main function of the table function syntax 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 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 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 the info object returns the extra info duckdb_bind_add_result_column adds a result column to the output of the table function syntax 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 the info object returns the init data object duckdb_function_set_error report that an error has occurred while executing the function syntax the info object error the error message duckdb_add_replacement_scan add a replacement scan definition to the specified database syntax the database object to add the replacement scan to replacement the replacement scan callback extra_data extra data that is passed back into the specified callback delete_callback the delete callback to call on the extra data if any duckdb_replacement_scan_set_function_name sets the replacement function name to use if this function is called in the replacement callback the replacement scan is performed if it is not called the replacement callback is not performed syntax the info object function_name the function name to substitute duckdb_replacement_scan_add_parameter adds a parameter to the replacement scan function syntax the info object parameter the parameter to add duckdb_replacement_scan_set_error report that an error has occurred while executing the replacement scan syntax the info object error the error message duckdb_appender_create creates an appender object syntax the connection context to create the appender in schema the schema of the table to append to or nullptr for the default schema table the table name to append to out_appender the resulting appender object returns duckdbsuccess on success or duckdberror on failure duckdb_appender_error returns the error message associated with the given appender if the appender has no error message this returns nullptr instead the error message should not be freed it will be de-allocated when duckdb_appender_destroy is called syntax the appender to get the error from returns the error message or nullptr if there is none duckdb_appender_flush flush the appender to the table forcing the cache of the appender to be cleared and the data to be appended to the base table this should generally not be used unless you know what you are doing instead call duckdb_appender_destroy when you are done with the appender syntax the appender to flush returns duckdbsuccess on success or duckdberror on failure duckdb_appender_close close the appender flushing all intermediate state in the appender to the table and closing it for further appends this is generally not necessary call duckdb_appender_destroy instead syntax the appender to flush and close returns duckdbsuccess on success or duckdberror on failure duckdb_appender_destroy close the appender and destroy it flushing all intermediate state in the appender to the table and de-allocating all memory associated with the appender syntax the appender to flush close and destroy returns duckdbsuccess on success or duckdberror on failure duckdb_appender_begin_row a nop function provided for backwards compatibility reasons does nothing only duckdb_appender_end_row is required syntax duckdb_appender_end_row finish the current row of appends after end_row is called the next row can be appended syntax the appender returns duckdbsuccess on success or duckdberror on failure duckdb_append_bool append a bool value to the appender syntax duckdb_append_int8 append an int8_t value to the appender syntax duckdb_append_int16 append an int16_t value to the appender syntax duckdb_append_int32 append an int32_t value to the appender syntax duckdb_append_int64 append an int64_t value to the appender syntax duckdb_append_hugeint append a duckdb_hugeint value to the appender syntax duckdb_append_uint8 append a uint8_t value to the appender syntax duckdb_append_uint16 append a uint16_t value to the appender syntax duckdb_append_uint32 append a uint32_t value to the appender syntax duckdb_append_uint64 append a uint64_t value to the appender syntax duckdb_append_float append a float value to the appender syntax duckdb_append_double append a double value to the appender syntax duckdb_append_date append a duckdb_date value to the appender syntax duckdb_append_time append a duckdb_time value to the appender syntax duckdb_append_timestamp append a duckdb_timestamp value to the appender syntax duckdb_append_interval append a duckdb_interval value to the appender syntax duckdb_append_varchar append a varchar value to the appender syntax duckdb_append_varchar_length append a varchar value to the appender syntax duckdb_append_blob append a blob value to the appender syntax duckdb_append_null append a null value to the appender of any type syntax duckdb_append_data_chunk appends a pre-filled data chunk to the specified appender the types of the data chunk must exactly match the types of the table no casting is performed if the types do not match or the appender is in an invalid state duckdberror is returned if the append is successful duckdbsuccess is returned syntax the appender to append to chunk the data chunk to append returns the return state duckdb_query_arrow executes a sql query within a connection and stores the full materialized result in an arrow structure if the query fails to execute duckdberror is returned and the error message can be retrieved by calling duckdb_query_arrow_error note that after running duckdb_query_arrow duckdb_destroy_arrow must be called on the result object even if the query fails otherwise the error stored within the result will not be freed correctly syntax the connection to perform the query in query the sql query to run out_result the query result returns duckdbsuccess on success or duckdberror on failure duckdb_query_arrow_schema fetch the internal arrow schema from the arrow result syntax the result to fetch the schema from out_schema the output schema returns duckdbsuccess on success or duckdberror on failure duckdb_query_arrow_array fetch an internal arrow array from the arrow result this function can be called multiple time to get next chunks which will free the previous out_array so consume the out_array before calling this function again syntax the result to fetch the array from out_array the output array returns duckdbsuccess on success or duckdberror on failure duckdb_arrow_column_count returns the number of columns present in a the arrow result object syntax the result object returns the number of columns present in the result object duckdb_arrow_row_count returns the number of rows present in a the arrow result object syntax the result object returns the number of rows present in the result object duckdb_arrow_rows_changed returns the number of rows changed by the query stored in the arrow result this is relevant only for insert update delete queries for other queries the rows_changed will be 0 syntax the result object returns the number of rows changed duckdb_query_arrow_error returns the error message contained within the result the error is only set if duckdb_query_arrow returns duckdberror the error message should not be freed it will be de-allocated when duckdb_destroy_arrow is called syntax the result object to fetch the nullmask from returns the error of the result duckdb_destroy_arrow closes the result and de-allocates all memory allocated for the arrow result syntax the result to destroy duckdb_execute_tasks execute duckdb tasks on this thread will return after max_tasks have been executed or if there are no more tasks present syntax the database object to execute tasks for max_tasks the maximum amount of tasks to execute duckdb_create_task_state creates a task state that can be used with duckdb_execute_tasks_state to execute tasks until duckdb_finish_execution is called on the state duckdb_destroy_state should be called on the result in order to free memory syntax the database object to create the task state for returns the task state that can be used with duckdb_execute_tasks_state duckdb_execute_tasks_state execute duckdb tasks on this thread the thread will keep on executing tasks forever until duckdb_finish_execution is called on the state multiple threads can share the same duckdb_task_state syntax the task state of the executor duckdb_execute_n_tasks_state execute duckdb tasks on this thread the thread will keep on executing tasks until either duckdb_finish_execution is called on the state max_tasks tasks have been executed or there are no more tasks to be executed multiple threads can share the same duckdb_task_state syntax the task state of the executor max_tasks the maximum amount of tasks to execute returns the amount of tasks that have actually been executed duckdb_finish_execution finish execution on a specific task syntax the task state to finish execution duckdb_task_state_is_finished check if the provided duckdb_task_state has finished execution syntax the task state to inspect returns whether or not duckdb_finish_execution has been called on the task state duckdb_destroy_task_state destroys the task state returned from duckdb_create_task_state note that this should not be called while there is an active duckdb_execute_tasks_state running on the task state syntax the task state to clean up duckdb_execution_is_finished returns true if execution of the current query is finished syntax the connection on which to check duckdb_stream_fetch_chunk fetches a data chunk from the streaming duckdb_result this function should be called repeatedly until the result is exhausted the result must be destroyed with duckdb_destroy_data_chunk this function can only be used on duckdb_results created with duckdb_pending_prepared_streaming if this function is used none of the other result functions can be used and vice versa i e this function cannot be mixed with the legacy result functions or the materialized result functions it is not known beforehand how many chunks will be returned by this result syntax the result object to fetch the data chunk from returns the resulting data chunk returns null if the result has an error", "category": "C", "url": "/docs/api/c/api", "blurb": "API Reference Open/Connect Syntax Path to the database file on disk, or nullptr or :memory: to open an in-memory..." @@ -212,7 +212,7 @@ }, { "title": "C API - Startup & Shutdown", - "text": "to use duckdb you must first initialize a duckdb_database handle using duckdb_open duckdb_open takes as parameter the database file to read and write from the special value null nullptr can be used to create an in-memory database note that for an in-memory database no data is persisted to disk i e all data is lost when you exit the process with the duckdb_database handle you can create one or many duckdb_connection using duckdb_connect while individual connections are thread-safe they will be locked during querying it is therefore recommended that each thread uses its own connection to allow for the best parallel performance all duckdb_connection s have to explicitly be disconnected with duckdb_disconnect and the duckdb_database has to be explicitly closed with duckdb_close to avoid memory and file handle leaking example duckdb_database db duckdb_connection con if duckdb_open null db duckdberror handle error if duckdb_connect db con duckdberror handle error run queries cleanup duckdb_disconnect con duckdb_close db api reference syntax path to the database file on disk or nullptr or memory to open an in-memory database out_database the result database object returns duckdbsuccess on success or duckdberror on failure duckdb_open_ext extended version of duckdb_open creates a new database or opens an existing database file stored at the the given path syntax path to the database file on disk or nullptr or memory to open an in-memory database out_database the result database object config optional configuration used to start up the database system out_error if set and the function returns duckdberror this will contain the reason why the start-up failed note that the error must be freed using duckdb_free returns duckdbsuccess on success or duckdberror on failure duckdb_close closes the specified database and de-allocates all memory allocated for that database this should be called after you are done with any database allocated through duckdb_open note that failing to call duckdb_close in case of e g a program crash will not cause data corruption still it is recommended to always correctly close a database object after you are done with it syntax the database object to shut down duckdb_connect opens a connection to a database connections are required to query the database and store transactional state associated with the connection the instantiated connection should be closed using duckdb_disconnect syntax the database file to connect to out_connection the result connection object returns duckdbsuccess on success or duckdberror on failure duckdb_disconnect closes the specified connection and de-allocates all memory allocated for that connection syntax the connection to close duckdb_library_version returns the version of the linked duckdb with a version postfix for dev versions usually used for developing c extensions that must return this for a compatibility check syntax", + "text": "to use duckdb you must first initialize a duckdb_database handle using duckdb_open duckdb_open takes as parameter the database file to read and write from the special value null nullptr can be used to create an in-memory database note that for an in-memory database no data is persisted to disk i e all data is lost when you exit the process with the duckdb_database handle you can create one or many duckdb_connection using duckdb_connect while individual connections are thread-safe they will be locked during querying it is therefore recommended that each thread uses its own connection to allow for the best parallel performance all duckdb_connection s have to explicitly be disconnected with duckdb_disconnect and the duckdb_database has to be explicitly closed with duckdb_close to avoid memory and file handle leaking example duckdb_database db duckdb_connection con if duckdb_open null db duckdberror handle error if duckdb_connect db con duckdberror handle error run queries cleanup duckdb_disconnect con duckdb_close db api reference syntax path to the database file on disk or nullptr or memory to open an in-memory database out_database the result database object returns duckdbsuccess on success or duckdberror on failure duckdb_open_ext extended version of duckdb_open creates a new database or opens an existing database file stored at the the given path syntax path to the database file on disk or nullptr or memory to open an in-memory database out_database the result database object config optional configuration used to start up the database system out_error if set and the function returns duckdberror this will contain the reason why the start-up failed note that the error must be freed using duckdb_free returns duckdbsuccess on success or duckdberror on failure duckdb_close closes the specified database and de-allocates all memory allocated for that database this should be called after you are done with any database allocated through duckdb_open note that failing to call duckdb_close in case of e g a program crash will not cause data corruption still it is recommended to always correctly close a database object after you are done with it syntax the database object to shut down duckdb_connect opens a connection to a database connections are required to query the database and store transactional state associated with the connection the instantiated connection should be closed using duckdb_disconnect syntax the database file to connect to out_connection the result connection object returns duckdbsuccess on success or duckdberror on failure duckdb_interrupt interrupt running query syntax the connection to interruot duckdb_query_progress get progress of the running query syntax the working connection returns -1 if no progress or a percentage of the progress duckdb_disconnect closes the specified connection and de-allocates all memory allocated for that connection syntax the connection to close duckdb_library_version returns the version of the linked duckdb with a version postfix for dev versions usually used for developing c extensions that must return this for a compatibility check syntax", "category": "C", "url": "/docs/api/c/connect", "blurb": "To use DuckDB, you must first initialize a duckdb_database handle using duckdb_open() . duckdb_open() takes as..." @@ -1087,10 +1087,10 @@ }, { "title": "Python Client API", - "text": "span class target id module-duckdb span p duckdb is an embeddable sql olap database management system p", + "text": "span class target id module-duckdb span dl class py data", "category": "Reference", "url": "/docs/api/python/reference/index", - "blurb": "

DuckDB is an embeddable SQL OLAP Database Management System

" + "blurb": "
" }, { "title": "Python DB API", diff --git a/docs/api/c/api.md b/docs/api/c/api.md index ece151e58ba..713afc2da49 100644 --- a/docs/api/c/api.md +++ b/docs/api/c/api.md @@ -10,6 +10,8 @@ selected: API Reference duckdb_state duckdb_open_ext(const char *path, duckdb_database *out_database, duckdb_config config, char **out_error); void duckdb_close(duckdb_database *database); duckdb_state duckdb_connect(duckdb_database database, duckdb_connection *out_connection); +void duckdb_interrupt(duckdb_connection connection); +double duckdb_query_progress(duckdb_connection connection); void duckdb_disconnect(duckdb_connection *connection); const char *duckdb_library_version(); @@ -397,6 +399,45 @@ The result connection object.
+### duckdb_interrupt +--- +Interrupt running query + +#### Syntax +--- +
void duckdb_interrupt(
+  duckdb_connection connection
+);
+
+#### Parameters +--- +* `connection` + +The connection to interruot + +
+ +### duckdb_query_progress +--- +Get progress of the running query + +#### Syntax +--- +
double duckdb_query_progress(
+  duckdb_connection connection
+);
+
+#### Parameters +--- +* `connection` + +The working connection +* `returns` + +-1 if no progress or a percentage of the progress + +
+ ### duckdb_disconnect --- Closes the specified connection and de-allocates all memory allocated for that connection. diff --git a/docs/api/c/connect.md b/docs/api/c/connect.md index 82d8e58deac..841452ebe25 100644 --- a/docs/api/c/connect.md +++ b/docs/api/c/connect.md @@ -33,6 +33,8 @@ duckdb_close(&db); duckdb_state duckdb_open_ext(const char *path, duckdb_database *out_database, duckdb_config config, char **out_error); void duckdb_close(duckdb_database *database); duckdb_state duckdb_connect(duckdb_database database, duckdb_connection *out_connection); +void duckdb_interrupt(duckdb_connection connection); +double duckdb_query_progress(duckdb_connection connection); void duckdb_disconnect(duckdb_connection *connection); const char *duckdb_library_version(); @@ -145,6 +147,45 @@ The result connection object.
+### duckdb_interrupt +--- +Interrupt running query + +#### Syntax +--- +
void duckdb_interrupt(
+  duckdb_connection connection
+);
+
+#### Parameters +--- +* `connection` + +The connection to interruot + +
+ +### duckdb_query_progress +--- +Get progress of the running query + +#### Syntax +--- +
double duckdb_query_progress(
+  duckdb_connection connection
+);
+
+#### Parameters +--- +* `connection` + +The working connection +* `returns` + +-1 if no progress or a percentage of the progress + +
+ ### duckdb_disconnect --- Closes the specified connection and de-allocates all memory allocated for that connection. diff --git a/docs/api/python/reference/index.md b/docs/api/python/reference/index.md index e4f6497f1f3..3e8e634d384 100644 --- a/docs/api/python/reference/index.md +++ b/docs/api/python/reference/index.md @@ -8,8 +8,7 @@ title: Python Client API
-

DuckDB is an embeddable SQL OLAP Database Management System

-
+
duckdb.threadsafety bool
@@ -50,7 +49,7 @@ title: Python Client API exception duckdb.BinderException
-

Bases: ProgrammingError

+

Bases: ProgrammingError

@@ -59,7 +58,7 @@ title: Python Client API exception duckdb.CastException
-

Bases: DataError

+

Bases: DataError

@@ -68,7 +67,7 @@ title: Python Client API exception duckdb.CatalogException
-

Bases: ProgrammingError

+

Bases: ProgrammingError

@@ -77,7 +76,7 @@ title: Python Client API exception duckdb.ConnectionException
-

Bases: OperationalError

+

Bases: OperationalError

@@ -86,7 +85,7 @@ title: Python Client API exception duckdb.ConstraintException
-

Bases: IntegrityError

+

Bases: IntegrityError

@@ -95,7 +94,7 @@ title: Python Client API exception duckdb.ConversionException
-

Bases: DataError

+

Bases: DataError

@@ -104,7 +103,7 @@ title: Python Client API exception duckdb.DataError
-

Bases: Error

+

Bases: Error

@@ -116,7 +115,7 @@ title: Python Client API

Bases: pybind11_object

-append(self: duckdb.DuckDBPyConnection, table_name: str, df: pandas.DataFrame, *, by_name: bool = False) → duckdb.DuckDBPyConnection +append(self: duckdb.duckdb.DuckDBPyConnection, table_name: str, df: pandas.DataFrame, *, by_name: bool = False) → duckdb.duckdb.DuckDBPyConnection

Append the passed DataFrame to the named table

@@ -125,7 +124,7 @@ title: Python Client API
-array_type(self: duckdb.DuckDBPyConnection, type: duckdb.typing.DuckDBPyType) → duckdb.typing.DuckDBPyType +array_type(self: duckdb.duckdb.DuckDBPyConnection, type: duckdb.duckdb.typing.DuckDBPyType) → duckdb.duckdb.typing.DuckDBPyType

Create an array type object of ‘type’

@@ -134,7 +133,7 @@ title: Python Client API
-arrow(self: duckdb.DuckDBPyConnection, rows_per_batch: int = 1000000) → pyarrow.lib.Table +arrow(self: duckdb.duckdb.DuckDBPyConnection, rows_per_batch: int = 1000000) → pyarrow.lib.Table

Fetch a result as Arrow table following execute()

@@ -143,7 +142,7 @@ title: Python Client API
-begin(self: duckdb.DuckDBPyConnection) → duckdb.DuckDBPyConnection +begin(self: duckdb.duckdb.DuckDBPyConnection) → duckdb.duckdb.DuckDBPyConnection

Start a new transaction

@@ -152,7 +151,7 @@ title: Python Client API
-close(self: duckdb.DuckDBPyConnection) → None +close(self: duckdb.duckdb.DuckDBPyConnection) → None

Close the connection

@@ -161,7 +160,7 @@ title: Python Client API
-commit(self: duckdb.DuckDBPyConnection) → duckdb.DuckDBPyConnection +commit(self: duckdb.duckdb.DuckDBPyConnection) → duckdb.duckdb.DuckDBPyConnection

Commit changes performed within a transaction

@@ -170,7 +169,7 @@ title: Python Client API
-create_function(self: duckdb.DuckDBPyConnection, name: str, function: function, return_type: object = None, parameters: duckdb.typing.DuckDBPyType = None, *, type: duckdb.functional.PythonUDFType = <PythonUDFType.NATIVE: 0>, null_handling: duckdb.functional.FunctionNullHandling = 0, exception_handling: duckdb.PythonExceptionHandling = 0, side_effects: bool = False) → duckdb.DuckDBPyConnection +create_function(self: duckdb.duckdb.DuckDBPyConnection, name: str, function: function, return_type: object = None, parameters: duckdb.duckdb.typing.DuckDBPyType = None, *, type: duckdb.duckdb.functional.PythonUDFType = <PythonUDFType.NATIVE: 0>, null_handling: duckdb.duckdb.functional.FunctionNullHandling = 0, exception_handling: duckdb.duckdb.PythonExceptionHandling = 0, side_effects: bool = False) → duckdb.duckdb.DuckDBPyConnection

Create a DuckDB function out of the passing in python function so it can be used in queries

@@ -179,7 +178,7 @@ title: Python Client API
-cursor(self: duckdb.DuckDBPyConnection) → duckdb.DuckDBPyConnection +cursor(self: duckdb.duckdb.DuckDBPyConnection) → duckdb.duckdb.DuckDBPyConnection

Create a duplicate of the current connection

@@ -188,7 +187,7 @@ title: Python Client API
-decimal_type(self: duckdb.DuckDBPyConnection, width: int, scale: int) → duckdb.typing.DuckDBPyType +decimal_type(self: duckdb.duckdb.DuckDBPyConnection, width: int, scale: int) → duckdb.duckdb.typing.DuckDBPyType

Create a decimal type with ‘width’ and ‘scale’

@@ -206,7 +205,7 @@ title: Python Client API
-df(self: duckdb.DuckDBPyConnection, *, date_as_object: bool = False) → pandas.DataFrame +df(self: duckdb.duckdb.DuckDBPyConnection, *, date_as_object: bool = False) → pandas.DataFrame

Fetch a result as DataFrame following execute()

@@ -215,7 +214,7 @@ title: Python Client API
-dtype(self: duckdb.DuckDBPyConnection, type_str: str) → duckdb.typing.DuckDBPyType +dtype(self: duckdb.duckdb.DuckDBPyConnection, type_str: str) → duckdb.duckdb.typing.DuckDBPyType

Create a type object by parsing the ‘type_str’ string

@@ -224,7 +223,7 @@ title: Python Client API
-duplicate(self: duckdb.DuckDBPyConnection) → duckdb.DuckDBPyConnection +duplicate(self: duckdb.duckdb.DuckDBPyConnection) → duckdb.duckdb.DuckDBPyConnection

Create a duplicate of the current connection

@@ -233,7 +232,7 @@ title: Python Client API
-enum_type(self: duckdb.DuckDBPyConnection, name: str, type: duckdb.typing.DuckDBPyType, values: list) → duckdb.typing.DuckDBPyType +enum_type(self: duckdb.duckdb.DuckDBPyConnection, name: str, type: duckdb.duckdb.typing.DuckDBPyType, values: list) → duckdb.duckdb.typing.DuckDBPyType

Create an enum type of underlying ‘type’, consisting of the list of ‘values’

@@ -242,7 +241,7 @@ title: Python Client API
-execute(self: duckdb.DuckDBPyConnection, query: str, parameters: object = None, multiple_parameter_sets: bool = False) → duckdb.DuckDBPyConnection +execute(self: duckdb.duckdb.DuckDBPyConnection, query: str, parameters: object = None, multiple_parameter_sets: bool = False) → duckdb.duckdb.DuckDBPyConnection

Execute the given SQL query, optionally using prepared statements with parameters set

@@ -251,7 +250,7 @@ title: Python Client API
-executemany(self: duckdb.DuckDBPyConnection, query: str, parameters: object = None) → duckdb.DuckDBPyConnection +executemany(self: duckdb.duckdb.DuckDBPyConnection, query: str, parameters: object = None) → duckdb.duckdb.DuckDBPyConnection

Execute the given prepared statement multiple times using the list of parameter sets in parameters

@@ -260,7 +259,7 @@ title: Python Client API
-fetch_arrow_table(self: duckdb.DuckDBPyConnection, rows_per_batch: int = 1000000) → pyarrow.lib.Table +fetch_arrow_table(self: duckdb.duckdb.DuckDBPyConnection, rows_per_batch: int = 1000000) → pyarrow.lib.Table

Fetch a result as Arrow table following execute()

@@ -269,7 +268,7 @@ title: Python Client API
-fetch_df(self: duckdb.DuckDBPyConnection, *, date_as_object: bool = False) → pandas.DataFrame +fetch_df(self: duckdb.duckdb.DuckDBPyConnection, *, date_as_object: bool = False) → pandas.DataFrame

Fetch a result as DataFrame following execute()

@@ -278,7 +277,7 @@ title: Python Client API
-fetch_df_chunk(self: duckdb.DuckDBPyConnection, vectors_per_chunk: int = 1, *, date_as_object: bool = False) → pandas.DataFrame +fetch_df_chunk(self: duckdb.duckdb.DuckDBPyConnection, vectors_per_chunk: int = 1, *, date_as_object: bool = False) → pandas.DataFrame

Fetch a chunk of the result as Data.Frame following execute()

@@ -287,7 +286,7 @@ title: Python Client API
-fetch_record_batch(self: duckdb.DuckDBPyConnection, rows_per_batch: int = 1000000) → pyarrow.lib.RecordBatchReader +fetch_record_batch(self: duckdb.duckdb.DuckDBPyConnection, rows_per_batch: int = 1000000) → pyarrow.lib.RecordBatchReader

Fetch an Arrow RecordBatchReader following execute()

@@ -296,7 +295,7 @@ title: Python Client API
-fetchall(self: duckdb.DuckDBPyConnection) → list +fetchall(self: duckdb.duckdb.DuckDBPyConnection) → list

Fetch all rows from a result following execute

@@ -305,7 +304,7 @@ title: Python Client API
-fetchdf(self: duckdb.DuckDBPyConnection, *, date_as_object: bool = False) → pandas.DataFrame +fetchdf(self: duckdb.duckdb.DuckDBPyConnection, *, date_as_object: bool = False) → pandas.DataFrame

Fetch a result as DataFrame following execute()

@@ -314,7 +313,7 @@ title: Python Client API
-fetchmany(self: duckdb.DuckDBPyConnection, size: int = 1) → list +fetchmany(self: duckdb.duckdb.DuckDBPyConnection, size: int = 1) → list

Fetch the next set of rows from a result following execute

@@ -323,7 +322,7 @@ title: Python Client API
-fetchnumpy(self: duckdb.DuckDBPyConnection) → dict +fetchnumpy(self: duckdb.duckdb.DuckDBPyConnection) → dict

Fetch a result as list of NumPy arrays following execute

@@ -332,7 +331,7 @@ title: Python Client API
-fetchone(self: duckdb.DuckDBPyConnection) → Optional[tuple] +fetchone(self: duckdb.duckdb.DuckDBPyConnection) → Optional[tuple]

Fetch a single row from a result following execute

@@ -341,7 +340,7 @@ title: Python Client API
-filesystem_is_registered(self: duckdb.DuckDBPyConnection, name: str) → bool +filesystem_is_registered(self: duckdb.duckdb.DuckDBPyConnection, name: str) → bool

Check if a filesystem with the provided name is currently registered

@@ -350,7 +349,7 @@ title: Python Client API
-from_arrow(self: duckdb.DuckDBPyConnection, arrow_object: object) → duckdb.DuckDBPyRelation +from_arrow(self: duckdb.duckdb.DuckDBPyConnection, arrow_object: object) → duckdb.duckdb.DuckDBPyRelation

Create a relation object from an Arrow object

@@ -359,7 +358,7 @@ title: Python Client API
-from_csv_auto(self: duckdb.DuckDBPyConnection, name: object, *, header: object = None, compression: object = None, sep: object = None, delimiter: object = None, dtype: object = None, na_values: object = None, skiprows: object = None, quotechar: object = None, escapechar: object = None, encoding: object = None, parallel: object = None, date_format: object = None, timestamp_format: object = None, sample_size: object = None, all_varchar: object = None, normalize_names: object = None, filename: object = None, null_padding: object = None) → duckdb.DuckDBPyRelation +from_csv_auto(self: duckdb.duckdb.DuckDBPyConnection, name: object, *, header: object = None, compression: object = None, sep: object = None, delimiter: object = None, dtype: object = None, na_values: object = None, skiprows: object = None, quotechar: object = None, escapechar: object = None, encoding: object = None, parallel: object = None, date_format: object = None, timestamp_format: object = None, sample_size: object = None, all_varchar: object = None, normalize_names: object = None, filename: object = None, null_padding: object = None) → duckdb.duckdb.DuckDBPyRelation

Create a relation object from the CSV file in ‘name’

@@ -368,7 +367,7 @@ title: Python Client API
-from_df(self: duckdb.DuckDBPyConnection, df: pandas.DataFrame = None) → duckdb.DuckDBPyRelation +from_df(self: duckdb.duckdb.DuckDBPyConnection, df: pandas.DataFrame = None) → duckdb.duckdb.DuckDBPyRelation

Create a relation object from the Data.Frame in df

@@ -382,11 +381,11 @@ title: Python Client API

Overloaded function.

    -

  1. from_parquet(self: duckdb.DuckDBPyConnection, file_glob: str, binary_as_string: bool = False, *, file_row_number: bool = False, filename: bool = False, hive_partitioning: bool = False, union_by_name: bool = False, compression: object = None) -> duckdb.DuckDBPyRelation

    2. +

  2. from_parquet(self: duckdb.duckdb.DuckDBPyConnection, file_glob: str, binary_as_string: bool = False, *, file_row_number: bool = False, filename: bool = False, hive_partitioning: bool = False, union_by_name: bool = False, compression: object = None) -> duckdb.duckdb.DuckDBPyRelation

Create a relation object from the Parquet files in file_glob

    -

  1. from_parquet(self: duckdb.DuckDBPyConnection, file_globs: List[str], binary_as_string: bool = False, *, file_row_number: bool = False, filename: bool = False, hive_partitioning: bool = False, union_by_name: bool = False, compression: object = None) -> duckdb.DuckDBPyRelation

    2. +

  2. from_parquet(self: duckdb.duckdb.DuckDBPyConnection, file_globs: List[str], binary_as_string: bool = False, *, file_row_number: bool = False, filename: bool = False, hive_partitioning: bool = False, union_by_name: bool = False, compression: object = None) -> duckdb.duckdb.DuckDBPyRelation

Create a relation object from the Parquet files in file_globs

@@ -394,7 +393,7 @@ title: Python Client API
-from_query(self: duckdb.DuckDBPyConnection, query: str, alias: str = '') → duckdb.DuckDBPyRelation +from_query(self: duckdb.duckdb.DuckDBPyConnection, query: str, alias: str = '') → duckdb.duckdb.DuckDBPyRelation

Run a SQL query. If it is a SELECT statement, create a relation object from the given SQL query, otherwise run the query as-is.

@@ -403,7 +402,7 @@ title: Python Client API
-from_substrait(self: duckdb.DuckDBPyConnection, proto: bytes) → duckdb.DuckDBPyRelation +from_substrait(self: duckdb.duckdb.DuckDBPyConnection, proto: bytes) → duckdb.duckdb.DuckDBPyRelation

Create a query object from protobuf plan

@@ -412,7 +411,7 @@ title: Python Client API
-from_substrait_json(self: duckdb.DuckDBPyConnection, json: str) → duckdb.DuckDBPyRelation +from_substrait_json(self: duckdb.duckdb.DuckDBPyConnection, json: str) → duckdb.duckdb.DuckDBPyRelation

Create a query object from a JSON protobuf plan

@@ -421,7 +420,7 @@ title: Python Client API
-get_substrait(self: duckdb.DuckDBPyConnection, query: str, *, enable_optimizer: bool = True) → duckdb.DuckDBPyRelation +get_substrait(self: duckdb.duckdb.DuckDBPyConnection, query: str, *, enable_optimizer: bool = True) → duckdb.duckdb.DuckDBPyRelation

Serialize a query to protobuf

@@ -430,7 +429,7 @@ title: Python Client API
-get_substrait_json(self: duckdb.DuckDBPyConnection, query: str, *, enable_optimizer: bool = True) → duckdb.DuckDBPyRelation +get_substrait_json(self: duckdb.duckdb.DuckDBPyConnection, query: str, *, enable_optimizer: bool = True) → duckdb.duckdb.DuckDBPyRelation

Serialize a query to protobuf on the JSON format

@@ -439,7 +438,7 @@ title: Python Client API
-get_table_names(self: duckdb.DuckDBPyConnection, query: str) → Set[str] +get_table_names(self: duckdb.duckdb.DuckDBPyConnection, query: str) → Set[str]

Extract the required table names from a query

@@ -448,7 +447,7 @@ title: Python Client API
-install_extension(self: duckdb.DuckDBPyConnection, extension: str, *, force_install: bool = False) → None +install_extension(self: duckdb.duckdb.DuckDBPyConnection, extension: str, *, force_install: bool = False) → None

Install an extension by name

@@ -457,7 +456,7 @@ title: Python Client API
-interrupt(self: duckdb.DuckDBPyConnection) → None +interrupt(self: duckdb.duckdb.DuckDBPyConnection) → None

Interrupt pending operations

@@ -466,7 +465,7 @@ title: Python Client API
-list_filesystems(self: duckdb.DuckDBPyConnection) → list +list_filesystems(self: duckdb.duckdb.DuckDBPyConnection) → list

List registered filesystems, including builtin ones

@@ -475,7 +474,7 @@ title: Python Client API
-list_type(self: duckdb.DuckDBPyConnection, type: duckdb.typing.DuckDBPyType) → duckdb.typing.DuckDBPyType +list_type(self: duckdb.duckdb.DuckDBPyConnection, type: duckdb.duckdb.typing.DuckDBPyType) → duckdb.duckdb.typing.DuckDBPyType

Create an array type object of ‘type’

@@ -484,7 +483,7 @@ title: Python Client API
-load_extension(self: duckdb.DuckDBPyConnection, extension: str) → None +load_extension(self: duckdb.duckdb.DuckDBPyConnection, extension: str) → None

Load an installed extension

@@ -493,7 +492,7 @@ title: Python Client API
-map_type(self: duckdb.DuckDBPyConnection, key: duckdb.typing.DuckDBPyType, value: duckdb.typing.DuckDBPyType) → duckdb.typing.DuckDBPyType +map_type(self: duckdb.duckdb.DuckDBPyConnection, key: duckdb.duckdb.typing.DuckDBPyType, value: duckdb.duckdb.typing.DuckDBPyType) → duckdb.duckdb.typing.DuckDBPyType

Create a map type object from ‘key_type’ and ‘value_type’

@@ -502,7 +501,7 @@ title: Python Client API
-pl(self: duckdb.DuckDBPyConnection, rows_per_batch: int = 1000000) → duckdb::PolarsDataFrame +pl(self: duckdb.duckdb.DuckDBPyConnection, rows_per_batch: int = 1000000) → duckdb::PolarsDataFrame

Fetch a result as Polars DataFrame following execute()

@@ -511,7 +510,7 @@ title: Python Client API
-query(self: duckdb.DuckDBPyConnection, query: str, alias: str = '') → duckdb.DuckDBPyRelation +query(self: duckdb.duckdb.DuckDBPyConnection, query: str, alias: str = '') → duckdb.duckdb.DuckDBPyRelation

Run a SQL query. If it is a SELECT statement, create a relation object from the given SQL query, otherwise run the query as-is.

@@ -520,7 +519,7 @@ title: Python Client API
-read_csv(self: duckdb.DuckDBPyConnection, name: object, *, header: object = None, compression: object = None, sep: object = None, delimiter: object = None, dtype: object = None, na_values: object = None, skiprows: object = None, quotechar: object = None, escapechar: object = None, encoding: object = None, parallel: object = None, date_format: object = None, timestamp_format: object = None, sample_size: object = None, all_varchar: object = None, normalize_names: object = None, filename: object = None, null_padding: object = None) → duckdb.DuckDBPyRelation +read_csv(self: duckdb.duckdb.DuckDBPyConnection, name: object, *, header: object = None, compression: object = None, sep: object = None, delimiter: object = None, dtype: object = None, na_values: object = None, skiprows: object = None, quotechar: object = None, escapechar: object = None, encoding: object = None, parallel: object = None, date_format: object = None, timestamp_format: object = None, sample_size: object = None, all_varchar: object = None, normalize_names: object = None, filename: object = None, null_padding: object = None) → duckdb.duckdb.DuckDBPyRelation

Create a relation object from the CSV file in ‘name’

@@ -529,7 +528,7 @@ title: Python Client API
-read_json(self: duckdb.DuckDBPyConnection, name: str, *, columns: Optional[object] = None, sample_size: Optional[object] = None, maximum_depth: Optional[object] = None, records: Optional[str] = None, format: Optional[str] = None) → duckdb.DuckDBPyRelation +read_json(self: duckdb.duckdb.DuckDBPyConnection, name: str, *, columns: Optional[object] = None, sample_size: Optional[object] = None, maximum_depth: Optional[object] = None, records: Optional[str] = None, format: Optional[str] = None) → duckdb.duckdb.DuckDBPyRelation

Create a relation object from the JSON file in ‘name’

@@ -543,11 +542,11 @@ title: Python Client API

Overloaded function.

    -

  1. read_parquet(self: duckdb.DuckDBPyConnection, file_glob: str, binary_as_string: bool = False, *, file_row_number: bool = False, filename: bool = False, hive_partitioning: bool = False, union_by_name: bool = False, compression: object = None) -> duckdb.DuckDBPyRelation

    2. +

  2. read_parquet(self: duckdb.duckdb.DuckDBPyConnection, file_glob: str, binary_as_string: bool = False, *, file_row_number: bool = False, filename: bool = False, hive_partitioning: bool = False, union_by_name: bool = False, compression: object = None) -> duckdb.duckdb.DuckDBPyRelation

Create a relation object from the Parquet files in file_glob

    -

  1. read_parquet(self: duckdb.DuckDBPyConnection, file_globs: List[str], binary_as_string: bool = False, *, file_row_number: bool = False, filename: bool = False, hive_partitioning: bool = False, union_by_name: bool = False, compression: object = None) -> duckdb.DuckDBPyRelation

    2. +

  2. read_parquet(self: duckdb.duckdb.DuckDBPyConnection, file_globs: List[str], binary_as_string: bool = False, *, file_row_number: bool = False, filename: bool = False, hive_partitioning: bool = False, union_by_name: bool = False, compression: object = None) -> duckdb.duckdb.DuckDBPyRelation

Create a relation object from the Parquet files in file_globs

@@ -555,7 +554,7 @@ title: Python Client API
-register(self: duckdb.DuckDBPyConnection, view_name: str, python_object: object) → duckdb.DuckDBPyConnection +register(self: duckdb.duckdb.DuckDBPyConnection, view_name: str, python_object: object) → duckdb.duckdb.DuckDBPyConnection

Register the passed Python Object value for querying with a view

@@ -564,7 +563,7 @@ title: Python Client API
-register_filesystem(self: duckdb.DuckDBPyConnection, filesystem: fsspec.AbstractFileSystem) → None +register_filesystem(self: duckdb.duckdb.DuckDBPyConnection, filesystem: fsspec.AbstractFileSystem) → None

Register a fsspec compliant filesystem

@@ -573,7 +572,7 @@ title: Python Client API
-remove_function(self: duckdb.DuckDBPyConnection, name: str) → duckdb.DuckDBPyConnection +remove_function(self: duckdb.duckdb.DuckDBPyConnection, name: str) → duckdb.duckdb.DuckDBPyConnection

Remove a previously created function

@@ -582,7 +581,7 @@ title: Python Client API
-rollback(self: duckdb.DuckDBPyConnection) → duckdb.DuckDBPyConnection +rollback(self: duckdb.duckdb.DuckDBPyConnection) → duckdb.duckdb.DuckDBPyConnection

Roll back changes performed within a transaction

@@ -591,7 +590,7 @@ title: Python Client API
-row_type(self: duckdb.DuckDBPyConnection, fields: object) → duckdb.typing.DuckDBPyType +row_type(self: duckdb.duckdb.DuckDBPyConnection, fields: object) → duckdb.duckdb.typing.DuckDBPyType

Create a struct type object from ‘fields’

@@ -600,7 +599,7 @@ title: Python Client API
-sql(self: duckdb.DuckDBPyConnection, query: str, alias: str = '') → duckdb.DuckDBPyRelation +sql(self: duckdb.duckdb.DuckDBPyConnection, query: str, alias: str = '') → duckdb.duckdb.DuckDBPyRelation

Run a SQL query. If it is a SELECT statement, create a relation object from the given SQL query, otherwise run the query as-is.

@@ -609,7 +608,7 @@ title: Python Client API
-sqltype(self: duckdb.DuckDBPyConnection, type_str: str) → duckdb.typing.DuckDBPyType +sqltype(self: duckdb.duckdb.DuckDBPyConnection, type_str: str) → duckdb.duckdb.typing.DuckDBPyType

Create a type object by parsing the ‘type_str’ string

@@ -618,7 +617,7 @@ title: Python Client API
-string_type(self: duckdb.DuckDBPyConnection, collation: str = '') → duckdb.typing.DuckDBPyType +string_type(self: duckdb.duckdb.DuckDBPyConnection, collation: str = '') → duckdb.duckdb.typing.DuckDBPyType

Create a string type with an optional collation

@@ -627,7 +626,7 @@ title: Python Client API
-struct_type(self: duckdb.DuckDBPyConnection, fields: object) → duckdb.typing.DuckDBPyType +struct_type(self: duckdb.duckdb.DuckDBPyConnection, fields: object) → duckdb.duckdb.typing.DuckDBPyType

Create a struct type object from ‘fields’

@@ -636,7 +635,7 @@ title: Python Client API
-table(self: duckdb.DuckDBPyConnection, table_name: str) → duckdb.DuckDBPyRelation +table(self: duckdb.duckdb.DuckDBPyConnection, table_name: str) → duckdb.duckdb.DuckDBPyRelation

Create a relation object for the name’d table

@@ -645,7 +644,7 @@ title: Python Client API
-table_function(self: duckdb.DuckDBPyConnection, name: str, parameters: object = None) → duckdb.DuckDBPyRelation +table_function(self: duckdb.duckdb.DuckDBPyConnection, name: str, parameters: object = None) → duckdb.duckdb.DuckDBPyRelation

Create a relation object from the name’d table function with given parameters

@@ -654,7 +653,7 @@ title: Python Client API
-tf(self: duckdb.DuckDBPyConnection) → dict +tf(self: duckdb.duckdb.DuckDBPyConnection) → dict

Fetch a result as dict of TensorFlow Tensors following execute()

@@ -663,7 +662,7 @@ title: Python Client API
-torch(self: duckdb.DuckDBPyConnection) → dict +torch(self: duckdb.duckdb.DuckDBPyConnection) → dict

Fetch a result as dict of PyTorch Tensors following execute()

@@ -672,7 +671,7 @@ title: Python Client API
-type(self: duckdb.DuckDBPyConnection, type_str: str) → duckdb.typing.DuckDBPyType +type(self: duckdb.duckdb.DuckDBPyConnection, type_str: str) → duckdb.duckdb.typing.DuckDBPyType

Create a type object by parsing the ‘type_str’ string

@@ -681,7 +680,7 @@ title: Python Client API
-union_type(self: duckdb.DuckDBPyConnection, members: object) → duckdb.typing.DuckDBPyType +union_type(self: duckdb.duckdb.DuckDBPyConnection, members: object) → duckdb.duckdb.typing.DuckDBPyType

Create a union type object from ‘members’

@@ -690,7 +689,7 @@ title: Python Client API
-unregister(self: duckdb.DuckDBPyConnection, view_name: str) → duckdb.DuckDBPyConnection +unregister(self: duckdb.duckdb.DuckDBPyConnection, view_name: str) → duckdb.duckdb.DuckDBPyConnection

Unregister the view name

@@ -699,7 +698,7 @@ title: Python Client API
-unregister_filesystem(self: duckdb.DuckDBPyConnection, name: str) → None +unregister_filesystem(self: duckdb.duckdb.DuckDBPyConnection, name: str) → None

Unregister a filesystem

@@ -708,7 +707,7 @@ title: Python Client API
-values(self: duckdb.DuckDBPyConnection, values: object) → duckdb.DuckDBPyRelation +values(self: duckdb.duckdb.DuckDBPyConnection, values: object) → duckdb.duckdb.DuckDBPyRelation

Create a relation object from the passed values

@@ -717,7 +716,7 @@ title: Python Client API
-view(self: duckdb.DuckDBPyConnection, view_name: str) → duckdb.DuckDBPyRelation +view(self: duckdb.duckdb.DuckDBPyConnection, view_name: str) → duckdb.duckdb.DuckDBPyRelation

Create a relation object for the name’d view

@@ -735,7 +734,7 @@ title: Python Client API

Bases: pybind11_object

-abs(self: duckdb.DuckDBPyRelation, aggregation_columns: str) → duckdb.DuckDBPyRelation +abs(self: duckdb.duckdb.DuckDBPyRelation, aggregation_columns: str) → duckdb.duckdb.DuckDBPyRelation

Returns the absolute value for the specified columns.

@@ -744,7 +743,7 @@ title: Python Client API
-aggregate(self: duckdb.DuckDBPyRelation, aggr_expr: str, group_expr: str = '') → duckdb.DuckDBPyRelation +aggregate(self: duckdb.duckdb.DuckDBPyRelation, aggr_expr: str, group_expr: str = '') → duckdb.duckdb.DuckDBPyRelation

Compute the aggregate aggr_expr by the optional groups group_expr on the relation

@@ -762,7 +761,7 @@ title: Python Client API
-apply(self: duckdb.DuckDBPyRelation, function_name: str, function_aggr: str, group_expr: str = '', function_parameter: str = '', projected_columns: str = '') → duckdb.DuckDBPyRelation +apply(self: duckdb.duckdb.DuckDBPyRelation, function_name: str, function_aggr: str, group_expr: str = '', function_parameter: str = '', projected_columns: str = '') → duckdb.duckdb.DuckDBPyRelation

Compute the function of a single column or a list of columns by the optional groups on the relation

@@ -771,7 +770,7 @@ title: Python Client API
-arrow(self: duckdb.DuckDBPyRelation, batch_size: int = 1000000) → pyarrow.lib.Table +arrow(self: duckdb.duckdb.DuckDBPyRelation, batch_size: int = 1000000) → pyarrow.lib.Table

Execute and fetch all rows as an Arrow Table

@@ -780,7 +779,7 @@ title: Python Client API
-close(self: duckdb.DuckDBPyRelation) → None +close(self: duckdb.duckdb.DuckDBPyRelation) → None

Closes the result

@@ -798,7 +797,7 @@ title: Python Client API
-count(self: duckdb.DuckDBPyRelation, count_aggr: str, group_expr: str = '') → duckdb.DuckDBPyRelation +count(self: duckdb.duckdb.DuckDBPyRelation, count_aggr: str, group_expr: str = '') → duckdb.duckdb.DuckDBPyRelation

Compute the aggregate count of a single column or a list of columns by the optional groups on the relation

@@ -807,7 +806,7 @@ title: Python Client API
-create(self: duckdb.DuckDBPyRelation, table_name: str) → None +create(self: duckdb.duckdb.DuckDBPyRelation, table_name: str) → None

Creates a new table named table_name with the contents of the relation object

@@ -816,7 +815,7 @@ title: Python Client API
-create_view(self: duckdb.DuckDBPyRelation, view_name: str, replace: bool = True) → duckdb.DuckDBPyRelation +create_view(self: duckdb.duckdb.DuckDBPyRelation, view_name: str, replace: bool = True) → duckdb.duckdb.DuckDBPyRelation

Creates a view named view_name that refers to the relation object

@@ -825,7 +824,7 @@ title: Python Client API
-cummax(self: duckdb.DuckDBPyRelation, aggregation_columns: str) → duckdb.DuckDBPyRelation +cummax(self: duckdb.duckdb.DuckDBPyRelation, aggregation_columns: str) → duckdb.duckdb.DuckDBPyRelation

Returns the cumulative maximum of the aggregate column.

@@ -834,7 +833,7 @@ title: Python Client API
-cummin(self: duckdb.DuckDBPyRelation, aggregation_columns: str) → duckdb.DuckDBPyRelation +cummin(self: duckdb.duckdb.DuckDBPyRelation, aggregation_columns: str) → duckdb.duckdb.DuckDBPyRelation

Returns the cumulative minimum of the aggregate column.

@@ -843,7 +842,7 @@ title: Python Client API
-cumprod(self: duckdb.DuckDBPyRelation, aggregation_columns: str) → duckdb.DuckDBPyRelation +cumprod(self: duckdb.duckdb.DuckDBPyRelation, aggregation_columns: str) → duckdb.duckdb.DuckDBPyRelation

Returns the cumulative product of the aggregate column.

@@ -852,7 +851,7 @@ title: Python Client API
-cumsum(self: duckdb.DuckDBPyRelation, aggregation_columns: str) → duckdb.DuckDBPyRelation +cumsum(self: duckdb.duckdb.DuckDBPyRelation, aggregation_columns: str) → duckdb.duckdb.DuckDBPyRelation

Returns the cumulative sum of the aggregate column.

@@ -861,7 +860,7 @@ title: Python Client API
-describe(self: duckdb.DuckDBPyRelation) → duckdb.DuckDBPyRelation +describe(self: duckdb.duckdb.DuckDBPyRelation) → duckdb.duckdb.DuckDBPyRelation

Gives basic statistics (e.g., min,max) and if null exists for each column of the relation.

@@ -879,7 +878,7 @@ title: Python Client API
-df(self: duckdb.DuckDBPyRelation, *, date_as_object: bool = False) → pandas.DataFrame +df(self: duckdb.duckdb.DuckDBPyRelation, *, date_as_object: bool = False) → pandas.DataFrame

Execute and fetch all rows as a pandas DataFrame

@@ -888,7 +887,7 @@ title: Python Client API
-distinct(self: duckdb.DuckDBPyRelation) → duckdb.DuckDBPyRelation +distinct(self: duckdb.duckdb.DuckDBPyRelation) → duckdb.duckdb.DuckDBPyRelation

Retrieve distinct rows from this relation object

@@ -906,7 +905,7 @@ title: Python Client API
-except_(self: duckdb.DuckDBPyRelation, other_rel: duckdb.DuckDBPyRelation) → duckdb.DuckDBPyRelation +except_(self: duckdb.duckdb.DuckDBPyRelation, other_rel: duckdb.duckdb.DuckDBPyRelation) → duckdb.duckdb.DuckDBPyRelation

Create the set except of this relation object with another relation object in other_rel

@@ -915,7 +914,7 @@ title: Python Client API
-execute(self: duckdb.DuckDBPyRelation) → duckdb.DuckDBPyRelation +execute(self: duckdb.duckdb.DuckDBPyRelation) → duckdb.duckdb.DuckDBPyRelation

Transform the relation into a result set

@@ -924,14 +923,14 @@ title: Python Client API
-explain(self: duckdb.DuckDBPyRelation, type: duckdb.ExplainType = 'standard') → str +explain(self: duckdb.duckdb.DuckDBPyRelation, type: duckdb.duckdb.ExplainType = 'standard') → str
-fetch_arrow_reader(self: duckdb.DuckDBPyRelation, batch_size: int = 1000000) → pyarrow.lib.RecordBatchReader +fetch_arrow_reader(self: duckdb.duckdb.DuckDBPyRelation, batch_size: int = 1000000) → pyarrow.lib.RecordBatchReader

Execute and return an Arrow Record Batch Reader that yields all rows

@@ -940,7 +939,7 @@ title: Python Client API
-fetch_arrow_table(self: duckdb.DuckDBPyRelation, batch_size: int = 1000000) → pyarrow.lib.Table +fetch_arrow_table(self: duckdb.duckdb.DuckDBPyRelation, batch_size: int = 1000000) → pyarrow.lib.Table

Execute and fetch all rows as an Arrow Table

@@ -949,7 +948,7 @@ title: Python Client API
-fetchall(self: duckdb.DuckDBPyRelation) → list +fetchall(self: duckdb.duckdb.DuckDBPyRelation) → list

Execute and fetch all rows as a list of tuples

@@ -958,7 +957,7 @@ title: Python Client API
-fetchdf(self: duckdb.DuckDBPyRelation, *, date_as_object: bool = False) → pandas.DataFrame +fetchdf(self: duckdb.duckdb.DuckDBPyRelation, *, date_as_object: bool = False) → pandas.DataFrame

Execute and fetch all rows as a pandas DataFrame

@@ -967,7 +966,7 @@ title: Python Client API
-fetchmany(self: duckdb.DuckDBPyRelation, size: int = 1) → list +fetchmany(self: duckdb.duckdb.DuckDBPyRelation, size: int = 1) → list

Execute and fetch the next set of rows as a list of tuples

@@ -976,7 +975,7 @@ title: Python Client API
-fetchnumpy(self: duckdb.DuckDBPyRelation) → dict +fetchnumpy(self: duckdb.duckdb.DuckDBPyRelation) → dict

Execute and fetch all rows as a Python dict mapping each column to one numpy arrays

@@ -985,7 +984,7 @@ title: Python Client API
-fetchone(self: duckdb.DuckDBPyRelation) → Optional[tuple] +fetchone(self: duckdb.duckdb.DuckDBPyRelation) → Optional[tuple]

Execute and fetch a single row as a tuple

@@ -994,7 +993,7 @@ title: Python Client API
-filter(self: duckdb.DuckDBPyRelation, filter_expr: str) → duckdb.DuckDBPyRelation +filter(self: duckdb.duckdb.DuckDBPyRelation, filter_expr: str) → duckdb.duckdb.DuckDBPyRelation

Filter the relation object by the filter in filter_expr

@@ -1003,7 +1002,7 @@ title: Python Client API
-insert(self: duckdb.DuckDBPyRelation, values: object) → None +insert(self: duckdb.duckdb.DuckDBPyRelation, values: object) → None

Inserts the given values into the relation

@@ -1012,7 +1011,7 @@ title: Python Client API
-insert_into(self: duckdb.DuckDBPyRelation, table_name: str) → None +insert_into(self: duckdb.duckdb.DuckDBPyRelation, table_name: str) → None

Inserts the relation object into an existing table named table_name

@@ -1021,7 +1020,7 @@ title: Python Client API
-intersect(self: duckdb.DuckDBPyRelation, other_rel: duckdb.DuckDBPyRelation) → duckdb.DuckDBPyRelation +intersect(self: duckdb.duckdb.DuckDBPyRelation, other_rel: duckdb.duckdb.DuckDBPyRelation) → duckdb.duckdb.DuckDBPyRelation

Create the set intersection of this relation object with another relation object in other_rel

@@ -1030,7 +1029,7 @@ title: Python Client API
-join(self: duckdb.DuckDBPyRelation, other_rel: duckdb.DuckDBPyRelation, condition: str, how: str = 'inner') → duckdb.DuckDBPyRelation +join(self: duckdb.duckdb.DuckDBPyRelation, other_rel: duckdb.duckdb.DuckDBPyRelation, condition: str, how: str = 'inner') → duckdb.duckdb.DuckDBPyRelation

Join the relation object with another relation object in other_rel using the join condition expression in join_condition. Types supported are ‘inner’ and ‘left’

@@ -1039,7 +1038,7 @@ title: Python Client API
-kurt(self: duckdb.DuckDBPyRelation, aggregation_columns: str, group_columns: str = '') → duckdb.DuckDBPyRelation +kurt(self: duckdb.duckdb.DuckDBPyRelation, aggregation_columns: str, group_columns: str = '') → duckdb.duckdb.DuckDBPyRelation

Returns the excess kurtosis of the aggregate column.

@@ -1048,7 +1047,7 @@ title: Python Client API
-limit(self: duckdb.DuckDBPyRelation, n: int, offset: int = 0) → duckdb.DuckDBPyRelation +limit(self: duckdb.duckdb.DuckDBPyRelation, n: int, offset: int = 0) → duckdb.duckdb.DuckDBPyRelation

Only retrieve the first n rows from this relation object, starting at offset

@@ -1057,7 +1056,7 @@ title: Python Client API
-mad(self: duckdb.DuckDBPyRelation, aggregation_columns: str, group_columns: str = '') → duckdb.DuckDBPyRelation +mad(self: duckdb.duckdb.DuckDBPyRelation, aggregation_columns: str, group_columns: str = '') → duckdb.duckdb.DuckDBPyRelation

Returns the median absolute deviation for the aggregate columns. NULL values are ignored. Temporal types return a positive INTERVAL.

@@ -1066,7 +1065,7 @@ title: Python Client API
-map(self: duckdb.DuckDBPyRelation, map_function: function, *, schema: Optional[object] = None) → duckdb.DuckDBPyRelation +map(self: duckdb.duckdb.DuckDBPyRelation, map_function: function, *, schema: Optional[object] = None) → duckdb.duckdb.DuckDBPyRelation

Calls the passed function on the relation

@@ -1075,7 +1074,7 @@ title: Python Client API
-max(self: duckdb.DuckDBPyRelation, max_aggr: str, group_expr: str = '') → duckdb.DuckDBPyRelation +max(self: duckdb.duckdb.DuckDBPyRelation, max_aggr: str, group_expr: str = '') → duckdb.duckdb.DuckDBPyRelation

Compute the aggregate max of a single column or a list of columns by the optional groups on the relation

@@ -1084,7 +1083,7 @@ title: Python Client API
-mean(self: duckdb.DuckDBPyRelation, mean_aggr: str, group_expr: str = '') → duckdb.DuckDBPyRelation +mean(self: duckdb.duckdb.DuckDBPyRelation, mean_aggr: str, group_expr: str = '') → duckdb.duckdb.DuckDBPyRelation

Compute the aggregate mean of a single column or a list of columns by the optional groups on the relation

@@ -1093,7 +1092,7 @@ title: Python Client API
-median(self: duckdb.DuckDBPyRelation, median_aggr: str, group_expr: str = '') → duckdb.DuckDBPyRelation +median(self: duckdb.duckdb.DuckDBPyRelation, median_aggr: str, group_expr: str = '') → duckdb.duckdb.DuckDBPyRelation

Compute the aggregate median of a single column or a list of columns by the optional groups on the relation

@@ -1102,7 +1101,7 @@ title: Python Client API
-min(self: duckdb.DuckDBPyRelation, min_aggr: str, group_expr: str = '') → duckdb.DuckDBPyRelation +min(self: duckdb.duckdb.DuckDBPyRelation, min_aggr: str, group_expr: str = '') → duckdb.duckdb.DuckDBPyRelation

Compute the aggregate min of a single column or a list of columns by the optional groups on the relation

@@ -1111,7 +1110,7 @@ title: Python Client API
-mode(self: duckdb.DuckDBPyRelation, aggregation_columns: str, group_columns: str = '') → duckdb.DuckDBPyRelation +mode(self: duckdb.duckdb.DuckDBPyRelation, aggregation_columns: str, group_columns: str = '') → duckdb.duckdb.DuckDBPyRelation

Returns the most frequent value for the aggregate columns. NULL values are ignored.

@@ -1120,7 +1119,7 @@ title: Python Client API
-order(self: duckdb.DuckDBPyRelation, order_expr: str) → duckdb.DuckDBPyRelation +order(self: duckdb.duckdb.DuckDBPyRelation, order_expr: str) → duckdb.duckdb.DuckDBPyRelation

Reorder the relation object by order_expr

@@ -1129,7 +1128,7 @@ title: Python Client API
-pl(self: duckdb.DuckDBPyRelation, batch_size: int = 1000000) → duckdb::PolarsDataFrame +pl(self: duckdb.duckdb.DuckDBPyRelation, batch_size: int = 1000000) → duckdb::PolarsDataFrame

Execute and fetch all rows as a Polars DataFrame

@@ -1138,7 +1137,7 @@ title: Python Client API
-prod(self: duckdb.DuckDBPyRelation, aggregation_columns: str, group_columns: str = '') → duckdb.DuckDBPyRelation +prod(self: duckdb.duckdb.DuckDBPyRelation, aggregation_columns: str, group_columns: str = '') → duckdb.duckdb.DuckDBPyRelation

Calculates the product of the aggregate column.

@@ -1147,7 +1146,7 @@ title: Python Client API
-project(self: duckdb.DuckDBPyRelation, project_expr: str) → duckdb.DuckDBPyRelation +project(self: duckdb.duckdb.DuckDBPyRelation, project_expr: str) → duckdb.duckdb.DuckDBPyRelation

Project the relation object by the projection in project_expr

@@ -1156,7 +1155,7 @@ title: Python Client API
-quantile(self: duckdb.DuckDBPyRelation, q: str, quantile_aggr: str, group_expr: str = '') → duckdb.DuckDBPyRelation +quantile(self: duckdb.duckdb.DuckDBPyRelation, q: str, quantile_aggr: str, group_expr: str = '') → duckdb.duckdb.DuckDBPyRelation

Compute the quantile of a single column or a list of columns by the optional groups on the relation

@@ -1165,7 +1164,7 @@ title: Python Client API
-query(self: duckdb.DuckDBPyRelation, virtual_table_name: str, sql_query: str) → duckdb.DuckDBPyRelation +query(self: duckdb.duckdb.DuckDBPyRelation, virtual_table_name: str, sql_query: str) → duckdb.duckdb.DuckDBPyRelation

Run the given SQL query in sql_query on the view named virtual_table_name that refers to the relation object

@@ -1174,7 +1173,7 @@ title: Python Client API
-record_batch(self: duckdb.DuckDBPyRelation, batch_size: int = 1000000) → pyarrow.lib.RecordBatchReader +record_batch(self: duckdb.duckdb.DuckDBPyRelation, batch_size: int = 1000000) → pyarrow.lib.RecordBatchReader

Execute and return an Arrow Record Batch Reader that yields all rows

@@ -1183,7 +1182,7 @@ title: Python Client API
-select_dtypes(self: duckdb.DuckDBPyRelation, types: object) → duckdb.DuckDBPyRelation +select_dtypes(self: duckdb.duckdb.DuckDBPyRelation, types: object) → duckdb.duckdb.DuckDBPyRelation

Select columns from the relation, by filtering based on type(s)

@@ -1192,7 +1191,7 @@ title: Python Client API
-select_types(self: duckdb.DuckDBPyRelation, types: object) → duckdb.DuckDBPyRelation +select_types(self: duckdb.duckdb.DuckDBPyRelation, types: object) → duckdb.duckdb.DuckDBPyRelation

Select columns from the relation, by filtering based on type(s)

@@ -1201,7 +1200,7 @@ title: Python Client API
-sem(self: duckdb.DuckDBPyRelation, aggregation_columns: str, group_columns: str = '') → duckdb.DuckDBPyRelation +sem(self: duckdb.duckdb.DuckDBPyRelation, aggregation_columns: str, group_columns: str = '') → duckdb.duckdb.DuckDBPyRelation

Returns the standard error of the mean of the aggregate column.

@@ -1210,7 +1209,7 @@ title: Python Client API
-set_alias(self: duckdb.DuckDBPyRelation, alias: str) → duckdb.DuckDBPyRelation +set_alias(self: duckdb.duckdb.DuckDBPyRelation, alias: str) → duckdb.duckdb.DuckDBPyRelation

Rename the relation object to new alias

@@ -1228,7 +1227,7 @@ title: Python Client API
-show(self: duckdb.DuckDBPyRelation) → None +show(self: duckdb.duckdb.DuckDBPyRelation) → None

Display a summary of the data

@@ -1237,7 +1236,7 @@ title: Python Client API
-skew(self: duckdb.DuckDBPyRelation, aggregation_columns: str, group_columns: str = '') → duckdb.DuckDBPyRelation +skew(self: duckdb.duckdb.DuckDBPyRelation, aggregation_columns: str, group_columns: str = '') → duckdb.duckdb.DuckDBPyRelation

Returns the skewness of the aggregate column.

@@ -1246,7 +1245,7 @@ title: Python Client API
-sql_query(self: duckdb.DuckDBPyRelation) → str +sql_query(self: duckdb.duckdb.DuckDBPyRelation) → str

Get the SQL query that is equivalent to the relation

@@ -1255,7 +1254,7 @@ title: Python Client API
-std(self: duckdb.DuckDBPyRelation, std_aggr: str, group_expr: str = '') → duckdb.DuckDBPyRelation +std(self: duckdb.duckdb.DuckDBPyRelation, std_aggr: str, group_expr: str = '') → duckdb.duckdb.DuckDBPyRelation

Compute the standard deviation of a single column or a list of columns by the optional groups on the relation

@@ -1264,7 +1263,7 @@ title: Python Client API
-sum(self: duckdb.DuckDBPyRelation, sum_aggr: str, group_expr: str = '') → duckdb.DuckDBPyRelation +sum(self: duckdb.duckdb.DuckDBPyRelation, sum_aggr: str, group_expr: str = '') → duckdb.duckdb.DuckDBPyRelation

Compute the aggregate sum of a single column or a list of columns by the optional groups on the relation

@@ -1273,7 +1272,7 @@ title: Python Client API
-tf(self: duckdb.DuckDBPyRelation) → dict +tf(self: duckdb.duckdb.DuckDBPyRelation) → dict

Fetch a result as dict of TensorFlow Tensors

@@ -1282,7 +1281,7 @@ title: Python Client API
-to_arrow_table(self: duckdb.DuckDBPyRelation, batch_size: int = 1000000) → pyarrow.lib.Table +to_arrow_table(self: duckdb.duckdb.DuckDBPyRelation, batch_size: int = 1000000) → pyarrow.lib.Table

Execute and fetch all rows as an Arrow Table

@@ -1291,7 +1290,7 @@ title: Python Client API
-to_csv(self: duckdb.DuckDBPyRelation, file_name: str, *, sep: object = None, na_rep: object = None, header: object = None, quotechar: object = None, escapechar: object = None, date_format: object = None, timestamp_format: object = None, quoting: object = None, encoding: object = None, compression: object = None) → None +to_csv(self: duckdb.duckdb.DuckDBPyRelation, file_name: str, *, sep: object = None, na_rep: object = None, header: object = None, quotechar: object = None, escapechar: object = None, date_format: object = None, timestamp_format: object = None, quoting: object = None, encoding: object = None, compression: object = None) → None

Write the relation object to a CSV file in ‘file_name’

@@ -1300,7 +1299,7 @@ title: Python Client API
-to_df(self: duckdb.DuckDBPyRelation, *, date_as_object: bool = False) → pandas.DataFrame +to_df(self: duckdb.duckdb.DuckDBPyRelation, *, date_as_object: bool = False) → pandas.DataFrame

Execute and fetch all rows as a pandas DataFrame

@@ -1309,7 +1308,7 @@ title: Python Client API
-to_parquet(self: duckdb.DuckDBPyRelation, file_name: str, *, compression: object = None) → None +to_parquet(self: duckdb.duckdb.DuckDBPyRelation, file_name: str, *, compression: object = None) → None

Write the relation object to a Parquet file in ‘file_name’

@@ -1318,7 +1317,7 @@ title: Python Client API
-to_table(self: duckdb.DuckDBPyRelation, table_name: str) → None +to_table(self: duckdb.duckdb.DuckDBPyRelation, table_name: str) → None

Creates a new table named table_name with the contents of the relation object

@@ -1327,7 +1326,7 @@ title: Python Client API
-to_view(self: duckdb.DuckDBPyRelation, view_name: str, replace: bool = True) → duckdb.DuckDBPyRelation +to_view(self: duckdb.duckdb.DuckDBPyRelation, view_name: str, replace: bool = True) → duckdb.duckdb.DuckDBPyRelation

Creates a view named view_name that refers to the relation object

@@ -1336,7 +1335,7 @@ title: Python Client API
-torch(self: duckdb.DuckDBPyRelation) → dict +torch(self: duckdb.duckdb.DuckDBPyRelation) → dict

Fetch a result as dict of PyTorch Tensors

@@ -1363,7 +1362,7 @@ title: Python Client API
-union(self: duckdb.DuckDBPyRelation, union_rel: duckdb.DuckDBPyRelation) → duckdb.DuckDBPyRelation +union(self: duckdb.duckdb.DuckDBPyRelation, union_rel: duckdb.duckdb.DuckDBPyRelation) → duckdb.duckdb.DuckDBPyRelation

Create the set union of this relation object with another relation object in other_rel

@@ -1372,7 +1371,7 @@ title: Python Client API
-unique(self: duckdb.DuckDBPyRelation, unique_aggr: str) → duckdb.DuckDBPyRelation +unique(self: duckdb.duckdb.DuckDBPyRelation, unique_aggr: str) → duckdb.duckdb.DuckDBPyRelation

Number of distinct values in a column.

@@ -1381,7 +1380,7 @@ title: Python Client API
-value_counts(self: duckdb.DuckDBPyRelation, value_counts_aggr: str, group_expr: str = '') → duckdb.DuckDBPyRelation +value_counts(self: duckdb.duckdb.DuckDBPyRelation, value_counts_aggr: str, group_expr: str = '') → duckdb.duckdb.DuckDBPyRelation

Count number of rows with each unique value of variable

@@ -1390,7 +1389,7 @@ title: Python Client API
-var(self: duckdb.DuckDBPyRelation, var_aggr: str, group_expr: str = '') → duckdb.DuckDBPyRelation +var(self: duckdb.duckdb.DuckDBPyRelation, var_aggr: str, group_expr: str = '') → duckdb.duckdb.DuckDBPyRelation

Compute the variance of a single column or a list of columns by the optional groups on the relation

@@ -1399,7 +1398,7 @@ title: Python Client API
-write_csv(self: duckdb.DuckDBPyRelation, file_name: str, *, sep: object = None, na_rep: object = None, header: object = None, quotechar: object = None, escapechar: object = None, date_format: object = None, timestamp_format: object = None, quoting: object = None, encoding: object = None, compression: object = None) → None +write_csv(self: duckdb.duckdb.DuckDBPyRelation, file_name: str, *, sep: object = None, na_rep: object = None, header: object = None, quotechar: object = None, escapechar: object = None, date_format: object = None, timestamp_format: object = None, quoting: object = None, encoding: object = None, compression: object = None) → None

Write the relation object to a CSV file in ‘file_name’

@@ -1408,7 +1407,7 @@ title: Python Client API
-write_parquet(self: duckdb.DuckDBPyRelation, file_name: str, *, compression: object = None) → None +write_parquet(self: duckdb.duckdb.DuckDBPyRelation, file_name: str, *, compression: object = None) → None

Write the relation object to a Parquet file in ‘file_name’

@@ -1472,7 +1471,7 @@ title: Python Client API exception duckdb.FatalException
-

Bases: Error

+

Bases: Error

@@ -1481,7 +1480,7 @@ title: Python Client API exception duckdb.HTTPException
-

Bases: IOException

+

Bases: IOException

Thrown when an error occurs in the httpfs extension, or whilst downloading an extension.

@@ -1519,7 +1518,7 @@ title: Python Client API exception duckdb.IOException
-

Bases: OperationalError

+

Bases: OperationalError

@@ -1528,7 +1527,7 @@ title: Python Client API exception duckdb.IntegrityError
-

Bases: Error

+

Bases: Error

@@ -1537,7 +1536,7 @@ title: Python Client API exception duckdb.InternalError
-

Bases: Error

+

Bases: Error

@@ -1546,7 +1545,7 @@ title: Python Client API exception duckdb.InternalException
-

Bases: InternalError

+

Bases: InternalError

@@ -1555,7 +1554,7 @@ title: Python Client API exception duckdb.InterruptException
-

Bases: Error

+

Bases: Error

@@ -1564,7 +1563,7 @@ title: Python Client API exception duckdb.InvalidInputException
-

Bases: ProgrammingError

+

Bases: ProgrammingError

@@ -1573,7 +1572,7 @@ title: Python Client API exception duckdb.InvalidTypeException
-

Bases: ProgrammingError

+

Bases: ProgrammingError

@@ -1582,7 +1581,7 @@ title: Python Client API exception duckdb.NotImplementedException
-

Bases: NotSupportedError

+

Bases: NotSupportedError

@@ -1591,7 +1590,7 @@ title: Python Client API exception duckdb.NotSupportedError
-

Bases: Error

+

Bases: Error

@@ -1600,7 +1599,7 @@ title: Python Client API exception duckdb.OperationalError
-

Bases: Error

+

Bases: Error

@@ -1609,7 +1608,7 @@ title: Python Client API exception duckdb.OutOfMemoryException
-

Bases: OperationalError

+

Bases: OperationalError

@@ -1618,7 +1617,7 @@ title: Python Client API exception duckdb.OutOfRangeException
-

Bases: DataError

+

Bases: DataError

@@ -1627,7 +1626,7 @@ title: Python Client API exception duckdb.ParserException
-

Bases: ProgrammingError

+

Bases: ProgrammingError

@@ -1636,7 +1635,7 @@ title: Python Client API exception duckdb.PermissionException
-

Bases: Error

+

Bases: Error

@@ -1645,7 +1644,7 @@ title: Python Client API exception duckdb.ProgrammingError
-

Bases: Error

+

Bases: Error

@@ -1694,7 +1693,7 @@ title: Python Client API exception duckdb.SequenceException
-

Bases: Error

+

Bases: Error

@@ -1703,7 +1702,7 @@ title: Python Client API exception duckdb.SerializationException
-

Bases: OperationalError

+

Bases: OperationalError

@@ -1712,7 +1711,7 @@ title: Python Client API exception duckdb.StandardException
-

Bases: Error

+

Bases: Error

@@ -1721,7 +1720,7 @@ title: Python Client API exception duckdb.SyntaxException
-

Bases: ProgrammingError

+

Bases: ProgrammingError

@@ -1730,7 +1729,7 @@ title: Python Client API exception duckdb.TransactionException
-

Bases: OperationalError

+

Bases: OperationalError

@@ -1739,7 +1738,7 @@ title: Python Client API exception duckdb.TypeMismatchException
-

Bases: DataError

+

Bases: DataError

@@ -1748,7 +1747,7 @@ title: Python Client API exception duckdb.ValueOutOfRangeException
-

Bases: DataError

+

Bases: DataError

@@ -1763,7 +1762,7 @@ title: Python Client API
-duckdb.aggregate(df: pandas.DataFrame, aggr_expr: str, group_expr: str = '', connection: duckdb.DuckDBPyConnection = None) → duckdb.DuckDBPyRelation +duckdb.aggregate(df: pandas.DataFrame, aggr_expr: str, group_expr: str = '', connection: duckdb.DuckDBPyConnection = None) → duckdb.duckdb.DuckDBPyRelation

Compute the aggregate aggr_expr by the optional groups group_expr on DataFrame df

@@ -1772,7 +1771,7 @@ title: Python Client API
-duckdb.alias(df: pandas.DataFrame, alias: str, connection: duckdb.DuckDBPyConnection = None) → duckdb.DuckDBPyRelation +duckdb.alias(df: pandas.DataFrame, alias: str, connection: duckdb.DuckDBPyConnection = None) → duckdb.duckdb.DuckDBPyRelation

Create a relation from DataFrame df with the passed alias

@@ -1781,7 +1780,7 @@ title: Python Client API
-duckdb.append(table_name: str, df: pandas.DataFrame, *, by_name: bool = False, connection: duckdb.DuckDBPyConnection = None) → duckdb.DuckDBPyConnection +duckdb.append(table_name: str, df: pandas.DataFrame, *, by_name: bool = False, connection: duckdb.DuckDBPyConnection = None) → duckdb.DuckDBPyConnection

Append the passed DataFrame to the named table

@@ -1790,7 +1789,7 @@ title: Python Client API
-duckdb.array_type(type: duckdb.typing.DuckDBPyType, connection: duckdb.DuckDBPyConnection = None) → duckdb.typing.DuckDBPyType +duckdb.array_type(type: duckdb.duckdb.typing.DuckDBPyType, connection: duckdb.DuckDBPyConnection = None) → duckdb.duckdb.typing.DuckDBPyType

Create an array type object of ‘type’

@@ -1808,7 +1807,7 @@ title: Python Client API

Fetch a result as Arrow table following execute()

    -

  1. arrow(arrow_object: object, connection: duckdb.DuckDBPyConnection = None) -> duckdb.DuckDBPyRelation

    2. +

  2. arrow(arrow_object: object, connection: duckdb.DuckDBPyConnection = None) -> duckdb.duckdb.DuckDBPyRelation

Create a relation object from an Arrow object

@@ -1816,7 +1815,7 @@ title: Python Client API
-duckdb.begin(connection: duckdb.DuckDBPyConnection = None) → duckdb.DuckDBPyConnection +duckdb.begin(connection: duckdb.DuckDBPyConnection = None) → duckdb.DuckDBPyConnection

Start a new transaction

@@ -1825,7 +1824,7 @@ title: Python Client API
-duckdb.close(connection: duckdb.DuckDBPyConnection = None) → None +duckdb.close(connection: duckdb.DuckDBPyConnection = None) → None

Close the connection

@@ -1834,7 +1833,7 @@ title: Python Client API
-duckdb.commit(connection: duckdb.DuckDBPyConnection = None) → duckdb.DuckDBPyConnection +duckdb.commit(connection: duckdb.DuckDBPyConnection = None) → duckdb.DuckDBPyConnection

Commit changes performed within a transaction

@@ -1843,7 +1842,7 @@ title: Python Client API
-duckdb.connect(database: str = ':memory:', read_only: bool = False, config: dict = None) → duckdb.DuckDBPyConnection +duckdb.connect(database: str = ':memory:', read_only: bool = False, config: dict = None) → duckdb.DuckDBPyConnection

Create a DuckDB database instance. Can take a database file name to read/write persistent data and a read_only flag if no changes are desired

@@ -1852,7 +1851,7 @@ title: Python Client API
-duckdb.create_function(name: str, function: function, return_type: object = None, parameters: duckdb.typing.DuckDBPyType = None, *, type: duckdb.functional.PythonUDFType = <PythonUDFType.NATIVE: 0>, null_handling: duckdb.functional.FunctionNullHandling = 0, exception_handling: duckdb.PythonExceptionHandling = 0, side_effects: bool = False, connection: duckdb.DuckDBPyConnection = None) → duckdb.DuckDBPyConnection +duckdb.create_function(name: str, function: function, return_type: object = None, parameters: duckdb.duckdb.typing.DuckDBPyType = None, *, type: duckdb.duckdb.functional.PythonUDFType = <PythonUDFType.NATIVE: 0>, null_handling: duckdb.duckdb.functional.FunctionNullHandling = 0, exception_handling: duckdb.duckdb.PythonExceptionHandling = 0, side_effects: bool = False, connection: duckdb.DuckDBPyConnection = None) → duckdb.DuckDBPyConnection

Create a DuckDB function out of the passing in python function so it can be used in queries

@@ -1861,7 +1860,7 @@ title: Python Client API
-duckdb.cursor(connection: duckdb.DuckDBPyConnection = None) → duckdb.DuckDBPyConnection +duckdb.cursor(connection: duckdb.DuckDBPyConnection = None) → duckdb.DuckDBPyConnection

Create a duplicate of the current connection

@@ -1870,7 +1869,7 @@ title: Python Client API
-duckdb.decimal_type(width: int, scale: int, connection: duckdb.DuckDBPyConnection = None) → duckdb.typing.DuckDBPyType +duckdb.decimal_type(width: int, scale: int, connection: duckdb.DuckDBPyConnection = None) → duckdb.duckdb.typing.DuckDBPyType

Create a decimal type with ‘width’ and ‘scale’

@@ -1879,7 +1878,7 @@ title: Python Client API
-duckdb.description(connection: duckdb.DuckDBPyConnection = None) → Optional[list] +duckdb.description(connection: duckdb.DuckDBPyConnection = None) → Optional[list]

Get result set attributes, mainly column names

@@ -1897,7 +1896,7 @@ title: Python Client API

Fetch a result as DataFrame following execute()

    -

  1. df(df: pandas.DataFrame, connection: duckdb.DuckDBPyConnection = None) -> duckdb.DuckDBPyRelation

    2. +

  2. df(df: pandas.DataFrame, connection: duckdb.DuckDBPyConnection = None) -> duckdb.duckdb.DuckDBPyRelation

Create a relation object from the DataFrame df

@@ -1905,7 +1904,7 @@ title: Python Client API
-duckdb.distinct(df: pandas.DataFrame, connection: duckdb.DuckDBPyConnection = None) → duckdb.DuckDBPyRelation +duckdb.distinct(df: pandas.DataFrame, connection: duckdb.DuckDBPyConnection = None) → duckdb.duckdb.DuckDBPyRelation

Compute the distinct rows from DataFrame df

@@ -1914,7 +1913,7 @@ title: Python Client API
-duckdb.dtype(type_str: str, connection: duckdb.DuckDBPyConnection = None) → duckdb.typing.DuckDBPyType +duckdb.dtype(type_str: str, connection: duckdb.DuckDBPyConnection = None) → duckdb.duckdb.typing.DuckDBPyType

Create a type object from ‘type_str’

@@ -1923,7 +1922,7 @@ title: Python Client API
-duckdb.duplicate(connection: duckdb.DuckDBPyConnection = None) → duckdb.DuckDBPyConnection +duckdb.duplicate(connection: duckdb.DuckDBPyConnection = None) → duckdb.DuckDBPyConnection

Create a duplicate of the current connection

@@ -1932,7 +1931,7 @@ title: Python Client API
-duckdb.enum_type(name: str, type: duckdb.typing.DuckDBPyType, values: list, connection: duckdb.DuckDBPyConnection = None) → duckdb.typing.DuckDBPyType +duckdb.enum_type(name: str, type: duckdb.duckdb.typing.DuckDBPyType, values: list, connection: duckdb.DuckDBPyConnection = None) → duckdb.duckdb.typing.DuckDBPyType

Create an enum type of underlying ‘type’, consisting of the list of ‘values’

@@ -1941,7 +1940,7 @@ title: Python Client API
-duckdb.execute(query: str, parameters: object = None, multiple_parameter_sets: bool = False, connection: duckdb.DuckDBPyConnection = None) → duckdb.DuckDBPyConnection +duckdb.execute(query: str, parameters: object = None, multiple_parameter_sets: bool = False, connection: duckdb.DuckDBPyConnection = None) → duckdb.DuckDBPyConnection

Execute the given SQL query, optionally using prepared statements with parameters set

@@ -1950,7 +1949,7 @@ title: Python Client API
-duckdb.executemany(query: str, parameters: object = None, connection: duckdb.DuckDBPyConnection = None) → duckdb.DuckDBPyConnection +duckdb.executemany(query: str, parameters: object = None, connection: duckdb.DuckDBPyConnection = None) → duckdb.DuckDBPyConnection

Execute the given prepared statement multiple times using the list of parameter sets in parameters

@@ -1959,7 +1958,7 @@ title: Python Client API
-duckdb.fetch_arrow_table(rows_per_batch: int = 1000000, connection: duckdb.DuckDBPyConnection = None) → pyarrow.lib.Table +duckdb.fetch_arrow_table(rows_per_batch: int = 1000000, connection: duckdb.DuckDBPyConnection = None) → pyarrow.lib.Table

Fetch a result as Arrow table following execute()

@@ -1968,7 +1967,7 @@ title: Python Client API
-duckdb.fetch_df(*, date_as_object: bool = False, connection: duckdb.DuckDBPyConnection = None) → pandas.DataFrame +duckdb.fetch_df(*, date_as_object: bool = False, connection: duckdb.DuckDBPyConnection = None) → pandas.DataFrame

Fetch a result as DataFrame following execute()

@@ -1977,7 +1976,7 @@ title: Python Client API
-duckdb.fetch_df_chunk(vectors_per_chunk: int = 1, *, date_as_object: bool = False, connection: duckdb.DuckDBPyConnection = None) → pandas.DataFrame +duckdb.fetch_df_chunk(vectors_per_chunk: int = 1, *, date_as_object: bool = False, connection: duckdb.DuckDBPyConnection = None) → pandas.DataFrame

Fetch a chunk of the result as DataFrame following execute()

@@ -1986,7 +1985,7 @@ title: Python Client API
-duckdb.fetch_record_batch(rows_per_batch: int = 1000000, connection: duckdb.DuckDBPyConnection = None) → pyarrow.lib.RecordBatchReader +duckdb.fetch_record_batch(rows_per_batch: int = 1000000, connection: duckdb.DuckDBPyConnection = None) → pyarrow.lib.RecordBatchReader

Fetch an Arrow RecordBatchReader following execute()

@@ -1995,7 +1994,7 @@ title: Python Client API
-duckdb.fetchall(connection: duckdb.DuckDBPyConnection = None) → list +duckdb.fetchall(connection: duckdb.DuckDBPyConnection = None) → list

Fetch all rows from a result following execute

@@ -2004,7 +2003,7 @@ title: Python Client API
-duckdb.fetchdf(*, date_as_object: bool = False, connection: duckdb.DuckDBPyConnection = None) → pandas.DataFrame +duckdb.fetchdf(*, date_as_object: bool = False, connection: duckdb.DuckDBPyConnection = None) → pandas.DataFrame

Fetch a result as DataFrame following execute()

@@ -2013,7 +2012,7 @@ title: Python Client API
-duckdb.fetchmany(size: int = 1, connection: duckdb.DuckDBPyConnection = None) → list +duckdb.fetchmany(size: int = 1, connection: duckdb.DuckDBPyConnection = None) → list

Fetch the next set of rows from a result following execute

@@ -2022,7 +2021,7 @@ title: Python Client API
-duckdb.fetchnumpy(connection: duckdb.DuckDBPyConnection = None) → dict +duckdb.fetchnumpy(connection: duckdb.DuckDBPyConnection = None) → dict

Fetch a result as list of NumPy arrays following execute

@@ -2031,7 +2030,7 @@ title: Python Client API
-duckdb.fetchone(connection: duckdb.DuckDBPyConnection = None) → Optional[tuple] +duckdb.fetchone(connection: duckdb.DuckDBPyConnection = None) → Optional[tuple]

Fetch a single row from a result following execute

@@ -2040,7 +2039,7 @@ title: Python Client API
-duckdb.filesystem_is_registered(name: str, connection: duckdb.DuckDBPyConnection = None) → bool +duckdb.filesystem_is_registered(name: str, connection: duckdb.DuckDBPyConnection = None) → bool

Check if a filesystem with the provided name is currently registered

@@ -2049,7 +2048,7 @@ title: Python Client API
-duckdb.filter(df: pandas.DataFrame, filter_expr: str, connection: duckdb.DuckDBPyConnection = None) → duckdb.DuckDBPyRelation +duckdb.filter(df: pandas.DataFrame, filter_expr: str, connection: duckdb.DuckDBPyConnection = None) → duckdb.duckdb.DuckDBPyRelation

Filter the DataFrame df by the filter in filter_expr

@@ -2058,7 +2057,7 @@ title: Python Client API
-duckdb.from_arrow(arrow_object: object, connection: duckdb.DuckDBPyConnection = None) → duckdb.DuckDBPyRelation +duckdb.from_arrow(arrow_object: object, connection: duckdb.DuckDBPyConnection = None) → duckdb.duckdb.DuckDBPyRelation

Create a relation object from an Arrow object

@@ -2067,7 +2066,7 @@ title: Python Client API
-duckdb.from_csv_auto(name: object, connection: duckdb.DuckDBPyConnection = None, header: object = None, compression: object = None, sep: object = None, delimiter: object = None, dtype: object = None, na_values: object = None, skiprows: object = None, quotechar: object = None, escapechar: object = None, encoding: object = None, parallel: object = None, date_format: object = None, timestamp_format: object = None, sample_size: object = None, all_varchar: object = None, normalize_names: object = None, filename: object = None, null_padding: object = None) → duckdb.DuckDBPyRelation +duckdb.from_csv_auto(name: object, connection: duckdb.DuckDBPyConnection = None, header: object = None, compression: object = None, sep: object = None, delimiter: object = None, dtype: object = None, na_values: object = None, skiprows: object = None, quotechar: object = None, escapechar: object = None, encoding: object = None, parallel: object = None, date_format: object = None, timestamp_format: object = None, sample_size: object = None, all_varchar: object = None, normalize_names: object = None, filename: object = None, null_padding: object = None) → duckdb.duckdb.DuckDBPyRelation

Create a relation object from the CSV file in ‘name’

@@ -2076,7 +2075,7 @@ title: Python Client API
-duckdb.from_df(df: pandas.DataFrame, connection: duckdb.DuckDBPyConnection = None) → duckdb.DuckDBPyRelation +duckdb.from_df(df: pandas.DataFrame, connection: duckdb.DuckDBPyConnection = None) → duckdb.duckdb.DuckDBPyRelation

Create a relation object from the DataFrame df

@@ -2090,11 +2089,11 @@ title: Python Client API

Overloaded function.

    -

  1. from_parquet(file_glob: str, binary_as_string: bool = False, *, file_row_number: bool = False, filename: bool = False, hive_partitioning: bool = False, union_by_name: bool = False, compression: object = None, connection: duckdb.DuckDBPyConnection = None) -> duckdb.DuckDBPyRelation

    2. +

  2. from_parquet(file_glob: str, binary_as_string: bool = False, *, file_row_number: bool = False, filename: bool = False, hive_partitioning: bool = False, union_by_name: bool = False, compression: object = None, connection: duckdb.DuckDBPyConnection = None) -> duckdb.duckdb.DuckDBPyRelation

Create a relation object from the Parquet files in file_glob

    -

  1. from_parquet(file_globs: List[str], binary_as_string: bool = False, *, file_row_number: bool = False, filename: bool = False, hive_partitioning: bool = False, union_by_name: bool = False, compression: object = None, connection: duckdb.DuckDBPyConnection = None) -> duckdb.DuckDBPyRelation

    2. +

  2. from_parquet(file_globs: List[str], binary_as_string: bool = False, *, file_row_number: bool = False, filename: bool = False, hive_partitioning: bool = False, union_by_name: bool = False, compression: object = None, connection: duckdb.DuckDBPyConnection = None) -> duckdb.duckdb.DuckDBPyRelation

Create a relation object from the Parquet files in file_globs

@@ -2107,11 +2106,11 @@ title: Python Client API

Overloaded function.

    -

  1. from_query(query: str, alias: str = ‘’, connection: duckdb.DuckDBPyConnection = None) -> duckdb.DuckDBPyRelation

    2. +

  2. from_query(query: str, alias: str = ‘’, connection: duckdb.DuckDBPyConnection = None) -> duckdb.duckdb.DuckDBPyRelation

Create a relation object from the given SQL query

    -

  1. from_query(query: str, alias: str = ‘query_relation’, connection: duckdb.DuckDBPyConnection = None) -> duckdb.DuckDBPyRelation

    2. +

  2. from_query(query: str, alias: str = ‘query_relation’, connection: duckdb.DuckDBPyConnection = None) -> duckdb.duckdb.DuckDBPyRelation

Create a relation object from the given SQL query

@@ -2124,11 +2123,11 @@ title: Python Client API

Overloaded function.

    -

  1. from_substrait(proto: bytes, connection: duckdb.DuckDBPyConnection = None) -> duckdb.DuckDBPyRelation

    2. +

  2. from_substrait(proto: bytes, connection: duckdb.DuckDBPyConnection = None) -> duckdb.duckdb.DuckDBPyRelation

Creates a query object from the substrait plan

    -

  1. from_substrait(proto: bytes, connection: duckdb.DuckDBPyConnection = None) -> duckdb.DuckDBPyRelation

    2. +

  2. from_substrait(proto: bytes, connection: duckdb.DuckDBPyConnection = None) -> duckdb.duckdb.DuckDBPyRelation

Create a query object from protobuf plan

@@ -2136,7 +2135,7 @@ title: Python Client API
-duckdb.from_substrait_json(json: str, connection: duckdb.DuckDBPyConnection = None) → duckdb.DuckDBPyRelation +duckdb.from_substrait_json(json: str, connection: duckdb.DuckDBPyConnection = None) → duckdb.duckdb.DuckDBPyRelation

Serialize a query object to protobuf

@@ -2150,11 +2149,11 @@ title: Python Client API

Overloaded function.

    -

  1. get_substrait(query: str, connection: duckdb.DuckDBPyConnection = None, *, enable_optimizer: bool = True) -> duckdb.DuckDBPyRelation

    2. +

  2. get_substrait(query: str, connection: duckdb.DuckDBPyConnection = None, *, enable_optimizer: bool = True) -> duckdb.duckdb.DuckDBPyRelation

Serialize a query object to protobuf

    -

  1. get_substrait(query: str, connection: duckdb.DuckDBPyConnection = None, *, enable_optimizer: bool = True) -> duckdb.DuckDBPyRelation

    2. +

  2. get_substrait(query: str, connection: duckdb.DuckDBPyConnection = None, *, enable_optimizer: bool = True) -> duckdb.duckdb.DuckDBPyRelation

Serialize a query to protobuf

@@ -2167,11 +2166,11 @@ title: Python Client API

Overloaded function.

    -

  1. get_substrait_json(query: str, connection: duckdb.DuckDBPyConnection = None, *, enable_optimizer: bool = True) -> duckdb.DuckDBPyRelation

    2. +

  2. get_substrait_json(query: str, connection: duckdb.DuckDBPyConnection = None, *, enable_optimizer: bool = True) -> duckdb.duckdb.DuckDBPyRelation

Serialize a query object to protobuf

    -

  1. get_substrait_json(query: str, connection: duckdb.DuckDBPyConnection = None, *, enable_optimizer: bool = True) -> duckdb.DuckDBPyRelation

    2. +

  2. get_substrait_json(query: str, connection: duckdb.DuckDBPyConnection = None, *, enable_optimizer: bool = True) -> duckdb.duckdb.DuckDBPyRelation

Serialize a query to protobuf on the JSON format

@@ -2179,7 +2178,7 @@ title: Python Client API
-duckdb.get_table_names(query: str, connection: duckdb.DuckDBPyConnection = None) → Set[str] +duckdb.get_table_names(query: str, connection: duckdb.DuckDBPyConnection = None) → Set[str]

Extract the required table names from a query

@@ -2188,7 +2187,7 @@ title: Python Client API
-duckdb.install_extension(extension: str, *, force_install: bool = False, connection: duckdb.DuckDBPyConnection = None) → None +duckdb.install_extension(extension: str, *, force_install: bool = False, connection: duckdb.DuckDBPyConnection = None) → None

Install an extension by name

@@ -2197,7 +2196,7 @@ title: Python Client API
-duckdb.interrupt(connection: duckdb.DuckDBPyConnection = None) → None +duckdb.interrupt(connection: duckdb.DuckDBPyConnection = None) → None

Interrupt pending operations

@@ -2206,7 +2205,7 @@ title: Python Client API
-duckdb.limit(df: pandas.DataFrame, n: int, connection: duckdb.DuckDBPyConnection = None) → duckdb.DuckDBPyRelation +duckdb.limit(df: pandas.DataFrame, n: int, connection: duckdb.DuckDBPyConnection = None) → duckdb.duckdb.DuckDBPyRelation

Retrieve the first n rows from the DataFrame df

@@ -2215,7 +2214,7 @@ title: Python Client API
-duckdb.list_filesystems(connection: duckdb.DuckDBPyConnection = None) → list +duckdb.list_filesystems(connection: duckdb.DuckDBPyConnection = None) → list

List registered filesystems, including builtin ones

@@ -2224,7 +2223,7 @@ title: Python Client API
-duckdb.list_type(type: duckdb.typing.DuckDBPyType, connection: duckdb.DuckDBPyConnection = None) → duckdb.typing.DuckDBPyType +duckdb.list_type(type: duckdb.duckdb.typing.DuckDBPyType, connection: duckdb.DuckDBPyConnection = None) → duckdb.duckdb.typing.DuckDBPyType

Create an array type object of ‘type’

@@ -2233,7 +2232,7 @@ title: Python Client API
-duckdb.load_extension(extension: str, connection: duckdb.DuckDBPyConnection = None) → None +duckdb.load_extension(extension: str, connection: duckdb.DuckDBPyConnection = None) → None

Load an installed extension

@@ -2242,7 +2241,7 @@ title: Python Client API
-duckdb.map_type(key: duckdb.typing.DuckDBPyType, value: duckdb.typing.DuckDBPyType, connection: duckdb.DuckDBPyConnection = None) → duckdb.typing.DuckDBPyType +duckdb.map_type(key: duckdb.duckdb.typing.DuckDBPyType, value: duckdb.duckdb.typing.DuckDBPyType, connection: duckdb.DuckDBPyConnection = None) → duckdb.duckdb.typing.DuckDBPyType

Create a map type object from ‘key_type’ and ‘value_type’

@@ -2251,7 +2250,7 @@ title: Python Client API
-duckdb.order(df: pandas.DataFrame, order_expr: str, connection: duckdb.DuckDBPyConnection = None) → duckdb.DuckDBPyRelation +duckdb.order(df: pandas.DataFrame, order_expr: str, connection: duckdb.DuckDBPyConnection = None) → duckdb.duckdb.DuckDBPyRelation

Reorder the DataFrame df by order_expr

@@ -2260,7 +2259,7 @@ title: Python Client API
-duckdb.pl(rows_per_batch: int = 1000000, connection: duckdb.DuckDBPyConnection = None) → duckdb::PolarsDataFrame +duckdb.pl(rows_per_batch: int = 1000000, connection: duckdb.DuckDBPyConnection = None) → duckdb::PolarsDataFrame

Fetch a result as Polars DataFrame following execute()

@@ -2269,7 +2268,7 @@ title: Python Client API
-duckdb.project(df: pandas.DataFrame, project_expr: str, connection: duckdb.DuckDBPyConnection = None) → duckdb.DuckDBPyRelation +duckdb.project(df: pandas.DataFrame, project_expr: str, connection: duckdb.DuckDBPyConnection = None) → duckdb.duckdb.DuckDBPyRelation

Project the DataFrame df by the projection in project_expr

@@ -2278,7 +2277,7 @@ title: Python Client API
-duckdb.query(query: str, alias: str = '', connection: duckdb.DuckDBPyConnection = None) → duckdb.DuckDBPyRelation +duckdb.query(query: str, alias: str = '', connection: duckdb.DuckDBPyConnection = None) → duckdb.duckdb.DuckDBPyRelation

Run a SQL query. If it is a SELECT statement, create a relation object from the given SQL query, otherwise run the query as-is.

@@ -2287,7 +2286,7 @@ title: Python Client API
-duckdb.query_df(df: pandas.DataFrame, virtual_table_name: str, sql_query: str, connection: duckdb.DuckDBPyConnection = None) → duckdb.DuckDBPyRelation +duckdb.query_df(df: pandas.DataFrame, virtual_table_name: str, sql_query: str, connection: duckdb.DuckDBPyConnection = None) → duckdb.duckdb.DuckDBPyRelation

Run the given SQL query in sql_query on the view named virtual_table_name that contains the content of DataFrame df

@@ -2296,7 +2295,7 @@ title: Python Client API
-duckdb.read_csv(name: object, connection: duckdb.DuckDBPyConnection = None, header: object = None, compression: object = None, sep: object = None, delimiter: object = None, dtype: object = None, na_values: object = None, skiprows: object = None, quotechar: object = None, escapechar: object = None, encoding: object = None, parallel: object = None, date_format: object = None, timestamp_format: object = None, sample_size: object = None, all_varchar: object = None, normalize_names: object = None, filename: object = None, null_padding: object = None) → duckdb.DuckDBPyRelation +duckdb.read_csv(name: object, connection: duckdb.DuckDBPyConnection = None, header: object = None, compression: object = None, sep: object = None, delimiter: object = None, dtype: object = None, na_values: object = None, skiprows: object = None, quotechar: object = None, escapechar: object = None, encoding: object = None, parallel: object = None, date_format: object = None, timestamp_format: object = None, sample_size: object = None, all_varchar: object = None, normalize_names: object = None, filename: object = None, null_padding: object = None) → duckdb.duckdb.DuckDBPyRelation

Create a relation object from the CSV file in ‘name’

@@ -2305,7 +2304,7 @@ title: Python Client API
-duckdb.read_json(name: str, connection: duckdb.DuckDBPyConnection = None, columns: Optional[object] = None, sample_size: Optional[object] = None, maximum_depth: Optional[object] = None, records: Optional[str] = None, format: Optional[str] = None) → duckdb.DuckDBPyRelation +duckdb.read_json(name: str, connection: duckdb.DuckDBPyConnection = None, columns: Optional[object] = None, sample_size: Optional[object] = None, maximum_depth: Optional[object] = None, records: Optional[str] = None, format: Optional[str] = None) → duckdb.duckdb.DuckDBPyRelation

Create a relation object from the JSON file in ‘name’

@@ -2319,11 +2318,11 @@ title: Python Client API

Overloaded function.

    -

  1. read_parquet(file_glob: str, binary_as_string: bool = False, *, file_row_number: bool = False, filename: bool = False, hive_partitioning: bool = False, union_by_name: bool = False, compression: object = None, connection: duckdb.DuckDBPyConnection = None) -> duckdb.DuckDBPyRelation

    2. +

  2. read_parquet(file_glob: str, binary_as_string: bool = False, *, file_row_number: bool = False, filename: bool = False, hive_partitioning: bool = False, union_by_name: bool = False, compression: object = None, connection: duckdb.DuckDBPyConnection = None) -> duckdb.duckdb.DuckDBPyRelation

Create a relation object from the Parquet files in file_glob

    -

  1. read_parquet(file_globs: List[str], binary_as_string: bool = False, *, file_row_number: bool = False, filename: bool = False, hive_partitioning: bool = False, union_by_name: bool = False, compression: object = None, connection: duckdb.DuckDBPyConnection = None) -> duckdb.DuckDBPyRelation

    2. +

  2. read_parquet(file_globs: List[str], binary_as_string: bool = False, *, file_row_number: bool = False, filename: bool = False, hive_partitioning: bool = False, union_by_name: bool = False, compression: object = None, connection: duckdb.DuckDBPyConnection = None) -> duckdb.duckdb.DuckDBPyRelation

Create a relation object from the Parquet files in file_globs

@@ -2331,7 +2330,7 @@ title: Python Client API
-duckdb.register(view_name: str, python_object: object, connection: duckdb.DuckDBPyConnection = None) → duckdb.DuckDBPyConnection +duckdb.register(view_name: str, python_object: object, connection: duckdb.DuckDBPyConnection = None) → duckdb.DuckDBPyConnection

Register the passed Python Object value for querying with a view

@@ -2340,7 +2339,7 @@ title: Python Client API
-duckdb.register_filesystem(filesystem: fsspec.AbstractFileSystem, connection: duckdb.DuckDBPyConnection = None) → None +duckdb.register_filesystem(filesystem: fsspec.AbstractFileSystem, connection: duckdb.DuckDBPyConnection = None) → None

Register a fsspec compliant filesystem

@@ -2349,7 +2348,7 @@ title: Python Client API
-duckdb.remove_function(name: str, connection: duckdb.DuckDBPyConnection = None) → duckdb.DuckDBPyConnection +duckdb.remove_function(name: str, connection: duckdb.DuckDBPyConnection = None) → duckdb.DuckDBPyConnection

Remove a previously created function

@@ -2358,7 +2357,7 @@ title: Python Client API
-duckdb.rollback(connection: duckdb.DuckDBPyConnection = None) → duckdb.DuckDBPyConnection +duckdb.rollback(connection: duckdb.DuckDBPyConnection = None) → duckdb.DuckDBPyConnection

Roll back changes performed within a transaction

@@ -2367,7 +2366,7 @@ title: Python Client API
-duckdb.row_type(fields: object, connection: duckdb.DuckDBPyConnection = None) → duckdb.typing.DuckDBPyType +duckdb.row_type(fields: object, connection: duckdb.DuckDBPyConnection = None) → duckdb.duckdb.typing.DuckDBPyType

Create a struct type object from ‘fields’

@@ -2376,7 +2375,7 @@ title: Python Client API
-duckdb.sql(query: str, alias: str = '', connection: duckdb.DuckDBPyConnection = None) → duckdb.DuckDBPyRelation +duckdb.sql(query: str, alias: str = '', connection: duckdb.DuckDBPyConnection = None) → duckdb.duckdb.DuckDBPyRelation

Run a SQL query. If it is a SELECT statement, create a relation object from the given SQL query, otherwise run the query as-is.

@@ -2385,7 +2384,7 @@ title: Python Client API
-duckdb.sqltype(type_str: str, connection: duckdb.DuckDBPyConnection = None) → duckdb.typing.DuckDBPyType +duckdb.sqltype(type_str: str, connection: duckdb.DuckDBPyConnection = None) → duckdb.duckdb.typing.DuckDBPyType

Create a type object from ‘type_str’

@@ -2394,7 +2393,7 @@ title: Python Client API
-duckdb.string_type(collation: str = '', connection: duckdb.DuckDBPyConnection = None) → duckdb.typing.DuckDBPyType +duckdb.string_type(collation: str = '', connection: duckdb.DuckDBPyConnection = None) → duckdb.duckdb.typing.DuckDBPyType

Create a string type with an optional collation

@@ -2403,7 +2402,7 @@ title: Python Client API
-duckdb.struct_type(fields: object, connection: duckdb.DuckDBPyConnection = None) → duckdb.typing.DuckDBPyType +duckdb.struct_type(fields: object, connection: duckdb.DuckDBPyConnection = None) → duckdb.duckdb.typing.DuckDBPyType

Create a struct type object from ‘fields’

@@ -2412,7 +2411,7 @@ title: Python Client API
-duckdb.table(table_name: str, connection: duckdb.DuckDBPyConnection = None) → duckdb.DuckDBPyRelation +duckdb.table(table_name: str, connection: duckdb.DuckDBPyConnection = None) → duckdb.duckdb.DuckDBPyRelation

Create a relation object for the name’d table

@@ -2421,7 +2420,7 @@ title: Python Client API
-duckdb.table_function(name: str, parameters: object = None, connection: duckdb.DuckDBPyConnection = None) → duckdb.DuckDBPyRelation +duckdb.table_function(name: str, parameters: object = None, connection: duckdb.DuckDBPyConnection = None) → duckdb.duckdb.DuckDBPyRelation

Create a relation object from the name’d table function with given parameters

@@ -2430,7 +2429,7 @@ title: Python Client API
-duckdb.tf(connection: duckdb.DuckDBPyConnection = None) → dict +duckdb.tf(connection: duckdb.DuckDBPyConnection = None) → dict

Fetch a result as dict of TensorFlow Tensors following execute()

@@ -2520,7 +2519,7 @@ title: Python Client API
-duckdb.torch(connection: duckdb.DuckDBPyConnection = None) → dict +duckdb.torch(connection: duckdb.DuckDBPyConnection = None) → dict

Fetch a result as dict of PyTorch Tensors following execute()

@@ -2529,7 +2528,7 @@ title: Python Client API
-duckdb.type(type_str: str, connection: duckdb.DuckDBPyConnection = None) → duckdb.typing.DuckDBPyType +duckdb.type(type_str: str, connection: duckdb.DuckDBPyConnection = None) → duckdb.duckdb.typing.DuckDBPyType

Create a type object from ‘type_str’

@@ -2538,7 +2537,7 @@ title: Python Client API
-duckdb.union_type(members: object, connection: duckdb.DuckDBPyConnection = None) → duckdb.typing.DuckDBPyType +duckdb.union_type(members: object, connection: duckdb.DuckDBPyConnection = None) → duckdb.duckdb.typing.DuckDBPyType

Create a union type object from ‘members’

@@ -2547,7 +2546,7 @@ title: Python Client API
-duckdb.unregister(view_name: str, connection: duckdb.DuckDBPyConnection = None) → duckdb.DuckDBPyConnection +duckdb.unregister(view_name: str, connection: duckdb.DuckDBPyConnection = None) → duckdb.DuckDBPyConnection

Unregister the view name

@@ -2556,7 +2555,7 @@ title: Python Client API
-duckdb.unregister_filesystem(name: str, connection: duckdb.DuckDBPyConnection = None) → None +duckdb.unregister_filesystem(name: str, connection: duckdb.DuckDBPyConnection = None) → None

Unregister a filesystem

@@ -2570,11 +2569,11 @@ title: Python Client API

Overloaded function.

    -

  1. values(values: object, connection: duckdb.DuckDBPyConnection = None) -> duckdb.DuckDBPyRelation

    2. +

  2. values(values: object, connection: duckdb.DuckDBPyConnection = None) -> duckdb.duckdb.DuckDBPyRelation

Create a relation object from the passed values

    -

  1. values(values: object, connection: duckdb.DuckDBPyConnection = None) -> duckdb.DuckDBPyRelation

    2. +

  2. values(values: object, connection: duckdb.DuckDBPyConnection = None) -> duckdb.duckdb.DuckDBPyRelation

Create a relation object from the passed values

@@ -2582,7 +2581,7 @@ title: Python Client API
-duckdb.view(view_name: str, connection: duckdb.DuckDBPyConnection = None) → duckdb.DuckDBPyRelation +duckdb.view(view_name: str, connection: duckdb.DuckDBPyConnection = None) → duckdb.duckdb.DuckDBPyRelation

Create a relation object for the name’d view

@@ -2591,7 +2590,7 @@ title: Python Client API
-duckdb.write_csv(df: pandas.DataFrame, file_name: str, connection: duckdb.DuckDBPyConnection = None) → None +duckdb.write_csv(df: pandas.DataFrame, file_name: str, connection: duckdb.DuckDBPyConnection = None) → None

Write the DataFrame df to a CSV file in file_name

From 2d77add1b9ad0b099f6d9b77ad9a7bf52a81b826 Mon Sep 17 00:00:00 2001 From: GitHub Actions Date: Mon, 7 Aug 2023 05:05:07 +0000 Subject: [PATCH 03/12] chore: auto update docs --- data/search_data.json | 26 +++++++++++++------------- docs/api/python/reference/index.md | 18 +++++------------- 2 files changed, 18 insertions(+), 26 deletions(-) diff --git a/data/search_data.json b/data/search_data.json index 1baf1cbbbd7..04ef28bcf0c 100644 --- a/data/search_data.json +++ b/data/search_data.json @@ -434,13 +434,6 @@ "url": "/docs/guides/sql_editors/dbeaver", "blurb": "How to set up DBeaver SQL IDE for DuckDB DBeaver is a powerful and popular desktop sql editor and integrated..." }, - { - "title": "Data Ingestion", - "text": "duckdb-wasm has multiple ways to import data depending on the format of the data there are two steps to import data into duckdb first the data file is imported into a local file system using register functions registeremptyfilebuffer registerfilebuffer registerfilehandle registerfiletext registerfileurl then the data file is imported into duckdb using insert functions insertarrowfromipcstream insertarrowtable insertcsvfrompath insertjsonfrompath or directly using from sql query using extensions like parquet or httpfs insert statements can also be used to import data data import open close connection create a new connection const c await db connect import data close the connection to release memory await c close apache arrow data can be inserted from an existing arrow table more example https arrow apache org docs js import tablefromarrays from apache-arrow const arrowtable tablefromarrays id 1 2 3 name john jane jack age 20 21 22 await c insertarrowtable arrowtable name arrow_table from a raw arrow ipc stream const streamresponse await fetch someapi const streamreader streamresponse body getreader const streaminserts while true const value done await streamreader read if done break streaminserts push c insertarrowfromipcstream value name streamed await promise all streaminserts csv from csv files interchangeable registerfile text buffer url handle const csvcontent 1 foo n2 bar n await db registerfiletext data csv csvcontent with typed insert options await db insertcsvfrompath data csv schema main name foo detect false header false delimiter columns col1 new arrow int32 col2 new arrow utf8 json from json documents in row-major format const jsonrowcontent col1 1 col2 foo col1 2 col2 bar await db registerfiletext rows json json stringify jsonrowcontent await c insertjsonfrompath rows json name rows or column-major format const jsoncolcontent col1 1 2 col2 foo bar await db registerfiletext columns json json stringify jsoncolcontent await c insertjsonfrompath columns json name columns from api const streamresponse await fetch someapi content json await db registerfilebuffer file json new uint8array await streamresponse arraybuffer await c insertjsonfrompath file json name jsoncontent parquet from parquet files local const pickedfile file letuserpickfile await db registerfilehandle local parquet pickedfile duckdbdataprotocol browser_filereader true remote await db registerfileurl remote parquet https origin remote parquet duckdbdataprotocol http false using fetch const res await fetch https origin remote parquet await db registerfilebuffer buffer parquet new uint8array await res arraybuffer by specifying urls in the sql text await c query create table direct as select from https origin remote parquet or by executing raw insert statements await c query insert into existing_table values 1 foo 2 bar httpfs by specifying urls in the sql text await c query create table direct as select from https origin remote parquet insert statement or by executing raw insert statements await c query insert into existing_table values 1 foo 2 bar", - "category": "Wasm", - "url": "/docs/api/wasm/data_ingestion", - "blurb": "DuckDB-Wasm has multiple ways to import data, depending on the format of the data. There are two steps to import data..." - }, { "title": "Data Ingestion", "text": "csv files csv files can be read using the read_csv function called either from within python or directly from within sql by default the read_csv function attempts to auto-detect the csv settings by sampling from the provided file import duckdb read from a file using fully auto-detected settings duckdb read_csv example csv read multiple csv files from a folder duckdb read_csv folder csv specify options on how the csv is formatted internally duckdb read_csv example csv header false sep override types of the first two columns duckdb read_csv example csv dtype int varchar use the experimental parallel csv reader duckdb read_csv example csv parallel true directly read a csv file from within sql duckdb sql select from example csv call read_csv from within sql duckdb sql select from read_csv_auto example csv see the csv loading page for more information parquet files parquet files can be read using the read_parquet function called either from within python or directly from within sql import duckdb read from a single parquet file duckdb read_parquet example parquet read multiple parquet files from a folder duckdb read_parquet folder parquet directly read a parquet file from within sql duckdb sql select from example parquet call read_parquet from within sql duckdb sql select from read_parquet example parquet see the parquet loading page for more information json files json files can be read using the read_json function called either from within python or directly from within sql by default the read_json function will automatically detect if a file contains newline-delimited json or regular json and will detect the schema of the objects stored within the json file import duckdb read from a single json file duckdb read_json example json read multiple json files from a folder duckdb read_json folder json directly read a json file from within sql duckdb sql select from example json call read_json from within sql duckdb sql select from read_json_auto example json dataframes arrow tables duckdb is automatically able to query a pandas dataframe polars dataframe or arrow object that is stored in a python variable by name duckdb supports querying multiple types of apache arrow objects including tables datasets recordbatchreaders and scanners see the python guides for more examples import duckdb import pandas as pd test_df pd dataframe from_dict i 1 2 3 4 j one two three four duckdb sql select from test_df fetchall 1 one 2 two 3 three 4 four duckdb also supports registering a dataframe or arrow object as a virtual table comparable to a sql view this is useful when querying a dataframe arrow object that is stored in another way as a class variable or a value in a dictionary below is a pandas example if your pandas dataframe is stored in another location here is an example of manually registering it import duckdb import pandas as pd my_dictionary my_dictionary test_df pd dataframe from_dict i 1 2 3 4 j one two three four duckdb register test_df_view my_dictionary test_df duckdb sql select from test_df_view fetchall 1 one 2 two 3 three 4 four you can also create a persistent table in duckdb from the contents of the dataframe or the view create a new table from the contents of a dataframe con execute create table test_df_table as select from test_df insert into an existing table from the contents of a dataframe con execute insert into test_df_table select from test_df pandas dataframes - object columns pandas dataframe columns of an object dtype require some special care since this stores values of arbitrary type to convert these columns to duckdb we first go through an analyze phase before converting the values in this analyze phase a sample of all the rows of the column are analyzed to determine the target type this sample size is by default set to 1000 if the type picked during the analyze step is wrong this will result in a failed to cast value error in which case you will need to increase the sample size the sample size can be changed by setting the pandas_analyze_sample config option example setting the sample size to 100000 duckdb default_connection execute set global pandas_analyze_sample 100000", @@ -448,6 +441,13 @@ "url": "/docs/api/python/data_ingestion", "blurb": "CSV Files CSV files can be read using the read_csv function, called either from within Python or directly from within..." }, + { + "title": "Data Ingestion", + "text": "duckdb-wasm has multiple ways to import data depending on the format of the data there are two steps to import data into duckdb first the data file is imported into a local file system using register functions registeremptyfilebuffer registerfilebuffer registerfilehandle registerfiletext registerfileurl then the data file is imported into duckdb using insert functions insertarrowfromipcstream insertarrowtable insertcsvfrompath insertjsonfrompath or directly using from sql query using extensions like parquet or httpfs insert statements can also be used to import data data import open close connection create a new connection const c await db connect import data close the connection to release memory await c close apache arrow data can be inserted from an existing arrow table more example https arrow apache org docs js import tablefromarrays from apache-arrow const arrowtable tablefromarrays id 1 2 3 name john jane jack age 20 21 22 await c insertarrowtable arrowtable name arrow_table from a raw arrow ipc stream const streamresponse await fetch someapi const streamreader streamresponse body getreader const streaminserts while true const value done await streamreader read if done break streaminserts push c insertarrowfromipcstream value name streamed await promise all streaminserts csv from csv files interchangeable registerfile text buffer url handle const csvcontent 1 foo n2 bar n await db registerfiletext data csv csvcontent with typed insert options await db insertcsvfrompath data csv schema main name foo detect false header false delimiter columns col1 new arrow int32 col2 new arrow utf8 json from json documents in row-major format const jsonrowcontent col1 1 col2 foo col1 2 col2 bar await db registerfiletext rows json json stringify jsonrowcontent await c insertjsonfrompath rows json name rows or column-major format const jsoncolcontent col1 1 2 col2 foo bar await db registerfiletext columns json json stringify jsoncolcontent await c insertjsonfrompath columns json name columns from api const streamresponse await fetch someapi content json await db registerfilebuffer file json new uint8array await streamresponse arraybuffer await c insertjsonfrompath file json name jsoncontent parquet from parquet files local const pickedfile file letuserpickfile await db registerfilehandle local parquet pickedfile duckdbdataprotocol browser_filereader true remote await db registerfileurl remote parquet https origin remote parquet duckdbdataprotocol http false using fetch const res await fetch https origin remote parquet await db registerfilebuffer buffer parquet new uint8array await res arraybuffer by specifying urls in the sql text await c query create table direct as select from https origin remote parquet or by executing raw insert statements await c query insert into existing_table values 1 foo 2 bar httpfs by specifying urls in the sql text await c query create table direct as select from https origin remote parquet insert statement or by executing raw insert statements await c query insert into existing_table values 1 foo 2 bar", + "category": "Wasm", + "url": "/docs/api/wasm/data_ingestion", + "blurb": "DuckDB-Wasm has multiple ways to import data, depending on the format of the data. There are two steps to import data..." + }, { "title": "Data Types", "text": "general-purpose data types the table below shows all the built-in general-purpose data types the alternatives listed in the aliases column can be used to refer to these types as well however note that the aliases are not part of the sql standard and hence might not be accepted by other database engines name aliases description --- --- --- bigint int8 long signed eight-byte integer bit bitstring string of 1 s and 0 s boolean bool logical logical boolean true false blob bytea binary varbinary variable-length binary data date calendar date year month day double float8 numeric decimal double precision floating-point number 8 bytes decimal prec scale fixed-precision number with the given width precision and scale hugeint signed sixteen-byte integer integer int4 int signed signed four-byte integer interval date time delta real float4 float single precision floating-point number 4 bytes smallint int2 short signed two-byte integer time time of day no time zone timestamp datetime combination of time and date timestamp with time zone timestamptz combination of time and date that uses the current time zone tinyint int1 signed one-byte integer ubigint unsigned eight-byte integer uinteger unsigned four-byte integer usmallint unsigned two-byte integer utinyint unsigned one-byte integer uuid uuid data type varchar char bpchar text string variable-length character string nested composite types duckdb supports four nested data types list struct map and union each supports different use cases and has a different structure name description rules when used in a column build from values define in ddl create --- --- --- --- --- list an ordered sequence of data values of the same type each row must have the same data type within each list but can have any number of elements 1 2 3 int struct a dictionary of multiple named values where each key is a string but the value can be a different type for each key each row must have the same keys i 42 j a struct i int j varchar map a dictionary of multiple named values each key having the same type and each value having the same type keys and values can be any type and can be different types from one another rows may have different keys map 1 2 a b map int varchar union a union of multiple alternative data types storing one of them in each value at a time a union also contains a discriminator tag value to inspect and access the currently set member type rows may be set to different member types of the union union_value num 2 union num int text varchar nesting list s struct s map s and union s can be arbitrarily nested to any depth so long as the type rules are observed -- struct with lists select birds duck goose heron aliens null amphibians frog toad -- struct with list of maps select test map 1 5 42 1 45 map 1 5 42 1 45 -- a list of unions select union_value num 2 union_value str abc union str varchar num integer links to detailed documentation", @@ -1003,17 +1003,17 @@ }, { "title": "Parquet Import", - "text": "how to run a query directly on a parquet file to run a query directly on a parquet file use the read_parquet function in the from clause of a query select from read_parquet input parquet the parquet file will be processed in parallel filters will be automatically pushed down into the parquet scan and only the relevant columns will be read automatically for more information see the blog post querying parquet with precision using duckdb", + "text": "how to load a parquet file into a table to read data from a parquet file use the read_parquet function in the from clause of a query select from read_parquet input parquet to create a new table using the result from a query use create table as from a select statement create table new_tbl as select from read_parquet input parquet to load data into an existing table from a query use insert into from a select statement insert into tbl select from read_parquet input parquet alternatively the copy statement can also be used to load data from a parquet file into an existing table copy tbl from input parquet format parquet for additional options see the parquet loading reference", "category": "Import", - "url": "/docs/guides/import/query_parquet", - "blurb": "How to run a query directly on a Parquet file To run a query directly on a Parquet file, use the read_parquet..." + "url": "/docs/guides/import/parquet_import", + "blurb": "How to load a Parquet file into a table To read data from a Parquet file, use the read_parquet function in the FROM..." }, { "title": "Parquet Import", - "text": "how to load a parquet file into a table to read data from a parquet file use the read_parquet function in the from clause of a query select from read_parquet input parquet to create a new table using the result from a query use create table as from a select statement create table new_tbl as select from read_parquet input parquet to load data into an existing table from a query use insert into from a select statement insert into tbl select from read_parquet input parquet alternatively the copy statement can also be used to load data from a parquet file into an existing table copy tbl from input parquet format parquet for additional options see the parquet loading reference", + "text": "how to run a query directly on a parquet file to run a query directly on a parquet file use the read_parquet function in the from clause of a query select from read_parquet input parquet the parquet file will be processed in parallel filters will be automatically pushed down into the parquet scan and only the relevant columns will be read automatically for more information see the blog post querying parquet with precision using duckdb", "category": "Import", - "url": "/docs/guides/import/parquet_import", - "blurb": "How to load a Parquet file into a table To read data from a Parquet file, use the read_parquet function in the FROM..." + "url": "/docs/guides/import/query_parquet", + "blurb": "How to run a query directly on a Parquet file To run a query directly on a Parquet file, use the read_parquet..." }, { "title": "Parquet Loading", diff --git a/docs/api/python/reference/index.md b/docs/api/python/reference/index.md index 3e8e634d384..2cfd543d693 100644 --- a/docs/api/python/reference/index.md +++ b/docs/api/python/reference/index.md @@ -393,7 +393,7 @@ title: Python Client API
-from_query(self: duckdb.duckdb.DuckDBPyConnection, query: str, alias: str = '') → duckdb.duckdb.DuckDBPyRelation +from_query(self: duckdb.duckdb.DuckDBPyConnection, query: str, *, alias: str = '', params: object = None) → duckdb.duckdb.DuckDBPyRelation

Run a SQL query. If it is a SELECT statement, create a relation object from the given SQL query, otherwise run the query as-is.

@@ -510,7 +510,7 @@ title: Python Client API
-query(self: duckdb.duckdb.DuckDBPyConnection, query: str, alias: str = '') → duckdb.duckdb.DuckDBPyRelation +query(self: duckdb.duckdb.DuckDBPyConnection, query: str, *, alias: str = '', params: object = None) → duckdb.duckdb.DuckDBPyRelation

Run a SQL query. If it is a SELECT statement, create a relation object from the given SQL query, otherwise run the query as-is.

@@ -599,7 +599,7 @@ title: Python Client API
-sql(self: duckdb.duckdb.DuckDBPyConnection, query: str, alias: str = '') → duckdb.duckdb.DuckDBPyRelation +sql(self: duckdb.duckdb.DuckDBPyConnection, query: str, *, alias: str = '', params: object = None) → duckdb.duckdb.DuckDBPyRelation

Run a SQL query. If it is a SELECT statement, create a relation object from the given SQL query, otherwise run the query as-is.

@@ -2101,18 +2101,10 @@ title: Python Client API
-duckdb.from_query(*args, **kwargs) +duckdb.from_query(query: str, alias: str = '', connection: duckdb.DuckDBPyConnection = None) → duckdb.duckdb.DuckDBPyRelation
-

Overloaded function.

-
    -

  1. from_query(query: str, alias: str = ‘’, connection: duckdb.DuckDBPyConnection = None) -> duckdb.duckdb.DuckDBPyRelation

    2. -
-

Create a relation object from the given SQL query

-
    -

  1. from_query(query: str, alias: str = ‘query_relation’, connection: duckdb.DuckDBPyConnection = None) -> duckdb.duckdb.DuckDBPyRelation

    2. -
-

Create a relation object from the given SQL query

+

Run a SQL query. If it is a SELECT statement, create a relation object from the given SQL query, otherwise run the query as-is.

From 29cca2192b1bf358a0a2671b1b118724a31ec142 Mon Sep 17 00:00:00 2001 From: GitHub Actions Date: Mon, 14 Aug 2023 05:05:27 +0000 Subject: [PATCH 04/12] chore: auto update docs --- data/search_data.json | 4 ++-- docs/api/c/api.md | 38 ++++++++++++++++++++++++++++++++++++++ docs/api/c/prepared.md | 15 +++++++++++++++ 3 files changed, 55 insertions(+), 2 deletions(-) diff --git a/data/search_data.json b/data/search_data.json index 04ef28bcf0c..4ad30daadb3 100644 --- a/data/search_data.json +++ b/data/search_data.json @@ -163,7 +163,7 @@ }, { "title": "C API - Complete API", - "text": "api reference open connect syntax path to the database file on disk or nullptr or memory to open an in-memory database out_database the result database object returns duckdbsuccess on success or duckdberror on failure duckdb_open_ext extended version of duckdb_open creates a new database or opens an existing database file stored at the the given path syntax path to the database file on disk or nullptr or memory to open an in-memory database out_database the result database object config optional configuration used to start up the database system out_error if set and the function returns duckdberror this will contain the reason why the start-up failed note that the error must be freed using duckdb_free returns duckdbsuccess on success or duckdberror on failure duckdb_close closes the specified database and de-allocates all memory allocated for that database this should be called after you are done with any database allocated through duckdb_open note that failing to call duckdb_close in case of e g a program crash will not cause data corruption still it is recommended to always correctly close a database object after you are done with it syntax the database object to shut down duckdb_connect opens a connection to a database connections are required to query the database and store transactional state associated with the connection the instantiated connection should be closed using duckdb_disconnect syntax the database file to connect to out_connection the result connection object returns duckdbsuccess on success or duckdberror on failure duckdb_interrupt interrupt running query syntax the connection to interruot duckdb_query_progress get progress of the running query syntax the working connection returns -1 if no progress or a percentage of the progress duckdb_disconnect closes the specified connection and de-allocates all memory allocated for that connection syntax the connection to close duckdb_library_version returns the version of the linked duckdb with a version postfix for dev versions usually used for developing c extensions that must return this for a compatibility check syntax duckdb_create_config initializes an empty configuration object that can be used to provide start-up options for the duckdb instance through duckdb_open_ext this will always succeed unless there is a malloc failure syntax the result configuration object returns duckdbsuccess on success or duckdberror on failure duckdb_config_count this returns the total amount of configuration options available for usage with duckdb_get_config_flag this should not be called in a loop as it internally loops over all the options syntax the amount of config options available duckdb_get_config_flag obtains a human-readable name and description of a specific configuration option this can be used to e g display configuration options this will succeed unless index is out of range i e duckdb_config_count the result name or description must not be freed syntax the index of the configuration option between 0 and duckdb_config_count out_name a name of the configuration flag out_description a description of the configuration flag returns duckdbsuccess on success or duckdberror on failure duckdb_set_config sets the specified option for the specified configuration the configuration option is indicated by name to obtain a list of config options see duckdb_get_config_flag in the source code configuration options are defined in config cpp this can fail if either the name is invalid or if the value provided for the option is invalid syntax the configuration object to set the option on name the name of the configuration flag to set option the value to set the configuration flag to returns duckdbsuccess on success or duckdberror on failure duckdb_destroy_config destroys the specified configuration option and de-allocates all memory allocated for the object syntax the configuration object to destroy duckdb_query executes a sql query within a connection and stores the full materialized result in the out_result pointer if the query fails to execute duckdberror is returned and the error message can be retrieved by calling duckdb_result_error note that after running duckdb_query duckdb_destroy_result must be called on the result object even if the query fails otherwise the error stored within the result will not be freed correctly syntax the connection to perform the query in query the sql query to run out_result the query result returns duckdbsuccess on success or duckdberror on failure duckdb_destroy_result closes the result and de-allocates all memory allocated for that connection syntax the result to destroy duckdb_column_name returns the column name of the specified column the result should not need be freed the column names will automatically be destroyed when the result is destroyed returns null if the column is out of range syntax the result object to fetch the column name from col the column index returns the column name of the specified column duckdb_column_type returns the column type of the specified column returns duckdb_type_invalid if the column is out of range syntax the result object to fetch the column type from col the column index returns the column type of the specified column duckdb_column_logical_type returns the logical column type of the specified column the return type of this call should be destroyed with duckdb_destroy_logical_type returns null if the column is out of range syntax the result object to fetch the column type from col the column index returns the logical column type of the specified column duckdb_column_count returns the number of columns present in a the result object syntax the result object returns the number of columns present in the result object duckdb_row_count returns the number of rows present in a the result object syntax the result object returns the number of rows present in the result object duckdb_rows_changed returns the number of rows changed by the query stored in the result this is relevant only for insert update delete queries for other queries the rows_changed will be 0 syntax the result object returns the number of rows changed duckdb_column_data deprecated prefer using duckdb_result_get_chunk instead returns the data of a specific column of a result in columnar format the function returns a dense array which contains the result data the exact type stored in the array depends on the corresponding duckdb_type as provided by duckdb_column_type for the exact type by which the data should be accessed see the comments in the types section or the duckdb_type enum for example for a column of type duckdb_type_integer rows can be accessed in the following manner int32_t data int32_t duckdb_column_data result 0 printf data for row d d n row data row syntax the result object to fetch the column data from col the column index returns the column data of the specified column duckdb_nullmask_data deprecated prefer using duckdb_result_get_chunk instead returns the nullmask of a specific column of a result in columnar format the nullmask indicates for every row whether or not the corresponding row is null if a row is null the values present in the array provided by duckdb_column_data are undefined int32_t data int32_t duckdb_column_data result 0 bool nullmask duckdb_nullmask_data result 0 if nullmask row printf data for row d null n row else printf data for row d d n row data row syntax the result object to fetch the nullmask from col the column index returns the nullmask of the specified column duckdb_result_error returns the error message contained within the result the error is only set if duckdb_query returns duckdberror the result of this function must not be freed it will be cleaned up when duckdb_destroy_result is called syntax the result object to fetch the error from returns the error of the result duckdb_result_get_chunk fetches a data chunk from the duckdb_result this function should be called repeatedly until the result is exhausted the result must be destroyed with duckdb_destroy_data_chunk this function supersedes all duckdb_value functions as well as the duckdb_column_data and duckdb_nullmask_data functions it results in significantly better performance and should be preferred in newer code-bases if this function is used none of the other result functions can be used and vice versa i e this function cannot be mixed with the legacy result functions use duckdb_result_chunk_count to figure out how many chunks there are in the result syntax the result object to fetch the data chunk from chunk_index the chunk index to fetch from returns the resulting data chunk returns null if the chunk index is out of bounds duckdb_result_is_streaming checks if the type of the internal result is streamqueryresult syntax the result object to check returns whether or not the result object is of the type streamqueryresult duckdb_result_chunk_count returns the number of data chunks present in the result syntax the result object returns number of data chunks present in the result duckdb_value_boolean syntax the boolean value at the specified location or false if the value cannot be converted duckdb_value_int8 syntax the int8_t value at the specified location or 0 if the value cannot be converted duckdb_value_int16 syntax the int16_t value at the specified location or 0 if the value cannot be converted duckdb_value_int32 syntax the int32_t value at the specified location or 0 if the value cannot be converted duckdb_value_int64 syntax the int64_t value at the specified location or 0 if the value cannot be converted duckdb_value_hugeint syntax the duckdb_hugeint value at the specified location or 0 if the value cannot be converted duckdb_value_decimal syntax the duckdb_decimal value at the specified location or 0 if the value cannot be converted duckdb_value_uint8 syntax the uint8_t value at the specified location or 0 if the value cannot be converted duckdb_value_uint16 syntax the uint16_t value at the specified location or 0 if the value cannot be converted duckdb_value_uint32 syntax the uint32_t value at the specified location or 0 if the value cannot be converted duckdb_value_uint64 syntax the uint64_t value at the specified location or 0 if the value cannot be converted duckdb_value_float syntax the float value at the specified location or 0 if the value cannot be converted duckdb_value_double syntax the double value at the specified location or 0 if the value cannot be converted duckdb_value_date syntax the duckdb_date value at the specified location or 0 if the value cannot be converted duckdb_value_time syntax the duckdb_time value at the specified location or 0 if the value cannot be converted duckdb_value_timestamp syntax the duckdb_timestamp value at the specified location or 0 if the value cannot be converted duckdb_value_interval syntax the duckdb_interval value at the specified location or 0 if the value cannot be converted duckdb_value_varchar syntax use duckdb_value_string instead this function does not work correctly if the string contains null bytes returns the text value at the specified location as a null-terminated string or nullptr if the value cannot be converted the result must be freed with duckdb_free duckdb_value_varchar_internal syntax use duckdb_value_string_internal instead this function does not work correctly if the string contains null bytes returns the char value at the specified location only works on varchar columns and does not auto-cast if the column is not a varchar column this function will return null the result must not be freed duckdb_value_string_internal syntax use duckdb_value_string_internal instead this function does not work correctly if the string contains null bytes returns the char value at the specified location only works on varchar columns and does not auto-cast if the column is not a varchar column this function will return null the result must not be freed duckdb_value_blob syntax the duckdb_blob value at the specified location returns a blob with blob data set to nullptr if the value cannot be converted the resulting blob data must be freed with duckdb_free duckdb_value_is_null syntax returns true if the value at the specified index is null and false otherwise duckdb_malloc allocate size bytes of memory using the duckdb internal malloc function any memory allocated in this manner should be freed using duckdb_free syntax the number of bytes to allocate returns a pointer to the allocated memory region duckdb_free free a value returned from duckdb_malloc duckdb_value_varchar or duckdb_value_blob syntax the memory region to de-allocate duckdb_vector_size the internal vector size used by duckdb this is the amount of tuples that will fit into a data chunk created by duckdb_create_data_chunk syntax the vector size duckdb_string_is_inlined whether or not the duckdb_string_t value is inlined this means that the data of the string does not have a separate allocation syntax duckdb_from_date decompose a duckdb_date object into year month and date stored as duckdb_date_struct syntax the date object as obtained from a duckdb_type_date column returns the duckdb_date_struct with the decomposed elements duckdb_to_date re-compose a duckdb_date from year month and date duckdb_date_struct syntax the year month and date stored in a duckdb_date_struct returns the duckdb_date element duckdb_from_time decompose a duckdb_time object into hour minute second and microsecond stored as duckdb_time_struct syntax the time object as obtained from a duckdb_type_time column returns the duckdb_time_struct with the decomposed elements duckdb_to_time re-compose a duckdb_time from hour minute second and microsecond duckdb_time_struct syntax the hour minute second and microsecond in a duckdb_time_struct returns the duckdb_time element duckdb_from_timestamp decompose a duckdb_timestamp object into a duckdb_timestamp_struct syntax the ts object as obtained from a duckdb_type_timestamp column returns the duckdb_timestamp_struct with the decomposed elements duckdb_to_timestamp re-compose a duckdb_timestamp from a duckdb_timestamp_struct syntax the de-composed elements in a duckdb_timestamp_struct returns the duckdb_timestamp element duckdb_hugeint_to_double converts a duckdb_hugeint object as obtained from a duckdb_type_hugeint column into a double syntax the hugeint value returns the converted double element duckdb_double_to_hugeint converts a double value to a duckdb_hugeint object if the conversion fails because the double value is too big the result will be 0 syntax the double value returns the converted duckdb_hugeint element duckdb_double_to_decimal converts a double value to a duckdb_decimal object if the conversion fails because the double value is too big or the width scale are invalid the result will be 0 syntax the double value returns the converted duckdb_decimal element duckdb_decimal_to_double converts a duckdb_decimal object as obtained from a duckdb_type_decimal column into a double syntax the decimal value returns the converted double element duckdb_prepare create a prepared statement object from a query note that after calling duckdb_prepare the prepared statement should always be destroyed using duckdb_destroy_prepare even if the prepare fails if the prepare fails duckdb_prepare_error can be called to obtain the reason why the prepare failed syntax the connection object query the sql query to prepare out_prepared_statement the resulting prepared statement object returns duckdbsuccess on success or duckdberror on failure duckdb_destroy_prepare closes the prepared statement and de-allocates all memory allocated for the statement syntax the prepared statement to destroy duckdb_prepare_error returns the error message associated with the given prepared statement if the prepared statement has no error message this returns nullptr instead the error message should not be freed it will be de-allocated when duckdb_destroy_prepare is called syntax the prepared statement to obtain the error from returns the error message or nullptr if there is none duckdb_nparams returns the number of parameters that can be provided to the given prepared statement returns 0 if the query was not successfully prepared syntax the prepared statement to obtain the number of parameters for duckdb_param_type returns the parameter type for the parameter at the given index returns duckdb_type_invalid if the parameter index is out of range or the statement was not successfully prepared syntax the prepared statement param_idx the parameter index returns the parameter type duckdb_clear_bindings clear the params bind to the prepared statement syntax duckdb_bind_boolean binds a bool value to the prepared statement at the specified index syntax duckdb_bind_int8 binds an int8_t value to the prepared statement at the specified index syntax duckdb_bind_int16 binds an int16_t value to the prepared statement at the specified index syntax duckdb_bind_int32 binds an int32_t value to the prepared statement at the specified index syntax duckdb_bind_int64 binds an int64_t value to the prepared statement at the specified index syntax duckdb_bind_hugeint binds an duckdb_hugeint value to the prepared statement at the specified index syntax duckdb_bind_decimal binds a duckdb_decimal value to the prepared statement at the specified index syntax duckdb_bind_uint8 binds an uint8_t value to the prepared statement at the specified index syntax duckdb_bind_uint16 binds an uint16_t value to the prepared statement at the specified index syntax duckdb_bind_uint32 binds an uint32_t value to the prepared statement at the specified index syntax duckdb_bind_uint64 binds an uint64_t value to the prepared statement at the specified index syntax duckdb_bind_float binds an float value to the prepared statement at the specified index syntax duckdb_bind_double binds an double value to the prepared statement at the specified index syntax duckdb_bind_date binds a duckdb_date value to the prepared statement at the specified index syntax duckdb_bind_time binds a duckdb_time value to the prepared statement at the specified index syntax duckdb_bind_timestamp binds a duckdb_timestamp value to the prepared statement at the specified index syntax duckdb_bind_interval binds a duckdb_interval value to the prepared statement at the specified index syntax duckdb_bind_varchar binds a null-terminated varchar value to the prepared statement at the specified index syntax duckdb_bind_varchar_length binds a varchar value to the prepared statement at the specified index syntax duckdb_bind_blob binds a blob value to the prepared statement at the specified index syntax duckdb_bind_null binds a null value to the prepared statement at the specified index syntax duckdb_execute_prepared executes the prepared statement with the given bound parameters and returns a materialized query result this method can be called multiple times for each prepared statement and the parameters can be modified between calls to this function syntax the prepared statement to execute out_result the query result returns duckdbsuccess on success or duckdberror on failure duckdb_execute_prepared_arrow executes the prepared statement with the given bound parameters and returns an arrow query result syntax the prepared statement to execute out_result the query result returns duckdbsuccess on success or duckdberror on failure duckdb_arrow_scan scans the arrow stream and creates a view with the given name syntax the connection on which to execute the scan table_name name of the temporary view to create arrow arrow stream wrapper returns duckdbsuccess on success or duckdberror on failure duckdb_arrow_array_scan scans the arrow array and creates a view with the given name syntax the connection on which to execute the scan table_name name of the temporary view to create arrow_schema arrow schema wrapper arrow_array arrow array wrapper out_stream output array stream that wraps around the passed schema for releasing deleting once done returns duckdbsuccess on success or duckdberror on failure duckdb_extract_statements extract all statements from a query note that after calling duckdb_extract_statements the extracted statements should always be destroyed using duckdb_destroy_extracted even if no statements were extracted if the extract fails duckdb_extract_statements_error can be called to obtain the reason why the extract failed syntax the connection object query the sql query to extract out_extracted_statements the resulting extracted statements object returns the number of extracted statements or 0 on failure duckdb_prepare_extracted_statement prepare an extracted statement note that after calling duckdb_prepare_extracted_statement the prepared statement should always be destroyed using duckdb_destroy_prepare even if the prepare fails if the prepare fails duckdb_prepare_error can be called to obtain the reason why the prepare failed syntax the connection object extracted_statements the extracted statements object index the index of the extracted statement to prepare out_prepared_statement the resulting prepared statement object returns duckdbsuccess on success or duckdberror on failure duckdb_extract_statements_error returns the error message contained within the extracted statements the result of this function must not be freed it will be cleaned up when duckdb_destroy_extracted is called syntax the extracted statements to fetch the error from returns the error of the extracted statements duckdb_destroy_extracted de-allocates all memory allocated for the extracted statements syntax the extracted statements to destroy duckdb_pending_prepared executes the prepared statement with the given bound parameters and returns a pending result the pending result represents an intermediate structure for a query that is not yet fully executed the pending result can be used to incrementally execute a query returning control to the client between tasks note that after calling duckdb_pending_prepared the pending result should always be destroyed using duckdb_destroy_pending even if this function returns duckdberror syntax the prepared statement to execute out_result the pending query result returns duckdbsuccess on success or duckdberror on failure duckdb_pending_prepared_streaming executes the prepared statement with the given bound parameters and returns a pending result this pending result will create a streaming duckdb_result when executed the pending result represents an intermediate structure for a query that is not yet fully executed note that after calling duckdb_pending_prepared_streaming the pending result should always be destroyed using duckdb_destroy_pending even if this function returns duckdberror syntax the prepared statement to execute out_result the pending query result returns duckdbsuccess on success or duckdberror on failure duckdb_destroy_pending closes the pending result and de-allocates all memory allocated for the result syntax the pending result to destroy duckdb_pending_error returns the error message contained within the pending result the result of this function must not be freed it will be cleaned up when duckdb_destroy_pending is called syntax the pending result to fetch the error from returns the error of the pending result duckdb_pending_execute_task executes a single task within the query returning whether or not the query is ready if this returns duckdb_pending_result_ready the duckdb_execute_pending function can be called to obtain the result if this returns duckdb_pending_result_not_ready the duckdb_pending_execute_task function should be called again if this returns duckdb_pending_error an error occurred during execution the error message can be obtained by calling duckdb_pending_error on the pending_result syntax the pending result to execute a task within returns the state of the pending result after the execution duckdb_execute_pending fully execute a pending query result returning the final query result if duckdb_pending_execute_task has been called until duckdb_pending_result_ready was returned this will return fast otherwise all remaining tasks must be executed first syntax the pending result to execute out_result the result object returns duckdbsuccess on success or duckdberror on failure duckdb_destroy_value destroys the value and de-allocates all memory allocated for that type syntax the value to destroy duckdb_create_varchar creates a value from a null-terminated string syntax the null-terminated string returns the value this must be destroyed with duckdb_destroy_value duckdb_create_varchar_length creates a value from a string syntax the text length the length of the text returns the value this must be destroyed with duckdb_destroy_value duckdb_create_int64 creates a value from an int64 syntax the bigint value returns the value this must be destroyed with duckdb_destroy_value duckdb_get_varchar obtains a string representation of the given value the result must be destroyed with duckdb_free syntax the value returns the string value this must be destroyed with duckdb_free duckdb_get_int64 obtains an int64 of the given value syntax the value returns the int64 value or 0 if no conversion is possible duckdb_create_logical_type creates a duckdb_logical_type from a standard primitive type the resulting type should be destroyed with duckdb_destroy_logical_type this should not be used with duckdb_type_decimal syntax the primitive type to create returns the logical type duckdb_create_list_type creates a list type from its child type the resulting type should be destroyed with duckdb_destroy_logical_type syntax the child type of list type to create returns the logical type duckdb_create_map_type creates a map type from its key type and value type the resulting type should be destroyed with duckdb_destroy_logical_type syntax the key type and value type of map type to create returns the logical type duckdb_create_union_type creates a union type from the passed types array the resulting type should be destroyed with duckdb_destroy_logical_type syntax the array of types that the union should consist of type_amount the size of the types array returns the logical type duckdb_create_decimal_type creates a duckdb_logical_type of type decimal with the specified width and scale the resulting type should be destroyed with duckdb_destroy_logical_type syntax the width of the decimal type scale the scale of the decimal type returns the logical type duckdb_get_type_id retrieves the type class of a duckdb_logical_type syntax the logical type object returns the type id duckdb_decimal_width retrieves the width of a decimal type syntax the logical type object returns the width of the decimal type duckdb_decimal_scale retrieves the scale of a decimal type syntax the logical type object returns the scale of the decimal type duckdb_decimal_internal_type retrieves the internal storage type of a decimal type syntax the logical type object returns the internal type of the decimal type duckdb_enum_internal_type retrieves the internal storage type of an enum type syntax the logical type object returns the internal type of the enum type duckdb_enum_dictionary_size retrieves the dictionary size of the enum type syntax the logical type object returns the dictionary size of the enum type duckdb_enum_dictionary_value retrieves the dictionary value at the specified position from the enum the result must be freed with duckdb_free syntax the logical type object index the index in the dictionary returns the string value of the enum type must be freed with duckdb_free duckdb_list_type_child_type retrieves the child type of the given list type the result must be freed with duckdb_destroy_logical_type syntax the logical type object returns the child type of the list type must be destroyed with duckdb_destroy_logical_type duckdb_map_type_key_type retrieves the key type of the given map type the result must be freed with duckdb_destroy_logical_type syntax the logical type object returns the key type of the map type must be destroyed with duckdb_destroy_logical_type duckdb_map_type_value_type retrieves the value type of the given map type the result must be freed with duckdb_destroy_logical_type syntax the logical type object returns the value type of the map type must be destroyed with duckdb_destroy_logical_type duckdb_struct_type_child_count returns the number of children of a struct type syntax the logical type object returns the number of children of a struct type duckdb_struct_type_child_name retrieves the name of the struct child the result must be freed with duckdb_free syntax the logical type object index the child index returns the name of the struct type must be freed with duckdb_free duckdb_struct_type_child_type retrieves the child type of the given struct type at the specified index the result must be freed with duckdb_destroy_logical_type syntax the logical type object index the child index returns the child type of the struct type must be destroyed with duckdb_destroy_logical_type duckdb_union_type_member_count returns the number of members that the union type has syntax the logical type union object returns the number of members of a union type duckdb_union_type_member_name retrieves the name of the union member the result must be freed with duckdb_free syntax the logical type object index the child index returns the name of the union member must be freed with duckdb_free duckdb_union_type_member_type retrieves the child type of the given union member at the specified index the result must be freed with duckdb_destroy_logical_type syntax the logical type object index the child index returns the child type of the union member must be destroyed with duckdb_destroy_logical_type duckdb_destroy_logical_type destroys the logical type and de-allocates all memory allocated for that type syntax the logical type to destroy duckdb_create_data_chunk creates an empty datachunk with the specified set of types syntax an array of types of the data chunk column_count the number of columns returns the data chunk duckdb_destroy_data_chunk destroys the data chunk and de-allocates all memory allocated for that chunk syntax the data chunk to destroy duckdb_data_chunk_reset resets a data chunk clearing the validity masks and setting the cardinality of the data chunk to 0 syntax the data chunk to reset duckdb_data_chunk_get_column_count retrieves the number of columns in a data chunk syntax the data chunk to get the data from returns the number of columns in the data chunk duckdb_data_chunk_get_vector retrieves the vector at the specified column index in the data chunk the pointer to the vector is valid for as long as the chunk is alive it does not need to be destroyed syntax the data chunk to get the data from returns the vector duckdb_data_chunk_get_size retrieves the current number of tuples in a data chunk syntax the data chunk to get the data from returns the number of tuples in the data chunk duckdb_data_chunk_set_size sets the current number of tuples in a data chunk syntax the data chunk to set the size in size the number of tuples in the data chunk duckdb_vector_get_column_type retrieves the column type of the specified vector the result must be destroyed with duckdb_destroy_logical_type syntax the vector get the data from returns the type of the vector duckdb_vector_get_data retrieves the data pointer of the vector the data pointer can be used to read or write values from the vector how to read or write values depends on the type of the vector syntax the vector to get the data from returns the data pointer duckdb_vector_get_validity retrieves the validity mask pointer of the specified vector if all values are valid this function might return null the validity mask is a bitset that signifies null-ness within the data chunk it is a series of uint64_t values where each uint64_t value contains validity for 64 tuples the bit is set to 1 if the value is valid i e not null or 0 if the value is invalid i e null validity of a specific value can be obtained like this idx_t entry_idx row_idx 64 idx_t idx_in_entry row_idx 64 bool is_valid validity_mask entry_idx 1 idx_in_entry alternatively the slower duckdb_validity_row_is_valid function can be used syntax the vector to get the data from returns the pointer to the validity mask or null if no validity mask is present duckdb_vector_ensure_validity_writable ensures the validity mask is writable by allocating it after this function is called duckdb_vector_get_validity will always return non-null this allows null values to be written to the vector regardless of whether a validity mask was present before syntax the vector to alter duckdb_vector_assign_string_element assigns a string element in the vector at the specified location syntax the vector to alter index the row position in the vector to assign the string to str the null-terminated string duckdb_vector_assign_string_element_len assigns a string element in the vector at the specified location syntax the vector to alter index the row position in the vector to assign the string to str the string str_len the length of the string in bytes duckdb_list_vector_get_child retrieves the child vector of a list vector the resulting vector is valid as long as the parent vector is valid syntax the vector returns the child vector duckdb_list_vector_get_size returns the size of the child vector of the list syntax the vector returns the size of the child list duckdb_list_vector_set_size sets the total size of the underlying child-vector of a list vector syntax the list vector size the size of the child list returns the duckdb state returns duckdberror if the vector is nullptr duckdb_list_vector_reserve sets the total capacity of the underlying child-vector of a list syntax the list vector required_capacity the total capacity to reserve return the duckdb state returns duckdberror if the vector is nullptr duckdb_struct_vector_get_child retrieves the child vector of a struct vector the resulting vector is valid as long as the parent vector is valid syntax the vector index the child index returns the child vector duckdb_validity_row_is_valid returns whether or not a row is valid i e not null in the given validity mask syntax the validity mask as obtained through duckdb_data_chunk_get_validity row the row index returns true if the row is valid false otherwise duckdb_validity_set_row_validity in a validity mask sets a specific row to either valid or invalid note that duckdb_data_chunk_ensure_validity_writable should be called before calling duckdb_data_chunk_get_validity to ensure that there is a validity mask to write to syntax the validity mask as obtained through duckdb_data_chunk_get_validity row the row index valid whether or not to set the row to valid or invalid duckdb_validity_set_row_invalid in a validity mask sets a specific row to invalid equivalent to duckdb_validity_set_row_validity with valid set to false syntax the validity mask row the row index duckdb_validity_set_row_valid in a validity mask sets a specific row to valid equivalent to duckdb_validity_set_row_validity with valid set to true syntax the validity mask row the row index duckdb_create_table_function creates a new empty table function the return value should be destroyed with duckdb_destroy_table_function syntax the table function object duckdb_destroy_table_function destroys the given table function object syntax the table function to destroy duckdb_table_function_set_name sets the name of the given table function syntax the table function name the name of the table function duckdb_table_function_add_parameter adds a parameter to the table function syntax 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 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 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 the table function bind the bind function duckdb_table_function_set_init sets the init function of the table function syntax the table function init the init function duckdb_table_function_set_local_init sets the thread-local init function of the table function syntax the table function init the init function duckdb_table_function_set_function sets the main function of the table function syntax 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 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 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 the info object returns the extra info duckdb_bind_add_result_column adds a result column to the output of the table function syntax 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 the info object returns the init data object duckdb_function_set_error report that an error has occurred while executing the function syntax the info object error the error message duckdb_add_replacement_scan add a replacement scan definition to the specified database syntax the database object to add the replacement scan to replacement the replacement scan callback extra_data extra data that is passed back into the specified callback delete_callback the delete callback to call on the extra data if any duckdb_replacement_scan_set_function_name sets the replacement function name to use if this function is called in the replacement callback the replacement scan is performed if it is not called the replacement callback is not performed syntax the info object function_name the function name to substitute duckdb_replacement_scan_add_parameter adds a parameter to the replacement scan function syntax the info object parameter the parameter to add duckdb_replacement_scan_set_error report that an error has occurred while executing the replacement scan syntax the info object error the error message duckdb_appender_create creates an appender object syntax the connection context to create the appender in schema the schema of the table to append to or nullptr for the default schema table the table name to append to out_appender the resulting appender object returns duckdbsuccess on success or duckdberror on failure duckdb_appender_error returns the error message associated with the given appender if the appender has no error message this returns nullptr instead the error message should not be freed it will be de-allocated when duckdb_appender_destroy is called syntax the appender to get the error from returns the error message or nullptr if there is none duckdb_appender_flush flush the appender to the table forcing the cache of the appender to be cleared and the data to be appended to the base table this should generally not be used unless you know what you are doing instead call duckdb_appender_destroy when you are done with the appender syntax the appender to flush returns duckdbsuccess on success or duckdberror on failure duckdb_appender_close close the appender flushing all intermediate state in the appender to the table and closing it for further appends this is generally not necessary call duckdb_appender_destroy instead syntax the appender to flush and close returns duckdbsuccess on success or duckdberror on failure duckdb_appender_destroy close the appender and destroy it flushing all intermediate state in the appender to the table and de-allocating all memory associated with the appender syntax the appender to flush close and destroy returns duckdbsuccess on success or duckdberror on failure duckdb_appender_begin_row a nop function provided for backwards compatibility reasons does nothing only duckdb_appender_end_row is required syntax duckdb_appender_end_row finish the current row of appends after end_row is called the next row can be appended syntax the appender returns duckdbsuccess on success or duckdberror on failure duckdb_append_bool append a bool value to the appender syntax duckdb_append_int8 append an int8_t value to the appender syntax duckdb_append_int16 append an int16_t value to the appender syntax duckdb_append_int32 append an int32_t value to the appender syntax duckdb_append_int64 append an int64_t value to the appender syntax duckdb_append_hugeint append a duckdb_hugeint value to the appender syntax duckdb_append_uint8 append a uint8_t value to the appender syntax duckdb_append_uint16 append a uint16_t value to the appender syntax duckdb_append_uint32 append a uint32_t value to the appender syntax duckdb_append_uint64 append a uint64_t value to the appender syntax duckdb_append_float append a float value to the appender syntax duckdb_append_double append a double value to the appender syntax duckdb_append_date append a duckdb_date value to the appender syntax duckdb_append_time append a duckdb_time value to the appender syntax duckdb_append_timestamp append a duckdb_timestamp value to the appender syntax duckdb_append_interval append a duckdb_interval value to the appender syntax duckdb_append_varchar append a varchar value to the appender syntax duckdb_append_varchar_length append a varchar value to the appender syntax duckdb_append_blob append a blob value to the appender syntax duckdb_append_null append a null value to the appender of any type syntax duckdb_append_data_chunk appends a pre-filled data chunk to the specified appender the types of the data chunk must exactly match the types of the table no casting is performed if the types do not match or the appender is in an invalid state duckdberror is returned if the append is successful duckdbsuccess is returned syntax the appender to append to chunk the data chunk to append returns the return state duckdb_query_arrow executes a sql query within a connection and stores the full materialized result in an arrow structure if the query fails to execute duckdberror is returned and the error message can be retrieved by calling duckdb_query_arrow_error note that after running duckdb_query_arrow duckdb_destroy_arrow must be called on the result object even if the query fails otherwise the error stored within the result will not be freed correctly syntax the connection to perform the query in query the sql query to run out_result the query result returns duckdbsuccess on success or duckdberror on failure duckdb_query_arrow_schema fetch the internal arrow schema from the arrow result syntax the result to fetch the schema from out_schema the output schema returns duckdbsuccess on success or duckdberror on failure duckdb_query_arrow_array fetch an internal arrow array from the arrow result this function can be called multiple time to get next chunks which will free the previous out_array so consume the out_array before calling this function again syntax the result to fetch the array from out_array the output array returns duckdbsuccess on success or duckdberror on failure duckdb_arrow_column_count returns the number of columns present in a the arrow result object syntax the result object returns the number of columns present in the result object duckdb_arrow_row_count returns the number of rows present in a the arrow result object syntax the result object returns the number of rows present in the result object duckdb_arrow_rows_changed returns the number of rows changed by the query stored in the arrow result this is relevant only for insert update delete queries for other queries the rows_changed will be 0 syntax the result object returns the number of rows changed duckdb_query_arrow_error returns the error message contained within the result the error is only set if duckdb_query_arrow returns duckdberror the error message should not be freed it will be de-allocated when duckdb_destroy_arrow is called syntax the result object to fetch the nullmask from returns the error of the result duckdb_destroy_arrow closes the result and de-allocates all memory allocated for the arrow result syntax the result to destroy duckdb_execute_tasks execute duckdb tasks on this thread will return after max_tasks have been executed or if there are no more tasks present syntax the database object to execute tasks for max_tasks the maximum amount of tasks to execute duckdb_create_task_state creates a task state that can be used with duckdb_execute_tasks_state to execute tasks until duckdb_finish_execution is called on the state duckdb_destroy_state should be called on the result in order to free memory syntax the database object to create the task state for returns the task state that can be used with duckdb_execute_tasks_state duckdb_execute_tasks_state execute duckdb tasks on this thread the thread will keep on executing tasks forever until duckdb_finish_execution is called on the state multiple threads can share the same duckdb_task_state syntax the task state of the executor duckdb_execute_n_tasks_state execute duckdb tasks on this thread the thread will keep on executing tasks until either duckdb_finish_execution is called on the state max_tasks tasks have been executed or there are no more tasks to be executed multiple threads can share the same duckdb_task_state syntax the task state of the executor max_tasks the maximum amount of tasks to execute returns the amount of tasks that have actually been executed duckdb_finish_execution finish execution on a specific task syntax the task state to finish execution duckdb_task_state_is_finished check if the provided duckdb_task_state has finished execution syntax the task state to inspect returns whether or not duckdb_finish_execution has been called on the task state duckdb_destroy_task_state destroys the task state returned from duckdb_create_task_state note that this should not be called while there is an active duckdb_execute_tasks_state running on the task state syntax the task state to clean up duckdb_execution_is_finished returns true if execution of the current query is finished syntax the connection on which to check duckdb_stream_fetch_chunk fetches a data chunk from the streaming duckdb_result this function should be called repeatedly until the result is exhausted the result must be destroyed with duckdb_destroy_data_chunk this function can only be used on duckdb_results created with duckdb_pending_prepared_streaming if this function is used none of the other result functions can be used and vice versa i e this function cannot be mixed with the legacy result functions or the materialized result functions it is not known beforehand how many chunks will be returned by this result syntax the result object to fetch the data chunk from returns the resulting data chunk returns null if the result has an error", + "text": "api reference open connect syntax path to the database file on disk or nullptr or memory to open an in-memory database out_database the result database object returns duckdbsuccess on success or duckdberror on failure duckdb_open_ext extended version of duckdb_open creates a new database or opens an existing database file stored at the the given path syntax path to the database file on disk or nullptr or memory to open an in-memory database out_database the result database object config optional configuration used to start up the database system out_error if set and the function returns duckdberror this will contain the reason why the start-up failed note that the error must be freed using duckdb_free returns duckdbsuccess on success or duckdberror on failure duckdb_close closes the specified database and de-allocates all memory allocated for that database this should be called after you are done with any database allocated through duckdb_open note that failing to call duckdb_close in case of e g a program crash will not cause data corruption still it is recommended to always correctly close a database object after you are done with it syntax the database object to shut down duckdb_connect opens a connection to a database connections are required to query the database and store transactional state associated with the connection the instantiated connection should be closed using duckdb_disconnect syntax the database file to connect to out_connection the result connection object returns duckdbsuccess on success or duckdberror on failure duckdb_interrupt interrupt running query syntax the connection to interruot duckdb_query_progress get progress of the running query syntax the working connection returns -1 if no progress or a percentage of the progress duckdb_disconnect closes the specified connection and de-allocates all memory allocated for that connection syntax the connection to close duckdb_library_version returns the version of the linked duckdb with a version postfix for dev versions usually used for developing c extensions that must return this for a compatibility check syntax duckdb_create_config initializes an empty configuration object that can be used to provide start-up options for the duckdb instance through duckdb_open_ext this will always succeed unless there is a malloc failure syntax the result configuration object returns duckdbsuccess on success or duckdberror on failure duckdb_config_count this returns the total amount of configuration options available for usage with duckdb_get_config_flag this should not be called in a loop as it internally loops over all the options syntax the amount of config options available duckdb_get_config_flag obtains a human-readable name and description of a specific configuration option this can be used to e g display configuration options this will succeed unless index is out of range i e duckdb_config_count the result name or description must not be freed syntax the index of the configuration option between 0 and duckdb_config_count out_name a name of the configuration flag out_description a description of the configuration flag returns duckdbsuccess on success or duckdberror on failure duckdb_set_config sets the specified option for the specified configuration the configuration option is indicated by name to obtain a list of config options see duckdb_get_config_flag in the source code configuration options are defined in config cpp this can fail if either the name is invalid or if the value provided for the option is invalid syntax the configuration object to set the option on name the name of the configuration flag to set option the value to set the configuration flag to returns duckdbsuccess on success or duckdberror on failure duckdb_destroy_config destroys the specified configuration option and de-allocates all memory allocated for the object syntax the configuration object to destroy duckdb_query executes a sql query within a connection and stores the full materialized result in the out_result pointer if the query fails to execute duckdberror is returned and the error message can be retrieved by calling duckdb_result_error note that after running duckdb_query duckdb_destroy_result must be called on the result object even if the query fails otherwise the error stored within the result will not be freed correctly syntax the connection to perform the query in query the sql query to run out_result the query result returns duckdbsuccess on success or duckdberror on failure duckdb_destroy_result closes the result and de-allocates all memory allocated for that connection syntax the result to destroy duckdb_column_name returns the column name of the specified column the result should not need be freed the column names will automatically be destroyed when the result is destroyed returns null if the column is out of range syntax the result object to fetch the column name from col the column index returns the column name of the specified column duckdb_column_type returns the column type of the specified column returns duckdb_type_invalid if the column is out of range syntax the result object to fetch the column type from col the column index returns the column type of the specified column duckdb_column_logical_type returns the logical column type of the specified column the return type of this call should be destroyed with duckdb_destroy_logical_type returns null if the column is out of range syntax the result object to fetch the column type from col the column index returns the logical column type of the specified column duckdb_column_count returns the number of columns present in a the result object syntax the result object returns the number of columns present in the result object duckdb_row_count returns the number of rows present in a the result object syntax the result object returns the number of rows present in the result object duckdb_rows_changed returns the number of rows changed by the query stored in the result this is relevant only for insert update delete queries for other queries the rows_changed will be 0 syntax the result object returns the number of rows changed duckdb_column_data deprecated prefer using duckdb_result_get_chunk instead returns the data of a specific column of a result in columnar format the function returns a dense array which contains the result data the exact type stored in the array depends on the corresponding duckdb_type as provided by duckdb_column_type for the exact type by which the data should be accessed see the comments in the types section or the duckdb_type enum for example for a column of type duckdb_type_integer rows can be accessed in the following manner int32_t data int32_t duckdb_column_data result 0 printf data for row d d n row data row syntax the result object to fetch the column data from col the column index returns the column data of the specified column duckdb_nullmask_data deprecated prefer using duckdb_result_get_chunk instead returns the nullmask of a specific column of a result in columnar format the nullmask indicates for every row whether or not the corresponding row is null if a row is null the values present in the array provided by duckdb_column_data are undefined int32_t data int32_t duckdb_column_data result 0 bool nullmask duckdb_nullmask_data result 0 if nullmask row printf data for row d null n row else printf data for row d d n row data row syntax the result object to fetch the nullmask from col the column index returns the nullmask of the specified column duckdb_result_error returns the error message contained within the result the error is only set if duckdb_query returns duckdberror the result of this function must not be freed it will be cleaned up when duckdb_destroy_result is called syntax the result object to fetch the error from returns the error of the result duckdb_result_get_chunk fetches a data chunk from the duckdb_result this function should be called repeatedly until the result is exhausted the result must be destroyed with duckdb_destroy_data_chunk this function supersedes all duckdb_value functions as well as the duckdb_column_data and duckdb_nullmask_data functions it results in significantly better performance and should be preferred in newer code-bases if this function is used none of the other result functions can be used and vice versa i e this function cannot be mixed with the legacy result functions use duckdb_result_chunk_count to figure out how many chunks there are in the result syntax the result object to fetch the data chunk from chunk_index the chunk index to fetch from returns the resulting data chunk returns null if the chunk index is out of bounds duckdb_result_is_streaming checks if the type of the internal result is streamqueryresult syntax the result object to check returns whether or not the result object is of the type streamqueryresult duckdb_result_chunk_count returns the number of data chunks present in the result syntax the result object returns number of data chunks present in the result duckdb_value_boolean syntax the boolean value at the specified location or false if the value cannot be converted duckdb_value_int8 syntax the int8_t value at the specified location or 0 if the value cannot be converted duckdb_value_int16 syntax the int16_t value at the specified location or 0 if the value cannot be converted duckdb_value_int32 syntax the int32_t value at the specified location or 0 if the value cannot be converted duckdb_value_int64 syntax the int64_t value at the specified location or 0 if the value cannot be converted duckdb_value_hugeint syntax the duckdb_hugeint value at the specified location or 0 if the value cannot be converted duckdb_value_decimal syntax the duckdb_decimal value at the specified location or 0 if the value cannot be converted duckdb_value_uint8 syntax the uint8_t value at the specified location or 0 if the value cannot be converted duckdb_value_uint16 syntax the uint16_t value at the specified location or 0 if the value cannot be converted duckdb_value_uint32 syntax the uint32_t value at the specified location or 0 if the value cannot be converted duckdb_value_uint64 syntax the uint64_t value at the specified location or 0 if the value cannot be converted duckdb_value_float syntax the float value at the specified location or 0 if the value cannot be converted duckdb_value_double syntax the double value at the specified location or 0 if the value cannot be converted duckdb_value_date syntax the duckdb_date value at the specified location or 0 if the value cannot be converted duckdb_value_time syntax the duckdb_time value at the specified location or 0 if the value cannot be converted duckdb_value_timestamp syntax the duckdb_timestamp value at the specified location or 0 if the value cannot be converted duckdb_value_interval syntax the duckdb_interval value at the specified location or 0 if the value cannot be converted duckdb_value_varchar syntax use duckdb_value_string instead this function does not work correctly if the string contains null bytes returns the text value at the specified location as a null-terminated string or nullptr if the value cannot be converted the result must be freed with duckdb_free duckdb_value_varchar_internal syntax use duckdb_value_string_internal instead this function does not work correctly if the string contains null bytes returns the char value at the specified location only works on varchar columns and does not auto-cast if the column is not a varchar column this function will return null the result must not be freed duckdb_value_string_internal syntax use duckdb_value_string_internal instead this function does not work correctly if the string contains null bytes returns the char value at the specified location only works on varchar columns and does not auto-cast if the column is not a varchar column this function will return null the result must not be freed duckdb_value_blob syntax the duckdb_blob value at the specified location returns a blob with blob data set to nullptr if the value cannot be converted the resulting blob data must be freed with duckdb_free duckdb_value_is_null syntax returns true if the value at the specified index is null and false otherwise duckdb_malloc allocate size bytes of memory using the duckdb internal malloc function any memory allocated in this manner should be freed using duckdb_free syntax the number of bytes to allocate returns a pointer to the allocated memory region duckdb_free free a value returned from duckdb_malloc duckdb_value_varchar or duckdb_value_blob syntax the memory region to de-allocate duckdb_vector_size the internal vector size used by duckdb this is the amount of tuples that will fit into a data chunk created by duckdb_create_data_chunk syntax the vector size duckdb_string_is_inlined whether or not the duckdb_string_t value is inlined this means that the data of the string does not have a separate allocation syntax duckdb_from_date decompose a duckdb_date object into year month and date stored as duckdb_date_struct syntax the date object as obtained from a duckdb_type_date column returns the duckdb_date_struct with the decomposed elements duckdb_to_date re-compose a duckdb_date from year month and date duckdb_date_struct syntax the year month and date stored in a duckdb_date_struct returns the duckdb_date element duckdb_from_time decompose a duckdb_time object into hour minute second and microsecond stored as duckdb_time_struct syntax the time object as obtained from a duckdb_type_time column returns the duckdb_time_struct with the decomposed elements duckdb_to_time re-compose a duckdb_time from hour minute second and microsecond duckdb_time_struct syntax the hour minute second and microsecond in a duckdb_time_struct returns the duckdb_time element duckdb_from_timestamp decompose a duckdb_timestamp object into a duckdb_timestamp_struct syntax the ts object as obtained from a duckdb_type_timestamp column returns the duckdb_timestamp_struct with the decomposed elements duckdb_to_timestamp re-compose a duckdb_timestamp from a duckdb_timestamp_struct syntax the de-composed elements in a duckdb_timestamp_struct returns the duckdb_timestamp element duckdb_hugeint_to_double converts a duckdb_hugeint object as obtained from a duckdb_type_hugeint column into a double syntax the hugeint value returns the converted double element duckdb_double_to_hugeint converts a double value to a duckdb_hugeint object if the conversion fails because the double value is too big the result will be 0 syntax the double value returns the converted duckdb_hugeint element duckdb_double_to_decimal converts a double value to a duckdb_decimal object if the conversion fails because the double value is too big or the width scale are invalid the result will be 0 syntax the double value returns the converted duckdb_decimal element duckdb_decimal_to_double converts a duckdb_decimal object as obtained from a duckdb_type_decimal column into a double syntax the decimal value returns the converted double element duckdb_prepare create a prepared statement object from a query note that after calling duckdb_prepare the prepared statement should always be destroyed using duckdb_destroy_prepare even if the prepare fails if the prepare fails duckdb_prepare_error can be called to obtain the reason why the prepare failed syntax the connection object query the sql query to prepare out_prepared_statement the resulting prepared statement object returns duckdbsuccess on success or duckdberror on failure duckdb_destroy_prepare closes the prepared statement and de-allocates all memory allocated for the statement syntax the prepared statement to destroy duckdb_prepare_error returns the error message associated with the given prepared statement if the prepared statement has no error message this returns nullptr instead the error message should not be freed it will be de-allocated when duckdb_destroy_prepare is called syntax the prepared statement to obtain the error from returns the error message or nullptr if there is none duckdb_nparams returns the number of parameters that can be provided to the given prepared statement returns 0 if the query was not successfully prepared syntax the prepared statement to obtain the number of parameters for duckdb_param_type returns the parameter type for the parameter at the given index returns duckdb_type_invalid if the parameter index is out of range or the statement was not successfully prepared syntax the prepared statement param_idx the parameter index returns the parameter type duckdb_clear_bindings clear the params bind to the prepared statement syntax duckdb_bind_parameter_index retrieve the index of the parameter for the prepared statement identified by name syntax duckdb_bind_boolean binds a bool value to the prepared statement at the specified index syntax duckdb_bind_int8 binds an int8_t value to the prepared statement at the specified index syntax duckdb_bind_int16 binds an int16_t value to the prepared statement at the specified index syntax duckdb_bind_int32 binds an int32_t value to the prepared statement at the specified index syntax duckdb_bind_int64 binds an int64_t value to the prepared statement at the specified index syntax duckdb_bind_hugeint binds an duckdb_hugeint value to the prepared statement at the specified index syntax duckdb_bind_decimal binds a duckdb_decimal value to the prepared statement at the specified index syntax duckdb_bind_uint8 binds an uint8_t value to the prepared statement at the specified index syntax duckdb_bind_uint16 binds an uint16_t value to the prepared statement at the specified index syntax duckdb_bind_uint32 binds an uint32_t value to the prepared statement at the specified index syntax duckdb_bind_uint64 binds an uint64_t value to the prepared statement at the specified index syntax duckdb_bind_float binds an float value to the prepared statement at the specified index syntax duckdb_bind_double binds an double value to the prepared statement at the specified index syntax duckdb_bind_date binds a duckdb_date value to the prepared statement at the specified index syntax duckdb_bind_time binds a duckdb_time value to the prepared statement at the specified index syntax duckdb_bind_timestamp binds a duckdb_timestamp value to the prepared statement at the specified index syntax duckdb_bind_interval binds a duckdb_interval value to the prepared statement at the specified index syntax duckdb_bind_varchar binds a null-terminated varchar value to the prepared statement at the specified index syntax duckdb_bind_varchar_length binds a varchar value to the prepared statement at the specified index syntax duckdb_bind_blob binds a blob value to the prepared statement at the specified index syntax duckdb_bind_null binds a null value to the prepared statement at the specified index syntax duckdb_execute_prepared executes the prepared statement with the given bound parameters and returns a materialized query result this method can be called multiple times for each prepared statement and the parameters can be modified between calls to this function syntax the prepared statement to execute out_result the query result returns duckdbsuccess on success or duckdberror on failure duckdb_execute_prepared_arrow executes the prepared statement with the given bound parameters and returns an arrow query result syntax the prepared statement to execute out_result the query result returns duckdbsuccess on success or duckdberror on failure duckdb_arrow_scan scans the arrow stream and creates a view with the given name syntax the connection on which to execute the scan table_name name of the temporary view to create arrow arrow stream wrapper returns duckdbsuccess on success or duckdberror on failure duckdb_arrow_array_scan scans the arrow array and creates a view with the given name syntax the connection on which to execute the scan table_name name of the temporary view to create arrow_schema arrow schema wrapper arrow_array arrow array wrapper out_stream output array stream that wraps around the passed schema for releasing deleting once done returns duckdbsuccess on success or duckdberror on failure duckdb_extract_statements extract all statements from a query note that after calling duckdb_extract_statements the extracted statements should always be destroyed using duckdb_destroy_extracted even if no statements were extracted if the extract fails duckdb_extract_statements_error can be called to obtain the reason why the extract failed syntax the connection object query the sql query to extract out_extracted_statements the resulting extracted statements object returns the number of extracted statements or 0 on failure duckdb_prepare_extracted_statement prepare an extracted statement note that after calling duckdb_prepare_extracted_statement the prepared statement should always be destroyed using duckdb_destroy_prepare even if the prepare fails if the prepare fails duckdb_prepare_error can be called to obtain the reason why the prepare failed syntax the connection object extracted_statements the extracted statements object index the index of the extracted statement to prepare out_prepared_statement the resulting prepared statement object returns duckdbsuccess on success or duckdberror on failure duckdb_extract_statements_error returns the error message contained within the extracted statements the result of this function must not be freed it will be cleaned up when duckdb_destroy_extracted is called syntax the extracted statements to fetch the error from returns the error of the extracted statements duckdb_destroy_extracted de-allocates all memory allocated for the extracted statements syntax the extracted statements to destroy duckdb_pending_prepared executes the prepared statement with the given bound parameters and returns a pending result the pending result represents an intermediate structure for a query that is not yet fully executed the pending result can be used to incrementally execute a query returning control to the client between tasks note that after calling duckdb_pending_prepared the pending result should always be destroyed using duckdb_destroy_pending even if this function returns duckdberror syntax the prepared statement to execute out_result the pending query result returns duckdbsuccess on success or duckdberror on failure duckdb_pending_prepared_streaming executes the prepared statement with the given bound parameters and returns a pending result this pending result will create a streaming duckdb_result when executed the pending result represents an intermediate structure for a query that is not yet fully executed note that after calling duckdb_pending_prepared_streaming the pending result should always be destroyed using duckdb_destroy_pending even if this function returns duckdberror syntax the prepared statement to execute out_result the pending query result returns duckdbsuccess on success or duckdberror on failure duckdb_destroy_pending closes the pending result and de-allocates all memory allocated for the result syntax the pending result to destroy duckdb_pending_error returns the error message contained within the pending result the result of this function must not be freed it will be cleaned up when duckdb_destroy_pending is called syntax the pending result to fetch the error from returns the error of the pending result duckdb_pending_execute_task executes a single task within the query returning whether or not the query is ready if this returns duckdb_pending_result_ready the duckdb_execute_pending function can be called to obtain the result if this returns duckdb_pending_result_not_ready the duckdb_pending_execute_task function should be called again if this returns duckdb_pending_error an error occurred during execution the error message can be obtained by calling duckdb_pending_error on the pending_result syntax the pending result to execute a task within returns the state of the pending result after the execution duckdb_execute_pending fully execute a pending query result returning the final query result if duckdb_pending_execute_task has been called until duckdb_pending_result_ready was returned this will return fast otherwise all remaining tasks must be executed first syntax the pending result to execute out_result the result object returns duckdbsuccess on success or duckdberror on failure duckdb_pending_execution_is_finished returns whether a duckdb_pending_state is finished executing for example if pending_state is duckdb_pending_result_ready this function will return true syntax the pending state on which to decide whether to finish execution returns boolean indicating pending execution should be considered finished duckdb_destroy_value destroys the value and de-allocates all memory allocated for that type syntax the value to destroy duckdb_create_varchar creates a value from a null-terminated string syntax the null-terminated string returns the value this must be destroyed with duckdb_destroy_value duckdb_create_varchar_length creates a value from a string syntax the text length the length of the text returns the value this must be destroyed with duckdb_destroy_value duckdb_create_int64 creates a value from an int64 syntax the bigint value returns the value this must be destroyed with duckdb_destroy_value duckdb_get_varchar obtains a string representation of the given value the result must be destroyed with duckdb_free syntax the value returns the string value this must be destroyed with duckdb_free duckdb_get_int64 obtains an int64 of the given value syntax the value returns the int64 value or 0 if no conversion is possible duckdb_create_logical_type creates a duckdb_logical_type from a standard primitive type the resulting type should be destroyed with duckdb_destroy_logical_type this should not be used with duckdb_type_decimal syntax the primitive type to create returns the logical type duckdb_create_list_type creates a list type from its child type the resulting type should be destroyed with duckdb_destroy_logical_type syntax the child type of list type to create returns the logical type duckdb_create_map_type creates a map type from its key type and value type the resulting type should be destroyed with duckdb_destroy_logical_type syntax the key type and value type of map type to create returns the logical type duckdb_create_union_type creates a union type from the passed types array the resulting type should be destroyed with duckdb_destroy_logical_type syntax the array of types that the union should consist of type_amount the size of the types array returns the logical type duckdb_create_decimal_type creates a duckdb_logical_type of type decimal with the specified width and scale the resulting type should be destroyed with duckdb_destroy_logical_type syntax the width of the decimal type scale the scale of the decimal type returns the logical type duckdb_get_type_id retrieves the type class of a duckdb_logical_type syntax the logical type object returns the type id duckdb_decimal_width retrieves the width of a decimal type syntax the logical type object returns the width of the decimal type duckdb_decimal_scale retrieves the scale of a decimal type syntax the logical type object returns the scale of the decimal type duckdb_decimal_internal_type retrieves the internal storage type of a decimal type syntax the logical type object returns the internal type of the decimal type duckdb_enum_internal_type retrieves the internal storage type of an enum type syntax the logical type object returns the internal type of the enum type duckdb_enum_dictionary_size retrieves the dictionary size of the enum type syntax the logical type object returns the dictionary size of the enum type duckdb_enum_dictionary_value retrieves the dictionary value at the specified position from the enum the result must be freed with duckdb_free syntax the logical type object index the index in the dictionary returns the string value of the enum type must be freed with duckdb_free duckdb_list_type_child_type retrieves the child type of the given list type the result must be freed with duckdb_destroy_logical_type syntax the logical type object returns the child type of the list type must be destroyed with duckdb_destroy_logical_type duckdb_map_type_key_type retrieves the key type of the given map type the result must be freed with duckdb_destroy_logical_type syntax the logical type object returns the key type of the map type must be destroyed with duckdb_destroy_logical_type duckdb_map_type_value_type retrieves the value type of the given map type the result must be freed with duckdb_destroy_logical_type syntax the logical type object returns the value type of the map type must be destroyed with duckdb_destroy_logical_type duckdb_struct_type_child_count returns the number of children of a struct type syntax the logical type object returns the number of children of a struct type duckdb_struct_type_child_name retrieves the name of the struct child the result must be freed with duckdb_free syntax the logical type object index the child index returns the name of the struct type must be freed with duckdb_free duckdb_struct_type_child_type retrieves the child type of the given struct type at the specified index the result must be freed with duckdb_destroy_logical_type syntax the logical type object index the child index returns the child type of the struct type must be destroyed with duckdb_destroy_logical_type duckdb_union_type_member_count returns the number of members that the union type has syntax the logical type union object returns the number of members of a union type duckdb_union_type_member_name retrieves the name of the union member the result must be freed with duckdb_free syntax the logical type object index the child index returns the name of the union member must be freed with duckdb_free duckdb_union_type_member_type retrieves the child type of the given union member at the specified index the result must be freed with duckdb_destroy_logical_type syntax the logical type object index the child index returns the child type of the union member must be destroyed with duckdb_destroy_logical_type duckdb_destroy_logical_type destroys the logical type and de-allocates all memory allocated for that type syntax the logical type to destroy duckdb_create_data_chunk creates an empty datachunk with the specified set of types syntax an array of types of the data chunk column_count the number of columns returns the data chunk duckdb_destroy_data_chunk destroys the data chunk and de-allocates all memory allocated for that chunk syntax the data chunk to destroy duckdb_data_chunk_reset resets a data chunk clearing the validity masks and setting the cardinality of the data chunk to 0 syntax the data chunk to reset duckdb_data_chunk_get_column_count retrieves the number of columns in a data chunk syntax the data chunk to get the data from returns the number of columns in the data chunk duckdb_data_chunk_get_vector retrieves the vector at the specified column index in the data chunk the pointer to the vector is valid for as long as the chunk is alive it does not need to be destroyed syntax the data chunk to get the data from returns the vector duckdb_data_chunk_get_size retrieves the current number of tuples in a data chunk syntax the data chunk to get the data from returns the number of tuples in the data chunk duckdb_data_chunk_set_size sets the current number of tuples in a data chunk syntax the data chunk to set the size in size the number of tuples in the data chunk duckdb_vector_get_column_type retrieves the column type of the specified vector the result must be destroyed with duckdb_destroy_logical_type syntax the vector get the data from returns the type of the vector duckdb_vector_get_data retrieves the data pointer of the vector the data pointer can be used to read or write values from the vector how to read or write values depends on the type of the vector syntax the vector to get the data from returns the data pointer duckdb_vector_get_validity retrieves the validity mask pointer of the specified vector if all values are valid this function might return null the validity mask is a bitset that signifies null-ness within the data chunk it is a series of uint64_t values where each uint64_t value contains validity for 64 tuples the bit is set to 1 if the value is valid i e not null or 0 if the value is invalid i e null validity of a specific value can be obtained like this idx_t entry_idx row_idx 64 idx_t idx_in_entry row_idx 64 bool is_valid validity_mask entry_idx 1 idx_in_entry alternatively the slower duckdb_validity_row_is_valid function can be used syntax the vector to get the data from returns the pointer to the validity mask or null if no validity mask is present duckdb_vector_ensure_validity_writable ensures the validity mask is writable by allocating it after this function is called duckdb_vector_get_validity will always return non-null this allows null values to be written to the vector regardless of whether a validity mask was present before syntax the vector to alter duckdb_vector_assign_string_element assigns a string element in the vector at the specified location syntax the vector to alter index the row position in the vector to assign the string to str the null-terminated string duckdb_vector_assign_string_element_len assigns a string element in the vector at the specified location syntax the vector to alter index the row position in the vector to assign the string to str the string str_len the length of the string in bytes duckdb_list_vector_get_child retrieves the child vector of a list vector the resulting vector is valid as long as the parent vector is valid syntax the vector returns the child vector duckdb_list_vector_get_size returns the size of the child vector of the list syntax the vector returns the size of the child list duckdb_list_vector_set_size sets the total size of the underlying child-vector of a list vector syntax the list vector size the size of the child list returns the duckdb state returns duckdberror if the vector is nullptr duckdb_list_vector_reserve sets the total capacity of the underlying child-vector of a list syntax the list vector required_capacity the total capacity to reserve return the duckdb state returns duckdberror if the vector is nullptr duckdb_struct_vector_get_child retrieves the child vector of a struct vector the resulting vector is valid as long as the parent vector is valid syntax the vector index the child index returns the child vector duckdb_validity_row_is_valid returns whether or not a row is valid i e not null in the given validity mask syntax the validity mask as obtained through duckdb_data_chunk_get_validity row the row index returns true if the row is valid false otherwise duckdb_validity_set_row_validity in a validity mask sets a specific row to either valid or invalid note that duckdb_data_chunk_ensure_validity_writable should be called before calling duckdb_data_chunk_get_validity to ensure that there is a validity mask to write to syntax the validity mask as obtained through duckdb_data_chunk_get_validity row the row index valid whether or not to set the row to valid or invalid duckdb_validity_set_row_invalid in a validity mask sets a specific row to invalid equivalent to duckdb_validity_set_row_validity with valid set to false syntax the validity mask row the row index duckdb_validity_set_row_valid in a validity mask sets a specific row to valid equivalent to duckdb_validity_set_row_validity with valid set to true syntax the validity mask row the row index duckdb_create_table_function creates a new empty table function the return value should be destroyed with duckdb_destroy_table_function syntax the table function object duckdb_destroy_table_function destroys the given table function object syntax the table function to destroy duckdb_table_function_set_name sets the name of the given table function syntax the table function name the name of the table function duckdb_table_function_add_parameter adds a parameter to the table function syntax 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 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 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 the table function bind the bind function duckdb_table_function_set_init sets the init function of the table function syntax the table function init the init function duckdb_table_function_set_local_init sets the thread-local init function of the table function syntax the table function init the init function duckdb_table_function_set_function sets the main function of the table function syntax 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 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 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 the info object returns the extra info duckdb_bind_add_result_column adds a result column to the output of the table function syntax 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 the info object returns the init data object duckdb_function_set_error report that an error has occurred while executing the function syntax the info object error the error message duckdb_add_replacement_scan add a replacement scan definition to the specified database syntax the database object to add the replacement scan to replacement the replacement scan callback extra_data extra data that is passed back into the specified callback delete_callback the delete callback to call on the extra data if any duckdb_replacement_scan_set_function_name sets the replacement function name to use if this function is called in the replacement callback the replacement scan is performed if it is not called the replacement callback is not performed syntax the info object function_name the function name to substitute duckdb_replacement_scan_add_parameter adds a parameter to the replacement scan function syntax the info object parameter the parameter to add duckdb_replacement_scan_set_error report that an error has occurred while executing the replacement scan syntax the info object error the error message duckdb_appender_create creates an appender object syntax the connection context to create the appender in schema the schema of the table to append to or nullptr for the default schema table the table name to append to out_appender the resulting appender object returns duckdbsuccess on success or duckdberror on failure duckdb_appender_error returns the error message associated with the given appender if the appender has no error message this returns nullptr instead the error message should not be freed it will be de-allocated when duckdb_appender_destroy is called syntax the appender to get the error from returns the error message or nullptr if there is none duckdb_appender_flush flush the appender to the table forcing the cache of the appender to be cleared and the data to be appended to the base table this should generally not be used unless you know what you are doing instead call duckdb_appender_destroy when you are done with the appender syntax the appender to flush returns duckdbsuccess on success or duckdberror on failure duckdb_appender_close close the appender flushing all intermediate state in the appender to the table and closing it for further appends this is generally not necessary call duckdb_appender_destroy instead syntax the appender to flush and close returns duckdbsuccess on success or duckdberror on failure duckdb_appender_destroy close the appender and destroy it flushing all intermediate state in the appender to the table and de-allocating all memory associated with the appender syntax the appender to flush close and destroy returns duckdbsuccess on success or duckdberror on failure duckdb_appender_begin_row a nop function provided for backwards compatibility reasons does nothing only duckdb_appender_end_row is required syntax duckdb_appender_end_row finish the current row of appends after end_row is called the next row can be appended syntax the appender returns duckdbsuccess on success or duckdberror on failure duckdb_append_bool append a bool value to the appender syntax duckdb_append_int8 append an int8_t value to the appender syntax duckdb_append_int16 append an int16_t value to the appender syntax duckdb_append_int32 append an int32_t value to the appender syntax duckdb_append_int64 append an int64_t value to the appender syntax duckdb_append_hugeint append a duckdb_hugeint value to the appender syntax duckdb_append_uint8 append a uint8_t value to the appender syntax duckdb_append_uint16 append a uint16_t value to the appender syntax duckdb_append_uint32 append a uint32_t value to the appender syntax duckdb_append_uint64 append a uint64_t value to the appender syntax duckdb_append_float append a float value to the appender syntax duckdb_append_double append a double value to the appender syntax duckdb_append_date append a duckdb_date value to the appender syntax duckdb_append_time append a duckdb_time value to the appender syntax duckdb_append_timestamp append a duckdb_timestamp value to the appender syntax duckdb_append_interval append a duckdb_interval value to the appender syntax duckdb_append_varchar append a varchar value to the appender syntax duckdb_append_varchar_length append a varchar value to the appender syntax duckdb_append_blob append a blob value to the appender syntax duckdb_append_null append a null value to the appender of any type syntax duckdb_append_data_chunk appends a pre-filled data chunk to the specified appender the types of the data chunk must exactly match the types of the table no casting is performed if the types do not match or the appender is in an invalid state duckdberror is returned if the append is successful duckdbsuccess is returned syntax the appender to append to chunk the data chunk to append returns the return state duckdb_query_arrow executes a sql query within a connection and stores the full materialized result in an arrow structure if the query fails to execute duckdberror is returned and the error message can be retrieved by calling duckdb_query_arrow_error note that after running duckdb_query_arrow duckdb_destroy_arrow must be called on the result object even if the query fails otherwise the error stored within the result will not be freed correctly syntax the connection to perform the query in query the sql query to run out_result the query result returns duckdbsuccess on success or duckdberror on failure duckdb_query_arrow_schema fetch the internal arrow schema from the arrow result syntax the result to fetch the schema from out_schema the output schema returns duckdbsuccess on success or duckdberror on failure duckdb_query_arrow_array fetch an internal arrow array from the arrow result this function can be called multiple time to get next chunks which will free the previous out_array so consume the out_array before calling this function again syntax the result to fetch the array from out_array the output array returns duckdbsuccess on success or duckdberror on failure duckdb_arrow_column_count returns the number of columns present in a the arrow result object syntax the result object returns the number of columns present in the result object duckdb_arrow_row_count returns the number of rows present in a the arrow result object syntax the result object returns the number of rows present in the result object duckdb_arrow_rows_changed returns the number of rows changed by the query stored in the arrow result this is relevant only for insert update delete queries for other queries the rows_changed will be 0 syntax the result object returns the number of rows changed duckdb_query_arrow_error returns the error message contained within the result the error is only set if duckdb_query_arrow returns duckdberror the error message should not be freed it will be de-allocated when duckdb_destroy_arrow is called syntax the result object to fetch the nullmask from returns the error of the result duckdb_destroy_arrow closes the result and de-allocates all memory allocated for the arrow result syntax the result to destroy duckdb_execute_tasks execute duckdb tasks on this thread will return after max_tasks have been executed or if there are no more tasks present syntax the database object to execute tasks for max_tasks the maximum amount of tasks to execute duckdb_create_task_state creates a task state that can be used with duckdb_execute_tasks_state to execute tasks until duckdb_finish_execution is called on the state duckdb_destroy_state should be called on the result in order to free memory syntax the database object to create the task state for returns the task state that can be used with duckdb_execute_tasks_state duckdb_execute_tasks_state execute duckdb tasks on this thread the thread will keep on executing tasks forever until duckdb_finish_execution is called on the state multiple threads can share the same duckdb_task_state syntax the task state of the executor duckdb_execute_n_tasks_state execute duckdb tasks on this thread the thread will keep on executing tasks until either duckdb_finish_execution is called on the state max_tasks tasks have been executed or there are no more tasks to be executed multiple threads can share the same duckdb_task_state syntax the task state of the executor max_tasks the maximum amount of tasks to execute returns the amount of tasks that have actually been executed duckdb_finish_execution finish execution on a specific task syntax the task state to finish execution duckdb_task_state_is_finished check if the provided duckdb_task_state has finished execution syntax the task state to inspect returns whether or not duckdb_finish_execution has been called on the task state duckdb_destroy_task_state destroys the task state returned from duckdb_create_task_state note that this should not be called while there is an active duckdb_execute_tasks_state running on the task state syntax the task state to clean up duckdb_execution_is_finished returns true if execution of the current query is finished syntax the connection on which to check duckdb_stream_fetch_chunk fetches a data chunk from the streaming duckdb_result this function should be called repeatedly until the result is exhausted the result must be destroyed with duckdb_destroy_data_chunk this function can only be used on duckdb_results created with duckdb_pending_prepared_streaming if this function is used none of the other result functions can be used and vice versa i e this function cannot be mixed with the legacy result functions or the materialized result functions it is not known beforehand how many chunks will be returned by this result syntax the result object to fetch the data chunk from returns the resulting data chunk returns null if the result has an error", "category": "C", "url": "/docs/api/c/api", "blurb": "API Reference Open/Connect Syntax Path to the database file on disk, or nullptr or :memory: to open an in-memory..." @@ -191,7 +191,7 @@ }, { "title": "C API - Prepared Statements", - "text": "a prepared statement is a parameterized query the query is prepared with question marks or dollar symbols 1 indicating the parameters of the query values can then be bound to these parameters after which the prepared statement can be executed using those parameters a single query can be prepared once and executed many times prepared statements are useful to easily supply parameters to functions while avoiding string concatenation sql injection attacks speeding up queries that will be executed many times with different parameters duckdb supports prepared statements in the c api with the duckdb_prepare method the duckdb_bind family of functions is used to supply values for subsequent execution of the prepared statement using duckdb_execute_prepared after we are done with the prepared statement it can be cleaned up using the duckdb_destroy_prepare method example duckdb_prepared_statement stmt duckdb_result result if duckdb_prepare con insert into integers values 1 2 stmt duckdberror handle error duckdb_bind_int32 stmt 1 42 the parameter index starts counting at 1 duckdb_bind_int32 stmt 2 43 null as second parameter means no result set is requested duckdb_execute_prepared stmt null duckdb_destroy_prepare stmt we can also query result sets using prepared statements if duckdb_prepare con select from integers where i stmt duckdberror handle error duckdb_bind_int32 stmt 1 42 duckdb_execute_prepared stmt result do something with result clean up duckdb_destroy_result result duckdb_destroy_prepare stmt after calling duckdb_prepare the prepared statement parameters can be inspected using duckdb_nparams and duckdb_param_type in case the prepare fails the error can be obtained through duckdb_prepare_error it is not required that the duckdb_bind family of functions matches the prepared statement parameter type exactly the values will be auto-cast to the required value as required for example calling duckdb_bind_int8 on a parameter type of duckdb_type_integer will work as expected do not use prepared statements to insert large amounts of data into duckdb instead it is recommended to use the appender api reference note that after calling duckdb_prepare the prepared statement should always be destroyed using duckdb_destroy_prepare even if the prepare fails if the prepare fails duckdb_prepare_error can be called to obtain the reason why the prepare failed syntax the connection object query the sql query to prepare out_prepared_statement the resulting prepared statement object returns duckdbsuccess on success or duckdberror on failure duckdb_destroy_prepare closes the prepared statement and de-allocates all memory allocated for the statement syntax the prepared statement to destroy duckdb_prepare_error returns the error message associated with the given prepared statement if the prepared statement has no error message this returns nullptr instead the error message should not be freed it will be de-allocated when duckdb_destroy_prepare is called syntax the prepared statement to obtain the error from returns the error message or nullptr if there is none duckdb_nparams returns the number of parameters that can be provided to the given prepared statement returns 0 if the query was not successfully prepared syntax the prepared statement to obtain the number of parameters for duckdb_param_type returns the parameter type for the parameter at the given index returns duckdb_type_invalid if the parameter index is out of range or the statement was not successfully prepared syntax the prepared statement param_idx the parameter index returns the parameter type duckdb_clear_bindings clear the params bind to the prepared statement syntax duckdb_bind_boolean binds a bool value to the prepared statement at the specified index syntax duckdb_bind_int8 binds an int8_t value to the prepared statement at the specified index syntax duckdb_bind_int16 binds an int16_t value to the prepared statement at the specified index syntax duckdb_bind_int32 binds an int32_t value to the prepared statement at the specified index syntax duckdb_bind_int64 binds an int64_t value to the prepared statement at the specified index syntax duckdb_bind_hugeint binds an duckdb_hugeint value to the prepared statement at the specified index syntax duckdb_bind_decimal binds a duckdb_decimal value to the prepared statement at the specified index syntax duckdb_bind_uint8 binds an uint8_t value to the prepared statement at the specified index syntax duckdb_bind_uint16 binds an uint16_t value to the prepared statement at the specified index syntax duckdb_bind_uint32 binds an uint32_t value to the prepared statement at the specified index syntax duckdb_bind_uint64 binds an uint64_t value to the prepared statement at the specified index syntax duckdb_bind_float binds an float value to the prepared statement at the specified index syntax duckdb_bind_double binds an double value to the prepared statement at the specified index syntax duckdb_bind_date binds a duckdb_date value to the prepared statement at the specified index syntax duckdb_bind_time binds a duckdb_time value to the prepared statement at the specified index syntax duckdb_bind_timestamp binds a duckdb_timestamp value to the prepared statement at the specified index syntax duckdb_bind_interval binds a duckdb_interval value to the prepared statement at the specified index syntax duckdb_bind_varchar binds a null-terminated varchar value to the prepared statement at the specified index syntax duckdb_bind_varchar_length binds a varchar value to the prepared statement at the specified index syntax duckdb_bind_blob binds a blob value to the prepared statement at the specified index syntax duckdb_bind_null binds a null value to the prepared statement at the specified index syntax duckdb_execute_prepared executes the prepared statement with the given bound parameters and returns a materialized query result this method can be called multiple times for each prepared statement and the parameters can be modified between calls to this function syntax the prepared statement to execute out_result the query result returns duckdbsuccess on success or duckdberror on failure duckdb_execute_prepared_arrow executes the prepared statement with the given bound parameters and returns an arrow query result syntax the prepared statement to execute out_result the query result returns duckdbsuccess on success or duckdberror on failure duckdb_arrow_scan scans the arrow stream and creates a view with the given name syntax the connection on which to execute the scan table_name name of the temporary view to create arrow arrow stream wrapper returns duckdbsuccess on success or duckdberror on failure duckdb_arrow_array_scan scans the arrow array and creates a view with the given name syntax the connection on which to execute the scan table_name name of the temporary view to create arrow_schema arrow schema wrapper arrow_array arrow array wrapper out_stream output array stream that wraps around the passed schema for releasing deleting once done returns duckdbsuccess on success or duckdberror on failure", + "text": "a prepared statement is a parameterized query the query is prepared with question marks or dollar symbols 1 indicating the parameters of the query values can then be bound to these parameters after which the prepared statement can be executed using those parameters a single query can be prepared once and executed many times prepared statements are useful to easily supply parameters to functions while avoiding string concatenation sql injection attacks speeding up queries that will be executed many times with different parameters duckdb supports prepared statements in the c api with the duckdb_prepare method the duckdb_bind family of functions is used to supply values for subsequent execution of the prepared statement using duckdb_execute_prepared after we are done with the prepared statement it can be cleaned up using the duckdb_destroy_prepare method example duckdb_prepared_statement stmt duckdb_result result if duckdb_prepare con insert into integers values 1 2 stmt duckdberror handle error duckdb_bind_int32 stmt 1 42 the parameter index starts counting at 1 duckdb_bind_int32 stmt 2 43 null as second parameter means no result set is requested duckdb_execute_prepared stmt null duckdb_destroy_prepare stmt we can also query result sets using prepared statements if duckdb_prepare con select from integers where i stmt duckdberror handle error duckdb_bind_int32 stmt 1 42 duckdb_execute_prepared stmt result do something with result clean up duckdb_destroy_result result duckdb_destroy_prepare stmt after calling duckdb_prepare the prepared statement parameters can be inspected using duckdb_nparams and duckdb_param_type in case the prepare fails the error can be obtained through duckdb_prepare_error it is not required that the duckdb_bind family of functions matches the prepared statement parameter type exactly the values will be auto-cast to the required value as required for example calling duckdb_bind_int8 on a parameter type of duckdb_type_integer will work as expected do not use prepared statements to insert large amounts of data into duckdb instead it is recommended to use the appender api reference note that after calling duckdb_prepare the prepared statement should always be destroyed using duckdb_destroy_prepare even if the prepare fails if the prepare fails duckdb_prepare_error can be called to obtain the reason why the prepare failed syntax the connection object query the sql query to prepare out_prepared_statement the resulting prepared statement object returns duckdbsuccess on success or duckdberror on failure duckdb_destroy_prepare closes the prepared statement and de-allocates all memory allocated for the statement syntax the prepared statement to destroy duckdb_prepare_error returns the error message associated with the given prepared statement if the prepared statement has no error message this returns nullptr instead the error message should not be freed it will be de-allocated when duckdb_destroy_prepare is called syntax the prepared statement to obtain the error from returns the error message or nullptr if there is none duckdb_nparams returns the number of parameters that can be provided to the given prepared statement returns 0 if the query was not successfully prepared syntax the prepared statement to obtain the number of parameters for duckdb_param_type returns the parameter type for the parameter at the given index returns duckdb_type_invalid if the parameter index is out of range or the statement was not successfully prepared syntax the prepared statement param_idx the parameter index returns the parameter type duckdb_clear_bindings clear the params bind to the prepared statement syntax duckdb_bind_parameter_index retrieve the index of the parameter for the prepared statement identified by name syntax duckdb_bind_boolean binds a bool value to the prepared statement at the specified index syntax duckdb_bind_int8 binds an int8_t value to the prepared statement at the specified index syntax duckdb_bind_int16 binds an int16_t value to the prepared statement at the specified index syntax duckdb_bind_int32 binds an int32_t value to the prepared statement at the specified index syntax duckdb_bind_int64 binds an int64_t value to the prepared statement at the specified index syntax duckdb_bind_hugeint binds an duckdb_hugeint value to the prepared statement at the specified index syntax duckdb_bind_decimal binds a duckdb_decimal value to the prepared statement at the specified index syntax duckdb_bind_uint8 binds an uint8_t value to the prepared statement at the specified index syntax duckdb_bind_uint16 binds an uint16_t value to the prepared statement at the specified index syntax duckdb_bind_uint32 binds an uint32_t value to the prepared statement at the specified index syntax duckdb_bind_uint64 binds an uint64_t value to the prepared statement at the specified index syntax duckdb_bind_float binds an float value to the prepared statement at the specified index syntax duckdb_bind_double binds an double value to the prepared statement at the specified index syntax duckdb_bind_date binds a duckdb_date value to the prepared statement at the specified index syntax duckdb_bind_time binds a duckdb_time value to the prepared statement at the specified index syntax duckdb_bind_timestamp binds a duckdb_timestamp value to the prepared statement at the specified index syntax duckdb_bind_interval binds a duckdb_interval value to the prepared statement at the specified index syntax duckdb_bind_varchar binds a null-terminated varchar value to the prepared statement at the specified index syntax duckdb_bind_varchar_length binds a varchar value to the prepared statement at the specified index syntax duckdb_bind_blob binds a blob value to the prepared statement at the specified index syntax duckdb_bind_null binds a null value to the prepared statement at the specified index syntax duckdb_execute_prepared executes the prepared statement with the given bound parameters and returns a materialized query result this method can be called multiple times for each prepared statement and the parameters can be modified between calls to this function syntax the prepared statement to execute out_result the query result returns duckdbsuccess on success or duckdberror on failure duckdb_execute_prepared_arrow executes the prepared statement with the given bound parameters and returns an arrow query result syntax the prepared statement to execute out_result the query result returns duckdbsuccess on success or duckdberror on failure duckdb_arrow_scan scans the arrow stream and creates a view with the given name syntax the connection on which to execute the scan table_name name of the temporary view to create arrow arrow stream wrapper returns duckdbsuccess on success or duckdberror on failure duckdb_arrow_array_scan scans the arrow array and creates a view with the given name syntax the connection on which to execute the scan table_name name of the temporary view to create arrow_schema arrow schema wrapper arrow_array arrow array wrapper out_stream output array stream that wraps around the passed schema for releasing deleting once done returns duckdbsuccess on success or duckdberror on failure", "category": "C", "url": "/docs/api/c/prepared", "blurb": "A prepared statement is a parameterized query. The query is prepared with question marks ( ? ) or dollar symbols ( $1..." diff --git a/docs/api/c/api.md b/docs/api/c/api.md index 713afc2da49..49cb6700fa7 100644 --- a/docs/api/c/api.md +++ b/docs/api/c/api.md @@ -91,6 +91,7 @@ selected: API Reference idx_t duckdb_nparams(duckdb_prepared_statement prepared_statement); duckdb_type duckdb_param_type(duckdb_prepared_statement prepared_statement, idx_t param_idx); duckdb_state duckdb_clear_bindings(duckdb_prepared_statement prepared_statement); +duckdb_state duckdb_bind_parameter_index(duckdb_prepared_statement prepared_statement, idx_t *param_idx_out, const char *name); duckdb_state duckdb_bind_boolean(duckdb_prepared_statement prepared_statement, idx_t param_idx, bool val); duckdb_state duckdb_bind_int8(duckdb_prepared_statement prepared_statement, idx_t param_idx, int8_t val); duckdb_state duckdb_bind_int16(duckdb_prepared_statement prepared_statement, idx_t param_idx, int16_t val); @@ -130,6 +131,7 @@ selected: API Reference const char *duckdb_pending_error(duckdb_pending_result pending_result); duckdb_pending_state duckdb_pending_execute_task(duckdb_pending_result pending_result); duckdb_state duckdb_execute_pending(duckdb_pending_result pending_result, duckdb_result *out_result); +bool duckdb_pending_execution_is_finished(duckdb_pending_state pending_state); ### **Value Interface** 
void duckdb_destroy_value(duckdb_value *value);
@@ -1813,6 +1815,20 @@ Clear the params bind to the prepared statement.

+### duckdb_bind_parameter_index +--- +Retrieve the index of the parameter for the prepared statement, identified by name + +#### Syntax +--- +
duckdb_state duckdb_bind_parameter_index(
+  duckdb_prepared_statement prepared_statement,
+  idx_t *param_idx_out,
+  const char *name
+);
+
+
+ ### duckdb_bind_boolean --- Binds a bool value to the prepared statement at the specified index. @@ -2487,6 +2503,28 @@ The result object.
+### duckdb_pending_execution_is_finished +--- +Returns whether a duckdb_pending_state is finished executing. For example if `pending_state` is +DUCKDB_PENDING_RESULT_READY, this function will return true. + +#### Syntax +--- +
bool duckdb_pending_execution_is_finished(
+  duckdb_pending_state pending_state
+);
+
+#### Parameters +--- +* `pending_state` + +The pending state on which to decide whether to finish execution. +* `returns` + +Boolean indicating pending execution should be considered finished. + +
+ ### duckdb_destroy_value --- Destroys the value and de-allocates all memory allocated for that type. diff --git a/docs/api/c/prepared.md b/docs/api/c/prepared.md index f1c64f109fc..79ea6d3879d 100644 --- a/docs/api/c/prepared.md +++ b/docs/api/c/prepared.md @@ -53,6 +53,7 @@ It is not required that the `duckdb_bind` family of functions matches the prepar idx_t duckdb_nparams(duckdb_prepared_statement prepared_statement); duckdb_type duckdb_param_type(duckdb_prepared_statement prepared_statement, idx_t param_idx); duckdb_state duckdb_clear_bindings(duckdb_prepared_statement prepared_statement); +duckdb_state duckdb_bind_parameter_index(duckdb_prepared_statement prepared_statement, idx_t *param_idx_out, const char *name); duckdb_state duckdb_bind_boolean(duckdb_prepared_statement prepared_statement, idx_t param_idx, bool val); duckdb_state duckdb_bind_int8(duckdb_prepared_statement prepared_statement, idx_t param_idx, int8_t val); duckdb_state duckdb_bind_int16(duckdb_prepared_statement prepared_statement, idx_t param_idx, int16_t val); @@ -214,6 +215,20 @@ Clear the params bind to the prepared statement.
+### duckdb_bind_parameter_index +--- +Retrieve the index of the parameter for the prepared statement, identified by name + +#### Syntax +--- +
duckdb_state duckdb_bind_parameter_index(
+  duckdb_prepared_statement prepared_statement,
+  idx_t *param_idx_out,
+  const char *name
+);
+
+
+ ### duckdb_bind_boolean --- Binds a bool value to the prepared statement at the specified index. From a9f7bb91d20d8f0d844c1fbfc2d66651c63fc52a Mon Sep 17 00:00:00 2001 From: GitHub Actions Date: Mon, 21 Aug 2023 05:04:57 +0000 Subject: [PATCH 05/12] chore: auto update docs --- data/search_data.json | 8 +- docs/api/c/api.md | 41 +++ docs/api/c/prepared.md | 15 + docs/api/python/reference/index.md | 564 ++++++++++++++--------------- 4 files changed, 342 insertions(+), 286 deletions(-) diff --git a/data/search_data.json b/data/search_data.json index 4ad30daadb3..e4a74def868 100644 --- a/data/search_data.json +++ b/data/search_data.json @@ -163,7 +163,7 @@ }, { "title": "C API - Complete API", - "text": "api reference open connect syntax path to the database file on disk or nullptr or memory to open an in-memory database out_database the result database object returns duckdbsuccess on success or duckdberror on failure duckdb_open_ext extended version of duckdb_open creates a new database or opens an existing database file stored at the the given path syntax path to the database file on disk or nullptr or memory to open an in-memory database out_database the result database object config optional configuration used to start up the database system out_error if set and the function returns duckdberror this will contain the reason why the start-up failed note that the error must be freed using duckdb_free returns duckdbsuccess on success or duckdberror on failure duckdb_close closes the specified database and de-allocates all memory allocated for that database this should be called after you are done with any database allocated through duckdb_open note that failing to call duckdb_close in case of e g a program crash will not cause data corruption still it is recommended to always correctly close a database object after you are done with it syntax the database object to shut down duckdb_connect opens a connection to a database connections are required to query the database and store transactional state associated with the connection the instantiated connection should be closed using duckdb_disconnect syntax the database file to connect to out_connection the result connection object returns duckdbsuccess on success or duckdberror on failure duckdb_interrupt interrupt running query syntax the connection to interruot duckdb_query_progress get progress of the running query syntax the working connection returns -1 if no progress or a percentage of the progress duckdb_disconnect closes the specified connection and de-allocates all memory allocated for that connection syntax the connection to close duckdb_library_version returns the version of the linked duckdb with a version postfix for dev versions usually used for developing c extensions that must return this for a compatibility check syntax duckdb_create_config initializes an empty configuration object that can be used to provide start-up options for the duckdb instance through duckdb_open_ext this will always succeed unless there is a malloc failure syntax the result configuration object returns duckdbsuccess on success or duckdberror on failure duckdb_config_count this returns the total amount of configuration options available for usage with duckdb_get_config_flag this should not be called in a loop as it internally loops over all the options syntax the amount of config options available duckdb_get_config_flag obtains a human-readable name and description of a specific configuration option this can be used to e g display configuration options this will succeed unless index is out of range i e duckdb_config_count the result name or description must not be freed syntax the index of the configuration option between 0 and duckdb_config_count out_name a name of the configuration flag out_description a description of the configuration flag returns duckdbsuccess on success or duckdberror on failure duckdb_set_config sets the specified option for the specified configuration the configuration option is indicated by name to obtain a list of config options see duckdb_get_config_flag in the source code configuration options are defined in config cpp this can fail if either the name is invalid or if the value provided for the option is invalid syntax the configuration object to set the option on name the name of the configuration flag to set option the value to set the configuration flag to returns duckdbsuccess on success or duckdberror on failure duckdb_destroy_config destroys the specified configuration option and de-allocates all memory allocated for the object syntax the configuration object to destroy duckdb_query executes a sql query within a connection and stores the full materialized result in the out_result pointer if the query fails to execute duckdberror is returned and the error message can be retrieved by calling duckdb_result_error note that after running duckdb_query duckdb_destroy_result must be called on the result object even if the query fails otherwise the error stored within the result will not be freed correctly syntax the connection to perform the query in query the sql query to run out_result the query result returns duckdbsuccess on success or duckdberror on failure duckdb_destroy_result closes the result and de-allocates all memory allocated for that connection syntax the result to destroy duckdb_column_name returns the column name of the specified column the result should not need be freed the column names will automatically be destroyed when the result is destroyed returns null if the column is out of range syntax the result object to fetch the column name from col the column index returns the column name of the specified column duckdb_column_type returns the column type of the specified column returns duckdb_type_invalid if the column is out of range syntax the result object to fetch the column type from col the column index returns the column type of the specified column duckdb_column_logical_type returns the logical column type of the specified column the return type of this call should be destroyed with duckdb_destroy_logical_type returns null if the column is out of range syntax the result object to fetch the column type from col the column index returns the logical column type of the specified column duckdb_column_count returns the number of columns present in a the result object syntax the result object returns the number of columns present in the result object duckdb_row_count returns the number of rows present in a the result object syntax the result object returns the number of rows present in the result object duckdb_rows_changed returns the number of rows changed by the query stored in the result this is relevant only for insert update delete queries for other queries the rows_changed will be 0 syntax the result object returns the number of rows changed duckdb_column_data deprecated prefer using duckdb_result_get_chunk instead returns the data of a specific column of a result in columnar format the function returns a dense array which contains the result data the exact type stored in the array depends on the corresponding duckdb_type as provided by duckdb_column_type for the exact type by which the data should be accessed see the comments in the types section or the duckdb_type enum for example for a column of type duckdb_type_integer rows can be accessed in the following manner int32_t data int32_t duckdb_column_data result 0 printf data for row d d n row data row syntax the result object to fetch the column data from col the column index returns the column data of the specified column duckdb_nullmask_data deprecated prefer using duckdb_result_get_chunk instead returns the nullmask of a specific column of a result in columnar format the nullmask indicates for every row whether or not the corresponding row is null if a row is null the values present in the array provided by duckdb_column_data are undefined int32_t data int32_t duckdb_column_data result 0 bool nullmask duckdb_nullmask_data result 0 if nullmask row printf data for row d null n row else printf data for row d d n row data row syntax the result object to fetch the nullmask from col the column index returns the nullmask of the specified column duckdb_result_error returns the error message contained within the result the error is only set if duckdb_query returns duckdberror the result of this function must not be freed it will be cleaned up when duckdb_destroy_result is called syntax the result object to fetch the error from returns the error of the result duckdb_result_get_chunk fetches a data chunk from the duckdb_result this function should be called repeatedly until the result is exhausted the result must be destroyed with duckdb_destroy_data_chunk this function supersedes all duckdb_value functions as well as the duckdb_column_data and duckdb_nullmask_data functions it results in significantly better performance and should be preferred in newer code-bases if this function is used none of the other result functions can be used and vice versa i e this function cannot be mixed with the legacy result functions use duckdb_result_chunk_count to figure out how many chunks there are in the result syntax the result object to fetch the data chunk from chunk_index the chunk index to fetch from returns the resulting data chunk returns null if the chunk index is out of bounds duckdb_result_is_streaming checks if the type of the internal result is streamqueryresult syntax the result object to check returns whether or not the result object is of the type streamqueryresult duckdb_result_chunk_count returns the number of data chunks present in the result syntax the result object returns number of data chunks present in the result duckdb_value_boolean syntax the boolean value at the specified location or false if the value cannot be converted duckdb_value_int8 syntax the int8_t value at the specified location or 0 if the value cannot be converted duckdb_value_int16 syntax the int16_t value at the specified location or 0 if the value cannot be converted duckdb_value_int32 syntax the int32_t value at the specified location or 0 if the value cannot be converted duckdb_value_int64 syntax the int64_t value at the specified location or 0 if the value cannot be converted duckdb_value_hugeint syntax the duckdb_hugeint value at the specified location or 0 if the value cannot be converted duckdb_value_decimal syntax the duckdb_decimal value at the specified location or 0 if the value cannot be converted duckdb_value_uint8 syntax the uint8_t value at the specified location or 0 if the value cannot be converted duckdb_value_uint16 syntax the uint16_t value at the specified location or 0 if the value cannot be converted duckdb_value_uint32 syntax the uint32_t value at the specified location or 0 if the value cannot be converted duckdb_value_uint64 syntax the uint64_t value at the specified location or 0 if the value cannot be converted duckdb_value_float syntax the float value at the specified location or 0 if the value cannot be converted duckdb_value_double syntax the double value at the specified location or 0 if the value cannot be converted duckdb_value_date syntax the duckdb_date value at the specified location or 0 if the value cannot be converted duckdb_value_time syntax the duckdb_time value at the specified location or 0 if the value cannot be converted duckdb_value_timestamp syntax the duckdb_timestamp value at the specified location or 0 if the value cannot be converted duckdb_value_interval syntax the duckdb_interval value at the specified location or 0 if the value cannot be converted duckdb_value_varchar syntax use duckdb_value_string instead this function does not work correctly if the string contains null bytes returns the text value at the specified location as a null-terminated string or nullptr if the value cannot be converted the result must be freed with duckdb_free duckdb_value_varchar_internal syntax use duckdb_value_string_internal instead this function does not work correctly if the string contains null bytes returns the char value at the specified location only works on varchar columns and does not auto-cast if the column is not a varchar column this function will return null the result must not be freed duckdb_value_string_internal syntax use duckdb_value_string_internal instead this function does not work correctly if the string contains null bytes returns the char value at the specified location only works on varchar columns and does not auto-cast if the column is not a varchar column this function will return null the result must not be freed duckdb_value_blob syntax the duckdb_blob value at the specified location returns a blob with blob data set to nullptr if the value cannot be converted the resulting blob data must be freed with duckdb_free duckdb_value_is_null syntax returns true if the value at the specified index is null and false otherwise duckdb_malloc allocate size bytes of memory using the duckdb internal malloc function any memory allocated in this manner should be freed using duckdb_free syntax the number of bytes to allocate returns a pointer to the allocated memory region duckdb_free free a value returned from duckdb_malloc duckdb_value_varchar or duckdb_value_blob syntax the memory region to de-allocate duckdb_vector_size the internal vector size used by duckdb this is the amount of tuples that will fit into a data chunk created by duckdb_create_data_chunk syntax the vector size duckdb_string_is_inlined whether or not the duckdb_string_t value is inlined this means that the data of the string does not have a separate allocation syntax duckdb_from_date decompose a duckdb_date object into year month and date stored as duckdb_date_struct syntax the date object as obtained from a duckdb_type_date column returns the duckdb_date_struct with the decomposed elements duckdb_to_date re-compose a duckdb_date from year month and date duckdb_date_struct syntax the year month and date stored in a duckdb_date_struct returns the duckdb_date element duckdb_from_time decompose a duckdb_time object into hour minute second and microsecond stored as duckdb_time_struct syntax the time object as obtained from a duckdb_type_time column returns the duckdb_time_struct with the decomposed elements duckdb_to_time re-compose a duckdb_time from hour minute second and microsecond duckdb_time_struct syntax the hour minute second and microsecond in a duckdb_time_struct returns the duckdb_time element duckdb_from_timestamp decompose a duckdb_timestamp object into a duckdb_timestamp_struct syntax the ts object as obtained from a duckdb_type_timestamp column returns the duckdb_timestamp_struct with the decomposed elements duckdb_to_timestamp re-compose a duckdb_timestamp from a duckdb_timestamp_struct syntax the de-composed elements in a duckdb_timestamp_struct returns the duckdb_timestamp element duckdb_hugeint_to_double converts a duckdb_hugeint object as obtained from a duckdb_type_hugeint column into a double syntax the hugeint value returns the converted double element duckdb_double_to_hugeint converts a double value to a duckdb_hugeint object if the conversion fails because the double value is too big the result will be 0 syntax the double value returns the converted duckdb_hugeint element duckdb_double_to_decimal converts a double value to a duckdb_decimal object if the conversion fails because the double value is too big or the width scale are invalid the result will be 0 syntax the double value returns the converted duckdb_decimal element duckdb_decimal_to_double converts a duckdb_decimal object as obtained from a duckdb_type_decimal column into a double syntax the decimal value returns the converted double element duckdb_prepare create a prepared statement object from a query note that after calling duckdb_prepare the prepared statement should always be destroyed using duckdb_destroy_prepare even if the prepare fails if the prepare fails duckdb_prepare_error can be called to obtain the reason why the prepare failed syntax the connection object query the sql query to prepare out_prepared_statement the resulting prepared statement object returns duckdbsuccess on success or duckdberror on failure duckdb_destroy_prepare closes the prepared statement and de-allocates all memory allocated for the statement syntax the prepared statement to destroy duckdb_prepare_error returns the error message associated with the given prepared statement if the prepared statement has no error message this returns nullptr instead the error message should not be freed it will be de-allocated when duckdb_destroy_prepare is called syntax the prepared statement to obtain the error from returns the error message or nullptr if there is none duckdb_nparams returns the number of parameters that can be provided to the given prepared statement returns 0 if the query was not successfully prepared syntax the prepared statement to obtain the number of parameters for duckdb_param_type returns the parameter type for the parameter at the given index returns duckdb_type_invalid if the parameter index is out of range or the statement was not successfully prepared syntax the prepared statement param_idx the parameter index returns the parameter type duckdb_clear_bindings clear the params bind to the prepared statement syntax duckdb_bind_parameter_index retrieve the index of the parameter for the prepared statement identified by name syntax duckdb_bind_boolean binds a bool value to the prepared statement at the specified index syntax duckdb_bind_int8 binds an int8_t value to the prepared statement at the specified index syntax duckdb_bind_int16 binds an int16_t value to the prepared statement at the specified index syntax duckdb_bind_int32 binds an int32_t value to the prepared statement at the specified index syntax duckdb_bind_int64 binds an int64_t value to the prepared statement at the specified index syntax duckdb_bind_hugeint binds an duckdb_hugeint value to the prepared statement at the specified index syntax duckdb_bind_decimal binds a duckdb_decimal value to the prepared statement at the specified index syntax duckdb_bind_uint8 binds an uint8_t value to the prepared statement at the specified index syntax duckdb_bind_uint16 binds an uint16_t value to the prepared statement at the specified index syntax duckdb_bind_uint32 binds an uint32_t value to the prepared statement at the specified index syntax duckdb_bind_uint64 binds an uint64_t value to the prepared statement at the specified index syntax duckdb_bind_float binds an float value to the prepared statement at the specified index syntax duckdb_bind_double binds an double value to the prepared statement at the specified index syntax duckdb_bind_date binds a duckdb_date value to the prepared statement at the specified index syntax duckdb_bind_time binds a duckdb_time value to the prepared statement at the specified index syntax duckdb_bind_timestamp binds a duckdb_timestamp value to the prepared statement at the specified index syntax duckdb_bind_interval binds a duckdb_interval value to the prepared statement at the specified index syntax duckdb_bind_varchar binds a null-terminated varchar value to the prepared statement at the specified index syntax duckdb_bind_varchar_length binds a varchar value to the prepared statement at the specified index syntax duckdb_bind_blob binds a blob value to the prepared statement at the specified index syntax duckdb_bind_null binds a null value to the prepared statement at the specified index syntax duckdb_execute_prepared executes the prepared statement with the given bound parameters and returns a materialized query result this method can be called multiple times for each prepared statement and the parameters can be modified between calls to this function syntax the prepared statement to execute out_result the query result returns duckdbsuccess on success or duckdberror on failure duckdb_execute_prepared_arrow executes the prepared statement with the given bound parameters and returns an arrow query result syntax the prepared statement to execute out_result the query result returns duckdbsuccess on success or duckdberror on failure duckdb_arrow_scan scans the arrow stream and creates a view with the given name syntax the connection on which to execute the scan table_name name of the temporary view to create arrow arrow stream wrapper returns duckdbsuccess on success or duckdberror on failure duckdb_arrow_array_scan scans the arrow array and creates a view with the given name syntax the connection on which to execute the scan table_name name of the temporary view to create arrow_schema arrow schema wrapper arrow_array arrow array wrapper out_stream output array stream that wraps around the passed schema for releasing deleting once done returns duckdbsuccess on success or duckdberror on failure duckdb_extract_statements extract all statements from a query note that after calling duckdb_extract_statements the extracted statements should always be destroyed using duckdb_destroy_extracted even if no statements were extracted if the extract fails duckdb_extract_statements_error can be called to obtain the reason why the extract failed syntax the connection object query the sql query to extract out_extracted_statements the resulting extracted statements object returns the number of extracted statements or 0 on failure duckdb_prepare_extracted_statement prepare an extracted statement note that after calling duckdb_prepare_extracted_statement the prepared statement should always be destroyed using duckdb_destroy_prepare even if the prepare fails if the prepare fails duckdb_prepare_error can be called to obtain the reason why the prepare failed syntax the connection object extracted_statements the extracted statements object index the index of the extracted statement to prepare out_prepared_statement the resulting prepared statement object returns duckdbsuccess on success or duckdberror on failure duckdb_extract_statements_error returns the error message contained within the extracted statements the result of this function must not be freed it will be cleaned up when duckdb_destroy_extracted is called syntax the extracted statements to fetch the error from returns the error of the extracted statements duckdb_destroy_extracted de-allocates all memory allocated for the extracted statements syntax the extracted statements to destroy duckdb_pending_prepared executes the prepared statement with the given bound parameters and returns a pending result the pending result represents an intermediate structure for a query that is not yet fully executed the pending result can be used to incrementally execute a query returning control to the client between tasks note that after calling duckdb_pending_prepared the pending result should always be destroyed using duckdb_destroy_pending even if this function returns duckdberror syntax the prepared statement to execute out_result the pending query result returns duckdbsuccess on success or duckdberror on failure duckdb_pending_prepared_streaming executes the prepared statement with the given bound parameters and returns a pending result this pending result will create a streaming duckdb_result when executed the pending result represents an intermediate structure for a query that is not yet fully executed note that after calling duckdb_pending_prepared_streaming the pending result should always be destroyed using duckdb_destroy_pending even if this function returns duckdberror syntax the prepared statement to execute out_result the pending query result returns duckdbsuccess on success or duckdberror on failure duckdb_destroy_pending closes the pending result and de-allocates all memory allocated for the result syntax the pending result to destroy duckdb_pending_error returns the error message contained within the pending result the result of this function must not be freed it will be cleaned up when duckdb_destroy_pending is called syntax the pending result to fetch the error from returns the error of the pending result duckdb_pending_execute_task executes a single task within the query returning whether or not the query is ready if this returns duckdb_pending_result_ready the duckdb_execute_pending function can be called to obtain the result if this returns duckdb_pending_result_not_ready the duckdb_pending_execute_task function should be called again if this returns duckdb_pending_error an error occurred during execution the error message can be obtained by calling duckdb_pending_error on the pending_result syntax the pending result to execute a task within returns the state of the pending result after the execution duckdb_execute_pending fully execute a pending query result returning the final query result if duckdb_pending_execute_task has been called until duckdb_pending_result_ready was returned this will return fast otherwise all remaining tasks must be executed first syntax the pending result to execute out_result the result object returns duckdbsuccess on success or duckdberror on failure duckdb_pending_execution_is_finished returns whether a duckdb_pending_state is finished executing for example if pending_state is duckdb_pending_result_ready this function will return true syntax the pending state on which to decide whether to finish execution returns boolean indicating pending execution should be considered finished duckdb_destroy_value destroys the value and de-allocates all memory allocated for that type syntax the value to destroy duckdb_create_varchar creates a value from a null-terminated string syntax the null-terminated string returns the value this must be destroyed with duckdb_destroy_value duckdb_create_varchar_length creates a value from a string syntax the text length the length of the text returns the value this must be destroyed with duckdb_destroy_value duckdb_create_int64 creates a value from an int64 syntax the bigint value returns the value this must be destroyed with duckdb_destroy_value duckdb_get_varchar obtains a string representation of the given value the result must be destroyed with duckdb_free syntax the value returns the string value this must be destroyed with duckdb_free duckdb_get_int64 obtains an int64 of the given value syntax the value returns the int64 value or 0 if no conversion is possible duckdb_create_logical_type creates a duckdb_logical_type from a standard primitive type the resulting type should be destroyed with duckdb_destroy_logical_type this should not be used with duckdb_type_decimal syntax the primitive type to create returns the logical type duckdb_create_list_type creates a list type from its child type the resulting type should be destroyed with duckdb_destroy_logical_type syntax the child type of list type to create returns the logical type duckdb_create_map_type creates a map type from its key type and value type the resulting type should be destroyed with duckdb_destroy_logical_type syntax the key type and value type of map type to create returns the logical type duckdb_create_union_type creates a union type from the passed types array the resulting type should be destroyed with duckdb_destroy_logical_type syntax the array of types that the union should consist of type_amount the size of the types array returns the logical type duckdb_create_decimal_type creates a duckdb_logical_type of type decimal with the specified width and scale the resulting type should be destroyed with duckdb_destroy_logical_type syntax the width of the decimal type scale the scale of the decimal type returns the logical type duckdb_get_type_id retrieves the type class of a duckdb_logical_type syntax the logical type object returns the type id duckdb_decimal_width retrieves the width of a decimal type syntax the logical type object returns the width of the decimal type duckdb_decimal_scale retrieves the scale of a decimal type syntax the logical type object returns the scale of the decimal type duckdb_decimal_internal_type retrieves the internal storage type of a decimal type syntax the logical type object returns the internal type of the decimal type duckdb_enum_internal_type retrieves the internal storage type of an enum type syntax the logical type object returns the internal type of the enum type duckdb_enum_dictionary_size retrieves the dictionary size of the enum type syntax the logical type object returns the dictionary size of the enum type duckdb_enum_dictionary_value retrieves the dictionary value at the specified position from the enum the result must be freed with duckdb_free syntax the logical type object index the index in the dictionary returns the string value of the enum type must be freed with duckdb_free duckdb_list_type_child_type retrieves the child type of the given list type the result must be freed with duckdb_destroy_logical_type syntax the logical type object returns the child type of the list type must be destroyed with duckdb_destroy_logical_type duckdb_map_type_key_type retrieves the key type of the given map type the result must be freed with duckdb_destroy_logical_type syntax the logical type object returns the key type of the map type must be destroyed with duckdb_destroy_logical_type duckdb_map_type_value_type retrieves the value type of the given map type the result must be freed with duckdb_destroy_logical_type syntax the logical type object returns the value type of the map type must be destroyed with duckdb_destroy_logical_type duckdb_struct_type_child_count returns the number of children of a struct type syntax the logical type object returns the number of children of a struct type duckdb_struct_type_child_name retrieves the name of the struct child the result must be freed with duckdb_free syntax the logical type object index the child index returns the name of the struct type must be freed with duckdb_free duckdb_struct_type_child_type retrieves the child type of the given struct type at the specified index the result must be freed with duckdb_destroy_logical_type syntax the logical type object index the child index returns the child type of the struct type must be destroyed with duckdb_destroy_logical_type duckdb_union_type_member_count returns the number of members that the union type has syntax the logical type union object returns the number of members of a union type duckdb_union_type_member_name retrieves the name of the union member the result must be freed with duckdb_free syntax the logical type object index the child index returns the name of the union member must be freed with duckdb_free duckdb_union_type_member_type retrieves the child type of the given union member at the specified index the result must be freed with duckdb_destroy_logical_type syntax the logical type object index the child index returns the child type of the union member must be destroyed with duckdb_destroy_logical_type duckdb_destroy_logical_type destroys the logical type and de-allocates all memory allocated for that type syntax the logical type to destroy duckdb_create_data_chunk creates an empty datachunk with the specified set of types syntax an array of types of the data chunk column_count the number of columns returns the data chunk duckdb_destroy_data_chunk destroys the data chunk and de-allocates all memory allocated for that chunk syntax the data chunk to destroy duckdb_data_chunk_reset resets a data chunk clearing the validity masks and setting the cardinality of the data chunk to 0 syntax the data chunk to reset duckdb_data_chunk_get_column_count retrieves the number of columns in a data chunk syntax the data chunk to get the data from returns the number of columns in the data chunk duckdb_data_chunk_get_vector retrieves the vector at the specified column index in the data chunk the pointer to the vector is valid for as long as the chunk is alive it does not need to be destroyed syntax the data chunk to get the data from returns the vector duckdb_data_chunk_get_size retrieves the current number of tuples in a data chunk syntax the data chunk to get the data from returns the number of tuples in the data chunk duckdb_data_chunk_set_size sets the current number of tuples in a data chunk syntax the data chunk to set the size in size the number of tuples in the data chunk duckdb_vector_get_column_type retrieves the column type of the specified vector the result must be destroyed with duckdb_destroy_logical_type syntax the vector get the data from returns the type of the vector duckdb_vector_get_data retrieves the data pointer of the vector the data pointer can be used to read or write values from the vector how to read or write values depends on the type of the vector syntax the vector to get the data from returns the data pointer duckdb_vector_get_validity retrieves the validity mask pointer of the specified vector if all values are valid this function might return null the validity mask is a bitset that signifies null-ness within the data chunk it is a series of uint64_t values where each uint64_t value contains validity for 64 tuples the bit is set to 1 if the value is valid i e not null or 0 if the value is invalid i e null validity of a specific value can be obtained like this idx_t entry_idx row_idx 64 idx_t idx_in_entry row_idx 64 bool is_valid validity_mask entry_idx 1 idx_in_entry alternatively the slower duckdb_validity_row_is_valid function can be used syntax the vector to get the data from returns the pointer to the validity mask or null if no validity mask is present duckdb_vector_ensure_validity_writable ensures the validity mask is writable by allocating it after this function is called duckdb_vector_get_validity will always return non-null this allows null values to be written to the vector regardless of whether a validity mask was present before syntax the vector to alter duckdb_vector_assign_string_element assigns a string element in the vector at the specified location syntax the vector to alter index the row position in the vector to assign the string to str the null-terminated string duckdb_vector_assign_string_element_len assigns a string element in the vector at the specified location syntax the vector to alter index the row position in the vector to assign the string to str the string str_len the length of the string in bytes duckdb_list_vector_get_child retrieves the child vector of a list vector the resulting vector is valid as long as the parent vector is valid syntax the vector returns the child vector duckdb_list_vector_get_size returns the size of the child vector of the list syntax the vector returns the size of the child list duckdb_list_vector_set_size sets the total size of the underlying child-vector of a list vector syntax the list vector size the size of the child list returns the duckdb state returns duckdberror if the vector is nullptr duckdb_list_vector_reserve sets the total capacity of the underlying child-vector of a list syntax the list vector required_capacity the total capacity to reserve return the duckdb state returns duckdberror if the vector is nullptr duckdb_struct_vector_get_child retrieves the child vector of a struct vector the resulting vector is valid as long as the parent vector is valid syntax the vector index the child index returns the child vector duckdb_validity_row_is_valid returns whether or not a row is valid i e not null in the given validity mask syntax the validity mask as obtained through duckdb_data_chunk_get_validity row the row index returns true if the row is valid false otherwise duckdb_validity_set_row_validity in a validity mask sets a specific row to either valid or invalid note that duckdb_data_chunk_ensure_validity_writable should be called before calling duckdb_data_chunk_get_validity to ensure that there is a validity mask to write to syntax the validity mask as obtained through duckdb_data_chunk_get_validity row the row index valid whether or not to set the row to valid or invalid duckdb_validity_set_row_invalid in a validity mask sets a specific row to invalid equivalent to duckdb_validity_set_row_validity with valid set to false syntax the validity mask row the row index duckdb_validity_set_row_valid in a validity mask sets a specific row to valid equivalent to duckdb_validity_set_row_validity with valid set to true syntax the validity mask row the row index duckdb_create_table_function creates a new empty table function the return value should be destroyed with duckdb_destroy_table_function syntax the table function object duckdb_destroy_table_function destroys the given table function object syntax the table function to destroy duckdb_table_function_set_name sets the name of the given table function syntax the table function name the name of the table function duckdb_table_function_add_parameter adds a parameter to the table function syntax 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 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 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 the table function bind the bind function duckdb_table_function_set_init sets the init function of the table function syntax the table function init the init function duckdb_table_function_set_local_init sets the thread-local init function of the table function syntax the table function init the init function duckdb_table_function_set_function sets the main function of the table function syntax 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 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 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 the info object returns the extra info duckdb_bind_add_result_column adds a result column to the output of the table function syntax 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 the info object returns the init data object duckdb_function_set_error report that an error has occurred while executing the function syntax the info object error the error message duckdb_add_replacement_scan add a replacement scan definition to the specified database syntax the database object to add the replacement scan to replacement the replacement scan callback extra_data extra data that is passed back into the specified callback delete_callback the delete callback to call on the extra data if any duckdb_replacement_scan_set_function_name sets the replacement function name to use if this function is called in the replacement callback the replacement scan is performed if it is not called the replacement callback is not performed syntax the info object function_name the function name to substitute duckdb_replacement_scan_add_parameter adds a parameter to the replacement scan function syntax the info object parameter the parameter to add duckdb_replacement_scan_set_error report that an error has occurred while executing the replacement scan syntax the info object error the error message duckdb_appender_create creates an appender object syntax the connection context to create the appender in schema the schema of the table to append to or nullptr for the default schema table the table name to append to out_appender the resulting appender object returns duckdbsuccess on success or duckdberror on failure duckdb_appender_error returns the error message associated with the given appender if the appender has no error message this returns nullptr instead the error message should not be freed it will be de-allocated when duckdb_appender_destroy is called syntax the appender to get the error from returns the error message or nullptr if there is none duckdb_appender_flush flush the appender to the table forcing the cache of the appender to be cleared and the data to be appended to the base table this should generally not be used unless you know what you are doing instead call duckdb_appender_destroy when you are done with the appender syntax the appender to flush returns duckdbsuccess on success or duckdberror on failure duckdb_appender_close close the appender flushing all intermediate state in the appender to the table and closing it for further appends this is generally not necessary call duckdb_appender_destroy instead syntax the appender to flush and close returns duckdbsuccess on success or duckdberror on failure duckdb_appender_destroy close the appender and destroy it flushing all intermediate state in the appender to the table and de-allocating all memory associated with the appender syntax the appender to flush close and destroy returns duckdbsuccess on success or duckdberror on failure duckdb_appender_begin_row a nop function provided for backwards compatibility reasons does nothing only duckdb_appender_end_row is required syntax duckdb_appender_end_row finish the current row of appends after end_row is called the next row can be appended syntax the appender returns duckdbsuccess on success or duckdberror on failure duckdb_append_bool append a bool value to the appender syntax duckdb_append_int8 append an int8_t value to the appender syntax duckdb_append_int16 append an int16_t value to the appender syntax duckdb_append_int32 append an int32_t value to the appender syntax duckdb_append_int64 append an int64_t value to the appender syntax duckdb_append_hugeint append a duckdb_hugeint value to the appender syntax duckdb_append_uint8 append a uint8_t value to the appender syntax duckdb_append_uint16 append a uint16_t value to the appender syntax duckdb_append_uint32 append a uint32_t value to the appender syntax duckdb_append_uint64 append a uint64_t value to the appender syntax duckdb_append_float append a float value to the appender syntax duckdb_append_double append a double value to the appender syntax duckdb_append_date append a duckdb_date value to the appender syntax duckdb_append_time append a duckdb_time value to the appender syntax duckdb_append_timestamp append a duckdb_timestamp value to the appender syntax duckdb_append_interval append a duckdb_interval value to the appender syntax duckdb_append_varchar append a varchar value to the appender syntax duckdb_append_varchar_length append a varchar value to the appender syntax duckdb_append_blob append a blob value to the appender syntax duckdb_append_null append a null value to the appender of any type syntax duckdb_append_data_chunk appends a pre-filled data chunk to the specified appender the types of the data chunk must exactly match the types of the table no casting is performed if the types do not match or the appender is in an invalid state duckdberror is returned if the append is successful duckdbsuccess is returned syntax the appender to append to chunk the data chunk to append returns the return state duckdb_query_arrow executes a sql query within a connection and stores the full materialized result in an arrow structure if the query fails to execute duckdberror is returned and the error message can be retrieved by calling duckdb_query_arrow_error note that after running duckdb_query_arrow duckdb_destroy_arrow must be called on the result object even if the query fails otherwise the error stored within the result will not be freed correctly syntax the connection to perform the query in query the sql query to run out_result the query result returns duckdbsuccess on success or duckdberror on failure duckdb_query_arrow_schema fetch the internal arrow schema from the arrow result syntax the result to fetch the schema from out_schema the output schema returns duckdbsuccess on success or duckdberror on failure duckdb_query_arrow_array fetch an internal arrow array from the arrow result this function can be called multiple time to get next chunks which will free the previous out_array so consume the out_array before calling this function again syntax the result to fetch the array from out_array the output array returns duckdbsuccess on success or duckdberror on failure duckdb_arrow_column_count returns the number of columns present in a the arrow result object syntax the result object returns the number of columns present in the result object duckdb_arrow_row_count returns the number of rows present in a the arrow result object syntax the result object returns the number of rows present in the result object duckdb_arrow_rows_changed returns the number of rows changed by the query stored in the arrow result this is relevant only for insert update delete queries for other queries the rows_changed will be 0 syntax the result object returns the number of rows changed duckdb_query_arrow_error returns the error message contained within the result the error is only set if duckdb_query_arrow returns duckdberror the error message should not be freed it will be de-allocated when duckdb_destroy_arrow is called syntax the result object to fetch the nullmask from returns the error of the result duckdb_destroy_arrow closes the result and de-allocates all memory allocated for the arrow result syntax the result to destroy duckdb_execute_tasks execute duckdb tasks on this thread will return after max_tasks have been executed or if there are no more tasks present syntax the database object to execute tasks for max_tasks the maximum amount of tasks to execute duckdb_create_task_state creates a task state that can be used with duckdb_execute_tasks_state to execute tasks until duckdb_finish_execution is called on the state duckdb_destroy_state should be called on the result in order to free memory syntax the database object to create the task state for returns the task state that can be used with duckdb_execute_tasks_state duckdb_execute_tasks_state execute duckdb tasks on this thread the thread will keep on executing tasks forever until duckdb_finish_execution is called on the state multiple threads can share the same duckdb_task_state syntax the task state of the executor duckdb_execute_n_tasks_state execute duckdb tasks on this thread the thread will keep on executing tasks until either duckdb_finish_execution is called on the state max_tasks tasks have been executed or there are no more tasks to be executed multiple threads can share the same duckdb_task_state syntax the task state of the executor max_tasks the maximum amount of tasks to execute returns the amount of tasks that have actually been executed duckdb_finish_execution finish execution on a specific task syntax the task state to finish execution duckdb_task_state_is_finished check if the provided duckdb_task_state has finished execution syntax the task state to inspect returns whether or not duckdb_finish_execution has been called on the task state duckdb_destroy_task_state destroys the task state returned from duckdb_create_task_state note that this should not be called while there is an active duckdb_execute_tasks_state running on the task state syntax the task state to clean up duckdb_execution_is_finished returns true if execution of the current query is finished syntax the connection on which to check duckdb_stream_fetch_chunk fetches a data chunk from the streaming duckdb_result this function should be called repeatedly until the result is exhausted the result must be destroyed with duckdb_destroy_data_chunk this function can only be used on duckdb_results created with duckdb_pending_prepared_streaming if this function is used none of the other result functions can be used and vice versa i e this function cannot be mixed with the legacy result functions or the materialized result functions it is not known beforehand how many chunks will be returned by this result syntax the result object to fetch the data chunk from returns the resulting data chunk returns null if the result has an error", + "text": "api reference open connect syntax path to the database file on disk or nullptr or memory to open an in-memory database out_database the result database object returns duckdbsuccess on success or duckdberror on failure duckdb_open_ext extended version of duckdb_open creates a new database or opens an existing database file stored at the the given path syntax path to the database file on disk or nullptr or memory to open an in-memory database out_database the result database object config optional configuration used to start up the database system out_error if set and the function returns duckdberror this will contain the reason why the start-up failed note that the error must be freed using duckdb_free returns duckdbsuccess on success or duckdberror on failure duckdb_close closes the specified database and de-allocates all memory allocated for that database this should be called after you are done with any database allocated through duckdb_open note that failing to call duckdb_close in case of e g a program crash will not cause data corruption still it is recommended to always correctly close a database object after you are done with it syntax the database object to shut down duckdb_connect opens a connection to a database connections are required to query the database and store transactional state associated with the connection the instantiated connection should be closed using duckdb_disconnect syntax the database file to connect to out_connection the result connection object returns duckdbsuccess on success or duckdberror on failure duckdb_interrupt interrupt running query syntax the connection to interruot duckdb_query_progress get progress of the running query syntax the working connection returns -1 if no progress or a percentage of the progress duckdb_disconnect closes the specified connection and de-allocates all memory allocated for that connection syntax the connection to close duckdb_library_version returns the version of the linked duckdb with a version postfix for dev versions usually used for developing c extensions that must return this for a compatibility check syntax duckdb_create_config initializes an empty configuration object that can be used to provide start-up options for the duckdb instance through duckdb_open_ext this will always succeed unless there is a malloc failure syntax the result configuration object returns duckdbsuccess on success or duckdberror on failure duckdb_config_count this returns the total amount of configuration options available for usage with duckdb_get_config_flag this should not be called in a loop as it internally loops over all the options syntax the amount of config options available duckdb_get_config_flag obtains a human-readable name and description of a specific configuration option this can be used to e g display configuration options this will succeed unless index is out of range i e duckdb_config_count the result name or description must not be freed syntax the index of the configuration option between 0 and duckdb_config_count out_name a name of the configuration flag out_description a description of the configuration flag returns duckdbsuccess on success or duckdberror on failure duckdb_set_config sets the specified option for the specified configuration the configuration option is indicated by name to obtain a list of config options see duckdb_get_config_flag in the source code configuration options are defined in config cpp this can fail if either the name is invalid or if the value provided for the option is invalid syntax the configuration object to set the option on name the name of the configuration flag to set option the value to set the configuration flag to returns duckdbsuccess on success or duckdberror on failure duckdb_destroy_config destroys the specified configuration option and de-allocates all memory allocated for the object syntax the configuration object to destroy duckdb_query executes a sql query within a connection and stores the full materialized result in the out_result pointer if the query fails to execute duckdberror is returned and the error message can be retrieved by calling duckdb_result_error note that after running duckdb_query duckdb_destroy_result must be called on the result object even if the query fails otherwise the error stored within the result will not be freed correctly syntax the connection to perform the query in query the sql query to run out_result the query result returns duckdbsuccess on success or duckdberror on failure duckdb_destroy_result closes the result and de-allocates all memory allocated for that connection syntax the result to destroy duckdb_column_name returns the column name of the specified column the result should not need be freed the column names will automatically be destroyed when the result is destroyed returns null if the column is out of range syntax the result object to fetch the column name from col the column index returns the column name of the specified column duckdb_column_type returns the column type of the specified column returns duckdb_type_invalid if the column is out of range syntax the result object to fetch the column type from col the column index returns the column type of the specified column duckdb_column_logical_type returns the logical column type of the specified column the return type of this call should be destroyed with duckdb_destroy_logical_type returns null if the column is out of range syntax the result object to fetch the column type from col the column index returns the logical column type of the specified column duckdb_column_count returns the number of columns present in a the result object syntax the result object returns the number of columns present in the result object duckdb_row_count returns the number of rows present in a the result object syntax the result object returns the number of rows present in the result object duckdb_rows_changed returns the number of rows changed by the query stored in the result this is relevant only for insert update delete queries for other queries the rows_changed will be 0 syntax the result object returns the number of rows changed duckdb_column_data deprecated prefer using duckdb_result_get_chunk instead returns the data of a specific column of a result in columnar format the function returns a dense array which contains the result data the exact type stored in the array depends on the corresponding duckdb_type as provided by duckdb_column_type for the exact type by which the data should be accessed see the comments in the types section or the duckdb_type enum for example for a column of type duckdb_type_integer rows can be accessed in the following manner int32_t data int32_t duckdb_column_data result 0 printf data for row d d n row data row syntax the result object to fetch the column data from col the column index returns the column data of the specified column duckdb_nullmask_data deprecated prefer using duckdb_result_get_chunk instead returns the nullmask of a specific column of a result in columnar format the nullmask indicates for every row whether or not the corresponding row is null if a row is null the values present in the array provided by duckdb_column_data are undefined int32_t data int32_t duckdb_column_data result 0 bool nullmask duckdb_nullmask_data result 0 if nullmask row printf data for row d null n row else printf data for row d d n row data row syntax the result object to fetch the nullmask from col the column index returns the nullmask of the specified column duckdb_result_error returns the error message contained within the result the error is only set if duckdb_query returns duckdberror the result of this function must not be freed it will be cleaned up when duckdb_destroy_result is called syntax the result object to fetch the error from returns the error of the result duckdb_result_get_chunk fetches a data chunk from the duckdb_result this function should be called repeatedly until the result is exhausted the result must be destroyed with duckdb_destroy_data_chunk this function supersedes all duckdb_value functions as well as the duckdb_column_data and duckdb_nullmask_data functions it results in significantly better performance and should be preferred in newer code-bases if this function is used none of the other result functions can be used and vice versa i e this function cannot be mixed with the legacy result functions use duckdb_result_chunk_count to figure out how many chunks there are in the result syntax the result object to fetch the data chunk from chunk_index the chunk index to fetch from returns the resulting data chunk returns null if the chunk index is out of bounds duckdb_result_is_streaming checks if the type of the internal result is streamqueryresult syntax the result object to check returns whether or not the result object is of the type streamqueryresult duckdb_result_chunk_count returns the number of data chunks present in the result syntax the result object returns number of data chunks present in the result duckdb_value_boolean syntax the boolean value at the specified location or false if the value cannot be converted duckdb_value_int8 syntax the int8_t value at the specified location or 0 if the value cannot be converted duckdb_value_int16 syntax the int16_t value at the specified location or 0 if the value cannot be converted duckdb_value_int32 syntax the int32_t value at the specified location or 0 if the value cannot be converted duckdb_value_int64 syntax the int64_t value at the specified location or 0 if the value cannot be converted duckdb_value_hugeint syntax the duckdb_hugeint value at the specified location or 0 if the value cannot be converted duckdb_value_decimal syntax the duckdb_decimal value at the specified location or 0 if the value cannot be converted duckdb_value_uint8 syntax the uint8_t value at the specified location or 0 if the value cannot be converted duckdb_value_uint16 syntax the uint16_t value at the specified location or 0 if the value cannot be converted duckdb_value_uint32 syntax the uint32_t value at the specified location or 0 if the value cannot be converted duckdb_value_uint64 syntax the uint64_t value at the specified location or 0 if the value cannot be converted duckdb_value_float syntax the float value at the specified location or 0 if the value cannot be converted duckdb_value_double syntax the double value at the specified location or 0 if the value cannot be converted duckdb_value_date syntax the duckdb_date value at the specified location or 0 if the value cannot be converted duckdb_value_time syntax the duckdb_time value at the specified location or 0 if the value cannot be converted duckdb_value_timestamp syntax the duckdb_timestamp value at the specified location or 0 if the value cannot be converted duckdb_value_interval syntax the duckdb_interval value at the specified location or 0 if the value cannot be converted duckdb_value_varchar syntax use duckdb_value_string instead this function does not work correctly if the string contains null bytes returns the text value at the specified location as a null-terminated string or nullptr if the value cannot be converted the result must be freed with duckdb_free duckdb_value_varchar_internal syntax use duckdb_value_string_internal instead this function does not work correctly if the string contains null bytes returns the char value at the specified location only works on varchar columns and does not auto-cast if the column is not a varchar column this function will return null the result must not be freed duckdb_value_string_internal syntax use duckdb_value_string_internal instead this function does not work correctly if the string contains null bytes returns the char value at the specified location only works on varchar columns and does not auto-cast if the column is not a varchar column this function will return null the result must not be freed duckdb_value_blob syntax the duckdb_blob value at the specified location returns a blob with blob data set to nullptr if the value cannot be converted the resulting blob data must be freed with duckdb_free duckdb_value_is_null syntax returns true if the value at the specified index is null and false otherwise duckdb_malloc allocate size bytes of memory using the duckdb internal malloc function any memory allocated in this manner should be freed using duckdb_free syntax the number of bytes to allocate returns a pointer to the allocated memory region duckdb_free free a value returned from duckdb_malloc duckdb_value_varchar or duckdb_value_blob syntax the memory region to de-allocate duckdb_vector_size the internal vector size used by duckdb this is the amount of tuples that will fit into a data chunk created by duckdb_create_data_chunk syntax the vector size duckdb_string_is_inlined whether or not the duckdb_string_t value is inlined this means that the data of the string does not have a separate allocation syntax duckdb_from_date decompose a duckdb_date object into year month and date stored as duckdb_date_struct syntax the date object as obtained from a duckdb_type_date column returns the duckdb_date_struct with the decomposed elements duckdb_to_date re-compose a duckdb_date from year month and date duckdb_date_struct syntax the year month and date stored in a duckdb_date_struct returns the duckdb_date element duckdb_from_time decompose a duckdb_time object into hour minute second and microsecond stored as duckdb_time_struct syntax the time object as obtained from a duckdb_type_time column returns the duckdb_time_struct with the decomposed elements duckdb_to_time re-compose a duckdb_time from hour minute second and microsecond duckdb_time_struct syntax the hour minute second and microsecond in a duckdb_time_struct returns the duckdb_time element duckdb_from_timestamp decompose a duckdb_timestamp object into a duckdb_timestamp_struct syntax the ts object as obtained from a duckdb_type_timestamp column returns the duckdb_timestamp_struct with the decomposed elements duckdb_to_timestamp re-compose a duckdb_timestamp from a duckdb_timestamp_struct syntax the de-composed elements in a duckdb_timestamp_struct returns the duckdb_timestamp element duckdb_hugeint_to_double converts a duckdb_hugeint object as obtained from a duckdb_type_hugeint column into a double syntax the hugeint value returns the converted double element duckdb_double_to_hugeint converts a double value to a duckdb_hugeint object if the conversion fails because the double value is too big the result will be 0 syntax the double value returns the converted duckdb_hugeint element duckdb_double_to_decimal converts a double value to a duckdb_decimal object if the conversion fails because the double value is too big or the width scale are invalid the result will be 0 syntax the double value returns the converted duckdb_decimal element duckdb_decimal_to_double converts a duckdb_decimal object as obtained from a duckdb_type_decimal column into a double syntax the decimal value returns the converted double element duckdb_prepare create a prepared statement object from a query note that after calling duckdb_prepare the prepared statement should always be destroyed using duckdb_destroy_prepare even if the prepare fails if the prepare fails duckdb_prepare_error can be called to obtain the reason why the prepare failed syntax the connection object query the sql query to prepare out_prepared_statement the resulting prepared statement object returns duckdbsuccess on success or duckdberror on failure duckdb_destroy_prepare closes the prepared statement and de-allocates all memory allocated for the statement syntax the prepared statement to destroy duckdb_prepare_error returns the error message associated with the given prepared statement if the prepared statement has no error message this returns nullptr instead the error message should not be freed it will be de-allocated when duckdb_destroy_prepare is called syntax the prepared statement to obtain the error from returns the error message or nullptr if there is none duckdb_nparams returns the number of parameters that can be provided to the given prepared statement returns 0 if the query was not successfully prepared syntax the prepared statement to obtain the number of parameters for duckdb_param_type returns the parameter type for the parameter at the given index returns duckdb_type_invalid if the parameter index is out of range or the statement was not successfully prepared syntax the prepared statement param_idx the parameter index returns the parameter type duckdb_clear_bindings clear the params bind to the prepared statement syntax duckdb_bind_value binds a value to the prepared statement at the specified index syntax duckdb_bind_parameter_index retrieve the index of the parameter for the prepared statement identified by name syntax duckdb_bind_boolean binds a bool value to the prepared statement at the specified index syntax duckdb_bind_int8 binds an int8_t value to the prepared statement at the specified index syntax duckdb_bind_int16 binds an int16_t value to the prepared statement at the specified index syntax duckdb_bind_int32 binds an int32_t value to the prepared statement at the specified index syntax duckdb_bind_int64 binds an int64_t value to the prepared statement at the specified index syntax duckdb_bind_hugeint binds an duckdb_hugeint value to the prepared statement at the specified index syntax duckdb_bind_decimal binds a duckdb_decimal value to the prepared statement at the specified index syntax duckdb_bind_uint8 binds an uint8_t value to the prepared statement at the specified index syntax duckdb_bind_uint16 binds an uint16_t value to the prepared statement at the specified index syntax duckdb_bind_uint32 binds an uint32_t value to the prepared statement at the specified index syntax duckdb_bind_uint64 binds an uint64_t value to the prepared statement at the specified index syntax duckdb_bind_float binds an float value to the prepared statement at the specified index syntax duckdb_bind_double binds an double value to the prepared statement at the specified index syntax duckdb_bind_date binds a duckdb_date value to the prepared statement at the specified index syntax duckdb_bind_time binds a duckdb_time value to the prepared statement at the specified index syntax duckdb_bind_timestamp binds a duckdb_timestamp value to the prepared statement at the specified index syntax duckdb_bind_interval binds a duckdb_interval value to the prepared statement at the specified index syntax duckdb_bind_varchar binds a null-terminated varchar value to the prepared statement at the specified index syntax duckdb_bind_varchar_length binds a varchar value to the prepared statement at the specified index syntax duckdb_bind_blob binds a blob value to the prepared statement at the specified index syntax duckdb_bind_null binds a null value to the prepared statement at the specified index syntax duckdb_execute_prepared executes the prepared statement with the given bound parameters and returns a materialized query result this method can be called multiple times for each prepared statement and the parameters can be modified between calls to this function syntax the prepared statement to execute out_result the query result returns duckdbsuccess on success or duckdberror on failure duckdb_execute_prepared_arrow executes the prepared statement with the given bound parameters and returns an arrow query result syntax the prepared statement to execute out_result the query result returns duckdbsuccess on success or duckdberror on failure duckdb_arrow_scan scans the arrow stream and creates a view with the given name syntax the connection on which to execute the scan table_name name of the temporary view to create arrow arrow stream wrapper returns duckdbsuccess on success or duckdberror on failure duckdb_arrow_array_scan scans the arrow array and creates a view with the given name syntax the connection on which to execute the scan table_name name of the temporary view to create arrow_schema arrow schema wrapper arrow_array arrow array wrapper out_stream output array stream that wraps around the passed schema for releasing deleting once done returns duckdbsuccess on success or duckdberror on failure duckdb_extract_statements extract all statements from a query note that after calling duckdb_extract_statements the extracted statements should always be destroyed using duckdb_destroy_extracted even if no statements were extracted if the extract fails duckdb_extract_statements_error can be called to obtain the reason why the extract failed syntax the connection object query the sql query to extract out_extracted_statements the resulting extracted statements object returns the number of extracted statements or 0 on failure duckdb_prepare_extracted_statement prepare an extracted statement note that after calling duckdb_prepare_extracted_statement the prepared statement should always be destroyed using duckdb_destroy_prepare even if the prepare fails if the prepare fails duckdb_prepare_error can be called to obtain the reason why the prepare failed syntax the connection object extracted_statements the extracted statements object index the index of the extracted statement to prepare out_prepared_statement the resulting prepared statement object returns duckdbsuccess on success or duckdberror on failure duckdb_extract_statements_error returns the error message contained within the extracted statements the result of this function must not be freed it will be cleaned up when duckdb_destroy_extracted is called syntax the extracted statements to fetch the error from returns the error of the extracted statements duckdb_destroy_extracted de-allocates all memory allocated for the extracted statements syntax the extracted statements to destroy duckdb_pending_prepared executes the prepared statement with the given bound parameters and returns a pending result the pending result represents an intermediate structure for a query that is not yet fully executed the pending result can be used to incrementally execute a query returning control to the client between tasks note that after calling duckdb_pending_prepared the pending result should always be destroyed using duckdb_destroy_pending even if this function returns duckdberror syntax the prepared statement to execute out_result the pending query result returns duckdbsuccess on success or duckdberror on failure duckdb_pending_prepared_streaming executes the prepared statement with the given bound parameters and returns a pending result this pending result will create a streaming duckdb_result when executed the pending result represents an intermediate structure for a query that is not yet fully executed note that after calling duckdb_pending_prepared_streaming the pending result should always be destroyed using duckdb_destroy_pending even if this function returns duckdberror syntax the prepared statement to execute out_result the pending query result returns duckdbsuccess on success or duckdberror on failure duckdb_destroy_pending closes the pending result and de-allocates all memory allocated for the result syntax the pending result to destroy duckdb_pending_error returns the error message contained within the pending result the result of this function must not be freed it will be cleaned up when duckdb_destroy_pending is called syntax the pending result to fetch the error from returns the error of the pending result duckdb_pending_execute_task executes a single task within the query returning whether or not the query is ready if this returns duckdb_pending_result_ready the duckdb_execute_pending function can be called to obtain the result if this returns duckdb_pending_result_not_ready the duckdb_pending_execute_task function should be called again if this returns duckdb_pending_error an error occurred during execution the error message can be obtained by calling duckdb_pending_error on the pending_result syntax the pending result to execute a task within returns the state of the pending result after the execution duckdb_execute_pending fully execute a pending query result returning the final query result if duckdb_pending_execute_task has been called until duckdb_pending_result_ready was returned this will return fast otherwise all remaining tasks must be executed first syntax the pending result to execute out_result the result object returns duckdbsuccess on success or duckdberror on failure duckdb_pending_execution_is_finished returns whether a duckdb_pending_state is finished executing for example if pending_state is duckdb_pending_result_ready this function will return true syntax the pending state on which to decide whether to finish execution returns boolean indicating pending execution should be considered finished duckdb_destroy_value destroys the value and de-allocates all memory allocated for that type syntax the value to destroy duckdb_create_varchar creates a value from a null-terminated string syntax the null-terminated string returns the value this must be destroyed with duckdb_destroy_value duckdb_create_varchar_length creates a value from a string syntax the text length the length of the text returns the value this must be destroyed with duckdb_destroy_value duckdb_create_int64 creates a value from an int64 syntax the bigint value returns the value this must be destroyed with duckdb_destroy_value duckdb_get_varchar obtains a string representation of the given value the result must be destroyed with duckdb_free syntax the value returns the string value this must be destroyed with duckdb_free duckdb_get_int64 obtains an int64 of the given value syntax the value returns the int64 value or 0 if no conversion is possible duckdb_create_logical_type creates a duckdb_logical_type from a standard primitive type the resulting type should be destroyed with duckdb_destroy_logical_type this should not be used with duckdb_type_decimal syntax the primitive type to create returns the logical type duckdb_create_list_type creates a list type from its child type the resulting type should be destroyed with duckdb_destroy_logical_type syntax the child type of list type to create returns the logical type duckdb_create_map_type creates a map type from its key type and value type the resulting type should be destroyed with duckdb_destroy_logical_type syntax the key type and value type of map type to create returns the logical type duckdb_create_union_type creates a union type from the passed types array the resulting type should be destroyed with duckdb_destroy_logical_type syntax the array of types that the union should consist of type_amount the size of the types array returns the logical type duckdb_create_decimal_type creates a duckdb_logical_type of type decimal with the specified width and scale the resulting type should be destroyed with duckdb_destroy_logical_type syntax the width of the decimal type scale the scale of the decimal type returns the logical type duckdb_get_type_id retrieves the type class of a duckdb_logical_type syntax the logical type object returns the type id duckdb_decimal_width retrieves the width of a decimal type syntax the logical type object returns the width of the decimal type duckdb_decimal_scale retrieves the scale of a decimal type syntax the logical type object returns the scale of the decimal type duckdb_decimal_internal_type retrieves the internal storage type of a decimal type syntax the logical type object returns the internal type of the decimal type duckdb_enum_internal_type retrieves the internal storage type of an enum type syntax the logical type object returns the internal type of the enum type duckdb_enum_dictionary_size retrieves the dictionary size of the enum type syntax the logical type object returns the dictionary size of the enum type duckdb_enum_dictionary_value retrieves the dictionary value at the specified position from the enum the result must be freed with duckdb_free syntax the logical type object index the index in the dictionary returns the string value of the enum type must be freed with duckdb_free duckdb_list_type_child_type retrieves the child type of the given list type the result must be freed with duckdb_destroy_logical_type syntax the logical type object returns the child type of the list type must be destroyed with duckdb_destroy_logical_type duckdb_map_type_key_type retrieves the key type of the given map type the result must be freed with duckdb_destroy_logical_type syntax the logical type object returns the key type of the map type must be destroyed with duckdb_destroy_logical_type duckdb_map_type_value_type retrieves the value type of the given map type the result must be freed with duckdb_destroy_logical_type syntax the logical type object returns the value type of the map type must be destroyed with duckdb_destroy_logical_type duckdb_struct_type_child_count returns the number of children of a struct type syntax the logical type object returns the number of children of a struct type duckdb_struct_type_child_name retrieves the name of the struct child the result must be freed with duckdb_free syntax the logical type object index the child index returns the name of the struct type must be freed with duckdb_free duckdb_struct_type_child_type retrieves the child type of the given struct type at the specified index the result must be freed with duckdb_destroy_logical_type syntax the logical type object index the child index returns the child type of the struct type must be destroyed with duckdb_destroy_logical_type duckdb_union_type_member_count returns the number of members that the union type has syntax the logical type union object returns the number of members of a union type duckdb_union_type_member_name retrieves the name of the union member the result must be freed with duckdb_free syntax the logical type object index the child index returns the name of the union member must be freed with duckdb_free duckdb_union_type_member_type retrieves the child type of the given union member at the specified index the result must be freed with duckdb_destroy_logical_type syntax the logical type object index the child index returns the child type of the union member must be destroyed with duckdb_destroy_logical_type duckdb_destroy_logical_type destroys the logical type and de-allocates all memory allocated for that type syntax the logical type to destroy duckdb_create_data_chunk creates an empty datachunk with the specified set of types syntax an array of types of the data chunk column_count the number of columns returns the data chunk duckdb_destroy_data_chunk destroys the data chunk and de-allocates all memory allocated for that chunk syntax the data chunk to destroy duckdb_data_chunk_reset resets a data chunk clearing the validity masks and setting the cardinality of the data chunk to 0 syntax the data chunk to reset duckdb_data_chunk_get_column_count retrieves the number of columns in a data chunk syntax the data chunk to get the data from returns the number of columns in the data chunk duckdb_data_chunk_get_vector retrieves the vector at the specified column index in the data chunk the pointer to the vector is valid for as long as the chunk is alive it does not need to be destroyed syntax the data chunk to get the data from returns the vector duckdb_data_chunk_get_size retrieves the current number of tuples in a data chunk syntax the data chunk to get the data from returns the number of tuples in the data chunk duckdb_data_chunk_set_size sets the current number of tuples in a data chunk syntax the data chunk to set the size in size the number of tuples in the data chunk duckdb_vector_get_column_type retrieves the column type of the specified vector the result must be destroyed with duckdb_destroy_logical_type syntax the vector get the data from returns the type of the vector duckdb_vector_get_data retrieves the data pointer of the vector the data pointer can be used to read or write values from the vector how to read or write values depends on the type of the vector syntax the vector to get the data from returns the data pointer duckdb_vector_get_validity retrieves the validity mask pointer of the specified vector if all values are valid this function might return null the validity mask is a bitset that signifies null-ness within the data chunk it is a series of uint64_t values where each uint64_t value contains validity for 64 tuples the bit is set to 1 if the value is valid i e not null or 0 if the value is invalid i e null validity of a specific value can be obtained like this idx_t entry_idx row_idx 64 idx_t idx_in_entry row_idx 64 bool is_valid validity_mask entry_idx 1 idx_in_entry alternatively the slower duckdb_validity_row_is_valid function can be used syntax the vector to get the data from returns the pointer to the validity mask or null if no validity mask is present duckdb_vector_ensure_validity_writable ensures the validity mask is writable by allocating it after this function is called duckdb_vector_get_validity will always return non-null this allows null values to be written to the vector regardless of whether a validity mask was present before syntax the vector to alter duckdb_vector_assign_string_element assigns a string element in the vector at the specified location syntax the vector to alter index the row position in the vector to assign the string to str the null-terminated string duckdb_vector_assign_string_element_len assigns a string element in the vector at the specified location syntax the vector to alter index the row position in the vector to assign the string to str the string str_len the length of the string in bytes duckdb_list_vector_get_child retrieves the child vector of a list vector the resulting vector is valid as long as the parent vector is valid syntax the vector returns the child vector duckdb_list_vector_get_size returns the size of the child vector of the list syntax the vector returns the size of the child list duckdb_list_vector_set_size sets the total size of the underlying child-vector of a list vector syntax the list vector size the size of the child list returns the duckdb state returns duckdberror if the vector is nullptr duckdb_list_vector_reserve sets the total capacity of the underlying child-vector of a list syntax the list vector required_capacity the total capacity to reserve return the duckdb state returns duckdberror if the vector is nullptr duckdb_struct_vector_get_child retrieves the child vector of a struct vector the resulting vector is valid as long as the parent vector is valid syntax the vector index the child index returns the child vector duckdb_validity_row_is_valid returns whether or not a row is valid i e not null in the given validity mask syntax the validity mask as obtained through duckdb_data_chunk_get_validity row the row index returns true if the row is valid false otherwise duckdb_validity_set_row_validity in a validity mask sets a specific row to either valid or invalid note that duckdb_data_chunk_ensure_validity_writable should be called before calling duckdb_data_chunk_get_validity to ensure that there is a validity mask to write to syntax the validity mask as obtained through duckdb_data_chunk_get_validity row the row index valid whether or not to set the row to valid or invalid duckdb_validity_set_row_invalid in a validity mask sets a specific row to invalid equivalent to duckdb_validity_set_row_validity with valid set to false syntax the validity mask row the row index duckdb_validity_set_row_valid in a validity mask sets a specific row to valid equivalent to duckdb_validity_set_row_validity with valid set to true syntax the validity mask row the row index duckdb_create_table_function creates a new empty table function the return value should be destroyed with duckdb_destroy_table_function syntax the table function object duckdb_destroy_table_function destroys the given table function object syntax the table function to destroy duckdb_table_function_set_name sets the name of the given table function syntax the table function name the name of the table function duckdb_table_function_add_parameter adds a parameter to the table function syntax 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 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 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 the table function bind the bind function duckdb_table_function_set_init sets the init function of the table function syntax the table function init the init function duckdb_table_function_set_local_init sets the thread-local init function of the table function syntax the table function init the init function duckdb_table_function_set_function sets the main function of the table function syntax 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 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 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 the info object returns the extra info duckdb_bind_add_result_column adds a result column to the output of the table function syntax 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 the info object returns the init data object duckdb_function_set_error report that an error has occurred while executing the function syntax the info object error the error message duckdb_add_replacement_scan add a replacement scan definition to the specified database syntax the database object to add the replacement scan to replacement the replacement scan callback extra_data extra data that is passed back into the specified callback delete_callback the delete callback to call on the extra data if any duckdb_replacement_scan_set_function_name sets the replacement function name to use if this function is called in the replacement callback the replacement scan is performed if it is not called the replacement callback is not performed syntax the info object function_name the function name to substitute duckdb_replacement_scan_add_parameter adds a parameter to the replacement scan function syntax the info object parameter the parameter to add duckdb_replacement_scan_set_error report that an error has occurred while executing the replacement scan syntax the info object error the error message duckdb_appender_create creates an appender object syntax the connection context to create the appender in schema the schema of the table to append to or nullptr for the default schema table the table name to append to out_appender the resulting appender object returns duckdbsuccess on success or duckdberror on failure duckdb_appender_error returns the error message associated with the given appender if the appender has no error message this returns nullptr instead the error message should not be freed it will be de-allocated when duckdb_appender_destroy is called syntax the appender to get the error from returns the error message or nullptr if there is none duckdb_appender_flush flush the appender to the table forcing the cache of the appender to be cleared and the data to be appended to the base table this should generally not be used unless you know what you are doing instead call duckdb_appender_destroy when you are done with the appender syntax the appender to flush returns duckdbsuccess on success or duckdberror on failure duckdb_appender_close close the appender flushing all intermediate state in the appender to the table and closing it for further appends this is generally not necessary call duckdb_appender_destroy instead syntax the appender to flush and close returns duckdbsuccess on success or duckdberror on failure duckdb_appender_destroy close the appender and destroy it flushing all intermediate state in the appender to the table and de-allocating all memory associated with the appender syntax the appender to flush close and destroy returns duckdbsuccess on success or duckdberror on failure duckdb_appender_begin_row a nop function provided for backwards compatibility reasons does nothing only duckdb_appender_end_row is required syntax duckdb_appender_end_row finish the current row of appends after end_row is called the next row can be appended syntax the appender returns duckdbsuccess on success or duckdberror on failure duckdb_append_bool append a bool value to the appender syntax duckdb_append_int8 append an int8_t value to the appender syntax duckdb_append_int16 append an int16_t value to the appender syntax duckdb_append_int32 append an int32_t value to the appender syntax duckdb_append_int64 append an int64_t value to the appender syntax duckdb_append_hugeint append a duckdb_hugeint value to the appender syntax duckdb_append_uint8 append a uint8_t value to the appender syntax duckdb_append_uint16 append a uint16_t value to the appender syntax duckdb_append_uint32 append a uint32_t value to the appender syntax duckdb_append_uint64 append a uint64_t value to the appender syntax duckdb_append_float append a float value to the appender syntax duckdb_append_double append a double value to the appender syntax duckdb_append_date append a duckdb_date value to the appender syntax duckdb_append_time append a duckdb_time value to the appender syntax duckdb_append_timestamp append a duckdb_timestamp value to the appender syntax duckdb_append_interval append a duckdb_interval value to the appender syntax duckdb_append_varchar append a varchar value to the appender syntax duckdb_append_varchar_length append a varchar value to the appender syntax duckdb_append_blob append a blob value to the appender syntax duckdb_append_null append a null value to the appender of any type syntax duckdb_append_data_chunk appends a pre-filled data chunk to the specified appender the types of the data chunk must exactly match the types of the table no casting is performed if the types do not match or the appender is in an invalid state duckdberror is returned if the append is successful duckdbsuccess is returned syntax the appender to append to chunk the data chunk to append returns the return state duckdb_query_arrow executes a sql query within a connection and stores the full materialized result in an arrow structure if the query fails to execute duckdberror is returned and the error message can be retrieved by calling duckdb_query_arrow_error note that after running duckdb_query_arrow duckdb_destroy_arrow must be called on the result object even if the query fails otherwise the error stored within the result will not be freed correctly syntax the connection to perform the query in query the sql query to run out_result the query result returns duckdbsuccess on success or duckdberror on failure duckdb_query_arrow_schema fetch the internal arrow schema from the arrow result syntax the result to fetch the schema from out_schema the output schema returns duckdbsuccess on success or duckdberror on failure duckdb_prepared_arrow_schema fetch the internal arrow schema from the prepared statement syntax the prepared statement to fetch the schema from out_schema the output schema returns duckdbsuccess on success or duckdberror on failure duckdb_query_arrow_array fetch an internal arrow array from the arrow result this function can be called multiple time to get next chunks which will free the previous out_array so consume the out_array before calling this function again syntax the result to fetch the array from out_array the output array returns duckdbsuccess on success or duckdberror on failure duckdb_arrow_column_count returns the number of columns present in a the arrow result object syntax the result object returns the number of columns present in the result object duckdb_arrow_row_count returns the number of rows present in a the arrow result object syntax the result object returns the number of rows present in the result object duckdb_arrow_rows_changed returns the number of rows changed by the query stored in the arrow result this is relevant only for insert update delete queries for other queries the rows_changed will be 0 syntax the result object returns the number of rows changed duckdb_query_arrow_error returns the error message contained within the result the error is only set if duckdb_query_arrow returns duckdberror the error message should not be freed it will be de-allocated when duckdb_destroy_arrow is called syntax the result object to fetch the nullmask from returns the error of the result duckdb_destroy_arrow closes the result and de-allocates all memory allocated for the arrow result syntax the result to destroy duckdb_execute_tasks execute duckdb tasks on this thread will return after max_tasks have been executed or if there are no more tasks present syntax the database object to execute tasks for max_tasks the maximum amount of tasks to execute duckdb_create_task_state creates a task state that can be used with duckdb_execute_tasks_state to execute tasks until duckdb_finish_execution is called on the state duckdb_destroy_state should be called on the result in order to free memory syntax the database object to create the task state for returns the task state that can be used with duckdb_execute_tasks_state duckdb_execute_tasks_state execute duckdb tasks on this thread the thread will keep on executing tasks forever until duckdb_finish_execution is called on the state multiple threads can share the same duckdb_task_state syntax the task state of the executor duckdb_execute_n_tasks_state execute duckdb tasks on this thread the thread will keep on executing tasks until either duckdb_finish_execution is called on the state max_tasks tasks have been executed or there are no more tasks to be executed multiple threads can share the same duckdb_task_state syntax the task state of the executor max_tasks the maximum amount of tasks to execute returns the amount of tasks that have actually been executed duckdb_finish_execution finish execution on a specific task syntax the task state to finish execution duckdb_task_state_is_finished check if the provided duckdb_task_state has finished execution syntax the task state to inspect returns whether or not duckdb_finish_execution has been called on the task state duckdb_destroy_task_state destroys the task state returned from duckdb_create_task_state note that this should not be called while there is an active duckdb_execute_tasks_state running on the task state syntax the task state to clean up duckdb_execution_is_finished returns true if execution of the current query is finished syntax the connection on which to check duckdb_stream_fetch_chunk fetches a data chunk from the streaming duckdb_result this function should be called repeatedly until the result is exhausted the result must be destroyed with duckdb_destroy_data_chunk this function can only be used on duckdb_results created with duckdb_pending_prepared_streaming if this function is used none of the other result functions can be used and vice versa i e this function cannot be mixed with the legacy result functions or the materialized result functions it is not known beforehand how many chunks will be returned by this result syntax the result object to fetch the data chunk from returns the resulting data chunk returns null if the result has an error", "category": "C", "url": "/docs/api/c/api", "blurb": "API Reference Open/Connect Syntax Path to the database file on disk, or nullptr or :memory: to open an in-memory..." @@ -191,7 +191,7 @@ }, { "title": "C API - Prepared Statements", - "text": "a prepared statement is a parameterized query the query is prepared with question marks or dollar symbols 1 indicating the parameters of the query values can then be bound to these parameters after which the prepared statement can be executed using those parameters a single query can be prepared once and executed many times prepared statements are useful to easily supply parameters to functions while avoiding string concatenation sql injection attacks speeding up queries that will be executed many times with different parameters duckdb supports prepared statements in the c api with the duckdb_prepare method the duckdb_bind family of functions is used to supply values for subsequent execution of the prepared statement using duckdb_execute_prepared after we are done with the prepared statement it can be cleaned up using the duckdb_destroy_prepare method example duckdb_prepared_statement stmt duckdb_result result if duckdb_prepare con insert into integers values 1 2 stmt duckdberror handle error duckdb_bind_int32 stmt 1 42 the parameter index starts counting at 1 duckdb_bind_int32 stmt 2 43 null as second parameter means no result set is requested duckdb_execute_prepared stmt null duckdb_destroy_prepare stmt we can also query result sets using prepared statements if duckdb_prepare con select from integers where i stmt duckdberror handle error duckdb_bind_int32 stmt 1 42 duckdb_execute_prepared stmt result do something with result clean up duckdb_destroy_result result duckdb_destroy_prepare stmt after calling duckdb_prepare the prepared statement parameters can be inspected using duckdb_nparams and duckdb_param_type in case the prepare fails the error can be obtained through duckdb_prepare_error it is not required that the duckdb_bind family of functions matches the prepared statement parameter type exactly the values will be auto-cast to the required value as required for example calling duckdb_bind_int8 on a parameter type of duckdb_type_integer will work as expected do not use prepared statements to insert large amounts of data into duckdb instead it is recommended to use the appender api reference note that after calling duckdb_prepare the prepared statement should always be destroyed using duckdb_destroy_prepare even if the prepare fails if the prepare fails duckdb_prepare_error can be called to obtain the reason why the prepare failed syntax the connection object query the sql query to prepare out_prepared_statement the resulting prepared statement object returns duckdbsuccess on success or duckdberror on failure duckdb_destroy_prepare closes the prepared statement and de-allocates all memory allocated for the statement syntax the prepared statement to destroy duckdb_prepare_error returns the error message associated with the given prepared statement if the prepared statement has no error message this returns nullptr instead the error message should not be freed it will be de-allocated when duckdb_destroy_prepare is called syntax the prepared statement to obtain the error from returns the error message or nullptr if there is none duckdb_nparams returns the number of parameters that can be provided to the given prepared statement returns 0 if the query was not successfully prepared syntax the prepared statement to obtain the number of parameters for duckdb_param_type returns the parameter type for the parameter at the given index returns duckdb_type_invalid if the parameter index is out of range or the statement was not successfully prepared syntax the prepared statement param_idx the parameter index returns the parameter type duckdb_clear_bindings clear the params bind to the prepared statement syntax duckdb_bind_parameter_index retrieve the index of the parameter for the prepared statement identified by name syntax duckdb_bind_boolean binds a bool value to the prepared statement at the specified index syntax duckdb_bind_int8 binds an int8_t value to the prepared statement at the specified index syntax duckdb_bind_int16 binds an int16_t value to the prepared statement at the specified index syntax duckdb_bind_int32 binds an int32_t value to the prepared statement at the specified index syntax duckdb_bind_int64 binds an int64_t value to the prepared statement at the specified index syntax duckdb_bind_hugeint binds an duckdb_hugeint value to the prepared statement at the specified index syntax duckdb_bind_decimal binds a duckdb_decimal value to the prepared statement at the specified index syntax duckdb_bind_uint8 binds an uint8_t value to the prepared statement at the specified index syntax duckdb_bind_uint16 binds an uint16_t value to the prepared statement at the specified index syntax duckdb_bind_uint32 binds an uint32_t value to the prepared statement at the specified index syntax duckdb_bind_uint64 binds an uint64_t value to the prepared statement at the specified index syntax duckdb_bind_float binds an float value to the prepared statement at the specified index syntax duckdb_bind_double binds an double value to the prepared statement at the specified index syntax duckdb_bind_date binds a duckdb_date value to the prepared statement at the specified index syntax duckdb_bind_time binds a duckdb_time value to the prepared statement at the specified index syntax duckdb_bind_timestamp binds a duckdb_timestamp value to the prepared statement at the specified index syntax duckdb_bind_interval binds a duckdb_interval value to the prepared statement at the specified index syntax duckdb_bind_varchar binds a null-terminated varchar value to the prepared statement at the specified index syntax duckdb_bind_varchar_length binds a varchar value to the prepared statement at the specified index syntax duckdb_bind_blob binds a blob value to the prepared statement at the specified index syntax duckdb_bind_null binds a null value to the prepared statement at the specified index syntax duckdb_execute_prepared executes the prepared statement with the given bound parameters and returns a materialized query result this method can be called multiple times for each prepared statement and the parameters can be modified between calls to this function syntax the prepared statement to execute out_result the query result returns duckdbsuccess on success or duckdberror on failure duckdb_execute_prepared_arrow executes the prepared statement with the given bound parameters and returns an arrow query result syntax the prepared statement to execute out_result the query result returns duckdbsuccess on success or duckdberror on failure duckdb_arrow_scan scans the arrow stream and creates a view with the given name syntax the connection on which to execute the scan table_name name of the temporary view to create arrow arrow stream wrapper returns duckdbsuccess on success or duckdberror on failure duckdb_arrow_array_scan scans the arrow array and creates a view with the given name syntax the connection on which to execute the scan table_name name of the temporary view to create arrow_schema arrow schema wrapper arrow_array arrow array wrapper out_stream output array stream that wraps around the passed schema for releasing deleting once done returns duckdbsuccess on success or duckdberror on failure", + "text": "a prepared statement is a parameterized query the query is prepared with question marks or dollar symbols 1 indicating the parameters of the query values can then be bound to these parameters after which the prepared statement can be executed using those parameters a single query can be prepared once and executed many times prepared statements are useful to easily supply parameters to functions while avoiding string concatenation sql injection attacks speeding up queries that will be executed many times with different parameters duckdb supports prepared statements in the c api with the duckdb_prepare method the duckdb_bind family of functions is used to supply values for subsequent execution of the prepared statement using duckdb_execute_prepared after we are done with the prepared statement it can be cleaned up using the duckdb_destroy_prepare method example duckdb_prepared_statement stmt duckdb_result result if duckdb_prepare con insert into integers values 1 2 stmt duckdberror handle error duckdb_bind_int32 stmt 1 42 the parameter index starts counting at 1 duckdb_bind_int32 stmt 2 43 null as second parameter means no result set is requested duckdb_execute_prepared stmt null duckdb_destroy_prepare stmt we can also query result sets using prepared statements if duckdb_prepare con select from integers where i stmt duckdberror handle error duckdb_bind_int32 stmt 1 42 duckdb_execute_prepared stmt result do something with result clean up duckdb_destroy_result result duckdb_destroy_prepare stmt after calling duckdb_prepare the prepared statement parameters can be inspected using duckdb_nparams and duckdb_param_type in case the prepare fails the error can be obtained through duckdb_prepare_error it is not required that the duckdb_bind family of functions matches the prepared statement parameter type exactly the values will be auto-cast to the required value as required for example calling duckdb_bind_int8 on a parameter type of duckdb_type_integer will work as expected do not use prepared statements to insert large amounts of data into duckdb instead it is recommended to use the appender api reference note that after calling duckdb_prepare the prepared statement should always be destroyed using duckdb_destroy_prepare even if the prepare fails if the prepare fails duckdb_prepare_error can be called to obtain the reason why the prepare failed syntax the connection object query the sql query to prepare out_prepared_statement the resulting prepared statement object returns duckdbsuccess on success or duckdberror on failure duckdb_destroy_prepare closes the prepared statement and de-allocates all memory allocated for the statement syntax the prepared statement to destroy duckdb_prepare_error returns the error message associated with the given prepared statement if the prepared statement has no error message this returns nullptr instead the error message should not be freed it will be de-allocated when duckdb_destroy_prepare is called syntax the prepared statement to obtain the error from returns the error message or nullptr if there is none duckdb_nparams returns the number of parameters that can be provided to the given prepared statement returns 0 if the query was not successfully prepared syntax the prepared statement to obtain the number of parameters for duckdb_param_type returns the parameter type for the parameter at the given index returns duckdb_type_invalid if the parameter index is out of range or the statement was not successfully prepared syntax the prepared statement param_idx the parameter index returns the parameter type duckdb_clear_bindings clear the params bind to the prepared statement syntax duckdb_bind_value binds a value to the prepared statement at the specified index syntax duckdb_bind_parameter_index retrieve the index of the parameter for the prepared statement identified by name syntax duckdb_bind_boolean binds a bool value to the prepared statement at the specified index syntax duckdb_bind_int8 binds an int8_t value to the prepared statement at the specified index syntax duckdb_bind_int16 binds an int16_t value to the prepared statement at the specified index syntax duckdb_bind_int32 binds an int32_t value to the prepared statement at the specified index syntax duckdb_bind_int64 binds an int64_t value to the prepared statement at the specified index syntax duckdb_bind_hugeint binds an duckdb_hugeint value to the prepared statement at the specified index syntax duckdb_bind_decimal binds a duckdb_decimal value to the prepared statement at the specified index syntax duckdb_bind_uint8 binds an uint8_t value to the prepared statement at the specified index syntax duckdb_bind_uint16 binds an uint16_t value to the prepared statement at the specified index syntax duckdb_bind_uint32 binds an uint32_t value to the prepared statement at the specified index syntax duckdb_bind_uint64 binds an uint64_t value to the prepared statement at the specified index syntax duckdb_bind_float binds an float value to the prepared statement at the specified index syntax duckdb_bind_double binds an double value to the prepared statement at the specified index syntax duckdb_bind_date binds a duckdb_date value to the prepared statement at the specified index syntax duckdb_bind_time binds a duckdb_time value to the prepared statement at the specified index syntax duckdb_bind_timestamp binds a duckdb_timestamp value to the prepared statement at the specified index syntax duckdb_bind_interval binds a duckdb_interval value to the prepared statement at the specified index syntax duckdb_bind_varchar binds a null-terminated varchar value to the prepared statement at the specified index syntax duckdb_bind_varchar_length binds a varchar value to the prepared statement at the specified index syntax duckdb_bind_blob binds a blob value to the prepared statement at the specified index syntax duckdb_bind_null binds a null value to the prepared statement at the specified index syntax duckdb_execute_prepared executes the prepared statement with the given bound parameters and returns a materialized query result this method can be called multiple times for each prepared statement and the parameters can be modified between calls to this function syntax the prepared statement to execute out_result the query result returns duckdbsuccess on success or duckdberror on failure duckdb_execute_prepared_arrow executes the prepared statement with the given bound parameters and returns an arrow query result syntax the prepared statement to execute out_result the query result returns duckdbsuccess on success or duckdberror on failure duckdb_arrow_scan scans the arrow stream and creates a view with the given name syntax the connection on which to execute the scan table_name name of the temporary view to create arrow arrow stream wrapper returns duckdbsuccess on success or duckdberror on failure duckdb_arrow_array_scan scans the arrow array and creates a view with the given name syntax the connection on which to execute the scan table_name name of the temporary view to create arrow_schema arrow schema wrapper arrow_array arrow array wrapper out_stream output array stream that wraps around the passed schema for releasing deleting once done returns duckdbsuccess on success or duckdberror on failure", "category": "C", "url": "/docs/api/c/prepared", "blurb": "A prepared statement is a parameterized query. The query is prepared with question marks ( ? ) or dollar symbols ( $1..." @@ -1087,10 +1087,10 @@ }, { "title": "Python Client API", - "text": "span class target id module-duckdb span dl class py data", + "text": "", "category": "Reference", "url": "/docs/api/python/reference/index", - "blurb": "
" + "blurb": "" }, { "title": "Python DB API", diff --git a/docs/api/c/api.md b/docs/api/c/api.md index 49cb6700fa7..cce5b24d559 100644 --- a/docs/api/c/api.md +++ b/docs/api/c/api.md @@ -91,6 +91,7 @@ selected: API Reference idx_t duckdb_nparams(duckdb_prepared_statement prepared_statement); duckdb_type duckdb_param_type(duckdb_prepared_statement prepared_statement, idx_t param_idx); duckdb_state duckdb_clear_bindings(duckdb_prepared_statement prepared_statement); +duckdb_state duckdb_bind_value(duckdb_prepared_statement prepared_statement, idx_t param_idx, duckdb_value val); duckdb_state duckdb_bind_parameter_index(duckdb_prepared_statement prepared_statement, idx_t *param_idx_out, const char *name); duckdb_state duckdb_bind_boolean(duckdb_prepared_statement prepared_statement, idx_t param_idx, bool val); duckdb_state duckdb_bind_int8(duckdb_prepared_statement prepared_statement, idx_t param_idx, int8_t val); @@ -272,6 +273,7 @@ selected: API Reference ### **Arrow Interface** 
duckdb_state duckdb_query_arrow(duckdb_connection connection, const char *query, duckdb_arrow *out_result);
 duckdb_state duckdb_query_arrow_schema(duckdb_arrow result, duckdb_arrow_schema *out_schema);
+duckdb_state duckdb_prepared_arrow_schema(duckdb_prepared_statement prepared, duckdb_arrow_schema *out_schema);
 duckdb_state duckdb_query_arrow_array(duckdb_arrow result, duckdb_arrow_array *out_array);
 idx_t duckdb_arrow_column_count(duckdb_arrow result);
 idx_t duckdb_arrow_row_count(duckdb_arrow result);
@@ -1815,6 +1817,20 @@ Clear the params bind to the prepared statement.

+### duckdb_bind_value +--- +Binds a value to the prepared statement at the specified index. + +#### Syntax +--- +
duckdb_state duckdb_bind_value(
+  duckdb_prepared_statement prepared_statement,
+  idx_t param_idx,
+  duckdb_value val
+);
+
+
+ ### duckdb_bind_parameter_index --- Retrieve the index of the parameter for the prepared statement, identified by name @@ -5047,6 +5063,31 @@ The output schema.
+### duckdb_prepared_arrow_schema +--- +Fetch the internal arrow schema from the prepared statement. + +#### Syntax +--- +
duckdb_state duckdb_prepared_arrow_schema(
+  duckdb_prepared_statement prepared,
+  duckdb_arrow_schema *out_schema
+);
+
+#### Parameters +--- +* `result` + +The prepared statement to fetch the schema from. +* `out_schema` + +The output schema. +* `returns` + +`DuckDBSuccess` on success or `DuckDBError` on failure. + +
+ ### duckdb_query_arrow_array --- Fetch an internal arrow array from the arrow result. diff --git a/docs/api/c/prepared.md b/docs/api/c/prepared.md index 79ea6d3879d..c9ae8a04480 100644 --- a/docs/api/c/prepared.md +++ b/docs/api/c/prepared.md @@ -53,6 +53,7 @@ It is not required that the `duckdb_bind` family of functions matches the prepar idx_t duckdb_nparams(duckdb_prepared_statement prepared_statement); duckdb_type duckdb_param_type(duckdb_prepared_statement prepared_statement, idx_t param_idx); duckdb_state duckdb_clear_bindings(duckdb_prepared_statement prepared_statement); +duckdb_state duckdb_bind_value(duckdb_prepared_statement prepared_statement, idx_t param_idx, duckdb_value val); duckdb_state duckdb_bind_parameter_index(duckdb_prepared_statement prepared_statement, idx_t *param_idx_out, const char *name); duckdb_state duckdb_bind_boolean(duckdb_prepared_statement prepared_statement, idx_t param_idx, bool val); duckdb_state duckdb_bind_int8(duckdb_prepared_statement prepared_statement, idx_t param_idx, int8_t val); @@ -215,6 +216,20 @@ Clear the params bind to the prepared statement.
+### duckdb_bind_value +--- +Binds a value to the prepared statement at the specified index. + +#### Syntax +--- +
duckdb_state duckdb_bind_value(
+  duckdb_prepared_statement prepared_statement,
+  idx_t param_idx,
+  duckdb_value val
+);
+
+
+ ### duckdb_bind_parameter_index --- Retrieve the index of the parameter for the prepared statement, identified by name diff --git a/docs/api/python/reference/index.md b/docs/api/python/reference/index.md index 2cfd543d693..5c066c3911a 100644 --- a/docs/api/python/reference/index.md +++ b/docs/api/python/reference/index.md @@ -8,9 +8,9 @@ title: Python Client API
-
+
-duckdb.threadsafety bool +duckdb.threadsafety bool

Indicates that this package is threadsafe

@@ -19,7 +19,7 @@ title: Python Client API
-duckdb.apilevel int +duckdb.apilevel int

Indicates which Python DBAPI version this package implements

@@ -28,7 +28,7 @@ title: Python Client API
-duckdb.paramstyle str +duckdb.paramstyle str

Indicates which parameter style duckdb supports

@@ -37,7 +37,7 @@ title: Python Client API
-duckdb.default_connection duckdb.DuckDBPyConnection +duckdb.default_connection duckdb.DuckDBPyConnection

The connection that is used by default if you don’t explicitly pass one to the root methods in this module

@@ -46,7 +46,7 @@ title: Python Client API
-exception duckdb.BinderException +exception duckdb.BinderException

Bases: ProgrammingError

@@ -55,7 +55,7 @@ title: Python Client API
-exception duckdb.CastException +exception duckdb.CastException

Bases: DataError

@@ -64,7 +64,7 @@ title: Python Client API
-exception duckdb.CatalogException +exception duckdb.CatalogException

Bases: ProgrammingError

@@ -73,7 +73,7 @@ title: Python Client API
-exception duckdb.ConnectionException +exception duckdb.ConnectionException

Bases: OperationalError

@@ -82,7 +82,7 @@ title: Python Client API
-exception duckdb.ConstraintException +exception duckdb.ConstraintException

Bases: IntegrityError

@@ -91,7 +91,7 @@ title: Python Client API
-exception duckdb.ConversionException +exception duckdb.ConversionException

Bases: DataError

@@ -100,7 +100,7 @@ title: Python Client API
-exception duckdb.DataError +exception duckdb.DataError

Bases: Error

@@ -109,13 +109,13 @@ title: Python Client API
-class duckdb.DuckDBPyConnection +class duckdb.DuckDBPyConnection

Bases: pybind11_object

-append(self: duckdb.duckdb.DuckDBPyConnection, table_name: str, df: pandas.DataFrame, *, by_name: bool = False) → duckdb.duckdb.DuckDBPyConnection +append(self: duckdb.duckdb.DuckDBPyConnection, table_name: str, df: pandas.DataFrame, *, by_name: bool = False) → duckdb.duckdb.DuckDBPyConnection

Append the passed DataFrame to the named table

@@ -124,7 +124,7 @@ title: Python Client API
-array_type(self: duckdb.duckdb.DuckDBPyConnection, type: duckdb.duckdb.typing.DuckDBPyType) → duckdb.duckdb.typing.DuckDBPyType +array_type(self: duckdb.duckdb.DuckDBPyConnection, type: duckdb.duckdb.typing.DuckDBPyType) → duckdb.duckdb.typing.DuckDBPyType

Create an array type object of ‘type’

@@ -133,7 +133,7 @@ title: Python Client API
-arrow(self: duckdb.duckdb.DuckDBPyConnection, rows_per_batch: int = 1000000) → pyarrow.lib.Table +arrow(self: duckdb.duckdb.DuckDBPyConnection, rows_per_batch: int = 1000000) → pyarrow.lib.Table

Fetch a result as Arrow table following execute()

@@ -142,7 +142,7 @@ title: Python Client API
-begin(self: duckdb.duckdb.DuckDBPyConnection) → duckdb.duckdb.DuckDBPyConnection +begin(self: duckdb.duckdb.DuckDBPyConnection) → duckdb.duckdb.DuckDBPyConnection

Start a new transaction

@@ -151,7 +151,7 @@ title: Python Client API
-close(self: duckdb.duckdb.DuckDBPyConnection) → None +close(self: duckdb.duckdb.DuckDBPyConnection) → None

Close the connection

@@ -160,7 +160,7 @@ title: Python Client API
-commit(self: duckdb.duckdb.DuckDBPyConnection) → duckdb.duckdb.DuckDBPyConnection +commit(self: duckdb.duckdb.DuckDBPyConnection) → duckdb.duckdb.DuckDBPyConnection

Commit changes performed within a transaction

@@ -169,7 +169,7 @@ title: Python Client API
-create_function(self: duckdb.duckdb.DuckDBPyConnection, name: str, function: function, return_type: object = None, parameters: duckdb.duckdb.typing.DuckDBPyType = None, *, type: duckdb.duckdb.functional.PythonUDFType = <PythonUDFType.NATIVE: 0>, null_handling: duckdb.duckdb.functional.FunctionNullHandling = 0, exception_handling: duckdb.duckdb.PythonExceptionHandling = 0, side_effects: bool = False) → duckdb.duckdb.DuckDBPyConnection +create_function(self: duckdb.duckdb.DuckDBPyConnection, name: str, function: function, return_type: object = None, parameters: duckdb.duckdb.typing.DuckDBPyType = None, *, type: duckdb.duckdb.functional.PythonUDFType = <PythonUDFType.NATIVE: 0>, null_handling: duckdb.duckdb.functional.FunctionNullHandling = 0, exception_handling: duckdb.duckdb.PythonExceptionHandling = 0, side_effects: bool = False) → duckdb.duckdb.DuckDBPyConnection

Create a DuckDB function out of the passing in python function so it can be used in queries

@@ -178,7 +178,7 @@ title: Python Client API
-cursor(self: duckdb.duckdb.DuckDBPyConnection) → duckdb.duckdb.DuckDBPyConnection +cursor(self: duckdb.duckdb.DuckDBPyConnection) → duckdb.duckdb.DuckDBPyConnection

Create a duplicate of the current connection

@@ -187,7 +187,7 @@ title: Python Client API
-decimal_type(self: duckdb.duckdb.DuckDBPyConnection, width: int, scale: int) → duckdb.duckdb.typing.DuckDBPyType +decimal_type(self: duckdb.duckdb.DuckDBPyConnection, width: int, scale: int) → duckdb.duckdb.typing.DuckDBPyType

Create a decimal type with ‘width’ and ‘scale’

@@ -196,7 +196,7 @@ title: Python Client API
-property description +property description

Get result set attributes, mainly column names

@@ -205,7 +205,7 @@ title: Python Client API
-df(self: duckdb.duckdb.DuckDBPyConnection, *, date_as_object: bool = False) → pandas.DataFrame +df(self: duckdb.duckdb.DuckDBPyConnection, *, date_as_object: bool = False) → pandas.DataFrame

Fetch a result as DataFrame following execute()

@@ -214,7 +214,7 @@ title: Python Client API
-dtype(self: duckdb.duckdb.DuckDBPyConnection, type_str: str) → duckdb.duckdb.typing.DuckDBPyType +dtype(self: duckdb.duckdb.DuckDBPyConnection, type_str: str) → duckdb.duckdb.typing.DuckDBPyType

Create a type object by parsing the ‘type_str’ string

@@ -223,7 +223,7 @@ title: Python Client API
-duplicate(self: duckdb.duckdb.DuckDBPyConnection) → duckdb.duckdb.DuckDBPyConnection +duplicate(self: duckdb.duckdb.DuckDBPyConnection) → duckdb.duckdb.DuckDBPyConnection

Create a duplicate of the current connection

@@ -232,7 +232,7 @@ title: Python Client API
-enum_type(self: duckdb.duckdb.DuckDBPyConnection, name: str, type: duckdb.duckdb.typing.DuckDBPyType, values: list) → duckdb.duckdb.typing.DuckDBPyType +enum_type(self: duckdb.duckdb.DuckDBPyConnection, name: str, type: duckdb.duckdb.typing.DuckDBPyType, values: list) → duckdb.duckdb.typing.DuckDBPyType

Create an enum type of underlying ‘type’, consisting of the list of ‘values’

@@ -241,7 +241,7 @@ title: Python Client API
-execute(self: duckdb.duckdb.DuckDBPyConnection, query: str, parameters: object = None, multiple_parameter_sets: bool = False) → duckdb.duckdb.DuckDBPyConnection +execute(self: duckdb.duckdb.DuckDBPyConnection, query: str, parameters: object = None, multiple_parameter_sets: bool = False) → duckdb.duckdb.DuckDBPyConnection

Execute the given SQL query, optionally using prepared statements with parameters set

@@ -250,7 +250,7 @@ title: Python Client API
-executemany(self: duckdb.duckdb.DuckDBPyConnection, query: str, parameters: object = None) → duckdb.duckdb.DuckDBPyConnection +executemany(self: duckdb.duckdb.DuckDBPyConnection, query: str, parameters: object = None) → duckdb.duckdb.DuckDBPyConnection

Execute the given prepared statement multiple times using the list of parameter sets in parameters

@@ -259,7 +259,7 @@ title: Python Client API
-fetch_arrow_table(self: duckdb.duckdb.DuckDBPyConnection, rows_per_batch: int = 1000000) → pyarrow.lib.Table +fetch_arrow_table(self: duckdb.duckdb.DuckDBPyConnection, rows_per_batch: int = 1000000) → pyarrow.lib.Table

Fetch a result as Arrow table following execute()

@@ -268,7 +268,7 @@ title: Python Client API
-fetch_df(self: duckdb.duckdb.DuckDBPyConnection, *, date_as_object: bool = False) → pandas.DataFrame +fetch_df(self: duckdb.duckdb.DuckDBPyConnection, *, date_as_object: bool = False) → pandas.DataFrame

Fetch a result as DataFrame following execute()

@@ -277,7 +277,7 @@ title: Python Client API
-fetch_df_chunk(self: duckdb.duckdb.DuckDBPyConnection, vectors_per_chunk: int = 1, *, date_as_object: bool = False) → pandas.DataFrame +fetch_df_chunk(self: duckdb.duckdb.DuckDBPyConnection, vectors_per_chunk: int = 1, *, date_as_object: bool = False) → pandas.DataFrame

Fetch a chunk of the result as Data.Frame following execute()

@@ -286,7 +286,7 @@ title: Python Client API
-fetch_record_batch(self: duckdb.duckdb.DuckDBPyConnection, rows_per_batch: int = 1000000) → pyarrow.lib.RecordBatchReader +fetch_record_batch(self: duckdb.duckdb.DuckDBPyConnection, rows_per_batch: int = 1000000) → pyarrow.lib.RecordBatchReader

Fetch an Arrow RecordBatchReader following execute()

@@ -295,7 +295,7 @@ title: Python Client API
-fetchall(self: duckdb.duckdb.DuckDBPyConnection) → list +fetchall(self: duckdb.duckdb.DuckDBPyConnection) → list

Fetch all rows from a result following execute

@@ -304,7 +304,7 @@ title: Python Client API
-fetchdf(self: duckdb.duckdb.DuckDBPyConnection, *, date_as_object: bool = False) → pandas.DataFrame +fetchdf(self: duckdb.duckdb.DuckDBPyConnection, *, date_as_object: bool = False) → pandas.DataFrame

Fetch a result as DataFrame following execute()

@@ -313,7 +313,7 @@ title: Python Client API
-fetchmany(self: duckdb.duckdb.DuckDBPyConnection, size: int = 1) → list +fetchmany(self: duckdb.duckdb.DuckDBPyConnection, size: int = 1) → list

Fetch the next set of rows from a result following execute

@@ -322,7 +322,7 @@ title: Python Client API
-fetchnumpy(self: duckdb.duckdb.DuckDBPyConnection) → dict +fetchnumpy(self: duckdb.duckdb.DuckDBPyConnection) → dict

Fetch a result as list of NumPy arrays following execute

@@ -331,7 +331,7 @@ title: Python Client API
-fetchone(self: duckdb.duckdb.DuckDBPyConnection) → Optional[tuple] +fetchone(self: duckdb.duckdb.DuckDBPyConnection) → Optional[tuple]

Fetch a single row from a result following execute

@@ -340,7 +340,7 @@ title: Python Client API
-filesystem_is_registered(self: duckdb.duckdb.DuckDBPyConnection, name: str) → bool +filesystem_is_registered(self: duckdb.duckdb.DuckDBPyConnection, name: str) → bool

Check if a filesystem with the provided name is currently registered

@@ -349,7 +349,7 @@ title: Python Client API
-from_arrow(self: duckdb.duckdb.DuckDBPyConnection, arrow_object: object) → duckdb.duckdb.DuckDBPyRelation +from_arrow(self: duckdb.duckdb.DuckDBPyConnection, arrow_object: object) → duckdb.duckdb.DuckDBPyRelation

Create a relation object from an Arrow object

@@ -358,7 +358,7 @@ title: Python Client API
-from_csv_auto(self: duckdb.duckdb.DuckDBPyConnection, name: object, *, header: object = None, compression: object = None, sep: object = None, delimiter: object = None, dtype: object = None, na_values: object = None, skiprows: object = None, quotechar: object = None, escapechar: object = None, encoding: object = None, parallel: object = None, date_format: object = None, timestamp_format: object = None, sample_size: object = None, all_varchar: object = None, normalize_names: object = None, filename: object = None, null_padding: object = None) → duckdb.duckdb.DuckDBPyRelation +from_csv_auto(self: duckdb.duckdb.DuckDBPyConnection, name: object, *, header: object = None, compression: object = None, sep: object = None, delimiter: object = None, dtype: object = None, na_values: object = None, skiprows: object = None, quotechar: object = None, escapechar: object = None, encoding: object = None, parallel: object = None, date_format: object = None, timestamp_format: object = None, sample_size: object = None, all_varchar: object = None, normalize_names: object = None, filename: object = None, null_padding: object = None) → duckdb.duckdb.DuckDBPyRelation

Create a relation object from the CSV file in ‘name’

@@ -367,7 +367,7 @@ title: Python Client API
-from_df(self: duckdb.duckdb.DuckDBPyConnection, df: pandas.DataFrame = None) → duckdb.duckdb.DuckDBPyRelation +from_df(self: duckdb.duckdb.DuckDBPyConnection, df: pandas.DataFrame = None) → duckdb.duckdb.DuckDBPyRelation

Create a relation object from the Data.Frame in df

@@ -376,7 +376,7 @@ title: Python Client API
-from_parquet(*args, **kwargs) +from_parquet(*args, **kwargs)

Overloaded function.

@@ -393,7 +393,7 @@ title: Python Client API
-from_query(self: duckdb.duckdb.DuckDBPyConnection, query: str, *, alias: str = '', params: object = None) → duckdb.duckdb.DuckDBPyRelation +from_query(self: duckdb.duckdb.DuckDBPyConnection, query: str, *, alias: str = '', params: object = None) → duckdb.duckdb.DuckDBPyRelation

Run a SQL query. If it is a SELECT statement, create a relation object from the given SQL query, otherwise run the query as-is.

@@ -402,7 +402,7 @@ title: Python Client API
-from_substrait(self: duckdb.duckdb.DuckDBPyConnection, proto: bytes) → duckdb.duckdb.DuckDBPyRelation +from_substrait(self: duckdb.duckdb.DuckDBPyConnection, proto: bytes) → duckdb.duckdb.DuckDBPyRelation

Create a query object from protobuf plan

@@ -411,7 +411,7 @@ title: Python Client API
-from_substrait_json(self: duckdb.duckdb.DuckDBPyConnection, json: str) → duckdb.duckdb.DuckDBPyRelation +from_substrait_json(self: duckdb.duckdb.DuckDBPyConnection, json: str) → duckdb.duckdb.DuckDBPyRelation

Create a query object from a JSON protobuf plan

@@ -420,7 +420,7 @@ title: Python Client API
-get_substrait(self: duckdb.duckdb.DuckDBPyConnection, query: str, *, enable_optimizer: bool = True) → duckdb.duckdb.DuckDBPyRelation +get_substrait(self: duckdb.duckdb.DuckDBPyConnection, query: str, *, enable_optimizer: bool = True) → duckdb.duckdb.DuckDBPyRelation

Serialize a query to protobuf

@@ -429,7 +429,7 @@ title: Python Client API
-get_substrait_json(self: duckdb.duckdb.DuckDBPyConnection, query: str, *, enable_optimizer: bool = True) → duckdb.duckdb.DuckDBPyRelation +get_substrait_json(self: duckdb.duckdb.DuckDBPyConnection, query: str, *, enable_optimizer: bool = True) → duckdb.duckdb.DuckDBPyRelation

Serialize a query to protobuf on the JSON format

@@ -438,7 +438,7 @@ title: Python Client API
-get_table_names(self: duckdb.duckdb.DuckDBPyConnection, query: str) → Set[str] +get_table_names(self: duckdb.duckdb.DuckDBPyConnection, query: str) → Set[str]

Extract the required table names from a query

@@ -447,7 +447,7 @@ title: Python Client API
-install_extension(self: duckdb.duckdb.DuckDBPyConnection, extension: str, *, force_install: bool = False) → None +install_extension(self: duckdb.duckdb.DuckDBPyConnection, extension: str, *, force_install: bool = False) → None

Install an extension by name

@@ -456,7 +456,7 @@ title: Python Client API
-interrupt(self: duckdb.duckdb.DuckDBPyConnection) → None +interrupt(self: duckdb.duckdb.DuckDBPyConnection) → None

Interrupt pending operations

@@ -465,7 +465,7 @@ title: Python Client API
-list_filesystems(self: duckdb.duckdb.DuckDBPyConnection) → list +list_filesystems(self: duckdb.duckdb.DuckDBPyConnection) → list

List registered filesystems, including builtin ones

@@ -474,7 +474,7 @@ title: Python Client API
-list_type(self: duckdb.duckdb.DuckDBPyConnection, type: duckdb.duckdb.typing.DuckDBPyType) → duckdb.duckdb.typing.DuckDBPyType +list_type(self: duckdb.duckdb.DuckDBPyConnection, type: duckdb.duckdb.typing.DuckDBPyType) → duckdb.duckdb.typing.DuckDBPyType

Create an array type object of ‘type’

@@ -483,7 +483,7 @@ title: Python Client API
-load_extension(self: duckdb.duckdb.DuckDBPyConnection, extension: str) → None +load_extension(self: duckdb.duckdb.DuckDBPyConnection, extension: str) → None

Load an installed extension

@@ -492,7 +492,7 @@ title: Python Client API
-map_type(self: duckdb.duckdb.DuckDBPyConnection, key: duckdb.duckdb.typing.DuckDBPyType, value: duckdb.duckdb.typing.DuckDBPyType) → duckdb.duckdb.typing.DuckDBPyType +map_type(self: duckdb.duckdb.DuckDBPyConnection, key: duckdb.duckdb.typing.DuckDBPyType, value: duckdb.duckdb.typing.DuckDBPyType) → duckdb.duckdb.typing.DuckDBPyType

Create a map type object from ‘key_type’ and ‘value_type’

@@ -501,7 +501,7 @@ title: Python Client API
-pl(self: duckdb.duckdb.DuckDBPyConnection, rows_per_batch: int = 1000000) → duckdb::PolarsDataFrame +pl(self: duckdb.duckdb.DuckDBPyConnection, rows_per_batch: int = 1000000) → duckdb::PolarsDataFrame

Fetch a result as Polars DataFrame following execute()

@@ -510,7 +510,7 @@ title: Python Client API
-query(self: duckdb.duckdb.DuckDBPyConnection, query: str, *, alias: str = '', params: object = None) → duckdb.duckdb.DuckDBPyRelation +query(self: duckdb.duckdb.DuckDBPyConnection, query: str, *, alias: str = '', params: object = None) → duckdb.duckdb.DuckDBPyRelation

Run a SQL query. If it is a SELECT statement, create a relation object from the given SQL query, otherwise run the query as-is.

@@ -519,7 +519,7 @@ title: Python Client API
-read_csv(self: duckdb.duckdb.DuckDBPyConnection, name: object, *, header: object = None, compression: object = None, sep: object = None, delimiter: object = None, dtype: object = None, na_values: object = None, skiprows: object = None, quotechar: object = None, escapechar: object = None, encoding: object = None, parallel: object = None, date_format: object = None, timestamp_format: object = None, sample_size: object = None, all_varchar: object = None, normalize_names: object = None, filename: object = None, null_padding: object = None) → duckdb.duckdb.DuckDBPyRelation +read_csv(self: duckdb.duckdb.DuckDBPyConnection, name: object, *, header: object = None, compression: object = None, sep: object = None, delimiter: object = None, dtype: object = None, na_values: object = None, skiprows: object = None, quotechar: object = None, escapechar: object = None, encoding: object = None, parallel: object = None, date_format: object = None, timestamp_format: object = None, sample_size: object = None, all_varchar: object = None, normalize_names: object = None, filename: object = None, null_padding: object = None) → duckdb.duckdb.DuckDBPyRelation

Create a relation object from the CSV file in ‘name’

@@ -528,7 +528,7 @@ title: Python Client API
-read_json(self: duckdb.duckdb.DuckDBPyConnection, name: str, *, columns: Optional[object] = None, sample_size: Optional[object] = None, maximum_depth: Optional[object] = None, records: Optional[str] = None, format: Optional[str] = None) → duckdb.duckdb.DuckDBPyRelation +read_json(self: duckdb.duckdb.DuckDBPyConnection, name: str, *, columns: Optional[object] = None, sample_size: Optional[object] = None, maximum_depth: Optional[object] = None, records: Optional[str] = None, format: Optional[str] = None) → duckdb.duckdb.DuckDBPyRelation

Create a relation object from the JSON file in ‘name’

@@ -537,7 +537,7 @@ title: Python Client API
-read_parquet(*args, **kwargs) +read_parquet(*args, **kwargs)

Overloaded function.

@@ -554,7 +554,7 @@ title: Python Client API
-register(self: duckdb.duckdb.DuckDBPyConnection, view_name: str, python_object: object) → duckdb.duckdb.DuckDBPyConnection +register(self: duckdb.duckdb.DuckDBPyConnection, view_name: str, python_object: object) → duckdb.duckdb.DuckDBPyConnection

Register the passed Python Object value for querying with a view

@@ -563,7 +563,7 @@ title: Python Client API
-register_filesystem(self: duckdb.duckdb.DuckDBPyConnection, filesystem: fsspec.AbstractFileSystem) → None +register_filesystem(self: duckdb.duckdb.DuckDBPyConnection, filesystem: fsspec.AbstractFileSystem) → None

Register a fsspec compliant filesystem

@@ -572,7 +572,7 @@ title: Python Client API
-remove_function(self: duckdb.duckdb.DuckDBPyConnection, name: str) → duckdb.duckdb.DuckDBPyConnection +remove_function(self: duckdb.duckdb.DuckDBPyConnection, name: str) → duckdb.duckdb.DuckDBPyConnection

Remove a previously created function

@@ -581,7 +581,7 @@ title: Python Client API
-rollback(self: duckdb.duckdb.DuckDBPyConnection) → duckdb.duckdb.DuckDBPyConnection +rollback(self: duckdb.duckdb.DuckDBPyConnection) → duckdb.duckdb.DuckDBPyConnection

Roll back changes performed within a transaction

@@ -590,7 +590,7 @@ title: Python Client API
-row_type(self: duckdb.duckdb.DuckDBPyConnection, fields: object) → duckdb.duckdb.typing.DuckDBPyType +row_type(self: duckdb.duckdb.DuckDBPyConnection, fields: object) → duckdb.duckdb.typing.DuckDBPyType

Create a struct type object from ‘fields’

@@ -599,7 +599,7 @@ title: Python Client API
-sql(self: duckdb.duckdb.DuckDBPyConnection, query: str, *, alias: str = '', params: object = None) → duckdb.duckdb.DuckDBPyRelation +sql(self: duckdb.duckdb.DuckDBPyConnection, query: str, *, alias: str = '', params: object = None) → duckdb.duckdb.DuckDBPyRelation

Run a SQL query. If it is a SELECT statement, create a relation object from the given SQL query, otherwise run the query as-is.

@@ -608,7 +608,7 @@ title: Python Client API
-sqltype(self: duckdb.duckdb.DuckDBPyConnection, type_str: str) → duckdb.duckdb.typing.DuckDBPyType +sqltype(self: duckdb.duckdb.DuckDBPyConnection, type_str: str) → duckdb.duckdb.typing.DuckDBPyType

Create a type object by parsing the ‘type_str’ string

@@ -617,7 +617,7 @@ title: Python Client API
-string_type(self: duckdb.duckdb.DuckDBPyConnection, collation: str = '') → duckdb.duckdb.typing.DuckDBPyType +string_type(self: duckdb.duckdb.DuckDBPyConnection, collation: str = '') → duckdb.duckdb.typing.DuckDBPyType

Create a string type with an optional collation

@@ -626,7 +626,7 @@ title: Python Client API
-struct_type(self: duckdb.duckdb.DuckDBPyConnection, fields: object) → duckdb.duckdb.typing.DuckDBPyType +struct_type(self: duckdb.duckdb.DuckDBPyConnection, fields: object) → duckdb.duckdb.typing.DuckDBPyType

Create a struct type object from ‘fields’

@@ -635,7 +635,7 @@ title: Python Client API
-table(self: duckdb.duckdb.DuckDBPyConnection, table_name: str) → duckdb.duckdb.DuckDBPyRelation +table(self: duckdb.duckdb.DuckDBPyConnection, table_name: str) → duckdb.duckdb.DuckDBPyRelation

Create a relation object for the name’d table

@@ -644,7 +644,7 @@ title: Python Client API
-table_function(self: duckdb.duckdb.DuckDBPyConnection, name: str, parameters: object = None) → duckdb.duckdb.DuckDBPyRelation +table_function(self: duckdb.duckdb.DuckDBPyConnection, name: str, parameters: object = None) → duckdb.duckdb.DuckDBPyRelation

Create a relation object from the name’d table function with given parameters

@@ -653,7 +653,7 @@ title: Python Client API
-tf(self: duckdb.duckdb.DuckDBPyConnection) → dict +tf(self: duckdb.duckdb.DuckDBPyConnection) → dict

Fetch a result as dict of TensorFlow Tensors following execute()

@@ -662,7 +662,7 @@ title: Python Client API
-torch(self: duckdb.duckdb.DuckDBPyConnection) → dict +torch(self: duckdb.duckdb.DuckDBPyConnection) → dict

Fetch a result as dict of PyTorch Tensors following execute()

@@ -671,7 +671,7 @@ title: Python Client API
-type(self: duckdb.duckdb.DuckDBPyConnection, type_str: str) → duckdb.duckdb.typing.DuckDBPyType +type(self: duckdb.duckdb.DuckDBPyConnection, type_str: str) → duckdb.duckdb.typing.DuckDBPyType

Create a type object by parsing the ‘type_str’ string

@@ -680,7 +680,7 @@ title: Python Client API
-union_type(self: duckdb.duckdb.DuckDBPyConnection, members: object) → duckdb.duckdb.typing.DuckDBPyType +union_type(self: duckdb.duckdb.DuckDBPyConnection, members: object) → duckdb.duckdb.typing.DuckDBPyType

Create a union type object from ‘members’

@@ -689,7 +689,7 @@ title: Python Client API
-unregister(self: duckdb.duckdb.DuckDBPyConnection, view_name: str) → duckdb.duckdb.DuckDBPyConnection +unregister(self: duckdb.duckdb.DuckDBPyConnection, view_name: str) → duckdb.duckdb.DuckDBPyConnection

Unregister the view name

@@ -698,7 +698,7 @@ title: Python Client API
-unregister_filesystem(self: duckdb.duckdb.DuckDBPyConnection, name: str) → None +unregister_filesystem(self: duckdb.duckdb.DuckDBPyConnection, name: str) → None

Unregister a filesystem

@@ -707,7 +707,7 @@ title: Python Client API
-values(self: duckdb.duckdb.DuckDBPyConnection, values: object) → duckdb.duckdb.DuckDBPyRelation +values(self: duckdb.duckdb.DuckDBPyConnection, values: object) → duckdb.duckdb.DuckDBPyRelation

Create a relation object from the passed values

@@ -716,7 +716,7 @@ title: Python Client API
-view(self: duckdb.duckdb.DuckDBPyConnection, view_name: str) → duckdb.duckdb.DuckDBPyRelation +view(self: duckdb.duckdb.DuckDBPyConnection, view_name: str) → duckdb.duckdb.DuckDBPyRelation

Create a relation object for the name’d view

@@ -728,13 +728,13 @@ title: Python Client API
-class duckdb.DuckDBPyRelation +class duckdb.DuckDBPyRelation

Bases: pybind11_object

-abs(self: duckdb.duckdb.DuckDBPyRelation, aggregation_columns: str) → duckdb.duckdb.DuckDBPyRelation +abs(self: duckdb.duckdb.DuckDBPyRelation, aggregation_columns: str) → duckdb.duckdb.DuckDBPyRelation

Returns the absolute value for the specified columns.

@@ -743,7 +743,7 @@ title: Python Client API
-aggregate(self: duckdb.duckdb.DuckDBPyRelation, aggr_expr: str, group_expr: str = '') → duckdb.duckdb.DuckDBPyRelation +aggregate(self: duckdb.duckdb.DuckDBPyRelation, aggr_expr: str, group_expr: str = '') → duckdb.duckdb.DuckDBPyRelation

Compute the aggregate aggr_expr by the optional groups group_expr on the relation

@@ -752,7 +752,7 @@ title: Python Client API
-property alias +property alias

Get the name of the current alias

@@ -761,7 +761,7 @@ title: Python Client API
-apply(self: duckdb.duckdb.DuckDBPyRelation, function_name: str, function_aggr: str, group_expr: str = '', function_parameter: str = '', projected_columns: str = '') → duckdb.duckdb.DuckDBPyRelation +apply(self: duckdb.duckdb.DuckDBPyRelation, function_name: str, function_aggr: str, group_expr: str = '', function_parameter: str = '', projected_columns: str = '') → duckdb.duckdb.DuckDBPyRelation

Compute the function of a single column or a list of columns by the optional groups on the relation

@@ -770,7 +770,7 @@ title: Python Client API
-arrow(self: duckdb.duckdb.DuckDBPyRelation, batch_size: int = 1000000) → pyarrow.lib.Table +arrow(self: duckdb.duckdb.DuckDBPyRelation, batch_size: int = 1000000) → pyarrow.lib.Table

Execute and fetch all rows as an Arrow Table

@@ -779,7 +779,7 @@ title: Python Client API
-close(self: duckdb.duckdb.DuckDBPyRelation) → None +close(self: duckdb.duckdb.DuckDBPyRelation) → None

Closes the result

@@ -788,7 +788,7 @@ title: Python Client API
-property columns +property columns

Return a list containing the names of the columns of the relation.

@@ -797,7 +797,7 @@ title: Python Client API
-count(self: duckdb.duckdb.DuckDBPyRelation, count_aggr: str, group_expr: str = '') → duckdb.duckdb.DuckDBPyRelation +count(self: duckdb.duckdb.DuckDBPyRelation, count_aggr: str, group_expr: str = '') → duckdb.duckdb.DuckDBPyRelation

Compute the aggregate count of a single column or a list of columns by the optional groups on the relation

@@ -806,7 +806,7 @@ title: Python Client API
-create(self: duckdb.duckdb.DuckDBPyRelation, table_name: str) → None +create(self: duckdb.duckdb.DuckDBPyRelation, table_name: str) → None

Creates a new table named table_name with the contents of the relation object

@@ -815,7 +815,7 @@ title: Python Client API
-create_view(self: duckdb.duckdb.DuckDBPyRelation, view_name: str, replace: bool = True) → duckdb.duckdb.DuckDBPyRelation +create_view(self: duckdb.duckdb.DuckDBPyRelation, view_name: str, replace: bool = True) → duckdb.duckdb.DuckDBPyRelation

Creates a view named view_name that refers to the relation object

@@ -824,7 +824,7 @@ title: Python Client API
-cummax(self: duckdb.duckdb.DuckDBPyRelation, aggregation_columns: str) → duckdb.duckdb.DuckDBPyRelation +cummax(self: duckdb.duckdb.DuckDBPyRelation, aggregation_columns: str) → duckdb.duckdb.DuckDBPyRelation

Returns the cumulative maximum of the aggregate column.

@@ -833,7 +833,7 @@ title: Python Client API
-cummin(self: duckdb.duckdb.DuckDBPyRelation, aggregation_columns: str) → duckdb.duckdb.DuckDBPyRelation +cummin(self: duckdb.duckdb.DuckDBPyRelation, aggregation_columns: str) → duckdb.duckdb.DuckDBPyRelation

Returns the cumulative minimum of the aggregate column.

@@ -842,7 +842,7 @@ title: Python Client API
-cumprod(self: duckdb.duckdb.DuckDBPyRelation, aggregation_columns: str) → duckdb.duckdb.DuckDBPyRelation +cumprod(self: duckdb.duckdb.DuckDBPyRelation, aggregation_columns: str) → duckdb.duckdb.DuckDBPyRelation

Returns the cumulative product of the aggregate column.

@@ -851,7 +851,7 @@ title: Python Client API
-cumsum(self: duckdb.duckdb.DuckDBPyRelation, aggregation_columns: str) → duckdb.duckdb.DuckDBPyRelation +cumsum(self: duckdb.duckdb.DuckDBPyRelation, aggregation_columns: str) → duckdb.duckdb.DuckDBPyRelation

Returns the cumulative sum of the aggregate column.

@@ -860,7 +860,7 @@ title: Python Client API
-describe(self: duckdb.duckdb.DuckDBPyRelation) → duckdb.duckdb.DuckDBPyRelation +describe(self: duckdb.duckdb.DuckDBPyRelation) → duckdb.duckdb.DuckDBPyRelation

Gives basic statistics (e.g., min,max) and if null exists for each column of the relation.

@@ -869,7 +869,7 @@ title: Python Client API
-property description +property description

Return the description of the result

@@ -878,7 +878,7 @@ title: Python Client API
-df(self: duckdb.duckdb.DuckDBPyRelation, *, date_as_object: bool = False) → pandas.DataFrame +df(self: duckdb.duckdb.DuckDBPyRelation, *, date_as_object: bool = False) → pandas.DataFrame

Execute and fetch all rows as a pandas DataFrame

@@ -887,7 +887,7 @@ title: Python Client API
-distinct(self: duckdb.duckdb.DuckDBPyRelation) → duckdb.duckdb.DuckDBPyRelation +distinct(self: duckdb.duckdb.DuckDBPyRelation) → duckdb.duckdb.DuckDBPyRelation

Retrieve distinct rows from this relation object

@@ -896,7 +896,7 @@ title: Python Client API
-property dtypes +property dtypes

Return a list containing the types of the columns of the relation.

@@ -905,7 +905,7 @@ title: Python Client API
-except_(self: duckdb.duckdb.DuckDBPyRelation, other_rel: duckdb.duckdb.DuckDBPyRelation) → duckdb.duckdb.DuckDBPyRelation +except_(self: duckdb.duckdb.DuckDBPyRelation, other_rel: duckdb.duckdb.DuckDBPyRelation) → duckdb.duckdb.DuckDBPyRelation

Create the set except of this relation object with another relation object in other_rel

@@ -914,7 +914,7 @@ title: Python Client API
-execute(self: duckdb.duckdb.DuckDBPyRelation) → duckdb.duckdb.DuckDBPyRelation +execute(self: duckdb.duckdb.DuckDBPyRelation) → duckdb.duckdb.DuckDBPyRelation

Transform the relation into a result set

@@ -923,14 +923,14 @@ title: Python Client API
-explain(self: duckdb.duckdb.DuckDBPyRelation, type: duckdb.duckdb.ExplainType = 'standard') → str +explain(self: duckdb.duckdb.DuckDBPyRelation, type: duckdb.duckdb.ExplainType = 'standard') → str
-fetch_arrow_reader(self: duckdb.duckdb.DuckDBPyRelation, batch_size: int = 1000000) → pyarrow.lib.RecordBatchReader +fetch_arrow_reader(self: duckdb.duckdb.DuckDBPyRelation, batch_size: int = 1000000) → pyarrow.lib.RecordBatchReader

Execute and return an Arrow Record Batch Reader that yields all rows

@@ -939,7 +939,7 @@ title: Python Client API
-fetch_arrow_table(self: duckdb.duckdb.DuckDBPyRelation, batch_size: int = 1000000) → pyarrow.lib.Table +fetch_arrow_table(self: duckdb.duckdb.DuckDBPyRelation, batch_size: int = 1000000) → pyarrow.lib.Table

Execute and fetch all rows as an Arrow Table

@@ -948,7 +948,7 @@ title: Python Client API
-fetchall(self: duckdb.duckdb.DuckDBPyRelation) → list +fetchall(self: duckdb.duckdb.DuckDBPyRelation) → list

Execute and fetch all rows as a list of tuples

@@ -957,7 +957,7 @@ title: Python Client API
-fetchdf(self: duckdb.duckdb.DuckDBPyRelation, *, date_as_object: bool = False) → pandas.DataFrame +fetchdf(self: duckdb.duckdb.DuckDBPyRelation, *, date_as_object: bool = False) → pandas.DataFrame

Execute and fetch all rows as a pandas DataFrame

@@ -966,7 +966,7 @@ title: Python Client API
-fetchmany(self: duckdb.duckdb.DuckDBPyRelation, size: int = 1) → list +fetchmany(self: duckdb.duckdb.DuckDBPyRelation, size: int = 1) → list

Execute and fetch the next set of rows as a list of tuples

@@ -975,7 +975,7 @@ title: Python Client API
-fetchnumpy(self: duckdb.duckdb.DuckDBPyRelation) → dict +fetchnumpy(self: duckdb.duckdb.DuckDBPyRelation) → dict

Execute and fetch all rows as a Python dict mapping each column to one numpy arrays

@@ -984,7 +984,7 @@ title: Python Client API
-fetchone(self: duckdb.duckdb.DuckDBPyRelation) → Optional[tuple] +fetchone(self: duckdb.duckdb.DuckDBPyRelation) → Optional[tuple]

Execute and fetch a single row as a tuple

@@ -993,7 +993,7 @@ title: Python Client API
-filter(self: duckdb.duckdb.DuckDBPyRelation, filter_expr: str) → duckdb.duckdb.DuckDBPyRelation +filter(self: duckdb.duckdb.DuckDBPyRelation, filter_expr: str) → duckdb.duckdb.DuckDBPyRelation

Filter the relation object by the filter in filter_expr

@@ -1002,7 +1002,7 @@ title: Python Client API
-insert(self: duckdb.duckdb.DuckDBPyRelation, values: object) → None +insert(self: duckdb.duckdb.DuckDBPyRelation, values: object) → None

Inserts the given values into the relation

@@ -1011,7 +1011,7 @@ title: Python Client API
-insert_into(self: duckdb.duckdb.DuckDBPyRelation, table_name: str) → None +insert_into(self: duckdb.duckdb.DuckDBPyRelation, table_name: str) → None

Inserts the relation object into an existing table named table_name

@@ -1020,7 +1020,7 @@ title: Python Client API
-intersect(self: duckdb.duckdb.DuckDBPyRelation, other_rel: duckdb.duckdb.DuckDBPyRelation) → duckdb.duckdb.DuckDBPyRelation +intersect(self: duckdb.duckdb.DuckDBPyRelation, other_rel: duckdb.duckdb.DuckDBPyRelation) → duckdb.duckdb.DuckDBPyRelation

Create the set intersection of this relation object with another relation object in other_rel

@@ -1029,7 +1029,7 @@ title: Python Client API
-join(self: duckdb.duckdb.DuckDBPyRelation, other_rel: duckdb.duckdb.DuckDBPyRelation, condition: str, how: str = 'inner') → duckdb.duckdb.DuckDBPyRelation +join(self: duckdb.duckdb.DuckDBPyRelation, other_rel: duckdb.duckdb.DuckDBPyRelation, condition: str, how: str = 'inner') → duckdb.duckdb.DuckDBPyRelation

Join the relation object with another relation object in other_rel using the join condition expression in join_condition. Types supported are ‘inner’ and ‘left’

@@ -1038,7 +1038,7 @@ title: Python Client API
-kurt(self: duckdb.duckdb.DuckDBPyRelation, aggregation_columns: str, group_columns: str = '') → duckdb.duckdb.DuckDBPyRelation +kurt(self: duckdb.duckdb.DuckDBPyRelation, aggregation_columns: str, group_columns: str = '') → duckdb.duckdb.DuckDBPyRelation

Returns the excess kurtosis of the aggregate column.

@@ -1047,7 +1047,7 @@ title: Python Client API
-limit(self: duckdb.duckdb.DuckDBPyRelation, n: int, offset: int = 0) → duckdb.duckdb.DuckDBPyRelation +limit(self: duckdb.duckdb.DuckDBPyRelation, n: int, offset: int = 0) → duckdb.duckdb.DuckDBPyRelation

Only retrieve the first n rows from this relation object, starting at offset

@@ -1056,7 +1056,7 @@ title: Python Client API
-mad(self: duckdb.duckdb.DuckDBPyRelation, aggregation_columns: str, group_columns: str = '') → duckdb.duckdb.DuckDBPyRelation +mad(self: duckdb.duckdb.DuckDBPyRelation, aggregation_columns: str, group_columns: str = '') → duckdb.duckdb.DuckDBPyRelation

Returns the median absolute deviation for the aggregate columns. NULL values are ignored. Temporal types return a positive INTERVAL.

@@ -1065,7 +1065,7 @@ title: Python Client API
-map(self: duckdb.duckdb.DuckDBPyRelation, map_function: function, *, schema: Optional[object] = None) → duckdb.duckdb.DuckDBPyRelation +map(self: duckdb.duckdb.DuckDBPyRelation, map_function: function, *, schema: Optional[object] = None) → duckdb.duckdb.DuckDBPyRelation

Calls the passed function on the relation

@@ -1074,7 +1074,7 @@ title: Python Client API
-max(self: duckdb.duckdb.DuckDBPyRelation, max_aggr: str, group_expr: str = '') → duckdb.duckdb.DuckDBPyRelation +max(self: duckdb.duckdb.DuckDBPyRelation, max_aggr: str, group_expr: str = '') → duckdb.duckdb.DuckDBPyRelation

Compute the aggregate max of a single column or a list of columns by the optional groups on the relation

@@ -1083,7 +1083,7 @@ title: Python Client API
-mean(self: duckdb.duckdb.DuckDBPyRelation, mean_aggr: str, group_expr: str = '') → duckdb.duckdb.DuckDBPyRelation +mean(self: duckdb.duckdb.DuckDBPyRelation, mean_aggr: str, group_expr: str = '') → duckdb.duckdb.DuckDBPyRelation

Compute the aggregate mean of a single column or a list of columns by the optional groups on the relation

@@ -1092,7 +1092,7 @@ title: Python Client API
-median(self: duckdb.duckdb.DuckDBPyRelation, median_aggr: str, group_expr: str = '') → duckdb.duckdb.DuckDBPyRelation +median(self: duckdb.duckdb.DuckDBPyRelation, median_aggr: str, group_expr: str = '') → duckdb.duckdb.DuckDBPyRelation

Compute the aggregate median of a single column or a list of columns by the optional groups on the relation

@@ -1101,7 +1101,7 @@ title: Python Client API
-min(self: duckdb.duckdb.DuckDBPyRelation, min_aggr: str, group_expr: str = '') → duckdb.duckdb.DuckDBPyRelation +min(self: duckdb.duckdb.DuckDBPyRelation, min_aggr: str, group_expr: str = '') → duckdb.duckdb.DuckDBPyRelation

Compute the aggregate min of a single column or a list of columns by the optional groups on the relation

@@ -1110,7 +1110,7 @@ title: Python Client API
-mode(self: duckdb.duckdb.DuckDBPyRelation, aggregation_columns: str, group_columns: str = '') → duckdb.duckdb.DuckDBPyRelation +mode(self: duckdb.duckdb.DuckDBPyRelation, aggregation_columns: str, group_columns: str = '') → duckdb.duckdb.DuckDBPyRelation

Returns the most frequent value for the aggregate columns. NULL values are ignored.

@@ -1119,7 +1119,7 @@ title: Python Client API
-order(self: duckdb.duckdb.DuckDBPyRelation, order_expr: str) → duckdb.duckdb.DuckDBPyRelation +order(self: duckdb.duckdb.DuckDBPyRelation, order_expr: str) → duckdb.duckdb.DuckDBPyRelation

Reorder the relation object by order_expr

@@ -1128,7 +1128,7 @@ title: Python Client API
-pl(self: duckdb.duckdb.DuckDBPyRelation, batch_size: int = 1000000) → duckdb::PolarsDataFrame +pl(self: duckdb.duckdb.DuckDBPyRelation, batch_size: int = 1000000) → duckdb::PolarsDataFrame

Execute and fetch all rows as a Polars DataFrame

@@ -1137,7 +1137,7 @@ title: Python Client API
-prod(self: duckdb.duckdb.DuckDBPyRelation, aggregation_columns: str, group_columns: str = '') → duckdb.duckdb.DuckDBPyRelation +prod(self: duckdb.duckdb.DuckDBPyRelation, aggregation_columns: str, group_columns: str = '') → duckdb.duckdb.DuckDBPyRelation

Calculates the product of the aggregate column.

@@ -1146,7 +1146,7 @@ title: Python Client API
-project(self: duckdb.duckdb.DuckDBPyRelation, project_expr: str) → duckdb.duckdb.DuckDBPyRelation +project(self: duckdb.duckdb.DuckDBPyRelation, project_expr: str) → duckdb.duckdb.DuckDBPyRelation

Project the relation object by the projection in project_expr

@@ -1155,7 +1155,7 @@ title: Python Client API
-quantile(self: duckdb.duckdb.DuckDBPyRelation, q: str, quantile_aggr: str, group_expr: str = '') → duckdb.duckdb.DuckDBPyRelation +quantile(self: duckdb.duckdb.DuckDBPyRelation, q: str, quantile_aggr: str, group_expr: str = '') → duckdb.duckdb.DuckDBPyRelation

Compute the quantile of a single column or a list of columns by the optional groups on the relation

@@ -1164,7 +1164,7 @@ title: Python Client API
-query(self: duckdb.duckdb.DuckDBPyRelation, virtual_table_name: str, sql_query: str) → duckdb.duckdb.DuckDBPyRelation +query(self: duckdb.duckdb.DuckDBPyRelation, virtual_table_name: str, sql_query: str) → duckdb.duckdb.DuckDBPyRelation

Run the given SQL query in sql_query on the view named virtual_table_name that refers to the relation object

@@ -1173,7 +1173,7 @@ title: Python Client API
-record_batch(self: duckdb.duckdb.DuckDBPyRelation, batch_size: int = 1000000) → pyarrow.lib.RecordBatchReader +record_batch(self: duckdb.duckdb.DuckDBPyRelation, batch_size: int = 1000000) → pyarrow.lib.RecordBatchReader

Execute and return an Arrow Record Batch Reader that yields all rows

@@ -1182,7 +1182,7 @@ title: Python Client API
-select_dtypes(self: duckdb.duckdb.DuckDBPyRelation, types: object) → duckdb.duckdb.DuckDBPyRelation +select_dtypes(self: duckdb.duckdb.DuckDBPyRelation, types: object) → duckdb.duckdb.DuckDBPyRelation

Select columns from the relation, by filtering based on type(s)

@@ -1191,7 +1191,7 @@ title: Python Client API
-select_types(self: duckdb.duckdb.DuckDBPyRelation, types: object) → duckdb.duckdb.DuckDBPyRelation +select_types(self: duckdb.duckdb.DuckDBPyRelation, types: object) → duckdb.duckdb.DuckDBPyRelation

Select columns from the relation, by filtering based on type(s)

@@ -1200,7 +1200,7 @@ title: Python Client API
-sem(self: duckdb.duckdb.DuckDBPyRelation, aggregation_columns: str, group_columns: str = '') → duckdb.duckdb.DuckDBPyRelation +sem(self: duckdb.duckdb.DuckDBPyRelation, aggregation_columns: str, group_columns: str = '') → duckdb.duckdb.DuckDBPyRelation

Returns the standard error of the mean of the aggregate column.

@@ -1209,7 +1209,7 @@ title: Python Client API
-set_alias(self: duckdb.duckdb.DuckDBPyRelation, alias: str) → duckdb.duckdb.DuckDBPyRelation +set_alias(self: duckdb.duckdb.DuckDBPyRelation, alias: str) → duckdb.duckdb.DuckDBPyRelation

Rename the relation object to new alias

@@ -1218,7 +1218,7 @@ title: Python Client API
-property shape +property shape

Tuple of # of rows, # of columns in relation.

@@ -1227,7 +1227,7 @@ title: Python Client API
-show(self: duckdb.duckdb.DuckDBPyRelation) → None +show(self: duckdb.duckdb.DuckDBPyRelation) → None

Display a summary of the data

@@ -1236,7 +1236,7 @@ title: Python Client API
-skew(self: duckdb.duckdb.DuckDBPyRelation, aggregation_columns: str, group_columns: str = '') → duckdb.duckdb.DuckDBPyRelation +skew(self: duckdb.duckdb.DuckDBPyRelation, aggregation_columns: str, group_columns: str = '') → duckdb.duckdb.DuckDBPyRelation

Returns the skewness of the aggregate column.

@@ -1245,7 +1245,7 @@ title: Python Client API
-sql_query(self: duckdb.duckdb.DuckDBPyRelation) → str +sql_query(self: duckdb.duckdb.DuckDBPyRelation) → str

Get the SQL query that is equivalent to the relation

@@ -1254,7 +1254,7 @@ title: Python Client API
-std(self: duckdb.duckdb.DuckDBPyRelation, std_aggr: str, group_expr: str = '') → duckdb.duckdb.DuckDBPyRelation +std(self: duckdb.duckdb.DuckDBPyRelation, std_aggr: str, group_expr: str = '') → duckdb.duckdb.DuckDBPyRelation

Compute the standard deviation of a single column or a list of columns by the optional groups on the relation

@@ -1263,7 +1263,7 @@ title: Python Client API
-sum(self: duckdb.duckdb.DuckDBPyRelation, sum_aggr: str, group_expr: str = '') → duckdb.duckdb.DuckDBPyRelation +sum(self: duckdb.duckdb.DuckDBPyRelation, sum_aggr: str, group_expr: str = '') → duckdb.duckdb.DuckDBPyRelation

Compute the aggregate sum of a single column or a list of columns by the optional groups on the relation

@@ -1272,7 +1272,7 @@ title: Python Client API
-tf(self: duckdb.duckdb.DuckDBPyRelation) → dict +tf(self: duckdb.duckdb.DuckDBPyRelation) → dict

Fetch a result as dict of TensorFlow Tensors

@@ -1281,7 +1281,7 @@ title: Python Client API
-to_arrow_table(self: duckdb.duckdb.DuckDBPyRelation, batch_size: int = 1000000) → pyarrow.lib.Table +to_arrow_table(self: duckdb.duckdb.DuckDBPyRelation, batch_size: int = 1000000) → pyarrow.lib.Table

Execute and fetch all rows as an Arrow Table

@@ -1290,7 +1290,7 @@ title: Python Client API
-to_csv(self: duckdb.duckdb.DuckDBPyRelation, file_name: str, *, sep: object = None, na_rep: object = None, header: object = None, quotechar: object = None, escapechar: object = None, date_format: object = None, timestamp_format: object = None, quoting: object = None, encoding: object = None, compression: object = None) → None +to_csv(self: duckdb.duckdb.DuckDBPyRelation, file_name: str, *, sep: object = None, na_rep: object = None, header: object = None, quotechar: object = None, escapechar: object = None, date_format: object = None, timestamp_format: object = None, quoting: object = None, encoding: object = None, compression: object = None) → None

Write the relation object to a CSV file in ‘file_name’

@@ -1299,7 +1299,7 @@ title: Python Client API
-to_df(self: duckdb.duckdb.DuckDBPyRelation, *, date_as_object: bool = False) → pandas.DataFrame +to_df(self: duckdb.duckdb.DuckDBPyRelation, *, date_as_object: bool = False) → pandas.DataFrame

Execute and fetch all rows as a pandas DataFrame

@@ -1308,7 +1308,7 @@ title: Python Client API
-to_parquet(self: duckdb.duckdb.DuckDBPyRelation, file_name: str, *, compression: object = None) → None +to_parquet(self: duckdb.duckdb.DuckDBPyRelation, file_name: str, *, compression: object = None) → None

Write the relation object to a Parquet file in ‘file_name’

@@ -1317,7 +1317,7 @@ title: Python Client API
-to_table(self: duckdb.duckdb.DuckDBPyRelation, table_name: str) → None +to_table(self: duckdb.duckdb.DuckDBPyRelation, table_name: str) → None

Creates a new table named table_name with the contents of the relation object

@@ -1326,7 +1326,7 @@ title: Python Client API
-to_view(self: duckdb.duckdb.DuckDBPyRelation, view_name: str, replace: bool = True) → duckdb.duckdb.DuckDBPyRelation +to_view(self: duckdb.duckdb.DuckDBPyRelation, view_name: str, replace: bool = True) → duckdb.duckdb.DuckDBPyRelation

Creates a view named view_name that refers to the relation object

@@ -1335,7 +1335,7 @@ title: Python Client API
-torch(self: duckdb.duckdb.DuckDBPyRelation) → dict +torch(self: duckdb.duckdb.DuckDBPyRelation) → dict

Fetch a result as dict of PyTorch Tensors

@@ -1344,7 +1344,7 @@ title: Python Client API
-property type +property type

Get the type of the relation.

@@ -1353,7 +1353,7 @@ title: Python Client API
-property types +property types

Return a list containing the types of the columns of the relation.

@@ -1362,7 +1362,7 @@ title: Python Client API
-union(self: duckdb.duckdb.DuckDBPyRelation, union_rel: duckdb.duckdb.DuckDBPyRelation) → duckdb.duckdb.DuckDBPyRelation +union(self: duckdb.duckdb.DuckDBPyRelation, union_rel: duckdb.duckdb.DuckDBPyRelation) → duckdb.duckdb.DuckDBPyRelation

Create the set union of this relation object with another relation object in other_rel

@@ -1371,7 +1371,7 @@ title: Python Client API
-unique(self: duckdb.duckdb.DuckDBPyRelation, unique_aggr: str) → duckdb.duckdb.DuckDBPyRelation +unique(self: duckdb.duckdb.DuckDBPyRelation, unique_aggr: str) → duckdb.duckdb.DuckDBPyRelation

Number of distinct values in a column.

@@ -1380,7 +1380,7 @@ title: Python Client API
-value_counts(self: duckdb.duckdb.DuckDBPyRelation, value_counts_aggr: str, group_expr: str = '') → duckdb.duckdb.DuckDBPyRelation +value_counts(self: duckdb.duckdb.DuckDBPyRelation, value_counts_aggr: str, group_expr: str = '') → duckdb.duckdb.DuckDBPyRelation

Count number of rows with each unique value of variable

@@ -1389,7 +1389,7 @@ title: Python Client API
-var(self: duckdb.duckdb.DuckDBPyRelation, var_aggr: str, group_expr: str = '') → duckdb.duckdb.DuckDBPyRelation +var(self: duckdb.duckdb.DuckDBPyRelation, var_aggr: str, group_expr: str = '') → duckdb.duckdb.DuckDBPyRelation

Compute the variance of a single column or a list of columns by the optional groups on the relation

@@ -1398,7 +1398,7 @@ title: Python Client API
-write_csv(self: duckdb.duckdb.DuckDBPyRelation, file_name: str, *, sep: object = None, na_rep: object = None, header: object = None, quotechar: object = None, escapechar: object = None, date_format: object = None, timestamp_format: object = None, quoting: object = None, encoding: object = None, compression: object = None) → None +write_csv(self: duckdb.duckdb.DuckDBPyRelation, file_name: str, *, sep: object = None, na_rep: object = None, header: object = None, quotechar: object = None, escapechar: object = None, date_format: object = None, timestamp_format: object = None, quoting: object = None, encoding: object = None, compression: object = None) → None

Write the relation object to a CSV file in ‘file_name’

@@ -1407,7 +1407,7 @@ title: Python Client API
-write_parquet(self: duckdb.duckdb.DuckDBPyRelation, file_name: str, *, compression: object = None) → None +write_parquet(self: duckdb.duckdb.DuckDBPyRelation, file_name: str, *, compression: object = None) → None

Write the relation object to a Parquet file in ‘file_name’

@@ -1419,7 +1419,7 @@ title: Python Client API
-exception duckdb.Error +exception duckdb.Error

Bases: Exception

@@ -1428,7 +1428,7 @@ title: Python Client API
-class duckdb.ExplainType +class duckdb.ExplainType

Bases: pybind11_object

@@ -1437,28 +1437,28 @@ title: Python Client API

ANALYZE

-ANALYZE = <ExplainType.ANALYZE: 1> +ANALYZE = <ExplainType.ANALYZE: 1>
-STANDARD = <ExplainType.STANDARD: 0> +STANDARD = <ExplainType.STANDARD: 0>
-property name +property name
-property value +property value
@@ -1468,7 +1468,7 @@ title: Python Client API
-exception duckdb.FatalException +exception duckdb.FatalException

Bases: Error

@@ -1477,35 +1477,35 @@ title: Python Client API
-exception duckdb.HTTPException +exception duckdb.HTTPException

Bases: IOException

Thrown when an error occurs in the httpfs extension, or whilst downloading an extension.

-body: str +body: str
-headers: Dict[str, str] +headers: Dict[str, str]
-reason: str +reason: str
-status_code: int +status_code: int
@@ -1515,7 +1515,7 @@ title: Python Client API
-exception duckdb.IOException +exception duckdb.IOException

Bases: OperationalError

@@ -1524,7 +1524,7 @@ title: Python Client API
-exception duckdb.IntegrityError +exception duckdb.IntegrityError

Bases: Error

@@ -1533,7 +1533,7 @@ title: Python Client API
-exception duckdb.InternalError +exception duckdb.InternalError

Bases: Error

@@ -1542,7 +1542,7 @@ title: Python Client API
-exception duckdb.InternalException +exception duckdb.InternalException

Bases: InternalError

@@ -1551,7 +1551,7 @@ title: Python Client API
-exception duckdb.InterruptException +exception duckdb.InterruptException

Bases: Error

@@ -1560,7 +1560,7 @@ title: Python Client API
-exception duckdb.InvalidInputException +exception duckdb.InvalidInputException

Bases: ProgrammingError

@@ -1569,7 +1569,7 @@ title: Python Client API
-exception duckdb.InvalidTypeException +exception duckdb.InvalidTypeException

Bases: ProgrammingError

@@ -1578,7 +1578,7 @@ title: Python Client API
-exception duckdb.NotImplementedException +exception duckdb.NotImplementedException

Bases: NotSupportedError

@@ -1587,7 +1587,7 @@ title: Python Client API
-exception duckdb.NotSupportedError +exception duckdb.NotSupportedError

Bases: Error

@@ -1596,7 +1596,7 @@ title: Python Client API
-exception duckdb.OperationalError +exception duckdb.OperationalError

Bases: Error

@@ -1605,7 +1605,7 @@ title: Python Client API
-exception duckdb.OutOfMemoryException +exception duckdb.OutOfMemoryException

Bases: OperationalError

@@ -1614,7 +1614,7 @@ title: Python Client API
-exception duckdb.OutOfRangeException +exception duckdb.OutOfRangeException

Bases: DataError

@@ -1623,7 +1623,7 @@ title: Python Client API
-exception duckdb.ParserException +exception duckdb.ParserException

Bases: ProgrammingError

@@ -1632,7 +1632,7 @@ title: Python Client API
-exception duckdb.PermissionException +exception duckdb.PermissionException

Bases: Error

@@ -1641,7 +1641,7 @@ title: Python Client API
-exception duckdb.ProgrammingError +exception duckdb.ProgrammingError

Bases: Error

@@ -1650,7 +1650,7 @@ title: Python Client API
-class duckdb.PythonExceptionHandling +class duckdb.PythonExceptionHandling

Bases: pybind11_object

@@ -1659,28 +1659,28 @@ title: Python Client API

RETURN_NULL

-DEFAULT = <PythonExceptionHandling.DEFAULT: 0> +DEFAULT = <PythonExceptionHandling.DEFAULT: 0>
-RETURN_NULL = <PythonExceptionHandling.RETURN_NULL: 1> +RETURN_NULL = <PythonExceptionHandling.RETURN_NULL: 1>
-property name +property name
-property value +property value
@@ -1690,7 +1690,7 @@ title: Python Client API
-exception duckdb.SequenceException +exception duckdb.SequenceException

Bases: Error

@@ -1699,7 +1699,7 @@ title: Python Client API
-exception duckdb.SerializationException +exception duckdb.SerializationException

Bases: OperationalError

@@ -1708,7 +1708,7 @@ title: Python Client API
-exception duckdb.StandardException +exception duckdb.StandardException

Bases: Error

@@ -1717,7 +1717,7 @@ title: Python Client API
-exception duckdb.SyntaxException +exception duckdb.SyntaxException

Bases: ProgrammingError

@@ -1726,7 +1726,7 @@ title: Python Client API
-exception duckdb.TransactionException +exception duckdb.TransactionException

Bases: OperationalError

@@ -1735,7 +1735,7 @@ title: Python Client API
-exception duckdb.TypeMismatchException +exception duckdb.TypeMismatchException

Bases: DataError

@@ -1744,7 +1744,7 @@ title: Python Client API
-exception duckdb.ValueOutOfRangeException +exception duckdb.ValueOutOfRangeException

Bases: DataError

@@ -1753,7 +1753,7 @@ title: Python Client API
-exception duckdb.Warning +exception duckdb.Warning

Bases: Exception

@@ -1762,7 +1762,7 @@ title: Python Client API
-duckdb.aggregate(df: pandas.DataFrame, aggr_expr: str, group_expr: str = '', connection: duckdb.DuckDBPyConnection = None) → duckdb.duckdb.DuckDBPyRelation +duckdb.aggregate(df: pandas.DataFrame, aggr_expr: str, group_expr: str = '', connection: duckdb.DuckDBPyConnection = None) → duckdb.duckdb.DuckDBPyRelation

Compute the aggregate aggr_expr by the optional groups group_expr on DataFrame df

@@ -1771,7 +1771,7 @@ title: Python Client API
-duckdb.alias(df: pandas.DataFrame, alias: str, connection: duckdb.DuckDBPyConnection = None) → duckdb.duckdb.DuckDBPyRelation +duckdb.alias(df: pandas.DataFrame, alias: str, connection: duckdb.DuckDBPyConnection = None) → duckdb.duckdb.DuckDBPyRelation

Create a relation from DataFrame df with the passed alias

@@ -1780,7 +1780,7 @@ title: Python Client API
-duckdb.append(table_name: str, df: pandas.DataFrame, *, by_name: bool = False, connection: duckdb.DuckDBPyConnection = None) → duckdb.DuckDBPyConnection +duckdb.append(table_name: str, df: pandas.DataFrame, *, by_name: bool = False, connection: duckdb.DuckDBPyConnection = None) → duckdb.DuckDBPyConnection

Append the passed DataFrame to the named table

@@ -1789,7 +1789,7 @@ title: Python Client API
-duckdb.array_type(type: duckdb.duckdb.typing.DuckDBPyType, connection: duckdb.DuckDBPyConnection = None) → duckdb.duckdb.typing.DuckDBPyType +duckdb.array_type(type: duckdb.duckdb.typing.DuckDBPyType, connection: duckdb.DuckDBPyConnection = None) → duckdb.duckdb.typing.DuckDBPyType

Create an array type object of ‘type’

@@ -1798,7 +1798,7 @@ title: Python Client API
-duckdb.arrow(*args, **kwargs) +duckdb.arrow(*args, **kwargs)

Overloaded function.

@@ -1815,7 +1815,7 @@ title: Python Client API
-duckdb.begin(connection: duckdb.DuckDBPyConnection = None) → duckdb.DuckDBPyConnection +duckdb.begin(connection: duckdb.DuckDBPyConnection = None) → duckdb.DuckDBPyConnection

Start a new transaction

@@ -1824,7 +1824,7 @@ title: Python Client API
-duckdb.close(connection: duckdb.DuckDBPyConnection = None) → None +duckdb.close(connection: duckdb.DuckDBPyConnection = None) → None

Close the connection

@@ -1833,7 +1833,7 @@ title: Python Client API
-duckdb.commit(connection: duckdb.DuckDBPyConnection = None) → duckdb.DuckDBPyConnection +duckdb.commit(connection: duckdb.DuckDBPyConnection = None) → duckdb.DuckDBPyConnection

Commit changes performed within a transaction

@@ -1842,7 +1842,7 @@ title: Python Client API
-duckdb.connect(database: str = ':memory:', read_only: bool = False, config: dict = None) → duckdb.DuckDBPyConnection +duckdb.connect(database: str = ':memory:', read_only: bool = False, config: dict = None) → duckdb.DuckDBPyConnection

Create a DuckDB database instance. Can take a database file name to read/write persistent data and a read_only flag if no changes are desired

@@ -1851,7 +1851,7 @@ title: Python Client API
-duckdb.create_function(name: str, function: function, return_type: object = None, parameters: duckdb.duckdb.typing.DuckDBPyType = None, *, type: duckdb.duckdb.functional.PythonUDFType = <PythonUDFType.NATIVE: 0>, null_handling: duckdb.duckdb.functional.FunctionNullHandling = 0, exception_handling: duckdb.duckdb.PythonExceptionHandling = 0, side_effects: bool = False, connection: duckdb.DuckDBPyConnection = None) → duckdb.DuckDBPyConnection +duckdb.create_function(name: str, function: function, return_type: object = None, parameters: duckdb.duckdb.typing.DuckDBPyType = None, *, type: duckdb.duckdb.functional.PythonUDFType = <PythonUDFType.NATIVE: 0>, null_handling: duckdb.duckdb.functional.FunctionNullHandling = 0, exception_handling: duckdb.duckdb.PythonExceptionHandling = 0, side_effects: bool = False, connection: duckdb.DuckDBPyConnection = None) → duckdb.DuckDBPyConnection

Create a DuckDB function out of the passing in python function so it can be used in queries

@@ -1860,7 +1860,7 @@ title: Python Client API
-duckdb.cursor(connection: duckdb.DuckDBPyConnection = None) → duckdb.DuckDBPyConnection +duckdb.cursor(connection: duckdb.DuckDBPyConnection = None) → duckdb.DuckDBPyConnection

Create a duplicate of the current connection

@@ -1869,7 +1869,7 @@ title: Python Client API
-duckdb.decimal_type(width: int, scale: int, connection: duckdb.DuckDBPyConnection = None) → duckdb.duckdb.typing.DuckDBPyType +duckdb.decimal_type(width: int, scale: int, connection: duckdb.DuckDBPyConnection = None) → duckdb.duckdb.typing.DuckDBPyType

Create a decimal type with ‘width’ and ‘scale’

@@ -1878,7 +1878,7 @@ title: Python Client API
-duckdb.description(connection: duckdb.DuckDBPyConnection = None) → Optional[list] +duckdb.description(connection: duckdb.DuckDBPyConnection = None) → Optional[list]

Get result set attributes, mainly column names

@@ -1887,7 +1887,7 @@ title: Python Client API
-duckdb.df(*args, **kwargs) +duckdb.df(*args, **kwargs)

Overloaded function.

@@ -1904,7 +1904,7 @@ title: Python Client API
-duckdb.distinct(df: pandas.DataFrame, connection: duckdb.DuckDBPyConnection = None) → duckdb.duckdb.DuckDBPyRelation +duckdb.distinct(df: pandas.DataFrame, connection: duckdb.DuckDBPyConnection = None) → duckdb.duckdb.DuckDBPyRelation

Compute the distinct rows from DataFrame df

@@ -1913,7 +1913,7 @@ title: Python Client API
-duckdb.dtype(type_str: str, connection: duckdb.DuckDBPyConnection = None) → duckdb.duckdb.typing.DuckDBPyType +duckdb.dtype(type_str: str, connection: duckdb.DuckDBPyConnection = None) → duckdb.duckdb.typing.DuckDBPyType

Create a type object from ‘type_str’

@@ -1922,7 +1922,7 @@ title: Python Client API
-duckdb.duplicate(connection: duckdb.DuckDBPyConnection = None) → duckdb.DuckDBPyConnection +duckdb.duplicate(connection: duckdb.DuckDBPyConnection = None) → duckdb.DuckDBPyConnection

Create a duplicate of the current connection

@@ -1931,7 +1931,7 @@ title: Python Client API
-duckdb.enum_type(name: str, type: duckdb.duckdb.typing.DuckDBPyType, values: list, connection: duckdb.DuckDBPyConnection = None) → duckdb.duckdb.typing.DuckDBPyType +duckdb.enum_type(name: str, type: duckdb.duckdb.typing.DuckDBPyType, values: list, connection: duckdb.DuckDBPyConnection = None) → duckdb.duckdb.typing.DuckDBPyType

Create an enum type of underlying ‘type’, consisting of the list of ‘values’

@@ -1940,7 +1940,7 @@ title: Python Client API
-duckdb.execute(query: str, parameters: object = None, multiple_parameter_sets: bool = False, connection: duckdb.DuckDBPyConnection = None) → duckdb.DuckDBPyConnection +duckdb.execute(query: str, parameters: object = None, multiple_parameter_sets: bool = False, connection: duckdb.DuckDBPyConnection = None) → duckdb.DuckDBPyConnection

Execute the given SQL query, optionally using prepared statements with parameters set

@@ -1949,7 +1949,7 @@ title: Python Client API
-duckdb.executemany(query: str, parameters: object = None, connection: duckdb.DuckDBPyConnection = None) → duckdb.DuckDBPyConnection +duckdb.executemany(query: str, parameters: object = None, connection: duckdb.DuckDBPyConnection = None) → duckdb.DuckDBPyConnection

Execute the given prepared statement multiple times using the list of parameter sets in parameters

@@ -1958,7 +1958,7 @@ title: Python Client API
-duckdb.fetch_arrow_table(rows_per_batch: int = 1000000, connection: duckdb.DuckDBPyConnection = None) → pyarrow.lib.Table +duckdb.fetch_arrow_table(rows_per_batch: int = 1000000, connection: duckdb.DuckDBPyConnection = None) → pyarrow.lib.Table

Fetch a result as Arrow table following execute()

@@ -1967,7 +1967,7 @@ title: Python Client API
-duckdb.fetch_df(*, date_as_object: bool = False, connection: duckdb.DuckDBPyConnection = None) → pandas.DataFrame +duckdb.fetch_df(*, date_as_object: bool = False, connection: duckdb.DuckDBPyConnection = None) → pandas.DataFrame

Fetch a result as DataFrame following execute()

@@ -1976,7 +1976,7 @@ title: Python Client API
-duckdb.fetch_df_chunk(vectors_per_chunk: int = 1, *, date_as_object: bool = False, connection: duckdb.DuckDBPyConnection = None) → pandas.DataFrame +duckdb.fetch_df_chunk(vectors_per_chunk: int = 1, *, date_as_object: bool = False, connection: duckdb.DuckDBPyConnection = None) → pandas.DataFrame

Fetch a chunk of the result as DataFrame following execute()

@@ -1985,7 +1985,7 @@ title: Python Client API
-duckdb.fetch_record_batch(rows_per_batch: int = 1000000, connection: duckdb.DuckDBPyConnection = None) → pyarrow.lib.RecordBatchReader +duckdb.fetch_record_batch(rows_per_batch: int = 1000000, connection: duckdb.DuckDBPyConnection = None) → pyarrow.lib.RecordBatchReader

Fetch an Arrow RecordBatchReader following execute()

@@ -1994,7 +1994,7 @@ title: Python Client API
-duckdb.fetchall(connection: duckdb.DuckDBPyConnection = None) → list +duckdb.fetchall(connection: duckdb.DuckDBPyConnection = None) → list

Fetch all rows from a result following execute

@@ -2003,7 +2003,7 @@ title: Python Client API
-duckdb.fetchdf(*, date_as_object: bool = False, connection: duckdb.DuckDBPyConnection = None) → pandas.DataFrame +duckdb.fetchdf(*, date_as_object: bool = False, connection: duckdb.DuckDBPyConnection = None) → pandas.DataFrame

Fetch a result as DataFrame following execute()

@@ -2012,7 +2012,7 @@ title: Python Client API
-duckdb.fetchmany(size: int = 1, connection: duckdb.DuckDBPyConnection = None) → list +duckdb.fetchmany(size: int = 1, connection: duckdb.DuckDBPyConnection = None) → list

Fetch the next set of rows from a result following execute

@@ -2021,7 +2021,7 @@ title: Python Client API
-duckdb.fetchnumpy(connection: duckdb.DuckDBPyConnection = None) → dict +duckdb.fetchnumpy(connection: duckdb.DuckDBPyConnection = None) → dict

Fetch a result as list of NumPy arrays following execute

@@ -2030,7 +2030,7 @@ title: Python Client API
-duckdb.fetchone(connection: duckdb.DuckDBPyConnection = None) → Optional[tuple] +duckdb.fetchone(connection: duckdb.DuckDBPyConnection = None) → Optional[tuple]

Fetch a single row from a result following execute

@@ -2039,7 +2039,7 @@ title: Python Client API
-duckdb.filesystem_is_registered(name: str, connection: duckdb.DuckDBPyConnection = None) → bool +duckdb.filesystem_is_registered(name: str, connection: duckdb.DuckDBPyConnection = None) → bool

Check if a filesystem with the provided name is currently registered

@@ -2048,7 +2048,7 @@ title: Python Client API
-duckdb.filter(df: pandas.DataFrame, filter_expr: str, connection: duckdb.DuckDBPyConnection = None) → duckdb.duckdb.DuckDBPyRelation +duckdb.filter(df: pandas.DataFrame, filter_expr: str, connection: duckdb.DuckDBPyConnection = None) → duckdb.duckdb.DuckDBPyRelation

Filter the DataFrame df by the filter in filter_expr

@@ -2057,7 +2057,7 @@ title: Python Client API
-duckdb.from_arrow(arrow_object: object, connection: duckdb.DuckDBPyConnection = None) → duckdb.duckdb.DuckDBPyRelation +duckdb.from_arrow(arrow_object: object, connection: duckdb.DuckDBPyConnection = None) → duckdb.duckdb.DuckDBPyRelation

Create a relation object from an Arrow object

@@ -2066,7 +2066,7 @@ title: Python Client API
-duckdb.from_csv_auto(name: object, connection: duckdb.DuckDBPyConnection = None, header: object = None, compression: object = None, sep: object = None, delimiter: object = None, dtype: object = None, na_values: object = None, skiprows: object = None, quotechar: object = None, escapechar: object = None, encoding: object = None, parallel: object = None, date_format: object = None, timestamp_format: object = None, sample_size: object = None, all_varchar: object = None, normalize_names: object = None, filename: object = None, null_padding: object = None) → duckdb.duckdb.DuckDBPyRelation +duckdb.from_csv_auto(name: object, connection: duckdb.DuckDBPyConnection = None, header: object = None, compression: object = None, sep: object = None, delimiter: object = None, dtype: object = None, na_values: object = None, skiprows: object = None, quotechar: object = None, escapechar: object = None, encoding: object = None, parallel: object = None, date_format: object = None, timestamp_format: object = None, sample_size: object = None, all_varchar: object = None, normalize_names: object = None, filename: object = None, null_padding: object = None) → duckdb.duckdb.DuckDBPyRelation

Create a relation object from the CSV file in ‘name’

@@ -2075,7 +2075,7 @@ title: Python Client API
-duckdb.from_df(df: pandas.DataFrame, connection: duckdb.DuckDBPyConnection = None) → duckdb.duckdb.DuckDBPyRelation +duckdb.from_df(df: pandas.DataFrame, connection: duckdb.DuckDBPyConnection = None) → duckdb.duckdb.DuckDBPyRelation

Create a relation object from the DataFrame df

@@ -2084,7 +2084,7 @@ title: Python Client API
-duckdb.from_parquet(*args, **kwargs) +duckdb.from_parquet(*args, **kwargs)

Overloaded function.

@@ -2101,7 +2101,7 @@ title: Python Client API
-duckdb.from_query(query: str, alias: str = '', connection: duckdb.DuckDBPyConnection = None) → duckdb.duckdb.DuckDBPyRelation +duckdb.from_query(query: str, alias: str = '', connection: duckdb.DuckDBPyConnection = None) → duckdb.duckdb.DuckDBPyRelation

Run a SQL query. If it is a SELECT statement, create a relation object from the given SQL query, otherwise run the query as-is.

@@ -2110,7 +2110,7 @@ title: Python Client API
-duckdb.from_substrait(*args, **kwargs) +duckdb.from_substrait(*args, **kwargs)

Overloaded function.

@@ -2127,7 +2127,7 @@ title: Python Client API
-duckdb.from_substrait_json(json: str, connection: duckdb.DuckDBPyConnection = None) → duckdb.duckdb.DuckDBPyRelation +duckdb.from_substrait_json(json: str, connection: duckdb.DuckDBPyConnection = None) → duckdb.duckdb.DuckDBPyRelation

Serialize a query object to protobuf

@@ -2136,7 +2136,7 @@ title: Python Client API
-duckdb.get_substrait(*args, **kwargs) +duckdb.get_substrait(*args, **kwargs)

Overloaded function.

@@ -2153,7 +2153,7 @@ title: Python Client API
-duckdb.get_substrait_json(*args, **kwargs) +duckdb.get_substrait_json(*args, **kwargs)

Overloaded function.

@@ -2170,7 +2170,7 @@ title: Python Client API
-duckdb.get_table_names(query: str, connection: duckdb.DuckDBPyConnection = None) → Set[str] +duckdb.get_table_names(query: str, connection: duckdb.DuckDBPyConnection = None) → Set[str]

Extract the required table names from a query

@@ -2179,7 +2179,7 @@ title: Python Client API
-duckdb.install_extension(extension: str, *, force_install: bool = False, connection: duckdb.DuckDBPyConnection = None) → None +duckdb.install_extension(extension: str, *, force_install: bool = False, connection: duckdb.DuckDBPyConnection = None) → None

Install an extension by name

@@ -2188,7 +2188,7 @@ title: Python Client API
-duckdb.interrupt(connection: duckdb.DuckDBPyConnection = None) → None +duckdb.interrupt(connection: duckdb.DuckDBPyConnection = None) → None

Interrupt pending operations

@@ -2197,7 +2197,7 @@ title: Python Client API
-duckdb.limit(df: pandas.DataFrame, n: int, connection: duckdb.DuckDBPyConnection = None) → duckdb.duckdb.DuckDBPyRelation +duckdb.limit(df: pandas.DataFrame, n: int, connection: duckdb.DuckDBPyConnection = None) → duckdb.duckdb.DuckDBPyRelation

Retrieve the first n rows from the DataFrame df

@@ -2206,7 +2206,7 @@ title: Python Client API
-duckdb.list_filesystems(connection: duckdb.DuckDBPyConnection = None) → list +duckdb.list_filesystems(connection: duckdb.DuckDBPyConnection = None) → list

List registered filesystems, including builtin ones

@@ -2215,7 +2215,7 @@ title: Python Client API
-duckdb.list_type(type: duckdb.duckdb.typing.DuckDBPyType, connection: duckdb.DuckDBPyConnection = None) → duckdb.duckdb.typing.DuckDBPyType +duckdb.list_type(type: duckdb.duckdb.typing.DuckDBPyType, connection: duckdb.DuckDBPyConnection = None) → duckdb.duckdb.typing.DuckDBPyType

Create an array type object of ‘type’

@@ -2224,7 +2224,7 @@ title: Python Client API
-duckdb.load_extension(extension: str, connection: duckdb.DuckDBPyConnection = None) → None +duckdb.load_extension(extension: str, connection: duckdb.DuckDBPyConnection = None) → None

Load an installed extension

@@ -2233,7 +2233,7 @@ title: Python Client API
-duckdb.map_type(key: duckdb.duckdb.typing.DuckDBPyType, value: duckdb.duckdb.typing.DuckDBPyType, connection: duckdb.DuckDBPyConnection = None) → duckdb.duckdb.typing.DuckDBPyType +duckdb.map_type(key: duckdb.duckdb.typing.DuckDBPyType, value: duckdb.duckdb.typing.DuckDBPyType, connection: duckdb.DuckDBPyConnection = None) → duckdb.duckdb.typing.DuckDBPyType

Create a map type object from ‘key_type’ and ‘value_type’

@@ -2242,7 +2242,7 @@ title: Python Client API
-duckdb.order(df: pandas.DataFrame, order_expr: str, connection: duckdb.DuckDBPyConnection = None) → duckdb.duckdb.DuckDBPyRelation +duckdb.order(df: pandas.DataFrame, order_expr: str, connection: duckdb.DuckDBPyConnection = None) → duckdb.duckdb.DuckDBPyRelation

Reorder the DataFrame df by order_expr

@@ -2251,7 +2251,7 @@ title: Python Client API
-duckdb.pl(rows_per_batch: int = 1000000, connection: duckdb.DuckDBPyConnection = None) → duckdb::PolarsDataFrame +duckdb.pl(rows_per_batch: int = 1000000, connection: duckdb.DuckDBPyConnection = None) → duckdb::PolarsDataFrame

Fetch a result as Polars DataFrame following execute()

@@ -2260,7 +2260,7 @@ title: Python Client API
-duckdb.project(df: pandas.DataFrame, project_expr: str, connection: duckdb.DuckDBPyConnection = None) → duckdb.duckdb.DuckDBPyRelation +duckdb.project(df: pandas.DataFrame, project_expr: str, connection: duckdb.DuckDBPyConnection = None) → duckdb.duckdb.DuckDBPyRelation

Project the DataFrame df by the projection in project_expr

@@ -2269,7 +2269,7 @@ title: Python Client API
-duckdb.query(query: str, alias: str = '', connection: duckdb.DuckDBPyConnection = None) → duckdb.duckdb.DuckDBPyRelation +duckdb.query(query: str, alias: str = '', connection: duckdb.DuckDBPyConnection = None) → duckdb.duckdb.DuckDBPyRelation

Run a SQL query. If it is a SELECT statement, create a relation object from the given SQL query, otherwise run the query as-is.

@@ -2278,7 +2278,7 @@ title: Python Client API
-duckdb.query_df(df: pandas.DataFrame, virtual_table_name: str, sql_query: str, connection: duckdb.DuckDBPyConnection = None) → duckdb.duckdb.DuckDBPyRelation +duckdb.query_df(df: pandas.DataFrame, virtual_table_name: str, sql_query: str, connection: duckdb.DuckDBPyConnection = None) → duckdb.duckdb.DuckDBPyRelation

Run the given SQL query in sql_query on the view named virtual_table_name that contains the content of DataFrame df

@@ -2287,7 +2287,7 @@ title: Python Client API
-duckdb.read_csv(name: object, connection: duckdb.DuckDBPyConnection = None, header: object = None, compression: object = None, sep: object = None, delimiter: object = None, dtype: object = None, na_values: object = None, skiprows: object = None, quotechar: object = None, escapechar: object = None, encoding: object = None, parallel: object = None, date_format: object = None, timestamp_format: object = None, sample_size: object = None, all_varchar: object = None, normalize_names: object = None, filename: object = None, null_padding: object = None) → duckdb.duckdb.DuckDBPyRelation +duckdb.read_csv(name: object, connection: duckdb.DuckDBPyConnection = None, header: object = None, compression: object = None, sep: object = None, delimiter: object = None, dtype: object = None, na_values: object = None, skiprows: object = None, quotechar: object = None, escapechar: object = None, encoding: object = None, parallel: object = None, date_format: object = None, timestamp_format: object = None, sample_size: object = None, all_varchar: object = None, normalize_names: object = None, filename: object = None, null_padding: object = None) → duckdb.duckdb.DuckDBPyRelation

Create a relation object from the CSV file in ‘name’

@@ -2296,7 +2296,7 @@ title: Python Client API
-duckdb.read_json(name: str, connection: duckdb.DuckDBPyConnection = None, columns: Optional[object] = None, sample_size: Optional[object] = None, maximum_depth: Optional[object] = None, records: Optional[str] = None, format: Optional[str] = None) → duckdb.duckdb.DuckDBPyRelation +duckdb.read_json(name: str, connection: duckdb.DuckDBPyConnection = None, columns: Optional[object] = None, sample_size: Optional[object] = None, maximum_depth: Optional[object] = None, records: Optional[str] = None, format: Optional[str] = None) → duckdb.duckdb.DuckDBPyRelation

Create a relation object from the JSON file in ‘name’

@@ -2305,7 +2305,7 @@ title: Python Client API
-duckdb.read_parquet(*args, **kwargs) +duckdb.read_parquet(*args, **kwargs)

Overloaded function.

@@ -2322,7 +2322,7 @@ title: Python Client API
-duckdb.register(view_name: str, python_object: object, connection: duckdb.DuckDBPyConnection = None) → duckdb.DuckDBPyConnection +duckdb.register(view_name: str, python_object: object, connection: duckdb.DuckDBPyConnection = None) → duckdb.DuckDBPyConnection

Register the passed Python Object value for querying with a view

@@ -2331,7 +2331,7 @@ title: Python Client API
-duckdb.register_filesystem(filesystem: fsspec.AbstractFileSystem, connection: duckdb.DuckDBPyConnection = None) → None +duckdb.register_filesystem(filesystem: fsspec.AbstractFileSystem, connection: duckdb.DuckDBPyConnection = None) → None

Register a fsspec compliant filesystem

@@ -2340,7 +2340,7 @@ title: Python Client API
-duckdb.remove_function(name: str, connection: duckdb.DuckDBPyConnection = None) → duckdb.DuckDBPyConnection +duckdb.remove_function(name: str, connection: duckdb.DuckDBPyConnection = None) → duckdb.DuckDBPyConnection

Remove a previously created function

@@ -2349,7 +2349,7 @@ title: Python Client API
-duckdb.rollback(connection: duckdb.DuckDBPyConnection = None) → duckdb.DuckDBPyConnection +duckdb.rollback(connection: duckdb.DuckDBPyConnection = None) → duckdb.DuckDBPyConnection

Roll back changes performed within a transaction

@@ -2358,7 +2358,7 @@ title: Python Client API
-duckdb.row_type(fields: object, connection: duckdb.DuckDBPyConnection = None) → duckdb.duckdb.typing.DuckDBPyType +duckdb.row_type(fields: object, connection: duckdb.DuckDBPyConnection = None) → duckdb.duckdb.typing.DuckDBPyType

Create a struct type object from ‘fields’

@@ -2367,7 +2367,7 @@ title: Python Client API
-duckdb.sql(query: str, alias: str = '', connection: duckdb.DuckDBPyConnection = None) → duckdb.duckdb.DuckDBPyRelation +duckdb.sql(query: str, alias: str = '', connection: duckdb.DuckDBPyConnection = None) → duckdb.duckdb.DuckDBPyRelation

Run a SQL query. If it is a SELECT statement, create a relation object from the given SQL query, otherwise run the query as-is.

@@ -2376,7 +2376,7 @@ title: Python Client API
-duckdb.sqltype(type_str: str, connection: duckdb.DuckDBPyConnection = None) → duckdb.duckdb.typing.DuckDBPyType +duckdb.sqltype(type_str: str, connection: duckdb.DuckDBPyConnection = None) → duckdb.duckdb.typing.DuckDBPyType

Create a type object from ‘type_str’

@@ -2385,7 +2385,7 @@ title: Python Client API
-duckdb.string_type(collation: str = '', connection: duckdb.DuckDBPyConnection = None) → duckdb.duckdb.typing.DuckDBPyType +duckdb.string_type(collation: str = '', connection: duckdb.DuckDBPyConnection = None) → duckdb.duckdb.typing.DuckDBPyType

Create a string type with an optional collation

@@ -2394,7 +2394,7 @@ title: Python Client API
-duckdb.struct_type(fields: object, connection: duckdb.DuckDBPyConnection = None) → duckdb.duckdb.typing.DuckDBPyType +duckdb.struct_type(fields: object, connection: duckdb.DuckDBPyConnection = None) → duckdb.duckdb.typing.DuckDBPyType

Create a struct type object from ‘fields’

@@ -2403,7 +2403,7 @@ title: Python Client API
-duckdb.table(table_name: str, connection: duckdb.DuckDBPyConnection = None) → duckdb.duckdb.DuckDBPyRelation +duckdb.table(table_name: str, connection: duckdb.DuckDBPyConnection = None) → duckdb.duckdb.DuckDBPyRelation

Create a relation object for the name’d table

@@ -2412,7 +2412,7 @@ title: Python Client API
-duckdb.table_function(name: str, parameters: object = None, connection: duckdb.DuckDBPyConnection = None) → duckdb.duckdb.DuckDBPyRelation +duckdb.table_function(name: str, parameters: object = None, connection: duckdb.DuckDBPyConnection = None) → duckdb.duckdb.DuckDBPyRelation

Create a relation object from the name’d table function with given parameters

@@ -2421,7 +2421,7 @@ title: Python Client API
-duckdb.tf(connection: duckdb.DuckDBPyConnection = None) → dict +duckdb.tf(connection: duckdb.DuckDBPyConnection = None) → dict

Fetch a result as dict of TensorFlow Tensors following execute()

@@ -2430,7 +2430,7 @@ title: Python Client API
-class duckdb.token_type +class duckdb.token_type

Bases: pybind11_object

@@ -2443,56 +2443,56 @@ title: Python Client API

comment

-comment = <token_type.comment: 5> +comment = <token_type.comment: 5>
-identifier = <token_type.identifier: 0> +identifier = <token_type.identifier: 0>
-keyword = <token_type.keyword: 4> +keyword = <token_type.keyword: 4>
-property name +property name
-numeric_const = <token_type.numeric_const: 1> +numeric_const = <token_type.numeric_const: 1>
-operator = <token_type.operator: 3> +operator = <token_type.operator: 3>
-string_const = <token_type.string_const: 2> +string_const = <token_type.string_const: 2>
-property value +property value
@@ -2502,7 +2502,7 @@ title: Python Client API
-duckdb.tokenize(query: str) → list +duckdb.tokenize(query: str) → list

Tokenizes a SQL string, returning a list of (position, type) tuples that can be used for e.g. syntax highlighting

@@ -2511,7 +2511,7 @@ title: Python Client API
-duckdb.torch(connection: duckdb.DuckDBPyConnection = None) → dict +duckdb.torch(connection: duckdb.DuckDBPyConnection = None) → dict

Fetch a result as dict of PyTorch Tensors following execute()

@@ -2520,7 +2520,7 @@ title: Python Client API
-duckdb.type(type_str: str, connection: duckdb.DuckDBPyConnection = None) → duckdb.duckdb.typing.DuckDBPyType +duckdb.type(type_str: str, connection: duckdb.DuckDBPyConnection = None) → duckdb.duckdb.typing.DuckDBPyType

Create a type object from ‘type_str’

@@ -2529,7 +2529,7 @@ title: Python Client API
-duckdb.union_type(members: object, connection: duckdb.DuckDBPyConnection = None) → duckdb.duckdb.typing.DuckDBPyType +duckdb.union_type(members: object, connection: duckdb.DuckDBPyConnection = None) → duckdb.duckdb.typing.DuckDBPyType

Create a union type object from ‘members’

@@ -2538,7 +2538,7 @@ title: Python Client API
-duckdb.unregister(view_name: str, connection: duckdb.DuckDBPyConnection = None) → duckdb.DuckDBPyConnection +duckdb.unregister(view_name: str, connection: duckdb.DuckDBPyConnection = None) → duckdb.DuckDBPyConnection

Unregister the view name

@@ -2547,7 +2547,7 @@ title: Python Client API
-duckdb.unregister_filesystem(name: str, connection: duckdb.DuckDBPyConnection = None) → None +duckdb.unregister_filesystem(name: str, connection: duckdb.DuckDBPyConnection = None) → None

Unregister a filesystem

@@ -2556,7 +2556,7 @@ title: Python Client API
-duckdb.values(*args, **kwargs) +duckdb.values(*args, **kwargs)

Overloaded function.

@@ -2573,7 +2573,7 @@ title: Python Client API
-duckdb.view(view_name: str, connection: duckdb.DuckDBPyConnection = None) → duckdb.duckdb.DuckDBPyRelation +duckdb.view(view_name: str, connection: duckdb.DuckDBPyConnection = None) → duckdb.duckdb.DuckDBPyRelation

Create a relation object for the name’d view

@@ -2582,7 +2582,7 @@ title: Python Client API
-duckdb.write_csv(df: pandas.DataFrame, file_name: str, connection: duckdb.DuckDBPyConnection = None) → None +duckdb.write_csv(df: pandas.DataFrame, file_name: str, connection: duckdb.DuckDBPyConnection = None) → None

Write the DataFrame df to a CSV file in file_name

From 440089fbaf68969f04d9cc6b17bf041beb629a17 Mon Sep 17 00:00:00 2001 From: GitHub Actions Date: Mon, 28 Aug 2023 05:06:12 +0000 Subject: [PATCH 06/12] chore: auto update docs --- data/search_data.json | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/data/search_data.json b/data/search_data.json index e4a74def868..16af8661642 100644 --- a/data/search_data.json +++ b/data/search_data.json @@ -434,13 +434,6 @@ "url": "/docs/guides/sql_editors/dbeaver", "blurb": "How to set up DBeaver SQL IDE for DuckDB DBeaver is a powerful and popular desktop sql editor and integrated..." }, - { - "title": "Data Ingestion", - "text": "csv files csv files can be read using the read_csv function called either from within python or directly from within sql by default the read_csv function attempts to auto-detect the csv settings by sampling from the provided file import duckdb read from a file using fully auto-detected settings duckdb read_csv example csv read multiple csv files from a folder duckdb read_csv folder csv specify options on how the csv is formatted internally duckdb read_csv example csv header false sep override types of the first two columns duckdb read_csv example csv dtype int varchar use the experimental parallel csv reader duckdb read_csv example csv parallel true directly read a csv file from within sql duckdb sql select from example csv call read_csv from within sql duckdb sql select from read_csv_auto example csv see the csv loading page for more information parquet files parquet files can be read using the read_parquet function called either from within python or directly from within sql import duckdb read from a single parquet file duckdb read_parquet example parquet read multiple parquet files from a folder duckdb read_parquet folder parquet directly read a parquet file from within sql duckdb sql select from example parquet call read_parquet from within sql duckdb sql select from read_parquet example parquet see the parquet loading page for more information json files json files can be read using the read_json function called either from within python or directly from within sql by default the read_json function will automatically detect if a file contains newline-delimited json or regular json and will detect the schema of the objects stored within the json file import duckdb read from a single json file duckdb read_json example json read multiple json files from a folder duckdb read_json folder json directly read a json file from within sql duckdb sql select from example json call read_json from within sql duckdb sql select from read_json_auto example json dataframes arrow tables duckdb is automatically able to query a pandas dataframe polars dataframe or arrow object that is stored in a python variable by name duckdb supports querying multiple types of apache arrow objects including tables datasets recordbatchreaders and scanners see the python guides for more examples import duckdb import pandas as pd test_df pd dataframe from_dict i 1 2 3 4 j one two three four duckdb sql select from test_df fetchall 1 one 2 two 3 three 4 four duckdb also supports registering a dataframe or arrow object as a virtual table comparable to a sql view this is useful when querying a dataframe arrow object that is stored in another way as a class variable or a value in a dictionary below is a pandas example if your pandas dataframe is stored in another location here is an example of manually registering it import duckdb import pandas as pd my_dictionary my_dictionary test_df pd dataframe from_dict i 1 2 3 4 j one two three four duckdb register test_df_view my_dictionary test_df duckdb sql select from test_df_view fetchall 1 one 2 two 3 three 4 four you can also create a persistent table in duckdb from the contents of the dataframe or the view create a new table from the contents of a dataframe con execute create table test_df_table as select from test_df insert into an existing table from the contents of a dataframe con execute insert into test_df_table select from test_df pandas dataframes - object columns pandas dataframe columns of an object dtype require some special care since this stores values of arbitrary type to convert these columns to duckdb we first go through an analyze phase before converting the values in this analyze phase a sample of all the rows of the column are analyzed to determine the target type this sample size is by default set to 1000 if the type picked during the analyze step is wrong this will result in a failed to cast value error in which case you will need to increase the sample size the sample size can be changed by setting the pandas_analyze_sample config option example setting the sample size to 100000 duckdb default_connection execute set global pandas_analyze_sample 100000", - "category": "Python", - "url": "/docs/api/python/data_ingestion", - "blurb": "CSV Files CSV files can be read using the read_csv function, called either from within Python or directly from within..." - }, { "title": "Data Ingestion", "text": "duckdb-wasm has multiple ways to import data depending on the format of the data there are two steps to import data into duckdb first the data file is imported into a local file system using register functions registeremptyfilebuffer registerfilebuffer registerfilehandle registerfiletext registerfileurl then the data file is imported into duckdb using insert functions insertarrowfromipcstream insertarrowtable insertcsvfrompath insertjsonfrompath or directly using from sql query using extensions like parquet or httpfs insert statements can also be used to import data data import open close connection create a new connection const c await db connect import data close the connection to release memory await c close apache arrow data can be inserted from an existing arrow table more example https arrow apache org docs js import tablefromarrays from apache-arrow const arrowtable tablefromarrays id 1 2 3 name john jane jack age 20 21 22 await c insertarrowtable arrowtable name arrow_table from a raw arrow ipc stream const streamresponse await fetch someapi const streamreader streamresponse body getreader const streaminserts while true const value done await streamreader read if done break streaminserts push c insertarrowfromipcstream value name streamed await promise all streaminserts csv from csv files interchangeable registerfile text buffer url handle const csvcontent 1 foo n2 bar n await db registerfiletext data csv csvcontent with typed insert options await db insertcsvfrompath data csv schema main name foo detect false header false delimiter columns col1 new arrow int32 col2 new arrow utf8 json from json documents in row-major format const jsonrowcontent col1 1 col2 foo col1 2 col2 bar await db registerfiletext rows json json stringify jsonrowcontent await c insertjsonfrompath rows json name rows or column-major format const jsoncolcontent col1 1 2 col2 foo bar await db registerfiletext columns json json stringify jsoncolcontent await c insertjsonfrompath columns json name columns from api const streamresponse await fetch someapi content json await db registerfilebuffer file json new uint8array await streamresponse arraybuffer await c insertjsonfrompath file json name jsoncontent parquet from parquet files local const pickedfile file letuserpickfile await db registerfilehandle local parquet pickedfile duckdbdataprotocol browser_filereader true remote await db registerfileurl remote parquet https origin remote parquet duckdbdataprotocol http false using fetch const res await fetch https origin remote parquet await db registerfilebuffer buffer parquet new uint8array await res arraybuffer by specifying urls in the sql text await c query create table direct as select from https origin remote parquet or by executing raw insert statements await c query insert into existing_table values 1 foo 2 bar httpfs by specifying urls in the sql text await c query create table direct as select from https origin remote parquet insert statement or by executing raw insert statements await c query insert into existing_table values 1 foo 2 bar", @@ -448,6 +441,13 @@ "url": "/docs/api/wasm/data_ingestion", "blurb": "DuckDB-Wasm has multiple ways to import data, depending on the format of the data. There are two steps to import data..." }, + { + "title": "Data Ingestion", + "text": "csv files csv files can be read using the read_csv function called either from within python or directly from within sql by default the read_csv function attempts to auto-detect the csv settings by sampling from the provided file import duckdb read from a file using fully auto-detected settings duckdb read_csv example csv read multiple csv files from a folder duckdb read_csv folder csv specify options on how the csv is formatted internally duckdb read_csv example csv header false sep override types of the first two columns duckdb read_csv example csv dtype int varchar use the experimental parallel csv reader duckdb read_csv example csv parallel true directly read a csv file from within sql duckdb sql select from example csv call read_csv from within sql duckdb sql select from read_csv_auto example csv see the csv loading page for more information parquet files parquet files can be read using the read_parquet function called either from within python or directly from within sql import duckdb read from a single parquet file duckdb read_parquet example parquet read multiple parquet files from a folder duckdb read_parquet folder parquet directly read a parquet file from within sql duckdb sql select from example parquet call read_parquet from within sql duckdb sql select from read_parquet example parquet see the parquet loading page for more information json files json files can be read using the read_json function called either from within python or directly from within sql by default the read_json function will automatically detect if a file contains newline-delimited json or regular json and will detect the schema of the objects stored within the json file import duckdb read from a single json file duckdb read_json example json read multiple json files from a folder duckdb read_json folder json directly read a json file from within sql duckdb sql select from example json call read_json from within sql duckdb sql select from read_json_auto example json dataframes arrow tables duckdb is automatically able to query a pandas dataframe polars dataframe or arrow object that is stored in a python variable by name duckdb supports querying multiple types of apache arrow objects including tables datasets recordbatchreaders and scanners see the python guides for more examples import duckdb import pandas as pd test_df pd dataframe from_dict i 1 2 3 4 j one two three four duckdb sql select from test_df fetchall 1 one 2 two 3 three 4 four duckdb also supports registering a dataframe or arrow object as a virtual table comparable to a sql view this is useful when querying a dataframe arrow object that is stored in another way as a class variable or a value in a dictionary below is a pandas example if your pandas dataframe is stored in another location here is an example of manually registering it import duckdb import pandas as pd my_dictionary my_dictionary test_df pd dataframe from_dict i 1 2 3 4 j one two three four duckdb register test_df_view my_dictionary test_df duckdb sql select from test_df_view fetchall 1 one 2 two 3 three 4 four you can also create a persistent table in duckdb from the contents of the dataframe or the view create a new table from the contents of a dataframe con execute create table test_df_table as select from test_df insert into an existing table from the contents of a dataframe con execute insert into test_df_table select from test_df pandas dataframes - object columns pandas dataframe columns of an object dtype require some special care since this stores values of arbitrary type to convert these columns to duckdb we first go through an analyze phase before converting the values in this analyze phase a sample of all the rows of the column are analyzed to determine the target type this sample size is by default set to 1000 if the type picked during the analyze step is wrong this will result in a failed to cast value error in which case you will need to increase the sample size the sample size can be changed by setting the pandas_analyze_sample config option example setting the sample size to 100000 duckdb default_connection execute set global pandas_analyze_sample 100000", + "category": "Python", + "url": "/docs/api/python/data_ingestion", + "blurb": "CSV Files CSV files can be read using the read_csv function, called either from within Python or directly from within..." + }, { "title": "Data Types", "text": "general-purpose data types the table below shows all the built-in general-purpose data types the alternatives listed in the aliases column can be used to refer to these types as well however note that the aliases are not part of the sql standard and hence might not be accepted by other database engines name aliases description --- --- --- bigint int8 long signed eight-byte integer bit bitstring string of 1 s and 0 s boolean bool logical logical boolean true false blob bytea binary varbinary variable-length binary data date calendar date year month day double float8 numeric decimal double precision floating-point number 8 bytes decimal prec scale fixed-precision number with the given width precision and scale hugeint signed sixteen-byte integer integer int4 int signed signed four-byte integer interval date time delta real float4 float single precision floating-point number 4 bytes smallint int2 short signed two-byte integer time time of day no time zone timestamp datetime combination of time and date timestamp with time zone timestamptz combination of time and date that uses the current time zone tinyint int1 signed one-byte integer ubigint unsigned eight-byte integer uinteger unsigned four-byte integer usmallint unsigned two-byte integer utinyint unsigned one-byte integer uuid uuid data type varchar char bpchar text string variable-length character string nested composite types duckdb supports four nested data types list struct map and union each supports different use cases and has a different structure name description rules when used in a column build from values define in ddl create --- --- --- --- --- list an ordered sequence of data values of the same type each row must have the same data type within each list but can have any number of elements 1 2 3 int struct a dictionary of multiple named values where each key is a string but the value can be a different type for each key each row must have the same keys i 42 j a struct i int j varchar map a dictionary of multiple named values each key having the same type and each value having the same type keys and values can be any type and can be different types from one another rows may have different keys map 1 2 a b map int varchar union a union of multiple alternative data types storing one of them in each value at a time a union also contains a discriminator tag value to inspect and access the currently set member type rows may be set to different member types of the union union_value num 2 union num int text varchar nesting list s struct s map s and union s can be arbitrarily nested to any depth so long as the type rules are observed -- struct with lists select birds duck goose heron aliens null amphibians frog toad -- struct with list of maps select test map 1 5 42 1 45 map 1 5 42 1 45 -- a list of unions select union_value num 2 union_value str abc union str varchar num integer links to detailed documentation", From cfad053ab22f2e52178af8b397cccba5f597de6f Mon Sep 17 00:00:00 2001 From: GitHub Actions Date: Mon, 4 Sep 2023 05:05:44 +0000 Subject: [PATCH 07/12] chore: auto update docs --- docs/api/python/reference/index.md | 414 +++++++++++++++++++++++------ 1 file changed, 333 insertions(+), 81 deletions(-) diff --git a/docs/api/python/reference/index.md b/docs/api/python/reference/index.md index 5c066c3911a..d77f2c98d08 100644 --- a/docs/api/python/reference/index.md +++ b/docs/api/python/reference/index.md @@ -732,15 +732,6 @@ title: Python Client API

Bases: pybind11_object

-
-
-abs(self: duckdb.duckdb.DuckDBPyRelation, aggregation_columns: str) → duckdb.duckdb.DuckDBPyRelation -
-
-

Returns the absolute value for the specified columns.

-
-
-
aggregate(self: duckdb.duckdb.DuckDBPyRelation, aggr_expr: str, group_expr: str = '') → duckdb.duckdb.DuckDBPyRelation @@ -759,6 +750,15 @@ title: Python Client API
+
+
+any_value(self: duckdb.duckdb.DuckDBPyRelation, column: str, groups: str = '', window_spec: str = '', projected_columns: str = '') → duckdb.duckdb.DuckDBPyRelation +
+
+

Returns the first non-null value from a given column

+
+
+
apply(self: duckdb.duckdb.DuckDBPyRelation, function_name: str, function_aggr: str, group_expr: str = '', function_parameter: str = '', projected_columns: str = '') → duckdb.duckdb.DuckDBPyRelation @@ -768,6 +768,24 @@ title: Python Client API
+
+
+arg_max(self: duckdb.duckdb.DuckDBPyRelation, arg_column: str, value_column: str, groups: str = '', window_spec: str = '', projected_columns: str = '') → duckdb.duckdb.DuckDBPyRelation +
+
+

Finds the row with the maximum value for a value column and returns the value of that row for an argument column

+
+
+ +
+
+arg_min(self: duckdb.duckdb.DuckDBPyRelation, arg_column: str, value_column: str, groups: str = '', window_spec: str = '', projected_columns: str = '') → duckdb.duckdb.DuckDBPyRelation +
+
+

Finds the row with the minimum value for a value column and returns the value of that row for an argument column

+
+
+
arrow(self: duckdb.duckdb.DuckDBPyRelation, batch_size: int = 1000000) → pyarrow.lib.Table @@ -777,6 +795,69 @@ title: Python Client API
+
+
+avg(self: duckdb.duckdb.DuckDBPyRelation, column: str, groups: str = '', window_spec: str = '', projected_columns: str = '') → duckdb.duckdb.DuckDBPyRelation +
+
+

Computes the average on a given column

+
+
+ +
+
+bit_and(self: duckdb.duckdb.DuckDBPyRelation, column: str, groups: str = '', window_spec: str = '', projected_columns: str = '') → duckdb.duckdb.DuckDBPyRelation +
+
+

Computes the bitwise AND of all bits present in a given column

+
+
+ +
+
+bit_or(self: duckdb.duckdb.DuckDBPyRelation, column: str, groups: str = '', window_spec: str = '', projected_columns: str = '') → duckdb.duckdb.DuckDBPyRelation +
+
+

Computes the bitwise OR of all bits present in a given column

+
+
+ +
+
+bit_xor(self: duckdb.duckdb.DuckDBPyRelation, column: str, groups: str = '', window_spec: str = '', projected_columns: str = '') → duckdb.duckdb.DuckDBPyRelation +
+
+

Computes the bitwise XOR of all bits present in a given column

+
+
+ +
+
+bitstring_agg(self: duckdb.duckdb.DuckDBPyRelation, column: str, min: Optional[object] = None, max: Optional[object] = None, groups: str = '', window_spec: str = '', projected_columns: str = '') → duckdb.duckdb.DuckDBPyRelation +
+
+

Computes a bitstring with bits set for each distinct value in a given column

+
+
+ +
+
+bool_and(self: duckdb.duckdb.DuckDBPyRelation, column: str, groups: str = '', window_spec: str = '', projected_columns: str = '') → duckdb.duckdb.DuckDBPyRelation +
+
+

Computes the logical AND of all values present in a given column

+
+
+ +
+
+bool_or(self: duckdb.duckdb.DuckDBPyRelation, column: str, groups: str = '', window_spec: str = '', projected_columns: str = '') → duckdb.duckdb.DuckDBPyRelation +
+
+

Computes the logical OR of all values present in a given column

+
+
+
close(self: duckdb.duckdb.DuckDBPyRelation) → None @@ -797,10 +878,10 @@ title: Python Client API
-count(self: duckdb.duckdb.DuckDBPyRelation, count_aggr: str, group_expr: str = '') → duckdb.duckdb.DuckDBPyRelation +count(self: duckdb.duckdb.DuckDBPyRelation, column: str, groups: str = '', window_spec: str = '', projected_columns: str = '') → duckdb.duckdb.DuckDBPyRelation
-

Compute the aggregate count of a single column or a list of columns by the optional groups on the relation

+

Computes the number of elements present in a given column

@@ -823,38 +904,20 @@ title: Python Client API
-
-cummax(self: duckdb.duckdb.DuckDBPyRelation, aggregation_columns: str) → duckdb.duckdb.DuckDBPyRelation -
-
-

Returns the cumulative maximum of the aggregate column.

-
-
- -
-
-cummin(self: duckdb.duckdb.DuckDBPyRelation, aggregation_columns: str) → duckdb.duckdb.DuckDBPyRelation -
-
-

Returns the cumulative minimum of the aggregate column.

-
-
- -
-
-cumprod(self: duckdb.duckdb.DuckDBPyRelation, aggregation_columns: str) → duckdb.duckdb.DuckDBPyRelation +
+cume_dist(self: duckdb.duckdb.DuckDBPyRelation, window_spec: str, projected_columns: str = '') → duckdb.duckdb.DuckDBPyRelation
-

Returns the cumulative product of the aggregate column.

+

Computes the cumulative distribution within the partition

-
-cumsum(self: duckdb.duckdb.DuckDBPyRelation, aggregation_columns: str) → duckdb.duckdb.DuckDBPyRelation +
+dense_rank(self: duckdb.duckdb.DuckDBPyRelation, window_spec: str, projected_columns: str = '') → duckdb.duckdb.DuckDBPyRelation
-

Returns the cumulative sum of the aggregate column.

+

Computes the dense rank within the partition

@@ -928,6 +991,15 @@ title: Python Client API
+
+
+favg(self: duckdb.duckdb.DuckDBPyRelation, column: str, groups: str = '', window_spec: str = '', projected_columns: str = '') → duckdb.duckdb.DuckDBPyRelation +
+
+

Computes the average of all values present in a given column using a more accurate floating point summation (Kahan Sum)

+
+
+
fetch_arrow_reader(self: duckdb.duckdb.DuckDBPyRelation, batch_size: int = 1000000) → pyarrow.lib.RecordBatchReader @@ -1000,6 +1072,51 @@ title: Python Client API
+
+
+first(self: duckdb.duckdb.DuckDBPyRelation, column: str, groups: str = '', projected_columns: str = '') → duckdb.duckdb.DuckDBPyRelation +
+
+

Returns the first value of a given column

+
+
+ +
+
+first_value(self: duckdb.duckdb.DuckDBPyRelation, column: str, window_spec: str = '', projected_columns: str = '') → duckdb.duckdb.DuckDBPyRelation +
+
+

Computes the first value within the group or partition

+
+
+ +
+
+fsum(self: duckdb.duckdb.DuckDBPyRelation, column: str, groups: str = '', window_spec: str = '', projected_columns: str = '') → duckdb.duckdb.DuckDBPyRelation +
+
+

Computes the sum of all values present in a given column using a more accurate floating point summation (Kahan Sum)

+
+
+ +
+
+geomean(self: duckdb.duckdb.DuckDBPyRelation, column: str, groups: str = '', projected_columns: str = '') → duckdb.duckdb.DuckDBPyRelation +
+
+

Computes the geometric mean over all values present in a given column

+
+
+ +
+
+histogram(self: duckdb.duckdb.DuckDBPyRelation, column: str, groups: str = '', window_spec: str = '', projected_columns: str = '') → duckdb.duckdb.DuckDBPyRelation +
+
+

Computes the histogram over all values present in a given column

+
+
+
insert(self: duckdb.duckdb.DuckDBPyRelation, values: object) → None @@ -1037,11 +1154,38 @@ title: Python Client API
-
-kurt(self: duckdb.duckdb.DuckDBPyRelation, aggregation_columns: str, group_columns: str = '') → duckdb.duckdb.DuckDBPyRelation +
+lag(self: duckdb.duckdb.DuckDBPyRelation, column: str, window_spec: str, offset: int = 1, default_value: str = 'NULL', ignore_nulls: bool = False, projected_columns: str = '') → duckdb.duckdb.DuckDBPyRelation +
+
+

Computes the lag within the partition

+
+
+ +
+
+last(self: duckdb.duckdb.DuckDBPyRelation, column: str, groups: str = '', projected_columns: str = '') → duckdb.duckdb.DuckDBPyRelation +
+
+

Returns the last value of a given column

+
+
+ +
+
+last_value(self: duckdb.duckdb.DuckDBPyRelation, column: str, window_spec: str = '', projected_columns: str = '') → duckdb.duckdb.DuckDBPyRelation
-

Returns the excess kurtosis of the aggregate column.

+

Computes the last value within the group or partition

+
+
+ +
+
+lead(self: duckdb.duckdb.DuckDBPyRelation, column: str, window_spec: str, offset: int = 1, default_value: str = 'NULL', ignore_nulls: bool = False, projected_columns: str = '') → duckdb.duckdb.DuckDBPyRelation +
+
+

Computes the lead within the partition

@@ -1055,11 +1199,11 @@ title: Python Client API
-
-mad(self: duckdb.duckdb.DuckDBPyRelation, aggregation_columns: str, group_columns: str = '') → duckdb.duckdb.DuckDBPyRelation +
+list(self: duckdb.duckdb.DuckDBPyRelation, column: str, groups: str = '', window_spec: str = '', projected_columns: str = '') → duckdb.duckdb.DuckDBPyRelation
-

Returns the median absolute deviation for the aggregate columns. NULL values are ignored. Temporal types return a positive INTERVAL.

+

Returns a list containing all values present in a given column

@@ -1074,46 +1218,64 @@ title: Python Client API
-max(self: duckdb.duckdb.DuckDBPyRelation, max_aggr: str, group_expr: str = '') → duckdb.duckdb.DuckDBPyRelation +max(self: duckdb.duckdb.DuckDBPyRelation, column: str, groups: str = '', window_spec: str = '', projected_columns: str = '') → duckdb.duckdb.DuckDBPyRelation
-

Compute the aggregate max of a single column or a list of columns by the optional groups on the relation

+

Returns the maximum value present in a given column

-mean(self: duckdb.duckdb.DuckDBPyRelation, mean_aggr: str, group_expr: str = '') → duckdb.duckdb.DuckDBPyRelation +mean(self: duckdb.duckdb.DuckDBPyRelation, column: str, groups: str = '', window_spec: str = '', projected_columns: str = '') → duckdb.duckdb.DuckDBPyRelation
-

Compute the aggregate mean of a single column or a list of columns by the optional groups on the relation

+

Computes the average on a given column

-median(self: duckdb.duckdb.DuckDBPyRelation, median_aggr: str, group_expr: str = '') → duckdb.duckdb.DuckDBPyRelation +median(self: duckdb.duckdb.DuckDBPyRelation, column: str, groups: str = '', window_spec: str = '', projected_columns: str = '') → duckdb.duckdb.DuckDBPyRelation
-

Compute the aggregate median of a single column or a list of columns by the optional groups on the relation

+

Computes the median over all values present in a given column

-min(self: duckdb.duckdb.DuckDBPyRelation, min_aggr: str, group_expr: str = '') → duckdb.duckdb.DuckDBPyRelation +min(self: duckdb.duckdb.DuckDBPyRelation, column: str, groups: str = '', window_spec: str = '', projected_columns: str = '') → duckdb.duckdb.DuckDBPyRelation
-

Compute the aggregate min of a single column or a list of columns by the optional groups on the relation

+

Returns the minimum value present in a given column

-mode(self: duckdb.duckdb.DuckDBPyRelation, aggregation_columns: str, group_columns: str = '') → duckdb.duckdb.DuckDBPyRelation +mode(self: duckdb.duckdb.DuckDBPyRelation, column: str, groups: str = '', window_spec: str = '', projected_columns: str = '') → duckdb.duckdb.DuckDBPyRelation +
+
+

Computes the mode over all values present in a given column

+
+
+ +
+
+n_tile(self: duckdb.duckdb.DuckDBPyRelation, window_spec: str, num_buckets: int, projected_columns: str = '') → duckdb.duckdb.DuckDBPyRelation +
+
+

Divides the partition as equally as possible into num_buckets

+
+
+ +
+
+nth_value(self: duckdb.duckdb.DuckDBPyRelation, column: str, window_spec: str, offset: int, ignore_nulls: bool = False, projected_columns: str = '') → duckdb.duckdb.DuckDBPyRelation
-

Returns the most frequent value for the aggregate columns. NULL values are ignored.

+

Computes the nth value within the partition

@@ -1126,6 +1288,15 @@ title: Python Client API
+
+
+percent_rank(self: duckdb.duckdb.DuckDBPyRelation, window_spec: str, projected_columns: str = '') → duckdb.duckdb.DuckDBPyRelation +
+
+

Computes the relative rank within the partition

+
+
+
pl(self: duckdb.duckdb.DuckDBPyRelation, batch_size: int = 1000000) → duckdb::PolarsDataFrame @@ -1136,11 +1307,11 @@ title: Python Client API
-
-prod(self: duckdb.duckdb.DuckDBPyRelation, aggregation_columns: str, group_columns: str = '') → duckdb.duckdb.DuckDBPyRelation +
+product(self: duckdb.duckdb.DuckDBPyRelation, column: str, groups: str = '', window_spec: str = '', projected_columns: str = '') → duckdb.duckdb.DuckDBPyRelation
-

Calculates the product of the aggregate column.

+

Returns the product of all values present in a given column

@@ -1155,10 +1326,28 @@ title: Python Client API
-quantile(self: duckdb.duckdb.DuckDBPyRelation, q: str, quantile_aggr: str, group_expr: str = '') → duckdb.duckdb.DuckDBPyRelation +quantile(self: duckdb.duckdb.DuckDBPyRelation, column: str, q: object = 0.5, groups: str = '', window_spec: str = '', projected_columns: str = '') → duckdb.duckdb.DuckDBPyRelation +
+
+

Computes the exact quantile value for a given column

+
+
+ +
+
+quantile_cont(self: duckdb.duckdb.DuckDBPyRelation, column: str, q: object = 0.5, groups: str = '', window_spec: str = '', projected_columns: str = '') → duckdb.duckdb.DuckDBPyRelation +
+
+

Computes the interpolated quantile value for a given column

+
+
+ +
+
+quantile_disc(self: duckdb.duckdb.DuckDBPyRelation, column: str, q: object = 0.5, groups: str = '', window_spec: str = '', projected_columns: str = '') → duckdb.duckdb.DuckDBPyRelation
-

Compute the quantile of a single column or a list of columns by the optional groups on the relation

+

Computes the exact quantile value for a given column

@@ -1171,6 +1360,24 @@ title: Python Client API
+
+
+rank(self: duckdb.duckdb.DuckDBPyRelation, window_spec: str, projected_columns: str = '') → duckdb.duckdb.DuckDBPyRelation +
+
+

Computes the rank within the partition

+
+
+ +
+
+rank_dense(self: duckdb.duckdb.DuckDBPyRelation, window_spec: str, projected_columns: str = '') → duckdb.duckdb.DuckDBPyRelation +
+
+

Computes the dense rank within the partition

+
+
+
record_batch(self: duckdb.duckdb.DuckDBPyRelation, batch_size: int = 1000000) → pyarrow.lib.RecordBatchReader @@ -1181,17 +1388,17 @@ title: Python Client API
-
-select_dtypes(self: duckdb.duckdb.DuckDBPyRelation, types: object) → duckdb.duckdb.DuckDBPyRelation +
+row_number(self: duckdb.duckdb.DuckDBPyRelation, window_spec: str, projected_columns: str = '') → duckdb.duckdb.DuckDBPyRelation
-

Select columns from the relation, by filtering based on type(s)

+

Computes the row number within the partition

-
-select_types(self: duckdb.duckdb.DuckDBPyRelation, types: object) → duckdb.duckdb.DuckDBPyRelation +
+select_dtypes(self: duckdb.duckdb.DuckDBPyRelation, types: object) → duckdb.duckdb.DuckDBPyRelation

Select columns from the relation, by filtering based on type(s)

@@ -1199,11 +1406,11 @@ title: Python Client API
-
-sem(self: duckdb.duckdb.DuckDBPyRelation, aggregation_columns: str, group_columns: str = '') → duckdb.duckdb.DuckDBPyRelation +
+select_types(self: duckdb.duckdb.DuckDBPyRelation, types: object) → duckdb.duckdb.DuckDBPyRelation
-

Returns the standard error of the mean of the aggregate column.

+

Select columns from the relation, by filtering based on type(s)

@@ -1235,38 +1442,65 @@ title: Python Client API
-
-skew(self: duckdb.duckdb.DuckDBPyRelation, aggregation_columns: str, group_columns: str = '') → duckdb.duckdb.DuckDBPyRelation +
+sql_query(self: duckdb.duckdb.DuckDBPyRelation) → str
-

Returns the skewness of the aggregate column.

+

Get the SQL query that is equivalent to the relation

-
-sql_query(self: duckdb.duckdb.DuckDBPyRelation) → str +
+std(self: duckdb.duckdb.DuckDBPyRelation, column: str, groups: str = '', window_spec: str = '', projected_columns: str = '') → duckdb.duckdb.DuckDBPyRelation
-

Get the SQL query that is equivalent to the relation

+

Computes the sample standard deviation for a given column

-
-std(self: duckdb.duckdb.DuckDBPyRelation, std_aggr: str, group_expr: str = '') → duckdb.duckdb.DuckDBPyRelation +
+stddev(self: duckdb.duckdb.DuckDBPyRelation, column: str, groups: str = '', window_spec: str = '', projected_columns: str = '') → duckdb.duckdb.DuckDBPyRelation +
+
+

Computes the sample standard deviation for a given column

+
+
+ +
+
+stddev_pop(self: duckdb.duckdb.DuckDBPyRelation, column: str, groups: str = '', window_spec: str = '', projected_columns: str = '') → duckdb.duckdb.DuckDBPyRelation +
+
+

Computes the population standard deviation for a given column

+
+
+ +
+
+stddev_samp(self: duckdb.duckdb.DuckDBPyRelation, column: str, groups: str = '', window_spec: str = '', projected_columns: str = '') → duckdb.duckdb.DuckDBPyRelation +
+
+

Computes the sample standard deviation for a given column

+
+
+ +
+
+string_agg(self: duckdb.duckdb.DuckDBPyRelation, column: str, sep: str = ',', groups: str = '', window_spec: str = '', projected_columns: str = '') → duckdb.duckdb.DuckDBPyRelation
-

Compute the standard deviation of a single column or a list of columns by the optional groups on the relation

+

Concatenates the values present in a given column with a separator

-sum(self: duckdb.duckdb.DuckDBPyRelation, sum_aggr: str, group_expr: str = '') → duckdb.duckdb.DuckDBPyRelation +sum(self: duckdb.duckdb.DuckDBPyRelation, column: str, groups: str = '', window_spec: str = '', projected_columns: str = '') → duckdb.duckdb.DuckDBPyRelation
-

Compute the aggregate sum of a single column or a list of columns by the optional groups on the relation

+

Computes the sum of all values present in a given column

@@ -1379,20 +1613,38 @@ title: Python Client API
-
-value_counts(self: duckdb.duckdb.DuckDBPyRelation, value_counts_aggr: str, group_expr: str = '') → duckdb.duckdb.DuckDBPyRelation +
+var(self: duckdb.duckdb.DuckDBPyRelation, column: str, groups: str = '', window_spec: str = '', projected_columns: str = '') → duckdb.duckdb.DuckDBPyRelation
-

Count number of rows with each unique value of variable

+

Computes the sample variance for a given column

-
-var(self: duckdb.duckdb.DuckDBPyRelation, var_aggr: str, group_expr: str = '') → duckdb.duckdb.DuckDBPyRelation +
+var_pop(self: duckdb.duckdb.DuckDBPyRelation, column: str, groups: str = '', window_spec: str = '', projected_columns: str = '') → duckdb.duckdb.DuckDBPyRelation +
+
+

Computes the population variance for a given column

+
+
+ +
+
+var_samp(self: duckdb.duckdb.DuckDBPyRelation, column: str, groups: str = '', window_spec: str = '', projected_columns: str = '') → duckdb.duckdb.DuckDBPyRelation +
+
+

Computes the sample variance for a given column

+
+
+ +
+
+variance(self: duckdb.duckdb.DuckDBPyRelation, column: str, groups: str = '', window_spec: str = '', projected_columns: str = '') → duckdb.duckdb.DuckDBPyRelation
-

Compute the variance of a single column or a list of columns by the optional groups on the relation

+

Computes the sample variance for a given column

From 0c3fc78a4c81b0637c7b875434206fd388bbbe28 Mon Sep 17 00:00:00 2001 From: GitHub Actions Date: Mon, 11 Sep 2023 05:05:55 +0000 Subject: [PATCH 08/12] chore: auto update docs --- data/search_data.json | 8 ++++---- docs/api/c/api.md | 31 +++++++++++++++++++++++++++++++ docs/api/c/types.md | 31 +++++++++++++++++++++++++++++++ docs/api/nodejs/reference.md | 6 +++--- 4 files changed, 69 insertions(+), 7 deletions(-) diff --git a/data/search_data.json b/data/search_data.json index 16af8661642..7a70c70be97 100644 --- a/data/search_data.json +++ b/data/search_data.json @@ -163,7 +163,7 @@ }, { "title": "C API - Complete API", - "text": "api reference open connect syntax path to the database file on disk or nullptr or memory to open an in-memory database out_database the result database object returns duckdbsuccess on success or duckdberror on failure duckdb_open_ext extended version of duckdb_open creates a new database or opens an existing database file stored at the the given path syntax path to the database file on disk or nullptr or memory to open an in-memory database out_database the result database object config optional configuration used to start up the database system out_error if set and the function returns duckdberror this will contain the reason why the start-up failed note that the error must be freed using duckdb_free returns duckdbsuccess on success or duckdberror on failure duckdb_close closes the specified database and de-allocates all memory allocated for that database this should be called after you are done with any database allocated through duckdb_open note that failing to call duckdb_close in case of e g a program crash will not cause data corruption still it is recommended to always correctly close a database object after you are done with it syntax the database object to shut down duckdb_connect opens a connection to a database connections are required to query the database and store transactional state associated with the connection the instantiated connection should be closed using duckdb_disconnect syntax the database file to connect to out_connection the result connection object returns duckdbsuccess on success or duckdberror on failure duckdb_interrupt interrupt running query syntax the connection to interruot duckdb_query_progress get progress of the running query syntax the working connection returns -1 if no progress or a percentage of the progress duckdb_disconnect closes the specified connection and de-allocates all memory allocated for that connection syntax the connection to close duckdb_library_version returns the version of the linked duckdb with a version postfix for dev versions usually used for developing c extensions that must return this for a compatibility check syntax duckdb_create_config initializes an empty configuration object that can be used to provide start-up options for the duckdb instance through duckdb_open_ext this will always succeed unless there is a malloc failure syntax the result configuration object returns duckdbsuccess on success or duckdberror on failure duckdb_config_count this returns the total amount of configuration options available for usage with duckdb_get_config_flag this should not be called in a loop as it internally loops over all the options syntax the amount of config options available duckdb_get_config_flag obtains a human-readable name and description of a specific configuration option this can be used to e g display configuration options this will succeed unless index is out of range i e duckdb_config_count the result name or description must not be freed syntax the index of the configuration option between 0 and duckdb_config_count out_name a name of the configuration flag out_description a description of the configuration flag returns duckdbsuccess on success or duckdberror on failure duckdb_set_config sets the specified option for the specified configuration the configuration option is indicated by name to obtain a list of config options see duckdb_get_config_flag in the source code configuration options are defined in config cpp this can fail if either the name is invalid or if the value provided for the option is invalid syntax the configuration object to set the option on name the name of the configuration flag to set option the value to set the configuration flag to returns duckdbsuccess on success or duckdberror on failure duckdb_destroy_config destroys the specified configuration option and de-allocates all memory allocated for the object syntax the configuration object to destroy duckdb_query executes a sql query within a connection and stores the full materialized result in the out_result pointer if the query fails to execute duckdberror is returned and the error message can be retrieved by calling duckdb_result_error note that after running duckdb_query duckdb_destroy_result must be called on the result object even if the query fails otherwise the error stored within the result will not be freed correctly syntax the connection to perform the query in query the sql query to run out_result the query result returns duckdbsuccess on success or duckdberror on failure duckdb_destroy_result closes the result and de-allocates all memory allocated for that connection syntax the result to destroy duckdb_column_name returns the column name of the specified column the result should not need be freed the column names will automatically be destroyed when the result is destroyed returns null if the column is out of range syntax the result object to fetch the column name from col the column index returns the column name of the specified column duckdb_column_type returns the column type of the specified column returns duckdb_type_invalid if the column is out of range syntax the result object to fetch the column type from col the column index returns the column type of the specified column duckdb_column_logical_type returns the logical column type of the specified column the return type of this call should be destroyed with duckdb_destroy_logical_type returns null if the column is out of range syntax the result object to fetch the column type from col the column index returns the logical column type of the specified column duckdb_column_count returns the number of columns present in a the result object syntax the result object returns the number of columns present in the result object duckdb_row_count returns the number of rows present in a the result object syntax the result object returns the number of rows present in the result object duckdb_rows_changed returns the number of rows changed by the query stored in the result this is relevant only for insert update delete queries for other queries the rows_changed will be 0 syntax the result object returns the number of rows changed duckdb_column_data deprecated prefer using duckdb_result_get_chunk instead returns the data of a specific column of a result in columnar format the function returns a dense array which contains the result data the exact type stored in the array depends on the corresponding duckdb_type as provided by duckdb_column_type for the exact type by which the data should be accessed see the comments in the types section or the duckdb_type enum for example for a column of type duckdb_type_integer rows can be accessed in the following manner int32_t data int32_t duckdb_column_data result 0 printf data for row d d n row data row syntax the result object to fetch the column data from col the column index returns the column data of the specified column duckdb_nullmask_data deprecated prefer using duckdb_result_get_chunk instead returns the nullmask of a specific column of a result in columnar format the nullmask indicates for every row whether or not the corresponding row is null if a row is null the values present in the array provided by duckdb_column_data are undefined int32_t data int32_t duckdb_column_data result 0 bool nullmask duckdb_nullmask_data result 0 if nullmask row printf data for row d null n row else printf data for row d d n row data row syntax the result object to fetch the nullmask from col the column index returns the nullmask of the specified column duckdb_result_error returns the error message contained within the result the error is only set if duckdb_query returns duckdberror the result of this function must not be freed it will be cleaned up when duckdb_destroy_result is called syntax the result object to fetch the error from returns the error of the result duckdb_result_get_chunk fetches a data chunk from the duckdb_result this function should be called repeatedly until the result is exhausted the result must be destroyed with duckdb_destroy_data_chunk this function supersedes all duckdb_value functions as well as the duckdb_column_data and duckdb_nullmask_data functions it results in significantly better performance and should be preferred in newer code-bases if this function is used none of the other result functions can be used and vice versa i e this function cannot be mixed with the legacy result functions use duckdb_result_chunk_count to figure out how many chunks there are in the result syntax the result object to fetch the data chunk from chunk_index the chunk index to fetch from returns the resulting data chunk returns null if the chunk index is out of bounds duckdb_result_is_streaming checks if the type of the internal result is streamqueryresult syntax the result object to check returns whether or not the result object is of the type streamqueryresult duckdb_result_chunk_count returns the number of data chunks present in the result syntax the result object returns number of data chunks present in the result duckdb_value_boolean syntax the boolean value at the specified location or false if the value cannot be converted duckdb_value_int8 syntax the int8_t value at the specified location or 0 if the value cannot be converted duckdb_value_int16 syntax the int16_t value at the specified location or 0 if the value cannot be converted duckdb_value_int32 syntax the int32_t value at the specified location or 0 if the value cannot be converted duckdb_value_int64 syntax the int64_t value at the specified location or 0 if the value cannot be converted duckdb_value_hugeint syntax the duckdb_hugeint value at the specified location or 0 if the value cannot be converted duckdb_value_decimal syntax the duckdb_decimal value at the specified location or 0 if the value cannot be converted duckdb_value_uint8 syntax the uint8_t value at the specified location or 0 if the value cannot be converted duckdb_value_uint16 syntax the uint16_t value at the specified location or 0 if the value cannot be converted duckdb_value_uint32 syntax the uint32_t value at the specified location or 0 if the value cannot be converted duckdb_value_uint64 syntax the uint64_t value at the specified location or 0 if the value cannot be converted duckdb_value_float syntax the float value at the specified location or 0 if the value cannot be converted duckdb_value_double syntax the double value at the specified location or 0 if the value cannot be converted duckdb_value_date syntax the duckdb_date value at the specified location or 0 if the value cannot be converted duckdb_value_time syntax the duckdb_time value at the specified location or 0 if the value cannot be converted duckdb_value_timestamp syntax the duckdb_timestamp value at the specified location or 0 if the value cannot be converted duckdb_value_interval syntax the duckdb_interval value at the specified location or 0 if the value cannot be converted duckdb_value_varchar syntax use duckdb_value_string instead this function does not work correctly if the string contains null bytes returns the text value at the specified location as a null-terminated string or nullptr if the value cannot be converted the result must be freed with duckdb_free duckdb_value_varchar_internal syntax use duckdb_value_string_internal instead this function does not work correctly if the string contains null bytes returns the char value at the specified location only works on varchar columns and does not auto-cast if the column is not a varchar column this function will return null the result must not be freed duckdb_value_string_internal syntax use duckdb_value_string_internal instead this function does not work correctly if the string contains null bytes returns the char value at the specified location only works on varchar columns and does not auto-cast if the column is not a varchar column this function will return null the result must not be freed duckdb_value_blob syntax the duckdb_blob value at the specified location returns a blob with blob data set to nullptr if the value cannot be converted the resulting blob data must be freed with duckdb_free duckdb_value_is_null syntax returns true if the value at the specified index is null and false otherwise duckdb_malloc allocate size bytes of memory using the duckdb internal malloc function any memory allocated in this manner should be freed using duckdb_free syntax the number of bytes to allocate returns a pointer to the allocated memory region duckdb_free free a value returned from duckdb_malloc duckdb_value_varchar or duckdb_value_blob syntax the memory region to de-allocate duckdb_vector_size the internal vector size used by duckdb this is the amount of tuples that will fit into a data chunk created by duckdb_create_data_chunk syntax the vector size duckdb_string_is_inlined whether or not the duckdb_string_t value is inlined this means that the data of the string does not have a separate allocation syntax duckdb_from_date decompose a duckdb_date object into year month and date stored as duckdb_date_struct syntax the date object as obtained from a duckdb_type_date column returns the duckdb_date_struct with the decomposed elements duckdb_to_date re-compose a duckdb_date from year month and date duckdb_date_struct syntax the year month and date stored in a duckdb_date_struct returns the duckdb_date element duckdb_from_time decompose a duckdb_time object into hour minute second and microsecond stored as duckdb_time_struct syntax the time object as obtained from a duckdb_type_time column returns the duckdb_time_struct with the decomposed elements duckdb_to_time re-compose a duckdb_time from hour minute second and microsecond duckdb_time_struct syntax the hour minute second and microsecond in a duckdb_time_struct returns the duckdb_time element duckdb_from_timestamp decompose a duckdb_timestamp object into a duckdb_timestamp_struct syntax the ts object as obtained from a duckdb_type_timestamp column returns the duckdb_timestamp_struct with the decomposed elements duckdb_to_timestamp re-compose a duckdb_timestamp from a duckdb_timestamp_struct syntax the de-composed elements in a duckdb_timestamp_struct returns the duckdb_timestamp element duckdb_hugeint_to_double converts a duckdb_hugeint object as obtained from a duckdb_type_hugeint column into a double syntax the hugeint value returns the converted double element duckdb_double_to_hugeint converts a double value to a duckdb_hugeint object if the conversion fails because the double value is too big the result will be 0 syntax the double value returns the converted duckdb_hugeint element duckdb_double_to_decimal converts a double value to a duckdb_decimal object if the conversion fails because the double value is too big or the width scale are invalid the result will be 0 syntax the double value returns the converted duckdb_decimal element duckdb_decimal_to_double converts a duckdb_decimal object as obtained from a duckdb_type_decimal column into a double syntax the decimal value returns the converted double element duckdb_prepare create a prepared statement object from a query note that after calling duckdb_prepare the prepared statement should always be destroyed using duckdb_destroy_prepare even if the prepare fails if the prepare fails duckdb_prepare_error can be called to obtain the reason why the prepare failed syntax the connection object query the sql query to prepare out_prepared_statement the resulting prepared statement object returns duckdbsuccess on success or duckdberror on failure duckdb_destroy_prepare closes the prepared statement and de-allocates all memory allocated for the statement syntax the prepared statement to destroy duckdb_prepare_error returns the error message associated with the given prepared statement if the prepared statement has no error message this returns nullptr instead the error message should not be freed it will be de-allocated when duckdb_destroy_prepare is called syntax the prepared statement to obtain the error from returns the error message or nullptr if there is none duckdb_nparams returns the number of parameters that can be provided to the given prepared statement returns 0 if the query was not successfully prepared syntax the prepared statement to obtain the number of parameters for duckdb_param_type returns the parameter type for the parameter at the given index returns duckdb_type_invalid if the parameter index is out of range or the statement was not successfully prepared syntax the prepared statement param_idx the parameter index returns the parameter type duckdb_clear_bindings clear the params bind to the prepared statement syntax duckdb_bind_value binds a value to the prepared statement at the specified index syntax duckdb_bind_parameter_index retrieve the index of the parameter for the prepared statement identified by name syntax duckdb_bind_boolean binds a bool value to the prepared statement at the specified index syntax duckdb_bind_int8 binds an int8_t value to the prepared statement at the specified index syntax duckdb_bind_int16 binds an int16_t value to the prepared statement at the specified index syntax duckdb_bind_int32 binds an int32_t value to the prepared statement at the specified index syntax duckdb_bind_int64 binds an int64_t value to the prepared statement at the specified index syntax duckdb_bind_hugeint binds an duckdb_hugeint value to the prepared statement at the specified index syntax duckdb_bind_decimal binds a duckdb_decimal value to the prepared statement at the specified index syntax duckdb_bind_uint8 binds an uint8_t value to the prepared statement at the specified index syntax duckdb_bind_uint16 binds an uint16_t value to the prepared statement at the specified index syntax duckdb_bind_uint32 binds an uint32_t value to the prepared statement at the specified index syntax duckdb_bind_uint64 binds an uint64_t value to the prepared statement at the specified index syntax duckdb_bind_float binds an float value to the prepared statement at the specified index syntax duckdb_bind_double binds an double value to the prepared statement at the specified index syntax duckdb_bind_date binds a duckdb_date value to the prepared statement at the specified index syntax duckdb_bind_time binds a duckdb_time value to the prepared statement at the specified index syntax duckdb_bind_timestamp binds a duckdb_timestamp value to the prepared statement at the specified index syntax duckdb_bind_interval binds a duckdb_interval value to the prepared statement at the specified index syntax duckdb_bind_varchar binds a null-terminated varchar value to the prepared statement at the specified index syntax duckdb_bind_varchar_length binds a varchar value to the prepared statement at the specified index syntax duckdb_bind_blob binds a blob value to the prepared statement at the specified index syntax duckdb_bind_null binds a null value to the prepared statement at the specified index syntax duckdb_execute_prepared executes the prepared statement with the given bound parameters and returns a materialized query result this method can be called multiple times for each prepared statement and the parameters can be modified between calls to this function syntax the prepared statement to execute out_result the query result returns duckdbsuccess on success or duckdberror on failure duckdb_execute_prepared_arrow executes the prepared statement with the given bound parameters and returns an arrow query result syntax the prepared statement to execute out_result the query result returns duckdbsuccess on success or duckdberror on failure duckdb_arrow_scan scans the arrow stream and creates a view with the given name syntax the connection on which to execute the scan table_name name of the temporary view to create arrow arrow stream wrapper returns duckdbsuccess on success or duckdberror on failure duckdb_arrow_array_scan scans the arrow array and creates a view with the given name syntax the connection on which to execute the scan table_name name of the temporary view to create arrow_schema arrow schema wrapper arrow_array arrow array wrapper out_stream output array stream that wraps around the passed schema for releasing deleting once done returns duckdbsuccess on success or duckdberror on failure duckdb_extract_statements extract all statements from a query note that after calling duckdb_extract_statements the extracted statements should always be destroyed using duckdb_destroy_extracted even if no statements were extracted if the extract fails duckdb_extract_statements_error can be called to obtain the reason why the extract failed syntax the connection object query the sql query to extract out_extracted_statements the resulting extracted statements object returns the number of extracted statements or 0 on failure duckdb_prepare_extracted_statement prepare an extracted statement note that after calling duckdb_prepare_extracted_statement the prepared statement should always be destroyed using duckdb_destroy_prepare even if the prepare fails if the prepare fails duckdb_prepare_error can be called to obtain the reason why the prepare failed syntax the connection object extracted_statements the extracted statements object index the index of the extracted statement to prepare out_prepared_statement the resulting prepared statement object returns duckdbsuccess on success or duckdberror on failure duckdb_extract_statements_error returns the error message contained within the extracted statements the result of this function must not be freed it will be cleaned up when duckdb_destroy_extracted is called syntax the extracted statements to fetch the error from returns the error of the extracted statements duckdb_destroy_extracted de-allocates all memory allocated for the extracted statements syntax the extracted statements to destroy duckdb_pending_prepared executes the prepared statement with the given bound parameters and returns a pending result the pending result represents an intermediate structure for a query that is not yet fully executed the pending result can be used to incrementally execute a query returning control to the client between tasks note that after calling duckdb_pending_prepared the pending result should always be destroyed using duckdb_destroy_pending even if this function returns duckdberror syntax the prepared statement to execute out_result the pending query result returns duckdbsuccess on success or duckdberror on failure duckdb_pending_prepared_streaming executes the prepared statement with the given bound parameters and returns a pending result this pending result will create a streaming duckdb_result when executed the pending result represents an intermediate structure for a query that is not yet fully executed note that after calling duckdb_pending_prepared_streaming the pending result should always be destroyed using duckdb_destroy_pending even if this function returns duckdberror syntax the prepared statement to execute out_result the pending query result returns duckdbsuccess on success or duckdberror on failure duckdb_destroy_pending closes the pending result and de-allocates all memory allocated for the result syntax the pending result to destroy duckdb_pending_error returns the error message contained within the pending result the result of this function must not be freed it will be cleaned up when duckdb_destroy_pending is called syntax the pending result to fetch the error from returns the error of the pending result duckdb_pending_execute_task executes a single task within the query returning whether or not the query is ready if this returns duckdb_pending_result_ready the duckdb_execute_pending function can be called to obtain the result if this returns duckdb_pending_result_not_ready the duckdb_pending_execute_task function should be called again if this returns duckdb_pending_error an error occurred during execution the error message can be obtained by calling duckdb_pending_error on the pending_result syntax the pending result to execute a task within returns the state of the pending result after the execution duckdb_execute_pending fully execute a pending query result returning the final query result if duckdb_pending_execute_task has been called until duckdb_pending_result_ready was returned this will return fast otherwise all remaining tasks must be executed first syntax the pending result to execute out_result the result object returns duckdbsuccess on success or duckdberror on failure duckdb_pending_execution_is_finished returns whether a duckdb_pending_state is finished executing for example if pending_state is duckdb_pending_result_ready this function will return true syntax the pending state on which to decide whether to finish execution returns boolean indicating pending execution should be considered finished duckdb_destroy_value destroys the value and de-allocates all memory allocated for that type syntax the value to destroy duckdb_create_varchar creates a value from a null-terminated string syntax the null-terminated string returns the value this must be destroyed with duckdb_destroy_value duckdb_create_varchar_length creates a value from a string syntax the text length the length of the text returns the value this must be destroyed with duckdb_destroy_value duckdb_create_int64 creates a value from an int64 syntax the bigint value returns the value this must be destroyed with duckdb_destroy_value duckdb_get_varchar obtains a string representation of the given value the result must be destroyed with duckdb_free syntax the value returns the string value this must be destroyed with duckdb_free duckdb_get_int64 obtains an int64 of the given value syntax the value returns the int64 value or 0 if no conversion is possible duckdb_create_logical_type creates a duckdb_logical_type from a standard primitive type the resulting type should be destroyed with duckdb_destroy_logical_type this should not be used with duckdb_type_decimal syntax the primitive type to create returns the logical type duckdb_create_list_type creates a list type from its child type the resulting type should be destroyed with duckdb_destroy_logical_type syntax the child type of list type to create returns the logical type duckdb_create_map_type creates a map type from its key type and value type the resulting type should be destroyed with duckdb_destroy_logical_type syntax the key type and value type of map type to create returns the logical type duckdb_create_union_type creates a union type from the passed types array the resulting type should be destroyed with duckdb_destroy_logical_type syntax the array of types that the union should consist of type_amount the size of the types array returns the logical type duckdb_create_decimal_type creates a duckdb_logical_type of type decimal with the specified width and scale the resulting type should be destroyed with duckdb_destroy_logical_type syntax the width of the decimal type scale the scale of the decimal type returns the logical type duckdb_get_type_id retrieves the type class of a duckdb_logical_type syntax the logical type object returns the type id duckdb_decimal_width retrieves the width of a decimal type syntax the logical type object returns the width of the decimal type duckdb_decimal_scale retrieves the scale of a decimal type syntax the logical type object returns the scale of the decimal type duckdb_decimal_internal_type retrieves the internal storage type of a decimal type syntax the logical type object returns the internal type of the decimal type duckdb_enum_internal_type retrieves the internal storage type of an enum type syntax the logical type object returns the internal type of the enum type duckdb_enum_dictionary_size retrieves the dictionary size of the enum type syntax the logical type object returns the dictionary size of the enum type duckdb_enum_dictionary_value retrieves the dictionary value at the specified position from the enum the result must be freed with duckdb_free syntax the logical type object index the index in the dictionary returns the string value of the enum type must be freed with duckdb_free duckdb_list_type_child_type retrieves the child type of the given list type the result must be freed with duckdb_destroy_logical_type syntax the logical type object returns the child type of the list type must be destroyed with duckdb_destroy_logical_type duckdb_map_type_key_type retrieves the key type of the given map type the result must be freed with duckdb_destroy_logical_type syntax the logical type object returns the key type of the map type must be destroyed with duckdb_destroy_logical_type duckdb_map_type_value_type retrieves the value type of the given map type the result must be freed with duckdb_destroy_logical_type syntax the logical type object returns the value type of the map type must be destroyed with duckdb_destroy_logical_type duckdb_struct_type_child_count returns the number of children of a struct type syntax the logical type object returns the number of children of a struct type duckdb_struct_type_child_name retrieves the name of the struct child the result must be freed with duckdb_free syntax the logical type object index the child index returns the name of the struct type must be freed with duckdb_free duckdb_struct_type_child_type retrieves the child type of the given struct type at the specified index the result must be freed with duckdb_destroy_logical_type syntax the logical type object index the child index returns the child type of the struct type must be destroyed with duckdb_destroy_logical_type duckdb_union_type_member_count returns the number of members that the union type has syntax the logical type union object returns the number of members of a union type duckdb_union_type_member_name retrieves the name of the union member the result must be freed with duckdb_free syntax the logical type object index the child index returns the name of the union member must be freed with duckdb_free duckdb_union_type_member_type retrieves the child type of the given union member at the specified index the result must be freed with duckdb_destroy_logical_type syntax the logical type object index the child index returns the child type of the union member must be destroyed with duckdb_destroy_logical_type duckdb_destroy_logical_type destroys the logical type and de-allocates all memory allocated for that type syntax the logical type to destroy duckdb_create_data_chunk creates an empty datachunk with the specified set of types syntax an array of types of the data chunk column_count the number of columns returns the data chunk duckdb_destroy_data_chunk destroys the data chunk and de-allocates all memory allocated for that chunk syntax the data chunk to destroy duckdb_data_chunk_reset resets a data chunk clearing the validity masks and setting the cardinality of the data chunk to 0 syntax the data chunk to reset duckdb_data_chunk_get_column_count retrieves the number of columns in a data chunk syntax the data chunk to get the data from returns the number of columns in the data chunk duckdb_data_chunk_get_vector retrieves the vector at the specified column index in the data chunk the pointer to the vector is valid for as long as the chunk is alive it does not need to be destroyed syntax the data chunk to get the data from returns the vector duckdb_data_chunk_get_size retrieves the current number of tuples in a data chunk syntax the data chunk to get the data from returns the number of tuples in the data chunk duckdb_data_chunk_set_size sets the current number of tuples in a data chunk syntax the data chunk to set the size in size the number of tuples in the data chunk duckdb_vector_get_column_type retrieves the column type of the specified vector the result must be destroyed with duckdb_destroy_logical_type syntax the vector get the data from returns the type of the vector duckdb_vector_get_data retrieves the data pointer of the vector the data pointer can be used to read or write values from the vector how to read or write values depends on the type of the vector syntax the vector to get the data from returns the data pointer duckdb_vector_get_validity retrieves the validity mask pointer of the specified vector if all values are valid this function might return null the validity mask is a bitset that signifies null-ness within the data chunk it is a series of uint64_t values where each uint64_t value contains validity for 64 tuples the bit is set to 1 if the value is valid i e not null or 0 if the value is invalid i e null validity of a specific value can be obtained like this idx_t entry_idx row_idx 64 idx_t idx_in_entry row_idx 64 bool is_valid validity_mask entry_idx 1 idx_in_entry alternatively the slower duckdb_validity_row_is_valid function can be used syntax the vector to get the data from returns the pointer to the validity mask or null if no validity mask is present duckdb_vector_ensure_validity_writable ensures the validity mask is writable by allocating it after this function is called duckdb_vector_get_validity will always return non-null this allows null values to be written to the vector regardless of whether a validity mask was present before syntax the vector to alter duckdb_vector_assign_string_element assigns a string element in the vector at the specified location syntax the vector to alter index the row position in the vector to assign the string to str the null-terminated string duckdb_vector_assign_string_element_len assigns a string element in the vector at the specified location syntax the vector to alter index the row position in the vector to assign the string to str the string str_len the length of the string in bytes duckdb_list_vector_get_child retrieves the child vector of a list vector the resulting vector is valid as long as the parent vector is valid syntax the vector returns the child vector duckdb_list_vector_get_size returns the size of the child vector of the list syntax the vector returns the size of the child list duckdb_list_vector_set_size sets the total size of the underlying child-vector of a list vector syntax the list vector size the size of the child list returns the duckdb state returns duckdberror if the vector is nullptr duckdb_list_vector_reserve sets the total capacity of the underlying child-vector of a list syntax the list vector required_capacity the total capacity to reserve return the duckdb state returns duckdberror if the vector is nullptr duckdb_struct_vector_get_child retrieves the child vector of a struct vector the resulting vector is valid as long as the parent vector is valid syntax the vector index the child index returns the child vector duckdb_validity_row_is_valid returns whether or not a row is valid i e not null in the given validity mask syntax the validity mask as obtained through duckdb_data_chunk_get_validity row the row index returns true if the row is valid false otherwise duckdb_validity_set_row_validity in a validity mask sets a specific row to either valid or invalid note that duckdb_data_chunk_ensure_validity_writable should be called before calling duckdb_data_chunk_get_validity to ensure that there is a validity mask to write to syntax the validity mask as obtained through duckdb_data_chunk_get_validity row the row index valid whether or not to set the row to valid or invalid duckdb_validity_set_row_invalid in a validity mask sets a specific row to invalid equivalent to duckdb_validity_set_row_validity with valid set to false syntax the validity mask row the row index duckdb_validity_set_row_valid in a validity mask sets a specific row to valid equivalent to duckdb_validity_set_row_validity with valid set to true syntax the validity mask row the row index duckdb_create_table_function creates a new empty table function the return value should be destroyed with duckdb_destroy_table_function syntax the table function object duckdb_destroy_table_function destroys the given table function object syntax the table function to destroy duckdb_table_function_set_name sets the name of the given table function syntax the table function name the name of the table function duckdb_table_function_add_parameter adds a parameter to the table function syntax 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 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 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 the table function bind the bind function duckdb_table_function_set_init sets the init function of the table function syntax the table function init the init function duckdb_table_function_set_local_init sets the thread-local init function of the table function syntax the table function init the init function duckdb_table_function_set_function sets the main function of the table function syntax 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 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 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 the info object returns the extra info duckdb_bind_add_result_column adds a result column to the output of the table function syntax 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 the info object returns the init data object duckdb_function_set_error report that an error has occurred while executing the function syntax the info object error the error message duckdb_add_replacement_scan add a replacement scan definition to the specified database syntax the database object to add the replacement scan to replacement the replacement scan callback extra_data extra data that is passed back into the specified callback delete_callback the delete callback to call on the extra data if any duckdb_replacement_scan_set_function_name sets the replacement function name to use if this function is called in the replacement callback the replacement scan is performed if it is not called the replacement callback is not performed syntax the info object function_name the function name to substitute duckdb_replacement_scan_add_parameter adds a parameter to the replacement scan function syntax the info object parameter the parameter to add duckdb_replacement_scan_set_error report that an error has occurred while executing the replacement scan syntax the info object error the error message duckdb_appender_create creates an appender object syntax the connection context to create the appender in schema the schema of the table to append to or nullptr for the default schema table the table name to append to out_appender the resulting appender object returns duckdbsuccess on success or duckdberror on failure duckdb_appender_error returns the error message associated with the given appender if the appender has no error message this returns nullptr instead the error message should not be freed it will be de-allocated when duckdb_appender_destroy is called syntax the appender to get the error from returns the error message or nullptr if there is none duckdb_appender_flush flush the appender to the table forcing the cache of the appender to be cleared and the data to be appended to the base table this should generally not be used unless you know what you are doing instead call duckdb_appender_destroy when you are done with the appender syntax the appender to flush returns duckdbsuccess on success or duckdberror on failure duckdb_appender_close close the appender flushing all intermediate state in the appender to the table and closing it for further appends this is generally not necessary call duckdb_appender_destroy instead syntax the appender to flush and close returns duckdbsuccess on success or duckdberror on failure duckdb_appender_destroy close the appender and destroy it flushing all intermediate state in the appender to the table and de-allocating all memory associated with the appender syntax the appender to flush close and destroy returns duckdbsuccess on success or duckdberror on failure duckdb_appender_begin_row a nop function provided for backwards compatibility reasons does nothing only duckdb_appender_end_row is required syntax duckdb_appender_end_row finish the current row of appends after end_row is called the next row can be appended syntax the appender returns duckdbsuccess on success or duckdberror on failure duckdb_append_bool append a bool value to the appender syntax duckdb_append_int8 append an int8_t value to the appender syntax duckdb_append_int16 append an int16_t value to the appender syntax duckdb_append_int32 append an int32_t value to the appender syntax duckdb_append_int64 append an int64_t value to the appender syntax duckdb_append_hugeint append a duckdb_hugeint value to the appender syntax duckdb_append_uint8 append a uint8_t value to the appender syntax duckdb_append_uint16 append a uint16_t value to the appender syntax duckdb_append_uint32 append a uint32_t value to the appender syntax duckdb_append_uint64 append a uint64_t value to the appender syntax duckdb_append_float append a float value to the appender syntax duckdb_append_double append a double value to the appender syntax duckdb_append_date append a duckdb_date value to the appender syntax duckdb_append_time append a duckdb_time value to the appender syntax duckdb_append_timestamp append a duckdb_timestamp value to the appender syntax duckdb_append_interval append a duckdb_interval value to the appender syntax duckdb_append_varchar append a varchar value to the appender syntax duckdb_append_varchar_length append a varchar value to the appender syntax duckdb_append_blob append a blob value to the appender syntax duckdb_append_null append a null value to the appender of any type syntax duckdb_append_data_chunk appends a pre-filled data chunk to the specified appender the types of the data chunk must exactly match the types of the table no casting is performed if the types do not match or the appender is in an invalid state duckdberror is returned if the append is successful duckdbsuccess is returned syntax the appender to append to chunk the data chunk to append returns the return state duckdb_query_arrow executes a sql query within a connection and stores the full materialized result in an arrow structure if the query fails to execute duckdberror is returned and the error message can be retrieved by calling duckdb_query_arrow_error note that after running duckdb_query_arrow duckdb_destroy_arrow must be called on the result object even if the query fails otherwise the error stored within the result will not be freed correctly syntax the connection to perform the query in query the sql query to run out_result the query result returns duckdbsuccess on success or duckdberror on failure duckdb_query_arrow_schema fetch the internal arrow schema from the arrow result syntax the result to fetch the schema from out_schema the output schema returns duckdbsuccess on success or duckdberror on failure duckdb_prepared_arrow_schema fetch the internal arrow schema from the prepared statement syntax the prepared statement to fetch the schema from out_schema the output schema returns duckdbsuccess on success or duckdberror on failure duckdb_query_arrow_array fetch an internal arrow array from the arrow result this function can be called multiple time to get next chunks which will free the previous out_array so consume the out_array before calling this function again syntax the result to fetch the array from out_array the output array returns duckdbsuccess on success or duckdberror on failure duckdb_arrow_column_count returns the number of columns present in a the arrow result object syntax the result object returns the number of columns present in the result object duckdb_arrow_row_count returns the number of rows present in a the arrow result object syntax the result object returns the number of rows present in the result object duckdb_arrow_rows_changed returns the number of rows changed by the query stored in the arrow result this is relevant only for insert update delete queries for other queries the rows_changed will be 0 syntax the result object returns the number of rows changed duckdb_query_arrow_error returns the error message contained within the result the error is only set if duckdb_query_arrow returns duckdberror the error message should not be freed it will be de-allocated when duckdb_destroy_arrow is called syntax the result object to fetch the nullmask from returns the error of the result duckdb_destroy_arrow closes the result and de-allocates all memory allocated for the arrow result syntax the result to destroy duckdb_execute_tasks execute duckdb tasks on this thread will return after max_tasks have been executed or if there are no more tasks present syntax the database object to execute tasks for max_tasks the maximum amount of tasks to execute duckdb_create_task_state creates a task state that can be used with duckdb_execute_tasks_state to execute tasks until duckdb_finish_execution is called on the state duckdb_destroy_state should be called on the result in order to free memory syntax the database object to create the task state for returns the task state that can be used with duckdb_execute_tasks_state duckdb_execute_tasks_state execute duckdb tasks on this thread the thread will keep on executing tasks forever until duckdb_finish_execution is called on the state multiple threads can share the same duckdb_task_state syntax the task state of the executor duckdb_execute_n_tasks_state execute duckdb tasks on this thread the thread will keep on executing tasks until either duckdb_finish_execution is called on the state max_tasks tasks have been executed or there are no more tasks to be executed multiple threads can share the same duckdb_task_state syntax the task state of the executor max_tasks the maximum amount of tasks to execute returns the amount of tasks that have actually been executed duckdb_finish_execution finish execution on a specific task syntax the task state to finish execution duckdb_task_state_is_finished check if the provided duckdb_task_state has finished execution syntax the task state to inspect returns whether or not duckdb_finish_execution has been called on the task state duckdb_destroy_task_state destroys the task state returned from duckdb_create_task_state note that this should not be called while there is an active duckdb_execute_tasks_state running on the task state syntax the task state to clean up duckdb_execution_is_finished returns true if execution of the current query is finished syntax the connection on which to check duckdb_stream_fetch_chunk fetches a data chunk from the streaming duckdb_result this function should be called repeatedly until the result is exhausted the result must be destroyed with duckdb_destroy_data_chunk this function can only be used on duckdb_results created with duckdb_pending_prepared_streaming if this function is used none of the other result functions can be used and vice versa i e this function cannot be mixed with the legacy result functions or the materialized result functions it is not known beforehand how many chunks will be returned by this result syntax the result object to fetch the data chunk from returns the resulting data chunk returns null if the result has an error", + "text": "api reference open connect syntax path to the database file on disk or nullptr or memory to open an in-memory database out_database the result database object returns duckdbsuccess on success or duckdberror on failure duckdb_open_ext extended version of duckdb_open creates a new database or opens an existing database file stored at the the given path syntax path to the database file on disk or nullptr or memory to open an in-memory database out_database the result database object config optional configuration used to start up the database system out_error if set and the function returns duckdberror this will contain the reason why the start-up failed note that the error must be freed using duckdb_free returns duckdbsuccess on success or duckdberror on failure duckdb_close closes the specified database and de-allocates all memory allocated for that database this should be called after you are done with any database allocated through duckdb_open note that failing to call duckdb_close in case of e g a program crash will not cause data corruption still it is recommended to always correctly close a database object after you are done with it syntax the database object to shut down duckdb_connect opens a connection to a database connections are required to query the database and store transactional state associated with the connection the instantiated connection should be closed using duckdb_disconnect syntax the database file to connect to out_connection the result connection object returns duckdbsuccess on success or duckdberror on failure duckdb_interrupt interrupt running query syntax the connection to interruot duckdb_query_progress get progress of the running query syntax the working connection returns -1 if no progress or a percentage of the progress duckdb_disconnect closes the specified connection and de-allocates all memory allocated for that connection syntax the connection to close duckdb_library_version returns the version of the linked duckdb with a version postfix for dev versions usually used for developing c extensions that must return this for a compatibility check syntax duckdb_create_config initializes an empty configuration object that can be used to provide start-up options for the duckdb instance through duckdb_open_ext this will always succeed unless there is a malloc failure syntax the result configuration object returns duckdbsuccess on success or duckdberror on failure duckdb_config_count this returns the total amount of configuration options available for usage with duckdb_get_config_flag this should not be called in a loop as it internally loops over all the options syntax the amount of config options available duckdb_get_config_flag obtains a human-readable name and description of a specific configuration option this can be used to e g display configuration options this will succeed unless index is out of range i e duckdb_config_count the result name or description must not be freed syntax the index of the configuration option between 0 and duckdb_config_count out_name a name of the configuration flag out_description a description of the configuration flag returns duckdbsuccess on success or duckdberror on failure duckdb_set_config sets the specified option for the specified configuration the configuration option is indicated by name to obtain a list of config options see duckdb_get_config_flag in the source code configuration options are defined in config cpp this can fail if either the name is invalid or if the value provided for the option is invalid syntax the configuration object to set the option on name the name of the configuration flag to set option the value to set the configuration flag to returns duckdbsuccess on success or duckdberror on failure duckdb_destroy_config destroys the specified configuration option and de-allocates all memory allocated for the object syntax the configuration object to destroy duckdb_query executes a sql query within a connection and stores the full materialized result in the out_result pointer if the query fails to execute duckdberror is returned and the error message can be retrieved by calling duckdb_result_error note that after running duckdb_query duckdb_destroy_result must be called on the result object even if the query fails otherwise the error stored within the result will not be freed correctly syntax the connection to perform the query in query the sql query to run out_result the query result returns duckdbsuccess on success or duckdberror on failure duckdb_destroy_result closes the result and de-allocates all memory allocated for that connection syntax the result to destroy duckdb_column_name returns the column name of the specified column the result should not need be freed the column names will automatically be destroyed when the result is destroyed returns null if the column is out of range syntax the result object to fetch the column name from col the column index returns the column name of the specified column duckdb_column_type returns the column type of the specified column returns duckdb_type_invalid if the column is out of range syntax the result object to fetch the column type from col the column index returns the column type of the specified column duckdb_column_logical_type returns the logical column type of the specified column the return type of this call should be destroyed with duckdb_destroy_logical_type returns null if the column is out of range syntax the result object to fetch the column type from col the column index returns the logical column type of the specified column duckdb_column_count returns the number of columns present in a the result object syntax the result object returns the number of columns present in the result object duckdb_row_count returns the number of rows present in a the result object syntax the result object returns the number of rows present in the result object duckdb_rows_changed returns the number of rows changed by the query stored in the result this is relevant only for insert update delete queries for other queries the rows_changed will be 0 syntax the result object returns the number of rows changed duckdb_column_data deprecated prefer using duckdb_result_get_chunk instead returns the data of a specific column of a result in columnar format the function returns a dense array which contains the result data the exact type stored in the array depends on the corresponding duckdb_type as provided by duckdb_column_type for the exact type by which the data should be accessed see the comments in the types section or the duckdb_type enum for example for a column of type duckdb_type_integer rows can be accessed in the following manner int32_t data int32_t duckdb_column_data result 0 printf data for row d d n row data row syntax the result object to fetch the column data from col the column index returns the column data of the specified column duckdb_nullmask_data deprecated prefer using duckdb_result_get_chunk instead returns the nullmask of a specific column of a result in columnar format the nullmask indicates for every row whether or not the corresponding row is null if a row is null the values present in the array provided by duckdb_column_data are undefined int32_t data int32_t duckdb_column_data result 0 bool nullmask duckdb_nullmask_data result 0 if nullmask row printf data for row d null n row else printf data for row d d n row data row syntax the result object to fetch the nullmask from col the column index returns the nullmask of the specified column duckdb_result_error returns the error message contained within the result the error is only set if duckdb_query returns duckdberror the result of this function must not be freed it will be cleaned up when duckdb_destroy_result is called syntax the result object to fetch the error from returns the error of the result duckdb_result_get_chunk fetches a data chunk from the duckdb_result this function should be called repeatedly until the result is exhausted the result must be destroyed with duckdb_destroy_data_chunk this function supersedes all duckdb_value functions as well as the duckdb_column_data and duckdb_nullmask_data functions it results in significantly better performance and should be preferred in newer code-bases if this function is used none of the other result functions can be used and vice versa i e this function cannot be mixed with the legacy result functions use duckdb_result_chunk_count to figure out how many chunks there are in the result syntax the result object to fetch the data chunk from chunk_index the chunk index to fetch from returns the resulting data chunk returns null if the chunk index is out of bounds duckdb_result_is_streaming checks if the type of the internal result is streamqueryresult syntax the result object to check returns whether or not the result object is of the type streamqueryresult duckdb_result_chunk_count returns the number of data chunks present in the result syntax the result object returns number of data chunks present in the result duckdb_value_boolean syntax the boolean value at the specified location or false if the value cannot be converted duckdb_value_int8 syntax the int8_t value at the specified location or 0 if the value cannot be converted duckdb_value_int16 syntax the int16_t value at the specified location or 0 if the value cannot be converted duckdb_value_int32 syntax the int32_t value at the specified location or 0 if the value cannot be converted duckdb_value_int64 syntax the int64_t value at the specified location or 0 if the value cannot be converted duckdb_value_hugeint syntax the duckdb_hugeint value at the specified location or 0 if the value cannot be converted duckdb_value_decimal syntax the duckdb_decimal value at the specified location or 0 if the value cannot be converted duckdb_value_uint8 syntax the uint8_t value at the specified location or 0 if the value cannot be converted duckdb_value_uint16 syntax the uint16_t value at the specified location or 0 if the value cannot be converted duckdb_value_uint32 syntax the uint32_t value at the specified location or 0 if the value cannot be converted duckdb_value_uint64 syntax the uint64_t value at the specified location or 0 if the value cannot be converted duckdb_value_float syntax the float value at the specified location or 0 if the value cannot be converted duckdb_value_double syntax the double value at the specified location or 0 if the value cannot be converted duckdb_value_date syntax the duckdb_date value at the specified location or 0 if the value cannot be converted duckdb_value_time syntax the duckdb_time value at the specified location or 0 if the value cannot be converted duckdb_value_timestamp syntax the duckdb_timestamp value at the specified location or 0 if the value cannot be converted duckdb_value_interval syntax the duckdb_interval value at the specified location or 0 if the value cannot be converted duckdb_value_varchar syntax use duckdb_value_string instead this function does not work correctly if the string contains null bytes returns the text value at the specified location as a null-terminated string or nullptr if the value cannot be converted the result must be freed with duckdb_free duckdb_value_varchar_internal syntax use duckdb_value_string_internal instead this function does not work correctly if the string contains null bytes returns the char value at the specified location only works on varchar columns and does not auto-cast if the column is not a varchar column this function will return null the result must not be freed duckdb_value_string_internal syntax use duckdb_value_string_internal instead this function does not work correctly if the string contains null bytes returns the char value at the specified location only works on varchar columns and does not auto-cast if the column is not a varchar column this function will return null the result must not be freed duckdb_value_blob syntax the duckdb_blob value at the specified location returns a blob with blob data set to nullptr if the value cannot be converted the resulting blob data must be freed with duckdb_free duckdb_value_is_null syntax returns true if the value at the specified index is null and false otherwise duckdb_malloc allocate size bytes of memory using the duckdb internal malloc function any memory allocated in this manner should be freed using duckdb_free syntax the number of bytes to allocate returns a pointer to the allocated memory region duckdb_free free a value returned from duckdb_malloc duckdb_value_varchar or duckdb_value_blob syntax the memory region to de-allocate duckdb_vector_size the internal vector size used by duckdb this is the amount of tuples that will fit into a data chunk created by duckdb_create_data_chunk syntax the vector size duckdb_string_is_inlined whether or not the duckdb_string_t value is inlined this means that the data of the string does not have a separate allocation syntax duckdb_from_date decompose a duckdb_date object into year month and date stored as duckdb_date_struct syntax the date object as obtained from a duckdb_type_date column returns the duckdb_date_struct with the decomposed elements duckdb_to_date re-compose a duckdb_date from year month and date duckdb_date_struct syntax the year month and date stored in a duckdb_date_struct returns the duckdb_date element duckdb_from_time decompose a duckdb_time object into hour minute second and microsecond stored as duckdb_time_struct syntax the time object as obtained from a duckdb_type_time column returns the duckdb_time_struct with the decomposed elements duckdb_to_time re-compose a duckdb_time from hour minute second and microsecond duckdb_time_struct syntax the hour minute second and microsecond in a duckdb_time_struct returns the duckdb_time element duckdb_from_timestamp decompose a duckdb_timestamp object into a duckdb_timestamp_struct syntax the ts object as obtained from a duckdb_type_timestamp column returns the duckdb_timestamp_struct with the decomposed elements duckdb_to_timestamp re-compose a duckdb_timestamp from a duckdb_timestamp_struct syntax the de-composed elements in a duckdb_timestamp_struct returns the duckdb_timestamp element duckdb_hugeint_to_double converts a duckdb_hugeint object as obtained from a duckdb_type_hugeint column into a double syntax the hugeint value returns the converted double element duckdb_double_to_hugeint converts a double value to a duckdb_hugeint object if the conversion fails because the double value is too big the result will be 0 syntax the double value returns the converted duckdb_hugeint element duckdb_double_to_decimal converts a double value to a duckdb_decimal object if the conversion fails because the double value is too big or the width scale are invalid the result will be 0 syntax the double value returns the converted duckdb_decimal element duckdb_decimal_to_double converts a duckdb_decimal object as obtained from a duckdb_type_decimal column into a double syntax the decimal value returns the converted double element duckdb_prepare create a prepared statement object from a query note that after calling duckdb_prepare the prepared statement should always be destroyed using duckdb_destroy_prepare even if the prepare fails if the prepare fails duckdb_prepare_error can be called to obtain the reason why the prepare failed syntax the connection object query the sql query to prepare out_prepared_statement the resulting prepared statement object returns duckdbsuccess on success or duckdberror on failure duckdb_destroy_prepare closes the prepared statement and de-allocates all memory allocated for the statement syntax the prepared statement to destroy duckdb_prepare_error returns the error message associated with the given prepared statement if the prepared statement has no error message this returns nullptr instead the error message should not be freed it will be de-allocated when duckdb_destroy_prepare is called syntax the prepared statement to obtain the error from returns the error message or nullptr if there is none duckdb_nparams returns the number of parameters that can be provided to the given prepared statement returns 0 if the query was not successfully prepared syntax the prepared statement to obtain the number of parameters for duckdb_param_type returns the parameter type for the parameter at the given index returns duckdb_type_invalid if the parameter index is out of range or the statement was not successfully prepared syntax the prepared statement param_idx the parameter index returns the parameter type duckdb_clear_bindings clear the params bind to the prepared statement syntax duckdb_bind_value binds a value to the prepared statement at the specified index syntax duckdb_bind_parameter_index retrieve the index of the parameter for the prepared statement identified by name syntax duckdb_bind_boolean binds a bool value to the prepared statement at the specified index syntax duckdb_bind_int8 binds an int8_t value to the prepared statement at the specified index syntax duckdb_bind_int16 binds an int16_t value to the prepared statement at the specified index syntax duckdb_bind_int32 binds an int32_t value to the prepared statement at the specified index syntax duckdb_bind_int64 binds an int64_t value to the prepared statement at the specified index syntax duckdb_bind_hugeint binds an duckdb_hugeint value to the prepared statement at the specified index syntax duckdb_bind_decimal binds a duckdb_decimal value to the prepared statement at the specified index syntax duckdb_bind_uint8 binds an uint8_t value to the prepared statement at the specified index syntax duckdb_bind_uint16 binds an uint16_t value to the prepared statement at the specified index syntax duckdb_bind_uint32 binds an uint32_t value to the prepared statement at the specified index syntax duckdb_bind_uint64 binds an uint64_t value to the prepared statement at the specified index syntax duckdb_bind_float binds an float value to the prepared statement at the specified index syntax duckdb_bind_double binds an double value to the prepared statement at the specified index syntax duckdb_bind_date binds a duckdb_date value to the prepared statement at the specified index syntax duckdb_bind_time binds a duckdb_time value to the prepared statement at the specified index syntax duckdb_bind_timestamp binds a duckdb_timestamp value to the prepared statement at the specified index syntax duckdb_bind_interval binds a duckdb_interval value to the prepared statement at the specified index syntax duckdb_bind_varchar binds a null-terminated varchar value to the prepared statement at the specified index syntax duckdb_bind_varchar_length binds a varchar value to the prepared statement at the specified index syntax duckdb_bind_blob binds a blob value to the prepared statement at the specified index syntax duckdb_bind_null binds a null value to the prepared statement at the specified index syntax duckdb_execute_prepared executes the prepared statement with the given bound parameters and returns a materialized query result this method can be called multiple times for each prepared statement and the parameters can be modified between calls to this function syntax the prepared statement to execute out_result the query result returns duckdbsuccess on success or duckdberror on failure duckdb_execute_prepared_arrow executes the prepared statement with the given bound parameters and returns an arrow query result syntax the prepared statement to execute out_result the query result returns duckdbsuccess on success or duckdberror on failure duckdb_arrow_scan scans the arrow stream and creates a view with the given name syntax the connection on which to execute the scan table_name name of the temporary view to create arrow arrow stream wrapper returns duckdbsuccess on success or duckdberror on failure duckdb_arrow_array_scan scans the arrow array and creates a view with the given name syntax the connection on which to execute the scan table_name name of the temporary view to create arrow_schema arrow schema wrapper arrow_array arrow array wrapper out_stream output array stream that wraps around the passed schema for releasing deleting once done returns duckdbsuccess on success or duckdberror on failure duckdb_extract_statements extract all statements from a query note that after calling duckdb_extract_statements the extracted statements should always be destroyed using duckdb_destroy_extracted even if no statements were extracted if the extract fails duckdb_extract_statements_error can be called to obtain the reason why the extract failed syntax the connection object query the sql query to extract out_extracted_statements the resulting extracted statements object returns the number of extracted statements or 0 on failure duckdb_prepare_extracted_statement prepare an extracted statement note that after calling duckdb_prepare_extracted_statement the prepared statement should always be destroyed using duckdb_destroy_prepare even if the prepare fails if the prepare fails duckdb_prepare_error can be called to obtain the reason why the prepare failed syntax the connection object extracted_statements the extracted statements object index the index of the extracted statement to prepare out_prepared_statement the resulting prepared statement object returns duckdbsuccess on success or duckdberror on failure duckdb_extract_statements_error returns the error message contained within the extracted statements the result of this function must not be freed it will be cleaned up when duckdb_destroy_extracted is called syntax the extracted statements to fetch the error from returns the error of the extracted statements duckdb_destroy_extracted de-allocates all memory allocated for the extracted statements syntax the extracted statements to destroy duckdb_pending_prepared executes the prepared statement with the given bound parameters and returns a pending result the pending result represents an intermediate structure for a query that is not yet fully executed the pending result can be used to incrementally execute a query returning control to the client between tasks note that after calling duckdb_pending_prepared the pending result should always be destroyed using duckdb_destroy_pending even if this function returns duckdberror syntax the prepared statement to execute out_result the pending query result returns duckdbsuccess on success or duckdberror on failure duckdb_pending_prepared_streaming executes the prepared statement with the given bound parameters and returns a pending result this pending result will create a streaming duckdb_result when executed the pending result represents an intermediate structure for a query that is not yet fully executed note that after calling duckdb_pending_prepared_streaming the pending result should always be destroyed using duckdb_destroy_pending even if this function returns duckdberror syntax the prepared statement to execute out_result the pending query result returns duckdbsuccess on success or duckdberror on failure duckdb_destroy_pending closes the pending result and de-allocates all memory allocated for the result syntax the pending result to destroy duckdb_pending_error returns the error message contained within the pending result the result of this function must not be freed it will be cleaned up when duckdb_destroy_pending is called syntax the pending result to fetch the error from returns the error of the pending result duckdb_pending_execute_task executes a single task within the query returning whether or not the query is ready if this returns duckdb_pending_result_ready the duckdb_execute_pending function can be called to obtain the result if this returns duckdb_pending_result_not_ready the duckdb_pending_execute_task function should be called again if this returns duckdb_pending_error an error occurred during execution the error message can be obtained by calling duckdb_pending_error on the pending_result syntax the pending result to execute a task within returns the state of the pending result after the execution duckdb_execute_pending fully execute a pending query result returning the final query result if duckdb_pending_execute_task has been called until duckdb_pending_result_ready was returned this will return fast otherwise all remaining tasks must be executed first syntax the pending result to execute out_result the result object returns duckdbsuccess on success or duckdberror on failure duckdb_pending_execution_is_finished returns whether a duckdb_pending_state is finished executing for example if pending_state is duckdb_pending_result_ready this function will return true syntax the pending state on which to decide whether to finish execution returns boolean indicating pending execution should be considered finished duckdb_destroy_value destroys the value and de-allocates all memory allocated for that type syntax the value to destroy duckdb_create_varchar creates a value from a null-terminated string syntax the null-terminated string returns the value this must be destroyed with duckdb_destroy_value duckdb_create_varchar_length creates a value from a string syntax the text length the length of the text returns the value this must be destroyed with duckdb_destroy_value duckdb_create_int64 creates a value from an int64 syntax the bigint value returns the value this must be destroyed with duckdb_destroy_value duckdb_get_varchar obtains a string representation of the given value the result must be destroyed with duckdb_free syntax the value returns the string value this must be destroyed with duckdb_free duckdb_get_int64 obtains an int64 of the given value syntax the value returns the int64 value or 0 if no conversion is possible duckdb_create_logical_type creates a duckdb_logical_type from a standard primitive type the resulting type should be destroyed with duckdb_destroy_logical_type this should not be used with duckdb_type_decimal syntax the primitive type to create returns the logical type duckdb_create_list_type creates a list type from its child type the resulting type should be destroyed with duckdb_destroy_logical_type syntax the child type of list type to create returns the logical type duckdb_create_map_type creates a map type from its key type and value type the resulting type should be destroyed with duckdb_destroy_logical_type syntax the key type and value type of map type to create returns the logical type duckdb_create_union_type creates a union type from the passed types array the resulting type should be destroyed with duckdb_destroy_logical_type syntax the array of types that the union should consist of type_amount the size of the types array returns the logical type duckdb_create_struct_type creates a struct type from the passed member name and type arrays the resulting type should be destroyed with duckdb_destroy_logical_type syntax the array of types that the struct should consist of member_names the array of names that the struct should consist of member_count the number of members that were specified for both arrays returns the logical type duckdb_create_decimal_type creates a duckdb_logical_type of type decimal with the specified width and scale the resulting type should be destroyed with duckdb_destroy_logical_type syntax the width of the decimal type scale the scale of the decimal type returns the logical type duckdb_get_type_id retrieves the type class of a duckdb_logical_type syntax the logical type object returns the type id duckdb_decimal_width retrieves the width of a decimal type syntax the logical type object returns the width of the decimal type duckdb_decimal_scale retrieves the scale of a decimal type syntax the logical type object returns the scale of the decimal type duckdb_decimal_internal_type retrieves the internal storage type of a decimal type syntax the logical type object returns the internal type of the decimal type duckdb_enum_internal_type retrieves the internal storage type of an enum type syntax the logical type object returns the internal type of the enum type duckdb_enum_dictionary_size retrieves the dictionary size of the enum type syntax the logical type object returns the dictionary size of the enum type duckdb_enum_dictionary_value retrieves the dictionary value at the specified position from the enum the result must be freed with duckdb_free syntax the logical type object index the index in the dictionary returns the string value of the enum type must be freed with duckdb_free duckdb_list_type_child_type retrieves the child type of the given list type the result must be freed with duckdb_destroy_logical_type syntax the logical type object returns the child type of the list type must be destroyed with duckdb_destroy_logical_type duckdb_map_type_key_type retrieves the key type of the given map type the result must be freed with duckdb_destroy_logical_type syntax the logical type object returns the key type of the map type must be destroyed with duckdb_destroy_logical_type duckdb_map_type_value_type retrieves the value type of the given map type the result must be freed with duckdb_destroy_logical_type syntax the logical type object returns the value type of the map type must be destroyed with duckdb_destroy_logical_type duckdb_struct_type_child_count returns the number of children of a struct type syntax the logical type object returns the number of children of a struct type duckdb_struct_type_child_name retrieves the name of the struct child the result must be freed with duckdb_free syntax the logical type object index the child index returns the name of the struct type must be freed with duckdb_free duckdb_struct_type_child_type retrieves the child type of the given struct type at the specified index the result must be freed with duckdb_destroy_logical_type syntax the logical type object index the child index returns the child type of the struct type must be destroyed with duckdb_destroy_logical_type duckdb_union_type_member_count returns the number of members that the union type has syntax the logical type union object returns the number of members of a union type duckdb_union_type_member_name retrieves the name of the union member the result must be freed with duckdb_free syntax the logical type object index the child index returns the name of the union member must be freed with duckdb_free duckdb_union_type_member_type retrieves the child type of the given union member at the specified index the result must be freed with duckdb_destroy_logical_type syntax the logical type object index the child index returns the child type of the union member must be destroyed with duckdb_destroy_logical_type duckdb_destroy_logical_type destroys the logical type and de-allocates all memory allocated for that type syntax the logical type to destroy duckdb_create_data_chunk creates an empty datachunk with the specified set of types syntax an array of types of the data chunk column_count the number of columns returns the data chunk duckdb_destroy_data_chunk destroys the data chunk and de-allocates all memory allocated for that chunk syntax the data chunk to destroy duckdb_data_chunk_reset resets a data chunk clearing the validity masks and setting the cardinality of the data chunk to 0 syntax the data chunk to reset duckdb_data_chunk_get_column_count retrieves the number of columns in a data chunk syntax the data chunk to get the data from returns the number of columns in the data chunk duckdb_data_chunk_get_vector retrieves the vector at the specified column index in the data chunk the pointer to the vector is valid for as long as the chunk is alive it does not need to be destroyed syntax the data chunk to get the data from returns the vector duckdb_data_chunk_get_size retrieves the current number of tuples in a data chunk syntax the data chunk to get the data from returns the number of tuples in the data chunk duckdb_data_chunk_set_size sets the current number of tuples in a data chunk syntax the data chunk to set the size in size the number of tuples in the data chunk duckdb_vector_get_column_type retrieves the column type of the specified vector the result must be destroyed with duckdb_destroy_logical_type syntax the vector get the data from returns the type of the vector duckdb_vector_get_data retrieves the data pointer of the vector the data pointer can be used to read or write values from the vector how to read or write values depends on the type of the vector syntax the vector to get the data from returns the data pointer duckdb_vector_get_validity retrieves the validity mask pointer of the specified vector if all values are valid this function might return null the validity mask is a bitset that signifies null-ness within the data chunk it is a series of uint64_t values where each uint64_t value contains validity for 64 tuples the bit is set to 1 if the value is valid i e not null or 0 if the value is invalid i e null validity of a specific value can be obtained like this idx_t entry_idx row_idx 64 idx_t idx_in_entry row_idx 64 bool is_valid validity_mask entry_idx 1 idx_in_entry alternatively the slower duckdb_validity_row_is_valid function can be used syntax the vector to get the data from returns the pointer to the validity mask or null if no validity mask is present duckdb_vector_ensure_validity_writable ensures the validity mask is writable by allocating it after this function is called duckdb_vector_get_validity will always return non-null this allows null values to be written to the vector regardless of whether a validity mask was present before syntax the vector to alter duckdb_vector_assign_string_element assigns a string element in the vector at the specified location syntax the vector to alter index the row position in the vector to assign the string to str the null-terminated string duckdb_vector_assign_string_element_len assigns a string element in the vector at the specified location syntax the vector to alter index the row position in the vector to assign the string to str the string str_len the length of the string in bytes duckdb_list_vector_get_child retrieves the child vector of a list vector the resulting vector is valid as long as the parent vector is valid syntax the vector returns the child vector duckdb_list_vector_get_size returns the size of the child vector of the list syntax the vector returns the size of the child list duckdb_list_vector_set_size sets the total size of the underlying child-vector of a list vector syntax the list vector size the size of the child list returns the duckdb state returns duckdberror if the vector is nullptr duckdb_list_vector_reserve sets the total capacity of the underlying child-vector of a list syntax the list vector required_capacity the total capacity to reserve return the duckdb state returns duckdberror if the vector is nullptr duckdb_struct_vector_get_child retrieves the child vector of a struct vector the resulting vector is valid as long as the parent vector is valid syntax the vector index the child index returns the child vector duckdb_validity_row_is_valid returns whether or not a row is valid i e not null in the given validity mask syntax the validity mask as obtained through duckdb_data_chunk_get_validity row the row index returns true if the row is valid false otherwise duckdb_validity_set_row_validity in a validity mask sets a specific row to either valid or invalid note that duckdb_data_chunk_ensure_validity_writable should be called before calling duckdb_data_chunk_get_validity to ensure that there is a validity mask to write to syntax the validity mask as obtained through duckdb_data_chunk_get_validity row the row index valid whether or not to set the row to valid or invalid duckdb_validity_set_row_invalid in a validity mask sets a specific row to invalid equivalent to duckdb_validity_set_row_validity with valid set to false syntax the validity mask row the row index duckdb_validity_set_row_valid in a validity mask sets a specific row to valid equivalent to duckdb_validity_set_row_validity with valid set to true syntax the validity mask row the row index duckdb_create_table_function creates a new empty table function the return value should be destroyed with duckdb_destroy_table_function syntax the table function object duckdb_destroy_table_function destroys the given table function object syntax the table function to destroy duckdb_table_function_set_name sets the name of the given table function syntax the table function name the name of the table function duckdb_table_function_add_parameter adds a parameter to the table function syntax 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 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 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 the table function bind the bind function duckdb_table_function_set_init sets the init function of the table function syntax the table function init the init function duckdb_table_function_set_local_init sets the thread-local init function of the table function syntax the table function init the init function duckdb_table_function_set_function sets the main function of the table function syntax 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 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 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 the info object returns the extra info duckdb_bind_add_result_column adds a result column to the output of the table function syntax 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 the info object returns the init data object duckdb_function_set_error report that an error has occurred while executing the function syntax the info object error the error message duckdb_add_replacement_scan add a replacement scan definition to the specified database syntax the database object to add the replacement scan to replacement the replacement scan callback extra_data extra data that is passed back into the specified callback delete_callback the delete callback to call on the extra data if any duckdb_replacement_scan_set_function_name sets the replacement function name to use if this function is called in the replacement callback the replacement scan is performed if it is not called the replacement callback is not performed syntax the info object function_name the function name to substitute duckdb_replacement_scan_add_parameter adds a parameter to the replacement scan function syntax the info object parameter the parameter to add duckdb_replacement_scan_set_error report that an error has occurred while executing the replacement scan syntax the info object error the error message duckdb_appender_create creates an appender object syntax the connection context to create the appender in schema the schema of the table to append to or nullptr for the default schema table the table name to append to out_appender the resulting appender object returns duckdbsuccess on success or duckdberror on failure duckdb_appender_error returns the error message associated with the given appender if the appender has no error message this returns nullptr instead the error message should not be freed it will be de-allocated when duckdb_appender_destroy is called syntax the appender to get the error from returns the error message or nullptr if there is none duckdb_appender_flush flush the appender to the table forcing the cache of the appender to be cleared and the data to be appended to the base table this should generally not be used unless you know what you are doing instead call duckdb_appender_destroy when you are done with the appender syntax the appender to flush returns duckdbsuccess on success or duckdberror on failure duckdb_appender_close close the appender flushing all intermediate state in the appender to the table and closing it for further appends this is generally not necessary call duckdb_appender_destroy instead syntax the appender to flush and close returns duckdbsuccess on success or duckdberror on failure duckdb_appender_destroy close the appender and destroy it flushing all intermediate state in the appender to the table and de-allocating all memory associated with the appender syntax the appender to flush close and destroy returns duckdbsuccess on success or duckdberror on failure duckdb_appender_begin_row a nop function provided for backwards compatibility reasons does nothing only duckdb_appender_end_row is required syntax duckdb_appender_end_row finish the current row of appends after end_row is called the next row can be appended syntax the appender returns duckdbsuccess on success or duckdberror on failure duckdb_append_bool append a bool value to the appender syntax duckdb_append_int8 append an int8_t value to the appender syntax duckdb_append_int16 append an int16_t value to the appender syntax duckdb_append_int32 append an int32_t value to the appender syntax duckdb_append_int64 append an int64_t value to the appender syntax duckdb_append_hugeint append a duckdb_hugeint value to the appender syntax duckdb_append_uint8 append a uint8_t value to the appender syntax duckdb_append_uint16 append a uint16_t value to the appender syntax duckdb_append_uint32 append a uint32_t value to the appender syntax duckdb_append_uint64 append a uint64_t value to the appender syntax duckdb_append_float append a float value to the appender syntax duckdb_append_double append a double value to the appender syntax duckdb_append_date append a duckdb_date value to the appender syntax duckdb_append_time append a duckdb_time value to the appender syntax duckdb_append_timestamp append a duckdb_timestamp value to the appender syntax duckdb_append_interval append a duckdb_interval value to the appender syntax duckdb_append_varchar append a varchar value to the appender syntax duckdb_append_varchar_length append a varchar value to the appender syntax duckdb_append_blob append a blob value to the appender syntax duckdb_append_null append a null value to the appender of any type syntax duckdb_append_data_chunk appends a pre-filled data chunk to the specified appender the types of the data chunk must exactly match the types of the table no casting is performed if the types do not match or the appender is in an invalid state duckdberror is returned if the append is successful duckdbsuccess is returned syntax the appender to append to chunk the data chunk to append returns the return state duckdb_query_arrow executes a sql query within a connection and stores the full materialized result in an arrow structure if the query fails to execute duckdberror is returned and the error message can be retrieved by calling duckdb_query_arrow_error note that after running duckdb_query_arrow duckdb_destroy_arrow must be called on the result object even if the query fails otherwise the error stored within the result will not be freed correctly syntax the connection to perform the query in query the sql query to run out_result the query result returns duckdbsuccess on success or duckdberror on failure duckdb_query_arrow_schema fetch the internal arrow schema from the arrow result syntax the result to fetch the schema from out_schema the output schema returns duckdbsuccess on success or duckdberror on failure duckdb_prepared_arrow_schema fetch the internal arrow schema from the prepared statement syntax the prepared statement to fetch the schema from out_schema the output schema returns duckdbsuccess on success or duckdberror on failure duckdb_query_arrow_array fetch an internal arrow array from the arrow result this function can be called multiple time to get next chunks which will free the previous out_array so consume the out_array before calling this function again syntax the result to fetch the array from out_array the output array returns duckdbsuccess on success or duckdberror on failure duckdb_arrow_column_count returns the number of columns present in a the arrow result object syntax the result object returns the number of columns present in the result object duckdb_arrow_row_count returns the number of rows present in a the arrow result object syntax the result object returns the number of rows present in the result object duckdb_arrow_rows_changed returns the number of rows changed by the query stored in the arrow result this is relevant only for insert update delete queries for other queries the rows_changed will be 0 syntax the result object returns the number of rows changed duckdb_query_arrow_error returns the error message contained within the result the error is only set if duckdb_query_arrow returns duckdberror the error message should not be freed it will be de-allocated when duckdb_destroy_arrow is called syntax the result object to fetch the nullmask from returns the error of the result duckdb_destroy_arrow closes the result and de-allocates all memory allocated for the arrow result syntax the result to destroy duckdb_execute_tasks execute duckdb tasks on this thread will return after max_tasks have been executed or if there are no more tasks present syntax the database object to execute tasks for max_tasks the maximum amount of tasks to execute duckdb_create_task_state creates a task state that can be used with duckdb_execute_tasks_state to execute tasks until duckdb_finish_execution is called on the state duckdb_destroy_state should be called on the result in order to free memory syntax the database object to create the task state for returns the task state that can be used with duckdb_execute_tasks_state duckdb_execute_tasks_state execute duckdb tasks on this thread the thread will keep on executing tasks forever until duckdb_finish_execution is called on the state multiple threads can share the same duckdb_task_state syntax the task state of the executor duckdb_execute_n_tasks_state execute duckdb tasks on this thread the thread will keep on executing tasks until either duckdb_finish_execution is called on the state max_tasks tasks have been executed or there are no more tasks to be executed multiple threads can share the same duckdb_task_state syntax the task state of the executor max_tasks the maximum amount of tasks to execute returns the amount of tasks that have actually been executed duckdb_finish_execution finish execution on a specific task syntax the task state to finish execution duckdb_task_state_is_finished check if the provided duckdb_task_state has finished execution syntax the task state to inspect returns whether or not duckdb_finish_execution has been called on the task state duckdb_destroy_task_state destroys the task state returned from duckdb_create_task_state note that this should not be called while there is an active duckdb_execute_tasks_state running on the task state syntax the task state to clean up duckdb_execution_is_finished returns true if execution of the current query is finished syntax the connection on which to check duckdb_stream_fetch_chunk fetches a data chunk from the streaming duckdb_result this function should be called repeatedly until the result is exhausted the result must be destroyed with duckdb_destroy_data_chunk this function can only be used on duckdb_results created with duckdb_pending_prepared_streaming if this function is used none of the other result functions can be used and vice versa i e this function cannot be mixed with the legacy result functions or the materialized result functions it is not known beforehand how many chunks will be returned by this result syntax the result object to fetch the data chunk from returns the resulting data chunk returns null if the result has an error", "category": "C", "url": "/docs/api/c/api", "blurb": "API Reference Open/Connect Syntax Path to the database file on disk, or nullptr or :memory: to open an in-memory..." @@ -226,7 +226,7 @@ }, { "title": "C API - Types", - "text": "duckdb is a strongly typed database system as such every column has a single type specified this type is constant over the entire column that is to say a column that is labeled as an integer column will only contain integer values duckdb also supports columns of composite types for example it is possible to define an array of integers int it is also possible to define types as arbitrary structs row i integer j varchar for that reason native duckdb type objects are not mere enums but a class that can potentially be nested types in the c api are modeled using an enum duckdb_type and a complex class duckdb_logical_type for most primitive types e g integers or varchars the enum is sufficient for more complex types such as lists structs or decimals the logical type must be used typedef enum duckdb_type duckdb_type_invalid duckdb_type_boolean duckdb_type_tinyint duckdb_type_smallint duckdb_type_integer duckdb_type_bigint duckdb_type_utinyint duckdb_type_usmallint duckdb_type_uinteger duckdb_type_ubigint duckdb_type_float duckdb_type_double duckdb_type_timestamp duckdb_type_date duckdb_type_time duckdb_type_interval duckdb_type_hugeint duckdb_type_varchar duckdb_type_blob duckdb_type_decimal duckdb_type_timestamp_s duckdb_type_timestamp_ms duckdb_type_timestamp_ns duckdb_type_enum duckdb_type_list duckdb_type_struct duckdb_type_map duckdb_type_uuid duckdb_type_json duckdb_type the enum type of a column in the result can be obtained using the duckdb_column_type function the logical type of a column can be obtained using the duckdb_column_logical_type function duckdb_value the duckdb_value functions will auto-cast values as required for example it is no problem to use duckdb_value_double on a column of type duckdb_value_int32 the value will be auto-cast and returned as a double note that in certain cases the cast may fail for example this can happen if we request a duckdb_value_int8 and the value does not fit within an int8 value in this case a default value will be returned usually 0 or nullptr the same default value will also be returned if the corresponding value is null the duckdb_value_is_null function can be used to check if a specific value is null or not the exception to the auto-cast rule is the duckdb_value_varchar_internal function this function does not auto-cast and only works for varchar columns the reason this function exists is that the result does not need to be freed note that duckdb_value_varchar and duckdb_value_blob require the result to be de-allocated using duckdb_free duckdb_result_get_chunk the duckdb_result_get_chunk function can be used to read data chunks from a duckdb result set and is the most efficient way of reading data from a duckdb result using the c api it is also the only way of reading data of certain types from a duckdb result for example the duckdb_value functions do not support structural reading of composite types lists or structs or more complex types like enums and decimals for more information about data chunks see the documentation on data chunks api reference the result must be destroyed with duckdb_destroy_data_chunk this function supersedes all duckdb_value functions as well as the duckdb_column_data and duckdb_nullmask_data functions it results in significantly better performance and should be preferred in newer code-bases if this function is used none of the other result functions can be used and vice versa i e this function cannot be mixed with the legacy result functions use duckdb_result_chunk_count to figure out how many chunks there are in the result syntax the result object to fetch the data chunk from chunk_index the chunk index to fetch from returns the resulting data chunk returns null if the chunk index is out of bounds duckdb_result_is_streaming checks if the type of the internal result is streamqueryresult syntax the result object to check returns whether or not the result object is of the type streamqueryresult duckdb_result_chunk_count returns the number of data chunks present in the result syntax the result object returns number of data chunks present in the result duckdb_value_boolean syntax the boolean value at the specified location or false if the value cannot be converted duckdb_value_int8 syntax the int8_t value at the specified location or 0 if the value cannot be converted duckdb_value_int16 syntax the int16_t value at the specified location or 0 if the value cannot be converted duckdb_value_int32 syntax the int32_t value at the specified location or 0 if the value cannot be converted duckdb_value_int64 syntax the int64_t value at the specified location or 0 if the value cannot be converted duckdb_value_hugeint syntax the duckdb_hugeint value at the specified location or 0 if the value cannot be converted duckdb_value_decimal syntax the duckdb_decimal value at the specified location or 0 if the value cannot be converted duckdb_value_uint8 syntax the uint8_t value at the specified location or 0 if the value cannot be converted duckdb_value_uint16 syntax the uint16_t value at the specified location or 0 if the value cannot be converted duckdb_value_uint32 syntax the uint32_t value at the specified location or 0 if the value cannot be converted duckdb_value_uint64 syntax the uint64_t value at the specified location or 0 if the value cannot be converted duckdb_value_float syntax the float value at the specified location or 0 if the value cannot be converted duckdb_value_double syntax the double value at the specified location or 0 if the value cannot be converted duckdb_value_date syntax the duckdb_date value at the specified location or 0 if the value cannot be converted duckdb_value_time syntax the duckdb_time value at the specified location or 0 if the value cannot be converted duckdb_value_timestamp syntax the duckdb_timestamp value at the specified location or 0 if the value cannot be converted duckdb_value_interval syntax the duckdb_interval value at the specified location or 0 if the value cannot be converted duckdb_value_varchar syntax use duckdb_value_string instead this function does not work correctly if the string contains null bytes returns the text value at the specified location as a null-terminated string or nullptr if the value cannot be converted the result must be freed with duckdb_free duckdb_value_varchar_internal syntax use duckdb_value_string_internal instead this function does not work correctly if the string contains null bytes returns the char value at the specified location only works on varchar columns and does not auto-cast if the column is not a varchar column this function will return null the result must not be freed duckdb_value_string_internal syntax use duckdb_value_string_internal instead this function does not work correctly if the string contains null bytes returns the char value at the specified location only works on varchar columns and does not auto-cast if the column is not a varchar column this function will return null the result must not be freed duckdb_value_blob syntax the duckdb_blob value at the specified location returns a blob with blob data set to nullptr if the value cannot be converted the resulting blob data must be freed with duckdb_free duckdb_value_is_null syntax returns true if the value at the specified index is null and false otherwise duckdb_from_date decompose a duckdb_date object into year month and date stored as duckdb_date_struct syntax the date object as obtained from a duckdb_type_date column returns the duckdb_date_struct with the decomposed elements duckdb_to_date re-compose a duckdb_date from year month and date duckdb_date_struct syntax the year month and date stored in a duckdb_date_struct returns the duckdb_date element duckdb_from_time decompose a duckdb_time object into hour minute second and microsecond stored as duckdb_time_struct syntax the time object as obtained from a duckdb_type_time column returns the duckdb_time_struct with the decomposed elements duckdb_to_time re-compose a duckdb_time from hour minute second and microsecond duckdb_time_struct syntax the hour minute second and microsecond in a duckdb_time_struct returns the duckdb_time element duckdb_from_timestamp decompose a duckdb_timestamp object into a duckdb_timestamp_struct syntax the ts object as obtained from a duckdb_type_timestamp column returns the duckdb_timestamp_struct with the decomposed elements duckdb_to_timestamp re-compose a duckdb_timestamp from a duckdb_timestamp_struct syntax the de-composed elements in a duckdb_timestamp_struct returns the duckdb_timestamp element duckdb_hugeint_to_double converts a duckdb_hugeint object as obtained from a duckdb_type_hugeint column into a double syntax the hugeint value returns the converted double element duckdb_double_to_hugeint converts a double value to a duckdb_hugeint object if the conversion fails because the double value is too big the result will be 0 syntax the double value returns the converted duckdb_hugeint element duckdb_double_to_decimal converts a double value to a duckdb_decimal object if the conversion fails because the double value is too big or the width scale are invalid the result will be 0 syntax the double value returns the converted duckdb_decimal element duckdb_decimal_to_double converts a duckdb_decimal object as obtained from a duckdb_type_decimal column into a double syntax the decimal value returns the converted double element duckdb_create_logical_type creates a duckdb_logical_type from a standard primitive type the resulting type should be destroyed with duckdb_destroy_logical_type this should not be used with duckdb_type_decimal syntax the primitive type to create returns the logical type duckdb_create_list_type creates a list type from its child type the resulting type should be destroyed with duckdb_destroy_logical_type syntax the child type of list type to create returns the logical type duckdb_create_map_type creates a map type from its key type and value type the resulting type should be destroyed with duckdb_destroy_logical_type syntax the key type and value type of map type to create returns the logical type duckdb_create_union_type creates a union type from the passed types array the resulting type should be destroyed with duckdb_destroy_logical_type syntax the array of types that the union should consist of type_amount the size of the types array returns the logical type duckdb_create_decimal_type creates a duckdb_logical_type of type decimal with the specified width and scale the resulting type should be destroyed with duckdb_destroy_logical_type syntax the width of the decimal type scale the scale of the decimal type returns the logical type duckdb_get_type_id retrieves the type class of a duckdb_logical_type syntax the logical type object returns the type id duckdb_decimal_width retrieves the width of a decimal type syntax the logical type object returns the width of the decimal type duckdb_decimal_scale retrieves the scale of a decimal type syntax the logical type object returns the scale of the decimal type duckdb_decimal_internal_type retrieves the internal storage type of a decimal type syntax the logical type object returns the internal type of the decimal type duckdb_enum_internal_type retrieves the internal storage type of an enum type syntax the logical type object returns the internal type of the enum type duckdb_enum_dictionary_size retrieves the dictionary size of the enum type syntax the logical type object returns the dictionary size of the enum type duckdb_enum_dictionary_value retrieves the dictionary value at the specified position from the enum the result must be freed with duckdb_free syntax the logical type object index the index in the dictionary returns the string value of the enum type must be freed with duckdb_free duckdb_list_type_child_type retrieves the child type of the given list type the result must be freed with duckdb_destroy_logical_type syntax the logical type object returns the child type of the list type must be destroyed with duckdb_destroy_logical_type duckdb_map_type_key_type retrieves the key type of the given map type the result must be freed with duckdb_destroy_logical_type syntax the logical type object returns the key type of the map type must be destroyed with duckdb_destroy_logical_type duckdb_map_type_value_type retrieves the value type of the given map type the result must be freed with duckdb_destroy_logical_type syntax the logical type object returns the value type of the map type must be destroyed with duckdb_destroy_logical_type duckdb_struct_type_child_count returns the number of children of a struct type syntax the logical type object returns the number of children of a struct type duckdb_struct_type_child_name retrieves the name of the struct child the result must be freed with duckdb_free syntax the logical type object index the child index returns the name of the struct type must be freed with duckdb_free duckdb_struct_type_child_type retrieves the child type of the given struct type at the specified index the result must be freed with duckdb_destroy_logical_type syntax the logical type object index the child index returns the child type of the struct type must be destroyed with duckdb_destroy_logical_type duckdb_union_type_member_count returns the number of members that the union type has syntax the logical type union object returns the number of members of a union type duckdb_union_type_member_name retrieves the name of the union member the result must be freed with duckdb_free syntax the logical type object index the child index returns the name of the union member must be freed with duckdb_free duckdb_union_type_member_type retrieves the child type of the given union member at the specified index the result must be freed with duckdb_destroy_logical_type syntax the logical type object index the child index returns the child type of the union member must be destroyed with duckdb_destroy_logical_type duckdb_destroy_logical_type destroys the logical type and de-allocates all memory allocated for that type syntax the logical type to destroy", + "text": "duckdb is a strongly typed database system as such every column has a single type specified this type is constant over the entire column that is to say a column that is labeled as an integer column will only contain integer values duckdb also supports columns of composite types for example it is possible to define an array of integers int it is also possible to define types as arbitrary structs row i integer j varchar for that reason native duckdb type objects are not mere enums but a class that can potentially be nested types in the c api are modeled using an enum duckdb_type and a complex class duckdb_logical_type for most primitive types e g integers or varchars the enum is sufficient for more complex types such as lists structs or decimals the logical type must be used typedef enum duckdb_type duckdb_type_invalid duckdb_type_boolean duckdb_type_tinyint duckdb_type_smallint duckdb_type_integer duckdb_type_bigint duckdb_type_utinyint duckdb_type_usmallint duckdb_type_uinteger duckdb_type_ubigint duckdb_type_float duckdb_type_double duckdb_type_timestamp duckdb_type_date duckdb_type_time duckdb_type_interval duckdb_type_hugeint duckdb_type_varchar duckdb_type_blob duckdb_type_decimal duckdb_type_timestamp_s duckdb_type_timestamp_ms duckdb_type_timestamp_ns duckdb_type_enum duckdb_type_list duckdb_type_struct duckdb_type_map duckdb_type_uuid duckdb_type_json duckdb_type the enum type of a column in the result can be obtained using the duckdb_column_type function the logical type of a column can be obtained using the duckdb_column_logical_type function duckdb_value the duckdb_value functions will auto-cast values as required for example it is no problem to use duckdb_value_double on a column of type duckdb_value_int32 the value will be auto-cast and returned as a double note that in certain cases the cast may fail for example this can happen if we request a duckdb_value_int8 and the value does not fit within an int8 value in this case a default value will be returned usually 0 or nullptr the same default value will also be returned if the corresponding value is null the duckdb_value_is_null function can be used to check if a specific value is null or not the exception to the auto-cast rule is the duckdb_value_varchar_internal function this function does not auto-cast and only works for varchar columns the reason this function exists is that the result does not need to be freed note that duckdb_value_varchar and duckdb_value_blob require the result to be de-allocated using duckdb_free duckdb_result_get_chunk the duckdb_result_get_chunk function can be used to read data chunks from a duckdb result set and is the most efficient way of reading data from a duckdb result using the c api it is also the only way of reading data of certain types from a duckdb result for example the duckdb_value functions do not support structural reading of composite types lists or structs or more complex types like enums and decimals for more information about data chunks see the documentation on data chunks api reference the result must be destroyed with duckdb_destroy_data_chunk this function supersedes all duckdb_value functions as well as the duckdb_column_data and duckdb_nullmask_data functions it results in significantly better performance and should be preferred in newer code-bases if this function is used none of the other result functions can be used and vice versa i e this function cannot be mixed with the legacy result functions use duckdb_result_chunk_count to figure out how many chunks there are in the result syntax the result object to fetch the data chunk from chunk_index the chunk index to fetch from returns the resulting data chunk returns null if the chunk index is out of bounds duckdb_result_is_streaming checks if the type of the internal result is streamqueryresult syntax the result object to check returns whether or not the result object is of the type streamqueryresult duckdb_result_chunk_count returns the number of data chunks present in the result syntax the result object returns number of data chunks present in the result duckdb_value_boolean syntax the boolean value at the specified location or false if the value cannot be converted duckdb_value_int8 syntax the int8_t value at the specified location or 0 if the value cannot be converted duckdb_value_int16 syntax the int16_t value at the specified location or 0 if the value cannot be converted duckdb_value_int32 syntax the int32_t value at the specified location or 0 if the value cannot be converted duckdb_value_int64 syntax the int64_t value at the specified location or 0 if the value cannot be converted duckdb_value_hugeint syntax the duckdb_hugeint value at the specified location or 0 if the value cannot be converted duckdb_value_decimal syntax the duckdb_decimal value at the specified location or 0 if the value cannot be converted duckdb_value_uint8 syntax the uint8_t value at the specified location or 0 if the value cannot be converted duckdb_value_uint16 syntax the uint16_t value at the specified location or 0 if the value cannot be converted duckdb_value_uint32 syntax the uint32_t value at the specified location or 0 if the value cannot be converted duckdb_value_uint64 syntax the uint64_t value at the specified location or 0 if the value cannot be converted duckdb_value_float syntax the float value at the specified location or 0 if the value cannot be converted duckdb_value_double syntax the double value at the specified location or 0 if the value cannot be converted duckdb_value_date syntax the duckdb_date value at the specified location or 0 if the value cannot be converted duckdb_value_time syntax the duckdb_time value at the specified location or 0 if the value cannot be converted duckdb_value_timestamp syntax the duckdb_timestamp value at the specified location or 0 if the value cannot be converted duckdb_value_interval syntax the duckdb_interval value at the specified location or 0 if the value cannot be converted duckdb_value_varchar syntax use duckdb_value_string instead this function does not work correctly if the string contains null bytes returns the text value at the specified location as a null-terminated string or nullptr if the value cannot be converted the result must be freed with duckdb_free duckdb_value_varchar_internal syntax use duckdb_value_string_internal instead this function does not work correctly if the string contains null bytes returns the char value at the specified location only works on varchar columns and does not auto-cast if the column is not a varchar column this function will return null the result must not be freed duckdb_value_string_internal syntax use duckdb_value_string_internal instead this function does not work correctly if the string contains null bytes returns the char value at the specified location only works on varchar columns and does not auto-cast if the column is not a varchar column this function will return null the result must not be freed duckdb_value_blob syntax the duckdb_blob value at the specified location returns a blob with blob data set to nullptr if the value cannot be converted the resulting blob data must be freed with duckdb_free duckdb_value_is_null syntax returns true if the value at the specified index is null and false otherwise duckdb_from_date decompose a duckdb_date object into year month and date stored as duckdb_date_struct syntax the date object as obtained from a duckdb_type_date column returns the duckdb_date_struct with the decomposed elements duckdb_to_date re-compose a duckdb_date from year month and date duckdb_date_struct syntax the year month and date stored in a duckdb_date_struct returns the duckdb_date element duckdb_from_time decompose a duckdb_time object into hour minute second and microsecond stored as duckdb_time_struct syntax the time object as obtained from a duckdb_type_time column returns the duckdb_time_struct with the decomposed elements duckdb_to_time re-compose a duckdb_time from hour minute second and microsecond duckdb_time_struct syntax the hour minute second and microsecond in a duckdb_time_struct returns the duckdb_time element duckdb_from_timestamp decompose a duckdb_timestamp object into a duckdb_timestamp_struct syntax the ts object as obtained from a duckdb_type_timestamp column returns the duckdb_timestamp_struct with the decomposed elements duckdb_to_timestamp re-compose a duckdb_timestamp from a duckdb_timestamp_struct syntax the de-composed elements in a duckdb_timestamp_struct returns the duckdb_timestamp element duckdb_hugeint_to_double converts a duckdb_hugeint object as obtained from a duckdb_type_hugeint column into a double syntax the hugeint value returns the converted double element duckdb_double_to_hugeint converts a double value to a duckdb_hugeint object if the conversion fails because the double value is too big the result will be 0 syntax the double value returns the converted duckdb_hugeint element duckdb_double_to_decimal converts a double value to a duckdb_decimal object if the conversion fails because the double value is too big or the width scale are invalid the result will be 0 syntax the double value returns the converted duckdb_decimal element duckdb_decimal_to_double converts a duckdb_decimal object as obtained from a duckdb_type_decimal column into a double syntax the decimal value returns the converted double element duckdb_create_logical_type creates a duckdb_logical_type from a standard primitive type the resulting type should be destroyed with duckdb_destroy_logical_type this should not be used with duckdb_type_decimal syntax the primitive type to create returns the logical type duckdb_create_list_type creates a list type from its child type the resulting type should be destroyed with duckdb_destroy_logical_type syntax the child type of list type to create returns the logical type duckdb_create_map_type creates a map type from its key type and value type the resulting type should be destroyed with duckdb_destroy_logical_type syntax the key type and value type of map type to create returns the logical type duckdb_create_union_type creates a union type from the passed types array the resulting type should be destroyed with duckdb_destroy_logical_type syntax the array of types that the union should consist of type_amount the size of the types array returns the logical type duckdb_create_struct_type creates a struct type from the passed member name and type arrays the resulting type should be destroyed with duckdb_destroy_logical_type syntax the array of types that the struct should consist of member_names the array of names that the struct should consist of member_count the number of members that were specified for both arrays returns the logical type duckdb_create_decimal_type creates a duckdb_logical_type of type decimal with the specified width and scale the resulting type should be destroyed with duckdb_destroy_logical_type syntax the width of the decimal type scale the scale of the decimal type returns the logical type duckdb_get_type_id retrieves the type class of a duckdb_logical_type syntax the logical type object returns the type id duckdb_decimal_width retrieves the width of a decimal type syntax the logical type object returns the width of the decimal type duckdb_decimal_scale retrieves the scale of a decimal type syntax the logical type object returns the scale of the decimal type duckdb_decimal_internal_type retrieves the internal storage type of a decimal type syntax the logical type object returns the internal type of the decimal type duckdb_enum_internal_type retrieves the internal storage type of an enum type syntax the logical type object returns the internal type of the enum type duckdb_enum_dictionary_size retrieves the dictionary size of the enum type syntax the logical type object returns the dictionary size of the enum type duckdb_enum_dictionary_value retrieves the dictionary value at the specified position from the enum the result must be freed with duckdb_free syntax the logical type object index the index in the dictionary returns the string value of the enum type must be freed with duckdb_free duckdb_list_type_child_type retrieves the child type of the given list type the result must be freed with duckdb_destroy_logical_type syntax the logical type object returns the child type of the list type must be destroyed with duckdb_destroy_logical_type duckdb_map_type_key_type retrieves the key type of the given map type the result must be freed with duckdb_destroy_logical_type syntax the logical type object returns the key type of the map type must be destroyed with duckdb_destroy_logical_type duckdb_map_type_value_type retrieves the value type of the given map type the result must be freed with duckdb_destroy_logical_type syntax the logical type object returns the value type of the map type must be destroyed with duckdb_destroy_logical_type duckdb_struct_type_child_count returns the number of children of a struct type syntax the logical type object returns the number of children of a struct type duckdb_struct_type_child_name retrieves the name of the struct child the result must be freed with duckdb_free syntax the logical type object index the child index returns the name of the struct type must be freed with duckdb_free duckdb_struct_type_child_type retrieves the child type of the given struct type at the specified index the result must be freed with duckdb_destroy_logical_type syntax the logical type object index the child index returns the child type of the struct type must be destroyed with duckdb_destroy_logical_type duckdb_union_type_member_count returns the number of members that the union type has syntax the logical type union object returns the number of members of a union type duckdb_union_type_member_name retrieves the name of the union member the result must be freed with duckdb_free syntax the logical type object index the child index returns the name of the union member must be freed with duckdb_free duckdb_union_type_member_type retrieves the child type of the given union member at the specified index the result must be freed with duckdb_destroy_logical_type syntax the logical type object index the child index returns the child type of the union member must be destroyed with duckdb_destroy_logical_type duckdb_destroy_logical_type destroys the logical type and de-allocates all memory allocated for that type syntax the logical type to destroy", "category": "C", "url": "/docs/api/c/types", "blurb": "DuckDB is a strongly typed database system. As such, every column has a single type specified. This type is constant..." @@ -940,10 +940,10 @@ }, { "title": "NodeJS API", - "text": "modules typedefs a name module_duckdb a duckdb summary these jsdoc annotations are still a work in progress - feedback and suggestions are welcome duckdb connection run sql params callback code void code all sql params callback code void code arrowipcall sql params callback code void code arrowipcstream sql params callback each sql params callback code void code stream sql params register_udf name return_type fun code void code prepare sql params callback code statement code exec sql params callback code void code register_udf_bulk name return_type callback code void code unregister_udf name return_type callback code void code register_buffer name array force callback code void code unregister_buffer name callback code void code statement sql get run sql params callback code void code all sql params callback code void code arrowipcall sql params callback code void code each sql params callback code void code finalize sql params callback code void code stream sql params columns code array lt columninfo gt code queryresult nextchunk nextipcbuffer asynciterator database close callback code void code close_internal callback code void code wait callback code void code serialize callback code void code parallelize callback code void code connect path code connection code interrupt callback code void code prepare sql code statement code run sql params callback code void code scanarrowipc sql params callback code void code each sql params callback code void code all sql params callback code void code arrowipcall sql params callback code void code arrowipcstream sql params callback code void code exec sql params callback code void code register_udf name return_type fun code this code register_buffer name code this code unregister_buffer name code this code unregister_udf name code this code registerreplacementscan fun code this code get error code number code open_readonly code number code open_readwrite code number code open_create code number code open_fullmutex code number code open_sharedcache code number code open_privatecache code number code a name module_duckdb connection a duckdb connection kind inner class of code duckdb code connection run sql params callback code void code all sql params callback code void code arrowipcall sql params callback code void code arrowipcstream sql params callback each sql params callback code void code stream sql params register_udf name return_type fun code void code prepare sql params callback code statement code exec sql params callback code void code register_udf_bulk name return_type callback code void code unregister_udf name return_type callback code void code register_buffer name array force callback code void code unregister_buffer name callback code void code a name module_duckdb connection run a connection run sql params callback code void code run a sql statement and trigger a callback when done kind instance method of code connection code param type --- --- sql params code code callback a name module_duckdb connection all a connection all sql params callback code void code run a sql query and triggers the callback once for all result rows kind instance method of code connection code param type --- --- sql params code code callback a name module_duckdb connection arrowipcall a connection arrowipcall sql params callback code void code run a sql query and serialize the result into the apache arrow ipc format requires arrow extension to be loaded kind instance method of code connection code param type --- --- sql params code code callback a name module_duckdb connection arrowipcstream a connection arrowipcstream sql params callback run a sql query returns a ipcresultstreamiterator that allows streaming the result into the apache arrow ipc format requires arrow extension to be loaded kind instance method of code connection code returns promise ipcresultstreamiterator param type --- --- sql params code code callback a name module_duckdb connection each a connection each sql params callback code void code runs a sql query and triggers the callback for each result row kind instance method of code connection code param type --- --- sql params code code callback a name module_duckdb connection stream a connection stream sql params kind instance method of code connection code param type --- --- sql params code code a name module_duckdb connection register_udf a connection register _ udf name return_type fun code void code register a user defined function kind instance method of code connection code note this follows the wasm udfs somewhat but is simpler because we can pass data much more cleanly param --- name return_type fun a name module_duckdb connection prepare a connection prepare sql params callback code statement code prepare a sql query for execution kind instance method of code connection code param type --- --- sql params code code callback a name module_duckdb connection exec a connection exec sql params callback code void code execute a sql query kind instance method of code connection code param type --- --- sql params code code callback a name module_duckdb connection register_udf_bulk a connection register _ udf _ bulk name return_type callback code void code register a user defined function kind instance method of code connection code param --- name return_type callback a name module_duckdb connection unregister_udf a connection unregister _ udf name return_type callback code void code unregister a user defined function kind instance method of code connection code param --- name return_type callback a name module_duckdb connection register_buffer a connection register _ buffer name array force callback code void code register a buffer to be scanned using the apache arrow ipc scanner requires arrow extension to be loaded kind instance method of code connection code param --- name array force callback a name module_duckdb connection unregister_buffer a connection unregister _ buffer name callback code void code unregister the buffer kind instance method of code connection code param --- name callback a name module_duckdb statement a duckdb statement kind inner class of code duckdb code statement sql get run sql params callback code void code all sql params callback code void code arrowipcall sql params callback code void code each sql params callback code void code finalize sql params callback code void code stream sql params columns code array lt columninfo gt code a name module_duckdb statement sql a statement sql kind instance property of code statement code returns sql contained in statement field a name module_duckdb statement get a statement get not implemented kind instance method of code statement code a name module_duckdb statement run a statement run sql params callback code void code kind instance method of code statement code param type --- --- sql params code code callback a name module_duckdb statement all a statement all sql params callback code void code kind instance method of code statement code param type --- --- sql params code code callback a name module_duckdb statement arrowipcall a statement arrowipcall sql params callback code void code kind instance method of code statement code param type --- --- sql params code code callback a name module_duckdb statement each a statement each sql params callback code void code kind instance method of code statement code param type --- --- sql params code code callback a name module_duckdb statement finalize a statement finalize sql params callback code void code kind instance method of code statement code param type --- --- sql params code code callback a name module_duckdb statement stream a statement stream sql params kind instance method of code statement code param type --- --- sql params code code a name module_duckdb statement columns a statement columns code array lt columninfo gt code kind instance method of code statement code returns code array lt columninfo gt code - - array of column names and types a name module_duckdb queryresult a duckdb queryresult kind inner class of code duckdb code queryresult nextchunk nextipcbuffer asynciterator a name module_duckdb queryresult nextchunk a queryresult nextchunk kind instance method of code queryresult code returns data chunk a name module_duckdb queryresult nextipcbuffer a queryresult nextipcbuffer function to fetch the next result blob of an arrow ipc stream in a zero-copy way requires arrow extension to be loaded kind instance method of code queryresult code returns data chunk a name module_duckdb queryresult asynciterator a queryresult asynciterator kind instance method of code queryresult code a name module_duckdb database a duckdb database main database interface kind inner property of code duckdb code param description --- --- path path to database file or memory for in-memory database access_mode access mode config the configuration object callback callback function database close callback code void code close_internal callback code void code wait callback code void code serialize callback code void code parallelize callback code void code connect path code connection code interrupt callback code void code prepare sql code statement code run sql params callback code void code scanarrowipc sql params callback code void code each sql params callback code void code all sql params callback code void code arrowipcall sql params callback code void code arrowipcstream sql params callback code void code exec sql params callback code void code register_udf name return_type fun code this code register_buffer name code this code unregister_buffer name code this code unregister_udf name code this code registerreplacementscan fun code this code get a name module_duckdb database close a database close callback code void code closes database instance kind instance method of code database code param --- callback a name module_duckdb database close_internal a database close _ internal callback code void code internal method do not use call connection close instead kind instance method of code database code param --- callback a name module_duckdb database wait a database wait callback code void code triggers callback when all scheduled database tasks have completed kind instance method of code database code param --- callback a name module_duckdb database serialize a database serialize callback code void code todo what does this do kind instance method of code database code param --- callback a name module_duckdb database parallelize a database parallelize callback code void code todo what does this do kind instance method of code database code param --- callback a name module_duckdb database connect a database connect path code connection code create a new database connection kind instance method of code database code param description --- --- path the database to connect to either a file path or memory a name module_duckdb database interrupt a database interrupt callback code void code supposedly interrupt queries but currently does not do anything kind instance method of code database code param --- callback a name module_duckdb database prepare a database prepare sql code statement code prepare a sql query for execution kind instance method of code database code param --- sql a name module_duckdb database run a database run sql params callback code void code convenience method for connection run using a built-in default connection kind instance method of code database code param type --- --- sql params code code callback a name module_duckdb database scanarrowipc a database scanarrowipc sql params callback code void code convenience method for connection scanarrowipc using a built-in default connection kind instance method of code database code param type --- --- sql params code code callback a name module_duckdb database each a database each sql params callback code void code kind instance method of code database code param type --- --- sql params code code callback a name module_duckdb database all a database all sql params callback code void code convenience method for connection apply using a built-in default connection kind instance method of code database code param type --- --- sql params code code callback a name module_duckdb database arrowipcall a database arrowipcall sql params callback code void code convenience method for connection arrowipcall using a built-in default connection kind instance method of code database code param type --- --- sql params code code callback a name module_duckdb database arrowipcstream a database arrowipcstream sql params callback code void code convenience method for connection arrowipcstream using a built-in default connection kind instance method of code database code param type --- --- sql params code code callback a name module_duckdb database exec a database exec sql params callback code void code kind instance method of code database code param type --- --- sql params code code callback a name module_duckdb database register_udf a database register _ udf name return_type fun code this code register a user defined function convenience method for connection register_udf kind instance method of code database code param --- name return_type fun a name module_duckdb database register_buffer a database register _ buffer name code this code register a buffer containing serialized data to be scanned from duckdb convenience method for connection unregister_buffer kind instance method of code database code param --- name a name module_duckdb database unregister_buffer a database unregister _ buffer name code this code unregister a buffer convenience method for connection unregister_buffer kind instance method of code database code param --- name a name module_duckdb database unregister_udf a database unregister _ udf name code this code unregister a udf convenience method for connection unregister_udf kind instance method of code database code param --- name a name module_duckdb database registerreplacementscan a database registerreplacementscan fun code this code register a table replace scan function kind instance method of code database code param description --- --- fun replacement scan function a name module_duckdb database get a database get not implemented kind instance method of code database code a name module_duckdb error a duckdb error code number code check that errno attribute equals this to check for a duckdb error kind inner constant of code duckdb code a name module_duckdb open_readonly a duckdb open _ readonly code number code open database in readonly mode kind inner constant of code duckdb code a name module_duckdb open_readwrite a duckdb open _ readwrite code number code currently ignored kind inner constant of code duckdb code a name module_duckdb open_create a duckdb open _ create code number code currently ignored kind inner constant of code duckdb code a name module_duckdb open_fullmutex a duckdb open _ fullmutex code number code currently ignored kind inner constant of code duckdb code a name module_duckdb open_sharedcache a duckdb open _ sharedcache code number code currently ignored kind inner constant of code duckdb code a name module_duckdb open_privatecache a duckdb open _ privatecache code number code currently ignored kind inner constant of code duckdb code a name columninfo a columninfo code object code kind global typedef properties name type description --- --- --- name code string code column name type code typeinfo code column type a name typeinfo a typeinfo code object code kind global typedef properties name type description --- --- --- id code string code type id alias code string code sql type alias sql_type code string code sql type name a name duckdberror a duckdberror code object code kind global typedef properties name type description --- --- --- errno code number code -1 for duckdb errors message code string code error message code code string code duckdb_nodejs_error for duckdb errors errortype code string code duckdb error type code eg http io catalog a name httperror a httperror code object code kind global typedef extends code duckdberror code properties name type description --- --- --- statuscode code number code http response status code reason code string code http response reason response code string code http response body headers code object code http headers", + "text": "modules typedefs a name module_duckdb a duckdb summary duckdb is an embeddable sql olap database management system duckdb connection run sql params callback code void code all sql params callback code void code arrowipcall sql params callback code void code arrowipcstream sql params callback each sql params callback code void code stream sql params register_udf name return_type fun code void code prepare sql params callback code statement code exec sql params callback code void code register_udf_bulk name return_type callback code void code unregister_udf name return_type callback code void code register_buffer name array force callback code void code unregister_buffer name callback code void code statement sql get run sql params callback code void code all sql params callback code void code arrowipcall sql params callback code void code each sql params callback code void code finalize sql params callback code void code stream sql params columns code array lt columninfo gt code queryresult nextchunk nextipcbuffer asynciterator database close callback code void code close_internal callback code void code wait callback code void code serialize callback code void code parallelize callback code void code connect path code connection code interrupt callback code void code prepare sql code statement code run sql params callback code void code scanarrowipc sql params callback code void code each sql params callback code void code all sql params callback code void code arrowipcall sql params callback code void code arrowipcstream sql params callback code void code exec sql params callback code void code register_udf name return_type fun code this code register_buffer name code this code unregister_buffer name code this code unregister_udf name code this code registerreplacementscan fun code this code get error code number code open_readonly code number code open_readwrite code number code open_create code number code open_fullmutex code number code open_sharedcache code number code open_privatecache code number code a name module_duckdb connection a duckdb connection kind inner class of code duckdb code connection run sql params callback code void code all sql params callback code void code arrowipcall sql params callback code void code arrowipcstream sql params callback each sql params callback code void code stream sql params register_udf name return_type fun code void code prepare sql params callback code statement code exec sql params callback code void code register_udf_bulk name return_type callback code void code unregister_udf name return_type callback code void code register_buffer name array force callback code void code unregister_buffer name callback code void code a name module_duckdb connection run a connection run sql params callback code void code run a sql statement and trigger a callback when done kind instance method of code connection code param type --- --- sql params code code callback a name module_duckdb connection all a connection all sql params callback code void code run a sql query and triggers the callback once for all result rows kind instance method of code connection code param type --- --- sql params code code callback a name module_duckdb connection arrowipcall a connection arrowipcall sql params callback code void code run a sql query and serialize the result into the apache arrow ipc format requires arrow extension to be loaded kind instance method of code connection code param type --- --- sql params code code callback a name module_duckdb connection arrowipcstream a connection arrowipcstream sql params callback run a sql query returns a ipcresultstreamiterator that allows streaming the result into the apache arrow ipc format requires arrow extension to be loaded kind instance method of code connection code returns promise ipcresultstreamiterator param type --- --- sql params code code callback a name module_duckdb connection each a connection each sql params callback code void code runs a sql query and triggers the callback for each result row kind instance method of code connection code param type --- --- sql params code code callback a name module_duckdb connection stream a connection stream sql params kind instance method of code connection code param type --- --- sql params code code a name module_duckdb connection register_udf a connection register _ udf name return_type fun code void code register a user defined function kind instance method of code connection code note this follows the wasm udfs somewhat but is simpler because we can pass data much more cleanly param --- name return_type fun a name module_duckdb connection prepare a connection prepare sql params callback code statement code prepare a sql query for execution kind instance method of code connection code param type --- --- sql params code code callback a name module_duckdb connection exec a connection exec sql params callback code void code execute a sql query kind instance method of code connection code param type --- --- sql params code code callback a name module_duckdb connection register_udf_bulk a connection register _ udf _ bulk name return_type callback code void code register a user defined function kind instance method of code connection code param --- name return_type callback a name module_duckdb connection unregister_udf a connection unregister _ udf name return_type callback code void code unregister a user defined function kind instance method of code connection code param --- name return_type callback a name module_duckdb connection register_buffer a connection register _ buffer name array force callback code void code register a buffer to be scanned using the apache arrow ipc scanner requires arrow extension to be loaded kind instance method of code connection code param --- name array force callback a name module_duckdb connection unregister_buffer a connection unregister _ buffer name callback code void code unregister the buffer kind instance method of code connection code param --- name callback a name module_duckdb statement a duckdb statement kind inner class of code duckdb code statement sql get run sql params callback code void code all sql params callback code void code arrowipcall sql params callback code void code each sql params callback code void code finalize sql params callback code void code stream sql params columns code array lt columninfo gt code a name module_duckdb statement sql a statement sql kind instance property of code statement code returns sql contained in statement field a name module_duckdb statement get a statement get not implemented kind instance method of code statement code a name module_duckdb statement run a statement run sql params callback code void code kind instance method of code statement code param type --- --- sql params code code callback a name module_duckdb statement all a statement all sql params callback code void code kind instance method of code statement code param type --- --- sql params code code callback a name module_duckdb statement arrowipcall a statement arrowipcall sql params callback code void code kind instance method of code statement code param type --- --- sql params code code callback a name module_duckdb statement each a statement each sql params callback code void code kind instance method of code statement code param type --- --- sql params code code callback a name module_duckdb statement finalize a statement finalize sql params callback code void code kind instance method of code statement code param type --- --- sql params code code callback a name module_duckdb statement stream a statement stream sql params kind instance method of code statement code param type --- --- sql params code code a name module_duckdb statement columns a statement columns code array lt columninfo gt code kind instance method of code statement code returns code array lt columninfo gt code - - array of column names and types a name module_duckdb queryresult a duckdb queryresult kind inner class of code duckdb code queryresult nextchunk nextipcbuffer asynciterator a name module_duckdb queryresult nextchunk a queryresult nextchunk kind instance method of code queryresult code returns data chunk a name module_duckdb queryresult nextipcbuffer a queryresult nextipcbuffer function to fetch the next result blob of an arrow ipc stream in a zero-copy way requires arrow extension to be loaded kind instance method of code queryresult code returns data chunk a name module_duckdb queryresult asynciterator a queryresult asynciterator kind instance method of code queryresult code a name module_duckdb database a duckdb database main database interface kind inner property of code duckdb code param description --- --- path path to database file or memory for in-memory database access_mode access mode config the configuration object callback callback function database close callback code void code close_internal callback code void code wait callback code void code serialize callback code void code parallelize callback code void code connect path code connection code interrupt callback code void code prepare sql code statement code run sql params callback code void code scanarrowipc sql params callback code void code each sql params callback code void code all sql params callback code void code arrowipcall sql params callback code void code arrowipcstream sql params callback code void code exec sql params callback code void code register_udf name return_type fun code this code register_buffer name code this code unregister_buffer name code this code unregister_udf name code this code registerreplacementscan fun code this code get a name module_duckdb database close a database close callback code void code closes database instance kind instance method of code database code param --- callback a name module_duckdb database close_internal a database close _ internal callback code void code internal method do not use call connection close instead kind instance method of code database code param --- callback a name module_duckdb database wait a database wait callback code void code triggers callback when all scheduled database tasks have completed kind instance method of code database code param --- callback a name module_duckdb database serialize a database serialize callback code void code currently a no-op provided for sqlite compatibility kind instance method of code database code param --- callback a name module_duckdb database parallelize a database parallelize callback code void code currently a no-op provided for sqlite compatibility kind instance method of code database code param --- callback a name module_duckdb database connect a database connect path code connection code create a new database connection kind instance method of code database code param description --- --- path the database to connect to either a file path or memory a name module_duckdb database interrupt a database interrupt callback code void code supposedly interrupt queries but currently does not do anything kind instance method of code database code param --- callback a name module_duckdb database prepare a database prepare sql code statement code prepare a sql query for execution kind instance method of code database code param --- sql a name module_duckdb database run a database run sql params callback code void code convenience method for connection run using a built-in default connection kind instance method of code database code param type --- --- sql params code code callback a name module_duckdb database scanarrowipc a database scanarrowipc sql params callback code void code convenience method for connection scanarrowipc using a built-in default connection kind instance method of code database code param type --- --- sql params code code callback a name module_duckdb database each a database each sql params callback code void code kind instance method of code database code param type --- --- sql params code code callback a name module_duckdb database all a database all sql params callback code void code convenience method for connection apply using a built-in default connection kind instance method of code database code param type --- --- sql params code code callback a name module_duckdb database arrowipcall a database arrowipcall sql params callback code void code convenience method for connection arrowipcall using a built-in default connection kind instance method of code database code param type --- --- sql params code code callback a name module_duckdb database arrowipcstream a database arrowipcstream sql params callback code void code convenience method for connection arrowipcstream using a built-in default connection kind instance method of code database code param type --- --- sql params code code callback a name module_duckdb database exec a database exec sql params callback code void code kind instance method of code database code param type --- --- sql params code code callback a name module_duckdb database register_udf a database register _ udf name return_type fun code this code register a user defined function convenience method for connection register_udf kind instance method of code database code param --- name return_type fun a name module_duckdb database register_buffer a database register _ buffer name code this code register a buffer containing serialized data to be scanned from duckdb convenience method for connection unregister_buffer kind instance method of code database code param --- name a name module_duckdb database unregister_buffer a database unregister _ buffer name code this code unregister a buffer convenience method for connection unregister_buffer kind instance method of code database code param --- name a name module_duckdb database unregister_udf a database unregister _ udf name code this code unregister a udf convenience method for connection unregister_udf kind instance method of code database code param --- name a name module_duckdb database registerreplacementscan a database registerreplacementscan fun code this code register a table replace scan function kind instance method of code database code param description --- --- fun replacement scan function a name module_duckdb database get a database get not implemented kind instance method of code database code a name module_duckdb error a duckdb error code number code check that errno attribute equals this to check for a duckdb error kind inner constant of code duckdb code a name module_duckdb open_readonly a duckdb open _ readonly code number code open database in readonly mode kind inner constant of code duckdb code a name module_duckdb open_readwrite a duckdb open _ readwrite code number code currently ignored kind inner constant of code duckdb code a name module_duckdb open_create a duckdb open _ create code number code currently ignored kind inner constant of code duckdb code a name module_duckdb open_fullmutex a duckdb open _ fullmutex code number code currently ignored kind inner constant of code duckdb code a name module_duckdb open_sharedcache a duckdb open _ sharedcache code number code currently ignored kind inner constant of code duckdb code a name module_duckdb open_privatecache a duckdb open _ privatecache code number code currently ignored kind inner constant of code duckdb code a name columninfo a columninfo code object code kind global typedef properties name type description --- --- --- name code string code column name type code typeinfo code column type a name typeinfo a typeinfo code object code kind global typedef properties name type description --- --- --- id code string code type id alias code string code sql type alias sql_type code string code sql type name a name duckdberror a duckdberror code object code kind global typedef properties name type description --- --- --- errno code number code -1 for duckdb errors message code string code error message code code string code duckdb_nodejs_error for duckdb errors errortype code string code duckdb error type code eg http io catalog a name httperror a httperror code object code kind global typedef extends code duckdberror code properties name type description --- --- --- statuscode code number code http response status code reason code string code http response reason response code string code http response body headers code object code http headers", "category": "Nodejs", "url": "/docs/api/nodejs/reference", - "blurb": "Modules Typedefs duckdb Summary : these jsdoc annotations are still a work in progress -..." + "blurb": "Modules Typedefs duckdb Summary : DuckDB is an embeddable SQL OLAP Database Management..." }, { "title": "Numeric Functions", diff --git a/docs/api/c/api.md b/docs/api/c/api.md index cce5b24d559..4a9d1edef07 100644 --- a/docs/api/c/api.md +++ b/docs/api/c/api.md @@ -147,6 +147,7 @@ selected: API Reference duckdb_logical_type duckdb_create_list_type(duckdb_logical_type type); duckdb_logical_type duckdb_create_map_type(duckdb_logical_type key_type, duckdb_logical_type value_type); duckdb_logical_type duckdb_create_union_type(duckdb_logical_type member_types, const char **member_names, idx_t member_count); +duckdb_logical_type duckdb_create_struct_type(duckdb_logical_type *member_types, const char **member_names, idx_t member_count); duckdb_logical_type duckdb_create_decimal_type(uint8_t width, uint8_t scale); duckdb_type duckdb_get_type_id(duckdb_logical_type type); uint8_t duckdb_decimal_width(duckdb_logical_type type); @@ -2765,6 +2766,36 @@ The logical type.
+### duckdb_create_struct_type +--- +Creates a STRUCT type from the passed member name and type arrays. +The resulting type should be destroyed with `duckdb_destroy_logical_type`. + +#### Syntax +--- +
duckdb_logical_type duckdb_create_struct_type(
+  duckdb_logical_type *member_types,
+  const char **member_names,
+  idx_t member_count
+);
+
+#### Parameters +--- +* `member_types` + +The array of types that the struct should consist of. +* `member_names` + +The array of names that the struct should consist of. +* `member_count` + +The number of members that were specified for both arrays. +* `returns` + +The logical type. + +
+ ### duckdb_create_decimal_type --- Creates a `duckdb_logical_type` of type decimal with the specified width and scale diff --git a/docs/api/c/types.md b/docs/api/c/types.md index 93f369a6e23..418fa44cfee 100644 --- a/docs/api/c/types.md +++ b/docs/api/c/types.md @@ -115,6 +115,7 @@ For more information about data chunks, see the [documentation on data chunks](d duckdb_logical_type duckdb_create_list_type(duckdb_logical_type type); duckdb_logical_type duckdb_create_map_type(duckdb_logical_type key_type, duckdb_logical_type value_type); duckdb_logical_type duckdb_create_union_type(duckdb_logical_type member_types, const char **member_names, idx_t member_count); +duckdb_logical_type duckdb_create_struct_type(duckdb_logical_type *member_types, const char **member_names, idx_t member_count); duckdb_logical_type duckdb_create_decimal_type(uint8_t width, uint8_t scale); duckdb_type duckdb_get_type_id(duckdb_logical_type type); uint8_t duckdb_decimal_width(duckdb_logical_type type); @@ -938,6 +939,36 @@ The logical type.
+### duckdb_create_struct_type +--- +Creates a STRUCT type from the passed member name and type arrays. +The resulting type should be destroyed with `duckdb_destroy_logical_type`. + +#### Syntax +--- +
duckdb_logical_type duckdb_create_struct_type(
+  duckdb_logical_type *member_types,
+  const char **member_names,
+  idx_t member_count
+);
+
+#### Parameters +--- +* `member_types` + +The array of types that the struct should consist of. +* `member_names` + +The array of names that the struct should consist of. +* `member_count` + +The number of members that were specified for both arrays. +* `returns` + +The logical type. + +
+ ### duckdb_create_decimal_type --- Creates a `duckdb_logical_type` of type decimal with the specified width and scale diff --git a/docs/api/nodejs/reference.md b/docs/api/nodejs/reference.md index 3b1325ad1d7..d9922fe9d22 100644 --- a/docs/api/nodejs/reference.md +++ b/docs/api/nodejs/reference.md @@ -26,7 +26,7 @@ selected: Client APIs ## duckdb -**Summary**: these jsdoc annotations are still a work in progress - feedback and suggestions are welcome! +**Summary**: DuckDB is an embeddable SQL OLAP Database Management System * [duckdb](#module_duckdb) * [~Connection](#module_duckdb..Connection) @@ -476,7 +476,7 @@ Triggers callback when all scheduled database tasks have completed. #### database.serialize(callback) ⇒ void -TODO: what does this do? +Currently a no-op. Provided for SQLite compatibility **Kind**: instance method of [Database](#module_duckdb..Database) @@ -487,7 +487,7 @@ TODO: what does this do? #### database.parallelize(callback) ⇒ void -TODO: what does this do? +Currently a no-op. Provided for SQLite compatibility **Kind**: instance method of [Database](#module_duckdb..Database) From fd6ac8a577109612c5b46e48fa2e773fe64799c9 Mon Sep 17 00:00:00 2001 From: GitHub Actions Date: Mon, 18 Sep 2023 05:06:33 +0000 Subject: [PATCH 09/12] chore: auto update docs --- data/search_data.json | 16 +- docs/api/nodejs/reference.md | 13 ++ docs/api/python/reference/index.md | 225 +++++++++++++++++++++++++++-- 3 files changed, 234 insertions(+), 20 deletions(-) diff --git a/data/search_data.json b/data/search_data.json index 7a70c70be97..5a2661e1ca6 100644 --- a/data/search_data.json +++ b/data/search_data.json @@ -434,13 +434,6 @@ "url": "/docs/guides/sql_editors/dbeaver", "blurb": "How to set up DBeaver SQL IDE for DuckDB DBeaver is a powerful and popular desktop sql editor and integrated..." }, - { - "title": "Data Ingestion", - "text": "duckdb-wasm has multiple ways to import data depending on the format of the data there are two steps to import data into duckdb first the data file is imported into a local file system using register functions registeremptyfilebuffer registerfilebuffer registerfilehandle registerfiletext registerfileurl then the data file is imported into duckdb using insert functions insertarrowfromipcstream insertarrowtable insertcsvfrompath insertjsonfrompath or directly using from sql query using extensions like parquet or httpfs insert statements can also be used to import data data import open close connection create a new connection const c await db connect import data close the connection to release memory await c close apache arrow data can be inserted from an existing arrow table more example https arrow apache org docs js import tablefromarrays from apache-arrow const arrowtable tablefromarrays id 1 2 3 name john jane jack age 20 21 22 await c insertarrowtable arrowtable name arrow_table from a raw arrow ipc stream const streamresponse await fetch someapi const streamreader streamresponse body getreader const streaminserts while true const value done await streamreader read if done break streaminserts push c insertarrowfromipcstream value name streamed await promise all streaminserts csv from csv files interchangeable registerfile text buffer url handle const csvcontent 1 foo n2 bar n await db registerfiletext data csv csvcontent with typed insert options await db insertcsvfrompath data csv schema main name foo detect false header false delimiter columns col1 new arrow int32 col2 new arrow utf8 json from json documents in row-major format const jsonrowcontent col1 1 col2 foo col1 2 col2 bar await db registerfiletext rows json json stringify jsonrowcontent await c insertjsonfrompath rows json name rows or column-major format const jsoncolcontent col1 1 2 col2 foo bar await db registerfiletext columns json json stringify jsoncolcontent await c insertjsonfrompath columns json name columns from api const streamresponse await fetch someapi content json await db registerfilebuffer file json new uint8array await streamresponse arraybuffer await c insertjsonfrompath file json name jsoncontent parquet from parquet files local const pickedfile file letuserpickfile await db registerfilehandle local parquet pickedfile duckdbdataprotocol browser_filereader true remote await db registerfileurl remote parquet https origin remote parquet duckdbdataprotocol http false using fetch const res await fetch https origin remote parquet await db registerfilebuffer buffer parquet new uint8array await res arraybuffer by specifying urls in the sql text await c query create table direct as select from https origin remote parquet or by executing raw insert statements await c query insert into existing_table values 1 foo 2 bar httpfs by specifying urls in the sql text await c query create table direct as select from https origin remote parquet insert statement or by executing raw insert statements await c query insert into existing_table values 1 foo 2 bar", - "category": "Wasm", - "url": "/docs/api/wasm/data_ingestion", - "blurb": "DuckDB-Wasm has multiple ways to import data, depending on the format of the data. There are two steps to import data..." - }, { "title": "Data Ingestion", "text": "csv files csv files can be read using the read_csv function called either from within python or directly from within sql by default the read_csv function attempts to auto-detect the csv settings by sampling from the provided file import duckdb read from a file using fully auto-detected settings duckdb read_csv example csv read multiple csv files from a folder duckdb read_csv folder csv specify options on how the csv is formatted internally duckdb read_csv example csv header false sep override types of the first two columns duckdb read_csv example csv dtype int varchar use the experimental parallel csv reader duckdb read_csv example csv parallel true directly read a csv file from within sql duckdb sql select from example csv call read_csv from within sql duckdb sql select from read_csv_auto example csv see the csv loading page for more information parquet files parquet files can be read using the read_parquet function called either from within python or directly from within sql import duckdb read from a single parquet file duckdb read_parquet example parquet read multiple parquet files from a folder duckdb read_parquet folder parquet directly read a parquet file from within sql duckdb sql select from example parquet call read_parquet from within sql duckdb sql select from read_parquet example parquet see the parquet loading page for more information json files json files can be read using the read_json function called either from within python or directly from within sql by default the read_json function will automatically detect if a file contains newline-delimited json or regular json and will detect the schema of the objects stored within the json file import duckdb read from a single json file duckdb read_json example json read multiple json files from a folder duckdb read_json folder json directly read a json file from within sql duckdb sql select from example json call read_json from within sql duckdb sql select from read_json_auto example json dataframes arrow tables duckdb is automatically able to query a pandas dataframe polars dataframe or arrow object that is stored in a python variable by name duckdb supports querying multiple types of apache arrow objects including tables datasets recordbatchreaders and scanners see the python guides for more examples import duckdb import pandas as pd test_df pd dataframe from_dict i 1 2 3 4 j one two three four duckdb sql select from test_df fetchall 1 one 2 two 3 three 4 four duckdb also supports registering a dataframe or arrow object as a virtual table comparable to a sql view this is useful when querying a dataframe arrow object that is stored in another way as a class variable or a value in a dictionary below is a pandas example if your pandas dataframe is stored in another location here is an example of manually registering it import duckdb import pandas as pd my_dictionary my_dictionary test_df pd dataframe from_dict i 1 2 3 4 j one two three four duckdb register test_df_view my_dictionary test_df duckdb sql select from test_df_view fetchall 1 one 2 two 3 three 4 four you can also create a persistent table in duckdb from the contents of the dataframe or the view create a new table from the contents of a dataframe con execute create table test_df_table as select from test_df insert into an existing table from the contents of a dataframe con execute insert into test_df_table select from test_df pandas dataframes - object columns pandas dataframe columns of an object dtype require some special care since this stores values of arbitrary type to convert these columns to duckdb we first go through an analyze phase before converting the values in this analyze phase a sample of all the rows of the column are analyzed to determine the target type this sample size is by default set to 1000 if the type picked during the analyze step is wrong this will result in a failed to cast value error in which case you will need to increase the sample size the sample size can be changed by setting the pandas_analyze_sample config option example setting the sample size to 100000 duckdb default_connection execute set global pandas_analyze_sample 100000", @@ -448,6 +441,13 @@ "url": "/docs/api/python/data_ingestion", "blurb": "CSV Files CSV files can be read using the read_csv function, called either from within Python or directly from within..." }, + { + "title": "Data Ingestion", + "text": "duckdb-wasm has multiple ways to import data depending on the format of the data there are two steps to import data into duckdb first the data file is imported into a local file system using register functions registeremptyfilebuffer registerfilebuffer registerfilehandle registerfiletext registerfileurl then the data file is imported into duckdb using insert functions insertarrowfromipcstream insertarrowtable insertcsvfrompath insertjsonfrompath or directly using from sql query using extensions like parquet or httpfs insert statements can also be used to import data data import open close connection create a new connection const c await db connect import data close the connection to release memory await c close apache arrow data can be inserted from an existing arrow table more example https arrow apache org docs js import tablefromarrays from apache-arrow const arrowtable tablefromarrays id 1 2 3 name john jane jack age 20 21 22 await c insertarrowtable arrowtable name arrow_table from a raw arrow ipc stream const streamresponse await fetch someapi const streamreader streamresponse body getreader const streaminserts while true const value done await streamreader read if done break streaminserts push c insertarrowfromipcstream value name streamed await promise all streaminserts csv from csv files interchangeable registerfile text buffer url handle const csvcontent 1 foo n2 bar n await db registerfiletext data csv csvcontent with typed insert options await db insertcsvfrompath data csv schema main name foo detect false header false delimiter columns col1 new arrow int32 col2 new arrow utf8 json from json documents in row-major format const jsonrowcontent col1 1 col2 foo col1 2 col2 bar await db registerfiletext rows json json stringify jsonrowcontent await c insertjsonfrompath rows json name rows or column-major format const jsoncolcontent col1 1 2 col2 foo bar await db registerfiletext columns json json stringify jsoncolcontent await c insertjsonfrompath columns json name columns from api const streamresponse await fetch someapi content json await db registerfilebuffer file json new uint8array await streamresponse arraybuffer await c insertjsonfrompath file json name jsoncontent parquet from parquet files local const pickedfile file letuserpickfile await db registerfilehandle local parquet pickedfile duckdbdataprotocol browser_filereader true remote await db registerfileurl remote parquet https origin remote parquet duckdbdataprotocol http false using fetch const res await fetch https origin remote parquet await db registerfilebuffer buffer parquet new uint8array await res arraybuffer by specifying urls in the sql text await c query create table direct as select from https origin remote parquet or by executing raw insert statements await c query insert into existing_table values 1 foo 2 bar httpfs by specifying urls in the sql text await c query create table direct as select from https origin remote parquet insert statement or by executing raw insert statements await c query insert into existing_table values 1 foo 2 bar", + "category": "Wasm", + "url": "/docs/api/wasm/data_ingestion", + "blurb": "DuckDB-Wasm has multiple ways to import data, depending on the format of the data. There are two steps to import data..." + }, { "title": "Data Types", "text": "general-purpose data types the table below shows all the built-in general-purpose data types the alternatives listed in the aliases column can be used to refer to these types as well however note that the aliases are not part of the sql standard and hence might not be accepted by other database engines name aliases description --- --- --- bigint int8 long signed eight-byte integer bit bitstring string of 1 s and 0 s boolean bool logical logical boolean true false blob bytea binary varbinary variable-length binary data date calendar date year month day double float8 numeric decimal double precision floating-point number 8 bytes decimal prec scale fixed-precision number with the given width precision and scale hugeint signed sixteen-byte integer integer int4 int signed signed four-byte integer interval date time delta real float4 float single precision floating-point number 4 bytes smallint int2 short signed two-byte integer time time of day no time zone timestamp datetime combination of time and date timestamp with time zone timestamptz combination of time and date that uses the current time zone tinyint int1 signed one-byte integer ubigint unsigned eight-byte integer uinteger unsigned four-byte integer usmallint unsigned two-byte integer utinyint unsigned one-byte integer uuid uuid data type varchar char bpchar text string variable-length character string nested composite types duckdb supports four nested data types list struct map and union each supports different use cases and has a different structure name description rules when used in a column build from values define in ddl create --- --- --- --- --- list an ordered sequence of data values of the same type each row must have the same data type within each list but can have any number of elements 1 2 3 int struct a dictionary of multiple named values where each key is a string but the value can be a different type for each key each row must have the same keys i 42 j a struct i int j varchar map a dictionary of multiple named values each key having the same type and each value having the same type keys and values can be any type and can be different types from one another rows may have different keys map 1 2 a b map int varchar union a union of multiple alternative data types storing one of them in each value at a time a union also contains a discriminator tag value to inspect and access the currently set member type rows may be set to different member types of the union union_value num 2 union num int text varchar nesting list s struct s map s and union s can be arbitrarily nested to any depth so long as the type rules are observed -- struct with lists select birds duck goose heron aliens null amphibians frog toad -- struct with list of maps select test map 1 5 42 1 45 map 1 5 42 1 45 -- a list of unions select union_value num 2 union_value str abc union str varchar num integer links to detailed documentation", @@ -940,7 +940,7 @@ }, { "title": "NodeJS API", - "text": "modules typedefs a name module_duckdb a duckdb summary duckdb is an embeddable sql olap database management system duckdb connection run sql params callback code void code all sql params callback code void code arrowipcall sql params callback code void code arrowipcstream sql params callback each sql params callback code void code stream sql params register_udf name return_type fun code void code prepare sql params callback code statement code exec sql params callback code void code register_udf_bulk name return_type callback code void code unregister_udf name return_type callback code void code register_buffer name array force callback code void code unregister_buffer name callback code void code statement sql get run sql params callback code void code all sql params callback code void code arrowipcall sql params callback code void code each sql params callback code void code finalize sql params callback code void code stream sql params columns code array lt columninfo gt code queryresult nextchunk nextipcbuffer asynciterator database close callback code void code close_internal callback code void code wait callback code void code serialize callback code void code parallelize callback code void code connect path code connection code interrupt callback code void code prepare sql code statement code run sql params callback code void code scanarrowipc sql params callback code void code each sql params callback code void code all sql params callback code void code arrowipcall sql params callback code void code arrowipcstream sql params callback code void code exec sql params callback code void code register_udf name return_type fun code this code register_buffer name code this code unregister_buffer name code this code unregister_udf name code this code registerreplacementscan fun code this code get error code number code open_readonly code number code open_readwrite code number code open_create code number code open_fullmutex code number code open_sharedcache code number code open_privatecache code number code a name module_duckdb connection a duckdb connection kind inner class of code duckdb code connection run sql params callback code void code all sql params callback code void code arrowipcall sql params callback code void code arrowipcstream sql params callback each sql params callback code void code stream sql params register_udf name return_type fun code void code prepare sql params callback code statement code exec sql params callback code void code register_udf_bulk name return_type callback code void code unregister_udf name return_type callback code void code register_buffer name array force callback code void code unregister_buffer name callback code void code a name module_duckdb connection run a connection run sql params callback code void code run a sql statement and trigger a callback when done kind instance method of code connection code param type --- --- sql params code code callback a name module_duckdb connection all a connection all sql params callback code void code run a sql query and triggers the callback once for all result rows kind instance method of code connection code param type --- --- sql params code code callback a name module_duckdb connection arrowipcall a connection arrowipcall sql params callback code void code run a sql query and serialize the result into the apache arrow ipc format requires arrow extension to be loaded kind instance method of code connection code param type --- --- sql params code code callback a name module_duckdb connection arrowipcstream a connection arrowipcstream sql params callback run a sql query returns a ipcresultstreamiterator that allows streaming the result into the apache arrow ipc format requires arrow extension to be loaded kind instance method of code connection code returns promise ipcresultstreamiterator param type --- --- sql params code code callback a name module_duckdb connection each a connection each sql params callback code void code runs a sql query and triggers the callback for each result row kind instance method of code connection code param type --- --- sql params code code callback a name module_duckdb connection stream a connection stream sql params kind instance method of code connection code param type --- --- sql params code code a name module_duckdb connection register_udf a connection register _ udf name return_type fun code void code register a user defined function kind instance method of code connection code note this follows the wasm udfs somewhat but is simpler because we can pass data much more cleanly param --- name return_type fun a name module_duckdb connection prepare a connection prepare sql params callback code statement code prepare a sql query for execution kind instance method of code connection code param type --- --- sql params code code callback a name module_duckdb connection exec a connection exec sql params callback code void code execute a sql query kind instance method of code connection code param type --- --- sql params code code callback a name module_duckdb connection register_udf_bulk a connection register _ udf _ bulk name return_type callback code void code register a user defined function kind instance method of code connection code param --- name return_type callback a name module_duckdb connection unregister_udf a connection unregister _ udf name return_type callback code void code unregister a user defined function kind instance method of code connection code param --- name return_type callback a name module_duckdb connection register_buffer a connection register _ buffer name array force callback code void code register a buffer to be scanned using the apache arrow ipc scanner requires arrow extension to be loaded kind instance method of code connection code param --- name array force callback a name module_duckdb connection unregister_buffer a connection unregister _ buffer name callback code void code unregister the buffer kind instance method of code connection code param --- name callback a name module_duckdb statement a duckdb statement kind inner class of code duckdb code statement sql get run sql params callback code void code all sql params callback code void code arrowipcall sql params callback code void code each sql params callback code void code finalize sql params callback code void code stream sql params columns code array lt columninfo gt code a name module_duckdb statement sql a statement sql kind instance property of code statement code returns sql contained in statement field a name module_duckdb statement get a statement get not implemented kind instance method of code statement code a name module_duckdb statement run a statement run sql params callback code void code kind instance method of code statement code param type --- --- sql params code code callback a name module_duckdb statement all a statement all sql params callback code void code kind instance method of code statement code param type --- --- sql params code code callback a name module_duckdb statement arrowipcall a statement arrowipcall sql params callback code void code kind instance method of code statement code param type --- --- sql params code code callback a name module_duckdb statement each a statement each sql params callback code void code kind instance method of code statement code param type --- --- sql params code code callback a name module_duckdb statement finalize a statement finalize sql params callback code void code kind instance method of code statement code param type --- --- sql params code code callback a name module_duckdb statement stream a statement stream sql params kind instance method of code statement code param type --- --- sql params code code a name module_duckdb statement columns a statement columns code array lt columninfo gt code kind instance method of code statement code returns code array lt columninfo gt code - - array of column names and types a name module_duckdb queryresult a duckdb queryresult kind inner class of code duckdb code queryresult nextchunk nextipcbuffer asynciterator a name module_duckdb queryresult nextchunk a queryresult nextchunk kind instance method of code queryresult code returns data chunk a name module_duckdb queryresult nextipcbuffer a queryresult nextipcbuffer function to fetch the next result blob of an arrow ipc stream in a zero-copy way requires arrow extension to be loaded kind instance method of code queryresult code returns data chunk a name module_duckdb queryresult asynciterator a queryresult asynciterator kind instance method of code queryresult code a name module_duckdb database a duckdb database main database interface kind inner property of code duckdb code param description --- --- path path to database file or memory for in-memory database access_mode access mode config the configuration object callback callback function database close callback code void code close_internal callback code void code wait callback code void code serialize callback code void code parallelize callback code void code connect path code connection code interrupt callback code void code prepare sql code statement code run sql params callback code void code scanarrowipc sql params callback code void code each sql params callback code void code all sql params callback code void code arrowipcall sql params callback code void code arrowipcstream sql params callback code void code exec sql params callback code void code register_udf name return_type fun code this code register_buffer name code this code unregister_buffer name code this code unregister_udf name code this code registerreplacementscan fun code this code get a name module_duckdb database close a database close callback code void code closes database instance kind instance method of code database code param --- callback a name module_duckdb database close_internal a database close _ internal callback code void code internal method do not use call connection close instead kind instance method of code database code param --- callback a name module_duckdb database wait a database wait callback code void code triggers callback when all scheduled database tasks have completed kind instance method of code database code param --- callback a name module_duckdb database serialize a database serialize callback code void code currently a no-op provided for sqlite compatibility kind instance method of code database code param --- callback a name module_duckdb database parallelize a database parallelize callback code void code currently a no-op provided for sqlite compatibility kind instance method of code database code param --- callback a name module_duckdb database connect a database connect path code connection code create a new database connection kind instance method of code database code param description --- --- path the database to connect to either a file path or memory a name module_duckdb database interrupt a database interrupt callback code void code supposedly interrupt queries but currently does not do anything kind instance method of code database code param --- callback a name module_duckdb database prepare a database prepare sql code statement code prepare a sql query for execution kind instance method of code database code param --- sql a name module_duckdb database run a database run sql params callback code void code convenience method for connection run using a built-in default connection kind instance method of code database code param type --- --- sql params code code callback a name module_duckdb database scanarrowipc a database scanarrowipc sql params callback code void code convenience method for connection scanarrowipc using a built-in default connection kind instance method of code database code param type --- --- sql params code code callback a name module_duckdb database each a database each sql params callback code void code kind instance method of code database code param type --- --- sql params code code callback a name module_duckdb database all a database all sql params callback code void code convenience method for connection apply using a built-in default connection kind instance method of code database code param type --- --- sql params code code callback a name module_duckdb database arrowipcall a database arrowipcall sql params callback code void code convenience method for connection arrowipcall using a built-in default connection kind instance method of code database code param type --- --- sql params code code callback a name module_duckdb database arrowipcstream a database arrowipcstream sql params callback code void code convenience method for connection arrowipcstream using a built-in default connection kind instance method of code database code param type --- --- sql params code code callback a name module_duckdb database exec a database exec sql params callback code void code kind instance method of code database code param type --- --- sql params code code callback a name module_duckdb database register_udf a database register _ udf name return_type fun code this code register a user defined function convenience method for connection register_udf kind instance method of code database code param --- name return_type fun a name module_duckdb database register_buffer a database register _ buffer name code this code register a buffer containing serialized data to be scanned from duckdb convenience method for connection unregister_buffer kind instance method of code database code param --- name a name module_duckdb database unregister_buffer a database unregister _ buffer name code this code unregister a buffer convenience method for connection unregister_buffer kind instance method of code database code param --- name a name module_duckdb database unregister_udf a database unregister _ udf name code this code unregister a udf convenience method for connection unregister_udf kind instance method of code database code param --- name a name module_duckdb database registerreplacementscan a database registerreplacementscan fun code this code register a table replace scan function kind instance method of code database code param description --- --- fun replacement scan function a name module_duckdb database get a database get not implemented kind instance method of code database code a name module_duckdb error a duckdb error code number code check that errno attribute equals this to check for a duckdb error kind inner constant of code duckdb code a name module_duckdb open_readonly a duckdb open _ readonly code number code open database in readonly mode kind inner constant of code duckdb code a name module_duckdb open_readwrite a duckdb open _ readwrite code number code currently ignored kind inner constant of code duckdb code a name module_duckdb open_create a duckdb open _ create code number code currently ignored kind inner constant of code duckdb code a name module_duckdb open_fullmutex a duckdb open _ fullmutex code number code currently ignored kind inner constant of code duckdb code a name module_duckdb open_sharedcache a duckdb open _ sharedcache code number code currently ignored kind inner constant of code duckdb code a name module_duckdb open_privatecache a duckdb open _ privatecache code number code currently ignored kind inner constant of code duckdb code a name columninfo a columninfo code object code kind global typedef properties name type description --- --- --- name code string code column name type code typeinfo code column type a name typeinfo a typeinfo code object code kind global typedef properties name type description --- --- --- id code string code type id alias code string code sql type alias sql_type code string code sql type name a name duckdberror a duckdberror code object code kind global typedef properties name type description --- --- --- errno code number code -1 for duckdb errors message code string code error message code code string code duckdb_nodejs_error for duckdb errors errortype code string code duckdb error type code eg http io catalog a name httperror a httperror code object code kind global typedef extends code duckdberror code properties name type description --- --- --- statuscode code number code http response status code reason code string code http response reason response code string code http response body headers code object code http headers", + "text": "modules typedefs a name module_duckdb a duckdb summary duckdb is an embeddable sql olap database management system duckdb connection run sql params callback code void code all sql params callback code void code arrowipcall sql params callback code void code arrowipcstream sql params callback each sql params callback code void code stream sql params register_udf name return_type fun code void code prepare sql params callback code statement code exec sql params callback code void code register_udf_bulk name return_type callback code void code unregister_udf name return_type callback code void code register_buffer name array force callback code void code unregister_buffer name callback code void code close callback code void code statement sql get run sql params callback code void code all sql params callback code void code arrowipcall sql params callback code void code each sql params callback code void code finalize sql params callback code void code stream sql params columns code array lt columninfo gt code queryresult nextchunk nextipcbuffer asynciterator database close callback code void code close_internal callback code void code wait callback code void code serialize callback code void code parallelize callback code void code connect path code connection code interrupt callback code void code prepare sql code statement code run sql params callback code void code scanarrowipc sql params callback code void code each sql params callback code void code all sql params callback code void code arrowipcall sql params callback code void code arrowipcstream sql params callback code void code exec sql params callback code void code register_udf name return_type fun code this code register_buffer name code this code unregister_buffer name code this code unregister_udf name code this code registerreplacementscan fun code this code get error code number code open_readonly code number code open_readwrite code number code open_create code number code open_fullmutex code number code open_sharedcache code number code open_privatecache code number code a name module_duckdb connection a duckdb connection kind inner class of code duckdb code connection run sql params callback code void code all sql params callback code void code arrowipcall sql params callback code void code arrowipcstream sql params callback each sql params callback code void code stream sql params register_udf name return_type fun code void code prepare sql params callback code statement code exec sql params callback code void code register_udf_bulk name return_type callback code void code unregister_udf name return_type callback code void code register_buffer name array force callback code void code unregister_buffer name callback code void code close callback code void code a name module_duckdb connection run a connection run sql params callback code void code run a sql statement and trigger a callback when done kind instance method of code connection code param type --- --- sql params code code callback a name module_duckdb connection all a connection all sql params callback code void code run a sql query and triggers the callback once for all result rows kind instance method of code connection code param type --- --- sql params code code callback a name module_duckdb connection arrowipcall a connection arrowipcall sql params callback code void code run a sql query and serialize the result into the apache arrow ipc format requires arrow extension to be loaded kind instance method of code connection code param type --- --- sql params code code callback a name module_duckdb connection arrowipcstream a connection arrowipcstream sql params callback run a sql query returns a ipcresultstreamiterator that allows streaming the result into the apache arrow ipc format requires arrow extension to be loaded kind instance method of code connection code returns promise ipcresultstreamiterator param type --- --- sql params code code callback a name module_duckdb connection each a connection each sql params callback code void code runs a sql query and triggers the callback for each result row kind instance method of code connection code param type --- --- sql params code code callback a name module_duckdb connection stream a connection stream sql params kind instance method of code connection code param type --- --- sql params code code a name module_duckdb connection register_udf a connection register _ udf name return_type fun code void code register a user defined function kind instance method of code connection code note this follows the wasm udfs somewhat but is simpler because we can pass data much more cleanly param --- name return_type fun a name module_duckdb connection prepare a connection prepare sql params callback code statement code prepare a sql query for execution kind instance method of code connection code param type --- --- sql params code code callback a name module_duckdb connection exec a connection exec sql params callback code void code execute a sql query kind instance method of code connection code param type --- --- sql params code code callback a name module_duckdb connection register_udf_bulk a connection register _ udf _ bulk name return_type callback code void code register a user defined function kind instance method of code connection code param --- name return_type callback a name module_duckdb connection unregister_udf a connection unregister _ udf name return_type callback code void code unregister a user defined function kind instance method of code connection code param --- name return_type callback a name module_duckdb connection register_buffer a connection register _ buffer name array force callback code void code register a buffer to be scanned using the apache arrow ipc scanner requires arrow extension to be loaded kind instance method of code connection code param --- name array force callback a name module_duckdb connection unregister_buffer a connection unregister _ buffer name callback code void code unregister the buffer kind instance method of code connection code param --- name callback a name module_duckdb connection close a connection close callback code void code closes connection kind instance method of code connection code param --- callback a name module_duckdb statement a duckdb statement kind inner class of code duckdb code statement sql get run sql params callback code void code all sql params callback code void code arrowipcall sql params callback code void code each sql params callback code void code finalize sql params callback code void code stream sql params columns code array lt columninfo gt code a name module_duckdb statement sql a statement sql kind instance property of code statement code returns sql contained in statement field a name module_duckdb statement get a statement get not implemented kind instance method of code statement code a name module_duckdb statement run a statement run sql params callback code void code kind instance method of code statement code param type --- --- sql params code code callback a name module_duckdb statement all a statement all sql params callback code void code kind instance method of code statement code param type --- --- sql params code code callback a name module_duckdb statement arrowipcall a statement arrowipcall sql params callback code void code kind instance method of code statement code param type --- --- sql params code code callback a name module_duckdb statement each a statement each sql params callback code void code kind instance method of code statement code param type --- --- sql params code code callback a name module_duckdb statement finalize a statement finalize sql params callback code void code kind instance method of code statement code param type --- --- sql params code code callback a name module_duckdb statement stream a statement stream sql params kind instance method of code statement code param type --- --- sql params code code a name module_duckdb statement columns a statement columns code array lt columninfo gt code kind instance method of code statement code returns code array lt columninfo gt code - - array of column names and types a name module_duckdb queryresult a duckdb queryresult kind inner class of code duckdb code queryresult nextchunk nextipcbuffer asynciterator a name module_duckdb queryresult nextchunk a queryresult nextchunk kind instance method of code queryresult code returns data chunk a name module_duckdb queryresult nextipcbuffer a queryresult nextipcbuffer function to fetch the next result blob of an arrow ipc stream in a zero-copy way requires arrow extension to be loaded kind instance method of code queryresult code returns data chunk a name module_duckdb queryresult asynciterator a queryresult asynciterator kind instance method of code queryresult code a name module_duckdb database a duckdb database main database interface kind inner property of code duckdb code param description --- --- path path to database file or memory for in-memory database access_mode access mode config the configuration object callback callback function database close callback code void code close_internal callback code void code wait callback code void code serialize callback code void code parallelize callback code void code connect path code connection code interrupt callback code void code prepare sql code statement code run sql params callback code void code scanarrowipc sql params callback code void code each sql params callback code void code all sql params callback code void code arrowipcall sql params callback code void code arrowipcstream sql params callback code void code exec sql params callback code void code register_udf name return_type fun code this code register_buffer name code this code unregister_buffer name code this code unregister_udf name code this code registerreplacementscan fun code this code get a name module_duckdb database close a database close callback code void code closes database instance kind instance method of code database code param --- callback a name module_duckdb database close_internal a database close _ internal callback code void code internal method do not use call connection close instead kind instance method of code database code param --- callback a name module_duckdb database wait a database wait callback code void code triggers callback when all scheduled database tasks have completed kind instance method of code database code param --- callback a name module_duckdb database serialize a database serialize callback code void code currently a no-op provided for sqlite compatibility kind instance method of code database code param --- callback a name module_duckdb database parallelize a database parallelize callback code void code currently a no-op provided for sqlite compatibility kind instance method of code database code param --- callback a name module_duckdb database connect a database connect path code connection code create a new database connection kind instance method of code database code param description --- --- path the database to connect to either a file path or memory a name module_duckdb database interrupt a database interrupt callback code void code supposedly interrupt queries but currently does not do anything kind instance method of code database code param --- callback a name module_duckdb database prepare a database prepare sql code statement code prepare a sql query for execution kind instance method of code database code param --- sql a name module_duckdb database run a database run sql params callback code void code convenience method for connection run using a built-in default connection kind instance method of code database code param type --- --- sql params code code callback a name module_duckdb database scanarrowipc a database scanarrowipc sql params callback code void code convenience method for connection scanarrowipc using a built-in default connection kind instance method of code database code param type --- --- sql params code code callback a name module_duckdb database each a database each sql params callback code void code kind instance method of code database code param type --- --- sql params code code callback a name module_duckdb database all a database all sql params callback code void code convenience method for connection apply using a built-in default connection kind instance method of code database code param type --- --- sql params code code callback a name module_duckdb database arrowipcall a database arrowipcall sql params callback code void code convenience method for connection arrowipcall using a built-in default connection kind instance method of code database code param type --- --- sql params code code callback a name module_duckdb database arrowipcstream a database arrowipcstream sql params callback code void code convenience method for connection arrowipcstream using a built-in default connection kind instance method of code database code param type --- --- sql params code code callback a name module_duckdb database exec a database exec sql params callback code void code kind instance method of code database code param type --- --- sql params code code callback a name module_duckdb database register_udf a database register _ udf name return_type fun code this code register a user defined function convenience method for connection register_udf kind instance method of code database code param --- name return_type fun a name module_duckdb database register_buffer a database register _ buffer name code this code register a buffer containing serialized data to be scanned from duckdb convenience method for connection unregister_buffer kind instance method of code database code param --- name a name module_duckdb database unregister_buffer a database unregister _ buffer name code this code unregister a buffer convenience method for connection unregister_buffer kind instance method of code database code param --- name a name module_duckdb database unregister_udf a database unregister _ udf name code this code unregister a udf convenience method for connection unregister_udf kind instance method of code database code param --- name a name module_duckdb database registerreplacementscan a database registerreplacementscan fun code this code register a table replace scan function kind instance method of code database code param description --- --- fun replacement scan function a name module_duckdb database get a database get not implemented kind instance method of code database code a name module_duckdb error a duckdb error code number code check that errno attribute equals this to check for a duckdb error kind inner constant of code duckdb code a name module_duckdb open_readonly a duckdb open _ readonly code number code open database in readonly mode kind inner constant of code duckdb code a name module_duckdb open_readwrite a duckdb open _ readwrite code number code currently ignored kind inner constant of code duckdb code a name module_duckdb open_create a duckdb open _ create code number code currently ignored kind inner constant of code duckdb code a name module_duckdb open_fullmutex a duckdb open _ fullmutex code number code currently ignored kind inner constant of code duckdb code a name module_duckdb open_sharedcache a duckdb open _ sharedcache code number code currently ignored kind inner constant of code duckdb code a name module_duckdb open_privatecache a duckdb open _ privatecache code number code currently ignored kind inner constant of code duckdb code a name columninfo a columninfo code object code kind global typedef properties name type description --- --- --- name code string code column name type code typeinfo code column type a name typeinfo a typeinfo code object code kind global typedef properties name type description --- --- --- id code string code type id alias code string code sql type alias sql_type code string code sql type name a name duckdberror a duckdberror code object code kind global typedef properties name type description --- --- --- errno code number code -1 for duckdb errors message code string code error message code code string code duckdb_nodejs_error for duckdb errors errortype code string code duckdb error type code eg http io catalog a name httperror a httperror code object code kind global typedef extends code duckdberror code properties name type description --- --- --- statuscode code number code http response status code reason code string code http response reason response code string code http response body headers code object code http headers", "category": "Nodejs", "url": "/docs/api/nodejs/reference", "blurb": "Modules Typedefs duckdb Summary : DuckDB is an embeddable SQL OLAP Database Management..." diff --git a/docs/api/nodejs/reference.md b/docs/api/nodejs/reference.md index d9922fe9d22..d2c48b13f01 100644 --- a/docs/api/nodejs/reference.md +++ b/docs/api/nodejs/reference.md @@ -43,6 +43,7 @@ selected: Client APIs * [.unregister_udf(name, return_type, callback)](#module_duckdb..Connection+unregister_udf) ⇒ void * [.register_buffer(name, array, force, callback)](#module_duckdb..Connection+register_buffer) ⇒ void * [.unregister_buffer(name, callback)](#module_duckdb..Connection+unregister_buffer) ⇒ void + * [.close(callback)](#module_duckdb..Connection+close) ⇒ void * [~Statement](#module_duckdb..Statement) * [.sql](#module_duckdb..Statement+sql) ⇒ * [.get()](#module_duckdb..Statement+get) @@ -106,6 +107,7 @@ selected: Client APIs * [.unregister_udf(name, return_type, callback)](#module_duckdb..Connection+unregister_udf) ⇒ void * [.register_buffer(name, array, force, callback)](#module_duckdb..Connection+register_buffer) ⇒ void * [.unregister_buffer(name, callback)](#module_duckdb..Connection+unregister_buffer) ⇒ void + * [.close(callback)](#module_duckdb..Connection+close) ⇒ void @@ -277,6 +279,17 @@ Unregister the Buffer | name | | callback | + + +#### connection.close(callback) ⇒ void +Closes connection + +**Kind**: instance method of [Connection](#module_duckdb..Connection) + +| Param | +| --- | +| callback | + ### duckdb~Statement diff --git a/docs/api/python/reference/index.md b/docs/api/python/reference/index.md index d77f2c98d08..b3a7db9fcb6 100644 --- a/docs/api/python/reference/index.md +++ b/docs/api/python/reference/index.md @@ -53,6 +53,13 @@ title: Python Client API
+
+
+duckdb.CaseExpression(condition: duckdb.duckdb.Expression, value: duckdb.duckdb.Expression) → duckdb.duckdb.Expression +
+
+
+
exception duckdb.CastException @@ -71,6 +78,15 @@ title: Python Client API
+
+
+duckdb.ColumnExpression(name: str) → duckdb.duckdb.Expression +
+
+

Create a column reference from the provided column name

+
+
+
exception duckdb.ConnectionException @@ -80,6 +96,15 @@ title: Python Client API
+
+
+duckdb.ConstantExpression(value: object) → duckdb.duckdb.Expression +
+
+

Create a constant expression from the provided value

+
+
+
exception duckdb.ConstraintException @@ -597,6 +622,15 @@ title: Python Client API
+
+
+property rowcount +
+
+

Get result set row count

+
+
+
sql(self: duckdb.duckdb.DuckDBPyConnection, query: str, *, alias: str = '', params: object = None) → duckdb.duckdb.DuckDBPyRelation @@ -1065,7 +1099,7 @@ title: Python Client API
-filter(self: duckdb.duckdb.DuckDBPyRelation, filter_expr: str) → duckdb.duckdb.DuckDBPyRelation +filter(self: duckdb.duckdb.DuckDBPyRelation, filter_expr: object) → duckdb.duckdb.DuckDBPyRelation

Filter the relation object by the filter in filter_expr

@@ -1317,7 +1351,7 @@ title: Python Client API
-project(self: duckdb.duckdb.DuckDBPyRelation, project_expr: str) → duckdb.duckdb.DuckDBPyRelation +project(self: duckdb.duckdb.DuckDBPyRelation, *args) → duckdb.duckdb.DuckDBPyRelation

Project the relation object by the projection in project_expr

@@ -1396,6 +1430,15 @@ title: Python Client API
+
+
+select(self: duckdb.duckdb.DuckDBPyRelation, *args) → duckdb.duckdb.DuckDBPyRelation +
+
+

Project the relation object by the projection in project_expr

+
+
+
select_dtypes(self: duckdb.duckdb.DuckDBPyRelation, types: object) → duckdb.duckdb.DuckDBPyRelation @@ -1441,6 +1484,15 @@ title: Python Client API
+
+
+sort(self: duckdb.duckdb.DuckDBPyRelation, *args) → duckdb.duckdb.DuckDBPyRelation +
+
+

Reorder the relation object by the provided expressions

+
+
+
sql_query(self: duckdb.duckdb.DuckDBPyRelation) → str @@ -1718,6 +1770,126 @@ title: Python Client API
+
+
+class duckdb.Expression +
+
+

Bases: pybind11_object

+
+
+alias(self: duckdb.duckdb.Expression, arg0: str) → duckdb.duckdb.Expression +
+
+

Create a copy of this expression with the given alias.

+
+
+ +
+
+asc(self: duckdb.duckdb.Expression) → duckdb.duckdb.Expression +
+
+

Set the order by modifier to ASCENDING.

+
+
+ +
+
+cast(self: duckdb.duckdb.Expression, type: duckdb.duckdb.typing.DuckDBPyType) → duckdb.duckdb.Expression +
+
+

TODO: add docs.

+
+
+ +
+
+desc(self: duckdb.duckdb.Expression) → duckdb.duckdb.Expression +
+
+

Set the order by modifier to DESCENDING.

+
+
+ +
+
+isin(self: duckdb.duckdb.Expression, *args) → duckdb.duckdb.Expression +
+
+

Return a IN expression comparing self to the input arguments.

+
+
Returns:
+
+

DuckDBPyExpression: The compare IN expression

+
+
+
+
+ +
+
+isnotin(self: duckdb.duckdb.Expression, *args) → duckdb.duckdb.Expression +
+
+

Return a NOT IN expression comparing self to the input arguments.

+
+
Returns:
+
+

DuckDBPyExpression: The compare NOT IN expression

+
+
+
+
+ +
+
+nulls_first(self: duckdb.duckdb.Expression) → duckdb.duckdb.Expression +
+
+

Set the NULL order by modifier to NULLS FIRST.

+
+
+ +
+
+nulls_last(self: duckdb.duckdb.Expression) → duckdb.duckdb.Expression +
+
+

Set the NULL order by modifier to NULLS LAST.

+
+
+ +
+
+otherwise(self: duckdb.duckdb.Expression, value: duckdb.duckdb.Expression) → duckdb.duckdb.Expression +
+
+

TODO: add docs.

+
+
+ +
+
+show(self: duckdb.duckdb.Expression) → None +
+
+

Print the stringified version of the expression.

+
+
+ +
+
+when(self: duckdb.duckdb.Expression, condition: duckdb.duckdb.Expression, value: duckdb.duckdb.Expression) → duckdb.duckdb.Expression +
+
+

TODO: add docs.

+
+
+ +
+
+
exception duckdb.FatalException @@ -1727,6 +1899,13 @@ title: Python Client API
+
+
+duckdb.FunctionExpression(function_name: str, *args) → duckdb.duckdb.Expression +
+
+
+
exception duckdb.HTTPException @@ -1967,6 +2146,19 @@ title: Python Client API
+
+
+duckdb.StarExpression(*args, **kwargs) +
+
+

Overloaded function.

+
    +

  1. StarExpression(*, exclude: list = []) -> duckdb.duckdb.Expression

    2. +

  2. StarExpression() -> duckdb.duckdb.Expression

    3. +
+
+
+
exception duckdb.SyntaxException @@ -2144,7 +2336,7 @@ title: Python Client API

Overloaded function.

    -

  1. df(*, date_as_object: bool = False, connection: duckdb.DuckDBPyConnection = None) -> pandas.DataFrame

    2. +

  2. df(*, date_as_object: bool = False, connection: duckdb.DuckDBPyConnection = None) -> pandas.DataFrame

Fetch a result as DataFrame following execute()

    @@ -2341,11 +2533,11 @@ title: Python Client API

    Overloaded function.

      -

    1. from_parquet(file_glob: str, binary_as_string: bool = False, *, file_row_number: bool = False, filename: bool = False, hive_partitioning: bool = False, union_by_name: bool = False, compression: object = None, connection: duckdb.DuckDBPyConnection = None) -> duckdb.duckdb.DuckDBPyRelation

      2. +

    2. from_parquet(file_glob: str, binary_as_string: bool = False, *, file_row_number: bool = False, filename: bool = False, hive_partitioning: bool = False, union_by_name: bool = False, compression: object = None, connection: duckdb.DuckDBPyConnection = None) -> duckdb.duckdb.DuckDBPyRelation

    Create a relation object from the Parquet files in file_glob

      -

    1. from_parquet(file_globs: List[str], binary_as_string: bool = False, *, file_row_number: bool = False, filename: bool = False, hive_partitioning: bool = False, union_by_name: bool = False, compression: object = None, connection: duckdb.DuckDBPyConnection = None) -> duckdb.duckdb.DuckDBPyRelation

      2. +

    2. from_parquet(file_globs: List[str], binary_as_string: bool = False, *, file_row_number: bool = False, filename: bool = False, hive_partitioning: bool = False, union_by_name: bool = False, compression: object = None, connection: duckdb.DuckDBPyConnection = None) -> duckdb.duckdb.DuckDBPyRelation

    Create a relation object from the Parquet files in file_globs

    @@ -2393,11 +2585,11 @@ title: Python Client API

    Overloaded function.

      -

    1. get_substrait(query: str, connection: duckdb.DuckDBPyConnection = None, *, enable_optimizer: bool = True) -> duckdb.duckdb.DuckDBPyRelation

      2. +

    2. get_substrait(query: str, connection: duckdb.DuckDBPyConnection = None, *, enable_optimizer: bool = True) -> duckdb.duckdb.DuckDBPyRelation

    Serialize a query object to protobuf

      -

    1. get_substrait(query: str, connection: duckdb.DuckDBPyConnection = None, *, enable_optimizer: bool = True) -> duckdb.duckdb.DuckDBPyRelation

      2. +

    2. get_substrait(query: str, connection: duckdb.DuckDBPyConnection = None, *, enable_optimizer: bool = True) -> duckdb.duckdb.DuckDBPyRelation

    Serialize a query to protobuf

    @@ -2410,11 +2602,11 @@ title: Python Client API

    Overloaded function.

      -

    1. get_substrait_json(query: str, connection: duckdb.DuckDBPyConnection = None, *, enable_optimizer: bool = True) -> duckdb.duckdb.DuckDBPyRelation

      2. +

    2. get_substrait_json(query: str, connection: duckdb.DuckDBPyConnection = None, *, enable_optimizer: bool = True) -> duckdb.duckdb.DuckDBPyRelation

    Serialize a query object to protobuf

      -

    1. get_substrait_json(query: str, connection: duckdb.DuckDBPyConnection = None, *, enable_optimizer: bool = True) -> duckdb.duckdb.DuckDBPyRelation

      2. +

    2. get_substrait_json(query: str, connection: duckdb.DuckDBPyConnection = None, *, enable_optimizer: bool = True) -> duckdb.duckdb.DuckDBPyRelation

    Serialize a query to protobuf on the JSON format

    @@ -2512,7 +2704,7 @@ title: Python Client API
    -duckdb.project(df: pandas.DataFrame, project_expr: str, connection: duckdb.DuckDBPyConnection = None) → duckdb.duckdb.DuckDBPyRelation +duckdb.project(df: pandas.DataFrame, project_expr: object, connection: duckdb.DuckDBPyConnection = None) → duckdb.duckdb.DuckDBPyRelation

    Project the DataFrame df by the projection in project_expr

    @@ -2562,11 +2754,11 @@ title: Python Client API

    Overloaded function.

      -

    1. read_parquet(file_glob: str, binary_as_string: bool = False, *, file_row_number: bool = False, filename: bool = False, hive_partitioning: bool = False, union_by_name: bool = False, compression: object = None, connection: duckdb.DuckDBPyConnection = None) -> duckdb.duckdb.DuckDBPyRelation

      2. +

    2. read_parquet(file_glob: str, binary_as_string: bool = False, *, file_row_number: bool = False, filename: bool = False, hive_partitioning: bool = False, union_by_name: bool = False, compression: object = None, connection: duckdb.DuckDBPyConnection = None) -> duckdb.duckdb.DuckDBPyRelation

    Create a relation object from the Parquet files in file_glob

      -

    1. read_parquet(file_globs: List[str], binary_as_string: bool = False, *, file_row_number: bool = False, filename: bool = False, hive_partitioning: bool = False, union_by_name: bool = False, compression: object = None, connection: duckdb.DuckDBPyConnection = None) -> duckdb.duckdb.DuckDBPyRelation

      2. +

    2. read_parquet(file_globs: List[str], binary_as_string: bool = False, *, file_row_number: bool = False, filename: bool = False, hive_partitioning: bool = False, union_by_name: bool = False, compression: object = None, connection: duckdb.DuckDBPyConnection = None) -> duckdb.duckdb.DuckDBPyRelation

    Create a relation object from the Parquet files in file_globs

    @@ -2617,6 +2809,15 @@ title: Python Client API
+
+
+duckdb.rowcount(connection: duckdb.DuckDBPyConnection = None) → int +
+
+

Get result set row count

+
+
+
duckdb.sql(query: str, alias: str = '', connection: duckdb.DuckDBPyConnection = None) → duckdb.duckdb.DuckDBPyRelation From 599a0d5da7fbbadbef9bc124ba02441f2ab360f2 Mon Sep 17 00:00:00 2001 From: GitHub Actions Date: Mon, 25 Sep 2023 05:05:53 +0000 Subject: [PATCH 10/12] chore: auto update docs --- data/search_data.json | 4 ++-- docs/api/c/api.md | 6 +++--- docs/api/c/data_chunk.md | 6 +++--- 3 files changed, 8 insertions(+), 8 deletions(-) diff --git a/data/search_data.json b/data/search_data.json index 5a2661e1ca6..ad7ad4afac7 100644 --- a/data/search_data.json +++ b/data/search_data.json @@ -163,7 +163,7 @@ }, { "title": "C API - Complete API", - "text": "api reference open connect syntax path to the database file on disk or nullptr or memory to open an in-memory database out_database the result database object returns duckdbsuccess on success or duckdberror on failure duckdb_open_ext extended version of duckdb_open creates a new database or opens an existing database file stored at the the given path syntax path to the database file on disk or nullptr or memory to open an in-memory database out_database the result database object config optional configuration used to start up the database system out_error if set and the function returns duckdberror this will contain the reason why the start-up failed note that the error must be freed using duckdb_free returns duckdbsuccess on success or duckdberror on failure duckdb_close closes the specified database and de-allocates all memory allocated for that database this should be called after you are done with any database allocated through duckdb_open note that failing to call duckdb_close in case of e g a program crash will not cause data corruption still it is recommended to always correctly close a database object after you are done with it syntax the database object to shut down duckdb_connect opens a connection to a database connections are required to query the database and store transactional state associated with the connection the instantiated connection should be closed using duckdb_disconnect syntax the database file to connect to out_connection the result connection object returns duckdbsuccess on success or duckdberror on failure duckdb_interrupt interrupt running query syntax the connection to interruot duckdb_query_progress get progress of the running query syntax the working connection returns -1 if no progress or a percentage of the progress duckdb_disconnect closes the specified connection and de-allocates all memory allocated for that connection syntax the connection to close duckdb_library_version returns the version of the linked duckdb with a version postfix for dev versions usually used for developing c extensions that must return this for a compatibility check syntax duckdb_create_config initializes an empty configuration object that can be used to provide start-up options for the duckdb instance through duckdb_open_ext this will always succeed unless there is a malloc failure syntax the result configuration object returns duckdbsuccess on success or duckdberror on failure duckdb_config_count this returns the total amount of configuration options available for usage with duckdb_get_config_flag this should not be called in a loop as it internally loops over all the options syntax the amount of config options available duckdb_get_config_flag obtains a human-readable name and description of a specific configuration option this can be used to e g display configuration options this will succeed unless index is out of range i e duckdb_config_count the result name or description must not be freed syntax the index of the configuration option between 0 and duckdb_config_count out_name a name of the configuration flag out_description a description of the configuration flag returns duckdbsuccess on success or duckdberror on failure duckdb_set_config sets the specified option for the specified configuration the configuration option is indicated by name to obtain a list of config options see duckdb_get_config_flag in the source code configuration options are defined in config cpp this can fail if either the name is invalid or if the value provided for the option is invalid syntax the configuration object to set the option on name the name of the configuration flag to set option the value to set the configuration flag to returns duckdbsuccess on success or duckdberror on failure duckdb_destroy_config destroys the specified configuration option and de-allocates all memory allocated for the object syntax the configuration object to destroy duckdb_query executes a sql query within a connection and stores the full materialized result in the out_result pointer if the query fails to execute duckdberror is returned and the error message can be retrieved by calling duckdb_result_error note that after running duckdb_query duckdb_destroy_result must be called on the result object even if the query fails otherwise the error stored within the result will not be freed correctly syntax the connection to perform the query in query the sql query to run out_result the query result returns duckdbsuccess on success or duckdberror on failure duckdb_destroy_result closes the result and de-allocates all memory allocated for that connection syntax the result to destroy duckdb_column_name returns the column name of the specified column the result should not need be freed the column names will automatically be destroyed when the result is destroyed returns null if the column is out of range syntax the result object to fetch the column name from col the column index returns the column name of the specified column duckdb_column_type returns the column type of the specified column returns duckdb_type_invalid if the column is out of range syntax the result object to fetch the column type from col the column index returns the column type of the specified column duckdb_column_logical_type returns the logical column type of the specified column the return type of this call should be destroyed with duckdb_destroy_logical_type returns null if the column is out of range syntax the result object to fetch the column type from col the column index returns the logical column type of the specified column duckdb_column_count returns the number of columns present in a the result object syntax the result object returns the number of columns present in the result object duckdb_row_count returns the number of rows present in a the result object syntax the result object returns the number of rows present in the result object duckdb_rows_changed returns the number of rows changed by the query stored in the result this is relevant only for insert update delete queries for other queries the rows_changed will be 0 syntax the result object returns the number of rows changed duckdb_column_data deprecated prefer using duckdb_result_get_chunk instead returns the data of a specific column of a result in columnar format the function returns a dense array which contains the result data the exact type stored in the array depends on the corresponding duckdb_type as provided by duckdb_column_type for the exact type by which the data should be accessed see the comments in the types section or the duckdb_type enum for example for a column of type duckdb_type_integer rows can be accessed in the following manner int32_t data int32_t duckdb_column_data result 0 printf data for row d d n row data row syntax the result object to fetch the column data from col the column index returns the column data of the specified column duckdb_nullmask_data deprecated prefer using duckdb_result_get_chunk instead returns the nullmask of a specific column of a result in columnar format the nullmask indicates for every row whether or not the corresponding row is null if a row is null the values present in the array provided by duckdb_column_data are undefined int32_t data int32_t duckdb_column_data result 0 bool nullmask duckdb_nullmask_data result 0 if nullmask row printf data for row d null n row else printf data for row d d n row data row syntax the result object to fetch the nullmask from col the column index returns the nullmask of the specified column duckdb_result_error returns the error message contained within the result the error is only set if duckdb_query returns duckdberror the result of this function must not be freed it will be cleaned up when duckdb_destroy_result is called syntax the result object to fetch the error from returns the error of the result duckdb_result_get_chunk fetches a data chunk from the duckdb_result this function should be called repeatedly until the result is exhausted the result must be destroyed with duckdb_destroy_data_chunk this function supersedes all duckdb_value functions as well as the duckdb_column_data and duckdb_nullmask_data functions it results in significantly better performance and should be preferred in newer code-bases if this function is used none of the other result functions can be used and vice versa i e this function cannot be mixed with the legacy result functions use duckdb_result_chunk_count to figure out how many chunks there are in the result syntax the result object to fetch the data chunk from chunk_index the chunk index to fetch from returns the resulting data chunk returns null if the chunk index is out of bounds duckdb_result_is_streaming checks if the type of the internal result is streamqueryresult syntax the result object to check returns whether or not the result object is of the type streamqueryresult duckdb_result_chunk_count returns the number of data chunks present in the result syntax the result object returns number of data chunks present in the result duckdb_value_boolean syntax the boolean value at the specified location or false if the value cannot be converted duckdb_value_int8 syntax the int8_t value at the specified location or 0 if the value cannot be converted duckdb_value_int16 syntax the int16_t value at the specified location or 0 if the value cannot be converted duckdb_value_int32 syntax the int32_t value at the specified location or 0 if the value cannot be converted duckdb_value_int64 syntax the int64_t value at the specified location or 0 if the value cannot be converted duckdb_value_hugeint syntax the duckdb_hugeint value at the specified location or 0 if the value cannot be converted duckdb_value_decimal syntax the duckdb_decimal value at the specified location or 0 if the value cannot be converted duckdb_value_uint8 syntax the uint8_t value at the specified location or 0 if the value cannot be converted duckdb_value_uint16 syntax the uint16_t value at the specified location or 0 if the value cannot be converted duckdb_value_uint32 syntax the uint32_t value at the specified location or 0 if the value cannot be converted duckdb_value_uint64 syntax the uint64_t value at the specified location or 0 if the value cannot be converted duckdb_value_float syntax the float value at the specified location or 0 if the value cannot be converted duckdb_value_double syntax the double value at the specified location or 0 if the value cannot be converted duckdb_value_date syntax the duckdb_date value at the specified location or 0 if the value cannot be converted duckdb_value_time syntax the duckdb_time value at the specified location or 0 if the value cannot be converted duckdb_value_timestamp syntax the duckdb_timestamp value at the specified location or 0 if the value cannot be converted duckdb_value_interval syntax the duckdb_interval value at the specified location or 0 if the value cannot be converted duckdb_value_varchar syntax use duckdb_value_string instead this function does not work correctly if the string contains null bytes returns the text value at the specified location as a null-terminated string or nullptr if the value cannot be converted the result must be freed with duckdb_free duckdb_value_varchar_internal syntax use duckdb_value_string_internal instead this function does not work correctly if the string contains null bytes returns the char value at the specified location only works on varchar columns and does not auto-cast if the column is not a varchar column this function will return null the result must not be freed duckdb_value_string_internal syntax use duckdb_value_string_internal instead this function does not work correctly if the string contains null bytes returns the char value at the specified location only works on varchar columns and does not auto-cast if the column is not a varchar column this function will return null the result must not be freed duckdb_value_blob syntax the duckdb_blob value at the specified location returns a blob with blob data set to nullptr if the value cannot be converted the resulting blob data must be freed with duckdb_free duckdb_value_is_null syntax returns true if the value at the specified index is null and false otherwise duckdb_malloc allocate size bytes of memory using the duckdb internal malloc function any memory allocated in this manner should be freed using duckdb_free syntax the number of bytes to allocate returns a pointer to the allocated memory region duckdb_free free a value returned from duckdb_malloc duckdb_value_varchar or duckdb_value_blob syntax the memory region to de-allocate duckdb_vector_size the internal vector size used by duckdb this is the amount of tuples that will fit into a data chunk created by duckdb_create_data_chunk syntax the vector size duckdb_string_is_inlined whether or not the duckdb_string_t value is inlined this means that the data of the string does not have a separate allocation syntax duckdb_from_date decompose a duckdb_date object into year month and date stored as duckdb_date_struct syntax the date object as obtained from a duckdb_type_date column returns the duckdb_date_struct with the decomposed elements duckdb_to_date re-compose a duckdb_date from year month and date duckdb_date_struct syntax the year month and date stored in a duckdb_date_struct returns the duckdb_date element duckdb_from_time decompose a duckdb_time object into hour minute second and microsecond stored as duckdb_time_struct syntax the time object as obtained from a duckdb_type_time column returns the duckdb_time_struct with the decomposed elements duckdb_to_time re-compose a duckdb_time from hour minute second and microsecond duckdb_time_struct syntax the hour minute second and microsecond in a duckdb_time_struct returns the duckdb_time element duckdb_from_timestamp decompose a duckdb_timestamp object into a duckdb_timestamp_struct syntax the ts object as obtained from a duckdb_type_timestamp column returns the duckdb_timestamp_struct with the decomposed elements duckdb_to_timestamp re-compose a duckdb_timestamp from a duckdb_timestamp_struct syntax the de-composed elements in a duckdb_timestamp_struct returns the duckdb_timestamp element duckdb_hugeint_to_double converts a duckdb_hugeint object as obtained from a duckdb_type_hugeint column into a double syntax the hugeint value returns the converted double element duckdb_double_to_hugeint converts a double value to a duckdb_hugeint object if the conversion fails because the double value is too big the result will be 0 syntax the double value returns the converted duckdb_hugeint element duckdb_double_to_decimal converts a double value to a duckdb_decimal object if the conversion fails because the double value is too big or the width scale are invalid the result will be 0 syntax the double value returns the converted duckdb_decimal element duckdb_decimal_to_double converts a duckdb_decimal object as obtained from a duckdb_type_decimal column into a double syntax the decimal value returns the converted double element duckdb_prepare create a prepared statement object from a query note that after calling duckdb_prepare the prepared statement should always be destroyed using duckdb_destroy_prepare even if the prepare fails if the prepare fails duckdb_prepare_error can be called to obtain the reason why the prepare failed syntax the connection object query the sql query to prepare out_prepared_statement the resulting prepared statement object returns duckdbsuccess on success or duckdberror on failure duckdb_destroy_prepare closes the prepared statement and de-allocates all memory allocated for the statement syntax the prepared statement to destroy duckdb_prepare_error returns the error message associated with the given prepared statement if the prepared statement has no error message this returns nullptr instead the error message should not be freed it will be de-allocated when duckdb_destroy_prepare is called syntax the prepared statement to obtain the error from returns the error message or nullptr if there is none duckdb_nparams returns the number of parameters that can be provided to the given prepared statement returns 0 if the query was not successfully prepared syntax the prepared statement to obtain the number of parameters for duckdb_param_type returns the parameter type for the parameter at the given index returns duckdb_type_invalid if the parameter index is out of range or the statement was not successfully prepared syntax the prepared statement param_idx the parameter index returns the parameter type duckdb_clear_bindings clear the params bind to the prepared statement syntax duckdb_bind_value binds a value to the prepared statement at the specified index syntax duckdb_bind_parameter_index retrieve the index of the parameter for the prepared statement identified by name syntax duckdb_bind_boolean binds a bool value to the prepared statement at the specified index syntax duckdb_bind_int8 binds an int8_t value to the prepared statement at the specified index syntax duckdb_bind_int16 binds an int16_t value to the prepared statement at the specified index syntax duckdb_bind_int32 binds an int32_t value to the prepared statement at the specified index syntax duckdb_bind_int64 binds an int64_t value to the prepared statement at the specified index syntax duckdb_bind_hugeint binds an duckdb_hugeint value to the prepared statement at the specified index syntax duckdb_bind_decimal binds a duckdb_decimal value to the prepared statement at the specified index syntax duckdb_bind_uint8 binds an uint8_t value to the prepared statement at the specified index syntax duckdb_bind_uint16 binds an uint16_t value to the prepared statement at the specified index syntax duckdb_bind_uint32 binds an uint32_t value to the prepared statement at the specified index syntax duckdb_bind_uint64 binds an uint64_t value to the prepared statement at the specified index syntax duckdb_bind_float binds an float value to the prepared statement at the specified index syntax duckdb_bind_double binds an double value to the prepared statement at the specified index syntax duckdb_bind_date binds a duckdb_date value to the prepared statement at the specified index syntax duckdb_bind_time binds a duckdb_time value to the prepared statement at the specified index syntax duckdb_bind_timestamp binds a duckdb_timestamp value to the prepared statement at the specified index syntax duckdb_bind_interval binds a duckdb_interval value to the prepared statement at the specified index syntax duckdb_bind_varchar binds a null-terminated varchar value to the prepared statement at the specified index syntax duckdb_bind_varchar_length binds a varchar value to the prepared statement at the specified index syntax duckdb_bind_blob binds a blob value to the prepared statement at the specified index syntax duckdb_bind_null binds a null value to the prepared statement at the specified index syntax duckdb_execute_prepared executes the prepared statement with the given bound parameters and returns a materialized query result this method can be called multiple times for each prepared statement and the parameters can be modified between calls to this function syntax the prepared statement to execute out_result the query result returns duckdbsuccess on success or duckdberror on failure duckdb_execute_prepared_arrow executes the prepared statement with the given bound parameters and returns an arrow query result syntax the prepared statement to execute out_result the query result returns duckdbsuccess on success or duckdberror on failure duckdb_arrow_scan scans the arrow stream and creates a view with the given name syntax the connection on which to execute the scan table_name name of the temporary view to create arrow arrow stream wrapper returns duckdbsuccess on success or duckdberror on failure duckdb_arrow_array_scan scans the arrow array and creates a view with the given name syntax the connection on which to execute the scan table_name name of the temporary view to create arrow_schema arrow schema wrapper arrow_array arrow array wrapper out_stream output array stream that wraps around the passed schema for releasing deleting once done returns duckdbsuccess on success or duckdberror on failure duckdb_extract_statements extract all statements from a query note that after calling duckdb_extract_statements the extracted statements should always be destroyed using duckdb_destroy_extracted even if no statements were extracted if the extract fails duckdb_extract_statements_error can be called to obtain the reason why the extract failed syntax the connection object query the sql query to extract out_extracted_statements the resulting extracted statements object returns the number of extracted statements or 0 on failure duckdb_prepare_extracted_statement prepare an extracted statement note that after calling duckdb_prepare_extracted_statement the prepared statement should always be destroyed using duckdb_destroy_prepare even if the prepare fails if the prepare fails duckdb_prepare_error can be called to obtain the reason why the prepare failed syntax the connection object extracted_statements the extracted statements object index the index of the extracted statement to prepare out_prepared_statement the resulting prepared statement object returns duckdbsuccess on success or duckdberror on failure duckdb_extract_statements_error returns the error message contained within the extracted statements the result of this function must not be freed it will be cleaned up when duckdb_destroy_extracted is called syntax the extracted statements to fetch the error from returns the error of the extracted statements duckdb_destroy_extracted de-allocates all memory allocated for the extracted statements syntax the extracted statements to destroy duckdb_pending_prepared executes the prepared statement with the given bound parameters and returns a pending result the pending result represents an intermediate structure for a query that is not yet fully executed the pending result can be used to incrementally execute a query returning control to the client between tasks note that after calling duckdb_pending_prepared the pending result should always be destroyed using duckdb_destroy_pending even if this function returns duckdberror syntax the prepared statement to execute out_result the pending query result returns duckdbsuccess on success or duckdberror on failure duckdb_pending_prepared_streaming executes the prepared statement with the given bound parameters and returns a pending result this pending result will create a streaming duckdb_result when executed the pending result represents an intermediate structure for a query that is not yet fully executed note that after calling duckdb_pending_prepared_streaming the pending result should always be destroyed using duckdb_destroy_pending even if this function returns duckdberror syntax the prepared statement to execute out_result the pending query result returns duckdbsuccess on success or duckdberror on failure duckdb_destroy_pending closes the pending result and de-allocates all memory allocated for the result syntax the pending result to destroy duckdb_pending_error returns the error message contained within the pending result the result of this function must not be freed it will be cleaned up when duckdb_destroy_pending is called syntax the pending result to fetch the error from returns the error of the pending result duckdb_pending_execute_task executes a single task within the query returning whether or not the query is ready if this returns duckdb_pending_result_ready the duckdb_execute_pending function can be called to obtain the result if this returns duckdb_pending_result_not_ready the duckdb_pending_execute_task function should be called again if this returns duckdb_pending_error an error occurred during execution the error message can be obtained by calling duckdb_pending_error on the pending_result syntax the pending result to execute a task within returns the state of the pending result after the execution duckdb_execute_pending fully execute a pending query result returning the final query result if duckdb_pending_execute_task has been called until duckdb_pending_result_ready was returned this will return fast otherwise all remaining tasks must be executed first syntax the pending result to execute out_result the result object returns duckdbsuccess on success or duckdberror on failure duckdb_pending_execution_is_finished returns whether a duckdb_pending_state is finished executing for example if pending_state is duckdb_pending_result_ready this function will return true syntax the pending state on which to decide whether to finish execution returns boolean indicating pending execution should be considered finished duckdb_destroy_value destroys the value and de-allocates all memory allocated for that type syntax the value to destroy duckdb_create_varchar creates a value from a null-terminated string syntax the null-terminated string returns the value this must be destroyed with duckdb_destroy_value duckdb_create_varchar_length creates a value from a string syntax the text length the length of the text returns the value this must be destroyed with duckdb_destroy_value duckdb_create_int64 creates a value from an int64 syntax the bigint value returns the value this must be destroyed with duckdb_destroy_value duckdb_get_varchar obtains a string representation of the given value the result must be destroyed with duckdb_free syntax the value returns the string value this must be destroyed with duckdb_free duckdb_get_int64 obtains an int64 of the given value syntax the value returns the int64 value or 0 if no conversion is possible duckdb_create_logical_type creates a duckdb_logical_type from a standard primitive type the resulting type should be destroyed with duckdb_destroy_logical_type this should not be used with duckdb_type_decimal syntax the primitive type to create returns the logical type duckdb_create_list_type creates a list type from its child type the resulting type should be destroyed with duckdb_destroy_logical_type syntax the child type of list type to create returns the logical type duckdb_create_map_type creates a map type from its key type and value type the resulting type should be destroyed with duckdb_destroy_logical_type syntax the key type and value type of map type to create returns the logical type duckdb_create_union_type creates a union type from the passed types array the resulting type should be destroyed with duckdb_destroy_logical_type syntax the array of types that the union should consist of type_amount the size of the types array returns the logical type duckdb_create_struct_type creates a struct type from the passed member name and type arrays the resulting type should be destroyed with duckdb_destroy_logical_type syntax the array of types that the struct should consist of member_names the array of names that the struct should consist of member_count the number of members that were specified for both arrays returns the logical type duckdb_create_decimal_type creates a duckdb_logical_type of type decimal with the specified width and scale the resulting type should be destroyed with duckdb_destroy_logical_type syntax the width of the decimal type scale the scale of the decimal type returns the logical type duckdb_get_type_id retrieves the type class of a duckdb_logical_type syntax the logical type object returns the type id duckdb_decimal_width retrieves the width of a decimal type syntax the logical type object returns the width of the decimal type duckdb_decimal_scale retrieves the scale of a decimal type syntax the logical type object returns the scale of the decimal type duckdb_decimal_internal_type retrieves the internal storage type of a decimal type syntax the logical type object returns the internal type of the decimal type duckdb_enum_internal_type retrieves the internal storage type of an enum type syntax the logical type object returns the internal type of the enum type duckdb_enum_dictionary_size retrieves the dictionary size of the enum type syntax the logical type object returns the dictionary size of the enum type duckdb_enum_dictionary_value retrieves the dictionary value at the specified position from the enum the result must be freed with duckdb_free syntax the logical type object index the index in the dictionary returns the string value of the enum type must be freed with duckdb_free duckdb_list_type_child_type retrieves the child type of the given list type the result must be freed with duckdb_destroy_logical_type syntax the logical type object returns the child type of the list type must be destroyed with duckdb_destroy_logical_type duckdb_map_type_key_type retrieves the key type of the given map type the result must be freed with duckdb_destroy_logical_type syntax the logical type object returns the key type of the map type must be destroyed with duckdb_destroy_logical_type duckdb_map_type_value_type retrieves the value type of the given map type the result must be freed with duckdb_destroy_logical_type syntax the logical type object returns the value type of the map type must be destroyed with duckdb_destroy_logical_type duckdb_struct_type_child_count returns the number of children of a struct type syntax the logical type object returns the number of children of a struct type duckdb_struct_type_child_name retrieves the name of the struct child the result must be freed with duckdb_free syntax the logical type object index the child index returns the name of the struct type must be freed with duckdb_free duckdb_struct_type_child_type retrieves the child type of the given struct type at the specified index the result must be freed with duckdb_destroy_logical_type syntax the logical type object index the child index returns the child type of the struct type must be destroyed with duckdb_destroy_logical_type duckdb_union_type_member_count returns the number of members that the union type has syntax the logical type union object returns the number of members of a union type duckdb_union_type_member_name retrieves the name of the union member the result must be freed with duckdb_free syntax the logical type object index the child index returns the name of the union member must be freed with duckdb_free duckdb_union_type_member_type retrieves the child type of the given union member at the specified index the result must be freed with duckdb_destroy_logical_type syntax the logical type object index the child index returns the child type of the union member must be destroyed with duckdb_destroy_logical_type duckdb_destroy_logical_type destroys the logical type and de-allocates all memory allocated for that type syntax the logical type to destroy duckdb_create_data_chunk creates an empty datachunk with the specified set of types syntax an array of types of the data chunk column_count the number of columns returns the data chunk duckdb_destroy_data_chunk destroys the data chunk and de-allocates all memory allocated for that chunk syntax the data chunk to destroy duckdb_data_chunk_reset resets a data chunk clearing the validity masks and setting the cardinality of the data chunk to 0 syntax the data chunk to reset duckdb_data_chunk_get_column_count retrieves the number of columns in a data chunk syntax the data chunk to get the data from returns the number of columns in the data chunk duckdb_data_chunk_get_vector retrieves the vector at the specified column index in the data chunk the pointer to the vector is valid for as long as the chunk is alive it does not need to be destroyed syntax the data chunk to get the data from returns the vector duckdb_data_chunk_get_size retrieves the current number of tuples in a data chunk syntax the data chunk to get the data from returns the number of tuples in the data chunk duckdb_data_chunk_set_size sets the current number of tuples in a data chunk syntax the data chunk to set the size in size the number of tuples in the data chunk duckdb_vector_get_column_type retrieves the column type of the specified vector the result must be destroyed with duckdb_destroy_logical_type syntax the vector get the data from returns the type of the vector duckdb_vector_get_data retrieves the data pointer of the vector the data pointer can be used to read or write values from the vector how to read or write values depends on the type of the vector syntax the vector to get the data from returns the data pointer duckdb_vector_get_validity retrieves the validity mask pointer of the specified vector if all values are valid this function might return null the validity mask is a bitset that signifies null-ness within the data chunk it is a series of uint64_t values where each uint64_t value contains validity for 64 tuples the bit is set to 1 if the value is valid i e not null or 0 if the value is invalid i e null validity of a specific value can be obtained like this idx_t entry_idx row_idx 64 idx_t idx_in_entry row_idx 64 bool is_valid validity_mask entry_idx 1 idx_in_entry alternatively the slower duckdb_validity_row_is_valid function can be used syntax the vector to get the data from returns the pointer to the validity mask or null if no validity mask is present duckdb_vector_ensure_validity_writable ensures the validity mask is writable by allocating it after this function is called duckdb_vector_get_validity will always return non-null this allows null values to be written to the vector regardless of whether a validity mask was present before syntax the vector to alter duckdb_vector_assign_string_element assigns a string element in the vector at the specified location syntax the vector to alter index the row position in the vector to assign the string to str the null-terminated string duckdb_vector_assign_string_element_len assigns a string element in the vector at the specified location syntax the vector to alter index the row position in the vector to assign the string to str the string str_len the length of the string in bytes duckdb_list_vector_get_child retrieves the child vector of a list vector the resulting vector is valid as long as the parent vector is valid syntax the vector returns the child vector duckdb_list_vector_get_size returns the size of the child vector of the list syntax the vector returns the size of the child list duckdb_list_vector_set_size sets the total size of the underlying child-vector of a list vector syntax the list vector size the size of the child list returns the duckdb state returns duckdberror if the vector is nullptr duckdb_list_vector_reserve sets the total capacity of the underlying child-vector of a list syntax the list vector required_capacity the total capacity to reserve return the duckdb state returns duckdberror if the vector is nullptr duckdb_struct_vector_get_child retrieves the child vector of a struct vector the resulting vector is valid as long as the parent vector is valid syntax the vector index the child index returns the child vector duckdb_validity_row_is_valid returns whether or not a row is valid i e not null in the given validity mask syntax the validity mask as obtained through duckdb_data_chunk_get_validity row the row index returns true if the row is valid false otherwise duckdb_validity_set_row_validity in a validity mask sets a specific row to either valid or invalid note that duckdb_data_chunk_ensure_validity_writable should be called before calling duckdb_data_chunk_get_validity to ensure that there is a validity mask to write to syntax the validity mask as obtained through duckdb_data_chunk_get_validity row the row index valid whether or not to set the row to valid or invalid duckdb_validity_set_row_invalid in a validity mask sets a specific row to invalid equivalent to duckdb_validity_set_row_validity with valid set to false syntax the validity mask row the row index duckdb_validity_set_row_valid in a validity mask sets a specific row to valid equivalent to duckdb_validity_set_row_validity with valid set to true syntax the validity mask row the row index duckdb_create_table_function creates a new empty table function the return value should be destroyed with duckdb_destroy_table_function syntax the table function object duckdb_destroy_table_function destroys the given table function object syntax the table function to destroy duckdb_table_function_set_name sets the name of the given table function syntax the table function name the name of the table function duckdb_table_function_add_parameter adds a parameter to the table function syntax 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 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 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 the table function bind the bind function duckdb_table_function_set_init sets the init function of the table function syntax the table function init the init function duckdb_table_function_set_local_init sets the thread-local init function of the table function syntax the table function init the init function duckdb_table_function_set_function sets the main function of the table function syntax 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 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 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 the info object returns the extra info duckdb_bind_add_result_column adds a result column to the output of the table function syntax 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 the info object returns the init data object duckdb_function_set_error report that an error has occurred while executing the function syntax the info object error the error message duckdb_add_replacement_scan add a replacement scan definition to the specified database syntax the database object to add the replacement scan to replacement the replacement scan callback extra_data extra data that is passed back into the specified callback delete_callback the delete callback to call on the extra data if any duckdb_replacement_scan_set_function_name sets the replacement function name to use if this function is called in the replacement callback the replacement scan is performed if it is not called the replacement callback is not performed syntax the info object function_name the function name to substitute duckdb_replacement_scan_add_parameter adds a parameter to the replacement scan function syntax the info object parameter the parameter to add duckdb_replacement_scan_set_error report that an error has occurred while executing the replacement scan syntax the info object error the error message duckdb_appender_create creates an appender object syntax the connection context to create the appender in schema the schema of the table to append to or nullptr for the default schema table the table name to append to out_appender the resulting appender object returns duckdbsuccess on success or duckdberror on failure duckdb_appender_error returns the error message associated with the given appender if the appender has no error message this returns nullptr instead the error message should not be freed it will be de-allocated when duckdb_appender_destroy is called syntax the appender to get the error from returns the error message or nullptr if there is none duckdb_appender_flush flush the appender to the table forcing the cache of the appender to be cleared and the data to be appended to the base table this should generally not be used unless you know what you are doing instead call duckdb_appender_destroy when you are done with the appender syntax the appender to flush returns duckdbsuccess on success or duckdberror on failure duckdb_appender_close close the appender flushing all intermediate state in the appender to the table and closing it for further appends this is generally not necessary call duckdb_appender_destroy instead syntax the appender to flush and close returns duckdbsuccess on success or duckdberror on failure duckdb_appender_destroy close the appender and destroy it flushing all intermediate state in the appender to the table and de-allocating all memory associated with the appender syntax the appender to flush close and destroy returns duckdbsuccess on success or duckdberror on failure duckdb_appender_begin_row a nop function provided for backwards compatibility reasons does nothing only duckdb_appender_end_row is required syntax duckdb_appender_end_row finish the current row of appends after end_row is called the next row can be appended syntax the appender returns duckdbsuccess on success or duckdberror on failure duckdb_append_bool append a bool value to the appender syntax duckdb_append_int8 append an int8_t value to the appender syntax duckdb_append_int16 append an int16_t value to the appender syntax duckdb_append_int32 append an int32_t value to the appender syntax duckdb_append_int64 append an int64_t value to the appender syntax duckdb_append_hugeint append a duckdb_hugeint value to the appender syntax duckdb_append_uint8 append a uint8_t value to the appender syntax duckdb_append_uint16 append a uint16_t value to the appender syntax duckdb_append_uint32 append a uint32_t value to the appender syntax duckdb_append_uint64 append a uint64_t value to the appender syntax duckdb_append_float append a float value to the appender syntax duckdb_append_double append a double value to the appender syntax duckdb_append_date append a duckdb_date value to the appender syntax duckdb_append_time append a duckdb_time value to the appender syntax duckdb_append_timestamp append a duckdb_timestamp value to the appender syntax duckdb_append_interval append a duckdb_interval value to the appender syntax duckdb_append_varchar append a varchar value to the appender syntax duckdb_append_varchar_length append a varchar value to the appender syntax duckdb_append_blob append a blob value to the appender syntax duckdb_append_null append a null value to the appender of any type syntax duckdb_append_data_chunk appends a pre-filled data chunk to the specified appender the types of the data chunk must exactly match the types of the table no casting is performed if the types do not match or the appender is in an invalid state duckdberror is returned if the append is successful duckdbsuccess is returned syntax the appender to append to chunk the data chunk to append returns the return state duckdb_query_arrow executes a sql query within a connection and stores the full materialized result in an arrow structure if the query fails to execute duckdberror is returned and the error message can be retrieved by calling duckdb_query_arrow_error note that after running duckdb_query_arrow duckdb_destroy_arrow must be called on the result object even if the query fails otherwise the error stored within the result will not be freed correctly syntax the connection to perform the query in query the sql query to run out_result the query result returns duckdbsuccess on success or duckdberror on failure duckdb_query_arrow_schema fetch the internal arrow schema from the arrow result syntax the result to fetch the schema from out_schema the output schema returns duckdbsuccess on success or duckdberror on failure duckdb_prepared_arrow_schema fetch the internal arrow schema from the prepared statement syntax the prepared statement to fetch the schema from out_schema the output schema returns duckdbsuccess on success or duckdberror on failure duckdb_query_arrow_array fetch an internal arrow array from the arrow result this function can be called multiple time to get next chunks which will free the previous out_array so consume the out_array before calling this function again syntax the result to fetch the array from out_array the output array returns duckdbsuccess on success or duckdberror on failure duckdb_arrow_column_count returns the number of columns present in a the arrow result object syntax the result object returns the number of columns present in the result object duckdb_arrow_row_count returns the number of rows present in a the arrow result object syntax the result object returns the number of rows present in the result object duckdb_arrow_rows_changed returns the number of rows changed by the query stored in the arrow result this is relevant only for insert update delete queries for other queries the rows_changed will be 0 syntax the result object returns the number of rows changed duckdb_query_arrow_error returns the error message contained within the result the error is only set if duckdb_query_arrow returns duckdberror the error message should not be freed it will be de-allocated when duckdb_destroy_arrow is called syntax the result object to fetch the nullmask from returns the error of the result duckdb_destroy_arrow closes the result and de-allocates all memory allocated for the arrow result syntax the result to destroy duckdb_execute_tasks execute duckdb tasks on this thread will return after max_tasks have been executed or if there are no more tasks present syntax the database object to execute tasks for max_tasks the maximum amount of tasks to execute duckdb_create_task_state creates a task state that can be used with duckdb_execute_tasks_state to execute tasks until duckdb_finish_execution is called on the state duckdb_destroy_state should be called on the result in order to free memory syntax the database object to create the task state for returns the task state that can be used with duckdb_execute_tasks_state duckdb_execute_tasks_state execute duckdb tasks on this thread the thread will keep on executing tasks forever until duckdb_finish_execution is called on the state multiple threads can share the same duckdb_task_state syntax the task state of the executor duckdb_execute_n_tasks_state execute duckdb tasks on this thread the thread will keep on executing tasks until either duckdb_finish_execution is called on the state max_tasks tasks have been executed or there are no more tasks to be executed multiple threads can share the same duckdb_task_state syntax the task state of the executor max_tasks the maximum amount of tasks to execute returns the amount of tasks that have actually been executed duckdb_finish_execution finish execution on a specific task syntax the task state to finish execution duckdb_task_state_is_finished check if the provided duckdb_task_state has finished execution syntax the task state to inspect returns whether or not duckdb_finish_execution has been called on the task state duckdb_destroy_task_state destroys the task state returned from duckdb_create_task_state note that this should not be called while there is an active duckdb_execute_tasks_state running on the task state syntax the task state to clean up duckdb_execution_is_finished returns true if execution of the current query is finished syntax the connection on which to check duckdb_stream_fetch_chunk fetches a data chunk from the streaming duckdb_result this function should be called repeatedly until the result is exhausted the result must be destroyed with duckdb_destroy_data_chunk this function can only be used on duckdb_results created with duckdb_pending_prepared_streaming if this function is used none of the other result functions can be used and vice versa i e this function cannot be mixed with the legacy result functions or the materialized result functions it is not known beforehand how many chunks will be returned by this result syntax the result object to fetch the data chunk from returns the resulting data chunk returns null if the result has an error", + "text": "api reference open connect syntax path to the database file on disk or nullptr or memory to open an in-memory database out_database the result database object returns duckdbsuccess on success or duckdberror on failure duckdb_open_ext extended version of duckdb_open creates a new database or opens an existing database file stored at the the given path syntax path to the database file on disk or nullptr or memory to open an in-memory database out_database the result database object config optional configuration used to start up the database system out_error if set and the function returns duckdberror this will contain the reason why the start-up failed note that the error must be freed using duckdb_free returns duckdbsuccess on success or duckdberror on failure duckdb_close closes the specified database and de-allocates all memory allocated for that database this should be called after you are done with any database allocated through duckdb_open note that failing to call duckdb_close in case of e g a program crash will not cause data corruption still it is recommended to always correctly close a database object after you are done with it syntax the database object to shut down duckdb_connect opens a connection to a database connections are required to query the database and store transactional state associated with the connection the instantiated connection should be closed using duckdb_disconnect syntax the database file to connect to out_connection the result connection object returns duckdbsuccess on success or duckdberror on failure duckdb_interrupt interrupt running query syntax the connection to interruot duckdb_query_progress get progress of the running query syntax the working connection returns -1 if no progress or a percentage of the progress duckdb_disconnect closes the specified connection and de-allocates all memory allocated for that connection syntax the connection to close duckdb_library_version returns the version of the linked duckdb with a version postfix for dev versions usually used for developing c extensions that must return this for a compatibility check syntax duckdb_create_config initializes an empty configuration object that can be used to provide start-up options for the duckdb instance through duckdb_open_ext this will always succeed unless there is a malloc failure syntax the result configuration object returns duckdbsuccess on success or duckdberror on failure duckdb_config_count this returns the total amount of configuration options available for usage with duckdb_get_config_flag this should not be called in a loop as it internally loops over all the options syntax the amount of config options available duckdb_get_config_flag obtains a human-readable name and description of a specific configuration option this can be used to e g display configuration options this will succeed unless index is out of range i e duckdb_config_count the result name or description must not be freed syntax the index of the configuration option between 0 and duckdb_config_count out_name a name of the configuration flag out_description a description of the configuration flag returns duckdbsuccess on success or duckdberror on failure duckdb_set_config sets the specified option for the specified configuration the configuration option is indicated by name to obtain a list of config options see duckdb_get_config_flag in the source code configuration options are defined in config cpp this can fail if either the name is invalid or if the value provided for the option is invalid syntax the configuration object to set the option on name the name of the configuration flag to set option the value to set the configuration flag to returns duckdbsuccess on success or duckdberror on failure duckdb_destroy_config destroys the specified configuration option and de-allocates all memory allocated for the object syntax the configuration object to destroy duckdb_query executes a sql query within a connection and stores the full materialized result in the out_result pointer if the query fails to execute duckdberror is returned and the error message can be retrieved by calling duckdb_result_error note that after running duckdb_query duckdb_destroy_result must be called on the result object even if the query fails otherwise the error stored within the result will not be freed correctly syntax the connection to perform the query in query the sql query to run out_result the query result returns duckdbsuccess on success or duckdberror on failure duckdb_destroy_result closes the result and de-allocates all memory allocated for that connection syntax the result to destroy duckdb_column_name returns the column name of the specified column the result should not need be freed the column names will automatically be destroyed when the result is destroyed returns null if the column is out of range syntax the result object to fetch the column name from col the column index returns the column name of the specified column duckdb_column_type returns the column type of the specified column returns duckdb_type_invalid if the column is out of range syntax the result object to fetch the column type from col the column index returns the column type of the specified column duckdb_column_logical_type returns the logical column type of the specified column the return type of this call should be destroyed with duckdb_destroy_logical_type returns null if the column is out of range syntax the result object to fetch the column type from col the column index returns the logical column type of the specified column duckdb_column_count returns the number of columns present in a the result object syntax the result object returns the number of columns present in the result object duckdb_row_count returns the number of rows present in a the result object syntax the result object returns the number of rows present in the result object duckdb_rows_changed returns the number of rows changed by the query stored in the result this is relevant only for insert update delete queries for other queries the rows_changed will be 0 syntax the result object returns the number of rows changed duckdb_column_data deprecated prefer using duckdb_result_get_chunk instead returns the data of a specific column of a result in columnar format the function returns a dense array which contains the result data the exact type stored in the array depends on the corresponding duckdb_type as provided by duckdb_column_type for the exact type by which the data should be accessed see the comments in the types section or the duckdb_type enum for example for a column of type duckdb_type_integer rows can be accessed in the following manner int32_t data int32_t duckdb_column_data result 0 printf data for row d d n row data row syntax the result object to fetch the column data from col the column index returns the column data of the specified column duckdb_nullmask_data deprecated prefer using duckdb_result_get_chunk instead returns the nullmask of a specific column of a result in columnar format the nullmask indicates for every row whether or not the corresponding row is null if a row is null the values present in the array provided by duckdb_column_data are undefined int32_t data int32_t duckdb_column_data result 0 bool nullmask duckdb_nullmask_data result 0 if nullmask row printf data for row d null n row else printf data for row d d n row data row syntax the result object to fetch the nullmask from col the column index returns the nullmask of the specified column duckdb_result_error returns the error message contained within the result the error is only set if duckdb_query returns duckdberror the result of this function must not be freed it will be cleaned up when duckdb_destroy_result is called syntax the result object to fetch the error from returns the error of the result duckdb_result_get_chunk fetches a data chunk from the duckdb_result this function should be called repeatedly until the result is exhausted the result must be destroyed with duckdb_destroy_data_chunk this function supersedes all duckdb_value functions as well as the duckdb_column_data and duckdb_nullmask_data functions it results in significantly better performance and should be preferred in newer code-bases if this function is used none of the other result functions can be used and vice versa i e this function cannot be mixed with the legacy result functions use duckdb_result_chunk_count to figure out how many chunks there are in the result syntax the result object to fetch the data chunk from chunk_index the chunk index to fetch from returns the resulting data chunk returns null if the chunk index is out of bounds duckdb_result_is_streaming checks if the type of the internal result is streamqueryresult syntax the result object to check returns whether or not the result object is of the type streamqueryresult duckdb_result_chunk_count returns the number of data chunks present in the result syntax the result object returns number of data chunks present in the result duckdb_value_boolean syntax the boolean value at the specified location or false if the value cannot be converted duckdb_value_int8 syntax the int8_t value at the specified location or 0 if the value cannot be converted duckdb_value_int16 syntax the int16_t value at the specified location or 0 if the value cannot be converted duckdb_value_int32 syntax the int32_t value at the specified location or 0 if the value cannot be converted duckdb_value_int64 syntax the int64_t value at the specified location or 0 if the value cannot be converted duckdb_value_hugeint syntax the duckdb_hugeint value at the specified location or 0 if the value cannot be converted duckdb_value_decimal syntax the duckdb_decimal value at the specified location or 0 if the value cannot be converted duckdb_value_uint8 syntax the uint8_t value at the specified location or 0 if the value cannot be converted duckdb_value_uint16 syntax the uint16_t value at the specified location or 0 if the value cannot be converted duckdb_value_uint32 syntax the uint32_t value at the specified location or 0 if the value cannot be converted duckdb_value_uint64 syntax the uint64_t value at the specified location or 0 if the value cannot be converted duckdb_value_float syntax the float value at the specified location or 0 if the value cannot be converted duckdb_value_double syntax the double value at the specified location or 0 if the value cannot be converted duckdb_value_date syntax the duckdb_date value at the specified location or 0 if the value cannot be converted duckdb_value_time syntax the duckdb_time value at the specified location or 0 if the value cannot be converted duckdb_value_timestamp syntax the duckdb_timestamp value at the specified location or 0 if the value cannot be converted duckdb_value_interval syntax the duckdb_interval value at the specified location or 0 if the value cannot be converted duckdb_value_varchar syntax use duckdb_value_string instead this function does not work correctly if the string contains null bytes returns the text value at the specified location as a null-terminated string or nullptr if the value cannot be converted the result must be freed with duckdb_free duckdb_value_varchar_internal syntax use duckdb_value_string_internal instead this function does not work correctly if the string contains null bytes returns the char value at the specified location only works on varchar columns and does not auto-cast if the column is not a varchar column this function will return null the result must not be freed duckdb_value_string_internal syntax use duckdb_value_string_internal instead this function does not work correctly if the string contains null bytes returns the char value at the specified location only works on varchar columns and does not auto-cast if the column is not a varchar column this function will return null the result must not be freed duckdb_value_blob syntax the duckdb_blob value at the specified location returns a blob with blob data set to nullptr if the value cannot be converted the resulting blob data must be freed with duckdb_free duckdb_value_is_null syntax returns true if the value at the specified index is null and false otherwise duckdb_malloc allocate size bytes of memory using the duckdb internal malloc function any memory allocated in this manner should be freed using duckdb_free syntax the number of bytes to allocate returns a pointer to the allocated memory region duckdb_free free a value returned from duckdb_malloc duckdb_value_varchar or duckdb_value_blob syntax the memory region to de-allocate duckdb_vector_size the internal vector size used by duckdb this is the amount of tuples that will fit into a data chunk created by duckdb_create_data_chunk syntax the vector size duckdb_string_is_inlined whether or not the duckdb_string_t value is inlined this means that the data of the string does not have a separate allocation syntax duckdb_from_date decompose a duckdb_date object into year month and date stored as duckdb_date_struct syntax the date object as obtained from a duckdb_type_date column returns the duckdb_date_struct with the decomposed elements duckdb_to_date re-compose a duckdb_date from year month and date duckdb_date_struct syntax the year month and date stored in a duckdb_date_struct returns the duckdb_date element duckdb_from_time decompose a duckdb_time object into hour minute second and microsecond stored as duckdb_time_struct syntax the time object as obtained from a duckdb_type_time column returns the duckdb_time_struct with the decomposed elements duckdb_to_time re-compose a duckdb_time from hour minute second and microsecond duckdb_time_struct syntax the hour minute second and microsecond in a duckdb_time_struct returns the duckdb_time element duckdb_from_timestamp decompose a duckdb_timestamp object into a duckdb_timestamp_struct syntax the ts object as obtained from a duckdb_type_timestamp column returns the duckdb_timestamp_struct with the decomposed elements duckdb_to_timestamp re-compose a duckdb_timestamp from a duckdb_timestamp_struct syntax the de-composed elements in a duckdb_timestamp_struct returns the duckdb_timestamp element duckdb_hugeint_to_double converts a duckdb_hugeint object as obtained from a duckdb_type_hugeint column into a double syntax the hugeint value returns the converted double element duckdb_double_to_hugeint converts a double value to a duckdb_hugeint object if the conversion fails because the double value is too big the result will be 0 syntax the double value returns the converted duckdb_hugeint element duckdb_double_to_decimal converts a double value to a duckdb_decimal object if the conversion fails because the double value is too big or the width scale are invalid the result will be 0 syntax the double value returns the converted duckdb_decimal element duckdb_decimal_to_double converts a duckdb_decimal object as obtained from a duckdb_type_decimal column into a double syntax the decimal value returns the converted double element duckdb_prepare create a prepared statement object from a query note that after calling duckdb_prepare the prepared statement should always be destroyed using duckdb_destroy_prepare even if the prepare fails if the prepare fails duckdb_prepare_error can be called to obtain the reason why the prepare failed syntax the connection object query the sql query to prepare out_prepared_statement the resulting prepared statement object returns duckdbsuccess on success or duckdberror on failure duckdb_destroy_prepare closes the prepared statement and de-allocates all memory allocated for the statement syntax the prepared statement to destroy duckdb_prepare_error returns the error message associated with the given prepared statement if the prepared statement has no error message this returns nullptr instead the error message should not be freed it will be de-allocated when duckdb_destroy_prepare is called syntax the prepared statement to obtain the error from returns the error message or nullptr if there is none duckdb_nparams returns the number of parameters that can be provided to the given prepared statement returns 0 if the query was not successfully prepared syntax the prepared statement to obtain the number of parameters for duckdb_param_type returns the parameter type for the parameter at the given index returns duckdb_type_invalid if the parameter index is out of range or the statement was not successfully prepared syntax the prepared statement param_idx the parameter index returns the parameter type duckdb_clear_bindings clear the params bind to the prepared statement syntax duckdb_bind_value binds a value to the prepared statement at the specified index syntax duckdb_bind_parameter_index retrieve the index of the parameter for the prepared statement identified by name syntax duckdb_bind_boolean binds a bool value to the prepared statement at the specified index syntax duckdb_bind_int8 binds an int8_t value to the prepared statement at the specified index syntax duckdb_bind_int16 binds an int16_t value to the prepared statement at the specified index syntax duckdb_bind_int32 binds an int32_t value to the prepared statement at the specified index syntax duckdb_bind_int64 binds an int64_t value to the prepared statement at the specified index syntax duckdb_bind_hugeint binds an duckdb_hugeint value to the prepared statement at the specified index syntax duckdb_bind_decimal binds a duckdb_decimal value to the prepared statement at the specified index syntax duckdb_bind_uint8 binds an uint8_t value to the prepared statement at the specified index syntax duckdb_bind_uint16 binds an uint16_t value to the prepared statement at the specified index syntax duckdb_bind_uint32 binds an uint32_t value to the prepared statement at the specified index syntax duckdb_bind_uint64 binds an uint64_t value to the prepared statement at the specified index syntax duckdb_bind_float binds an float value to the prepared statement at the specified index syntax duckdb_bind_double binds an double value to the prepared statement at the specified index syntax duckdb_bind_date binds a duckdb_date value to the prepared statement at the specified index syntax duckdb_bind_time binds a duckdb_time value to the prepared statement at the specified index syntax duckdb_bind_timestamp binds a duckdb_timestamp value to the prepared statement at the specified index syntax duckdb_bind_interval binds a duckdb_interval value to the prepared statement at the specified index syntax duckdb_bind_varchar binds a null-terminated varchar value to the prepared statement at the specified index syntax duckdb_bind_varchar_length binds a varchar value to the prepared statement at the specified index syntax duckdb_bind_blob binds a blob value to the prepared statement at the specified index syntax duckdb_bind_null binds a null value to the prepared statement at the specified index syntax duckdb_execute_prepared executes the prepared statement with the given bound parameters and returns a materialized query result this method can be called multiple times for each prepared statement and the parameters can be modified between calls to this function syntax the prepared statement to execute out_result the query result returns duckdbsuccess on success or duckdberror on failure duckdb_execute_prepared_arrow executes the prepared statement with the given bound parameters and returns an arrow query result syntax the prepared statement to execute out_result the query result returns duckdbsuccess on success or duckdberror on failure duckdb_arrow_scan scans the arrow stream and creates a view with the given name syntax the connection on which to execute the scan table_name name of the temporary view to create arrow arrow stream wrapper returns duckdbsuccess on success or duckdberror on failure duckdb_arrow_array_scan scans the arrow array and creates a view with the given name syntax the connection on which to execute the scan table_name name of the temporary view to create arrow_schema arrow schema wrapper arrow_array arrow array wrapper out_stream output array stream that wraps around the passed schema for releasing deleting once done returns duckdbsuccess on success or duckdberror on failure duckdb_extract_statements extract all statements from a query note that after calling duckdb_extract_statements the extracted statements should always be destroyed using duckdb_destroy_extracted even if no statements were extracted if the extract fails duckdb_extract_statements_error can be called to obtain the reason why the extract failed syntax the connection object query the sql query to extract out_extracted_statements the resulting extracted statements object returns the number of extracted statements or 0 on failure duckdb_prepare_extracted_statement prepare an extracted statement note that after calling duckdb_prepare_extracted_statement the prepared statement should always be destroyed using duckdb_destroy_prepare even if the prepare fails if the prepare fails duckdb_prepare_error can be called to obtain the reason why the prepare failed syntax the connection object extracted_statements the extracted statements object index the index of the extracted statement to prepare out_prepared_statement the resulting prepared statement object returns duckdbsuccess on success or duckdberror on failure duckdb_extract_statements_error returns the error message contained within the extracted statements the result of this function must not be freed it will be cleaned up when duckdb_destroy_extracted is called syntax the extracted statements to fetch the error from returns the error of the extracted statements duckdb_destroy_extracted de-allocates all memory allocated for the extracted statements syntax the extracted statements to destroy duckdb_pending_prepared executes the prepared statement with the given bound parameters and returns a pending result the pending result represents an intermediate structure for a query that is not yet fully executed the pending result can be used to incrementally execute a query returning control to the client between tasks note that after calling duckdb_pending_prepared the pending result should always be destroyed using duckdb_destroy_pending even if this function returns duckdberror syntax the prepared statement to execute out_result the pending query result returns duckdbsuccess on success or duckdberror on failure duckdb_pending_prepared_streaming executes the prepared statement with the given bound parameters and returns a pending result this pending result will create a streaming duckdb_result when executed the pending result represents an intermediate structure for a query that is not yet fully executed note that after calling duckdb_pending_prepared_streaming the pending result should always be destroyed using duckdb_destroy_pending even if this function returns duckdberror syntax the prepared statement to execute out_result the pending query result returns duckdbsuccess on success or duckdberror on failure duckdb_destroy_pending closes the pending result and de-allocates all memory allocated for the result syntax the pending result to destroy duckdb_pending_error returns the error message contained within the pending result the result of this function must not be freed it will be cleaned up when duckdb_destroy_pending is called syntax the pending result to fetch the error from returns the error of the pending result duckdb_pending_execute_task executes a single task within the query returning whether or not the query is ready if this returns duckdb_pending_result_ready the duckdb_execute_pending function can be called to obtain the result if this returns duckdb_pending_result_not_ready the duckdb_pending_execute_task function should be called again if this returns duckdb_pending_error an error occurred during execution the error message can be obtained by calling duckdb_pending_error on the pending_result syntax the pending result to execute a task within returns the state of the pending result after the execution duckdb_execute_pending fully execute a pending query result returning the final query result if duckdb_pending_execute_task has been called until duckdb_pending_result_ready was returned this will return fast otherwise all remaining tasks must be executed first syntax the pending result to execute out_result the result object returns duckdbsuccess on success or duckdberror on failure duckdb_pending_execution_is_finished returns whether a duckdb_pending_state is finished executing for example if pending_state is duckdb_pending_result_ready this function will return true syntax the pending state on which to decide whether to finish execution returns boolean indicating pending execution should be considered finished duckdb_destroy_value destroys the value and de-allocates all memory allocated for that type syntax the value to destroy duckdb_create_varchar creates a value from a null-terminated string syntax the null-terminated string returns the value this must be destroyed with duckdb_destroy_value duckdb_create_varchar_length creates a value from a string syntax the text length the length of the text returns the value this must be destroyed with duckdb_destroy_value duckdb_create_int64 creates a value from an int64 syntax the bigint value returns the value this must be destroyed with duckdb_destroy_value duckdb_get_varchar obtains a string representation of the given value the result must be destroyed with duckdb_free syntax the value returns the string value this must be destroyed with duckdb_free duckdb_get_int64 obtains an int64 of the given value syntax the value returns the int64 value or 0 if no conversion is possible duckdb_create_logical_type creates a duckdb_logical_type from a standard primitive type the resulting type should be destroyed with duckdb_destroy_logical_type this should not be used with duckdb_type_decimal syntax the primitive type to create returns the logical type duckdb_create_list_type creates a list type from its child type the resulting type should be destroyed with duckdb_destroy_logical_type syntax the child type of list type to create returns the logical type duckdb_create_map_type creates a map type from its key type and value type the resulting type should be destroyed with duckdb_destroy_logical_type syntax the key type and value type of map type to create returns the logical type duckdb_create_union_type creates a union type from the passed types array the resulting type should be destroyed with duckdb_destroy_logical_type syntax the array of types that the union should consist of type_amount the size of the types array returns the logical type duckdb_create_struct_type creates a struct type from the passed member name and type arrays the resulting type should be destroyed with duckdb_destroy_logical_type syntax the array of types that the struct should consist of member_names the array of names that the struct should consist of member_count the number of members that were specified for both arrays returns the logical type duckdb_create_decimal_type creates a duckdb_logical_type of type decimal with the specified width and scale the resulting type should be destroyed with duckdb_destroy_logical_type syntax the width of the decimal type scale the scale of the decimal type returns the logical type duckdb_get_type_id retrieves the type class of a duckdb_logical_type syntax the logical type object returns the type id duckdb_decimal_width retrieves the width of a decimal type syntax the logical type object returns the width of the decimal type duckdb_decimal_scale retrieves the scale of a decimal type syntax the logical type object returns the scale of the decimal type duckdb_decimal_internal_type retrieves the internal storage type of a decimal type syntax the logical type object returns the internal type of the decimal type duckdb_enum_internal_type retrieves the internal storage type of an enum type syntax the logical type object returns the internal type of the enum type duckdb_enum_dictionary_size retrieves the dictionary size of the enum type syntax the logical type object returns the dictionary size of the enum type duckdb_enum_dictionary_value retrieves the dictionary value at the specified position from the enum the result must be freed with duckdb_free syntax the logical type object index the index in the dictionary returns the string value of the enum type must be freed with duckdb_free duckdb_list_type_child_type retrieves the child type of the given list type the result must be freed with duckdb_destroy_logical_type syntax the logical type object returns the child type of the list type must be destroyed with duckdb_destroy_logical_type duckdb_map_type_key_type retrieves the key type of the given map type the result must be freed with duckdb_destroy_logical_type syntax the logical type object returns the key type of the map type must be destroyed with duckdb_destroy_logical_type duckdb_map_type_value_type retrieves the value type of the given map type the result must be freed with duckdb_destroy_logical_type syntax the logical type object returns the value type of the map type must be destroyed with duckdb_destroy_logical_type duckdb_struct_type_child_count returns the number of children of a struct type syntax the logical type object returns the number of children of a struct type duckdb_struct_type_child_name retrieves the name of the struct child the result must be freed with duckdb_free syntax the logical type object index the child index returns the name of the struct type must be freed with duckdb_free duckdb_struct_type_child_type retrieves the child type of the given struct type at the specified index the result must be freed with duckdb_destroy_logical_type syntax the logical type object index the child index returns the child type of the struct type must be destroyed with duckdb_destroy_logical_type duckdb_union_type_member_count returns the number of members that the union type has syntax the logical type union object returns the number of members of a union type duckdb_union_type_member_name retrieves the name of the union member the result must be freed with duckdb_free syntax the logical type object index the child index returns the name of the union member must be freed with duckdb_free duckdb_union_type_member_type retrieves the child type of the given union member at the specified index the result must be freed with duckdb_destroy_logical_type syntax the logical type object index the child index returns the child type of the union member must be destroyed with duckdb_destroy_logical_type duckdb_destroy_logical_type destroys the logical type and de-allocates all memory allocated for that type syntax the logical type to destroy duckdb_create_data_chunk creates an empty datachunk with the specified set of types syntax an array of types of the data chunk column_count the number of columns returns the data chunk duckdb_destroy_data_chunk destroys the data chunk and de-allocates all memory allocated for that chunk syntax the data chunk to destroy duckdb_data_chunk_reset resets a data chunk clearing the validity masks and setting the cardinality of the data chunk to 0 syntax the data chunk to reset duckdb_data_chunk_get_column_count retrieves the number of columns in a data chunk syntax the data chunk to get the data from returns the number of columns in the data chunk duckdb_data_chunk_get_vector retrieves the vector at the specified column index in the data chunk the pointer to the vector is valid for as long as the chunk is alive it does not need to be destroyed syntax the data chunk to get the data from returns the vector duckdb_data_chunk_get_size retrieves the current number of tuples in a data chunk syntax the data chunk to get the data from returns the number of tuples in the data chunk duckdb_data_chunk_set_size sets the current number of tuples in a data chunk syntax the data chunk to set the size in size the number of tuples in the data chunk duckdb_vector_get_column_type retrieves the column type of the specified vector the result must be destroyed with duckdb_destroy_logical_type syntax the vector get the data from returns the type of the vector duckdb_vector_get_data retrieves the data pointer of the vector the data pointer can be used to read or write values from the vector how to read or write values depends on the type of the vector syntax the vector to get the data from returns the data pointer duckdb_vector_get_validity retrieves the validity mask pointer of the specified vector if all values are valid this function might return null the validity mask is a bitset that signifies null-ness within the data chunk it is a series of uint64_t values where each uint64_t value contains validity for 64 tuples the bit is set to 1 if the value is valid i e not null or 0 if the value is invalid i e null validity of a specific value can be obtained like this idx_t entry_idx row_idx 64 idx_t idx_in_entry row_idx 64 bool is_valid validity_mask entry_idx 1 idx_in_entry alternatively the slower duckdb_validity_row_is_valid function can be used syntax the vector to get the data from returns the pointer to the validity mask or null if no validity mask is present duckdb_vector_ensure_validity_writable ensures the validity mask is writable by allocating it after this function is called duckdb_vector_get_validity will always return non-null this allows null values to be written to the vector regardless of whether a validity mask was present before syntax the vector to alter duckdb_vector_assign_string_element assigns a string element in the vector at the specified location syntax the vector to alter index the row position in the vector to assign the string to str the null-terminated string duckdb_vector_assign_string_element_len assigns a string element in the vector at the specified location syntax the vector to alter index the row position in the vector to assign the string to str the string str_len the length of the string in bytes duckdb_list_vector_get_child retrieves the child vector of a list vector the resulting vector is valid as long as the parent vector is valid syntax the vector returns the child vector duckdb_list_vector_get_size returns the size of the child vector of the list syntax the vector returns the size of the child list duckdb_list_vector_set_size sets the total size of the underlying child-vector of a list vector syntax the list vector size the size of the child list returns the duckdb state returns duckdberror if the vector is nullptr duckdb_list_vector_reserve sets the total capacity of the underlying child-vector of a list syntax the list vector required_capacity the total capacity to reserve return the duckdb state returns duckdberror if the vector is nullptr duckdb_struct_vector_get_child retrieves the child vector of a struct vector the resulting vector is valid as long as the parent vector is valid syntax the vector index the child index returns the child vector duckdb_validity_row_is_valid returns whether or not a row is valid i e not null in the given validity mask syntax the validity mask as obtained through duckdb_vector_get_validity row the row index returns true if the row is valid false otherwise duckdb_validity_set_row_validity in a validity mask sets a specific row to either valid or invalid note that duckdb_vector_ensure_validity_writable should be called before calling duckdb_vector_get_validity to ensure that there is a validity mask to write to syntax the validity mask as obtained through duckdb_vector_get_validity row the row index valid whether or not to set the row to valid or invalid duckdb_validity_set_row_invalid in a validity mask sets a specific row to invalid equivalent to duckdb_validity_set_row_validity with valid set to false syntax the validity mask row the row index duckdb_validity_set_row_valid in a validity mask sets a specific row to valid equivalent to duckdb_validity_set_row_validity with valid set to true syntax the validity mask row the row index duckdb_create_table_function creates a new empty table function the return value should be destroyed with duckdb_destroy_table_function syntax the table function object duckdb_destroy_table_function destroys the given table function object syntax the table function to destroy duckdb_table_function_set_name sets the name of the given table function syntax the table function name the name of the table function duckdb_table_function_add_parameter adds a parameter to the table function syntax 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 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 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 the table function bind the bind function duckdb_table_function_set_init sets the init function of the table function syntax the table function init the init function duckdb_table_function_set_local_init sets the thread-local init function of the table function syntax the table function init the init function duckdb_table_function_set_function sets the main function of the table function syntax 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 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 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 the info object returns the extra info duckdb_bind_add_result_column adds a result column to the output of the table function syntax 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 the info object returns the init data object duckdb_function_set_error report that an error has occurred while executing the function syntax the info object error the error message duckdb_add_replacement_scan add a replacement scan definition to the specified database syntax the database object to add the replacement scan to replacement the replacement scan callback extra_data extra data that is passed back into the specified callback delete_callback the delete callback to call on the extra data if any duckdb_replacement_scan_set_function_name sets the replacement function name to use if this function is called in the replacement callback the replacement scan is performed if it is not called the replacement callback is not performed syntax the info object function_name the function name to substitute duckdb_replacement_scan_add_parameter adds a parameter to the replacement scan function syntax the info object parameter the parameter to add duckdb_replacement_scan_set_error report that an error has occurred while executing the replacement scan syntax the info object error the error message duckdb_appender_create creates an appender object syntax the connection context to create the appender in schema the schema of the table to append to or nullptr for the default schema table the table name to append to out_appender the resulting appender object returns duckdbsuccess on success or duckdberror on failure duckdb_appender_error returns the error message associated with the given appender if the appender has no error message this returns nullptr instead the error message should not be freed it will be de-allocated when duckdb_appender_destroy is called syntax the appender to get the error from returns the error message or nullptr if there is none duckdb_appender_flush flush the appender to the table forcing the cache of the appender to be cleared and the data to be appended to the base table this should generally not be used unless you know what you are doing instead call duckdb_appender_destroy when you are done with the appender syntax the appender to flush returns duckdbsuccess on success or duckdberror on failure duckdb_appender_close close the appender flushing all intermediate state in the appender to the table and closing it for further appends this is generally not necessary call duckdb_appender_destroy instead syntax the appender to flush and close returns duckdbsuccess on success or duckdberror on failure duckdb_appender_destroy close the appender and destroy it flushing all intermediate state in the appender to the table and de-allocating all memory associated with the appender syntax the appender to flush close and destroy returns duckdbsuccess on success or duckdberror on failure duckdb_appender_begin_row a nop function provided for backwards compatibility reasons does nothing only duckdb_appender_end_row is required syntax duckdb_appender_end_row finish the current row of appends after end_row is called the next row can be appended syntax the appender returns duckdbsuccess on success or duckdberror on failure duckdb_append_bool append a bool value to the appender syntax duckdb_append_int8 append an int8_t value to the appender syntax duckdb_append_int16 append an int16_t value to the appender syntax duckdb_append_int32 append an int32_t value to the appender syntax duckdb_append_int64 append an int64_t value to the appender syntax duckdb_append_hugeint append a duckdb_hugeint value to the appender syntax duckdb_append_uint8 append a uint8_t value to the appender syntax duckdb_append_uint16 append a uint16_t value to the appender syntax duckdb_append_uint32 append a uint32_t value to the appender syntax duckdb_append_uint64 append a uint64_t value to the appender syntax duckdb_append_float append a float value to the appender syntax duckdb_append_double append a double value to the appender syntax duckdb_append_date append a duckdb_date value to the appender syntax duckdb_append_time append a duckdb_time value to the appender syntax duckdb_append_timestamp append a duckdb_timestamp value to the appender syntax duckdb_append_interval append a duckdb_interval value to the appender syntax duckdb_append_varchar append a varchar value to the appender syntax duckdb_append_varchar_length append a varchar value to the appender syntax duckdb_append_blob append a blob value to the appender syntax duckdb_append_null append a null value to the appender of any type syntax duckdb_append_data_chunk appends a pre-filled data chunk to the specified appender the types of the data chunk must exactly match the types of the table no casting is performed if the types do not match or the appender is in an invalid state duckdberror is returned if the append is successful duckdbsuccess is returned syntax the appender to append to chunk the data chunk to append returns the return state duckdb_query_arrow executes a sql query within a connection and stores the full materialized result in an arrow structure if the query fails to execute duckdberror is returned and the error message can be retrieved by calling duckdb_query_arrow_error note that after running duckdb_query_arrow duckdb_destroy_arrow must be called on the result object even if the query fails otherwise the error stored within the result will not be freed correctly syntax the connection to perform the query in query the sql query to run out_result the query result returns duckdbsuccess on success or duckdberror on failure duckdb_query_arrow_schema fetch the internal arrow schema from the arrow result syntax the result to fetch the schema from out_schema the output schema returns duckdbsuccess on success or duckdberror on failure duckdb_prepared_arrow_schema fetch the internal arrow schema from the prepared statement syntax the prepared statement to fetch the schema from out_schema the output schema returns duckdbsuccess on success or duckdberror on failure duckdb_query_arrow_array fetch an internal arrow array from the arrow result this function can be called multiple time to get next chunks which will free the previous out_array so consume the out_array before calling this function again syntax the result to fetch the array from out_array the output array returns duckdbsuccess on success or duckdberror on failure duckdb_arrow_column_count returns the number of columns present in a the arrow result object syntax the result object returns the number of columns present in the result object duckdb_arrow_row_count returns the number of rows present in a the arrow result object syntax the result object returns the number of rows present in the result object duckdb_arrow_rows_changed returns the number of rows changed by the query stored in the arrow result this is relevant only for insert update delete queries for other queries the rows_changed will be 0 syntax the result object returns the number of rows changed duckdb_query_arrow_error returns the error message contained within the result the error is only set if duckdb_query_arrow returns duckdberror the error message should not be freed it will be de-allocated when duckdb_destroy_arrow is called syntax the result object to fetch the nullmask from returns the error of the result duckdb_destroy_arrow closes the result and de-allocates all memory allocated for the arrow result syntax the result to destroy duckdb_execute_tasks execute duckdb tasks on this thread will return after max_tasks have been executed or if there are no more tasks present syntax the database object to execute tasks for max_tasks the maximum amount of tasks to execute duckdb_create_task_state creates a task state that can be used with duckdb_execute_tasks_state to execute tasks until duckdb_finish_execution is called on the state duckdb_destroy_state should be called on the result in order to free memory syntax the database object to create the task state for returns the task state that can be used with duckdb_execute_tasks_state duckdb_execute_tasks_state execute duckdb tasks on this thread the thread will keep on executing tasks forever until duckdb_finish_execution is called on the state multiple threads can share the same duckdb_task_state syntax the task state of the executor duckdb_execute_n_tasks_state execute duckdb tasks on this thread the thread will keep on executing tasks until either duckdb_finish_execution is called on the state max_tasks tasks have been executed or there are no more tasks to be executed multiple threads can share the same duckdb_task_state syntax the task state of the executor max_tasks the maximum amount of tasks to execute returns the amount of tasks that have actually been executed duckdb_finish_execution finish execution on a specific task syntax the task state to finish execution duckdb_task_state_is_finished check if the provided duckdb_task_state has finished execution syntax the task state to inspect returns whether or not duckdb_finish_execution has been called on the task state duckdb_destroy_task_state destroys the task state returned from duckdb_create_task_state note that this should not be called while there is an active duckdb_execute_tasks_state running on the task state syntax the task state to clean up duckdb_execution_is_finished returns true if execution of the current query is finished syntax the connection on which to check duckdb_stream_fetch_chunk fetches a data chunk from the streaming duckdb_result this function should be called repeatedly until the result is exhausted the result must be destroyed with duckdb_destroy_data_chunk this function can only be used on duckdb_results created with duckdb_pending_prepared_streaming if this function is used none of the other result functions can be used and vice versa i e this function cannot be mixed with the legacy result functions or the materialized result functions it is not known beforehand how many chunks will be returned by this result syntax the result object to fetch the data chunk from returns the resulting data chunk returns null if the result has an error", "category": "C", "url": "/docs/api/c/api", "blurb": "API Reference Open/Connect Syntax Path to the database file on disk, or nullptr or :memory: to open an in-memory..." @@ -177,7 +177,7 @@ }, { "title": "C API - Data Chunks", - "text": "data chunks represent a horizontal slice of a table they hold a number of vectors that can each hold up to the vector_size rows the vector size can be obtained through the duckdb_vector_size function and is configurable but is usually set to 1024 data chunks and vectors are what duckdb uses natively to store and represent data for this reason the data chunk interface is the most efficient way of interfacing with duckdb be aware however that correctly interfacing with duckdb using the data chunk api does require knowledge of duckdb s internal vector format the primary manner of interfacing with data chunks is by obtaining the internal vectors of the data chunk using the duckdb_data_chunk_get_vector method and subsequently using the duckdb_vector_get_data and duckdb_vector_get_validity methods to read the internal data and the validity mask of the vector for composite types list and struct vectors duckdb_list_vector_get_child and duckdb_struct_vector_get_child should be used to read child vectors api reference syntax an array of types of the data chunk column_count the number of columns returns the data chunk duckdb_destroy_data_chunk destroys the data chunk and de-allocates all memory allocated for that chunk syntax the data chunk to destroy duckdb_data_chunk_reset resets a data chunk clearing the validity masks and setting the cardinality of the data chunk to 0 syntax the data chunk to reset duckdb_data_chunk_get_column_count retrieves the number of columns in a data chunk syntax the data chunk to get the data from returns the number of columns in the data chunk duckdb_data_chunk_get_vector retrieves the vector at the specified column index in the data chunk the pointer to the vector is valid for as long as the chunk is alive it does not need to be destroyed syntax the data chunk to get the data from returns the vector duckdb_data_chunk_get_size retrieves the current number of tuples in a data chunk syntax the data chunk to get the data from returns the number of tuples in the data chunk duckdb_data_chunk_set_size sets the current number of tuples in a data chunk syntax the data chunk to set the size in size the number of tuples in the data chunk duckdb_vector_get_column_type retrieves the column type of the specified vector the result must be destroyed with duckdb_destroy_logical_type syntax the vector get the data from returns the type of the vector duckdb_vector_get_data retrieves the data pointer of the vector the data pointer can be used to read or write values from the vector how to read or write values depends on the type of the vector syntax the vector to get the data from returns the data pointer duckdb_vector_get_validity retrieves the validity mask pointer of the specified vector if all values are valid this function might return null the validity mask is a bitset that signifies null-ness within the data chunk it is a series of uint64_t values where each uint64_t value contains validity for 64 tuples the bit is set to 1 if the value is valid i e not null or 0 if the value is invalid i e null validity of a specific value can be obtained like this idx_t entry_idx row_idx 64 idx_t idx_in_entry row_idx 64 bool is_valid validity_mask entry_idx 1 idx_in_entry alternatively the slower duckdb_validity_row_is_valid function can be used syntax the vector to get the data from returns the pointer to the validity mask or null if no validity mask is present duckdb_vector_ensure_validity_writable ensures the validity mask is writable by allocating it after this function is called duckdb_vector_get_validity will always return non-null this allows null values to be written to the vector regardless of whether a validity mask was present before syntax the vector to alter duckdb_vector_assign_string_element assigns a string element in the vector at the specified location syntax the vector to alter index the row position in the vector to assign the string to str the null-terminated string duckdb_vector_assign_string_element_len assigns a string element in the vector at the specified location syntax the vector to alter index the row position in the vector to assign the string to str the string str_len the length of the string in bytes duckdb_list_vector_get_child retrieves the child vector of a list vector the resulting vector is valid as long as the parent vector is valid syntax the vector returns the child vector duckdb_list_vector_get_size returns the size of the child vector of the list syntax the vector returns the size of the child list duckdb_list_vector_set_size sets the total size of the underlying child-vector of a list vector syntax the list vector size the size of the child list returns the duckdb state returns duckdberror if the vector is nullptr duckdb_list_vector_reserve sets the total capacity of the underlying child-vector of a list syntax the list vector required_capacity the total capacity to reserve return the duckdb state returns duckdberror if the vector is nullptr duckdb_struct_vector_get_child retrieves the child vector of a struct vector the resulting vector is valid as long as the parent vector is valid syntax the vector index the child index returns the child vector duckdb_validity_row_is_valid returns whether or not a row is valid i e not null in the given validity mask syntax the validity mask as obtained through duckdb_data_chunk_get_validity row the row index returns true if the row is valid false otherwise duckdb_validity_set_row_validity in a validity mask sets a specific row to either valid or invalid note that duckdb_data_chunk_ensure_validity_writable should be called before calling duckdb_data_chunk_get_validity to ensure that there is a validity mask to write to syntax the validity mask as obtained through duckdb_data_chunk_get_validity row the row index valid whether or not to set the row to valid or invalid duckdb_validity_set_row_invalid in a validity mask sets a specific row to invalid equivalent to duckdb_validity_set_row_validity with valid set to false syntax the validity mask row the row index duckdb_validity_set_row_valid in a validity mask sets a specific row to valid equivalent to duckdb_validity_set_row_validity with valid set to true syntax the validity mask row the row index", + "text": "data chunks represent a horizontal slice of a table they hold a number of vectors that can each hold up to the vector_size rows the vector size can be obtained through the duckdb_vector_size function and is configurable but is usually set to 1024 data chunks and vectors are what duckdb uses natively to store and represent data for this reason the data chunk interface is the most efficient way of interfacing with duckdb be aware however that correctly interfacing with duckdb using the data chunk api does require knowledge of duckdb s internal vector format the primary manner of interfacing with data chunks is by obtaining the internal vectors of the data chunk using the duckdb_data_chunk_get_vector method and subsequently using the duckdb_vector_get_data and duckdb_vector_get_validity methods to read the internal data and the validity mask of the vector for composite types list and struct vectors duckdb_list_vector_get_child and duckdb_struct_vector_get_child should be used to read child vectors api reference syntax an array of types of the data chunk column_count the number of columns returns the data chunk duckdb_destroy_data_chunk destroys the data chunk and de-allocates all memory allocated for that chunk syntax the data chunk to destroy duckdb_data_chunk_reset resets a data chunk clearing the validity masks and setting the cardinality of the data chunk to 0 syntax the data chunk to reset duckdb_data_chunk_get_column_count retrieves the number of columns in a data chunk syntax the data chunk to get the data from returns the number of columns in the data chunk duckdb_data_chunk_get_vector retrieves the vector at the specified column index in the data chunk the pointer to the vector is valid for as long as the chunk is alive it does not need to be destroyed syntax the data chunk to get the data from returns the vector duckdb_data_chunk_get_size retrieves the current number of tuples in a data chunk syntax the data chunk to get the data from returns the number of tuples in the data chunk duckdb_data_chunk_set_size sets the current number of tuples in a data chunk syntax the data chunk to set the size in size the number of tuples in the data chunk duckdb_vector_get_column_type retrieves the column type of the specified vector the result must be destroyed with duckdb_destroy_logical_type syntax the vector get the data from returns the type of the vector duckdb_vector_get_data retrieves the data pointer of the vector the data pointer can be used to read or write values from the vector how to read or write values depends on the type of the vector syntax the vector to get the data from returns the data pointer duckdb_vector_get_validity retrieves the validity mask pointer of the specified vector if all values are valid this function might return null the validity mask is a bitset that signifies null-ness within the data chunk it is a series of uint64_t values where each uint64_t value contains validity for 64 tuples the bit is set to 1 if the value is valid i e not null or 0 if the value is invalid i e null validity of a specific value can be obtained like this idx_t entry_idx row_idx 64 idx_t idx_in_entry row_idx 64 bool is_valid validity_mask entry_idx 1 idx_in_entry alternatively the slower duckdb_validity_row_is_valid function can be used syntax the vector to get the data from returns the pointer to the validity mask or null if no validity mask is present duckdb_vector_ensure_validity_writable ensures the validity mask is writable by allocating it after this function is called duckdb_vector_get_validity will always return non-null this allows null values to be written to the vector regardless of whether a validity mask was present before syntax the vector to alter duckdb_vector_assign_string_element assigns a string element in the vector at the specified location syntax the vector to alter index the row position in the vector to assign the string to str the null-terminated string duckdb_vector_assign_string_element_len assigns a string element in the vector at the specified location syntax the vector to alter index the row position in the vector to assign the string to str the string str_len the length of the string in bytes duckdb_list_vector_get_child retrieves the child vector of a list vector the resulting vector is valid as long as the parent vector is valid syntax the vector returns the child vector duckdb_list_vector_get_size returns the size of the child vector of the list syntax the vector returns the size of the child list duckdb_list_vector_set_size sets the total size of the underlying child-vector of a list vector syntax the list vector size the size of the child list returns the duckdb state returns duckdberror if the vector is nullptr duckdb_list_vector_reserve sets the total capacity of the underlying child-vector of a list syntax the list vector required_capacity the total capacity to reserve return the duckdb state returns duckdberror if the vector is nullptr duckdb_struct_vector_get_child retrieves the child vector of a struct vector the resulting vector is valid as long as the parent vector is valid syntax the vector index the child index returns the child vector duckdb_validity_row_is_valid returns whether or not a row is valid i e not null in the given validity mask syntax the validity mask as obtained through duckdb_vector_get_validity row the row index returns true if the row is valid false otherwise duckdb_validity_set_row_validity in a validity mask sets a specific row to either valid or invalid note that duckdb_vector_ensure_validity_writable should be called before calling duckdb_vector_get_validity to ensure that there is a validity mask to write to syntax the validity mask as obtained through duckdb_vector_get_validity row the row index valid whether or not to set the row to valid or invalid duckdb_validity_set_row_invalid in a validity mask sets a specific row to invalid equivalent to duckdb_validity_set_row_validity with valid set to false syntax the validity mask row the row index duckdb_validity_set_row_valid in a validity mask sets a specific row to valid equivalent to duckdb_validity_set_row_validity with valid set to true syntax the validity mask row the row index", "category": "C", "url": "/docs/api/c/data_chunk", "blurb": "Data chunks represent a horizontal slice of a table. They hold a number of vectors, that can each hold up to the..." diff --git a/docs/api/c/api.md b/docs/api/c/api.md index 4a9d1edef07..e9e64467584 100644 --- a/docs/api/c/api.md +++ b/docs/api/c/api.md @@ -3657,7 +3657,7 @@ Returns whether or not a row is valid (i.e. not NULL) in the given validity mask --- * `validity` -The validity mask, as obtained through `duckdb_data_chunk_get_validity` +The validity mask, as obtained through `duckdb_vector_get_validity` * `row` The row index @@ -3671,7 +3671,7 @@ true if the row is valid, false otherwise --- In a validity mask, sets a specific row to either valid or invalid. -Note that `duckdb_data_chunk_ensure_validity_writable` should be called before calling `duckdb_data_chunk_get_validity`, +Note that `duckdb_vector_ensure_validity_writable` should be called before calling `duckdb_vector_get_validity`, to ensure that there is a validity mask to write to. #### Syntax @@ -3686,7 +3686,7 @@ to ensure that there is a validity mask to write to. --- * `validity` -The validity mask, as obtained through `duckdb_data_chunk_get_validity`. +The validity mask, as obtained through `duckdb_vector_get_validity`. * `row` The row index diff --git a/docs/api/c/data_chunk.md b/docs/api/c/data_chunk.md index d7038bdac77..9c65ce24942 100644 --- a/docs/api/c/data_chunk.md +++ b/docs/api/c/data_chunk.md @@ -485,7 +485,7 @@ Returns whether or not a row is valid (i.e. not NULL) in the given validity mask --- * `validity` -The validity mask, as obtained through `duckdb_data_chunk_get_validity` +The validity mask, as obtained through `duckdb_vector_get_validity` * `row` The row index @@ -499,7 +499,7 @@ true if the row is valid, false otherwise --- In a validity mask, sets a specific row to either valid or invalid. -Note that `duckdb_data_chunk_ensure_validity_writable` should be called before calling `duckdb_data_chunk_get_validity`, +Note that `duckdb_vector_ensure_validity_writable` should be called before calling `duckdb_vector_get_validity`, to ensure that there is a validity mask to write to. #### Syntax @@ -514,7 +514,7 @@ to ensure that there is a validity mask to write to. --- * `validity` -The validity mask, as obtained through `duckdb_data_chunk_get_validity`. +The validity mask, as obtained through `duckdb_vector_get_validity`. * `row` The row index From cbbc3a7d57e91c1928bf67a303ffd3b41e9f9cfb Mon Sep 17 00:00:00 2001 From: GitHub Actions Date: Mon, 2 Oct 2023 05:06:11 +0000 Subject: [PATCH 11/12] chore: auto update docs --- data/search_data.json | 26 +-- docs/api/python/reference/index.md | 315 ++++++++++++++++++++++++++++- 2 files changed, 317 insertions(+), 24 deletions(-) diff --git a/data/search_data.json b/data/search_data.json index ad7ad4afac7..4a6c5bab56a 100644 --- a/data/search_data.json +++ b/data/search_data.json @@ -434,13 +434,6 @@ "url": "/docs/guides/sql_editors/dbeaver", "blurb": "How to set up DBeaver SQL IDE for DuckDB DBeaver is a powerful and popular desktop sql editor and integrated..." }, - { - "title": "Data Ingestion", - "text": "csv files csv files can be read using the read_csv function called either from within python or directly from within sql by default the read_csv function attempts to auto-detect the csv settings by sampling from the provided file import duckdb read from a file using fully auto-detected settings duckdb read_csv example csv read multiple csv files from a folder duckdb read_csv folder csv specify options on how the csv is formatted internally duckdb read_csv example csv header false sep override types of the first two columns duckdb read_csv example csv dtype int varchar use the experimental parallel csv reader duckdb read_csv example csv parallel true directly read a csv file from within sql duckdb sql select from example csv call read_csv from within sql duckdb sql select from read_csv_auto example csv see the csv loading page for more information parquet files parquet files can be read using the read_parquet function called either from within python or directly from within sql import duckdb read from a single parquet file duckdb read_parquet example parquet read multiple parquet files from a folder duckdb read_parquet folder parquet directly read a parquet file from within sql duckdb sql select from example parquet call read_parquet from within sql duckdb sql select from read_parquet example parquet see the parquet loading page for more information json files json files can be read using the read_json function called either from within python or directly from within sql by default the read_json function will automatically detect if a file contains newline-delimited json or regular json and will detect the schema of the objects stored within the json file import duckdb read from a single json file duckdb read_json example json read multiple json files from a folder duckdb read_json folder json directly read a json file from within sql duckdb sql select from example json call read_json from within sql duckdb sql select from read_json_auto example json dataframes arrow tables duckdb is automatically able to query a pandas dataframe polars dataframe or arrow object that is stored in a python variable by name duckdb supports querying multiple types of apache arrow objects including tables datasets recordbatchreaders and scanners see the python guides for more examples import duckdb import pandas as pd test_df pd dataframe from_dict i 1 2 3 4 j one two three four duckdb sql select from test_df fetchall 1 one 2 two 3 three 4 four duckdb also supports registering a dataframe or arrow object as a virtual table comparable to a sql view this is useful when querying a dataframe arrow object that is stored in another way as a class variable or a value in a dictionary below is a pandas example if your pandas dataframe is stored in another location here is an example of manually registering it import duckdb import pandas as pd my_dictionary my_dictionary test_df pd dataframe from_dict i 1 2 3 4 j one two three four duckdb register test_df_view my_dictionary test_df duckdb sql select from test_df_view fetchall 1 one 2 two 3 three 4 four you can also create a persistent table in duckdb from the contents of the dataframe or the view create a new table from the contents of a dataframe con execute create table test_df_table as select from test_df insert into an existing table from the contents of a dataframe con execute insert into test_df_table select from test_df pandas dataframes - object columns pandas dataframe columns of an object dtype require some special care since this stores values of arbitrary type to convert these columns to duckdb we first go through an analyze phase before converting the values in this analyze phase a sample of all the rows of the column are analyzed to determine the target type this sample size is by default set to 1000 if the type picked during the analyze step is wrong this will result in a failed to cast value error in which case you will need to increase the sample size the sample size can be changed by setting the pandas_analyze_sample config option example setting the sample size to 100000 duckdb default_connection execute set global pandas_analyze_sample 100000", - "category": "Python", - "url": "/docs/api/python/data_ingestion", - "blurb": "CSV Files CSV files can be read using the read_csv function, called either from within Python or directly from within..." - }, { "title": "Data Ingestion", "text": "duckdb-wasm has multiple ways to import data depending on the format of the data there are two steps to import data into duckdb first the data file is imported into a local file system using register functions registeremptyfilebuffer registerfilebuffer registerfilehandle registerfiletext registerfileurl then the data file is imported into duckdb using insert functions insertarrowfromipcstream insertarrowtable insertcsvfrompath insertjsonfrompath or directly using from sql query using extensions like parquet or httpfs insert statements can also be used to import data data import open close connection create a new connection const c await db connect import data close the connection to release memory await c close apache arrow data can be inserted from an existing arrow table more example https arrow apache org docs js import tablefromarrays from apache-arrow const arrowtable tablefromarrays id 1 2 3 name john jane jack age 20 21 22 await c insertarrowtable arrowtable name arrow_table from a raw arrow ipc stream const streamresponse await fetch someapi const streamreader streamresponse body getreader const streaminserts while true const value done await streamreader read if done break streaminserts push c insertarrowfromipcstream value name streamed await promise all streaminserts csv from csv files interchangeable registerfile text buffer url handle const csvcontent 1 foo n2 bar n await db registerfiletext data csv csvcontent with typed insert options await db insertcsvfrompath data csv schema main name foo detect false header false delimiter columns col1 new arrow int32 col2 new arrow utf8 json from json documents in row-major format const jsonrowcontent col1 1 col2 foo col1 2 col2 bar await db registerfiletext rows json json stringify jsonrowcontent await c insertjsonfrompath rows json name rows or column-major format const jsoncolcontent col1 1 2 col2 foo bar await db registerfiletext columns json json stringify jsoncolcontent await c insertjsonfrompath columns json name columns from api const streamresponse await fetch someapi content json await db registerfilebuffer file json new uint8array await streamresponse arraybuffer await c insertjsonfrompath file json name jsoncontent parquet from parquet files local const pickedfile file letuserpickfile await db registerfilehandle local parquet pickedfile duckdbdataprotocol browser_filereader true remote await db registerfileurl remote parquet https origin remote parquet duckdbdataprotocol http false using fetch const res await fetch https origin remote parquet await db registerfilebuffer buffer parquet new uint8array await res arraybuffer by specifying urls in the sql text await c query create table direct as select from https origin remote parquet or by executing raw insert statements await c query insert into existing_table values 1 foo 2 bar httpfs by specifying urls in the sql text await c query create table direct as select from https origin remote parquet insert statement or by executing raw insert statements await c query insert into existing_table values 1 foo 2 bar", @@ -448,6 +441,13 @@ "url": "/docs/api/wasm/data_ingestion", "blurb": "DuckDB-Wasm has multiple ways to import data, depending on the format of the data. There are two steps to import data..." }, + { + "title": "Data Ingestion", + "text": "csv files csv files can be read using the read_csv function called either from within python or directly from within sql by default the read_csv function attempts to auto-detect the csv settings by sampling from the provided file import duckdb read from a file using fully auto-detected settings duckdb read_csv example csv read multiple csv files from a folder duckdb read_csv folder csv specify options on how the csv is formatted internally duckdb read_csv example csv header false sep override types of the first two columns duckdb read_csv example csv dtype int varchar use the experimental parallel csv reader duckdb read_csv example csv parallel true directly read a csv file from within sql duckdb sql select from example csv call read_csv from within sql duckdb sql select from read_csv_auto example csv see the csv loading page for more information parquet files parquet files can be read using the read_parquet function called either from within python or directly from within sql import duckdb read from a single parquet file duckdb read_parquet example parquet read multiple parquet files from a folder duckdb read_parquet folder parquet directly read a parquet file from within sql duckdb sql select from example parquet call read_parquet from within sql duckdb sql select from read_parquet example parquet see the parquet loading page for more information json files json files can be read using the read_json function called either from within python or directly from within sql by default the read_json function will automatically detect if a file contains newline-delimited json or regular json and will detect the schema of the objects stored within the json file import duckdb read from a single json file duckdb read_json example json read multiple json files from a folder duckdb read_json folder json directly read a json file from within sql duckdb sql select from example json call read_json from within sql duckdb sql select from read_json_auto example json dataframes arrow tables duckdb is automatically able to query a pandas dataframe polars dataframe or arrow object that is stored in a python variable by name duckdb supports querying multiple types of apache arrow objects including tables datasets recordbatchreaders and scanners see the python guides for more examples import duckdb import pandas as pd test_df pd dataframe from_dict i 1 2 3 4 j one two three four duckdb sql select from test_df fetchall 1 one 2 two 3 three 4 four duckdb also supports registering a dataframe or arrow object as a virtual table comparable to a sql view this is useful when querying a dataframe arrow object that is stored in another way as a class variable or a value in a dictionary below is a pandas example if your pandas dataframe is stored in another location here is an example of manually registering it import duckdb import pandas as pd my_dictionary my_dictionary test_df pd dataframe from_dict i 1 2 3 4 j one two three four duckdb register test_df_view my_dictionary test_df duckdb sql select from test_df_view fetchall 1 one 2 two 3 three 4 four you can also create a persistent table in duckdb from the contents of the dataframe or the view create a new table from the contents of a dataframe con execute create table test_df_table as select from test_df insert into an existing table from the contents of a dataframe con execute insert into test_df_table select from test_df pandas dataframes - object columns pandas dataframe columns of an object dtype require some special care since this stores values of arbitrary type to convert these columns to duckdb we first go through an analyze phase before converting the values in this analyze phase a sample of all the rows of the column are analyzed to determine the target type this sample size is by default set to 1000 if the type picked during the analyze step is wrong this will result in a failed to cast value error in which case you will need to increase the sample size the sample size can be changed by setting the pandas_analyze_sample config option example setting the sample size to 100000 duckdb default_connection execute set global pandas_analyze_sample 100000", + "category": "Python", + "url": "/docs/api/python/data_ingestion", + "blurb": "CSV Files CSV files can be read using the read_csv function, called either from within Python or directly from within..." + }, { "title": "Data Types", "text": "general-purpose data types the table below shows all the built-in general-purpose data types the alternatives listed in the aliases column can be used to refer to these types as well however note that the aliases are not part of the sql standard and hence might not be accepted by other database engines name aliases description --- --- --- bigint int8 long signed eight-byte integer bit bitstring string of 1 s and 0 s boolean bool logical logical boolean true false blob bytea binary varbinary variable-length binary data date calendar date year month day double float8 numeric decimal double precision floating-point number 8 bytes decimal prec scale fixed-precision number with the given width precision and scale hugeint signed sixteen-byte integer integer int4 int signed signed four-byte integer interval date time delta real float4 float single precision floating-point number 4 bytes smallint int2 short signed two-byte integer time time of day no time zone timestamp datetime combination of time and date timestamp with time zone timestamptz combination of time and date that uses the current time zone tinyint int1 signed one-byte integer ubigint unsigned eight-byte integer uinteger unsigned four-byte integer usmallint unsigned two-byte integer utinyint unsigned one-byte integer uuid uuid data type varchar char bpchar text string variable-length character string nested composite types duckdb supports four nested data types list struct map and union each supports different use cases and has a different structure name description rules when used in a column build from values define in ddl create --- --- --- --- --- list an ordered sequence of data values of the same type each row must have the same data type within each list but can have any number of elements 1 2 3 int struct a dictionary of multiple named values where each key is a string but the value can be a different type for each key each row must have the same keys i 42 j a struct i int j varchar map a dictionary of multiple named values each key having the same type and each value having the same type keys and values can be any type and can be different types from one another rows may have different keys map 1 2 a b map int varchar union a union of multiple alternative data types storing one of them in each value at a time a union also contains a discriminator tag value to inspect and access the currently set member type rows may be set to different member types of the union union_value num 2 union num int text varchar nesting list s struct s map s and union s can be arbitrarily nested to any depth so long as the type rules are observed -- struct with lists select birds duck goose heron aliens null amphibians frog toad -- struct with list of maps select test map 1 5 42 1 45 map 1 5 42 1 45 -- a list of unions select union_value num 2 union_value str abc union str varchar num integer links to detailed documentation", @@ -1003,17 +1003,17 @@ }, { "title": "Parquet Import", - "text": "how to load a parquet file into a table to read data from a parquet file use the read_parquet function in the from clause of a query select from read_parquet input parquet to create a new table using the result from a query use create table as from a select statement create table new_tbl as select from read_parquet input parquet to load data into an existing table from a query use insert into from a select statement insert into tbl select from read_parquet input parquet alternatively the copy statement can also be used to load data from a parquet file into an existing table copy tbl from input parquet format parquet for additional options see the parquet loading reference", + "text": "how to run a query directly on a parquet file to run a query directly on a parquet file use the read_parquet function in the from clause of a query select from read_parquet input parquet the parquet file will be processed in parallel filters will be automatically pushed down into the parquet scan and only the relevant columns will be read automatically for more information see the blog post querying parquet with precision using duckdb", "category": "Import", - "url": "/docs/guides/import/parquet_import", - "blurb": "How to load a Parquet file into a table To read data from a Parquet file, use the read_parquet function in the FROM..." + "url": "/docs/guides/import/query_parquet", + "blurb": "How to run a query directly on a Parquet file To run a query directly on a Parquet file, use the read_parquet..." }, { "title": "Parquet Import", - "text": "how to run a query directly on a parquet file to run a query directly on a parquet file use the read_parquet function in the from clause of a query select from read_parquet input parquet the parquet file will be processed in parallel filters will be automatically pushed down into the parquet scan and only the relevant columns will be read automatically for more information see the blog post querying parquet with precision using duckdb", + "text": "how to load a parquet file into a table to read data from a parquet file use the read_parquet function in the from clause of a query select from read_parquet input parquet to create a new table using the result from a query use create table as from a select statement create table new_tbl as select from read_parquet input parquet to load data into an existing table from a query use insert into from a select statement insert into tbl select from read_parquet input parquet alternatively the copy statement can also be used to load data from a parquet file into an existing table copy tbl from input parquet format parquet for additional options see the parquet loading reference", "category": "Import", - "url": "/docs/guides/import/query_parquet", - "blurb": "How to run a query directly on a Parquet file To run a query directly on a Parquet file, use the read_parquet..." + "url": "/docs/guides/import/parquet_import", + "blurb": "How to load a Parquet file into a table To read data from a Parquet file, use the read_parquet function in the FROM..." }, { "title": "Parquet Loading", diff --git a/docs/api/python/reference/index.md b/docs/api/python/reference/index.md index b3a7db9fcb6..15fbac77673 100644 --- a/docs/api/python/reference/index.md +++ b/docs/api/python/reference/index.md @@ -44,6 +44,15 @@ title: Python Client API
+
+
+class duckdb.BinaryValue(object: Any) +
+
+

Bases: Value

+
+
+
exception duckdb.BinderException @@ -53,6 +62,33 @@ title: Python Client API
+
+
+class duckdb.BitValue(object: Any) +
+
+

Bases: Value

+
+
+ +
+
+class duckdb.BlobValue(object: Any) +
+
+

Bases: Value

+
+
+ +
+
+class duckdb.BooleanValue(object: Any) +
+
+

Bases: Value

+
+
+
duckdb.CaseExpression(condition: duckdb.duckdb.Expression, value: duckdb.duckdb.Expression) → duckdb.duckdb.Expression @@ -132,6 +168,33 @@ title: Python Client API
+
+
+class duckdb.DateValue(object: Any) +
+
+

Bases: Value

+
+
+ +
+
+class duckdb.DecimalValue(object: Any, width: int, scale: int) +
+
+

Bases: Value

+
+
+ +
+
+class duckdb.DoubleValue(object: Any) +
+
+

Bases: Value

+
+
+
class duckdb.DuckDBPyConnection @@ -383,7 +446,7 @@ title: Python Client API
-from_csv_auto(self: duckdb.duckdb.DuckDBPyConnection, name: object, *, header: object = None, compression: object = None, sep: object = None, delimiter: object = None, dtype: object = None, na_values: object = None, skiprows: object = None, quotechar: object = None, escapechar: object = None, encoding: object = None, parallel: object = None, date_format: object = None, timestamp_format: object = None, sample_size: object = None, all_varchar: object = None, normalize_names: object = None, filename: object = None, null_padding: object = None) → duckdb.duckdb.DuckDBPyRelation +from_csv_auto(self: duckdb.duckdb.DuckDBPyConnection, name: object, *, header: object = None, compression: object = None, sep: object = None, delimiter: object = None, dtype: object = None, na_values: object = None, skiprows: object = None, quotechar: object = None, escapechar: object = None, encoding: object = None, parallel: object = None, date_format: object = None, timestamp_format: object = None, sample_size: object = None, all_varchar: object = None, normalize_names: object = None, filename: object = None, null_padding: object = None, names: object = None) → duckdb.duckdb.DuckDBPyRelation

Create a relation object from the CSV file in ‘name’

@@ -544,7 +607,7 @@ title: Python Client API
-read_csv(self: duckdb.duckdb.DuckDBPyConnection, name: object, *, header: object = None, compression: object = None, sep: object = None, delimiter: object = None, dtype: object = None, na_values: object = None, skiprows: object = None, quotechar: object = None, escapechar: object = None, encoding: object = None, parallel: object = None, date_format: object = None, timestamp_format: object = None, sample_size: object = None, all_varchar: object = None, normalize_names: object = None, filename: object = None, null_padding: object = None) → duckdb.duckdb.DuckDBPyRelation +read_csv(self: duckdb.duckdb.DuckDBPyConnection, name: object, *, header: object = None, compression: object = None, sep: object = None, delimiter: object = None, dtype: object = None, na_values: object = None, skiprows: object = None, quotechar: object = None, escapechar: object = None, encoding: object = None, parallel: object = None, date_format: object = None, timestamp_format: object = None, sample_size: object = None, all_varchar: object = None, normalize_names: object = None, filename: object = None, null_padding: object = None, names: object = None) → duckdb.duckdb.DuckDBPyRelation

Create a relation object from the CSV file in ‘name’

@@ -1180,7 +1243,7 @@ title: Python Client API
-join(self: duckdb.duckdb.DuckDBPyRelation, other_rel: duckdb.duckdb.DuckDBPyRelation, condition: str, how: str = 'inner') → duckdb.duckdb.DuckDBPyRelation +join(self: duckdb.duckdb.DuckDBPyRelation, other_rel: duckdb.duckdb.DuckDBPyRelation, condition: object, how: str = 'inner') → duckdb.duckdb.DuckDBPyRelation

Join the relation object with another relation object in other_rel using the join condition expression in join_condition. Types supported are ‘inner’ and ‘left’

@@ -1351,7 +1414,7 @@ title: Python Client API
-project(self: duckdb.duckdb.DuckDBPyRelation, *args) → duckdb.duckdb.DuckDBPyRelation +project(self: duckdb.duckdb.DuckDBPyRelation, *args, **kwargs) → duckdb.duckdb.DuckDBPyRelation

Project the relation object by the projection in project_expr

@@ -1432,7 +1495,7 @@ title: Python Client API
-select(self: duckdb.duckdb.DuckDBPyRelation, *args) → duckdb.duckdb.DuckDBPyRelation +select(self: duckdb.duckdb.DuckDBPyRelation, *args, **kwargs) → duckdb.duckdb.DuckDBPyRelation

Project the relation object by the projection in project_expr

@@ -1477,7 +1540,7 @@ title: Python Client API
-show(self: duckdb.duckdb.DuckDBPyRelation) → None +show(self: duckdb.duckdb.DuckDBPyRelation, *, max_width: Optional[int] = None, max_rows: Optional[int] = None, max_col_width: Optional[int] = None, null_value: Optional[str] = None, render_mode: object = None) → None

Display a summary of the data

@@ -1782,6 +1845,16 @@ title: Python Client API

Create a copy of this expression with the given alias.

+
+
Parameters:
+
+

name: The alias to use for the expression, this will affect how it can be referenced.

+
+
Returns:
+
+

Expression: self with an alias.

+
+
@@ -1799,7 +1872,17 @@ title: Python Client API cast(self: duckdb.duckdb.Expression, type: duckdb.duckdb.typing.DuckDBPyType) → duckdb.duckdb.Expression
-

TODO: add docs.

+

Create a CastExpression to type from self

+
+
Parameters:
+
+

type: The type to cast to

+
+
Returns:
+
+

CastExpression: self::type

+
+
@@ -1865,7 +1948,17 @@ title: Python Client API otherwise(self: duckdb.duckdb.Expression, value: duckdb.duckdb.Expression) → duckdb.duckdb.Expression
-

TODO: add docs.

+

Add an ELSE <value> clause to the CaseExpression.

+
+
Parameters:
+
+

value: The value to use if none of the WHEN conditions are met.

+
+
Returns:
+
+

CaseExpression: self with an ELSE clause.

+
+
@@ -1883,7 +1976,18 @@ title: Python Client API when(self: duckdb.duckdb.Expression, condition: duckdb.duckdb.Expression, value: duckdb.duckdb.Expression) → duckdb.duckdb.Expression
-

TODO: add docs.

+

Add an additional WHEN <condition> THEN <value> clause to the CaseExpression.

+
+
Parameters:
+
+

condition: The condition that must be met. +value: The value to use if the condition is met.

+
+
Returns:
+
+

CaseExpression: self with an additional WHEN clause.

+
+
@@ -1899,6 +2003,15 @@ title: Python Client API
+
+
+class duckdb.FloatValue(object: Any) +
+
+

Bases: Value

+
+
+
duckdb.FunctionExpression(function_name: str, *args) → duckdb.duckdb.Expression @@ -1944,6 +2057,15 @@ title: Python Client API
+
+
+class duckdb.HugeIntegerValue(object: Any) +
+
+

Bases: Value

+
+
+
exception duckdb.IOException @@ -1953,6 +2075,15 @@ title: Python Client API
+
+
+class duckdb.IntegerValue(object: Any) +
+
+

Bases: Value

+
+
+
exception duckdb.IntegrityError @@ -1989,6 +2120,15 @@ title: Python Client API
+
+
+class duckdb.IntervalValue(object: Any) +
+
+

Bases: Value

+
+
+
exception duckdb.InvalidInputException @@ -2007,6 +2147,15 @@ title: Python Client API
+
+
+class duckdb.LongValue(object: Any) +
+
+

Bases: Value

+
+
+
exception duckdb.NotImplementedException @@ -2025,6 +2174,15 @@ title: Python Client API
+
+
+class duckdb.NullValue +
+
+

Bases: Value

+
+
+
exception duckdb.OperationalError @@ -2137,6 +2295,15 @@ title: Python Client API
+
+
+class duckdb.ShortValue(object: Any) +
+
+

Bases: Value

+
+
+
exception duckdb.StandardException @@ -2159,6 +2326,15 @@ title: Python Client API
+
+
+class duckdb.StringValue(object: Any) +
+
+

Bases: Value

+
+
+
exception duckdb.SyntaxException @@ -2168,6 +2344,69 @@ title: Python Client API
+
+
+class duckdb.TimeTimeZoneValue(object: Any) +
+
+

Bases: Value

+
+
+ +
+
+class duckdb.TimeValue(object: Any) +
+
+

Bases: Value

+
+
+ +
+
+class duckdb.TimestampMilisecondValue(object: Any) +
+
+

Bases: Value

+
+
+ +
+
+class duckdb.TimestampNanosecondValue(object: Any) +
+
+

Bases: Value

+
+
+ +
+
+class duckdb.TimestampSecondValue(object: Any) +
+
+

Bases: Value

+
+
+ +
+
+class duckdb.TimestampTimeZoneValue(object: Any) +
+
+

Bases: Value

+
+
+ +
+
+class duckdb.TimestampValue(object: Any) +
+
+

Bases: Value

+
+
+
exception duckdb.TransactionException @@ -2186,6 +2425,60 @@ title: Python Client API
+
+
+class duckdb.UUIDValue(object: Any) +
+
+

Bases: Value

+
+
+ +
+
+class duckdb.UnsignedBinaryValue(object: Any) +
+
+

Bases: Value

+
+
+ +
+
+class duckdb.UnsignedIntegerValue(object: Any) +
+
+

Bases: Value

+
+
+ +
+
+class duckdb.UnsignedLongValue(object: Any) +
+
+

Bases: Value

+
+
+ +
+
+class duckdb.UnsignedShortValue(object: Any) +
+
+

Bases: Value

+
+
+ +
+
+class duckdb.Value(object: Any, type: DuckDBPyType) +
+
+

Bases: object

+
+
+
exception duckdb.ValueOutOfRangeException @@ -2510,7 +2803,7 @@ title: Python Client API
-duckdb.from_csv_auto(name: object, connection: duckdb.DuckDBPyConnection = None, header: object = None, compression: object = None, sep: object = None, delimiter: object = None, dtype: object = None, na_values: object = None, skiprows: object = None, quotechar: object = None, escapechar: object = None, encoding: object = None, parallel: object = None, date_format: object = None, timestamp_format: object = None, sample_size: object = None, all_varchar: object = None, normalize_names: object = None, filename: object = None, null_padding: object = None) → duckdb.duckdb.DuckDBPyRelation +duckdb.from_csv_auto(name: object, connection: duckdb.DuckDBPyConnection = None, header: object = None, compression: object = None, sep: object = None, delimiter: object = None, dtype: object = None, na_values: object = None, skiprows: object = None, quotechar: object = None, escapechar: object = None, encoding: object = None, parallel: object = None, date_format: object = None, timestamp_format: object = None, sample_size: object = None, all_varchar: object = None, normalize_names: object = None, filename: object = None, null_padding: object = None, names: object = None) → duckdb.duckdb.DuckDBPyRelation

Create a relation object from the CSV file in ‘name’

@@ -2731,7 +3024,7 @@ title: Python Client API
-duckdb.read_csv(name: object, connection: duckdb.DuckDBPyConnection = None, header: object = None, compression: object = None, sep: object = None, delimiter: object = None, dtype: object = None, na_values: object = None, skiprows: object = None, quotechar: object = None, escapechar: object = None, encoding: object = None, parallel: object = None, date_format: object = None, timestamp_format: object = None, sample_size: object = None, all_varchar: object = None, normalize_names: object = None, filename: object = None, null_padding: object = None) → duckdb.duckdb.DuckDBPyRelation +duckdb.read_csv(name: object, connection: duckdb.DuckDBPyConnection = None, header: object = None, compression: object = None, sep: object = None, delimiter: object = None, dtype: object = None, na_values: object = None, skiprows: object = None, quotechar: object = None, escapechar: object = None, encoding: object = None, parallel: object = None, date_format: object = None, timestamp_format: object = None, sample_size: object = None, all_varchar: object = None, normalize_names: object = None, filename: object = None, null_padding: object = None, names: object = None) → duckdb.duckdb.DuckDBPyRelation

Create a relation object from the CSV file in ‘name’

From ba4d12b0b615f61a2832bca6142c82dd7622447d Mon Sep 17 00:00:00 2001 From: GitHub Actions Date: Mon, 9 Oct 2023 05:06:05 +0000 Subject: [PATCH 12/12] chore: auto update docs --- data/search_data.json | 6 +++--- docs/api/c/api.md | 10 +++++----- docs/api/c/connect.md | 4 ++-- docs/api/c/prepared.md | 6 +++--- 4 files changed, 13 insertions(+), 13 deletions(-) diff --git a/data/search_data.json b/data/search_data.json index 4a6c5bab56a..7aa6791d5ac 100644 --- a/data/search_data.json +++ b/data/search_data.json @@ -163,7 +163,7 @@ }, { "title": "C API - Complete API", - "text": "api reference open connect syntax path to the database file on disk or nullptr or memory to open an in-memory database out_database the result database object returns duckdbsuccess on success or duckdberror on failure duckdb_open_ext extended version of duckdb_open creates a new database or opens an existing database file stored at the the given path syntax path to the database file on disk or nullptr or memory to open an in-memory database out_database the result database object config optional configuration used to start up the database system out_error if set and the function returns duckdberror this will contain the reason why the start-up failed note that the error must be freed using duckdb_free returns duckdbsuccess on success or duckdberror on failure duckdb_close closes the specified database and de-allocates all memory allocated for that database this should be called after you are done with any database allocated through duckdb_open note that failing to call duckdb_close in case of e g a program crash will not cause data corruption still it is recommended to always correctly close a database object after you are done with it syntax the database object to shut down duckdb_connect opens a connection to a database connections are required to query the database and store transactional state associated with the connection the instantiated connection should be closed using duckdb_disconnect syntax the database file to connect to out_connection the result connection object returns duckdbsuccess on success or duckdberror on failure duckdb_interrupt interrupt running query syntax the connection to interruot duckdb_query_progress get progress of the running query syntax the working connection returns -1 if no progress or a percentage of the progress duckdb_disconnect closes the specified connection and de-allocates all memory allocated for that connection syntax the connection to close duckdb_library_version returns the version of the linked duckdb with a version postfix for dev versions usually used for developing c extensions that must return this for a compatibility check syntax duckdb_create_config initializes an empty configuration object that can be used to provide start-up options for the duckdb instance through duckdb_open_ext this will always succeed unless there is a malloc failure syntax the result configuration object returns duckdbsuccess on success or duckdberror on failure duckdb_config_count this returns the total amount of configuration options available for usage with duckdb_get_config_flag this should not be called in a loop as it internally loops over all the options syntax the amount of config options available duckdb_get_config_flag obtains a human-readable name and description of a specific configuration option this can be used to e g display configuration options this will succeed unless index is out of range i e duckdb_config_count the result name or description must not be freed syntax the index of the configuration option between 0 and duckdb_config_count out_name a name of the configuration flag out_description a description of the configuration flag returns duckdbsuccess on success or duckdberror on failure duckdb_set_config sets the specified option for the specified configuration the configuration option is indicated by name to obtain a list of config options see duckdb_get_config_flag in the source code configuration options are defined in config cpp this can fail if either the name is invalid or if the value provided for the option is invalid syntax the configuration object to set the option on name the name of the configuration flag to set option the value to set the configuration flag to returns duckdbsuccess on success or duckdberror on failure duckdb_destroy_config destroys the specified configuration option and de-allocates all memory allocated for the object syntax the configuration object to destroy duckdb_query executes a sql query within a connection and stores the full materialized result in the out_result pointer if the query fails to execute duckdberror is returned and the error message can be retrieved by calling duckdb_result_error note that after running duckdb_query duckdb_destroy_result must be called on the result object even if the query fails otherwise the error stored within the result will not be freed correctly syntax the connection to perform the query in query the sql query to run out_result the query result returns duckdbsuccess on success or duckdberror on failure duckdb_destroy_result closes the result and de-allocates all memory allocated for that connection syntax the result to destroy duckdb_column_name returns the column name of the specified column the result should not need be freed the column names will automatically be destroyed when the result is destroyed returns null if the column is out of range syntax the result object to fetch the column name from col the column index returns the column name of the specified column duckdb_column_type returns the column type of the specified column returns duckdb_type_invalid if the column is out of range syntax the result object to fetch the column type from col the column index returns the column type of the specified column duckdb_column_logical_type returns the logical column type of the specified column the return type of this call should be destroyed with duckdb_destroy_logical_type returns null if the column is out of range syntax the result object to fetch the column type from col the column index returns the logical column type of the specified column duckdb_column_count returns the number of columns present in a the result object syntax the result object returns the number of columns present in the result object duckdb_row_count returns the number of rows present in a the result object syntax the result object returns the number of rows present in the result object duckdb_rows_changed returns the number of rows changed by the query stored in the result this is relevant only for insert update delete queries for other queries the rows_changed will be 0 syntax the result object returns the number of rows changed duckdb_column_data deprecated prefer using duckdb_result_get_chunk instead returns the data of a specific column of a result in columnar format the function returns a dense array which contains the result data the exact type stored in the array depends on the corresponding duckdb_type as provided by duckdb_column_type for the exact type by which the data should be accessed see the comments in the types section or the duckdb_type enum for example for a column of type duckdb_type_integer rows can be accessed in the following manner int32_t data int32_t duckdb_column_data result 0 printf data for row d d n row data row syntax the result object to fetch the column data from col the column index returns the column data of the specified column duckdb_nullmask_data deprecated prefer using duckdb_result_get_chunk instead returns the nullmask of a specific column of a result in columnar format the nullmask indicates for every row whether or not the corresponding row is null if a row is null the values present in the array provided by duckdb_column_data are undefined int32_t data int32_t duckdb_column_data result 0 bool nullmask duckdb_nullmask_data result 0 if nullmask row printf data for row d null n row else printf data for row d d n row data row syntax the result object to fetch the nullmask from col the column index returns the nullmask of the specified column duckdb_result_error returns the error message contained within the result the error is only set if duckdb_query returns duckdberror the result of this function must not be freed it will be cleaned up when duckdb_destroy_result is called syntax the result object to fetch the error from returns the error of the result duckdb_result_get_chunk fetches a data chunk from the duckdb_result this function should be called repeatedly until the result is exhausted the result must be destroyed with duckdb_destroy_data_chunk this function supersedes all duckdb_value functions as well as the duckdb_column_data and duckdb_nullmask_data functions it results in significantly better performance and should be preferred in newer code-bases if this function is used none of the other result functions can be used and vice versa i e this function cannot be mixed with the legacy result functions use duckdb_result_chunk_count to figure out how many chunks there are in the result syntax the result object to fetch the data chunk from chunk_index the chunk index to fetch from returns the resulting data chunk returns null if the chunk index is out of bounds duckdb_result_is_streaming checks if the type of the internal result is streamqueryresult syntax the result object to check returns whether or not the result object is of the type streamqueryresult duckdb_result_chunk_count returns the number of data chunks present in the result syntax the result object returns number of data chunks present in the result duckdb_value_boolean syntax the boolean value at the specified location or false if the value cannot be converted duckdb_value_int8 syntax the int8_t value at the specified location or 0 if the value cannot be converted duckdb_value_int16 syntax the int16_t value at the specified location or 0 if the value cannot be converted duckdb_value_int32 syntax the int32_t value at the specified location or 0 if the value cannot be converted duckdb_value_int64 syntax the int64_t value at the specified location or 0 if the value cannot be converted duckdb_value_hugeint syntax the duckdb_hugeint value at the specified location or 0 if the value cannot be converted duckdb_value_decimal syntax the duckdb_decimal value at the specified location or 0 if the value cannot be converted duckdb_value_uint8 syntax the uint8_t value at the specified location or 0 if the value cannot be converted duckdb_value_uint16 syntax the uint16_t value at the specified location or 0 if the value cannot be converted duckdb_value_uint32 syntax the uint32_t value at the specified location or 0 if the value cannot be converted duckdb_value_uint64 syntax the uint64_t value at the specified location or 0 if the value cannot be converted duckdb_value_float syntax the float value at the specified location or 0 if the value cannot be converted duckdb_value_double syntax the double value at the specified location or 0 if the value cannot be converted duckdb_value_date syntax the duckdb_date value at the specified location or 0 if the value cannot be converted duckdb_value_time syntax the duckdb_time value at the specified location or 0 if the value cannot be converted duckdb_value_timestamp syntax the duckdb_timestamp value at the specified location or 0 if the value cannot be converted duckdb_value_interval syntax the duckdb_interval value at the specified location or 0 if the value cannot be converted duckdb_value_varchar syntax use duckdb_value_string instead this function does not work correctly if the string contains null bytes returns the text value at the specified location as a null-terminated string or nullptr if the value cannot be converted the result must be freed with duckdb_free duckdb_value_varchar_internal syntax use duckdb_value_string_internal instead this function does not work correctly if the string contains null bytes returns the char value at the specified location only works on varchar columns and does not auto-cast if the column is not a varchar column this function will return null the result must not be freed duckdb_value_string_internal syntax use duckdb_value_string_internal instead this function does not work correctly if the string contains null bytes returns the char value at the specified location only works on varchar columns and does not auto-cast if the column is not a varchar column this function will return null the result must not be freed duckdb_value_blob syntax the duckdb_blob value at the specified location returns a blob with blob data set to nullptr if the value cannot be converted the resulting blob data must be freed with duckdb_free duckdb_value_is_null syntax returns true if the value at the specified index is null and false otherwise duckdb_malloc allocate size bytes of memory using the duckdb internal malloc function any memory allocated in this manner should be freed using duckdb_free syntax the number of bytes to allocate returns a pointer to the allocated memory region duckdb_free free a value returned from duckdb_malloc duckdb_value_varchar or duckdb_value_blob syntax the memory region to de-allocate duckdb_vector_size the internal vector size used by duckdb this is the amount of tuples that will fit into a data chunk created by duckdb_create_data_chunk syntax the vector size duckdb_string_is_inlined whether or not the duckdb_string_t value is inlined this means that the data of the string does not have a separate allocation syntax duckdb_from_date decompose a duckdb_date object into year month and date stored as duckdb_date_struct syntax the date object as obtained from a duckdb_type_date column returns the duckdb_date_struct with the decomposed elements duckdb_to_date re-compose a duckdb_date from year month and date duckdb_date_struct syntax the year month and date stored in a duckdb_date_struct returns the duckdb_date element duckdb_from_time decompose a duckdb_time object into hour minute second and microsecond stored as duckdb_time_struct syntax the time object as obtained from a duckdb_type_time column returns the duckdb_time_struct with the decomposed elements duckdb_to_time re-compose a duckdb_time from hour minute second and microsecond duckdb_time_struct syntax the hour minute second and microsecond in a duckdb_time_struct returns the duckdb_time element duckdb_from_timestamp decompose a duckdb_timestamp object into a duckdb_timestamp_struct syntax the ts object as obtained from a duckdb_type_timestamp column returns the duckdb_timestamp_struct with the decomposed elements duckdb_to_timestamp re-compose a duckdb_timestamp from a duckdb_timestamp_struct syntax the de-composed elements in a duckdb_timestamp_struct returns the duckdb_timestamp element duckdb_hugeint_to_double converts a duckdb_hugeint object as obtained from a duckdb_type_hugeint column into a double syntax the hugeint value returns the converted double element duckdb_double_to_hugeint converts a double value to a duckdb_hugeint object if the conversion fails because the double value is too big the result will be 0 syntax the double value returns the converted duckdb_hugeint element duckdb_double_to_decimal converts a double value to a duckdb_decimal object if the conversion fails because the double value is too big or the width scale are invalid the result will be 0 syntax the double value returns the converted duckdb_decimal element duckdb_decimal_to_double converts a duckdb_decimal object as obtained from a duckdb_type_decimal column into a double syntax the decimal value returns the converted double element duckdb_prepare create a prepared statement object from a query note that after calling duckdb_prepare the prepared statement should always be destroyed using duckdb_destroy_prepare even if the prepare fails if the prepare fails duckdb_prepare_error can be called to obtain the reason why the prepare failed syntax the connection object query the sql query to prepare out_prepared_statement the resulting prepared statement object returns duckdbsuccess on success or duckdberror on failure duckdb_destroy_prepare closes the prepared statement and de-allocates all memory allocated for the statement syntax the prepared statement to destroy duckdb_prepare_error returns the error message associated with the given prepared statement if the prepared statement has no error message this returns nullptr instead the error message should not be freed it will be de-allocated when duckdb_destroy_prepare is called syntax the prepared statement to obtain the error from returns the error message or nullptr if there is none duckdb_nparams returns the number of parameters that can be provided to the given prepared statement returns 0 if the query was not successfully prepared syntax the prepared statement to obtain the number of parameters for duckdb_param_type returns the parameter type for the parameter at the given index returns duckdb_type_invalid if the parameter index is out of range or the statement was not successfully prepared syntax the prepared statement param_idx the parameter index returns the parameter type duckdb_clear_bindings clear the params bind to the prepared statement syntax duckdb_bind_value binds a value to the prepared statement at the specified index syntax duckdb_bind_parameter_index retrieve the index of the parameter for the prepared statement identified by name syntax duckdb_bind_boolean binds a bool value to the prepared statement at the specified index syntax duckdb_bind_int8 binds an int8_t value to the prepared statement at the specified index syntax duckdb_bind_int16 binds an int16_t value to the prepared statement at the specified index syntax duckdb_bind_int32 binds an int32_t value to the prepared statement at the specified index syntax duckdb_bind_int64 binds an int64_t value to the prepared statement at the specified index syntax duckdb_bind_hugeint binds an duckdb_hugeint value to the prepared statement at the specified index syntax duckdb_bind_decimal binds a duckdb_decimal value to the prepared statement at the specified index syntax duckdb_bind_uint8 binds an uint8_t value to the prepared statement at the specified index syntax duckdb_bind_uint16 binds an uint16_t value to the prepared statement at the specified index syntax duckdb_bind_uint32 binds an uint32_t value to the prepared statement at the specified index syntax duckdb_bind_uint64 binds an uint64_t value to the prepared statement at the specified index syntax duckdb_bind_float binds an float value to the prepared statement at the specified index syntax duckdb_bind_double binds an double value to the prepared statement at the specified index syntax duckdb_bind_date binds a duckdb_date value to the prepared statement at the specified index syntax duckdb_bind_time binds a duckdb_time value to the prepared statement at the specified index syntax duckdb_bind_timestamp binds a duckdb_timestamp value to the prepared statement at the specified index syntax duckdb_bind_interval binds a duckdb_interval value to the prepared statement at the specified index syntax duckdb_bind_varchar binds a null-terminated varchar value to the prepared statement at the specified index syntax duckdb_bind_varchar_length binds a varchar value to the prepared statement at the specified index syntax duckdb_bind_blob binds a blob value to the prepared statement at the specified index syntax duckdb_bind_null binds a null value to the prepared statement at the specified index syntax duckdb_execute_prepared executes the prepared statement with the given bound parameters and returns a materialized query result this method can be called multiple times for each prepared statement and the parameters can be modified between calls to this function syntax the prepared statement to execute out_result the query result returns duckdbsuccess on success or duckdberror on failure duckdb_execute_prepared_arrow executes the prepared statement with the given bound parameters and returns an arrow query result syntax the prepared statement to execute out_result the query result returns duckdbsuccess on success or duckdberror on failure duckdb_arrow_scan scans the arrow stream and creates a view with the given name syntax the connection on which to execute the scan table_name name of the temporary view to create arrow arrow stream wrapper returns duckdbsuccess on success or duckdberror on failure duckdb_arrow_array_scan scans the arrow array and creates a view with the given name syntax the connection on which to execute the scan table_name name of the temporary view to create arrow_schema arrow schema wrapper arrow_array arrow array wrapper out_stream output array stream that wraps around the passed schema for releasing deleting once done returns duckdbsuccess on success or duckdberror on failure duckdb_extract_statements extract all statements from a query note that after calling duckdb_extract_statements the extracted statements should always be destroyed using duckdb_destroy_extracted even if no statements were extracted if the extract fails duckdb_extract_statements_error can be called to obtain the reason why the extract failed syntax the connection object query the sql query to extract out_extracted_statements the resulting extracted statements object returns the number of extracted statements or 0 on failure duckdb_prepare_extracted_statement prepare an extracted statement note that after calling duckdb_prepare_extracted_statement the prepared statement should always be destroyed using duckdb_destroy_prepare even if the prepare fails if the prepare fails duckdb_prepare_error can be called to obtain the reason why the prepare failed syntax the connection object extracted_statements the extracted statements object index the index of the extracted statement to prepare out_prepared_statement the resulting prepared statement object returns duckdbsuccess on success or duckdberror on failure duckdb_extract_statements_error returns the error message contained within the extracted statements the result of this function must not be freed it will be cleaned up when duckdb_destroy_extracted is called syntax the extracted statements to fetch the error from returns the error of the extracted statements duckdb_destroy_extracted de-allocates all memory allocated for the extracted statements syntax the extracted statements to destroy duckdb_pending_prepared executes the prepared statement with the given bound parameters and returns a pending result the pending result represents an intermediate structure for a query that is not yet fully executed the pending result can be used to incrementally execute a query returning control to the client between tasks note that after calling duckdb_pending_prepared the pending result should always be destroyed using duckdb_destroy_pending even if this function returns duckdberror syntax the prepared statement to execute out_result the pending query result returns duckdbsuccess on success or duckdberror on failure duckdb_pending_prepared_streaming executes the prepared statement with the given bound parameters and returns a pending result this pending result will create a streaming duckdb_result when executed the pending result represents an intermediate structure for a query that is not yet fully executed note that after calling duckdb_pending_prepared_streaming the pending result should always be destroyed using duckdb_destroy_pending even if this function returns duckdberror syntax the prepared statement to execute out_result the pending query result returns duckdbsuccess on success or duckdberror on failure duckdb_destroy_pending closes the pending result and de-allocates all memory allocated for the result syntax the pending result to destroy duckdb_pending_error returns the error message contained within the pending result the result of this function must not be freed it will be cleaned up when duckdb_destroy_pending is called syntax the pending result to fetch the error from returns the error of the pending result duckdb_pending_execute_task executes a single task within the query returning whether or not the query is ready if this returns duckdb_pending_result_ready the duckdb_execute_pending function can be called to obtain the result if this returns duckdb_pending_result_not_ready the duckdb_pending_execute_task function should be called again if this returns duckdb_pending_error an error occurred during execution the error message can be obtained by calling duckdb_pending_error on the pending_result syntax the pending result to execute a task within returns the state of the pending result after the execution duckdb_execute_pending fully execute a pending query result returning the final query result if duckdb_pending_execute_task has been called until duckdb_pending_result_ready was returned this will return fast otherwise all remaining tasks must be executed first syntax the pending result to execute out_result the result object returns duckdbsuccess on success or duckdberror on failure duckdb_pending_execution_is_finished returns whether a duckdb_pending_state is finished executing for example if pending_state is duckdb_pending_result_ready this function will return true syntax the pending state on which to decide whether to finish execution returns boolean indicating pending execution should be considered finished duckdb_destroy_value destroys the value and de-allocates all memory allocated for that type syntax the value to destroy duckdb_create_varchar creates a value from a null-terminated string syntax the null-terminated string returns the value this must be destroyed with duckdb_destroy_value duckdb_create_varchar_length creates a value from a string syntax the text length the length of the text returns the value this must be destroyed with duckdb_destroy_value duckdb_create_int64 creates a value from an int64 syntax the bigint value returns the value this must be destroyed with duckdb_destroy_value duckdb_get_varchar obtains a string representation of the given value the result must be destroyed with duckdb_free syntax the value returns the string value this must be destroyed with duckdb_free duckdb_get_int64 obtains an int64 of the given value syntax the value returns the int64 value or 0 if no conversion is possible duckdb_create_logical_type creates a duckdb_logical_type from a standard primitive type the resulting type should be destroyed with duckdb_destroy_logical_type this should not be used with duckdb_type_decimal syntax the primitive type to create returns the logical type duckdb_create_list_type creates a list type from its child type the resulting type should be destroyed with duckdb_destroy_logical_type syntax the child type of list type to create returns the logical type duckdb_create_map_type creates a map type from its key type and value type the resulting type should be destroyed with duckdb_destroy_logical_type syntax the key type and value type of map type to create returns the logical type duckdb_create_union_type creates a union type from the passed types array the resulting type should be destroyed with duckdb_destroy_logical_type syntax the array of types that the union should consist of type_amount the size of the types array returns the logical type duckdb_create_struct_type creates a struct type from the passed member name and type arrays the resulting type should be destroyed with duckdb_destroy_logical_type syntax the array of types that the struct should consist of member_names the array of names that the struct should consist of member_count the number of members that were specified for both arrays returns the logical type duckdb_create_decimal_type creates a duckdb_logical_type of type decimal with the specified width and scale the resulting type should be destroyed with duckdb_destroy_logical_type syntax the width of the decimal type scale the scale of the decimal type returns the logical type duckdb_get_type_id retrieves the type class of a duckdb_logical_type syntax the logical type object returns the type id duckdb_decimal_width retrieves the width of a decimal type syntax the logical type object returns the width of the decimal type duckdb_decimal_scale retrieves the scale of a decimal type syntax the logical type object returns the scale of the decimal type duckdb_decimal_internal_type retrieves the internal storage type of a decimal type syntax the logical type object returns the internal type of the decimal type duckdb_enum_internal_type retrieves the internal storage type of an enum type syntax the logical type object returns the internal type of the enum type duckdb_enum_dictionary_size retrieves the dictionary size of the enum type syntax the logical type object returns the dictionary size of the enum type duckdb_enum_dictionary_value retrieves the dictionary value at the specified position from the enum the result must be freed with duckdb_free syntax the logical type object index the index in the dictionary returns the string value of the enum type must be freed with duckdb_free duckdb_list_type_child_type retrieves the child type of the given list type the result must be freed with duckdb_destroy_logical_type syntax the logical type object returns the child type of the list type must be destroyed with duckdb_destroy_logical_type duckdb_map_type_key_type retrieves the key type of the given map type the result must be freed with duckdb_destroy_logical_type syntax the logical type object returns the key type of the map type must be destroyed with duckdb_destroy_logical_type duckdb_map_type_value_type retrieves the value type of the given map type the result must be freed with duckdb_destroy_logical_type syntax the logical type object returns the value type of the map type must be destroyed with duckdb_destroy_logical_type duckdb_struct_type_child_count returns the number of children of a struct type syntax the logical type object returns the number of children of a struct type duckdb_struct_type_child_name retrieves the name of the struct child the result must be freed with duckdb_free syntax the logical type object index the child index returns the name of the struct type must be freed with duckdb_free duckdb_struct_type_child_type retrieves the child type of the given struct type at the specified index the result must be freed with duckdb_destroy_logical_type syntax the logical type object index the child index returns the child type of the struct type must be destroyed with duckdb_destroy_logical_type duckdb_union_type_member_count returns the number of members that the union type has syntax the logical type union object returns the number of members of a union type duckdb_union_type_member_name retrieves the name of the union member the result must be freed with duckdb_free syntax the logical type object index the child index returns the name of the union member must be freed with duckdb_free duckdb_union_type_member_type retrieves the child type of the given union member at the specified index the result must be freed with duckdb_destroy_logical_type syntax the logical type object index the child index returns the child type of the union member must be destroyed with duckdb_destroy_logical_type duckdb_destroy_logical_type destroys the logical type and de-allocates all memory allocated for that type syntax the logical type to destroy duckdb_create_data_chunk creates an empty datachunk with the specified set of types syntax an array of types of the data chunk column_count the number of columns returns the data chunk duckdb_destroy_data_chunk destroys the data chunk and de-allocates all memory allocated for that chunk syntax the data chunk to destroy duckdb_data_chunk_reset resets a data chunk clearing the validity masks and setting the cardinality of the data chunk to 0 syntax the data chunk to reset duckdb_data_chunk_get_column_count retrieves the number of columns in a data chunk syntax the data chunk to get the data from returns the number of columns in the data chunk duckdb_data_chunk_get_vector retrieves the vector at the specified column index in the data chunk the pointer to the vector is valid for as long as the chunk is alive it does not need to be destroyed syntax the data chunk to get the data from returns the vector duckdb_data_chunk_get_size retrieves the current number of tuples in a data chunk syntax the data chunk to get the data from returns the number of tuples in the data chunk duckdb_data_chunk_set_size sets the current number of tuples in a data chunk syntax the data chunk to set the size in size the number of tuples in the data chunk duckdb_vector_get_column_type retrieves the column type of the specified vector the result must be destroyed with duckdb_destroy_logical_type syntax the vector get the data from returns the type of the vector duckdb_vector_get_data retrieves the data pointer of the vector the data pointer can be used to read or write values from the vector how to read or write values depends on the type of the vector syntax the vector to get the data from returns the data pointer duckdb_vector_get_validity retrieves the validity mask pointer of the specified vector if all values are valid this function might return null the validity mask is a bitset that signifies null-ness within the data chunk it is a series of uint64_t values where each uint64_t value contains validity for 64 tuples the bit is set to 1 if the value is valid i e not null or 0 if the value is invalid i e null validity of a specific value can be obtained like this idx_t entry_idx row_idx 64 idx_t idx_in_entry row_idx 64 bool is_valid validity_mask entry_idx 1 idx_in_entry alternatively the slower duckdb_validity_row_is_valid function can be used syntax the vector to get the data from returns the pointer to the validity mask or null if no validity mask is present duckdb_vector_ensure_validity_writable ensures the validity mask is writable by allocating it after this function is called duckdb_vector_get_validity will always return non-null this allows null values to be written to the vector regardless of whether a validity mask was present before syntax the vector to alter duckdb_vector_assign_string_element assigns a string element in the vector at the specified location syntax the vector to alter index the row position in the vector to assign the string to str the null-terminated string duckdb_vector_assign_string_element_len assigns a string element in the vector at the specified location syntax the vector to alter index the row position in the vector to assign the string to str the string str_len the length of the string in bytes duckdb_list_vector_get_child retrieves the child vector of a list vector the resulting vector is valid as long as the parent vector is valid syntax the vector returns the child vector duckdb_list_vector_get_size returns the size of the child vector of the list syntax the vector returns the size of the child list duckdb_list_vector_set_size sets the total size of the underlying child-vector of a list vector syntax the list vector size the size of the child list returns the duckdb state returns duckdberror if the vector is nullptr duckdb_list_vector_reserve sets the total capacity of the underlying child-vector of a list syntax the list vector required_capacity the total capacity to reserve return the duckdb state returns duckdberror if the vector is nullptr duckdb_struct_vector_get_child retrieves the child vector of a struct vector the resulting vector is valid as long as the parent vector is valid syntax the vector index the child index returns the child vector duckdb_validity_row_is_valid returns whether or not a row is valid i e not null in the given validity mask syntax the validity mask as obtained through duckdb_vector_get_validity row the row index returns true if the row is valid false otherwise duckdb_validity_set_row_validity in a validity mask sets a specific row to either valid or invalid note that duckdb_vector_ensure_validity_writable should be called before calling duckdb_vector_get_validity to ensure that there is a validity mask to write to syntax the validity mask as obtained through duckdb_vector_get_validity row the row index valid whether or not to set the row to valid or invalid duckdb_validity_set_row_invalid in a validity mask sets a specific row to invalid equivalent to duckdb_validity_set_row_validity with valid set to false syntax the validity mask row the row index duckdb_validity_set_row_valid in a validity mask sets a specific row to valid equivalent to duckdb_validity_set_row_validity with valid set to true syntax the validity mask row the row index duckdb_create_table_function creates a new empty table function the return value should be destroyed with duckdb_destroy_table_function syntax the table function object duckdb_destroy_table_function destroys the given table function object syntax the table function to destroy duckdb_table_function_set_name sets the name of the given table function syntax the table function name the name of the table function duckdb_table_function_add_parameter adds a parameter to the table function syntax 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 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 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 the table function bind the bind function duckdb_table_function_set_init sets the init function of the table function syntax the table function init the init function duckdb_table_function_set_local_init sets the thread-local init function of the table function syntax the table function init the init function duckdb_table_function_set_function sets the main function of the table function syntax 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 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 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 the info object returns the extra info duckdb_bind_add_result_column adds a result column to the output of the table function syntax 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 the info object returns the init data object duckdb_function_set_error report that an error has occurred while executing the function syntax the info object error the error message duckdb_add_replacement_scan add a replacement scan definition to the specified database syntax the database object to add the replacement scan to replacement the replacement scan callback extra_data extra data that is passed back into the specified callback delete_callback the delete callback to call on the extra data if any duckdb_replacement_scan_set_function_name sets the replacement function name to use if this function is called in the replacement callback the replacement scan is performed if it is not called the replacement callback is not performed syntax the info object function_name the function name to substitute duckdb_replacement_scan_add_parameter adds a parameter to the replacement scan function syntax the info object parameter the parameter to add duckdb_replacement_scan_set_error report that an error has occurred while executing the replacement scan syntax the info object error the error message duckdb_appender_create creates an appender object syntax the connection context to create the appender in schema the schema of the table to append to or nullptr for the default schema table the table name to append to out_appender the resulting appender object returns duckdbsuccess on success or duckdberror on failure duckdb_appender_error returns the error message associated with the given appender if the appender has no error message this returns nullptr instead the error message should not be freed it will be de-allocated when duckdb_appender_destroy is called syntax the appender to get the error from returns the error message or nullptr if there is none duckdb_appender_flush flush the appender to the table forcing the cache of the appender to be cleared and the data to be appended to the base table this should generally not be used unless you know what you are doing instead call duckdb_appender_destroy when you are done with the appender syntax the appender to flush returns duckdbsuccess on success or duckdberror on failure duckdb_appender_close close the appender flushing all intermediate state in the appender to the table and closing it for further appends this is generally not necessary call duckdb_appender_destroy instead syntax the appender to flush and close returns duckdbsuccess on success or duckdberror on failure duckdb_appender_destroy close the appender and destroy it flushing all intermediate state in the appender to the table and de-allocating all memory associated with the appender syntax the appender to flush close and destroy returns duckdbsuccess on success or duckdberror on failure duckdb_appender_begin_row a nop function provided for backwards compatibility reasons does nothing only duckdb_appender_end_row is required syntax duckdb_appender_end_row finish the current row of appends after end_row is called the next row can be appended syntax the appender returns duckdbsuccess on success or duckdberror on failure duckdb_append_bool append a bool value to the appender syntax duckdb_append_int8 append an int8_t value to the appender syntax duckdb_append_int16 append an int16_t value to the appender syntax duckdb_append_int32 append an int32_t value to the appender syntax duckdb_append_int64 append an int64_t value to the appender syntax duckdb_append_hugeint append a duckdb_hugeint value to the appender syntax duckdb_append_uint8 append a uint8_t value to the appender syntax duckdb_append_uint16 append a uint16_t value to the appender syntax duckdb_append_uint32 append a uint32_t value to the appender syntax duckdb_append_uint64 append a uint64_t value to the appender syntax duckdb_append_float append a float value to the appender syntax duckdb_append_double append a double value to the appender syntax duckdb_append_date append a duckdb_date value to the appender syntax duckdb_append_time append a duckdb_time value to the appender syntax duckdb_append_timestamp append a duckdb_timestamp value to the appender syntax duckdb_append_interval append a duckdb_interval value to the appender syntax duckdb_append_varchar append a varchar value to the appender syntax duckdb_append_varchar_length append a varchar value to the appender syntax duckdb_append_blob append a blob value to the appender syntax duckdb_append_null append a null value to the appender of any type syntax duckdb_append_data_chunk appends a pre-filled data chunk to the specified appender the types of the data chunk must exactly match the types of the table no casting is performed if the types do not match or the appender is in an invalid state duckdberror is returned if the append is successful duckdbsuccess is returned syntax the appender to append to chunk the data chunk to append returns the return state duckdb_query_arrow executes a sql query within a connection and stores the full materialized result in an arrow structure if the query fails to execute duckdberror is returned and the error message can be retrieved by calling duckdb_query_arrow_error note that after running duckdb_query_arrow duckdb_destroy_arrow must be called on the result object even if the query fails otherwise the error stored within the result will not be freed correctly syntax the connection to perform the query in query the sql query to run out_result the query result returns duckdbsuccess on success or duckdberror on failure duckdb_query_arrow_schema fetch the internal arrow schema from the arrow result syntax the result to fetch the schema from out_schema the output schema returns duckdbsuccess on success or duckdberror on failure duckdb_prepared_arrow_schema fetch the internal arrow schema from the prepared statement syntax the prepared statement to fetch the schema from out_schema the output schema returns duckdbsuccess on success or duckdberror on failure duckdb_query_arrow_array fetch an internal arrow array from the arrow result this function can be called multiple time to get next chunks which will free the previous out_array so consume the out_array before calling this function again syntax the result to fetch the array from out_array the output array returns duckdbsuccess on success or duckdberror on failure duckdb_arrow_column_count returns the number of columns present in a the arrow result object syntax the result object returns the number of columns present in the result object duckdb_arrow_row_count returns the number of rows present in a the arrow result object syntax the result object returns the number of rows present in the result object duckdb_arrow_rows_changed returns the number of rows changed by the query stored in the arrow result this is relevant only for insert update delete queries for other queries the rows_changed will be 0 syntax the result object returns the number of rows changed duckdb_query_arrow_error returns the error message contained within the result the error is only set if duckdb_query_arrow returns duckdberror the error message should not be freed it will be de-allocated when duckdb_destroy_arrow is called syntax the result object to fetch the nullmask from returns the error of the result duckdb_destroy_arrow closes the result and de-allocates all memory allocated for the arrow result syntax the result to destroy duckdb_execute_tasks execute duckdb tasks on this thread will return after max_tasks have been executed or if there are no more tasks present syntax the database object to execute tasks for max_tasks the maximum amount of tasks to execute duckdb_create_task_state creates a task state that can be used with duckdb_execute_tasks_state to execute tasks until duckdb_finish_execution is called on the state duckdb_destroy_state should be called on the result in order to free memory syntax the database object to create the task state for returns the task state that can be used with duckdb_execute_tasks_state duckdb_execute_tasks_state execute duckdb tasks on this thread the thread will keep on executing tasks forever until duckdb_finish_execution is called on the state multiple threads can share the same duckdb_task_state syntax the task state of the executor duckdb_execute_n_tasks_state execute duckdb tasks on this thread the thread will keep on executing tasks until either duckdb_finish_execution is called on the state max_tasks tasks have been executed or there are no more tasks to be executed multiple threads can share the same duckdb_task_state syntax the task state of the executor max_tasks the maximum amount of tasks to execute returns the amount of tasks that have actually been executed duckdb_finish_execution finish execution on a specific task syntax the task state to finish execution duckdb_task_state_is_finished check if the provided duckdb_task_state has finished execution syntax the task state to inspect returns whether or not duckdb_finish_execution has been called on the task state duckdb_destroy_task_state destroys the task state returned from duckdb_create_task_state note that this should not be called while there is an active duckdb_execute_tasks_state running on the task state syntax the task state to clean up duckdb_execution_is_finished returns true if execution of the current query is finished syntax the connection on which to check duckdb_stream_fetch_chunk fetches a data chunk from the streaming duckdb_result this function should be called repeatedly until the result is exhausted the result must be destroyed with duckdb_destroy_data_chunk this function can only be used on duckdb_results created with duckdb_pending_prepared_streaming if this function is used none of the other result functions can be used and vice versa i e this function cannot be mixed with the legacy result functions or the materialized result functions it is not known beforehand how many chunks will be returned by this result syntax the result object to fetch the data chunk from returns the resulting data chunk returns null if the result has an error", + "text": "api reference open connect syntax path to the database file on disk or nullptr or memory to open an in-memory database out_database the result database object returns duckdbsuccess on success or duckdberror on failure duckdb_open_ext extended version of duckdb_open creates a new database or opens an existing database file stored at the given path syntax path to the database file on disk or nullptr or memory to open an in-memory database out_database the result database object config optional configuration used to start up the database system out_error if set and the function returns duckdberror this will contain the reason why the start-up failed note that the error must be freed using duckdb_free returns duckdbsuccess on success or duckdberror on failure duckdb_close closes the specified database and de-allocates all memory allocated for that database this should be called after you are done with any database allocated through duckdb_open note that failing to call duckdb_close in case of e g a program crash will not cause data corruption still it is recommended to always correctly close a database object after you are done with it syntax the database object to shut down duckdb_connect opens a connection to a database connections are required to query the database and store transactional state associated with the connection the instantiated connection should be closed using duckdb_disconnect syntax the database file to connect to out_connection the result connection object returns duckdbsuccess on success or duckdberror on failure duckdb_interrupt interrupt running query syntax the connection to interruot duckdb_query_progress get progress of the running query syntax the working connection returns -1 if no progress or a percentage of the progress duckdb_disconnect closes the specified connection and de-allocates all memory allocated for that connection syntax the connection to close duckdb_library_version returns the version of the linked duckdb with a version postfix for dev versions usually used for developing c extensions that must return this for a compatibility check syntax duckdb_create_config initializes an empty configuration object that can be used to provide start-up options for the duckdb instance through duckdb_open_ext this will always succeed unless there is a malloc failure syntax the result configuration object returns duckdbsuccess on success or duckdberror on failure duckdb_config_count this returns the total amount of configuration options available for usage with duckdb_get_config_flag this should not be called in a loop as it internally loops over all the options syntax the amount of config options available duckdb_get_config_flag obtains a human-readable name and description of a specific configuration option this can be used to e g display configuration options this will succeed unless index is out of range i e duckdb_config_count the result name or description must not be freed syntax the index of the configuration option between 0 and duckdb_config_count out_name a name of the configuration flag out_description a description of the configuration flag returns duckdbsuccess on success or duckdberror on failure duckdb_set_config sets the specified option for the specified configuration the configuration option is indicated by name to obtain a list of config options see duckdb_get_config_flag in the source code configuration options are defined in config cpp this can fail if either the name is invalid or if the value provided for the option is invalid syntax the configuration object to set the option on name the name of the configuration flag to set option the value to set the configuration flag to returns duckdbsuccess on success or duckdberror on failure duckdb_destroy_config destroys the specified configuration option and de-allocates all memory allocated for the object syntax the configuration object to destroy duckdb_query executes a sql query within a connection and stores the full materialized result in the out_result pointer if the query fails to execute duckdberror is returned and the error message can be retrieved by calling duckdb_result_error note that after running duckdb_query duckdb_destroy_result must be called on the result object even if the query fails otherwise the error stored within the result will not be freed correctly syntax the connection to perform the query in query the sql query to run out_result the query result returns duckdbsuccess on success or duckdberror on failure duckdb_destroy_result closes the result and de-allocates all memory allocated for that connection syntax the result to destroy duckdb_column_name returns the column name of the specified column the result should not need be freed the column names will automatically be destroyed when the result is destroyed returns null if the column is out of range syntax the result object to fetch the column name from col the column index returns the column name of the specified column duckdb_column_type returns the column type of the specified column returns duckdb_type_invalid if the column is out of range syntax the result object to fetch the column type from col the column index returns the column type of the specified column duckdb_column_logical_type returns the logical column type of the specified column the return type of this call should be destroyed with duckdb_destroy_logical_type returns null if the column is out of range syntax the result object to fetch the column type from col the column index returns the logical column type of the specified column duckdb_column_count returns the number of columns present in a the result object syntax the result object returns the number of columns present in the result object duckdb_row_count returns the number of rows present in a the result object syntax the result object returns the number of rows present in the result object duckdb_rows_changed returns the number of rows changed by the query stored in the result this is relevant only for insert update delete queries for other queries the rows_changed will be 0 syntax the result object returns the number of rows changed duckdb_column_data deprecated prefer using duckdb_result_get_chunk instead returns the data of a specific column of a result in columnar format the function returns a dense array which contains the result data the exact type stored in the array depends on the corresponding duckdb_type as provided by duckdb_column_type for the exact type by which the data should be accessed see the comments in the types section or the duckdb_type enum for example for a column of type duckdb_type_integer rows can be accessed in the following manner int32_t data int32_t duckdb_column_data result 0 printf data for row d d n row data row syntax the result object to fetch the column data from col the column index returns the column data of the specified column duckdb_nullmask_data deprecated prefer using duckdb_result_get_chunk instead returns the nullmask of a specific column of a result in columnar format the nullmask indicates for every row whether or not the corresponding row is null if a row is null the values present in the array provided by duckdb_column_data are undefined int32_t data int32_t duckdb_column_data result 0 bool nullmask duckdb_nullmask_data result 0 if nullmask row printf data for row d null n row else printf data for row d d n row data row syntax the result object to fetch the nullmask from col the column index returns the nullmask of the specified column duckdb_result_error returns the error message contained within the result the error is only set if duckdb_query returns duckdberror the result of this function must not be freed it will be cleaned up when duckdb_destroy_result is called syntax the result object to fetch the error from returns the error of the result duckdb_result_get_chunk fetches a data chunk from the duckdb_result this function should be called repeatedly until the result is exhausted the result must be destroyed with duckdb_destroy_data_chunk this function supersedes all duckdb_value functions as well as the duckdb_column_data and duckdb_nullmask_data functions it results in significantly better performance and should be preferred in newer code-bases if this function is used none of the other result functions can be used and vice versa i e this function cannot be mixed with the legacy result functions use duckdb_result_chunk_count to figure out how many chunks there are in the result syntax the result object to fetch the data chunk from chunk_index the chunk index to fetch from returns the resulting data chunk returns null if the chunk index is out of bounds duckdb_result_is_streaming checks if the type of the internal result is streamqueryresult syntax the result object to check returns whether or not the result object is of the type streamqueryresult duckdb_result_chunk_count returns the number of data chunks present in the result syntax the result object returns number of data chunks present in the result duckdb_value_boolean syntax the boolean value at the specified location or false if the value cannot be converted duckdb_value_int8 syntax the int8_t value at the specified location or 0 if the value cannot be converted duckdb_value_int16 syntax the int16_t value at the specified location or 0 if the value cannot be converted duckdb_value_int32 syntax the int32_t value at the specified location or 0 if the value cannot be converted duckdb_value_int64 syntax the int64_t value at the specified location or 0 if the value cannot be converted duckdb_value_hugeint syntax the duckdb_hugeint value at the specified location or 0 if the value cannot be converted duckdb_value_decimal syntax the duckdb_decimal value at the specified location or 0 if the value cannot be converted duckdb_value_uint8 syntax the uint8_t value at the specified location or 0 if the value cannot be converted duckdb_value_uint16 syntax the uint16_t value at the specified location or 0 if the value cannot be converted duckdb_value_uint32 syntax the uint32_t value at the specified location or 0 if the value cannot be converted duckdb_value_uint64 syntax the uint64_t value at the specified location or 0 if the value cannot be converted duckdb_value_float syntax the float value at the specified location or 0 if the value cannot be converted duckdb_value_double syntax the double value at the specified location or 0 if the value cannot be converted duckdb_value_date syntax the duckdb_date value at the specified location or 0 if the value cannot be converted duckdb_value_time syntax the duckdb_time value at the specified location or 0 if the value cannot be converted duckdb_value_timestamp syntax the duckdb_timestamp value at the specified location or 0 if the value cannot be converted duckdb_value_interval syntax the duckdb_interval value at the specified location or 0 if the value cannot be converted duckdb_value_varchar syntax use duckdb_value_string instead this function does not work correctly if the string contains null bytes returns the text value at the specified location as a null-terminated string or nullptr if the value cannot be converted the result must be freed with duckdb_free duckdb_value_varchar_internal syntax use duckdb_value_string_internal instead this function does not work correctly if the string contains null bytes returns the char value at the specified location only works on varchar columns and does not auto-cast if the column is not a varchar column this function will return null the result must not be freed duckdb_value_string_internal syntax use duckdb_value_string_internal instead this function does not work correctly if the string contains null bytes returns the char value at the specified location only works on varchar columns and does not auto-cast if the column is not a varchar column this function will return null the result must not be freed duckdb_value_blob syntax the duckdb_blob value at the specified location returns a blob with blob data set to nullptr if the value cannot be converted the resulting blob data must be freed with duckdb_free duckdb_value_is_null syntax returns true if the value at the specified index is null and false otherwise duckdb_malloc allocate size bytes of memory using the duckdb internal malloc function any memory allocated in this manner should be freed using duckdb_free syntax the number of bytes to allocate returns a pointer to the allocated memory region duckdb_free free a value returned from duckdb_malloc duckdb_value_varchar or duckdb_value_blob syntax the memory region to de-allocate duckdb_vector_size the internal vector size used by duckdb this is the amount of tuples that will fit into a data chunk created by duckdb_create_data_chunk syntax the vector size duckdb_string_is_inlined whether or not the duckdb_string_t value is inlined this means that the data of the string does not have a separate allocation syntax duckdb_from_date decompose a duckdb_date object into year month and date stored as duckdb_date_struct syntax the date object as obtained from a duckdb_type_date column returns the duckdb_date_struct with the decomposed elements duckdb_to_date re-compose a duckdb_date from year month and date duckdb_date_struct syntax the year month and date stored in a duckdb_date_struct returns the duckdb_date element duckdb_from_time decompose a duckdb_time object into hour minute second and microsecond stored as duckdb_time_struct syntax the time object as obtained from a duckdb_type_time column returns the duckdb_time_struct with the decomposed elements duckdb_to_time re-compose a duckdb_time from hour minute second and microsecond duckdb_time_struct syntax the hour minute second and microsecond in a duckdb_time_struct returns the duckdb_time element duckdb_from_timestamp decompose a duckdb_timestamp object into a duckdb_timestamp_struct syntax the ts object as obtained from a duckdb_type_timestamp column returns the duckdb_timestamp_struct with the decomposed elements duckdb_to_timestamp re-compose a duckdb_timestamp from a duckdb_timestamp_struct syntax the de-composed elements in a duckdb_timestamp_struct returns the duckdb_timestamp element duckdb_hugeint_to_double converts a duckdb_hugeint object as obtained from a duckdb_type_hugeint column into a double syntax the hugeint value returns the converted double element duckdb_double_to_hugeint converts a double value to a duckdb_hugeint object if the conversion fails because the double value is too big the result will be 0 syntax the double value returns the converted duckdb_hugeint element duckdb_double_to_decimal converts a double value to a duckdb_decimal object if the conversion fails because the double value is too big or the width scale are invalid the result will be 0 syntax the double value returns the converted duckdb_decimal element duckdb_decimal_to_double converts a duckdb_decimal object as obtained from a duckdb_type_decimal column into a double syntax the decimal value returns the converted double element duckdb_prepare create a prepared statement object from a query note that after calling duckdb_prepare the prepared statement should always be destroyed using duckdb_destroy_prepare even if the prepare fails if the prepare fails duckdb_prepare_error can be called to obtain the reason why the prepare failed syntax the connection object query the sql query to prepare out_prepared_statement the resulting prepared statement object returns duckdbsuccess on success or duckdberror on failure duckdb_destroy_prepare closes the prepared statement and de-allocates all memory allocated for the statement syntax the prepared statement to destroy duckdb_prepare_error returns the error message associated with the given prepared statement if the prepared statement has no error message this returns nullptr instead the error message should not be freed it will be de-allocated when duckdb_destroy_prepare is called syntax the prepared statement to obtain the error from returns the error message or nullptr if there is none duckdb_nparams returns the number of parameters that can be provided to the given prepared statement returns 0 if the query was not successfully prepared syntax the prepared statement to obtain the number of parameters for duckdb_param_type returns the parameter type for the parameter at the given index returns duckdb_type_invalid if the parameter index is out of range or the statement was not successfully prepared syntax the prepared statement param_idx the parameter index returns the parameter type duckdb_clear_bindings clear the params bind to the prepared statement syntax duckdb_bind_value binds a value to the prepared statement at the specified index syntax duckdb_bind_parameter_index retrieve the index of the parameter for the prepared statement identified by name syntax duckdb_bind_boolean binds a bool value to the prepared statement at the specified index syntax duckdb_bind_int8 binds an int8_t value to the prepared statement at the specified index syntax duckdb_bind_int16 binds an int16_t value to the prepared statement at the specified index syntax duckdb_bind_int32 binds an int32_t value to the prepared statement at the specified index syntax duckdb_bind_int64 binds an int64_t value to the prepared statement at the specified index syntax duckdb_bind_hugeint binds a duckdb_hugeint value to the prepared statement at the specified index syntax duckdb_bind_decimal binds a duckdb_decimal value to the prepared statement at the specified index syntax duckdb_bind_uint8 binds an uint8_t value to the prepared statement at the specified index syntax duckdb_bind_uint16 binds an uint16_t value to the prepared statement at the specified index syntax duckdb_bind_uint32 binds an uint32_t value to the prepared statement at the specified index syntax duckdb_bind_uint64 binds an uint64_t value to the prepared statement at the specified index syntax duckdb_bind_float binds a float value to the prepared statement at the specified index syntax duckdb_bind_double binds a double value to the prepared statement at the specified index syntax duckdb_bind_date binds a duckdb_date value to the prepared statement at the specified index syntax duckdb_bind_time binds a duckdb_time value to the prepared statement at the specified index syntax duckdb_bind_timestamp binds a duckdb_timestamp value to the prepared statement at the specified index syntax duckdb_bind_interval binds a duckdb_interval value to the prepared statement at the specified index syntax duckdb_bind_varchar binds a null-terminated varchar value to the prepared statement at the specified index syntax duckdb_bind_varchar_length binds a varchar value to the prepared statement at the specified index syntax duckdb_bind_blob binds a blob value to the prepared statement at the specified index syntax duckdb_bind_null binds a null value to the prepared statement at the specified index syntax duckdb_execute_prepared executes the prepared statement with the given bound parameters and returns a materialized query result this method can be called multiple times for each prepared statement and the parameters can be modified between calls to this function syntax the prepared statement to execute out_result the query result returns duckdbsuccess on success or duckdberror on failure duckdb_execute_prepared_arrow executes the prepared statement with the given bound parameters and returns an arrow query result syntax the prepared statement to execute out_result the query result returns duckdbsuccess on success or duckdberror on failure duckdb_arrow_scan scans the arrow stream and creates a view with the given name syntax the connection on which to execute the scan table_name name of the temporary view to create arrow arrow stream wrapper returns duckdbsuccess on success or duckdberror on failure duckdb_arrow_array_scan scans the arrow array and creates a view with the given name syntax the connection on which to execute the scan table_name name of the temporary view to create arrow_schema arrow schema wrapper arrow_array arrow array wrapper out_stream output array stream that wraps around the passed schema for releasing deleting once done returns duckdbsuccess on success or duckdberror on failure duckdb_extract_statements extract all statements from a query note that after calling duckdb_extract_statements the extracted statements should always be destroyed using duckdb_destroy_extracted even if no statements were extracted if the extract fails duckdb_extract_statements_error can be called to obtain the reason why the extract failed syntax the connection object query the sql query to extract out_extracted_statements the resulting extracted statements object returns the number of extracted statements or 0 on failure duckdb_prepare_extracted_statement prepare an extracted statement note that after calling duckdb_prepare_extracted_statement the prepared statement should always be destroyed using duckdb_destroy_prepare even if the prepare fails if the prepare fails duckdb_prepare_error can be called to obtain the reason why the prepare failed syntax the connection object extracted_statements the extracted statements object index the index of the extracted statement to prepare out_prepared_statement the resulting prepared statement object returns duckdbsuccess on success or duckdberror on failure duckdb_extract_statements_error returns the error message contained within the extracted statements the result of this function must not be freed it will be cleaned up when duckdb_destroy_extracted is called syntax the extracted statements to fetch the error from returns the error of the extracted statements duckdb_destroy_extracted de-allocates all memory allocated for the extracted statements syntax the extracted statements to destroy duckdb_pending_prepared executes the prepared statement with the given bound parameters and returns a pending result the pending result represents an intermediate structure for a query that is not yet fully executed the pending result can be used to incrementally execute a query returning control to the client between tasks note that after calling duckdb_pending_prepared the pending result should always be destroyed using duckdb_destroy_pending even if this function returns duckdberror syntax the prepared statement to execute out_result the pending query result returns duckdbsuccess on success or duckdberror on failure duckdb_pending_prepared_streaming executes the prepared statement with the given bound parameters and returns a pending result this pending result will create a streaming duckdb_result when executed the pending result represents an intermediate structure for a query that is not yet fully executed note that after calling duckdb_pending_prepared_streaming the pending result should always be destroyed using duckdb_destroy_pending even if this function returns duckdberror syntax the prepared statement to execute out_result the pending query result returns duckdbsuccess on success or duckdberror on failure duckdb_destroy_pending closes the pending result and de-allocates all memory allocated for the result syntax the pending result to destroy duckdb_pending_error returns the error message contained within the pending result the result of this function must not be freed it will be cleaned up when duckdb_destroy_pending is called syntax the pending result to fetch the error from returns the error of the pending result duckdb_pending_execute_task executes a single task within the query returning whether or not the query is ready if this returns duckdb_pending_result_ready the duckdb_execute_pending function can be called to obtain the result if this returns duckdb_pending_result_not_ready the duckdb_pending_execute_task function should be called again if this returns duckdb_pending_error an error occurred during execution the error message can be obtained by calling duckdb_pending_error on the pending_result syntax the pending result to execute a task within returns the state of the pending result after the execution duckdb_execute_pending fully execute a pending query result returning the final query result if duckdb_pending_execute_task has been called until duckdb_pending_result_ready was returned this will return fast otherwise all remaining tasks must be executed first syntax the pending result to execute out_result the result object returns duckdbsuccess on success or duckdberror on failure duckdb_pending_execution_is_finished returns whether a duckdb_pending_state is finished executing for example if pending_state is duckdb_pending_result_ready this function will return true syntax the pending state on which to decide whether to finish execution returns boolean indicating pending execution should be considered finished duckdb_destroy_value destroys the value and de-allocates all memory allocated for that type syntax the value to destroy duckdb_create_varchar creates a value from a null-terminated string syntax the null-terminated string returns the value this must be destroyed with duckdb_destroy_value duckdb_create_varchar_length creates a value from a string syntax the text length the length of the text returns the value this must be destroyed with duckdb_destroy_value duckdb_create_int64 creates a value from an int64 syntax the bigint value returns the value this must be destroyed with duckdb_destroy_value duckdb_get_varchar obtains a string representation of the given value the result must be destroyed with duckdb_free syntax the value returns the string value this must be destroyed with duckdb_free duckdb_get_int64 obtains an int64 of the given value syntax the value returns the int64 value or 0 if no conversion is possible duckdb_create_logical_type creates a duckdb_logical_type from a standard primitive type the resulting type should be destroyed with duckdb_destroy_logical_type this should not be used with duckdb_type_decimal syntax the primitive type to create returns the logical type duckdb_create_list_type creates a list type from its child type the resulting type should be destroyed with duckdb_destroy_logical_type syntax the child type of list type to create returns the logical type duckdb_create_map_type creates a map type from its key type and value type the resulting type should be destroyed with duckdb_destroy_logical_type syntax the key type and value type of map type to create returns the logical type duckdb_create_union_type creates a union type from the passed types array the resulting type should be destroyed with duckdb_destroy_logical_type syntax the array of types that the union should consist of type_amount the size of the types array returns the logical type duckdb_create_struct_type creates a struct type from the passed member name and type arrays the resulting type should be destroyed with duckdb_destroy_logical_type syntax the array of types that the struct should consist of member_names the array of names that the struct should consist of member_count the number of members that were specified for both arrays returns the logical type duckdb_create_decimal_type creates a duckdb_logical_type of type decimal with the specified width and scale the resulting type should be destroyed with duckdb_destroy_logical_type syntax the width of the decimal type scale the scale of the decimal type returns the logical type duckdb_get_type_id retrieves the type class of a duckdb_logical_type syntax the logical type object returns the type id duckdb_decimal_width retrieves the width of a decimal type syntax the logical type object returns the width of the decimal type duckdb_decimal_scale retrieves the scale of a decimal type syntax the logical type object returns the scale of the decimal type duckdb_decimal_internal_type retrieves the internal storage type of a decimal type syntax the logical type object returns the internal type of the decimal type duckdb_enum_internal_type retrieves the internal storage type of an enum type syntax the logical type object returns the internal type of the enum type duckdb_enum_dictionary_size retrieves the dictionary size of the enum type syntax the logical type object returns the dictionary size of the enum type duckdb_enum_dictionary_value retrieves the dictionary value at the specified position from the enum the result must be freed with duckdb_free syntax the logical type object index the index in the dictionary returns the string value of the enum type must be freed with duckdb_free duckdb_list_type_child_type retrieves the child type of the given list type the result must be freed with duckdb_destroy_logical_type syntax the logical type object returns the child type of the list type must be destroyed with duckdb_destroy_logical_type duckdb_map_type_key_type retrieves the key type of the given map type the result must be freed with duckdb_destroy_logical_type syntax the logical type object returns the key type of the map type must be destroyed with duckdb_destroy_logical_type duckdb_map_type_value_type retrieves the value type of the given map type the result must be freed with duckdb_destroy_logical_type syntax the logical type object returns the value type of the map type must be destroyed with duckdb_destroy_logical_type duckdb_struct_type_child_count returns the number of children of a struct type syntax the logical type object returns the number of children of a struct type duckdb_struct_type_child_name retrieves the name of the struct child the result must be freed with duckdb_free syntax the logical type object index the child index returns the name of the struct type must be freed with duckdb_free duckdb_struct_type_child_type retrieves the child type of the given struct type at the specified index the result must be freed with duckdb_destroy_logical_type syntax the logical type object index the child index returns the child type of the struct type must be destroyed with duckdb_destroy_logical_type duckdb_union_type_member_count returns the number of members that the union type has syntax the logical type union object returns the number of members of a union type duckdb_union_type_member_name retrieves the name of the union member the result must be freed with duckdb_free syntax the logical type object index the child index returns the name of the union member must be freed with duckdb_free duckdb_union_type_member_type retrieves the child type of the given union member at the specified index the result must be freed with duckdb_destroy_logical_type syntax the logical type object index the child index returns the child type of the union member must be destroyed with duckdb_destroy_logical_type duckdb_destroy_logical_type destroys the logical type and de-allocates all memory allocated for that type syntax the logical type to destroy duckdb_create_data_chunk creates an empty datachunk with the specified set of types syntax an array of types of the data chunk column_count the number of columns returns the data chunk duckdb_destroy_data_chunk destroys the data chunk and de-allocates all memory allocated for that chunk syntax the data chunk to destroy duckdb_data_chunk_reset resets a data chunk clearing the validity masks and setting the cardinality of the data chunk to 0 syntax the data chunk to reset duckdb_data_chunk_get_column_count retrieves the number of columns in a data chunk syntax the data chunk to get the data from returns the number of columns in the data chunk duckdb_data_chunk_get_vector retrieves the vector at the specified column index in the data chunk the pointer to the vector is valid for as long as the chunk is alive it does not need to be destroyed syntax the data chunk to get the data from returns the vector duckdb_data_chunk_get_size retrieves the current number of tuples in a data chunk syntax the data chunk to get the data from returns the number of tuples in the data chunk duckdb_data_chunk_set_size sets the current number of tuples in a data chunk syntax the data chunk to set the size in size the number of tuples in the data chunk duckdb_vector_get_column_type retrieves the column type of the specified vector the result must be destroyed with duckdb_destroy_logical_type syntax the vector get the data from returns the type of the vector duckdb_vector_get_data retrieves the data pointer of the vector the data pointer can be used to read or write values from the vector how to read or write values depends on the type of the vector syntax the vector to get the data from returns the data pointer duckdb_vector_get_validity retrieves the validity mask pointer of the specified vector if all values are valid this function might return null the validity mask is a bitset that signifies null-ness within the data chunk it is a series of uint64_t values where each uint64_t value contains validity for 64 tuples the bit is set to 1 if the value is valid i e not null or 0 if the value is invalid i e null validity of a specific value can be obtained like this idx_t entry_idx row_idx 64 idx_t idx_in_entry row_idx 64 bool is_valid validity_mask entry_idx 1 idx_in_entry alternatively the slower duckdb_validity_row_is_valid function can be used syntax the vector to get the data from returns the pointer to the validity mask or null if no validity mask is present duckdb_vector_ensure_validity_writable ensures the validity mask is writable by allocating it after this function is called duckdb_vector_get_validity will always return non-null this allows null values to be written to the vector regardless of whether a validity mask was present before syntax the vector to alter duckdb_vector_assign_string_element assigns a string element in the vector at the specified location syntax the vector to alter index the row position in the vector to assign the string to str the null-terminated string duckdb_vector_assign_string_element_len assigns a string element in the vector at the specified location syntax the vector to alter index the row position in the vector to assign the string to str the string str_len the length of the string in bytes duckdb_list_vector_get_child retrieves the child vector of a list vector the resulting vector is valid as long as the parent vector is valid syntax the vector returns the child vector duckdb_list_vector_get_size returns the size of the child vector of the list syntax the vector returns the size of the child list duckdb_list_vector_set_size sets the total size of the underlying child-vector of a list vector syntax the list vector size the size of the child list returns the duckdb state returns duckdberror if the vector is nullptr duckdb_list_vector_reserve sets the total capacity of the underlying child-vector of a list syntax the list vector required_capacity the total capacity to reserve return the duckdb state returns duckdberror if the vector is nullptr duckdb_struct_vector_get_child retrieves the child vector of a struct vector the resulting vector is valid as long as the parent vector is valid syntax the vector index the child index returns the child vector duckdb_validity_row_is_valid returns whether or not a row is valid i e not null in the given validity mask syntax the validity mask as obtained through duckdb_vector_get_validity row the row index returns true if the row is valid false otherwise duckdb_validity_set_row_validity in a validity mask sets a specific row to either valid or invalid note that duckdb_vector_ensure_validity_writable should be called before calling duckdb_vector_get_validity to ensure that there is a validity mask to write to syntax the validity mask as obtained through duckdb_vector_get_validity row the row index valid whether or not to set the row to valid or invalid duckdb_validity_set_row_invalid in a validity mask sets a specific row to invalid equivalent to duckdb_validity_set_row_validity with valid set to false syntax the validity mask row the row index duckdb_validity_set_row_valid in a validity mask sets a specific row to valid equivalent to duckdb_validity_set_row_validity with valid set to true syntax the validity mask row the row index duckdb_create_table_function creates a new empty table function the return value should be destroyed with duckdb_destroy_table_function syntax the table function object duckdb_destroy_table_function destroys the given table function object syntax the table function to destroy duckdb_table_function_set_name sets the name of the given table function syntax the table function name the name of the table function duckdb_table_function_add_parameter adds a parameter to the table function syntax 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 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 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 the table function bind the bind function duckdb_table_function_set_init sets the init function of the table function syntax the table function init the init function duckdb_table_function_set_local_init sets the thread-local init function of the table function syntax the table function init the init function duckdb_table_function_set_function sets the main function of the table function syntax 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 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 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 the info object returns the extra info duckdb_bind_add_result_column adds a result column to the output of the table function syntax 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 the info object returns the init data object duckdb_function_set_error report that an error has occurred while executing the function syntax the info object error the error message duckdb_add_replacement_scan add a replacement scan definition to the specified database syntax the database object to add the replacement scan to replacement the replacement scan callback extra_data extra data that is passed back into the specified callback delete_callback the delete callback to call on the extra data if any duckdb_replacement_scan_set_function_name sets the replacement function name to use if this function is called in the replacement callback the replacement scan is performed if it is not called the replacement callback is not performed syntax the info object function_name the function name to substitute duckdb_replacement_scan_add_parameter adds a parameter to the replacement scan function syntax the info object parameter the parameter to add duckdb_replacement_scan_set_error report that an error has occurred while executing the replacement scan syntax the info object error the error message duckdb_appender_create creates an appender object syntax the connection context to create the appender in schema the schema of the table to append to or nullptr for the default schema table the table name to append to out_appender the resulting appender object returns duckdbsuccess on success or duckdberror on failure duckdb_appender_error returns the error message associated with the given appender if the appender has no error message this returns nullptr instead the error message should not be freed it will be de-allocated when duckdb_appender_destroy is called syntax the appender to get the error from returns the error message or nullptr if there is none duckdb_appender_flush flush the appender to the table forcing the cache of the appender to be cleared and the data to be appended to the base table this should generally not be used unless you know what you are doing instead call duckdb_appender_destroy when you are done with the appender syntax the appender to flush returns duckdbsuccess on success or duckdberror on failure duckdb_appender_close close the appender flushing all intermediate state in the appender to the table and closing it for further appends this is generally not necessary call duckdb_appender_destroy instead syntax the appender to flush and close returns duckdbsuccess on success or duckdberror on failure duckdb_appender_destroy close the appender and destroy it flushing all intermediate state in the appender to the table and de-allocating all memory associated with the appender syntax the appender to flush close and destroy returns duckdbsuccess on success or duckdberror on failure duckdb_appender_begin_row a nop function provided for backwards compatibility reasons does nothing only duckdb_appender_end_row is required syntax duckdb_appender_end_row finish the current row of appends after end_row is called the next row can be appended syntax the appender returns duckdbsuccess on success or duckdberror on failure duckdb_append_bool append a bool value to the appender syntax duckdb_append_int8 append an int8_t value to the appender syntax duckdb_append_int16 append an int16_t value to the appender syntax duckdb_append_int32 append an int32_t value to the appender syntax duckdb_append_int64 append an int64_t value to the appender syntax duckdb_append_hugeint append a duckdb_hugeint value to the appender syntax duckdb_append_uint8 append a uint8_t value to the appender syntax duckdb_append_uint16 append a uint16_t value to the appender syntax duckdb_append_uint32 append a uint32_t value to the appender syntax duckdb_append_uint64 append a uint64_t value to the appender syntax duckdb_append_float append a float value to the appender syntax duckdb_append_double append a double value to the appender syntax duckdb_append_date append a duckdb_date value to the appender syntax duckdb_append_time append a duckdb_time value to the appender syntax duckdb_append_timestamp append a duckdb_timestamp value to the appender syntax duckdb_append_interval append a duckdb_interval value to the appender syntax duckdb_append_varchar append a varchar value to the appender syntax duckdb_append_varchar_length append a varchar value to the appender syntax duckdb_append_blob append a blob value to the appender syntax duckdb_append_null append a null value to the appender of any type syntax duckdb_append_data_chunk appends a pre-filled data chunk to the specified appender the types of the data chunk must exactly match the types of the table no casting is performed if the types do not match or the appender is in an invalid state duckdberror is returned if the append is successful duckdbsuccess is returned syntax the appender to append to chunk the data chunk to append returns the return state duckdb_query_arrow executes a sql query within a connection and stores the full materialized result in an arrow structure if the query fails to execute duckdberror is returned and the error message can be retrieved by calling duckdb_query_arrow_error note that after running duckdb_query_arrow duckdb_destroy_arrow must be called on the result object even if the query fails otherwise the error stored within the result will not be freed correctly syntax the connection to perform the query in query the sql query to run out_result the query result returns duckdbsuccess on success or duckdberror on failure duckdb_query_arrow_schema fetch the internal arrow schema from the arrow result syntax the result to fetch the schema from out_schema the output schema returns duckdbsuccess on success or duckdberror on failure duckdb_prepared_arrow_schema fetch the internal arrow schema from the prepared statement syntax the prepared statement to fetch the schema from out_schema the output schema returns duckdbsuccess on success or duckdberror on failure duckdb_query_arrow_array fetch an internal arrow array from the arrow result this function can be called multiple time to get next chunks which will free the previous out_array so consume the out_array before calling this function again syntax the result to fetch the array from out_array the output array returns duckdbsuccess on success or duckdberror on failure duckdb_arrow_column_count returns the number of columns present in a the arrow result object syntax the result object returns the number of columns present in the result object duckdb_arrow_row_count returns the number of rows present in a the arrow result object syntax the result object returns the number of rows present in the result object duckdb_arrow_rows_changed returns the number of rows changed by the query stored in the arrow result this is relevant only for insert update delete queries for other queries the rows_changed will be 0 syntax the result object returns the number of rows changed duckdb_query_arrow_error returns the error message contained within the result the error is only set if duckdb_query_arrow returns duckdberror the error message should not be freed it will be de-allocated when duckdb_destroy_arrow is called syntax the result object to fetch the nullmask from returns the error of the result duckdb_destroy_arrow closes the result and de-allocates all memory allocated for the arrow result syntax the result to destroy duckdb_execute_tasks execute duckdb tasks on this thread will return after max_tasks have been executed or if there are no more tasks present syntax the database object to execute tasks for max_tasks the maximum amount of tasks to execute duckdb_create_task_state creates a task state that can be used with duckdb_execute_tasks_state to execute tasks until duckdb_finish_execution is called on the state duckdb_destroy_state should be called on the result in order to free memory syntax the database object to create the task state for returns the task state that can be used with duckdb_execute_tasks_state duckdb_execute_tasks_state execute duckdb tasks on this thread the thread will keep on executing tasks forever until duckdb_finish_execution is called on the state multiple threads can share the same duckdb_task_state syntax the task state of the executor duckdb_execute_n_tasks_state execute duckdb tasks on this thread the thread will keep on executing tasks until either duckdb_finish_execution is called on the state max_tasks tasks have been executed or there are no more tasks to be executed multiple threads can share the same duckdb_task_state syntax the task state of the executor max_tasks the maximum amount of tasks to execute returns the amount of tasks that have actually been executed duckdb_finish_execution finish execution on a specific task syntax the task state to finish execution duckdb_task_state_is_finished check if the provided duckdb_task_state has finished execution syntax the task state to inspect returns whether or not duckdb_finish_execution has been called on the task state duckdb_destroy_task_state destroys the task state returned from duckdb_create_task_state note that this should not be called while there is an active duckdb_execute_tasks_state running on the task state syntax the task state to clean up duckdb_execution_is_finished returns true if execution of the current query is finished syntax the connection on which to check duckdb_stream_fetch_chunk fetches a data chunk from the streaming duckdb_result this function should be called repeatedly until the result is exhausted the result must be destroyed with duckdb_destroy_data_chunk this function can only be used on duckdb_results created with duckdb_pending_prepared_streaming if this function is used none of the other result functions can be used and vice versa i e this function cannot be mixed with the legacy result functions or the materialized result functions it is not known beforehand how many chunks will be returned by this result syntax the result object to fetch the data chunk from returns the resulting data chunk returns null if the result has an error", "category": "C", "url": "/docs/api/c/api", "blurb": "API Reference Open/Connect Syntax Path to the database file on disk, or nullptr or :memory: to open an in-memory..." @@ -191,7 +191,7 @@ }, { "title": "C API - Prepared Statements", - "text": "a prepared statement is a parameterized query the query is prepared with question marks or dollar symbols 1 indicating the parameters of the query values can then be bound to these parameters after which the prepared statement can be executed using those parameters a single query can be prepared once and executed many times prepared statements are useful to easily supply parameters to functions while avoiding string concatenation sql injection attacks speeding up queries that will be executed many times with different parameters duckdb supports prepared statements in the c api with the duckdb_prepare method the duckdb_bind family of functions is used to supply values for subsequent execution of the prepared statement using duckdb_execute_prepared after we are done with the prepared statement it can be cleaned up using the duckdb_destroy_prepare method example duckdb_prepared_statement stmt duckdb_result result if duckdb_prepare con insert into integers values 1 2 stmt duckdberror handle error duckdb_bind_int32 stmt 1 42 the parameter index starts counting at 1 duckdb_bind_int32 stmt 2 43 null as second parameter means no result set is requested duckdb_execute_prepared stmt null duckdb_destroy_prepare stmt we can also query result sets using prepared statements if duckdb_prepare con select from integers where i stmt duckdberror handle error duckdb_bind_int32 stmt 1 42 duckdb_execute_prepared stmt result do something with result clean up duckdb_destroy_result result duckdb_destroy_prepare stmt after calling duckdb_prepare the prepared statement parameters can be inspected using duckdb_nparams and duckdb_param_type in case the prepare fails the error can be obtained through duckdb_prepare_error it is not required that the duckdb_bind family of functions matches the prepared statement parameter type exactly the values will be auto-cast to the required value as required for example calling duckdb_bind_int8 on a parameter type of duckdb_type_integer will work as expected do not use prepared statements to insert large amounts of data into duckdb instead it is recommended to use the appender api reference note that after calling duckdb_prepare the prepared statement should always be destroyed using duckdb_destroy_prepare even if the prepare fails if the prepare fails duckdb_prepare_error can be called to obtain the reason why the prepare failed syntax the connection object query the sql query to prepare out_prepared_statement the resulting prepared statement object returns duckdbsuccess on success or duckdberror on failure duckdb_destroy_prepare closes the prepared statement and de-allocates all memory allocated for the statement syntax the prepared statement to destroy duckdb_prepare_error returns the error message associated with the given prepared statement if the prepared statement has no error message this returns nullptr instead the error message should not be freed it will be de-allocated when duckdb_destroy_prepare is called syntax the prepared statement to obtain the error from returns the error message or nullptr if there is none duckdb_nparams returns the number of parameters that can be provided to the given prepared statement returns 0 if the query was not successfully prepared syntax the prepared statement to obtain the number of parameters for duckdb_param_type returns the parameter type for the parameter at the given index returns duckdb_type_invalid if the parameter index is out of range or the statement was not successfully prepared syntax the prepared statement param_idx the parameter index returns the parameter type duckdb_clear_bindings clear the params bind to the prepared statement syntax duckdb_bind_value binds a value to the prepared statement at the specified index syntax duckdb_bind_parameter_index retrieve the index of the parameter for the prepared statement identified by name syntax duckdb_bind_boolean binds a bool value to the prepared statement at the specified index syntax duckdb_bind_int8 binds an int8_t value to the prepared statement at the specified index syntax duckdb_bind_int16 binds an int16_t value to the prepared statement at the specified index syntax duckdb_bind_int32 binds an int32_t value to the prepared statement at the specified index syntax duckdb_bind_int64 binds an int64_t value to the prepared statement at the specified index syntax duckdb_bind_hugeint binds an duckdb_hugeint value to the prepared statement at the specified index syntax duckdb_bind_decimal binds a duckdb_decimal value to the prepared statement at the specified index syntax duckdb_bind_uint8 binds an uint8_t value to the prepared statement at the specified index syntax duckdb_bind_uint16 binds an uint16_t value to the prepared statement at the specified index syntax duckdb_bind_uint32 binds an uint32_t value to the prepared statement at the specified index syntax duckdb_bind_uint64 binds an uint64_t value to the prepared statement at the specified index syntax duckdb_bind_float binds an float value to the prepared statement at the specified index syntax duckdb_bind_double binds an double value to the prepared statement at the specified index syntax duckdb_bind_date binds a duckdb_date value to the prepared statement at the specified index syntax duckdb_bind_time binds a duckdb_time value to the prepared statement at the specified index syntax duckdb_bind_timestamp binds a duckdb_timestamp value to the prepared statement at the specified index syntax duckdb_bind_interval binds a duckdb_interval value to the prepared statement at the specified index syntax duckdb_bind_varchar binds a null-terminated varchar value to the prepared statement at the specified index syntax duckdb_bind_varchar_length binds a varchar value to the prepared statement at the specified index syntax duckdb_bind_blob binds a blob value to the prepared statement at the specified index syntax duckdb_bind_null binds a null value to the prepared statement at the specified index syntax duckdb_execute_prepared executes the prepared statement with the given bound parameters and returns a materialized query result this method can be called multiple times for each prepared statement and the parameters can be modified between calls to this function syntax the prepared statement to execute out_result the query result returns duckdbsuccess on success or duckdberror on failure duckdb_execute_prepared_arrow executes the prepared statement with the given bound parameters and returns an arrow query result syntax the prepared statement to execute out_result the query result returns duckdbsuccess on success or duckdberror on failure duckdb_arrow_scan scans the arrow stream and creates a view with the given name syntax the connection on which to execute the scan table_name name of the temporary view to create arrow arrow stream wrapper returns duckdbsuccess on success or duckdberror on failure duckdb_arrow_array_scan scans the arrow array and creates a view with the given name syntax the connection on which to execute the scan table_name name of the temporary view to create arrow_schema arrow schema wrapper arrow_array arrow array wrapper out_stream output array stream that wraps around the passed schema for releasing deleting once done returns duckdbsuccess on success or duckdberror on failure", + "text": "a prepared statement is a parameterized query the query is prepared with question marks or dollar symbols 1 indicating the parameters of the query values can then be bound to these parameters after which the prepared statement can be executed using those parameters a single query can be prepared once and executed many times prepared statements are useful to easily supply parameters to functions while avoiding string concatenation sql injection attacks speeding up queries that will be executed many times with different parameters duckdb supports prepared statements in the c api with the duckdb_prepare method the duckdb_bind family of functions is used to supply values for subsequent execution of the prepared statement using duckdb_execute_prepared after we are done with the prepared statement it can be cleaned up using the duckdb_destroy_prepare method example duckdb_prepared_statement stmt duckdb_result result if duckdb_prepare con insert into integers values 1 2 stmt duckdberror handle error duckdb_bind_int32 stmt 1 42 the parameter index starts counting at 1 duckdb_bind_int32 stmt 2 43 null as second parameter means no result set is requested duckdb_execute_prepared stmt null duckdb_destroy_prepare stmt we can also query result sets using prepared statements if duckdb_prepare con select from integers where i stmt duckdberror handle error duckdb_bind_int32 stmt 1 42 duckdb_execute_prepared stmt result do something with result clean up duckdb_destroy_result result duckdb_destroy_prepare stmt after calling duckdb_prepare the prepared statement parameters can be inspected using duckdb_nparams and duckdb_param_type in case the prepare fails the error can be obtained through duckdb_prepare_error it is not required that the duckdb_bind family of functions matches the prepared statement parameter type exactly the values will be auto-cast to the required value as required for example calling duckdb_bind_int8 on a parameter type of duckdb_type_integer will work as expected do not use prepared statements to insert large amounts of data into duckdb instead it is recommended to use the appender api reference note that after calling duckdb_prepare the prepared statement should always be destroyed using duckdb_destroy_prepare even if the prepare fails if the prepare fails duckdb_prepare_error can be called to obtain the reason why the prepare failed syntax the connection object query the sql query to prepare out_prepared_statement the resulting prepared statement object returns duckdbsuccess on success or duckdberror on failure duckdb_destroy_prepare closes the prepared statement and de-allocates all memory allocated for the statement syntax the prepared statement to destroy duckdb_prepare_error returns the error message associated with the given prepared statement if the prepared statement has no error message this returns nullptr instead the error message should not be freed it will be de-allocated when duckdb_destroy_prepare is called syntax the prepared statement to obtain the error from returns the error message or nullptr if there is none duckdb_nparams returns the number of parameters that can be provided to the given prepared statement returns 0 if the query was not successfully prepared syntax the prepared statement to obtain the number of parameters for duckdb_param_type returns the parameter type for the parameter at the given index returns duckdb_type_invalid if the parameter index is out of range or the statement was not successfully prepared syntax the prepared statement param_idx the parameter index returns the parameter type duckdb_clear_bindings clear the params bind to the prepared statement syntax duckdb_bind_value binds a value to the prepared statement at the specified index syntax duckdb_bind_parameter_index retrieve the index of the parameter for the prepared statement identified by name syntax duckdb_bind_boolean binds a bool value to the prepared statement at the specified index syntax duckdb_bind_int8 binds an int8_t value to the prepared statement at the specified index syntax duckdb_bind_int16 binds an int16_t value to the prepared statement at the specified index syntax duckdb_bind_int32 binds an int32_t value to the prepared statement at the specified index syntax duckdb_bind_int64 binds an int64_t value to the prepared statement at the specified index syntax duckdb_bind_hugeint binds a duckdb_hugeint value to the prepared statement at the specified index syntax duckdb_bind_decimal binds a duckdb_decimal value to the prepared statement at the specified index syntax duckdb_bind_uint8 binds an uint8_t value to the prepared statement at the specified index syntax duckdb_bind_uint16 binds an uint16_t value to the prepared statement at the specified index syntax duckdb_bind_uint32 binds an uint32_t value to the prepared statement at the specified index syntax duckdb_bind_uint64 binds an uint64_t value to the prepared statement at the specified index syntax duckdb_bind_float binds a float value to the prepared statement at the specified index syntax duckdb_bind_double binds a double value to the prepared statement at the specified index syntax duckdb_bind_date binds a duckdb_date value to the prepared statement at the specified index syntax duckdb_bind_time binds a duckdb_time value to the prepared statement at the specified index syntax duckdb_bind_timestamp binds a duckdb_timestamp value to the prepared statement at the specified index syntax duckdb_bind_interval binds a duckdb_interval value to the prepared statement at the specified index syntax duckdb_bind_varchar binds a null-terminated varchar value to the prepared statement at the specified index syntax duckdb_bind_varchar_length binds a varchar value to the prepared statement at the specified index syntax duckdb_bind_blob binds a blob value to the prepared statement at the specified index syntax duckdb_bind_null binds a null value to the prepared statement at the specified index syntax duckdb_execute_prepared executes the prepared statement with the given bound parameters and returns a materialized query result this method can be called multiple times for each prepared statement and the parameters can be modified between calls to this function syntax the prepared statement to execute out_result the query result returns duckdbsuccess on success or duckdberror on failure duckdb_execute_prepared_arrow executes the prepared statement with the given bound parameters and returns an arrow query result syntax the prepared statement to execute out_result the query result returns duckdbsuccess on success or duckdberror on failure duckdb_arrow_scan scans the arrow stream and creates a view with the given name syntax the connection on which to execute the scan table_name name of the temporary view to create arrow arrow stream wrapper returns duckdbsuccess on success or duckdberror on failure duckdb_arrow_array_scan scans the arrow array and creates a view with the given name syntax the connection on which to execute the scan table_name name of the temporary view to create arrow_schema arrow schema wrapper arrow_array arrow array wrapper out_stream output array stream that wraps around the passed schema for releasing deleting once done returns duckdbsuccess on success or duckdberror on failure", "category": "C", "url": "/docs/api/c/prepared", "blurb": "A prepared statement is a parameterized query. The query is prepared with question marks ( ? ) or dollar symbols ( $1..." @@ -212,7 +212,7 @@ }, { "title": "C API - Startup & Shutdown", - "text": "to use duckdb you must first initialize a duckdb_database handle using duckdb_open duckdb_open takes as parameter the database file to read and write from the special value null nullptr can be used to create an in-memory database note that for an in-memory database no data is persisted to disk i e all data is lost when you exit the process with the duckdb_database handle you can create one or many duckdb_connection using duckdb_connect while individual connections are thread-safe they will be locked during querying it is therefore recommended that each thread uses its own connection to allow for the best parallel performance all duckdb_connection s have to explicitly be disconnected with duckdb_disconnect and the duckdb_database has to be explicitly closed with duckdb_close to avoid memory and file handle leaking example duckdb_database db duckdb_connection con if duckdb_open null db duckdberror handle error if duckdb_connect db con duckdberror handle error run queries cleanup duckdb_disconnect con duckdb_close db api reference syntax path to the database file on disk or nullptr or memory to open an in-memory database out_database the result database object returns duckdbsuccess on success or duckdberror on failure duckdb_open_ext extended version of duckdb_open creates a new database or opens an existing database file stored at the the given path syntax path to the database file on disk or nullptr or memory to open an in-memory database out_database the result database object config optional configuration used to start up the database system out_error if set and the function returns duckdberror this will contain the reason why the start-up failed note that the error must be freed using duckdb_free returns duckdbsuccess on success or duckdberror on failure duckdb_close closes the specified database and de-allocates all memory allocated for that database this should be called after you are done with any database allocated through duckdb_open note that failing to call duckdb_close in case of e g a program crash will not cause data corruption still it is recommended to always correctly close a database object after you are done with it syntax the database object to shut down duckdb_connect opens a connection to a database connections are required to query the database and store transactional state associated with the connection the instantiated connection should be closed using duckdb_disconnect syntax the database file to connect to out_connection the result connection object returns duckdbsuccess on success or duckdberror on failure duckdb_interrupt interrupt running query syntax the connection to interruot duckdb_query_progress get progress of the running query syntax the working connection returns -1 if no progress or a percentage of the progress duckdb_disconnect closes the specified connection and de-allocates all memory allocated for that connection syntax the connection to close duckdb_library_version returns the version of the linked duckdb with a version postfix for dev versions usually used for developing c extensions that must return this for a compatibility check syntax", + "text": "to use duckdb you must first initialize a duckdb_database handle using duckdb_open duckdb_open takes as parameter the database file to read and write from the special value null nullptr can be used to create an in-memory database note that for an in-memory database no data is persisted to disk i e all data is lost when you exit the process with the duckdb_database handle you can create one or many duckdb_connection using duckdb_connect while individual connections are thread-safe they will be locked during querying it is therefore recommended that each thread uses its own connection to allow for the best parallel performance all duckdb_connection s have to explicitly be disconnected with duckdb_disconnect and the duckdb_database has to be explicitly closed with duckdb_close to avoid memory and file handle leaking example duckdb_database db duckdb_connection con if duckdb_open null db duckdberror handle error if duckdb_connect db con duckdberror handle error run queries cleanup duckdb_disconnect con duckdb_close db api reference syntax path to the database file on disk or nullptr or memory to open an in-memory database out_database the result database object returns duckdbsuccess on success or duckdberror on failure duckdb_open_ext extended version of duckdb_open creates a new database or opens an existing database file stored at the given path syntax path to the database file on disk or nullptr or memory to open an in-memory database out_database the result database object config optional configuration used to start up the database system out_error if set and the function returns duckdberror this will contain the reason why the start-up failed note that the error must be freed using duckdb_free returns duckdbsuccess on success or duckdberror on failure duckdb_close closes the specified database and de-allocates all memory allocated for that database this should be called after you are done with any database allocated through duckdb_open note that failing to call duckdb_close in case of e g a program crash will not cause data corruption still it is recommended to always correctly close a database object after you are done with it syntax the database object to shut down duckdb_connect opens a connection to a database connections are required to query the database and store transactional state associated with the connection the instantiated connection should be closed using duckdb_disconnect syntax the database file to connect to out_connection the result connection object returns duckdbsuccess on success or duckdberror on failure duckdb_interrupt interrupt running query syntax the connection to interruot duckdb_query_progress get progress of the running query syntax the working connection returns -1 if no progress or a percentage of the progress duckdb_disconnect closes the specified connection and de-allocates all memory allocated for that connection syntax the connection to close duckdb_library_version returns the version of the linked duckdb with a version postfix for dev versions usually used for developing c extensions that must return this for a compatibility check syntax", "category": "C", "url": "/docs/api/c/connect", "blurb": "To use DuckDB, you must first initialize a duckdb_database handle using duckdb_open() . duckdb_open() takes as..." diff --git a/docs/api/c/api.md b/docs/api/c/api.md index e9e64467584..67591a00b98 100644 --- a/docs/api/c/api.md +++ b/docs/api/c/api.md @@ -297,7 +297,7 @@ selected: API Reference
### duckdb_open --- -Creates a new database or opens an existing database file stored at the the given path. +Creates a new database or opens an existing database file stored at the given path. If no path is given a new in-memory database is created instead. The instantiated database should be closed with 'duckdb_close' @@ -324,7 +324,7 @@ The result database object. ### duckdb_open_ext --- -Extended version of duckdb_open. Creates a new database or opens an existing database file stored at the the given path. +Extended version of duckdb_open. Creates a new database or opens an existing database file stored at the given path. #### Syntax --- @@ -1918,7 +1918,7 @@ Binds an int64_t value to the prepared statement at the specified index. ### duckdb_bind_hugeint --- -Binds an duckdb_hugeint value to the prepared statement at the specified index. +Binds a duckdb_hugeint value to the prepared statement at the specified index. #### Syntax --- @@ -2002,7 +2002,7 @@ Binds an uint64_t value to the prepared statement at the specified index. ### duckdb_bind_float --- -Binds an float value to the prepared statement at the specified index. +Binds a float value to the prepared statement at the specified index. #### Syntax --- @@ -2016,7 +2016,7 @@ Binds an float value to the prepared statement at the specified index. ### duckdb_bind_double --- -Binds an double value to the prepared statement at the specified index. +Binds a double value to the prepared statement at the specified index. #### Syntax --- diff --git a/docs/api/c/connect.md b/docs/api/c/connect.md index 841452ebe25..29295f6415e 100644 --- a/docs/api/c/connect.md +++ b/docs/api/c/connect.md @@ -40,7 +40,7 @@ duckdb_close(&db); ### duckdb_open --- -Creates a new database or opens an existing database file stored at the the given path. +Creates a new database or opens an existing database file stored at the given path. If no path is given a new in-memory database is created instead. The instantiated database should be closed with 'duckdb_close' @@ -67,7 +67,7 @@ The result database object. ### duckdb_open_ext --- -Extended version of duckdb_open. Creates a new database or opens an existing database file stored at the the given path. +Extended version of duckdb_open. Creates a new database or opens an existing database file stored at the given path. #### Syntax --- diff --git a/docs/api/c/prepared.md b/docs/api/c/prepared.md index c9ae8a04480..bcc88381058 100644 --- a/docs/api/c/prepared.md +++ b/docs/api/c/prepared.md @@ -316,7 +316,7 @@ Binds an int64_t value to the prepared statement at the specified index. ### duckdb_bind_hugeint --- -Binds an duckdb_hugeint value to the prepared statement at the specified index. +Binds a duckdb_hugeint value to the prepared statement at the specified index. #### Syntax --- @@ -400,7 +400,7 @@ Binds an uint64_t value to the prepared statement at the specified index. ### duckdb_bind_float --- -Binds an float value to the prepared statement at the specified index. +Binds a float value to the prepared statement at the specified index. #### Syntax --- @@ -414,7 +414,7 @@ Binds an float value to the prepared statement at the specified index. ### duckdb_bind_double --- -Binds an double value to the prepared statement at the specified index. +Binds a double value to the prepared statement at the specified index. #### Syntax ---