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