CppCrate::Client Class Reference

Public Types
enum	ConnectionOptions { ConnectToFirstNodeAlways, ConnectToLastAccessedNode, ConnectToRandomNode }

Public Member Functions
	Client ()
void	clearDefaultSchema ()
std::vector< Node >	clusterNodes ()
bool	connect (const std::string &url)
bool	connect (const Node &node)
bool	connect (const std::vector< Node > &nodes, ConnectionOptions options=ConnectToLastAccessedNode)
RawResult	createBlobStorage (const std::string &tableName, int shards=-1, int replicas=-1, const std::string &path=std::string())
RawResult	createBlobStorage (const std::string &tableName, const std::string &path)
const std::string &	defaultSchema () const
BlobResult	deleteBlob (const std::string &tableName, const std::string &key)
void	disconnect ()
BlobResult	downloadBlob (const std::string &tableName, const std::string &key, std::ostream &data)
Result	exec (const std::string &sql)
Result	exec (const Query &query)
RawResult	execRaw (const std::string &sql)
RawResult	execRaw (const Query &query)
BlobResult	existsBlob (const std::string &tableName, const std::string &key)
bool	isConnected () const
	operator bool () const
bool	refresh (const std::string &table)
RawResult	removeBlobStorage (const std::string &tableName)
std::vector< std::string >	schemata ()
void	setDefaultSchema (const std::string &schema)
BlobResult	uploadBlob (const std::string &tableName, std::istream &data)

Detailed Description

The class Client provides the main interface for accessing to Crate.

To connect to a Crate cluster use connect(). Even tough connecting to a single node is enough CppCrate offers to define multiple nodes that can be used in case of node failure. The exact behavior of using this internal fall back mechanism see Client::ConnectionOptions.

Once connected use exec() or execRaw() to query Crate. While the latter version returns Crate's raw reply the former lets you conveniently access specific reply information. See RawResult and Result for more information. In order to avoid defining the used schema all over the place setDefaultSchema() can be used to minimize the typing effort.

Client c;
c.connect("http://localhost:4200");
if (c) {
  c.setDefaultSchema("my_schema");
  c.exec("SELECT * FROM my_table"); // expands to: SELECT * FROM my_schema.my_table
}

Beside custom queries CppCrate provides some predefined actions that are needed frequently when working with Crate: clusterNodes() for example returns all nodes of the cluster the client is connected to, or refresh() forces Crate to refresh its internal state.

Blob support

Client also provides an interface for accessing blob data. See createBlobStorage(), uploadBlob(), existsBlob(), downloadBlob(), deleteBlob(), and removeBlobStorage() for more information.

Member Enumeration Documentation

ConnectionOptions

enum CppCrate::Client::ConnectionOptions

Describes how the client handles node failures. CppCrate's fallback mechanism is only activated on network errors. Error reports issued by Crate are not considered.

Enumerator
ConnectToFirstNodeAlways	The client will always use the first node for queries. If a query fails the client will automatically retry to sent the query to the next node and so on.
ConnectToLastAccessedNode	The client use the node for queries, that was used successfully the last time. If the query fails the client will automatically retry to sent the query to the next node and so on.
ConnectToRandomNode	The client use a random node for new queries. If the query fails the client will automatically retry to sent the query to the next node and so on.

Constructor & Destructor Documentation

Client()

CppCrate::Client::Client

(

)

Constructs a not connected client.

Warning

Using any function - except connect() and disconnect() - of a not connected client is undefined behavior!

Member Function Documentation

clearDefaultSchema()

void CppCrate::Client::clearDefaultSchema

(

)

Resets the default schema.

clusterNodes()

std::vector< Node > CppCrate::Client::clusterNodes

(

)

Returns all Crate cluster nodes the client is currently connected to.

connect() [1/3]

bool CppCrate::Client::connect

(

const std::string &

url

)

Connects the client to the Crate cluster node identified by the URL url. This is equivalent to

connect(Node("<url>"));

connect() [2/3]

bool CppCrate::Client::connect

(

const Node &

node

)

Connects the client to the Crate cluster node node.

connect() [3/3]

bool CppCrate::Client::connect	(	const std::vector< Node > &	nodes,
		ConnectionOptions	options = ConnectToLastAccessedNode
	)

Connects the client to the Crate cluster using the provided Crate cluster nodes nodes. Which node is used is defined by options.

See also

Client::ConnectionOptions

createBlobStorage() [1/2]

RawResult CppCrate::Client::createBlobStorage	(	const std::string &	tableName,
		int	shards = -1,
		int	replicas = -1,
		const std::string &	path = std::string()
	)

Creates a new blob table named tableName. Additionally the number of shards and replications can be defined using shards and replicas. If shards or replicas is lesser than 0 it is ignored. If path is set, it is used for the new table's path.

The returned RawResult can be used to determine if the action was successful.

CppCrate::RawResult r = client.createBlobStorage("images");
if (r) {
  // success
}
// or simply
if (client.createBlobStorage("images")) {
  // success
}

Precondition

path must not contain single quotes (') - except they are properly escaped.

createBlobStorage() [2/2]

RawResult CppCrate::Client::createBlobStorage	(	const std::string &	tableName,
		const std::string &	path
	)

Creates a new blob table named tableName stored at path.

This is a convenient function for

createBlobStorage(tableName, -1, -1, path);

Precondition

path must not contain single quotes (') - except they are properly escaped.

defaultSchema()

const std::string & CppCrate::Client::defaultSchema

(

)

const

Returns the default schema.

deleteBlob()

BlobResult CppCrate::Client::deleteBlob	(	const std::string &	tableName,
		const std::string &	key
	)

Deletes the blob identified by key of the table tableName and returns the action's result.

disconnect()

void CppCrate::Client::disconnect

(

)

Disconnects the client from the Crate cluster.

Warning

Using any function - except connect() and disconnect() - of a not connected client is undefined behavior!

downloadBlob()

BlobResult CppCrate::Client::downloadBlob	(	const std::string &	tableName,
		const std::string &	key,
		std::ostream &	data
	)

Downloads the blob identified by key of the table tableName and stores it to data.

std::ofstream stream;
stream.open("/path/to/store/the/blob", std::ifstream::out | std::ifstream::binary);
if (stream) {
  CppCrate::BlobResult result = client.downloadBlob(
    "blobtable", "93390aa9ed64e1e96149ceb0262f34aa2aedcffc", stream);
  if (result) {
    std::cout << "Download succeeded!\n";
  }
}

Precondition

data must be writable and already opened in binary mode.

exec() [1/2]

Result CppCrate::Client::exec

(

const std::string &

sql

)

Executes the SQL statement sql and returns the result.

exec() [2/2]

Result CppCrate::Client::exec

(

const Query &

query

)

Executes the query query and returns the result.

execRaw() [1/2]

RawResult CppCrate::Client::execRaw

(

const std::string &

sql

)

Executes the SQL statement sql and returns the raw result.

execRaw() [2/2]

RawResult CppCrate::Client::execRaw

(

const Query &

query

)

Executes the query query and returns the raw result.

existsBlob()

BlobResult CppCrate::Client::existsBlob	(	const std::string &	tableName,
		const std::string &	key
	)

Returns whether a blob identified by key exists in the table tableName.

Note

Be careful interpreting BlobResult::hasError() of the returned result. It does not automatically mean that the blob does not exists. An error have might occurred because of network issues. Remember to call BlobResult::isCrateError()!

isConnected()

bool CppCrate::Client::isConnected

(

)

const

Returns whether the client is connected.

operator bool()

CppCrate::Client::operator bool ( ) const

explicit

Returns whether the client is connected.

refresh()

bool CppCrate::Client::refresh

(

const std::string &

table

)

Refreshes the table table and returns if the refresh was successful.

Note

See https://crate.io/docs/reference/sql/refresh.html#refresh-data for further information about Crate's eventually consistency.

removeBlobStorage()

RawResult CppCrate::Client::removeBlobStorage

(

const std::string &

tableName

)

Drops the blob table named tableName and returns the corresponding raw result that can be used to determine if the action was successful.

CppCrate::RawResult r = client.removeBlobStorage("images");
if (r) {
  // success
}
// or simply
if (client.removeBlobStorage("images")) {
  // success
}

schemata()

std::vector< std::string > CppCrate::Client::schemata

(

)

Returns all existing schemata.

setDefaultSchema()

void CppCrate::Client::setDefaultSchema

(

const std::string &

schema

)

Sets the default schema to schema. This allows SQL statements like

client.setDefaultSchema("my_schema");
client.exec("SELECT * FROM my_table");

instead of specifying the schema explicitly

client.exec("SELECT * FROM my_schema.my_table");

uploadBlob()

BlobResult CppCrate::Client::uploadBlob	(	const std::string &	tableName,
		std::istream &	data
	)

Uploads data to the table tableName. If the operation was successful the result can be used to receive the key of the inserted blob.

std::ifstream stream;
stream.open("/path/to/blob", std::ifstream::in | std::ifstream::binary);
if (stream) {
  CppCrate::BlobResult result = client.uploadBlob("blobtable", stream);
  if (result) {
    std::cout << "Key is " << result.key() << "\n";
  }
}

Precondition

data must be readable and already opened in binary mode.