Problemen met OData-verzamelingsfilters in Azure AI Zoeken oplossen

Als u wilt filteren op verzamelingsvelden in Azure AI Zoeken, kunt u deanyen all operators samen met lambda-expressies gebruiken. Een lambda-expressie is een subfilter dat wordt toegepast op elk element van een verzameling.

Niet elke functie van filterexpressies is beschikbaar in een lambda-expressie. Welke functies beschikbaar zijn, is afhankelijk van het gegevenstype van het verzamelingsveld dat u wilt filteren. Deze beperking kan resulteren in een fout als u een functie probeert te gebruiken in een lambda-expressie die niet wordt ondersteund in die context. Als u dergelijke fouten ondervindt tijdens het schrijven van een complex filter op verzamelingsvelden, helpt dit artikel u bij het oplossen van het probleem.

Veelvoorkomende verzamelingsfilterfouten

De volgende tabel bevat fouten die kunnen optreden bij het uitvoeren van een verzamelingsfilter. Deze fouten treden op wanneer u een functie gebruikt van filterexpressies die niet worden ondersteund in een lambda-expressie. Elke fout bevat enkele richtlijnen voor het herschrijven van uw filter om de fout te voorkomen. De tabel bevat ook een koppeling naar de relevante sectie van dit artikel met meer informatie over het voorkomen van die fout.

Geldige verzamelingsfilters schrijven

De regels voor het schrijven van geldige verzamelingsfilters verschillen voor elk gegevenstype. In de volgende secties worden de regels beschreven door voorbeelden weer te geven van welke filterfuncties worden ondersteund en welke niet:

• Regels voor het filteren van tekenreeksverzamelingen
• Regels voor het filteren van Booleaanse verzamelingen
• Regels voor het filteren van GeographyPoint-verzamelingen
• Regels voor het filteren van vergelijkbare verzamelingen
• Regels voor het filteren van complexe verzamelingen

Regels voor het filteren van tekenreeksverzamelingen

Binnen lambda-expressies voor string-collecties kunnen alleen de vergelijkingsoperatoren eq en ne worden gebruikt.

Het lichaam van een any kan alleen op gelijkheid testen, terwijl het lichaam van een all kan alleen op ongelijkheid testen.

Het is ook mogelijk om meerdere expressies te combineren in or de hoofdtekst van een any, en via and in de hoofdtekst van een all. Omdat de search.in functie gelijk is aan het combineren van gelijkheidscontroles met or, is het ook toegestaan in de hoofdtekst van een any. Omgekeerd is not search.in toegestaan in het lichaam van een all.

Deze expressies zijn bijvoorbeeld toegestaan:

• tags/any(t: t eq 'books')
• tags/any(t: search.in(t, 'books, games, toys'))
• tags/all(t: t ne 'books')
• tags/all(t: not (t eq 'books'))
• tags/all(t: not search.in(t, 'books, games, toys'))
• tags/any(t: t eq 'books' or t eq 'games')
• tags/all(t: t ne 'books' and not (t eq 'games'))

Hoewel deze expressies niet zijn toegestaan:

• tags/any(t: t ne 'books')
• tags/any(t: not search.in(t, 'books, games, toys'))
• tags/all(t: t eq 'books')
• tags/all(t: search.in(t, 'books, games, toys'))
• tags/any(t: t eq 'books' and t ne 'games')
• tags/all(t: t ne 'books' or not (t eq 'games'))

Regels voor het filteren van Booleaanse verzamelingen

Het type Edm.Boolean ondersteunt alleen de eq en ne operators. Daarom is het niet erg logisch om dergelijke componenten te combineren waarmee dezelfde bereikvariabele and/or wordt gecontroleerd, omdat dat altijd zou leiden tot tautologieën of tegenstrijdigheden.

Hier volgen enkele voorbeelden van filters voor Booleaanse verzamelingen die zijn toegestaan:

• flags/any(f: f)
• flags/all(f: f)
• flags/any(f: f eq true)
• flags/any(f: f ne true)
• flags/all(f: not f)
• flags/all(f: not (f eq true))

In tegenstelling tot tekenreeksverzamelingen hebben Booleaanse verzamelingen geen limieten voor welke operator kan worden gebruikt in welk type lambda-expressie. Beide eq en ne kunnen worden gebruikt in de hoofdtekst van any of all.

Expressies zoals de volgende zijn niet toegestaan voor Booleaanse verzamelingen:

• flags/any(f: f or not f)
• flags/any(f: f or f)
• flags/all(f: f and not f)
• flags/all(f: f and f eq true)

Regels voor het filteren van GeographyPoint-verzamelingen

Waarden van het type Edm.GeographyPoint in een verzameling kunnen niet rechtstreeks met elkaar worden vergeleken. In plaats daarvan moeten ze worden gebruikt als parameters voor de geo.distance en geo.intersects functies. De geo.distance functie moet op zijn beurt worden vergeleken met een afstandswaarde met behulp van een van de vergelijkingsoperatoren lt, leof gtge. Deze regels zijn ook van toepassing op niet-collection Edm.GeographyPoint-velden.

Net als tekenreeksverzamelingen hebben verzamelingen Edm.GeographyPoint enkele regels voor de manier waarop de georuimtelijke functies kunnen worden gebruikt en gecombineerd in de verschillende typen lambda-expressies:

• Welke vergelijkingsoperatoren u met de geo.distance functie kunt gebruiken, is afhankelijk van het type lambda-expressie. Voor any, kunt u alleen lt gebruiken of le. Voor all, kunt u alleen gt gebruiken of ge. U kunt expressies met betrekking tot geo.distance negatief maken, maar u moet de vergelijkingsoperator wijzigen (geo.distance(...) lt x wordt not (geo.distance(...) ge x) en geo.distance(...) le x wordt not (geo.distance(...) gt x)).
• In de hoofdtekst van een all, moet de geo.intersects functie worden ontkend. Omgekeerd mag in de hoofdtekst van een any de functie geo.intersects niet worden weggenomen.
• In de hoofdtekst van een any kunnen geo-ruimtelijke expressies worden gecombineerd met behulp van or. In de hoofdtekst van een all, kunnen dergelijke expressies worden gecombineerd met behulp van and.

De bovenstaande beperkingen bestaan om soortgelijke redenen als de beperking van gelijkheid/ongelijkheid voor stringverzamelingen. Zie Informatie over OData-verzamelingsfilters in Azure AI Zoeken voor meer informatie over deze redenen.

Hier volgen enkele voorbeelden van filters voor Edm.GeographyPoint verzamelingen die zijn toegestaan:

• locations/any(l: geo.distance(l, geography'POINT(-122 49)') lt 10)
• locations/any(l: not (geo.distance(l, geography'POINT(-122 49)') ge 10) or geo.intersects(l, geography'POLYGON((-122.031577 47.578581, -122.031577 47.678581, -122.131577 47.678581, -122.031577 47.578581))'))
• locations/all(l: geo.distance(l, geography'POINT(-122 49)') ge 10 and not geo.intersects(l, geography'POLYGON((-122.031577 47.578581, -122.031577 47.678581, -122.131577 47.678581, -122.031577 47.578581))'))

Expressies zoals de volgende zijn niet toegestaan voor Edm.GeographyPoint verzamelingen:

• locations/any(l: l eq geography'POINT(-122 49)')
• locations/any(l: not geo.intersects(l, geography'POLYGON((-122.031577 47.578581, -122.031577 47.678581, -122.131577 47.678581, -122.031577 47.578581))'))
• locations/all(l: geo.intersects(l, geography'POLYGON((-122.031577 47.578581, -122.031577 47.678581, -122.131577 47.678581, -122.031577 47.578581))'))
• locations/any(l: geo.distance(l, geography'POINT(-122 49)') gt 10)
• locations/all(l: geo.distance(l, geography'POINT(-122 49)') lt 10)
• locations/any(l: geo.distance(l, geography'POINT(-122 49)') lt 10 and geo.intersects(l, geography'POLYGON((-122.031577 47.578581, -122.031577 47.678581, -122.131577 47.678581, -122.031577 47.578581))'))
• locations/all(l: geo.distance(l, geography'POINT(-122 49)') le 10 or not geo.intersects(l, geography'POLYGON((-122.031577 47.578581, -122.031577 47.678581, -122.131577 47.678581, -122.031577 47.578581))'))

Regels voor het filteren van vergelijkbare verzamelingen

Deze sectie is van toepassing op alle volgende gegevenstypen:

• Collection(Edm.DateTimeOffset)
• Collection(Edm.Double)
• Collection(Edm.Int32)
• Collection(Edm.Int64)

Typen zoals Edm.Int32 en ondersteunen alle zes de vergelijkingsoperatoren: Edm.DateTimeOffset, , eqne, lt, , leen gtge . Lambda-expressies over verzamelingen van deze typen kunnen eenvoudige expressies bevatten met behulp van een van deze operators. Dit geldt voor zowel any als all. Deze filters zijn bijvoorbeeld toegestaan:

• ratings/any(r: r ne 5)
• dates/any(d: d gt 2017-08-24T00:00:00Z)
• not margins/all(m: m eq 3.5)

Er gelden echter beperkingen voor hoe dergelijke vergelijkingsexpressies kunnen worden gecombineerd tot complexere expressies binnen een lambda-expressie:

• Regels voor any:

  • Eenvoudige ongelijkheidsexpressies kunnen niet nuttig worden gecombineerd met andere expressies. Deze expressie is bijvoorbeeld toegestaan:

    • ratings/any(r: r ne 5)

    maar deze uitdrukking is dat niet:

    • ratings/any(r: r ne 5 and r gt 2)

    en hoewel deze expressie is toegestaan, is deze niet nuttig omdat de voorwaarden overlappen:

    • ratings/any(r: r ne 5 or r gt 7)

  • Eenvoudige vergelijkingsexpressies met betrekking tot eq, lt, le, gt of ge kunnen worden gecombineerd met and/or. Voorbeeld:

    • ratings/any(r: r gt 2 and r le 5)
    • ratings/any(r: r le 5 or r gt 7)

  • Vergelijkingsexpressies gecombineerd met and (combinaties) kunnen verder worden gecombineerd met behulp van or. Dit formulier staat bekend in Booleaanse logica als 'Disjunctive Normal Form' (DNF). Voorbeeld:

    • ratings/any(r: (r gt 2 and r le 5) or (r gt 7 and r lt 10))
• Regels voor all:

  • Eenvoudige gelijkheidsexpressies kunnen niet nuttig worden gecombineerd met andere expressies. Deze expressie is bijvoorbeeld toegestaan:

    • ratings/all(r: r eq 5)

    maar deze uitdrukking is dat niet:

    • ratings/all(r: r eq 5 or r le 2)

    en hoewel deze expressie is toegestaan, is deze niet nuttig omdat de voorwaarden overlappen:

    • ratings/all(r: r eq 5 and r le 7)

  • Eenvoudige vergelijkingsexpressies met betrekking tot ne, lt, le, gt of ge kunnen worden gecombineerd met and/or. Voorbeeld:

    • ratings/all(r: r gt 2 and r le 5)
    • ratings/all(r: r le 5 or r gt 7)

  • Vergelijkingsexpressies gecombineerd met or (disjunctions) kunnen verder worden gecombineerd met behulp van and. Dit staat in de Booleaanse logica bekend als 'Conjunctieve Normale Vorm' (CNF). Voorbeeld:

    • ratings/all(r: (r le 2 or r gt 5) and (r lt 7 or r ge 10))

Regels voor het filteren van complexe verzamelingen

Lambda-expressies boven complexe verzamelingen ondersteunen een veel flexibelere syntaxis dan lambda-expressies ten opzichte van verzamelingen primitieve typen. U kunt elke filterconstructie binnen een dergelijke lambda-expressie gebruiken die u buiten één kunt gebruiken, met slechts twee uitzonderingen.

Ten eerste worden de functies search.ismatch en search.ismatchscoring niet ondersteund in lambda-expressies. Zie Inzicht in OData-verzamelingsfilters in Azure AI Zoeken voor meer informatie.

Ten tweede is het niet toegestaan om te verwijzen naar velden die niet zijn gebonden aan de bereikvariabele (zogenaamde vrije variabelen). Denk bijvoorbeeld aan de volgende twee equivalente OData-filterexpressies:

1. stores/any(s: s/amenities/any(a: a eq 'parking')) and details/margin gt 0.5
2. stores/any(s: s/amenities/any(a: a eq 'parking' and details/margin gt 0.5))

De eerste expressie is toegestaan, terwijl het tweede formulier wordt geweigerd omdat details/margin deze niet is gebonden aan de bereikvariabele s.

Deze regel is ook van toepassing op expressies met variabelen die zijn gebonden in een buitenbereik. Dergelijke variabelen zijn gratis met betrekking tot het bereik waarin ze worden weergegeven. De eerste expressie is bijvoorbeeld toegestaan, terwijl de tweede equivalente expressie niet is toegestaan omdat s/name vrij is met betrekking tot het bereik van de bereikvariabele a.

1. stores/any(s: s/amenities/any(a: a eq 'parking') and s/name ne 'Flagship')
2. stores/any(s: s/amenities/any(a: a eq 'parking' and s/name ne 'Flagship'))

Deze beperking mag in de praktijk geen probleem zijn, omdat het altijd mogelijk is om filters te maken, zodat lambda-expressies alleen afhankelijke variabelen bevatten.

Spiekbriefje voor verzamelingsfilterregels

De volgende tabel bevat een overzicht van de regels voor het samenstellen van geldige filters voor elk gegevenstype van de verzameling.

Zie Geldige verzamelingsfilters schrijven voor voorbeelden van het maken van geldige filters voor elke case.

Als u vaak filters schrijft en het begrijpen van de regels vanuit de basisprincipes nuttiger voor u zou zijn dan ze alleen maar te onthouden, raadpleeg Inzicht in OData-verzamelingsfilters in Azure AI Zoeken.

Volgende stappen

• Informatie over OData-verzamelingsfilters in Azure AI Zoeken
• Filters in Azure AI Zoeken
• Overzicht van OData-expressietaal voor Azure AI Zoeken
• Naslaginformatie over de syntaxis van de OData-expressie voor Azure AI Zoeken
• Documenten zoeken (AZURE AI Search REST API)