HomeDev guideRecipesAPI ReferenceGraphQL
Dev guideUser GuideGitHubNuGetDev CommunitySubmit a ticketLog In
GitHubNuGetDev CommunitySubmit a ticket

Full-text search

Describes opt-in for content properties, when using the GraphQL API for the Optimizely querying service, to retrieve content in Optimizely solutions.

The use-case for full-text search is to match on words or phrases in longer textual content (like a description), where as you can use filter on shorter values (like a page title or a name).

Properties on content types are opt-in for full-text search support. By default, fields are filtered only as an exact value. When fields need to have full-text search support, including tokenization and language stemming, you can use the following operators:

  • match operator – The recommended full-text search operator.
  • contains operator – Recommended when queries should match as phrases only.

The match operator is optimized for returning the most relevant results and applies common text-matching techniques. It works on searchable string fields, which should contain large chunks of text.

The contains operator is a limited search feature for full-text search because it does only phrase matching. But there are many cases where there are relevant items even though the query does not match as a phrase.

The match operator returns more relevant results than contains and returns more results in general, which offers a better user experience for site visitors. We recommend the match operator as a default operator for site search. By default, Optimizely Graph ranks by relevance, which is recommended to use in combination with match. This operator works also with synonyms. The match operator will not match on stop words, which precede the matching criteria described below.

The match operator will:

  1. Return items that exactly match to the top.
  2. Return items that match as a phrase below exact matches.
  3. Return items where matching words occur closer to each other below phrase matches.
  4. Return items that match all words in the query but in a different order next.
  5. Return items that match some of the words in the tail of the list, where more matches are ranked higher.

The scores computed by match is influenced by the locale. If the content is unevenly distributed because it has yet to be translated fully in a locale, it will impact the score with matches from that locale as it will have lower relevance scores. Optimizely Graph cannot guarantee that the match operator will follow the previously listed heuristics.

In this case, you can customize the ranking by using the boost option. An example query:

query MyQuery {
  Content(
    locale: ALL
    where: {
      _fulltext: { match: "Schwarzenegger description" }
      _or: [
        { Language: {Name: {eq: "en"}} }
        { Language: {Name: {in: ["sv","de"], boost:20}} }
      ]
    }
  ) {
    total
    items {
      Name
      _fulltext
      _score
      Language {
        Name
      }
    }
  }
}

📘

Note

The match and contains matches on terms which are tokenized by word boundaries according to UAX #29: Unicode Text Segmentation. This means that when you match a term with a leading or trailing punctuation character in a term, these characters are ignored.

Enable full-text search support for fields

You can enable full-text search support from the Optimizely Content Management System (CMS) Admin view by selecting the Searchable property option as shown in the image. This option is available for each property on the content type.

📘

Note

When the Searchable property option is changed, the Content type indexing job starts automatically, but you also need to manually run the Content indexing job.

The change is reflected in the GraphQL schema schema with the SearchableStringFilterInput type for fields where this option is enabled. This adds the support for the contains operator.

Search content for searchable fields with _fulltext

The GraphQL querying service generates a special _fulltext field for each content type. This matches the searchable fields on content. The type of fields where you can apply searchable can be any, including dates and numbers. Optimizely Graph supports full-text search on values of any basic field type with searchable, that is contains on the field _fulltext and is projected as such. The following GraphQL field types are supported with _fulltext:

  • String
  • Date
  • Int
  • Float
  • Bool

The separate values of the searchable fields are preserved without any overlap between values.

When you enable the Searchable property for a field, its child elements are also made searchable. The use of the _fulltext field is more efficient than querying for searchable fields separately.

Get searchable field values in content types

The GraphQL querying service lets you get searchable field values (includes its nested field values) in one field _fulltext with array string type on only the top level directly under items. All content types are supported.

Example:

{
  Content(locale: en) {
    items {
      Name
      _fulltext
    }
  }
}

Example result:

{
  "data": {
    "Content": {
      "items": [
        {
          "Name": "Abraham Lincoln",
          "_fulltext": [
            "Abraham Lincoln",
            "With malice toward none; with charity for...",
            "..."
          ]
        },
        {
          "Name": "Vincent Van Gogh",
          "_fulltext": [
            "<h3>Example</h3>",
            "Vincent Van Gogh",
            "..."
          ]
        }
      ]
    }
  }
}