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

Facets

Facets are all about enriching your search query responses. A Facet is a tool to help you generate counts for a value or range based on a field from your schema. A field can be text, number, date or geolocation data. At first glance, Facets may seem confusing. But things become clear when we look at the object we pass within our request:

// A skeleton-like example of a Facets request object.
{
  "query": string,
  "facets": {
    string: [
      {
        "type": string,
        key: { ... },
      }
    ]
  }
}'

A facet is the trusty side-kick of the search query. It is Robin to Batman. Therefore, first we provide a query. Next, we send in a facets object. Within that object, we need to specify a key that represents a Field from within our schema. Let us assume that your engine is filled with something that everybody loves - say, RubyGems.

Your schema may look something like this:

Existing Field Type
name Text
authors Text
info Text
downloads Number

First, a query without Facets. Consider that we have adjusted our search queries so that they put maximum weight towards the name field and minimum weight towards the info field. When we search for rake, the top Gem will be the one named... rake!

POST /api/as/v1/engines/{ENGINE_NAME}/search
Example - Performing a search query with maximum weight for name.
curl -X GET 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/ruby-gems/search' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer search-qcqrj73hmom796c98r22zeao' \
-d '{
  "search_fields": {
    "name": {
      "weight": 10
    },
    "info": {
      "weight": 1
    }
  },
  "query": "rake"
}'
Example Response
{
  "meta": {
    "warnings": [],
    "page": {
      "current": 1,
      "total_pages": 65,
      "total_results": 648,
      "size": 10
    },
    "request_id": "8d8793b7b3713bdb042fb5779228e5fd"
  },
  "results": [
    {
      "name": {
        "raw": "rake"
      },
      "id": {
        "raw": "1"
      },
      "authors": {
        "raw": "Hiroshi SHIBATA, Eric Hodel, Jim Weirich"
      },
      "downloads": {
        "raw": 195960151
      },
      "info": {
        "raw": "Rake is a Make-like program implemented in Ruby. Tasks and dependencies are\nspecified in standard Ruby syntax.\nRake has the following features:\n  * Rakefiles (rake's version of Makefiles) are completely defined in standard Ruby syntax.\n    No XML files to edit. No quirky Makefile syntax to worry about (is that a tab or a space?)\n  * Users ca
n specify tasks with prerequisites.\n  * Rake supports rule patterns to synthesize implicit tasks.\n  * Flexible FileLists that act like arrays but know about manipulating file names and paths.\n  * Supports parallel execution of tasks.\n"
      },
      "_meta": {
        "score": 144.31232
      }
    },
    {
      "name": {
        "raw": "rake-jekyll"
      },
      "id": {
        "raw": "6108"
      },
      "authors": {
        "raw": "Jakub Jirutka"
      },
      "downloads": {
        "raw": 18897
      },
      "info": {
        "raw": "Tasks for deploying Jekyll site to Git etc."
      },
      "_meta": {
        "score": 102.050446
      }
    },
    {
      "name": {
        "raw": "rake-hooks"
      },
      "id": {
        "raw": "5094"
      },
      "authors": {
        "raw": "Guillermo Álvarez, Joel Moss"
      },
      "downloads": {
        "raw": 125004
      },
      "info": {
        "raw": "Add after and before hooks to rake tasks. You can use \"after :task do ... end\" and \"before :task do ... end\"."
      },
      "_meta": {
        "score": 102.050446
      }
    },
    # ... Truncated
  ]
}

Example - Performing a search query with maximum weight for name.
No Java example available, showing cURL
curl -X GET 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/ruby-gems/search' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer search-qcqrj73hmom796c98r22zeao' \
-d '{
  "search_fields": {
    "name": {
      "weight": 10
    },
    "info": {
      "weight": 1
    }
  },
  "query": "rake"
}'
Example Response
No Java example available, showing cURL
{
  "meta": {
    "warnings": [],
    "page": {
      "current": 1,
      "total_pages": 65,
      "total_results": 648,
      "size": 10
    },
    "request_id": "8d8793b7b3713bdb042fb5779228e5fd"
  },
  "results": [
    {
      "name": {
        "raw": "rake"
      },
      "id": {
        "raw": "1"
      },
      "authors": {
        "raw": "Hiroshi SHIBATA, Eric Hodel, Jim Weirich"
      },
      "downloads": {
        "raw": 195960151
      },
      "info": {
        "raw": "Rake is a Make-like program implemented in Ruby. Tasks and dependencies are\nspecified in standard Ruby syntax.\nRake has the following features:\n  * Rakefiles (rake's version of Makefiles) are completely defined in standard Ruby syntax.\n    No XML files to edit. No quirky Makefile syntax to worry about (is that a tab or a space?)\n  * Users ca
n specify tasks with prerequisites.\n  * Rake supports rule patterns to synthesize implicit tasks.\n  * Flexible FileLists that act like arrays but know about manipulating file names and paths.\n  * Supports parallel execution of tasks.\n"
      },
      "_meta": {
        "score": 144.31232
      }
    },
    {
      "name": {
        "raw": "rake-jekyll"
      },
      "id": {
        "raw": "6108"
      },
      "authors": {
        "raw": "Jakub Jirutka"
      },
      "downloads": {
        "raw": 18897
      },
      "info": {
        "raw": "Tasks for deploying Jekyll site to Git etc."
      },
      "_meta": {
        "score": 102.050446
      }
    },
    {
      "name": {
        "raw": "rake-hooks"
      },
      "id": {
        "raw": "5094"
      },
      "authors": {
        "raw": "Guillermo Álvarez, Joel Moss"
      },
      "downloads": {
        "raw": 125004
      },
      "info": {
        "raw": "Add after and before hooks to rake tasks. You can use "after :task do ... end" and "before :task do ... end"."
      },
      "_meta": {
        "score": 102.050446
      }
    },
    # ... Truncated
  ]
}

Example - Performing a search query with maximum weight for name.
No Node example available, showing cURL
curl -X GET 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/ruby-gems/search' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer search-qcqrj73hmom796c98r22zeao' \
-d '{
  "search_fields": {
    "name": {
      "weight": 10
    },
    "info": {
      "weight": 1
    }
  },
  "query": "rake"
}'
Example Response
No Node example available, showing cURL
{
  "meta": {
    "warnings": [],
    "page": {
      "current": 1,
      "total_pages": 65,
      "total_results": 648,
      "size": 10
    },
    "request_id": "8d8793b7b3713bdb042fb5779228e5fd"
  },
  "results": [
    {
      "name": {
        "raw": "rake"
      },
      "id": {
        "raw": "1"
      },
      "authors": {
        "raw": "Hiroshi SHIBATA, Eric Hodel, Jim Weirich"
      },
      "downloads": {
        "raw": 195960151
      },
      "info": {
        "raw": "Rake is a Make-like program implemented in Ruby. Tasks and dependencies are\nspecified in standard Ruby syntax.\nRake has the following features:\n  * Rakefiles (rake's version of Makefiles) are completely defined in standard Ruby syntax.\n    No XML files to edit. No quirky Makefile syntax to worry about (is that a tab or a space?)\n  * Users ca
n specify tasks with prerequisites.\n  * Rake supports rule patterns to synthesize implicit tasks.\n  * Flexible FileLists that act like arrays but know about manipulating file names and paths.\n  * Supports parallel execution of tasks.\n"
      },
      "_meta": {
        "score": 144.31232
      }
    },
    {
      "name": {
        "raw": "rake-jekyll"
      },
      "id": {
        "raw": "6108"
      },
      "authors": {
        "raw": "Jakub Jirutka"
      },
      "downloads": {
        "raw": 18897
      },
      "info": {
        "raw": "Tasks for deploying Jekyll site to Git etc."
      },
      "_meta": {
        "score": 102.050446
      }
    },
    {
      "name": {
        "raw": "rake-hooks"
      },
      "id": {
        "raw": "5094"
      },
      "authors": {
        "raw": "Guillermo Álvarez, Joel Moss"
      },
      "downloads": {
        "raw": 125004
      },
      "info": {
        "raw": "Add after and before hooks to rake tasks. You can use "after :task do ... end" and "before :task do ... end"."
      },
      "_meta": {
        "score": 102.050446
      }
    },
    # ... Truncated
  ]
}

Example - Performing a search query with maximum weight for name.
No Ruby example available, showing cURL
curl -X GET 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/ruby-gems/search' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer search-qcqrj73hmom796c98r22zeao' \
-d '{
  "search_fields": {
    "name": {
      "weight": 10
    },
    "info": {
      "weight": 1
    }
  },
  "query": "rake"
}'
Example Response
No Ruby example available, showing cURL
{
  "meta": {
    "warnings": [],
    "page": {
      "current": 1,
      "total_pages": 65,
      "total_results": 648,
      "size": 10
    },
    "request_id": "8d8793b7b3713bdb042fb5779228e5fd"
  },
  "results": [
    {
      "name": {
        "raw": "rake"
      },
      "id": {
        "raw": "1"
      },
      "authors": {
        "raw": "Hiroshi SHIBATA, Eric Hodel, Jim Weirich"
      },
      "downloads": {
        "raw": 195960151
      },
      "info": {
        "raw": "Rake is a Make-like program implemented in Ruby. Tasks and dependencies are\nspecified in standard Ruby syntax.\nRake has the following features:\n  * Rakefiles (rake's version of Makefiles) are completely defined in standard Ruby syntax.\n    No XML files to edit. No quirky Makefile syntax to worry about (is that a tab or a space?)\n  * Users ca
n specify tasks with prerequisites.\n  * Rake supports rule patterns to synthesize implicit tasks.\n  * Flexible FileLists that act like arrays but know about manipulating file names and paths.\n  * Supports parallel execution of tasks.\n"
      },
      "_meta": {
        "score": 144.31232
      }
    },
    {
      "name": {
        "raw": "rake-jekyll"
      },
      "id": {
        "raw": "6108"
      },
      "authors": {
        "raw": "Jakub Jirutka"
      },
      "downloads": {
        "raw": 18897
      },
      "info": {
        "raw": "Tasks for deploying Jekyll site to Git etc."
      },
      "_meta": {
        "score": 102.050446
      }
    },
    {
      "name": {
        "raw": "rake-hooks"
      },
      "id": {
        "raw": "5094"
      },
      "authors": {
        "raw": "Guillermo Álvarez, Joel Moss"
      },
      "downloads": {
        "raw": 125004
      },
      "info": {
        "raw": "Add after and before hooks to rake tasks. You can use "after :task do ... end" and "before :task do ... end"."
      },
      "_meta": {
        "score": 102.050446
      }
    },
    # ... Truncated
  ]
}

Example - Performing a search query with maximum weight for name.
No Python example available, showing cURL
curl -X GET 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/ruby-gems/search' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer search-qcqrj73hmom796c98r22zeao' \
-d '{
  "search_fields": {
    "name": {
      "weight": 10
    },
    "info": {
      "weight": 1
    }
  },
  "query": "rake"
}'
Example Response
No Python example available, showing cURL
{
  "meta": {
    "warnings": [],
    "page": {
      "current": 1,
      "total_pages": 65,
      "total_results": 648,
      "size": 10
    },
    "request_id": "8d8793b7b3713bdb042fb5779228e5fd"
  },
  "results": [
    {
      "name": {
        "raw": "rake"
      },
      "id": {
        "raw": "1"
      },
      "authors": {
        "raw": "Hiroshi SHIBATA, Eric Hodel, Jim Weirich"
      },
      "downloads": {
        "raw": 195960151
      },
      "info": {
        "raw": "Rake is a Make-like program implemented in Ruby. Tasks and dependencies are\nspecified in standard Ruby syntax.\nRake has the following features:\n  * Rakefiles (rake's version of Makefiles) are completely defined in standard Ruby syntax.\n    No XML files to edit. No quirky Makefile syntax to worry about (is that a tab or a space?)\n  * Users ca
n specify tasks with prerequisites.\n  * Rake supports rule patterns to synthesize implicit tasks.\n  * Flexible FileLists that act like arrays but know about manipulating file names and paths.\n  * Supports parallel execution of tasks.\n"
      },
      "_meta": {
        "score": 144.31232
      }
    },
    {
      "name": {
        "raw": "rake-jekyll"
      },
      "id": {
        "raw": "6108"
      },
      "authors": {
        "raw": "Jakub Jirutka"
      },
      "downloads": {
        "raw": 18897
      },
      "info": {
        "raw": "Tasks for deploying Jekyll site to Git etc."
      },
      "_meta": {
        "score": 102.050446
      }
    },
    {
      "name": {
        "raw": "rake-hooks"
      },
      "id": {
        "raw": "5094"
      },
      "authors": {
        "raw": "Guillermo Álvarez, Joel Moss"
      },
      "downloads": {
        "raw": 125004
      },
      "info": {
        "raw": "Add after and before hooks to rake tasks. You can use "after :task do ... end" and "before :task do ... end"."
      },
      "_meta": {
        "score": 102.050446
      }
    },
    # ... Truncated
  ]
}

Example - Performing a search query with maximum weight for name.
No Javascript example available, showing cURL
curl -X GET 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/ruby-gems/search' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer search-qcqrj73hmom796c98r22zeao' \
-d '{
  "search_fields": {
    "name": {
      "weight": 10
    },
    "info": {
      "weight": 1
    }
  },
  "query": "rake"
}'
Example Response
No Javascript example available, showing cURL
{
  "meta": {
    "warnings": [],
    "page": {
      "current": 1,
      "total_pages": 65,
      "total_results": 648,
      "size": 10
    },
    "request_id": "8d8793b7b3713bdb042fb5779228e5fd"
  },
  "results": [
    {
      "name": {
        "raw": "rake"
      },
      "id": {
        "raw": "1"
      },
      "authors": {
        "raw": "Hiroshi SHIBATA, Eric Hodel, Jim Weirich"
      },
      "downloads": {
        "raw": 195960151
      },
      "info": {
        "raw": "Rake is a Make-like program implemented in Ruby. Tasks and dependencies are\nspecified in standard Ruby syntax.\nRake has the following features:\n  * Rakefiles (rake's version of Makefiles) are completely defined in standard Ruby syntax.\n    No XML files to edit. No quirky Makefile syntax to worry about (is that a tab or a space?)\n  * Users ca
n specify tasks with prerequisites.\n  * Rake supports rule patterns to synthesize implicit tasks.\n  * Flexible FileLists that act like arrays but know about manipulating file names and paths.\n  * Supports parallel execution of tasks.\n"
      },
      "_meta": {
        "score": 144.31232
      }
    },
    {
      "name": {
        "raw": "rake-jekyll"
      },
      "id": {
        "raw": "6108"
      },
      "authors": {
        "raw": "Jakub Jirutka"
      },
      "downloads": {
        "raw": 18897
      },
      "info": {
        "raw": "Tasks for deploying Jekyll site to Git etc."
      },
      "_meta": {
        "score": 102.050446
      }
    },
    {
      "name": {
        "raw": "rake-hooks"
      },
      "id": {
        "raw": "5094"
      },
      "authors": {
        "raw": "Guillermo Álvarez, Joel Moss"
      },
      "downloads": {
        "raw": 125004
      },
      "info": {
        "raw": "Add after and before hooks to rake tasks. You can use "after :task do ... end" and "before :task do ... end"."
      },
      "_meta": {
        "score": 102.050446
      }
    },
    # ... Truncated
  ]
}

Our schema has some text fields and a number field. Under a field, there are keys. Next to keys, are values. A facet will count values based on their key.

If we were to apply a Facet with a value for the ranges parameter, then plug-in downloads as our field, or key, to generate a count...

Example - Performing a search query using a facet to count Gems with more than 100,000 downloads.
curl -X GET 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/ruby-gems/search' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer search-qcqrj73hmom796c98r22zeao' \
-d '{
  "query": "rake",
  "search_fields": {
    "name": {
      "weight": 10
    }
  },
  "facets": {
    "downloads": [
      {
        "type": "range",
        "ranges": [
          { "from": 100000 }
        ]
      }
    ]
  }
}'
Example Response
{
  "meta": {
    "warnings": [],
    "page": {
      "current": 1,
      "total_pages": 12,
      "total_results": 117,
      "size": 10
    },
    "request_id": "8b47cd138c8eb1ad021a5427a788b4ac"
  },
  "results": [
    # ... Truncated
  ]
  "facets": {
    "downloads": [
      {
        "type": "range",
        "data": [
          {
            "from": 100000,
            "count": 66
          }
        ]
      }
    ]
  }
}

Example - Performing a search query using a facet to count Gems with more than 100,000 downloads.
No Java example available, showing cURL
curl -X GET 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/ruby-gems/search' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer search-qcqrj73hmom796c98r22zeao' \
-d '{
  "query": "rake",
  "search_fields": {
    "name": {
      "weight": 10
    }
  },
  "facets": {
    "downloads": [
      {
        "type": "range",
        "ranges": [
          { "from": 100000 }
        ]
      }
    ]
  }
}'
Example Response
No Java example available, showing cURL
{
  "meta": {
    "warnings": [],
    "page": {
      "current": 1,
      "total_pages": 12,
      "total_results": 117,
      "size": 10
    },
    "request_id": "8b47cd138c8eb1ad021a5427a788b4ac"
  },
  "results": [
    # ... Truncated
  ]
  "facets": {
    "downloads": [
      {
        "type": "range",
        "data": [
          {
            "from": 100000,
            "count": 66
          }
        ]
      }
    ]
  }
}

Example - Performing a search query using a facet to count Gems with more than 100,000 downloads.
No Node example available, showing cURL
curl -X GET 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/ruby-gems/search' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer search-qcqrj73hmom796c98r22zeao' \
-d '{
  "query": "rake",
  "search_fields": {
    "name": {
      "weight": 10
    }
  },
  "facets": {
    "downloads": [
      {
        "type": "range",
        "ranges": [
          { "from": 100000 }
        ]
      }
    ]
  }
}'
Example Response
No Node example available, showing cURL
{
  "meta": {
    "warnings": [],
    "page": {
      "current": 1,
      "total_pages": 12,
      "total_results": 117,
      "size": 10
    },
    "request_id": "8b47cd138c8eb1ad021a5427a788b4ac"
  },
  "results": [
    # ... Truncated
  ]
  "facets": {
    "downloads": [
      {
        "type": "range",
        "data": [
          {
            "from": 100000,
            "count": 66
          }
        ]
      }
    ]
  }
}

Example - Performing a search query using a facet to count Gems with more than 100,000 downloads.
No Ruby example available, showing cURL
curl -X GET 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/ruby-gems/search' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer search-qcqrj73hmom796c98r22zeao' \
-d '{
  "query": "rake",
  "search_fields": {
    "name": {
      "weight": 10
    }
  },
  "facets": {
    "downloads": [
      {
        "type": "range",
        "ranges": [
          { "from": 100000 }
        ]
      }
    ]
  }
}'
Example Response
No Ruby example available, showing cURL
{
  "meta": {
    "warnings": [],
    "page": {
      "current": 1,
      "total_pages": 12,
      "total_results": 117,
      "size": 10
    },
    "request_id": "8b47cd138c8eb1ad021a5427a788b4ac"
  },
  "results": [
    # ... Truncated
  ]
  "facets": {
    "downloads": [
      {
        "type": "range",
        "data": [
          {
            "from": 100000,
            "count": 66
          }
        ]
      }
    ]
  }
}

Example - Performing a search query using a facet to count Gems with more than 100,000 downloads.
No Python example available, showing cURL
curl -X GET 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/ruby-gems/search' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer search-qcqrj73hmom796c98r22zeao' \
-d '{
  "query": "rake",
  "search_fields": {
    "name": {
      "weight": 10
    }
  },
  "facets": {
    "downloads": [
      {
        "type": "range",
        "ranges": [
          { "from": 100000 }
        ]
      }
    ]
  }
}'
Example Response
No Python example available, showing cURL
{
  "meta": {
    "warnings": [],
    "page": {
      "current": 1,
      "total_pages": 12,
      "total_results": 117,
      "size": 10
    },
    "request_id": "8b47cd138c8eb1ad021a5427a788b4ac"
  },
  "results": [
    # ... Truncated
  ]
  "facets": {
    "downloads": [
      {
        "type": "range",
        "data": [
          {
            "from": 100000,
            "count": 66
          }
        ]
      }
    ]
  }
}

Example - Performing a search query using a facet to count Gems with more than 100,000 downloads.
No Javascript example available, showing cURL
curl -X GET 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/ruby-gems/search' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer search-qcqrj73hmom796c98r22zeao' \
-d '{
  "query": "rake",
  "search_fields": {
    "name": {
      "weight": 10
    }
  },
  "facets": {
    "downloads": [
      {
        "type": "range",
        "ranges": [
          { "from": 100000 }
        ]
      }
    ]
  }
}'
Example Response
No Javascript example available, showing cURL
{
  "meta": {
    "warnings": [],
    "page": {
      "current": 1,
      "total_pages": 12,
      "total_results": 117,
      "size": 10
    },
    "request_id": "8b47cd138c8eb1ad021a5427a788b4ac"
  },
  "results": [
    # ... Truncated
  ]
  "facets": {
    "downloads": [
      {
        "type": "range",
        "data": [
          {
            "from": 100000,
            "count": 66
          }
        ]
      }
    ]
  }
}

We now know that there are 66 other gems that match on rake that have over 100,000 downloads.

The key is that the user found what they were looking for, they wanted rake and they found rake. However, if you want to get ahead of their experience, to guide them in an aware and intelligent way, then Facets are an invaluable tool in trying to predict what the visitor will want to find next. In this way, we enrich the search experience.

If people were searching for a certain make of Car, you could count and return all of the colours -- perhaps they really want a blue one.

If they were searching for Thai Curry recipes, you could count and return all of the flavours -- perhaps they really want a red one!

You can apply Facets on key values, number ranges, geographical coordinates, sort ascending or descending, determine the size of the result response, chain them in deeper queries and much more.

For full detail on how to apply Facets, check out the Search API Reference.

What's Next?

You are well on your way to getting a handle on search and its many... facets (hehehe). Poor jokes aside, there are many other features that can help you get the most out of App Search. You might want to learn how to gain insights into user search data. For that, Analytics and Clickthrough will serve you well. If you are looking to get into result tuning, consider Curations.


Stuck? Looking for help? Contact Support!