Ricerca pacchetti fornisce un client per il servizio di ricerca di App Engine.
Operazioni di base
Gli indici contengono documenti. Ogni indice è identificato dal suo nome: una stringa ASCII leggibile.
All'interno di un indice, i documenti sono associati a un ID, che è anche una stringa ASCII leggibile. I contenuti di un documento sono una mappatura dai nomi dei campi sensibili alle maiuscole ai valori. I tipi validi per i valori dei campi sono:
- stringa,
- search.Atom,
- search.HTML,
- time.Time (memorizzati con precisione in un millisecondo),
- float64 (valore compreso tra -2.147.483.647 e 2.147.483.647 inclusi),
- appengine.GeoPoint.
I metodi Get e Put in un indice consentono di caricare e salvare un documento. I contenuti di un documento sono generalmente rappresentati da un puntatore struct.
Esempio di codice:
type Doc struct {
Author string
Comment string
Creation time.Time
}
index, err := search.Open("comments")
if err != nil {
return err
}
newID, err := index.Put(ctx, "", &Doc{
Author: "gopher",
Comment: "the truth of the matter",
Creation: time.Now(),
})
if err != nil {
return err
}
Un singolo documento può essere recuperato dal suo ID. Passa uno struct di destinazione per arrivare a conservare il documento risultante.
var doc Doc
err := index.Get(ctx, id, &doc)
if err != nil {
return err
}
Cercare ed elencare i documenti
Gli indici hanno due metodi per recuperare più documenti contemporaneamente: Ricerca ed Elenco.
La ricerca di una query in un indice genererà un iteratore. Come per un iteratore del datastore del pacchetto, passa uno struct di destinazione a Avanti per decodificare il risultato successivo. In seguito, all'esaurimento dell'iteratore verrà restituito il valore Fatto.
for t := index.Search(ctx, "Comment:truth", nil); ; {
var doc Doc
id, err := t.Next(&doc)
if err == search.Done {
break
}
if err != nil {
return err
}
fmt.Fprintf(w, "%s -> %#v\n", id, doc)
}
La ricerca utilizza una query in formato stringa per determinare quali documenti restituire. La query può essere semplice, ad esempio una singola parola per trovare una corrispondenza, oppure complessa. Il linguaggio di query è descritto all'indirizzo https://cloud.google.com/appengine/docs/standard/go/search/query_strings
La funzione di ricerca utilizza anche uno struct facoltativo SearchOptions che offre un controllo molto maggiore su come vengono calcolati e restituiti i risultati.
Elenco chiamate per eseguire l'iterazione di tutti i documenti in un indice.
for t := index.List(ctx, nil); ; {
var doc Doc
id, err := t.Next(&doc)
if err == search.Done {
break
}
if err != nil {
return err
}
fmt.Fprintf(w, "%s -> %#v\n", id, doc)
}
Campi e facet
I contenuti di un documento possono essere rappresentati in vari tipi. In genere si tratta di puntatori struct, ma possono anche essere rappresentati da qualsiasi tipo che implementi l'interfaccia FieldLoadSaver. FieldLoadSaver consente di impostare i metadati per il documento con il tipo DocumentMetadata. I puntatori struct sono più digitati e più facili da usare, mentre i FieldLoadSaver sono più flessibili.
I contenuti di un documento possono essere espressi in due modi: campi e facet.
I campi sono il metodo più comune per fornire contenuti per i documenti. I campi possono memorizzare dati in più tipi e possono essere abbinati nelle ricerche utilizzando le stringhe di query.
I facet consentono di allegare informazioni relative alle categorie a un documento. Gli unici tipi validi per i facet sono search.Atom e float64. I facet consentono ai risultati di ricerca di contenere riepiloghi delle categorie corrispondenti in una ricerca e di limitare le ricerche in modo che corrispondano solo a categorie specifiche.
Per impostazione predefinita, per i puntatori struct, tutti i campi dello struct vengono utilizzati come campi del documento e il nome del campo utilizzato è lo stesso dello struct (e quindi deve iniziare con una lettera maiuscola). I campi struct possono avere un tag search:"name,options". Il nome deve iniziare con una lettera ed essere composto solo da caratteri di parole. Il nome di un tag "-" indica che il campo verrà ignorato. Se l'opzione è "facet", il campo struct verrà utilizzato come
facet del documento. Se l'opzione è "", la virgola potrebbe essere omessa. Non ci sono altre opzioni riconosciute.
Esempio di codice:
// A and B are renamed to a and b.
// A, C and I are facets.
// D's tag is equivalent to having no tag at all (E).
// F and G are ignored entirely by the search package.
// I has tag information for both the search and json packages.
type TaggedStruct struct {
A float64 `search:"a,facet"`
B float64 `search:"b"`
C float64 `search:",facet"`
D float64 `search:""`
E float64
F float64 `search:"-"`
G float64 `search:"-,facet"`
I float64 `search:",facet" json:"i"`
}
Interfaccia FieldLoadSaver
I contenuti di un documento possono anche essere rappresentati da qualsiasi tipo che implementa l'interfaccia FieldLoadSaver. Questo tipo può essere un puntatore struct, ma non deve esserlo. Il pacchetto di ricerca chiama Carica durante il caricamento dei contenuti del documento e Salva quando li salva. Oltre a una sezione di campi, i metodi Carica e Salva utilizzano anche il tipo DocumentMetadata per fornire informazioni aggiuntive su un documento (come il ranking o l'insieme di facet). Questa interfaccia può essere utilizzata per ricavare campi non memorizzati, verificare di campi o impostare lingue specifiche per i campi stringa e HTML.
Esempio di codice:
type CustomFieldsExample struct {
// Item's title and which language it is in.
Title string
Lang string
// Mass, in grams.
Mass int
}
func (x *CustomFieldsExample) Load(fields []search.Field, meta *search.DocumentMetadata) error {
// Load the title field, failing if any other field is found.
for _, f := range fields {
if f.Name != "title" {
return fmt.Errorf("unknown field %q", f.Name)
}
s, ok := f.Value.(string)
if !ok {
return fmt.Errorf("unsupported type %T for field %q", f.Value, f.Name)
}
x.Title = s
x.Lang = f.Language
}
// Load the mass facet, failing if any other facet is found.
for _, f := range meta.Facets {
if f.Name != "mass" {
return fmt.Errorf("unknown facet %q", f.Name)
}
m, ok := f.Value.(float64)
if !ok {
return fmt.Errorf("unsupported type %T for facet %q", f.Value, f.Name)
}
x.Mass = int(m)
}
return nil
}
func (x *CustomFieldsExample) Save() ([]search.Field, *search.DocumentMetadata, error) {
fields := []search.Field{
{Name: "title", Value: x.Title, Language: x.Lang},
}
meta := &search.DocumentMetadata{
Facets: {
{Name: "mass", Value: float64(x.Mass)},
},
}
return fields, meta, nil
}
Variabili
ErrInvalidDocumentType, ErrNoSuchDocument, ErrTooManyDocuments
var (
// ErrInvalidDocumentType is returned when methods like Put, Get or Next
// are passed a dst or src argument of invalid type.
ErrInvalidDocumentType = errors.New("search: invalid document type")
// ErrNoSuchDocument is returned when no document was found for a given ID.
ErrNoSuchDocument = errors.New("search: no such document")
// ErrTooManyDocuments is returned when the user passes too many documents to
// PutMulti or DeleteMulti.
ErrTooManyDocuments = fmt.Errorf("search: too many documents given to put or delete (max is %d)", maxDocumentsPerPutDelete)
)Fine
Il valore "Fine" viene restituito al termine dell'iterazione della query.
Funzioni
LoadStruct funzione
LoadStruct carica i campi da f a dst. dst deve essere un puntatore struct.
Atomo
type Atom stringAtom è un campo documento i cui contenuti sono indicizzati come una singola stringa indivisibile.
Cursor
type Cursor stringIl cursore rappresenta la posizione di un iteratore.
Il valore stringa di un cursore è sicuro per il web. Può essere salvata e ripristinata per un utilizzo successivo.
Metadati Documento
type DocumentMetadata struct {
// Rank is an integer specifying the order the document will be returned in
// search results. If zero, the rank will be set to the number of seconds since
// 2011-01-01 00:00:00 UTC when being Put into an index.
Rank int
// Facets is the set of facets for this document.
Facets []Facet
}DocumentMetadata è uno struct contenente informazioni che descrivono un determinato documento.
ErrFacet Mancata corrispondenza
ErrFacetMismatch viene restituito quando un facet deve essere caricato in un tipo diverso da quello da cui è stato archiviato oppure quando un campo risulta mancante o non esportato nello struct di destinazione. StructType è il tipo di struct a cui punta l'argomento di destinazione passato a Iterator.Next.
Errore funzione (*ErrFacetMismatch)
func (e *ErrFacetMismatch) Error() stringMancata corrispondenza campo err
ErrFieldMismatch viene restituito quando un campo deve essere caricato in un campo diverso da quello da cui è stato archiviato o quando un campo non è presente o non è esportato nello struct di destinazione.
Errore funzione (*ErrFieldMismatch)
func (e *ErrFieldMismatch) Error() stringFacet
type Facet struct {
// Name is the facet name. A valid facet name matches /[A-Za-z][A-Za-z0-9_]*/.
// A facet name cannot be longer than 500 characters.
Name string
// Value is the facet value.
//
// When being used in documents (for example, in
// DocumentMetadata.Facets), the valid types are:
// - search.Atom,
// - float64.
//
// When being used in SearchOptions.Refinements or being returned
// in FacetResult, the valid types are:
// - search.Atom,
// - search.Range.
Value interface{}
}Facet è una coppia nome/valore utilizzata per aggiungere informazioni categoriche a un documento.
FacetResult
type FacetResult struct {
Facet
// Count is the number of times this specific facet and value appeared in the
// matching documents.
Count int
}FacetResult rappresenta il numero di volte in cui un determinato facet e valore sono visualizzati nei documenti corrispondenti a una richiesta di ricerca.
Opzione di ricerca facet
type FacetSearchOption interface {
// contains filtered or unexported methods
}FacetSearchOption controlla quali informazioni dei facet vengono restituite nei risultati di ricerca.
funzione AutoFacetDiscovery
func AutoFacetDiscovery(facetLimit, valueLimit int) FacetSearchOptionAutoFacetDiscovery restituisce un'opzione FacetSearchOption che consente il rilevamento automatico dei facet per la ricerca. Il rilevamento automatico dei facet cerca i facet che appaiono più spesso nell'aggregato nei documenti corrispondenti.
Il numero massimo di facet restituiti è controllato da facetLimit, mentre il numero massimo di valori per facet da facetLimit. Un limite pari a zero indica che deve essere utilizzato un limite predefinito.
funzione FacetDiscovery
func FacetDiscovery(name string, value ...interface{}) FacetSearchOptionFacetDiscovery restituisce un'opzione FacetSearchOption che seleziona un facet da restituire con i risultati di ricerca. Per impostazione predefinita, verranno restituiti i valori che si verificano più spesso per quel facet. Tuttavia, puoi anche specificare un elenco di particolari Atom o intervalli specifici da restituire.
funzione FacetDocumentdepth
func FacetDocumentDepth(depth int) FacetSearchOptionFacetDocumentdepth restituisce un'opzione FacetSearchOption che controlla il numero di documenti da valutare durante la preparazione dei risultati dei facet.
Campo
type Field struct {
// Name is the field name. A valid field name matches /[A-Za-z][A-Za-z0-9_]*/.
Name string
// Value is the field value. The valid types are:
// - string,
// - search.Atom,
// - search.HTML,
// - time.Time (stored with millisecond precision),
// - float64,
// - GeoPoint.
Value interface{}
// Language is a two-letter ISO 639-1 code for the field's language,
// defaulting to "en" if nothing is specified. It may only be specified for
// fields of type string and search.HTML.
Language string
// Derived marks fields that were calculated as a result of a
// FieldExpression provided to Search. This field is ignored when saving a
// document.
Derived bool
}Il campo è una coppia nome/valore. Il documento di un indice di ricerca può essere caricato e salvato come una sequenza di campi.
funzione SaveStruct
SaveStruct restituisce i campi da src come sezione di Field. L'src deve essere un puntatore struct.
FieldExpression
type FieldExpression struct {
// Name is the name to use for the computed field.
Name string
// Expr is evaluated to provide a custom content snippet for each document.
// See https://cloud.google.com/appengine/docs/standard/go/search/options for
// the supported expression syntax.
Expr string
}FieldExpression definisce un'espressione personalizzata da valutare per ogni risultato.
Elenco campi
type FieldList []FieldFieldList converte un campo []Field per implementare FieldLoadSaver.
carica funzione (*FieldList)
func (l *FieldList) Load(f []Field, _ *DocumentMetadata) errorCarica carica tutti i campi forniti in l. Non reimposta prima *l su una sezione vuota.
func (*FieldList) Salva
func (l *FieldList) Save() ([]Field, *DocumentMetadata, error)Salva restituisce tutti i campi come una sezione di Campi.
FieldLoadSaver
type FieldLoadSaver interface {
Load([]Field, *DocumentMetadata) error
Save() ([]Field, *DocumentMetadata, error)
}FieldLoadSaver può essere convertito da e in una sezione di campi con metadati del documento aggiuntivi.
HTML
type HTML stringHTML è un campo documento i cui contenuti sono indicizzati come HTML. Solo i nodi di testo sono indicizzati: "foobar" verrà considerato come "foobar".
Indice
type Index struct {
// contains filtered or unexported fields
}L'indice è un indice di documenti.
funzione Apri
Apri apre l'indice con il nome specificato. L'indice viene creato se non esiste già.
Il nome è una stringa ASCII leggibile. Non deve contenere spazi e non deve iniziare con "!".
funzione (*Indice) Elimina
Il pulsante Elimina elimina un documento dall'indice.
funzione (*Indice) DeleteMulti
DeleteMulti elimina più documenti dall'indice.
L'errore restituito potrebbe essere un'istanza di appengine.MultiError, nel qual caso avrà le stesse dimensioni di src e i singoli errori al suo interno corrisponderanno agli elementi in src.
func (*Indice) Get
Get carica il documento con l'ID specificato in dst.
L'ID è una stringa ASCII leggibile. Non deve essere vuoto, non deve contenere spazi vuoti e non deve iniziare con "!".
dst deve essere un puntatore struct non null o implementare l'interfaccia FieldLoadSaver.
ErrFieldMismatch viene restituito quando un campo deve essere caricato in un tipo diverso da quello da cui è stato archiviato oppure quando un campo risulta mancante o non esportato nello struct di destinazione. ErrFieldMismatch viene restituito solo se dst è un puntatore struct. Spetta al destinatario decidere se questo errore è irreversibile, recuperabile o ignorabile.
Elenco funzioni (*Indice)
func (x *Index) List(c context.Context, opts *ListOptions) *IteratorL'elenco elenca tutti i documenti in un indice. I documenti vengono restituiti in ordine ID crescente.
func (*Indice) Put
Inserimento dei salvataggi src nell'indice. Se l'ID è vuoto, viene allocato un nuovo ID, che viene restituito dal servizio. Se l'ID non è vuoto, qualsiasi voce di indice esistente per quell'ID viene sostituita.
L'ID è una stringa ASCII leggibile. Non deve contenere spazi e non deve iniziare con "!".
src deve essere un puntatore struct non null o implementare l'interfaccia FieldLoadSaver.
funzione (*Indice) PutMulti
PutMulti è simile a Put, ma è più efficiente per aggiungere più documenti all'indice contemporaneamente.
Puoi aggiungere fino a 200 documenti alla volta. Se tenti di aggiungerne altri, viene restituito ErrTooManyDocuments.
Gli ID possono essere una sezione vuota (il che significa che verranno assegnati nuovi ID per ogni documento aggiunto) o una sezione delle stesse dimensioni degli elementi src.
L'errore potrebbe essere un'istanza di appengine.MultiError, nel qual caso avrà le stesse dimensioni di src e i singoli errori al suo interno corrisponderanno agli elementi in src.
ricerca func (*indice)
La ricerca cerca nell'indice la query specificata.
Iterator
type Iterator struct {
// contains filtered or unexported fields
}L'iteratore è il risultato della ricerca di una query in un indice o dell'elenco di un indice.
Conteggio funzioni (*iteratori)
Il conteggio restituisce un'approssimazione del numero di documenti corrispondenti alla query. È valido solo per richiamare gli iteratori restituiti dalla Ricerca.
Cursore func (*iteratore)
Il cursore restituisce il cursore associato al documento corrente (ovvero il documento restituito più di recente da una chiamata a Avanti).
Se passi questo cursore in una chiamata futura alla Ricerca, i risultati verranno avviati con il primo documento dopo il documento corrente.
funzione (*iteratore) Facet
func (t *Iterator) Facets() ([][]FacetResult, error)Facet restituisce i facet che si trovano all'interno dei risultati di ricerca, se sono stati richiesti facet in Opzioni di ricerca.
funzione (*iteratore) Avanti
Quindi restituisce l'ID del risultato successivo. Quando non ci sono altri risultati, viene restituito l'errore "Fine".
dst deve essere un puntatore struct non null, implementare l'interfaccia FieldLoadSaver o essere un valore di interfaccia null. Se viene fornito un dst diverso da zero, verrà compilato con i campi indicizzati. dst viene ignorato se questo iteratore è stato creato con un'opzione IDOnly.
ListOptions
type ListOptions struct {
// StartID is the inclusive lower bound for the ID of the returned
// documents. The zero value means all documents will be returned.
StartID string
// Limit is the maximum number of documents to return. The zero value
// indicates no limit.
Limit int
// IDsOnly indicates that only document IDs should be returned for the list
// operation; no document fields are populated.
IDsOnly bool
}ListOptions sono le opzioni per elencare i documenti in un indice. Passare un valore null *ListOptions equivale a utilizzare i valori predefiniti.
Intervallo
type Range struct {
Start, End float64
}L'intervallo rappresenta un intervallo numerico con inizio e fine inclusivi inclusi. L'inizio può essere specificato come math.Inf(-1) per indicare che non esiste un valore minimo, mentre la fine può essere specificata in modo simile come math.Inf(1); almeno uno tra i valori di inizio o fine deve essere un numero finito.
almeno func
Almeno restituisce un intervallo che corrisponde a qualsiasi valore maggiore o uguale a min.
funzione Minore
MenoThan restituisce un intervallo che corrisponde a un valore inferiore a max.
Scorer
type Scorer interface {
// contains filtered or unexported methods
}Un Scorer definisce il modo in cui viene assegnato un punteggio a un documento.
MatchScorer, RescoringMatchScorer
var (
// MatchScorer assigns a score based on term frequency in a document.
MatchScorer Scorer = enumScorer{pb.ScorerSpec_MATCH_SCORER}
// RescoringMatchScorer assigns a score based on the quality of the query
// match. It is similar to a MatchScorer but uses a more complex scoring
// algorithm based on match term frequency and other factors like field type.
// Please be aware that this algorithm is continually refined and can change
// over time without notice. This means that the ordering of search results
// that use this scorer can also change without notice.
RescoringMatchScorer Scorer = enumScorer{pb.ScorerSpec_RESCORING_MATCH_SCORER}
)Opzioni di ricerca
type SearchOptions struct {
// Limit is the maximum number of documents to return. The zero value
// indicates no limit.
Limit int
// IDsOnly indicates that only document IDs should be returned for the search
// operation; no document fields are populated.
IDsOnly bool
// Sort controls the ordering of search results.
Sort *SortOptions
// Fields specifies which document fields to include in the results. If omitted,
// all document fields are returned. No more than 100 fields may be specified.
Fields []string
// Expressions specifies additional computed fields to add to each returned
// document.
Expressions []FieldExpression
// Facets controls what facet information is returned for these search results.
// If no options are specified, no facet results will be returned.
Facets []FacetSearchOption
// Refinements filters the returned documents by requiring them to contain facets
// with specific values. Refinements are applied in conjunction for facets with
// different names, and in disjunction otherwise.
Refinements []Facet
// Cursor causes the results to commence with the first document after
// the document associated with the cursor.
Cursor Cursor
// Offset specifies the number of documents to skip over before returning results.
// When specified, Cursor must be nil.
Offset int
// CountAccuracy specifies the maximum result count that can be expected to
// be accurate. If zero, the count accuracy defaults to 20.
CountAccuracy int
}Opzioni di ricerca sono le opzioni per la ricerca in un indice. Passare un valore pari a zero *SearchOptions equivale a utilizzare i valori predefiniti.
SortExpression
type SortExpression struct {
// Expr is evaluated to provide a sorting value for each document.
// See https://cloud.google.com/appengine/docs/standard/go/search/options for
// the supported expression syntax.
Expr string
// Reverse causes the documents to be sorted in ascending order.
Reverse bool
// The default value to use when no field is present or the expresion
// cannot be calculated for a document. For text sorts, Default must
// be of type string; for numeric sorts, float64.
Default interface{}
}SortExpression definisce una dimensione singola per l'ordinamento di un documento.
SortOptions
type SortOptions struct {
// Expressions is a slice of expressions representing a multi-dimensional
// sort.
Expressions []SortExpression
// Scorer, when specified, will cause the documents to be scored according to
// search term frequency.
Scorer Scorer
// Limit is the maximum number of objects to score and/or sort. Limit cannot
// be more than 10,000. The zero value indicates a default limit.
Limit int
}SortOptions controlla l'ordine e il punteggio dei risultati di ricerca.