Hyper API for C++ 0.0.20027
Hyper client library for C++ applications
|
Defines a Hyper connection. More...
#include <Connection.hpp>
Public Member Functions | |
Connection (const Endpoint &endpoint, const std::unordered_map< std::string, std::string > ¶meters={}) | |
Connects to a Hyper endpoint without attaching to a database. | |
Connection (const Endpoint &endpoint, const std::string &databasePath, CreateMode createMode=CreateMode::None, const std::unordered_map< std::string, std::string > ¶meters={}) | |
Connects to a Hyper endpoint and attaches to exactly one database. | |
Connection () noexcept | |
Constructs a Connection object that does not represent a connection. | |
virtual | ~Connection () noexcept |
Destructor. | |
Connection (Connection &&other) noexcept | |
Move constructor. | |
Connection & | operator= (Connection &&other) noexcept |
Move assignment operator. | |
Connection (const Connection &other)=delete | |
Connection & | operator= (const Connection &other)=delete |
HYPER_API_NODISCARD Result | executeQuery (const std::string &sql) |
Executes a SQL query and returns the result. | |
int64_t | executeCommand (const std::string &sql) |
Executes a SQL command and returns the affected row count, if any. | |
template<typename T > | |
T | executeScalarQuery (const std::string &sql) |
Executes a SQL query that returns exactly one row with one column. | |
Catalog & | getCatalog () noexcept |
Returns the catalog of this connection. | |
void | cancel () noexcept |
Issues an asynchronous cancel request for the running query on the given connection. | |
bool | isReady () |
Checks whether the connection is ready, i.e., if the connection can be used. | |
bool | isOpen () const noexcept |
Checks whether the connection is open. | |
virtual void | close () noexcept |
Closes the connection. | |
HyperServiceVersion | getHyperServiceVersion () |
Returns the Hyper Service version of this connection. | |
bool | isCapabilityActive (const std::string &capabilityFlag) |
Returns true if the capability flag is active on this connection. | |
Static Public Member Functions | |
static std::vector< HyperServiceVersion > | querySupportedHyperServiceVersionRange (const Endpoint &endpoint) |
Connects to the Hyper endpoint and determines which Hyper Service version numbers are common between the Hyper API and the Hyper server. | |
Defines a Hyper connection.
Used for all interactions with Hyper.
Definition at line 42 of file Connection.hpp.
hyperapi::Connection::Connection | ( | const Endpoint & | endpoint, |
const std::unordered_map< std::string, std::string > & | parameters = {} |
||
) |
Connects to a Hyper endpoint without attaching to a database.
endpoint | The endpoint of the server to connect to. |
parameters | Optional connection parameters to pass to Hyper. The available parameters are documented in the Tableau Hyper documentation, chapter "Connection Settings". All parameter keys and values are expected to be passed in UTF-8 encoding. |
HyperException | If connecting failed. |
hyperapi::Connection::Connection | ( | const Endpoint & | endpoint, |
const std::string & | databasePath, | ||
CreateMode | createMode = CreateMode::None , |
||
const std::unordered_map< std::string, std::string > & | parameters = {} |
||
) |
Connects to a Hyper endpoint and attaches to exactly one database.
endpoint | The endpoint of the server to connect to. |
databasePath | The name/path of the database to connect to. The database will be attached using the stem of the databasePath as name. |
createMode | Whether the database should be created and what to do in case of an already existing database. |
parameters | Optional connection parameters to pass to Hyper. The available parameters are documented in the Tableau Hyper documentation, chapter "Connection Settings". All parameter keys and values are expected to be passed in UTF-8 encoding. |
HyperException | If connecting failed or connecting to the specified endpoint is not supported by this version of the API. |
|
inlinenoexcept |
Constructs a Connection
object that does not represent a connection.
Definition at line 79 of file Connection.hpp.
|
virtualnoexcept |
Destructor.
Closes the connection (if open).
|
noexcept |
Issues an asynchronous cancel request for the running query on the given connection.
This method may be called from another thread. Upon cancel, the command executing the query may fail. Note that this is a best-effort method that will never throw, even if the connection is closed. It is not guaranteed to do an actual cancel.
|
virtualnoexcept |
Closes the connection.
int64_t hyperapi::Connection::executeCommand | ( | const std::string & | sql | ) |
Executes a SQL command and returns the affected row count, if any.
If the SQL statement is an UPDATE, INSERT, or DELETE statement, then this method will return the number of affected rows, otherwise it will return -1.
Note that this method can be used to execute any SQL command, even if it returns a result. In that case, the result is discarded.
sql | The query |
HyperException |
HYPER_API_NODISCARD Result hyperapi::Connection::executeQuery | ( | const std::string & | sql | ) |
Executes a SQL query and returns the result.
This method can be used to execute any SQL command, even if it doesn't return a result. In this case, the result will be empty.
Note that this method is flagged "no_discard", as you should never use it if you don't need to look at the result. If you don't need a result, use executeCommand instead.
sql | The query |
HyperException |
T hyperapi::Connection::executeScalarQuery | ( | const std::string & | sql | ) |
Executes a SQL query that returns exactly one row with one column.
The template parameter T
has to be set to the anticipated value type of the column, which is the type that the respective getTYPE
method of the class Row
would return.
An exception to this rule are the types string_view
and ByteSpan
, because these are non-owning references into the query result. When the method returns, the result is already deconstructed, so we need to return an owning reference instead, which is std::string
for string_view
and std::vector<uint8_t>
for ByteSpan
. E.g., for the type Text
, Row::getText
would return string_view
, so T
would need to be std::string
. Using the wrong type here will cause an exception at runtime.
Another exception to the rule is that this method generally allows larger integer types than the query uses. So a query producing an INTEGER
can be templated with an int32_t
or an int64_t
.
Finally, all types can be retrieved using T = std::vector<uint8_t>
, which will result in calling the getRaw
method to get the raw binary representation of the type. Note that the binary representation is not part of the supported interface, so it can change between versions.
By default, the return type of this method is T
. If the result can be NULL however, then T has to be an optional<>; otherwise, a NULL value would result in an exception at runtime.
This method will throw if the executed query doesn't exactly return one row with one column.
T | The anticipated value type |
sql | The query |
HyperException |
|
noexcept |
Returns the catalog of this connection.
HyperServiceVersion hyperapi::Connection::getHyperServiceVersion | ( | ) |
Returns the Hyper Service version of this connection.
HyperException |
bool hyperapi::Connection::isCapabilityActive | ( | const std::string & | capabilityFlag | ) |
Returns true if the capability flag is active on this connection.
capabilityFlag | The capability flag to check. It is prefixed with capability_ . |
|
inlinenoexcept |
Checks whether the connection is open.
Definition at line 208 of file Connection.hpp.
bool hyperapi::Connection::isReady | ( | ) |
Checks whether the connection is ready, i.e., if the connection can be used.
A connection that is not ready is currently processing a query, so using it for further query methods will throw a HyperException. Note that this method is not thread-safe; only use it on the same thread that potentially uses the connection.
(Note that a non-ready connection doesn't mean that the thread is in a blocking call; an open Result for example always keeps the connection busy).
|
static |
Connects to the Hyper endpoint and determines which Hyper Service version numbers are common between the Hyper API and the Hyper server.
endpoint | Endpoint to connect to. |
HyperException | If connecting failed. |