Autocomplete

Auto-complete, word completion, type-ahead, or search-as-you-type, is a feature in which an application predicts the rest of a word a user is typing. The use-cases for autocomplete are:

• Prevents queries with no results.
• Prevents spelling mistakes.
• Faster to create query and get results.
• Gives ideas to visitors of other queries to use.

You can implement autocomplete as part of a search box and search in facets as part of the navigation.

You can retrieve autocomplete suggestions using the autocomplete root level field, similar to facets. With this output field, you can get autocomplete suggestions for all fields with the type StringFilterInput, including nested fields like ContentLink.GuidValue. Autocomplete is not supported for other field types, but you can always use full-text search to match on fields of type SearchableStringFilterInput. Autocomplete lets visitors get values to filter on, making a page more relevant to them.

You have two input arguments:

• value – Mandatory
  • Can be 1 or more words and in the same word order.
  • Each word can be 10 characters, when longer, no suggestions are returned.
  • In case value consists of only an empty string, then no autocomplete suggestions are retrieved.
  • Punctuation characters will be ignored when matching.
  • HTML tags will not match with results.
• limit – Optional
  • Default is 10.
  • Not supported higher than 1,000.
  • Recommended to be set to 0 as input argument of the content type for best performance. By default it is already 0 when no where is used.
    • For example, BiographyPage(limit:0)

Multiple fields

You can select one or more fields in autocomplete:

{
  BiographyPage {
    autocomplete {
      ContentLink {
        GuidValue(value: "3e53")
      }
      Status(value: "pub")
    }
  }
}

The autocomplete suggestions are returned as a list in the projected autocomplete field:

"data": {
  "BiographyPage": {
    "autocomplete": {
      "ContentLink": {
        "GuidValue": [
          "4eaece75-3e53-440b-8dec-eb8d6d6895e0"
        ]
      },
      "Status": [
        "Published"
      ]
    }
  }
}

Multi-valued fields with higher cardinality

Autocomplete is very useful when a field is multi-valued and has a higher cardinality.

{
  BiographyPage {
    autocomplete {
      Tags(value: "peo", limit: 5)
    }
  }
}

The values in Tags have overlapping values between items, and more relevant suggestions will be ranked higher. So the following suggestions can be returned, limited by the top five suggestions as requested:

"data": {
  "BiographyPage": {
    "autocomplete": {
      "Tags": [
        "People who committed suicide",
        "People who are Nobel laureates",
        "Bletchley Park people",
        "British people of World War II",
        "Colony of Jamaica people"
      ]
    }
  }
}

Use multiple words

You can retrieve autocomplete suggestions using phrases:

{
  BiographyPage {
    autocomplete {
      Tags(value: "who are")
    }
  }
}

The following example returns suggestions that contain the phrase who are like this:

"data": {
  "BiographyPage": {
    "autocomplete": {
      "Tags": [
        "People who are Nobel laureates"
      ]
    }
  }
}

Using special characters and punctuation

This query with special characters will return suggestions with special characters:

{
  BiographyPage {
    total
    autocomplete {
      Tags(value: "a thu của")
    }
  }
}

However, this query will not return any results because it contains HTML tags:

{
  BiographyPage {
    total
    autocomplete {
      Tags(value: "<p>mainbody</p>\\n<p>m&ugrave;a thu của em&nbsp;</p>")
    }
  }
}

Neither will this query return any suggestions, because we do not support matching on punctuation characters:

{
  BiographyPage {
    total
    autocomplete {
      Tags(value: "!@#$%^&")
    }
  }
}

Combine with filtering and search

You can combine autocomplete with filtering and search using the where input argument. The autocomplete suggestions are refined to the result set. The result set is also narrowed down by the autocomplete value used.

📘

Note

Optimizely has set the limit to 0 in the content type for best performance.

{
  BiographyPage(
    limit:0,
    where: { Tags: { in: ["People who committed suicide", "People who are Nobel laureates"] } }
  ) {
    total
    autocomplete {
      Tags(value: "who", limit: 5)
    }
  }
}

The following example returns suggestions that only match within the three items:

"BiographyPage": {
  "total": 3,
  "autocomplete": {
    "Tags": [
      "People who committed suicide",
      "People who are Nobel laureates",
      "People who have received posthumous pardons"
    ]
  }
}

Combine with facets

You can combine autocomplete suggestions with facets. The facets returned are determined by the narrowed down search results (items) by applying the autocomplete value as a filter:

{
  BiographyPage {
    total
    autocomplete {
      Tags(value: "nobe", limit: 5)
    }
    facets {
      Tags (limit: 5) {
        name
        count
      }
    }
  }
}

Response:

"data": {
  "BiographyPage": {
    "total": 2,
    "autocomplete": {
      "Tags": [
        "People who are Nobel laureates",
        "French Nobel laureates",
        "Nobel laureates in Chemistry",
        "Nobel laureates in Physics",
        "Nobel laureates with multiple Nobel awards"
      ]
    },
    "facets": {
      "Tags": [
        {
          "name": "People who are Nobel laureates",
          "count": 2
        },
        {
          "name": "People who committed suicide",
          "count": 2
        },
        {
          "name": "1867 births",
          "count": 1
        },
        {
          "name": "1912 births",
          "count": 1
        },
        {
          "name": "1934 deaths",
          "count": 1
        }
      ]
    }
  }
}