hyperapi::Connection Class Reference

Defines a Hyper connection. More...

#include <Connection.hpp>

Public Member Functions
	Connection (const Endpoint &endpoint, const std::unordered_map< std::string, std::string > &parameters={})
	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 > &parameters={})
	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.

Detailed Description

Defines a Hyper connection.

Used for all interactions with Hyper.

Examples

create_hyper_file_from_csv.cpp, delete_data_in_existing_hyper_file.cpp, insert_data_into_multiple_tables.cpp, insert_data_into_single_table.cpp, insert_data_with_expressions.cpp, insert_spatial_data_to_a_hyper_file.cpp, read_and_print_data_from_existing_hyper_file.cpp, and update_data_in_existing_hyper_file.cpp.

Definition at line 42 of file Connection.hpp.

Constructor & Destructor Documentation

Connection() [1/3]

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.

Parameters

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.

Exceptions

HyperException

If connecting failed.

Connection() [2/3]

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.

Parameters

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.

Exceptions

HyperException

If connecting failed or connecting to the specified endpoint is not supported by this version of the API.

Connection() [3/3]

hyperapi::Connection::Connection ( )

inlinenoexcept

Constructs a Connection object that does not represent a connection.

Postcondition

!isOpen()

Definition at line 79 of file Connection.hpp.

~Connection()

virtual hyperapi::Connection::~Connection ( )

virtualnoexcept

Destructor.

Closes the connection (if open).

Member Function Documentation

cancel()

void hyperapi::Connection::cancel ( )

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.

close()

virtual void hyperapi::Connection::close ( )

virtualnoexcept

Closes the connection.

Postcondition

!isOpen()

executeCommand()

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.

Parameters

sql

The query

Exceptions

HyperException

Precondition

connection.isOpen()

Returns

the number of affected rows, if applicable; otherwise -1

executeQuery()

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.

Parameters

sql

The query

Exceptions

HyperException

Precondition

isOpen()

Returns

the query result result consumption.

executeScalarQuery()

template<typename T >

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.

int                     i1 = executeScalarQuery<int>("...");
hyperapi::optional<int> i2 = executeScalarQuery<optional<int>(...);

This method will throw if the executed query doesn't exactly return one row with one column.

Template Parameters

T	The anticipated value type

Parameters

sql

The query

Exceptions

HyperException

Precondition

connection.isOpen()

The requested type is compatible to the column type.

Returns

the single result value, or if T is an optional<>, an absent value in case of a NULL query result.

getCatalog()

Catalog & hyperapi::Connection::getCatalog ( )

noexcept

Returns the catalog of this connection.

Precondition

isOpen()

getHyperServiceVersion()

HyperServiceVersion hyperapi::Connection::getHyperServiceVersion

(

)

Returns the Hyper Service version of this connection.

Precondition

isOpen()

Returns

The Hyper Service version of this connection.

Exceptions

HyperException

isCapabilityActive()

bool hyperapi::Connection::isCapabilityActive

(

const std::string &

capabilityFlag

)

Returns true if the capability flag is active on this connection.

Precondition

isOpen()

Parameters

capabilityFlag

The capability flag to check. It is prefixed with capability_.

isOpen()

bool hyperapi::Connection::isOpen ( ) const

inlinenoexcept

Checks whether the connection is open.

Definition at line 208 of file Connection.hpp.

isReady()

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).

Precondition

connection.isOpen()

Returns

Whether the connection is ready.

querySupportedHyperServiceVersionRange()

static std::vector< HyperServiceVersion > hyperapi::Connection::querySupportedHyperServiceVersionRange ( const Endpoint &  endpoint )

static

Connects to the Hyper endpoint and determines which Hyper Service version numbers are common between the Hyper API and the Hyper server.

Parameters

endpoint

Endpoint to connect to.

Returns

List of Hyper Service versions that are supported by both this HAPI and the endpoint.

Exceptions

HyperException

If connecting failed.

---

The documentation for this class was generated from the following file:

• hyperapi/Connection.hpp