Google Cloud Spanner C++ Client  1.32.1
A C++ Client Library for Google Cloud Spanner
sql_statement.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_SQL_STATEMENT_H
16 #define GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_SPANNER_SQL_STATEMENT_H
17 
18 #include "google/cloud/spanner/value.h"
19 #include "google/cloud/spanner/version.h"
20 #include "google/cloud/status_or.h"
21 #include <google/spanner/v1/spanner.pb.h>
22 #include <string>
23 #include <unordered_map>
24 #include <vector>
25 
26 namespace google {
27 namespace cloud {
28 namespace spanner_internal {
29 inline namespace SPANNER_CLIENT_NS {
30 struct SqlStatementInternals;
31 } // namespace SPANNER_CLIENT_NS
32 } // namespace spanner_internal
33 
34 namespace spanner {
35 inline namespace SPANNER_CLIENT_NS {
36 /**
37  * Represents a potentially parameterized SQL statement.
38  *
39  * Details on case sensitivity for SQL statements and string values can be
40  * found here: [Case
41  * Sensitivity](https://cloud.google.com/spanner/docs/lexical#case-sensitivity)
42  *
43  * @note `SqlStatement` equality comparisons are case-sensitive.
44  *
45  * Parameter placeholders are specified by `@<param name>` in the SQL string.
46  * Values for parameters are a collection of `std::pair<std::string const,
47  * google::cloud:spanner::Value>`.
48  * @par Example
49  * @snippet samples.cc spanner-sql-statement-params
50  */
51 class SqlStatement {
52  public:
53  /// Type alias for parameter collection.
54  using ParamType = std::unordered_map<std::string, Value>;
55 
56  SqlStatement() = default;
57  /// Constructs a SqlStatement without parameters.
58  explicit SqlStatement(std::string statement)
59  : statement_(std::move(statement)) {}
60  /// Constructs a SqlStatement with specified parameters.
61  SqlStatement(std::string statement, ParamType params)
62  : statement_(std::move(statement)), params_(std::move(params)) {}
63 
64  /// Copy and move.
65  SqlStatement(SqlStatement const&) = default;
66  SqlStatement(SqlStatement&&) = default;
67  SqlStatement& operator=(SqlStatement const&) = default;
69 
70  /**
71  * Returns the SQL statement.
72  * No parameter substitution is performed in the statement string.
73  */
74  std::string const& sql() const { return statement_; }
75 
76  /**
77  * Returns the collection of parameters.
78  * @return If no parameters were specified, the container will be empty.
79  */
80  ParamType const& params() const { return params_; }
81 
82  /**
83  * Returns the names of all the parameters.
84  */
85  std::vector<std::string> ParameterNames() const;
86 
87  /**
88  * Returns the value of the requested parameter.
89  * @param parameter_name name of requested parameter.
90  * @return `StatusCode::kNotFound` returned for invalid names.
91  */
92  google::cloud::StatusOr<Value> GetParameter(
93  std::string const& parameter_name) const;
94 
95  friend bool operator==(SqlStatement const& a, SqlStatement const& b) {
96  return a.statement_ == b.statement_ && a.params_ == b.params_;
97  }
98  friend bool operator!=(SqlStatement const& a, SqlStatement const& b) {
99  return !(a == b);
100  }
101 
102  /**
103  * Outputs a string representation of the given @p stmt to the given @p os.
104  *
105  * @warning This is intended for debugging and human consumption only, not
106  * machine consumption, as the output format may change without notice.
107  */
108  friend std::ostream& operator<<(std::ostream& os, SqlStatement const& stmt);
109 
110  private:
111  friend struct spanner_internal::SPANNER_CLIENT_NS::SqlStatementInternals;
112 
113  std::string statement_;
114  ParamType params_;
115 };
116 
117 } // namespace SPANNER_CLIENT_NS
118 } // namespace spanner
119 
120 // Internal implementation details that callers should not use.
121 namespace spanner_internal {
122 inline namespace SPANNER_CLIENT_NS {
123 // Use this proto type because it conveniently wraps all three attributes
124 // required to represent a SQL statement.
125 using SqlStatementProto =
126  ::google::spanner::v1::ExecuteBatchDmlRequest::Statement;
127 
128 struct SqlStatementInternals {
129  static SqlStatementProto ToProto(spanner::SqlStatement s);
130 };
131 
132 inline SqlStatementProto ToProto(spanner::SqlStatement s) {
133  return SqlStatementInternals::ToProto(std::move(s));
134 }
135 } // namespace SPANNER_CLIENT_NS
136 } // namespace spanner_internal
137 } // namespace cloud
138 } // namespace google
139 
140 #endif // GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_SPANNER_SQL_STATEMENT_H