Class Value (6.50.1)

public abstract class Value implements Serializable

Represents a value to be consumed by the Cloud Spanner API. A value can be NULL or non-NULL; regardless, values always have an associated type.

The Value API is optimized for construction, since this is the majority use-case when using this class with the Cloud Spanner libraries. The factory method signatures and internal representations are design to minimize memory usage and object creation while still maintaining the immutability contract of this class. In particular, arrays of primitive types can be constructed without requiring boxing into collections of wrapper types. The getters in this class are intended primarily for test purposes, and so do not share the same performance characteristics; in particular, getters for array types may be expensive.

Value instances are immutable.

Inheritance

java.lang.Object > Value

Implements

Serializable

Inherited Members

Object.clone()

Object.equals(Object)

Object.finalize()

Object.getClass()

Object.hashCode()

Object.notify()

Object.notifyAll()

Object.toString()

Object.wait()

Object.wait(long)

Object.wait(long,int)

Static Fields

COMMIT_TIMESTAMP

public static final Timestamp COMMIT_TIMESTAMP

Placeholder value to be passed to a mutation to make Cloud Spanner store the commit timestamp in that column. The commit timestamp is the timestamp corresponding to when Cloud Spanner commits the transaction containing the mutation.

Note that this particular timestamp instance has no semantic meaning. In particular the value of seconds and nanoseconds in this timestamp are meaningless. This placeholder can only be used for columns that have set the option "(allow_commit_timestamp=true)" in the schema.

When reading the value stored in such a column, the value returned is an actual timestamp corresponding to the commit time of the transaction, which has no relation to this placeholder. See Also: Transaction Semantics

Field Value
Type	Description
`com.google.cloud.Timestamp`

NAN

public static final String NAN

Constant to specify a PG Numeric NaN value.

Field Value
Type	Description
`String`

Static Methods

bool(boolean v)

public static Value bool(boolean v)

Returns a BOOL value.

Parameter
Name	Description
`v`	`boolean`

Returns
Type	Description
`Value`

bool(Boolean v)

public static Value bool(Boolean v)

Returns a BOOL value.

Parameter
Name	Description
`v`	`Boolean` the value, which may be null

Returns
Type	Description
`Value`

boolArray(boolean[] v)

public static Value boolArray(boolean[] v)

Returns an ARRAY<BOOL> value.

Parameter
Name	Description
`v`	`boolean[]` the source of element values, which may be null to produce a value for which `isNull()` is `true`

Returns
Type	Description
`Value`

boolArray(boolean[] v, int pos, int length)

public static Value boolArray(boolean[] v, int pos, int length)

Returns an ARRAY<BOOL> value that takes its elements from a region of an array.

Parameters
Name	Description
`v`	`boolean[]` the source of element values, which may be null to produce a value for which `isNull()` is `true`
`pos`	`int` the start position of `v` to copy values from. Ignored if `v` is `null`.
`length`	`int` the number of values to copy from `v`. Ignored if `v` is `null`.

Returns
Type	Description
`Value`

boolArray(Iterable<Boolean> v)

public static Value boolArray(Iterable<Boolean> v)

Returns an ARRAY<BOOL> value.

Parameter
Name	Description
`v`	`Iterable<Boolean>` the source of element values. This may be `null` to produce a value for which `isNull()` is `true`. Individual elements may also be `null`.

Returns
Type	Description
`Value`

bytes(ByteArray v)

public static Value bytes(ByteArray v)

Returns a BYTES value.

Parameter
Name	Description
`v`	`com.google.cloud.ByteArray` the value, which may be null

Returns
Type	Description
`Value`

bytesArray(Iterable<ByteArray> v)

public static Value bytesArray(Iterable<ByteArray> v)

Returns an ARRAY<BYTES> value.

Parameter
Name	Description
`v`	`Iterable<com.google.cloud.ByteArray>` the source of element values. This may be `null` to produce a value for which `isNull()` is `true`. Individual elements may also be `null`.

Returns
Type	Description
`Value`

bytesArrayFromBase64(Iterable<String> base64Strings)

public static Value bytesArrayFromBase64(Iterable<String> base64Strings)

Returns an ARRAY<BYTES> value.

Parameter
Name	Description
`base64Strings`	`Iterable<String>` the source of element values. This may be `null` to produce a value for which `isNull()` is `true`. Individual elements may also be `null`. Non-null values must be a valid Base64 string.

Returns
Type	Description
`Value`

bytesFromBase64(String base64String)

public static Value bytesFromBase64(String base64String)

Returns a BYTES value.

Parameter
Name	Description
`base64String`	`String` the value in Base64 encoding, which may be null. This value must be a valid base64 string.

Returns
Type	Description
`Value`

date(Date v)

public static Value date(Date v)

Returns a DATE value. The range [1678-01-01, 2262-01-01) is the legal interval for cloud spanner dates. A write to a date column is rejected if the value is outside of that interval.

Parameter
Name	Description
`v`	`com.google.cloud.Date`

Returns
Type	Description
`Value`

dateArray(Iterable<Date> v)

public static Value dateArray(Iterable<Date> v)

Returns an ARRAY<DATE> value. The range [1678-01-01, 2262-01-01) is the legal interval for cloud spanner dates. A write to a date column is rejected if the value is outside of that interval.

Parameter
Name	Description
`v`	`Iterable<com.google.cloud.Date>` the source of element values. This may be `null` to produce a value for which `isNull()` is `true`. Individual elements may also be `null`.

Returns
Type	Description
`Value`

float64(double v)

public static Value float64(double v)

Returns a FLOAT64 value.

Parameter
Name	Description
`v`	`double`

Returns
Type	Description
`Value`

float64(Double v)

public static Value float64(Double v)

Returns a FLOAT64 value.

Parameter
Name	Description
`v`	`Double` the value, which may be null

Returns
Type	Description
`Value`

float64Array(double[] v)

public static Value float64Array(double[] v)

Returns an ARRAY<FLOAT64> value.

Parameter
Name	Description
`v`	`double[]` the source of element values, which may be null to produce a value for which `isNull()` is `true`

Returns
Type	Description
`Value`

float64Array(double[] v, int pos, int length)

public static Value float64Array(double[] v, int pos, int length)

Returns an ARRAY<FLOAT64> value that takes its elements from a region of an array.

Parameters
Name	Description
`v`	`double[]` the source of element values, which may be null to produce a value for which `isNull()` is `true`
`pos`	`int` the start position of `v` to copy values from. Ignored if `v` is `null`.
`length`	`int` the number of values to copy from `v`. Ignored if `v` is `null`.

Returns
Type	Description
`Value`

float64Array(Iterable<Double> v)

public static Value float64Array(Iterable<Double> v)

Returns an ARRAY<FLOAT64> value.

Parameter
Name	Description
`v`	`Iterable<Double>` the source of element values. This may be `null` to produce a value for which `isNull()` is `true`. Individual elements may also be `null`.

Returns
Type	Description
`Value`

int64(Long v)

public static Value int64(Long v)

Returns an INT64 value.

Parameter
Name	Description
`v`	`Long` the value, which may be null

Returns
Type	Description
`Value`

int64(long v)

public static Value int64(long v)

Returns an INT64 value.

Parameter
Name	Description
`v`	`long`

Returns
Type	Description
`Value`

int64Array(Iterable<Long> v)

public static Value int64Array(Iterable<Long> v)

Returns an ARRAY<INT64> value.

Parameter
Name	Description
`v`	`Iterable<Long>` the source of element values. This may be `null` to produce a value for which `isNull()` is `true`. Individual elements may also be `null`.

Returns
Type	Description
`Value`

int64Array(long[] v)

public static Value int64Array(long[] v)

Returns an ARRAY<INT64> value.

Parameter
Name	Description
`v`	`long[]` the source of element values, which may be null to produce a value for which `isNull()` is `true`

Returns
Type	Description
`Value`

int64Array(long[] v, int pos, int length)

public static Value int64Array(long[] v, int pos, int length)

Returns an ARRAY<INT64> value that takes its elements from a region of an array.

Parameters
Name	Description
`v`	`long[]` the source of element values, which may be null to produce a value for which `isNull()` is `true`
`pos`	`int` the start position of `v` to copy values from. Ignored if `v` is `null`.
`length`	`int` the number of values to copy from `v`. Ignored if `v` is `null`.

Returns
Type	Description
`Value`

json(String v)

public static Value json(String v)

Returns a JSON value.

Parameter
Name	Description
`v`	`String` the value, which may be null

Returns
Type	Description
`Value`

jsonArray(Iterable<String> v)

public static Value jsonArray(Iterable<String> v)

Returns an ARRAY<JSON> value.

Parameter
Name	Description
`v`	`Iterable<String>` the source of element values. This may be `null` to produce a value for which `isNull()` is `true`. Individual elements may also be `null`.

Returns
Type	Description
`Value`

numeric(BigDecimal v)

public static Value numeric(BigDecimal v)

Returns a NUMERIC value. The valid value range for the whole component of the BigDecimal is from -9,999,999,999,999,999,999,999,999 to +9,999,999,999,999,999,999,999,999 (both inclusive), i.e. the max length of the whole component is 29 digits. The max length of the fractional part is 9 digits. Trailing zeros in the fractional part are not considered and will be lost, as Cloud Spanner does not preserve the precision of a numeric value.

If you set a numeric value of a record to for example 0.10, Cloud Spanner will return this value as 0.1 in subsequent queries. Use BigDecimal#stripTrailingZeros() to compare inserted values with retrieved values if your application might insert numeric values with trailing zeros.

Parameter
Name	Description
`v`	`BigDecimal` the value, which may be null

Returns
Type	Description
`Value`

numericArray(Iterable<BigDecimal> v)

public static Value numericArray(Iterable<BigDecimal> v)

Returns an ARRAY<NUMERIC> value.

Parameter
Name	Description
`v`	`Iterable<BigDecimal>` the source of element values. This may be `null` to produce a value for which `isNull()` is `true`. Individual elements may also be `null`.

Returns
Type	Description
`Value`

pgJsonb(String v)

public static Value pgJsonb(String v)

Returns a PG JSONB value.

Parameter
Name	Description
`v`	`String` the value, which may be null

Returns
Type	Description
`Value`

pgJsonbArray(Iterable<String> v)

public static Value pgJsonbArray(Iterable<String> v)

Returns an ARRAY<JSONB> value.

Parameter
Name	Description
`v`	`Iterable<String>` the source of element values. This may be `null` to produce a value for which `isNull()` is `true`. Individual elements may also be `null`.

Returns
Type	Description
`Value`

pgNumeric(String v)

public static Value pgNumeric(String v)

Returns a PG NUMERIC value. This value has flexible precision and scale which is specified in the Database DDL. This value also supports NaNs, which can be specified with Value.pgNumeric(Value.NAN) or simply as Value.pgNumeric("NaN").

Note that this flavour of numeric is different than Spanner numerics (Value#numeric(BigDecimal)). It should be used only for handling numerics in the PostgreSQL dialect.

Parameter
Name	Description
`v`	`String` the value, which may be null

Returns
Type	Description
`Value`

pgNumericArray(Iterable<String> v)

public static Value pgNumericArray(Iterable<String> v)

Returns an ARRAY<PG_NUMERIC> value.

Parameter
Name	Description
`v`	`Iterable<String>` the source of element values. This may be `null` to produce a value for which `isNull()` is `true`. Individual elements may also be `null`. Individual elements may be `"NaN"` or Value#NAN.

Returns
Type	Description
`Value`

string(String v)

public static Value string(String v)

Returns a STRING value.

Parameter
Name	Description
`v`	`String` the value, which may be null

Returns
Type	Description
`Value`

stringArray(Iterable<String> v)

public static Value stringArray(Iterable<String> v)

Returns an ARRAY<STRING> value.

Parameter
Name	Description
`v`	`Iterable<String>` the source of element values. This may be `null` to produce a value for which `isNull()` is `true`. Individual elements may also be `null`.

Returns
Type	Description
`Value`

struct(Struct v)

public static Value struct(Struct v)

Returns a non-NULL {#code STRUCT} value.

Parameter
Name	Description
`v`	`Struct`

Returns
Type	Description
`Value`

struct(Type type, Struct v)

public static Value struct(Type type, Struct v)

Returns a STRUCT value of Type type.

Parameters
Name	Description
`type`	`Type` the type of the `STRUCT` value
`v`	`Struct` the struct `STRUCT` value. This may be `null` to produce a value for which `isNull()` is `true`. If non-`null`, Struct#getType() must match type.

Returns
Type	Description
`Value`

structArray(Type elementType, Iterable<Struct> v)

public static Value structArray(Type elementType, Iterable<Struct> v)

Returns an ARRAY<STRUCT<...>> value.

Parameters
Name	Description
`elementType`	`Type`
`v`	`Iterable<Struct>` the source of element values. This may be `null` to produce a value for which `isNull()` is `true`. Individual elements may also be `null`.

Returns
Type	Description
`Value`

timestamp(Timestamp v)

public static Value timestamp(Timestamp v)

Returns a TIMESTAMP value.

Parameter
Name	Description
`v`	`com.google.cloud.Timestamp`

Returns
Type	Description
`Value`

timestampArray(Iterable<Timestamp> v)

public static Value timestampArray(Iterable<Timestamp> v)

Returns an ARRAY<TIMESTAMP> value.

Parameter
Name	Description
`v`	`Iterable<com.google.cloud.Timestamp>` the source of element values. This may be `null` to produce a value for which `isNull()` is `true`. Individual elements may also be `null`.

Returns
Type	Description
`Value`

untyped(Value value)

public static Value untyped(Value value)

Returns a Value that wraps the given proto value. This can be used to construct a value without a specific type, and let the backend infer the type based on the statement where it is used.

Parameter
Name	Description
`value`	`Value` the non-null proto value (a NullValue is allowed)

Returns
Type	Description
`Value`

Methods

getAsString()

public String getAsString()

Returns this value as a raw string representation. This is guaranteed to work for all values, regardless of the underlying data type, and is guaranteed not to be truncated.

Returns the string "NULL" for null values.

Returns
Type	Description
`String`

getAsStringList()

public ImmutableList<String> getAsStringList()

Returns this value as a list of raw string representations. This is guaranteed to work for all values, regardless of the underlying data type, and the strings are guaranteed not to be truncated. The method returns a singleton list for non-array values and a list containing as many elements as there are in the array for array values. This method can be used instead of the #getAsString() method if you need to quote the individual elements in an array.

Returns the string "NULL" for null values.

Returns
Type	Description
`com.google.common.collect.ImmutableList<String>`

getBool()

public abstract boolean getBool()

Returns the value of a BOOL-typed instance.

Returns
Type	Description
`boolean`

getBoolArray()

public abstract List<Boolean> getBoolArray()

Returns the value of an ARRAY<BOOL>-typed instance. While the returned list itself will never be null, elements of that list may be null.

Returns
Type	Description
`List<Boolean>`

getBytes()

public abstract ByteArray getBytes()

Returns the value of a BYTES-typed instance.

Returns
Type	Description
`com.google.cloud.ByteArray`

getBytesArray()

public abstract List<ByteArray> getBytesArray()

Returns the value of an ARRAY<BYTES>-typed instance. While the returned list itself will never be null, elements of that list may be null.

Returns
Type	Description
`List<com.google.cloud.ByteArray>`

getDate()

public abstract Date getDate()

Returns the value of a DATE-typed instance.

Returns
Type	Description
`com.google.cloud.Date`

getDateArray()

public abstract List<Date> getDateArray()

Returns the value of an ARRAY<DATE>-typed instance. While the returned list itself will never be null, elements of that list may be null.

Returns
Type	Description
`List<com.google.cloud.Date>`

getFloat64()

public abstract double getFloat64()

Returns the value of a FLOAT64-typed instance.

Returns
Type	Description
`double`

getFloat64Array()

public abstract List<Double> getFloat64Array()

Returns the value of an ARRAY<FLOAT64>-typed instance. While the returned list itself will never be null, elements of that list may be null.

Returns
Type	Description
`List<Double>`

getInt64()

public abstract long getInt64()

Returns the value of a INT64-typed instance.

Returns
Type	Description
`long`

getInt64Array()

public abstract List<Long> getInt64Array()

Returns the value of an ARRAY<INT64>-typed instance. While the returned list itself will never be null, elements of that list may be null.

Returns
Type	Description
`List<Long>`

getJson()

public String getJson()

Returns the value of a JSON-typed instance.

Returns
Type	Description
`String`

getJsonArray()

public List<String> getJsonArray()

Returns the value of an ARRAY<JSON>-typed instance. While the returned list itself will never be null, elements of that list may be null.

Returns
Type	Description
`List<String>`

getNumeric()

public abstract BigDecimal getNumeric()

Returns the value of a NUMERIC-typed instance.

Returns
Type	Description
`BigDecimal`

getNumericArray()

public abstract List<BigDecimal> getNumericArray()

Returns the value of an ARRAY<NUMERIC>-typed instance. While the returned list itself will never be null, elements of that list may be null.

Returns
Type	Description
`List<BigDecimal>`

getPgJsonb()

public String getPgJsonb()

Returns the value of a JSONB-typed instance.

Returns
Type	Description
`String`

getPgJsonbArray()

public List<String> getPgJsonbArray()

Returns the value of an ARRAY<JSONB>-typed instance. While the returned list itself will never be null, elements of that list may be null.

Returns
Type	Description
`List<String>`

getString()

public abstract String getString()

Returns the value of a STRING-typed instance.

Returns
Type	Description
`String`

getStringArray()

public abstract List<String> getStringArray()

Returns the value of an ARRAY<STRING>-typed instance. While the returned list itself will never be null, elements of that list may be null.

Returns
Type	Description
`List<String>`

getStruct()

public abstract Struct getStruct()

Returns the value of a STRUCT-typed instance.

Returns
Type	Description
`Struct`

getStructArray()

public abstract List<Struct> getStructArray()

Returns the value of an ARRAY<STRUCT<...>>-typed instance. While the returned list itself will never be null, elements of that list may be null.

Returns
Type	Description
`List<Struct>`

getTimestamp()

public abstract Timestamp getTimestamp()

Returns the value of a TIMESTAMP-typed instance.

Returns
Type	Description
`com.google.cloud.Timestamp`

getTimestampArray()

public abstract List<Timestamp> getTimestampArray()

Returns the value of an ARRAY<TIMESTAMP>-typed instance. While the returned list itself will never be null, elements of that list may be null.

Returns
Type	Description
`List<com.google.cloud.Timestamp>`

getType()

public abstract Type getType()

Returns the type of this value. This will return a type even if isNull() is true.

Returns
Type	Description
`Type`

isCommitTimestamp()

public abstract boolean isCommitTimestamp()

Returns true if this is a commit timestamp value.

Returns
Type	Description
`boolean`

isNull()

public abstract boolean isNull()

Returns true if this instance represents a NULL value.

Returns
Type	Description
`boolean`

toString()

public String toString()

Returns
Type	Description
`String`

Overrides

Object.toString()