google-cloud-spanner 0.21.0

data/lib/google/cloud/spanner/v1/doc/google/spanner/v1/query_plan.rb

@@ -0,0 +1,120 @@
+# Copyright 2017, Google Inc. All rights reserved.
+#
+# 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.
+
+module Google
+  module Spanner
+    module V1
+      # Node information for nodes appearing in a QueryPlan#plan_nodes.
+      # @!attribute [rw] index
+      #   @return [Integer]
+      #     The +PlanNode+'s index in Node list.
+      # @!attribute [rw] kind
+      #   @return [Google::Spanner::V1::PlanNode::Kind]
+      #     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 node, it will have a condensed representation
+      #     which can be used to directly embed a description of the node in its
+      #     parent.
+      # @!attribute [rw] display_name
+      #   @return [String]
+      #     The display name for the node.
+      # @!attribute [rw] child_links
+      #   @return [Array<Google::Spanner::V1::PlanNode::ChildLink>]
+      #     List of child node +index+es and their relationship to this parent.
+      # @!attribute [rw] short_representation
+      #   @return [Google::Spanner::V1::PlanNode::ShortRepresentation]
+      #     Condensed representation for SCALAR nodes.
+      # @!attribute [rw] metadata
+      #   @return [Google::Protobuf::Struct]
+      #     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"
+      #         }
+      # @!attribute [rw] execution_stats
+      #   @return [Google::Protobuf::Struct]
+      #     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.
+      class PlanNode
+        # Metadata associated with a parent-child relationship appearing in a
+        # PlanNode.
+        # @!attribute [rw] child_index
+        #   @return [Integer]
+        #     The node to which the link points.
+        # @!attribute [rw] type
+        #   @return [String]
+        #     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.
+        # @!attribute [rw] variable
+        #   @return [String]
+        #     Only present if the child node is 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.
+        class ChildLink; end
+
+        # Condensed representation of a node and its subtree. Only present for
+        # +SCALAR+ PlanNode(s).
+        # @!attribute [rw] description
+        #   @return [String]
+        #     A string representation of the expression subtree rooted at this node.
+        # @!attribute [rw] subqueries
+        #   @return [Hash{String => Integer}]
+        #     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.
+        class ShortRepresentation; end
+
+        # The kind of PlanNode. Distinguishes between the two different kinds of
+        # nodes that can appear in a query plan.
+        module 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
+        end
+      end
+
+      # Contains an ordered list of nodes appearing in the query plan.
+      # @!attribute [rw] plan_nodes
+      #   @return [Array<Google::Spanner::V1::PlanNode>]
+      #     The nodes in the query plan. Plan nodes are returned in pre-order starting
+      #     with the plan root. Each PlanNode's +id+ corresponds to its index in
+      #     +plan_nodes+.
+      class QueryPlan; end
+    end
+  end
+end

data/lib/google/cloud/spanner/v1/doc/google/spanner/v1/result_set.rb

@@ -0,0 +1,175 @@
+# Copyright 2017, Google Inc. All rights reserved.
+#
+# 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.
+
+module Google
+  module Spanner
+    module V1
+      # Results from Read or
+      # ExecuteSql.
+      # @!attribute [rw] metadata
+      #   @return [Google::Spanner::V1::ResultSetMetadata]
+      #     Metadata about the result set, such as row type information.
+      # @!attribute [rw] rows
+      #   @return [Array<Google::Protobuf::ListValue>]
+      #     Each element in +rows+ is a row whose format is defined by
+      #     Metadata::Row_type. The ith element
+      #     in each row matches the ith field in
+      #     Metadata::Row_type. Elements are
+      #     encoded based on type as described
+      #     Here.
+      # @!attribute [rw] stats
+      #   @return [Google::Spanner::V1::ResultSetStats]
+      #     Query plan and execution statistics for the query that produced this
+      #     result set. These can be requested by setting
+      #     ExecuteSqlRequest#query_mode.
+      class ResultSet; end
+
+      # 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.
+      # @!attribute [rw] metadata
+      #   @return [Google::Spanner::V1::ResultSetMetadata]
+      #     Metadata about the result set, such as row type information.
+      #     Only present in the first response.
+      # @!attribute [rw] values
+      #   @return [Array<Google::Protobuf::Value>]
+      #     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.
+      #
+      #     Most values are encoded based on type as described
+      #     Here.
+      #
+      #     It is 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
+      #     field. Two or more chunked values can be merged to form a
+      #     complete value as follows:
+      #
+      #       * +bool/number/null+: cannot 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
+      #           "resume_token": "Bqp2..."
+      #         }
+      #         {
+      #           "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"+.
+      # @!attribute [rw] chunked_value
+      #   @return [true, false]
+      #     If true, then the final value in Values is chunked, and must
+      #     be combined with more values from subsequent +PartialResultSet+s
+      #     to obtain a complete field value.
+      # @!attribute [rw] resume_token
+      #   @return [String]
+      #     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.
+      # @!attribute [rw] stats
+      #   @return [Google::Spanner::V1::ResultSetStats]
+      #     Query plan and execution statistics for the query that produced this
+      #     streaming result set. These can be requested by setting
+      #     ExecuteSqlRequest#query_mode and are sent
+      #     only once with the last response in the stream.
+      class PartialResultSet; end
+
+      # Metadata about a ResultSet or PartialResultSet.
+      # @!attribute [rw] row_type
+      #   @return [Google::Spanner::V1::StructType]
+      #     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" } },
+      #         ]
+      # @!attribute [rw] transaction
+      #   @return [Google::Spanner::V1::Transaction]
+      #     If the read or SQL query began a transaction as a side-effect, the
+      #     information about the new transaction is yielded here.
+      class ResultSetMetadata; end
+
+      # Additional statistics about a ResultSet or PartialResultSet.
+      # @!attribute [rw] query_plan
+      #   @return [Google::Spanner::V1::QueryPlan]
+      #     QueryPlan for the query associated with this result.
+      # @!attribute [rw] query_stats
+      #   @return [Google::Protobuf::Struct]
+      #     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"
+      #         }
+      class ResultSetStats; end
+    end
+  end
+end

data/lib/google/cloud/spanner/v1/doc/google/spanner/v1/spanner.rb

@@ -0,0 +1,206 @@
+# Copyright 2017, Google Inc. All rights reserved.
+#
+# 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.
+
+module Google
+  module Spanner
+    module V1
+      # The request for CreateSession.
+      # @!attribute [rw] database
+      #   @return [String]
+      #     Required. The database in which the new session is created.
+      class CreateSessionRequest; end
+
+      # A session in the Cloud Spanner API.
+      # @!attribute [rw] name
+      #   @return [String]
+      #     Required. The name of the session.
+      class Session; end
+
+      # The request for GetSession.
+      # @!attribute [rw] name
+      #   @return [String]
+      #     Required. The name of the session to retrieve.
+      class GetSessionRequest; end
+
+      # The request for DeleteSession.
+      # @!attribute [rw] name
+      #   @return [String]
+      #     Required. The name of the session to delete.
+      class DeleteSessionRequest; end
+
+      # The request for ExecuteSql and
+      # ExecuteStreamingSql.
+      # @!attribute [rw] session
+      #   @return [String]
+      #     Required. The session in which the SQL query should be performed.
+      # @!attribute [rw] transaction
+      #   @return [Google::Spanner::V1::TransactionSelector]
+      #     The transaction to use. If none is provided, the default is a
+      #     temporary read-only transaction with strong concurrency.
+      # @!attribute [rw] sql
+      #   @return [String]
+      #     Required. The SQL query string.
+      # @!attribute [rw] params
+      #   @return [Google::Protobuf::Struct]
+      #     The SQL query string can contain parameter placeholders. A parameter
+      #     placeholder consists of +'@'+ followed by the parameter
+      #     name. Parameter names consist of any combination of letters,
+      #     numbers, and underscores.
+      #
+      #     Parameters can appear anywhere that a literal value is expected.  The same
+      #     parameter name can be used more than once, for example:
+      #       +"WHERE id > @msg_id AND id < @msg_id + 100"+
+      #
+      #     It is an error to execute an SQL query with unbound parameters.
+      #
+      #     Parameter values are specified using +params+, which is a JSON
+      #     object whose keys are parameter names, and whose values are the
+      #     corresponding parameter values.
+      # @!attribute [rw] param_types
+      #   @return [Hash{String => Google::Spanner::V1::Type}]
+      #     It is not always possible for Cloud Spanner to infer the right SQL type
+      #     from a JSON value.  For example, values of type +BYTES+ and values
+      #     of type +STRING+ both appear in Params as JSON strings.
+      #
+      #     In these cases, +param_types+ can be used to specify the exact
+      #     SQL type for some or all of the SQL query parameters. See the
+      #     definition of Type for more information
+      #     about SQL types.
+      # @!attribute [rw] resume_token
+      #   @return [String]
+      #     If this request is resuming a previously interrupted SQL query
+      #     execution, +resume_token+ should be copied from the last
+      #     PartialResultSet yielded before the interruption. Doing this
+      #     enables the new SQL query execution to resume where the last one left
+      #     off. The rest of the request parameters must exactly match the
+      #     request that yielded this token.
+      # @!attribute [rw] query_mode
+      #   @return [Google::Spanner::V1::ExecuteSqlRequest::QueryMode]
+      #     Used to control the amount of debugging information returned in
+      #     ResultSetStats.
+      class ExecuteSqlRequest
+        # Mode in which the query must be processed.
+        module QueryMode
+          # The default mode where only the query result, without any information
+          # about the query plan is returned.
+          NORMAL = 0
+
+          # This mode returns only the query plan, without any result rows or
+          # execution statistics information.
+          PLAN = 1
+
+          # This mode returns both the query plan and the execution statistics along
+          # with the result rows.
+          PROFILE = 2
+        end
+      end
+
+      # The request for Read and
+      # StreamingRead.
+      # @!attribute [rw] session
+      #   @return [String]
+      #     Required. The session in which the read should be performed.
+      # @!attribute [rw] transaction
+      #   @return [Google::Spanner::V1::TransactionSelector]
+      #     The transaction to use. If none is provided, the default is a
+      #     temporary read-only transaction with strong concurrency.
+      # @!attribute [rw] table
+      #   @return [String]
+      #     Required. The name of the table in the database to be read.
+      # @!attribute [rw] index
+      #   @return [String]
+      #     If non-empty, the name of an index on Table. This index is
+      #     used instead of the table primary key when interpreting Key_set
+      #     and sorting result rows. See Key_set for further information.
+      # @!attribute [rw] columns
+      #   @return [Array<String>]
+      #     The columns of Table to be returned for each row matching
+      #     this request.
+      # @!attribute [rw] key_set
+      #   @return [Google::Spanner::V1::KeySet]
+      #     Required. +key_set+ identifies the rows to be yielded. +key_set+ names the
+      #     primary keys of the rows in Table to be yielded, unless Index
+      #     is present. If Index is present, then Key_set instead names
+      #     index keys in Index.
+      #
+      #     Rows are yielded in table primary key order (if Index is empty)
+      #     or index key order (if Index is non-empty).
+      #
+      #     It is not an error for the +key_set+ to name rows that do not
+      #     exist in the database. Read yields nothing for nonexistent rows.
+      # @!attribute [rw] limit
+      #   @return [Integer]
+      #     If greater than zero, only the first +limit+ rows are yielded. If +limit+
+      #     is zero, the default is no limit.
+      # @!attribute [rw] resume_token
+      #   @return [String]
+      #     If this request is resuming a previously interrupted read,
+      #     +resume_token+ should be copied from the last
+      #     PartialResultSet yielded before the interruption. Doing this
+      #     enables the new read to resume where the last read left off. The
+      #     rest of the request parameters must exactly match the request
+      #     that yielded this token.
+      class ReadRequest; end
+
+      # The request for BeginTransaction.
+      # @!attribute [rw] session
+      #   @return [String]
+      #     Required. The session in which the transaction runs.
+      # @!attribute [rw] options
+      #   @return [Google::Spanner::V1::TransactionOptions]
+      #     Required. Options for the new transaction.
+      class BeginTransactionRequest; end
+
+      # The request for Commit.
+      # @!attribute [rw] session
+      #   @return [String]
+      #     Required. The session in which the transaction to be committed is running.
+      # @!attribute [rw] transaction_id
+      #   @return [String]
+      #     Commit a previously-started transaction.
+      # @!attribute [rw] single_use_transaction
+      #   @return [Google::Spanner::V1::TransactionOptions]
+      #     Execute mutations in a temporary transaction. Note that unlike
+      #     commit of a previously-started transaction, commit with a
+      #     temporary transaction is non-idempotent. That is, if the
+      #     +CommitRequest+ is sent to Cloud Spanner more than once (for
+      #     instance, due to retries in the application, or in the
+      #     transport library), it is possible that the mutations are
+      #     executed more than once. If this is undesirable, use
+      #     BeginTransaction and
+      #     Commit instead.
+      # @!attribute [rw] mutations
+      #   @return [Array<Google::Spanner::V1::Mutation>]
+      #     The mutations to be executed when this transaction commits. All
+      #     mutations are applied atomically, in the order they appear in
+      #     this list.
+      class CommitRequest; end
+
+      # The response for Commit.
+      # @!attribute [rw] commit_timestamp
+      #   @return [Google::Protobuf::Timestamp]
+      #     The Cloud Spanner timestamp at which the transaction committed.
+      class CommitResponse; end
+
+      # The request for Rollback.
+      # @!attribute [rw] session
+      #   @return [String]
+      #     Required. The session in which the transaction to roll back is running.
+      # @!attribute [rw] transaction_id
+      #   @return [String]
+      #     Required. The transaction to roll back.
+      class RollbackRequest; end
+    end
+  end
+end