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

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
 

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:

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, 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_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.

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_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: