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. Ti consigliamo
di scrivere i valori dei campi in lettere minuscole, perché le ricerche nei campi atom, testo
e HTML non fanno distinzione tra maiuscole e minuscole. Inoltre, una stringa di query può contenere anche gli
operatori booleani AND, OR e NOT, che vengono riconosciuti
usando le maiuscole.
Una virgola può apparire 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 diverse forme. Esistono due modi principali per creare una query: con e senza nomi dei campi. Una ricerca globale utilizza una stringa di query che contiene solo valori dei campi:
query = "blue"
query = "NOT white"
query = "blue OR red"
query = "blue guitar"
Una ricerca campi utilizza una stringa di query contenente 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 costruire stringhe di query per ricerche globali e sul campo e come funziona la logica di ricerca in ciascun caso.
Ti consigliamo di registrare le stringhe di query nella tua applicazione se vuoi conservare un record delle query eseguite.
Ricerca globale
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 contenente uno o più valori dei campi. L'algoritmo di ricerca riconosce il tipo di ogni valore e cerca in tutti i campi dei documenti che potrebbero contenere quel valore.
Query con un 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 contenente 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 numerico con un valore uguale al numero nella query (un campo numerico con valore 5 corrisponderà alla query "5" e "5.0").
- Un campo di testo o HTML contenente un token corrispondente al numero visualizzato nella query (il campo di testo "ha impiegato 5 minuti" corrisponderà alla query "5" ma non "5.0").
- Un campo atomico 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 alla data (gli zero iniziali nella stringa di query sono facoltativi, i valori "2012-07-04" e "2012-7-4" sono la stessa data).
- Un campo di testo o HTML contenente un token che corrisponde letteralmente alla data visualizzata nella query.
- Un campo atom che corrisponde letteralmente alla data così come appare nella query.
Puoi anteporre l'operatore booleano NOT (in lettere maiuscole) a una query di una sola parola. Il risultato è un elenco di documenti privi di campi corrispondenti al valore della query, secondo le stesse regole. Di conseguenza, la query NOT red recupererà tutti i documenti che non hanno campi di testo o HTML contenenti "rosso" o campi atom con valore red.
Potresti aver notato che i campi dei punti geografici non sono stati menzionati. Al momento non è possibile specificare un valore di punti geografici non elaborati come stringa, di conseguenza i punti geografici non possono essere visualizzati nelle ricerche globali.
Query con più valori
In una stringa di ricerca globale puoi specificare più valori (separati da spazi). Lo spazio tra parole, stringhe tra virgolette, numeri e date viene considerato come un operatore AND implicito. Le due stringhe di ricerca di seguito sono quasi le stesse; si differenziano nel modo in cui la ricerca globale tratta i campi atomici, come spiegato di seguito:
query = "small red"
query = "small AND red"
Quando si esegue una ricerca globale con più valori, la corrispondenza dei campi viene eseguita indipendentemente da ciascun valore della stringa, mentre la corrispondenza dei campi atom 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.
- La ricerca dei campi Atom viene eseguita solo se la stringa di query non contiene operatori booleani (
AND,OR,NOT). L'intera stringa di query deve corrispondere a un campo atom.
Nota la terza regola che riguarda i campi atomici. 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 proverà a trovare una corrispondenza tra la stringa di query e i campi atom.
L'esempio seguente mostra quattro documenti recuperati utilizzando la stringa di query "boccio di rosa". Ogni documento ha due campi di testo e un campo atom. La colonna dei commenti spiega perché ogni documento soddisfa la query.
| ID documento | Campo di testo 1 | Campo di testo 2 | Campo atomico | Commento |
|---|---|---|---|---|
| 1 | potente come una rosa | un auricolare per legare tutti | cespuglio spinoso | I valori corrispondenti possono essere visualizzati in campi diversi |
| 2 | largo come un fiume | come un germoglio su una rosa | rotolare erba | I valori corrispondenti possono apparire in qualsiasi ordine nello stesso campo di testo o HTML, con testo intermedio |
| 3 | nel profondo dell'oceano | i ragazzi rose bud | cuffia blu | I valori corrispondenti possono essere visualizzati in qualsiasi ordine nello stesso campo di testo o HTML |
| 4 | alta 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 hai invertito i valori nella query e hai cercato "bud rose",
i documenti 1, 2 e 3 verrebbero comunque restituiti, ma non il documento 4. Per cercare una stringa di caratteri esatta nei campi atom, testo e HTML, cita la stringa nella stringa di query. La ricerca di "rose bud" restituirà 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 compaiono all'interno di una stringa tra virgolette,
vengono trattati come parte del valore del campo, non come operatori. Puoi usare le parentesi in una stringa di query per chiarire la logica.
La precedenza dell'operatore booleano, dalla più alta alla più bassa, è: 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
Radice
Per cercare varianti comuni di una parola, ad esempio forme plurali e finali di verbi, utilizza l'operatore staminale ~ (il carattere tilde). Si tratta di un operatore prefisso che deve precedere un valore senza spazi. Il valore ~cat corrisponderà a "gatto" o "gatti", così come ~dog corrisponde a "cane" o "cani". L'algoritmo di stemming non è infallibile. Il valore ~care corrisponderà a "care" e "caring", ma non a "cares" o "cared". La radice viene utilizzata solo per la ricerca di campi di testo e HTML.
Tokenizzazione
Quando un documento viene indicizzato, i relativi campi sono tokenizzati. Analogamente, vengono tokenizzati anche i valori in una stringa di query. 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"
Ricerca campi
Una ricerca campi cerca i valori in campi di documenti specifici, in base al nome del campo. Una stringa di query di ricerca dei campi è composta da una o più espressioni che specificano un nome di campo, un operatore relazionale e un valore di campo. Gli operatori relazionali disponibili dipendono dal tipo di campo. L'operatore di uguaglianza, rappresentato dai due punti o dal segno uguale, può essere utilizzato per tutti i tipi di campo. Ecco alcune stringhe di query 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'uso di spazi vuoti ai 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, mentre un'espressione per il valore di un campo può essere negata anteponendo il carattere NOT in maiuscolo.
Query sui campi atom
Il valore di un campo atom è una stringa di caratteri. Le query sui campi atom non fanno distinzione tra maiuscole e minuscole. Se la query specifica un valore di campo con spazi vuoti o punteggiatura, assicurati di citare il valore nella stringa di query. L'unico operatore relazionale valido per i campi atom è l'operatore di uguaglianza. L'intero contenuto di un campo atom deve corrispondere al valore della query, compreso qualsiasi carattere Unicode che combina caratteri o caratteri accentati nel campo. La radice empirica non è supportata per i campi atom.
| Stringa di query | Commenti |
|---|---|
"weather=stormy"
|
Entrambe le forme dell'operatore di uguaglianza sono valide. Recupera i documenti con un campo meteo uguale a "tempestoso". |
"Title: \"Tom&Jerry\""
|
Se stai cercando un campo atom che contiene spazi vuoti o caratteri speciali, racchiudi il valore tra virgolette. |
"Color = (red OR blue)"
|
Puoi utilizzare le parentesi e l'operatore logico OR per specificare un elenco di valori di campi alternativi. |
Query su 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 valore" e non "campo uguale al valore". Puoi utilizzare l'operatore per la 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 appare all'interno di una stringa tra virgolette, non viene trattato in modo speciale, ma è solo un'altra parte della stringa di caratteri con cui trovare una corrispondenza. Ricorda 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 gli Unicode che combinano caratteri e caratteri accentati vengono "normalizzati" nei loro equivalenti non accentati. Anche la combinazione di caratteri e accenti viene normalizzata nelle stringhe di query su questi campi, in modo che una query possa includere o meno i moduli accentati e corrisponderà ai campi in entrambi i casi.
| Stringa di query | Commenti |
|---|---|
"Comment = great" |
Entrambe le forme dell'operatore di uguaglianza sono valide. Recupera i documenti con un campo di commento che contiene almeno un'occorrenza della parola "great" nel campo Commento. |
"Comment = (great big 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, separandole con un numero qualsiasi di altre parole. Lo spazio tra le parole implica un operatore logico AND; la seconda forma lo rende esplicito. |
"Comment = \"insanely great\""
|
Per cercare una stringa di testo specifica, racchiudi la stringa tra virgolette. Questa query recupererà i documenti il cui campo Commento contiene la frase "Incredibilmente grande" (e anche "Incredibilmente fantastico", che è tokenizzato nella stessa cosa). |
"pet = ~dog"
|
L'operatore di stemming corrisponderà alle varianti della parola "dog" nel campo pet. |
"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" oppure entrambi. |
"weather = ((rain OR snow) AND cold)" |
Puoi utilizzare gli operatori logici OR e AND, insieme alle parentesi, per specificare un valore di campo più complesso. |
"weather = \"rain OR shine\"" |
Poiché l'OR logico è incorporato in una stringa tra virgolette, non viene considerato come un operatore relazionale. Questa stringa di query recupera i documenti con un campo meteo che contiene la stringa "pioggia o sole" |
Query sui campi numerici
Il valore di un 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 è presente alcun 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 in yyyy-mm-dd form. Gli zeri iniziali sono facoltativi per i mesi e i giorni con una sola cifra. Gli operatori relazionali validi per i campi
date sono gli operatori di uguaglianza, insieme agli operatori minore di/superiore (<, <=, >, >=). Tieni presente che non è presente alcun operatore di disuguaglianza. Puoi
anteporre l'operatore NOT a un'espressione per annullarla. Ecco alcuni esempi di stringhe di query per i campi delle date:
"start_date: 2012-05-20"
"end_date: 2013-5-1"
"birthday >= 2000-12-31"
"NOT birthday = 2000-12-25"
Query sui campi dei punti geografici
Non esistono operatori relazionali che funzionino con i campi di punti geografici, di conseguenza non è possibile nominare questi campi direttamente in una stringa di query. L'API Search offre due funzioni speciali che possono essere utilizzate per le query relative ai campi dei punti geografici:
geopoint(lat,long)- Definisce un punto geografico in base alla latitudine e alla longitudine.
distance(point1, point2)- Calcola la distanza in metri tra due punti geografici. Ogni punto può essere specificato utilizzando il nome di un campo di punti geografici o una chiamata alla funzione di punto geografico. Tieni presente che non puoi fornire due nomi di campo come argomenti per questa funzione. Almeno un argomento deve essere una costante.
Queste funzioni possono essere utilizzate per creare query che recuperano località relative a una posizione costante. I seguenti esempi presuppongono che l'indice contenga documenti con campi di punti geografici denominati "survey_marker" e "home".
| Stringa di query | Commenti |
|---|---|
"distance(survey_marker, geopoint(35.2, 40.5)) < 100" |
Cerca gli indicatori a meno di 100 metri da un determinato punto geografico. |
"distance(home, geopoint(35.2, 40.5)) > 100" |
Cerca case a più di 100 metri da un determinato punto geografico. |
Le applicazioni che utilizzano la geolocalizzazione in genere ricevono informazioni dal browser. Se l'utente lo consente, la località può essere dedotta dal suo indirizzo IP oppure è possibile inserire un codice postale. La posizione può anche provenire da altre API, come l'API Geolocation di Google Maps.
Query su più campi
Puoi combinare più espressioni di query sul campo in una query elencandole in sequenza, separate da spazi vuoti. In questo modo viene inserito un AND implicito tra ogni
espressione, quindi devono essere tutte soddisfatte per recuperare un documento. Puoi aggiungere esplicitamente operatori AND e OR tra le espressioni e utilizzare le parentesi per chiarire 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 operatore logico AND; 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 sul campo
Una stringa di query può contenere un numero illimitato di espressioni di ricerca globali ed espressioni di ricerca sui campi. Gli spazi tra le espressioni vengono trattati come AND. Puoi
anche utilizzare in modo esplicito OR e AND, insieme alle parentesi. Ogni espressione viene gestita in base alle regole associate a quel tipo di termine.
| Stringa di query | Commenti |
|---|---|
"keyboard great price<5000"
|
Recupera i documenti in cui le parole "great" e "tastiera" appaiono in qualsiasi campo di testo, HTML o atom, ed è presente un campo price inferiore a 5000.
Il valore AND è implicito, mentre il secondo è equivalente.
|
"keyboard OR product=piano" |
Recupera i documenti con un campo del prodotto contenente un pianoforte o documenti con qualsiasi campo di testo, HTML o atom contenente la tastiera. |