Class Value (2.44.0-rc)

The Value class represents a type-safe, nullable Bigtable value.

For now, this is a minimal class to unblock further development of the Bigtable GoogleSQL feature. It is conceptually similar to a std::any except the only allowed types will be those supported by Bigtable, and a "null" value (similar to a std::any without a value) still has an associated type. The supported types are shown in the following table along with how they map to the Bigtable types (https://cloud.google.com/bigtable/docs/data-types):

Bigtable Type	C++ Type `T`
BOOL	`bool`
INT64	`std::int64_t`
FLOAT32	`float`
FLOAT64	`double`
STRING	`std::string`
BYTES	`google::cloud::bigtable::Bytes`
TIMESTAMP	`google::cloud::bigtable::Timestamp`
DATE	`absl::CivilDay`
ARRAY	`std::vector<T>` // [1]
STRUCT	`std::tuple<Ts...>`
MAP	`std::unordered_map<K, V>` // [2]

[1] The type T may be any of the other supported types, except for ARRAY/std::vector. [2] The type K may be any of Bytes, std::string, and std::int64_t.

Callers may create instances by passing any of the supported values (shown in the table above) to the constructor. "Null" values are created using the MakeNullValue<T>() factory function or by passing an empty absl::optional<T> to the Value constructor.

Bigtable Arrays

Bigtable arrays are represented in C++ as a std::vector<T>, where the type T may be any of the other allowed Bigtable types, such as bool, std::int64_t, etc. The only exception is that arrays may not directly contain another array; to achieve a similar result you could create an array of a 1-element struct holding an array. The following examples show usage of arrays.

std::vector<std::int64_t> vec = {1, 2, 3, 4, 5};
bigtable::Value v(vec);
auto copy = *v.get<std::vector<std::int64_t>>();
assert(vec == copy);

Bigtable Structs

Bigtable structs are represented in C++ as instances of std::tuple holding zero or more of the allowed Bigtable types, such as bool, std::int64_t, std::vector, and even other std::tuple objects. Each tuple element corresponds to a single field in a Bigtable STRUCT.

Bigtable STRUCT fields may optionally contain a string indicating the field's name. Fields names may be empty, unique, or repeated. A named field may be specified as a tuple element of type std::pair<std::string, T>, where the pair's .first member indicates the field's name, and the .second member is any valid Bigtable type T.

using Struct = std::tuple<bool, std::pair<std::string, std::int64_t>>;
Struct s  = {true, {"Foo", 42}};
bigtable::Value v(s);
assert(s == *v.get<Struct>());

Note: While a STRUCT's (optional) field names are not part of its C++ type, they are part of its Bigtable STRUCT type. Array's (i.e., std::vector) must contain a single element type, therefore it is an error to construct a std::vector of std::tuple objects with differently named fields.

Bigtable Maps

Bigtable maps are represented in C++ as a std::unordered_map<K, V>, where the type K may be any of Bytes, std::string or std::int64_t. Normally encoded Map values won't have repeated keys, however, this client handles the case as follows: if the same key appears multiple times, the last value takes precedence.

The following examples show usage of maps.

std::unordered_map<std::string, std::unordered_map<std::string,
std::int64_t>> m = {{"map1",
{{"key1", 1}}, "map2": {{"key2", 2}}};
bigtable::Value mv(m);
auto copy = *v.get<std::unordered_map<std::string, std::int64_t>>>();
assert(m == copy);