Le package Search fournit un client pour le service de recherche d'App Engine.
Opérations de base
Les index contiennent des documents. Chaque index est identifié par son nom : une chaîne ASCII lisible par l'homme.
Dans un index, les documents sont associés à un ID, qui est également une chaîne ASCII lisible par l'homme. Le contenu d'un document est une mise en correspondance des noms de champs sensibles à la casse avec des valeurs. Les types de valeurs de champ valides sont les suivants :
- string,
- search.Atom,
- search.HTML,
- time.Time (stockée avec une précision à la milliseconde),
- Valeur flottante comprise entre 0.0 et 1.0 inclus.
- appengine.GeoPoint.
Les méthodes Get et Put sur un index chargent et enregistrent un document. Le contenu d'un document est généralement représenté par un pointeur de structure.
Exemple de code :
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 seul document peut être récupéré par son ID. Pour ce faire, transmettez une structure de destination à la méthode Get pour conserver le document résultant.
var doc Doc
err := index.Get(ctx, id, &doc)
if err != nil {
return err
}
Recherche et affichage d'une liste de documents
Les index peuvent faire appel à deux méthodes pour récupérer plusieurs documents à la fois : "Search" et "List".
La recherche d'un index pour une requête renvoie un itérateur. Tout comme avec un itérateur de package Datastore, vous transmettez une structure de destination à "Next" pour décoder le résultat suivant. "Next" renvoie la valeur "Done" lorsque l'itérateur est épuisé.
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 méthode "Search" récupère une requête de chaîne pour déterminer quels documents renvoyer. Il peut s'agir d'une requête simple, par exemple un mot à rechercher, ou d'une requête complexe. Le langage de requête est décrit à la page https://cloud.google.com/appengine/docs/standard/go/search/query_strings.
La méthode "Search" récupère également une structure optionnelle SearchOptions qui confère beaucoup plus de contrôle sur la manière de calculer et de renvoyer les résultats.
Appelez "List" pour parcourir l'ensemble des documents d'un index.
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)
}
Champs et attributs
Le contenu d'un document peut être représenté par divers types. En règle générale, il s'agit de pointeurs de structure, mais n'importe quel type qui met en œuvre l'interface FieldLoadSaver peut être utilisé. FieldLoadSaver permet de définir des métadonnées pour le document avec le type DocumentMetadata. Les pointeurs de structure sont des types plus forts et plus faciles à utiliser, mais les types FieldLoadSaver sont plus flexibles.
Le contenu d'un document peut être exprimé de deux manières : par des champs et par des attributs.
Les champs constituent le moyen le plus courant de fournir du contenu à des documents. Les champs peuvent stocker des données dans plusieurs types et être mis en correspondance lors de recherches à l'aide de chaînes de requête.
Les attributs permettent d'associer des informations catégoriques à un document. Les seuls types valides pour les attributs sont "search.Atom" et "float64". Les attributs permettent aux résultats de recherche de contenir des résumés des catégories mises en correspondance lors d'une recherche et de limiter les recherches afin qu'elles ne mettent en correspondance que des catégories spécifiques.
Par défaut, avec les pointeurs de structure, tous les champs de structure sont utilisés comme champs de document et le nom du champ utilisé est identique à celui de la structure (et doit donc commencer par une lettre majuscule). Les champs de structure peuvent présenter un tag search:"name,options". Le nom doit commencer par une lettre et ne contenir que des caractères de mot. Un nom de tag "-" signifie que le champ sera ignoré. Si "options" est "facet", le champ de structure sera utilisé comme attribut de document. Si "options" est "", la virgule peut être omise. Il n'y a pas d'autres options reconnues.
Exemple de code :
// 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"`
}
Interface FieldLoadSaver
Le contenu d'un document peut également être représenté par n'importe quel type qui met en œuvre l'interface FieldLoadSaver. Il peut d'agir d'un pointeur de structure, mais ce n'est pas nécessairement le cas. Le package Search appelle la méthode "Load" lors du chargement du contenu du document et la méthode "Save" lors de la sauvegarde. Outre une tranche de "Fields", les méthodes "Load" et "Save" utilisent également le type "DocumentMetadata" pour fournir des informations supplémentaires sur un document (tel que son classement ou son ensemble d'attributs). Les utilisations possibles de cette interface incluent la dérivation de champs non stockés, la vérification de champs ou la définition de langages spécifiques pour les champs de chaîne et HTML.
Exemple de code :
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
}
Variables
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)
)OK
La valeur Done est renvoyée lorsque l'itération d'une requête est terminée.
Fonctions
func LoadStruct
La fonction "LoadStruct" charge les champs de "f" à "dst". "dst" doit être un pointeur de structure.
Atom
type Atom stringLe type "Atom" représente un champ de document dont le contenu est indexé sous la forme d'une seule chaîne indivisible.
Cursor
type Cursor stringLe type "Cursor" représente la position d'un itérateur.
La valeur de chaîne d'un curseur est adaptée au Web. Il peut être enregistré et restauré pour une utilisation ultérieure.
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
}Le type "DocumentMetadata" représente une structure contenant des informations qui décrivent un document donné.
ErrFacetMismatch
Le type "ErrFacetMismatch" est renvoyé lorsqu'un attribut doit être chargé dans un type différent de celui où il a été stocké, lorsqu'il manque un champ ou que le champ n'est pas exporté dans la structure de destination. "StructType" est le type de structure vers laquelle pointe l'argument de destination transmis à "Iterator.Next".
func (*ErrFacetMismatch) Error
func (e *ErrFacetMismatch) Error() stringErrFieldMismatch
Le type "ErrFieldMismatch" est renvoyé lorsqu'un champ doit être chargé dans un fichier différent de celui où il a été stocké, lorsqu'il manque un champ ou que le champ n'est pas exporté dans la structure de destination.
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{}
}Le type "Facet" représente une paire nom/valeur utilisée pour ajouter des informations de catégorie à un document.
FacetResult
type FacetResult struct {
Facet
// Count is the number of times this specific facet and value appeared in the
// matching documents.
Count int
}Le type "FacetResult" représente le nombre de fois qu'un attribut et une valeur sont apparus dans les documents correspondant à une requête de recherche.
FacetSearchOption
type FacetSearchOption interface {
// contains filtered or unexported methods
}Le type "FacetSearchOption" contrôle les informations d'attribut renvoyées dans les résultats de recherche.
func AutoFacetDiscovery
func AutoFacetDiscovery(facetLimit, valueLimit int) FacetSearchOptionLa fonction "AutoFacetDiscovery" renvoie une option "FacetSearchOption" qui permet la découverte automatique d'attributs pour la recherche. La découverte automatique d'attributs recherche les attributs qui apparaissent le plus souvent ensemble dans les documents correspondants.
Le nombre maximal d'attributs renvoyés et le nombre maximal de valeurs par attribut sont contrôlés par "facetLimit". Une limite de zéro indique qu'une limite par défaut doit être utilisée.
func FacetDiscovery
func FacetDiscovery(name string, value ...interface{}) FacetSearchOptionLa fonction "FacetDiscovery" renvoie une option "FacetSearchOption" qui sélectionne un attribut à renvoyer avec les résultats de recherche. Par défaut, les valeurs les plus fréquentes de cet attribut sont renvoyées. Cependant, vous pouvez également spécifier une liste d'éléments "Atom" particuliers ou de plages spécifiques à renvoyer.
func FacetDocumentDepth
func FacetDocumentDepth(depth int) FacetSearchOptionLa fonction "FacetDocumentDepth" renvoie une option "FacetSearchOption" qui contrôle le nombre de documents à évaluer avec les résultats d'attribut de préparation.
Champ
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
}Le type "Field" représente une paire nom/valeur. Un document d'index de recherche peut être chargé et enregistré sous la forme d'une séquence de champs.
func SaveStruct
La fonction SaveStruct renvoie les champs "src" en tant que tranche de "Field". "src" doit être un pointeur de structure.
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
}Le type "FieldExpression" définit une expression personnalisée à évaluer pour chaque résultat.
FieldList
type FieldList []FieldLe type "FieldList" convertit un champ [] pour mettre en œuvre FieldLoadSaver.
func (*FieldList) Load
func (l *FieldList) Load(f []Field, _ *DocumentMetadata) errorLa fonction "Load" charge tous les champs fournis en 1. Elle ne commence pas par réinitialiser *1 sur une tranche vide.
func (*FieldList) Save
func (l *FieldList) Save() ([]Field, *DocumentMetadata, error)La fonction "Save" renvoie tous les champs de 1 sous forme de tranche de "Fields".
FieldLoadSaver
type FieldLoadSaver interface {
Load([]Field, *DocumentMetadata) error
Save() ([]Field, *DocumentMetadata, error)
}Le type "FieldLoadSaver" peut être converti à partir d'une tranche de "Fields" ou en tranche de "Fields" avec des métadonnées de document supplémentaires.
HTML
type HTML stringLe type "HTML" représente un champ de document dont le contenu est indexé au format HTML. Seuls les nœuds de texte sont indexés : "foo"bar" est traité de la même façon que "foobar".
Index
type Index struct {
// contains filtered or unexported fields
}Le type "Index" représente un index de documents.
func Open
La fonction "Open" ouvre l'index désigné. L'index est créé s'il n'existe pas.
Le nom est une chaîne ASCII lisible par l'homme. Elle ne doit contenir aucun caractère d'espacement ni commencer par "!".
func (*Index) Delete
La fonction "Delete" supprime un document de l'index.
func (*Index) DeleteMulti
La fonction DeleteMulti permet d'effacer plusieurs documents de l'index.
L'erreur renvoyée peut être une instance d'appengine.MultiError, auquel cas elle est de la même taille que les erreurs "src", et les erreurs individuelles qu'elles contiennent correspondent aux éléments des "srcs".
func (*Index) Get
La fonction "Get" charge le document avec l'ID donné dans "dst".
L'ID est une chaîne ASCII lisible par l'homme. Ce champ ne doit pas être vide, ne doit pas contenir de caractères d'espacement ni commencer par "!".
"dst" doit être un pointeur de structure non nul ou apte à mettre en œuvre l'interface FieldLoadSaver.
"ErrFieldMismatch" est renvoyé lorsqu'un champ doit être chargé dans un type différent de celui dans lequel il était stocké, lorsqu'il manque un champ ou lorsque le champ n'est pas exporté dans la structure de destination. "ErrFieldMismatch" n'est renvoyé que si "dst" est un pointeur de structure. Il appartient à l'appelé de décider si cette erreur est fatale, récupérable ou si elle peut être ignorée.
func (*Index) List
func (x *Index) List(c context.Context, opts *ListOptions) *IteratorLa fonction "List" répertorie tous les documents d'un index. Les documents sont renvoyés par ordre croissant d'ID.
func (*Index) Put
La fonction "Put" enregistre "src" dans l'index. Si "id" est vide, un nouvel identifiant est attribué par le service et renvoyé. Dans le cas contraire, toute entrée d'index existante pour cet ID sera remplacée.
L'ID est une chaîne ASCII lisible par l'homme. Elle ne doit contenir aucun caractère d'espacement ni commencer par "!".
"src" doit être un pointeur de structure non nul ou apte à mettre en œuvre l'interface FieldLoadSaver.
func (*Index) PutMulti
La fonction PutMulti est semblable à la fonction Put, mais elle est plus efficace pour ajouter plusieurs documents à l'index en même temps.
Vous pouvez ajouter jusqu'à 200 documents à la fois. Affiche ErrTooManyDocuments si vous essayez d'en ajouter.
L'ID peut être une tranche vide (ce qui signifie que les nouveaux ID seront alloués à chacun des documents ajoutés) ou une tranche de la même taille que les "srcs".
L'erreur peut être une instance d'appengine.MultiError, auquel cas la taille sera la même que celle des "srcs", et les erreurs individuelles qu'elles contiennent correspondent aux éléments des "srcs".
func (*Index) Search
La fonction "Search" recherche l'index pour la requête donnée.
anonyme
type Iterator struct {
// contains filtered or unexported fields
}Le type "Iterator" représente le résultat de la recherche d'un index pour une requête ou l'affichage d'une liste d'index.
func (*Iterator) Count
La fonction "Count" renvoie un nombre approximatif de documents correspondant à la requête. Seuls les appels d'itérateurs renvoyés par la fonction "Search" sont valides.
func (*Iterator) Cursor
La fonction "Cursor" renvoie le curseur associé au document actuel (c'est-à-dire le dernier document renvoyé par un appel de "Next").
Si vous transmettez ce curseur lors d'un prochain appel de "Search", ces résultats commenceront par le premier document suivant le document actuel.
func (*Iterator) Facets
func (t *Iterator) Facets() ([][]FacetResult, error)La fonction "Facets" renvoie les attributs trouvés dans les résultats de recherche, s'ils ont été demandés dans les options de recherche.
func (*Iterator) Next
La fonction "Next" renvoie l'ID du résultat suivant. Lorsqu'il n'y a plus de résultats, la valeur "Done" est renvoyée en tant qu'erreur.
"dst" doit être un pointeur de structure non nul, apte à mettre en œuvre l'interface FieldLoadSaver ou une valeur d'interface nulle. Si un "dst" non nul est fourni, il sera rempli par les champs indexés. Le "dst" est ignoré si cet itérateur a été créé avec une option "IDsOnly".
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
}Le type "ListOptions" représente les options définies pour répertorier les documents dans un index. Transmettre un type "*ListOptions" nul revient à utiliser les valeurs par défaut.
Range
type Range struct {
Start, End float64
}Le type "Range" représente une plage numérique avec des valeurs de début inclusives et des valeurs de fin exclusives. Le début peut être spécifié sous la forme "math.Inf(-1)" pour indiquer qu'il n'y a pas de valeur minimale, et la fin sous la forme "math.Inf(1)". Au moins une valeur de début ou de fin doit être un nombre fini.
func AtLeast
La fonction "AtLeast" renvoie une plage correspondant à n'importe quelle valeur supérieure ou égale à la valeur minimale.
func LessThan
La fonction "LessThan" renvoie une plage correspondant à n'importe quelle valeur inférieure à la valeur maximale.
Scorer
type Scorer interface {
// contains filtered or unexported methods
}Un type "Scorer" définit le mode d'évaluation d'un document.
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
}Le type "SearchOptions" représente les options définies pour rechercher un index. Transmettre un type "*SearchOptions" nul revient à utiliser les valeurs par défaut.
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{}
}Le type "SortExpression" définit une seule dimension pour le tri d'un document.
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
}Le type "SortOptions" contrôle le classement et l'évaluation des résultats de recherche.