L'API Search fornisce un modello a documenti di indicizzazione contenenti dati strutturati. Puoi cercare in un indice organizzare e presentare i risultati di ricerca. L'API supporta la corrispondenza del testo completo su campi di stringa. I documenti e gli indici vengono salvati in un archivio permanente separato ottimizzate per le operazioni di ricerca. L'API Search può indicizzare un numero qualsiasi di documenti. La App Engine Datastore può essere più appropriato per le applicazioni che devono per recuperare set di risultati molto grandi.
Panoramica
L'API Search si basa su quattro concetti principali: documenti, indici, query e che consentono di analizzare i dati e visualizzare i risultati.
Documenti
Un documento è un oggetto con un ID univoco e un elenco di campi contenenti i dati dell'utente. Ogni campo ha un nome e un tipo. Esistono diversi tipi di campi: identificati dai tipi di valori che contengono:
- Campo atomo: una stringa di caratteri indivisibile.
- Campo di testo: una stringa di testo normale in cui è possibile cercare parola per parola.
- Campo HTML: una stringa contenente tag di markup HTML, solo il testo esterno nei tag di markup.
- Campo numerico: un numero con rappresentazione in virgola mobile.
- Campo data: un oggetto data.
- Campo punto geografico: un oggetto dati con coordinate di latitudine e longitudine.
La dimensione massima di un documento è 1 MB.
Indici
Un indice archivia i documenti per il recupero. Puoi recuperare un singolo documento il suo ID, un intervallo di documenti con ID consecutivi o tutti i documenti di Google. Puoi anche cercare in un indice per recuperare documenti che soddisfano una criteri sui campi e sui relativi valori, specificati come stringa di query. Puoi gestire le impostazioni gruppi di documenti inserendoli in indici separati.
Non c'è limite al numero di documenti in un indice o al numero di che puoi utilizzare. La dimensione totale di tutti i documenti in un singolo indice è è limitato a 10 GB per impostazione predefinita. Gli utenti con il ruolo Amministratore App Engine possono inviare una richiesta dalla console Google Cloud App Engine Search per ingrandire fino a 200 GB.
Query
Per cercare in un indice, devi creare una query contenente una stringa di query ed eventualmente alcune opzioni aggiuntive. Una stringa di query specifica le condizioni per i valori di uno o più campi del documento. Quando cerchi un indice, vengono restituiti solo quelli documenti nell'indice con campi che soddisfano la query.
La query più semplice, a volte chiamata "ricerca globale" è una stringa che contiene solo valori dei campi. Questa ricerca utilizza una stringa per cercare documenti che contengono le parole "rosa" e "acqua":
che cerca i documenti con campi che contengono la data 4 luglio 1776 o campi di testo che includono la stringa "1776-07-04":
Una stringa di query può anche essere più specifica. Può contenere uno o più termini, ciascuno assegnare un nome a un campo e a un vincolo al valore. La forma esatta di un termine dipende dal tipo di campo. Ad esempio, supponendo che esista un campo di testo chiamato "prodotto" e un numero campo denominato "price", ecco un'immagine stringa di query con due termini:
Le opzioni di query, come suggerisce il nome, non sono obbligatorie. Consentono di attivare una serie di funzionalità:
- Controlla quanti documenti vengono restituiti nei risultati della ricerca.
- Specifica quali campi del documento includere nei risultati. L'impostazione predefinita è includere tutti i campi del documento originale. Puoi specificare che I risultati includono solo un sottoinsieme di campi (il documento originale non è interessato).
- Ordina i risultati.
- Creare "campi calcolati" per i documenti con
FieldExpressions
e i campi di testo ridotti snippet. - Supporta la visualizzazione dei risultati di ricerca tramite pagine restituendo solo una parte dei documenti corrispondenti per ogni query (utilizzando offset e cursori)
Ti consigliamo di registrare le stringhe di query nella tua applicazione se vuoi mantenere delle query eseguite.
Risultati di ricerca
Una chiamata al numerosearch()
può restituire solo un numero limitato di documenti corrispondenti.
La ricerca potrebbe trovare più documenti di quelli che possono essere restituiti in una singola chiamata. Ciascuna
ricerca restituisce un'istanza
Results
, che contiene informazioni sul numero di documenti trovati e su come
ne sono stati restituiti molti, insieme all'elenco dei documenti restituiti. Puoi ripetere
la stessa ricerca, utilizzando
cursori
o offset
per recuperare il set completo di documenti corrispondenti.
Materiale di formazione aggiuntivo
Oltre a questa documentazione, puoi leggere corso di formazione in due parti sull'API Search all'indirizzo Google Developer's Academy. Anche se la classe utilizza l'API Python, potresti trovare utile la discussione aggiuntiva dei concetti di ricerca.
Documenti e campi
La classe Document rappresenta i documenti. Ogni documento include un identificatore documento e un elenco di campi.Identificatore documento
Ogni documento in un indice deve avere un identificatore di documento univoco o doc_id
.
L'identificatore può essere utilizzato per recuperare un documento da un indice senza eseguire
una ricerca. Per impostazione predefinita, l'API Search genera automaticamente un doc_id
quando
viene creato un documento. Puoi anche specificare doc_id
personalmente quando
per creare un documento. Un elemento doc_id
deve contenere solo caratteri ASCII visibili e stampabili
(codici ASCII da 33 a 126 inclusi) e non più di 500
caratteri. Un identificatore di documento non può iniziare con un punto esclamativo ("!")
e non può iniziare e terminare con trattini bassi doppi ("__").
Sebbene sia conveniente creare identificatori di documenti univoci leggibili e significativi,
non puoi includere doc_id
in una ricerca. Considera questo scenario: hai un indice con documenti che rappresentano componenti, utilizzando il numero di serie del componente come doc_id
. Sarà molto efficiente recuperare il documento per ogni singola parte, ma sarà impossibile cercare un intervallo di numeri di serie insieme ad altri valori di campo, come la data di acquisto. Il problema viene risolto memorizzando il numero di serie in un campo atom.
Campi documento
Un documento contiene campi con un nome, un tipo e un singolo valore di quel tipo. Due o più campi possono avere lo stesso nome, ma tipi diversi. Per Ad esempio, puoi definire due campi con il nome "age": uno di tipo testo (il valore "ventidue"), l'altra con un tipo di numero (valore 22).
Nomi dei campi
I nomi dei campi sono sensibili alle maiuscole e possono contenere solo caratteri ASCII. Devono iniziare con una lettera e può contenere lettere, numeri o trattini bassi. Nome di un campo non può contenere più di 500 caratteri.
Campi con più valori
Un campo può contenere un solo valore, che deve corrispondere al tipo di campo. I nomi dei campi non devono essere univoci. Un documento può avere più campi con lo stesso nome e lo stesso tipo, per rappresentare un campo con più valori. Tuttavia, i campi di date e numeri con lo stesso nome non possono essere ripetuti. Un documento può anche contenere più campi con lo stesso nome diversi.
Tipi di campo
Esistono tre tipi di campi in cui vengono memorizzate le stringhe di caratteri java.lang.String
.
collettivamente definiti campi stringa:
- Campo di testo: una stringa di lunghezza massima di 1024**2 caratteri.
- Campo HTML: una stringa formattata in HTML con una lunghezza massima di 1024**2 caratteri.
- Campo Atom: una stringa di lunghezza massima di 500 caratteri.
Esistono anche tre tipi di campi per l'archiviazione di dati non testuali:
- Campo numerico: un valore in virgola mobile a doppia precisione compreso tra -2.147.483.647 e 2.147.483.647.
- Campo data: A
java.util.Date
di Google. - Campo punti geografici: un punto sulla Terra descritto da latitudine e longitudine coordinate.
I tipi di campo vengono specificati utilizzando gli enumerati
Field.FieldType
TEXT
, HTML
, ATOM
, NUMBER
, DATE
e GEO_POINT
.
Trattamento speciale dei campi di stringhe e date
Quando un documento con data, testo o I campi HTML vengono aggiunti a un indice; si verificano alcune operazioni speciali. È utile a capire cosa sta succedendo "in background" per utilizzare l'API Search in modo efficace.
Tokenizzazione dei campi stringa
Quando un campo HTML o di testo viene indicizzato, i relativi contenuti vengono tokenizzati. La stringa viene suddivisa in token ogni volta che vengono visualizzati spazi vuoti o caratteri speciali (segni di punteggiatura, segno di cancelletto, barra di sbarramento e così via). L'indice includerà una voce per ogni token. Ciò consente di cercare parole chiave e frasi che comprende solo una parte del valore di un campo. Ad esempio, la ricerca di "scuro" che associa un documento a un campo di testo contenente la stringa "it was a dark and notte tempestosa" e la ricerca di "tempo" corrisponderà a un documento con un campo di testo contenente la stringa "this is a real-time system".
Nei campi HTML, il testo all'interno dei tag di markup non è tokenizzato, quindi un documento con un
Il campo HTML contenente it was a <strong>dark</strong> night
corrisponderà a
cerca "notte", ma non "forte". Se vuoi poter cercare
di markup, memorizzalo in un campo di testo.
I campi di atomi non vengono tokenizzati. Un documento con un campo atomico che ha il valore "maltempo" corrisponderà solo alla ricerca dell'intera stringa "maltempo". it non trova corrispondenze per la ricerca di "non valido" o "meteo" da soli.
Regole di tokenizzazione
Il trattino basso (_) e la e commerciale (&) non suddividono le parole in di token.
Questi caratteri di spaziatura suddividono sempre le parole in token: spazio, ritorno a capo, avanzamento riga, tabulazione orizzontale, tabulazione verticale, a capo di modulo e NULL.
Questi caratteri vengono trattati come punteggiatura e suddivideranno le parole in token:
! " % ( ) * , - | / [ ] ] ^ ` : = > ? @ { } ~ $ I caratteri nella tabella seguente di solito suddividono le parole in token, ma possono essere gestiti in modo diverso a seconda del contesto in cui vengono visualizzate:
Basato su caratteri Regola <
In un campo HTML il valore "minore di" indica l'inizio di un tag HTML che viene ignorato. +
Una stringa composta da uno o più "plus" vengono trattati come parte della parola se compare alla fine della parola (C++). #
L'"hash" è trattato come parte della parola se è preceduta da a, b, c, d, e, f, g, j o x (a# - g# sono note musicali; j# e x# sono linguaggio di programmazione, c# sono entrambi). Se un termine è preceduto da "#" (#google), viene trattato come un hashtag e l'hash diventa parte della parola. '
L'apostrofo è una lettera se precede la lettera "s" seguito da un'interruzione di parola, come in "John's hat". .
Se tra le cifre è presente un punto decimale, questo fa parte di un numero (ovvero del separatore decimale). Può anche essere parte di una parola se usato in un acronimo (A.B.C). -
Il trattino fa parte di una parola se usato in un acronimo (I-B-M). Tutti gli altri caratteri a 7 bit, tranne lettere e numeri ("A-Z", "a-z", "0-9") sono gestiti come punteggiatura e suddividono le parole in token.
Tutto il resto viene analizzato come carattere UTF-8.
Acronimi
La tokenizzazione utilizza regole speciali per riconoscere gli acronimi (stringhe come "I.B.M.", "a-b-c" o "C I A"). Un acronimo è una stringa di singoli caratteri alfabetici, con lo stesso carattere separatore tra tutti i caratteri. I separatori validi sono il punto, il trattino o un numero qualsiasi di spazi. Il carattere separatore viene rimosso dalla stringa quando viene tokenizzato un acronimo. Quindi le stringhe di esempio menzionate sopra diventano i token "ibm", "abc" e "cia". Il testo originale rimane nel campo del documento.
Quando hai a che fare con gli acronimi, tieni presente che:
- Un acronimo non può contenere più di 21 lettere. Una stringa di acronimi valida con più di 21 lettere saranno suddivise in una serie di acronimi, ogni 21 lettere o meno.
- Se le lettere di un acronimo sono separate da spazi, tutte le lettere devono essere lo stesso caso. Gli acronimi creati con punto e trattino possono usare lettere maiuscole e minuscole lettere.
- Quando cerchi un acronimo, puoi inserire la relativa forma canonica (la stringa senza separatori) o l'acronimo con la punteggiatura preceduta dal carattere trattino o il punto (ma non entrambi) tra le lettere. Pertanto, il testo "I.B.M" potrebbe essere recuperato con uno qualsiasi dei termini di ricerca "I-B-M", "I.B.M" o "IBM".
Precisione del campo della data
Quando crei un campo della data in un
documento, imposti il relativo valore su un java.util.Date
.
Ai fini dell'indicizzazione e della ricerca
campo data, qualsiasi componente temporale è
ignorata e la data viene convertita nel numero di giorni a partire dal giorno 1/1/1970 UTC. Questo
significa che anche se il campo Data
può contenere un valore di tempo preciso; una query relativa a una data può specificare solo
valore del campo data nel modulo
yyyy-mm-dd
. Ciò significa anche che l'ordine ordinato
i campi data con la stessa data sono
non ben definiti.
Altre proprietà del documento
Il ranking di un documento è un numero intero positivo che determina il valore predefinito
l'ordine dei documenti restituiti da una ricerca. Per impostazione predefinita, il ranking è impostato su
l'ora di creazione del documento calcolata in secondi dal 1° gennaio,
2011. Puoi impostare esplicitamente il ranking quando crei un documento. È un brutto
di assegnare lo stesso ranking a molti documenti e non si dovrebbe mai
di più di 10.000 documenti di pari livello.
Se specifichi ordinare
opzioni,
puoi utilizzare il ranking come chiave di ordinamento. Tieni presente che quando il ranking viene utilizzato in un ordinamento
espressione
o un'espressione di campo
viene indicato come _rank
.
Impostazioni internazionali specifica la lingua in che i campi sono codificati.
Consulta le
Document
pagina di riferimento della classe per ulteriori dettagli su questi attributi.
Collegamento da un documento ad altre risorse
Puoi utilizzare i campi doc_id
e altri di un documento come link ad altre risorse nella tua applicazione. Ad esempio, se utilizzi
Blobstore che puoi associare
il documento con un blob specifico impostando doc_id
o il valore di un
Campo Atom alla BlobKey dei dati.
Creazione di un documento
Per creare un documento, richiedi un nuovo builder utilizzando
Document.newBuilder()
. Quando l'applicazione ha accesso a un builder, può specificare un'istanza
identificatore del documento e aggiungere campi.
I campi, ad esempio i documenti, vengono creati con un builder. La
Field.newBuilder()
restituisce un generatore di campi che consente di specificare il nome di un campo
valore. Il tipo di campo viene specificato automaticamente scegliendo un insieme specifico
. Ad esempio, per indicare che un campo contiene testo normale, richiama
setText()
Il seguente codice crea un documento con campi che rappresentano un messaggio di benvenuto nel guestbook.
Per accedere ai campi all'interno del documento, utilizza getOnlyField()
:
Utilizzo di un indice
Inserire i documenti in un indice
Quando inserisci un documento in un indice, il documento viene copiato nello spazio di archiviazione permanente e ciascuno dei suoi campi viene indicizzato in base al nome, al tipo e al valore doc_id
.
Il seguente esempio di codice mostra come accedere a un indice e inserire un documento in li annotino. Ecco i passaggi:
- Crea una
IndexSpec
- Crei una
SearchService
- Chiama il numero
SearchService.getIndex()
per creare un'istanza di Index. - Chiama il numero
Index.put()
per aggiungere il documento all'indice.
put()
. Batch put in batch
è più efficiente che aggiungere i documenti uno alla volta.
Quando inserisci un documento in un indice e l'indice contiene già un documento
con lo stesso doc_id
, il nuovo documento sostituisce quello precedente. Nessun avviso è
fornite. Puoi chiamare
Index.get(id)
prima di creare o aggiungere un documento a un indice per verificare se esiste già un
doc_id
specifico.
Tieni presente che la creazione di un'istanza di Index
non garantisce che
dell'indice permanente esistente. Un indice permanente viene creato la prima volta che lo aggiungi un documento con il metodo put
.
Se vuoi verificare se un
esistente esiste prima di iniziare a utilizzarlo, utilizza
SearchService.getIndexes()
.
Aggiornamento dei documenti
Un documento non può essere modificato dopo averlo aggiunto a un indice. Non puoi aggiungere o
rimuovi campi o modifica il valore di un campo. Tuttavia, puoi sostituire il documento
con un nuovo documento con lo stesso doc_id
.
Recupero di documenti per doc_id in corso...
Esistono due modi per recuperare documenti da un indice utilizzando identificatori:- Utilizza
Index.get()
per recuperare un singolo documento tramitedoc_id
. - Utilizza
Index.getRange()
per recuperare un gruppo di documenti consecutivi ordinati perdoc_id
.
Ogni chiamata è mostrata nell'esempio seguente.
Ricerca di documenti in base ai contenuti
Per recuperare documenti da un indice, puoi creare una stringa di query e richiamare
Index.search()
.
La stringa di query può essere passata direttamente
come argomento oppure puoi includere la stringa in una
Query
che viene passato come argomento.
Per impostazione predefinita, search()
restituisce i documenti corrispondenti ordinati in ordine decrescente di ranking. Per controllare il numero di documenti
restituito, la modalità di ordinamento o aggiungere campi calcolati ai risultati, devi
utilizzare un oggetto Query
, che contiene una stringa di query e può anche specificare
altre opzioni di ricerca e ordinamento.
Eliminazione di un indice
Ogni indice è costituito dai documenti indicizzati e da uno schema di indice. Per eliminare un indice: eliminare tutti i documenti in un indice e poi eliminare lo schema dell'indice.
Puoi eliminare i documenti in un indice specificando il doc_id
di
uno o più documenti
da eliminare con il metodo delete()
.
Devi eliminare i documenti in batch per migliorare l'efficienza. Puoi trasferire fino a
200 ID documento alla volta nel metodo delete()
.
delete()
. Batch
le eliminazioni sono più efficienti che gestirle una alla volta.
Coerenza finale
Quando inserisci, aggiorni o elimini un documento in un indice, la modifica si propaga in più data center. Questo di solito avviene rapidamente, ma quando possono variare. L'API Search garantisce la coerenza finale. Ciò significa che in alcuni casi, una ricerca o il recupero di uno o più documenti potrebbe restituire risultati che non riflettono le modifiche più recenti.
Determinare la dimensione di un indice
Un indice archivia i documenti per il recupero. Puoi recuperare un singolo documento tramite il relativo ID, un intervallo di documenti con ID consecutivi o tutti i documenti di un indice. Puoi anche cercare in un indice per recuperare documenti che soddisfano una
criteri sui campi e sui relativi valori, specificati come stringa di query. Puoi gestire gruppi di documenti inserendoli in indici separati. Non c'è limite a
il numero di documenti in un indice o il numero di indici che puoi utilizzare. La
la dimensione totale di tutti i documenti in un singolo indice è limitata a 10 GB per impostazione predefinita
ma possono essere aumentati fino a 200 GB inviando una richiesta dal
App Engine Search della console Google Cloud
. Il metodo
Index.getStorageLimit()
restituisce la dimensione massima consentita di un indice.
Index.getStorageUsage()
è una stima della quantità di spazio di archiviazione utilizzata da un indice. Questo numero è
è una stima perché il sistema di monitoraggio dell'indice non funziona in modo continuo; il
l'utilizzo effettivo viene calcolato periodicamente. Il valore storage_usage
viene regolato tra
i punti di campionamento tenendo conto delle aggiunte ai documenti, ma non delle eliminazioni.
Schemi indice
Ogni indice ha uno schema che mostra tutti i nomi e i tipi di campi che nei documenti che contiene. Non puoi definire uno schema personalmente. Gli schemi vengono gestiti in modo dinamico; vengono aggiornate man mano che vengono aggiunti un indice. Uno schema semplice potrebbe essere simile al seguente, in formato JSON:
{'comment': ['TEXT'], 'date': ['DATE'], 'author': ['TEXT'], 'count': ['NUMBER']}
Ogni chiave nel dizionario è il nome di un campo del documento. Il valore della chiave è un dei tipi di campo utilizzati con il nome di quel campo. Se hai utilizzato lo stesso nome campo con tipi di campi diversi lo schema elenca più di un campo digita il nome di un campo, come in questo esempio:
{'ambiguous-integer': ['TEXT', 'NUMBER', 'ATOM']}
Quando un campo compare in uno schema, non può mai essere rimosso. Non è possibile eliminare un campo, anche se l'indice non contiene più documenti con quel particolare nome campo.
Puoi visualizzare gli schemi per i tuoi indici in questo modo: Tieni presente che una chiamata aGetIndexes()
non può restituire più di 1000 indici. Per recuperare altri indici, chiama il metodo
ripetutamente, utilizzando setStartIndexName()
insieme
GetIndexesRequest.Builder
Uno schema non definisce una "classe" nel senso della programmazione di oggetti. Per quanto riguarda all'API Search, ogni documento è univoco e gli indici possono contenere diversi tipi di documenti. Se vuoi trattare raccolte di oggetti con lo stesso elenco di campi delle istanze di una classe, è un'astrazione che devi in modo forzato nel codice. Ad esempio, puoi assicurarti che tutti i documenti con lo stesso insieme di campi vengano conservati nel proprio indice. Lo schema dell'indice può essere visto come definizione della classe e ogni documento nell'indice è un'istanza per la classe.
Visualizzazione degli indici nella console Google Cloud
Nella console Google Cloud, puoi visualizzare le informazioni sul tuo degli indici dell'applicazione e dei documenti che contengono. Se fai clic sul nome di un indice, vengono visualizzati i documenti che contiene. Vedrai tutti i campi schema definiti per l'indice; per ogni documento con un campo con questo nome, vedrai il valore del campo. Puoi anche eseguire query sui dati dell'indice direttamente dalla console.
Quote dell'API Search
L'API Search prevede diverse quote gratuite:
Risorsa o chiamata API | Quota gratuita |
---|---|
Capacità di archiviazione totale (documenti e indici) | 0,25 GB |
Query | 1000 query al giorno |
Aggiunta di documenti agli indici | 0,01 GB al giorno |
L'API Search impone questi limiti per garantire l'affidabilità del servizio. Si applicano sia alle app gratuite che a quelle a pagamento:
Risorsa | Quota di sicurezza |
---|---|
Utilizzo massimo delle query | 100 minuti aggregati di tempo di esecuzione delle query al minuto |
Numero massimo di documenti aggiunti o eliminati | 15.000 al minuto |
Dimensione massima per indice (numero illimitato di indici consentiti) | 10 GB |
L'utilizzo dell'API viene conteggiato in modi diversi a seconda del tipo di chiamata:
Index.search()
: ogni chiamata API viene conteggiata come una query; è il tempo di esecuzione equivalente alla latenza della chiamata.Index.put()
: quando aggiungi documenti agli indici, le dimensioni di ogni documento e il numero di documenti vengono conteggiati ai fini della quota di indicizzazione.- Tutte le altre chiamate all'API Search vengono conteggiate in base al numero di operazioni che
comporta:
SearchService.getIndexes()
: viene conteggiata un'operazione per ogni indice effettivamente restituito o un'operazione se non viene restituito nulla.Index.get()
eIndex.getRange()
1 operazione conteggiata per ogni documento effettivamente restituito oppure 1 operazione se non viene restituito nulla.Index.delete()
: 1 operazione conteggiata per ogni documento nella richiesta o 1 operazione se la richiesta è vuota.
La quota per la velocità effettiva delle query è imposta in modo che un singolo utente non possa eseguire la monopolizzazione il servizio di ricerca. Poiché le query possono essere eseguite contemporaneamente, ogni applicazione può eseguire query che consumano fino a 100 minuti di tempo di esecuzione a un minuto di tempo. Se esegui molte query brevi, probabilmente non raggiungeranno questo limite. Una volta superata la quota, le query successive non riusciranno fino alla sezione temporale successiva, quando la quota verrà ripristinata. La quota non è rigorosamente in porzioni da un minuto; una variante del l'algoritmo leaky bucket viene utilizzato controllare la larghezza di banda della ricerca con incrementi di cinque secondi.
Per ulteriori informazioni sulle quote, consulta la pagina Quote . Quando un'app tenta di superare questi valori, viene restituito un errore di quota insufficiente restituito.
Tieni presente che, anche se questi limiti vengono applicati al minuto, nella console i totali giornalieri di ognuna. I clienti con assistenza Silver, Gold o Platinum possono richiedere limiti di velocità effettiva più elevati contattando il rappresentante dell'assistenza.
Prezzi dell'API Search
All'utilizzo che supera le quote gratuite vengono applicati i seguenti costi:
Risorsa | Costo |
---|---|
Capacità di archiviazione totale (documenti e indici) | $0,18 per GB al mese |
Query | 0,50 $ per 10.000 query |
Indicizzazione dei documenti disponibili per la ricerca | 2,00 $ per GB |
Puoi trovare ulteriori informazioni sui prezzi nella pagina Prezzi.