google/spanner/v1/type.proto

// Copyright 2023 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

syntax = "proto3";

package google.spanner.v1;

import "google/api/field_behavior.proto";

option csharp_namespace = "Google.Cloud.Spanner.V1";
option go_package = "cloud.google.com/go/spanner/apiv1/spannerpb;spannerpb";
option java_multiple_files = true;
option java_outer_classname = "TypeProto";
option java_package = "com.google.spanner.v1";
option php_namespace = "Google\\Cloud\\Spanner\\V1";
option ruby_package = "Google::Cloud::Spanner::V1";

// `Type` indicates the type of a Cloud Spanner value, as might be stored in a
// table cell or returned from an SQL query.
message Type {
  // Required. The [TypeCode][google.spanner.v1.TypeCode] for this type.
  TypeCode code = 1 [(google.api.field_behavior) = REQUIRED];

  // If [code][google.spanner.v1.Type.code] == [ARRAY][google.spanner.v1.TypeCode.ARRAY], then `array_element_type`
  // is the type of the array elements.
  Type array_element_type = 2;

  // If [code][google.spanner.v1.Type.code] == [STRUCT][google.spanner.v1.TypeCode.STRUCT], then `struct_type`
  // provides type information for the struct's fields.
  StructType struct_type = 3;

  // The [TypeAnnotationCode][google.spanner.v1.TypeAnnotationCode] that disambiguates SQL type that Spanner will
  // use to represent values of this type during query processing. This is
  // necessary for some type codes because a single [TypeCode][google.spanner.v1.TypeCode] can be mapped
  // to different SQL types depending on the SQL dialect. [type_annotation][google.spanner.v1.Type.type_annotation]
  // typically is not needed to process the content of a value (it doesn't
  // affect serialization) and clients can ignore it on the read path.
  TypeAnnotationCode type_annotation = 4;

  // If [code][google.spanner.v1.Type.code] ==
  // [PROTO][google.spanner.v1.TypeCode.PROTO] or
  // [code][google.spanner.v1.Type.code] ==
  // [ENUM][google.spanner.v1.TypeCode.ENUM], then `proto_type_fqn` is the fully
  // qualified name of the proto type representing the proto/enum definition.
  string proto_type_fqn = 5;
}

// `StructType` defines the fields of a [STRUCT][google.spanner.v1.TypeCode.STRUCT] type.
message StructType {
  // Message representing a single field of a struct.
  message Field {
    // The name of the field. For reads, this is the column name. For
    // SQL queries, it is the column alias (e.g., `"Word"` in the
    // query `"SELECT 'hello' AS Word"`), or the column name (e.g.,
    // `"ColName"` in the query `"SELECT ColName FROM Table"`). Some
    // columns might have an empty name (e.g., `"SELECT
    // UPPER(ColName)"`). Note that a query result can contain
    // multiple fields with the same name.
    string name = 1;

    // The type of the field.
    Type type = 2;
  }

  // The list of fields that make up this struct. Order is
  // significant, because values of this struct type are represented as
  // lists, where the order of field values matches the order of
  // fields in the [StructType][google.spanner.v1.StructType]. In turn, the order of fields
  // matches the order of columns in a read request, or the order of
  // fields in the `SELECT` clause of a query.
  repeated Field fields = 1;
}

// `TypeCode` is used as part of [Type][google.spanner.v1.Type] to
// indicate the type of a Cloud Spanner value.
//
// Each legal value of a type can be encoded to or decoded from a JSON
// value, using the encodings described below. All Cloud Spanner values can
// be `null`, regardless of type; `null`s are always encoded as a JSON
// `null`.
enum TypeCode {
  // Not specified.
  TYPE_CODE_UNSPECIFIED = 0;

  // Encoded as JSON `true` or `false`.
  BOOL = 1;

  // Encoded as `string`, in decimal format.
  INT64 = 2;

  // Encoded as `number`, or the strings `"NaN"`, `"Infinity"`, or
  // `"-Infinity"`.
  FLOAT64 = 3;

  // Encoded as `number`, or the strings `"NaN"`, `"Infinity"`, or
  // `"-Infinity"`.
  FLOAT32 = 15;

  // Encoded as `string` in RFC 3339 timestamp format. The time zone
  // must be present, and must be `"Z"`.
  //
  // If the schema has the column option
  // `allow_commit_timestamp=true`, the placeholder string
  // `"spanner.commit_timestamp()"` can be used to instruct the system
  // to insert the commit timestamp associated with the transaction
  // commit.
  TIMESTAMP = 4;

  // Encoded as `string` in RFC 3339 date format.
  DATE = 5;

  // Encoded as `string`.
  STRING = 6;

  // Encoded as a base64-encoded `string`, as described in RFC 4648,
  // section 4.
  BYTES = 7;

  // Encoded as `list`, where the list elements are represented
  // according to
  // [array_element_type][google.spanner.v1.Type.array_element_type].
  ARRAY = 8;

  // Encoded as `list`, where list element `i` is represented according
  // to [struct_type.fields[i]][google.spanner.v1.StructType.fields].
  STRUCT = 9;

  // Encoded as `string`, in decimal format or scientific notation format.
  // <br>Decimal format:
  // <br>`[+-]Digits[.[Digits]]` or
  // <br>`[+-][Digits].Digits`
  //
  // Scientific notation:
  // <br>`[+-]Digits[.[Digits]][ExponentIndicator[+-]Digits]` or
  // <br>`[+-][Digits].Digits[ExponentIndicator[+-]Digits]`
  // <br>(ExponentIndicator is `"e"` or `"E"`)
  NUMERIC = 10;

  // Encoded as a JSON-formatted `string` as described in RFC 7159. The
  // following rules are applied when parsing JSON input:
  //
  // - Whitespace characters are not preserved.
  // - If a JSON object has duplicate keys, only the first key is preserved.
  // - Members of a JSON object are not guaranteed to have their order
  //   preserved.
  // - JSON array elements will have their order preserved.
  JSON = 11;

  // Encoded as a base64-encoded `string`, as described in RFC 4648,
  // section 4.
  PROTO = 13;

  // Encoded as `string`, in decimal format.
  ENUM = 14;
}

// `TypeAnnotationCode` is used as a part of [Type][google.spanner.v1.Type] to
// disambiguate SQL types that should be used for a given Cloud Spanner value.
// Disambiguation is needed because the same Cloud Spanner type can be mapped to
// different SQL types depending on SQL dialect. TypeAnnotationCode doesn't
// affect the way value is serialized.
enum TypeAnnotationCode {
  // Not specified.
  TYPE_ANNOTATION_CODE_UNSPECIFIED = 0;

  // PostgreSQL compatible NUMERIC type. This annotation needs to be applied to
  // [Type][google.spanner.v1.Type] instances having [NUMERIC][google.spanner.v1.TypeCode.NUMERIC]
  // type code to specify that values of this type should be treated as
  // PostgreSQL NUMERIC values. Currently this annotation is always needed for
  // [NUMERIC][google.spanner.v1.TypeCode.NUMERIC] when a client interacts with PostgreSQL-enabled
  // Spanner databases.
  PG_NUMERIC = 2;

  // PostgreSQL compatible JSONB type. This annotation needs to be applied to
  // [Type][google.spanner.v1.Type] instances having [JSON][google.spanner.v1.TypeCode.JSON]
  // type code to specify that values of this type should be treated as
  // PostgreSQL JSONB values. Currently this annotation is always needed for
  // [JSON][google.spanner.v1.TypeCode.JSON] when a client interacts with PostgreSQL-enabled
  // Spanner databases.
  PG_JSONB = 3;

  // PostgreSQL compatible OID type. This annotation can be used by a client
  // interacting with PostgreSQL-enabled Spanner database to specify that a
  // value should be treated using the semantics of the OID type.
  PG_OID = 4;
}