couchbase 3.8.1 → 3.9.0

data/ext/couchbase/couchbase/collection.hxx

@@ -28,6 +28,8 @@
 #include <couchbase/get_and_touch_options.hxx>
 #include <couchbase/get_any_replica_options.hxx>
 #include <couchbase/get_options.hxx>
+#include <couchbase/get_replica_options.hxx>
+#include <couchbase/get_replica_strategy.hxx>
 #include <couchbase/insert_options.hxx>
 #include <couchbase/lookup_in_all_replicas_options.hxx>
 #include <couchbase/lookup_in_any_replica_options.hxx>
@@ -340,8 +342,13 @@ public:
    * @exception errc::common::ambiguous_timeout
    * @exception errc::common::unambiguous_timeout
    *
+   * @note Not served over the @ref couchbase2 "couchbase2" transport, which reports
+   * @ref errc::common::feature_not_available for replica reads.
+   *
    * @since 1.0.0
    * @committed
+   * @cng_since{1.4.0}
+   * @cng_uncommitted
    */
   void get_any_replica(std::string document_id,
                        const get_any_replica_options& options,
@@ -368,19 +375,98 @@ public:
    * @exception errc::common::ambiguous_timeout
    * @exception errc::common::unambiguous_timeout
    *
+   * @note Not served over the @ref couchbase2 "couchbase2" transport, which reports
+   * @ref errc::common::feature_not_available for replica reads.
+   *
    * @since 1.0.0
    * @committed
+   * @cng_since{1.4.0}
+   * @cng_uncommitted
    */
   [[nodiscard]] auto get_any_replica(std::string document_id,
                                      const get_any_replica_options& options = {}) const
     -> std::future<std::pair<error, get_replica_result>>;
 
+  /**
+   * Reads from the replica the strategy selects.
+   *
+   * @param document_id the document id which is used to uniquely identify it.
+   * @param strategy selects the replica to read from
+   * @param options the custom options
+   * @param handler the handler that implements @ref get_replica_handler
+   *
+   * @exception errc::key_value::document_not_found_on_replica
+   *    the replica responded, but does not hold the document. The @ref error::cause() is
+   *    @ref errc::key_value::document_not_found.
+   *
+   * @exception errc::key_value::replica_index_out_of_bounds
+   *    the requested index is at or beyond the bucket's configured replica count, or that count is
+   *    zero. Reported without a network round trip.
+   *
+   * @exception errc::key_value::replica_index_currently_unavailable
+   *    the index exists for this bucket, but the copy cannot be read now: the vbucket map's row is
+   *    shorter than the configured count, or it does not place that replica on a node the topology
+   *    lists.
+   *
+   * @exception errc::common::unambiguous_timeout
+   *
+   * @note Not served over the @ref couchbase2 "couchbase2" transport, which reports
+   * @ref errc::common::feature_not_available for replica reads.
+   *
+   * @since 1.5.0
+   * @committed
+   */
+  void get_replica(std::string document_id,
+                   const get_replica_strategy& strategy,
+                   const get_replica_options& options,
+                   get_replica_handler&& handler) const;
+
+  /**
+   * Reads from the replica the strategy selects.
+   *
+   * @snippet{trimleft} test_integration_read_replica.cxx get_replica-from_index
+   *
+   * @param document_id the document id which is used to uniquely identify it.
+   * @param strategy selects the replica to read from
+   * @param options the custom options
+   * @return the future object with the result of the selected replica.
+   *
+   * @exception errc::key_value::document_not_found_on_replica
+   *    the replica responded, but does not hold the document. The @ref error::cause() is
+   *    @ref errc::key_value::document_not_found.
+   *
+   * @exception errc::key_value::replica_index_out_of_bounds
+   *    the requested index is at or beyond the bucket's configured replica count, or that count is
+   *    zero. Reported without a network round trip.
+   *
+   * @exception errc::key_value::replica_index_currently_unavailable
+   *    the index exists for this bucket, but the copy cannot be read now: the vbucket map's row is
+   *    shorter than the configured count, or it does not place that replica on a node the topology
+   *    lists.
+   *
+   * @exception errc::common::unambiguous_timeout
+   *
+   * @note Not served over the @ref couchbase2 "couchbase2" transport, which reports
+   * @ref errc::common::feature_not_available for replica reads.
+   *
+   * @since 1.5.0
+   * @committed
+   */
+  [[nodiscard]] auto get_replica(std::string document_id,
+                                 const get_replica_strategy& strategy,
+                                 const get_replica_options& options = {}) const
+    -> std::future<std::pair<error, get_replica_result>>;
+
   /**
    * Reads from all available replicas and the active node and returns the results as a vector.
    *
    * @note Individual errors are ignored, so you can think of this API as a best effort
    * approach which explicitly emphasises availability over consistency.
    *
+   * @note Entries appear in response-arrival order, not vBucket map order.
+   * Use @c get_replica_result::is_replica() to distinguish the active node's
+   * entry; do not rely on positional indexing to identify it.
+   *
    * @param document_id the document id which is used to uniquely identify it.
    * @param options the custom options
    * @param handler the handler that implements @ref get_all_replicas_handler
@@ -388,8 +474,13 @@ public:
    * @exception errc::common::ambiguous_timeout
    * @exception errc::common::unambiguous_timeout
    *
+   * @note Not served over the @ref couchbase2 "couchbase2" transport, which reports
+   * @ref errc::common::feature_not_available for replica reads.
+   *
    * @since 1.0.0
    * @committed
+   * @cng_since{1.4.0}
+   * @cng_uncommitted
    */
   void get_all_replicas(std::string document_id,
                         const get_all_replicas_options& options,
@@ -401,6 +492,10 @@ public:
    * @note Individual errors are ignored, so you can think of this API as a best effort
    * approach which explicitly emphasises availability over consistency.
    *
+   * @note Entries appear in response-arrival order, not vBucket map order.
+   * Use @c get_replica_result::is_replica() to distinguish the active node's
+   * entry; do not rely on positional indexing to identify it.
+   *
    * Select preferred server group in connection options:
    * @snippet{trimleft} test_integration_read_replica.cxx select-preferred_server_group
    *
@@ -415,8 +510,13 @@ public:
    * @exception errc::common::ambiguous_timeout
    * @exception errc::common::unambiguous_timeout
    *
+   * @note Not served over the @ref couchbase2 "couchbase2" transport, which reports
+   * @ref errc::common::feature_not_available for replica reads.
+   *
    * @since 1.0.0
    * @committed
+   * @cng_since{1.4.0}
+   * @cng_uncommitted
    */
   [[nodiscard]] auto get_all_replicas(std::string document_id,
                                       const get_all_replicas_options& options = {}) const
@@ -784,8 +884,13 @@ public:
    * @exception errc::common::ambiguous_timeout
    * @exception errc::common::unambiguous_timeout
    *
+   * @note Not served over the @ref couchbase2 "couchbase2" transport, which reports
+   * @ref errc::common::feature_not_available for subdocument mutations.
+   *
    * @since 1.0.0
    * @committed
+   * @cng_since{1.4.0}
+   * @cng_uncommitted
    */
   void mutate_in(std::string document_id,
                  const mutate_in_specs& specs,
@@ -809,8 +914,13 @@ public:
    * @exception errc::common::ambiguous_timeout
    * @exception errc::common::unambiguous_timeout
    *
+   * @note Not served over the @ref couchbase2 "couchbase2" transport, which reports
+   * @ref errc::common::feature_not_available for subdocument mutations.
+   *
    * @since 1.0.0
    * @committed
+   * @cng_since{1.4.0}
+   * @cng_uncommitted
    */
   [[nodiscard]] auto mutate_in(std::string document_id,
                                const mutate_in_specs& specs,
@@ -830,8 +940,13 @@ public:
    * @exception errc::common::ambiguous_timeout
    * @exception errc::common::unambiguous_timeout
    *
+   * @note Not served over the @ref couchbase2 "couchbase2" transport, which reports
+   * @ref errc::common::feature_not_available for subdocument lookups.
+   *
    * @since 1.0.0
    * @committed
+   * @cng_since{1.4.0}
+   * @cng_uncommitted
    */
   void lookup_in(std::string document_id,
                  const lookup_in_specs& specs,
@@ -851,8 +966,13 @@ public:
    * @exception errc::common::ambiguous_timeout
    * @exception errc::common::unambiguous_timeout
    *
+   * @note Not served over the @ref couchbase2 "couchbase2" transport, which reports
+   * @ref errc::common::feature_not_available for subdocument lookups.
+   *
    * @since 1.0.0
    * @committed
+   * @cng_since{1.4.0}
+   * @cng_uncommitted
    */
   [[nodiscard]] auto lookup_in(std::string document_id,
                                const lookup_in_specs& specs,
@@ -863,6 +983,10 @@ public:
    * Performs lookups to document fragments with default options from all replicas and the active
    * node and returns the result as a vector.
    *
+   * @note Entries appear in response-arrival order, not vBucket map order.
+   * Use @c lookup_in_replica_result::is_replica() to distinguish the active
+   * node's entry; do not rely on positional indexing to identify it.
+   *
    * @param document_id the outer document ID
    * @param specs an object that specifies the types of lookups to perform
    * @param options custom options to modify the lookup options
@@ -873,8 +997,13 @@ public:
    * @exception errc::common::ambiguous_timeout
    * @exception errc::common::unambiguous_timeout
    *
+   * @note Not served over the @ref couchbase2 "couchbase2" transport, which reports
+   * @ref errc::common::feature_not_available for replica lookups.
+   *
    * @since 1.0.0
    * @committed
+   * @cng_since{1.4.0}
+   * @cng_uncommitted
    */
   void lookup_in_all_replicas(std::string document_id,
                               const lookup_in_specs& specs,
@@ -885,6 +1014,10 @@ public:
    * Performs lookups to document fragments with default options from all replicas and the active
    * node and returns the result as a vector.
    *
+   * @note Entries appear in response-arrival order, not vBucket map order.
+   * Use @c lookup_in_replica_result::is_replica() to distinguish the active
+   * node's entry; do not rely on positional indexing to identify it.
+   *
    * @param document_id the outer document ID
    * @param specs an object that specifies the types of lookups to perform
    * @param options custom options to modify the lookup options
@@ -895,8 +1028,13 @@ public:
    * @exception errc::common::ambiguous_timeout
    * @exception errc::common::unambiguous_timeout
    *
+   * @note Not served over the @ref couchbase2 "couchbase2" transport, which reports
+   * @ref errc::common::feature_not_available for replica lookups.
+   *
    * @since 1.0.0
    * @committed
+   * @cng_since{1.4.0}
+   * @cng_uncommitted
    */
   [[nodiscard]] auto lookup_in_all_replicas(std::string document_id,
                                             const lookup_in_specs& specs,
@@ -917,8 +1055,13 @@ public:
    * @exception errc::common::ambiguous_timeout
    * @exception errc::common::unambiguous_timeout
    *
+   * @note Not served over the @ref couchbase2 "couchbase2" transport, which reports
+   * @ref errc::common::feature_not_available for replica lookups.
+   *
    * @since 1.0.0
    * @committed
+   * @cng_since{1.4.0}
+   * @cng_uncommitted
    */
   void lookup_in_any_replica(std::string document_id,
                              const lookup_in_specs& specs,
@@ -939,8 +1082,13 @@ public:
    * @exception errc::common::ambiguous_timeout
    * @exception errc::common::unambiguous_timeout
    *
+   * @note Not served over the @ref couchbase2 "couchbase2" transport, which reports
+   * @ref errc::common::feature_not_available for replica lookups.
+   *
    * @since 1.0.0
    * @committed
+   * @cng_since{1.4.0}
+   * @cng_uncommitted
    */
   [[nodiscard]] auto lookup_in_any_replica(std::string document_id,
                                            const lookup_in_specs& specs,
@@ -1069,8 +1217,15 @@ public:
    * system may have to scan a lot of documents to find the matching documents. For low latency
    * range queries, it is recommended that you use SQL++ with the necessary indexes.
    *
+   * @note Not served over the @ref couchbase2 "couchbase2" transport, and not refused up front: the
+   * scan needs the bucket configuration and the per-node connections that transport does not open,
+   * so it fails on that path rather than reporting
+   * @ref errc::common::feature_not_available.
+   *
    * @since 1.0.0
    * @volatile
+   * @cng_since{1.4.0}
+   * @cng_uncommitted
    */
   void scan(const scan_type& scan_type, const scan_options& options, scan_handler&& handler) const;
 
@@ -1086,8 +1241,15 @@ public:
    * system may have to scan a lot of documents to find the matching documents. For low latency
    * range queries, it is recommended that you use SQL++ with the necessary indexes.
    *
+   * @note Not served over the @ref couchbase2 "couchbase2" transport, and not refused up front: the
+   * scan needs the bucket configuration and the per-node connections that transport does not open,
+   * so it fails on that path rather than reporting
+   * @ref errc::common::feature_not_available.
+   *
    * @since 1.0.0
    * @volatile
+   * @cng_since{1.4.0}
+   * @cng_uncommitted
    */
   [[nodiscard]] auto scan(const scan_type& scan_type, const scan_options& options = {}) const
     -> std::future<std::pair<error, scan_result>>;
@@ -1096,10 +1258,29 @@ public:
    * Resolves a document key to the identity of the cluster node that currently
    * owns it, using the client-side vBucket map (no network round-trip).
    *
+   * The handler is guaranteed to be invoked exactly once even if no bucket
+   * configuration ever arrives — the request timeout drives a fall-through to
+   * @c errc::common::unambiguous_timeout. On success the @c node_id is
+   * truthy and byte-for-byte equal to the @c node_id surfaced on results and
+   * errors of KV operations against the same key for the current topology.
+   *
+   * @note The returned identity reflects the topology snapshot at call
+   * time. During a rebalance, the @c node_id returned here may transiently
+   * not appear in a subsequent call to @ref node_ids (and vice versa); the
+   * two APIs are consistent only against a stable topology.
+   *
    * @param document_id the document id to resolve
-   * @param options options to customize the request
+   * @param options options to customize the request (e.g. timeout)
    * @param handler the handler that receives the result
    *
+   * @exception errc::common::invalid_argument if @p document_id is empty.
+   * @exception errc::common::bucket_not_found if the bucket does not exist.
+   * @exception errc::network::configuration_not_available if the bucket
+   *            configuration is present but the vBucket map does not resolve
+   *            the key to a known node.
+   * @exception errc::common::unambiguous_timeout if the bucket configuration
+   *            did not arrive within the request timeout.
+   *
    * @since 1.3.2
    * @uncommitted
    */
@@ -1115,6 +1296,14 @@ public:
    * @param options options to customize the request
    * @return future carrying the error (if any) and node_id
    *
+   * @exception errc::common::invalid_argument if @p document_id is empty.
+   * @exception errc::common::bucket_not_found if the bucket does not exist.
+   * @exception errc::network::configuration_not_available if the bucket
+   *            configuration is present but the vBucket map does not resolve
+   *            the key to a known node.
+   * @exception errc::common::unambiguous_timeout if the bucket configuration
+   *            did not arrive within the request timeout.
+   *
    * @since 1.3.2
    * @uncommitted
    */
@@ -1123,39 +1312,70 @@ public:
     -> std::future<std::pair<error, node_id>>;
 
   /**
-   * Returns the set of cluster nodes that currently serve key-value
-   * traffic for this collection's bucket, drawn from the client-side
-   * topology snapshot (no network round-trip).
+   * Returns the cluster nodes that currently serve key-value traffic for
+   * this collection's bucket, drawn from the client-side topology snapshot
+   * (no network round-trip).
    *
    * Each entry corresponds to one cluster node and is the same node_id
    * the SDK reports on KV results and errors that touched that node, so
-   * the returned set is directly comparable to the keys of any
+   * the returned vector is directly comparable to the keys of any
    * application-side state that is keyed by node_id (e.g. a per-node
    * circuit breaker registry). A periodic sweep that diffs the
    * registry's keys against this set is the canonical way to retire
    * tracker state for a node that has been removed from the cluster
    * topology.
    *
-   * Nodes that do not expose a key-value port for the configured
-   * transport (TLS or plain) are excluded from the returned set, since
-   * they do not serve KV operations and therefore have no meaningful
-   * identity from the SDK's point of view.
+   * Entries are returned in topology order; no deduplication is
+   * performed (topology nodes are unique by construction). Callers that
+   * want a set semantic can hash the entries themselves —
+   * @c std::hash<couchbase::node_id> is specialised for this purpose.
    *
-   * @param options options to customize the request
+   * Nodes that do not expose a key-value port for the configured
+   * transport (TLS or plain) are excluded from the result, since they do
+   * not serve KV operations and therefore have no meaningful identity
+   * from the SDK's point of view.
+   *
+   * @note The returned vector is a snapshot of the topology at call time.
+   * During a rebalance, a @c node_id previously returned by @ref
+   * node_id_for may transiently not appear here (and vice versa); the
+   * two APIs are consistent only against a stable topology. Application
+   * sweep loops should tolerate transient differences (e.g. require a
+   * node to be absent across two consecutive sweeps before retiring
+   * tracker state) rather than acting on a single snapshot.
+   *
+   * @param options options to customize the request (e.g. timeout)
    * @param handler the handler that receives the result
    *
+   * @exception errc::common::bucket_not_found if the bucket does not exist.
+   * @exception errc::network::configuration_not_available if the bucket
+   *            configuration is absent or its set of KV-serving nodes is
+   *            momentarily empty (e.g. mid-rebalance).
+   * @exception errc::common::unambiguous_timeout if the bucket
+   *            configuration did not arrive within the request timeout.
+   *
    * @since 1.3.2
    * @uncommitted
    */
   void node_ids(const node_ids_options& options, node_ids_handler&& handler) const;
 
   /**
-   * Returns the set of cluster nodes that currently serve key-value
-   * traffic for this collection's bucket, drawn from the client-side
-   * topology snapshot (no network round-trip).
+   * Returns the cluster nodes that currently serve key-value traffic for
+   * this collection's bucket, drawn from the client-side topology snapshot
+   * (no network round-trip).
+   *
+   * See the handler overload for the full contract, including topology-
+   * snapshot semantics and the exception set.
    *
    * @param options options to customize the request
-   * @return future carrying the error (if any) and the set of node_ids
+   * @return future carrying the error (if any) and the vector of
+   *         @c node_id entries in topology order
+   *
+   * @exception errc::common::bucket_not_found if the bucket does not exist.
+   * @exception errc::network::configuration_not_available if the bucket
+   *            configuration is absent or its set of KV-serving nodes is
+   *            momentarily empty (e.g. mid-rebalance).
+   * @exception errc::common::unambiguous_timeout if the bucket
+   *            configuration did not arrive within the request timeout.
    *
    * @since 1.3.2
    * @uncommitted

data/ext/couchbase/couchbase/common_durability_options.hxx

@@ -53,8 +53,8 @@ public:
   /**
    * Allows to customize the enhanced durability requirements for this operation.
    *
-   * @note if a {@link #durability(persist_to, replicate_to)} has been set beforehand it will be set
-   * back to {@link persist_to::none} and
+   * @note if a {@link #durability durability(persist_to, replicate_to)} has been set beforehand it
+   * will be set back to {@link persist_to::none} and
    * {@link replicate_to::none}, since it is not allowed to use both mechanisms at the same
    * time.</p>
    *
@@ -75,13 +75,28 @@ public:
   /**
    * Allows to customize the poll-based durability requirements for this operation.
    *
-   * @note if a {@link #durability(durability_level)} has been set beforehand it will be set back to
+   * @note if a {@link #durability durability(durability_level)} has been set beforehand it will be
+   * set back to
    * {@link durability_level::none}, since it is not allowed to use both mechanisms at the same
    * time.
    *
+   * @note Not served over the @ref couchbase2 "couchbase2" transport, and not refused before the
+   * mutation is applied: observing persistence and replication needs per-node connections that
+   * transport does not open, so the mutation is sent to the gateway and applied and only the
+   * polling that follows fails. The document is already written when the error arrives, and that
+   * error comes from the failed poll rather than being
+   * @ref errc::common::feature_not_available. Level-based durability, set by
+   * @c durability(durability_level), is served normally and is the durability to use over that
+   * transport.
+   *
    * @param persist_to_nodes the durability persistence requirement.
    * @param replicate_to_nodes the durability replication requirement.
    * @return this options builder for chaining purposes.
+   *
+   * @since 1.0.0
+   * @committed
+   * @cng_since{1.4.0}
+   * @cng_uncommitted
    */
   auto durability(persist_to persist_to_nodes, replicate_to replicate_to_nodes) -> derived_class&
   {

data/ext/couchbase/couchbase/conjunction_query.hxx

@@ -32,7 +32,7 @@ namespace couchbase
  *
  * Match documents with `"location"` in the field `reviews.content` and `true` in the field
  * `free_breakfast`.
- * @snippet{trimleft} test_unit_search.cxx search-conjunction
+ * @snippet{trimleft} unit/management/search.cxx search-conjunction
  *
  * @see https://docs.couchbase.com/server/current/fts/fts-supported-queries-conjuncts-disjuncts.html
  * server documentation

data/ext/couchbase/couchbase/create_dataset_analytics_options.hxx

@@ -49,7 +49,12 @@ public:
   /**
    * WHERE clause to use for creating the dataset
    *
-   * @param condition
+   * The value is an arbitrary SQL++ predicate and is embedded in the generated statement verbatim.
+   * Unlike the dataverse, dataset and bucket names, it is not quoted or escaped, because there is
+   * no encoding that would leave a predicate meaningful. Pass only expressions the application
+   * itself controls; interpolating unvalidated input here allows arbitrary SQL++ to be injected.
+   *
+   * @param condition SQL++ predicate expression, e.g. `type = "airline"`
    * @return reference to this object, for use in chaining
    *
    * @since 1.0.0

data/ext/couchbase/couchbase/date_range_query.hxx

@@ -34,10 +34,10 @@ namespace couchbase
  *
  * Match documents where field `review_date` falls within the range ("2001-10-09T10:20:30-08:00",
  * "2016-10-31")
- * @snippet{trimleft} test_unit_search.cxx search-date-range
+ * @snippet{trimleft} unit/management/search.cxx search-date-range
  *
  * It also works with `std::tm` and `std::chrono::system_clock::time_point`.
- * @snippet{trimleft} test_unit_search.cxx search-date-range-tm
+ * @snippet{trimleft} unit/management/search.cxx search-date-range-tm
  *
  * @see https://docs.couchbase.com/server/current/fts/fts-supported-queries-date-range.html server
  * documentation.

data/ext/couchbase/couchbase/decrement_options.hxx

@@ -68,7 +68,7 @@ struct decrement_options : public common_durability_options<decrement_options> {
    * Sets the expiry for the document. By default the document will never expire.
    *
    * The duration must be less than 50 years. For expiry further in the future, use
-   * {@link #expiry(std::chrono::system_clock::time_point)}.
+   * {@link #expiry expiry(std::chrono::system_clock::time_point)}.
    *
    * @param duration the duration after which the document will expire (zero duration means never
    * expire).

data/ext/couchbase/couchbase/disjunction_query.hxx

@@ -35,7 +35,7 @@ namespace couchbase
  * * `"location"` in the field `reviews.content`
  * * `true` in the field `free_breakfast`.
  *
- * @snippet{trimleft} test_unit_search.cxx search-disjunction
+ * @snippet{trimleft} unit/management/search.cxx search-disjunction
  *
  * @see https://docs.couchbase.com/server/current/fts/fts-supported-queries-conjuncts-disjuncts.html
  * server documentation

data/ext/couchbase/couchbase/error.hxx

@@ -32,9 +32,41 @@ class error
 public:
   error() = default;
   error(std::error_code ec, std::string message = {}, error_context ctx = {});
+
+  /**
+   * Constructs an error that wraps another error as its underlying cause.
+   *
+   * @since 1.0.0
+   * @committed
+   */
   error(std::error_code ec, std::string message, error_context ctx, error cause);
+
+  /**
+   * Constructs an error carrying the identity of the cluster node that
+   * returned it. Used by the KV path to attach the @c node_id from the
+   * session that handled the request.
+   *
+   * @since 1.3.2
+   * @uncommitted
+   */
   error(std::error_code ec, std::string message, error_context ctx, couchbase::node_id node_id);
 
+  /**
+   * Constructs an error that both wraps an underlying cause and carries the
+   * identity of the cluster node where the failure originated. Used when a
+   * higher-level path (e.g. transactions) wraps a KV failure — without this
+   * overload the outer error would silently lose @c node_id() attribution
+   * even though the inner @c cause()->node_id() is populated.
+   *
+   * @since 1.3.2
+   * @uncommitted
+   */
+  error(std::error_code ec,
+        std::string message,
+        error_context ctx,
+        error cause,
+        couchbase::node_id node_id);
+
   [[nodiscard]] auto ec() const -> std::error_code;
   [[nodiscard]] auto message() const -> const std::string&;
   [[nodiscard]] auto ctx() const -> const error_context&;

data/ext/couchbase/couchbase/error_codes.hxx

@@ -646,6 +646,38 @@ enum class key_value {
    */
   // KV Code: 0xa7
   range_scan_completed = 134,
+
+  /**
+   * The document was not found on the replica that @ref collection#get_replica() read from. This is
+   * the code @ref error::ec() reports; a caller that wants to treat the general condition uniformly
+   * reads @ref error::cause(), which carries @ref errc::key_value::document_not_found.
+   *
+   * @since 1.5.0
+   * @committed
+   */
+  document_not_found_on_replica = 135,
+
+  /**
+   * The bucket has no replica at the requested index: the index is at or beyond its configured
+   * replica count, or that count is zero. Reported without a network round trip, and retrying
+   * cannot help. Use @ref get_replica_strategy_from_index_options::wrap() to read a different
+   * replica instead.
+   *
+   * @since 1.5.0
+   * @committed
+   */
+  replica_index_out_of_bounds = 136,
+
+  /**
+   * The replica exists for this bucket, but cannot be read now. Either the vbucket map's row for
+   * this document is shorter than the configured replica count, or it does not place that replica
+   * on a node the topology lists. A rebalance resolves both. Use
+   * @ref get_replica_strategy_from_index_options::wrap() to read another replica instead.
+   *
+   * @since 1.5.0
+   * @committed
+   */
+  replica_index_currently_unavailable = 137,
 };
 
 /**

data/ext/couchbase/couchbase/geo_bounding_box_query.hxx

@@ -35,7 +35,7 @@ namespace couchbase
  * identical to the initial, thus explicitly closing the box. However, specifying an explicit
  * closure in this way is optional: the closure will be inferred by the Couchbase Server if not
  * explicitly specified.
- * @snippet{trimleft} test_unit_search.cxx search-geo-bounding-box
+ * @snippet{trimleft} unit/management/search.cxx search-geo-bounding-box
  *
  * @see
  * https://docs.couchbase.com/server/current/fts/fts-supported-queries-geo-bounded-rectangle.html

data/ext/couchbase/couchbase/geo_distance_query.hxx

@@ -32,7 +32,7 @@ namespace couchbase
  * The following query specifies a longitude of `-2.235143` and a latitude of `53.482358`. The
  * target-field `geo` is specified, as is a distance of `100 miles`: this is the radius within which
  * target-locations must reside for their documents to be returned.
- * @snippet{trimleft} test_unit_search.cxx search-geo-distance
+ * @snippet{trimleft} unit/management/search.cxx search-geo-distance
  *
  * @see https://docs.couchbase.com/server/current/fts/fts-supported-queries-geo-point-distance.html
  * server documentation

data/ext/couchbase/couchbase/geo_polygon_query.hxx

@@ -31,7 +31,7 @@ namespace couchbase
  *
  * If a target data-location falls within the box, its document is returned.
  *
- * @snippet{trimleft} test_unit_search.cxx search-geo-polygon
+ * @snippet{trimleft} unit/management/search.cxx search-geo-polygon
  *
  * @see https://docs.couchbase.com/server/current/fts/fts-supported-queries-geo-bounded-polygon.html
  * server documentation