JSON Facet API

Metrics Example

By default, the domain for facets starts with all documents that match the base query and any filters. Here’s an example that requests various metrics about the root domain:

curl http://localhost:8983/solr/techproducts/query -d '
q=memory&
fq=inStock:true&
json.facet={
  "avg_price" : "avg(price)",
  "num_suppliers" : "unique(manu_exact)",
  "median_weight" : "percentile(weight,50)"
}'

The response to the facet request above will start with documents matching the root domain (docs containing "memory" with inStock:true) then calculate and return the requested metrics:

 "facets" : {
    "count" : 4,
    "avg_price" : 109.9950008392334,
    "num_suppliers" : 3,
    "median_weight" : 352.0
  }

Bucketing Facet Example

Here’s an example of a bucketing facet, that partitions documents into bucket based on the cat field (short for category), and returns the top 3 buckets:

curl http://localhost:8983/solr/techproducts/query -d 'q=*:*&
json.facet={
  categories : {
    type : terms,
    field : cat,    // bucket documents based on the "cat" field
    limit : 3       // retrieve the top 3 buckets ranked by the number of docs in each bucket
  }
}'

The response below shows us that 32 documents match the default root domain. and 12 documents have cat:electronics, 4 documents have cat:currency, etc.

[...]
  "facets":{
    "count":32,
    "categories":{
      "buckets":[{
          "val":"electronics",
          "count":12},
        {
          "val":"currency",
          "count":4},
        {
          "val":"memory",
          "count":3},
      ]
    }
  }

Making a Facet Request

In this guide, we will often just present the facet command block:

{
  x: "average(mul(price,popularity))"
}

To execute a facet command block such as this, you’ll need to use the json.facet parameter, and provide at least a base query such as q=*:*

curl http://localhost:8983/solr/techproducts/query -d 'q=*:*&json.facet=
{
  x: "avg(mul(price,popularity))"
}
'

Another option is to use the JSON Request API to provide the entire request in JSON:

curl http://localhost:8983/solr/techproducts/query -d '
{
  query: "*:*",                        // this is the base query
  filter: [ "inStock:true" ],          // a list of filters
  facet: {
    x: "avg(mul(price,popularity))"    // and our funky metric of average of price * popularity
 }
}
'

JSON Extensions

The Noggit JSON parser that is used by Solr accepts a number of JSON extensions such as,

Range Facet Parameters

To ease migration, the range facet parameter names and semantics largely mirror facet.range query-parameter style faceting. For example "start" here corresponds to "facet.range.start" in a facet.range command.

Nested Facet Example

Let’s start off with a simple non-nested terms facet on the genre field:

 top_genres:{
    type: terms
    field: genre,
    limit: 5
  }

Now if we wanted to add a nested facet to find the top 2 authors for each genre bucket:

  top_genres:{
    type: terms,
    field: genre,
    limit: 5,
    facet:{
      top_authors:{
        type: terms, // nested terms facet on author will be calculated for each parent bucket (genre)
        field: author,
        limit: 2
      }
    }
  }

And the response will look something like:

  "facets":{
    "top_genres":{
      "buckets":[
        {
          "val":"Fantasy",
          "count":5432,
          "top_authors":{  // these are the top authors in the "Fantasy" genre
            "buckets":[{
                "val":"Mercedes Lackey",
                "count":121},
              {
                "val":"Piers Anthony",
                "count":98}
            ]
          }
        },
        {
          "val":"Mystery",
          "count":4322,
          "top_authors":{  // these are the top authors in the "Mystery" genre
            "buckets":[{
                "val":"James Patterson",
                "count":146},
              {
                "val":"Patricia Cornwell",
                "count":132}
            ]
          }
        }

By default "top authors" is defined by simple document count descending, but we could use our aggregation functions to sort by more interesting metrics.

Sorting Facets By Nested Functions

The default sort for a field or terms facet is by bucket count descending. We can optionally sort ascending or descending by any facet function that appears in each bucket.

{
  categories:{
    type : terms      // terms facet creates a bucket for each indexed term in the field
    field : cat,
    sort : "x desc",  // can also use sort:{x:desc}
    facet : {
      x : "avg(price)",     // x = average price for each facet bucket
      y : "max(popularity)" // y = max popularity value in each facet bucket
    }
  }
}

Adding Domain Filters

The simplest example of a domain change is to specify an additional filter which will be applied to the existing domain. This can be done via the filter keyword in the domain block of the facet.

Example:

{
  categories: {
     type: terms,
     field: cat,
     domain: {filter: "popularity:[5 TO 10]" }
   }
}

The value of filter can be a single query to treat as a filter, or a JSON list of filter queries. Each query can be:

When a filter option is combined with other domain changing options, the filtering is applied after the other domain changes take place.

Filter Exclusions

Domains can also exclude the top-level query or filters via the excludeTags keywords in the domain block of the facet, expanding the existing domain.

Example:

&q={!tag=top}"running shorts"
&fq={!tag=COLOR}color:Blue
&json={
   filter:"{!tag=BRAND}brand:Bosco"
   facet:{
      sizes:{type:terms, field:size},
      colors:{type:terms, field:color, domain:{excludeTags:COLOR} },
      brands:{type:terms, field:brand, domain:{excludeTags:"BRAND,top"} }
   }
}

The value of excludeTags can be a single string tag, array of string tags or comma-separated tags in the single string.

When an excludeTags option is combined with other domain changing options, it expands the domain before any other domain changes take place.

See also the section on multi-select faceting.

Arbitrary Domain Query

A query domain can be specified when you wish to compute a facet against an arbitrary set of documents, regardless of the original domain. The most common use case would be to compute a top level facet against a specific subset of the collection, regardless of the main query. But it can also be useful on nested facets when building Semantic Knowledge Graphs.

Example:

{
  "categories": {
     "type": "terms",
     "field": "cat",
     "domain": {"query": "*:*" }
   }
}

The value of query can be a single query, or a JSON list of queries. Each query can be:

Block Join Domain Changes

When a collection contains Block Join child documents, the blockChildren or blockParent domain options can be used transform an existing domain containing one type of document, into a domain containing the documents with the specified relationship (child or parent of) to the documents from the original domain.

Both of these options work similar to the corresponding Block Join Query Parsers by taking in a single String query that exclusively matches all parent documents in the collection. If blockParent is used, then the resulting domain will contain all parent documents of the children from the original domain. If If blockChildren is used, then the resulting domain will contain all child documents of the parents from the original domain.

Example:

{
  "colors": {                         
    "type": "terms",
    "field": "sku_color",             
    "facet" : {
      "brands" : {
        "type": "terms",
        "field": "product_brand",     
        "domain": {
          "blockParent": "doc_type:product"
        }
      }}}}

Join Query Domain Changes

A join domain change option can be used to specify arbitrary from and to fields to use in transforming from the existing domain to a related set of documents.

This works very similar to the Join Query Parser, and has the same limitations when dealing with multi-shard collections.

Example:

{
  "colors": {
    "type": "terms",
    "field": "sku_color",
    "facet": {
      "brands": {
        "type": "terms",
        "field": "product_brand",
        "domain" : {
          "join" : {
            "from": "product_id_of_this_sku",
            "to": "id"
          },
          "filter": "doc_type:product"
        }
      }
    }
  }
}

Graph Traversal Domain Changes

A graph domain change option works similarly to the join domain option, but can do traversal multiple hops from the existing domain to other documents.

This works very similar to the Graph Query Parser, supporting all of it’s optional parameters, and has the same limitations when dealing with multi-shard collections.

Example:

{
  "related_brands": {
    "type": "terms",
    "field": "brand",
    "domain": {
      "graph": {
        "from": "related_product_ids",
        "to": "id",
        "maxDepth": 3
      }
    }
  }
}

Block Join Counts Example

Suppose we have products with multiple SKUs, and we want to count products for each color.

{
  "id": "1", "type": "product", "name": "Solr T-Shirt",
  "_childDocuments_": [
    { "id": "11", "type": "SKU", "color": "Red",  "size": "L" },
    { "id": "12", "type": "SKU", "color": "Blue", "size": "L" },
    { "id": "13", "type": "SKU", "color": "Red",  "size": "M" }
  ]
},
{
  "id": "2", "type": "product", "name": "Solr T-Shirt",
  "_childDocuments_": [
    { "id": "21", "type": "SKU", "color": "Blue", "size": "S" }
  ]
}

When searching against a set of SKU documents, we can ask for a facet on color, with a nested statistic counting all the "blocks" — aka: products:

color: {
  type: terms,
  field: color,
  limit: -1,
  facet: {
    productsCount: "uniqueBlock(_root_)"
  }
}

and get:

color:{
   buckets:[
      { val:Blue, count:2, productsCount:2 },
      { val:Red, count:2, productsCount:1 }
   ]
}

Please notice that _root_ is an internal field added by Lucene to each child document to reference on parent one. Aggregation uniqueBlock(_root_) is functionally equivalent to unique(_root_), but is optimized for nested documents block structure. It’s recommended to define limit: -1 for uniqueBlock calculation, like in above example, since default value of limit parameter is 10, while uniqueBlock is supposed to be much faster with -1.

relatedness() Options

When using the extended type:func syntax for specifying a relatedness() aggregation, an opional min_popularity (float) option can be used to specify a lower bound on the foreground_popularity and background_popularity values, that must be met in order for the relatedness score to be valid — If this min_popularity is not met, then the relatedness score will be -Infinity.

{ "type": "func",
  "func": "relatedness($fore,$back)",
  "min_popularity": 0.001,
}

This can be particularly useful when using a descending sorting on relatedness() with foreground and background queries that are disjoint, to ensure the "top buckets" are all relevant to both sets.

Semantic Knowledge Graph Example

curl -sS -X POST 'http://localhost:8983/solr/gettingstarted/update?commit=true' -d '[
{"id":"01",age:15,"state":"AZ","hobbies":["soccer","painting","cycling"]},
{"id":"02",age:22,"state":"AZ","hobbies":["swimming","darts","cycling"]},
{"id":"03",age:27,"state":"AZ","hobbies":["swimming","frisbee","painting"]},
{"id":"04",age:33,"state":"AZ","hobbies":["darts"]},
{"id":"05",age:42,"state":"AZ","hobbies":["swimming","golf","painting"]},
{"id":"06",age:54,"state":"AZ","hobbies":["swimming","golf"]},
{"id":"07",age:67,"state":"AZ","hobbies":["golf","painting"]},
{"id":"08",age:71,"state":"AZ","hobbies":["painting"]},
{"id":"09",age:14,"state":"CO","hobbies":["soccer","frisbee","skiing","swimming","skating"]},
{"id":"10",age:23,"state":"CO","hobbies":["skiing","darts","cycling","swimming"]},
{"id":"11",age:26,"state":"CO","hobbies":["skiing","golf"]},
{"id":"12",age:35,"state":"CO","hobbies":["golf","frisbee","painting","skiing"]},
{"id":"13",age:47,"state":"CO","hobbies":["skiing","darts","painting","skating"]},
{"id":"14",age:51,"state":"CO","hobbies":["skiing","golf"]},
{"id":"15",age:64,"state":"CO","hobbies":["skating","cycling"]},
{"id":"16",age:73,"state":"CO","hobbies":["painting"]},
]'

curl -sS -X POST http://localhost:8983/solr/gettingstarted/query -d 'rows=0&q=*:*
&back=*:*                                  
&fore=age:[35 TO *]                        
&json.facet={
  hobby : {
    type : terms,
    field : hobbies,
    limit : 5,
    sort : { r1: desc },                   
    facet : {
      r1 : "relatedness($fore,$back)",     
      location : {
        type : terms,
        field : state,
        limit : 2,
        sort : { r2: desc },               
        facet : {
          r2 : "relatedness($fore,$back)"  
        }
      }
    }
  }
}'

"facets":{
  "count":16,
  "hobby":{
    "buckets":[{
        "val":"golf",
        "count":6,                                
        "r1":{
          "relatedness":0.01225,
          "foreground_popularity":0.3125,         
          "background_popularity":0.375},         
        "location":{
          "buckets":[{
              "val":"az",
              "count":3,
              "r2":{
                "relatedness":0.00496,            
                "foreground_popularity":0.1875,   
                "background_popularity":0.5}},    
            {
              "val":"co",
              "count":3,
              "r2":{
                "relatedness":-0.00496,           
                "foreground_popularity":0.125,
                "background_popularity":0.5}}]}},
      {
        "val":"painting",
        "count":8,                                
        "r1":{
          "relatedness":0.01097,
          "foreground_popularity":0.375,
          "background_popularity":0.5},
        "location":{
          "buckets":[{
            ...