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. Ti consigliamo di scrivere i valori dei campi in minuscolo, perché le ricerche nei campi atom, testo 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 scrivendoli 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 dei campi:

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

Questo documento descrive come costruire stringhe di query per ricerche globali e sui campi e come funziona la logica di ricerca in ogni caso.

Ti consigliamo di registrare le stringhe di query nell'applicazione se vuoi conservare 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 contenente uno o più valori dei campi. L'algoritmo di ricerca riconosce il tipo di ogni valore e cerca in tutti i campi del documento che potrebbero contenere quel valore.

Query a un valore

Una ricerca con una stringa di query che contiene un singolo valore viene gestita in base alle seguenti 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 contengono:

  • Un campo numerico con un valore uguale a quello nella query (un campo numerico con valore 5 corrisponderà alle query "5" e "5,0").
  • Un campo di testo o HTML contenente 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 atom 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 corrisponde a quella data (gli zeri iniziali nella stringa di query sono facoltativi, "2012-07-04" e "2012-7-4" corrispondono alla 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 visualizzata nella query.

Puoi anteporre l'operatore booleano NOT (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 contenenti il valore "rosso" o qualsiasi campo Atom con il valore red.

Potresti aver notato che i campi di geopoint non sono stati menzionati. Al momento, non è possibile specificare un valore di punto geografico non elaborato come stringa, pertanto i punti geografici non possono essere visualizzati nelle ricerche globali.

Query multivalore

Puoi specificare più valori (separati da spazi) in una stringa di ricerca globale. Lo spazio vuoto tra parole, stringhe tra virgolette, numeri e date viene considerato come un operatore implicito AND. Le due stringhe di ricerca riportate di seguito sono quasi le stesse e si differenziano nel modo in cui la ricerca globale tratta i campi atom, 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 in modo indipendente da ciascun valore nella stringa e la corrispondenza dei campi Atom viene gestita in modo diverso, in particolare:

  • I valori delle query possono essere visualizzati in qualsiasi ordine in un campo di testo o HTML.
  • Valori diversi possono essere visualizzati in campi differenti.
  • La ricerca nei campi Atom viene eseguita solo quando 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 Atom. La stringa di query "red small" non contiene il valore booleano AND (anche se è implicito), quindi la ricerca tenterà di trovare i campi atom corrispondenti. La stringa "red AND small" contiene un operatore booleano, quindi la ricerca non cercherà di abbinare la stringa di query ai 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 atom. 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 potente come una rosa un auricolare per legarli tutti cespuglio di spine I valori corrispondenti possono essere visualizzati in campi diversi
2 largo come un fiume come un bocciolo su una rosa erba caduta 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 figli di 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 verranno comunque restituiti, al contrario del documento 4. Per cercare una stringa di caratteri esatta nei campi Atom, di testo e HTML, cita la stringa nella stringa di query. La ricerca di "rose bud" restituirà 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, non come operatori. Puoi usare le parentesi in una stringa di query per chiarire la logica.

La precedenza degli operatori 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

Stemming

Per cercare varianti comuni di una parola, come le forme plurali e le finali di verbo, utilizza l'operatore radice ~ (il carattere tilde). Questo è un operatore di prefisso che deve precedere un valore senza spazi intermedi. Il valore ~cat corrisponderà a "gatto" o a "gatti" e allo stesso modo ~dog corrisponde a "cane" o "cani". L'algoritmo di stemming non è infallibile. Il valore ~care corrisponderà a "care" e "care", 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 vengono tokenizzati. Analogamente, vengono tokenizzati anche i valori in una stringa di query. Ciò significa che quella che potrebbe sembrare una query a un valore viene in realtà trattata come una query a più valori. Ad esempio:

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

Una ricerca nei campi cerca i valori in campi specifici del documento, in base al nome del campo. Una stringa di query di ricerca di un 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 dai due punti o dal segno uguale, può essere utilizzato per tutti i tipi di campo. Di seguito sono riportate 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'utilizzo di spazi vuoti su entrambi i lati dell'operatore relazionale è facoltativo. Come nel caso delle 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 l'espressione di un valore di campo può essere negata anteponendo un NOT maiuscolo.

Query sui campi Atom

Il valore di un campo Atom è una stringa di caratteri. Le query nei campi Atom non fanno distinzione tra maiuscole e minuscole. Se la query specifica un valore del campo con spazi vuoti o punteggiatura, assicurati di citare il valore 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; sono inclusi tutti i caratteri Unicode che combinano caratteri o caratteri accentati nel campo. Lo stemming non è supportato per i campi Atom.

Stringa di query Commenti
"weather=stormy"
"weather: stormy"
Entrambi i tipi di operatore di uguaglianza sono validi. Recupera i documenti con un campo meteo che indica "tempestoso".
"Title: \"Tom&Jerry\""
"Couple: \"Fred and Ethel\""
"Version = \"1HCP(21.3)\""
Se stai cercando un campo Atom che contiene spazi vuoti 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 per i campi.

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 "campo include valore" e non "campo è uguale valore". Puoi utilizzare l'operatore di derivazione per cercare varianti di una parola. Inoltre, puoi utilizzare gli operatori OR e AND per specificare espressioni booleane complesse per il valore del campo. Se un operatore booleano è presente all'interno di una stringa tra virgolette, non viene trattato in modo speciale, ma è solo un altro pezzo della stringa di caratteri da associare. Ricorda che quando esegui una ricerca 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 Unicode che combinano caratteri e caratteri accentati vengono "normalizzati" rispetto ai loro equivalenti non accentati. La combinazione di caratteri e accenti viene normalizzata anche nelle stringhe di query in questi campi, in modo che una query possa includere o meno i moduli accentati e corrisponderà ai campi in entrambi i casi.

Stringa di queryCommenti
"Comment = great"
"Comment: great"
Entrambi i tipi di operatore di uguaglianza sono validi. Recupera i documenti con un campo di commento che contiene almeno un'occorrenza della parola "great" 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, separate da un numero qualsiasi di altre parole. 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, racchiudi la stringa tra virgolette. Questa query recupererà i documenti il cui campo Commento contiene la frase "inanely-great" (e anche "insanely-great", che è tokenizzata alla stessa cosa).
"pet = ~dog" L'operatore di stemming corrisponderà alle varianti della parola "cane" nel campo relativo all'animale.
"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 ed AND, insieme alle parentesi, per specificare un valore di campo più complesso.
"weather = \"rain OR shine\"" Poiché l'operatore logico è incorporato in una stringa tra virgolette, non viene considerato un operatore relazionale. Questa stringa di query recupera i documenti con un campo meteo contenente la stringa "pioggia o sole"

Query sui campi numerici

Il valore di un campo numerico può essere scritto come un numero intero, un decimale o un 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

Un valore del campo data deve essere scritto in yyyy-mm-dd form. Gli zeri iniziali sono facoltativi per i mesi e i giorni di una cifra. Gli operatori relazionali validi per i campi delle date sono gli operatori di uguaglianza, insieme agli operatori "minore di/maggiore di" (<, <=, >, >=). Tieni presente che non esiste alcun operatore di disuguaglianza. Puoi anteporre l'operatore NOT a un'espressione per annullarlo. Di seguito sono riportate alcune stringhe di query di esempio per i campi di data:

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

Query sui campi di punti geografici

Non ci sono operatori relazionali che funzionano con i campi di geopoint, quindi 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 di punti geografici:

geopoint(lat,long)
Definisce un punto geografico con latitudine e 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 punto geografico o una chiamata della funzione di punto geografico. Tieni presente che non puoi fornire due nomi di campo come argomenti di questa funzione. Almeno un argomento deve essere una costante.

Queste funzioni possono essere utilizzate per costruire query che recuperano le località relative a una posizione costante. I seguenti esempi presuppongono che l'indice contenga documenti con campi di geopoint denominati "survey_Mark" e "home".

Stringa di query Commenti
"distance(survey_marker, geopoint(35.2, 40.5)) < 100" Cerca 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 di distanza 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 o può inserire un codice postale. La posizione può provenire anche da altre API come l'API Google Maps Geolocation.

Query su più campi

Puoi combinare più espressioni di query di campo in una query elencandole in sequenza separate da spazi vuoti. Questo inserisce un valore AND implicito tra ogni espressione, quindi tutte devono essere soddisfatte per recuperare un documento. Puoi aggiungere esplicitamente 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 rende questo aspetto esplicito.
"product=piano AND NOT manufacturer=steinway" Recupera tutti i pianoforti non Steinway.
"product=piano AND price<2000" Questa query recupera pianoforti economici.

Un mix di ricerche globali e sul campo

Una stringa di query può contenere un numero qualsiasi di espressioni di ricerca globali ed espressioni di ricerca dei campi. Gli spazi tra le espressioni vengono trattati come AND. Puoi anche usare esplicitamente OR e AND, 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 "great" e "keyboard" appaiono in qualsiasi campo di testo, HTML o atom ed è presente un campo prezzo inferiore a 5000. AND è implicito, mentre la seconda forma è equivalente.
"keyboard OR product=piano" Recupera i documenti con un campo di prodotto contenente pianoforte o documenti con qualsiasi campo di testo, HTML o Atom contenente la tastiera.