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