Package com.google.cloud.spanner

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

See Also:

  • Field Details

    • 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:

    • NAN

      public static final String NAN
      Constant to specify a PG Numeric NaN value.
      See Also:

  • Method Details

    • untyped

      public static Value untyped(com.google.protobuf.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.
      Parameters:
      value - the non-null proto value (a NullValue is allowed)

    • bool

      public static Value bool(@Nullable Boolean v)
      Returns a BOOL value.
      Parameters:
      v - the value, which may be null

    • bool

      public static Value bool(boolean v)
      Returns a BOOL value.

    • int64

      public static Value int64(@Nullable Long v)
      Returns an INT64 value.
      Parameters:
      v - the value, which may be null

    • int64

      public static Value int64(long v)
      Returns an INT64 value.

    • float64

      public static Value float64(@Nullable Double v)
      Returns a FLOAT64 value.
      Parameters:
      v - the value, which may be null

    • float64

      public static Value float64(double v)
      Returns a FLOAT64 value.

    • numeric

      public static Value numeric(@Nullable 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.

      Parameters:
      v - the value, which may be null

    • pgNumeric

      public static Value pgNumeric(@Nullable 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 (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 a STRING value.
      Parameters:
      v - the value, which may be null

    • json

      public static Value json(@Nullable String v)
      Returns a JSON value.
      Parameters:
      v - the value, which may be null

    • pgJsonb

      public static Value pgJsonb(@Nullable String v)
      Returns a PG JSONB value.
      Parameters:
      v - the value, which may be null

    • protoMessage

      public static Value protoMessage(com.google.protobuf.AbstractMessage v)
      Return a PROTO value for not null proto messages.
      Parameters:
      v - Not null Proto message.

    • protoMessage

      public static Value protoMessage(@Nullable com.google.cloud.ByteArray v, String protoTypeFqn)
      Return a PROTO value
      Parameters:
      v - Serialized Proto Array, which may be null.
      protoTypeFqn - Fully qualified name of proto representing the proto definition. Use static method from proto class MyProtoClass.getDescriptor().getFullName()

    • protoMessage

      public static Value protoMessage(@Nullable com.google.cloud.ByteArray v, com.google.protobuf.Descriptors.Descriptor descriptor)
      Return a PROTO value
      Parameters:
      v - Serialized Proto Array, which may be null.
      descriptor - Proto Type Descriptor, use static method from proto class MyProtoClass.getDescriptor().

    • protoEnum

      public static Value protoEnum(com.google.protobuf.ProtocolMessageEnum v)
      Return a ENUM value for not null proto messages.
      Parameters:
      v - Proto Enum, which may be null.

    • protoEnum

      public static Value protoEnum(@Nullable Long v, String protoTypeFqn)
      Return a ENUM value.
      Parameters:
      v - Enum non-primitive Integer constant.
      protoTypeFqn - Fully qualified name of proto representing the enum definition. Use static method from proto class MyProtoEnum.getDescriptor().getFullName()

    • protoEnum

      public static Value protoEnum(@Nullable Long v, com.google.protobuf.Descriptors.EnumDescriptor enumDescriptor)
      Return a ENUM value.
      Parameters:
      v - Enum non-primitive Integer constant.
      enumDescriptor - Enum Type Descriptor. Use static method from proto class * MyProtoEnum.getDescriptor().

    • protoEnum

      public static Value protoEnum(long v, String protoTypeFqn)
      Return a ENUM value.
      Parameters:
      v - Enum integer primitive constant.
      protoTypeFqn - Fully qualified name of proto representing the enum definition. Use static method from proto class MyProtoEnum.getDescriptor().getFullName()

    • bytes

      public static Value bytes(@Nullable com.google.cloud.ByteArray v)
      e Returns a BYTES value. Returns a BYTES value.
      Parameters:
      v - the value, which may be null

    • bytesFromBase64

      public static Value bytesFromBase64(@Nullable String base64String)
      Returns a BYTES value.
      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 a TIMESTAMP value.

    • date

      public static Value date(@Nullable com.google.cloud.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.

    • struct

      public static Value struct(Struct v)
      Returns a non-NULL {#code STRUCT} value.

    • struct

      public static Value struct(Type type, @Nullable Struct v)
      Returns a STRUCT value of Type type.
      Parameters:
      type - the type of the STRUCT value
      v - the struct STRUCT value. This may be null to produce a value for which isNull() is true. If non-null, StructReader.getType() must match type.

    • boolArray

      public static Value boolArray(@Nullable boolean[] v)
      Returns an ARRAY<BOOL> value.
      Parameters:
      v - the source of element values, which may be null to produce a value for which isNull() is true

    • boolArray

      public static Value boolArray(@Nullable boolean[] v, int pos, int length)
      Returns an ARRAY<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 which isNull() is true
      pos - the start position of v to copy values from. Ignored if v is null.
      length - the number of values to copy from v. Ignored if v is null.

    • boolArray

      public static Value boolArray(@Nullable Iterable<Boolean> v)
      Returns an ARRAY<BOOL> value.
      Parameters:
      v - the source of element values. This may be null to produce a value for which isNull() is true. Individual elements may also be null.

    • int64Array

      public static Value int64Array(@Nullable long[] v)
      Returns an ARRAY<INT64> value.
      Parameters:
      v - the source of element values, which may be null to produce a value for which isNull() is true

    • int64Array

      public static Value int64Array(@Nullable long[] v, int pos, int length)
      Returns an ARRAY<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 which isNull() is true
      pos - the start position of v to copy values from. Ignored if v is null.
      length - the number of values to copy from v. Ignored if v is null.

    • int64Array

      public static Value int64Array(@Nullable Iterable<Long> v)
      Returns an ARRAY<INT64> value.
      Parameters:
      v - the source of element values. This may be null to produce a value for which isNull() is true. Individual elements may also be null.

    • float64Array

      public static Value float64Array(@Nullable double[] v)
      Returns an ARRAY<FLOAT64> value.
      Parameters:
      v - the source of element values, which may be null to produce a value for which isNull() is true

    • float64Array

      public static Value float64Array(@Nullable double[] v, int pos, int length)
      Returns an ARRAY<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 which isNull() is true
      pos - the start position of v to copy values from. Ignored if v is null.
      length - the number of values to copy from v. Ignored if v is null.

    • float64Array

      public static Value float64Array(@Nullable Iterable<Double> v)
      Returns an ARRAY<FLOAT64> value.
      Parameters:
      v - the source of element values. This may be null to produce a value for which isNull() is true. Individual elements may also be null.

    • numericArray

      public static Value numericArray(@Nullable Iterable<BigDecimal> v)
      Returns an ARRAY<NUMERIC> value.
      Parameters:
      v - the source of element values. This may be null to produce a value for which isNull() is true. Individual elements may also be null.

    • pgNumericArray

      public static Value pgNumericArray(@Nullable Iterable<String> v)
      Returns an ARRAY<PG_NUMERIC> value.
      Parameters:
      v - 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 NAN.

    • stringArray

      public static Value stringArray(@Nullable Iterable<String> v)
      Returns an ARRAY<STRING> value.
      Parameters:
      v - the source of element values. This may be null to produce a value for which isNull() is true. Individual elements may also be null.

    • jsonArray

      public static Value jsonArray(@Nullable Iterable<String> v)
      Returns an ARRAY<JSON> value.
      Parameters:
      v - the source of element values. This may be null to produce a value for which isNull() is true. Individual elements may also be null.

    • pgJsonbArray

      public static Value pgJsonbArray(@Nullable Iterable<String> v)
      Returns an ARRAY<JSONB> value.
      Parameters:
      v - the source of element values. This may be null to produce a value for which isNull() is true. Individual elements may also be null.

    • protoMessageArray

      public static Value protoMessageArray(@Nullable Iterable<com.google.protobuf.AbstractMessage> v, com.google.protobuf.Descriptors.Descriptor descriptor)
      Returns an ARRAY<PROTO> value.
      Parameters:
      v - 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 - Proto Type Descriptor, use static method from proto class MyProtoClass.getDescriptor().

    • protoMessageArray

      public static Value protoMessageArray(@Nullable Iterable<com.google.cloud.ByteArray> v, String protoTypeFqn)
      Returns an ARRAY<PROTO> value.
      Parameters:
      v - 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 - Fully qualified name of proto representing the proto definition. Use static method from proto class MyProtoClass.getDescriptor().getFullName()

    • protoEnumArray

      public static Value protoEnumArray(@Nullable Iterable<com.google.protobuf.ProtocolMessageEnum> v, com.google.protobuf.Descriptors.EnumDescriptor descriptor)
      Returns an ARRAY<ENUM> value.
      Parameters:
      v - 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 - Proto Type Descriptor, use static method from proto class MyProtoClass.getDescriptor().

    • protoEnumArray

      public static Value protoEnumArray(@Nullable Iterable<Long> v, String protoTypeFqn)
      Returns an ARRAY<ENUM> value.
      Parameters:
      v - 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 - Fully qualified name of proto representing the enum definition. Use static method from proto class MyProtoEnum.getDescriptor().getFullName()

    • bytesArray

      public static Value bytesArray(@Nullable Iterable<com.google.cloud.ByteArray> v)
      Returns an ARRAY<BYTES> value.
      Parameters:
      v - the source of element values. This may be null to produce a value for which isNull() is true. Individual elements may also be null.

    • bytesArrayFromBase64

      public static Value bytesArrayFromBase64(@Nullable Iterable<String> base64Strings)
      Returns an ARRAY<BYTES> value.
      Parameters:
      base64Strings - 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.

    • timestampArray

      public static Value timestampArray(@Nullable Iterable<com.google.cloud.Timestamp> v)
      Returns an ARRAY<TIMESTAMP> value.
      Parameters:
      v - the source of element values. This may be null to produce a value for which isNull() is true. Individual elements may also be null.

    • dateArray

      public static Value dateArray(@Nullable Iterable<com.google.cloud.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.
      Parameters:
      v - the source of element values. This may be null to produce a value for which isNull() is true. Individual elements may also be null.

    • structArray

      public static Value structArray(Type elementType, @Nullable Iterable<Struct> v)
      Returns an ARRAY<STRUCT<...>> value.
      Parameters:
      elementType -
      v - the source of element values. This may be null to produce a value for which isNull() is true. Individual elements may also be null.

    • getType

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

    • isNull

      public abstract boolean isNull()
      Returns true if this instance represents a NULL value.

    • getBool

      public abstract boolean getBool()
      Returns the value of a BOOL-typed instance.
      Throws:
      IllegalStateException - if isNull() or the value is not of the expected type

    • getInt64

      public abstract long getInt64()
      Returns the value of a INT64-typed instance.
      Throws:
      IllegalStateException - if isNull() or the value is not of the expected type

    • getFloat64

      public abstract double getFloat64()
      Returns the value of a FLOAT64-typed instance.
      Throws:
      IllegalStateException - if isNull() or the value is not of the expected type

    • getNumeric

      public abstract BigDecimal getNumeric()
      Returns the value of a NUMERIC-typed instance.
      Throws:
      IllegalStateException - if isNull() or the value is not of the expected type

    • getString

      public abstract String getString()
      Returns the value of a STRING-typed instance.
      Throws:
      IllegalStateException - if isNull() or the value is not of the expected type

    • getJson

      public String getJson()
      Returns the value of a JSON-typed instance.
      Throws:
      IllegalStateException - if isNull() or the value is not of the expected type

    • getPgJsonb

      public String getPgJsonb()
      Returns the value of a JSONB-typed instance.
      Throws:
      IllegalStateException - if isNull() or the value is not of the expected type

    • getProtoMessage

      public <T extends com.google.protobuf.AbstractMessage> T getProtoMessage(T m)
      Returns the value of a PROTO-typed instance.
      Throws:
      IllegalStateException - if isNull() or the value is not of the expected type

    • getProtoEnum

      public <T extends com.google.protobuf.ProtocolMessageEnum> T getProtoEnum(Function<Integer,com.google.protobuf.ProtocolMessageEnum> method)
      Returns the value of a ENUM-typed instance.
      Throws:
      IllegalStateException - if isNull() or the value is not of the expected type

    • getBytes

      public abstract com.google.cloud.ByteArray getBytes()
      Returns the value of a BYTES-typed instance.
      Throws:
      IllegalStateException - if isNull() or the value is not of the expected type

    • getTimestamp

      public abstract com.google.cloud.Timestamp getTimestamp()
      Returns the value of a TIMESTAMP-typed instance.
      Throws:
      IllegalStateException - if isNull() or the value is not of the expected type or isCommitTimestamp().

    • 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 a DATE-typed instance.
      Throws:
      IllegalStateException - if isNull() or the value is not of the expected type

    • getStruct

      public abstract Struct getStruct()
      Returns the value of a STRUCT-typed instance.
      Throws:
      IllegalStateException - if isNull() or the value is not of the expected type

    • 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.
      Throws:
      IllegalStateException - if isNull() or the value is not of the expected type

    • 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.
      Throws:
      IllegalStateException - if isNull() or the value is not of the expected type

    • 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.
      Throws:
      IllegalStateException - if isNull() or the value is not of the expected type

    • 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.
      Throws:
      IllegalStateException - if isNull() or the value is not of the expected type

    • 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.
      Throws:
      IllegalStateException - if isNull() or the value is not of the expected type

    • 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.
      Throws:
      IllegalStateException - if isNull() or the value is not of the expected type

    • 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.
      Throws:
      IllegalStateException - if isNull() or the value is not of the expected type

    • getProtoMessageArray

      public <T extends com.google.protobuf.AbstractMessage> List<T> getProtoMessageArray(T m)
      Returns the value of an ARRAY<PROTO>-typed instance. While the returned list itself will never be null, elements of that list may be null.
      Throws:
      IllegalStateException - if isNull() or the value is not of the expected type

    • getProtoEnumArray

      public <T extends com.google.protobuf.ProtocolMessageEnum> List<T> getProtoEnumArray(Function<Integer,com.google.protobuf.ProtocolMessageEnum> method)
      Returns the value of an ARRAY<ENUM>-typed instance. While the returned list itself will never be null, elements of that list may be null.
      Throws:
      IllegalStateException - if isNull() or the value is not of the expected type

    • getBytesArray

      public abstract List<com.google.cloud.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.
      Throws:
      IllegalStateException - if isNull() or the value is not of the expected type

    • getTimestampArray

      public abstract List<com.google.cloud.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.
      Throws:
      IllegalStateException - if isNull() or the value is not of the expected type

    • getDateArray

      public abstract List<com.google.cloud.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.
      Throws:
      IllegalStateException - if isNull() or the value is not of the expected type

    • 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.
      Throws:
      IllegalStateException - if isNull() or the value is not of the expected type

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • 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 the getAsString() method if you need to quote the individual elements in an array.

      Returns the string "NULL" for null values.