Create and register a schema

A Google Cloud Search schema is a JSON structure that defines objects, properties, and options for indexing and querying data. Your content connector uses the registered schema to structure and index repository data.

You create a schema by providing a JSON schema object to the API. You must register a schema for each repository before indexing data.

This document covers schema creation basics. To optimize the search experience, see Improve search quality.

Create a schema

Follow these steps to create your Cloud Search schema:

1. Identify expected user behavior
2. Initialize a data source
3. Define your objects
4. Define object properties
5. Register your schema
6. Index your data
7. Test your schema
8. Tune your schema

Identify expected user behavior

Anticipating how users search helps define your schema strategy. For a movie database, users might search for "movies starring Robert Redford." Your schema must support queries for movies with a specific actor.

To align your schema with user behavior:

1. Evaluate diverse queries from different users.
2. Identify logical data sets, or objects, such as a "movie."
3. Identify properties (attributes) like title or release date.
4. Identify valid values for properties, such as "Raiders of the Lost Ark."
5. Determine sorting and ranking needs, like chronological order or audience ratings.
6. Identify context properties, such as job role, to improve autocomplete suggestions.
7. List these objects, properties, and example values. Use this list to define operator options.

Initialize your data source

A data source represents indexed repository data stored in Google Cloud. See Manage third-party data sources. When a user clicks a result, Cloud Search directs them to the item using the URL from the indexing request.

Define your objects

The object is the fundamental unit of a schema. Logical structures like "movie" or "person" are objects. Each object has properties like title, duration, or name.

A schema is a list of object definitions in the objectDefinitions tag.

{
  "objectDefinitions": [
    { "name": "movie" },
    { "name": "person" }
  ]
}

Use unique names for each object, such as movie. The schema service uses these names as keys. See ObjectDefinition.

Define object properties

Define properties, like title and release date, in the propertyDefinitions section. Use options for freshnessOptions (ranking) and displayOptions (UI labels).

{
  "objectDefinitions": [{
    "name": "movie",
    "propertyDefinitions": [
      {
        "name": "movieTitle",
        "isReturnable": true,
        "textPropertyOptions": {
          "retrievalImportance": { "importance": "HIGHEST" },
          "operatorOptions": { "operatorName": "title" }
        },
        "displayOptions": { "displayLabel": "Title" }
      },
      {
        "name": "releaseDate",
        "isReturnable": true,
        "isSortable": true,
        "datePropertyOptions": {
          "operatorOptions": {
            "operatorName": "released",
            "lessThanOperatorName": "releasedbefore",
            "greaterThanOperatorName": "releasedafter"
          }
        }
      }
    ]
  }]
}

A PropertyDefinition includes:

• A name string.
• Type-agnostic options (e.g., isReturnable).
• A type and type-specific options (e.g., textPropertyOptions).
• operatorOptions for search operators.
• displayOptions for UI labels.

You can reuse property names across different objects. For example, movieTitle can appear in both a movie object and a person object's filmography.

Add type-agnostic options

PropertyDefinition includes boolean options to configure search functionality for a property, regardless of its type. These options default to false and must be set to true to be used.

• isReturnable: Set to true if the property data should be returned in search results using the Query API. Non-returnable properties can be used for searching or ranking without appearing in results.
• isRepeatable: Set to true if the property can have multiple values. For example, a movie has one release date but multiple actors.
• isSortable: Set to true if the property can be used for sorting. Cannot be true if isRepeatable is true or if the property is inside a repeatable sub-object.
• isFacetable: Set to true if the property can be used for generating facets (attributes used to refine search results).
  • Requires isReturnable to be true.
  • Supported only for enum, boolean, and text properties.
• isWildcardSearchable: Set to true to allow users to perform wildcard searches on this property. This option is only available on text properties and its behavior depends on the exactMatchWithOperator setting:
  • If exactMatchWithOperator is true: The text value is treated as a single token. A query like science-* matches the value science-fiction.
  • If exactMatchWithOperator is false: The text value is tokenized. A query like sci* or fi* matches science-fiction, but science-* does not.

Define type

Set the data type by defining the appropriate property options object (e.g., textPropertyOptions). Use enums (enumPropertyOptions) if you know all possible values. A property can have only one data type.

Define operator options

operatorOptions describe how a property functions as a search operator.