Faceting Syntax

Facets can be returned with a query by adding the facets parameter. All numeric and date based values specified in the parsetable are able to be faceted and can be faceted based on where their value falls within an overall range. This document details responses received from the different facet queries that the search engine accepts.

Date and Number Facets

To facet a number or date field, add &facets=fieldname:range(params) to the query URI, where fieldname is the field specified in the parse table, and params includes at least three of the following five parameters. One must be a beginning (begin or before), one must be gap, and one must be ending (end or after).

• begin - The first value in the range (Required)
• end - The first value beyond the range (Required)
• gap - How the range is divided into bins (Required)
• before - Include a special bin for all values before the begin parameter (Optional; default = false)
• after - Include a special bin for all values after the end parameter (Optional; default = false)

The five parameters (begin, end, gap, before, after) can be specified in any order. The bins are only available in ascending format and are limited to a total of 100. The gaps that delineate bins within the range can be non-uniform in size.

Example:

https://<appliance_ip>/search?q=doctor&facets=n.height:range(begin:0, end:80, gap:10)

Response:

...
<facets>
  <facet name="height" type="number">
    <bins>
      <bin range="[0 TO 10}">0</bin>
      <bin range="[10 TO 20}">0</bin>
      <bin range="[20 TO 30}">0</bin>
      <bin range="[30 TO 40}">0</bin>
      <bin range="[40 TO 50}">0</bin>
      <bin range="[50 TO 60}">3</bin>
      <bin range="[60 TO 70}">10</bin>
      <bin range="[70 TO 80}">5</bin>
    </bins>
  </facet>
</facets>

You can enter a shortcut syntax, but the begin, end, and gap must be in that order.

Example

https://<appliance_ip>/search?q=doctor&facets=n.height:range(0, 80, 10)

String Facets

To facet a string facets, add &facets=name:field(params) to the query URI, where name is specified in the taxonomy file, and params includes under or undertn. See here for some more discussion and examples.

Enter &facets="" as part of your query to discover all available fields that can run facets.

You can uses facets in lists using IMAT's Boolean IN:

https://<appliance_ip>/search?q=car&facets=car:IN(chevy,ford,toyota,kia)

Multiple Facets

You can return more than one facet by creating a comma separated list.

Example:

https://<appliance_ip>/search?q=data&facets=lastmodified:range(begin:-4years, end:today, gap:{-7 days, -1 month, -2 years}),contentlength:range(begin=0, end=4G, gap={50k, 1M, 25M, 100M, 4G})

Response:

...
<facets>
  <facet name="lastmodified" type="date">
    <bins>
      <bin range="[2008-08-13 TO 2010-08-13}">2</bin>
      <bin range="[2010-08-13 TO 2012-07-13}">2</bin>
      <bin range="[2012-07-13 TO 2012-08-06}">0</bin>
      <bin range="[2012-08-06 TO 2012-08-13}">0</bin>
    </bins>
  </facet>
  <facet name="contentlength" type="number">
    <bins>
      <bin range="[0 TO 51200}">13</bin>
      <bin range="[51200 TO 1048576}">3</bin>
      <bin range="[1048576 TO 26214400}">5</bin>
      <bin range="[26214400 TO 104857600}">0</bin>
      <bin range="[104857600 TO 4294967296}">0</bin>
    </bins>
  </facet>
</facets>