Controlling facet options

Note

See Using faceted search for basic facet use cases.

The response returns facet values based on the sort order and the max you specify. If you require a fixed list of facets, use a value object. You can either use facet IDs or facet values, but we recommend using facet IDs.

If the request has a fixed list of facets, the response returns facets in the same order, regardless of the sort order. If the fixed list of facets is less than the max, the remaining facets are dynamic and conform to sort.

The following examples continue the getting facet values from each facet type example.

Getting fixed facet values that are available

The following shows an example of getting fixed facet values. In this example, you request only the white, red, and black facet values from the colors facet.

Here is a sample request that uses facet IDs:

RequestResponse
{
  "facet": {
    "colors": {
      "max": 3,
      "value": ["color_id_white", "color_id_red", "color_id_black"]
    }
  }
}

Here is a sample request that uses facet names:

RequestResponse
{
  "facet": {
    "colors": {
      "max": 3,
      "value": ["white", "red", "black"]
    }
  }
}

Here is the response:

RequestResponse
{
  "ts": 1480977544,
  "rid": "response_id_fc1",
  "facet": {
    "colors": {
      "value": [
        {"id": "color_id_white", "text": "White", "count": 1},
        {"id": "color_id_red", "text": "Red", "count": 23},
        {"id": "color_id_black", "text": "Black", "count": 8}
      ]  
    }
  },
  "facet_names": ["colors"]
}

The response returns the colors in the same order provided in the request.

Getting multiple fixed facet values from a facet regardless of item count

The following shows an example of getting multiple fixed facet values. In this example, you request three fixed facet values (white, black, and grey) from the colors facet regardless of item count.

Here is the request:

RequestResponse
{
  "facet": {
    "colors": {
      "min_count": 0,
      "max": 3,
      "value": ["color_id_white", "color_id_black", "color_id_grey"]
    }
  }
}
Note

To get a facet that does not contain any item (count = 0), set min_count to 1 .

Here is the response:

RequestResponse
{
  "ts": 1480977544,
  "rid": "response_id_186",
  "facet": {
    "colors": {
      "value": [
        {"id": "color_id_white", "text": "White", "count": 1},
        {"id": "color_id_black", "text": "Black", "count": 8},
        {"id": "color_id_grey", "text": "Grey", "count": 0}
      ]  
    }
  },
  "facet_names": ["colors"]
}

Getting a mix of fixed facets and dynamic facets

The following shows an example of getting a mix of fixed and dynamic facets. In this example, you request three fixed facet values (white, red, and black) from the colors facet and two dynamic colors.

Here is the request:

RequestResponse
{
  "facet": {
    "colors": {
      "max": 5,
      "value": ["color_id_white", "color_id_red", "color_id_black"]
    }
  }
}

Here is the response:

RequestResponse
{
  "ts": 1480977544,
  "rid": "response_id_185",
  "facet": {
    "colors": {
      "value": [
        {"id": "color_id_white", "text": "White", "count": 1},
        {"id": "color_id_red", "text": "Red", "count": 23},
        {"id": "color_id_black", "text": "Black", "count": 8},
        {"id": "color_id_blue", "text": "Blue", "count": 11},
        {"id": "color_id_yellow", "text": "Yellow", "count": 10}
      ]  
    }
  },
  "facet_names": ["colors"]
}

Getting facets with a minimum count

The following shows an example of getting facets with a minimum count. In this example, you request three facet values where each facet value has at least ten items in it (min_count = 10).

Here is the request:

RequestResponse
{
  "facet": {
    "colors": {
      "min_count": 10,
      "max": 3,
      "value": ["color_id_white", "color_id_red", "color_id_black"]
    }
  }
}

Here is the response:

RequestResponse
{
  "ts": 1480977544,
  "rid": "response_id_186",
  "facet": {
    "colors": {
      "value": [
        {"id": "color_id_red", "text": "Red", "count": 23},
        {"id": "color_id_blue", "text": "Blue", "count": 11},
        {"id": "color_id_yellow", "text": "Yellow", "count": 10}
      ]  
    }
  },
  "facet_names": ["colors"]
}

Getting the total number of facet values for all facets

The following shows an example to get the total number of facet values for all facets.

Here is the request:

RequestResponse
{
  "facet": {
    "total": true,
    "colors": {
      "max": 1,
    },
    "genders": {
      "max": 2
    }
  }
}

Here is the response:

RequestResponse
{
  "ts": 1480977544,
  "rid": "response_id_186",
  "facet": {
    "colors": {
      "total": 11,
      "value": [
        {"id": "color_id_red", "text": "Red", "count": 23}
      ]  
    },
    "genders": {
      "total": 4,
      "value": [
        {"id": "gender_id_male", "text": "Men's", "count": 20},
        {"id": "gender_id_female", "text": "Women's", "count": 21}
      ]
    }
  },
  "facet_names": ["colors", "genders"]
}

Getting the total number of facet values for one facet

The following shows an example to get the total number of facet values for a single facet.

Here is the request:

RequestResponse
{
  "facet": {
    "colors": {
      "total": true,
      "max": 1,
    },
    "genders": {
      "max": 2
    }
  }
}

Here is the response:

RequestResponse
{
  "ts": 1480977544,
  "rid": "response_id_186",
  "facet": {
    "colors": {
      "total": 11,
      "value": [
        {"id": "color_id_red", "text": "Red", "count": 23}
      ]  
    },
    "genders": {
      "value": [
        {"id": "gender_id_male", "text": "Men's", "count": 20},
        {"id": "gender_id_female", "text": "Women's", "count": 21}
      ]
    }
  },
  "facet_names": ["colors", "genders"]
}

Do you have some feedback for us?

If you have suggestions for improving this article,