Kudu C++ client API
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
client.h
1 // Licensed to the Apache Software Foundation (ASF) under one
2 // or more contributor license agreements. See the NOTICE file
3 // distributed with this work for additional information
4 // regarding copyright ownership. The ASF licenses this file
5 // to you under the Apache License, Version 2.0 (the
6 // "License"); you may not use this file except in compliance
7 // with the License. You may obtain a copy of the License at
8 //
9 // http://www.apache.org/licenses/LICENSE-2.0
10 //
11 // Unless required by applicable law or agreed to in writing,
12 // software distributed under the License is distributed on an
13 // "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
14 // KIND, either express or implied. See the License for the
15 // specific language governing permissions and limitations
16 // under the License.
17 
24 
25 #ifndef KUDU_CLIENT_CLIENT_H
26 #define KUDU_CLIENT_CLIENT_H
27 
28 #include <stdint.h>
29 #include <string>
30 #include <vector>
31 
32 #include "kudu/client/resource_metrics.h"
33 #include "kudu/client/row_result.h"
34 #include "kudu/client/scan_batch.h"
35 #include "kudu/client/scan_predicate.h"
36 #include "kudu/client/schema.h"
37 #include "kudu/client/shared_ptr.h"
38 #ifdef KUDU_HEADERS_NO_STUBS
39 #include <gtest/gtest_prod.h>
40 #include "kudu/gutil/macros.h"
41 #include "kudu/gutil/port.h"
42 #else
43 #include "kudu/client/stubs.h"
44 #endif
45 #include "kudu/client/write_op.h"
46 #include "kudu/util/kudu_export.h"
47 #include "kudu/util/monotime.h"
48 #include "kudu/util/status.h"
49 
50 #if _GLIBCXX_USE_CXX11_ABI
51 #error \
52  "Kudu will not function properly if built with gcc 5's new ABI. " \
53  "Please modify your application to set -D_GLIBCXX_USE_CXX11_ABI=0. " \
54  "For more information about the new ABI, see " \
55  "https://gcc.gnu.org/onlinedocs/libstdc++/manual/using_dual_abi.html."
56 #endif
57 
58 namespace kudu {
59 
60 class ClientStressTest_TestUniqueClientIds_Test;
61 class LinkedListTester;
62 class PartitionSchema;
63 
64 namespace client {
65 
66 class KuduLoggingCallback;
67 class KuduScanToken;
68 class KuduSession;
69 class KuduStatusCallback;
70 class KuduTable;
71 class KuduTableAlterer;
72 class KuduTableCreator;
73 class KuduTabletServer;
74 class KuduValue;
75 class KuduWriteOperation;
76 
77 namespace internal {
78 class Batcher;
79 class GetTableSchemaRpc;
80 class LookupRpc;
81 class MetaCache;
82 class RemoteTablet;
83 class RemoteTabletServer;
84 class WriteRpc;
85 } // namespace internal
86 
99 void KUDU_EXPORT InstallLoggingCallback(KuduLoggingCallback* cb);
100 
107 void KUDU_EXPORT UninstallLoggingCallback();
108 
124 void KUDU_EXPORT SetVerboseLogLevel(int level);
125 
135 Status KUDU_EXPORT SetInternalSignalNumber(int signum);
136 
139 std::string KUDU_EXPORT GetShortVersionString();
140 
143 std::string KUDU_EXPORT GetAllVersionInfo();
144 
149 class KUDU_EXPORT KuduClientBuilder {
150  public:
153 
157  KuduClientBuilder& clear_master_server_addrs();
158 
164  KuduClientBuilder& master_server_addrs(const std::vector<std::string>& addrs);
165 
173  KuduClientBuilder& add_master_server_addr(const std::string& addr);
174 
184  KuduClientBuilder& default_admin_operation_timeout(const MonoDelta& timeout);
185 
193  KuduClientBuilder& default_rpc_timeout(const MonoDelta& timeout);
194 
205  Status Build(sp::shared_ptr<KuduClient>* client);
206 
207  private:
208  class KUDU_NO_EXPORT Data;
209 
210  // Owned.
211  Data* data_;
212 
213  DISALLOW_COPY_AND_ASSIGN(KuduClientBuilder);
214 };
215 
242 class KUDU_EXPORT KuduClient : public sp::enable_shared_from_this<KuduClient> {
243  public:
244  ~KuduClient();
245 
250  KuduTableCreator* NewTableCreator();
251 
260  Status IsCreateTableInProgress(const std::string& table_name,
261  bool *create_in_progress);
262 
268  Status DeleteTable(const std::string& table_name);
269 
276  KuduTableAlterer* NewTableAlterer(const std::string& table_name);
277 
286  Status IsAlterTableInProgress(const std::string& table_name,
287  bool *alter_in_progress);
295  Status GetTableSchema(const std::string& table_name,
296  KuduSchema* schema);
297 
304  Status ListTabletServers(std::vector<KuduTabletServer*>* tablet_servers);
305 
313  Status ListTables(std::vector<std::string>* tables,
314  const std::string& filter = "");
315 
323  Status TableExists(const std::string& table_name, bool* exists);
324 
338  Status OpenTable(const std::string& table_name,
339  sp::shared_ptr<KuduTable>* table);
340 
346  sp::shared_ptr<KuduSession> NewSession();
347 
351 
352  CLOSEST_REPLICA,
353 
355  FIRST_REPLICA
356  };
357 
360  bool IsMultiMaster() const;
361 
363  const MonoDelta& default_admin_operation_timeout() const;
364 
366  const MonoDelta& default_rpc_timeout() const;
367 
370  static const uint64_t kNoTimestamp;
371 
379  uint64_t GetLatestObservedTimestamp() const;
380 
392  void SetLatestObservedTimestamp(uint64_t ht_timestamp);
393 
394  private:
395  class KUDU_NO_EXPORT Data;
396 
397  friend class internal::Batcher;
398  friend class internal::GetTableSchemaRpc;
399  friend class internal::LookupRpc;
400  friend class internal::MetaCache;
401  friend class internal::RemoteTablet;
402  friend class internal::RemoteTabletServer;
403  friend class internal::WriteRpc;
404  friend class ClientTest;
405  friend class KuduClientBuilder;
406  friend class KuduScanner;
407  friend class KuduScanTokenBuilder;
408  friend class KuduTable;
409  friend class KuduTableAlterer;
410  friend class KuduTableCreator;
411 
412  FRIEND_TEST(kudu::ClientStressTest, TestUniqueClientIds);
413  FRIEND_TEST(ClientTest, TestGetTabletServerBlacklist);
414  FRIEND_TEST(ClientTest, TestMasterDown);
415  FRIEND_TEST(ClientTest, TestMasterLookupPermits);
416  FRIEND_TEST(ClientTest, TestMetaCacheExpiry);
417  FRIEND_TEST(ClientTest, TestNonCoveringRangePartitions);
418  FRIEND_TEST(ClientTest, TestReplicatedTabletWritesWithLeaderElection);
419  FRIEND_TEST(ClientTest, TestScanFaultTolerance);
420  FRIEND_TEST(ClientTest, TestScanTimeout);
421  FRIEND_TEST(ClientTest, TestWriteWithDeadMaster);
422  FRIEND_TEST(MasterFailoverTest, TestPauseAfterCreateTableIssued);
423 
424  KuduClient();
425 
426  // Owned.
427  Data* data_;
428 
429  DISALLOW_COPY_AND_ASSIGN(KuduClient);
430 };
431 
433 class KUDU_EXPORT KuduTableCreator {
434  public:
435  ~KuduTableCreator();
436 
448  KuduTableCreator& table_name(const std::string& name);
449 
460  KuduTableCreator& schema(const KuduSchema* schema);
461 
478  KuduTableCreator& add_hash_partitions(const std::vector<std::string>& columns,
479  int32_t num_buckets);
480 
496  KuduTableCreator& add_hash_partitions(const std::vector<std::string>& columns,
497  int32_t num_buckets, int32_t seed);
498 
511  KuduTableCreator& set_range_partition_columns(const std::vector<std::string>& columns);
512 
517  };
518 
547  KuduTableCreator& add_range_partition(KuduPartialRow* lower_bound,
548  KuduPartialRow* upper_bound,
549  RangePartitionBound lower_bound_type = INCLUSIVE_BOUND,
550  RangePartitionBound upper_bound_type = EXCLUSIVE_BOUND);
551 
560  KuduTableCreator& add_range_partition_split(KuduPartialRow* split_row);
561 
567  KuduTableCreator& split_rows(const std::vector<const KuduPartialRow*>& split_rows);
568 
578  KuduTableCreator& num_replicas(int n_replicas);
579 
589  KuduTableCreator& timeout(const MonoDelta& timeout);
590 
598  KuduTableCreator& wait(bool wait);
599 
613  Status Create();
614 
615  private:
616  class KUDU_NO_EXPORT Data;
617 
618  friend class KuduClient;
619 
620  explicit KuduTableCreator(KuduClient* client);
621 
622  // Owned.
623  Data* data_;
624 
625  DISALLOW_COPY_AND_ASSIGN(KuduTableCreator);
626 };
627 
648 class KUDU_EXPORT KuduTable : public sp::enable_shared_from_this<KuduTable> {
649  public:
650  ~KuduTable();
651 
653  const std::string& name() const;
654 
662  const std::string& id() const;
663 
665  const KuduSchema& schema() const;
666 
670  KuduInsert* NewInsert();
671 
675  KuduUpsert* NewUpsert();
676 
680  KuduUpdate* NewUpdate();
681 
685  KuduDelete* NewDelete();
686 
710  KuduPredicate* NewComparisonPredicate(const Slice& col_name,
712  KuduValue* value);
713 
716  KuduClient* client() const;
717 
719  const PartitionSchema& partition_schema() const;
720 
721  private:
722  class KUDU_NO_EXPORT Data;
723 
724  friend class KuduClient;
725 
726  KuduTable(const sp::shared_ptr<KuduClient>& client,
727  const std::string& name,
728  const std::string& table_id,
729  const KuduSchema& schema,
730  const PartitionSchema& partition_schema);
731 
732  // Owned.
733  Data* data_;
734 
735  DISALLOW_COPY_AND_ASSIGN(KuduTable);
736 };
737 
749 class KUDU_EXPORT KuduTableAlterer {
750  public:
751  ~KuduTableAlterer();
752 
758  KuduTableAlterer* RenameTo(const std::string& new_name);
759 
769  KuduColumnSpec* AddColumn(const std::string& name);
770 
779  KuduColumnSpec* AlterColumn(const std::string& name);
780 
788  KuduTableAlterer* DropColumn(const std::string& name);
789 
821  KuduTableAlterer* AddRangePartition(
822  KuduPartialRow* lower_bound,
823  KuduPartialRow* upper_bound,
826 
854  KuduTableAlterer* DropRangePartition(
855  KuduPartialRow* lower_bound,
856  KuduPartialRow* upper_bound,
859 
869  KuduTableAlterer* timeout(const MonoDelta& timeout);
870 
882  KuduTableAlterer* wait(bool wait);
883 
888  Status Alter();
889 
890  private:
891  class KUDU_NO_EXPORT Data;
892  friend class KuduClient;
893 
895  const std::string& name);
896 
897  // Owned.
898  Data* data_;
899 
900  DISALLOW_COPY_AND_ASSIGN(KuduTableAlterer);
901 };
902 
908 class KUDU_EXPORT KuduError {
909  public:
910  ~KuduError();
911 
913  const Status& status() const;
914 
916  const KuduWriteOperation& failed_op() const;
917 
925  KuduWriteOperation* release_failed_op();
926 
937  bool was_possibly_successful() const;
938 
939  private:
940  class KUDU_NO_EXPORT Data;
941 
942  friend class internal::Batcher;
943  friend class KuduSession;
944 
945  KuduError(KuduWriteOperation* failed_op, const Status& error);
946 
947  // Owned.
948  Data* data_;
949 
950  DISALLOW_COPY_AND_ASSIGN(KuduError);
951 };
952 
953 
1012 class KUDU_EXPORT KuduSession : public sp::enable_shared_from_this<KuduSession> {
1013  public:
1014  ~KuduSession();
1015 
1017  enum FlushMode {
1023 
1043 
1047  MANUAL_FLUSH
1048  };
1049 
1058  Status SetFlushMode(FlushMode m) WARN_UNUSED_RESULT;
1059 
1081 
1096  COMMIT_WAIT
1097  };
1098 
1104  Status SetExternalConsistencyMode(ExternalConsistencyMode m)
1105  WARN_UNUSED_RESULT;
1106 
1122  Status SetMutationBufferSpace(size_t size_bytes) WARN_UNUSED_RESULT;
1123 
1128  void SetTimeoutMillis(int millis);
1129 
1133 
1152  Status Apply(KuduWriteOperation* write_op) WARN_UNUSED_RESULT;
1153 
1169  void ApplyAsync(KuduWriteOperation* write_op, KuduStatusCallback* cb);
1170 
1182  Status Flush() WARN_UNUSED_RESULT;
1183 
1221  void FlushAsync(KuduStatusCallback* cb);
1222 
1225  Status Close() WARN_UNUSED_RESULT;
1226 
1237  bool HasPendingOperations() const;
1238 
1252  int CountBufferedOperations() const;
1253 
1262  int CountPendingErrors() const;
1263 
1276  void GetPendingErrors(std::vector<KuduError*>* errors, bool* overflowed);
1277 
1279  KuduClient* client() const;
1280 
1281  private:
1282  class KUDU_NO_EXPORT Data;
1283 
1284  friend class KuduClient;
1285  friend class internal::Batcher;
1286  explicit KuduSession(const sp::shared_ptr<KuduClient>& client);
1287 
1288  // Owned.
1289  Data* data_;
1290 
1291  DISALLOW_COPY_AND_ASSIGN(KuduSession);
1292 };
1293 
1294 
1299 class KUDU_EXPORT KuduScanner {
1300  public:
1302  enum ReadMode {
1311 
1330  READ_AT_SNAPSHOT
1331  };
1332 
1336  enum OrderMode {
1343 
1348  ORDERED
1349  };
1350 
1354  enum { kScanTimeoutMillis = 30000 };
1355 
1361  explicit KuduScanner(KuduTable* table);
1362  ~KuduScanner();
1363 
1373  Status SetProjectedColumnNames(const std::vector<std::string>& col_names)
1374  WARN_UNUSED_RESULT;
1375 
1385  Status SetProjectedColumnIndexes(const std::vector<int>& col_indexes)
1386  WARN_UNUSED_RESULT;
1387 
1393  Status SetProjectedColumns(const std::vector<std::string>& col_names)
1394  WARN_UNUSED_RESULT;
1395 
1404  Status AddConjunctPredicate(KuduPredicate* pred) WARN_UNUSED_RESULT;
1405 
1414  Status AddLowerBound(const KuduPartialRow& key);
1415 
1423  Status AddLowerBoundRaw(const Slice& key);
1424 
1433  Status AddExclusiveUpperBound(const KuduPartialRow& key);
1434 
1442  Status AddExclusiveUpperBoundRaw(const Slice& key);
1443 
1452  Status AddLowerBoundPartitionKeyRaw(const Slice& partition_key);
1453 
1462  Status AddExclusiveUpperBoundPartitionKeyRaw(const Slice& partition_key);
1463 
1470  Status SetCacheBlocks(bool cache_blocks);
1471 
1473  Status Open();
1474 
1490  Status KeepAlive();
1491 
1500  void Close();
1501 
1510  bool HasMoreRows() const;
1511 
1523  Status NextBatch(std::vector<KuduRowResult>* rows);
1524 
1533  Status NextBatch(KuduScanBatch* batch);
1534 
1543  Status GetCurrentServer(KuduTabletServer** server);
1544 
1546  const ResourceMetrics& GetResourceMetrics() const;
1547 
1554  Status SetBatchSizeBytes(uint32_t batch_size);
1555 
1563  Status SetSelection(KuduClient::ReplicaSelection selection)
1564  WARN_UNUSED_RESULT;
1565 
1571  Status SetReadMode(ReadMode read_mode) WARN_UNUSED_RESULT;
1572 
1578  Status SetOrderMode(OrderMode order_mode) WARN_UNUSED_RESULT;
1579 
1592  Status SetFaultTolerant() WARN_UNUSED_RESULT;
1593 
1599  Status SetSnapshotMicros(uint64_t snapshot_timestamp_micros) WARN_UNUSED_RESULT;
1600 
1607  Status SetSnapshotRaw(uint64_t snapshot_timestamp) WARN_UNUSED_RESULT;
1608 
1614  Status SetTimeoutMillis(int millis);
1615 
1617  KuduSchema GetProjectionSchema() const;
1618 
1620  std::string ToString() const;
1621 
1622  private:
1623  class KUDU_NO_EXPORT Data;
1624 
1625  friend class KuduScanToken;
1626  FRIEND_TEST(ClientTest, TestScanCloseProxy);
1627  FRIEND_TEST(ClientTest, TestScanFaultTolerance);
1628  FRIEND_TEST(ClientTest, TestScanNoBlockCaching);
1629  FRIEND_TEST(ClientTest, TestScanTimeout);
1630 
1631  // Owned.
1632  Data* data_;
1633 
1634  DISALLOW_COPY_AND_ASSIGN(KuduScanner);
1635 };
1636 
1657 class KUDU_EXPORT KuduScanToken {
1658  public:
1659 
1660  ~KuduScanToken();
1661 
1672  Status IntoKuduScanner(KuduScanner** scanner) const WARN_UNUSED_RESULT;
1673 
1682  const std::vector<KuduTabletServer*>& TabletServers() const;
1683 
1691  Status Serialize(std::string* buf) const WARN_UNUSED_RESULT;
1692 
1704  static Status DeserializeIntoScanner(KuduClient* client,
1705  const std::string& serialized_token,
1706  KuduScanner** scanner) WARN_UNUSED_RESULT;
1707 
1708  private:
1709  class KUDU_NO_EXPORT Data;
1710 
1711  friend class KuduScanTokenBuilder;
1712 
1713  explicit KuduScanToken(Data* data);
1714 
1715  // Owned.
1716  Data* data_;
1717 
1718  DISALLOW_COPY_AND_ASSIGN(KuduScanToken);
1719 };
1720 
1724 class KUDU_EXPORT KuduScanTokenBuilder {
1725  public:
1726 
1732  explicit KuduScanTokenBuilder(KuduTable* table);
1734 
1744  Status SetProjectedColumnNames(const std::vector<std::string>& col_names)
1745  WARN_UNUSED_RESULT;
1746 
1748  Status SetProjectedColumnIndexes(const std::vector<int>& col_indexes)
1749  WARN_UNUSED_RESULT;
1750 
1752  Status AddConjunctPredicate(KuduPredicate* pred) WARN_UNUSED_RESULT;
1753 
1755  Status AddLowerBound(const KuduPartialRow& key) WARN_UNUSED_RESULT;
1756 
1765  Status AddUpperBound(const KuduPartialRow& key) WARN_UNUSED_RESULT;
1766 
1768  Status SetCacheBlocks(bool cache_blocks) WARN_UNUSED_RESULT;
1769 
1776  Status SetBatchSizeBytes(uint32_t batch_size) WARN_UNUSED_RESULT;
1777 
1785  Status SetSelection(KuduClient::ReplicaSelection selection)
1786  WARN_UNUSED_RESULT;
1787 
1789  Status SetReadMode(KuduScanner::ReadMode read_mode) WARN_UNUSED_RESULT;
1790 
1792  Status SetFaultTolerant() WARN_UNUSED_RESULT;
1793 
1795  Status SetSnapshotMicros(uint64_t snapshot_timestamp_micros)
1796  WARN_UNUSED_RESULT;
1797 
1799  Status SetSnapshotRaw(uint64_t snapshot_timestamp) WARN_UNUSED_RESULT;
1800 
1802  Status SetTimeoutMillis(int millis) WARN_UNUSED_RESULT;
1803 
1812  Status Build(std::vector<KuduScanToken*>* tokens) WARN_UNUSED_RESULT;
1813 
1815  std::string ToString() const;
1816 
1817  private:
1818  class KUDU_NO_EXPORT Data;
1819 
1820  // Owned.
1821  Data* data_;
1822 
1823  DISALLOW_COPY_AND_ASSIGN(KuduScanTokenBuilder);
1824 };
1825 
1827 class KUDU_EXPORT KuduTabletServer {
1828  public:
1829  ~KuduTabletServer();
1830 
1833  const std::string& uuid() const;
1834 
1837  const std::string& hostname() const;
1838 
1839  private:
1840  class KUDU_NO_EXPORT Data;
1841 
1842  friend class KuduClient;
1843  friend class KuduScanner;
1844  friend class KuduScanTokenBuilder;
1845 
1846  KuduTabletServer();
1847 
1848  // Owned.
1849  Data* data_;
1850 
1851  DISALLOW_COPY_AND_ASSIGN(KuduTabletServer);
1852 };
1853 
1854 } // namespace client
1855 } // namespace kudu
1856 #endif
A single row update to be sent to the cluster.
Definition: write_op.h:175
A representation of a table's schema.
Definition: schema.h:409
A representation of an operation's outcome.
Definition: status.h:106
A constant cell value with a specific type.
Definition: value.h:33
ExternalConsistencyMode
The possible external consistency modes on which Kudu operates.
Definition: client.h:1061
A single row insert to be sent to the cluster.
Definition: write_op.h:123
Builder API for specifying or altering a column within a table schema.
Definition: schema.h:222
static const uint64_t kNoTimestamp
Definition: client.h:370
ReplicaSelection
Policy with which to choose amongst multiple replicas.
Definition: client.h:349
A single row upsert to be sent to the cluster.
Definition: write_op.h:148
Builds scan tokens for a table.
Definition: client.h:1724
ComparisonOp
Supported comparison operators.
Definition: scan_predicate.h:39
Alters an existing table based on the provided steps.
Definition: client.h:749
OrderMode
Definition: client.h:1336
Definition: client.h:1342
A representation of comparison predicate for Kudu queries.
Definition: scan_predicate.h:36
An exclusive bound.
Definition: client.h:515
This class represents an error which occurred in a write operation.
Definition: client.h:908
A handle for a connection to a cluster.
Definition: client.h:242
An inclusive bound.
Definition: client.h:516
In-memory representation of a remote tablet server.
Definition: client.h:1827
The interface for all status callbacks.
Definition: callbacks.h:161
A wrapper around externally allocated data.
Definition: slice.h:43
A representation of a table on a particular cluster.
Definition: client.h:648
This class is a representation of a single scan.
Definition: client.h:1299
ReadMode
The read modes for scanners.
Definition: client.h:1302
A "factory" for KuduClient objects.
Definition: client.h:149
A single-row write operation to be sent to a Kudu table.
Definition: write_op.h:55
Select the LEADER replica.
Definition: client.h:350
RangePartitionBound
Range partition bound type.
Definition: client.h:514
FlushMode
Modes of flush operations.
Definition: client.h:1017
A single row delete to be sent to the cluster.
Definition: write_op.h:202
A helper class to create a new table with the desired options.
Definition: client.h:433
Representation of a Kudu client session.
Definition: client.h:1012
A row which may only contain values for a subset of the columns.
Definition: partial_row.h:53
A representation of a time interval.
Definition: monotime.h:43