apache · leaves12138 · Jun 2, 2026 · Jun 1, 2026 · Jun 1, 2026
diff --git a/include/paimon/predicate/full_text_search.h b/include/paimon/predicate/full_text_search.h
@@ -0,0 +1,91 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you 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 <functional>
+#include <map>
+#include <memory>
+#include <optional>
+#include <string>
+#include <vector>
+
+#include "paimon/predicate/predicate.h"
+#include "paimon/utils/roaring_bitmap64.h"
+#include "paimon/visibility.h"
+namespace paimon {
+/// A configuration structure for full-text search operations.
+struct PAIMON_EXPORT FullTextSearch {
+    /// Enumeration of supported full-text search types.
+    enum class SearchType {
+        /// All terms in the query must be present (AND semantics).
+        MATCH_ALL = 1,
+        /// Any term in the query can match (OR semantics).
+        MATCH_ANY = 2,
+        /// Matches the exact sequence of words (with proximity).
+        PHRASE = 3,
+        /// Matches terms starting with the given string (e.g., "run*" → running, runner).
+        PREFIX = 4,
+        /// Supports wildcards * and ? (e.g., "ap*e", "app?e" -> "apple").
+        WILDCARD = 5,
+        /// Default/fallback type for unrecognized or invalid queries.
+        UNKNOWN = 128
+    };
+
+    FullTextSearch(const std::string& _field_name, std::optional<int32_t> _limit,
+                   const std::string& _query, const SearchType& _search_type,
+                   const std::optional<RoaringBitmap64>& _pre_filter)
+        : field_name(_field_name),
+          limit(_limit),
+          query(_query),
+          search_type(_search_type),
+          pre_filter(_pre_filter) {}
+
+    std::shared_ptr<FullTextSearch> ReplacePreFilter(
+        const std::optional<RoaringBitmap64>& _pre_filter) const {
+        return std::make_shared<FullTextSearch>(field_name, limit, query, search_type, _pre_filter);
+    }
+
+    /// Name of the field to search within (must be a full-text indexed field).
+    std::string field_name;
+    /// Maximum number of documents to return. If set, limit ordered by top scores. Otherwise, no
+    /// score return.
+    std::optional<int32_t> limit;
+    /// The query string to search for. The interpretation depends on search_type:
+    ///
+    /// - For MATCH_ALL/MATCH_ANY: keywords are split into terms using the **same analyzer as
+    ///   indexing**.
+    ///   Example: "Hello World" → terms ["hello", "world"] (after lowercasing and tokenization).
+    ///
+    /// - For PHRASE: matches the exact word sequence (with optional slop). Also be analyzed.
+    ///
+    /// - For PREFIX: matches terms starting with the given string (e.g., "run" → running, runner).
+    ///   Only the prefix part is considered; analysis will not be applied.
+    ///
+    /// - For WILDCARD: supports wildcards * and ? (e.g., "ap*e", "app?e").
+    ///   Not passed through analyzer — matched directly against indexed terms.
+    ///
+    /// @note Analyzer consistency between indexing and querying is critical for correctness.
+    std::string query;
+    /// Type of search to perform.
+    SearchType search_type;
+    /// A pre-filter based on **global row IDs**, implemented by leveraging another global index.
+    /// Only rows whose global row ID is present in `pre_filter` will be included during search.
+    /// If not set, all rows will be included.
+    std::optional<RoaringBitmap64> pre_filter;
+};
+}  // namespace paimon
diff --git a/include/paimon/predicate/predicate_builder.h b/include/paimon/predicate/predicate_builder.h
@@ -0,0 +1,171 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you 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 <memory>
+#include <string>
+#include <vector>
+
+#include "paimon/predicate/predicate.h"
+#include "paimon/result.h"
+#include "paimon/visibility.h"
+
+namespace paimon {
+class Literal;
+enum class FieldType;
+
+/// A utility class to create `Predicate` object for common filter conditions.
+///
+/// PredicateBuilder provides static factory methods to create various types of predicates
+/// that can be used for filtering data in Paimon tables.
+class PAIMON_EXPORT PredicateBuilder {
+ public:
+    PredicateBuilder() = delete;
+    ~PredicateBuilder() = delete;
+
+    /// Create an equality predicate (field == literal).
+    ///
+    /// @param field_index The index of the field in read schema (0-based).
+    /// @param field_name The name of the field.
+    /// @param field_type The data type of the field.
+    /// @param literal The literal value to compare against.
+    /// @return A shared pointer to the created Predicate object.
+    static std::shared_ptr<Predicate> Equal(int32_t field_index, const std::string& field_name,
+                                            const FieldType& field_type, const Literal& literal);
+
+    /// Create a not-equal predicate (field != literal).
+    static std::shared_ptr<Predicate> NotEqual(int32_t field_index, const std::string& field_name,
+                                               const FieldType& field_type, const Literal& literal);
+
+    /// Create a less-than predicate (field < literal).
+    static std::shared_ptr<Predicate> LessThan(int32_t field_index, const std::string& field_name,
+                                               const FieldType& field_type, const Literal& literal);
+
+    /// Create a less-than-or-equal predicate (field <= literal).
+    static std::shared_ptr<Predicate> LessOrEqual(int32_t field_index,
+                                                  const std::string& field_name,
+                                                  const FieldType& field_type,
+                                                  const Literal& literal);
+
+    /// Create a greater-than predicate (field > literal).
+    static std::shared_ptr<Predicate> GreaterThan(int32_t field_index,
+                                                  const std::string& field_name,
+                                                  const FieldType& field_type,
+                                                  const Literal& literal);
+
+    /// Create a greater-than-or-equal predicate (field >= literal).
+    static std::shared_ptr<Predicate> GreaterOrEqual(int32_t field_index,
+                                                     const std::string& field_name,
+                                                     const FieldType& field_type,
+                                                     const Literal& literal);
+
+    /// Create an IS NULL predicate (field IS NULL).
+    static std::shared_ptr<Predicate> IsNull(int32_t field_index, const std::string& field_name,
+                                             const FieldType& field_type);
+
+    /// Create an IS NOT NULL predicate (field IS NOT NULL).
+    static std::shared_ptr<Predicate> IsNotNull(int32_t field_index, const std::string& field_name,
+                                                const FieldType& field_type);
+
+    /// Create an IN predicate (field IN (literal1, literal2, ...)).
+    ///
+    /// Tests whether the field value matches any of the provided literal values.
+    static std::shared_ptr<Predicate> In(int32_t field_index, const std::string& field_name,
+                                         const FieldType& field_type,
+                                         const std::vector<Literal>& literals);
+
+    /// Create a NOT IN predicate (field NOT IN (literal1, literal2, ...)).
+    ///
+    /// Tests whether the field value does not match any of the provided literal values.
+    static std::shared_ptr<Predicate> NotIn(int32_t field_index, const std::string& field_name,
+                                            const FieldType& field_type,
+                                            const std::vector<Literal>& literals);
+
+    /// Create a BETWEEN predicate (field BETWEEN lower_bound AND upper_bound).
+    ///
+    /// Tests whether the field value falls within the specified range (inclusive on both ends).
+    ///
+    /// @param field_index The index of the field in read schema (0-based).
+    /// @param field_name The name of the field.
+    /// @param field_type The data type of the field.
+    /// @param included_lower_bound The lower bound of the range (inclusive).
+    /// @param included_upper_bound The upper bound of the range (inclusive).
+    static std::shared_ptr<Predicate> Between(int32_t field_index, const std::string& field_name,
+                                              const FieldType& field_type,
+                                              const Literal& included_lower_bound,
+                                              const Literal& included_upper_bound);
+
+    /// Create an AND predicate combining multiple predicates.
+    ///
+    /// Creates a logical AND operation that evaluates to true only when all input predicates
+    /// evaluate to true.
+    ///
+    /// @param predicates A vector of shared pointers to the predicates, which must not be empty.
+    static Result<std::shared_ptr<Predicate>> And(
+        const std::vector<std::shared_ptr<Predicate>>& predicates);
+
+    /// Create an OR predicate combining multiple predicates.
+    ///
+    /// Creates a logical OR operation that evaluates to true when at least one of the input
+    /// predicates evaluates to true.
+    ///
+    /// @param predicates A vector of shared pointers to the predicates, which must not be empty.
+    static Result<std::shared_ptr<Predicate>> Or(
+        const std::vector<std::shared_ptr<Predicate>>& predicates);
+
+    /// Create a NOT predicate negating the result of another predicate.
+    ///
+    /// Creates a logical NOT operation that inverts the truth value of the input predicate.
+    ///
+    /// @param predicate A shared pointer to the predicate to be negated, which must not be nullptr.
+    static Result<std::shared_ptr<Predicate>> Not(const std::shared_ptr<Predicate>& predicate);
+
+    /// Create a starts-with predicate (field like 'abc%' or field like 'abc_').
+    ///
+    /// Tests whether the field value starts with the provided literal value.
+    static Result<std::shared_ptr<Predicate>> StartsWith(int32_t field_index,
+                                                         const std::string& field_name,
+                                                         const FieldType& field_type,
+                                                         const Literal& literal);
+
+    /// Create an ends-with predicate (field like '%abc' or field like '_abc').
+    ///
+    /// Tests whether the field value ends with the provided literal value.
+    static Result<std::shared_ptr<Predicate>> EndsWith(int32_t field_index,
+                                                       const std::string& field_name,
+                                                       const FieldType& field_type,
+                                                       const Literal& literal);
+
+    /// Create a contains predicate (field like '%abc%').
+    ///
+    /// Tests whether the field value contains the provided literal value.
+    static Result<std::shared_ptr<Predicate>> Contains(int32_t field_index,
+                                                       const std::string& field_name,
+                                                       const FieldType& field_type,
+                                                       const Literal& literal);
+
+    /// Create a like predicate (field like literal).
+    ///
+    /// Tests whether the field value like the provided literal value.
+    static Result<std::shared_ptr<Predicate>> Like(int32_t field_index,
+                                                   const std::string& field_name,
+                                                   const FieldType& field_type,
+                                                   const Literal& literal);
+};
+}  // namespace paimon
diff --git a/include/paimon/predicate/predicate_utils.h b/include/paimon/predicate/predicate_utils.h
@@ -0,0 +1,133 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you 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 <map>
+#include <memory>
+#include <optional>
+#include <set>
+#include <string>
+#include <vector>
+
+#include "paimon/predicate/function.h"
+#include "paimon/predicate/function_visitor.h"
+#include "paimon/predicate/leaf_predicate.h"
+#include "paimon/predicate/predicate.h"
+#include "paimon/result.h"
+#include "paimon/status.h"
+#include "paimon/visibility.h"
+
+namespace paimon {
+
+class PAIMON_EXPORT PredicateUtils {
+ public:
+    PredicateUtils() = delete;
+    ~PredicateUtils() = delete;
+    static Result<bool> ContainAnyField(const std::shared_ptr<Predicate>& predicate,
+                                        const std::set<std::string>& field_names);
+
+    static Result<std::shared_ptr<Predicate>> ExcludePredicateWithFields(
+        const std::shared_ptr<Predicate>& predicates, const std::set<std::string>& field_names);
+
+    static Result<std::vector<std::shared_ptr<Predicate>>> ExcludePredicateWithFields(
+        const std::vector<std::shared_ptr<Predicate>>& predicates,
+        const std::set<std::string>& field_names);
+
+    static std::vector<std::shared_ptr<Predicate>> SplitAnd(
+        const std::shared_ptr<Predicate>& predicate);
+
+    // picked_field_name_to_idx: [field_name, idx in target schema]
+    static Result<std::shared_ptr<Predicate>> CreatePickedFieldFilter(
+        const std::shared_ptr<Predicate>& predicate,
+        const std::map<std::string, int32_t>& picked_field_name_to_idx);
+
+    static Status GetAllNames(const std::shared_ptr<Predicate>& predicate,
+                              std::set<std::string>* field_names);
+
+    template <typename T>
+    static Result<T> VisitPredicate(const std::shared_ptr<LeafPredicate>& predicate,
+                                    const std::shared_ptr<FunctionVisitor<T>>& visitor) {
+        auto type = predicate->GetFunction().GetType();
+        switch (type) {
+            case Function::Type::IS_NULL:
+                return visitor->VisitIsNull();
+            case Function::Type::IS_NOT_NULL:
+                return visitor->VisitIsNotNull();
+            case Function::Type::EQUAL: {
+                assert(predicate->Literals().size() == 1);
+                return visitor->VisitEqual(predicate->Literals()[0]);
+            }
+            case Function::Type::NOT_EQUAL: {
+                assert(predicate->Literals().size() == 1);
+                return visitor->VisitNotEqual(predicate->Literals()[0]);
+            }
+            case Function::Type::GREATER_THAN: {
+                assert(predicate->Literals().size() == 1);
+                return visitor->VisitGreaterThan(predicate->Literals()[0]);
+            }
+            case Function::Type::GREATER_OR_EQUAL: {
+                assert(predicate->Literals().size() == 1);
+                return visitor->VisitGreaterOrEqual(predicate->Literals()[0]);
+            }
+            case Function::Type::LESS_THAN: {
+                assert(predicate->Literals().size() == 1);
+                return visitor->VisitLessThan(predicate->Literals()[0]);
+            }
+            case Function::Type::LESS_OR_EQUAL: {
+                assert(predicate->Literals().size() == 1);
+                return visitor->VisitLessOrEqual(predicate->Literals()[0]);
+            }
+            case Function::Type::IN:
+                return visitor->VisitIn(predicate->Literals());
+            case Function::Type::NOT_IN:
+                return visitor->VisitNotIn(predicate->Literals());
+            case Function::Type::STARTS_WITH: {
+                assert(predicate->Literals().size() == 1);
+                return visitor->VisitStartsWith(predicate->Literals()[0]);
+            }
+            case Function::Type::ENDS_WITH: {
+                assert(predicate->Literals().size() == 1);
+                return visitor->VisitEndsWith(predicate->Literals()[0]);
+            }
+            case Function::Type::CONTAINS: {
+                assert(predicate->Literals().size() == 1);
+                return visitor->VisitContains(predicate->Literals()[0]);
+            }
+            case Function::Type::LIKE: {
+                assert(predicate->Literals().size() == 1);
+                return visitor->VisitLike(predicate->Literals()[0]);
+            }
+            default:
+                return Status::Invalid("invalid " + predicate->GetFunction().ToString() +
+                                       " function in leaf predicate");
+        }
+    }
+
+ private:
+    static Result<std::optional<std::shared_ptr<Predicate>>> ReconstructPredicateWithPickedFields(
+        const std::shared_ptr<Predicate>& predicate,
+        const std::map<std::string, int32_t>& picked_field_name_to_idx);
+
+    static void SplitCompound(const Function::Type& type,
+                              const std::shared_ptr<Predicate>& predicate,
+                              std::vector<std::shared_ptr<Predicate>>* result);
+};
+
+}  // namespace paimon