Couchbase C++ SDK 1.0.2 (rev. 51f4775)
Loading...
Searching...
No Matches
collection.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
23#include <couchbase/error.hxx>
25#include <couchbase/expiry.hxx>
47
48#include <future>
49#include <memory>
50
51namespace couchbase
52{
53#ifndef COUCHBASE_CXX_CLIENT_DOXYGEN
54namespace core
55{
56class cluster;
57} // namespace core
58class bucket;
59class scope;
60class collection_impl;
61#endif
62
70{
71public:
78 static constexpr auto default_name{ "_default" };
79
88 [[nodiscard]] auto bucket_name() const -> const std::string&;
89
98 [[nodiscard]] auto scope_name() const -> const std::string&;
99
108 [[nodiscard]] auto name() const -> const std::string&;
109
118 [[nodiscard]] auto binary() const -> binary_collection;
119
135 void get(std::string document_id, const get_options& options, get_handler&& handler) const;
136
152 [[nodiscard]] auto get(std::string document_id, const get_options& options = {}) const
153 -> std::future<std::pair<error, get_result>>;
154
171 void get_and_touch(std::string document_id,
172 std::chrono::seconds duration,
173 const get_and_touch_options& options,
174 get_and_touch_handler&& handler) const;
175
192 [[nodiscard]] auto get_and_touch(std::string document_id,
193 std::chrono::seconds duration,
194 const get_and_touch_options& options = {}) const
195 -> std::future<std::pair<error, get_result>>;
196
213 void get_and_touch(std::string document_id,
214 std::chrono::system_clock::time_point time_point,
215 const get_and_touch_options& options,
216 get_and_touch_handler&& handler) const;
217
234 [[nodiscard]] auto get_and_touch(std::string document_id,
235 std::chrono::system_clock::time_point time_point,
236 const get_and_touch_options& options = {}) const
237 -> std::future<std::pair<error, get_result>>;
238
255 void touch(std::string document_id,
256 std::chrono::seconds duration,
257 const touch_options& options,
258 touch_handler&& handler) const;
259
276 [[nodiscard]] auto touch(std::string document_id,
277 std::chrono::seconds duration,
278 const touch_options& options = {}) const
279 -> std::future<std::pair<error, result>>;
280
297 void touch(std::string document_id,
298 std::chrono::system_clock::time_point time_point,
299 const touch_options& options,
300 touch_handler&& handler) const;
301
318 [[nodiscard]] auto touch(std::string document_id,
319 std::chrono::system_clock::time_point time_point,
320 const touch_options& options = {}) const
321 -> std::future<std::pair<error, result>>;
322
340 void get_any_replica(std::string document_id,
341 const get_any_replica_options& options,
342 get_any_replica_handler&& handler) const;
343
368 [[nodiscard]] auto get_any_replica(std::string document_id,
369 const get_any_replica_options& options = {}) const
370 -> std::future<std::pair<error, get_replica_result>>;
371
388 void get_all_replicas(std::string document_id,
389 const get_all_replicas_options& options,
390 get_all_replicas_handler&& handler) const;
391
415 [[nodiscard]] auto get_all_replicas(std::string document_id,
416 const get_all_replicas_options& options = {}) const
417 -> std::future<std::pair<error, get_all_replicas_result>>;
418
434 void upsert(std::string document_id,
435 codec::encoded_value document,
436 const upsert_options& options,
437 upsert_handler&& handler) const;
438
456 template<typename Transcoder = codec::default_json_transcoder, typename Document>
457 void upsert(std::string document_id,
458 Document document,
459 const upsert_options& options,
460 upsert_handler&& handler) const
461 {
462 return upsert(
463 std::move(document_id), Transcoder::encode(document), options, std::move(handler));
464 }
465
481 [[nodiscard]] auto upsert(std::string document_id,
482 codec::encoded_value document,
483 const upsert_options& options) const
484 -> std::future<std::pair<error, mutation_result>>;
485
503 template<typename Transcoder = codec::default_json_transcoder, typename Document>
504 [[nodiscard]] auto upsert(std::string document_id,
505 const Document& document,
506 const upsert_options& options = {}) const
507 -> std::future<std::pair<error, mutation_result>>
508 {
509 return upsert(std::move(document_id), Transcoder::encode(document), options);
510 }
511
526 void insert(std::string document_id,
527 codec::encoded_value document,
528 const insert_options& options,
529 insert_handler&& handler) const;
530
550 template<typename Transcoder = codec::default_json_transcoder,
551 typename Document,
552 std::enable_if_t<!std::is_same_v<codec::encoded_value, Document>, bool> = true>
553 void insert(std::string document_id,
554 Document document,
555 const insert_options& options,
556 insert_handler&& handler) const
557 {
558 return insert(
559 std::move(document_id), Transcoder::encode(document), options, std::move(handler));
560 }
561
576 [[nodiscard]] auto insert(std::string document_id,
577 codec::encoded_value document,
578 const insert_options& options) const
579 -> std::future<std::pair<error, mutation_result>>;
580
600 template<typename Transcoder = codec::default_json_transcoder,
601 typename Document,
602 std::enable_if_t<!std::is_same_v<codec::encoded_value, Document>, bool> = true>
603 [[nodiscard]] auto insert(std::string document_id,
604 const Document& document,
605 const insert_options& options = {}) const
606 -> std::future<std::pair<error, mutation_result>>
607 {
608 return insert(std::move(document_id), Transcoder::encode(document), options);
609 }
610
625 void replace(std::string document_id,
626 codec::encoded_value document,
627 const replace_options& options,
628 replace_handler&& handler) const;
629
651 template<typename Transcoder = codec::default_json_transcoder,
652 typename Document,
653 std::enable_if_t<!std::is_same_v<codec::encoded_value, Document>, bool> = true>
654 void replace(std::string document_id,
655 Document document,
656 const replace_options& options,
657 replace_handler&& handler) const
658 {
659 return replace(
660 std::move(document_id), Transcoder::encode(document), options, std::move(handler));
661 }
662
677 [[nodiscard]] auto replace(std::string document_id,
678 codec::encoded_value document,
679 const replace_options& options) const
680 -> std::future<std::pair<error, mutation_result>>;
681
703 template<typename Transcoder = codec::default_json_transcoder,
704 typename Document,
705 std::enable_if_t<!std::is_same_v<codec::encoded_value, Document>, bool> = true>
706 [[nodiscard]] auto replace(std::string document_id,
707 const Document& document,
708 const replace_options& options = {}) const
709 -> std::future<std::pair<error, mutation_result>>
710 {
711 return replace(std::move(document_id), Transcoder::encode(document), options);
712 }
713
731 void remove(std::string document_id,
732 const remove_options& options,
733 remove_handler&& handler) const;
734
752 [[nodiscard]] auto remove(std::string document_id, const remove_options& options = {}) const
753 -> std::future<std::pair<error, mutation_result>>;
754
775 void mutate_in(std::string document_id,
776 const mutate_in_specs& specs,
777 const mutate_in_options& options,
778 mutate_in_handler&& handler) const;
779
800 [[nodiscard]] auto mutate_in(std::string document_id,
801 const mutate_in_specs& specs,
802 const mutate_in_options& options = {}) const
803 -> std::future<std::pair<error, mutate_in_result>>;
804
821 void lookup_in(std::string document_id,
822 const lookup_in_specs& specs,
823 const lookup_in_options& options,
824 lookup_in_handler&& handler) const;
825
842 [[nodiscard]] auto lookup_in(std::string document_id,
843 const lookup_in_specs& specs,
844 const lookup_in_options& options = {}) const
845 -> std::future<std::pair<error, lookup_in_result>>;
846
864 void lookup_in_all_replicas(std::string document_id,
865 const lookup_in_specs& specs,
866 const lookup_in_all_replicas_options& options,
867 lookup_in_all_replicas_handler&& handler) const;
868
886 [[nodiscard]] auto lookup_in_all_replicas(std::string document_id,
887 const lookup_in_specs& specs,
888 const lookup_in_all_replicas_options& options = {})
889 const -> std::future<std::pair<error, lookup_in_all_replicas_result>>;
890
908 void lookup_in_any_replica(std::string document_id,
909 const lookup_in_specs& specs,
910 const lookup_in_any_replica_options& options,
911 lookup_in_any_replica_handler&& handler) const;
912
930 [[nodiscard]] auto lookup_in_any_replica(std::string document_id,
931 const lookup_in_specs& specs,
932 const lookup_in_any_replica_options& options = {}) const
933 -> std::future<std::pair<error, lookup_in_replica_result>>;
934
946 void get_and_lock(std::string document_id,
947 std::chrono::seconds lock_duration,
948 const get_and_lock_options& options,
949 get_and_lock_handler&& handler) const;
950
962 [[nodiscard]] auto get_and_lock(std::string document_id,
963 std::chrono::seconds lock_duration,
964 const get_and_lock_options& options = {}) const
965 -> std::future<std::pair<error, get_result>>;
966
985 void unlock(std::string document_id,
987 const unlock_options& options,
988 unlock_handler&& handler) const;
989
1008 [[nodiscard]] auto unlock(std::string document_id,
1010 const unlock_options& options = {}) const -> std::future<error>;
1011
1025 void exists(std::string document_id,
1026 const exists_options& options,
1027 exists_handler&& handler) const;
1028
1042 [[nodiscard]] auto exists(std::string document_id, const exists_options& options = {}) const
1043 -> std::future<std::pair<error, exists_result>>;
1044
1060 void scan(const scan_type& scan_type, const scan_options& options, scan_handler&& handler) const;
1061
1077 [[nodiscard]] auto scan(const scan_type& scan_type, const scan_options& options = {}) const
1078 -> std::future<std::pair<error, scan_result>>;
1079
1080 [[nodiscard]] auto query_indexes() const -> collection_query_index_manager;
1081
1082private:
1083 friend class bucket;
1084 friend class scope;
1085
1086 collection(core::cluster core,
1087 std::string_view bucket_name,
1088 std::string_view scope_name,
1089 std::string_view name);
1090
1091 std::shared_ptr<collection_impl> impl_;
1092};
1093} // namespace couchbase
Allows to perform certain operations on non-JSON documents.
Definition binary_collection.hxx:47
Provides access to Couchbase bucket.
Definition bucket.hxx:45
CAS is a special type that represented in protocol using unsigned 64-bit integer, but only equality c...
Definition cas.hxx:34
The cluster is the main entry point when connecting to a Couchbase cluster.
Definition cluster.hxx:60
The Query Index Manager interface contains the means for managing indexes used for queries.
Definition collection_query_index_manager.hxx:53
The collection provides access to all collection APIs.
Definition collection.hxx:70
auto touch(std::string document_id, std::chrono::system_clock::time_point time_point, const touch_options &options={}) const -> std::future< std::pair< error, result > >
Updates the expiration a document given an id, without modifying or returning its value.
auto replace(std::string document_id, codec::encoded_value document, const replace_options &options) const -> std::future< std::pair< error, mutation_result > >
Replaces a body of the document which already exists with specified encoded body.
void replace(std::string document_id, Document document, const replace_options &options, replace_handler &&handler) const
Replaces a full document which already exists.
Definition collection.hxx:654
auto insert(std::string document_id, const Document &document, const insert_options &options={}) const -> std::future< std::pair< error, mutation_result > >
Inserts a full document which does not exist yet with custom options.
Definition collection.hxx:603
auto scan(const scan_type &scan_type, const scan_options &options={}) const -> std::future< std::pair< error, scan_result > >
Performs a key-value scan operation on the collection.
auto mutate_in(std::string document_id, const mutate_in_specs &specs, const mutate_in_options &options={}) const -> std::future< std::pair< error, mutate_in_result > >
Performs mutations to document fragments.
void remove(std::string document_id, const remove_options &options, remove_handler &&handler) const
Removes a Document from a collection.
auto bucket_name() const -> const std::string &
Returns name of the bucket where the collection is defined.
auto unlock(std::string document_id, couchbase::cas cas, const unlock_options &options={}) const -> std::future< error >
Unlocks a document if it has been locked previously, with default options.
void lookup_in_all_replicas(std::string document_id, const lookup_in_specs &specs, const lookup_in_all_replicas_options &options, lookup_in_all_replicas_handler &&handler) const
Performs lookups to document fragments with default options from all replicas and the active node and...
void get_and_lock(std::string document_id, std::chrono::seconds lock_duration, const get_and_lock_options &options, get_and_lock_handler &&handler) const
Gets a document for a given id and places a pessimistic lock on it for mutations.
static constexpr auto default_name
Constant for the name of the default collection in the bucket.
Definition collection.hxx:78
auto binary() const -> binary_collection
Provides access to the binary APIs, not used for JSON documents.
void scan(const scan_type &scan_type, const scan_options &options, scan_handler &&handler) const
Performs a key-value scan operation on the collection.
void lookup_in_any_replica(std::string document_id, const lookup_in_specs &specs, const lookup_in_any_replica_options &options, lookup_in_any_replica_handler &&handler) const
Performs lookups to document fragments with default options from all replicas and returns the first f...
void touch(std::string document_id, std::chrono::system_clock::time_point time_point, const touch_options &options, touch_handler &&handler) const
Updates the expiration a document given an id, without modifying or returning its value.
void exists(std::string document_id, const exists_options &options, exists_handler &&handler) const
Checks if the document exists on the server.
void get_and_touch(std::string document_id, std::chrono::seconds duration, const get_and_touch_options &options, get_and_touch_handler &&handler) const
Fetches a full document and resets its expiration time to the value provided.
auto lookup_in_all_replicas(std::string document_id, const lookup_in_specs &specs, const lookup_in_all_replicas_options &options={}) const -> std::future< std::pair< error, lookup_in_all_replicas_result > >
Performs lookups to document fragments with default options from all replicas and the active node and...
void get_any_replica(std::string document_id, const get_any_replica_options &options, get_any_replica_handler &&handler) const
Reads all available replicas, and returns the first found.
auto get_and_touch(std::string document_id, std::chrono::seconds duration, const get_and_touch_options &options={}) const -> std::future< std::pair< error, get_result > >
Fetches a full document and resets its expiration time to the value provided.
void lookup_in(std::string document_id, const lookup_in_specs &specs, const lookup_in_options &options, lookup_in_handler &&handler) const
Performs lookups to document fragments with default options.
void replace(std::string document_id, codec::encoded_value document, const replace_options &options, replace_handler &&handler) const
Replaces a body of the document which already exists with specified encoded body.
auto replace(std::string document_id, const Document &document, const replace_options &options={}) const -> std::future< std::pair< error, mutation_result > >
Replaces a full document which already exists.
Definition collection.hxx:706
auto get_and_touch(std::string document_id, std::chrono::system_clock::time_point time_point, const get_and_touch_options &options={}) const -> std::future< std::pair< error, get_result > >
Fetches a full document and resets its expiration time to the absolute value provided.
auto upsert(std::string document_id, const Document &document, const upsert_options &options={}) const -> std::future< std::pair< error, mutation_result > >
Upserts a full document which might or might not exist yet with custom options.
Definition collection.hxx:504
auto touch(std::string document_id, std::chrono::seconds duration, const touch_options &options={}) const -> std::future< std::pair< error, result > >
Updates the expiration a document given an id, without modifying or returning its value.
void upsert(std::string document_id, codec::encoded_value document, const upsert_options &options, upsert_handler &&handler) const
Upserts an encoded body of the document which might or might not exist yet, with custom options.
void upsert(std::string document_id, Document document, const upsert_options &options, upsert_handler &&handler) const
Upserts a full document which might or might not exist yet with custom options.
Definition collection.hxx:457
auto remove(std::string document_id, const remove_options &options={}) const -> std::future< std::pair< error, mutation_result > >
Removes a Document from a collection.
auto name() const -> const std::string &
Returns name of the collection.
auto upsert(std::string document_id, codec::encoded_value document, const upsert_options &options) const -> std::future< std::pair< error, mutation_result > >
Upserts an encoded body of the document which might or might not exist yet, with custom options.
auto lookup_in(std::string document_id, const lookup_in_specs &specs, const lookup_in_options &options={}) const -> std::future< std::pair< error, lookup_in_result > >
Performs lookups to document fragments with default options.
auto exists(std::string document_id, const exists_options &options={}) const -> std::future< std::pair< error, exists_result > >
Checks if the document exists on the server.
void insert(std::string document_id, codec::encoded_value document, const insert_options &options, insert_handler &&handler) const
Inserts an encoded body of the document which does not exist yet with custom options.
void get(std::string document_id, const get_options &options, get_handler &&handler) const
Fetches the full document from this collection.
auto get_all_replicas(std::string document_id, const get_all_replicas_options &options={}) const -> std::future< std::pair< error, get_all_replicas_result > >
Reads from all available replicas and the active node and returns the results as a vector.
auto get_and_lock(std::string document_id, std::chrono::seconds lock_duration, const get_and_lock_options &options={}) const -> std::future< std::pair< error, get_result > >
Gets a document for a given id and places a pessimistic lock on it for mutations.
auto get_any_replica(std::string document_id, const get_any_replica_options &options={}) const -> std::future< std::pair< error, get_replica_result > >
Reads all available replicas, and returns the first found.
auto lookup_in_any_replica(std::string document_id, const lookup_in_specs &specs, const lookup_in_any_replica_options &options={}) const -> std::future< std::pair< error, lookup_in_replica_result > >
Performs lookups to document fragments with default options from all replicas and returns the first f...
void get_all_replicas(std::string document_id, const get_all_replicas_options &options, get_all_replicas_handler &&handler) const
Reads from all available replicas and the active node and returns the results as a vector.
auto query_indexes() const -> collection_query_index_manager
void mutate_in(std::string document_id, const mutate_in_specs &specs, const mutate_in_options &options, mutate_in_handler &&handler) const
Performs mutations to document fragments.
void unlock(std::string document_id, couchbase::cas cas, const unlock_options &options, unlock_handler &&handler) const
Unlocks a document if it has been locked previously, with default options.
auto insert(std::string document_id, codec::encoded_value document, const insert_options &options) const -> std::future< std::pair< error, mutation_result > >
Inserts an encoded body of the document which does not exist yet with custom options.
auto scope_name() const -> const std::string &
Returns name of the scope where the collection is defined.
void touch(std::string document_id, std::chrono::seconds duration, const touch_options &options, touch_handler &&handler) const
Updates the expiration a document given an id, without modifying or returning its value.
void get_and_touch(std::string document_id, std::chrono::system_clock::time_point time_point, const get_and_touch_options &options, get_and_touch_handler &&handler) const
Fetches a full document and resets its expiration time to the absolute value provided.
void insert(std::string document_id, Document document, const insert_options &options, insert_handler &&handler) const
Inserts a full document which does not exist yet with custom options.
Definition collection.hxx:553
Definition lookup_in_specs.hxx:34
Definition mutate_in_specs.hxx:80
The scope identifies a group of collections and allows high application density as a result.
Definition scope.hxx:47
json_transcoder< tao_json_serializer > default_json_transcoder
Definition default_json_transcoder.hxx:28
Represents a single item from the result of collection::scan()
Definition allow_querying_search_index_options.hxx:28
std::function< void(error, get_replica_result)> get_any_replica_handler
The signature for the handler of the collection::get_any_replica() operation.
Definition get_any_replica_options.hxx:92
std::function< void(error, mutation_result)> insert_handler
The signature for the handler of the collection::insert() operation.
Definition insert_options.hxx:114
@ replace
Replace the document, fail if it does not exist.
@ upsert
Replace the document or create it if it does not exist.
@ insert
Create the document, fail if it exists.
std::function< void(error, lookup_in_result)> lookup_in_handler
The signature for the handler of the collection::lookup_in() operation.
Definition lookup_in_options.hxx:94
std::function< void(error, get_result)> get_handler
The signature for the handler of the collection::get() operation.
Definition get_options.hxx:111
std::function< void(error, get_all_replicas_result)> get_all_replicas_handler
The signature for the handler of the collection::get_all_replicas() operation.
Definition get_all_replicas_options.hxx:101
std::function< void(error, get_result)> get_and_lock_handler
The signature for the handler of the collection::get_and_lock() operation.
Definition get_and_lock_options.hxx:70
std::function< void(error, mutation_result)> remove_handler
The signature for the handler of the collection::remove() operation.
Definition remove_options.hxx:103
std::function< void(error, mutation_result)> upsert_handler
The signature for the handler of the collection::upsert() operation.
Definition upsert_options.hxx:138
std::function< void(error, mutate_in_result)> mutate_in_handler
The signature for the handler of the collection::mutate_in() operation.
Definition mutate_in_options.hxx:219
std::function< void(error, lookup_in_all_replicas_result)> lookup_in_all_replicas_handler
The signature for the handler of the collection::lookup_in_all_replicas() operation.
Definition lookup_in_all_replicas_options.hxx:106
std::function< void(error, scan_result)> scan_handler
The signature for the handler of the collection::scan() operation.
Definition scan_options.hxx:168
std::function< void(error, result)> touch_handler
The signature for the handler of the collection::touch() operation.
Definition touch_options.hxx:70
std::function< void(error, mutation_result)> replace_handler
The signature for the handler of the collection::replace() operation.
Definition replace_options.hxx:167
std::function< void(error, lookup_in_replica_result)> lookup_in_any_replica_handler
The signature for the handler of the collection::lookup_in_any_replica() operation.
Definition lookup_in_any_replica_options.hxx:97
std::function< void(error)> unlock_handler
The signature for the handler of the collection::unlock() operation.
Definition unlock_options.hxx:73
std::function< void(error, get_result)> get_and_touch_handler
The signature for the handler of the collection::get_and_touch() operation.
Definition get_and_touch_options.hxx:70
std::function< void(error, exists_result)> exists_handler
The signature for the handler of the collection::exists() operation.
Definition exists_options.hxx:74
Definition encoded_value.hxx:27
Options for collection::exists().
Definition exists_options.hxx:41
Options for collection::get_all_replicas().
Definition get_all_replicas_options.hxx:36
Options for collection::get_and_lock().
Definition get_and_lock_options.hxx:37
Options for collection::get_and_touch().
Definition get_and_touch_options.hxx:37
Options for collection::get_any_replica().
Definition get_any_replica_options.hxx:35
Options for collection::get().
Definition get_options.hxx:37
Options for collection::insert().
Definition insert_options.hxx:41
Options for collection::lookup_in_all_replicas().
Definition lookup_in_all_replicas_options.hxx:41
Options for collection::lookup_in_any_replica().
Definition lookup_in_any_replica_options.hxx:40
Options for collection::lookup_in().
Definition lookup_in_options.hxx:44
Options for collection::mutate_in().
Definition mutate_in_options.hxx:44
Options for collection::remove().
Definition remove_options.hxx:41
Options for collection::replace().
Definition replace_options.hxx:41
Options for collection::scan().
Definition scan_options.hxx:40
The base class for the different scan types.
Definition scan_type.hxx:96
Options for collection::touch().
Definition touch_options.hxx:37
Options for collection::unlock().
Definition unlock_options.hxx:40
Options for collection::upsert().
Definition upsert_options.hxx:41