Pacchetto google.golang.org/appengine/search (v1.6.8)

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

var Done = errors.New("search: query has no more results")

Il valore "Fine" viene restituito al termine dell'iterazione della query.

Funzioni

LoadStruct funzione 

func LoadStruct(dst interface{}, f []Field) error

LoadStruct carica i campi da f a dst. dst deve essere un puntatore struct.

Atomo

type Atom string

Atom è un campo documento i cui contenuti sono indicizzati come una singola stringa indivisibile.

Cursor

type Cursor string

Il 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

type ErrFacetMismatch struct {
	StructType reflect.Type
	FacetName  string
	Reason     string
}

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() string

Mancata corrispondenza campo err

type ErrFieldMismatch struct {
	FieldName string
	Reason    string
}

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() string

Facet

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) FacetSearchOption

AutoFacetDiscovery 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{}) FacetSearchOption

FacetDiscovery 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) FacetSearchOption

FacetDocumentdepth 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 

func SaveStruct(src interface{}) ([]Field, error)

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 []Field

FieldList converte un campo []Field per implementare FieldLoadSaver.

carica funzione (*FieldList) 

func (l *FieldList) Load(f []Field, _ *DocumentMetadata) error

Carica 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 string

HTML è 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 

func Open(name string) (*Index, error)

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 

func (x *Index) Delete(c context.Context, id string) error

Il pulsante Elimina elimina un documento dall'indice.

funzione (*Indice) DeleteMulti 

func (x *Index) DeleteMulti(c context.Context, ids []string) error

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 

func (x *Index) Get(c context.Context, id string, dst interface{}) error

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) *Iterator

L'elenco elenca tutti i documenti in un indice. I documenti vengono restituiti in ordine ID crescente.

func (*Indice) Put 

func (x *Index) Put(c context.Context, id string, src interface{}) (string, error)

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 

func (x *Index) PutMulti(c context.Context, ids []string, srcs []interface{}) ([]string, error)

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.

func (x *Index) Search(c context.Context, query string, opts *SearchOptions) *Iterator

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) 

func (t *Iterator) Count() int

Il conteggio restituisce un'approssimazione del numero di documenti corrispondenti alla query. È valido solo per richiamare gli iteratori restituiti dalla Ricerca.

Cursore func (*iteratore) 

func (t *Iterator) Cursor() Cursor

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 

func (t *Iterator) Next(dst interface{}) (string, error)

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 

func AtLeast(min float64) Range

Almeno restituisce un intervallo che corrisponde a qualsiasi valore maggiore o uguale a min.

funzione Minore 

func LessThan(max float64) Range

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.