userver: userver/ydb/table.hpp Source File
Loading...
Searching...
No Matches
table.hpp
1#pragma once
2
3#include <ydb-cpp-sdk/client/table/table.h>
4
5#include <userver/dynamic_config/source.hpp>
6#include <userver/rcu/rcu.hpp>
7#include <userver/utils/impl/source_location.hpp>
8#include <userver/utils/statistics/fwd.hpp>
9
10#include <userver/ydb/builder.hpp>
11#include <userver/ydb/exceptions.hpp>
12#include <userver/ydb/query.hpp>
13#include <userver/ydb/response.hpp>
14#include <userver/ydb/settings.hpp>
15#include <userver/ydb/transaction.hpp>
16#include <userver/ydb/types.hpp>
17
18namespace NMonitoring {
19class TMetricRegistry;
20} // namespace NMonitoring
21
22USERVER_NAMESPACE_BEGIN
23
24namespace tracing {
25class Span;
26} // namespace tracing
27
28namespace utils {
29class RetryBudget;
30} // namespace utils
31
32namespace ydb {
33
34namespace impl {
35struct Stats;
36struct TableSettings;
37class Driver;
38struct RequestContext;
39enum class IsStreaming : bool {};
40} // namespace impl
41
42using ScanQuerySettings = NYdb::NTable::TStreamExecScanQuerySettings;
43
44class TableClient final {
45 public:
46 /// @cond
47 // For internal use only.
48 TableClient(impl::TableSettings settings,
49 OperationSettings operation_settings,
50 dynamic_config::Source config_source,
51 std::shared_ptr<impl::Driver> driver);
52
53 ~TableClient();
54 /// @endcond
55
56 /// Query for creating/deleting tables
57 void ExecuteSchemeQuery(const std::string& query);
58
59 void MakeDirectory(const std::string& path);
60 void RemoveDirectory(const std::string& path);
61
62 NYdb::NScheme::TDescribePathResult DescribePath(std::string_view path);
63 NYdb::NScheme::TListDirectoryResult ListDirectory(std::string_view path);
64
65 NYdb::NTable::TDescribeTableResult DescribeTable(std::string_view path);
66 void CreateTable(std::string_view path,
67 NYdb::NTable::TTableDescription&& table_desc);
68 void DropTable(std::string_view path);
69
70 /// @name Data queries execution
71 /// Execute a single data query outside of transactions. Query parameters are
72 /// passed in `Args` as "string key - value" pairs:
73 ///
74 /// @code
75 /// client.ExecuteDataQuery(query, "name1", value1, "name2", value2, ...);
76 /// @endcode
77 ///
78 /// Use ydb::PreparedArgsBuilder for storing a generic buffer of query params
79 /// if needed.
80 ///
81 /// @{
82 template <typename... Args>
83 ExecuteResponse ExecuteDataQuery(const Query& query, Args&&... args);
84
85 template <typename... Args>
86 ExecuteResponse ExecuteDataQuery(OperationSettings settings,
87 const Query& query, Args&&... args);
88
89 ExecuteResponse ExecuteDataQuery(OperationSettings settings,
90 const Query& query,
91 PreparedArgsBuilder&& builder);
92
93 ExecuteResponse ExecuteDataQuery(QuerySettings query_settings,
94 OperationSettings settings,
95 const Query& query,
96 PreparedArgsBuilder&& builder);
97 /// @}
98
99 /// @name Transactions
100 /// @brief Begin a transaction with the specified name. The settings are used
101 /// for the `BEGIN` statement.
102 /// @see ydb::Transaction
103 ///
104 /// @{
105 Transaction Begin(std::string transaction_name,
106 OperationSettings settings = {});
107
108 Transaction Begin(std::string transaction_name, TransactionMode tx_mode);
109 /// @}
110
111 /// Builder for storing dynamic query params.
112 PreparedArgsBuilder GetBuilder() const;
113
114 /// Efficiently write large ranges of table data.
115 void BulkUpsert(std::string_view table, NYdb::TValue&& rows,
116 OperationSettings settings = {});
117
118 /// Efficiently write large ranges of table data.
119 /// The passed range of structs is serialized to TValue.
120 template <typename RangeOfStructs>
121 void BulkUpsert(std::string_view table, const RangeOfStructs& rows,
122 OperationSettings settings = {});
123
124 /// Efficiently read large ranges of table data.
125 ReadTableResults ReadTable(
126 std::string_view table,
127 NYdb::NTable::TReadTableSettings&& read_settings = {},
128 OperationSettings settings = {});
129
130 /// @name Scan queries execution
131 /// A separate data access interface designed primarily for performing
132 /// analytical ad-hoc queries.
133 /// @{
134 template <typename... Args>
135 ScanQueryResults ExecuteScanQuery(const Query& query, Args&&... args);
136
137 template <typename... Args>
138 ScanQueryResults ExecuteScanQuery(ScanQuerySettings&& scan_settings,
139 OperationSettings settings,
140 const Query& query, Args&&... args);
141
142 ScanQueryResults ExecuteScanQuery(ScanQuerySettings&& scan_settings,
143 OperationSettings settings,
144 const Query& query,
145 PreparedArgsBuilder&& builder);
146 /// @}
147
148 /// @cond
149 // For internal use only.
150 void SetDefaultSettings(OperationSettings settings);
151
152 // For internal use only.
153 friend void DumpMetric(utils::statistics::Writer& writer,
154 const TableClient& table_client);
155 /// @endcond
156
157 NYdb::NTable::TTableClient& GetNativeTableClient();
158 utils::RetryBudget& GetRetryBudget();
159
160 private:
161 friend class Transaction;
162 friend struct impl::RequestContext;
163
164 std::string JoinDbPath(std::string_view path) const;
165
166 static tracing::Span MakeSpan(const Query& query,
167 const OperationSettings& settings,
168 tracing::Span* custom_parent_span,
169 utils::impl::SourceLocation location);
170
171 void Select1();
172
173 static engine::Deadline GetDeadline(
174 tracing::Span& span, const dynamic_config::Snapshot& config_snapshot);
175
176 void PrepareSettings(const Query& query,
177 const dynamic_config::Snapshot& config_snapshot,
178 OperationSettings& os, impl::IsStreaming) const;
179
180 NYdb::NTable::TExecDataQuerySettings ToExecQuerySettings(
181 QuerySettings query_settings) const;
182
183 template <typename... Args>
184 PreparedArgsBuilder MakeBuilder(Args&&... args);
185
186 // Func: (TSession, const std::string& full_path, const Settings&)
187 // -> NThreading::TFuture<T>
188 // OR
189 // (TTableClient&, const std::string& full_path, const Settings&)
190 // -> NThreading::TFuture<T>
191 // ExecuteSchemeQueryImpl -> T
192 template <typename Settings, typename Func>
193 auto ExecuteWithPathImpl(std::string_view path,
194 std::string_view operation_name,
195 OperationSettings&& settings, Func&& func);
196
197 dynamic_config::Source config_source_;
198 rcu::Variable<OperationSettings> default_settings_;
199 const bool keep_in_query_cache_;
200 std::unique_ptr<impl::Stats> stats_;
201 std::shared_ptr<impl::Driver> driver_;
202 std::unique_ptr<NYdb::NScheme::TSchemeClient> scheme_client_;
203 std::unique_ptr<NYdb::NTable::TTableClient> table_client_;
204};
205
206template <typename... Args>
207PreparedArgsBuilder TableClient::MakeBuilder(Args&&... args) {
208 auto builder = GetBuilder();
209 builder.AddParams(std::forward<Args>(args)...);
210 return builder;
211}
212
213template <typename... Args>
214ExecuteResponse TableClient::ExecuteDataQuery(const Query& query,
215 Args&&... args) {
216 return ExecuteDataQuery(OperationSettings{}, query,
217 MakeBuilder(std::forward<Args>(args)...));
218}
219
220template <typename... Args>
221ExecuteResponse TableClient::ExecuteDataQuery(OperationSettings settings,
222 const Query& query,
223 Args&&... args) {
224 return ExecuteDataQuery(settings, query,
225 MakeBuilder(std::forward<Args>(args)...));
226}
227
228template <typename RangeOfStructs>
229void TableClient::BulkUpsert(std::string_view table, const RangeOfStructs& rows,
230 OperationSettings settings) {
231 NYdb::TValueBuilder builder;
232 ydb::Write(builder, rows);
233 BulkUpsert(table, builder.Build(), std::move(settings));
234}
235
236template <typename... Args>
237ScanQueryResults TableClient::ExecuteScanQuery(const Query& query,
238 Args&&... args) {
239 return ExecuteScanQuery(ScanQuerySettings{}, OperationSettings{}, query,
240 MakeBuilder(std::forward<Args>(args)...));
241}
242
243template <typename... Args>
244ScanQueryResults TableClient::ExecuteScanQuery(
245 ScanQuerySettings&& scan_settings, OperationSettings settings,
246 const Query& query, Args&&... args) {
247 return ExecuteScanQuery(std::move(scan_settings), std::move(settings), query,
248 MakeBuilder(std::forward<Args>(args)...));
249}
250
251} // namespace ydb
252
253USERVER_NAMESPACE_END