Powered by Zoomin Software. For more details please contactZoomin

Develop with FastTrack

Table of Contents

BucketRangeFacet

Save PDF
Save selected topicSave selected topic and subtopicsSave all topics
Share
Share to emailCopy topic URL
Print
  • Last Updated: May 5, 2026
  • 4 minute read
    • MarkLogic Server
    • Documentation

The BucketRangeFacet widget displays bucketed ranges for a faceted numeric property in search results. Once search results are returned, users can check a box next to the buckets to constrain the results.

Note:

The NumberRangeFacet widget can also be used to constrain search results for a faceted numeric property.

MarkLogic setup

Faceted search requires a [range index](https://docs.progress.com/bundle/marklogic-server-administrate-12 # This is the version of marklogic. Change this variable when you want links to point to a different version of the docs/page/topics/range-indexes-and-lexicons.html) on the faceted property. A range index can be added to the database configuration with the MarkLogic Admin Interface or with an API.

This example shows a path range index added to the salary property in the Admin Interface.

Example showing a path range index added to the salary property in the Admin Interface.

After an index is added, a faceted constraint must be configured using [query options](https://docs.progress.com/bundle/marklogic-server-use-search-12 # This is the version of marklogic. Change this variable when you want links to point to a different version of the docs/page/topics/query-options.html). In this example, the search application returns facets for the /envelope/salary property in the search results. The constraint settings correspond to the settings for the index. return-facets is set to true so that facet results are returned:

<?xml version="1.0" encoding="UTF-8"?>
<options xmlns="http://marklogic.com/appservices/search">    
  <constraint name="salaryBucketed">
    <range collation="" facet="true" type="xs:int">
      <path-index>/envelope/salary</path-index>
      <bucket lt="75000" ge="50000" name="$50000 - $75000">$50000 - $75000</bucket>
      <bucket lt="100000" ge="75000" name="$75000 - $100000">$75000 - $100000</bucket>
      <bucket ge="100000" name="Over $100000">Over $100000</bucket>
      <facet-option>limit=25</facet-option>
    </range>
  </constraint>    
  <return-facets>true</return-facets>
</options>

The example code will return this response:

{
  "snippet-format": "snippet",
  "total": 3,
  "start": 1,
  "page-length": 10,
  "selected": "include",
  "results": [
    {
      "index": 1,
      "uri": "/person/1001.json",
      "path": "fn:doc(\"/person/1001.json\")",
      "score": 0,
      "confidence": 0,
      "fitness": 0,
      "href": "/v1/documents?uri=%2Fperson%2F1001.json",
      "mimetype": "application/json",
      "format": "json",
      "matches": [
        {
          "path": "fn:doc(\"/person/1001.json\")/object-node()",
          "match-text": [
            "person Nerta Hallwood Marketing Manager Active 1985-03-04 104000 person-1001.jpg"
          ]
        }
      ],
      "extracted": {
        "kind": "array",
        "content": [
          {
            "envelope": {
              "entityType": "person",
              "id": 1001,
              "firstName": "Nerta",
              "lastName": "Hallwood",
              "title": "Marketing Manager",
              "status": "Active",
              "dob": "1985-03-04",
              "salary": 104000,
              "image": "person-1001.jpg",
            }
          }
        ]
      }
    },
    // ...
  ],
  "facets": {
    "salaryBucketed": {
      "type": "bucketed",
      "facetValues": [
        {
          "name": "$50000 - $75000",
          "count": 1,
          "value": "$50000 - $75000"
        },
        {
          "name": "$75000 - $100000",
          "count": 1,
          "value": "$75000 - $100000"
        },
        {
          "name": "Over $100000",
          "count": 1,
          "value": "Over $100000"
        }
      ]
    }  
  },
  // ...
}

Example rendering

Using the code and response in MarkLogic setup, the BucketRangeFacet widget displays a set of range buckets based on the results. Each bucket contains one document in the salary range. A user can check the corresponding box to apply the constraint on the facet.

Example showing the BucketRangeFacet widget displaying range buckets based on search results. Each bucket contains one document in the salary range. A user can check the corresponding box to apply the constraint to the facet.

This shows the BucketRangeFacet widget after a user clicks the $75,000–$100,000 range bucket.

The BucketRangeFacet widget after a user clicks the $75,000–$100,000 range bucket.

BucketRangeFacet example configuration

In this example configuration, the BucketRangeFacet widget is imported and configured in a React application.

import { useContext, useState } from "react";
import './App.css';
import { MarkLogicContext, SearchBox, ResultsSnippet, BucketRangeFacet } from "ml-fasttrack";
  
function App() {
  
  const context = useContext(MarkLogicContext);
  
  const handleSearch = (params) => {
    context.setQtext(params?.q);
  }
 
  const handleFacetClick = (selection) => {
    context.addStringFacetConstraint(selection)
  }
 
  return (
    <div className="App">
      <div>
        <SearchBox onSearch={handleSearch}/>
      </div>
      <div style={{display: 'flex', flexDirection: 'row'}}>
          <div style={{width: '640px'}}>
            <ResultsSnippet
              results={context.searchResponse.results}
              paginationFooter={true}
            />
          </div>
          <div>
          {context?.searchResponse?.facets?.salaryBucketed &&
            <BucketRangeFacet
              title="Salary Range"
              data={context?.searchResponse?.facets?.salaryBucketed}
              name="salaryBucketed"
              onSelect={handleFacetClick}
            />
          }
          </div>
      </div>
    </div>
  );
}
  
export default App;

Code explanation

In the BucketRangeFacet example configuration:

  • The data prop is set to the bucketed numeric facet from the search response object. 

  • The onSelect callback manages check box clicks and receives a selection object from the widget. 

  • The application can then set the facet constraint in the application context using the addStringFacetConstraint method.

Setting and resetting the widget

See the section Setting and resetting facet widgets.

Configuring AND/OR logic

See the section Configuring AND/OR logic for facet widgets.

BucketRangeFacet API

Prop

Type

Description

data

{ type: string; facetValues: { name: string; count: number; value: string; }[]; } 

Facet data to display from search results.

name

string

The unique key used to identify this facet. Required if title is not provided.

title

string

Title for the collapsible header. If not provided, name will be used as the facet key.

subTitle

string

Subtitle for the collapsible header. 

containerStyle

CSSProperties

CSS styles applied to the widget.

ExpansionPanelProps

ExpansionPanelProps

Expansion panel configuration.

onSelect

(value: IFacetValue) => void

Callback function triggered by a selection. See IFacetValue API.

resetConfig

({ hide?: boolean; label?: string; ButtonProps?: ButtonProps; onReset?: () => void; })

Applies a Reset button to the bottom of the component.

resetConfig.hide

boolean

Whether to hide the Reset button.

resetConfig.label

string

The Reset button label.

resetConfig.ButtonProps

ButtonProps

KendoReact Button props for the Reset button.

resetConfig.onReset

() => void;

Callback function triggered when the user clicks the Reset button.

noValues

ReactNode | string

Value displayed if no facetValues were provided.

logicConfig

ILogicConfig

See Configuring AND/OR logic for facet widgets.

ref

const facetRef = useRef(null);

A React ref object that can be used to access the underlying DOM element or component instance. See Setting and resetting facet widgets.

IFacetValue API

This example shows a value object passed to the onSelect callback:

export interface IFacetValue<V = string | number> {
  name: string;
  count: number;
  value: V;
}
TitleResults for “How to create a CRG?”Also Available inAlert