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