Documents and Indexes

The Search API provides a model for indexing documents that contain structured data. You can search an index, and organize and present search results. The API supports full text matching on string fields. Documents and indexes are saved in a separate persistent store optimized for search operations. The Search API can index any number of documents. The App Engine Datastore may be more appropriate for applications that need to retrieve very large result sets.

  1. Overview
  2. Documents and fields
  3. Creating a document
  4. Working with an index
  5. Index schemas
  6. Viewing indexes in the Google Cloud Platform Console
  7. Search API quotas
  8. Search API pricing

Overview

The Search API is based on four main concepts: documents, indexes, queries, and results.

Documents

A document is an object with a unique ID and a list of fields containing user data. Each field has a name and a type. There are several types of fields, identified by the kinds of values they contain:

  • Atom Field - an indivisible character string
  • Text Field - a plain text string that can be searched word by word
  • HTML Field - a string that contains HTML markup tags, only the text outside the markup tags can be searched
  • Number Field - a floating point number
  • Date Field - a date object
  • Geopoint Field - a data object with latitude and longitude coordinates

The maximum size of a document is 1 MB.

Indexes

An index stores documents for retrieval. You can retrieve a single document by its ID, a range of documents with consecutive IDs, or all the documents in an index. You can also search an index to retrieve documents that satisfy given criteria on fields and their values, specified as a query string. You can manage groups of documents by putting them into separate indexes.

There is no limit to the number of documents in an index or the number of indexes you can use. The total size of all the documents in a single index is limited to 10GB by default but may be increased to up to 200GB by submitting a request.

Queries

To search an index, you construct a query, which has a query string and possibly some additional options. A query string specifies conditions for the values of one or more document fields. When you search an index you get back only those documents in the index with fields that satisfy the query.

The simplest query, sometimes called a "global search" is a string that contains only field values. This search uses a string that searches for documents that contain the words "rose" and "water":

index.search("rose water");

This one searches for documents with date fields that contain the date July 4, 1776, or text fields that include the string "1776-07-04":

index.search("1776-07-04");

A query string can also be more specific. It can contain one or more terms, each naming a field and a constraint on the field's value. The exact form of a term depends on the type of the field. For instance, assuming there is a text field called "product", and a number field called "price", here's a query string with two terms:

// search for documents with pianos that cost less than $5000
index.search("product = piano AND price < 5000");

Query options, as the name implies, are not required. They enable a variety of features:

  • Control how many documents are returned in the search results.
  • Specify what document fields to include in the results. The default is to include all the fields from the original document. You can specify that the results only include a subset of fields (the original document is not affected).
  • Sort the results.
  • Create "computed fields" for documents using FieldExpressions and abridged text fields using snippets.
  • Support paging through the search results by returning only a portion of the matched documents on each query (using offsets and cursors)

Search results

A call to search() can only return a limited number of matching documents. Your search may find more documents than can be returned in a single call. Each search call returns an instance of the Results class, which contains information about how many documents were found and how many were returned, along with the list of returned documents. You can repeat the same search, using cursors or offsets to retrieve the complete set of matching documents.

Additional training material

In addition to this documentation, you can read the two-part training class on the Search API at the Google Developer's Academy. (Although the class uses the Python API, you may find the additional discussion of the Search concepts useful.)