Filter-specificaties

Een filter-specificatie is een expressie waarmee je documenten selecteert. Je gebruikt hem in de Data REST API als filter-parameter bij het ophalen van een lijst, en als filter in de body van de query- en aggregate-endpoints.

De filter-parameter accepteert een expressie met de volgende structuur:

<veldpad> <operator> <waarde>

Combineer met AND / OR en haakjes. Voorbeeld:

filter=(is_paid_visit EQ false AND license_plate STRSTART "AB") OR amount GT 100

Velden

Operatoren

Operator Tekstvariant Werkt op Betekenis
== EQ alle types gelijk
!= NEQ alle types niet gelijk
> GT nummer, datum groter dan
< LT nummer, datum kleiner dan
>= GEQ nummer, datum groter dan of gelijk
<= LEQ nummer, datum kleiner dan of gelijk
& BAND int bitwise AND
| BOR int bitwise OR
^ BXOR int bitwise XOR
IN alle types waarde zit in array
NIN alle types waarde zit niet in array
BETWEEN nummer, datum tussen twee waarden (inclusief)
STRCON string, nummer bevat substring (case-insensitive)
STRSTART string, nummer begint met substring (case-insensitive)
STREND string, nummer eindigt op substring (case-insensitive)
STREQ string, nummer string-gelijkheid, case-insensitive
ISNULL alle types veld is leeg/null
ISNOTNULL alle types veld is niet null

ISNULL en ISNOTNULL worden geschreven zonder waarde, bijv. filter=editedDate ISNULL. In plaats van ISNULL kan je ook == null (of EQ null) gebruiken, en vergelijkbaar is mogelijk met ISNOTNULL.

Waardes

Booleaanse combinaties

Voorbeelden

is_paid_visit EQ false
license_plate STRSTART "AB"
editedDate GT 1715000000000
status IN ["Open","Pending"]
amount BETWEEN [100, 200]
editedDate ISNOTNULL
(branch EQ "A" OR branch EQ "B") AND is_paid EQ true

Functies

Naast een vaste waarde kun je aan de rechterkant van een vergelijking ook een functie gebruiken. De functie wordt door de server geëvalueerd op het moment van uitvoeren, zodat je bijvoorbeeld kunt filteren op "vandaag" of op gegevens van de ingelogde gebruiker.

Tijdsfuncties geven het begin (middernacht) van een dag terug, als UNIX-epoch in milliseconden, berekend in een bepaalde tijdzone. timezone_id is een IANA-tijdzone-identifier, bijvoorbeeld "Europe/Amsterdam", "Europe/London" of "America/New_York". Laat je timezone_id weg, dan wordt de primaire tijdzone van de applicatie gebruikt.

Functie Beschrijving Voorbeeld
start_of_today([timezone_id]) Begin van vandaag editedDate GEQ start_of_today()
start_of_day(relative_day[, timezone_id]) Begin van een dag relatief aan vandaag (0 = vandaag, -1 = gisteren, 1 = morgen) createdDate GEQ start_of_day(-7)
start_of_latest(day_of_week[, timezone_id]) Begin van de meest recente keer dat de weekdag voorkwam (mon t/m sun, niet hoofdlettergevoelig) completionDate GEQ start_of_latest("mon")

Gebruikersfuncties — lezen gegevens van de ingelogde gebruiker en vereisen dus authenticatie. Zonder ingelogde gebruiker evalueren ze tot een constante false en matchen ze niets.

Functie Beschrijving Voorbeeld
get_user_field(path[, role_name]) Veld uit het rolprofiel van de ingelogde gebruiker. path is een puntgescheiden pad (bijv. "location.entityId"). Bij een pad dat door een array loopt worden de waarden van alle elementen verzameld. Zonder role_name wordt het profiel van de huidige rol gelezen. location.entityId EQ get_user_field("location.entityId")
get_user_meta(field) Metadata van de ingelogde gebruiker. field is een van id, status, firstName, lastName of lastLogin. createdByUserId EQ get_user_meta("id")

Voorbeelden:

editedDate GEQ start_of_today()
createdDate GEQ start_of_day(-1, "Europe/Amsterdam")
assignee EQ get_user_meta("id")
entityId IN get_user_field("locaties.entityId")
title EQ get_user_meta("firstName")
priority GEQ get_user_meta("lastLogin")

Functies kunnen alleen worden gecombineerd met EQ, NEQ, GT, LT, GEQ, LEQ, IN en NIN. Geeft de functie meerdere waarden (bijv. een pad door een array), dan is IN of NIN verplicht. IN op een arrayveld matcht bij overlap: het is genoeg als één element van het veld in de lijst zit — niet alle waarden hoeven voor te komen.