Couchbase C++ SDK 1.0.2 (rev. 51f4775)
Loading...
Searching...
No Matches
query_options.hxx
Go to the documentation of this file.
1/* -*- Mode: C++; tab-width: 4; c-basic-offset: 4; indent-tabs-mode: nil -*- */
2/*
3 * Copyright 2020-Present Couchbase, Inc.
4 *
5 * Licensed under the Apache License, Version 2.0 (the "License");
6 * you may not use this file except in compliance with the License.
7 * You may obtain a copy of the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17
18#pragma once
19
21#include <couchbase/error.hxx>
26
27#include <chrono>
28#include <functional>
29#include <map>
30#include <optional>
31#include <vector>
32
33namespace couchbase
34{
35namespace codec
36{
37class tao_json_serializer;
38} // namespace codec
39
46struct query_options : public common_options<query_options> {
53 struct built : public common_options<query_options>::built {
54 const bool adhoc;
55 const bool metrics;
56 const bool readonly;
57 const bool flex_index;
58 const bool preserve_expiry;
59 std::optional<bool> use_replica;
60 std::optional<std::uint64_t> max_parallelism;
61 std::optional<std::uint64_t> scan_cap;
62 std::optional<std::chrono::milliseconds> scan_wait;
63 std::optional<std::uint64_t> pipeline_batch;
64 std::optional<std::uint64_t> pipeline_cap;
65 std::optional<std::string> client_context_id;
66 std::optional<query_scan_consistency> scan_consistency;
67 std::vector<mutation_token> mutation_state;
68 std::optional<query_profile> profile;
69 std::vector<codec::binary> positional_parameters;
70 std::map<std::string, codec::binary, std::less<>> named_parameters;
71 std::map<std::string, codec::binary, std::less<>> raw;
72 };
73
85 [[nodiscard]] auto build() const -> built
86 {
87 return {
89 adhoc_,
90 metrics_,
91 readonly_,
92 flex_index_,
93 preserve_expiry_,
94 use_replica_,
95 max_parallelism_,
96 scan_cap_,
97 scan_wait_,
98 pipeline_batch_,
99 pipeline_cap_,
100 client_context_id_,
101 scan_consistency_,
102 mutation_state_,
103 profile_,
104 positional_parameters_,
105 named_parameters_,
106 raw_,
107 };
108 }
109
128 auto adhoc(bool adhoc) -> query_options&
129 {
130 adhoc_ = adhoc;
131 return self();
132 }
133
148 auto metrics(bool metrics) -> query_options&
149 {
150 metrics_ = metrics;
151 return self();
152 }
153
171 {
172 profile_ = profile;
173 return self();
174 }
175
204 {
205 readonly_ = readonly;
206 return self();
207 }
208
219 {
220 flex_index_ = flex_index;
221 return self();
222 }
223
237 {
238 preserve_expiry_ = preserve_expiry;
239 return self();
240 }
241
254 {
255 use_replica_ = use_replica;
256 return self();
257 }
258
272 {
273 max_parallelism_ = max_parallelism;
274 return self();
275 }
276
289 auto scan_cap(std::uint64_t scan_cap) -> query_options&
290 {
291 scan_cap_ = scan_cap;
292 return self();
293 }
294
308 auto scan_wait(std::chrono::milliseconds wait) -> query_options&
309 {
310 if (scan_consistency_ == query_scan_consistency::not_bounded) {
311 scan_wait_.reset();
312 } else {
313 scan_wait_ = wait;
314 }
315 return self();
316 }
317
331 {
332 pipeline_batch_ = pipeline_batch;
333 return self();
334 }
335
350 {
351 pipeline_cap_ = pipeline_cap;
352 return self();
353 }
354
368 {
369 if (client_context_id.empty()) {
370 client_context_id_.reset();
371 } else {
372 client_context_id_ = std::move(client_context_id);
373 }
374 return self();
375 }
376
400 {
401 scan_consistency_ = scan_consistency;
402 mutation_state_.clear();
403 return self();
404 }
405
427 {
428 mutation_state_ = state.tokens();
429 scan_consistency_.reset();
430 return self();
431 }
432
443 template<typename Serializer = codec::tao_json_serializer,
444 typename Value,
445 std::enable_if_t<codec::is_serializer_v<Serializer>, bool> = true>
446 auto raw(std::string name, const Value& value) -> query_options&
447 {
448 raw_[std::move(name)] = std::move(Serializer::template serialize(value));
449 return self();
450 }
451
462 template<typename Serializer = codec::tao_json_serializer,
463 typename... Parameters,
464 std::enable_if_t<codec::is_serializer_v<Serializer>, bool> = true>
465 auto positional_parameters(const Parameters&... parameters) -> query_options&
466 {
467 named_parameters_.clear();
468 positional_parameters_.clear();
469 encode_positional_parameters<Serializer>(parameters...);
470 return self();
471 }
472
483 template<typename Serializer = codec::tao_json_serializer,
484 typename... Parameters,
485 std::enable_if_t<codec::is_serializer_v<Serializer>, bool> = true>
486 auto named_parameters(const Parameters&... parameters) -> query_options&
487 {
488 named_parameters_.clear();
489 positional_parameters_.clear();
490 encode_named_parameters<Serializer>(parameters...);
491 return self();
492 }
493
508 auto encoded_raw_options(std::map<std::string, codec::binary, std::less<>> options)
509 -> query_options&
510 {
511 raw_ = std::move(options);
512 return self();
513 }
514
530 auto encoded_positional_parameters(std::vector<codec::binary> parameters) -> query_options&
531 {
532 named_parameters_.clear();
533 positional_parameters_ = std::move(parameters);
534 return self();
535 }
536
551 auto encoded_named_parameters(std::map<std::string, codec::binary, std::less<>> parameters)
552 -> query_options&
553 {
554 named_parameters_ = std::move(parameters);
555 positional_parameters_.clear();
556 return self();
557 }
558
559private:
560 template<typename Serializer = codec::tao_json_serializer,
561 typename Parameter,
562 typename... Rest,
563 std::enable_if_t<codec::is_serializer_v<Serializer>, bool> = true>
564 void encode_positional_parameters(const Parameter& parameter, Rest... args)
565 {
566 positional_parameters_.emplace_back(std::move(Serializer::template serialize(parameter)));
567 if constexpr (sizeof...(args) > 0) {
568 encode_positional_parameters<Serializer>(args...);
569 }
570 }
571
572 template<typename Serializer = codec::tao_json_serializer,
573 typename Name,
574 typename Parameter,
575 typename... Rest,
576 std::enable_if_t<codec::is_serializer_v<Serializer>, bool> = true>
577 void encode_named_parameters(const std::pair<Name, Parameter>& parameter, Rest... args)
578 {
579 named_parameters_[parameter.first] =
580 std::move(Serializer::template serialize(parameter.second));
581 if constexpr (sizeof...(args) > 0) {
582 encode_named_parameters<Serializer>(args...);
583 }
584 }
585
586 bool adhoc_{ true };
587 bool metrics_{ false };
588 bool readonly_{ false };
589 bool flex_index_{ false };
590 bool preserve_expiry_{ false };
591 std::optional<bool> use_replica_{};
592 std::optional<std::uint64_t> max_parallelism_{};
593 std::optional<std::uint64_t> scan_cap_{};
594 std::optional<std::uint64_t> pipeline_batch_{};
595 std::optional<std::uint64_t> pipeline_cap_{};
596 std::optional<std::string> client_context_id_{};
597 std::optional<std::chrono::milliseconds> scan_wait_{};
598 std::optional<query_scan_consistency> scan_consistency_{};
599 std::vector<mutation_token> mutation_state_{};
600 std::optional<query_profile> profile_{};
601 std::vector<codec::binary> positional_parameters_{};
602 std::map<std::string, codec::binary, std::less<>> raw_{};
603 std::map<std::string, codec::binary, std::less<>> named_parameters_{};
604};
605
612using query_handler = std::function<void(error, query_result)>;
613} // namespace couchbase
Definition tao_json_serializer.hxx:42
Common options that used by most operations.
Definition common_options.hxx:37
auto self() -> query_options &
Definition common_options.hxx:102
auto build_common_options() const -> built
Definition common_options.hxx:89
Definition error.hxx:30
Aggregation of one or more mutation_tokens for specifying consistency requirements of N1QL or FTS que...
Definition mutation_state.hxx:35
Represents result of cluster::query() and scope::query() calls.
Definition query_result.hxx:42
std::vector< std::byte > binary
Definition encoded_value.hxx:25
Represents a single item from the result of collection::scan()
Definition allow_querying_search_index_options.hxx:28
query_profile
Definition query_profile.hxx:22
query_scan_consistency
Definition query_scan_consistency.hxx:22
@ not_bounded
The indexer will return whatever state it has to the query engine at the time of query.
std::function< void(error, query_result)> query_handler
The signature for the handler of the cluster::query() and scope::query() operations.
Definition query_options.hxx:612
Immutable value object representing consistent options.
Definition query_options.hxx:53
std::vector< mutation_token > mutation_state
Definition query_options.hxx:67
std::optional< std::uint64_t > max_parallelism
Definition query_options.hxx:60
std::map< std::string, codec::binary, std::less<> > named_parameters
Definition query_options.hxx:70
const bool metrics
Definition query_options.hxx:55
std::optional< query_scan_consistency > scan_consistency
Definition query_options.hxx:66
std::optional< query_profile > profile
Definition query_options.hxx:68
const bool readonly
Definition query_options.hxx:56
std::optional< std::chrono::milliseconds > scan_wait
Definition query_options.hxx:62
std::map< std::string, codec::binary, std::less<> > raw
Definition query_options.hxx:71
const bool adhoc
Definition query_options.hxx:54
std::optional< std::uint64_t > scan_cap
Definition query_options.hxx:61
std::optional< std::string > client_context_id
Definition query_options.hxx:65
std::optional< bool > use_replica
Definition query_options.hxx:59
const bool flex_index
Definition query_options.hxx:57
const bool preserve_expiry
Definition query_options.hxx:58
std::vector< codec::binary > positional_parameters
Definition query_options.hxx:69
std::optional< std::uint64_t > pipeline_batch
Definition query_options.hxx:63
std::optional< std::uint64_t > pipeline_cap
Definition query_options.hxx:64
Options for cluster::query() and scope::query().
Definition query_options.hxx:46
auto client_context_id(std::string client_context_id) -> query_options &
Supports providing a custom client context ID for this query.
Definition query_options.hxx:367
auto named_parameters(const Parameters &... parameters) -> query_options &
Set list of named parameters for a query.
Definition query_options.hxx:486
auto preserve_expiry(bool preserve_expiry) -> query_options &
Tells the query engine to preserve expiration values set on any documents modified by this query.
Definition query_options.hxx:236
auto encoded_raw_options(std::map< std::string, codec::binary, std::less<> > options) -> query_options &
Set map of raw options for a query.
Definition query_options.hxx:508
auto metrics(bool metrics) -> query_options &
Enables per-request metrics in the trailing section of the query.
Definition query_options.hxx:148
auto max_parallelism(std::uint64_t max_parallelism) -> query_options &
Allows overriding the default maximum parallelism for the query execution on the server side.
Definition query_options.hxx:271
auto encoded_named_parameters(std::map< std::string, codec::binary, std::less<> > parameters) -> query_options &
Set map of named parameters for a query.
Definition query_options.hxx:551
auto raw(std::string name, const Value &value) -> query_options &
Definition query_options.hxx:446
auto pipeline_cap(std::uint64_t pipeline_cap) -> query_options &
Allows customizing the maximum number of items each execution operator can buffer between various ope...
Definition query_options.hxx:349
auto build() const -> built
Validates options and returns them as an immutable value.
Definition query_options.hxx:85
auto scan_wait(std::chrono::milliseconds wait) -> query_options &
Allows customizing how long the query engine is willing to wait until the index catches up to whateve...
Definition query_options.hxx:308
auto encoded_positional_parameters(std::vector< codec::binary > parameters) -> query_options &
Set list of positional parameters for a query.
Definition query_options.hxx:530
auto scan_cap(std::uint64_t scan_cap) -> query_options &
Supports customizing the maximum buffered channel size between the indexer and the query service.
Definition query_options.hxx:289
auto pipeline_batch(std::uint64_t pipeline_batch) -> query_options &
Supports customizing the number of items execution operators can batch for fetch from the KV layer on...
Definition query_options.hxx:330
auto readonly(bool readonly) -> query_options &
Allows explicitly marking a query as being readonly and not mutating and documents on the server side...
Definition query_options.hxx:203
auto use_replica(bool use_replica) -> query_options &
Specifies that the query engine should use replica nodes for KV fetches if the active node is down.
Definition query_options.hxx:253
auto adhoc(bool adhoc) -> query_options &
Allows turning this request into a prepared statement query.
Definition query_options.hxx:128
auto flex_index(bool flex_index) -> query_options &
Tells the query engine to use a flex index (utilizing the search service).
Definition query_options.hxx:218
auto consistent_with(const mutation_state &state) -> query_options &
Sets the mutation_tokens this query should be consistent with.
Definition query_options.hxx:426
auto scan_consistency(query_scan_consistency scan_consistency) -> query_options &
Customizes the consistency guarantees for this query.
Definition query_options.hxx:399
auto profile(query_profile profile) -> query_options &
Customizes the server profiling level for this query.
Definition query_options.hxx:170
auto positional_parameters(const Parameters &... parameters) -> query_options &
Set list of positional parameters for a query.
Definition query_options.hxx:465