@google-cloud/spanner-api 0.1.0

package/build/protos/google/spanner/v1/mutation.proto

@@ -0,0 +1,156 @@
+// Copyright 2026 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";
+import "google/protobuf/struct.proto";
+import "google/protobuf/timestamp.proto";
+import "google/spanner/v1/keys.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 = "MutationProto";
+option java_package = "com.google.spanner.v1";
+option php_namespace = "Google\\Cloud\\Spanner\\V1";
+option ruby_package = "Google::Cloud::Spanner::V1";
+
+// A modification to one or more Cloud Spanner rows.  Mutations can be
+// applied to a Cloud Spanner database by sending them in a
+// [Commit][google.spanner.v1.Spanner.Commit] call.
+message Mutation {
+  // Arguments to [insert][google.spanner.v1.Mutation.insert],
+  // [update][google.spanner.v1.Mutation.update],
+  // [insert_or_update][google.spanner.v1.Mutation.insert_or_update], and
+  // [replace][google.spanner.v1.Mutation.replace] operations.
+  message Write {
+    // Required. The table whose rows will be written.
+    string table = 1 [(google.api.field_behavior) = REQUIRED];
+
+    // The names of the columns in
+    // [table][google.spanner.v1.Mutation.Write.table] to be written.
+    //
+    // The list of columns must contain enough columns to allow
+    // Cloud Spanner to derive values for all primary key columns in the
+    // row(s) to be modified.
+    repeated string columns = 2;
+
+    // The values to be written. `values` can contain more than one
+    // list of values. If it does, then multiple rows are written, one
+    // for each entry in `values`. Each list in `values` must have
+    // exactly as many entries as there are entries in
+    // [columns][google.spanner.v1.Mutation.Write.columns] above. Sending
+    // multiple lists is equivalent to sending multiple `Mutation`s, each
+    // containing one `values` entry and repeating
+    // [table][google.spanner.v1.Mutation.Write.table] and
+    // [columns][google.spanner.v1.Mutation.Write.columns]. Individual values in
+    // each list are encoded as described [here][google.spanner.v1.TypeCode].
+    repeated google.protobuf.ListValue values = 3;
+  }
+
+  // Arguments to [delete][google.spanner.v1.Mutation.delete] operations.
+  message Delete {
+    // Required. The table whose rows will be deleted.
+    string table = 1 [(google.api.field_behavior) = REQUIRED];
+
+    // Required. The primary keys of the rows within
+    // [table][google.spanner.v1.Mutation.Delete.table] to delete.  The primary
+    // keys must be specified in the order in which they appear in the `PRIMARY
+    // KEY()` clause of the table's equivalent DDL statement (the DDL statement
+    // used to create the table). Delete is idempotent. The transaction will
+    // succeed even if some or all rows do not exist.
+    KeySet key_set = 2 [(google.api.field_behavior) = REQUIRED];
+  }
+
+  // Arguments to [send][google.spanner.v1.Mutation.send] operations.
+  message Send {
+    // Required. The queue to which the message will be sent.
+    string queue = 1 [(google.api.field_behavior) = REQUIRED];
+
+    // Required. The primary key of the message to be sent.
+    google.protobuf.ListValue key = 2 [(google.api.field_behavior) = REQUIRED];
+
+    // The time at which Spanner will begin attempting to deliver the message.
+    // If `deliver_time` is not set, Spanner will deliver the message
+    // immediately. If `deliver_time` is in the past, Spanner will replace it
+    // with a value closer to the current time.
+    google.protobuf.Timestamp deliver_time = 3;
+
+    // The payload of the message.
+    google.protobuf.Value payload = 4;
+  }
+
+  // Arguments to [ack][google.spanner.v1.Mutation.ack] operations.
+  message Ack {
+    // Required. The queue where the message to be acked is stored.
+    string queue = 1 [(google.api.field_behavior) = REQUIRED];
+
+    // Required. The primary key of the message to be acked.
+    google.protobuf.ListValue key = 2 [(google.api.field_behavior) = REQUIRED];
+
+    // By default, an attempt to ack a message that does not exist will fail
+    // with a `NOT_FOUND` error. With `ignore_not_found` set to true, the ack
+    // will succeed even if the message does not exist. This is useful for
+    // unconditionally acking a message, even if it is missing or has already
+    // been acked.
+    bool ignore_not_found = 3;
+  }
+
+  // Required. The operation to perform.
+  oneof operation {
+    // Insert new rows in a table. If any of the rows already exist,
+    // the write or transaction fails with error `ALREADY_EXISTS`.
+    Write insert = 1;
+
+    // Update existing rows in a table. If any of the rows does not
+    // already exist, the transaction fails with error `NOT_FOUND`.
+    Write update = 2;
+
+    // Like [insert][google.spanner.v1.Mutation.insert], except that if the row
+    // already exists, then its column values are overwritten with the ones
+    // provided. Any column values not explicitly written are preserved.
+    //
+    // When using
+    // [insert_or_update][google.spanner.v1.Mutation.insert_or_update], just as
+    // when using [insert][google.spanner.v1.Mutation.insert], all `NOT NULL`
+    // columns in the table must be given a value. This holds true even when the
+    // row already exists and will therefore actually be updated.
+    Write insert_or_update = 3;
+
+    // Like [insert][google.spanner.v1.Mutation.insert], except that if the row
+    // already exists, it is deleted, and the column values provided are
+    // inserted instead. Unlike
+    // [insert_or_update][google.spanner.v1.Mutation.insert_or_update], this
+    // means any values not explicitly written become `NULL`.
+    //
+    // In an interleaved table, if you create the child table with the
+    // `ON DELETE CASCADE` annotation, then replacing a parent row
+    // also deletes the child rows. Otherwise, you must delete the
+    // child rows before you replace the parent row.
+    Write replace = 4;
+
+    // Delete rows from a table. Succeeds whether or not the named
+    // rows were present.
+    Delete delete = 5;
+
+    // Send a message to a queue.
+    Send send = 6;
+
+    // Ack a message from a queue.
+    Ack ack = 7;
+  }
+}

package/build/protos/google/spanner/v1/query_plan.proto

@@ -0,0 +1,156 @@
+// Copyright 2026 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";
+import "google/protobuf/struct.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 = "QueryPlanProto";
+option java_package = "com.google.spanner.v1";
+option php_namespace = "Google\\Cloud\\Spanner\\V1";
+option ruby_package = "Google::Cloud::Spanner::V1";
+
+// Node information for nodes appearing in a
+// [QueryPlan.plan_nodes][google.spanner.v1.QueryPlan.plan_nodes].
+message PlanNode {
+  // The kind of [PlanNode][google.spanner.v1.PlanNode]. Distinguishes between
+  // the two different kinds of nodes that can appear in a query plan.
+  enum Kind {
+    // Not specified.
+    KIND_UNSPECIFIED = 0;
+
+    // Denotes a Relational operator node in the expression tree. Relational
+    // operators represent iterative processing of rows during query execution.
+    // For example, a `TableScan` operation that reads rows from a table.
+    RELATIONAL = 1;
+
+    // Denotes a Scalar node in the expression tree. Scalar nodes represent
+    // non-iterable entities in the query plan. For example, constants or
+    // arithmetic operators appearing inside predicate expressions or references
+    // to column names.
+    SCALAR = 2;
+  }
+
+  // Metadata associated with a parent-child relationship appearing in a
+  // [PlanNode][google.spanner.v1.PlanNode].
+  message ChildLink {
+    // The node to which the link points.
+    int32 child_index = 1;
+
+    // The type of the link. For example, in Hash Joins this could be used to
+    // distinguish between the build child and the probe child, or in the case
+    // of the child being an output variable, to represent the tag associated
+    // with the output variable.
+    string type = 2;
+
+    // Only present if the child node is
+    // [SCALAR][google.spanner.v1.PlanNode.Kind.SCALAR] and corresponds to an
+    // output variable of the parent node. The field carries the name of the
+    // output variable. For example, a `TableScan` operator that reads rows from
+    // a table will have child links to the `SCALAR` nodes representing the
+    // output variables created for each column that is read by the operator.
+    // The corresponding `variable` fields will be set to the variable names
+    // assigned to the columns.
+    string variable = 3;
+  }
+
+  // Condensed representation of a node and its subtree. Only present for
+  // `SCALAR` [PlanNode(s)][google.spanner.v1.PlanNode].
+  message ShortRepresentation {
+    // A string representation of the expression subtree rooted at this node.
+    string description = 1;
+
+    // A mapping of (subquery variable name) -> (subquery node id) for cases
+    // where the `description` string of this node references a `SCALAR`
+    // subquery contained in the expression subtree rooted at this node. The
+    // referenced `SCALAR` subquery may not necessarily be a direct child of
+    // this node.
+    map<string, int32> subqueries = 2;
+  }
+
+  // The `PlanNode`'s index in [node
+  // list][google.spanner.v1.QueryPlan.plan_nodes].
+  int32 index = 1;
+
+  // Used to determine the type of node. May be needed for visualizing
+  // different kinds of nodes differently. For example, If the node is a
+  // [SCALAR][google.spanner.v1.PlanNode.Kind.SCALAR] node, it will have a
+  // condensed representation which can be used to directly embed a description
+  // of the node in its parent.
+  Kind kind = 2;
+
+  // The display name for the node.
+  string display_name = 3;
+
+  // List of child node `index`es and their relationship to this parent.
+  repeated ChildLink child_links = 4;
+
+  // Condensed representation for
+  // [SCALAR][google.spanner.v1.PlanNode.Kind.SCALAR] nodes.
+  ShortRepresentation short_representation = 5;
+
+  // Attributes relevant to the node contained in a group of key-value pairs.
+  // For example, a Parameter Reference node could have the following
+  // information in its metadata:
+  //
+  //     {
+  //       "parameter_reference": "param1",
+  //       "parameter_type": "array"
+  //     }
+  google.protobuf.Struct metadata = 6;
+
+  // The execution statistics associated with the node, contained in a group of
+  // key-value pairs. Only present if the plan was returned as a result of a
+  // profile query. For example, number of executions, number of rows/time per
+  // execution etc.
+  google.protobuf.Struct execution_stats = 7;
+}
+
+// Output of query advisor analysis.
+message QueryAdvisorResult {
+  // Recommendation to add new indexes to run queries more efficiently.
+  message IndexAdvice {
+    // Optional. DDL statements to add new indexes that will improve the query.
+    repeated string ddl = 1 [(google.api.field_behavior) = OPTIONAL];
+
+    // Optional. Estimated latency improvement factor. For example if the query
+    // currently takes 500 ms to run and the estimated latency with new indexes
+    // is 100 ms this field will be 5.
+    double improvement_factor = 2 [(google.api.field_behavior) = OPTIONAL];
+  }
+
+  // Optional. Index Recommendation for a query. This is an optional field and
+  // the recommendation will only be available when the recommendation
+  // guarantees significant improvement in query performance.
+  repeated IndexAdvice index_advice = 1
+      [(google.api.field_behavior) = OPTIONAL];
+}
+
+// Contains an ordered list of nodes appearing in the query plan.
+message QueryPlan {
+  // The nodes in the query plan. Plan nodes are returned in pre-order starting
+  // with the plan root. Each [PlanNode][google.spanner.v1.PlanNode]'s `id`
+  // corresponds to its index in `plan_nodes`.
+  repeated PlanNode plan_nodes = 1;
+
+  // Optional. The advise/recommendations for a query. Currently this field will
+  // be serving index recommendations for a query.
+  QueryAdvisorResult query_advice = 2 [(google.api.field_behavior) = OPTIONAL];
+}

package/build/protos/google/spanner/v1/result_set.proto

@@ -0,0 +1,260 @@
+// Copyright 2026 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";
+import "google/protobuf/struct.proto";
+import "google/spanner/v1/location.proto";
+import "google/spanner/v1/query_plan.proto";
+import "google/spanner/v1/transaction.proto";
+import "google/spanner/v1/type.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 = "ResultSetProto";
+option java_package = "com.google.spanner.v1";
+option php_namespace = "Google\\Cloud\\Spanner\\V1";
+option ruby_package = "Google::Cloud::Spanner::V1";
+
+// Results from [Read][google.spanner.v1.Spanner.Read] or
+// [ExecuteSql][google.spanner.v1.Spanner.ExecuteSql].
+message ResultSet {
+  // Metadata about the result set, such as row type information.
+  ResultSetMetadata metadata = 1;
+
+  // Each element in `rows` is a row whose format is defined by
+  // [metadata.row_type][google.spanner.v1.ResultSetMetadata.row_type]. The ith
+  // element in each row matches the ith field in
+  // [metadata.row_type][google.spanner.v1.ResultSetMetadata.row_type]. Elements
+  // are encoded based on type as described [here][google.spanner.v1.TypeCode].
+  repeated google.protobuf.ListValue rows = 2;
+
+  // Query plan and execution statistics for the SQL statement that
+  // produced this result set. These can be requested by setting
+  // [ExecuteSqlRequest.query_mode][google.spanner.v1.ExecuteSqlRequest.query_mode].
+  // DML statements always produce stats containing the number of rows
+  // modified, unless executed using the
+  // [ExecuteSqlRequest.QueryMode.PLAN][google.spanner.v1.ExecuteSqlRequest.QueryMode.PLAN]
+  // [ExecuteSqlRequest.query_mode][google.spanner.v1.ExecuteSqlRequest.query_mode].
+  // Other fields might or might not be populated, based on the
+  // [ExecuteSqlRequest.query_mode][google.spanner.v1.ExecuteSqlRequest.query_mode].
+  ResultSetStats stats = 3;
+
+  // Optional. A precommit token is included if the read-write transaction is on
+  // a multiplexed session. Pass the precommit token with the highest sequence
+  // number from this transaction attempt to the
+  // [Commit][google.spanner.v1.Spanner.Commit] request for this transaction.
+  MultiplexedSessionPrecommitToken precommit_token = 5
+      [(google.api.field_behavior) = OPTIONAL];
+
+  // Optional. A cache update expresses a set of changes the client should
+  // incorporate into its location cache. The client should discard the changes
+  // if they are older than the data it already has. This data can be obtained
+  // in response to requests that included a `RoutingHint` field, but may also
+  // be obtained by explicit location-fetching RPCs which may be added in the
+  // future.
+  CacheUpdate cache_update = 6 [(google.api.field_behavior) = OPTIONAL];
+}
+
+// Partial results from a streaming read or SQL query. Streaming reads and
+// SQL queries better tolerate large result sets, large rows, and large
+// values, but are a little trickier to consume.
+message PartialResultSet {
+  // Metadata about the result set, such as row type information.
+  // Only present in the first response.
+  ResultSetMetadata metadata = 1;
+
+  // A streamed result set consists of a stream of values, which might
+  // be split into many `PartialResultSet` messages to accommodate
+  // large rows and/or large values. Every N complete values defines a
+  // row, where N is equal to the number of entries in
+  // [metadata.row_type.fields][google.spanner.v1.StructType.fields].
+  //
+  // Most values are encoded based on type as described
+  // [here][google.spanner.v1.TypeCode].
+  //
+  // It's possible that the last value in values is "chunked",
+  // meaning that the rest of the value is sent in subsequent
+  // `PartialResultSet`(s). This is denoted by the
+  // [chunked_value][google.spanner.v1.PartialResultSet.chunked_value] field.
+  // Two or more chunked values can be merged to form a complete value as
+  // follows:
+  //
+  //   * `bool/number/null`: can't be chunked
+  //   * `string`: concatenate the strings
+  //   * `list`: concatenate the lists. If the last element in a list is a
+  //     `string`, `list`, or `object`, merge it with the first element in
+  //     the next list by applying these rules recursively.
+  //   * `object`: concatenate the (field name, field value) pairs. If a
+  //     field name is duplicated, then apply these rules recursively
+  //     to merge the field values.
+  //
+  // Some examples of merging:
+  //
+  //     Strings are concatenated.
+  //     "foo", "bar" => "foobar"
+  //
+  //     Lists of non-strings are concatenated.
+  //     [2, 3], [4] => [2, 3, 4]
+  //
+  //     Lists are concatenated, but the last and first elements are merged
+  //     because they are strings.
+  //     ["a", "b"], ["c", "d"] => ["a", "bc", "d"]
+  //
+  //     Lists are concatenated, but the last and first elements are merged
+  //     because they are lists. Recursively, the last and first elements
+  //     of the inner lists are merged because they are strings.
+  //     ["a", ["b", "c"]], [["d"], "e"] => ["a", ["b", "cd"], "e"]
+  //
+  //     Non-overlapping object fields are combined.
+  //     {"a": "1"}, {"b": "2"} => {"a": "1", "b": 2"}
+  //
+  //     Overlapping object fields are merged.
+  //     {"a": "1"}, {"a": "2"} => {"a": "12"}
+  //
+  //     Examples of merging objects containing lists of strings.
+  //     {"a": ["1"]}, {"a": ["2"]} => {"a": ["12"]}
+  //
+  // For a more complete example, suppose a streaming SQL query is
+  // yielding a result set whose rows contain a single string
+  // field. The following `PartialResultSet`s might be yielded:
+  //
+  //     {
+  //       "metadata": { ... }
+  //       "values": ["Hello", "W"]
+  //       "chunked_value": true
+  //       "resume_token": "Af65..."
+  //     }
+  //     {
+  //       "values": ["orl"]
+  //       "chunked_value": true
+  //     }
+  //     {
+  //       "values": ["d"]
+  //       "resume_token": "Zx1B..."
+  //     }
+  //
+  // This sequence of `PartialResultSet`s encodes two rows, one
+  // containing the field value `"Hello"`, and a second containing the
+  // field value `"World" = "W" + "orl" + "d"`.
+  //
+  // Not all `PartialResultSet`s contain a `resume_token`. Execution can only be
+  // resumed from a previously yielded `resume_token`. For the above sequence of
+  // `PartialResultSet`s, resuming the query with `"resume_token": "Af65..."`
+  // yields results from the `PartialResultSet` with value "orl".
+  repeated google.protobuf.Value values = 2;
+
+  // If true, then the final value in
+  // [values][google.spanner.v1.PartialResultSet.values] is chunked, and must be
+  // combined with more values from subsequent `PartialResultSet`s to obtain a
+  // complete field value.
+  bool chunked_value = 3;
+
+  // Streaming calls might be interrupted for a variety of reasons, such
+  // as TCP connection loss. If this occurs, the stream of results can
+  // be resumed by re-sending the original request and including
+  // `resume_token`. Note that executing any other transaction in the
+  // same session invalidates the token.
+  bytes resume_token = 4;
+
+  // Query plan and execution statistics for the statement that produced this
+  // streaming result set. These can be requested by setting
+  // [ExecuteSqlRequest.query_mode][google.spanner.v1.ExecuteSqlRequest.query_mode]
+  // and are sent only once with the last response in the stream. This field is
+  // also present in the last response for DML statements.
+  ResultSetStats stats = 5;
+
+  // Optional. A precommit token is included if the read-write transaction
+  // has multiplexed sessions enabled. Pass the precommit token with the highest
+  // sequence number from this transaction attempt to the
+  // [Commit][google.spanner.v1.Spanner.Commit] request for this transaction.
+  MultiplexedSessionPrecommitToken precommit_token = 8
+      [(google.api.field_behavior) = OPTIONAL];
+
+  // Optional. Indicates whether this is the last `PartialResultSet` in the
+  // stream. The server might optionally set this field. Clients shouldn't rely
+  // on this field being set in all cases.
+  bool last = 9 [(google.api.field_behavior) = OPTIONAL];
+
+  // Optional. A cache update expresses a set of changes the client should
+  // incorporate into its location cache. The client should discard the changes
+  // if they are older than the data it already has. This data can be obtained
+  // in response to requests that included a `RoutingHint` field, but may also
+  // be obtained by explicit location-fetching RPCs which may be added in the
+  // future.
+  CacheUpdate cache_update = 10 [(google.api.field_behavior) = OPTIONAL];
+}
+
+// Metadata about a [ResultSet][google.spanner.v1.ResultSet] or
+// [PartialResultSet][google.spanner.v1.PartialResultSet].
+message ResultSetMetadata {
+  // Indicates the field names and types for the rows in the result
+  // set. For example, a SQL query like `"SELECT UserId, UserName FROM
+  // Users"` could return a `row_type` value like:
+  //
+  //     "fields": [
+  //       { "name": "UserId", "type": { "code": "INT64" } },
+  //       { "name": "UserName", "type": { "code": "STRING" } },
+  //     ]
+  StructType row_type = 1;
+
+  // If the read or SQL query began a transaction as a side-effect, the
+  // information about the new transaction is yielded here.
+  Transaction transaction = 2;
+
+  // A SQL query can be parameterized. In PLAN mode, these parameters can be
+  // undeclared. This indicates the field names and types for those undeclared
+  // parameters in the SQL query. For example, a SQL query like `"SELECT * FROM
+  // Users where UserId = @userId and UserName = @userName "` could return a
+  // `undeclared_parameters` value like:
+  //
+  //     "fields": [
+  //       { "name": "UserId", "type": { "code": "INT64" } },
+  //       { "name": "UserName", "type": { "code": "STRING" } },
+  //     ]
+  StructType undeclared_parameters = 3;
+}
+
+// Additional statistics about a [ResultSet][google.spanner.v1.ResultSet] or
+// [PartialResultSet][google.spanner.v1.PartialResultSet].
+message ResultSetStats {
+  // [QueryPlan][google.spanner.v1.QueryPlan] for the query associated with this
+  // result.
+  QueryPlan query_plan = 1;
+
+  // Aggregated statistics from the execution of the query. Only present when
+  // the query is profiled. For example, a query could return the statistics as
+  // follows:
+  //
+  //     {
+  //       "rows_returned": "3",
+  //       "elapsed_time": "1.22 secs",
+  //       "cpu_time": "1.19 secs"
+  //     }
+  google.protobuf.Struct query_stats = 2;
+
+  // The number of rows modified by the DML statement.
+  oneof row_count {
+    // Standard DML returns an exact count of rows that were modified.
+    int64 row_count_exact = 3;
+
+    // Partitioned DML doesn't offer exactly-once semantics, so it
+    // returns a lower bound of the rows modified.
+    int64 row_count_lower_bound = 4;
+  }
+}