La búsqueda de paquetes proporciona un cliente para el servicio de búsqueda de App Engine.
Operaciones básicas
Los índices contienen documentos, y cada índice se identifica por su nombre: una string ASCII de lectura simple.
Dentro de un índice, los documentos están asociados con un ID, que también es una string ASCII de lectura simple. El contenido de un documento es una asignación de nombres de campos que distinguen desde mayúsculas y minúsculas hasta valores. Los tipos válidos para los valores de campo son los que se detallan a continuación:
- string,
- search.Atom,
- search.HTML,
- time.Time (almacenado con precisión de milisegundos)
- float64 (valor entre -2,147,483,647 y 2,147,483,647 inclusive)
- appengine.GeoPoint.
Los métodos Get y Put en un índice cargan y guardan un documento. Por lo general, el contenido de un documento se representa con un puntero de struct.
Código de ejemplo:
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 }
Se puede recuperar un documento individual por su ID. Pasa un struct de destino a Get para retener el documento resultante.
var doc Doc err := index.Get(ctx, id, &doc) if err != nil { return err }
Búsqueda y listado de documentos
Los índices tienen dos métodos para recuperar múltiples documentos a la vez: Search y List.
Buscar una consulta en un índice dará como resultado un iterador. Al igual que con un iterador del almacén de datos de paquetes, debes pasar un struct de destino a Next para decodificar el resultado siguiente. Next mostrará Done cuando se agote el iterador.
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) }
Search toma una consulta de string para determinar qué documentos mostrar. La consulta puede ser simple, como una sola palabra, o compleja. El lenguaje de consulta se describe en https://cloud.google.com/appengine/docs/standard/go/search/query_strings.
Search también toma un struct SearchOptions opcional que brinda mucho más control sobre cómo se calculan y muestran los resultados.
Llama a List para iterar sobre todos los documentos de un índice.
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) }
Campos y facetas
El contenido de un documento puede representarse con una variedad de tipos. Por lo general, son punteros de struct, pero también pueden representarse con cualquier tipo que implemente la interfaz FieldLoadSaver. FieldLoadSaver permite establecer metadatos para el documento con el tipo DocumentMetadata. Los punteros de struct están más tipificados y son más fáciles de usar; los FieldLoadSavers son más flexibles.
El contenido de un documento se puede expresar de dos maneras: campos y facetas.
Los campos son la forma más común de proporcionar contenido de documentos. Los campos permiten almacenar datos de múltiples tipos y se pueden buscar mediante strings de consulta.
Las facetas proporcionan una forma de adjuntar información categórica a un documento. Los únicos tipos válidos para facetas son search.Atom y float64. Las facetas permiten que los resultados de la búsqueda contengan resúmenes de las categorías coincidentes y restringen las búsquedas para que solo coincidan con categorías específicas.
De forma predeterminada, para los punteros de struct todos los campos de struct se usan como campos de documento, y el nombre de campo usado es el mismo que en el struct (y, por lo tanto, debe comenzar con una letra mayúscula). Los campos struct pueden tener una etiqueta search:"name,options". El nombre debe comenzar con una letra y contener solo caracteres de palabras. Un nombre de etiqueta “-” significa que el campo será ignorado. Si la opción es “facet”, el campo de struct se usará como una faceta de documento. Si la opción es “”, entonces se puede omitir la coma. No hay otras opciones reconocidas.
Código de ejemplo:
// 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"` }
La interfaz de FieldLoadSaver
El contenido de un documento también puede representarse con cualquier tipo que implemente la interfaz de FieldLoadSaver. Este tipo puede ser un puntero de struct, pero no es obligatorio. El paquete de búsqueda llamará a Load cuando cargue el contenido del documento y a Save cuando lo guarde. Además de una porción de Fields, los métodos Load y Save también usan el tipo DocumentMetadata para proporcionar información adicional sobre un documento (como su clasificación o conjunto de facetas). Los posibles usos de esta interfaz incluyen derivar campos no almacenados, verificar campos o establecer lenguajes específicos para campos de string y HTML.
Código de ejemplo:
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)
)Listo
Se muestra Done cuando se ha completado una iteración de la consulta.
Funciones
func LoadStruct
LoadStruct carga los campos de f a dst. dst debe ser un puntero de struct.
Átomo
type Atom stringAtom es un campo de documento cuyo contenido está indexado como una sola string indivisible.
Cursor
type Cursor stringCursor representa la posición de un iterador.
El valor de string de un cursor es seguro para la Web. Se puede guardar y restablecer para su uso posterior.
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 es un struct que contiene información que describe un documento determinado.
ErrFacetMismatch
ErrFacetMismatch se muestra cuando una faceta debe cargarse en un tipo diferente al de origen, o cuando hay un campo faltante o no exportado en el struct de destino. StructType es el tipo de struct al que apunta el argumento de destino que se pasa a Iterator.Next.
func (*ErrFacetMismatch) Error
func (e *ErrFacetMismatch) Error() stringErrFieldMismatch
ErrFieldMismatch se muestra cuando un campo debe cargarse en un tipo diferente al de origen o cuando hay un campo faltante o no exportado en el struct de destino.
func (*ErrFieldMismatch) Error
func (e *ErrFieldMismatch) Error() stringFaceta
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 es un par nombre/valor que se usa para agregar información categórica 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 representa la cantidad de veces que una faceta y un valor en particular aparecieron en los documentos que coinciden con una solicitud de búsqueda.
FacetSearchOption
type FacetSearchOption interface {
// contains filtered or unexported methods
}FacetSearchOption controla qué información de faceta se muestra en los resultados de la búsqueda.
func AutoFacetDiscovery
func AutoFacetDiscovery(facetLimit, valueLimit int) FacetSearchOptionAutoFacetDiscovery muestra una FacetSearchOption que permite la detección automática de facetas para la búsqueda. La detección automática de facetas busca las facetas que aparecen con mayor frecuencia en el conjunto agregado de los documentos coincidentes.
facetLimit controla el número máximo de facetas mostradas y el número máximo de valores por faceta. Un límite de cero indica que se debe usar un límite predeterminado.
func FacetDiscovery
func FacetDiscovery(name string, value ...interface{}) FacetSearchOptionFacetDiscovery devuelve una FacetSearchOption que selecciona una faceta que se mostrará con los resultados de la búsqueda. De forma predeterminada se mostrarán los valores más frecuentes para esa faceta. Sin embargo, también puedes especificar una lista de Atoms particulares o Ranges específicos para mostrar.
func FacetDocumentDepth
func FacetDocumentDepth(depth int) FacetSearchOptionFacetDocumentDepth muestra una FacetSearchOption que controla la cantidad de documentos que se evaluarán con los resultados de las facetas en preparación.
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
}Field es un par nombre/valor. El documento de un índice de búsqueda se puede cargar y guardar como una secuencia de Fields.
func SaveStruct
SaveStruct muestra los campos de src como una porción de Field.src debe ser un puntero de 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 define una expresión personalizada para evaluar en cada resultado.
FieldList
type FieldList []FieldFieldList convierte un []Field para implementar FieldLoadSaver.
func (*FieldList) Load
func (l *FieldList) Load(f []Field, _ *DocumentMetadata) errorLoad carga todos los campos proporcionados en l. No reinicia primero *l a una porción vacía.
func (*FieldList) Save
func (l *FieldList) Save() ([]Field, *DocumentMetadata, error)Save muestra todos los campos de l como una porción de Fields.
FieldLoadSaver
type FieldLoadSaver interface {
Load([]Field, *DocumentMetadata) error
Save() ([]Field, *DocumentMetadata, error)
}FieldLoadSaver se puede convertir desde y hacia una porción de Fields con metadatos de documentos adicionales.
HTML
type HTML stringHTML es un campo de documento cuyo contenido está indexado como HTML. Solo se indexan los nodos de texto: “foobar” se tratará como “foobar”.
Índice
type Index struct {
// contains filtered or unexported fields
}Index es un índice de documentos.
func Open
Open abre el índice con el nombre determinado. El índice se crea si aún no existe.
El nombre es una string ASCII de lectura simple. No debe contener caracteres de espacio en blanco ni comenzar con “!”.
func (*Index) Delete
Delete borra un documento del índice.
func (*Index) DeleteMulti
DeleteMulti borra múltiples documentos del índice.
El error que se muestra puede ser una instancia de appengine.MultiError, en cuyo caso será del mismo tamaño que los src y los errores individuales dentro de ellos corresponderán a los elementos en srcs.
func (*Index) Get
Get carga el documento con el ID determinado en dst.
El ID es una string ASCII de lectura simple. No debe estar vacío, contener caracteres de espacio en blanco ni comenzar con “!”.
dst debe ser un puntero de struct no nulo o debe implementar la interfaz FieldLoadSaver.
ErrFieldMismatch se muestra cuando debe cargarse un campo en un tipo diferente en el que se almacenó o cuando falta un campo o no se exporta en la estructura de destino. ErrFieldMismatch solo se muestra si dst es un puntero de struct. Quien realiza la llamada debe decidir si este error es recuperable o no, o si se puede ignorar.
func (*Index) List
func (x *Index) List(c context.Context, opts *ListOptions) *IteratorList enumera todos los documentos de un índice. Los documentos se muestran en orden de ID creciente.
func (*Index) Put
Put guarda src en el índice. Si id está vacío, el servicio asigna un ID nuevo y lo muestra. Si id no está vacío, se reemplaza cualquier entrada de índice existente para ese ID.
El ID es una string ASCII de lectura simple. No debe contener caracteres de espacio en blanco ni comenzar con “!”.
src debe ser un puntero de struct no nulo o debe implementar la interfaz FieldLoadSaver.
func (*Index) PutMulti
PutMulti es como put, pero es más eficiente para agregar varios documentos al índice a la vez.
Se pueden agregar hasta 200 documentos a la vez. Se muestra ErrTooManyDocuments si intentas agregar más.
Los IDs pueden ser una porción vacía (lo que significa que se asignarán IDs nuevos para cada uno de los documentos agregados) o una porción del mismo tamaño que las src.
El error puede ser una instancia de appengine.MultiError, en cuyo caso será del mismo tamaño que los src y los errores individuales dentro de ellos corresponderán con los elementos en srcs.
func (*Index) Search
Search busca la consulta dada en el índice.
Iterador
type Iterator struct {
// contains filtered or unexported fields
}Iterator es el resultado de buscar una consulta en un índice o enumerar un índice.
func (*Iterator) Count
Count muestra una aproximación del número de documentos que coinciden con la consulta. Solo es válido para llamar a iteradores devueltos por Search.
func (*Iterator) Cursor
Cursor muestra el cursor asociado con el documento actual (es decir, el documento más reciente mostrado por una llamada a Next).
Pasar este cursor en una llamada futura a Search hará que los resultados comiencen con el primer documento después del documento actual.
func (*Iterator) Facets
func (t *Iterator) Facets() ([][]FacetResult, error)Facets muestra las facetas encontradas en los resultados de la búsqueda, si se solicitó alguna faceta en SearchOptions.
func (*Iterator) Next
Next muestra el ID del resultado siguiente. Cuando no hay más resultados, se muestra Done como error.
dst debe ser un puntero de struct no nulo, implementar la interfaz FieldLoadSaver o ser un valor de interfaz nulo. Si se proporciona un dst no nulo, se rellenará con los campos indexados. dst se ignora si este iterador se creó con una opción 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
}ListOptions son las opciones para enumerar los documentos de un índice. Pasar un *ListOptions nulo equivale a usar los valores predeterminados.
Range
type Range struct {
Start, End float64
}Range representa un rango numérico, con Start inclusivo y End exclusivo. Start puede especificarse como math.Inf(-1) para indicar que no hay un valor mínimo, y End puede especificarse como math.Inf(1); al menos uno de los dos debe ser un número finito.
func AtLeast
AtLeast muestra un Range que coincide con cualquier valor mayor o igual que min.
func LessThan
LessThan muestra un Range que coincide con cualquier valor menor que max.
Scorer
type Scorer interface {
// contains filtered or unexported methods
}Un Scorer define cómo se puntú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}
)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 son las opciones de búsqueda para un índice. Pasar un *SearchOptions nulo equivale a usar los valores predeterminados.
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 define una dimensión individual para ordenar 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 controla el orden y la puntuación de los resultados de la búsqueda.