Class Value (6.66.0)

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

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)

e Returns a BYTES value. 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

float32(float v)

public static Value float32(float v)

Returns a FLOAT32 value.

Parameter
Name Description
v float
Returns
Type Description
Value

float32(Float v)

public static Value float32(Float v)

Returns a FLOAT32 value.

Parameter
Name Description
v Float

the value, which may be null

Returns
Type Description
Value

float32Array(float[] v)

public static Value float32Array(float[] v)

Returns an ARRAY<FLOAT32> value.

Parameter
Name Description
v float[]

the source of element values, which may be null to produce a value for which isNull() is true

Returns
Type Description
Value

float32Array(float[] v, int pos, int length)

public static Value float32Array(float[] v, int pos, int length)

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

Parameters
Name Description
v float[]

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

float32Array(Iterable<Float> v)

public static Value float32Array(Iterable<Float> v)

Returns an ARRAY<FLOAT32> value.

Parameter
Name Description
v Iterable<Float>

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

pgOid(Long v)

public static Value pgOid(Long v)

Returns an PG_OID value.

Parameter
Name Description
v Long

the value, which may be null

Returns
Type Description
Value

pgOid(long v)

public static Value pgOid(long v)

Returns an PG_OID value.

Parameter
Name Description
v long
Returns
Type Description
Value

pgOidArray(Iterable<Long> v)

public static Value pgOidArray(Iterable<Long> v)

Returns an ARRAY<PG_OID> 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

pgOidArray(long[] v)

public static Value pgOidArray(long[] v)

Returns an ARRAY<PG_OID> 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

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

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

Returns an ARRAY<PG_OID> 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

protoEnum(ProtocolMessageEnum v)

public static Value protoEnum(ProtocolMessageEnum v)

Return a ENUM value for not null proto messages.

Parameter
Name Description
v ProtocolMessageEnum

Proto Enum, which may be null.

Returns
Type Description
Value

protoEnum(Long v, Descriptors.EnumDescriptor enumDescriptor)

public static Value protoEnum(Long v, Descriptors.EnumDescriptor enumDescriptor)

Return a ENUM value.

Parameters
Name Description
v Long

Enum non-primitive Integer constant.

enumDescriptor EnumDescriptor

Enum Type Descriptor. Use static method from proto class * MyProtoEnum.getDescriptor().

Returns
Type Description
Value

protoEnum(Long v, String protoTypeFqn)

public static Value protoEnum(Long v, String protoTypeFqn)

Return a ENUM value.

Parameters
Name Description
v Long

Enum non-primitive Integer constant.

protoTypeFqn String

Fully qualified name of proto representing the enum definition. Use static method from proto class MyProtoEnum.getDescriptor().getFullName()

Returns
Type Description
Value

protoEnum(long v, String protoTypeFqn)

public static Value protoEnum(long v, String protoTypeFqn)

Return a ENUM value.

Parameters
Name Description
v long

Enum integer primitive constant.

protoTypeFqn String

Fully qualified name of proto representing the enum definition. Use static method from proto class MyProtoEnum.getDescriptor().getFullName()

Returns
Type Description
Value

protoEnumArray(Iterable<ProtocolMessageEnum> v, Descriptors.EnumDescriptor descriptor)

public static Value protoEnumArray(Iterable<ProtocolMessageEnum> v, Descriptors.EnumDescriptor descriptor)

Returns an ARRAY<ENUM> value.

Parameters
Name Description
v Iterable<ProtocolMessageEnum>

the source of element values. This may be null to produce a value for which isNull() is true. Individual elements may also be null.

descriptor EnumDescriptor

Proto Type Descriptor, use static method from proto class MyProtoClass.getDescriptor().

Returns
Type Description
Value

protoEnumArray(Iterable<Long> v, String protoTypeFqn)

public static Value protoEnumArray(Iterable<Long> v, String protoTypeFqn)

Returns an ARRAY<ENUM> value.

Parameters
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.

protoTypeFqn String

Fully qualified name of proto representing the enum definition. Use static method from proto class MyProtoEnum.getDescriptor().getFullName()

Returns
Type Description
Value

protoMessage(ByteArray v, Descriptors.Descriptor descriptor)

public static Value protoMessage(ByteArray v, Descriptors.Descriptor descriptor)

Return a PROTO value

Parameters
Name Description
v com.google.cloud.ByteArray

Serialized Proto Array, which may be null.

descriptor Descriptor

Proto Type Descriptor, use static method from proto class MyProtoClass.getDescriptor().

Returns
Type Description
Value

protoMessage(ByteArray v, String protoTypeFqn)

public static Value protoMessage(ByteArray v, String protoTypeFqn)

Return a PROTO value

Parameters
Name Description
v com.google.cloud.ByteArray

Serialized Proto Array, which may be null.

protoTypeFqn String

Fully qualified name of proto representing the proto definition. Use static method from proto class MyProtoClass.getDescriptor().getFullName()

Returns
Type Description
Value

protoMessage(AbstractMessage v)

public static Value protoMessage(AbstractMessage v)

Return a PROTO value for not null proto messages.

Parameter
Name Description
v AbstractMessage

Not null Proto message.

Returns
Type Description
Value

protoMessageArray(Iterable<ByteArray> v, String protoTypeFqn)

public static Value protoMessageArray(Iterable<ByteArray> v, String protoTypeFqn)

Returns an ARRAY<PROTO> value.

Parameters
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.

protoTypeFqn String

Fully qualified name of proto representing the proto definition. Use static method from proto class MyProtoClass.getDescriptor().getFullName()

Returns
Type Description
Value

protoMessageArray(Iterable<AbstractMessage> v, Descriptors.Descriptor descriptor)

public static Value protoMessageArray(Iterable<AbstractMessage> v, Descriptors.Descriptor descriptor)

Returns an ARRAY<PROTO> value.

Parameters
Name Description
v Iterable<AbstractMessage>

the source of element values. This may be null to produce a value for which isNull() is true. Individual elements may also be null.

descriptor Descriptor

Proto Type Descriptor, use static method from proto class MyProtoClass.getDescriptor().

Returns
Type Description
Value

string(String v)

public static Value string(String v)