1// Copyright 2023 Google LLC 2// 3// Licensed under the Apache License, Version 2.0 (the "License"); 4// you may not use this file except in compliance with the License. 5// You may obtain a copy of the License at 6// 7// http://www.apache.org/licenses/LICENSE-2.0 8// 9// Unless required by applicable law or agreed to in writing, software 10// distributed under the License is distributed on an "AS IS" BASIS, 11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12// See the License for the specific language governing permissions and 13// limitations under the License. 14 15syntax = "proto3"; 16 17package google.spanner.v1; 18 19import "google/api/field_behavior.proto"; 20 21option csharp_namespace = "Google.Cloud.Spanner.V1"; 22option go_package = "cloud.google.com/go/spanner/apiv1/spannerpb;spannerpb"; 23option java_multiple_files = true; 24option java_outer_classname = "TypeProto"; 25option java_package = "com.google.spanner.v1"; 26option php_namespace = "Google\\Cloud\\Spanner\\V1"; 27option ruby_package = "Google::Cloud::Spanner::V1"; 28 29// `Type` indicates the type of a Cloud Spanner value, as might be stored in a 30// table cell or returned from an SQL query. 31message Type { 32 // Required. The [TypeCode][google.spanner.v1.TypeCode] for this type. 33 TypeCode code = 1 [(google.api.field_behavior) = REQUIRED]; 34 35 // If [code][google.spanner.v1.Type.code] == [ARRAY][google.spanner.v1.TypeCode.ARRAY], then `array_element_type` 36 // is the type of the array elements. 37 Type array_element_type = 2; 38 39 // If [code][google.spanner.v1.Type.code] == [STRUCT][google.spanner.v1.TypeCode.STRUCT], then `struct_type` 40 // provides type information for the struct's fields. 41 StructType struct_type = 3; 42 43 // The [TypeAnnotationCode][google.spanner.v1.TypeAnnotationCode] that disambiguates SQL type that Spanner will 44 // use to represent values of this type during query processing. This is 45 // necessary for some type codes because a single [TypeCode][google.spanner.v1.TypeCode] can be mapped 46 // to different SQL types depending on the SQL dialect. [type_annotation][google.spanner.v1.Type.type_annotation] 47 // typically is not needed to process the content of a value (it doesn't 48 // affect serialization) and clients can ignore it on the read path. 49 TypeAnnotationCode type_annotation = 4; 50 51 // If [code][google.spanner.v1.Type.code] == 52 // [PROTO][google.spanner.v1.TypeCode.PROTO] or 53 // [code][google.spanner.v1.Type.code] == 54 // [ENUM][google.spanner.v1.TypeCode.ENUM], then `proto_type_fqn` is the fully 55 // qualified name of the proto type representing the proto/enum definition. 56 string proto_type_fqn = 5; 57} 58 59// `StructType` defines the fields of a [STRUCT][google.spanner.v1.TypeCode.STRUCT] type. 60message StructType { 61 // Message representing a single field of a struct. 62 message Field { 63 // The name of the field. For reads, this is the column name. For 64 // SQL queries, it is the column alias (e.g., `"Word"` in the 65 // query `"SELECT 'hello' AS Word"`), or the column name (e.g., 66 // `"ColName"` in the query `"SELECT ColName FROM Table"`). Some 67 // columns might have an empty name (e.g., `"SELECT 68 // UPPER(ColName)"`). Note that a query result can contain 69 // multiple fields with the same name. 70 string name = 1; 71 72 // The type of the field. 73 Type type = 2; 74 } 75 76 // The list of fields that make up this struct. Order is 77 // significant, because values of this struct type are represented as 78 // lists, where the order of field values matches the order of 79 // fields in the [StructType][google.spanner.v1.StructType]. In turn, the order of fields 80 // matches the order of columns in a read request, or the order of 81 // fields in the `SELECT` clause of a query. 82 repeated Field fields = 1; 83} 84 85// `TypeCode` is used as part of [Type][google.spanner.v1.Type] to 86// indicate the type of a Cloud Spanner value. 87// 88// Each legal value of a type can be encoded to or decoded from a JSON 89// value, using the encodings described below. All Cloud Spanner values can 90// be `null`, regardless of type; `null`s are always encoded as a JSON 91// `null`. 92enum TypeCode { 93 // Not specified. 94 TYPE_CODE_UNSPECIFIED = 0; 95 96 // Encoded as JSON `true` or `false`. 97 BOOL = 1; 98 99 // Encoded as `string`, in decimal format. 100 INT64 = 2; 101 102 // Encoded as `number`, or the strings `"NaN"`, `"Infinity"`, or 103 // `"-Infinity"`. 104 FLOAT64 = 3; 105 106 // Encoded as `number`, or the strings `"NaN"`, `"Infinity"`, or 107 // `"-Infinity"`. 108 FLOAT32 = 15; 109 110 // Encoded as `string` in RFC 3339 timestamp format. The time zone 111 // must be present, and must be `"Z"`. 112 // 113 // If the schema has the column option 114 // `allow_commit_timestamp=true`, the placeholder string 115 // `"spanner.commit_timestamp()"` can be used to instruct the system 116 // to insert the commit timestamp associated with the transaction 117 // commit. 118 TIMESTAMP = 4; 119 120 // Encoded as `string` in RFC 3339 date format. 121 DATE = 5; 122 123 // Encoded as `string`. 124 STRING = 6; 125 126 // Encoded as a base64-encoded `string`, as described in RFC 4648, 127 // section 4. 128 BYTES = 7; 129 130 // Encoded as `list`, where the list elements are represented 131 // according to 132 // [array_element_type][google.spanner.v1.Type.array_element_type]. 133 ARRAY = 8; 134 135 // Encoded as `list`, where list element `i` is represented according 136 // to [struct_type.fields[i]][google.spanner.v1.StructType.fields]. 137 STRUCT = 9; 138 139 // Encoded as `string`, in decimal format or scientific notation format. 140 // <br>Decimal format: 141 // <br>`[+-]Digits[.[Digits]]` or 142 // <br>`[+-][Digits].Digits` 143 // 144 // Scientific notation: 145 // <br>`[+-]Digits[.[Digits]][ExponentIndicator[+-]Digits]` or 146 // <br>`[+-][Digits].Digits[ExponentIndicator[+-]Digits]` 147 // <br>(ExponentIndicator is `"e"` or `"E"`) 148 NUMERIC = 10; 149 150 // Encoded as a JSON-formatted `string` as described in RFC 7159. The 151 // following rules are applied when parsing JSON input: 152 // 153 // - Whitespace characters are not preserved. 154 // - If a JSON object has duplicate keys, only the first key is preserved. 155 // - Members of a JSON object are not guaranteed to have their order 156 // preserved. 157 // - JSON array elements will have their order preserved. 158 JSON = 11; 159 160 // Encoded as a base64-encoded `string`, as described in RFC 4648, 161 // section 4. 162 PROTO = 13; 163 164 // Encoded as `string`, in decimal format. 165 ENUM = 14; 166} 167 168// `TypeAnnotationCode` is used as a part of [Type][google.spanner.v1.Type] to 169// disambiguate SQL types that should be used for a given Cloud Spanner value. 170// Disambiguation is needed because the same Cloud Spanner type can be mapped to 171// different SQL types depending on SQL dialect. TypeAnnotationCode doesn't 172// affect the way value is serialized. 173enum TypeAnnotationCode { 174 // Not specified. 175 TYPE_ANNOTATION_CODE_UNSPECIFIED = 0; 176 177 // PostgreSQL compatible NUMERIC type. This annotation needs to be applied to 178 // [Type][google.spanner.v1.Type] instances having [NUMERIC][google.spanner.v1.TypeCode.NUMERIC] 179 // type code to specify that values of this type should be treated as 180 // PostgreSQL NUMERIC values. Currently this annotation is always needed for 181 // [NUMERIC][google.spanner.v1.TypeCode.NUMERIC] when a client interacts with PostgreSQL-enabled 182 // Spanner databases. 183 PG_NUMERIC = 2; 184 185 // PostgreSQL compatible JSONB type. This annotation needs to be applied to 186 // [Type][google.spanner.v1.Type] instances having [JSON][google.spanner.v1.TypeCode.JSON] 187 // type code to specify that values of this type should be treated as 188 // PostgreSQL JSONB values. Currently this annotation is always needed for 189 // [JSON][google.spanner.v1.TypeCode.JSON] when a client interacts with PostgreSQL-enabled 190 // Spanner databases. 191 PG_JSONB = 3; 192 193 // PostgreSQL compatible OID type. This annotation can be used by a client 194 // interacting with PostgreSQL-enabled Spanner database to specify that a 195 // value should be treated using the semantics of the OID type. 196 PG_OID = 4; 197} 198