Stringhe di query

Una stringa di query contiene caratteri Unicode. La lunghezza massima di una stringa di query è di 2000 caratteri. Tutte le stringhe di query contengono almeno un valore di campo. È consigliabile scrivere i valori dei campi in minuscolo, perché le ricerche nei campi atom, text e HTML non fanno distinzione tra maiuscole e minuscole e una stringa di query può contenere anche gli operatori booleani AND, OR e NOT, che vengono riconosciuti se scritti in maiuscolo.

Una virgola può essere visualizzata in una stringa di query solo se viene utilizzata per separare gli argomenti di una funzione: distance(home, geopoint(35.2, 40.5)) > 100 o se fa parte di una stringa tra virgolette.

Una stringa di query può assumere molte forme. Esistono due modi principali per costruire una query: con e senza nomi di campo. Una ricerca globale utilizza una stringa di query che contiene solo i valori dei campi:

query = "blue"
query = "NOT white"
query = "blue OR red"
query = "blue guitar"

Una ricerca nei campi utilizza una stringa di query che contiene una o più espressioni che specificano i nomi e i valori dei campi:

query = "model:gibson date < 1965-01-01"
query = "title:\"Harry Potter\" AND pages<500"
query = "beverage:wine color:(red OR white) NOT country:france"

Questo documento descrive come creare stringhe di query per le ricerche globali e per campo e come funziona la logica di ricerca in ogni caso.

Ti consigliamo di registrare le stringhe di query nella tua applicazione se vuoi tenere un registro delle query eseguite.

La ricerca globale offre la possibilità di cercare documenti specificando valori che potrebbero essere visualizzati in qualsiasi campo del documento. Per eseguire una ricerca globale, scrivi una stringa di query che contenga uno o più valori di campo. L'algoritmo di ricerca riconosce il tipo di ogni valore e cerca in tutti i campi del documento che potrebbero contenere quel valore.

Query con un solo valore

Una ricerca con una stringa di query che contiene un singolo valore viene gestita in base a queste regole:

Se la stringa di query è una parola (red) o una stringa tra virgolette ("red rose"), la ricerca recupera tutti i documenti di un indice che hanno:

  • Un campo di testo o HTML che contiene la parola o la stringa tra virgolette (la corrispondenza non fa distinzione tra maiuscole e minuscole).
  • Un campo atom con un valore che corrisponde alla parola o alla stringa tra virgolette (la corrispondenza non fa distinzione tra maiuscole e minuscole).

Se la stringa di query è un numero ("3.14159"), la ricerca recupera tutti i documenti che hanno:

  • Un campo di testo o HTML che contiene un token che corrisponde al numero visualizzato nella query (il campo di testo "ha impiegato 5 minuti" corrisponderà alla query "5" ma non a "5.0").
  • Un campo atomo che corrisponde letteralmente al numero visualizzato nella query.

Se la stringa di query è una data nel formato aaaa-mm-gg, la ricerca recupera tutti i documenti che hanno:

  • Un campo data il cui valore è uguale a quella data (gli zeri iniziali nella stringa di query sono facoltativi, "2012-07-04" e "2012-7-4" sono la stessa data).
  • Un campo di testo o HTML che contiene un token che corrisponde letteralmente alla data come appare nella query.
  • Un campo atom che corrisponde letteralmente alla data visualizzata nella query.

Puoi anteporre l'operatore booleano NOT (in maiuscolo) a una query di una sola parola. Il risultato è un elenco di documenti che non hanno campi corrispondenti al valore della query, in base alle stesse regole. Pertanto, la query NOT red recupererà tutti i documenti che non hanno campi di testo o HTML che contengono "red" o campi atom con il valore red.

Potresti aver notato che i campi geopoint non sono stati menzionati. Al momento non puoi specificare un valore geopoint non elaborato come stringa, quindi i geopoint non possono essere visualizzati nelle ricerche globali.

Query multivalore

Puoi specificare più valori (separati da spazi) in una stringa di ricerca globale. Lo spazio tra parole, stringhe tra virgolette, numeri e date viene considerato come un operatore AND implicito. Le due stringhe di ricerca riportate di seguito sono quasi identiche; differiscono per il modo in cui la ricerca globale tratta i campi atom, come spiegato di seguito:

query = "small red"
query = "small AND red"

Quando esegui una ricerca globale con più valori, la corrispondenza dei campi viene eseguita in modo indipendente su ogni valore della stringa e la corrispondenza dei campi atomici viene gestita in modo diverso, in particolare:

  • I valori della query possono essere visualizzati in qualsiasi ordine in un campo di testo o HTML.
  • Valori diversi possono essere visualizzati in campi diversi.
  • I campi Atom vengono cercati solo quando la stringa di query non contiene operatori booleani (AND, OR, NOT). L'intera stringa di query deve corrispondere a un campo Atom.

Prendi nota della terza regola relativa ai campi atom. La stringa di query "red small" non contiene il valore booleano AND (anche se è implicito), quindi la ricerca tenterà di trovare campi atom corrispondenti. La stringa "red AND small" contiene un operatore booleano, quindi la ricerca non tenterà di trovare una corrispondenza tra la stringa di query e i campi atom.

L'esempio seguente mostra quattro documenti recuperati utilizzando la stringa di query "bocciolo di rosa". Ogni documento ha due campi di testo e un campo atomo. La colonna dei commenti spiega perché ogni documento soddisfa la query.

ID documento Campo di testo 1 Campo di testo 2 Campo Atom Commento
1 forte come una rosa un auricolare per domarli tutti cespuglio spinoso I valori corrispondenti possono essere visualizzati in campi diversi
2 wide like a river come un bocciolo su una rosa tumble weed I valori corrispondenti possono essere visualizzati in qualsiasi ordine nello stesso campo di testo o HTML, con testo intermedio
3 profondo come l'oceano i ragazzi bocciolo di rosa blue bonnet I valori corrispondenti possono essere visualizzati in qualsiasi ordine nello stesso campo di testo o HTML
4 alto come una montagna il bellissimo giardino bocciolo di rosa Il campo Atom corrisponde perché il suo valore è uguale all'intera stringa di query

Tieni presente che se inverti i valori nella query e cerchi "rosa bocciolo", i documenti 1, 2 e 3 verranno comunque restituiti, ma il documento 4 no. Per cercare una stringa di caratteri esatta nei campi atom, di testo e HTML, inserisci la stringa tra virgolette nella stringa di query. Una ricerca di "rose bud" restituirebbe solo i documenti 3 e 4 dell'esempio.

Operatori booleani

Puoi specificare una ricerca globale più complessa utilizzando l'operatore booleano NOT prima di un valore e gli operatori AND e OR tra i valori. Tieni presente che questi operatori devono essere scritti in maiuscolo. Se vengono visualizzati all'interno di una stringa tra virgolette, vengono trattati come parte del valore del campo, non come operatori. Puoi utilizzare le parentesi in una stringa di query per rendere chiara la logica.

La precedenza degli operatori booleani, dal più alto al più basso, è: NOT, OR, AND:

NOT cat AND dogs OR horses --> (NOT cat) AND (dogs OR horses)
NOT cat OR dogs AND horses --> ((NOT cat) OR dogs) AND horses

Stemming

Per cercare le varianti comuni di una parola, come le forme plurali e le terminazioni verbali, utilizza l'operatore di radice ~ (il carattere tilde). Si tratta di un operatore di prefisso che deve precedere un valore senza spazi intermedi. Il valore ~cat corrisponderà a "cat" o "cats", mentre ~dog corrisponderà a "dog" o "dogs". L'algoritmo di stemming non è infallibile. Il valore ~care corrisponderà a "care" e "caring", ma non a "cares" o "cared". Lo stemming viene utilizzato solo per la ricerca nei campi di testo e HTML.

Tokenizzazione

Quando un documento viene indicizzato, i relativi campi vengono tokenizzati. Allo stesso modo, anche i valori in una stringa di query vengono tokenizzati. Ciò significa che quella che potrebbe sembrare una query con un solo valore viene in realtà trattata come una query con più valori. Ad esempio:

"real-time" --> "real time"
"2001-12-15" --> "2001 12 15"
"1.5" --> "1 5"

Una ricerca per campo cerca valori in campi specifici del documento, in base al nome del campo. Una stringa di query di ricerca per campo è composta da una o più espressioni che specificano un nome campo, un operatore relazionale e un valore campo. Gli operatori relazionali disponibili dipendono dal tipo di campo. L'operatore di uguaglianza, rappresentato da due punti o dal segno uguale, può essere utilizzato per tutti i tipi di campi. Ecco alcune stringhe di query dei campi per diversi tipi di campi:

query = "pet = dog"
query = "author = \"Ray Bradbury\""
query = "color:red"
query = "NOT color:red"
query = "price < 500"
query = "birthday>=2011-05-10"

Tieni presente che l'utilizzo di spazi bianchi su entrambi i lati dell'operatore relazionale è facoltativo. Come per le stringhe di query di ricerca globale, il valore di un campo di testo, HTML o atom può essere racchiuso tra virgolette per specificare una stringa e un'espressione per un valore di campo può essere negata anteponendo NOT in maiuscolo.

Query sui campi atom

Il valore di un campo atom è una stringa di caratteri. Le query sui campi atomici non distinguono tra maiuscole e minuscole. Se la query specifica un valore di campo con spazi bianchi o punteggiatura, assicurati di racchiudere il valore tra virgolette all'interno della stringa di query. L'unico operatore relazionale valido per i campi atom è l'operatore di uguaglianza. Il contenuto completo di un campo atom deve corrispondere al valore della query, inclusi eventuali caratteri Unicode combinati o caratteri accentati nel campo. La derivazione non è supportata per i campi atomici.

Stringa di query Commenti
"weather=stormy"
"weather: stormy" 		Entrambe le forme dell'operatore di uguaglianza sono valide. Recupera i documenti con un campo meteo uguale a "tempestoso".
"Title: \"Tom&Jerry\""
"Couple: \"Fred and Ethel\""
"Version = \"1HCP(21.3)\""
 		Se stai cercando un campo atom che contiene spazi bianchi o caratteri speciali, racchiudi il valore tra virgolette.
"Color = (red OR blue)"
"Color = (\"dark red\" OR \"bright blue\")" 		Puoi utilizzare le parentesi e l'operatore logico OR per specificare un elenco di valori alternativi dei campi.

Query sui campi di testo e HTML

L'unico operatore relazionale valido per i campi di testo e HTML è l'uguaglianza. In questo caso l'operatore significa "il campo include il valore" e non "il campo è uguale al valore". Puoi utilizzare l'operatore di stemming per cercare varianti di una parola. Puoi anche utilizzare gli operatori OR e AND per specificare espressioni booleane complesse per il valore del campo. Se un operatore booleano viene visualizzato all'interno di una stringa tra virgolette, non viene trattato in modo speciale, ma è solo un altro elemento della stringa di caratteri da corrispondere. Tieni presente che quando cerchi nei campi HTML, il testo all'interno dei tag di markup HTML viene ignorato. Le query sui campi di testo e HTML non fanno distinzione tra maiuscole e minuscole. Quando questi campi vengono indicizzati, tutti i caratteri combinati Unicode e i caratteri accentati vengono "normalizzati" in modo che corrispondano ai caratteri non accentati. Anche la combinazione di caratteri e accenti viene normalizzata nelle stringhe di query in questi campi, quindi una query può includere o meno le forme accentate e corrisponderà ai campi in entrambi i casi.

Stringa di queryCommenti
"Comment = great"
"Comment: great"		 Entrambe le forme dell'operatore di uguaglianza sono valide. Recupera i documenti con un campo dei commenti che contiene almeno un'occorrenza della parola "ottimo" nel campo Commento.
"Comment = (great big ball)"
"Comment = (great AND big AND ball)" 		Per cercare due o più parole in un campo, in qualsiasi ordine, racchiudi le parole tra parentesi. Questa stringa di query recupera i documenti con un campo Commento che include tutte e tre le parole in qualsiasi ordine con un numero qualsiasi di altre parole tra loro. Lo spazio tra le parole implica un AND logico; la seconda forma lo rende esplicito.
"Comment = \"insanely great\"" Per cercare una stringa di testo specifica, racchiudila tra virgolette. Questa query recupererà i documenti il cui campo Commento contiene la frase "insanely great" (e anche "insanely-great", che viene tokenizzata nello stesso modo).
"pet = ~dog" L'operatore di stemming corrisponderà alle varianti della parola "cane" nel campo dell'animale domestico.
"Color = (red OR blue)" Per cercare una corrispondenza da un elenco di alternative, racchiudi l'elenco tra parentesi con la parola chiave OR tra le alternative. Questa query recupera i documenti il cui campo Colore include "rosso" o "blu" o entrambi.
"weather = ((rain OR snow) AND cold)" Puoi utilizzare gli operatori logici OR e AND, insieme alle parentesi, per specificare un valore del campo più complesso.
"weather = \"rain OR shine\"" Poiché l'OR logico è incorporato in una stringa tra virgolette, non viene trattato come un operatore relazionale. Questa stringa di query recupera i documenti con un campo meteo che contiene la stringa "con qualsiasi tempo"

Query sui campi numerici

Un valore di campo numerico può essere scritto come numero intero, decimale o esponenziale. Gli operatori relazionali validi per i campi numerici sono gli operatori di uguaglianza, insieme agli operatori minore di/maggiore di (<, <=, >, >=). Tieni presente che non esiste un operatore di disuguaglianza (!=). Ecco alcuni esempi di stringhe di query per i campi numerici:

"quantity = 10000"
"size: 4"
"price < 9.99"
"theta > 1.5E-2"

Query sui campi data

Il valore di un campo data deve essere scritto nel formato yyyy-mm-dd form. Gli zeri iniziali sono facoltativi per i mesi e i giorni a una cifra. Gli operatori relazionali validi per i campi data sono gli operatori di uguaglianza, insieme agli operatori minore di/maggiore di (<, <=, >, >=). Tieni presente che non esiste un operatore di disuguaglianza. Puoi anteporre l'operatore NOT a un'espressione per negarla. Ecco alcuni esempi di stringhe di query per i campi data:

"start_date: 2012-05-20"
"end_date: 2013-5-1"
"birthday >= 2000-12-31"
"NOT birthday = 2000-12-25"

Query sui campi geopoint

Non esistono operatori relazionali che funzionano con i campi geopoint, pertanto i campi geopoint non possono essere denominati direttamente in una stringa di query. L'API Search fornisce due funzioni speciali che possono essere utilizzate per le query che coinvolgono campi geopoint:

geopoint(lat,long)
Definisce un geopoint in base a latitudine e longitudine.
distance(point1, point2)
Calcola la distanza in metri tra due geopoint. Ogni punto può essere specificato utilizzando il nome di un campo geopoint o un'invocazione della funzione geopoint. Tieni presente che non puoi fornire due nomi di campi come argomenti di questa funzione. Almeno un argomento deve essere una costante.

Queste funzioni possono essere utilizzate per creare query che recuperano posizioni relative a una posizione costante. Gli esempi seguenti presuppongono che l'indice contenga documenti con campi geopoint denominati "survey_marker" e "home".

Stringa di query Commenti
"distance(survey_marker, geopoint(35.2, 40.5)) < 100" Cerca indicatori a meno di 100 metri da un geopoint specificato.
"distance(home, geopoint(35.2, 40.5)) > 100" Cerca case a più di 100 metri da un determinato geopoint.

Le applicazioni che utilizzano la geolocalizzazione in genere ricevono informazioni dal browser. Se l'utente lo consente, la posizione può essere dedotta dal suo indirizzo IP oppure può inserire un codice postale. La posizione può provenire anche da altre API, come l'API Geolocation di Google Maps.

Query su più campi

Puoi combinare più espressioni di query di campo in un'unica query elencandole in sequenza separate da spazi bianchi. In questo modo viene inserito un AND implicito tra ogni espressione, quindi tutte devono essere soddisfatte per recuperare un documento. Puoi aggiungere in modo esplicito gli operatori AND e OR tra le espressioni e utilizzare le parentesi per rendere chiara la logica.

Stringa di query Commenti
"product=piano manufacturer=steinway"
"product=piano AND manufacturer=steinway" 		Queste query recuperano tutti i pianoforti Steinway. Lo spazio tra i termini implica un AND logico; la seconda forma lo rende esplicito.
"product=piano AND NOT manufacturer=steinway" Recupera tutti i pianoforti non Steinway.
"product=piano AND price<2000" Questa query recupera pianoforti economici.

Combinazione di ricerche globali e per campo

Una stringa di query può contenere un numero qualsiasi di espressioni di ricerca globale ed espressioni di ricerca nei campi. Gli spazi tra le espressioni vengono trattati come AND. Puoi utilizzare anche OR e AND in modo esplicito, insieme alle parentesi. Ogni espressione verrà gestita in base alle regole associate a quel tipo di termine.

Stringa di queryCommenti
"keyboard great price<5000"
"keyboard AND great AND price<5000" 		Recupera i documenti in cui le parole "ottima" e "tastiera" compaiono in qualsiasi campo di testo, HTML o atom e in cui è presente un campo prezzo inferiore a 5000. Il AND è implicito, la seconda forma è equivalente.
"keyboard OR product=piano" Recupera i documenti con un campo prodotto che contiene pianoforte oppure i documenti con qualsiasi campo di testo, HTML o atom che contiene tastiera.