search

Overview ¶

Package search provides a client for App Engine's search service.

Basic Operations ¶

Indexes contain documents. Each index is identified by its name: a human-readable ASCII string.

Within an index, documents are associated with an ID, which is also a human-readable ASCII string. A document's contents are a mapping from case-sensitive field names to values. Valid types for field values 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.

The Get and Put methods on an Index load and save a document. A document's contents are typically represented by a struct pointer.

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(ctx, "", &Doc{
	Author:   "gopher",
	Comment:  "the truth of the matter",
	Creation: time.Now(),
})
if err != nil {
	return err
}

A single document can be retrieved by its ID. Pass a destination struct to Get to hold the resulting document.

var doc Doc
err := index.Get(ctx, id, &doc)
if err != nil {
	return err
}

Search and Listing Documents ¶

Indexes have two methods for retrieving multiple documents at once: Search and List.

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(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 takes a string query to determine which documents to return. The query can be simple, such as a single word to match, or complex. The query language is described at https://cloud.google.com/appengine/docs/standard/go/search/query_strings

Search also takes an optional SearchOptions struct which gives much more control over how results are calculated and returned.

Call List to iterate over all documents in an index.

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

Fields and Facets ¶

A document's contents can be represented by a variety of types. These are typically struct pointers, but they can also be represented by any type implementing the FieldLoadSaver interface. The FieldLoadSaver allows metadata to be set for the document with the DocumentMetadata type. Struct pointers are more strongly typed and are easier to use; FieldLoadSavers are more flexible.

A document's contents can be expressed in two ways: fields and facets.

Fields are the most common way of providing content for documents. Fields can store data in multiple types and can be matched in searches using query strings.

Facets provide a way to attach categorical information to a document. The only valid types for facets are search.Atom and float64. Facets allow search results to contain summaries of the categories matched in a search, and to restrict searches to only match against specific categories.

By default, for struct pointers, all of the struct fields are used as document fields, and the field name used is the same as on the struct (and hence must start with an upper case letter). Struct fields may have a `search:"name,options"` tag. The name must start with a letter and be composed only of word characters. A "-" tag name means that the field will be ignored. If options is "facet" then the struct field will be used as a document facet. If options is "" then the comma may be omitted. There are no other recognized options.

Example code:

// 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"`
}

The FieldLoadSaver Interface ¶

A document's contents can also be represented by any type that implements the FieldLoadSaver interface. This type may be a struct pointer, but it does not have to be. The search package will call Load when loading the document's contents, and Save when saving them. In addition to a slice of Fields, the Load and Save methods also use the DocumentMetadata type to provide additional information about a document (such as its Rank, or set of Facets). Possible uses for this interface include deriving non-stored fields, verifying fields or setting specific languages for string and HTML fields.

Example code:

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
}