BucketRangeFacet
- Last Updated: May 5, 2026
- 5 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 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.
After an index is added, a faceted constraint must be configured using query options. 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.
This shows 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
dataprop is set to the bucketed numeric facet from the search response object. - The
onSelectcallback 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
addStringFacetConstraintmethod.
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.
Configuring NOT logic
The notConfig property of logicConfig enables a NOT operator toggle next to each facet value. When activated, selected values are excluded from search results rather than included.
To enable the NOT toggle with default settings, pass an empty notConfig object:
<BucketRangeFacet
...
logicConfig={{
notConfig: {}
}}
/>
To combine NOT logic with AND/OR operators:
<BucketRangeFacet
...
logicConfig={{
defaultOperator: 'OR',
andConfig: {},
orConfig: {},
notConfig: {}
}}
/>
When notConfig is enabled, a "-" button appears beside each facet value. Clicking it toggles that value into a NOT selection, visually indicated with a strikethrough by default. NOT selections generate exclusion constraints in the search query.
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 |
string |
Title for the collapsible header. If not provided, |
subTitle |
string |
Subtitle for the collapsible header. |
containerStyle |
CSSProperties |
CSS styles applied to the widget. |
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 |
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 |
ILogicProps |
Configures AND/OR/NOT logic operators for the facet. See Configuring AND/OR logic for facet widgets and Configuring NOT logic above. |
logicConfig.notConfig |
INotLogicConfig |
Enables a NOT toggle on each facet value. When active, the selected values are excluded from search results rather than included. |
logicConfig.notConfig.hide |
boolean |
When |
logicConfig.notConfig.label |
(isNotted: boolean) => ReactNode |
Custom label for the NOT toggle button. Default: |
logicConfig.notConfig.valueStyle |
CSSProperties |
Style applied to values when the NOT operator is active. Default: |
logicConfig.notConfig.ButtonProps |
KendoReact ButtonProps for the NOT toggle button. |
|
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;
}