Kudu C++ client API
 All Classes Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
Public Types | Public Member Functions | Static Public Attributes | 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

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

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

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

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_nameName 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_credsThe 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.

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.
Status kudu::client::KuduClient::GetTableSchema ( const std::string &  table_name,
KuduSchema schema 
)

Get table's schema.

Parameters
[in]table_nameName of the table.
[out]schemaRaw 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_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.
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_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.
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]tablesThe placeholder for the result. Appended only on success.
[in]filterSubstring 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_serversThe 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_nameName 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_nameName of the table.
[out]tableThe 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_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.

Parameters
[in]table_nameName of the table.
[out]existsSet 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: