couchbase 3.8.1 → 3.9.0

data/ext/couchbase/couchbase/search_options.hxx

@@ -24,12 +24,15 @@
 #include <couchbase/search_facet.hxx>
 #include <couchbase/search_result.hxx>
 #include <couchbase/search_scan_consistency.hxx>
+#include <couchbase/search_scoring.hxx>
 #include <couchbase/search_sort.hxx>
 
 #include <chrono>
 #include <functional>
 #include <memory>
 #include <optional>
+#include <stdexcept>
+#include <type_traits>
 
 namespace couchbase
 {
@@ -68,6 +71,7 @@ struct search_options : public common_options<search_options> {
     std::map<std::string, std::shared_ptr<search_facet>, std::less<>> facets{};
     std::vector<std::shared_ptr<search_sort>> sort{};
     std::vector<std::string> sort_string{};
+    std::optional<search_scoring::built> scoring{};
   };
 
   /**
@@ -101,6 +105,7 @@ struct search_options : public common_options<search_options> {
       facets_,
       sort_,
       sort_string_,
+      scoring_,
     };
   }
 
@@ -135,10 +140,10 @@ struct search_options : public common_options<search_options> {
    * data it has in the index right away. This is fast, but might not include the most recent
    * mutations.
    *
-   * Note that you cannot use this method and {@link #consistent_with(const mutation_state&)} at the
-   * same time, since they are mutually exclusive. As a rule of thumb, if you only care to be
-   * consistent with the mutation you just wrote on the same thread/app, use
-   * {@link #consistent_with(const mutation_state&)}.
+   * Note that you cannot use this method and {@link #consistent_with consistent_with(const
+   * mutation_state&)} at the same time, since they are mutually exclusive. As a rule of thumb, if
+   * you only care to be consistent with the mutation you just wrote on the same thread/app, use
+   * {@link #consistent_with consistent_with(const mutation_state&)}.
    *
    * @param scan_consistency the index scan consistency to be used for this query
    * @return this options builder for chaining purposes.
@@ -160,9 +165,10 @@ struct search_options : public common_options<search_options> {
    * and if you want your N1QL query to include those you need to pass the mutation tokens into a
    * {@link mutation_state}.
    *
-   * Note that you cannot use this method and {@link #scan_consistency(search_scan_consistency)} at
-   * the same time, since they are mutually exclusive. As a rule of thumb, if you only care to be
-   * consistent with the mutation you just wrote on the same thread/app, use this method.
+   * Note that you cannot use this method and {@link #scan_consistency
+   * scan_consistency(search_scan_consistency)} at the same time, since they are mutually exclusive.
+   * As a rule of thumb, if you only care to be consistent with the mutation you just wrote on the
+   * same thread/app, use this method.
    *
    * @param state the mutation state containing the mutation tokens.
    * @return this options builder for chaining purposes.
@@ -249,15 +255,58 @@ struct search_options : public common_options<search_options> {
    * @param disable
    * @return this options builder for chaining purposes.
    *
+   * @deprecated Use scoring(search_scoring_none{}) instead; see
+   * <couchbase/search_scoring_none.hxx>.
+   *
+   * @throws std::invalid_argument if @ref scoring() has already been set and @p disable is true:
+   * both would write the same field, so they cannot be used together. Turning this back off with
+   * `disable_scoring(false)` after `scoring()` is not a conflict.
+   *
    * @since 1.0.0
-   * @committed
    */
+  [[deprecated("Use search_options::scoring(search_scoring_none{}) instead.")]]
   auto disable_scoring(bool disable) -> search_options&
   {
+    if (disable && scoring_.has_value()) {
+      throw std::invalid_argument("disable_scoring() cannot be used together with scoring()");
+    }
     disable_scoring_ = disable;
     return self();
   }
 
+  /**
+   * Selects how the server scores the hits, and how it merges the FTS and vector result sets of a
+   * hybrid request into a single ranked list.
+   *
+   * @tparam Scoring type of the scoring mode, that derives from @ref search_scoring
+   * @param scoring the scoring mode, see @ref search_scoring
+   * @return this options builder for chaining purposes.
+   *
+   * @note the score fusion strategies require Couchbase Server 8.1 or above. Setting one on an
+   * older cluster fails the operation with @ref errc::common::feature_not_available.
+   *
+   * @note this writes the request's top-level "score" and "params" fields. A @ref raw() call for
+   * either of those names is applied after this option is encoded and silently wins.
+   *
+   * @throws std::invalid_argument if @ref disable_scoring() is currently set to true: both write
+   * the same field, so they cannot be used together, even when they agree (scoring @ref
+   * search_scoring_none with disable_scoring(true)). Calling `disable_scoring(false)` first clears
+   * the conflict.
+   *
+   * @since 1.5.0
+   * @committed
+   */
+  template<typename Scoring,
+           std::enable_if_t<std::is_base_of_v<search_scoring, Scoring>, bool> = true>
+  auto scoring(const Scoring& scoring) -> search_options&
+  {
+    if (disable_scoring_) {
+      throw std::invalid_argument("scoring() cannot be used together with disable_scoring()");
+    }
+    scoring_ = scoring.build();
+    return self();
+  }
+
   /**
    * If set to true, will include the @ref search_row#locations().
    *
@@ -517,6 +566,7 @@ private:
   std::map<std::string, std::shared_ptr<search_facet>, std::less<>> facets_{};
   std::vector<std::shared_ptr<search_sort>> sort_{};
   std::vector<std::string> sort_string_{};
+  std::optional<search_scoring::built> scoring_{};
 };
 
 /**

data/ext/couchbase/couchbase/search_scoring.hxx

@@ -0,0 +1,94 @@
+/* -*- Mode: C++; tab-width: 4; c-basic-offset: 4; indent-tabs-mode: nil -*- */
+/*
+ *   Copyright 2020-Present Couchbase, Inc.
+ *
+ *   Licensed under the Apache License, Version 2.0 (the "License");
+ *   you may not use this file except in compliance with the License.
+ *   You may obtain a copy of the License at
+ *
+ *       http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *   Unless required by applicable law or agreed to in writing, software
+ *   distributed under the License is distributed on an "AS IS" BASIS,
+ *   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *   See the License for the specific language governing permissions and
+ *   limitations under the License.
+ */
+
+#pragma once
+
+#include <cstdint>
+#include <optional>
+#include <variant>
+
+namespace couchbase
+{
+/**
+ * Base class for the scoring mode of a search query.
+ *
+ * Score fusion controls how the FTS and vector result sets of a hybrid request are merged into a
+ * single ranked list. It is only meaningful for a hybrid request (both an FTS query and a vector
+ * search); when applied to a single result set the server re-scores the hits but leaves their
+ * ordering unchanged.
+ *
+ * Each mode is its own type and only exposes its own parameters:
+ *
+ * @li @ref search_scoring_reciprocal_rank_fusion merges by rank.
+ * @li @ref search_scoring_relative_score_fusion merges by normalized score.
+ * @li @ref search_scoring_none disables scoring.
+ *
+ * @see search_options#scoring()
+ *
+ * @since 1.5.0
+ * @committed
+ */
+class search_scoring
+{
+public:
+  /**
+   * Immutable value object representing a scoring mode.
+   *
+   * @since 1.5.0
+   * @internal
+   */
+  struct built {
+    /**
+     * Scoring is disabled.
+     */
+    struct none {
+    };
+
+    /**
+     * Reciprocal Rank Fusion: merges the result sets by rank.
+     */
+    struct reciprocal_rank_fusion {
+      std::optional<std::uint32_t> rank_constant{};
+      std::optional<std::uint32_t> window_size{};
+    };
+
+    /**
+     * Relative Score Fusion: merges the result sets by normalized score.
+     */
+    struct relative_score_fusion {
+      std::optional<std::uint32_t> window_size{};
+    };
+
+    std::variant<none, reciprocal_rank_fusion, relative_score_fusion> mode{ none{} };
+  };
+
+  virtual ~search_scoring() = default;
+
+  /**
+   * Returns the scoring mode as an immutable value.
+   *
+   * @return the scoring mode as an immutable value
+   *
+   * @since 1.5.0
+   * @internal
+   */
+  [[nodiscard]] virtual auto build() const -> built = 0;
+
+protected:
+  search_scoring() = default;
+};
+} // namespace couchbase

data/ext/couchbase/couchbase/search_scoring_none.hxx

@@ -0,0 +1,51 @@
+/* -*- Mode: C++; tab-width: 4; c-basic-offset: 4; indent-tabs-mode: nil -*- */
+/*
+ *   Copyright 2020-Present Couchbase, Inc.
+ *
+ *   Licensed under the Apache License, Version 2.0 (the "License");
+ *   you may not use this file except in compliance with the License.
+ *   You may obtain a copy of the License at
+ *
+ *       http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *   Unless required by applicable law or agreed to in writing, software
+ *   distributed under the License is distributed on an "AS IS" BASIS,
+ *   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *   See the License for the specific language governing permissions and
+ *   limitations under the License.
+ */
+
+#pragma once
+
+#include <couchbase/search_scoring.hxx>
+
+namespace couchbase
+{
+/**
+ * Disables scoring, so that the server does not perform any scoring on the hits.
+ *
+ * This sends the same `"none"` that the deprecated @ref search_options#disable_scoring() sends. It
+ * is not a fusion strategy: `"none"` predates score fusion, so it works on older server versions.
+ *
+ * @since 1.5.0
+ * @committed
+ */
+class search_scoring_none : public search_scoring
+{
+public:
+  search_scoring_none() = default;
+
+  /**
+   * Returns the scoring mode as an immutable value.
+   *
+   * @return the scoring mode as an immutable value
+   *
+   * @since 1.5.0
+   * @internal
+   */
+  [[nodiscard]] auto build() const -> search_scoring::built override
+  {
+    return { search_scoring::built::none{} };
+  }
+};
+} // namespace couchbase

data/ext/couchbase/couchbase/search_scoring_reciprocal_rank_fusion.hxx

@@ -0,0 +1,88 @@
+/* -*- Mode: C++; tab-width: 4; c-basic-offset: 4; indent-tabs-mode: nil -*- */
+/*
+ *   Copyright 2020-Present Couchbase, Inc.
+ *
+ *   Licensed under the Apache License, Version 2.0 (the "License");
+ *   you may not use this file except in compliance with the License.
+ *   You may obtain a copy of the License at
+ *
+ *       http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *   Unless required by applicable law or agreed to in writing, software
+ *   distributed under the License is distributed on an "AS IS" BASIS,
+ *   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *   See the License for the specific language governing permissions and
+ *   limitations under the License.
+ */
+
+#pragma once
+
+#include <couchbase/search_scoring.hxx>
+
+namespace couchbase
+{
+/**
+ * Merges the FTS and vector result sets by rank rather than by raw score.
+ *
+ * It works well with the server defaults, and is the recommended strategy.
+ *
+ * @note available from Couchbase Server 8.1. Setting it makes the SDK check for the score fusion
+ * cluster capability, and fail the operation with @ref errc::common::feature_not_available if the
+ * cluster does not advertise it.
+ *
+ * @since 1.5.0
+ * @uncommitted
+ */
+class search_scoring_reciprocal_rank_fusion : public search_scoring
+{
+public:
+  search_scoring_reciprocal_rank_fusion() = default;
+
+  /**
+   * The rank constant of the Reciprocal Rank Fusion formula.
+   *
+   * @param rank_constant the rank constant
+   * @return this scoring mode for chaining purposes.
+   *
+   * @since 1.5.0
+   * @uncommitted
+   */
+  auto rank_constant(std::uint32_t rank_constant) -> search_scoring_reciprocal_rank_fusion&
+  {
+    rank_constant_ = rank_constant;
+    return *this;
+  }
+
+  /**
+   * How many results per list are considered for fusion.
+   *
+   * @param window_size the window size
+   * @return this scoring mode for chaining purposes.
+   *
+   * @since 1.5.0
+   * @uncommitted
+   */
+  auto window_size(std::uint32_t window_size) -> search_scoring_reciprocal_rank_fusion&
+  {
+    window_size_ = window_size;
+    return *this;
+  }
+
+  /**
+   * Returns the scoring mode as an immutable value.
+   *
+   * @return the scoring mode as an immutable value
+   *
+   * @since 1.5.0
+   * @internal
+   */
+  [[nodiscard]] auto build() const -> search_scoring::built override
+  {
+    return { search_scoring::built::reciprocal_rank_fusion{ rank_constant_, window_size_ } };
+  }
+
+private:
+  std::optional<std::uint32_t> rank_constant_{};
+  std::optional<std::uint32_t> window_size_{};
+};
+} // namespace couchbase

data/ext/couchbase/couchbase/search_scoring_relative_score_fusion.hxx

@@ -0,0 +1,70 @@
+/* -*- Mode: C++; tab-width: 4; c-basic-offset: 4; indent-tabs-mode: nil -*- */
+/*
+ *   Copyright 2020-Present Couchbase, Inc.
+ *
+ *   Licensed under the Apache License, Version 2.0 (the "License");
+ *   you may not use this file except in compliance with the License.
+ *   You may obtain a copy of the License at
+ *
+ *       http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *   Unless required by applicable law or agreed to in writing, software
+ *   distributed under the License is distributed on an "AS IS" BASIS,
+ *   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *   See the License for the specific language governing permissions and
+ *   limitations under the License.
+ */
+
+#pragma once
+
+#include <couchbase/search_scoring.hxx>
+
+namespace couchbase
+{
+/**
+ * Merges the FTS and vector result sets by normalized score rather than by rank.
+ *
+ * @note available from Couchbase Server 8.1. Setting it makes the SDK check for the score fusion
+ * cluster capability, and fail the operation with @ref errc::common::feature_not_available if the
+ * cluster does not advertise it.
+ *
+ * @since 1.5.0
+ * @uncommitted
+ */
+class search_scoring_relative_score_fusion : public search_scoring
+{
+public:
+  search_scoring_relative_score_fusion() = default;
+
+  /**
+   * How many results per list are considered for fusion.
+   *
+   * @param window_size the window size
+   * @return this scoring mode for chaining purposes.
+   *
+   * @since 1.5.0
+   * @uncommitted
+   */
+  auto window_size(std::uint32_t window_size) -> search_scoring_relative_score_fusion&
+  {
+    window_size_ = window_size;
+    return *this;
+  }
+
+  /**
+   * Returns the scoring mode as an immutable value.
+   *
+   * @return the scoring mode as an immutable value
+   *
+   * @since 1.5.0
+   * @internal
+   */
+  [[nodiscard]] auto build() const -> search_scoring::built override
+  {
+    return { search_scoring::built::relative_score_fusion{ window_size_ } };
+  }
+
+private:
+  std::optional<std::uint32_t> window_size_{};
+};
+} // namespace couchbase

data/ext/couchbase/couchbase/term_range_query.hxx

@@ -30,7 +30,7 @@ namespace couchbase
  * specified range. Either min or max can be omitted, but not both.
  *
  * Match documents where field `desc` contains terms in the range `("foo", "foof")`:
- * @snippet{trimleft} test_unit_search.cxx search-term-range
+ * @snippet{trimleft} unit/management/search.cxx search-term-range
  *
  * @see https://docs.couchbase.com/server/current/fts/fts-supported-queries-term-range.html server
  * documentation.

data/ext/couchbase/couchbase/tracing/request_span.hxx

@@ -61,6 +61,52 @@ public:
     return true;
   }
 
+  /**
+   * Efficiently record the dispatch operation identifier (the request opaque) without formatting it
+   * to a string on the hot path.
+   *
+   * The default implementation returns false, which tells the SDK to record the identifier as a
+   * regular string tag via add_tag() instead — so external tracer implementations are unaffected.
+   * Built-in spans may override this to capture the raw value and defer the (rarely needed)
+   * formatting until the span is actually reported.
+   *
+   * @return true if the span captured the identifier; false to request the string-tag fallback.
+   */
+  [[nodiscard]] virtual auto try_set_dispatch_operation_id(std::uint32_t /* opaque */) -> bool
+  {
+    return false;
+  }
+
+  /**
+   * Efficiently record the local connection identifier of a dispatch span without materializing a
+   * tag-name string on the hot path.
+   *
+   * Like try_set_dispatch_operation_id(), the default returns false so the SDK records the value as
+   * a regular string tag and external tracer implementations are unaffected.
+   *
+   * @return true if the span captured the identifier; false to request the string-tag fallback.
+   */
+  [[nodiscard]] virtual auto try_set_dispatch_local_id(const std::string& /* local_id */) -> bool
+  {
+    return false;
+  }
+
+  /**
+   * Efficiently record the result metadata of a dispatch span (server processing time and the peer
+   * socket) in a single call, without materializing tag-name strings on the hot path.
+   *
+   * The default returns false so the SDK records the values as regular string tags and external
+   * tracer implementations are unaffected.
+   *
+   * @return true if the span captured the metadata; false to request the string-tag fallback.
+   */
+  [[nodiscard]] virtual auto try_set_dispatch_result(std::uint64_t /* server_duration_us */,
+                                                     const std::string& /* peer_address */,
+                                                     std::uint16_t /* peer_port */) -> bool
+  {
+    return false;
+  }
+
 private:
   std::string name_{};
   std::shared_ptr<request_span> parent_{ nullptr };

data/ext/couchbase/couchbase/transactions/transaction_get_multi_replicas_from_preferred_server_group_result.hxx

@@ -15,12 +15,12 @@
  */
 #pragma once
 
-#include "couchbase/error_codes.hxx"
-#include <couchbase/codec/default_json_transcoder.hxx>
+#include <couchbase/codec/lenient_json_transcoder.hxx>
 
+#include <cstddef>
 #include <optional>
 #include <stdexcept>
-#include <system_error>
+#include <string>
 #include <vector>
 
 namespace couchbase
@@ -48,40 +48,40 @@ public:
   /**
    * Content of the document.
    *
+   * When no transcoder is given, the document is decoded leniently, without validating its
+   * common flags. Pass a transcoder explicitly to enforce its flag handling instead.
+   *
+   * @return content of the document.
+   */
+  template<typename Document, std::enable_if_t<!codec::is_transcoder_v<Document>, bool> = true>
+  [[nodiscard]] auto content_as(std::size_t spec_index) const -> Document
+  {
+    return codec::default_lenient_json_transcoder::decode<Document>(content_at(spec_index));
+  }
+
+  /**
+   * Content of the document, decoded with the given transcoder.
+   *
    * @return content of the document.
    */
   template<typename Document,
-           typename Transcoder = codec::default_json_transcoder,
+           typename Transcoder,
            std::enable_if_t<!codec::is_transcoder_v<Document>, bool> = true,
            std::enable_if_t<codec::is_transcoder_v<Transcoder>, bool> = true>
   [[nodiscard]] auto content_as(std::size_t spec_index) const -> Document
   {
-    if (spec_index >= content_.size()) {
-      throw std::invalid_argument("spec index " + std::to_string(spec_index) + " is not valid");
-    }
-    if (const auto& content = content_[spec_index]; content.has_value()) {
-      return Transcoder::template decode<Document>(content.value());
-    }
-    throw std::system_error(errc::key_value::document_not_found,
-                            "document was not found for index " + std::to_string(spec_index));
+    return Transcoder::template decode<Document>(content_at(spec_index));
   }
 
   /**
-   * Content of the document.
+   * Content of the document, decoded with the given transcoder.
    *
    * @return content of the document.
    */
   template<typename Transcoder, std::enable_if_t<codec::is_transcoder_v<Transcoder>, bool> = true>
   [[nodiscard]] auto content_as(std::size_t spec_index) const -> typename Transcoder::document_type
   {
-    if (spec_index >= content_.size()) {
-      throw std::invalid_argument("spec index " + std::to_string(spec_index) + " is not valid");
-    }
-    if (const auto& content = content_[spec_index]; content.has_value()) {
-      return Transcoder::decode(content.value());
-    }
-    throw std::system_error(errc::key_value::document_not_found,
-                            "document was not found for index " + std::to_string(spec_index));
+    return Transcoder::decode(content_at(spec_index));
   }
 
   /**
@@ -106,6 +106,8 @@ private:
   {
   }
 
+  [[nodiscard]] auto content_at(std::size_t spec_index) const -> const codec::encoded_value&;
+
   std::vector<std::optional<codec::encoded_value>> content_;
 };
 } // namespace transactions

data/ext/couchbase/couchbase/transactions/transaction_get_multi_result.hxx

@@ -15,9 +15,12 @@
  */
 #pragma once
 
-#include <couchbase/codec/default_json_transcoder.hxx>
+#include <couchbase/codec/lenient_json_transcoder.hxx>
 
+#include <cstddef>
 #include <optional>
+#include <stdexcept>
+#include <string>
 #include <vector>
 
 namespace couchbase
@@ -42,40 +45,40 @@ public:
   /**
    * Content of the document.
    *
+   * When no transcoder is given, the document is decoded leniently, without validating its
+   * common flags. Pass a transcoder explicitly to enforce its flag handling instead.
+   *
+   * @return content of the document.
+   */
+  template<typename Document, std::enable_if_t<!codec::is_transcoder_v<Document>, bool> = true>
+  [[nodiscard]] auto content_as(std::size_t spec_index) const -> Document
+  {
+    return codec::default_lenient_json_transcoder::decode<Document>(content_at(spec_index));
+  }
+
+  /**
+   * Content of the document, decoded with the given transcoder.
+   *
    * @return content of the document.
    */
   template<typename Document,
-           typename Transcoder = codec::default_json_transcoder,
+           typename Transcoder,
            std::enable_if_t<!codec::is_transcoder_v<Document>, bool> = true,
            std::enable_if_t<codec::is_transcoder_v<Transcoder>, bool> = true>
   [[nodiscard]] auto content_as(std::size_t spec_index) const -> Document
   {
-    if (spec_index >= content_.size()) {
-      throw std::invalid_argument("spec index " + std::to_string(spec_index) + " is not valid");
-    }
-    if (const auto& content = content_[spec_index]; content.has_value()) {
-      return Transcoder::template decode<Document>(content.value());
-    }
-    throw std::system_error(errc::key_value::document_not_found,
-                            "document was not found for index " + std::to_string(spec_index));
+    return Transcoder::template decode<Document>(content_at(spec_index));
   }
 
   /**
-   * Content of the document.
+   * Content of the document, decoded with the given transcoder.
    *
    * @return content of the document.
    */
   template<typename Transcoder, std::enable_if_t<codec::is_transcoder_v<Transcoder>, bool> = true>
   [[nodiscard]] auto content_as(std::size_t spec_index) const -> typename Transcoder::document_type
   {
-    if (spec_index >= content_.size()) {
-      throw std::invalid_argument("spec index " + std::to_string(spec_index) + " is not valid");
-    }
-    if (const auto& content = content_[spec_index]; content.has_value()) {
-      return Transcoder::decode(content_[spec_index]);
-    }
-    throw std::system_error(errc::key_value::document_not_found,
-                            "document was not found for index " + std::to_string(spec_index));
+    return Transcoder::decode(content_at(spec_index));
   }
 
   /**
@@ -99,6 +102,8 @@ private:
   {
   }
 
+  [[nodiscard]] auto content_at(std::size_t spec_index) const -> const codec::encoded_value&;
+
   std::vector<std::optional<codec::encoded_value>> content_;
 };
 } // namespace transactions