couchbase 3.4.1 → 3.4.3

data/ext/couchbase/couchbase/analytics_result.hxx

@@ -0,0 +1,102 @@
+/* -*- 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/analytics_meta_data.hxx>
+#include <couchbase/codec/tao_json_serializer.hxx>
+
+#include <chrono>
+#include <cinttypes>
+#include <optional>
+#include <vector>
+
+namespace couchbase
+{
+
+/**
+ * Represents result of @ref cluster#analytics_query() and @ref scope#analytics_query() calls.
+ *
+ * @since 1.0.0
+ * @committed
+ */
+class analytics_result
+{
+  public:
+    /**
+     * @since 1.0.0
+     * @internal
+     */
+    analytics_result() = default;
+
+    /**
+     * @since 1.0.0
+     * @volatile
+     */
+    analytics_result(analytics_meta_data meta_data, std::vector<codec::binary> rows)
+      : meta_data_{ std::move(meta_data) }
+      , rows_{ std::move(rows) }
+    {
+    }
+
+    /**
+     * Returns the {@link analytics_meta_data} giving access to the additional metadata associated with this analytics query.
+     *
+     * @return response metadata
+     *
+     * @since 1.0.0
+     * @committed
+     */
+    [[nodiscard]] auto meta_data() const -> const analytics_meta_data&
+    {
+        return meta_data_;
+    }
+
+    /**
+     * @return list of analytics results as binary strings
+     *
+     * @since 1.0.0
+     * @internal
+     */
+    [[nodiscard]] auto rows_as_binary() const -> const std::vector<codec::binary>&
+    {
+        return rows_;
+    }
+
+    template<typename Serializer,
+             typename Document = typename Serializer::document_type,
+             std::enable_if_t<codec::is_serializer_v<Serializer>, bool> = true>
+    [[nodiscard]] auto rows_as() const -> std::vector<Document>
+    {
+        std::vector<Document> rows;
+        rows.reserve(rows_.size());
+        for (const auto& row : rows_) {
+            rows.emplace_back(Serializer::template deserialize<Document>(row));
+        }
+        return rows;
+    }
+
+    [[nodiscard]] auto rows_as_json() const -> std::vector<codec::tao_json_serializer::document_type>
+    {
+        return rows_as<codec::tao_json_serializer>();
+    }
+
+  private:
+    analytics_meta_data meta_data_{};
+    std::vector<codec::binary> rows_{};
+};
+} // namespace couchbase

data/ext/couchbase/couchbase/analytics_scan_consistency.hxx

@@ -0,0 +1,46 @@
+/* -*- 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
+
+namespace couchbase
+{
+enum class analytics_scan_consistency {
+    /**
+     * The indexer will return whatever state it has to the query engine at the time of query.
+     *
+     * This is the default (for single-statement requests). No timestamp vector is used in the index scan. This is also the fastest mode,
+     * because we avoid the cost of obtaining the vector, and we also avoid any wait for the index to catch up to the vector.
+     *
+     * @since 1.0.0
+     * @committed
+     */
+    not_bounded = 0,
+
+    /**
+     * The indexer will wait until all mutations have been processed at the time of request before returning to the query engine.
+     *
+     * This implements strong consistency per request. Before processing the request, a current vector is obtained. The vector is used as a
+     * lower bound for the statements in the request. If there are DML statements in the request, RYOW ("read your own write") is also
+     * applied within the request.
+     *
+     * @since 1.0.0
+     * @committed
+     */
+    request_plus,
+};
+} // namespace couchbase

data/ext/couchbase/couchbase/analytics_status.hxx

@@ -0,0 +1,41 @@
+/* -*- 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
+
+namespace couchbase
+{
+/**
+ * Status of the Analytics Query
+ *
+ * @since 1.0.0
+ * @committed
+ */
+enum class analytics_status {
+    running,
+    success,
+    errors,
+    completed,
+    stopped,
+    timeout,
+    closed,
+    fatal,
+    aborted,
+    unknown,
+};
+
+} // namespace couchbase

data/ext/couchbase/couchbase/analytics_warning.hxx

@@ -0,0 +1,85 @@
+/* -*- 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 <string>
+
+namespace couchbase
+{
+
+/**
+ * Represents a single warning returned from the analytics engine.
+ *
+ * @note warnings are not terminal errors but hints from the engine that something was not as expected.
+ *
+ * @since 1.0.0
+ * @committed
+ */
+class analytics_warning
+{
+  public:
+    /**
+     * @since 1.0.0
+     * @internal
+     */
+    analytics_warning() = default;
+
+    /**
+     * @since 1.0.0
+     * @volatile
+     */
+    analytics_warning(std::uint64_t code, std::string message)
+      : code_{ code }
+      , message_{ std::move(message) }
+    {
+    }
+
+    /**
+     * Error code.
+     *
+     * @return error code
+     *
+     * @since 1.0.0
+     * @committed
+     */
+    [[nodiscard]] auto code() const -> std::uint64_t
+    {
+        return code_;
+    }
+
+    /**
+     * Error message.
+     *
+     * @return human readable explanation
+     *
+     * @since 1.0.0
+     * @committed
+     */
+    [[nodiscard]] auto message() const -> const std::string&
+    {
+        return message_;
+    }
+
+  private:
+    std::uint64_t code_{};
+    std::string message_{};
+};
+
+} // namespace couchbase

data/ext/couchbase/couchbase/behavior_options.hxx

@@ -54,18 +54,26 @@ class behavior_options
         return *this;
     }
 
+    auto dump_configuration(bool enable) -> behavior_options&
+    {
+        dump_configuration_ = enable;
+        return *this;
+    }
+
     struct built {
         std::string user_agent_extra;
         bool show_queries;
         bool enable_clustermap_notification;
         bool enable_mutation_tokens;
         bool enable_unordered_execution;
+        bool dump_configuration;
     };
 
     [[nodiscard]] auto build() const -> built
     {
         return {
-            user_agent_extra_, show_queries_, enable_clustermap_notification_, enable_mutation_tokens_, enable_unordered_execution_,
+            user_agent_extra_,           show_queries_,       enable_clustermap_notification_, enable_mutation_tokens_,
+            enable_unordered_execution_, dump_configuration_,
         };
     }
 
@@ -75,5 +83,6 @@ class behavior_options
     bool enable_clustermap_notification_{ false };
     bool enable_mutation_tokens_{ true };
     bool enable_unordered_execution_{ true };
+    bool dump_configuration_{ false };
 };
 } // namespace couchbase

data/ext/couchbase/couchbase/boolean_field_query.hxx

@@ -0,0 +1,77 @@
+/* -*- 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
+{
+/**
+ * Allow to match `true`/`false` in a field mapped as boolean.
+ *
+ * @since 1.0.0
+ * @committed
+ */
+class boolean_field_query : public search_query
+{
+  public:
+    /**
+     * Create a new boolean field query.
+     *
+     * @param value the input string to be matched against
+     *
+     * @since 1.0.0
+     * @committed
+     */
+    explicit boolean_field_query(bool value)
+      : bool_{ value }
+    {
+    }
+
+    /**
+     * 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) -> boolean_field_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:
+    bool bool_;
+    std::optional<std::string> field_{};
+};
+} // namespace couchbase

data/ext/couchbase/couchbase/boolean_query.hxx

@@ -0,0 +1,223 @@
+/* -*- 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/conjunction_query.hxx>
+#include <couchbase/disjunction_query.hxx>
+#include <couchbase/match_all_query.hxx>
+#include <couchbase/match_none_query.hxx>
+#include <couchbase/search_query.hxx>
+
+#include <cstdint>
+#include <memory>
+#include <vector>
+
+namespace couchbase
+{
+/**
+ * The boolean query is a useful combination of conjunction and disjunction queries. A boolean query takes three lists of queries:
+ *
+ * * **must** - result documents must satisfy all of these queries.
+ * * **should** - result documents should satisfy these queries.
+ * * **must not** - result documents must not satisfy any of these queries.
+ *
+ * At execution, a boolean query that has no child queries in any 3 categories is not allowed and will fail fast.
+ *
+ * The inner representation of child queries in the `must`/`must_not`/`should` sections are respectively a @ref conjunction_query and two
+ * @ref disjunction_query.
+ *
+ * In the example below the following rules enforced by the boolean query:
+ * * retrieved documents MUST match `"hostel room"` in their `reviews.content` field AND have `true` in `free_breakfast` field.
+ * * also the documents SHOULD have EITHER `reviews.ratings.Overall > 4` OR `reviews.ratings.Service > 5`.
+ * * and finally, exclude documents with `city` `"Padfield"` or `"Gilingham"`.
+ *
+ * @snippet test_unit_search.cxx search-boolean
+ *
+ * @see https://docs.couchbase.com/server/current/fts/fts-supported-queries-boolean-field-query.html server documentation
+ *
+ * @since 1.0.0
+ * @committed
+ */
+class boolean_query : public search_query
+{
+  public:
+    /**
+     * Set @ref conjunction_query that groups all queries the documents **must** satisfy.
+     *
+     * @param query must-query
+     *
+     * @return this query for chaining purposes.
+     *
+     * @since 1.0.0
+     * @committed
+     */
+    auto must(conjunction_query query) -> boolean_query&
+    {
+        must_ = std::move(query);
+        return *this;
+    }
+
+    /**
+     * Create @ref conjunction_query with given queries and set it as **must** query.
+     *
+     * @tparam SearchQuery any subclass of @ref search_query
+     * @param queries
+     *
+     * @return this query for chaining purposes.
+     *
+     * @since 1.0.0
+     * @committed
+     */
+    template<typename... SearchQuery>
+    auto must(SearchQuery... queries) -> boolean_query&
+    {
+        must_ = conjunction_query(queries...);
+        return *this;
+    }
+
+    /**
+     * Returns @ref conjunction_query that groups all queries the documents **must** satisfy. Use it to add more queries.
+     *
+     * @return must-query
+     *
+     * @since 1.0.0
+     * @committed
+     */
+    auto must() -> conjunction_query&
+    {
+        if (!must_) {
+            must_ = conjunction_query();
+        }
+        return must_.value();
+    }
+
+    /**
+     * Set @ref disjunction_query that groups  queries the documents **should** satisfy.
+     *
+     * @param query should-query
+     *
+     * @return this query for chaining purposes.
+     *
+     * @since 1.0.0
+     * @committed
+     */
+    auto should(disjunction_query query) -> boolean_query&
+    {
+        should_ = std::move(query);
+        return *this;
+    }
+
+    /**
+     * Create @ref disjunction_query with given queries and set it as **should** query.
+     *
+     * @tparam SearchQuery any subclass of @ref search_query
+     * @param queries
+     *
+     * @return this query for chaining purposes.
+     *
+     * @since 1.0.0
+     * @committed
+     */
+    template<typename... SearchQuery>
+    auto should(SearchQuery... queries) -> boolean_query&
+    {
+        should_ = disjunction_query(queries...);
+        return *this;
+    }
+
+    /**
+     * Returns @ref disjunction_query that groups  queries the documents **should** satisfy. Use it to add more queries or change
+     * @ref disjunction_query#min.
+     *
+     * @return should-query
+     *
+     * @since 1.0.0
+     * @committed
+     */
+    auto should() -> disjunction_query&
+    {
+        if (!should_) {
+            should_ = disjunction_query();
+        }
+        return should_.value();
+    }
+
+    /**
+     * Set @ref disjunction_query that groups queries the documents **must not** satisfy.
+     *
+     * @param query must_not-query
+     *
+     * @return this query for chaining purposes.
+     *
+     * @since 1.0.0
+     * @committed
+     */
+    auto must_not(disjunction_query query) -> boolean_query&
+    {
+        must_not_ = std::move(query);
+        return *this;
+    }
+
+    /**
+     * Create @ref disjunction_query with given queries and set it as **must not** query.
+     *
+     * @tparam SearchQuery any subclass of @ref search_query
+     * @param queries
+     *
+     * @return this query for chaining purposes.
+     *
+     * @since 1.0.0
+     * @committed
+     */
+    template<typename... SearchQuery>
+    auto must_not(SearchQuery... queries) -> boolean_query&
+    {
+        must_not_ = disjunction_query(queries...);
+        return *this;
+    }
+
+    /**
+     * Returns @ref disjunction_query that groups  queries the documents **should** satisfy. Use it to add more queries.
+     *
+     * @return must_not-query
+     *
+     * @since 1.0.0
+     * @committed
+     */
+    auto must_not() -> disjunction_query&
+    {
+        if (!must_not_) {
+            must_not_ = disjunction_query();
+        }
+        return must_not_.value();
+    }
+
+    /**
+     * @return encoded representation of the query.
+     *
+     * @since 1.0.0
+     * @internal
+     */
+    [[nodiscard]] auto encode() const -> encoded_search_query override;
+
+  private:
+    std::optional<conjunction_query> must_{};
+    std::optional<disjunction_query> should_{};
+    std::optional<disjunction_query> must_not_{};
+};
+} // namespace couchbase