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 sono sensibili alle maiuscole 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ò 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 fa parte di una stringa tra virgolette.
Una stringa di query può assumere molte forme. Esistono due modi principali per creare una query: con e senza nomi di campo. Una ricerca globale utilizza una stringa di query che contiene solo valori di campo:
Una ricerca in un campo utilizza una stringa di query contenente una o più espressioni che specificano i nomi e i valori dei campi:
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 conservare un record delle query eseguite.
Ricerca globale
La ricerca globale offre la possibilità di cercare documenti specificando valori che potrebbero apparire in qualsiasi campo del documento. Per eseguire una ricerca globale, scrivi una stringa di query contenente uno o più valori di campo. L'algoritmo di ricerca riconosce il tipo di ciascun valore e cerca in tutti i campi del documento che potrebbero contenere quel valore.
Query con un valore
Una ricerca con una stringa di query contenente un singolo valore viene gestita secondo queste regole:
Se la stringa di query è una parola (red) o una stringa tra virgolette ("red rose"), la ricerca recupera tutti i documenti in un indice che contengono:
- Un campo di testo o HTML contenente la parola o la stringa tra virgolette (la corrispondenza è indipendente dalle maiuscole).
- Un campo atomo con un valore che corrisponde alla parola o alla stringa tra virgolette (la corrispondenza è senza distinzione tra maiuscole e minuscole).
Se la stringa di query è un numero ("3.14159"), la ricerca recupera tutti i documenti che:
- Un campo di testo o HTML contenente un token che corrisponde al numero visualizzato nella query (il campo di testo "ci sono voluti 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 contengono:
- Un campo data il cui valore è uguale a quella data (i zeri iniziali nella stringa di query sono facoltativi, "2012-07-04" e "2012-07-04" sono la stessa data).
- Un campo di testo o HTML contenente un token che corrisponde alla data come appare nella query.
- Un campo atom che corrisponde esattamente alla data visualizzata nella query.
Puoi anteporre l'operatore booleano NOT (in maiuscolo) a una query di una 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 contengono campi di testo o HTML contenenti "rosso" 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, pertanto i geopoint non possono comparire nelle ricerche globali.
Query con più valori
Puoi specificare più valori (separati da spazi) in una stringa di ricerca globale. Lo spazio tra parole, stringhe tra virgolette, numeri e date viene trattato come un operatore AND implicito. Le due stringhe di ricerca riportate di seguito sono quasi uguali; differiscono per il modo in cui la ricerca globale tratta i campi di atomi, 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 indipendente da ciascun valore nella stringa e la corrispondenza dei campi di atomi viene gestita in modo diverso, in particolare:
- I valori di query possono essere visualizzati in qualsiasi ordine in un campo di testo o HTML.
- In campi diversi possono essere visualizzati valori diversi.
- I campi di atomi 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 di atomi.
Prendi nota della terza regola relativa ai campi di atomi. La stringa di query "rosso piccolo" non contiene il valore booleano AND (anche se è implicito), pertanto la ricerca tenterà di trovare campi di atomi corrispondenti. La stringa "rosso E piccolo" contiene un operatore booleano, pertanto la ricerca non tenterà di abbinare la stringa di query ai campi dell'atomo.
L'esempio seguente mostra quattro documenti recuperati utilizzando la stringa di query "rose bud". Ogni documento ha due campi di testo e un campo di atomi. La colonna Commento spiega perché ogni documento soddisfa la query.
| ID documento | Campo di testo 1 | Campo di testo 2 | Campo atomo | Commento |
|---|---|---|---|---|
| 1 | forte come una rosa | un bud per unirli tutti | rovo | I valori corrispondenti possono essere visualizzati in campi diversi |
| 2 | largo come un fiume | 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 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 dell'atome corrisponde perché il suo valore corrisponde all'intera stringa di query |
Tieni presente che se invertivi i valori nella query e cercavi "rosa di buccia", i documenti 1, 2 e 3 verrebbero comunque restituiti, ma non il documento 4. Per cercare una stringa di caratteri esatta nei campi atom, di testo e HTML,
chiudere la stringa tra virgolette nella stringa di query. Una ricerca di "rose bud" restituirebbe solo i documenti 3 e 4 nell'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 appaiono all'interno di una stringa tra virgolette, vengono trattati come parte del valore del campo e non come operatori. Puoi utilizzare le parentesi in una stringa di query per rendere chiara la logica.
La precedenza degli operatori booleani, 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
Stemming
Per cercare le varianti comuni di una parola, come le forme plurali e le terminazioni dei verbi, utilizza l'operatore radice ~ (il carattere tilde). Si tratta di un operatore di prefisso che deve precedere un valore senza spazi intermedi. Il valore ~cat corrisponde a "gatto" o "gatti" e, allo stesso modo, ~dog corrisponde a "cane" o "cani". L'algoritmo di derivazione non è infallibile. Il valore ~care corrisponde a "care" e "caring", ma non a "cares" o "cared". L'analisi morfologica viene utilizzata solo per la ricerca nei campi di testo e HTML.
Tokenizzazione
Quando un documento viene indicizzato, i relativi campi vengono tokenizzati. Analogamente, anche i valori in una stringa di query vengono tokenizzati. Ciò significa che quella che potrebbe sembrare una query con un valore viene trattata come una query con più valori. Ad esempio:
"real-time" --> "real time"
"2001-12-15" --> "2001 12 15"
"1.5" --> "1 5"
Ricerca nel campo
Una ricerca in un campo 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 di relazione disponibili dipendono dal tipo di campo. L'operatore di uguaglianza, rappresentato da due punti o dal segno di uguale, può essere utilizzato per tutti i tipi di campi. Di seguito sono riportate 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 vuoti 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 un NOT maiuscolo.
Query sui campi di Atom
Il valore di un campo atomo è una stringa di caratteri. Le query sui campi degli atomi non fanno distinzione tra maiuscole e minuscole. Se la query specifica un valore di campo con spazi 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. I contenuti completi di un campo atom devono corrispondere al valore della query, inclusi eventuali caratteri Unicode combinati o con accenti nel campo. L'analisi morfologica non è supportata per i campi di atomi.
| 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 di atomi che contiene spazi 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 campo alternativi. |
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 indica "il campo include il valore" e non "il campo è uguale al valore". Puoi utilizzare l'operatore di derivazione 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 compare all'interno di una stringa tra virgolette, non viene trattato in modo speciale, ma è solo un altro elemento della stringa di caratteri da abbinare. Tieni presente che, quando esegui ricerche nei campi HTML, il testo all'interno degli elementi 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, eventuali caratteri Unicode combinati e caratteri accentati al loro interno vengono "normalizzati" ai corrispondenti equivalenti senza accenti. I caratteri combinati e gli accenti vengono normalizzati anche nelle stringhe di query su questi campi, pertanto una query può includere o meno le forme con accento 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 una occorrenza della parola "ottimo" 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 con un numero qualsiasi di altre parole tra di loro. Lo spazio tra le parole implica un AND logico; la seconda forma lo esplicita. |
"Comment = \"insanely great\""
|
Per cercare una stringa di testo specifica, racchiudila tra virgolette. Questa query recupererà i documenti il cui campo Comment contiene la frase "insanely great" (e anche "insanely-great", che viene tokenizzata allo stesso modo). |
"pet = ~dog"
|
L'operatore di derivazione corrisponderà alle varianti della parola "cane" nel campo 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 di campo più complesso. |
"weather = \"rain OR shine\"" |
Poiché l'operatore 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 contenente la stringa "rain or shine" |
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/maggiore (<, <=, >, >=). Tieni presente che non esiste un operatore di disuguaglianza (!=). Ecco alcune stringhe di query di esempio per i campi numerici:
"quantity = 10000"
"size: 4"
"price < 9.99"
"theta > 1.5E-2"
Query sui campi data
Un valore di campo della data deve essere scritto in yyyy-mm-dd form. I 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 alcune stringhe di query di esempio per i campi della 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 funzionino 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 i campi geopoint:
geopoint(lat,long)- Definisce un punto geografico a partire da una latitudine e una 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 le posizioni in base 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 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 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 sui campi in una singola query elencandole in sequenza separate da spazi. Viene inserito un AND implicito tra ogni expressione, quindi tutte devono essere soddisfatte per recuperare un documento. Puoi
aggiungere esplicitamente gli 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 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. |
Combinare ricerche globali e ricerche nei campi
Una stringa di query può contenere un numero qualsiasi di espressioni di ricerca globale ed espressioni di ricerca dei campi. Gli spazi tra le espressioni vengono considerati come AND. Puoi anche utilizzare 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 query | Commenti |
|---|---|
"keyboard great price<5000"
|
Recupera i documenti in cui le parole "fantastica" e "tastiera" appaiono in qualsiasi
campo di testo, HTML o atom ed è presente un campo del prezzo inferiore a 5000.
AND è implicito, la seconda forma è equivalente.
|
"keyboard OR product=piano" |
Recupera i documenti con un campo del prodotto contenente piano o i documenti con un campo di testo, HTML o atom contenente tastiera. |