couchbase 3.4.2 → 3.4.3

data/ext/couchbase/couchbase/match_query.hxx

@@ -0,0 +1,163 @@
+/* -*- 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 <stdexcept>
+#include <string>
+
+namespace couchbase
+{
+/**
+ * A match query analyzes the input text and uses that analyzed text to query the index. An attempt is made to use the same analyzer that
+ * was used when the field was indexed.
+ *
+ * Match documents with both `"location"` and `"hostel"` terms in the field `reviews.content`, ensuring common prefix length `4`, maximum
+ * fuzziness and select standard analyzer.
+ * @snippet test_unit_search.cxx search-match
+ *
+ * @see https://docs.couchbase.com/server/current/fts/fts-supported-queries-match.html server documentation
+ *
+ * @since 1.0.0
+ * @committed
+ */
+class match_query : public search_query
+{
+  public:
+    /**
+     * Create a new match query.
+     *
+     * @param match the input string to be matched against
+     *
+     * @since 1.0.0
+     * @committed
+     */
+    explicit match_query(std::string match)
+      : match_{ std::move(match) }
+    {
+    }
+
+    /**
+     * Require that the term also have the same prefix of the specified length (must be positive).
+     *
+     * @param length the length of the term prefix
+     *
+     * @return this query for chaining purposes.
+     *
+     * @since 1.0.0
+     * @committed
+     */
+    auto prefix_length(std::uint32_t length) -> match_query&
+    {
+        if (length <= 0) {
+            throw std::invalid_argument("prefix_length must be positive");
+        }
+
+        prefix_length_ = length;
+        return *this;
+    }
+
+    /**
+     * Analyzers are used to transform input text into a stream of tokens for indexing. The Server comes with built-in analyzers and the
+     * users can create their own.
+     *
+     * @param analyzer_name the name of the analyzer used
+     *
+     * @return this query for chaining purposes.
+     *
+     * @since 1.0.0
+     * @committed
+     */
+    auto analyzer(std::string analyzer_name) -> match_query&
+    {
+        analyzer_ = std::move(analyzer_name);
+        return *this;
+    }
+
+    /**
+     * If a field is specified, only terms in that field will be matched.
+     *
+     * This can also affect the used analyzer if one isn't specified explicitly.
+     *
+     * @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) -> match_query&
+    {
+        field_ = std::move(field_name);
+        return *this;
+    }
+
+    /**
+     * Perform fuzzy matching. If the fuzziness parameter is set to a non-zero integer the analyzed text will be matched with the specified
+     * level of fuzziness.
+     *
+     * @param fuzziness level of fuzziness (the maximum supported fuzziness is 2).
+     *
+     * @return this query for chaining purposes.
+     *
+     * @since 1.0.0
+     * @committed
+     */
+    auto fuzziness(std::uint32_t fuzziness) -> match_query&
+    {
+        fuzziness_ = fuzziness;
+        return *this;
+    }
+
+    /**
+     * Defines how the individual match terms should be logically concatenated
+     *
+     * @param concatenation_operator operator to be used
+     *
+     * @return this query for chaining purposes.
+     *
+     * @since 1.0.0
+     * @committed
+     */
+    auto match_operator(couchbase::match_operator concatenation_operator) -> match_query&
+    {
+        operator_ = concatenation_operator;
+        return *this;
+    }
+
+    /**
+     * @return encoded representation of the query.
+     *
+     * @since 1.0.0
+     * @internal
+     */
+    [[nodiscard]] auto encode() const -> encoded_search_query override;
+
+  private:
+    std::string match_;
+    std::optional<std::uint32_t> prefix_length_{};
+    std::optional<std::string> analyzer_{};
+    std::optional<std::string> field_{};
+    std::optional<std::uint32_t> fuzziness_{};
+    std::optional<couchbase::match_operator> operator_{};
+};
+} // namespace couchbase

data/ext/couchbase/couchbase/numeric_range.hxx

@@ -0,0 +1,58 @@
+/* -*- 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 <cstdint>
+#include <optional>
+#include <string>
+
+namespace couchbase
+{
+/**
+ * Numeric range for @ref numeric_range_facet.
+ */
+class numeric_range
+{
+  public:
+    numeric_range(std::string name, double min, double max);
+    static numeric_range with_min(std::string name, double start);
+    static numeric_range with_max(std::string name, double end);
+
+    [[nodiscard]] auto name() const -> const std::string&
+    {
+        return name_;
+    }
+
+    [[nodiscard]] auto min() const -> const std::optional<double>&
+    {
+        return min_;
+    }
+
+    [[nodiscard]] auto max() const -> const std::optional<double>&
+    {
+        return max_;
+    }
+
+  private:
+    numeric_range(std::string name, std::optional<double> min, std::optional<double> max);
+
+    std::string name_;
+    std::optional<double> min_{};
+    std::optional<double> max_{};
+};
+} // namespace couchbase

data/ext/couchbase/couchbase/numeric_range_facet.hxx

@@ -0,0 +1,56 @@
+/* -*- 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/numeric_range.hxx>
+#include <couchbase/search_facet.hxx>
+
+#include <vector>
+
+namespace couchbase
+{
+/**
+ * A facet that categorizes rows into numerical ranges (or buckets) provided by the user.
+ */
+class numeric_range_facet : public search_facet
+{
+  public:
+    numeric_range_facet(std::string field, std::vector<numeric_range> ranges)
+      : search_facet{ std::move(field) }
+      , ranges_{ std::move(ranges) }
+    {
+    }
+
+    numeric_range_facet(std::string field, std::uint32_t size, std::vector<numeric_range> ranges)
+      : search_facet{ std::move(field), size }
+      , ranges_{ std::move(ranges) }
+    {
+    }
+
+    /**
+     * @return encoded representation of the search facet.
+     *
+     * @since 1.0.0
+     * @internal
+     */
+    [[nodiscard]] auto encode() const -> encoded_search_facet override;
+
+  private:
+    std::vector<numeric_range> ranges_;
+};
+} // namespace couchbase

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