A pesquisa de pacote fornece um cliente para o serviço de pesquisa do App Engine.
Operações básicas
Os índices contêm documentos. Cada índice é identificado pelo nome: uma string ASCII legível.
Dentro de um índice, os documentos são associados a um código, que também é uma string ASCII legível. O conteúdo de um documento é um mapeamento dos nomes de campo que diferenciam maiúsculas de minúsculas para valores. Os tipos válidos para valores de campo são:
- string,
- search.Atom,
- search.HTML,
- time.Time (armazenado com precisão de milissegundos),
- float64 (valor flutuante, entre -2,147,483,647 e 2,147,483,647, inclusive).
- appengine.GeoPoint.
Os métodos Get e Put em um índice carregam e salvam um documento. O conteúdo de um documento costuma ser representado por um ponteiro struct.
Exemplo de código:
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 }
Um único documento pode ser recuperado pelo código. Passe um struct de destino para Get a fim de manter o documento resultante.
var doc Doc err := index.Get(ctx, id, &doc) if err != nil { return err }
Como pesquisar e listar documentos
Os índices têm dois métodos para recuperar vários documentos de uma só vez: Search e List.
Procurar em um índice uma consulta resultará em um iterador. Assim como acontece com um iterador do armazenamento de dados do pacote, passe um struct de destino para Next a fim de decodificar o próximo resultado. Next retornará Done quando o iterador tiver terminado.
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 utiliza uma consulta de string para determinar quais documentos retornar. A consulta pode ser simples, como uma única palavra para correspondência, ou complexa. A linguagem da consulta está descrita em https://cloud.google.com/appengine/docs/standard/go/search/query_strings
Search também utiliza um struct SearchOptions opcional que oferece muito mais controle sobre como os resultados são calculados e retornados.
Chame List para iterar em todos os documentos em um í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 e atributos
O conteúdo de um documento pode ser representado por uma grande variedade de tipos. Eles normalmente são ponteiros de struct, mas também podem ser representados por qualquer tipo que implemente a interface FieldLoadSaver. O FieldLoadSaver permite que os metadados sejam definidos para o documento com o tipo DocumentMetadata. Os ponteiros de struct são mais fortemente tipados e são mais fáceis de usar. FieldLoadSavers são mais flexíveis.
O conteúdo de um documento pode ser expressado de duas maneiras: campos e atributos.
Campos são a maneira mais comum de fornecer conteúdo para documentos. Os campos podem armazenar dados em vários tipos e ser comparados em pesquisas que usam strings de consulta.
Os atributos oferecem uma maneira de anexar informações categóricas a um documento. Os únicos tipos válidos para atributos são search.Atom e float64. Os atributos permitem que os resultados da pesquisa contenham resumos das categorias correspondentes em uma pesquisa e restrinjam pesquisas apenas a categorias específicas.
Por padrão, para ponteiros de struct, todos os campos de struct são usados como campos de documento, e o nome do campo usado é o mesmo do struct (e, por isso, precisa começar com uma letra maiúscula). Os campos de struct podem ter uma tag search:"name,options". O nome precisa começar com uma letra e ser composto apenas de caracteres de palavras. Um nome de tag "-" significa que o campo será ignorado. Se as opções forem "atributos", o campo de struct será usado como um atributo de documento. Se as opções forem "", a vírgula poderá ser omitida. Não há outras opções reconhecidas.
Código de exemplo:
// 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"` }
A interface FieldLoadSaver
O conteúdo de um documento também pode ser representado por qualquer tipo que implemente a interface FieldLoadSaver. Esse tipo pode ser um ponteiro de struct, mas não precisa ser. O pacote de pesquisa chamará Load ao carregar o conteúdo do documento e Salvar ao salvá-los. Além de uma fatia de Fields, os métodos Load e Save também usam o tipo DocumentMetadata para fornecer informações adicionais sobre um documento (como Rank ou conjunto de Facets). Entre os usos possíveis para essa interface estão derivar campos não armazenados, verificar campos ou definir linguagens específicas para campos de string e HTML.
Exemplo de código:
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 }
Variáveis
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)
)Concluído
Done é retornado quando uma iteração de consulta é concluída.
Funções
func LoadStruct
LoadStruct carrega os campos de f a dst. dst precisa ser um ponteiro de struct.
Atom
type Atom stringAtom é um campo de documento que oferece conteúdo indexado como uma única string indivisível.
Cursor
type Cursor stringCursor representa a posição de um iterador.
O valor de string de um cursor é seguro para Web. Ele pode ser salvo e restaurado para 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 é um struct contendo informações que descrevem um determinado documento.
ErrFacetMismatch
ErrFacetMismatch é retornado quando um atributo precisa ser carregado em um tipo diferente daquele onde foi armazenado, ou quando um campo não foi encontrado ou não foi exportado no struct de destino. StructType é o tipo do struct apontado pelo argumento de destino passado para Iterator.Next.
func (*ErrFacetMismatch) Error
func (e *ErrFacetMismatch) Error() stringErrFieldMismatch
ErrFieldMismatch é retornado quando um campo precisa ser carregado em um diferente daquele de onde foi armazenado ou quando um campo não foi encontrado ou não foi exportado no struct de destino.
func (*ErrFieldMismatch) Error
func (e *ErrFieldMismatch) Error() stringAtributo
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 é um par de nome/valor usado para adicionar informações categóricas a um 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 o número de vezes em que um determinado atributo e um determinado valor apareceram nos documentos correspondentes a uma solicitação de pesquisa.
FacetSearchOption
type FacetSearchOption interface {
// contains filtered or unexported methods
}FacetSearchOption controla quais informações de atributo são retornadas nos resultados da pesquisa.
func AutoFacetDiscovery
func AutoFacetDiscovery(facetLimit, valueLimit int) FacetSearchOptionAutoFacetDiscovery retorna uma FacetSearchOption que permite a detecção automática de atributo para a pesquisa. A descoberta automática de atributo procura os atributos que mais aparecem no agregado nos documentos correspondentes.
O número máximo de atributos retornados é controlado por facetLimit, e o número máximo de valores por atributo por facetLimit. Um limite de zero indica que um limite padrão precisa ser usado.
func FacetDiscovery
func FacetDiscovery(name string, value ...interface{}) FacetSearchOptionFacetDiscovery retorna uma FacetSearchOption que seleciona um atributo a ser retornado com os resultados da pesquisa. Por padrão, os valores mais frequentes para esse atributo serão retornados. No entanto, você também pode especificar uma lista de Atoms ou Ranges específicos a serem retornados.
func FacetDocumentDepth
func FacetDocumentDepth(depth int) FacetSearchOptionFacetDocumentDepth retorna uma FacetSearchOption que controla o número de documentos a serem avaliados com a preparação de resultados de atributo.
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 é um par nome/valor. O documento de um índice de pesquisa pode ser carregado e salvo como uma sequência de Fields.
func SaveStruct
SaveStruct retorna os campos de src como uma fatia de Field. O src precisa ser um ponteiro 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 uma expressão personalizada a ser avaliada para cada resultado.
FieldList
type FieldList []FieldFieldList converte um []Field para implementar FieldLoadSaver.
func (*FieldList) Load
func (l *FieldList) Load(f []Field, _ *DocumentMetadata) errorLoad carrega todos os campos fornecidos em l. Ele não redefine *l primeiro para uma fatia vazia.
func (*FieldList) Save
func (l *FieldList) Save() ([]Field, *DocumentMetadata, error)Save retorna todos os campos de I como uma fatia de Fields.
FieldLoadSaver
type FieldLoadSaver interface {
Load([]Field, *DocumentMetadata) error
Save() ([]Field, *DocumentMetadata, error)
}FieldLoadSaver pode ser convertido de e para uma fatia de Fields com metadados de documento adicionais.
HTML
type HTML stringHTML é um campo de documento com conteúdo indexado como HTML. Somente nós de texto são indexados: "foobar" será tratado como "foobar".
Índice
type Index struct {
// contains filtered or unexported fields
}Index é um índice de documentos.
func Open
Open abre o índice com o nome indicado. O índice será criado, se ele ainda não existir.
O nome é uma string ASCII legível. Ele não pode conter espaços em branco e não pode começar com "!".
func (*Index) Delete
Delete exclui um documento do índice.
func (*Index) DeleteMulti
DeleteMulti exclui vários documentos do índice.
O erro retornado pode ser uma instância de appengine.MultiError. Nesse caso, ele vai ter o mesmo tamanho que os srcs, e os erros individuais dentro deles corresponderão aos itens nos srcs.
func (*Index) Get
Get carrega o documento com o código indicado em dst.
Código é uma string ASCII legível. Ele não pode estar vazio, não pode conter caracteres de espaço em branco e não pode começar com "!".
dst precisa ser um ponteiro de struct não nulo ou implementar a interface FieldLoadSaver.
ErrFieldMismatch é retornado quando um campo precisa ser carregado em um tipo diferente daquele de onde foi armazenado ou quando um campo não é encontrado ou não é exportado no struct de destino. ErrFieldMismatch só será retornado se dst for um ponteiro de struct. Cabe ao chamador decidir se esse erro é fatal, recuperável ou ignorável.
func (*Index) List
func (x *Index) List(c context.Context, opts *ListOptions) *IteratorList lista todos os documentos em um índice. Os documentos são retornados em ordem de código crescente.
func (*Index) Put
Put salva src no índice. Se o código estiver vazio, um novo código será alocado pelo serviço e retornado. Se o código não estiver vazio, qualquer entrada de índice existente para esse código for substituído.
Código é uma string ASCII legível. Ele não pode conter espaços em branco e não pode começar com "!".
src precisa ser um ponteiro de struct não nulo ou implementar a interface FieldLoadSaver.
func (*Index) PutMulti
PutMulti é como Put, mas é mais eficiente para adicionar vários documentos ao índice de uma só vez.
É possível adicionar até 200 documentos de uma vez. ErrTooManyDocuments é retornado se você tentar adicionar mais.
Os IDs podem ser uma fração vazia (o que significa que novos IDs serão alocados para cada um dos documentos adicionados) ou uma fração do mesmo tamanho que os srcs.
O erro pode ser uma instância de appengine.MultiError. Nesse caso, ele vai ter o mesmo tamanho que os srcs, e os erros individuais deles corresponderão aos itens nos srcs.
func (*Index) Search
Search pesquisa o índice em busca da consulta indicada.
Iterator
type Iterator struct {
// contains filtered or unexported fields
}Iterator é o resultado da pesquisa de um índice em busca de uma consulta ou da listagem de um índice.
func (*Iterator) Count
Count retorna uma aproximação do número de documentos correspondentes com a consulta. Ele só é válido para chamar iteradores retornados por Search.
func (*Iterator) Cursor
Cursor retorna o cursor associado ao documento atual (ou seja, o documento retornado mais recentemente por uma chamada para Next).
Passar esse cursor em uma chamada futura para Search fará esses resultados começarem com o primeiro documento depois do documento atual.
func (*Iterator) Facets
func (t *Iterator) Facets() ([][]FacetResult, error)Facets retornará os atributos encontrados nos resultados da pesquisa, se algum atributo for solicitado no SearchOptions.
func (*Iterator) Next
Next retorna o código do próximo resultado. Quando não há mais resultados, Done é retornado como o erro.
dst precisa ser um ponteiro de struct não nulo, implementar a interface FieldLoadSaver ou ser um valor de interface nulo. Se um dst não nulo for fornecido, ele será preenchido com os campos indexados. dst será ignorado se esse iterador tiver sido criado com uma opção 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 são as opções para listar documentos em um índice. Passar um *ListOptions nulo equivale a usar os valores padrão.
Intervalo
type Range struct {
Start, End float64
}Range representa um intervalo numérico com início inclusivo e um final exclusivo. O início pode ser especificado como math.Inf(-1) para indicar que não há valor mínimo, e End pode ser especificado como math.Inf(1). Pelo menos uma das opções Start ou End precisa ser um número finito.
func AtLeast
AtLeast retorna um Range correspondente a qualquer valor maior que ou igual a min.
func LessThan
LessThan retorna um Range correspondente a qualquer valor menor que max.
Scorer
type Scorer interface {
// contains filtered or unexported methods
}Um Scorer define como um documento é pontuado.
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 são as opções para pesquisar um índice. Passar *SearchOptions nulo equivale a usar os valores padrão.
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 uma única dimensão para classificar um 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 controlam a ordem e a pontuação dos resultados da pesquisa.