Sintassi di $filter OData in Ricerca di intelligenza artificiale di Azure

  • Articolo

In Ricerca di intelligenza artificiale di Azure il parametro $filter specifica criteri di inclusione o esclusione per la restituzione delle corrispondenze nei risultati della ricerca. Questo articolo descrive la sintassi OData di $filter e fornisce esempi.

La costruzione e le costanti dei percorsi di campo sono descritte nella panoramica del linguaggio OData in Ricerca di intelligenza artificiale di Azure. Per altre informazioni sugli scenari di filtro, vedere Filtri in Ricerca di intelligenza artificiale di Azure.

Sintassi

Un filtro nel linguaggio OData è un'espressione booleana, che a sua volta può essere uno dei diversi tipi di espressione, come illustrato dal seguente modulo EBNF (Extended Backus-Naur):

boolean_expression ::=
    collection_filter_expression
    | logical_expression
    | comparison_expression
    | boolean_literal
    | boolean_function_call
    | '(' boolean_expression ')'
    | variable

/* This can be a range variable in the case of a lambda, or a field path. */
variable ::= identifier | field_path

È disponibile anche un diagramma di sintassi interattivo:

Diagramma della sintassi OData per Ricerca di intelligenza artificiale di Azure

Nota

Vedere Informazioni di riferimento sulla sintassi delle espressioni OData per Ricerca di intelligenza artificiale di Azure per l'EBNF completo.

I tipi di espressioni booleane includono:

Precedenza dell'operatore nei filtri

Se si scrive un'espressione di filtro senza parentesi intorno alle relative espressioni secondarie, Ricerca intelligenza artificiale di Azure la valuterà in base a un set di regole di precedenza dell'operatore. Queste regole si basano su quali operatori vengono usati per combinare le sottoespressione. Nella tabella seguente sono elencati i gruppi di operatori in ordine dalla precedenza più alta alla più bassa:

Raggruppa Operatore/i
Operatori logici not
Operatori di confronto eq, ne, gt, lt, gele
Operatori logici and
Operatori logici or

Un operatore superiore nella tabella precedente verrà "associato più strettamente" ai relativi operandi rispetto ad altri operatori. Ad esempio, and è di precedenza maggiore rispetto ora e gli operatori di confronto hanno una precedenza maggiore rispetto a uno di essi, quindi le due espressioni seguenti sono equivalenti:

    Rating gt 0 and Rating lt 3 or Rating gt 7 and Rating lt 10
    ((Rating gt 0) and (Rating lt 3)) or ((Rating gt 7) and (Rating lt 10))

L'operatore not ha la precedenza più alta di tutti, anche superiore agli operatori di confronto. Ecco perché se si prova a scrivere un filtro simile al seguente:

    not Rating gt 5

Verrà visualizzato questo messaggio di errore:

    Invalid expression: A unary operator with an incompatible type was detected. Found operand type 'Edm.Int32' for operator kind 'Not'.

Questo errore si verifica perché l'operatore è associato solo al Rating campo , che è di tipo Edm.Int32e non all'intera espressione di confronto. La correzione consiste nell'inserire l'operando tra not parentesi:

    not (Rating gt 5)

Limitazioni relative alle dimensioni dei filtri

Esistono limiti alle dimensioni e alla complessità delle espressioni di filtro che è possibile inviare a Ricerca di intelligenza artificiale di Azure. I limiti si basano approssimativamente sul numero di clausole nell'espressione filtro. Una buona linea guida è che, se si dispone di centinaia di clausole, si rischia di superare il limite. È consigliabile progettare l'applicazione in modo che non generi filtri di dimensioni non associate.

Suggerimento

L'uso della search.in funzione invece di lunghe disgiunzioni di confronti di uguaglianza può aiutare a evitare il limite della clausola di filtro, poiché una chiamata di funzione conta come una singola clausola.

Esempi

Trova tutti gli alberghi con almeno una camera con una tariffa di base inferiore a $ 200 che sono valutati a o superiore a 4:

    $filter=Rooms/any(room: room/BaseRate lt 200.0) and Rating ge 4

Trova tutti gli hotel diversi da "Sea View Motel" che sono stati rinnovati dal 2010:

    $filter=HotelName ne 'Sea View Motel' and LastRenovationDate ge 2010-01-01T00:00:00Z

Trova tutti gli hotel ristrutturati nel 2010 o versioni successive. Il valore letterale datetime include informazioni sul fuso orario per l'ora solare del Pacifico:

    $filter=LastRenovationDate ge 2010-01-01T00:00:00-08:00

Trova tutti gli hotel che hanno parcheggio incluso e dove tutte le camere sono non fumabili:

    $filter=ParkingIncluded and Rooms/all(room: not room/SmokingAllowed)

OPPURE

    $filter=ParkingIncluded eq true and Rooms/all(room: room/SmokingAllowed eq false)

Trovare tutti gli alberghi di lusso o con parcheggio incluso e di categoria 5 o superiore:

    $filter=(Category eq 'Luxury' or ParkingIncluded eq true) and Rating eq 5

Trovare tutti gli alberghi con il tag "wifi" in almeno una camera (dove ogni camera ha tag archiviati in un Collection(Edm.String) campo):

    $filter=Rooms/any(room: room/Tags/any(tag: tag eq 'wifi'))

Trova tutti gli hotel con qualsiasi camera:

    $filter=Rooms/any()

Trova tutti gli hotel che non hanno camere:

    $filter=not Rooms/any()

Trovare tutti gli hotel entro 10 chilometri da un punto di riferimento specificato (dove Location è un campo di tipo Edm.GeographyPoint):

    $filter=geo.distance(Location, geography'POINT(-122.131577 47.678581)') le 10

Trovare tutti gli hotel all'interno di un determinato viewport descritto come poligono (dove Location è un campo di tipo Edm.GeographyPoint). Il poligono deve essere chiuso, ovvero il primo e l'ultimo set di punti devono essere uguali. Inoltre, i punti devono essere elencati in ordine antiorario.

    $filter=geo.intersects(Location, geography'POLYGON((-122.031577 47.578581, -122.031577 47.678581, -122.131577 47.678581, -122.031577 47.578581))')

Trovare tutti gli hotel in cui il campo "Descrizione" è null. Il campo sarà Null se non è mai stato impostato o se è stato impostato in modo esplicito su Null:

    $filter=Description eq null

Trova tutti gli hotel con nome uguale a "Sea View motel" o "Budget hotel". Queste frasi contengono spazi e lo spazio è un delimitatore predefinito. È possibile specificare un delimitatore alternativo tra virgolette singole come terzo parametro stringa:

    $filter=search.in(HotelName, 'Sea View motel,Budget hotel', ',')

Trovare tutti gli alberghi con nome uguale a "Sea View motel" o "Budget hotel" separati da '|':

    $filter=search.in(HotelName, 'Sea View motel|Budget hotel', '|')

Trova tutti gli alberghi in cui tutte le camere hanno il tag 'wifi' o 'tub':

    $filter=Rooms/any(room: room/Tags/any(tag: search.in(tag, 'wifi, tub')))

Trovare una corrispondenza sulle frasi all'interno di una raccolta, ad esempio "asciugamani riscaldati" o "asciugamani riscaldati" inclusi nei tag.

    $filter=Rooms/any(room: room/Tags/any(tag: search.in(tag, 'heated towel racks,hairdryer included', ','))

Trovare documenti con la parola "waterfront". Questa query di filtro è identica a una richiesta di ricerca con search=waterfront.

    $filter=search.ismatchscoring('waterfront')

Trovare i documenti con la parola "hostel" e classificazione 4 o superiore oppure i documenti con la parola "motel" e classificazione 5. Questa richiesta non può essere espressa senza la search.ismatchscoring funzione perché combina la ricerca full-text con operazioni di filtro tramite or.

    $filter=search.ismatchscoring('hostel') and rating ge 4 or search.ismatchscoring('motel') and rating eq 5

Trovare i documenti senza la parola "luxury".

    $filter=not search.ismatch('luxury')

Trovare i documenti con la frase "ocean view" o classificazione 5. La query search.ismatchscoring verrà eseguita solo sui campi HotelName e Description. I documenti che corrispondono solo alla seconda clausola della disgiunzione verranno restituiti anche - hotel con Rating uguale a 5. Tali documenti verranno restituiti con un punteggio uguale a zero per chiarire che non corrispondono ad alcuna delle parti con punteggio dell'espressione.

    $filter=search.ismatchscoring('"ocean view"', 'Description,HotelName') or Rating eq 5

Trova hotel dove i termini "hotel" e "aeroporto" non sono più di cinque parole a parte nella descrizione, e dove tutte le camere sono non fumate. Questa query usa il linguaggio di query Lucene completo.

    $filter=search.ismatch('"hotel airport"~5', 'Description', 'full', 'any') and not Rooms/any(room: room/SmokingAllowed)

Trovare documenti con una parola che inizia con le lettere "lux" nel campo Descrizione. Questa query usa la ricerca del prefisso in combinazione con search.ismatch.

    $filter=search.ismatch('lux*', 'Description')

Passaggi successivi