couchbase 3.4.2 → 3.4.3

data/ext/couchbase/couchbase/geo_bounding_box_query.hxx

@@ -0,0 +1,107 @@
+/* -*- 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/geo_point.hxx>
+#include <couchbase/search_query.hxx>
+
+#include <optional>
+#include <string>
+
+namespace couchbase
+{
+/**
+ * This query finds all @ref geo_point indexed matches within a given area (identified by the list of @ref geo_point coordinates). Each of
+ * the pairs is taken to indicate one corner of a polygon. Documents are returned if they reference a location within the area of the
+ * polygon.
+ *
+ * The following query-body uses an array of @ref geo_point to specify the latitude and longitude of each of the corners of a polygon, known
+ * as polygon points. Here, the last-specified entry is 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 test_unit_search.cxx search-geo-bounding-box
+ *
+ * @see https://docs.couchbase.com/server/current/fts/fts-supported-queries-geo-bounded-rectangle.html server documentation
+ *
+ * @since 1.0.0
+ * @committed
+ */
+class geo_bounding_box_query : public search_query
+{
+  public:
+    /**
+     * Create a new geo bounding box query.
+     *
+     * @param top_left the top left coordinates signify the bounding box area
+     * @param bottom_right the bottom right coordinates signify the bounding box area
+     *
+     * @since 1.0.0
+     * @committed
+     */
+    geo_bounding_box_query(geo_point top_left, geo_point bottom_right)
+      : top_left_{ top_left }
+      , bottom_right_{ bottom_right }
+    {
+    }
+
+    /**
+     * Create a new geo distance query.
+     *
+     * @param top_left_latitude  latitude of the top left coordinate
+     * @param top_left_longitude  longitude of the top left coordinate
+     * @param bottom_right_latitude  latitude of the bottom right coordinate
+     * @param bottom_right_longitude  latitude of the bottom right coordinate
+     *
+     * @since 1.0.0
+     * @committed
+     */
+    geo_bounding_box_query(double top_left_latitude, double top_left_longitude, double bottom_right_latitude, double bottom_right_longitude)
+      : top_left_{ geo_point{ top_left_latitude, top_left_longitude } }
+      , bottom_right_{ geo_point{ bottom_right_latitude, bottom_right_longitude } }
+    {
+    }
+
+    /**
+     * 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) -> geo_bounding_box_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:
+    geo_point top_left_;
+    geo_point bottom_right_;
+    std::optional<std::string> field_{};
+};
+} // namespace couchbase

data/ext/couchbase/couchbase/geo_distance_query.hxx

@@ -0,0 +1,109 @@
+/* -*- 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/geo_point.hxx>
+#include <couchbase/search_query.hxx>
+
+#include <optional>
+#include <string>
+
+namespace couchbase
+{
+/**
+ * This query finds all matches from a given location as @ref geo_point within the given distance. Both the point and the distance are
+ * required.
+ *
+ * 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 test_unit_search.cxx search-geo-distance
+ *
+ * @see https://docs.couchbase.com/server/current/fts/fts-supported-queries-geo-point-distance.html server documentation
+ *
+ * @since 1.0.0
+ * @committed
+ */
+class geo_distance_query : public search_query
+{
+  public:
+    /**
+     * Create a new geo distance query.
+     *
+     * @param location the location represents a point from which the distance is measured.
+     * @param distance the distance describes how far from the location the radius should be matched. For example, `"11km"`,
+     * `"11kilometers"`, `"3nm"`, `"3nauticalmiles"`, `"17mi"`, `"17miles"`, `"19m"`, `"19meters"`.
+     *
+     * @see https://github.com/blevesearch/bleve/blob/ae28975038cb25655da968e3f043210749ba382b/geo/geo_dist.go#L29-L37 list of distance
+     * units.
+     *
+     * @since 1.0.0
+     * @committed
+     */
+    geo_distance_query(geo_point location, std::string distance)
+      : location_{ location }
+      , distance_{ std::move(distance) }
+    {
+    }
+
+    /**
+     * Create a new geo distance query.
+     *
+     * @param latitude the location latitude
+     * @param longitude the location longitude
+     * @param distance the distance describes how far from the location the radius should be matched. For example, `"11km"`,
+     * `"11kilometers"`, `"3nm"`, `"3nauticalmiles"`, `"17mi"`, `"17miles"`, `"19m"`, `"19meters"`.
+     *
+     * @since 1.0.0
+     * @committed
+     */
+    geo_distance_query(double latitude, double longitude, std::string distance)
+      : location_{ geo_point{ latitude, longitude } }
+      , distance_{ std::move(distance) }
+    {
+    }
+
+    /**
+     * 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) -> geo_distance_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:
+    geo_point location_;
+    std::string distance_;
+    std::optional<std::string> field_{};
+};
+} // namespace couchbase

data/ext/couchbase/couchbase/geo_point.hxx

@@ -0,0 +1,32 @@
+/* -*- 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
+
+namespace couchbase
+{
+/**
+ * Tuple representing geographical point.
+ *
+ * @since 1.0.0
+ * @committed
+ */
+struct geo_point {
+    double latitude{ 0 };
+    double longitude{ 0 };
+};
+} // namespace couchbase

data/ext/couchbase/couchbase/geo_polygon_query.hxx

@@ -0,0 +1,85 @@
+/* -*- 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/geo_point.hxx>
+#include <couchbase/search_query.hxx>
+
+#include <optional>
+#include <string>
+#include <vector>
+
+namespace couchbase
+{
+/**
+ * A search query which allows to match inside a geo polygon.
+ *
+ * If a target data-location falls within the box, its document is returned.
+ *
+ * @snippet test_unit_search.cxx search-geo-polygon
+ *
+ * @see https://docs.couchbase.com/server/current/fts/fts-supported-queries-geo-bounded-polygon.html server documentation
+ *
+ * @since 1.0.0
+ * @committed
+ */
+class geo_polygon_query : public search_query
+{
+  public:
+    /**
+     * Create a new geo polygon query.
+     *
+     * @param points the points specifying corners of geo polygon.
+     *
+     * @since 1.0.0
+     * @committed
+     */
+    explicit geo_polygon_query(std::vector<geo_point> points)
+      : polygon_points_{ std::move(points) }
+    {
+    }
+
+    /**
+     * 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) -> geo_polygon_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<geo_point> polygon_points_;
+    std::optional<std::string> field_{};
+};
+} // namespace couchbase

data/ext/couchbase/couchbase/highlight_style.hxx

@@ -0,0 +1,45 @@
+/* -*- 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
+{
+/**
+ * Enumeration of the highlighting styles recognized by the FTS engine.
+ *
+ * @since 1.0.0
+ * @committed
+ */
+enum class highlight_style {
+    /**
+     * Use HTML tags `<mark>` and `</mark>` to indicate matches in the fields.
+     *
+     * @since 1.0.0
+     * @committed
+     */
+    html,
+
+    /**
+     * Use ANSI code sequences `\\x1b[43m>` and `\\x1b[0m` to indicate matches in the fields.
+     *
+     * @since 1.0.0
+     * @committed
+     */
+    ansi,
+};
+} // namespace couchbase

data/ext/couchbase/couchbase/match_all_query.hxx

@@ -0,0 +1,43 @@
+/* -*- 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>
+
+namespace couchbase
+{
+/**
+ * A query that matches all indexed documents.
+ *
+ * @see https://docs.couchbase.com/server/current/fts/fts-supported-queries-match-all.html server documentation
+ *
+ * @since 1.0.0
+ * @committed
+ */
+class match_all_query : public search_query
+{
+  public:
+    /**
+     * @return encoded representation of the query.
+     *
+     * @since 1.0.0
+     * @internal
+     */
+    [[nodiscard]] auto encode() const -> encoded_search_query override;
+};
+} // namespace couchbase

data/ext/couchbase/couchbase/match_none_query.hxx

@@ -0,0 +1,43 @@
+/* -*- 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>
+
+namespace couchbase
+{
+/**
+ * A query that matches nothing.
+ *
+ * @see https://docs.couchbase.com/server/current/fts/fts-supported-queries-match-none.html server documentation
+ *
+ * @since 1.0.0
+ * @committed
+ */
+class match_none_query : public search_query
+{
+  public:
+    /**
+     * @return encoded representation of the query.
+     *
+     * @since 1.0.0
+     * @internal
+     */
+    [[nodiscard]] auto encode() const -> encoded_search_query override;
+};
+} // namespace couchbase

data/ext/couchbase/couchbase/match_operator.hxx

@@ -0,0 +1,45 @@
+/* -*- 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
+
+namespace couchbase
+{
+/**
+ * Defines how the individual match terms should be logically concatenated
+ *
+ * @since 1.0.0
+ * @committed
+ */
+enum class match_operator {
+    /**
+     * Individual match terms are concatenated with a logical OR - this is the default if not provided.
+     *
+     * @since 1.0.0
+     * @committed
+     */
+    logical_or,
+
+    /**
+     * Individual match terms are concatenated with a logical AND.
+     *
+     * @since 1.0.0
+     * @committed
+     */
+    logical_and,
+};
+} // namespace couchbase

data/ext/couchbase/couchbase/match_phrase_query.hxx

@@ -0,0 +1,108 @@
+/* -*- 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 input text is analyzed and a phrase query is built with the terms resulting from the analysis. This type of query searches for terms
+ * occurring in the specified positions and offsets. This depends on term vectors, which are consulted to determine phrase distance.
+ *
+ * For example, a match phrase query for `"location for functions"` is matched with `"locate the function"`, if the standard analyzer is
+ * used: this analyzer uses a **stemmer**, which tokenizes `"location"` and `"locate"` to `"locat"`, and reduces `"functions"` and
+ * `"function"` to `"function"`. Additionally, the analyzer employs stop removal, which removes small and less significant words from input
+ * and target text, so that matches are attempted on only the more significant elements of vocabulary: in this case `"for"` and `"the"` are
+ * removed. Following this processing, the tokens `"locat"` and `"function"` are recognized as common to both input and target; and also as
+ * being both in the same sequence as, and at the same distance from one another; and therefore a match is made.
+ * @snippet test_unit_search.cxx search-match-phrase
+ *
+ * @see https://docs.couchbase.com/server/current/fts/fts-supported-queries-match-phrase.html
+ *
+ * @since 1.0.0
+ * @committed
+ */
+class match_phrase_query : public search_query
+{
+  public:
+    /**
+     * Create a new match phrase query.
+     *
+     * @param match_phrase the input string to be matched against
+     *
+     * @since 1.0.0
+     * @committed
+     */
+    explicit match_phrase_query(std::string match_phrase)
+      : match_phrase_{ std::move(match_phrase) }
+    {
+    }
+
+    /**
+     * 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_phrase_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_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::string match_phrase_;
+    std::optional<std::string> analyzer_{};
+    std::optional<std::string> field_{};
+};
+} // namespace couchbase