FacetDefinition

The field name to create a facet against. For example, the following query will create a facet against the custom_attributes.director field, and return the ten most common facet values of this field (for Products that match the search query):

{
    "field": "custom_attributes.director",
    "size": 10
}

The alias parameter gives a unique name to a facet, especially useful when you have multiple facets on the same field.

By default, facet results use the field as the key. But with multiple facets on one field, this can get confusing. alias solves this:

{
   "field": "custom_attributes.director",
   "alias": "director_facet",
   "size": 10
}

In the response, you'll see results under the key director_facet instead of the field name.

The exclude parameter filters out facet values using a regular expression. For example:

{
    "field": "custom_attributes.director",
    "size": 10,
    "exclude": "Steven.*"
}

This will omit all facet values starting with "Steven" (case-sensitive).

To exclude values with special characters, use a backslash \ or double quotes:

{
    "field": "custom_attributes.place_name",
    "size": 10,
    "exclude": "\"St.\".*"
}

This excludes facet values starting with "St.".

Remember, exclude only affects facet values, not the search results themselves.

Filter facet values based on a regular expression. For example, the following query will return only the facet values that start with Steven (case-sensitive):

{
    "field": "custom_attributes.director",
    "size": 10,
    "include": "Steven.*"
}

You can escape a special character with a preceding backslash \ or surround it with double quotes. For example, the following query will only return the facet values starting with St.:

{
    "field": "custom_attributes.place_name",
    "size": 10,
    "include": "\"St.\".*"
}

Note that, the include parameter will only affect the facet values, and will not affect the search result itself.

Facet queries that support facet counts for any arbitrary Lucene queries, each of which is labeled by a user-friendly "key":

{
    "field": "my_custom_facet",
    "queries": [
        {
            "query": "price: [* TO 10] AND size:"Small"",
            "key": "Less than 10 dollars / Small size"
        },
        {
            "query": "price: [10 TO 100] AND size:"Medium"",
            "key": "10 to 100 dollars / Medium size"
        },
        {
            "query": "price: [100 TO *] AND size:"Large"",
            "key": "More than 100 dollars / Large size"
        }
    ]
}

In the response, Miso refers to the query result by their key. For example, the above request will have the following response:

{
  "facet_counts": {
    "facet_fields": {
      "my_custom_facet": [
        [
          "Less than 10 dollars / Small size", 1987
        ],
        [
          "10 to 100 dollars / Medium size", 109
        ],
        [
          "More than 100 dollars / Large size", 123
        ]
      ]
    }
  }
}

Facet ranges for numeric fields or date-like string fields. For example, the following query groups the products into fours buckets against on their original_price ranges, each of which has a user-friendly "key":

{
    "field": "original_price",
    "ranges": [
        {"to": 10, "key": "Less than 10 dollars"},
        {"from": 10, "to": 100, "key": "10 to 100 dollars"},
        {"from": 100, "to": 1000, "key": "100 to 1,000 dollars"},
        {"from": 1000, "key": "More than 1,000 dollars"}
    ]
}

For each range object, you need to at least specify one of the to or from values (or both). from is always inclusive, and to is always exclusive. In the response, Miso refers to each bucket by their key. For example, the above request will have the following response:

{
  "facet_counts": {
    "facet_fields": {
      "original_price": [
        [
          "Less than 10 dollars", 1987
        ],
        [
          "10 to 100 dollars", 109
        ],
        [
          "100 to 1,000 dollars", 123
        ],
        [
          "More than 1,000 dollars", 5
        ]
      ]
    }
  }
}

Number of facet values to return. The facet values are sort descendingly by the number of Products that have these values (and match the search query).