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