Funzioni geografiche spaziali OData in Ricerca di intelligenza artificiale di Azure e geo.distancegeo.intersects

  • Articolo

Ricerca di intelligenza artificiale di Azure supporta le query spaziali geografiche nelle espressioni di filtro OData tramite le geo.distance funzioni e geo.intersects . La geo.distance funzione restituisce la distanza in chilometri tra due punti, una variabile di campo o intervallo e una costante passata come parte del filtro. La geo.intersects funzione restituisce true se un punto specificato si trova all'interno di un determinato poligono, dove il punto è una variabile di campo o intervallo e il poligono viene specificato come costante passata come parte del filtro.

La geo.distance funzione può essere usata anche nel parametro $orderby per ordinare i risultati della ricerca in base alla distanza da un determinato punto. La sintassi per geo.distance in $orderby è la stessa che in $filter. Quando si usa geo.distance in $orderby, il campo a cui si applica deve essere di tipo Edm.GeographyPoint e deve anche essere ordinabile.

Nota

Quando si usa geo.distance nel parametro $orderby , il campo passato alla funzione deve contenere solo un singolo punto geografico. In altre parole, deve essere di tipo Edm.GeographyPoint e non Collection(Edm.GeographyPoint). Non è possibile ordinare i campi della raccolta in Ricerca di intelligenza artificiale di Azure.

Sintassi

Il seguente EBNF (Extended Backus-Naur Form) definisce la grammatica delle geo.distance funzioni e geo.intersects , nonché i valori geo-spaziali su cui operano:

geo_distance_call ::=
    'geo.distance(' variable ',' geo_point ')'
    | 'geo.distance(' geo_point ',' variable ')'

geo_point ::= "geography'POINT(" lon_lat ")'"

lon_lat ::= float_literal ' ' float_literal

geo_intersects_call ::=
    'geo.intersects(' variable ',' geo_polygon ')'

/* You need at least four points to form a polygon, where the first and
last points are the same. */
geo_polygon ::=
    "geography'POLYGON((" lon_lat ',' lon_lat ',' lon_lat ',' lon_lat_list "))'"

lon_lat_list ::= lon_lat(',' lon_lat)*

È 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.

geo.distance

La geo.distance funzione accetta due parametri di tipo Edm.GeographyPoint e restituisce un Edm.Double valore che corrisponde alla distanza tra di esse in chilometri. Ciò differisce da altri servizi che supportano operazioni geo-spaziali OData, che in genere restituiscono distanze in metri.

Uno dei parametri da deve geo.distance essere una costante del punto geografico e l'altro deve essere un percorso di campo (o una variabile di intervallo nel caso di un filtro che esegue l'iterazione su un campo di tipo Collection(Edm.GeographyPoint)). L'ordine di questi parametri non è importante.

La costante del punto geografico è nel formato geography'POINT(<longitude> <latitude>)', dove la longitudine e la latitudine sono costanti numeriche.

Nota

Quando si usa geo.distance in un filtro, è necessario confrontare la distanza restituita dalla funzione con una costante usando lt, le, gto ge. Gli operatori eq e ne non sono supportati quando si confrontano le distanze. Ad esempio, si tratta di un utilizzo corretto di geo.distance: $filter=geo.distance(location, geography'POINT(-122.131577 47.678581)') le 5.

geo.intersects

La geo.intersects funzione accetta una variabile di tipo Edm.GeographyPoint e una costante Edm.GeographyPolygon e restituisce un oggettotrueEdm.Boolean -- se il punto si trova all'interno dei limiti del poligono, false in caso contrario.

Il poligono è una superficie bidimensionale archiviata come sequenza di punti che definiscono un anello di delimitazione (vedere gli esempi seguenti). Il poligono deve essere chiuso, quindi il primo e l'ultimo set di punti devono coincidere. I punti in un poligono devono essere in senso antiorario.

Query geo-spaziali e poligoni che si estendono sul meridiano del 180°

Per molte librerie di query geo-spaziali che simulano una query che include il 180° meridiano (vicino alla linea di data) è fuori limite o richiede una soluzione alternativa, ad esempio suddividere il poligono in due, uno su entrambi i lati del meridiano.

In Ricerca di intelligenza artificiale di Azure le query spaziali geografiche che includono longitudine a 180 gradi funzioneranno come previsto se la forma della query è rettangolare e le coordinate sono allineate a un layout della griglia lungo la longitudine e la latitudine (ad esempio, geo.intersects(location, geography'POLYGON((179 65, 179 66, -179 66, -179 65, 179 65))'). In caso contrario, per le forme non rettangolari o non allineate, considerare l'approccio basato sulla suddivisione del poligono.

Funzioni spaziali geografiche e null

Analogamente a tutti gli altri campi non di raccolta in Ricerca di intelligenza artificiale di Azure, i campi di tipo Edm.GeographyPoint possono contenere null valori. Quando Ricerca intelligenza geo.intersects artificiale di Azure valuta per un campo che è null, il risultato sarà falsesempre . Il comportamento di geo.distance in questo caso dipende dal contesto:

  • Nei filtri, geo.distance di un null campo viene restituito .null Ciò significa che il documento non corrisponde perché null rispetto a qualsiasi valore non Null restituisce false.
  • Quando si ordinano i risultati utilizzando $orderby, geo.distance di un null campo viene restituita la distanza massima possibile. I documenti con un campo di questo tipo verranno ordinati in ordine inferiore a tutti gli altri quando viene usata la direzione asc di ordinamento (impostazione predefinita) e superiore a tutte le altre quando la direzione è desc.

Esempi

Esempi di filtro

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

    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 posizione è un campo di tipo Edm.GeographyPoint). Si noti che il poligono è chiuso (il primo e l'ultimo set di punti devono coincidere) e che i punti devono essere elencati in senso antiorario.

    geo.intersects(location, geography'POLYGON((-122.031577 47.578581, -122.031577 47.678581, -122.131577 47.678581, -122.031577 47.578581))')

Esempi di order-by

Ordinare gli hotel decrescente in ratingbase a , quindi crescente per distanza dalle coordinate specificate:

    rating desc,geo.distance(location, geography'POINT(-122.131577 47.678581)') asc

Ordinare gli hotel in ordine decrescente per search.score e rating, e quindi in ordine crescente per distanza dalle coordinate specificate in modo che tra due hotel con classificazioni identiche, quello più vicino viene elencato per primo:

    search.score() desc,rating desc,geo.distance(location, geography'POINT(-122.131577 47.678581)') asc

Passaggi successivi