Google Cloud Spanner C++ Client  2.1.0
A C++ Client Library for Google Cloud Spanner
query_partition.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_QUERY_PARTITION_H
16 #define GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_SPANNER_QUERY_PARTITION_H
17 
18 #include "google/cloud/spanner/connection.h"
19 #include "google/cloud/spanner/sql_statement.h"
20 #include "google/cloud/spanner/version.h"
21 #include "google/cloud/status_or.h"
22 #include <memory>
23 #include <string>
24 
25 namespace google {
26 namespace cloud {
27 namespace spanner_internal {
29 class QueryPartitionTester;
30 struct QueryPartitionInternals;
32 } // namespace spanner_internal
33 
34 namespace spanner {
36 
37 /**
38  * Serializes an instance of `QueryPartition` to a string of bytes.
39  *
40  * The serialized string of bytes is suitable for writing to disk or
41  * transmission to another process.
42  *
43  * @note The serialized string may contain NUL and other non-printable
44  * characters. Therefore, callers should avoid [formatted IO][formatted-io]
45  * functions that may incorrectly reformat the string data.
46  *
47  * @param query_partition - instance to be serialized.
48  *
49  * @par Example
50  * @snippet samples.cc serialize-query-partition
51  *
52  * [formatted-io]:
53  * https://en.cppreference.com/w/cpp/string/basic_string/operator_ltltgtgt
54  */
55 StatusOr<std::string> SerializeQueryPartition(
56  QueryPartition const& query_partition);
57 
58 /**
59  * Deserializes the provided string into a `QueryPartition`.
60  *
61  * The @p serialized_query_partition argument must be a string that was
62  * previously returned by a call to `SerializeQueryPartition()`.
63  *
64  * @note The serialized string may contain NUL and other non-printable
65  * characters. Therefore, callers should avoid [formatted IO][formatted-io]
66  * functions that may incorrectly reformat the string data.
67  *
68  * @param serialized_query_partition
69  *
70  * @par Example
71  * @snippet samples.cc deserialize-query-partition
72  *
73  * [formatted-io]:
74  * https://en.cppreference.com/w/cpp/string/basic_string/operator_ltltgtgt
75  */
77  std::string const& serialized_query_partition);
78 
79 /**
80  * The `QueryPartition` class is a regular type that represents a single slice
81  * of a parallel SQL read.
82  *
83  * Instances of `QueryPartition` are created by `Client::PartitionSql`. Once
84  * created, `QueryPartition` objects can be serialized, transmitted to separate
85  * process, and used to read data in parallel using `Client::ExecuteQuery`.
86  */
88  public:
89  /**
90  * Constructs an instance of `QueryPartition` that is not associated with any
91  * `SqlStatement`.
92  */
93  QueryPartition() = default;
94 
95  /// @name Copy and move
96  ///@{
97  QueryPartition(QueryPartition const&) = default;
99  QueryPartition& operator=(QueryPartition const&) = default;
101  ///@}
102 
103  /**
104  * Accessor for the `SqlStatement` associated with this `QueryPartition`.
105  */
106  SqlStatement const& sql_statement() const { return sql_statement_; }
107 
108  /// @name Equality
109  ///@{
110  friend bool operator==(QueryPartition const& a, QueryPartition const& b);
111  friend bool operator!=(QueryPartition const& a, QueryPartition const& b) {
112  return !(a == b);
113  }
114  ///@}
115 
116  private:
117  friend class spanner_internal::QueryPartitionTester;
118  friend struct spanner_internal::QueryPartitionInternals;
119  friend StatusOr<std::string> SerializeQueryPartition(
120  QueryPartition const& query_partition);
122  std::string const& serialized_query_partition);
123 
124  QueryPartition(std::string transaction_id, std::string transaction_tag,
125  std::string session_id, std::string partition_token,
126  SqlStatement sql_statement);
127 
128  // Accessor methods for use by friends.
129  std::string const& partition_token() const { return partition_token_; }
130  std::string const& session_id() const { return session_id_; }
131  std::string const& transaction_tag() const { return transaction_tag_; }
132  std::string const& transaction_id() const { return transaction_id_; }
133 
134  std::string transaction_id_;
135  std::string transaction_tag_;
136  std::string session_id_;
137  std::string partition_token_;
138  SqlStatement sql_statement_;
139 };
140 
142 } // namespace spanner
143 
144 // Internal implementation details that callers should not use.
145 namespace spanner_internal {
147 
148 struct QueryPartitionInternals {
149  static spanner::QueryPartition MakeQueryPartition(
150  std::string const& transaction_id, std::string const& transaction_tag,
151  std::string const& session_id, std::string const& partition_token,
152  spanner::SqlStatement const& sql_statement) {
153  return spanner::QueryPartition(transaction_id, transaction_tag, session_id,
154  partition_token, sql_statement);
155  }
156 
157  static spanner::Connection::SqlParams MakeSqlParams(
158  spanner::QueryPartition const& query_partition) {
159  spanner::QueryOptions query_options; // not serialized
160  return {MakeTransactionFromIds(query_partition.session_id(),
161  query_partition.transaction_id(),
162  query_partition.transaction_tag()),
163  query_partition.sql_statement(), query_options,
164  query_partition.partition_token()};
165  }
166 };
167 
168 inline spanner::QueryPartition MakeQueryPartition(
169  std::string const& transaction_id, std::string const& transaction_tag,
170  std::string const& session_id, std::string const& partition_token,
171  spanner::SqlStatement const& sql_statement) {
172  return QueryPartitionInternals::MakeQueryPartition(
173  transaction_id, transaction_tag, session_id, partition_token,
174  sql_statement);
175 }
176 
177 inline spanner::Connection::SqlParams MakeSqlParams(
178  spanner::QueryPartition const& query_partition) {
179  return QueryPartitionInternals::MakeSqlParams(query_partition);
180 }
181 
183 } // namespace spanner_internal
184 } // namespace cloud
185 } // namespace google
186 
187 #endif // GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_SPANNER_QUERY_PARTITION_H