Sintassi di $filter OData in Ricerca cognitiva di Azure

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

Le costanti e la costruzione dei percorsi di campo sono descritte nella panoramica del linguaggio OData in Ricerca cognitiva di Azure. Per altre informazioni sugli scenari di filtro, vedere Filtri in Ricerca cognitiva 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 EBNF (Extended Backus-Naur Form):

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:

I tipi di espressioni booleane includono:

  • Espressioni di filtro di raccolta che usano any o all. Questi criteri applicano criteri di filtro ai campi della raccolta. Per altre informazioni, vedere Operatori di raccolta OData in Ricerca cognitiva di Azure.
  • Espressioni logiche che combinano altre espressioni booleane usando gli operatori and, ore not. Per altre informazioni, vedere Operatori logici OData in Ricerca cognitiva di Azure.
  • Espressioni di confronto, che confrontano campi o variabili di intervallo con valori costanti usando gli operatori eq, , neltgt, ge, e .le Per altre informazioni, vedere Operatori di confronto OData in Ricerca cognitiva di Azure. Le espressioni di confronto vengono usate anche per confrontare le distanze tra le coordinate geografiche spaziali usando la geo.distance funzione . Per altre informazioni, vedere Funzioni geografiche OData in Ricerca cognitiva di Azure.
  • Valori letterali true booleani e false. Queste costanti possono essere utili a volte quando si generano filtri a livello di codice, ma in caso contrario non tendono a essere usati in pratica.
  • Chiamate a funzioni booleane, tra cui:
  • Percorsi di campo o variabili di intervallo di tipo Edm.Boolean. Ad esempio, se l'indice ha un campo booleano denominato IsEnabled e si desidera restituire tutti i documenti in cui questo campo è true, l'espressione di filtro può essere solo il nome IsEnabled.
  • Espressioni booleane tra parentesi. L'uso delle parentesi può essere utile per determinare in modo esplicito l'ordine delle operazioni in un filtro. Per altre informazioni sulla precedenza predefinita degli operatori OData, vedere la sezione successiva.

Precedenza dell'operatore nei filtri

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

Raggruppare Operatori
Operatori logici not
Operatori di confronto eq, ne, gt, lt, ge, le
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 di ore 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 , 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 cognitiva 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 anziché delle lunghe disgiunzioni dei confronti di uguaglianza può aiutare a evitare il limite della clausola di filtro, poiché una chiamata di funzione viene conteggiato come singola clausola.

Esempio

Trova tutti gli alberghi con almeno una camera con una tariffa di base inferiore a $ 200 che sono classificati 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 rinnovati 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 fumatori:

    $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 hotel 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 tutte le camere:

    $filter=Rooms/any()

Trova tutti gli hotel che non dispongono di camere:

    $filter=not Rooms/any()

Trovare tutti gli hotel entro 10 chilometri da un determinato punto di riferimento (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', ',')

Trova tutti gli hotel con nome uguale a 'Sea View motel' o 'Budget hotel' separato da '|'):

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

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

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

Trova una corrispondenza sulle frasi all'interno di una raccolta, ad esempio "rack asciugamani riscaldati" o "incluso" in 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 funzione perché combina la search.ismatchscoring ricerca full-text con le operazioni di filtro usando 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 punteggio uguale a zero per chiarire che non corrispondono a nessuna delle parti con punteggio dell'espressione.

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

Trovare hotel dove i termini "hotel" e "aeroporto" non sono più di cinque parole a parte nella descrizione, e dove tutte le camere sono non-fumatori. 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