Please note that the contents of this offline web site may be out of date. To access the most recent documentation visit the online version .
Note that links that point to online resources are green in color and will open in a new window.
We would love it if you could give us feedback about this material by filling this form (You have to be online to fill it)



The search package

import "appengine/search"

Introduction

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,
- 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://developers.google.com/appengine/docs/go/search/query_strings

Index

Variables
func LoadStruct(dst interface{}, f []Field) error
func SaveStruct(src interface{}) ([]Field, error)
type Atom
type Field
type FieldList
func (l *FieldList) Load(f []Field) error
func (l *FieldList) Save() ([]Field, error)
type FieldLoadSaver
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.

func LoadStruct

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

LoadStruct loads the fields from f to dst. dst must be a struct pointer.

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 Atom

type Atom string

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

type Field

type Field struct {
    // Name is the field name. A valid field name matches /[A-Z][A-Za-z0-9_]*/.
    // A field name cannot be longer than 500 characters.
    Name string
    // Value is the field value. The valid types are:
    //  - string,
    //  - search.Atom,
    //  - search.HTML,
    //  - time.Time (stored with millisecond precision),
    //  - float64,
    //  - appengine.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
}

Field is a name/value pair. A search index's document can be loaded and saved as a sequence of Fields.

type FieldList

type FieldList []Field

FieldList converts a []Field to implement FieldLoadSaver.

func (*FieldList) Load

func (l *FieldList) Load(f []Field) 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, error)

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

type FieldLoadSaver

type FieldLoadSaver interface {
    Load([]Field) error
    Save() ([]Field, error)
}

FieldLoadSaver can be converted from and to a slice of Fields.

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.

If dst is a struct pointer, then fields which are missing or unexported in the destination struct are silently ignored.

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

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

Authentication required

You need to be signed in with Google+ to do that.

Signing you in...

Google Developers needs your permission to do that.