Google Cloud Bigtable C++ Client  1.35.0
A C++ Client Library for Google Cloud Bigtable
table_admin.h
Go to the documentation of this file.
1 // Copyright 2017 Google Inc.
2 //
3 // Licensed under the Apache License, Version 2.0 (the "License");
4 // you may not use this file except in compliance with the License.
5 // You may obtain a copy of the License at
6 //
7 // https://www.apache.org/licenses/LICENSE-2.0
8 //
9 // Unless required by applicable law or agreed to in writing, software
10 // distributed under the License is distributed on an "AS IS" BASIS,
11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 // See the License for the specific language governing permissions and
13 // limitations under the License.
14 
15 #ifndef GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_BIGTABLE_TABLE_ADMIN_H
16 #define GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_BIGTABLE_TABLE_ADMIN_H
17 
18 #include "google/cloud/bigtable/admin_client.h"
19 #include "google/cloud/bigtable/column_family.h"
20 #include "google/cloud/bigtable/completion_queue.h"
21 #include "google/cloud/bigtable/iam_policy.h"
22 #include "google/cloud/bigtable/metadata_update_policy.h"
23 #include "google/cloud/bigtable/polling_policy.h"
24 #include "google/cloud/bigtable/resource_names.h"
25 #include "google/cloud/bigtable/table_config.h"
26 #include "google/cloud/bigtable/version.h"
27 #include "google/cloud/future.h"
28 #include "google/cloud/grpc_error_delegate.h"
29 #include "google/cloud/iam_policy.h"
30 #include "google/cloud/internal/attributes.h"
31 #include "google/cloud/status_or.h"
32 #include "absl/types/optional.h"
33 #include <chrono>
34 #include <future>
35 #include <memory>
36 #include <string>
37 #include <vector>
38 
39 namespace google {
40 namespace cloud {
41 namespace bigtable {
43 /// The result of checking replication against a given token.
44 enum class Consistency {
45  /// Some of the mutations created before the consistency token have not been
46  /// received by all the table replicas.
48  /// All mutations created before the consistency token have been received by
49  /// all the table replicas.
51 };
52 
53 /**
54  * Implements the API to administer tables in a Cloud Bigtable instance.
55  *
56  * @par Thread-safety
57  * Instances of this class created via copy-construction or copy-assignment
58  * share the underlying pool of connections. Access to these copies via multiple
59  * threads is guaranteed to work. Two threads operating concurrently on the same
60  * instance of this class is not guaranteed to work.
61  *
62  * @par Cost
63  * Creating a new object of type `TableAdmin` is comparable to creating a few
64  * objects of type `std::string` or a few objects of type
65  * `std::shared_ptr<int>`. The class represents a shallow handle to a remote
66  * object.
67  *
68  * @par Error Handling
69  * This class uses `StatusOr<T>` to report errors. When an operation fails to
70  * perform its work the returned `StatusOr<T>` contains the error details. If
71  * the `ok()` member function in the `StatusOr<T>` returns `true` then it
72  * contains the expected result. Operations that do not return a value simply
73  * return a `google::cloud::Status` indicating success or the details of the
74  * error Please consult the [`StatusOr<T>`
75  * documentation](#google::cloud::StatusOr) for more details.
76  *
77  * @code
78  * namespace cbt = google::cloud::bigtable;
79  * namespace btadmin = google::bigtable::admin::v2;
80  * cbt::TableAdmin admin = ...;
81  * google::cloud::StatusOr<btadmin::Table> metadata = admin.GetTable(...);
82  *
83  * if (!metadata) {
84  * std::cerr << "Error fetching table metadata\n";
85  * return;
86  * }
87  *
88  * // Use "metadata" as a smart pointer here, e.g.:
89  * std::cout << "The full table name is " << table->name() << " the table has "
90  * << table->column_families_size() << " column families\n";
91  * @endcode
92  *
93  * In addition, the @ref index "main page" contains examples using `StatusOr<T>`
94  * to handle errors.
95  *
96  * @par Retry, Backoff, and Idempotency Policies
97  * The library automatically retries requests that fail with transient errors,
98  * and uses [truncated exponential backoff][backoff-link] to backoff between
99  * retries. The default policies are to continue retrying for up to 10 minutes.
100  * On each transient failure the backoff period is doubled, starting with an
101  * initial backoff of 100 milliseconds. The backoff period growth is truncated
102  * at 60 seconds. The default idempotency policy is to only retry idempotent
103  * operations. Note that most operations that change state are **not**
104  * idempotent.
105  *
106  * The application can override these policies when constructing objects of this
107  * class. The documentation for the constructors show examples of this in
108  * action.
109  *
110  * [backoff-link]: https://cloud.google.com/storage/docs/exponential-backoff
111  *
112  * @see https://cloud.google.com/bigtable/ for an overview of Cloud Bigtable.
113  *
114  * @see https://cloud.google.com/bigtable/docs/overview for an overview of the
115  * Cloud Bigtable data model.
116  *
117  * @see https://cloud.google.com/bigtable/docs/instances-clusters-nodes for an
118  * introduction of the main APIs into Cloud Bigtable.
119  *
120  * @see https://cloud.google.com/bigtable/docs/reference/service-apis-overview
121  * for an overview of the underlying Cloud Bigtable API.
122  *
123  * @see #google::cloud::StatusOr for a description of the error reporting class
124  * used by this library.
125  *
126  * @see `LimitedTimeRetryPolicy` and `LimitedErrorCountRetryPolicy` for
127  * alternative retry policies.
128  *
129  * @see `ExponentialBackoffPolicy` to configure different parameters for the
130  * exponential backoff policy.
131  *
132  * @see `SafeIdempotentMutationPolicy` and `AlwaysRetryMutationPolicy` for
133  * alternative idempotency policies.
134  */
135 class TableAdmin {
136  public:
137  /**
138  * @param client the interface to create grpc stubs, report errors, etc.
139  * @param instance_id the id of the instance, e.g., "my-instance", the full
140  * name (e.g. '/projects/my-project/instances/my-instance') is built using
141  * the project id in the @p client parameter.
142  */
143  TableAdmin(std::shared_ptr<AdminClient> client, std::string instance_id)
144  : client_(std::move(client)),
145  instance_id_(std::move(instance_id)),
146  instance_name_(InstanceName()),
147  rpc_retry_policy_prototype_(
148  DefaultRPCRetryPolicy(internal::kBigtableTableAdminLimits)),
149  rpc_backoff_policy_prototype_(
150  DefaultRPCBackoffPolicy(internal::kBigtableTableAdminLimits)),
151  metadata_update_policy_(instance_name(), MetadataParamTypes::PARENT),
152  polling_policy_prototype_(
153  DefaultPollingPolicy(internal::kBigtableTableAdminLimits)),
154  background_threads_(client_->BackgroundThreadsFactory()()) {}
155 
156  /**
157  * Create a new TableAdmin using explicit policies to handle RPC errors.
158  *
159  * @param client the interface to create grpc stubs, report errors, etc.
160  * @param instance_id the id of the instance, e.g., "my-instance", the full
161  * name (e.g. '/projects/my-project/instances/my-instance') is built using
162  * the project id in the @p client parameter.
163  * @param policies the set of policy overrides for this object.
164  * @tparam Policies the types of the policies to override, the types must
165  * derive from one of the following types:
166  * - `RPCBackoffPolicy` how to backoff from a failed RPC. Currently only
167  * `ExponentialBackoffPolicy` is implemented. You can also create your
168  * own policies that backoff using a different algorithm.
169  * - `RPCRetryPolicy` for how long to retry failed RPCs. Use
170  * `LimitedErrorCountRetryPolicy` to limit the number of failures
171  * allowed. Use `LimitedTimeRetryPolicy` to bound the time for any
172  * request. You can also create your own policies that combine time and
173  * error counts.
174  * - `PollingPolicy` for how long will the class wait for
175  * `google.longrunning.Operation` to complete. This class combines both
176  * the backoff policy for checking long running operations and the
177  * retry policy.
178  *
179  * @see GenericPollingPolicy, ExponentialBackoffPolicy,
180  * LimitedErrorCountRetryPolicy, LimitedTimeRetryPolicy.
181  */
182  template <typename... Policies>
183  TableAdmin(std::shared_ptr<AdminClient> client, std::string instance_id,
184  Policies&&... policies)
185  : TableAdmin(std::move(client), std::move(instance_id)) {
186  ChangePolicies(std::forward<Policies>(policies)...);
187  }
188 
189  TableAdmin(TableAdmin const&) = default;
190  TableAdmin& operator=(TableAdmin const&) = default;
191 
192  //@{
193  /// @name Convenience shorthands for the schema views.
194  using TableView = ::google::bigtable::admin::v2::Table::View;
195  /// Only populate 'name' and fields related to the table's encryption state.
196  static auto constexpr ENCRYPTION_VIEW = // NOLINT(readability-identifier-naming)
197  google::bigtable::admin::v2::Table::ENCRYPTION_VIEW;
198  /// Populate all the fields in the response.
199  static auto constexpr FULL = // NOLINT(readability-identifier-naming)
200  google::bigtable::admin::v2::Table::FULL;
201  /// Populate only the name in the responses.
202  static auto constexpr NAME_ONLY = // NOLINT(readability-identifier-naming)
203  google::bigtable::admin::v2::Table::NAME_ONLY;
204  /// Populate only the name and the fields related to the table replication
205  /// state.
206  static auto constexpr REPLICATION_VIEW = // NOLINT(readability-identifier-naming)
207  google::bigtable::admin::v2::Table::REPLICATION_VIEW;
208  /// Populate only the name and the fields related to the table schema.
209  static auto constexpr SCHEMA_VIEW = // NOLINT(readability-identifier-naming)
210  google::bigtable::admin::v2::Table::SCHEMA_VIEW;
211  /// Use the default view as defined for each function.
212  static auto constexpr VIEW_UNSPECIFIED = // NOLINT(readability-identifier-naming)
213  google::bigtable::admin::v2::Table::VIEW_UNSPECIFIED;
214  //@}
215 
216  std::string const& project() const { return client_->project(); }
217  std::string const& instance_id() const { return instance_id_; }
218  std::string const& instance_name() const { return instance_name_; }
219 
220  /**
221  * Create a new table in the instance.
222  *
223  * @param table_id the name of the table relative to the instance managed by
224  * this object. The full table name is
225  * `projects/<PROJECT_ID>/instances/<INSTANCE_ID>/tables/<table_id>`
226  * where PROJECT_ID is obtained from the associated AdminClient and
227  * INSTANCE_ID is the instance_id() of this object.
228  * @param config the initial schema for the table.
229  * @return the attributes of the newly created table. Notice that the server
230  * only populates the table_name() field at this time.
231  *
232  * @par Idempotency
233  * This operation is always treated as non-idempotent.
234  *
235  * @par Thread-safety
236  * Two threads concurrently calling this member function on the same instance
237  * of this class are **not** guaranteed to work. Consider copying the object
238  * and using different copies in each thread.
239  *
240  * @par Example
241  * @snippet table_admin_snippets.cc create table
242  */
243  StatusOr<::google::bigtable::admin::v2::Table> CreateTable(
244  std::string table_id, TableConfig config);
245 
246  /**
247  * Return all the tables in the instance.
248  *
249  * @param view define what information about the tables is retrieved.
250  * - `VIEW_UNSPECIFIED`: equivalent to `VIEW_SCHEMA`.
251  * - `NAME`: return only the name of the table.
252  * - `VIEW_SCHEMA`: return the name and the schema.
253  * - `FULL`: return all the information about the table.
254  *
255  * @par Idempotency
256  * This operation is read-only and therefore it is always idempotent.
257  *
258  * @par Thread-safety
259  * Two threads concurrently calling this member function on the same instance
260  * of this class are **not** guaranteed to work. Consider copying the object
261  * and using different copies in each thread.
262  *
263  * @par Example
264  * @snippet table_admin_snippets.cc list tables
265  */
266  StatusOr<std::vector<::google::bigtable::admin::v2::Table>> ListTables(
267  ::google::bigtable::admin::v2::Table::View view);
268 
269  /**
270  * Get information about a single table.
271  *
272  * @param table_id the id of the table within the instance associated with
273  * this object. The full name of the table is
274  * `this->instance_name() + "/tables/" + table_id`
275  * @param view describes how much information to get about the name.
276  * - VIEW_UNSPECIFIED: equivalent to VIEW_SCHEMA.
277  * - NAME: return only the name of the table.
278  * - VIEW_SCHEMA: return the name and the schema.
279  * - FULL: return all the information about the table.
280  * @return the information about the table or status.
281  *
282  * @par Idempotency
283  * This operation is read-only and therefore it is always idempotent.
284  *
285  * @par Thread-safety
286  * Two threads concurrently calling this member function on the same instance
287  * of this class are **not** guaranteed to work. Consider copying the object
288  * and using different copies in each thread.
289  *
290  * @par Example
291  * @snippet table_admin_snippets.cc get table
292  */
293  StatusOr<::google::bigtable::admin::v2::Table> GetTable(
294  std::string const& table_id, TableView view = SCHEMA_VIEW);
295 
296  /**
297  * Delete a table.
298  *
299  * @param table_id the id of the table within the instance associated with
300  * this object. The full name of the table is
301  * `this->instance_name() + "/tables/" + table_id`
302  *
303  * @return status of the operation.
304  *
305  * @par Idempotency
306  * This operation is always treated as non-idempotent.
307  *
308  * @par Thread-safety
309  * Two threads concurrently calling this member function on the same instance
310  * of this class are **not** guaranteed to work. Consider copying the object
311  * and using different copies in each thread.
312  *
313  * @par Example
314  * @snippet table_admin_snippets.cc delete table
315  */
316  Status DeleteTable(std::string const& table_id);
317 
318  /**
319  * Parameters for `CreateBackup`.
320  *
321  * @param cluster_id the name of the cluster relative to the instance managed
322  * by the `TableAdmin` object. The full cluster name is
323  * `projects/<PROJECT_ID>/instances/<INSTANCE_ID>/clusters/<cluster_id>`
324  * where PROJECT_ID is obtained from the associated AdminClient and
325  * INSTANCE_ID is the instance_id() of the `TableAdmin` object.
326  * @param backup_id the name of the backup relative to the cluster specified.
327  * The full backup name is
328  * `projects/<PROJECT_ID>/instances/<INSTANCE_ID>/clusters/<CLUSTER_ID>/backups/<backup_id>`
329  * where PROJECT_ID is obtained from the associated AdminClient,
330  * INSTANCE_ID is the instance_id() of the `TableAdmin` object, and
331  * CLUSTER_ID is the cluster_id specified for this object.
332  * @param table_id the id of the table within the instance to be backed up.
333  * The full name of the table is
334  * `projects/<PROJECT_ID>/instances/<INSTANCE_ID>/tables/<table_id>`
335  * where PROJECT_ID is obtained from the associated AdminClient and
336  * INSTANCE_ID is the instance_id() of the `TableAdmin` object.
337  * @param expire_time the date and time when the created backup will expire.
338  */
340  CreateBackupParams() = default;
341  CreateBackupParams(std::string cluster_id, std::string backup_id,
342  std::string table_id,
343  std::chrono::system_clock::time_point expire_time)
344  : cluster_id(std::move(cluster_id)),
345  backup_id(std::move(backup_id)),
346  table_name(std::move(table_id)),
347  expire_time(std::move(expire_time)) {}
348 
349  google::bigtable::admin::v2::CreateBackupRequest AsProto(
350  std::string instance_name) const;
351 
352  std::string cluster_id;
353  std::string backup_id;
354  std::string table_name;
355  std::chrono::system_clock::time_point expire_time;
356  };
357 
358  /**
359  * Create a new backup of a table in the instance.
360  *
361  * @param params instance of `CreateBackupParams`.
362  *
363  * @par Idempotency
364  * This operation is always treated as non-idempotent.
365  *
366  * @par Thread-safety
367  * Two threads concurrently calling this member function on the same instance
368  * of this class are **not** guaranteed to work. Consider copying the object
369  * and using different copies in each thread.
370  *
371  * @par Example
372  * @snippet bigtable_table_admin_backup_snippets.cc create backup
373  */
374  StatusOr<google::bigtable::admin::v2::Backup> CreateBackup(
375  CreateBackupParams const& params);
376 
377  /**
378  * Get information about a single backup.
379  *
380  * @param cluster_id the name of the cluster relative to the instance managed
381  * by the `TableAdmin` object. The full cluster name is
382  * `projects/<PROJECT_ID>/instances/<INSTANCE_ID>/clusters/<cluster_id>`
383  * where PROJECT_ID is obtained from the associated AdminClient and
384  * INSTANCE_ID is the instance_id() of the `TableAdmin` object.
385  * @param backup_id the name of the backup relative to the cluster specified.
386  * The full backup name is
387  * `projects/<PROJECT_ID>/instances/<INSTANCE_ID>/clusters/<CLUSTER_ID>/backups/<backup_id>`
388  * where PROJECT_ID is obtained from the associated AdminClient,
389  * INSTANCE_ID is the instance_id() of the `TableAdmin` object, and
390  * CLUSTER_ID is the cluster_id previously specified.
391  *
392  * @par Idempotency
393  * This operation is read-only and therefore it is always idempotent.
394  *
395  * @par Thread-safety
396  * Two threads concurrently calling this member function on the same instance
397  * of this class are **not** guaranteed to work. Consider copying the object
398  * and using different copies in each thread.
399  *
400  * @par Example
401  * @snippet bigtable_table_admin_backup_snippets.cc get backup
402  */
403  StatusOr<google::bigtable::admin::v2::Backup> GetBackup(
404  std::string const& cluster_id, std::string const& backup_id);
405 
406  /**
407  * Parameters for `UpdateBackup`.
408  *
409  * @param cluster_id the name of the cluster relative to the instance managed
410  * by the `TableAdmin` object. The full cluster name is
411  * `projects/<PROJECT_ID>/instances/<INSTANCE_ID>/clusters/<cluster_id>`
412  * where PROJECT_ID is obtained from the associated AdminClient and
413  * INSTANCE_ID is the instance_id() of the `TableAdmin` object.
414  * @param backup_id the name of the backup relative to the cluster specified.
415  * The full backup name is
416  * `projects/<PROJECT_ID>/instances/<INSTANCE_ID>/clusters/<CLUSTER_ID>/backups/<backup_id>`
417  * where PROJECT_ID is obtained from the associated AdminClient,
418  * INSTANCE_ID is the instance_id() of the `TableAdmin` object, and
419  * CLUSTER_ID is the cluster_id specified for this object.
420  * @param expire_time the date and time when the created backup will expire.
421  */
423  UpdateBackupParams() = default;
424  UpdateBackupParams(std::string cluster_id, std::string backup_id,
425  std::chrono::system_clock::time_point expire_time)
426  : cluster_id(std::move(cluster_id)),
427  backup_name(std::move(backup_id)),
428  expire_time(std::move(expire_time)) {}
429 
430  google::bigtable::admin::v2::UpdateBackupRequest AsProto(
431  std::string const& instance_name) const;
432 
433  std::string cluster_id;
434  std::string backup_name;
435  std::chrono::system_clock::time_point expire_time;
436  };
437 
438  /**
439  * Updates a backup of a table in the instance.
440  *
441  * @param params instance of `UpdateBackupParams`.
442  *
443  * @par Idempotency
444  * This operation is always treated as non-idempotent.
445  *
446  * @par Thread-safety
447  * Two threads concurrently calling this member function on the same instance
448  * of this class are **not** guaranteed to work. Consider copying the object
449  * and using different copies in each thread.
450  *
451  * @par Example
452  * @snippet bigtable_table_admin_backup_snippets.cc update backup
453  */
454  StatusOr<google::bigtable::admin::v2::Backup> UpdateBackup(
455  UpdateBackupParams const& params);
456 
457  /**
458  * Delete a backup.
459  *
460  * @param cluster_id the name of the cluster relative to the instance managed
461  * by the `TableAdmin` object. The full cluster name is
462  * `projects/<PROJECT_ID>/instances/<INSTANCE_ID>/clusters/<cluster_id>`
463  * where PROJECT_ID is obtained from the associated AdminClient and
464  * INSTANCE_ID is the instance_id() of the `TableAdmin` object.
465  * @param backup_id the name of the backup relative to the cluster specified.
466  * The full backup name is
467  * `projects/<PROJECT_ID>/instances/<INSTANCE_ID>/clusters/<CLUSTER_ID>/backups/<backup_id>`
468  * where PROJECT_ID is obtained from the associated AdminClient,
469  * INSTANCE_ID is the instance_id() of the `TableAdmin` object, and
470  * CLUSTER_ID is the cluster_id previously specified.
471  *
472  * @par Idempotency
473  * This operation is always treated as non-idempotent.
474  *
475  * @par Thread-safety
476  * Two threads concurrently calling this member function on the same instance
477  * of this class are **not** guaranteed to work. Consider copying the object
478  * and using different copies in each thread.
479  *
480  * @par Example
481  * @snippet bigtable_table_admin_backup_snippets.cc delete backup
482  */
483  Status DeleteBackup(std::string const& cluster_id,
484  std::string const& backup_id);
485 
486  /**
487  * Delete a backup.
488  *
489  * @param backup typically returned by a call to `GetBackup` or `ListBackups`.
490  *
491  * @par Idempotency
492  * This operation is always treated as non-idempotent.
493  *
494  * @par Thread-safety
495  * Two threads concurrently calling this member function on the same instance
496  * of this class are **not** guaranteed to work. Consider copying the object
497  * and using different copies in each thread.
498  *
499  * @par Example
500  * @snippet bigtable_table_admin_backup_snippets.cc delete backup
501  */
502  Status DeleteBackup(google::bigtable::admin::v2::Backup const& backup);
503 
504  /**
505  * Parameters for `ListBackups`.
506  */
508  ListBackupsParams() = default;
509 
510  /**
511  * Sets the cluster_id.
512  *
513  * @param c the name of the cluster relative to the instance
514  * managed by the `TableAdmin` object. If no cluster_id is specified,
515  * the all backups in all clusters are listed. The full cluster name is
516  * `projects/<PROJECT_ID>/instances/<INSTANCE_ID>/clusters/<cluster_id>`
517  * where PROJECT_ID is obtained from the associated AdminClient and
518  * INSTANCE_ID is the instance_id() of the `TableAdmin` object.
519  */
520  ListBackupsParams& set_cluster(std::string c) {
521  this->cluster_id = std::move(c);
522  return *this;
523  }
524 
525  /**
526  * Sets the filtering expression.
527  *
528  * @param f expression that filters backups listed in the response.
529  * The expression must specify the field name, a comparison operator,
530  * and the value that you want to use for filtering. The value must be a
531  * string, a number, or a boolean. The comparison operator must be
532  * <, >, <=, >=, !=, =, or :. Colon ‘:’ represents a HAS operator which
533  * is roughly synonymous with equality. Filter rules are case
534  * insensitive.
535  *
536  * The fields eligible for filtering are:
537  * * `name`
538  * * `table`
539  * * `state`
540  * * `start_time` (and values are of the format
541  * `YYYY-MM-DDTHH:MM:SSZ`)
542  * * `end_time` (and values are of the format `YYYY-MM-DDTHH:MM:SSZ`)
543  * * `expire_time` (and values are of the format
544  * `YYYY-MM-DDTHH:MM:SSZ`)
545  * * `size_bytes`
546  *
547  * To filter on multiple expressions, provide each separate expression
548  * within parentheses. By default, each expression is an AND expression.
549  * However, you can include AND, OR, and NOT expressions explicitly.
550  *
551  * Some examples of using filters are:
552  * * `name:"exact"` --> The backup's name is the string "exact".
553  * * `name:howl` --> The backup's name contains the string "howl".
554  * * `table:prod` --> The table's name contains the string "prod".
555  * * `state:CREATING` --> The backup is pending creation.
556  * * `state:READY` --> The backup is fully created and ready for use.
557  * * `(name:howl) AND (start_time < \"2018-03-28T14:50:00Z\")`
558  * --> The backup name contains the string "howl" and start_time
559  * of the backup is before `2018-03-28T14:50:00Z`.
560  * * `size_bytes > 10000000000` --> The backup's size is greater than
561  * 10GB
562  */
563  ListBackupsParams& set_filter(std::string f) {
564  this->filter = std::move(f);
565  return *this;
566  }
567 
568  /**
569  * Sets the ordering expression.
570  *
571  * @param o expression for specifying the sort order of the results
572  * of the request. The string value should specify only one field in
573  * `google::bigtable::admin::v2::Backup`.
574  * The following field names are supported:
575  * * name
576  * * table
577  * * expire_time
578  * * start_time
579  * * end_time
580  * * size_bytes
581  * * state
582  *
583  * For example, "start_time". The default sorting order is ascending.
584  * Append the " desc" suffix to the field name to sort descending, e.g.
585  * "start_time desc". Redundant space characters in the syntax are
586  * insignificant.
587  *
588  * If order_by is empty, results will be sorted by `start_time` in
589  * descending order starting from the most recently created backup.
590  */
591  ListBackupsParams& set_order_by(std::string o) {
592  this->order_by = std::move(o);
593  return *this;
594  }
595 
596  google::bigtable::admin::v2::ListBackupsRequest AsProto(
597  std::string const& instance_name) const;
598 
599  absl::optional<std::string> cluster_id;
600  absl::optional<std::string> filter;
601  absl::optional<std::string> order_by;
602  };
603 
604  /**
605  * Retrieves a list of backups.
606  *
607  * @param params instance of `ListBackupsParams`.
608  *
609  * @par Idempotency
610  * This operation is read-only and therefore it is always idempotent.
611  *
612  * @par Thread-safety
613  * Two threads concurrently calling this member function on the same instance
614  * of this class are **not** guaranteed to work. Consider copying the object
615  * and using different copies in each thread.
616  *
617  * @par Example
618  * @snippet bigtable_table_admin_backup_snippets.cc list backups
619  */
620  StatusOr<std::vector<google::bigtable::admin::v2::Backup>> ListBackups(
621  ListBackupsParams const& params);
622 
623  /**
624  * Parameters for `RestoreTable`.
625  *
626  * @param table_id the name of the table relative to the instance managed by
627  * this object. The full table name is
628  * `projects/<PROJECT_ID>/instances/<INSTANCE_ID>/tables/<table_id>`
629  * where PROJECT_ID is obtained from the associated AdminClient and
630  * INSTANCE_ID is the instance_id() of this object.
631  * @param cluster_id the name of the cluster relative to the instance managed
632  * by the `TableAdmin` object. The full cluster name is
633  * `projects/<PROJECT_ID>/instances/<INSTANCE_ID>/clusters/<cluster_id>`
634  * where PROJECT_ID is obtained from the associated AdminClient and
635  * INSTANCE_ID is the instance_id() of the `TableAdmin` object.
636  * @param backup_id the name of the backup relative to the cluster specified.
637  * The full backup name is
638  * `projects/<PROJECT_ID>/instances/<INSTANCE_ID>/clusters/<CLUSTER_ID>/backups/<backup_id>`
639  * where PROJECT_ID is obtained from the associated AdminClient,
640  * INSTANCE_ID is the instance_id() of the `TableAdmin` object, and
641  * CLUSTER_ID is the cluster_id previously specified.
642  */
644  RestoreTableParams() = default;
645  RestoreTableParams(std::string table_id, std::string cluster_id,
646  std::string backup_id)
647  : table_id(std::move(table_id)),
648  cluster_id(std::move(cluster_id)),
649  backup_id(std::move(backup_id)) {}
650 
651  /// @deprecated covert the parameters to a proto.
652  google::bigtable::admin::v2::RestoreTableRequest AsProto(
653  std::string const& instance_name) const;
654 
655  std::string table_id;
656  std::string cluster_id;
657  std::string backup_id;
658  };
659 
660  /**
661  * Parameters for `RestoreTable`.
662  *
663  * @param table_id the name of the table relative to the instance managed by
664  * this object. The full table name is
665  * `projects/<PROJECT_ID>/instances/<INSTANCE_ID>/tables/<table_id>`
666  * where PROJECT_ID is obtained from the associated AdminClient and
667  * INSTANCE_ID is the instance_id() of this object.
668  * @param backup_name the full name of the backup used to restore @p table_id.
669  */
671  std::string table_id;
672  std::string backup_name;
673  };
674 
675  /**
676  * Restore a backup into a new table in the instance.
677  *
678  * @param params instance of `RestoreTableParams`.
679  *
680  * @par Idempotency
681  * This operation is always treated as non-idempotent.
682  *
683  * @par Thread-safety
684  * Two threads concurrently calling this member function on the same instance
685  * of this class are **not** guaranteed to work. Consider copying the object
686  * and using different copies in each thread.
687  *
688  * @par Example
689  * @snippet bigtable_table_admin_backup_snippets.cc restore table
690  */
691  StatusOr<google::bigtable::admin::v2::Table> RestoreTable(
692  RestoreTableParams const& params);
693 
694  /**
695  * Restore a backup into a new table in the instance.
696  *
697  * @param params instance of `RestoreTableFromInstanceParams`.
698  *
699  * @par Idempotency
700  * This operation is always treated as non-idempotent.
701  *
702  * @par Thread-safety
703  * Two threads concurrently calling this member function on the same instance
704  * of this class are **not** guaranteed to work. Consider copying the object
705  * and using different copies in each thread.
706  *
707  * @par Example
708  * @snippet bigtable_table_admin_backup_snippets.cc restore2
709  */
710  StatusOr<google::bigtable::admin::v2::Table> RestoreTable(
712 
713  /**
714  * Modify the schema for an existing table.
715  *
716  * @param table_id the id of the table within the instance associated with
717  * this object. The full name of the table is
718  * `this->instance_name() + "/tables/" + table_id`
719  * @param modifications the list of modifications to the schema.
720  *
721  * @par Idempotency
722  * This operation is always treated as non-idempotent.
723  *
724  * @par Thread-safety
725  * Two threads concurrently calling this member function on the same instance
726  * of this class are **not** guaranteed to work. Consider copying the object
727  * and using different copies in each thread.
728  *
729  * @par Example
730  * @snippet table_admin_snippets.cc modify table
731  */
732  StatusOr<::google::bigtable::admin::v2::Table> ModifyColumnFamilies(
733  std::string const& table_id,
734  std::vector<ColumnFamilyModification> modifications);
735 
736  /**
737  * Delete all the rows that start with a given prefix.
738  *
739  * @param table_id the id of the table within the instance associated with
740  * this object. The full name of the table is
741  * `this->instance_name() + "/tables/" + table_id`
742  * @param row_key_prefix drop any rows that start with this prefix.
743  *
744  * @par Idempotency
745  * This operation is always treated as non-idempotent.
746  *
747  * @par Thread-safety
748  * Two threads concurrently calling this member function on the same instance
749  * of this class are **not** guaranteed to work. Consider copying the object
750  * and using different copies in each thread.
751  *
752  * @par Example
753  * @snippet table_admin_snippets.cc drop rows by prefix
754  */
755  Status DropRowsByPrefix(std::string const& table_id,
756  std::string row_key_prefix);
757 
758  /**
759  * Generates consistency token for a table.
760  *
761  * @param table_id the id of the table for which we want to generate
762  * consistency token.
763  * @return the consistency token for table.
764  *
765  * @par Idempotency
766  * This operation is read-only and therefore it is always idempotent.
767  *
768  * @par Thread-safety
769  * Two threads concurrently calling this member function on the same instance
770  * of this class are **not** guaranteed to work. Consider copying the object
771  * and using different copies in each thread.
772  *
773  * @par Example
774  * @snippet table_admin_snippets.cc generate consistency token
775  */
776  StatusOr<std::string> GenerateConsistencyToken(std::string const& table_id);
777 
778  /**
779  * Checks consistency of a table.
780  *
781  * @param table_id the id of the table for which we want to check
782  * consistency.
783  * @param consistency_token the consistency token of the table.
784  * @return the consistency status for the table.
785  *
786  * @par Idempotency
787  * This operation is read-only and therefore it is always idempotent.
788  *
789  * @par Thread-safety
790  * Two threads concurrently calling this member function on the same instance
791  * of this class are **not** guaranteed to work. Consider copying the object
792  * and using different copies in each thread.
793  *
794  * @par Example
795  * @snippet table_admin_snippets.cc check consistency
796  */
797  StatusOr<Consistency> CheckConsistency(std::string const& table_id,
798  std::string const& consistency_token);
799 
800  /**
801  * Checks consistency of a table with multiple calls using a separate thread
802  *
803  * @param table_id the id of the table for which we want to check
804  * consistency.
805  * @param consistency_token the consistency token of the table.
806  * @return the consistency status for the table.
807  *
808  * @par Idempotency
809  * This operation is read-only and therefore it is always idempotent.
810  *
811  * @par Thread-safety
812  * Two threads concurrently calling this member function on the same instance
813  * of this class are **not** guaranteed to work. Consider copying the object
814  * and using different copies in each thread.
815  *
816  * @par Example
817  * @snippet table_admin_snippets.cc wait for consistency check
818  */
820  std::string const& table_id, std::string const& consistency_token);
821 
822  /**
823  * Delete all the rows in a table.
824  *
825  * @param table_id the id of the table within the instance associated with
826  * this object. The full name of the table is
827  * `this->instance_name() + "/tables/" + table_id`
828  *
829  * @par Idempotency
830  * This operation is always treated as non-idempotent.
831  *
832  * @par Thread-safety
833  * Two threads concurrently calling this member function on the same instance
834  * of this class are **not** guaranteed to work. Consider copying the object
835  * and using different copies in each thread.
836  *
837  * @par Example
838  * @snippet table_admin_snippets.cc drop all rows
839  */
840  Status DropAllRows(std::string const& table_id);
841 
842  /**
843  * Gets the policy for @p table_id.
844  *
845  * @param table_id the table to query.
846  * @return google::iam::v1::Policy the full IAM policy for the table.
847  *
848  * @par Idempotency
849  * This operation is read-only and therefore it is always idempotent.
850  *
851  * @par Thread-safety
852  * Two threads concurrently calling this member function on the same instance
853  * of this class are **not** guaranteed to work. Consider copying the object
854  * and using different copies in each thread.
855  *
856  * @par Example
857  * @snippet table_admin_iam_policy_snippets.cc get iam policy
858  */
859  StatusOr<google::iam::v1::Policy> GetIamPolicy(std::string const& table_id);
860 
861  /**
862  * Gets the policy for @p backup_id.
863  *
864  * @param cluster_id the associated cluster that contains backup.
865  *
866  * @param backup_id the backup to query.
867  * @return google::iam::v1::Policy the full IAM policy for the backup.
868  *
869  * @par Idempotency
870  * This operation is read-only and therefore it is always idempotent.
871  *
872  * @par Thread-safety
873  * Two threads concurrently calling this member function on the same instance
874  * of this class are **not** guaranteed to work. Consider copying the object
875  * and using different copies in each thread.
876  *
877  * @par Example
878  * @snippet bigtable_table_admin_backup_snippets.cc get backup iam policy
879  */
880  StatusOr<google::iam::v1::Policy> GetIamPolicy(std::string const& cluster_id,
881  std::string const& backup_id);
882 
883  /**
884  * Sets the IAM policy for a table.
885  *
886  * This is the preferred way to overload `IamBindings`. This is more closely
887  * coupled to the underlying protocol, enable more actions and is more likely
888  * to tolerate future protocol changes.
889  *
890  * @param table_id which table to set the IAM policy for.
891  * @param iam_policy google::iam::v1::Policy object containing role and
892  * members.
893  * @return google::iam::v1::Policy the current IAM policy for the table.
894  *
895  * @warning ETags are currently not used by Cloud Bigtable.
896  *
897  * @par Idempotency
898  * This operation is always treated as non-idempotent.
899  *
900  * @par Thread-safety
901  * Two threads concurrently calling this member function on the same instance
902  * of this class are **not** guaranteed to work. Consider copying the object
903  * and using different copies in each thread.
904  *
905  * @par Example
906  * @snippet table_admin_iam_policy_snippets.cc set iam policy
907  */
908  StatusOr<google::iam::v1::Policy> SetIamPolicy(
909  std::string const& table_id, google::iam::v1::Policy const& iam_policy);
910 
911  /**
912  * Sets the IAM policy for a backup.
913  *
914  * This is the preferred way to overload `IamBindings`. This is more closely
915  * coupled to the underlying protocol, enable more actions and is more likely
916  * to tolerate future protocol changes.
917  *
918  * @param cluster_id which is the cluster containing the backup.
919  * @param backup_id which backup to set the IAM policy for.
920  * @param iam_policy google::iam::v1::Policy object containing role and
921  * members.
922  * @return google::iam::v1::Policy the current IAM policy for the table.
923  *
924  * @warning ETags are currently not used by Cloud Bigtable.
925  *
926  * @par Idempotency
927  * This operation is always treated as non-idempotent.
928  *
929  * @par Thread-safety
930  * Two threads concurrently calling this member function on the same instance
931  * of this class are **not** guaranteed to work. Consider copying the object
932  * and using different copies in each thread.
933  *
934  * @par Example
935  * @snippet bigtable_table_admin_backup_snippets.cc set backup iam policy
936  */
937  StatusOr<google::iam::v1::Policy> SetIamPolicy(
938  std::string const& cluster_id, std::string const& backup_id,
939  google::iam::v1::Policy const& iam_policy);
940 
941  /**
942  * Returns a permission set that the caller has on the specified table.
943  *
944  * @param table_id the ID of the table to query.
945  * @param permissions set of permissions to check for the resource.
946  *
947  * @par Idempotency
948  * This operation is read-only and therefore it is always idempotent.
949  *
950  * @par Thread-safety
951  * Two threads concurrently calling this member function on the same instance
952  * of this class are **not** guaranteed to work. Consider copying the object
953  * and using different copies in each thread.
954  *
955  * @par Example
956  * @snippet table_admin_iam_policy_snippets.cc test iam permissions
957  *
958  * @see https://cloud.google.com/bigtable/docs/access-control for a list of
959  * valid permissions on Google Cloud Bigtable.
960  */
961  StatusOr<std::vector<std::string>> TestIamPermissions(
962  std::string const& table_id, std::vector<std::string> const& permissions);
963 
964  /**
965  * Returns a permission set that the caller has on the specified backup.
966  *
967  * @param cluster_id the ID of the cluster that contains the backup.
968  * @param backup_id the ID of the backup to query.
969  * @param permissions set of permissions to check for the resource.
970  *
971  * @par Idempotency
972  * This operation is read-only and therefore it is always idempotent.
973  *
974  * @par Thread-safety
975  * Two threads concurrently calling this member function on the same instance
976  * of this class are **not** guaranteed to work. Consider copying the object
977  * and using different copies in each thread.
978  *
979  * @par Example
980  * @snippet table_admin_iam_policy_snippets.cc test iam permissions
981  *
982  * @see https://cloud.google.com/bigtable/docs/access-control for a list of
983  * valid permissions on Google Cloud Bigtable.
984  */
985  StatusOr<std::vector<std::string>> TestIamPermissions(
986  std::string const& cluster_id, std::string const& backup_id,
987  std::vector<std::string> const& permissions);
988 
989  /// Return the fully qualified name of a table in this object's instance.
990  std::string TableName(std::string const& table_id) const {
992  table_id);
993  }
994 
995  /// Return the fully qualified name of a Cluster.
996  std::string ClusterName(std::string const& cluster_id) const {
998  cluster_id);
999  }
1000 
1001  /// Return the fully qualified name of a Backup.
1002  std::string BackupName(std::string const& cluster_id,
1003  std::string const& backup_id) const {
1005  cluster_id, backup_id);
1006  }
1007 
1008  private:
1009  friend class TableAdminTester;
1010 
1011  //@{
1012  /// @name Helper functions to implement constructors with changed policies.
1013  void ChangePolicy(RPCRetryPolicy const& policy) {
1014  rpc_retry_policy_prototype_ = policy.clone();
1015  }
1016 
1017  void ChangePolicy(RPCBackoffPolicy const& policy) {
1018  rpc_backoff_policy_prototype_ = policy.clone();
1019  }
1020 
1021  void ChangePolicy(PollingPolicy const& policy) {
1022  polling_policy_prototype_ = policy.clone();
1023  }
1024 
1025  template <typename Policy, typename... Policies>
1026  void ChangePolicies(Policy&& policy, Policies&&... policies) {
1027  ChangePolicy(policy);
1028  ChangePolicies(std::forward<Policies>(policies)...);
1029  }
1030  void ChangePolicies() {}
1031  //@}
1032 
1033  std::unique_ptr<RPCRetryPolicy> clone_rpc_retry_policy() {
1034  return rpc_retry_policy_prototype_->clone();
1035  }
1036 
1037  std::unique_ptr<RPCBackoffPolicy> clone_rpc_backoff_policy() {
1038  return rpc_backoff_policy_prototype_->clone();
1039  }
1040 
1041  MetadataUpdatePolicy clone_metadata_update_policy() {
1042  return metadata_update_policy_;
1043  }
1044 
1045  std::unique_ptr<PollingPolicy> clone_polling_policy() {
1046  return polling_policy_prototype_->clone();
1047  }
1048 
1049  /// Compute the fully qualified instance name.
1050  std::string InstanceName() const;
1051 
1052  future<StatusOr<google::bigtable::admin::v2::Backup>> AsyncCreateBackupImpl(
1053  CompletionQueue& cq, CreateBackupParams const& params);
1054 
1055  future<StatusOr<google::bigtable::admin::v2::Table>> AsyncRestoreTableImpl(
1056  CompletionQueue& cq, RestoreTableParams const& params);
1057 
1058  future<StatusOr<google::bigtable::admin::v2::Table>> AsyncRestoreTableImpl(
1060 
1061  future<StatusOr<Consistency>> AsyncCheckConsistency(
1062  CompletionQueue& cq, std::string const& table_id,
1063  std::string const& consistency_token);
1064 
1065  future<StatusOr<Consistency>> AsyncWaitForConsistencyImpl(
1066  CompletionQueue& cq, std::string const& table_id,
1067  std::string const& consistency_token);
1068 
1069  std::shared_ptr<AdminClient> client_;
1070  std::string instance_id_;
1071  std::string instance_name_;
1072  std::shared_ptr<RPCRetryPolicy const> rpc_retry_policy_prototype_;
1073  std::shared_ptr<RPCBackoffPolicy const> rpc_backoff_policy_prototype_;
1074  bigtable::MetadataUpdatePolicy metadata_update_policy_;
1075  std::shared_ptr<PollingPolicy const> polling_policy_prototype_;
1076  std::shared_ptr<BackgroundThreads> background_threads_;
1077 };
1078 
1080 } // namespace bigtable
1081 } // namespace cloud
1082 } // namespace google
1083 
1084 #endif // GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_BIGTABLE_TABLE_ADMIN_H