Hosmel Quintana
Introduction
Installation
Configuration
Basic usage
Defining a Search
Fields and Columns
Operators and Values
Text and Wildcards
Free-Text Terms
Complements and Nullable Columns
Dates and Time Zones
JSON Columns
Relations
Aggregates
Scopes and Predicates
Full-Text Search
Directives and Sorting
Field Authorization
Validation Errors
Advanced usage
Custom Resolvers
Form Request Validation
View on GitHub

Free-Text Terms

Search several text and typed fields at once with values that have no field name.

A free-text term is a value without a field name, such as coffee in coffee status:open. The core calls these bare terms. Each one searches the fields you list in terms().

Choose term targets

Pass public field names to terms():

php
use HosmelQ\SearchSyntaxParser\Laravel\Field;
use HosmelQ\SearchSyntaxParser\Laravel\Search;

$search = Search::make()->fields([
    Field::string('name'),
    Field::string('description')->nullable(),
    Field::integer('quantity')->nullable(),
    Field::numeric('rating')->nullable(),
    Field::uuid('identifier', 'uuid')->nullable(),
])->terms(['name', 'description', 'quantity', 'rating', 'identifier']);

Every name must exist in fields(), even for denied fields and searches without free-text terms. Unknown names, dates, dynamic field patterns, and directives throw InvalidArgumentException. Denied fields are skipped.

Match text and typed values

A term matches when any eligible target matches. Ordinary text fields use contains matching, even if their fielded mode is exact or prefix. Quoted terms search a contiguous phrase. Full-text fields search words or quoted phrases instead.

Separate terms use AND. red coffee requires both terms somewhere in the configured fields; they may match different targets.

Other field types participate only when the core's tryCast() accepts the candidate. 10 can match quantity 10; coffee skips integer, numeric, and UUID targets. Storage conversions run after casting, so scaled decimal values work as terms too.

Rejected candidates never reach SQL. Valid numeric candidates bind with the required SQL type, including values outside an integer column's range or fractional scaled values. Numeric term fields must target numeric storage on PostgreSQL.

Use wildcards

A free-text wildcard compiles to a literal TextPattern on ordinary text fields; the SQL resolver renders it with toLike(). Ana* matches a whole value starting with Ana. It does not match Ana in the middle of a value. Full-text targets use a prefix on the last extracted word.

Each target must accept the pattern under its own wildcard and minimum-length rules. Fields with withoutWildcards(), map(), or scale() are skipped. Leading wildcard terms are disabled; use a fielded pattern with allowLeadingWildcards() when needed.

Quoted "Ana*" searches for a literal asterisk on ordinary text targets. Full-text targets treat the asterisk as punctuation and search the word Ana without a prefix operator.

Search related or JSON values

Relation fields search eligible related rows through existence subqueries. JSON array fields match any correctly typed element. Both keep their usual typed comparisons and complement rules.

Negate a term

A negative term requires every eligible field to miss. Nullable fields contribute NULL-aware complements, and relation targets include records without matching related rows.

If no target accepts a term, it matches no rows. Its negation matches every row. This also applies when no term targets are configured.

Text and WildcardsComplements and Nullable Columns