Das Paket "search" bietet einen Client für den Suchdienst von App Engine.
Grundlegende Vorgänge
Indexe enthalten Dokumente. Jeder Index wird durch seinen Namen, eine für den Menschen lesbare ASCII-Zeichenfolge, identifiziert.
In einem Index sind Dokumente mit einer ID verknüpft, die auch eine für Menschen lesbare ASCII-Zeichenfolge ist. Der Inhalt eines Dokuments ist eine Zuordnung von Feldnamen, bei denen die Groß- und Kleinschreibung berücksichtigt wird, zu Werten. Gültige Typen für Feldwerte sind:
- String,
- search.Atom,
- search.HTML,
- time.Time (gespeichert mit einer Genauigkeit von einer Millisekunde),
- float64 (Wert zwischen -2.147.483.647 und 2.147.483.647 inklusive),
- appengine.GeoPoint
Die Methoden "Get" und "Put" in einem Index laden und speichern ein Dokument. Der Inhalt eines Dokuments wird normalerweise durch einen Strukturzeiger dargestellt.
Beispielcode:
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 }
Ein einzelnes Dokument kann anhand seiner ID abgerufen werden. Übergeben Sie eine Zielstruktur an "Get", um das daraus resultierende Dokument zu halten.
var doc Doc err := index.Get(ctx, id, &doc) if err != nil { return err }
Dokumente suchen und auflisten
Indexe haben zwei Methoden, um mehrere Dokumente gleichzeitig abzurufen: "Search" und "List".
Die Suche nach einem Index für eine Abfrage führt zu einem Iterator. Wie bei einem Iterator aus dem Paketdatenspeicher übergeben Sie eine Zielstruktur an "Next", um das nächste Ergebnis zu decodieren. "Next" gibt "Done" zurück, wenn der Iterator erschöpft ist.
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) }
Die Suche ermittelt anhand einer Stringabfrage, welche Dokumente zurückgegeben werden. Eine Abfrage kann einfach sein, z. B. ein einzelnes Wort, das übereinstimmen muss, oder sie kann komplex sein. Die Abfragesprache wird unter https://cloud.google.com/appengine/docs/standard/go/search/query_strings beschrieben.
"Search" verwendet auch eine optionale "SearchOptions"-Struktur, die mehr Kontrolle darüber bietet, wie Ergebnisse berechnet und zurückgegeben werden.
Rufen Sie "List" auf, um über alle Dokumente in einem Index zu iterieren.
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) }
Felder und Attribute
Der Inhalt eines Dokuments kann durch eine Vielzahl von Typen dargestellt werden. Dies sind normalerweise Strukturzeiger, sie können jedoch auch durch einen anderen Typ dargestellt werden, der die "FieldLoadSaver"-Schnittstelle implementiert. Mit "FieldLoadSaver" können Metadaten für das Dokument mit dem Typ "DocumentMetadata" festgelegt werden. Strukturzeiger sind stärker typisiert und einfacher zu verwenden; "FieldLoadSavers" sind hingegen flexibler.
Der Inhalt eines Dokuments kann auf zwei Arten ausgedrückt werden: durch Felder und Attribute.
Felder sind die gebräuchlichste Art, Inhalte für Dokumente anzubieten. Felder können Daten in mehreren Typen speichern und bei Suchvorgängen durch Abfragestrings abgeglichen werden.
Attribute bieten eine Möglichkeit, Kategoriedaten an ein Dokument anzuhängen. Die einzigen gültigen Typen für Attribute sind search.Atom und Float64. Wenn Sie möchten, dass in den Suchergebnissen die Zusammenfassungen von übereinstimmenden Kategorien in einer Suche enthalten sind, verwenden Sie Attribute. Mit Attributen können Sie die Suchvorgänge auch auf bestimmte Kategorien beschränken.
Standardmäßig werden für die Strukturzeiger alle Strukturfelder als Dokumentfelder verwendet. Der verwendete Feldname ist dabei der gleiche wie in der Struktur und muss daher mit einem Großbuchstaben beginnen. Struct-Felder können ein search:"name,options"-Tag haben. Der Name muss mit einem Buchstaben beginnen und darf nur aus Wortzeichen bestehen. Der Tag-Name "-" bedeutet, dass das Feld ignoriert wird. Wenn für die Optionen "facet" angegeben ist, wird das Feld "struct" als Dokumentattribut verwendet. Wenn für die Optionen "" angegeben ist, kann das Komma weggelassen werden. Andere anerkannte Optionen gibt es nicht.
Beispielcode:
// 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"` }
Schnittstelle "FieldLoadSaver"
Der Inhalt eines Dokuments kann auch durch einen beliebigen Typ repräsentiert werden, der die Schnittstelle "FieldLoadSaver" implementiert. Dieser Typ kann ein Strukturzeiger sein, muss es aber nicht. Das Paket "Search" ruft "Load" auf, wenn der Inhalt des Dokuments geladen wird, und "Save", wenn er gespeichert wird. Zusätzlich zu einem Segment von Feldern verwenden die Methoden "Load" und "Save" auch den Typ "DocumentMetadata", um weitere Informationen zu einem Dokument, z. B. seinen Rang oder sein Attributset, zu liefern. Diese Schnittstelle lässt sich dazu verwenden, nicht gespeicherte Felder abzuleiten, Felder zu überprüfen oder bestimmte Sprachen für String- und HTML-Felder festzulegen.
Beispielcode:
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 }
Variablen
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)
)Fertig
"Done" wird zurückgegeben, wenn eine Abfrageiteration abgeschlossen wurde.
Funktionen
func LoadStruct
"LoadStruct" lädt die Felder von "f" nach "dst". "dst" muss ein Strukturzeiger sein.
Atom
type Atom string"Atom" ist ein Dokumentfeld, dessen Inhalt als einzelner unteilbarer String indiziert wird.
Cursor
type Cursor string"Cursor" stellt die Position eines Iterators dar.
Der Stringwert eines Cursors ist websicher. Er kann gespeichert und für die spätere Verwendung wiederhergestellt werden.
DocumentMetadata
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" ist eine Struktur, die Informationen zur Beschreibung eines bestimmten Dokuments enthält.
ErrFacetMismatch
"ErrFieldMismatch" wird zurückgegeben, wenn ein Feld in einen anderen Typ geladen werden soll als jenem, aus dem es gespeichert wurde, wenn ein Feld fehlt oder in der Zielstruktur nicht exportiert wurde. "StructType" ist der Typ der Struktur, auf die vom Zielargument gezeigt wird, das an "Iterator.Next" übergeben wird.
func (*ErrFacetMismatch) Error
func (e *ErrFacetMismatch) Error() stringErrFieldMismatch
"ErrFieldMismatch" wird zurückgegeben, wenn ein Feld in einen anderen Typ geladen werden soll als den, aus dem es gespeichert wurde, oder wenn ein Feld fehlt oder in der Zielstruktur nicht exportiert wurde.
func (*ErrFieldMismatch) Error
func (e *ErrFieldMismatch) Error() stringAttribut
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" umfasst ein Name/Wert-Paar, um einem Dokument Kategoriedaten hinzuzufügen.
FacetResult
type FacetResult struct {
Facet
// Count is the number of times this specific facet and value appeared in the
// matching documents.
Count int
}"FacetResult" stellt die Häufigkeit dar, mit der ein bestimmtes Attribut und ein bestimmter Wert, die einer Suchanfrage entsprechen, in den Dokumenten angezeigt wurden.
FacetSearchOption
type FacetSearchOption interface {
// contains filtered or unexported methods
}"FacetSearchOption" bestimmt, welche Attributinformationen in den Suchergebnissen zurückgegeben werden.
func AutoFacetDiscovery
func AutoFacetDiscovery(facetLimit, valueLimit int) FacetSearchOption"AutoFacetDiscovery" gibt eine "FacetSearchOption" zurück, die die automatische Attributerkennung für die Suche aktiviert. Bei der automatischen Attributerkennung werden die Attribute gesucht, die am häufigsten in der Zusammenfassung in den übereinstimmenden Dokumenten angezeigt werden.
Die maximale Anzahl zurückgegebener Attribute wird durch "facetLimit" festgelegt. Die maximale Anzahl der Werte pro Attribut wird durch "valueLimit" bestimmt. Ein Limit von null gibt an, dass das Standardlimit verwendet werden soll.
func FacetDiscovery
func FacetDiscovery(name string, value ...interface{}) FacetSearchOption"FacetDiscovery" gibt eine "FacetSearchOption" zurück, die ein Attribut auswählt, das mit den Suchergebnissen zurückgegeben werden soll. Standardmäßig werden die am häufigsten auftretenden Werte für dieses Attribut zurückgegeben. Sie können jedoch auch eine Liste bestimmter Atome oder bestimmter Bereiche angeben, die zurückgegeben werden soll.
func FacetDocumentDepth
func FacetDocumentDepth(depth int) FacetSearchOption"FacetDocumentDepth" gibt eine "FacetSearchOption" zurück, die die Anzahl der Dokumente bestimmt, die bei der Vorbereitung der Attributergebnisse ausgewertet werden müssen.
Feld
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
}"Field" ist ein Name/Wert-Paar. Das Dokument eines Suchindex kann geladen und als eine Abfolge von "Fields" gespeichert werden.
func SaveStruct
"SaveStruct" gibt die Felder von "src" als ein Segment von "Field" zurück. "src" muss ein Strukturzeiger sein.
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" definiert einen benutzerdefinierten Ausdruck, der für jedes Ergebnis ausgewertet wird.
FieldList
type FieldList []Field"FieldList" konvertiert ein Feld [], sodass es "FieldLoadSaver" implementiert.
func (*FieldList) Load
func (l *FieldList) Load(f []Field, _ *DocumentMetadata) error"Load" lädt alle bereitgestellten Felder in l. Es setzt *l nicht zuerst auf ein leeres Segment zurück.
func (*FieldList) Save
func (l *FieldList) Save() ([]Field, *DocumentMetadata, error)"Save" gibt alle Felder von l als Segment von "Field" zurück.
FieldLoadSaver
type FieldLoadSaver interface {
Load([]Field, *DocumentMetadata) error
Save() ([]Field, *DocumentMetadata, error)
}"FieldLoadSaver" kann mit zusätzlichen Dokument-Metadaten von und in ein Segment von "Fields" konvertiert werden.
HTML
type HTML string"HTML" ist ein Dokumentfeld, dessen Inhalt als HTML indexiert wird. Nur Textknoten werden indexiert: "foobar" wird als "foobar" behandelt.
Index
type Index struct {
// contains filtered or unexported fields
}"Index" ist ein Index von Dokumenten.
func Open
"Open" öffnet den Index mit dem angegebenen Namen. Der Index wird erstellt, wenn er nicht bereits vorhanden ist.
Der Name ist eine von Menschen lesbare ASCII-Zeichenfolge. Sie darf keine Leerzeichen enthalten und nicht mit "!" beginnen.
func (*Index) Delete
"Delete" löscht ein Dokument aus dem Index.
Funktion (*Index) DeleteMulti
"DeleteMulti" löscht mehrere Dokumente aus dem Index.
Der zurückgegebene Fehler kann eine Instanz von appengine.MultiError sein. In diesem Fall hat er dieselbe Größe wie srcs und die einzelnen Fehler entsprechen den Elementen in srcs.
func (*Index) Get
"Get" lädt das Dokument mit der angegebenen ID in "dst".
Die ID ist eine von Menschen lesbare ASCII-Zeichenfolge. Sie darf nicht leer sein, keine Leerzeichen enthalten und nicht mit "!" beginnen.
"dst" muss ein Strukturzeiger ungleich null sein oder die Schnittstelle "FieldLoadSaver" implementieren.
"ErrFieldMismatch" wird zurückgegeben, wenn ein Feld in einen anderen Typ geladen werden soll als den, aus dem es gespeichert wurde, oder wenn ein Feld fehlt oder in der Zielstruktur nicht exportiert wurde. "ErrFieldMismatch" wird nur zurückgegeben, wenn es sich bei "dst" um einen Strukturzeiger handelt. Es ist Aufgabe des Angerufenen, zu entscheiden, ob dieser Fehler schwerwiegend, wiederherstellbar oder ignorierbar ist.
func (*Index) List
func (x *Index) List(c context.Context, opts *ListOptions) *Iterator"List" listet alle Dokumente in einem Index auf. Die Dokumente werden in aufsteigender ID-Reihenfolge zurückgegeben.
func (*Index) Put
"Put" speichert "src" im Index. Wenn "id" leer ist, wird vom Dienst eine neue ID zugewiesen und zurückgegeben. Wenn "id" nicht leer ist, werden vorhandene Indexeinträge für diese ID ersetzt.
Die ID ist eine von Menschen lesbare ASCII-Zeichenfolge. Sie darf keine Leerzeichen enthalten und nicht mit "!" beginnen.
"src" muss ein Strukturzeiger ungleich null sein oder die Schnittstelle "FieldLoadSaver" implementieren.
Funktion (*Index) PutMulti
"PutMulti" ähnelt "Put", ist jedoch effizienter, wenn mehrere Dokumente gleichzeitig dem Index hinzugefügt werden sollen.
Es können bis zu 200 Dokumente gleichzeitig hinzugefügt werden. "ErrTooManyDocuments" wird zurückgegeben, wenn Sie versuchen, weitere hinzuzufügen.
ids können entweder ein leeres Segment (dann werden für jedes hinzugefügte Dokument neue IDs zugewiesen) oder ein Segment mit der gleichen Größe wie srcs sein.
Der Fehler kann eine Instanz von appengine.MultiError sein. In diesem Fall hat er dieselbe Größe wie srcs und die einzelnen Fehler darin entsprechen den Elementen in srcs.
func (*Index) Search
"Search" durchsucht den Index nach der angegebenen Abfrage.
Iterator
type Iterator struct {
// contains filtered or unexported fields
}"Iterator" ist das Ergebnis der Suche nach einem Index für eine Abfrage oder die Auflistung eines Index.
func (*Iterator) Count
"Count" gibt einen Näherungswert der Anzahl der Dokumente zurück, die von der Abfrage abgeglichen wurden. Es können nur Iteratoren aufgerufen werden, die von "Search" zurückgegeben werden.
func (*Iterator) Cursor
"Cursor" gibt den Cursor zurück, der dem aktuellen Dokument zugeordnet ist, d. h, das zuletzt von einem Aufruf von "Next" zurückgegebene Dokument.
Wird dieser Cursor in einem zukünftigen Aufruf von "Search" übergeben, beginnen diese Ergebnisse mit dem ersten Dokument nach dem aktuellen Dokument.
func (*Iterator) Facets
func (t *Iterator) Facets() ([][]FacetResult, error)"Facets" gibt die in den Suchergebnissen gefundenen Attribute zurück, wenn in den Suchoptionen Attribute angefordert wurden.
func (*Iterator) Next
"Next" gibt die ID des nächsten Ergebnisses zurück. Wenn keine weiteren Ergebnisse vorliegen, wird "Done" als Fehler zurückgegeben.
"dst" muss ein Strukturzeiger ungleich null sein, die Schnittstelle "FieldLoadSaver" implementieren oder den Schnittstellenwert null haben. Wenn "dst" nicht null ist, wird es mit den indizierten Feldern gefüllt. "dst" wird ignoriert, wenn dieser Iterator mit der Option "IDsOnly" erstellt wurde.
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" sind die Optionen zum Auflisten von Dokumenten in einem Index. Das Übergeben von null "*ListOptions" entspricht der Verwendung der Standardwerte.
Wertebereich
type Range struct {
Start, End float64
}"Range" repräsentiert einen numerischen Bereich, wobei "Start" einbezogen und "End" ausgeschlossen wird. "Start" kann als "math.Inf(-1)" angegeben werden, um festzulegen, dass es keinen Mindestwert gibt. "End" kann in ähnlicher Weise als "math.Inf(1)" angegeben werden. Mindestens ein Start- oder End-Wert muss eine endliche Zahl sein.
func AtLeast
"AtLeast" gibt einen Bereich zurück, dessen Werte größer als oder gleich "min" sind.
func LessThan
"LessThan" gibt einen Bereich zurück, dessen Werte kleiner als "max" sind.
Scorer
type Scorer interface {
// contains filtered or unexported methods
}Ein Scorer definiert, wie ein Dokument bewertet wird.
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}
)SearchOptions
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
}"SearchOptions" sind die Optionen zum Durchsuchen eines Indexes. Wenn Sie null "*SearchOptions" übergeben, entspricht dies der Verwendung der Standardwerte.
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" definiert eine einzelne Dimension zur Sortierung eines Dokuments.
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" steuert die Sortierung und Bewertung von Suchergebnissen.