Documentation
¶
Overview ¶
Package search provides a client for App Engine's search service.
Indexes contains documents, and a document's contents are a mapping from case- sensitive field names to values. In Go, documents are represented by struct pointers, and the valid types for a struct's fields are:
- 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.
Documents can also be represented by any type implementing the FieldLoadSaver interface.
Example 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(c, "", &Doc{
Author: "gopher",
Comment: "the truth of the matter",
Creation: time.Now(),
})
if err != nil {
return err
}
Searching an index for a query will result in an iterator. As with an iterator from package datastore, pass a destination struct to Next to decode the next result. Next will return Done when the iterator is exhausted.
for t := index.Search(c, "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)
}
Call List to iterate over documents.
for t := index.List(c, 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)
}
A single document can also be retrieved by its ID. Pass a destination struct to Get to hold the resulting document.
var doc Doc
err := index.Get(c, id, &doc)
if err != nil {
return err
}
Queries are expressed as strings, plus some optional parameters. The query language is described at https://cloud.google.com/appengine/docs/go/search/query_strings
Note that in Go, field names come from the struct field definition and begin with an upper case letter.
Index ¶
- Variables
- func LoadStruct(dst interface{}, f []Field) error
- type Atom
- type DocumentMetadata
- type ErrFieldMismatch
- type Field
- type FieldExpression
- type FieldList
- type FieldLoadSaver
- type HTML
- type Index
- func (x *Index) Delete(c appengine.Context, id string) error
- func (x *Index) Get(c appengine.Context, id string, dst interface{}) error
- func (x *Index) List(c appengine.Context, opts *ListOptions) *Iterator
- func (x *Index) Put(c appengine.Context, id string, src interface{}) (string, error)
- func (x *Index) Search(c appengine.Context, query string, opts *SearchOptions) *Iterator
- type Iterator
- type ListOptions
- type Scorer
- type SearchOptions
- type SortExpression
- type SortOptions
Constants ¶
This section is empty.
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")
Done is returned when a query iteration has completed.
Functions ¶
func LoadStruct ¶
func LoadStruct(dst interface{}, f []Field) error
LoadStruct loads the fields from f to dst. dst must be a struct pointer.
Types ¶
type Atom ¶
type Atom string
Atom is a document field whose contents are indexed as a single indivisible string.
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
}
DocumentMetadata is a struct containing information describing a given document.
type ErrFieldMismatch ¶
type ErrFieldMismatch struct {
FieldName string
Reason string
}
ErrFieldMismatch is returned when a field is to be loaded into a different than the one it was stored from, or when a field is missing or unexported in the destination struct.
type Field ¶
type Field struct {
// Name is the field name.
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 693-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 is a name/value pair. A search index's document can be loaded and saved as a sequence of Fields.
func SaveStruct ¶
func SaveStruct(src interface{}) ([]Field, error)
SaveStruct returns the fields from src as a slice of Field. src must be a struct pointer.
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/go/search/options for
// the supported expression syntax.
Expr string
}
FieldExpression defines a custom expression to evaluate for each result.
type FieldList ¶
type FieldList []Field
FieldList converts a []Field to implement FieldLoadSaver.
type FieldLoadSaver ¶
type FieldLoadSaver interface {
Load([]Field, *DocumentMetadata) error
Save() ([]Field, *DocumentMetadata, error)
}
FieldLoadSaver can be converted from and to a slice of Fields with additional document metadata.
type HTML ¶
type HTML string
HTML is a document field whose contents are indexed as HTML. Only text nodes are indexed: "foo<b>bar" will be treated as "foobar".
type Index ¶
type Index struct {
// contains filtered or unexported fields
}
Index is an index of documents.
func Open ¶
func Open(name string) (*Index, error)
Open opens the index with the given name. The index is created if it does not already exist.
The name is a human-readable ASCII string. It must contain no whitespace characters and not start with "!".
func (*Index) Delete ¶
func (x *Index) Delete(c appengine.Context, id string) error
Delete deletes a document from the index.
func (*Index) Get ¶
func (x *Index) Get(c appengine.Context, id string, dst interface{}) error
Get loads the document with the given ID into dst.
The ID is a human-readable ASCII string. It must be non-empty, contain no whitespace characters and not start with "!".
dst must be a non-nil struct pointer or implement the FieldLoadSaver interface.
ErrFieldMismatch is returned when a field is to be loaded into a different type than the one it was stored from, or when a field is missing or unexported in the destination struct. ErrFieldMismatch is only returned if dst is a struct pointer. It is up to the callee to decide whether this error is fatal, recoverable, or ignorable.
func (*Index) List ¶
func (x *Index) List(c appengine.Context, opts *ListOptions) *Iterator
List lists all of the documents in an index. The documents are returned in increasing ID order.
func (*Index) Put ¶
func (x *Index) Put(c appengine.Context, id string, src interface{}) (string, error)
Put saves src to the index. If id is empty, a new ID is allocated by the service and returned. If id is not empty, any existing index entry for that ID is replaced.
The ID is a human-readable ASCII string. It must contain no whitespace characters and not start with "!".
src must be a non-nil struct pointer or implement the FieldLoadSaver interface.
type Iterator ¶
type Iterator struct {
// contains filtered or unexported fields
}
Iterator is the result of searching an index for a query or listing an index.
func (*Iterator) Count ¶
func (t *Iterator) Count() int
Count returns an approximation of the number of documents matched by the query. It is only valid to call for iterators returned by Search.
func (*Iterator) Next ¶
func (t *Iterator) Next(dst interface{}) (string, error)
Next returns the ID of the next result. When there are no more results, Done is returned as the error.
dst must be a non-nil struct pointer, implement the FieldLoadSaver interface, or be a nil interface value. If a non-nil dst is provided, it will be filled with the indexed fields. dst is ignored if this iterator was created with an IDsOnly option.
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 are the options for listing documents in an index. Passing a nil *ListOptions is equivalent to using the default values.
type Scorer ¶
type Scorer interface {
// contains filtered or unexported methods
}
A Scorer defines how a document is scored.
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
}
SearchOptions are the options for searching an index. Passing a nil *SearchOptions is equivalent to using the default values.
type SortExpression ¶
type SortExpression struct {
// Expr is evaluated to provide a sorting value for each document.
// See https://cloud.google.com/appengine/docs/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 defines a single dimension for sorting a document.
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 control the ordering and scoring of search results.