CAPIV2: Part one - #24702
Conversation
# Conflicts: # src/execution/operator/helper/physical_set.cpp
| // !!!!!!! | ||
| // WARNING: this file is autogenerated, manual changes will be overwritten | ||
| // !!!!!!! |
There was a problem hiding this comment.
The generated duckdb_v2.h API header
| //---------------------------------------------------------------------------------------------------------------------- | ||
| // 8888888b. 888 8888888b. 888888b. d8888 8888888b. 8888888 | ||
| // 888 "Y88b 888 888 "Y88b 888 "88b d88888 888 Y88b 888 | ||
| // 888 888 888 888 888 888 .88P d88P888 888 888 888 | ||
| // 888 888 888 888 .d8888b 888 888 888 888 8888888K. d88P 888 888 d88P 888 | ||
| // 888 888 888 888 d88P" 888 .88P 888 888 888 "Y88b d88P 888 8888888P" 888 | ||
| // 888 888 888 888 888 888888K 888 888 888 888 d88P 888 888 888 | ||
| // 888 .d88P Y88b 888 Y88b. 888 "88b 888 .d88P 888 d88P d8888888888 888 888 | ||
| // 8888888P" "Y88888 "Y8888P 888 888 8888888P" 8888888P" d88P 888 888 8888888 | ||
| //---------------------------------------------------------------------------------------------------------------------- |
There was a problem hiding this comment.
The "stable" C++ API header. You only need to include this and duckdb_cpp.cpp to use C++ on-top of the V2-C-API from a client. For an extension you also need duckdb_cpp_extension.hpp - but thats it.
One of the really cool things Im happy about is that this header by itself does not include duckdb_v2.h itself (only the implementation file does), so it does not pollute your source files with a bunch of c-symbols.
| // A minimal extension built against the V2 C API through the stable C++ API. It exists to exercise the V2 loader | ||
| // end-to-end: the entrypoint, the vtable handed out by get_api, and the context DuckDB lends for the duration of the | ||
| // load. There is no registration API on the V2 surface yet, so the body only reads through the context and logs. | ||
|
|
||
| #include "duckdb_cpp_extension.hpp" | ||
|
|
||
| static constexpr const char *LOG_TYPE = "CppApiDemo"; | ||
|
|
||
| using namespace duckdb::cxx; | ||
|
|
||
| DUCKDB_CPP_EXTENSION_ENTRYPOINT(Extension &extension, Context &context) { | ||
| (void)extension; | ||
|
|
||
| // Binding a type proves the context is live and has a transaction: this reaches into the catalog. | ||
| const auto type = context.ParseType("STRUCT(a INTEGER, b VARCHAR)"); | ||
|
|
||
| context.Log(LogLevel::INFO, "cpp_api_demo loaded, parsed " + type.ToText(), LOG_TYPE); | ||
| } |
There was a problem hiding this comment.
Super small example of how the entrypoint for a C++ extension that builds on top of the stableduckdb_cpp.hpp header looks.
There are no functions to e.g. register scalar functions and do other extension-like stuff etc yet, but in the future they will be exposed as methods on the Extension object. (similar to how the ExtensionLoader works today)
This PR adds an initial draft of the first half of the V2 C-API + the stable "C++ API" built on top of it.
WARNING: This is a DRAFT
Nothing here should be considered decided or stable - we're still interested in receiving feedback, but don't start building against this yet or panic if certain features are missing. Also lots of the documentation is still clanker-generated vomit left from the initial prototyping phase. Things will evolve significantly in the coming weeks.
This first half covers the following sections:
Environment(new)Databaseand optionsConnectionContext(new)Extension, and new entry-point (new)SQLStatements(new)QueryResult(streaming, new)LogicalTypeValueDataChunkVector(new non-flat vector-types)VectorView(new)This is focused on just adding enough surface to support "client" use-cases, e.g. open a database, perform some queries, fetch some results - and not so much "extending DuckDB with new features". We've prototyped that other half already in a separate fork (scalar/table/cast/copy functions, filesystem, custom types, arrow interop, logging, etc, etc) which will follow soon.
This PR is big, but Is nonetheless smaller than it might look at first glance due to the large number of lines added by spec files and tests. I think the primarily interesting files to look at is
duckdb_v2.h,duckdb_cpp.hpp. Additionally, almost 60% of the entire API surface is currently dedicated to differentduckdb::Valueconstructors/accessors. More on that further below.I'll try to go through section-by-section and highlight some of the motivations, design decisions, ideas, future work, and notable differences from the V1 API.
Error Handling
TODOThe
EnvironmentTODODatabaseandDatabaseOptionsTODOConnectionvsContextTODOV2
ExtensionentrypointTODOSQL Statement Expansion
TODOStreaming Query Results
TODOContext-scoped Types and Values
TODONon-flat vectors and
VectorViewTODO