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

Complements and Nullable Columns

Include NULL values in negated clauses, and complement fields that search several columns.

A negated clause matches every row the positive clause does not match. SQL leaves NULL out of both, so the package needs to know which columns can hold NULL.

Include missing values

NOT, a leading minus, and inequality select the complement of a matching set. Add nullable() when a stored column or expression may return NULL:

php
use HosmelQ\SearchSyntaxParser\Laravel\Field;

$field = Field::integer('quantity')->nullable();
QueryMatches
quantity:!=10Every quantity except 10, including NULL.
NOT quantity:>10Quantities at most 10, including NULL.
quantity:<=10Quantities at most 10, excluding NULL.
-quantity:*NULL quantities.

Without nullable(), ordinary SQL NULL behavior applies to comparisons. Explicit existence and absence checks always use IS NOT NULL and IS NULL. The package does not inspect your schema.

Search several nullable columns

A field with several columns matches when any target matches. Its complement requires every target to miss:

php
use HosmelQ\SearchSyntaxParser\Laravel\Field;

$field = Field::string('person')
    ->columns(['first_name', 'last_name'])
    ->nullable();

person:Ana matches either column. person:!=Ana excludes a row when either column matches, even when the other is NULL. -person:* requires both columns to be NULL.

The inequality uses a NULL-aware condition for each target:

sql
(first_name <> ? OR first_name IS NULL)
AND (last_name <> ? OR last_name IS NULL)

Each leaf is grouped. The core pushes NOT through boolean groups and removes double negation before compilation.

Other target types

JSON targets always include missing values in complements. Scalar complements also include JSON null and values of another type. Array complements mean no element matches, including empty arrays and non-array values.

Relation fields exclude matching related rows with whereDoesntHave(). Records without related rows, or with NULL targets, are included regardless of nullable().

Aggregate fields handle missing aggregate values automatically. Scope fields complement the primary keys selected by their predicates.

NULL-aware and negative conditions can match many rows and change index selection. Check query plans for the negative filters your application exposes.

Free-Text TermsDates and Time Zones