Google Cloud Bigtable C++ Client  1.35.0
A C++ Client Library for Google Cloud Bigtable
cell.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_CELL_H
16 #define GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_BIGTABLE_CELL_H
17 
18 #include "google/cloud/bigtable/internal/google_bytes_traits.h"
19 #include "google/cloud/bigtable/row_key.h"
20 #include "google/cloud/bigtable/version.h"
21 #include "google/cloud/status_or.h"
22 #include <chrono>
23 #include <string>
24 #include <type_traits>
25 #include <vector>
26 
27 namespace google {
28 namespace cloud {
29 namespace bigtable {
31 class Cell;
32 struct Mutation;
34 
35 /**
36  * Defines the type for column qualifiers.
37  *
38  * Inside Google some protobuf fields of type `bytes` are mapped to a different
39  * type than `std::string`. This is the case for column qualifiers. We use this
40  * type to automatically detect what is the representation for this field and
41  * use the correct mapping.
42  *
43  * External users of the Cloud Bigtable C++ client library should treat this as
44  * a complicated `typedef` for `std::string`. We have no plans to change the
45  * type in the external version of the C++ client library for the foreseeable
46  * future. In the eventuality that we do decide to change the type, this would
47  * be a reason update the library major version number, and we would give users
48  * time to migrate.
49  *
50  * In other words, external users of the Cloud Bigtable C++ client should simply
51  * write `std::string` where this type appears. For Google projects that must
52  * compile both inside and outside Google, this alias may be convenient.
53  */
54 using ColumnQualifierType = std::decay<
55  decltype(std::declval<google::bigtable::v2::Column>().qualifier())>::type;
56 
57 /**
58  * Defines the type for cell values.
59  *
60  * Inside Google some protobuf fields of type `bytes` are mapped to a different
61  * type than `std::string`. This is the case for column qualifiers. We use this
62  * type to automatically detect what is the representation for this field and
63  * use the correct mapping.
64  *
65  * External users of the Cloud Bigtable C++ client library should treat this as
66  * a complicated `typedef` for `std::string`. We have no plans to change the
67  * type in the external version of the C++ client library for the foreseeable
68  * future. In the eventuality that we do decide to change the type, this would
69  * be a reason update the library major version number, and we would give users
70  * time to migrate.
71  *
72  * In other words, external users of the Cloud Bigtable C++ client should simply
73  * write `std::string` where this type appears. For Google projects that must
74  * compile both inside and outside Google, this alias may be convenient.
75  */
76 using CellValueType = std::decay<
77  decltype(std::declval<google::bigtable::v2::Cell>().value())>::type;
78 
79 /**
80  * The in-memory representation of a Bigtable cell.
81  *
82  * Bigtable stores data in rows, indexes by row keys. Each row may contain
83  * multiple column families, each column family might contain multiple columns,
84  * and each column has multiple cells indexed by timestamp. Notice that the
85  * storage is sparse, column families, columns, and timestamps might contain
86  * zero cells.
87  *
88  * The Cell class owns all its data.
89  */
90 class Cell {
91  public:
92  /// Create a Cell and fill it with data.
93  template <typename KeyType, typename ColumnType, typename ValueType,
94  // This function does not participate in overload resolution if
95  // ValueType is not an integral type. The case for integral types is
96  // handled by the next overload, where the value is stored as a Big
97  // Endian number.
98  typename std::enable_if<!std::is_integral<ValueType>::value,
99  int>::type = 0>
100  Cell(KeyType&& row_key, std::string family_name,
101  ColumnType&& column_qualifier, std::int64_t timestamp, ValueType&& value,
102  std::vector<std::string> labels)
103  : row_key_(std::forward<KeyType>(row_key)),
104  family_name_(std::move(family_name)),
105  column_qualifier_(std::forward<ColumnType>(column_qualifier)),
106  timestamp_(timestamp),
107  value_(std::forward<ValueType>(value)),
108  labels_(std::move(labels)) {}
109 
110  /// Create a Cell and fill it with a 64-bit value encoded as big endian.
111  template <typename KeyType, typename ColumnType>
112  Cell(KeyType&& row_key, std::string family_name,
113  ColumnType&& column_qualifier, std::int64_t timestamp,
114  std::int64_t value, std::vector<std::string> labels)
115  : Cell(std::forward<KeyType>(row_key), std::move(family_name),
116  std::forward<ColumnType>(column_qualifier), timestamp,
117  google::cloud::internal::EncodeBigEndian(value),
118  std::move(labels)) {}
119 
120  /// Create a cell and fill it with data, but with empty labels.
121  template <typename KeyType, typename ColumnType, typename ValueType>
122  Cell(KeyType&& row_key, std::string family_name,
123  ColumnType&& column_qualifier, std::int64_t timestamp, ValueType&& value)
124  : Cell(std::forward<KeyType>(row_key), std::move(family_name),
125  std::forward<ColumnType>(column_qualifier), timestamp,
126  std::forward<ValueType>(value), std::vector<std::string>{}) {}
127 
128  /// Return the row key this cell belongs to. The returned value is not valid
129  /// after this object is deleted.
130  RowKeyType const& row_key() const { return row_key_; }
131 
132  /// Return the family this cell belongs to. The returned value is not valid
133  /// after this object is deleted.
134  std::string const& family_name() const { return family_name_; }
135 
136  /// Return the column this cell belongs to. The returned value is not valid
137  /// after this object is deleted.
138  ColumnQualifierType const& column_qualifier() const {
139  return column_qualifier_;
140  }
141 
142  /// Return the timestamp of this cell.
143  std::chrono::microseconds timestamp() const {
144  return std::chrono::microseconds(timestamp_);
145  }
146 
147  /// Return the contents of this cell. The returned value is not valid after
148  /// this object is deleted.
149  CellValueType const& value() const& { return value_; }
150  /// Return the contents of this cell.
151  CellValueType&& value() && { return std::move(value_); }
152 
153  /**
154  * Interpret the value as a big-endian encoded `T` and return it.
155  *
156  * Google Cloud Bigtable stores arbitrary blobs in each cell. Some
157  * applications interpret these blobs as strings, other as encoded protos,
158  * and sometimes as big-endian integers. This is a helper function to convert
159  * the blob into a T value.
160  */
161  template <typename T>
162  StatusOr<T> decode_big_endian_integer() const {
163  return internal::DecodeBigEndianCellValue<T>(value_);
164  }
165 
166  /// Return the labels applied to this cell by label transformer read filters.
167  std::vector<std::string> const& labels() const { return labels_; }
168 
169  private:
170  RowKeyType row_key_;
171  std::string family_name_;
172  ColumnQualifierType column_qualifier_;
173  std::int64_t timestamp_;
174  CellValueType value_;
175  std::vector<std::string> labels_;
176 
178 };
179 
181 } // namespace bigtable
182 } // namespace cloud
183 } // namespace google
184 
185 #endif // GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_BIGTABLE_CELL_H