kudu::client::KuduClient Class Reference

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

#include <client.h>

Inherits std::tr1::enable_shared_from_this< KuduClient >.

Public Types
enum	ReplicaSelection { LEADER_ONLY, CLOSEST_REPLICA, FIRST_REPLICA }
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	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

kudu::client::KuduClient Class Reference

Public Types

Public Member Functions

Static Public Attributes

Friends

Detailed Description

Member Enumeration Documentation

Member Function Documentation

Member Data Documentation