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 beNULLor non-NULL; regardless, values always have an associated type.The
ValueAPI 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.Valueinstances are immutable.- See Also:
- Serialized Form
-
-
Field Summary
Fields Modifier and Type Field Description static com.google.cloud.TimestampCOMMIT_TIMESTAMPPlaceholder value to be passed to a mutation to make Cloud Spanner store the commit timestamp in that column.static StringNANConstant 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 Valuebool(boolean v)Returns aBOOLvalue.static Valuebool(Boolean v)Returns aBOOLvalue.static ValueboolArray(boolean[] v)Returns anARRAY<BOOL>value.static ValueboolArray(boolean[] v, int pos, int length)Returns anARRAY<BOOL>value that takes its elements from a region of an array.static ValueboolArray(Iterable<Boolean> v)Returns anARRAY<BOOL>value.static Valuebytes(com.google.cloud.ByteArray v)Returns aBYTESvalue.static ValuebytesArray(Iterable<com.google.cloud.ByteArray> v)Returns anARRAY<BYTES>value.static ValuebytesArrayFromBase64(Iterable<String> base64Strings)Returns anARRAY<BYTES>value.static ValuebytesFromBase64(String base64String)Returns aBYTESvalue.static Valuedate(com.google.cloud.Date v)Returns aDATEvalue.static ValuedateArray(Iterable<com.google.cloud.Date> v)Returns anARRAY<DATE>value.static Valuefloat64(double v)Returns aFLOAT64value.static Valuefloat64(Double v)Returns aFLOAT64value.static Valuefloat64Array(double[] v)Returns anARRAY<FLOAT64>value.static Valuefloat64Array(double[] v, int pos, int length)Returns anARRAY<FLOAT64>value that takes its elements from a region of an array.static Valuefloat64Array(Iterable<Double> v)Returns anARRAY<FLOAT64>value.StringgetAsString()Returns this value as a raw string representation.com.google.common.collect.ImmutableList<String>getAsStringList()Returns this value as a list of raw string representations.abstract booleangetBool()Returns the value of aBOOL-typed instance.abstract List<Boolean>getBoolArray()Returns the value of anARRAY<BOOL>-typed instance.abstract com.google.cloud.ByteArraygetBytes()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.DategetDate()Returns the value of aDATE-typed instance.abstract List<com.google.cloud.Date>getDateArray()Returns the value of anARRAY<DATE>-typed instance.abstract doublegetFloat64()Returns the value of aFLOAT64-typed instance.abstract List<Double>getFloat64Array()Returns the value of anARRAY<FLOAT64>-typed instance.abstract longgetInt64()Returns the value of aINT64-typed instance.abstract List<Long>getInt64Array()Returns the value of anARRAY<INT64>-typed instance.StringgetJson()Returns the value of aJSON-typed instance.List<String>getJsonArray()Returns the value of anARRAY<JSON>-typed instance.abstract BigDecimalgetNumeric()Returns the value of aNUMERIC-typed instance.abstract List<BigDecimal>getNumericArray()Returns the value of anARRAY<NUMERIC>-typed instance.StringgetPgJsonb()Returns the value of aJSONB-typed instance.List<String>getPgJsonbArray()Returns the value of anARRAY<JSONB>-typed instance.abstract StringgetString()Returns the value of aSTRING-typed instance.abstract List<String>getStringArray()Returns the value of anARRAY<STRING>-typed instance.abstract StructgetStruct()Returns the value of aSTRUCT-typed instance.abstract List<Struct>getStructArray()Returns the value of anARRAY<STRUCT<...>>-typed instance.abstract com.google.cloud.TimestampgetTimestamp()Returns the value of aTIMESTAMP-typed instance.abstract List<com.google.cloud.Timestamp>getTimestampArray()Returns the value of anARRAY<TIMESTAMP>-typed instance.abstract TypegetType()Returns the type of this value.static Valueint64(long v)Returns anINT64value.static Valueint64(Long v)Returns anINT64value.static Valueint64Array(long[] v)Returns anARRAY<INT64>value.static Valueint64Array(long[] v, int pos, int length)Returns anARRAY<INT64>value that takes its elements from a region of an array.static Valueint64Array(Iterable<Long> v)Returns anARRAY<INT64>value.abstract booleanisCommitTimestamp()Returns true if this is a commit timestamp value.abstract booleanisNull()Returnstrueif this instance represents aNULLvalue.static Valuejson(String v)Returns aJSONvalue.static ValuejsonArray(Iterable<String> v)Returns anARRAY<JSON>value.static Valuenumeric(BigDecimal v)Returns aNUMERICvalue.static ValuenumericArray(Iterable<BigDecimal> v)Returns anARRAY<NUMERIC>value.static ValuepgJsonb(String v)Returns aPG JSONBvalue.static ValuepgJsonbArray(Iterable<String> v)Returns anARRAY<JSONB>value.static ValuepgNumeric(String v)Returns aPG NUMERICvalue.static ValuepgNumericArray(Iterable<String> v)Returns anARRAY<PG_NUMERIC>value.static Valuestring(String v)Returns aSTRINGvalue.static ValuestringArray(Iterable<String> v)Returns anARRAY<STRING>value.static Valuestruct(Struct v)Returns a non-NULL{#code STRUCT} value.static Valuestruct(Type type, Struct v)Returns aSTRUCTvalue ofTypetype.static ValuestructArray(Type elementType, Iterable<Struct> v)Returns anARRAY<STRUCT<...>>value.static Valuetimestamp(com.google.cloud.Timestamp v)Returns aTIMESTAMPvalue.static ValuetimestampArray(Iterable<com.google.cloud.Timestamp> v)Returns anARRAY<TIMESTAMP>value.StringtoString()static Valueuntyped(com.google.protobuf.Value value)Returns aValuethat 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 aValuethat 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 (aNullValueis allowed)
-
bool
public static Value bool(@Nullable Boolean v)
Returns aBOOLvalue.- Parameters:
v- the value, which may be null
-
bool
public static Value bool(boolean v)
Returns aBOOLvalue.
-
int64
public static Value int64(@Nullable Long v)
Returns anINT64value.- Parameters:
v- the value, which may be null
-
int64
public static Value int64(long v)
Returns anINT64value.
-
float64
public static Value float64(@Nullable Double v)
Returns aFLOAT64value.- Parameters:
v- the value, which may be null
-
float64
public static Value float64(double v)
Returns aFLOAT64value.
-
numeric
public static Value numeric(@Nullable BigDecimal v)
Returns aNUMERICvalue. The valid value range for the whole component of theBigDecimalis 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 NUMERICvalue. 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 aSTRINGvalue.- Parameters:
v- the value, which may be null
-
json
public static Value json(@Nullable String v)
Returns aJSONvalue.- Parameters:
v- the value, which may be null
-
pgJsonb
public static Value pgJsonb(@Nullable String v)
Returns aPG JSONBvalue.- Parameters:
v- the value, which may be null
-
bytes
public static Value bytes(@Nullable com.google.cloud.ByteArray v)
Returns aBYTESvalue.- Parameters:
v- the value, which may be null
-
bytesFromBase64
public static Value bytesFromBase64(@Nullable String base64String)
Returns aBYTESvalue.- Parameters:
base64String- the value in Base64 encoding, which may be null. This value must be a valid base64 string.
-
timestamp
public static Value timestamp(@Nullable com.google.cloud.Timestamp v)
Returns aTIMESTAMPvalue.
-
date
public static Value date(@Nullable com.google.cloud.Date v)
Returns aDATEvalue. 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 aSTRUCTvalue ofTypetype.- Parameters:
type- the type of theSTRUCTvaluev- the structSTRUCTvalue. This may benullto 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()istruepos- the start position ofvto copy values from. Ignored ifvisnull.length- the number of values to copy fromv. Ignored ifvisnull.
-
boolArray
public static Value boolArray(@Nullable Iterable<Boolean> v)
Returns anARRAY<BOOL>value.- Parameters:
v- the source of element values. This may benullto 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()istruepos- the start position ofvto copy values from. Ignored ifvisnull.length- the number of values to copy fromv. Ignored ifvisnull.
-
int64Array
public static Value int64Array(@Nullable Iterable<Long> v)
Returns anARRAY<INT64>value.- Parameters:
v- the source of element values. This may benullto 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()istruepos- the start position ofvto copy values from. Ignored ifvisnull.length- the number of values to copy fromv. Ignored ifvisnull.
-
float64Array
public static Value float64Array(@Nullable Iterable<Double> v)
Returns anARRAY<FLOAT64>value.- Parameters:
v- the source of element values. This may benullto 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 benullto 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 benullto 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 benullto 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 benullto 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 benullto 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 benullto produce a value for whichisNull()istrue. Individual elements may also benull.
-
bytesArrayFromBase64
public static Value bytesArrayFromBase64(@Nullable Iterable<String> base64Strings)
Returns anARRAY<BYTES>value.- Parameters:
base64Strings- the source of element values. This may benullto produce a value for whichisNull()istrue. Individual elements may also benull. Non-null values must be a valid Base64 string.
-
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 benullto 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 benullto 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 benullto 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()
Returnstrueif this instance represents aNULLvalue.
-
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
-
getAsString
@Nonnull 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.
-
getAsStringList
@Nonnull public com.google.common.collect.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 thegetAsString()method if you need to quote the individual elements in an array.Returns the string "NULL" for null values.
-
-