couchbase 3.4.2 → 3.4.4

data/ext/couchbase/couchbase/numeric_range_facet_result.hxx

@@ -0,0 +1,55 @@
+/* -*- 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_facet_result.hxx>
+#include <couchbase/search_numeric_range.hxx>
+
+#include <string>
+#include <vector>
+
+namespace couchbase
+{
+#ifndef COUCHBASE_CXX_CLIENT_DOXYGEN
+class internal_numeric_range_facet_result;
+#endif
+
+/**
+ * @since 1.0.0
+ * @committed
+ */
+class numeric_range_facet_result : public search_facet_result
+{
+  public:
+    /**
+     * @since 1.0.0
+     * @internal
+     */
+    explicit numeric_range_facet_result(internal_numeric_range_facet_result internal);
+
+    [[nodiscard]] auto name() const -> const std::string& override;
+    [[nodiscard]] auto field() const -> const std::string& override;
+    [[nodiscard]] auto total() const -> std::uint64_t override;
+    [[nodiscard]] auto missing() const -> std::uint64_t override;
+    [[nodiscard]] auto other() const -> std::uint64_t override;
+    [[nodiscard]] auto numeric_ranges() const -> const std::vector<search_numeric_range>&;
+
+  private:
+    std::unique_ptr<internal_numeric_range_facet_result> internal_;
+};
+} // namespace couchbase

data/ext/couchbase/couchbase/numeric_range_query.hxx

@@ -0,0 +1,143 @@
+/* -*- Mode: C++; tab-width: 4; c-basic-offset: 4; indent-tabs-mode: nil -*- */
+/*
+ *   Copyright 2023-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/match_operator.hxx>
+#include <couchbase/search_query.hxx>
+
+#include <cstdint>
+#include <optional>
+#include <string>
+
+namespace couchbase
+{
+/**
+ * The numeric range query finds documents containing a numeric value in the specified field within the specified range. Either min or max
+ * can be omitted, but not both.
+ *
+ * By default, min is inclusive and max is exclusive.
+ *
+ * Match documents where field `id` contains numbers in the range `(100, 1000)`:
+ * @snippet test_unit_search.cxx search-numeric-range
+ *
+ * @since 1.0.0
+ * @committed
+ */
+class numeric_range_query : public search_query
+{
+  public:
+    /**
+     * Set lower limit of the range. Whether to include limit into the range will be decided by server defaults (inclusive).
+     *
+     * @param value  lower limit of the range.
+     *
+     * @return this query for chaining purposes.
+     *
+     * @since 1.0.0
+     * @committed
+     */
+    auto min(double value) -> numeric_range_query&
+    {
+        min_ = value;
+        return *this;
+    }
+
+    /**
+     * Set lower limit and specify whether to include it into the limit.
+     *
+     * @param value  lower limit of the range.
+     * @param inclusive whether to include limit value into the interval.
+     *
+     * @return this query for chaining purposes.
+     *
+     * @since 1.0.0
+     * @committed
+     */
+    auto min(double value, bool inclusive) -> numeric_range_query&
+    {
+        min_ = value;
+        inclusive_min_ = inclusive;
+        return *this;
+    }
+
+    /**
+     * Set upper limit of the range. Whether to include limit into the range will be decided by server defaults (exclusive).
+     *
+     * @param value  upper limit of the range
+     *
+     * @return this query for chaining purposes.
+     *
+     * @since 1.0.0
+     * @committed
+     */
+    auto max(double value) -> numeric_range_query&
+    {
+        max_ = value;
+        return *this;
+    }
+
+    /**
+     * Set upper limit and specify whether to include it into the limit.
+     *
+     * @param value  upper limit of the range.
+     * @param inclusive whether to include limit value into the interval.
+     *
+     * @return this query for chaining purposes.
+     *
+     * @since 1.0.0
+     * @committed
+     */
+    auto max(double value, bool inclusive) -> numeric_range_query&
+    {
+        max_ = value;
+        inclusive_max_ = inclusive;
+        return *this;
+    }
+
+    /**
+     * If a field is specified, only terms in that field will be matched.
+     *
+     * @param field_name name of the field to be matched
+     *
+     * @return this query for chaining purposes.
+     *
+     * @since 1.0.0
+     * @committed
+     */
+    auto field(std::string field_name) -> numeric_range_query&
+    {
+        field_ = std::move(field_name);
+        return *this;
+    }
+
+    /**
+     * @return encoded representation of the query.
+     *
+     * @since 1.0.0
+     * @internal
+     */
+    [[nodiscard]] auto encode() const -> encoded_search_query override;
+
+  private:
+    std::optional<double> min_{};
+    std::optional<double> max_{};
+    std::optional<bool> inclusive_min_{};
+    std::optional<bool> inclusive_max_{};
+    std::optional<std::string> field_{};
+};
+} // namespace couchbase

data/ext/couchbase/couchbase/phrase_query.hxx

@@ -0,0 +1,93 @@
+/* -*- Mode: C++; tab-width: 4; c-basic-offset: 4; indent-tabs-mode: nil -*- */
+/*
+ *   Copyright 2023-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_query.hxx>
+
+#include <optional>
+#include <stdexcept>
+#include <string>
+#include <vector>
+
+namespace couchbase
+{
+/**
+ * A query that looks for **exact** match of several terms (in the exact order) in the index. The provided terms must exist in the correct
+ * order, at the correct index offsets, in the specified field (as no analyzer are applied to the terms). Queried field must have been
+ * indexed with `includeTermVectors` set to `true`. It is generally more useful in debugging scenarios, and the @ref match_phrase_query
+ * should usually be preferred for real-world use cases.
+ *
+ * Match documents with terms `"nice"` and `"view"` in field `reviews.content`:
+ * @snippet test_unit_search.cxx search-phrase
+ *
+ * @see https://docs.couchbase.com/server/current/fts/fts-supported-queries-phrase.html server documentation
+ *
+ * @since 1.0.0
+ * @committed
+ */
+class phrase_query : public search_query
+{
+  public:
+    /**
+     * Create a new phrase query.
+     *
+     * The mandatory list of terms that must exactly match in the index. Note that the index can (and usually will) contain terms that are
+     * derived from the text in documents, as analyzers can apply process like stemming.
+     *
+     * @param terms non-empty vector of terms.
+     *
+     * @since 1.0.0
+     * @committed
+     */
+    explicit phrase_query(std::initializer_list<std::string> terms)
+      : terms_{ terms }
+    {
+        if (terms_.empty()) {
+            throw std::invalid_argument("terms must not be empty in phrase_query");
+        }
+    }
+
+    /**
+     * If a field is specified, only terms in that field will be matched.
+     *
+     * @param field_name name of the field to be matched
+     *
+     * @return this query for chaining purposes.
+     *
+     * @since 1.0.0
+     * @committed
+     */
+    auto field(std::string field_name) -> phrase_query&
+    {
+        field_ = std::move(field_name);
+        return *this;
+    }
+
+    /**
+     * @return encoded representation of the query.
+     *
+     * @since 1.0.0
+     * @internal
+     */
+    [[nodiscard]] auto encode() const -> encoded_search_query override;
+
+  private:
+    std::vector<std::string> terms_;
+    std::optional<std::string> field_{};
+};
+} // namespace couchbase

data/ext/couchbase/couchbase/prefix_query.hxx

@@ -0,0 +1,82 @@
+/* -*- Mode: C++; tab-width: 4; c-basic-offset: 4; indent-tabs-mode: nil -*- */
+/*
+ *   Copyright 2023-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_query.hxx>
+
+#include <optional>
+#include <string>
+
+namespace couchbase
+{
+/**
+ * The prefix query finds documents containing terms that start with the provided prefix. Usual better alternative is @ref match_query.
+ *
+ * Match documents where field `reviews.content` contains words starting with `"inter"`:
+ * @snippet test_unit_search.cxx search-prefix
+ *
+ * @see https://docs.couchbase.com/server/current/fts/fts-supported-queries-prefix-query.html server documentation
+ *
+ * @since 1.0.0
+ * @committed
+ */
+class prefix_query : public search_query
+{
+  public:
+    /**
+     * Create a new prefix query.
+     *
+     * @param prefix prefix to match
+     *
+     * @since 1.0.0
+     * @committed
+     */
+    explicit prefix_query(std::string prefix)
+      : prefix_{ std::move(prefix) }
+    {
+    }
+
+    /**
+     * If a field is specified, only terms in that field will be matched.
+     *
+     * @param field_name name of the field to be matched
+     *
+     * @return this query for chaining purposes.
+     *
+     * @since 1.0.0
+     * @committed
+     */
+    auto field(std::string field_name) -> prefix_query&
+    {
+        field_ = std::move(field_name);
+        return *this;
+    }
+
+    /**
+     * @return encoded representation of the query.
+     *
+     * @since 1.0.0
+     * @internal
+     */
+    [[nodiscard]] auto encode() const -> encoded_search_query override;
+
+  private:
+    std::string prefix_;
+    std::optional<std::string> field_{};
+};
+} // namespace couchbase

data/ext/couchbase/couchbase/query_error_context.hxx

@@ -57,7 +57,7 @@ class query_error_context : public error_context
                         std::string http_body,
                         std::string hostname,
                         std::uint16_t port)
-      : error_context{ ec, std::move(last_dispatched_to), std::move(last_dispatched_from), retry_attempts, std::move(retry_reasons) }
+      : error_context{ {}, ec, std::move(last_dispatched_to), std::move(last_dispatched_from), retry_attempts, std::move(retry_reasons) }
       , first_error_code_{ first_error_code }
       , first_error_message_{ std::move(first_error_message) }
       , client_context_id_{ std::move(client_context_id) }
@@ -127,6 +127,8 @@ class query_error_context : public error_context
         return port_;
     }
 
+    [[nodiscard]] auto to_json() const -> std::string;
+
   private:
     std::uint64_t first_error_code_{};
     std::string first_error_message_{};

data/ext/couchbase/couchbase/query_index_manager.hxx

@@ -61,19 +61,11 @@ class query_index_manager
      */
     void get_all_indexes(std::string bucket_name,
                          const get_all_query_indexes_options& options,
-                         get_all_query_indexes_handler&& handler) const
-    {
-        return core::impl::initiate_get_all_query_indexes(
-          core_, std::move(bucket_name), options.build(), std::forward<get_all_query_indexes_handler>(handler));
-    }
+                         get_all_query_indexes_handler&& handler) const;
+
     [[nodiscard]] auto get_all_indexes(std::string bucket_name, const get_all_query_indexes_options& options) const
-      -> std::future<std::pair<manager_error_context, std::vector<couchbase::management::query::index>>>
-    {
-        auto barrier = std::make_shared<std::promise<std::pair<manager_error_context, std::vector<couchbase::management::query::index>>>>();
-        auto future = barrier->get_future();
-        get_all_indexes(std::move(bucket_name), options, [barrier](auto ctx, auto resp) { barrier->set_value({ ctx, resp }); });
-        return future;
-    }
+      -> std::future<std::pair<manager_error_context, std::vector<couchbase::management::query::index>>>;
+
     /**
      * Create an index on a bucket.
      *
@@ -90,23 +82,12 @@ class query_index_manager
                       std::string index_name,
                       std::vector<std::string> fields,
                       const create_query_index_options& options,
-                      create_query_index_handler&& handler) const
-    {
-        core::impl::initiate_create_query_index(
-          core_, std::move(bucket_name), std::move(index_name), std::move(fields), options.build(), std::move(handler));
-    }
+                      create_query_index_handler&& handler) const;
 
     [[nodiscard]] auto create_index(std::string bucket_name,
                                     std::string index_name,
                                     std::vector<std::string> fields,
-                                    const create_query_index_options& options) const -> std::future<manager_error_context>
-    {
-        auto barrier = std::make_shared<std::promise<manager_error_context>>();
-        auto future = barrier->get_future();
-        create_index(
-          std::move(bucket_name), std::move(index_name), std::move(fields), options, [barrier](auto ctx) { barrier->set_value(ctx); });
-        return future;
-    }
+                                    const create_query_index_options& options) const -> std::future<manager_error_context>;
 
     /**
      * Create a primary index on a bucket.
@@ -120,19 +101,10 @@ class query_index_manager
      */
     void create_primary_index(std::string bucket_name,
                               const create_primary_query_index_options& options,
-                              create_query_index_handler&& handler)
-    {
-        return core::impl::initiate_create_primary_query_index(core_, std::move(bucket_name), options.build(), std::move(handler));
-    }
+                              create_query_index_handler&& handler);
 
     [[nodiscard]] auto create_primary_index(std::string bucket_name, const create_primary_query_index_options& options)
-      -> std::future<manager_error_context>
-    {
-        auto barrier = std::make_shared<std::promise<manager_error_context>>();
-        auto future = barrier->get_future();
-        create_primary_index(std::move(bucket_name), options, [barrier](auto ctx) { barrier->set_value(ctx); });
-        return future;
-    }
+      -> std::future<manager_error_context>;
     /**
      * Drop primary index on a bucket.
      *
@@ -143,19 +115,10 @@ class query_index_manager
      * @since 1.0.0
      * @committed
      */
-    void drop_primary_index(std::string bucket_name, const drop_primary_query_index_options& options, drop_query_index_handler&& handler)
-    {
-        return core::impl::initiate_drop_primary_query_index(core_, std::move(bucket_name), options.build(), std::move(handler));
-    }
+    void drop_primary_index(std::string bucket_name, const drop_primary_query_index_options& options, drop_query_index_handler&& handler);
 
     [[nodiscard]] auto drop_primary_index(std::string bucket_name, const drop_primary_query_index_options& options)
-      -> std::future<manager_error_context>
-    {
-        auto barrier = std::make_shared<std::promise<manager_error_context>>();
-        auto future = barrier->get_future();
-        drop_primary_index(std::move(bucket_name), options, [barrier](auto ctx) { barrier->set_value(ctx); });
-        return future;
-    }
+      -> std::future<manager_error_context>;
 
     /**
      *
@@ -170,20 +133,10 @@ class query_index_manager
     void drop_index(std::string bucket_name,
                     std::string index_name,
                     const drop_query_index_options& options,
-                    drop_query_index_handler&& handler)
-    {
-        return core::impl::initiate_drop_query_index(
-          core_, std::move(bucket_name), std::move(index_name), options.build(), std::move(handler));
-    }
+                    drop_query_index_handler&& handler);
 
     [[nodiscard]] auto drop_index(std::string bucket_name, std::string index_name, const drop_query_index_options& options)
-      -> std::future<manager_error_context>
-    {
-        auto barrier = std::make_shared<std::promise<manager_error_context>>();
-        auto future = barrier->get_future();
-        drop_index(std::move(bucket_name), std::move(index_name), options, [barrier](auto ctx) { barrier->set_value(ctx); });
-        return future;
-    }
+      -> std::future<manager_error_context>;
     /**
      * Builds all currently deferred indexes.
      *
@@ -198,20 +151,10 @@ class query_index_manager
      */
     void build_deferred_indexes(std::string bucket_name,
                                 const build_query_index_options& options,
-                                build_deferred_query_indexes_handler&& handler) const
-    {
-        return core::impl::initiate_build_deferred_indexes(
-          core_, std::move(bucket_name), options.build(), std::forward<build_deferred_query_indexes_handler>(handler));
-    }
+                                build_deferred_query_indexes_handler&& handler) const;
 
     [[nodiscard]] auto build_deferred_indexes(std::string bucket_name, const build_query_index_options& options) const
-      -> std::future<manager_error_context>
-    {
-        auto barrier = std::make_shared<std::promise<manager_error_context>>();
-        auto future = barrier->get_future();
-        build_deferred_indexes(std::move(bucket_name), options, [barrier](auto ctx) { barrier->set_value(std::move(ctx)); });
-        return future;
-    }
+      -> std::future<manager_error_context>;
 
     /**
      * Polls the state of a set of indexes, until they all are online.
@@ -227,21 +170,11 @@ class query_index_manager
     void watch_indexes(std::string bucket_name,
                        std::vector<std::string> index_names,
                        const watch_query_indexes_options& options,
-                       watch_query_indexes_handler&& handler)
-    {
-        return core::impl::initiate_watch_query_indexes(
-          core_, std::move(bucket_name), std::move(index_names), options.build(), std::move(handler));
-    }
+                       watch_query_indexes_handler&& handler);
 
     [[nodiscard]] auto watch_indexes(std::string bucket_name,
                                      std::vector<std::string> index_names,
-                                     const watch_query_indexes_options& options)
-    {
-        auto barrier = std::make_shared<std::promise<manager_error_context>>();
-        auto future = barrier->get_future();
-        watch_indexes(std::move(bucket_name), std::move(index_names), options, [barrier](auto ctx) { barrier->set_value(ctx); });
-        return future;
-    }
+                                     const watch_query_indexes_options& options) -> std::future<manager_error_context>;
 
   private:
     friend class cluster;

data/ext/couchbase/couchbase/query_options.hxx

@@ -51,6 +51,7 @@ struct query_options : public common_options<query_options> {
         const bool readonly;
         const bool flex_index;
         const bool preserve_expiry;
+        std::optional<bool> use_replica;
         std::optional<std::uint64_t> max_parallelism;
         std::optional<std::uint64_t> scan_cap;
         std::optional<std::chrono::milliseconds> scan_wait;
@@ -84,6 +85,7 @@ struct query_options : public common_options<query_options> {
             readonly_,
             flex_index_,
             preserve_expiry_,
+            use_replica_,
             max_parallelism_,
             scan_cap_,
             scan_wait_,
@@ -225,6 +227,21 @@ struct query_options : public common_options<query_options> {
         return self();
     }
 
+    /**
+     * Specifies that the query engine should use replica nodes for KV fetches if the active node is down.
+     *
+     * @param use_replica whether replica nodes should be used if the active node is down. If not provided, the server default will be used.
+     * @return the options builder for chaining purposes.
+     *
+     * @since 1.0.0
+     * @committed
+     */
+    auto use_replica(bool use_replica) -> query_options&
+    {
+        use_replica_ = use_replica;
+        return self();
+    }
+
     /**
      * Allows overriding the default maximum parallelism for the query execution on the server side.
      *
@@ -529,6 +546,7 @@ struct query_options : public common_options<query_options> {
     bool readonly_{ false };
     bool flex_index_{ false };
     bool preserve_expiry_{ false };
+    std::optional<bool> use_replica_{};
     std::optional<std::uint64_t> max_parallelism_{};
     std::optional<std::uint64_t> scan_cap_{};
     std::optional<std::uint64_t> pipeline_batch_{};

data/ext/couchbase/couchbase/query_string_query.hxx

@@ -0,0 +1,72 @@
+/* -*- Mode: C++; tab-width: 4; c-basic-offset: 4; indent-tabs-mode: nil -*- */
+/*
+ *   Copyright 2023-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_query.hxx>
+
+#include <string>
+
+namespace couchbase
+{
+/**
+ * The query string query allows humans to describe complex queries using a simple syntax.
+ *
+ * 1. When you specify multiple query-clauses, you can specify the relative importance to a given clause by suffixing it with the `^`
+ * operator, followed by a number or by specifying the boost parameter with the number to boost the search. For example perform
+ * @ref match_query for pool in both the name and description fields, but documents having the term in the name field score higher.
+ * @snippet test_unit_search.cxx search-query-string-boosting
+ *
+ * 2. You can perform date or numeric range searches by using the `>`, `>=`, `<`, and `<=` operators, followed by a date value in quotes.
+ * For example, perform a @ref date_range_query on the created field for values after September 21, 2016.
+ * @snippet test_unit_search.cxx search-query-string-date-range
+ * Or, perform a @ref numeric_range_query  on the `reviews.ratings.Cleanliness` field, for values greater than 4.
+ * @snippet test_unit_search.cxx search-query-string-numeric-range
+ *
+ * @see https://docs.couchbase.com/server/current/fts/fts-query-string-syntax.html definition of query syntax
+ *
+ * @since 1.0.0
+ * @committed
+ */
+class query_string_query : public search_query
+{
+  public:
+    /**
+     * Create a new query string query.
+     *
+     * @param query the query string to be analyzed and used against
+     *
+     * @since 1.0.0
+     * @committed
+     */
+    explicit query_string_query(std::string query)
+      : query_{ std::move(query) }
+    {
+    }
+
+    /**
+     * @return encoded representation of the query.
+     *
+     * @since 1.0.0
+     * @internal
+     */
+    [[nodiscard]] auto encode() const -> encoded_search_query override;
+
+  private:
+    std::string query_;
+};
+} // namespace couchbase