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)

Status	SoftDeleteTable (const std::string &table_name, uint32_t reserve_seconds=0)

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	ListSoftDeletedTables (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 ()

Status	NewTransaction (sp::shared_ptr< KuduTransaction > *txn) WARN_UNUSED_RESULT

bool	IsMultiMaster () const

const MonoDelta &	default_admin_operation_timeout () const

const MonoDelta &	default_rpc_timeout () const

MonoDelta	connection_negotiation_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

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

◆ ReplicaSelection

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. Local replicas are considered the closest, followed by replicas in the same location as the client, followed by all other replicas. If there are multiple closest replicas, one is chosen randomly.
FIRST_REPLICA	Select the first replica in the list.

Member Function Documentation

◆ connection_negotiation_timeout()

MonoDelta kudu::client::KuduClient::connection_negotiation_timeout ( ) const

Returns: Timeout for connection negotiation to a remote server.

◆ default_admin_operation_timeout()

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

Returns: Default timeout for admin operations.

◆ default_rpc_timeout()

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

Returns: Default timeout for RPCs.

◆ DeleteTable()

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

Delete/drop a table without reserving. The deleted table may turn to soft-deleted status with the flag –default_deleted_table_reserve_seconds set to nonzero on the master side.

The delete operation or drop operation means that the service will directly delete the table after receiving the instruction. Which means that once we delete the table by mistake, we have no way to recall the deleted data. We have added a new SoftDeleteTable API to allow the deleted data to be reserved for a period of time, which means that the wrongly deleted data may be recalled. In order to be compatible with the previous versions, this interface will continue to directly delete tables without reserving the table.

Refer to SoftDeleteTable for detailed usage examples.

Parameters

[in] table_name Name of the table to drop.

Returns: Operation status.

◆ ExportAuthenticationCredentials()

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.

◆ GetLatestObservedTimestamp()

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

Get the highest HybridTime timestamp observed by the client.

This is useful when retrieving timestamp from one client and forwarding it to another to enforce external consistency when using KuduSession::CLIENT_PROPAGATED external consistency mode.

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

Returns: Highest HybridTime timestamp observed by the client.

◆ GetTableSchema()

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.

◆ IsAlterTableInProgress()

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.

◆ IsCreateTableInProgress()

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.

◆ IsMultiMaster()

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

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

◆ ListSoftDeletedTables()

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

List soft-deleted tables only those names pass a substring with names matching the specified 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.

◆ ListTables()

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

List non-soft-deleted 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.

◆ ListTabletServers()

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.

◆ NewSession()

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.

◆ NewTableAlterer()

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.

◆ NewTableCreator()

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

Create a KuduTableCreator object.

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

◆ NewTransaction()

Status kudu::client::KuduClient::NewTransaction ( sp::shared_ptr< KuduTransaction > * txn )

Start a multi-row transaction.

This method results in an RPC sent to a Kudu cluster to begin a multi-row distributed transaction. In case of success, the resulting transaction handle is output into the 'txn' parameter. That handle can be used to create a new KuduSession using the NewSession(const sp::shared_ptr<KuduSession>&) method. To commit or rollback all single-row write operations performed in the context of the newly created transaction, use KuduTransaction::Commit() and KuduTransaction::Rollback() methods correspondingly.

Note: The newly created object starts sending keep-alive messages for the newly opened transaction as required by the keep-alive interval assigned to the transaction by the system. To keep the heartbeating, the newly created KuduTransaction should be kept in scope.

Warning: This method is experimental and may change or disappear in future.

Parameters

txn	[out] The resulting `KuduTransaction` object wrapped into a smart pointer. This 'out' parameter is populated iff the operation to begin a transaction was successful.

Returns: The status of underlying "begin transaction" operation.

◆ OpenTable()

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?

◆ SetLatestObservedTimestamp()

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.

◆ SoftDeleteTable()

Status kudu::client::KuduClient::SoftDeleteTable	(	const std::string &	table_name,
		uint32_t	reserve_seconds = `0`
	)

Soft delete/drop a table.

Usage Example1: Equal to DeleteTable(table_name) and the table will not be reserved.

client->SoftDeleteTable(table_name);

Usage Example2: The table will be reserved for 600s after delete operation. We can recall the table in time after the delete.

client->SoftDeleteTable(table_name, false, 600);

client->RecallTable(table_id);

Parameters

[in]	table_name	Name of the table to drop.
[in]	reserve_seconds	Reserve seconds after being deleted.

Returns: Operation status.

◆ TableExists()

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

◆ kNoTimestamp

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

Detailed Description

Member Enumeration Documentation

◆ ReplicaSelection

Member Function Documentation

◆ connection_negotiation_timeout()

◆ default_admin_operation_timeout()

◆ default_rpc_timeout()

◆ DeleteTable()

◆ ExportAuthenticationCredentials()

◆ GetLatestObservedTimestamp()

◆ GetTableSchema()

◆ IsAlterTableInProgress()

◆ IsCreateTableInProgress()

◆ IsMultiMaster()

◆ ListSoftDeletedTables()

◆ ListTables()

◆ ListTabletServers()

◆ NewSession()

◆ NewTableAlterer()

◆ NewTableCreator()

◆ NewTransaction()

◆ OpenTable()

◆ SetLatestObservedTimestamp()

◆ SoftDeleteTable()

◆ TableExists()

Member Data Documentation

◆ kNoTimestamp