userver: userver/ydb/table.hpp Source File
All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Modules Pages Concepts
table.hpp
1#pragma once
2
3#include <ydb-cpp-sdk/client/query/client.h>
4#include <ydb-cpp-sdk/client/query/query.h>
5#include <ydb-cpp-sdk/client/table/table.h>
6
7#include <userver/dynamic_config/source.hpp>
8#include <userver/utils/statistics/fwd.hpp>
9
10#include <userver/ydb/builder.hpp>
11#include <userver/ydb/query.hpp>
12#include <userver/ydb/response.hpp>
13#include <userver/ydb/settings.hpp>
14#include <userver/ydb/transaction.hpp>
15
16namespace NMonitoring {
17class TMetricRegistry;
18} // namespace NMonitoring
19
20USERVER_NAMESPACE_BEGIN
21
22namespace tracing {
23class Span;
24} // namespace tracing
25
26namespace utils {
27class RetryBudget;
28} // namespace utils
29
30namespace ydb {
31
32namespace impl {
33struct Stats;
34struct TableSettings;
35class Driver;
36struct RequestContext;
37enum class IsStreaming : bool {};
38} // namespace impl
39
40using DescribePathSettings = NYdb::NScheme::TDescribePathSettings;
41using ListDirectorySettings = NYdb::NScheme::TListDirectorySettings;
42using MakeDirectorySettings = NYdb::NScheme::TMakeDirectorySettings;
43using RemoveDirectorySettings = NYdb::NScheme::TRemoveDirectorySettings;
44
45using BulkUpsertSettings = NYdb::NTable::TBulkUpsertSettings;
46using CreateTableSettings = NYdb::NTable::TCreateTableSettings;
47using DescribeTableSettings = NYdb::NTable::TDescribeTableSettings;
48using DropTableSettings = NYdb::NTable::TDropTableSettings;
49using ScanQuerySettings = NYdb::NTable::TStreamExecScanQuerySettings;
50
51class TableClient final {
52public:
53 /// @cond
54 // For internal use only.
55 TableClient(
56 impl::TableSettings settings,
57 OperationSettings operation_settings,
58 dynamic_config::Source config_source,
59 std::shared_ptr<impl::Driver> driver
60 );
61
62 ~TableClient();
63 /// @endcond
64
65 /// Query for creating/deleting tables
66 void ExecuteSchemeQuery(const std::string& query);
67
68 void MakeDirectory(const std::string& path, MakeDirectorySettings query_settings = {});
69 void RemoveDirectory(const std::string& path, RemoveDirectorySettings query_settings = {});
70
71 NYdb::NScheme::TDescribePathResult DescribePath(std::string_view path, DescribePathSettings query_settings = {});
72 NYdb::NScheme::TListDirectoryResult ListDirectory(std::string_view path, ListDirectorySettings query_settings = {});
73
74 NYdb::NTable::TDescribeTableResult DescribeTable(std::string_view path, DescribeTableSettings query_settings = {});
75 void CreateTable(
76 std::string_view path,
77 NYdb::NTable::TTableDescription&& table_desc,
78 CreateTableSettings query_settings = {}
79 );
80 void DropTable(std::string_view path, DropTableSettings query_settings = {});
81
82 /// @name Data queries execution
83 /// Execute a single data query outside of transactions. Query parameters are
84 /// passed in `Args` as "string key - value" pairs:
85 ///
86 /// @code
87 /// client.ExecuteDataQuery(query, "name1", value1, "name2", value2, ...);
88 /// @endcode
89 ///
90 /// Use ydb::PreparedArgsBuilder for storing a generic buffer of query params
91 /// if needed.
92 ///
93 /// @{
94 template <typename... Args>
95 ExecuteResponse ExecuteDataQuery(const Query& query, Args&&... args);
96
97 template <typename... Args>
98 ExecuteResponse ExecuteDataQuery(OperationSettings settings, const Query& query, Args&&... args);
99
100 ExecuteResponse ExecuteDataQuery(OperationSettings settings, const Query& query, PreparedArgsBuilder&& builder);
101
102 ExecuteResponse ExecuteDataQuery(
103 QuerySettings query_settings,
104 OperationSettings settings,
105 const Query& query,
106 PreparedArgsBuilder&& builder
107 );
108 /// @}
109
110 /// @name Transactions
111 /// @brief Begin a transaction with the specified name. The settings are used
112 /// for the `BEGIN` statement.
113 /// @see ydb::Transaction
114 ///
115 /// @{
116 Transaction Begin(std::string transaction_name, OperationSettings settings = {});
117
118 Transaction Begin(std::string transaction_name, TransactionMode tx_mode);
119 /// @}
120
121 /// Builder for storing dynamic query params.
122 PreparedArgsBuilder GetBuilder() const;
123
124 /// Efficiently write large ranges of table data.
126 std::string_view table,
127 NYdb::TValue&& rows,
128 OperationSettings settings = {},
129 BulkUpsertSettings query_settings = {}
130 );
131
132 /// Efficiently write large ranges of table data.
133 /// The passed range of structs is serialized to TValue.
134 template <typename RangeOfStructs>
135 void BulkUpsert(std::string_view table, const RangeOfStructs& rows, OperationSettings settings = {});
136
137 /// Efficiently read large ranges of table data.
138 ReadTableResults ReadTable(
139 std::string_view table,
140 NYdb::NTable::TReadTableSettings&& read_settings = {},
141 OperationSettings settings = {}
142 );
143
144 /// @name Scan queries execution
145 /// A separate data access interface designed primarily for performing
146 /// analytical ad-hoc queries.
147 /// @{
148 template <typename... Args>
149 ScanQueryResults ExecuteScanQuery(const Query& query, Args&&... args);
150
151 template <typename... Args>
152 ScanQueryResults
153 ExecuteScanQuery(ScanQuerySettings&& scan_settings, OperationSettings settings, const Query& query, Args&&... args);
154
155 ScanQueryResults ExecuteScanQuery(
156 ScanQuerySettings&& scan_settings,
157 OperationSettings settings,
158 const Query& query,
159 PreparedArgsBuilder&& builder
160 );
161 /// @}
162
163 /// @name Queries execution (using YDB Query SDK)
164 /// Execute a single query outside of transactions. Query parameters are
165 /// passed in `Args` as "string key - value" pairs:
166 ///
167 /// @code
168 /// client.ExecuteQuery(query, "name1", value1, "name2", value2, ...);
169 /// @endcode
170 ///
171 /// Use ydb::PreparedArgsBuilder for storing a generic buffer of query params
172 /// if needed.
173 ///
174 /// If both exec_settings and settings args are passed,
175 /// exec_settings.client_timeout_ms and exec_settings.trace_id are ignored
176 /// and are overwritten by settings.client_timeout_ms and settings.trace_id.
177 /// @{
178 template <typename... Args>
179 ExecuteResponse ExecuteQuery(const Query& query, Args&&... args);
180
181 template <typename... Args>
182 ExecuteResponse ExecuteQuery(OperationSettings settings, const Query& query, Args&&... args);
183
184 ExecuteResponse ExecuteQuery(OperationSettings settings, const Query& query, PreparedArgsBuilder&& builder);
185
186 ExecuteResponse ExecuteQuery(
187 NYdb::NQuery::TExecuteQuerySettings&& exec_settings,
188 OperationSettings settings,
189 const Query& query,
190 PreparedArgsBuilder&& builder
191 );
192 /// @}
193
194 /// @cond
195 // For internal use only.
196 friend void DumpMetric(utils::statistics::Writer& writer, const TableClient& table_client);
197 /// @endcond
198
199 /// Get native table or query client
200 /// @warning Use with care! Facilities from
201 /// `<core/include/userver/drivers/subscribable_futures.hpp>` can help with
202 /// non-blocking wait operations.
203 /// @{
204 NYdb::NTable::TTableClient& GetNativeTableClient();
205
206 NYdb::NQuery::TQueryClient& GetNativeQueryClient();
207 /// @}
208
209 utils::RetryBudget& GetRetryBudget();
210
211private:
212 friend class Transaction;
213 friend struct impl::RequestContext;
214
215 std::string JoinDbPath(std::string_view path) const;
216
217 void Select1();
218
219 NYdb::NTable::TExecDataQuerySettings ToExecQuerySettings(QuerySettings query_settings) const;
220
221 template <typename... Args>
222 PreparedArgsBuilder MakeBuilder(Args&&... args);
223
224 // Func: (TSession, const std::string& full_path, const Settings&)
225 // -> NThreading::TFuture<T>
226 // OR
227 // (TTableClient&, const std::string& full_path, const Settings&)
228 // -> NThreading::TFuture<T>
229 // ExecuteSchemeQueryImpl -> T
230 template <typename QuerySettings, typename Func>
231 auto ExecuteWithPathImpl(
232 std::string_view path,
233 std::string_view operation_name,
234 OperationSettings settings,
235 QuerySettings&& query_settings,
236 Func&& func
237 );
238
239 dynamic_config::Source config_source_;
240 const OperationSettings default_settings_;
241 const bool keep_in_query_cache_;
242 std::unique_ptr<impl::Stats> stats_;
243 std::shared_ptr<impl::Driver> driver_;
244 std::unique_ptr<NYdb::NScheme::TSchemeClient> scheme_client_;
245 std::unique_ptr<NYdb::NTable::TTableClient> table_client_;
246 std::unique_ptr<NYdb::NQuery::TQueryClient> query_client_;
247};
248
249template <typename... Args>
250PreparedArgsBuilder TableClient::MakeBuilder(Args&&... args) {
251 auto builder = GetBuilder();
252 builder.AddParams(std::forward<Args>(args)...);
253 return builder;
254}
255
256template <typename... Args>
257ExecuteResponse TableClient::ExecuteDataQuery(const Query& query, Args&&... args) {
258 return ExecuteDataQuery(OperationSettings{}, query, MakeBuilder(std::forward<Args>(args)...));
259}
260
261template <typename... Args>
262ExecuteResponse TableClient::ExecuteDataQuery(OperationSettings settings, const Query& query, Args&&... args) {
263 return ExecuteDataQuery(settings, query, MakeBuilder(std::forward<Args>(args)...));
264}
265
266template <typename RangeOfStructs>
267void TableClient::BulkUpsert(std::string_view table, const RangeOfStructs& rows, OperationSettings settings) {
268 NYdb::TValueBuilder builder;
269 ydb::Write(builder, rows);
270 BulkUpsert(table, builder.Build(), std::move(settings));
271}
272
273template <typename... Args>
274ScanQueryResults TableClient::ExecuteScanQuery(const Query& query, Args&&... args) {
275 return ExecuteScanQuery(ScanQuerySettings{}, OperationSettings{}, query, MakeBuilder(std::forward<Args>(args)...));
276}
277
278template <typename... Args>
279ScanQueryResults TableClient::ExecuteScanQuery(
280 ScanQuerySettings&& scan_settings,
281 OperationSettings settings,
282 const Query& query,
283 Args&&... args
284) {
285 return ExecuteScanQuery(
286 std::move(scan_settings), std::move(settings), query, MakeBuilder(std::forward<Args>(args)...)
287 );
288}
289
290template <typename... Args>
291ExecuteResponse TableClient::ExecuteQuery(const Query& query, Args&&... args) {
292 return ExecuteQuery(OperationSettings{}, query, MakeBuilder(std::forward<Args>(args)...));
293}
294
295template <typename... Args>
296ExecuteResponse TableClient::ExecuteQuery(OperationSettings settings, const Query& query, Args&&... args) {
297 return ExecuteQuery(settings, query, MakeBuilder(std::forward<Args>(args)...));
298}
299
300} // namespace ydb
301
302USERVER_NAMESPACE_END