Google Cloud Spanner C++ Client  1.34.0
A C++ Client Library for Google Cloud Spanner
results.h
Go to the documentation of this file.
1 // Copyright 2019 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 #ifndef GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_SPANNER_RESULTS_H
16 #define GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_SPANNER_RESULTS_H
17 
18 #include "google/cloud/spanner/row.h"
19 #include "google/cloud/spanner/timestamp.h"
20 #include "google/cloud/spanner/version.h"
21 #include "google/cloud/optional.h"
22 #include "absl/types/optional.h"
23 #include <google/spanner/v1/spanner.pb.h>
24 #include <memory>
25 #include <string>
26 #include <unordered_map>
27 
28 namespace google {
29 namespace cloud {
30 namespace spanner_internal {
32 class ResultSourceInterface {
33  public:
34  virtual ~ResultSourceInterface() = default;
35  // Returns OK Status with an empty Row to indicate end-of-stream.
36  virtual StatusOr<spanner::Row> NextRow() = 0;
37  virtual absl::optional<google::spanner::v1::ResultSetMetadata> Metadata() = 0;
38  virtual absl::optional<google::spanner::v1::ResultSetStats> Stats() const = 0;
39 };
40 
42 } // namespace spanner_internal
43 
44 namespace spanner {
46 
47 /**
48  * Contains a hierarchical representation of the operations the database server
49  * performs in order to execute a particular SQL statement.
50  * [Query Plan
51  * proto](https://github.com/googleapis/googleapis/blob/master/google/spanner/v1/query_plan.proto)
52  *
53  * @par Example:
54  * @snippet samples.cc analyze-query
55  */
56 using ExecutionPlan = ::google::spanner::v1::QueryPlan;
57 
58 /**
59  * Represents the stream of `Rows` returned from `spanner::Client::Read()` or
60  * `spanner::Client::ExecuteQuery()`.
61  *
62  * This is a range defined by the [Input Iterators][input-iterator] returned
63  * from its `begin()` and `end()` members. Callers may directly iterate the
64  * `RowStream` instance, which will return a sequence of `StatusOr<Row>`
65  * objects.
66  *
67  * For convenience, callers may wrap instances in a `StreamOf<std::tuple<...>>`
68  * object, which will automatically parse each `Row` into a `std::tuple` with
69  * the specified types.
70  *
71  * [input-iterator]: https://en.cppreference.com/w/cpp/named_req/InputIterator
72  */
73 class RowStream {
74  public:
75  RowStream() = default;
76  explicit RowStream(
77  std::unique_ptr<spanner_internal::ResultSourceInterface> source)
78  : source_(std::move(source)) {}
79 
80  // This class is movable but not copyable.
81  RowStream(RowStream&&) = default;
82  RowStream& operator=(RowStream&&) = default;
83 
84  /// Returns a `RowStreamIterator` defining the beginning of this range.
86  return RowStreamIterator([this]() mutable { return source_->NextRow(); });
87  }
88 
89  /// Returns a `RowStreamIterator` defining the end of this range.
90  // NOLINTNEXTLINE(readability-convert-member-functions-to-static)
91  RowStreamIterator end() { return {}; }
92 
93  /**
94  * Retrieves the timestamp at which the read occurred.
95  *
96  * @note Only available if a read-only transaction was used.
97  */
98  absl::optional<Timestamp> ReadTimestamp() const;
99 
100  private:
101  std::unique_ptr<spanner_internal::ResultSourceInterface> source_;
102 };
103 
104 /**
105  * Represents the result of a data modifying operation using
106  * `spanner::Client::ExecuteDml()`.
107  *
108  * This class encapsulates the result of a Cloud Spanner DML operation, i.e.,
109  * `INSERT`, `UPDATE`, or `DELETE`.
110  *
111  * @note `ExecuteDmlResult` returns the number of rows modified.
112  *
113  * @par Example:
114  * @snippet samples.cc execute-dml
115  */
116 class DmlResult {
117  public:
118  DmlResult() = default;
119  explicit DmlResult(
120  std::unique_ptr<spanner_internal::ResultSourceInterface> source)
121  : source_(std::move(source)) {}
122 
123  // This class is movable but not copyable.
124  DmlResult(DmlResult&&) = default;
125  DmlResult& operator=(DmlResult&&) = default;
126 
127  /**
128  * Returns the number of rows modified by the DML statement.
129  *
130  * @note Partitioned DML only provides a lower bound of the rows modified, all
131  * other DML statements provide an exact count.
132  */
133  std::int64_t RowsModified() const;
134 
135  private:
136  std::unique_ptr<spanner_internal::ResultSourceInterface> source_;
137 };
138 
139 /**
140  * Represents the stream of `Rows` and profile stats returned from
141  * `spanner::Client::ProfileQuery()`.
142  *
143  * This is a range defined by the [Input Iterators][input-iterator] returned
144  * from its `begin()` and `end()` members. Callers may directly iterate the
145  * `ProfileQueryResult` instance, which will return a sequence of
146  * `StatusOr<Row>` objects.
147  *
148  * For convenience, callers may wrap instances in a `StreamOf<std::tuple<...>>`
149  * object, which will automatically parse each `Row` into a `std::tuple` with
150  * the specified types.
151  *
152  * [input-iterator]: https://en.cppreference.com/w/cpp/named_req/InputIterator
153  *
154  * @par Example:
155  * @snippet samples.cc profile-query
156  */
158  public:
159  ProfileQueryResult() = default;
161  std::unique_ptr<spanner_internal::ResultSourceInterface> source)
162  : source_(std::move(source)) {}
163 
164  // This class is movable but not copyable.
167 
168  /// Returns a `RowStreamIterator` defining the beginning of this result set.
170  return RowStreamIterator([this]() mutable { return source_->NextRow(); });
171  }
172 
173  /// Returns a `RowStreamIterator` defining the end of this result set.
174  // NOLINTNEXTLINE(readability-convert-member-functions-to-static)
175  RowStreamIterator end() { return {}; }
176 
177  /**
178  * Retrieves the timestamp at which the read occurred.
179  *
180  * @note Only available if a read-only transaction was used.
181  */
182  absl::optional<Timestamp> ReadTimestamp() const;
183 
184  /**
185  * Returns a collection of key value pair statistics for the SQL statement
186  * execution.
187  *
188  * @note Only available when the statement is executed and all results have
189  * been read.
190  */
191  absl::optional<std::unordered_map<std::string, std::string>> ExecutionStats()
192  const;
193 
194  /**
195  * Returns the plan of execution for the SQL statement.
196  */
197  absl::optional<spanner::ExecutionPlan> ExecutionPlan() const;
198 
199  private:
200  std::unique_ptr<spanner_internal::ResultSourceInterface> source_;
201 };
202 
203 /**
204  * Represents the result and profile stats of a data modifying operation using
205  * `spanner::Client::ProfileDml()`.
206  *
207  * This class encapsulates the result of a Cloud Spanner DML operation, i.e.,
208  * `INSERT`, `UPDATE`, or `DELETE`.
209  *
210  * @note `ProfileDmlResult` returns the number of rows modified, execution
211  * statistics, and query plan.
212  *
213  * @par Example:
214  * @snippet samples.cc profile-dml
215  */
217  public:
218  ProfileDmlResult() = default;
220  std::unique_ptr<spanner_internal::ResultSourceInterface> source)
221  : source_(std::move(source)) {}
222 
223  // This class is movable but not copyable.
226 
227  /**
228  * Returns the number of rows modified by the DML statement.
229  *
230  * @note Partitioned DML only provides a lower bound of the rows modified, all
231  * other DML statements provide an exact count.
232  */
233  std::int64_t RowsModified() const;
234 
235  /**
236  * Returns a collection of key value pair statistics for the SQL statement
237  * execution.
238  *
239  * @note Only available when the SQL statement is executed.
240  */
241  absl::optional<std::unordered_map<std::string, std::string>> ExecutionStats()
242  const;
243 
244  /**
245  * Returns the plan of execution for the SQL statement.
246  */
247  absl::optional<spanner::ExecutionPlan> ExecutionPlan() const;
248 
249  private:
250  std::unique_ptr<spanner_internal::ResultSourceInterface> source_;
251 };
253 } // namespace spanner
254 } // namespace cloud
255 } // namespace google
256 
257 #endif // GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_SPANNER_RESULTS_H