Class QueryConstraint

java.lang.Object
io.fluxzero.common.api.search.constraints.PathConstraint
io.fluxzero.common.api.search.constraints.QueryConstraint
All Implemented Interfaces:
Constraint
public class QueryConstraint extends PathConstraint
A Constraint that parses a human-friendly query string into a structured tree of constraints.

This class allows users to write intuitive search strings like: 

  "error & (critical | urgent) & !resolved"
  ""exact phrase" | partial* & !excluded"

The query string supports:

  • Terms: space-separated words, optionally with wildcards (*).
  • Exact phrases: quoted strings (e.g., "full text").
  • Operators: & (AND), | (OR), ! (NOT), and parentheses for grouping.
  • Lookahead behavior: Controlled via lookAheadForAllTerms to mimic user-friendly search behavior.

Wildcards:

  • A trailing * enables prefix-matching (e.g., hat* matches hatter).
  • A leading * enables postfix-matching (e.g., *hat matches chat).
  • Both allows infix-matching (e.g., *hat* matches groupchatting).

Usage Examples

// Match documents containing both "order" and "cancel"
QueryConstraint.query("order cancel");

// Match documents with "error" or "failure"
QueryConstraint.query("error | failure");

// Match documents where "payment" appears but not "test"
QueryConstraint.query("payment !test");

// Match documents containing a phrase
QueryConstraint.query("\"order received\"");

If a lookAheadForAllTerms flag is set to true, then every term is treated as a look-ahead match (e.g., "chat" will match "chatbot", "chatter", etc.). The query is applied over the configured document paths, or across all paths if none are set.

Internally, the query is decomposed into a structure of ContainsConstraint, NotConstraint, AllConstraint, and AnyConstraint nodes that evaluate against document fields.

Performance Considerations

  • Queries using a prefix or postfix wildcard (e.g., user* or *name) are resolved at the data store level and typically fast.
  • Queries using both prefix and postfix wildcards (e.g., *log*) are not natively supported by the backend and require in-memory filtering, which can be slow for large result sets.
  • Similarly, prefix or postfix matches with terms shorter than 3 characters are also evaluated in-memory.
    Note: This limitation does not apply to complete word matches (i.e., without wildcards). For example, "to" as an exact term is efficient, but to* or *to are not.
  • When possible, prefer longer terms and structure queries to enable efficient execution via the underlying document store.
See Also:

  • Constructor Details

    • QueryConstraint

      public QueryConstraint()

  • Method Details

    • query

      public static Constraint query(String query, String... paths)
      Creates a QueryConstraint that parses and evaluates the given query string.
      Parameters:
      query - the human-readable query string
      paths - one or more document paths to apply the query to
      Returns:
      a parsed and decomposed constraint

    • query

      public static Constraint query(String query, boolean lookAheadForAllTerms, String... paths)
      Creates a QueryConstraint with optional lookahead behavior for terms.
      Parameters:
      query - the query string
      lookAheadForAllTerms - if true, all terms will behave like lookaheads (i.e., include trailing wildcard logic)
      paths - the paths to apply the query to

    • matches

      public boolean matches(Document document)
      Overrides Constraint.matches(Document) to evaluate a decomposed constraint tree. The parsing is done lazily and cached for reuse.
      Specified by:
      matches in interface Constraint
      Overrides:
      matches in class PathConstraint
      Parameters:
      document - the document to test
      Returns:
      true if the constraint matches the document

    • matches

      protected boolean matches(Document.Entry entry, Document document)
      Not supported directly on a single document entry. Throws UnsupportedOperationException.
      Specified by:
      matches in class PathConstraint
      Parameters:
      entry - the document entry to evaluate
      Returns:
      true if the entry satisfies the condition; false otherwise