Help us shape the future of Go! Take the 2026 Go Developer Survey

search

package
v0.12.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Mar 16, 2015 License: Apache-2.0, Apache-2.0 Imports: 12 Imported by: 0

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

Constants

This section is empty.

Variables

View Source
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")
)
View Source
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.

func (*ErrFieldMismatch) Error

func (e *ErrFieldMismatch) Error() string

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.

func (*FieldList) Load

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

Load loads all of the provided fields into l. It does not first reset *l to an empty slice.

func (*FieldList) Save

func (l *FieldList) Save() ([]Field, *DocumentMetadata, error)

Save returns all of l's fields as a slice of Fields.

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.

func (*Index) Search

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

Search searches the index for the given query.

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL