Define synonyms

It's common for an organization to have unique terminology or multiple ways to refer to a concept or thing. You should define synonyms to establish equivalency of terms to helps users find items when searching.

Synonyms are defined by indexing items with the _dictionaryEntry well-known schema.

Items of type _dictionaryEntry require two properties:

Property Type Description
_term string The term to define. Recommended values are unhyphenated words or phrases without punctuation.
_synonym string (repeated) Alternate terms to be included in queries matching the string defined in _term

When a user includes the value of the _term property in a query, the effective query becomes "term OR synonyms." For example, if the term "scifi" is defined with the synonym "science fiction" then a query containing the word "scifi" matches items containing either "scifi" or "science fiction."

Synonyms are not applied bidirectionally. If the query is instead for "science fiction," Cloud Search will not apply any synonyms to the query. The query only matches items containing "science fiction. Items containing "scifi" are omitted.

To make all both terms interchangeable, define each term separately.

Term Synonyms
scifi science fiction
science fiction scifi

During query processing hyphenation and other punctuation are removed prior to applying synonyms. The user query sci-fi matches the _term sci fi. To create synonyms for terms which may be hyphenated by users, first normalize the _term to use whitespace instead of hyphens.

Continuing the example, the following definitions match the user queries treat sci-fi, sci fi, scifi, and science fiction as interchangeable:

Term Synonyms
scifi science fiction, sci fi
sci fi science fiction, scifi
science fiction scifi, sci fi

Define a term and synonyms with the content connector SDK

You can use the Content Connector SDK to define terms and their synonyms. See Create a content connector for instructions on building a connector.

The following snippet illustrates building a RepositoryDoc representing the term and synonym based on a CSV file record:
 * Creates a document for indexing.
 * For this connector sample, the created document is domain public
 *  searchable. The content is a simple text string.
 * @param record The current CSV record to convert
 * @return the fully formed document ready for indexing
private ApiOperation buildDocument(CSVRecord record) {
  // Extract term and synonyms from record
  String term = record.get(0);
  List<String> synonyms =, false)
      .skip(1) // Skip term

  Multimap<String, Object> structuredData = ArrayListMultimap.create();
  structuredData.put("_term", term);
  structuredData.putAll("_synonym", synonyms);

  String itemName = String.format("dictionary/%s", term);

  // Using the SDK item builder class to create the item
  Item item =

  // Create the fully formed document
  return new RepositoryDoc.Builder()

Note the following when defining synonyms:

  • Synonym entries are required to be domain public. In the previous example, this is accomplished by setting the ACL to DOMAIN_PUBLIC_ACL.
  • The following properties should not be defined for your configuration file because they will override the domain public setting in your code:
    • defaultAcl.mode=FALLBACK
    • defaultAcl.public=true