Class Value
- java.lang.Object
-
- com.google.cloud.spanner.Value
-
- All Implemented Interfaces:
Serializable
@Immutable public abstract class Value extends Object implements Serializable
Represents a value to be consumed by the Cloud Spanner API. A value can beNULL
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.- See Also:
- Serialized Form
-
-
Field Summary
Fields Modifier and Type Field Description static com.google.cloud.Timestamp
COMMIT_TIMESTAMP
Placeholder value to be passed to a mutation to make Cloud Spanner store the commit timestamp in that column.static String
NAN
Constant to specify a PG Numeric NaN value.
-
Method Summary
All Methods Static Methods Instance Methods Abstract Methods Concrete Methods Modifier and Type Method Description static Value
bool(boolean v)
Returns aBOOL
value.static Value
bool(Boolean v)
Returns aBOOL
value.static Value
boolArray(boolean[] v)
Returns anARRAY<BOOL>
value.static Value
boolArray(boolean[] v, int pos, int length)
Returns anARRAY<BOOL>
value that takes its elements from a region of an array.static Value
boolArray(Iterable<Boolean> v)
Returns anARRAY<BOOL>
value.static Value
bytes(com.google.cloud.ByteArray v)
Returns aBYTES
value.static Value
bytesArray(Iterable<com.google.cloud.ByteArray> v)
Returns anARRAY<BYTES>
value.static Value
date(com.google.cloud.Date v)
Returns aDATE
value.static Value
dateArray(Iterable<com.google.cloud.Date> v)
Returns anARRAY<DATE>
value.static Value
float64(double v)
Returns aFLOAT64
value.static Value
float64(Double v)
Returns aFLOAT64
value.static Value
float64Array(double[] v)
Returns anARRAY<FLOAT64>
value.static Value
float64Array(double[] v, int pos, int length)
Returns anARRAY<FLOAT64>
value that takes its elements from a region of an array.static Value
float64Array(Iterable<Double> v)
Returns anARRAY<FLOAT64>
value.abstract boolean
getBool()
Returns the value of aBOOL
-typed instance.abstract List<Boolean>
getBoolArray()
Returns the value of anARRAY<BOOL>
-typed instance.abstract com.google.cloud.ByteArray
getBytes()
Returns the value of aBYTES
-typed instance.abstract List<com.google.cloud.ByteArray>
getBytesArray()
Returns the value of anARRAY<BYTES>
-typed instance.abstract com.google.cloud.Date
getDate()
Returns the value of aDATE
-typed instance.abstract List<com.google.cloud.Date>
getDateArray()
Returns the value of anARRAY<DATE>
-typed instance.abstract double
getFloat64()
Returns the value of aFLOAT64
-typed instance.abstract List<Double>
getFloat64Array()
Returns the value of anARRAY<FLOAT64>
-typed instance.abstract long
getInt64()
Returns the value of aINT64
-typed instance.abstract List<Long>
getInt64Array()
Returns the value of anARRAY<INT64>
-typed instance.String
getJson()
Returns the value of aJSON
-typed instance.List<String>
getJsonArray()
Returns the value of anARRAY<JSON>
-typed instance.abstract BigDecimal
getNumeric()
Returns the value of aNUMERIC
-typed instance.abstract List<BigDecimal>
getNumericArray()
Returns the value of anARRAY<NUMERIC>
-typed instance.String
getPgJsonb()
Returns the value of aJSONB
-typed instance.List<String>
getPgJsonbArray()
Returns the value of anARRAY<JSONB>
-typed instance.abstract String
getString()
Returns the value of aSTRING
-typed instance.abstract List<String>
getStringArray()
Returns the value of anARRAY<STRING>
-typed instance.abstract Struct
getStruct()
Returns the value of aSTRUCT
-typed instance.abstract List<Struct>
getStructArray()
Returns the value of anARRAY<STRUCT<...>>
-typed instance.abstract com.google.cloud.Timestamp
getTimestamp()
Returns the value of aTIMESTAMP
-typed instance.abstract List<com.google.cloud.Timestamp>
getTimestampArray()
Returns the value of anARRAY<TIMESTAMP>
-typed instance.abstract Type
getType()
Returns the type of this value.static Value
int64(long v)
Returns anINT64
value.static Value
int64(Long v)
Returns anINT64
value.static Value
int64Array(long[] v)
Returns anARRAY<INT64>
value.static Value
int64Array(long[] v, int pos, int length)
Returns anARRAY<INT64>
value that takes its elements from a region of an array.static Value
int64Array(Iterable<Long> v)
Returns anARRAY<INT64>
value.abstract boolean
isCommitTimestamp()
Returns true if this is a commit timestamp value.abstract boolean
isNull()
Returnstrue
if this instance represents aNULL
value.static Value
json(String v)
Returns aJSON
value.static Value
jsonArray(Iterable<String> v)
Returns anARRAY<JSON>
value.static Value
numeric(BigDecimal v)
Returns aNUMERIC
value.static Value
numericArray(Iterable<BigDecimal> v)
Returns anARRAY<NUMERIC>
value.static Value
pgJsonb(String v)
Returns aPG JSONB
value.static Value
pgJsonbArray(Iterable<String> v)
Returns anARRAY<JSONB>
value.static Value
pgNumeric(String v)
Returns aPG NUMERIC
value.static Value
pgNumericArray(Iterable<String> v)
Returns anARRAY<PG_NUMERIC>
value.static Value
string(String v)
Returns aSTRING
value.static Value
stringArray(Iterable<String> v)
Returns anARRAY<STRING>
value.static Value
struct(Struct v)
Returns a non-NULL
{#code STRUCT} value.static Value
struct(Type type, Struct v)
Returns aSTRUCT
value ofType
type.static Value
structArray(Type elementType, Iterable<Struct> v)
Returns anARRAY<STRUCT<...>>
value.static Value
timestamp(com.google.cloud.Timestamp v)
Returns aTIMESTAMP
value.static Value
timestampArray(Iterable<com.google.cloud.Timestamp> v)
Returns anARRAY<TIMESTAMP>
value.String
toString()
static Value
untyped(com.google.protobuf.Value value)
Returns aValue
that wraps the given proto value.
-
-
-
Field Detail
-
COMMIT_TIMESTAMP
public static final com.google.cloud.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
-
NAN
public static final String NAN
Constant to specify a PG Numeric NaN value.- See Also:
- Constant Field Values
-
-
Method Detail
-
untyped
public static Value untyped(com.google.protobuf.Value value)
Returns aValue
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.- Parameters:
value
- the non-null proto value (aNullValue
is allowed)
-
bool
public static Value bool(@Nullable Boolean v)
Returns aBOOL
value.- Parameters:
v
- the value, which may be null
-
bool
public static Value bool(boolean v)
Returns aBOOL
value.
-
int64
public static Value int64(@Nullable Long v)
Returns anINT64
value.- Parameters:
v
- the value, which may be null
-
int64
public static Value int64(long v)
Returns anINT64
value.
-
float64
public static Value float64(@Nullable Double v)
Returns aFLOAT64
value.- Parameters:
v
- the value, which may be null
-
float64
public static Value float64(double v)
Returns aFLOAT64
value.
-
numeric
public static Value numeric(@Nullable BigDecimal v)
Returns aNUMERIC
value. The valid value range for the whole component of theBigDecimal
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.- Parameters:
v
- the value, which may be null
-
pgNumeric
public static Value pgNumeric(@Nullable String v)
Returns aPG NUMERIC
value. This value has flexible precision and scale which is specified in the Database DDL. This value also supportsNaNs
, which can be specified withValue.pgNumeric(Value.NAN)
or simply asValue.pgNumeric("NaN")
.Note that this flavour of numeric is different than Spanner numerics (
numeric(BigDecimal)
). It should be used only for handling numerics in the PostgreSQL dialect.- Parameters:
v
- the value, which may be null
-
string
public static Value string(@Nullable String v)
Returns aSTRING
value.- Parameters:
v
- the value, which may be null
-
json
public static Value json(@Nullable String v)
Returns aJSON
value.- Parameters:
v
- the value, which may be null
-
pgJsonb
public static Value pgJsonb(@Nullable String v)
Returns aPG JSONB
value.- Parameters:
v
- the value, which may be null
-
bytes
public static Value bytes(@Nullable com.google.cloud.ByteArray v)
Returns aBYTES
value.- Parameters:
v
- the value, which may be null
-
timestamp
public static Value timestamp(@Nullable com.google.cloud.Timestamp v)
Returns aTIMESTAMP
value.
-
date
public static Value date(@Nullable com.google.cloud.Date v)
Returns aDATE
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.
-
struct
public static Value struct(Type type, @Nullable Struct v)
Returns aSTRUCT
value ofType
type.- Parameters:
type
- the type of theSTRUCT
valuev
- the structSTRUCT
value. This may benull
to produce a value for whichisNull()
istrue
. If non-null
,StructReader.getType()
must match type.
-
boolArray
public static Value boolArray(@Nullable boolean[] v)
Returns anARRAY<BOOL>
value.- Parameters:
v
- the source of element values, which may be null to produce a value for whichisNull()
istrue
-
boolArray
public static Value boolArray(@Nullable boolean[] v, int pos, int length)
Returns anARRAY<BOOL>
value that takes its elements from a region of an array.- Parameters:
v
- the source of element values, which may be null to produce a value for whichisNull()
istrue
pos
- the start position ofv
to copy values from. Ignored ifv
isnull
.length
- the number of values to copy fromv
. Ignored ifv
isnull
.
-
boolArray
public static Value boolArray(@Nullable Iterable<Boolean> v)
Returns anARRAY<BOOL>
value.- Parameters:
v
- the source of element values. This may benull
to produce a value for whichisNull()
istrue
. Individual elements may also benull
.
-
int64Array
public static Value int64Array(@Nullable long[] v)
Returns anARRAY<INT64>
value.- Parameters:
v
- the source of element values, which may be null to produce a value for whichisNull()
istrue
-
int64Array
public static Value int64Array(@Nullable long[] v, int pos, int length)
Returns anARRAY<INT64>
value that takes its elements from a region of an array.- Parameters:
v
- the source of element values, which may be null to produce a value for whichisNull()
istrue
pos
- the start position ofv
to copy values from. Ignored ifv
isnull
.length
- the number of values to copy fromv
. Ignored ifv
isnull
.
-
int64Array
public static Value int64Array(@Nullable Iterable<Long> v)
Returns anARRAY<INT64>
value.- Parameters:
v
- the source of element values. This may benull
to produce a value for whichisNull()
istrue
. Individual elements may also benull
.
-
float64Array
public static Value float64Array(@Nullable double[] v)
Returns anARRAY<FLOAT64>
value.- Parameters:
v
- the source of element values, which may be null to produce a value for whichisNull()
istrue
-
float64Array
public static Value float64Array(@Nullable double[] v, int pos, int length)
Returns anARRAY<FLOAT64>
value that takes its elements from a region of an array.- Parameters:
v
- the source of element values, which may be null to produce a value for whichisNull()
istrue
pos
- the start position ofv
to copy values from. Ignored ifv
isnull
.length
- the number of values to copy fromv
. Ignored ifv
isnull
.
-
float64Array
public static Value float64Array(@Nullable Iterable<Double> v)
Returns anARRAY<FLOAT64>
value.- Parameters:
v
- the source of element values. This may benull
to produce a value for whichisNull()
istrue
. Individual elements may also benull
.
-
numericArray
public static Value numericArray(@Nullable Iterable<BigDecimal> v)
Returns anARRAY<NUMERIC>
value.- Parameters:
v
- the source of element values. This may benull
to produce a value for whichisNull()
istrue
. Individual elements may also benull
.
-
pgNumericArray
public static Value pgNumericArray(@Nullable Iterable<String> v)
Returns anARRAY<PG_NUMERIC>
value.- Parameters:
v
- the source of element values. This may benull
to produce a value for whichisNull()
istrue
. Individual elements may also benull
. Individual elements may be"NaN"
orNAN
.
-
stringArray
public static Value stringArray(@Nullable Iterable<String> v)
Returns anARRAY<STRING>
value.- Parameters:
v
- the source of element values. This may benull
to produce a value for whichisNull()
istrue
. Individual elements may also benull
.
-
jsonArray
public static Value jsonArray(@Nullable Iterable<String> v)
Returns anARRAY<JSON>
value.- Parameters:
v
- the source of element values. This may benull
to produce a value for whichisNull()
istrue
. Individual elements may also benull
.
-
pgJsonbArray
public static Value pgJsonbArray(@Nullable Iterable<String> v)
Returns anARRAY<JSONB>
value.- Parameters:
v
- the source of element values. This may benull
to produce a value for whichisNull()
istrue
. Individual elements may also benull
.
-
bytesArray
public static Value bytesArray(@Nullable Iterable<com.google.cloud.ByteArray> v)
Returns anARRAY<BYTES>
value.- Parameters:
v
- the source of element values. This may benull
to produce a value for whichisNull()
istrue
. Individual elements may also benull
.
-
timestampArray
public static Value timestampArray(@Nullable Iterable<com.google.cloud.Timestamp> v)
Returns anARRAY<TIMESTAMP>
value.- Parameters:
v
- the source of element values. This may benull
to produce a value for whichisNull()
istrue
. Individual elements may also benull
.
-
dateArray
public static Value dateArray(@Nullable Iterable<com.google.cloud.Date> v)
Returns anARRAY<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.- Parameters:
v
- the source of element values. This may benull
to produce a value for whichisNull()
istrue
. Individual elements may also benull
.
-
structArray
public static Value structArray(Type elementType, @Nullable Iterable<Struct> v)
Returns anARRAY<STRUCT<...>>
value.- Parameters:
elementType
-v
- the source of element values. This may benull
to produce a value for whichisNull()
istrue
. Individual elements may also benull
.
-
getType
public abstract Type getType()
Returns the type of this value. This will return a type even ifisNull()
is true.
-
isNull
public abstract boolean isNull()
Returnstrue
if this instance represents aNULL
value.
-
getBool
public abstract boolean getBool()
Returns the value of aBOOL
-typed instance.- Throws:
IllegalStateException
- ifisNull()
or the value is not of the expected type
-
getInt64
public abstract long getInt64()
Returns the value of aINT64
-typed instance.- Throws:
IllegalStateException
- ifisNull()
or the value is not of the expected type
-
getFloat64
public abstract double getFloat64()
Returns the value of aFLOAT64
-typed instance.- Throws:
IllegalStateException
- ifisNull()
or the value is not of the expected type
-
getNumeric
public abstract BigDecimal getNumeric()
Returns the value of aNUMERIC
-typed instance.- Throws:
IllegalStateException
- ifisNull()
or the value is not of the expected type
-
getString
public abstract String getString()
Returns the value of aSTRING
-typed instance.- Throws:
IllegalStateException
- ifisNull()
or the value is not of the expected type
-
getJson
public String getJson()
Returns the value of aJSON
-typed instance.- Throws:
IllegalStateException
- ifisNull()
or the value is not of the expected type
-
getPgJsonb
public String getPgJsonb()
Returns the value of aJSONB
-typed instance.- Throws:
IllegalStateException
- ifisNull()
or the value is not of the expected type
-
getBytes
public abstract com.google.cloud.ByteArray getBytes()
Returns the value of aBYTES
-typed instance.- Throws:
IllegalStateException
- ifisNull()
or the value is not of the expected type
-
getTimestamp
public abstract com.google.cloud.Timestamp getTimestamp()
Returns the value of aTIMESTAMP
-typed instance.- Throws:
IllegalStateException
- ifisNull()
or the value is not of the expected type orisCommitTimestamp()
.
-
isCommitTimestamp
public abstract boolean isCommitTimestamp()
Returns true if this is a commit timestamp value.
-
getDate
public abstract com.google.cloud.Date getDate()
Returns the value of aDATE
-typed instance.- Throws:
IllegalStateException
- ifisNull()
or the value is not of the expected type
-
getStruct
public abstract Struct getStruct()
Returns the value of aSTRUCT
-typed instance.- Throws:
IllegalStateException
- ifisNull()
or the value is not of the expected type
-
getBoolArray
public abstract List<Boolean> getBoolArray()
Returns the value of anARRAY<BOOL>
-typed instance. While the returned list itself will never benull
, elements of that list may be null.- Throws:
IllegalStateException
- ifisNull()
or the value is not of the expected type
-
getInt64Array
public abstract List<Long> getInt64Array()
Returns the value of anARRAY<INT64>
-typed instance. While the returned list itself will never benull
, elements of that list may be null.- Throws:
IllegalStateException
- ifisNull()
or the value is not of the expected type
-
getFloat64Array
public abstract List<Double> getFloat64Array()
Returns the value of anARRAY<FLOAT64>
-typed instance. While the returned list itself will never benull
, elements of that list may be null.- Throws:
IllegalStateException
- ifisNull()
or the value is not of the expected type
-
getNumericArray
public abstract List<BigDecimal> getNumericArray()
Returns the value of anARRAY<NUMERIC>
-typed instance. While the returned list itself will never benull
, elements of that list may be null.- Throws:
IllegalStateException
- ifisNull()
or the value is not of the expected type
-
getStringArray
public abstract List<String> getStringArray()
Returns the value of anARRAY<STRING>
-typed instance. While the returned list itself will never benull
, elements of that list may be null.- Throws:
IllegalStateException
- ifisNull()
or the value is not of the expected type
-
getJsonArray
public List<String> getJsonArray()
Returns the value of anARRAY<JSON>
-typed instance. While the returned list itself will never benull
, elements of that list may be null.- Throws:
IllegalStateException
- ifisNull()
or the value is not of the expected type
-
getPgJsonbArray
public List<String> getPgJsonbArray()
Returns the value of anARRAY<JSONB>
-typed instance. While the returned list itself will never benull
, elements of that list may be null.- Throws:
IllegalStateException
- ifisNull()
or the value is not of the expected type
-
getBytesArray
public abstract List<com.google.cloud.ByteArray> getBytesArray()
Returns the value of anARRAY<BYTES>
-typed instance. While the returned list itself will never benull
, elements of that list may be null.- Throws:
IllegalStateException
- ifisNull()
or the value is not of the expected type
-
getTimestampArray
public abstract List<com.google.cloud.Timestamp> getTimestampArray()
Returns the value of anARRAY<TIMESTAMP>
-typed instance. While the returned list itself will never benull
, elements of that list may be null.- Throws:
IllegalStateException
- ifisNull()
or the value is not of the expected type
-
getDateArray
public abstract List<com.google.cloud.Date> getDateArray()
Returns the value of anARRAY<DATE>
-typed instance. While the returned list itself will never benull
, elements of that list may be null.- Throws:
IllegalStateException
- ifisNull()
or the value is not of the expected type
-
getStructArray
public abstract List<Struct> getStructArray()
Returns the value of anARRAY<STRUCT<...>>
-typed instance. While the returned list itself will never benull
, elements of that list may be null.- Throws:
IllegalStateException
- ifisNull()
or the value is not of the expected type
-
-