Kudu C++ client API
 All Classes Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
Public Types | Public Member Functions | Static Public Attributes | Friends | List of all members
kudu::client::KuduClient Class Reference

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

#include <client.h>

Inheritance diagram for kudu::client::KuduClient:

Public Types

 Policy with which to choose amongst multiple replicas. More...

Public Member Functions

KuduTableCreatorNewTableCreator ()
Status IsCreateTableInProgress (const std::string &table_name, bool *create_in_progress)
Status DeleteTable (const std::string &table_name)
KuduTableAltererNewTableAlterer (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< KuduSessionNewSession ()
bool IsMultiMaster () const
const MonoDeltadefault_admin_operation_timeout () const
const MonoDeltadefault_rpc_timeout () const
uint64_t GetLatestObservedTimestamp () const
void SetLatestObservedTimestamp (uint64_t ht_timestamp)

Static Public Attributes

static const uint64_t kNoTimestamp


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:

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.

This class is thread-safe.
Cluster administration functions are likely to be in this class as well.

Member Enumeration Documentation

Policy with which to choose amongst multiple replicas.


Select the LEADER replica.


Select the closest replica to the client, or a random one if all replicas are equidistant.


Select the first replica in the list.

Member Function Documentation

const MonoDelta& kudu::client::KuduClient::default_admin_operation_timeout ( ) const
Default timeout for admin operations.
const MonoDelta& kudu::client::KuduClient::default_rpc_timeout ( ) const
Default timeout for RPCs.
Status kudu::client::KuduClient::DeleteTable ( const std::string &  table_name)

Delete/drop a table.

[in]table_nameName of the table to drop.
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
uint64_t snapshot_timestamp = client->GetLatestObservedTimestamp() + 1;
KuduScanner scanner(table.get());
... // 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

This method is experimental and will either disappear or change in a future release.
Highest HybridTime timestamp observed by the client.
Status kudu::client::KuduClient::GetTableSchema ( const std::string &  table_name,
KuduSchema schema 

Get table's schema.

[in]table_nameName of the table.
[out]schemaRaw pointer to the schema object; caller gets ownership.
Operation status.
Status kudu::client::KuduClient::IsAlterTableInProgress ( const std::string &  table_name,
bool *  alter_in_progress 

Check if table alteration is in-progress.

[in]table_nameName of the table.
[out]alter_in_progressThe value is set only in case of success; it is true iff the operation is in progress.
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.

[in]table_nameName of the table.
[out]create_in_progressThe value is set only in case of success; it is true iff the operation is in progress.
Operation status.
bool kudu::client::KuduClient::IsMultiMaster ( ) const
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.

[out]tablesThe placeholder for the result. Appended only on success.
[in]filterSubstring filter to use; empty sub-string filter matches all tables.
Status object for the operation.
Status kudu::client::KuduClient::ListTabletServers ( std::vector< KuduTabletServer * > *  tablet_servers)

Get information on current tablet servers.

[out]tablet_serversThe placeholder for the result. The caller takes ownership of the container's elements.
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).

A new session object; caller is responsible for destroying it.
KuduTableAlterer* kudu::client::KuduClient::NewTableAlterer ( const std::string &  table_name)

Create a KuduTableAlterer object.

[in]table_nameName of the table to alter.
Pointer to newly created object: it is the caller's responsibility to free it.
KuduTableCreator* kudu::client::KuduClient::NewTableCreator ( )

Create a KuduTableCreator object.

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.

[in]table_nameName of the table.
[out]tableThe result table.
Operation status.

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.

This method is experimental and will either disappear or change in a future release.
[in]ht_timestampTimestamp 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.

[in]table_nameName of the table.
[out]existsSet only on success; set to true iff table exists.
Status object for the operation.

Member Data Documentation

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

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

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