//===----------------------------------------------------------------------===// // DuckDB // // duckdb/main/connection.hpp // // //===----------------------------------------------------------------------===// #pragma once #include "duckdb/common/enums/profiler_format.hpp" #include "duckdb/common/serializer/buffered_file_writer.hpp" #include "duckdb/common/winapi.hpp" #include "duckdb/function/udf_function.hpp" #include "duckdb/main/materialized_query_result.hpp" #include "duckdb/main/pending_query_result.hpp" #include "duckdb/main/prepared_statement.hpp" #include "duckdb/main/query_result.hpp" #include "duckdb/main/relation.hpp" #include "duckdb/main/stream_query_result.hpp" #include "duckdb/main/table_description.hpp" #include "duckdb/parser/sql_statement.hpp" namespace duckdb { class ColumnDataCollection; class ClientContext; class DatabaseInstance; class DuckDB; class LogicalOperator; class SelectStatement; struct BufferedCSVReaderOptions; typedef void (*warning_callback)(std::string); //! A connection to a database. This represents a (client) connection that can //! be used to query the database. class Connection { public: DUCKDB_API explicit Connection(DuckDB &database); DUCKDB_API explicit Connection(DatabaseInstance &database); DUCKDB_API ~Connection(); shared_ptr context; warning_callback warning_cb; public: //! Returns query profiling information for the current query DUCKDB_API string GetProfilingInformation(ProfilerPrintFormat format = ProfilerPrintFormat::QUERY_TREE); //! Interrupt execution of the current query DUCKDB_API void Interrupt(); //! Enable query profiling DUCKDB_API void EnableProfiling(); //! Disable query profiling DUCKDB_API void DisableProfiling(); DUCKDB_API void SetWarningCallback(warning_callback); //! Enable aggressive verification/testing of queries, should only be used in testing DUCKDB_API void EnableQueryVerification(); DUCKDB_API void DisableQueryVerification(); //! Force parallel execution, even for smaller tables. Should only be used in testing. DUCKDB_API void ForceParallelism(); //! Issues a query to the database and returns a QueryResult. This result can be either a StreamQueryResult or a //! MaterializedQueryResult. The result can be stepped through with calls to Fetch(). Note that there can only be //! one active StreamQueryResult per Connection object. Calling SendQuery() will invalidate any previously existing //! StreamQueryResult. DUCKDB_API unique_ptr SendQuery(const string &query); //! Issues a query to the database and materializes the result (if necessary). Always returns a //! MaterializedQueryResult. DUCKDB_API unique_ptr Query(const string &query); //! Issues a query to the database and materializes the result (if necessary). Always returns a //! MaterializedQueryResult. DUCKDB_API unique_ptr Query(unique_ptr statement); // prepared statements template unique_ptr Query(const string &query, Args... args) { vector values; return QueryParamsRecursive(query, values, args...); } //! Issues a query to the database and returns a Pending Query Result. Note that "query" may only contain //! a single statement. DUCKDB_API unique_ptr PendingQuery(const string &query, bool allow_stream_result = false); //! Issues a query to the database and returns a Pending Query Result DUCKDB_API unique_ptr PendingQuery(unique_ptr statement, bool allow_stream_result = false); //! Prepare the specified query, returning a prepared statement object DUCKDB_API unique_ptr Prepare(const string &query); //! Prepare the specified statement, returning a prepared statement object DUCKDB_API unique_ptr Prepare(unique_ptr statement); //! Get the table info of a specific table (in the default schema), or nullptr if it cannot be found DUCKDB_API unique_ptr TableInfo(const string &table_name); //! Get the table info of a specific table, or nullptr if it cannot be found DUCKDB_API unique_ptr TableInfo(const string &schema_name, const string &table_name); //! Extract a set of SQL statements from a specific query DUCKDB_API vector> ExtractStatements(const string &query); //! Extract the logical plan that corresponds to a query DUCKDB_API unique_ptr ExtractPlan(const string &query); //! Appends a DataChunk to the specified table DUCKDB_API void Append(TableDescription &description, DataChunk &chunk); //! Appends a ColumnDataCollection to the specified table DUCKDB_API void Append(TableDescription &description, ColumnDataCollection &collection); //! Returns a relation that produces a table from this connection DUCKDB_API shared_ptr Table(const string &tname); DUCKDB_API shared_ptr Table(const string &schema_name, const string &table_name); //! Returns a relation that produces a view from this connection DUCKDB_API shared_ptr View(const string &tname); DUCKDB_API shared_ptr View(const string &schema_name, const string &table_name); //! Returns a relation that calls a specified table function DUCKDB_API shared_ptr TableFunction(const string &tname); DUCKDB_API shared_ptr TableFunction(const string &tname, const vector &values, const named_parameter_map_t &named_parameters); DUCKDB_API shared_ptr TableFunction(const string &tname, const vector &values); //! Returns a relation that produces values DUCKDB_API shared_ptr Values(const vector> &values); DUCKDB_API shared_ptr Values(const vector> &values, const vector &column_names, const string &alias = "values"); DUCKDB_API shared_ptr Values(const string &values); DUCKDB_API shared_ptr Values(const string &values, const vector &column_names, const string &alias = "values"); //! Reads CSV file DUCKDB_API shared_ptr ReadCSV(const string &csv_file); DUCKDB_API shared_ptr ReadCSV(const string &csv_file, BufferedCSVReaderOptions &options); DUCKDB_API shared_ptr ReadCSV(const string &csv_file, const vector &columns); //! Reads Parquet file DUCKDB_API shared_ptr ReadParquet(const string &parquet_file, bool binary_as_string); //! Returns a relation from a query DUCKDB_API shared_ptr RelationFromQuery(const string &query, const string &alias = "queryrelation", const string &error = "Expected a single SELECT statement"); DUCKDB_API shared_ptr RelationFromQuery(unique_ptr select_stmt, const string &alias = "queryrelation"); //! Returns a substrait BLOB from a valid query DUCKDB_API string GetSubstrait(const string &query); //! Returns a Query Result from a substrait blob DUCKDB_API unique_ptr FromSubstrait(const string &proto); //! Returns a substrait BLOB from a valid query DUCKDB_API string GetSubstraitJSON(const string &query); //! Returns a Query Result from a substrait JSON DUCKDB_API unique_ptr FromSubstraitJSON(const string &json); DUCKDB_API void BeginTransaction(); DUCKDB_API void Commit(); DUCKDB_API void Rollback(); DUCKDB_API void SetAutoCommit(bool auto_commit); DUCKDB_API bool IsAutoCommit(); DUCKDB_API bool HasActiveTransaction(); //! Fetch a list of table names that are required for a given query DUCKDB_API unordered_set GetTableNames(const string &query); template void CreateScalarFunction(const string &name, TR (*udf_func)(Args...)) { scalar_function_t function = UDFWrapper::CreateScalarFunction(name, udf_func); UDFWrapper::RegisterFunction(name, function, *context); } template void CreateScalarFunction(const string &name, vector args, LogicalType ret_type, TR (*udf_func)(Args...)) { scalar_function_t function = UDFWrapper::CreateScalarFunction(name, args, std::move(ret_type), udf_func); UDFWrapper::RegisterFunction(name, args, ret_type, function, *context); } template void CreateVectorizedFunction(const string &name, scalar_function_t udf_func, LogicalType varargs = LogicalType::INVALID) { UDFWrapper::RegisterFunction(name, udf_func, *context, std::move(varargs)); } void CreateVectorizedFunction(const string &name, vector args, LogicalType ret_type, scalar_function_t udf_func, LogicalType varargs = LogicalType::INVALID) { UDFWrapper::RegisterFunction(name, std::move(args), std::move(ret_type), udf_func, *context, std::move(varargs)); } //------------------------------------- Aggreate Functions ----------------------------------------// template void CreateAggregateFunction(const string &name) { AggregateFunction function = UDFWrapper::CreateAggregateFunction(name); UDFWrapper::RegisterAggrFunction(function, *context); } template void CreateAggregateFunction(const string &name) { AggregateFunction function = UDFWrapper::CreateAggregateFunction(name); UDFWrapper::RegisterAggrFunction(function, *context); } template void CreateAggregateFunction(const string &name, LogicalType ret_type, LogicalType input_typeA) { AggregateFunction function = UDFWrapper::CreateAggregateFunction(name, ret_type, input_typeA); UDFWrapper::RegisterAggrFunction(function, *context); } template void CreateAggregateFunction(const string &name, LogicalType ret_type, LogicalType input_typeA, LogicalType input_typeB) { AggregateFunction function = UDFWrapper::CreateAggregateFunction(name, ret_type, input_typeA, input_typeB); UDFWrapper::RegisterAggrFunction(function, *context); } void CreateAggregateFunction(const string &name, vector arguments, LogicalType return_type, aggregate_size_t state_size, aggregate_initialize_t initialize, aggregate_update_t update, aggregate_combine_t combine, aggregate_finalize_t finalize, aggregate_simple_update_t simple_update = nullptr, bind_aggregate_function_t bind = nullptr, aggregate_destructor_t destructor = nullptr) { AggregateFunction function = UDFWrapper::CreateAggregateFunction(name, arguments, return_type, state_size, initialize, update, combine, finalize, simple_update, bind, destructor); UDFWrapper::RegisterAggrFunction(function, *context); } private: unique_ptr QueryParamsRecursive(const string &query, vector &values); template unique_ptr QueryParamsRecursive(const string &query, vector &values, T value, Args... args) { values.push_back(Value::CreateValue(value)); return QueryParamsRecursive(query, values, args...); } }; } // namespace duckdb