C++ Driver API Reference

On this page

Connection and transport
Cursor and statements
Result objects
Entity metadata
Typed values
Experimental streaming
Exceptions and resource ownership

Include PolyphenyCPPDriver.h for connections, cursors, results, metadata and typed values. This reference covers the application-facing API in v1.0.0. Start with the integration guide to build and connect.

Connection and transport

Function	Behavior
`Connection::Connection(host, user, password)`	Opens a plain TCP connection to `host` on port 20590. Uses the `public` namespace and enables auto-commit.
`Connection::Connection(properties)`	Opens plain TCP to `localhost:20590` using the supplied `ConnectionProperties`.
`Connection::Connection(properties, transport)`	Takes a `std::unique_ptr<Transport::Transport>` and opens a connection with it. Select this overload for a custom port or Unix socket.
`~Connection()`	Ends the Prism session and closes the transport.
`get_server_api_version()`	Returns the advertised Prism major and minor versions as `std::pair<int, int>`.
`search_entities(namespace[, pattern])`	Returns the Prism `EntitiesResponse` for the specified namespace.
`get_document_collections(namespace[, pattern])`	Returns a `std::vector<Results::DocumentMetadata>` with the matching collection entities. Requires server support for Prism 2.2 document metadata.

The constructor copies ConnectionProperties when opening the connection. Use the property object’s setters to configure the next connection.

Property	Accessors	Default
Username	`get_username()`, `set_username(value)`	`pa`
Password	`get_password()`, `set_password(value)`	Empty string
Default namespace	`get_default_namespace()`, `set_default_namespace(value)`	`public`
Send password	`get_is_password_required()`, `set_is_password_required(value)`	`true`
Auto-commit	`get_is_auto_commit()`, `set_is_auto_commit(value)`	`true`

Set the same values when constructing ConnectionProperties(username, password, default_namespace, is_password_required, is_auto_commit). Each argument has the default shown above. The password flag controls whether the password is sent in the Prism handshake. Keep auto-commit enabled for standalone statements. The v1.0.0 connection API exposes transaction configuration through this flag, while transaction control requires an API with explicit commit and rollback support.

Transport constructor	Header	Behavior
`Transport::PlainTcpTransport(host, port)`	`transport/PlainTcpTransport.h`	Plain TCP. The port defaults to 20590 and the no-argument constructor uses `localhost`.
`Transport::UnixTransport(socket_file)`	`transport/UnixTransport.h`	Unix-domain socket on a Unix-compatible platform. Pass the actual socket path from the server configuration.
`Transport::SecureTcpTransport(cert_file, key_file, host, port)`	`transport/SecureTcpTransport.h`	Opens a TLS listener using OpenSSL. The optional certificate and private key are PEM files for client authentication. Defaults are empty file paths, `localhost` and 20590. Version 1.0.0 leaves peer certificate and hostname verification disabled.

Custom transports implement connect(), send_message(message) and receive_message() from transport/Transport.h. Send and receive whole serialized Prism messages. Implement shutdown() to interrupt any blocked receive so disconnect can finish. Connections invoke these methods on the supplied transport.

Cursor and statements

Function	Behavior
`Cursor(connection)`	Creates a cursor bound to that connection. Use a separate cursor for each active statement.
`Cursor(other)`	Copies the cursor’s connection and statement state. Use fresh cursors for independent statements.
`execute(language, statement[, namespace])`	Executes one statement and returns a `std::unique_ptr<Results::Result>`.
`execute(language, statements[, namespace])`	Executes a `std::vector<std::string>` of data manipulation statements and returns their update counts as `std::vector<uint64_t>`.
`prepare_indexed(language, statement[, namespace])`	Prepares a statement with positional `?` placeholders.
`prepare_named(language, statement[, namespace])`	Prepares a statement with `:name` placeholders.
`execute_prepared(parameters)`	Executes the prepared statement with a mutable `std::vector<Types::TypedValue>` or a mutable `std::unordered_map<std::string, Types::TypedValue>` matching the preparation mode. Returns a regular result.
`execute_prepared(parameter_sets)`	Executes an indexed data manipulation statement with a mutable `std::vector<std::vector<Types::TypedValue>>`. Returns the server’s update counts.

Omit the namespace to use the default from the connection. See the prepared SQL and batch example.

Result objects

Type	Functions
`Results::Result`	`get_result_type()` returns `RELATIONAL`, `DOCUMENT`, `GRAPH` or `SCALAR`. `unwrap<T>()` returns a non-owning pointer to the specified concrete result or throws on a type mismatch.
`Results::ScalarResult`	`get_scalar()` returns an unsigned 64-bit scalar, such as the affected row count.
`Results::RelationalResult`	`get_metadata()` returns shared column metadata. `begin()` and `end()` access rows.
`Results::RelationalMetadata`	`get_column_count()` counts result columns. `get_column_meta(index)` takes a valid zero-based index. `get_column_index_from_label(label)` maps a label to its zero-based index and throws for an unknown label.
`Results::RelationalColumnMetadata`	`get_column_index()` returns the reported index. `get_column_name()` and `get_column_label()` return the underlying name and result label. `get_protocol_type_name()` returns the Prism type name. `get_is_nullable()`, `get_length()`, `get_precision()` and `get_scale()` return the reported nullability and size characteristics.
`Results::Row`	`operator[]` returns a reference by zero-based index or column label. `at(index)` and `at(label)` return a copy with bounds or lookup checking. `size()` counts columns. `begin()` and `end()` iterate over their values.
`Results::DocumentResult`	`begin()` and `end()` access documents as `std::unordered_map<std::string, Types::TypedValue>`.
`Results::GraphResult`	`begin()` and `end()` access `std::shared_ptr<Results::GraphElement>` values from graph frames.
`Results::GraphElement`	`get_id()`, `get_name()` and `get_labels()` expose the element’s attributes. `get_element_type()` returns `GraphElementType::NODE` or `GraphElementType::EDGE`. The element inherits map operations to access its properties.
`Results::Node`	Exposes the common graph methods and property map. Include `results/Node.h` for the concrete class.
`Results::Edge`	`get_left()` and `get_right()` return the endpoint IDs. `get_direction()` returns `Results::EdgeDirection::LEFT_TO_RIGHT`, `RIGHT_TO_LEFT` or `NONE`. Include `results/Edge.h`.

The driver constructs results, rows, column metadata, nodes and edges from the corresponding Prism frame or message types. For normal queries, obtain them through the cursor and the result accessors. A scalar result can also be constructed directly from its uint64_t value.

The relational, document and graph iterators support operator*, prefix operator++, operator== and operator!=. Incrementing can fetch another page and change end(). Reevaluate end() in the loop condition. The query examples show this pattern and the server requirements for graph frames.

For graph downcasts in v1.0.0, check get_element_type() and use static_cast as in the example. The declared GraphElement::unwrap<T>() uses a dynamic_cast that fails to compile with this release’s graph base class.

Entity metadata

search_entities() returns the full generated Prism entities response, including the table variant for relational namespaces. Inspect each entity’s variant before accessing its metadata. Pass a pattern such as prod% to filter by name on the server. In Polypheny-DB, % matches any sequence and _ matches one character. Omit the pattern to request all entities in the namespace.

get_document_collections() filters the response to document entities and exposes the following fields.

Type	Field	Meaning
`Results::DocumentMetadata`	`namespace_name`	Namespace containing the collection.
`Results::DocumentMetadata`	`collection_name`	Name of the collection.
`Results::DocumentMetadata`	`fields`	Known field paths and inferred types observed in the sample.
`Results::DocumentMetadata`	`sample_document_json`	Optional JSON string with a sample document. Check the `std::optional` before reading it.
`Results::DocumentMetadata`	`document_indexes`	Index descriptors reported by the collection’s storage adapters.
`Results::DocumentField`	`field_path`	Field name or nested path. Dots separate path segments. A literal dot is escaped as `\.` and a literal backslash as `\\`.
`Results::DocumentField`	`type_name`	Server-reported type such as `string`, `int`, `double`, `bool`, `array`, `object`, `null` or `mixed`.
`Results::DocumentField`	`is_optional`	True if the field was missing or null in one or more sampled documents.
`Results::DocumentIndex`	`field_path`	Path of the indexed field.
`Results::DocumentIndex`	`index_type`	Storage adapter’s index type.
`Results::DocumentIndex`	`unique`	True when the reported index enforces uniqueness for this single field within the index’s coverage.

Polypheny-DB infers the shape from up to 100 documents per collection. Treat these fields as observations of the sample. A collection with no sampled documents returns no inferred fields and omits the sample JSON. The index list can be empty.

Typed values

Types::TypedValue wraps Prism values from results and values passed to prepared statements. Construct one from the C++ type in the table and read it with the corresponding accessor. Accessors require the matching Prism value variant and throw std::runtime_error on a type mismatch. They can deserialize lazily and are non-const. When a row is const, use row.at(...) to get a copy.

Prism value	C++ constructor input	Accessor
Null	No argument	`is_null()` tests the variant.
Boolean	`bool`	`as_boolean()`
32-bit integer	`int32_t`	`as_int32_t()`
64-bit integer	`int64_t`	`as_int64_t()`
Decimal	GMP `mpf_class`	`as_big_decimal()`
Single precision float	`float`	`as_float()`
Double precision float	`double`	`as_double()`
Date	`std::chrono::system_clock::time_point`	`as_date()`
Time of day	`std::chrono::milliseconds` since midnight	`as_time()`
Timestamp	`std::chrono::system_clock::time_point` and a second argument of `true`	`as_timestamp()`
Interval	`Types::Interval`	`as_interval()`
String	`std::string` or `const char*`	`as_string()`
Binary	`std::vector<uint8_t>`	`as_bytes()`
List	`std::list<Types::TypedValue>`	`as_list()`
Document	`std::unordered_map<std::string, Types::TypedValue>`	`as_document()`
File	`Types::File`	`as_file()`

Use get_value_case() for the exact Protobuf variant, or operator<< to display a value. TypedValue is copy-constructible and copy-assignable. At the protocol boundary, the constructor taking a ProtoValue and a client wraps a wire value, and serialize(streaming_index) transfers ownership of a new ProtoValue to the caller.

Types::Interval(months, milliseconds) stores the two unsigned components. Use get_months() and get_milliseconds() to read them, equals(other) to compare, and operator<< to display them. The ProtoInterval constructor and serialize() convert to and from the wire representation.

Include types/File.h to construct Types::File from a byte vector or an existing std::istream. The optional forward_only argument restricts backward seeks. An input stream must outlive its File. File derives from std::streambuf, so an std::istream can read an as_file() result while the buffer remains alive. The driver also supports copying or assigning a File.

Experimental streaming

The experimental build uses the Prism 5.1 schema and advertises client and server streaming. It requires a compatible Prism 5.1 server. In the default Prism 2.2 build, strings, binary values and files travel inline. In a streaming build, TypedValue::STREAMING_THRESHOLD controls when strings and binary values are sent as streams, and bound files use streams when a statement streaming index is available. Use the default Prism 2.2 build for get_document_collections().

Exceptions and resource ownership

Server errors from synchronous requests such as preparation, prepared execution and metadata lookup raise Errors::ServerError from connection/ServerError.h. Error responses to unparameterized statements and batches raise std::runtime_error.
Socket closures can raise Errors::ConnectionClosedError from transport/ConnectionClosedError.h. Both driver-specific error classes derive from std::exception and provide what().
Invalid result or value conversions and several transport errors raise std::runtime_error. Bounds-checked row access and missing map keys can raise std::out_of_range.
Keep the connection and cursor alive while reading results. Destroy the result before reusing its cursor. Pointers from unwrap<T>() and iterators are valid while the owning result is alive.

Prepared Statements

.NET