Predicate

public indirect enum Predicate : Sendable

A recursive predicate tree that represents complex boolean logic for filtering documents.

Predicates can be combined with .and, .or, and .not to build arbitrary boolean expressions. Leaf predicates compare a document field against a value using operators such as equals, less-than, range, substring, and regex.

The predicate tree is evaluated bottom-up by QueryBuilder.evaluate(_:in:), which walks the tree recursively for each candidate document.

  • Matches documents where the field equals the given value. This is the most efficient predicate because it can be pushed down to an indexed lookup O(log n) via binary search when an index on the field exists.

    Declaration

    Swift

    case equal(String, any FieldValueConvertible)

  • Matches documents where the field differs from the given value. Always evaluated in memory — the index can only answer equality, not inequality, without a full scan.

    Declaration

    Swift

    case notEqual(String, any FieldValueConvertible)

  • Matches documents where the field is strictly less than the given value. Uses an indexed range scan (O(log n + k)) when an index on the field exists; falls back to in-memory filtering otherwise.

    Declaration

    Swift

    case lessThan(String, any FieldValueConvertible)

  • Matches documents where the field is less than or equal to the given value. Uses an indexed range scan when available.

    Declaration

    Swift

    case lessThanOrEqual(String, any FieldValueConvertible)

  • Matches documents where the field is strictly greater than the given value. Uses an indexed range scan when available.

    Declaration

    Swift

    case greaterThan(String, any FieldValueConvertible)

  • Matches documents where the field is greater than or equal to the given value. Uses an indexed range scan when available.

    Declaration

    Swift

    case greaterThanOrEqual(String, any FieldValueConvertible)

  • Matches documents where the field falls within the inclusive range [lower, upper]. Uses an indexed range scan when available. Both bounds are required and must be of compatible types.

    Declaration

    Swift

    case between(String, any FieldValueConvertible, any FieldValueConvertible)

  • Matches documents where the field is a member of the given set. When an index exists, each element is looked up individually and the results are merged (OR semantics). This avoids a full scan for small-to-medium IN lists; for large sets a full scan may be cheaper.

    Declaration

    Swift

    case inSet(String, [any FieldValueConvertible])

  • Matches documents where the field is not a member of the given set. Always evaluated in memory because the index stores only positive membership — exclusion requires scanning the posting list or filtering.

    Declaration

    Swift

    case notInSet(String, [any FieldValueConvertible])

  • Matches documents where the string field contains the given substring anywhere in its value. Comparison is case-sensitive and uses String.contains(_:). Always evaluated in memory — there is no substring index.

    Declaration

    Swift

    case contains(String, String)

  • Matches documents where the string field starts with the given prefix. Comparison is case-sensitive and uses String.hasPrefix(_:). Always evaluated in memory.

    Declaration

    Swift

    case startsWith(String, String)

  • Matches documents where the string field ends with the given suffix. Comparison is case-sensitive and uses String.hasSuffix(_:). Always evaluated in memory.

    Declaration

    Swift

    case endsWith(String, String)

  • Matches documents where the string field matches a SQL-style LIKE pattern. Supports % (any sequence of characters) and _ (any single character). The pattern is compiled into an NSRegularExpression at predicate-construction time (so the regex is built once, not once per document). Matching is case-insensitive. Always evaluated in memory.

    Note

    There is no escape character. To match a literal % or _, use a custom Predicate.glob or .equal instead.

    Declaration

    Swift

    case like(String, String, SafeRegex)

  • Matches documents where the string field matches a shell-style glob pattern. Supports * (any sequence), ? (any single character), and [...] (character class with optional negation via [!...]). The pattern is compiled into an NSRegularExpression at predicate-construction time. Matching is case-sensitive. Always evaluated in memory.

    Note

    The implementation converts the glob to a regex, so edge cases with path separators or special file-glob rules may not apply.

    Declaration

    Swift

    case glob(String, String, SafeRegex)

  • Matches documents where the given field is present (not null and not absent from the document). The field must exist at any depth reachable via dot-path notation. Always evaluated in memory.

    Declaration

    Swift

    case exists(String)

  • Matches documents where the given field is absent (null or missing from the document). Always evaluated in memory.

    Declaration

    Swift

    case notExists(String)

  • Matches documents that satisfy all child predicates (logical AND). Evaluation short-circuits on the first failure for performance.

    Declaration

    Swift

    case and([Predicate])

  • Matches documents that satisfy any child predicate (logical OR). Evaluation short-circuits on the first success for performance.

    Declaration

    Swift

    case or([Predicate])

  • Matches documents that do not satisfy the child predicate (logical NOT).

    Declaration

    Swift

    case not(Predicate)