Class Value (2.20.0)

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

It is conceptually similar to a std::any except the only allowed types are those supported by Spanner, 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 Spanner types (https://cloud.google.com/spanner/docs/data-types):

Spanner Type	C++ Type `T`
BOOL	`bool`
INT64	`std::int64_t`
FLOAT64	`double`
STRING	`std::string`
BYTES	`google::cloud::spanner::Bytes`
JSON	`google::cloud::spanner::Json`
JSONB	`google::cloud::spanner::JsonB`
NUMERIC	`google::cloud::spanner::Numeric`
NUMERIC(PG)	`google::cloud::spanner::PgNumeric`
OID(PG)	`google::cloud::spanner::PgOid`
TIMESTAMP	`google::cloud::spanner::Timestamp`
DATE	`absl::CivilDay`
ARRAY	`std::vector<T>` // [1]
STRUCT	`std::tuple<Ts...>`

[1] The type T may be any of the other supported types, except for ARRAY/std::vector.

Value is a regular C++ value type with support for copy, move, equality, etc. A default-constructed Value represents an empty value with no type.

Note: There is also a C++ type of CommitTimestamp that corresponds to a Cloud Spanner TIMESTAMP object for setting the commit timestamp on a column with the allow_commit_timestamp set to true in the schema.

Example

Using a non-null value.

std::string msg = "hello";
spanner::Value v(msg);
StatusOr<std::string> copy = v.get<std::string>();
if (copy) {
  std::cout << *copy;  // prints "hello"
}

Example

Using a null value.

spanner::Value v = spanner::MakeNullValue<std::int64_t>();
StatusOr<std::int64_t> i = v.get<std::int64_t>();
assert(!i.ok());  // Can't get the value because v is null
StatusOr < absl::optional<std::int64_t> j =
    v.get<absl::optional<std::int64_t>>();
assert(j.ok());  // OK because an empty option can represent the null
assert(!j->has_value());  // v held no value.

Nullness

All of the supported types (above) are "nullable". A null is created in one of two ways:

Passing an absl::optional<T>() with no value to Value's constructor.
Using the MakeNullValue<T>() helper function (defined below).

Nulls can be retrieved from a Value::get<T> by specifying the type T as an absl::optional<U>. The returned optional will either be empty (indicating null) or it will contain the actual value. See the documentation for Value::get<T> below for more details.

Spanner Arrays

Spanner arrays are represented in C++ as a std::vector<T>, where the type T may be any of the other allowed Spanner 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};
spanner::Value v(vec);
auto copy = *v.get<std::vector<std::int64_t>>();
assert(vec == copy);

Spanner Structs

Spanner structs are represented in C++ as instances of std::tuple holding zero or more of the allowed Spanner 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 Spanner STRUCT.

Spanner 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 Spanner type T.

using Struct = std::tuple<bool, std::pair<std::string, std::int64_t>>;
Struct s  = {true, {"Foo", 42}};
spanner::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 Spanner 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.

Constructors

Value()

Constructs a Value that holds nothing.

All calls to get<T>() will return an error.

Value(Value const &)

Parameter
Name	Description
	`Value const &`