---
title: "Nullable, relačné a JSON filtre — Query Builder for Laravel | Roundly"
description: "Filtrujte nullable stĺpce so sentinelom none, to-many relácie s negáciou cez whereDoesntHave a JSON polia podľa členstva."
url: https://roundly-consulting.com/sk/open-source/navody/query-builder-for-laravel/nullable-a-relacne-filtre
language: sk
---

[Všetky balíky](https://roundly-consulting.com/sk/open-source.md)

[Query Builder for Laravel](https://roundly-consulting.com/sk/open-source/navody/query-builder-for-laravel.md)

# Nullable, relačné a JSON filtre

Tri konštruktory odpovedajú na otázky, ktoré samotná hodnota nevyjadrí: „nemá hodnotu“, „súvisí s“ a „má tento tag“. Každý podporuje is a negáciu not.

## Nullable stĺpce — nullable()

Nullable stĺpec potrebuje nullable(), nie operators(). „Riadky bez projektu“ a „riadky s projektom“ sa samotnou hodnotou vyjadriť nedajú — prázdne filter\[project\]= sa nelíši od chýbajúceho filtra — preto nullable() rezervuje sentinel (predvolene none) a číta aj jeho negáciu:

```php
use RoundlyConsulting\QueryBuilder\Enums\FilterValueShape;

->allowedFilters(
    AllowedFilter::nullable('project', 'project_id', FilterValueShape::Uuid),
)

// ?filter[project]=none            → project_id IS NULL
// ?filter[project]=not:none        → project_id IS NOT NULL
// ?filter[project]=<uuid>          → project_id = <uuid>
// ?filter[project]=not:<uuid>      → project_id != <uuid>, or project_id IS NULL
// ?filter[project]=none,<uuid>     → project_id IS NULL, or project_id = <uuid>
// ?filter[project]=not:none,<uuid> → project_id IS NOT NULL and != <uuid>
```

Signatúra: nullable(string $name, ?string $internalName = null, FilterValueShape $shape = FilterValueShape::Text, array $operators = \[RequestedOperator::Not\], string $sentinel = FilterSentinel::NONE). Negácia skutočnej hodnoty zahŕňa aj nenastavené riadky — „nie tento projekt“ pokrýva aj riadky bez projektu.

Sentinel je predvolená hodnota, nie rezervácia. Ak stĺpec legitímne ukladá reťazec none, odovzdajte vlastný:

```php
AllowedFilter::nullable('assignee', 'assignee_id', FilterValueShape::Id, sentinel: 'unassigned'),

// ?filter[assignee]=unassigned → assignee_id IS NULL
```

## Relácie — relation()

relation() porovnáva cez reláciu: whereHas pri zhode, whereDoesntHave pri negácii — nikdy negované whereHas, ktoré ponechá presne tie riadky, ktoré má vylúčiť (riadok s dvoma štítkami podmienku splní cez ten druhý). Druhý argument je relácia, tretí plne kvalifikovaný stĺpec v nej:

```php
use RoundlyConsulting\QueryBuilder\Enums\FilterValueShape;
use RoundlyConsulting\QueryBuilder\Support\FilterSentinel;

->allowedFilters(
    AllowedFilter::relation('label', 'labels', 'labels.id', FilterValueShape::Uuid),
    AllowedFilter::relation('department', 'departments', 'departments.id', FilterValueShape::Id, sentinel: FilterSentinel::NONE),
)

// ?filter[label]=<id>               → whereHas('labels', labels.id IN (<id>))
// ?filter[label]=not:<id>           → whereDoesntHave('labels', labels.id IN (<id>))
// ?filter[department]=none          → no related departments at all
// ?filter[department]=not:none      → at least one related department
// ?filter[department]=none,<id>     → no department, or related to <id>
// ?filter[department]=not:none,<id> → has a department, and not <id>
```

Signatúra: relation(string $name, string $relation, string $column, FilterValueShape $shape = FilterValueShape::Text, array $operators = \[RequestedOperator::Not\], ?string $sentinel = null). Sentinel je predvolene vypnutý — odovzdajte ho tam, kde je „bez akejkoľvek väzby“ otázka, ktorú zoznam kladie.

## JSON polia — jsonContains()

jsonContains() hľadá členstvo v JSON poli, napríklad v stĺpci tags, cez natívnu JSON podporu databázového drivera (whereJsonContains). exact() by porovnal celý dokument a partial() by našiel release aj vo vnútri pre-release:

```php
use RoundlyConsulting\QueryBuilder\Enums\FilterValueShape;

->allowedFilters(
    AllowedFilter::jsonContains('tag', 'tags'),
    AllowedFilter::jsonContains('label_ids', shape: FilterValueShape::Id),
)

// ?filter[tag]=release          → tags contains "release"
// ?filter[tag]=release,docs     → tagged release OR docs
// ?filter[tag]=not:release      → not tagged release (rows with NULL tags included)
// ?filter[tag]=not:release,docs → tagged neither
// ?filter[label_ids]=5          → label_ids contains the number 5, so [5, 7] matches
// ?filter[label_ids]=not:5      → excludes [5, 7]
```

Signatúra: jsonContains(string $name, ?string $internalName = null, array $operators = \[RequestedOperator::Not\], FilterValueShape $shape = FilterValueShape::Text). Viac hodnôt sa spája cez OR („ktorékoľvek z týchto“), ich negácia cez AND („žiadne z týchto“).

Členstvo v JSON poli je na každom engine typovo striktné — text „5“ nie je číslo 5 — preto pri prvkoch, ktoré nie sú text, deklarujte ich tvar. FilterValueShape::Id viaže hodnoty ako celé čísla (pole id, napríklad \[5, 7\]) a Boolean ako booleany; predvolený Text, napríklad pre stĺpec tags, a Uuid viažu text. Hodnota, ktorá tvaru nezodpovedá, nenájde nič a jej negácia nevylúči nič.

## Podporované operátory

Tieto tri filtre odpovedajú presne na dve otázky — „je jedným z týchto“ a „nie je žiadnym z týchto“ — preto prijímajú len RequestedOperator::Is a RequestedOperator::Not, pričom is sa dá pomenovať vždy. Deklarovanie čohokoľvek iného (gte, contains, …) vyhodí UnsupportedOperator už pri vytvorení filtra: ide o chybu vývojára zachytenú pri deklarácii, nie o chybu requestu.

## Prejavte lásku k open source

Tento balík je zadarmo pod licenciou MIT. Ak vám šetrí čas, jednorazový príspevok alebo členstvo na Patreone nám pomôže ho ďalej udržiavať, testovať a dokumentovať.

[Ďalšie spôsoby podpory vrátane kryptomien](https://roundly-consulting.com/sk/podporte-nas.md)

Odoslaním daru súhlasíte s našimi [podmienkami prijímania darov](https://roundly-consulting.com/sk/podmienky-darov.md).

[Podporte našu open-source prácu (otvorí sa v novej karte)](https://donate.stripe.com/dRmeVe8FX5PF1Qd9pXcEw00) [Pridajte sa k nám na Patreone (otvorí sa v novej karte)](https://www.patreon.com/cw/roundly)

## Chcete to zabudovať do svojho produktu?

Naše balíky integrujeme do zákazkových Laravel a AI riešení. Napíšte nám, na čom pracujete, a ozveme sa do 48 hodín.

[Ponuka do 48 hodín](https://roundly-consulting.com/sk/kontakt.md) [Prezrieť všetky balíky](https://roundly-consulting.com/sk/open-source/navody/query-builder-for-laravel.md)