legacy-libs/google-proto-files/google/spanner/v1/result_set.proto

   1 // Copyright 2018 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
  15 syntax = "proto3";
  16
  17 package google.spanner.v1;
  18
  19 import "google/api/annotations.proto";
  20 import "google/protobuf/struct.proto";
  21 import "google/spanner/v1/query_plan.proto";
  22 import "google/spanner/v1/transaction.proto";
  23 import "google/spanner/v1/type.proto";
  24
  25 option cc_enable_arenas = true;
  26 option csharp_namespace = "Google.Cloud.Spanner.V1";
  27 option go_package = "google.golang.org/genproto/googleapis/spanner/v1;spanner";
  28 option java_multiple_files = true;
  29 option java_outer_classname = "ResultSetProto";
  30 option java_package = "com.google.spanner.v1";
  31 option php_namespace = "Google\\Cloud\\Spanner\\V1";
  32
  33 // Results from [Read][google.spanner.v1.Spanner.Read] or
  34 // [ExecuteSql][google.spanner.v1.Spanner.ExecuteSql].
  35 message ResultSet {
  36   // Metadata about the result set, such as row type information.
  37   ResultSetMetadata metadata = 1;
  38
  39   // Each element in `rows` is a row whose format is defined by
  40   // [metadata.row_type][google.spanner.v1.ResultSetMetadata.row_type]. The ith
  41   // element in each row matches the ith field in
  42   // [metadata.row_type][google.spanner.v1.ResultSetMetadata.row_type]. Elements
  43   // are encoded based on type as described [here][google.spanner.v1.TypeCode].
  44   repeated google.protobuf.ListValue rows = 2;
  45
  46   // Query plan and execution statistics for the SQL statement that
  47   // produced this result set. These can be requested by setting
  48   // [ExecuteSqlRequest.query_mode][google.spanner.v1.ExecuteSqlRequest.query_mode].
  49   // DML statements always produce stats containing the number of rows
  50   // modified, unless executed using the
  51   // [ExecuteSqlRequest.QueryMode.PLAN][google.spanner.v1.ExecuteSqlRequest.QueryMode.PLAN]
  52   // [ExecuteSqlRequest.query_mode][google.spanner.v1.ExecuteSqlRequest.query_mode].
  53   // Other fields may or may not be populated, based on the
  54   // [ExecuteSqlRequest.query_mode][google.spanner.v1.ExecuteSqlRequest.query_mode].
  55   ResultSetStats stats = 3;
  56 }
  57
  58 // Partial results from a streaming read or SQL query. Streaming reads and
  59 // SQL queries better tolerate large result sets, large rows, and large
  60 // values, but are a little trickier to consume.
  61 message PartialResultSet {
  62   // Metadata about the result set, such as row type information.
  63   // Only present in the first response.
  64   ResultSetMetadata metadata = 1;
  65
  66   // A streamed result set consists of a stream of values, which might
  67   // be split into many `PartialResultSet` messages to accommodate
  68   // large rows and/or large values. Every N complete values defines a
  69   // row, where N is equal to the number of entries in
  70   // [metadata.row_type.fields][google.spanner.v1.StructType.fields].
  71   //
  72   // Most values are encoded based on type as described
  73   // [here][google.spanner.v1.TypeCode].
  74   //
  75   // It is possible that the last value in values is "chunked",
  76   // meaning that the rest of the value is sent in subsequent
  77   // `PartialResultSet`(s). This is denoted by the
  78   // [chunked_value][google.spanner.v1.PartialResultSet.chunked_value] field.
  79   // Two or more chunked values can be merged to form a complete value as
  80   // follows:
  81   //
  82   //   * `bool/number/null`: cannot be chunked
  83   //   * `string`: concatenate the strings
  84   //   * `list`: concatenate the lists. If the last element in a list is a
  85   //     `string`, `list`, or `object`, merge it with the first element in
  86   //     the next list by applying these rules recursively.
  87   //   * `object`: concatenate the (field name, field value) pairs. If a
  88   //     field name is duplicated, then apply these rules recursively
  89   //     to merge the field values.
  90   //
  91   // Some examples of merging:
  92   //
  93   //     # Strings are concatenated.
  94   //     "foo", "bar" => "foobar"
  95   //
  96   //     # Lists of non-strings are concatenated.
  97   //     [2, 3], [4] => [2, 3, 4]
  98   //
  99   //     # Lists are concatenated, but the last and first elements are merged
 100   //     # because they are strings.
 101   //     ["a", "b"], ["c", "d"] => ["a", "bc", "d"]
 102   //
 103   //     # Lists are concatenated, but the last and first elements are merged
 104   //     # because they are lists. Recursively, the last and first elements
 105   //     # of the inner lists are merged because they are strings.
 106   //     ["a", ["b", "c"]], [["d"], "e"] => ["a", ["b", "cd"], "e"]
 107   //
 108   //     # Non-overlapping object fields are combined.
 109   //     {"a": "1"}, {"b": "2"} => {"a": "1", "b": 2"}
 110   //
 111   //     # Overlapping object fields are merged.
 112   //     {"a": "1"}, {"a": "2"} => {"a": "12"}
 113   //
 114   //     # Examples of merging objects containing lists of strings.
 115   //     {"a": ["1"]}, {"a": ["2"]} => {"a": ["12"]}
 116   //
 117   // For a more complete example, suppose a streaming SQL query is
 118   // yielding a result set whose rows contain a single string
 119   // field. The following `PartialResultSet`s might be yielded:
 120   //
 121   //     {
 122   //       "metadata": { ... }
 123   //       "values": ["Hello", "W"]
 124   //       "chunked_value": true
 125   //       "resume_token": "Af65..."
 126   //     }
 127   //     {
 128   //       "values": ["orl"]
 129   //       "chunked_value": true
 130   //       "resume_token": "Bqp2..."
 131   //     }
 132   //     {
 133   //       "values": ["d"]
 134   //       "resume_token": "Zx1B..."
 135   //     }
 136   //
 137   // This sequence of `PartialResultSet`s encodes two rows, one
 138   // containing the field value `"Hello"`, and a second containing the
 139   // field value `"World" = "W" + "orl" + "d"`.
 140   repeated google.protobuf.Value values = 2;
 141
 142   // If true, then the final value in
 143   // [values][google.spanner.v1.PartialResultSet.values] is chunked, and must be
 144   // combined with more values from subsequent `PartialResultSet`s to obtain a
 145   // complete field value.
 146   bool chunked_value = 3;
 147
 148   // Streaming calls might be interrupted for a variety of reasons, such
 149   // as TCP connection loss. If this occurs, the stream of results can
 150   // be resumed by re-sending the original request and including
 151   // `resume_token`. Note that executing any other transaction in the
 152   // same session invalidates the token.
 153   bytes resume_token = 4;
 154
 155   // Query plan and execution statistics for the statement that produced this
 156   // streaming result set. These can be requested by setting
 157   // [ExecuteSqlRequest.query_mode][google.spanner.v1.ExecuteSqlRequest.query_mode]
 158   // and are sent only once with the last response in the stream. This field
 159   // will also be present in the last response for DML statements.
 160   ResultSetStats stats = 5;
 161 }
 162
 163 // Metadata about a [ResultSet][google.spanner.v1.ResultSet] or
 164 // [PartialResultSet][google.spanner.v1.PartialResultSet].
 165 message ResultSetMetadata {
 166   // Indicates the field names and types for the rows in the result
 167   // set.  For example, a SQL query like `"SELECT UserId, UserName FROM
 168   // Users"` could return a `row_type` value like:
 169   //
 170   //     "fields": [
 171   //       { "name": "UserId", "type": { "code": "INT64" } },
 172   //       { "name": "UserName", "type": { "code": "STRING" } },
 173   //     ]
 174   StructType row_type = 1;
 175
 176   // If the read or SQL query began a transaction as a side-effect, the
 177   // information about the new transaction is yielded here.
 178   Transaction transaction = 2;
 179 }
 180
 181 // Additional statistics about a [ResultSet][google.spanner.v1.ResultSet] or
 182 // [PartialResultSet][google.spanner.v1.PartialResultSet].
 183 message ResultSetStats {
 184   // [QueryPlan][google.spanner.v1.QueryPlan] for the query associated with this
 185   // result.
 186   QueryPlan query_plan = 1;
 187
 188   // Aggregated statistics from the execution of the query. Only present when
 189   // the query is profiled. For example, a query could return the statistics as
 190   // follows:
 191   //
 192   //     {
 193   //       "rows_returned": "3",
 194   //       "elapsed_time": "1.22 secs",
 195   //       "cpu_time": "1.19 secs"
 196   //     }
 197   google.protobuf.Struct query_stats = 2;
 198
 199   // The number of rows modified by the DML statement.
 200   oneof row_count {
 201     // Standard DML returns an exact count of rows that were modified.
 202     int64 row_count_exact = 3;
 203
 204     // Partitioned DML does not offer exactly-once semantics, so it
 205     // returns a lower bound of the rows modified.
 206     int64 row_count_lower_bound = 4;
 207   }
 208 }