Categorie: api Bijgewerkt: 2026-04-23 odata rest-api filters query paginering

OData Filter Referentie

De Ultimo REST API ondersteunt OData versie 4 query opties voor het filteren, sorteren, selecteren en pagineren van data. Dit artikel beschrijft alle beschikbare operators, functies en query opties met concrete voorbeelden per use case.

Beschikbaarheid: Professional, Premium, Enterprise

Query opties overzichtbewerken

Optie Beschrijving Voorbeeld
$filter Filter resultaten op voorwaarden $filter=Status eq 2
$select Selecteer specifieke properties $select=Id,Description
$expand Voeg gerelateerde entiteiten toe $expand=Department
$orderby Sorteer resultaten $orderby=Description asc
$top Beperk aantal resultaten $top=10
$skip Sla records over $skip=20
$count Voeg totaal aantal toe aan response $count=true

$filter - Vergelijkingsoperatorenbewerken

Operator Beschrijving Voorbeeld
eq Gelijk aan $filter=Status eq 2
ne Niet gelijk aan $filter=Status ne 0
gt Groter dan $filter=Id gt '100'
ge Groter dan of gelijk aan $filter=Id ge '100'
lt Kleiner dan $filter=Id lt '200'
le Kleiner dan of gelijk aan $filter=Id le '200'
like Patroon match $filter=Description like '%pomp%'
in In een lijst van waarden $filter=Status in (1, 2, 3)

like operatorbewerken

De like operator ondersteunt twee wildcards:

$filter=Description like '%pomp%'        # Bevat "pomp"
$filter=Description like 'Koel%'         # Begint met "Koel"
$filter=Description like '%installatie'  # Eindigt met "installatie"
$filter=Id like '000__'                  # Id begint met "000" gevolgd door 2 tekens

in operatorbewerken

Filter op meerdere waarden tegelijk:

$filter=Status in (1, 2, 3)
$filter=Department/Id in ('01', '02', '03')

De in-operator heeft een praktische limiet van circa 100 waarden per filter. Voor grotere sets split de query in meerdere calls of gebruik een range-filter (Id ge 'X' and Id lt 'Y').

$filter - Logische operatorenbewerken

Operator Beschrijving Voorbeeld
and Logische EN $filter=Status eq 2 and Context eq 1
or Logische OF $filter=Status eq 2 or Status eq 3
not Logische NIET $filter=not (Status eq 0)
() Groepering $filter=(Status eq 2 or Status eq 3) and Context eq 1

Gecombineerde filtersbewerken

# Actieve equipment van afdeling 01
$filter=Status eq 2 and Department/Id eq '01'

# Jobs met status 1 of 2, van context Technical Service
$filter=(Status eq 1 or Status eq 2) and Context eq 1

# Equipment die NIET inactief is
$filter=not (Status eq 0)

Ondersteunde datatypesbewerken

Datatype Voorbeeld filter
Null $filter=Description eq null
Boolean $filter=IsActive eq true
Integer $filter=Status eq 2
Decimal $filter=Amount gt 100.50
String $filter=Id eq '00001'
Date $filter=InstallDate eq 2022-04-07
DateTimeOffset $filter=ModifiedOn gt 2025-01-01T00:00:00Z
TimeOfDay $filter=StartTime ge 08:00:00

Let op: Stringwaarden moeten tussen enkele aanhalingstekens staan. Numerieke waarden en datums niet.

Filteren op relatiesbewerken

Filter op gerelateerde entiteiten door /Id toe te voegen aan het attribuutpad:

# Equipment van afdeling 01
$filter=Department/Id eq '01'

# Jobs voor een specifiek equipment
$filter=Equipment/Id eq '00001'

# Equipment op een specifieke locatie
$filter=Site/Id eq 'HOOFD'

$select - Properties selecterenbewerken

Beperk de response tot specifieke properties:

GET .../object/Equipment?$select=Id,Description,Status

# Response bevat alleen:
# { "Id": "00001", "Description": "Koelinstallatie", "Status": 2 }

Meerdere properties scheiden met komma's:

$select=Id,Description,Status,InstallDate,Department

$select op relatie-properties vereist $expandbewerken

Een veelvoorkomende valkuil: om een property van een gerelateerde entiteit te selecteren (bijv. ProcessFunction/Id) moet die relatie eerst worden geëxpandeerd. Alleen $select met het slash-pad geeft een syntax-error.

# Werkt NIET — geeft SelectSyntaxError:
$select=Id,ProcessFunction/Id

# Werkt WEL:
$expand=ProcessFunction&$select=Id,ProcessFunction/Id

Dit is efficiënt voor grote analyses: de response bevat dan alleen de parent-ID zonder het volledige relatie-object.

$expand - Gerelateerde entiteitenbewerken

Voeg gerelateerde entiteiten toe aan de response. Maximaal 3 niveaus diep.

Basis expandbewerken

GET .../object/Equipment?$expand=Department,CostCenter

Geneste expandbewerken

GET .../object/Equipment?$expand=Department($expand=Site)

Expand met selectbewerken

GET .../object/Equipment?$expand=Department($select=Id,Description)

Expand met filterbewerken

GET .../object/Department('01')?$expand=Jobs($filter=Status eq 1)

$orderby - Sorterenbewerken

Sorteer resultaten oplopend (asc) of aflopend (desc):

# Oplopend op beschrijving (standaard)
$orderby=Description asc

# Aflopend op aanmaakdatum
$orderby=CreatedOn desc

# Meervoudige sortering
$orderby=Department asc,Description asc

$top en $skip - Pagineringbewerken

$top - Beperk resultatenbewerken

# Eerste 10 records
$top=10

$skip - Offsetbewerken

# Sla de eerste 20 records over
$skip=20

Combinatie voor pagineringbewerken

# Pagina 1 (records 1-25)
$top=25&$skip=0

# Pagina 2 (records 26-50)
$top=25&$skip=25

# Pagina 3 (records 51-75)
$top=25&$skip=50

Aanbeveling: Gebruik bij voorkeur de nextPageLink uit de server response in plaats van handmatige paginering met $top en $skip.

Praktische $top-limietbewerken

Voor entiteiten met beperkt aantal velden en met $select actief kan $top=1000 in één request slagen zonder nextPageLink. Voor zwaardere queries (veel $expand, grote payloads) legt de server eerder een lagere pagina-limiet op, ook als $top=1000 wordt meegegeven. Detecteer dit aan de aanwezigheid van nextPageLink in de response en volg die altijd.

Valkuil: handmatige keyset-paginatie op string-IDsbewerken

Een alternatief voor $skip is keyset-paginatie op het ID-veld:

# Eerste batch
$filter=Id ge ''&$orderby=Id asc&$top=100

# Volgende batch
$filter=Id gt '<laatste Id uit vorige batch>'&$orderby=Id asc&$top=100

Dit werkt correct voor numerieke IDs en voor strikt-alfabetische IDs met vaste lengte. Voor alfanumerieke IDs met variabele lengte kan dit records missen. Voorbeeld:

Id = '08LEID1'    — string-vergelijking: '08LEID1' < '08LEID10'
Id = '08LEID10'   — alfabetisch na '08LEID1', maar '08LEID2' zit daartussen

Als de eerste batch eindigt op 08LEID9 en de volgende start met Id gt '08LEID9', worden 08LEID10 tot 08LEID99 overgeslagen omdat ze lexicografisch vóór 08LEID9 komen. Altijd nextPageLink gebruiken; die hanteert server-side de correcte sortering.

$top - Beperk resultatenbewerken

# Eerste 10 records
$top=10

$skip - Offsetbewerken

# Sla de eerste 20 records over
$skip=20

Combinatie voor pagineringbewerken

# Pagina 1 (records 1-25)
$top=25&$skip=0

# Pagina 2 (records 26-50)
$top=25&$skip=25

# Pagina 3 (records 51-75)
$top=25&$skip=50

Aanbeveling: Gebruik bij voorkeur de nextPageLink uit de server response in plaats van handmatige paginering met $top en $skip.

$count - Totaal aantalbewerken

Voeg het totaal aantal records toe aan de response:

GET .../object/Equipment?$count=true

# Response bevat:
# { "count": 1542, "items": [...] }

Combineer met filters:

GET .../object/Equipment?$filter=Status eq 2&$count=true

Count-only pattern (efficiënt tellen)bewerken

Voor dashboards en KPI's heb je vaak alleen het aantal records nodig, niet de records zelf. De combinatie $top=0&$count=true geeft alleen de count terug zonder data:

GET .../object/Job?$filter=Status in (1, 2, 4)&$top=0&$count=true

# Response:
# { "count": 894, "items": [] }

Dit is significant goedkoper dan records ophalen en lokaal tellen, vooral bij grote datasets. Gebruik dit patroon voor alle aantallen-in-een-widget.

Voorbeelden per use casebewerken

Equipment managementbewerken

# Alle actieve equipment ophalen
GET .../object/Equipment?$filter=Status eq 2&$select=Id,Description,EquipmentType

# Equipment met vervallen onderhoudsdatum
GET .../object/Equipment?$filter=NextPmMaintenanceDate lt 2025-04-01&$orderby=NextPmMaintenanceDate asc

# Equipment zoeken op beschrijving
GET .../object/Equipment?$filter=Description like '%koeling%'

# Equipment per afdeling met type-informatie
GET .../object/Equipment?$filter=Department/Id eq '01'&$expand=EquipmentType($select=Id,Description)

Job managementbewerken

# Open jobs (status 1 = nieuw, 2 = in behandeling)
GET .../object/Job?$filter=Status in (1, 2)&$orderby=CreatedOn desc

# Jobs voor een specifiek equipment
GET .../object/Job?$filter=Equipment/Id eq '00001'&$select=Id,Description,Status

# Jobs aangemaakt in de afgelopen week
GET .../object/Job?$filter=CreatedOn ge 2025-03-28&$top=50

# Afgemelde jobs met equipment details
GET .../object/Job?$filter=Status eq 3&$expand=Equipment($select=Id,Description)

# Achterstallige jobs (TargetDate-valkuil: sluit null expliciet uit)
GET .../object/Job?$filter=Status in (1, 2, 4) and TargetDate lt 2026-04-23T00:00:00Z and TargetDate ne null

TargetDate-valkuil: niet elke open job heeft een TargetDate. Zonder and TargetDate ne null kunnen records zonder streefdatum — afhankelijk van de null-sort-order — onterecht als achterstallig worden geteld of juist worden gemist. Voeg altijd ne null toe bij overdue-filters om het filter robuust te maken. Dezelfde regel geldt voor andere datumvelden (ScheduledStartDate, ScheduledFinishDate) bij vergelijkbare queries.

Artikelen en voorraadbewerken

# Alle actieve artikelen
GET .../object/Article?$filter=Status eq 2&$select=Id,Description,StockLevel

# Artikelen met voorraad onder minimum
GET .../object/Article?$filter=StockLevel lt MinimumStockLevel

# Artikelen van een specifieke leverancier
GET .../object/Article?$filter=Vendor/Id eq 'LEV001'

Medewerkers en afdelingenbewerken

# Alle medewerkers van een afdeling
GET .../object/Employee?$filter=Department/Id eq '01'&$select=Id,Name,Email

# Alle afdelingen met hun medewerkers
GET .../object/Department?$expand=Employees($select=Id,Name)

# Zoek medewerker op naam
GET .../object/Employee?$filter=Name like '%Janssen%'

Speciale tekens in filtersbewerken

Aanhalingstekensbewerken

Enkele aanhalingstekens in stringwaarden moeten verdubbeld worden:

$filter=Description eq 'O''Brien'

URL encodingbewerken

Bepaalde tekens vereisen URL encoding:

Teken Encoded
Spatie %20 of +
< %3C
> %3E
% %25
& %26
" %22

Forward slashes in IDsbewerken

Forward slashes werken niet in ID-paden maar wel in filters:

# Werkt NIET:
GET .../object/Building('01/02')

# Werkt WEL:
GET .../object/Building?$filter=Id eq '01/02'

Combinatievoorbeeldenbewerken

Complexe querybewerken

GET .../object/Equipment
  ?$filter=Status eq 2 and Department/Id eq '01' and InstallDate ge 2020-01-01
  &$select=Id,Description,InstallDate,SerialNumber
  &$expand=Department($select=Description)
  &$orderby=InstallDate desc
  &$top=25
  &$count=true

Paginering met filtering en sorteringbewerken

# Eerste pagina
GET .../object/Job?$filter=Status eq 1&$orderby=CreatedOn desc&$top=50&$skip=0&$count=true

# Volgende pagina (gebruik bij voorkeur nextPageLink)
GET .../object/Job?$filter=Status eq 1&$orderby=CreatedOn desc&$top=50&$skip=50

Beperkingenbewerken

Gerelateerde artikelenbewerken

Brondatabewerken

Dit artikel is consultant-synthese. Voor ground-truth data over specifieke Ultimo-objecten gebruik de onderstaande tools.