OData-functie search.in in Azure AI Search
Een veelvoorkomend scenario in OData-filterexpressies is om te controleren of één veld in elk document gelijk is aan een van de vele mogelijke waarden. Zo implementeren sommige toepassingen beveiligingsbeperkingen , door een veld met een of meer principal-id's te controleren op basis van een lijst met principal-id's die de gebruiker de query uitgeeft. Een van de manieren om een query als deze te schrijven, is door de operatoren en or de eq volgende operatoren te gebruiken:
group_ids/any(g: g eq '123' or g eq '456' or g eq '789')
Er is echter een kortere manier om dit te schrijven, met behulp van de search.in functie:
group_ids/any(g: search.in(g, '123, 456, 789'))
Belangrijk
Naast korter en gemakkelijker leesbaar te zijn, biedt het gebruik search.in ook prestatievoordelen en voorkomt u bepaalde groottebeperkingen van filters wanneer er honderden of zelfs duizenden waarden in het filter moeten worden opgenomen. Daarom raden we u ten zeerste aan om in plaats van een complexere scheiding van gelijkheidsexpressies te gebruiken search.in .
Notitie
Versie 4.01 van de OData-standaard heeft onlangs de in operator geïntroduceerd, die vergelijkbaar gedrag heeft als de search.in functie in Azure AI Search. Azure AI Search biedt echter geen ondersteuning voor deze operator, dus u moet in plaats daarvan de search.in functie gebruiken.
Syntaxis
Het volgende EBNF (Extended Backus-Naur Form) definieert de grammatica van de search.in functie:
search_in_call ::=
'search.in(' variable ',' string_literal(',' string_literal)? ')'
Er is ook een interactief syntaxisdiagram beschikbaar:
Notitie
Zie naslaginformatie over de syntaxis van de OData-expressie voor Azure AI Search voor het volledige EBNF.
De search.in functie test of een bepaald tekenreeksveld of een bereikvariabele gelijk is aan een van een bepaalde lijst met waarden. Gelijkheid tussen de variabele en elke waarde in de lijst wordt op hoofdlettergevoelige wijze bepaald, op dezelfde manier als voor de eq operator. Daarom is een expressie vergelijkbaar met search.in(myfield, 'a, b, c')myfield eq 'a' or myfield eq 'b' or myfield eq 'c', behalve dat dit search.in veel betere prestaties oplevert.
Er zijn twee overbelastingen van de search.in functie:
search.in(variable, valueList)search.in(variable, valueList, delimiters)
De parameters worden gedefinieerd in de volgende tabel:
| Parameternaam | Type | Description |
|---|---|---|
variable |
Edm.String |
Een tekenreeksveldreferentie (of een bereikvariabele voor een tekenreeksverzamelingsveld in het geval dat search.in wordt gebruikt in een any of all expressie). |
valueList |
Edm.String |
Een tekenreeks met een door scheidingstekens gescheiden lijst met waarden die overeenkomen met de variable parameter. Als de delimiters parameter niet is opgegeven, zijn de standaardscheidingstekens spatie en komma. |
delimiters |
Edm.String |
Een tekenreeks waarbij elk teken wordt behandeld als scheidingsteken bij het parseren van de valueList parameter. De standaardwaarde van deze parameter is ' ,' dat alle waarden met spaties en/of komma's ertussen worden gescheiden. Als u andere scheidingstekens dan spaties en komma's wilt gebruiken omdat uw waarden deze tekens bevatten, kunt u alternatieve scheidingstekens opgeven, zoals '|' in deze parameter. |
Prestaties van search.in
Als u gebruikt search.in, kunt u een reactietijd van een sub seconde verwachten wanneer de tweede parameter een lijst met honderden of duizenden waarden bevat. Er is geen expliciete limiet voor het aantal items dat u kunt doorgeven search.in, hoewel u nog steeds beperkt bent door de maximale aanvraaggrootte. De latentie neemt echter toe naarmate het aantal waarden groeit.
Voorbeelden
Zoek alle hotels met een naam die gelijk is aan 'Sea View motel' of 'Budget hotel'. Zinnen bevatten spaties. Dit is een standaardscheidingsteken. U kunt een alternatief scheidingsteken tussen enkele aanhalingstekens opgeven als de derde tekenreeksparameter:
search.in(HotelName, 'Sea View motel,Budget hotel', ',')
Zoek alle hotels met een naam die gelijk is aan 'Sea View motel' of 'Budget hotel' gescheiden door |):
search.in(HotelName, 'Sea View motel|Budget hotel', '|')
Zoek alle hotels met kamers met het label 'wifi' of 'tub':
Rooms/any(room: room/Tags/any(tag: search.in(tag, 'wifi, tub')))
Zoek een overeenkomst op zinnen in een verzameling, zoals 'verwarmde handdoekrekken' of 'haardroger inbegrepen' in tags.
Rooms/any(room: room/Tags/any(tag: search.in(tag, 'heated towel racks,hairdryer included', ','))
Zoek alle hotels zonder het label 'motel' of 'cabin':
Tags/all(tag: not search.in(tag, 'motel, cabin'))