BucketRangeFacet
- 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 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.
BucketRangeFacet API
Prop |
Type |
Description |
|---|---|---|
data |
{ type: string; facetValues: { name: string; count: number; value: string; }[]; } |
Facet data to display from search results. |
name |
string |
String identifying the facet. Passed as the name value in the onSelect event. |
title |
string |
Title for the collapsible header. |
subTitle |
string |
Subtitle for the collapsible header. |
containerStylename |
CSSPropertiesstring |
String value identifying the item to uncheck. For integration with the SelectedFacets widget. |
reset |
string |
String value identifying the item to uncheck. For integration with the SelectedFacets widget. CSS style for the container |
onSelect |
(value: { type: string; name: string; value: string[]; title?: string | undefined; }) => voidstring |
Callback function triggered by a selection. Receives a selection object.Label for the reset button. |
BucketRangeFacet callbacks
This example shows a selection object passed to the onSelect callback:
{
"type": "string",
"name": "salaryBucketed",
"value": [
"$50000 - $75000"
],
"title": "Salary Range"
}