A handle for a connection to a cluster. More...

#include <client.h>

Inheritance diagram for kudu::client::KuduClient:

Collaboration diagram for kudu::client::KuduClient:

Public Types
enum	ReplicaSelection { LEADER_ONLY, CLOSEST_REPLICA, FIRST_REPLICA }
	Policy with which to choose amongst multiple replicas. More...

Public Member Functions
KuduTableCreator *	NewTableCreator ()

Status	IsCreateTableInProgress (const std::string &table_name, bool *create_in_progress)

Status	DeleteTable (const std::string &table_name)

KuduTableAlterer *	NewTableAlterer (const std::string &table_name)

Status	IsAlterTableInProgress (const std::string &table_name, bool *alter_in_progress)

Status	GetTableSchema (const std::string &table_name, KuduSchema *schema)

Status	ListTabletServers (std::vector< KuduTabletServer * > *tablet_servers)

Status	ListTables (std::vector< std::string > *tables, const std::string &filter="")

Status	TableExists (const std::string &table_name, bool *exists)

Status	OpenTable (const std::string &table_name, sp::shared_ptr< KuduTable > *table)

sp::shared_ptr< KuduSession >	NewSession ()

bool	IsMultiMaster () const

const MonoDelta &	default_admin_operation_timeout () const

const MonoDelta &	default_rpc_timeout () const

uint64_t	GetLatestObservedTimestamp () const

void	SetLatestObservedTimestamp (uint64_t ht_timestamp)

Status	ExportAuthenticationCredentials (std::string *authn_creds) const

Static Public Attributes
static const uint64_t	kNoTimestamp

Friends
class	internal::Batcher

class	internal::GetTableSchemaRpc

class	internal::LookupRpc

class	internal::MetaCache

class	internal::RemoteTablet

class	internal::RemoteTabletServer

class	internal::WriteRpc

class	ClientTest

class	KuduClientBuilder

class	KuduPartitionerBuilder

class	KuduScanner

class	KuduScanToken

class	KuduScanTokenBuilder

class	KuduSession

class	KuduTable

class	KuduTableAlterer

class	KuduTableCreator

class	::kudu::SecurityUnknownTskTest

class	tools::LeaderMasterProxy

Detailed Description

A handle for a connection to a cluster.

The KuduClient class represents a connection to a cluster. From the user perspective, they should only need to create one of these in their application, likely a singleton – but it is not a singleton in Kudu in any way. Different KuduClient objects do not interact with each other – no connection pooling, etc. With the exception of common properties managed by free (non-member) functions in the kudu::client namespace, each KuduClient object is sandboxed with no global cross-client state.

In the implementation, the client holds various pieces of common infrastructure which is not table-specific:

RPC messenger: reactor threads and RPC connections are pooled here
Authentication: the client is initialized with some credentials, and all accesses through it share those credentials.
Caches: caches of table schemas, tablet locations, tablet server IP addresses, etc are shared per-client.

In order to actually write data to the cluster, callers must first create a KuduSession object using NewSession(). A KuduClient may have several associated sessions.

Note: This class is thread-safe.

Todo:: Cluster administration functions are likely to be in this class as well.

Member Enumeration Documentation

enum kudu::client::KuduClient::ReplicaSelection

Policy with which to choose amongst multiple replicas.

Enumerator
LEADER_ONLY	Select the LEADER replica.
CLOSEST_REPLICA	Select the closest replica to the client, or a random one if all replicas are equidistant.
FIRST_REPLICA	Select the first replica in the list.

Member Function Documentation

const MonoDelta& kudu::client::KuduClient::default_admin_operation_timeout ( ) const

Returns: Default timeout for admin operations.

const MonoDelta& kudu::client::KuduClient::default_rpc_timeout ( ) const

Returns: Default timeout for RPCs.

Status kudu::client::KuduClient::DeleteTable ( const std::string & table_name )

Delete/drop a table.

Parameters

[in] table_name Name of the table to drop.

Returns: Operation status.

Status kudu::client::KuduClient::ExportAuthenticationCredentials ( std::string * authn_creds ) const

Export the current authentication credentials from this client. This includes the necessary credentials to authenticate to the cluster, as well as to authenticate the cluster to the client.

The resulting binary string may be passed into a new C++ client via the KuduClientBuilder::import_authentication_credentials method, or into a new Java client via KuduClient::importAuthenticationCredentials.

Parameters

[out] authn_creds The resulting binary authentication credentials.

Returns: Status object for the operation.

uint64_t kudu::client::KuduClient::GetLatestObservedTimestamp ( ) const

Get the highest HybridTime timestamp observed by the client.

The latest observed timestamp can be used to start a snapshot scan on a table which is guaranteed to contain all data written or previously read by this client. See KuduScanner for more details on timestamps.

How to get Read-Your-Writes consistency: the code snippet below uses KuduClient::GetLatestObservedTimestamp() along with KuduScanner::SetSnapshotRaw() to perform READ_AT_SNAPSHOT scan containing the data which has just been written. Notice extra 1 added to the timestamp passed to KuduScanner::SetSnapshotRaw():

shared_ptr<KuduClient> client;
... // open/initialize the client
shared_ptr<KuduSession> session(client->NewSession());
... // set Kudu session properties
shared_ptr<KuduTable> table;
... // open the table
unique_ptr<KuduInsert> insert_op(table->NewInsert());
... // populate new insert operation with data
RETURN_NOT_OK(session->Apply(insert_op.release()));
RETURN_NOT_OK(session->Flush());
uint64_t snapshot_timestamp = client->GetLatestObservedTimestamp() + 1;
KuduScanner scanner(table.get());
RETURN_NOT_OK(scanner.SetSnapshotRaw(snapshot_timestamp));
RETURN_NOT_OK(scanner.SetSelection(KuduClient::LEADER_ONLY));
RETURN_NOT_OK(scanner.SetReadMode(KuduScanner::READ_AT_SNAPSHOT));
RETURN_NOT_OK(scanner.Open());
... // retrieve scanned rows

There are currently races in which, in rare occasions, Read-Your-Writes consistency might not hold even in this case. These are being taken care of as part of KUDU-430

Note: This method is experimental and will either disappear or change in a future release.

Returns: Highest HybridTime timestamp observed by the client.

Status kudu::client::KuduClient::GetTableSchema	(	const std::string &	table_name,
		KuduSchema *	schema
	)

Get table's schema.

Parameters

[in]	table_name	Name of the table.
[out]	schema	Raw pointer to the schema object; caller gets ownership.

Returns: Operation status.

Status kudu::client::KuduClient::IsAlterTableInProgress	(	const std::string &	table_name,
		bool *	alter_in_progress
	)

Check if table alteration is in-progress.

Parameters

[in]	table_name	Name of the table.
[out]	alter_in_progress	The value is set only in case of success; it is `true` iff the operation is in progress.

Returns: Operation status.

Status kudu::client::KuduClient::IsCreateTableInProgress	(	const std::string &	table_name,
		bool *	create_in_progress
	)

Check whether a create table operation is in-progress.

Parameters

[in]	table_name	Name of the table.
[out]	create_in_progress	The value is set only in case of success; it is `true` iff the operation is in progress.

Returns: Operation status.

bool kudu::client::KuduClient::IsMultiMaster ( ) const

Returns: true iff client is configured to talk to multiple Kudu master servers.

Status kudu::client::KuduClient::ListTables	(	std::vector< std::string > *	tables,
		const std::string &	filter = `""`
	)

List only those tables whose names pass a substring match on filter.

Parameters

[out]	tables	The placeholder for the result. Appended only on success.
[in]	filter	Substring filter to use; empty sub-string filter matches all tables.

Returns: Status object for the operation.

Status kudu::client::KuduClient::ListTabletServers ( std::vector< KuduTabletServer * > * tablet_servers )

Get information on current tablet servers.

Parameters

[out] tablet_servers The placeholder for the result. The caller takes ownership of the container's elements.

Returns: Operation status.

sp::shared_ptr<KuduSession> kudu::client::KuduClient::NewSession ( )

Create a new session for interacting with the cluster.

This is a fully local operation (no RPCs or blocking).

Returns: A new session object; caller is responsible for destroying it.

KuduTableAlterer* kudu::client::KuduClient::NewTableAlterer ( const std::string & table_name )

Create a KuduTableAlterer object.

Parameters

[in] table_name Name of the table to alter.

Returns: Pointer to newly created object: it is the caller's responsibility to free it.

KuduTableCreator* kudu::client::KuduClient::NewTableCreator ( )

Create a KuduTableCreator object.

Returns: Pointer to newly created object; it is the caller's responsibility to free it.

Status kudu::client::KuduClient::OpenTable	(	const std::string &	table_name,
		sp::shared_ptr< KuduTable > *	table
	)

Open table with the given name.

This method does an RPC to ensure that the table exists and looks up its schema.

Note: New range partitions created by other clients will immediately be available after opening the table.

Parameters

[in]	table_name	Name of the table.
[out]	table	The result table.

Returns: Operation status.

Todo:

Should we offer an async version of this as well?

Probably should have a configurable timeout in KuduClientBuilder?

void kudu::client::KuduClient::SetLatestObservedTimestamp ( uint64_t ht_timestamp )

Sets the latest observed HybridTime timestamp.

This is only useful when forwarding timestamps between clients to enforce external consistency when using KuduSession::CLIENT_PROPAGATED external consistency mode.

The HybridTime encoded timestamp should be obtained from another client's KuduClient::GetLatestObservedTimestamp() method.

Note: This method is experimental and will either disappear or change in a future release.

Parameters

[in] ht_timestamp Timestamp encoded in HybridTime format.

Status kudu::client::KuduClient::TableExists	(	const std::string &	table_name,
		bool *	exists
	)

Check if the table given by 'table_name' exists.

Parameters

[in]	table_name	Name of the table.
[out]	exists	Set only on success; set to `true` iff table exists.

Returns: Status object for the operation.

Member Data Documentation

const uint64_t kudu::client::KuduClient::kNoTimestamp

static

Value for the latest observed timestamp when none has been observed or set.

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

include/kudu/client/client.h

Public Types

Public Member Functions

Static Public Attributes

Friends

Detailed Description

Member Enumeration Documentation

Member Function Documentation

Member Data Documentation