Class Value
- All Implemented Interfaces:
Serializable
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.
- See Also:
-
Field Summary
Modifier and TypeFieldDescriptionstatic final com.google.cloud.Timestamp
Placeholder value to be passed to a mutation to make Cloud Spanner store the commit timestamp in that column.static final String
Constant to specify a PG Numeric NaN value. -
Method Summary
Modifier and TypeMethodDescriptionstatic Value
bool
(boolean v) Returns aBOOL
value.static Value
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
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
bytesArrayFromBase64
(Iterable<String> base64Strings) Returns anARRAY<BYTES>
value.static Value
bytesFromBase64
(String base64String) Returns aBYTES
value.static Value
date
(com.google.cloud.Date v) Returns aDATE
value.static Value
Returns anARRAY<DATE>
value.static Value
float64
(double v) Returns aFLOAT64
value.static Value
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
Returns anARRAY<FLOAT64>
value.Returns this value as a raw string representation.com.google.common.collect.ImmutableList<String>
Returns this value as a list of raw string representations.abstract boolean
getBool()
Returns the value of aBOOL
-typed instance.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>
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>
Returns the value of anARRAY<DATE>
-typed instance.abstract double
Returns the value of aFLOAT64
-typed instance.Returns the value of anARRAY<FLOAT64>
-typed instance.abstract long
getInt64()
Returns the value of aINT64
-typed instance.Returns the value of anARRAY<INT64>
-typed instance.getJson()
Returns the value of aJSON
-typed instance.Returns the value of anARRAY<JSON>
-typed instance.abstract BigDecimal
Returns the value of aNUMERIC
-typed instance.abstract List<BigDecimal>
Returns the value of anARRAY<NUMERIC>
-typed instance.Returns the value of aJSONB
-typed instance.Returns the value of anARRAY<JSONB>
-typed instance.abstract String
Returns the value of aSTRING
-typed instance.Returns the value of anARRAY<STRING>
-typed instance.abstract Struct
Returns the value of aSTRUCT
-typed instance.Returns the value of anARRAY<STRUCT<...>>
-typed instance.abstract com.google.cloud.Timestamp
Returns the value of aTIMESTAMP
-typed instance.abstract List<com.google.cloud.Timestamp>
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
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
Returns true if this is a commit timestamp value.abstract boolean
isNull()
Returnstrue
if this instance represents aNULL
value.static Value
Returns aJSON
value.static Value
Returns anARRAY<JSON>
value.static Value
Returns aNUMERIC
value.static Value
Returns anARRAY<NUMERIC>
value.static Value
Returns aPG JSONB
value.static Value
Returns anARRAY<JSONB>
value.static Value
Returns aPG NUMERIC
value.static Value
Returns anARRAY<PG_NUMERIC>
value.static Value
Returns aSTRING
value.static Value
Returns anARRAY<STRING>
value.static Value
Returns a non-NULL
{#code STRUCT} value.static Value
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.toString()
static Value
untyped
(com.google.protobuf.Value value) Returns aValue
that wraps the given proto value.
-
Field Details
-
COMMIT_TIMESTAMP
public static final com.google.cloud.Timestamp COMMIT_TIMESTAMPPlaceholder 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:
-
NAN
Constant to specify a PG Numeric NaN value.- See Also:
-
-
Method Details
-
untyped
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
Returns aBOOL
value.- Parameters:
v
- the value, which may be null
-
bool
Returns aBOOL
value. -
int64
Returns anINT64
value.- Parameters:
v
- the value, which may be null
-
int64
Returns anINT64
value. -
float64
Returns aFLOAT64
value.- Parameters:
v
- the value, which may be null
-
float64
Returns aFLOAT64
value. -
numeric
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
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
Returns aSTRING
value.- Parameters:
v
- the value, which may be null
-
json
Returns aJSON
value.- Parameters:
v
- the value, which may be null
-
pgJsonb
Returns aPG JSONB
value.- Parameters:
v
- the value, which may be null
-
bytes
Returns aBYTES
value.- Parameters:
v
- the value, which may be null
-
bytesFromBase64
Returns aBYTES
value.- Parameters:
base64String
- the value in Base64 encoding, which may be null. This value must be a valid base64 string.
-
timestamp
Returns aTIMESTAMP
value. -
date
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
Returns a non-NULL
{#code STRUCT} value. -
struct
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
Returns anARRAY<BOOL>
value.- Parameters:
v
- the source of element values, which may be null to produce a value for whichisNull()
istrue
-
boolArray
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
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
Returns anARRAY<INT64>
value.- Parameters:
v
- the source of element values, which may be null to produce a value for whichisNull()
istrue
-
int64Array
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
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
Returns anARRAY<FLOAT64>
value.- Parameters:
v
- the source of element values, which may be null to produce a value for whichisNull()
istrue
-
float64Array
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
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
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
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
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
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
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
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
.
-
bytesArrayFromBase64
Returns anARRAY<BYTES>
value.- Parameters:
base64Strings
- the source of element values. This may benull
to produce a value for whichisNull()
istrue
. Individual elements may also benull
. Non-null values must be a valid Base64 string.
-
timestampArray
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
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
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
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
Returns the value of aNUMERIC
-typed instance.- Throws:
IllegalStateException
- ifisNull()
or the value is not of the expected type
-
getString
Returns the value of aSTRING
-typed instance.- Throws:
IllegalStateException
- ifisNull()
or the value is not of the expected type
-
getJson
Returns the value of aJSON
-typed instance.- Throws:
IllegalStateException
- ifisNull()
or the value is not of the expected type
-
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
Returns the value of aSTRUCT
-typed instance.- Throws:
IllegalStateException
- ifisNull()
or the value is not of the expected type
-
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
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
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
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
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
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
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
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
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
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
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
-
toString
-
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.
-
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 thegetAsString()
method if you need to quote the individual elements in an array.Returns the string "NULL" for null values.
-