El paquete de búsqueda

import "google.golang.org/appengine/search"

Introducción

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 (stored with millisecond precision),
- float64 (value between -2,147,483,647 and 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 de 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
}

Índice

Variables
func LoadStruct(dst interface{}, f []Field) error
func SaveStruct(src interface{}) ([]Field, error)
type Atom
type Cursor
type DocumentMetadata
type ErrFacetMismatch
    func (e *ErrFacetMismatch) Error() string
type ErrFieldMismatch
    func (e *ErrFieldMismatch) Error() string
type Facet
type FacetResult
type FacetSearchOption
    func AutoFacetDiscovery(facetLimit, valueLimit int) FacetSearchOption
    func FacetDiscovery(name string, value …interface{}) FacetSearchOption
    func FacetDocumentDepth(depth int) FacetSearchOption
type Field
type FieldExpression
type FieldList
    func (l *FieldList) Load(f []Field, _ *DocumentMetadata) error
    func (l *FieldList) Save() ([]Field, *DocumentMetadata, error)
type FieldLoadSaver
type HTML
type Index
    func Open(name string) (*Index, error)
    func (x *Index) Delete(c context.Context, id string) error
    func (x *Index) Get(c context.Context, id string, dst interface{}) error
    func (x *Index) List(c context.Context, opts *ListOptions) *Iterator
    func (x *Index) Put(c context.Context, id string, src interface{}) (string, error)
    func (x *Index) Search(c context.Context, query string, opts *SearchOptions) *Iterator
type Iterator
    func (t *Iterator) Count() int
    func (t *Iterator) Cursor() Cursor
    func (t *Iterator) Facets() ([][]FacetResult, error)
    func (t *Iterator) Next(dst interface{}) (string, error)
type ListOptions
type Range
    func AtLeast(min float64) Range
    func LessThan(max float64) Range
type Scorer
type SearchOptions
type SortExpression
type SortOptions

Variables

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")
)
var Done = errors.New("search: query has no more results")

Se muestra Done cuando se completa una iteración de la consulta.

func LoadStruct

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

LoadStruct carga los campos de f a dst. dst debe ser un puntero de struct.

func SaveStruct

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

SaveStruct muestra los campos de src como una porción de Field. src debe ser un puntero de struct.

type Atom

type Atom string

Atom es un campo de documento cuyo contenido está indexado como una sola string indivisible.

type Cursor

type Cursor string

Cursor 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.

type 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.

type ErrFacetMismatch

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

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

type ErrFieldMismatch

type ErrFieldMismatch struct {
    FieldName string
    Reason    string
}

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

type 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 es un par nombre/valor que se usa para agregar información categórica a un documento.

type 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.

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

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

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

FacetDocumentDepth muestra una FacetSearchOption que controla la cantidad de documentos que se evaluarán con los resultados de las facetas en preparación.

type Field

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.

type 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.

type FieldList

type FieldList []Field

FieldList convierte un []Field para implementar FieldLoadSaver.

func (*FieldList) Load

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

Load 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.

type 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.

type HTML

type HTML string

HTML es un campo de documento cuyo contenido está indexado como HTML. Solo se indexan los nodos de texto: “foo<b>bar” se tratará como “foobar”.

type Index

type Index struct {
    // contains filtered or unexported fields
}

Index es un índice de documentos.

func Open

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

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

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

Delete borra un documento del índice.

func (*Index) Get

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

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

List enumera todos los documentos de un índice. Los documentos se muestran en orden de ID creciente.

func (*Index) Put

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

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

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

Search busca la consulta dada en el índice.

type Iterator

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

func (t *Iterator) Count() int

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

func (t *Iterator) Cursor() 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

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

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.

type 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.

type 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

func AtLeast(min float64) Range

AtLeast muestra un Range que coincide con cualquier valor mayor o igual que min.

func LessThan

func LessThan(max float64) Range

LessThan muestra un Range que coincide con cualquier valor menor que max.

type Scorer

type Scorer interface {
    // contains filtered or unexported methods
}

Un Scorer define cómo se puntúa un documento.

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

type 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.

type 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.

type 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.

¿Te ha resultado útil esta página? Enviar comentarios:

Enviar comentarios sobre...

Entorno estándar de App Engine para Go