search mobile facets autocomplete spellcheck crawler rankings weights synonyms analytics engage api customize documentation install setup technology content domains user history info home business cart chart contact email activate analyticsalt analytics autocomplete cart contact content crawling custom documentation domains email engage faceted history info install mobile person querybuilder search setup spellcheck synonyms weights engage_search_term engage_related_content engage_next_results engage_personalized_results engage_recent_results success add arrow-down arrow-left arrow-right arrow-up caret-down caret-left caret-right caret-up check close content conversions-small conversions details edit grid help small-info error live magento minus move photo pin plus preview refresh search settings small-home stat subtract text trash unpin wordpress x alert case_deflection advanced-permissions keyword-detection predictive-ai sso
Site Search Documentation / tutorials: Customizing Swiftype Search Results with jQuery

Customizing Swiftype Search Results with jQuery

The Swiftype jQuery plugin gives you an easy way to control your search results without needing to use the Swiftype API directly. For this tutorial, we have created a simple website to demonstrate features of the crawler and how they can be used from the jQuery plugin. Before beginning this tutorial, take a quick look at the website and the meta tags in its source code.

Note: The engine key given in this tutorial is a real, working key. The results shown are fetched from the Swiftype API. Feel free to examine the source code of the demo site and try your own queries.

  1. Changing the list of fields returned
  2. Restricting matches to specified fields
  3. Filtering
  4. Range queries
  5. Sorting
  6. Faceting
  7. Configuration with functions

Changing the list of fields returned

You can change the list of fields returned by Swiftype with the fetchFields option. By default, this returns all string, text, and enum fields (read more about field types). You can see the default results of a search for "post" in Example 1.

Example 1

   engineKey: 'hGbFw82z3WdSMZ9q764B',
   resultContainingElement: '#st-results-container'

Example 1 Output

To change the fields returned, specify the fields you want in the fetchFields as shown in Example 2. The document type for crawled pages is page, so that is used as the key.

Example 2

   engineKey: 'hGbFw82z3WdSMZ9q764B',
   fetchFields: {'page': ['title', 'url']}

Example 2 Output

Now, only title and url (and the special field id which is always returned) are returned with the search results.

Subsequent examples make use of fetchFields to make the JSON results easier to read.

Restricting matches to specified fields

By default, Swiftype will match all string and text fields. To restrict this behavior, use the searchFields option. Again, the page Document Type is used as the key.

In Example 3, searching is restricted only to the title field.

Example 3

  engineKey: 'jaDGyzkR6iYHkfNsPpNK',
  fetchFields: {'page': ['title', 'url']},
  searchFields: {'page': ['title']}

Example 3 Output

Only documents with the word "post" in the title are matched.


Filters are additional query parameters that are always applied to searches. One way to use filters is to restrict results by the value of a field. The page schema has a field type that can be set with the st:type meta tag. The example site has two values for type:page and post (for example, you could use this to separate static pages from blog posts).

Example 4 shows a search for "post" filtered so that the results only match documents with type page.

Example 4

   engineKey: 'hGbFw82z3WdSMZ9q764B',
   fetchFields: {'page': ['title', 'url', 'type']},
   filters: {'page': {'type': 'page'}}

Example 4 Output

Range queries

Another type of filter is a range query. Range queries may be applied to date, integer and float fields. The crawler schema includes a published_at date field which can be set with the st:published_at meta tag. Example 5 uses a range filter on published_at to restrict results for the term "post" to the range January 1, 2012 – June 1, 2012.

Example 5

   engineKey: 'hGbFw82z3WdSMZ9q764B',
   fetchFields: {'page': ['title', 'url', 'published_at']},
   filters: {'page': {'published_at': {'type': 'range', 'from': '2012-01-01', 'to': '2012-06-01'}}}

Example 5 Output

All documents published after June 1, 2012 are excluded.


By default, Swiftype sorts by relevance. However, this can be changed with the sortField and sortDirection options. Only enum, integer, float, and date field types can be sorted on.

Example 6 sorts the results of the query "post" by the published_at field in descending order (like a blog's reverse chronological order). The value of sortField is a mapping of DocumentType slugs (in this case, page) to the field to sort by. The value for sortDirection is a mapping of DocumentType slugs to direction (asc or desc).

Example 6

   engineKey: 'hGbFw82z3WdSMZ9q764B',
   fetchFields: {'page': ['title', 'url', 'published_at']},
   sortField: {'page': 'published_at'},
   sortDirection: {'page': 'desc'}

Example 6 Output


Facets allow you to get a count of each unique value of a field for a given query. Fields available for faceting must be of type enum, float, integer, or date (see the Schema Design Tutorial for more details).

Facets are returned in the info section of the response with an entry for each field that was used for faceting.

Example 7 facets the results of the query "post" by the type field (which is an enum containing either "page" or "post" in this engine.)

Example 7

   engineKey: 'hGbFw82z3WdSMZ9q764B',
   fetchFields: {'page': ['title', 'url', 'published_at']},
   facets: {'page': ['type']}

Example 7 Output

Configuration with Functions

All of the configuration options described above can take a function as an argument. The function is evaluated when the search is submitted. This allows customization of the search query based on user input. See the custom.html file in the GitHub repository for an example.