search

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.

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://developers.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
• type Atom
• type HTML
• type Index
  • func Open(name string) (*Index, error)
  • 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
  • func (t *Iterator) Count() int
  • func (t *Iterator) Next(dst interface{}) (string, error)
• type ListOptions
• type SearchOptions

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.

Types

type Atom

type Atom string

Atom is a document field whose contents are indexed as a single indivisible string.

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.

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.

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 or a nil interface value. If a non-nil struct pointer is provided, that struct will be filled with the indexed fields.

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
}

ListOptions are the options for listing documents in an index. Passing a nil *ListOptions is equivalent to using the default values.

type SearchOptions

type SearchOptions struct {
}

SearchOptions are the options for searching an index. Passing a nil *SearchOptions is equivalent to using the default values.

There are currently no options. Future versions may introduce some.