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)

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	KuduScanner

class	KuduScanToken

class	KuduScanTokenBuilder

class	KuduSession

class	KuduTable

class	KuduTableAlterer

class	KuduTableCreator

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.

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.

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