- -

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

- -

#include <client.h>

-

-Inheritance 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	ConnectToClusterBaseTest

-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

-

add_master_server_addr(const std::string &addr)	kudu::client::KuduClientBuilder
Build(sp::shared_ptr< KuduClient > *client)	kudu::client::KuduClientBuilder
clear_master_server_addrs()	kudu::client::KuduClientBuilder
default_admin_operation_timeout(const MonoDelta &timeout)	kudu::client::KuduClientBuilder
default_rpc_timeout(const MonoDelta &timeout)	kudu::client::KuduClientBuilder
import_authentication_credentials(std::string authn_creds)	kudu::client::KuduClientBuilder
internal::ReplicaController (defined in kudu::client::KuduClientBuilder)	kudu::client::KuduClientBuilder	friend
KuduClientBuilder() (defined in kudu::client::KuduClientBuilder)	kudu::client::KuduClientBuilder
master_server_addrs(const std::vector< std::string > &addrs)	kudu::client::KuduClientBuilder
~KuduClientBuilder() (defined in kudu::client::KuduClientBuilder)	kudu::client::KuduClientBuilder

-Public Member Functions
KuduClientBuilder &	clear_master_server_addrs ()

KuduClientBuilder &	master_server_addrs (const std::vector< std::string > &addrs)

KuduClientBuilder &	add_master_server_addr (const std::string &addr)

KuduClientBuilder &	default_admin_operation_timeout (const MonoDelta &timeout)

KuduClientBuilder &	default_rpc_timeout (const MonoDelta &timeout)

KuduClientBuilder &	import_authentication_credentials (std::string authn_creds)

Status	Build (sp::shared_ptr< KuduClient > *client)

-Public Types

-Public Member Functions

-Static Public Attributes

-Friends

Detailed Description

Member Enumeration Documentation

Member Function Documentation

Member Data Documentation

-Public Member Functions

-Friends

Detailed Description

Member Function Documentation