NumericFacet (Search Engine)
NumericFacet (Search Engine)
Example Implementation
numeric-facet.fn.tsx
import {
NumericFacet as HeadlessNumericFacet,
NumericFacetValue,
} from '@coveo/headless';
import {useEffect, useState, FunctionComponent} from 'react';
interface NumericFacetProps {
controller: HeadlessNumericFacet;
format: (n: number) => string;
}
export const NumericFacet: FunctionComponent<NumericFacetProps> = (props) => {
const {controller} = props;
const [state, setState] = useState(controller.state);
useEffect(() => controller.subscribe(() => setState(controller.state)), []);
function getKeyForRange(value: NumericFacetValue) {
return `[${value.start}..${value.end}${value.endInclusive ? ']' : '['}`;
}
if (
!state.values.filter(
(value) => value.state !== 'idle' || value.numberOfResults > 0
).length
) {
return <div>No facet values</div>;
}
const {format} = props;
return (
<ul>
{state.values.map((value) => (
<li key={getKeyForRange(value)}>
<input
type="checkbox"
checked={controller.isValueSelected(value)}
onChange={() => controller.toggleSelect(value)}
disabled={state.isLoading}
/>
{format(value.start)} to {format(value.end)}{' '}
{value.endInclusive ? 'inclusively' : 'exclusively'} (
{value.numberOfResults}{' '}
{value.numberOfResults === 1 ? 'result' : 'results'})
</li>
))}
</ul>
);
};
// usage
/**
* ```tsx
* const [KB, MB, GB] = [1e3, 1e6, 1e9];
*
* const controller = buildNumericFacet(engine, {
* options: {
* field: 'size',
* generateAutomaticRanges: false,
* currentValues: [ // Must be specified when `generateAutomaticRanges` is false.
* buildNumericRange({start: 0, end: 5 * KB}),
* buildNumericRange({start: 5 * KB, end: 5 * MB}),
* buildNumericRange({start: 5 * MB, end: 5 * GB}),
* ],
* },
* });
*
* <NumericFacet controller={controller} format={(bytes) => `${bytes} bytes`} />;
* ```
*/
The NumericFacet
controller makes it possible to create a facet with numeric ranges.
Methods
deselectAll
Deselects all facet values.
disable
Disables the facet. In other words, prevents it from filtering results.
enable
Enables the facet. In other words, undoes the effects of disable
.
isSortedBy
Checks whether the facet values are sorted according to the specified criterion.
Parameters
-
criterion:
'ascending' | 'descending'
The criterion to compare.
Returns boolean
: Whether the facet values are sorted according to the specified criterion.
isValueSelected
Checks whether the specified facet value is selected.
Parameters
-
selection:
NumericFacetValue
The facet value to check.
Returns boolean
: Whether the specified facet value is selected.
sortBy
Sorts the facet values according to the specified criterion.
Parameters
-
criterion:
'ascending' | 'descending'
The criterion to sort values by.
toggleSelect
Toggles the specified facet value.
Parameters
-
selection:
NumericFacetValue
The facet value to toggle.
toggleSingleSelect
Toggles the specified facet value, deselecting others.
Parameters
-
selection:
NumericFacetValue
The facet value to toggle.
subscribe
Adds a callback that’s invoked on state change.
Parameters
-
listener:
() => void
A callback that’s invoked on state change.
Returns Unsubscribe
: A function to remove the listener.
Attributes
state
The state of the NumericFacet
controller.
Properties
-
enabled:
boolean
Whether the facet is enabled and its values are used to filter search results.
-
facetId:
string
The facet ID.
-
hasActiveValues:
boolean
true
if there’s at least one non-idle value andfalse
otherwise. -
isLoading:
boolean
true
if a search is in progress andfalse
otherwise. -
sortCriterion:
'ascending' | 'descending'
The active sortCriterion of the facet.
-
values:
NumericFacetValue[]
The values of the facet.
Initialize
buildNumericFacet
Creates a NumericFacet
controller instance.
Parameters
-
engine:
SearchEngine
The headless engine.
-
props:
NumericFacetProps
The configurable
NumericFacet
properties.
Returns NumericFacet
NumericFacetProps
The configurable NumericFacet
properties.
Properties
-
options:
NumericFacetOptions
The options for the
NumericFacet
controller.
NumericFacetOptions
The options for the NumericFacet
controller.
Properties
-
field:
string
The field whose values you want to display in the facet.
-
generateAutomaticRanges:
boolean
Whether the index should automatically create range values.
Tip: If you set this parameter to true, you should ensure that the 'Use cache for numeric queries' option is enabled for this facet’s field in your index in order to speed up automatic range evaluation.
-
currentValues?:
NumericRangeRequest[]
The values displayed by the facet in the search interface at the moment of the request.
If
generateAutomaticRanges
is false, values must be specified. IfgenerateAutomaticRanges
is true, automatic ranges are going to be appended after the specified values.Default:
[]
-
facetId?:
string
A unique identifier for the controller. By default, a unique random identifier is generated.
-
filterFacetCount?:
boolean
Whether to exclude folded result parents when estimating the result count for each facet value.
Default:
true
-
injectionDepth?:
number
The maximum number of results to scan in the index to ensure that the facet lists all potential facet values.
Note: A high injectionDepth may negatively impact the facet request performance.
Minimum:
0
Default:
1000
-
numberOfValues?:
number
The number of values to request for this facet. Also determines the number of additional values to request each time this facet is expanded, and the number of values to display when this facet is collapsed.
Minimum:
1
Default:
8
-
rangeAlgorithm?:
'even' | 'equiprobable'
The algorithm that’s used for generating the ranges of this facet when they aren’t manually defined. The default value of
"even"
generates equally sized facet ranges across all of the results. The value"equiprobable"
generates facet ranges which vary in size but have a more balanced number of results within each range.Default:
even
-
sortCriteria?:
'ascending' | 'descending'
The sort criterion to apply to the returned facet values.
Default:
ascending
Utils
buildNumericRange
Creates a NumericRangeRequest
.
Parameters
-
config:
NumericRangeOptions
The options with which to create a
NumericRangeRequest
.
Returns NumericRangeRequest
: The options defining a value to display in a NumericFacet
.
Related Types
NumericFacetValue
Properties
-
end:
number
The ending value for the numeric range.
-
endInclusive:
boolean
Whether or not the end value is included in the range.
-
numberOfResults:
number
The number of results that have the facet value.
-
start:
number
The starting value for the numeric range.
-
state:
'idle' | 'selected'
The state of the facet value, indicating whether it is filtering results (
selected
) or not (idle
).
NumericRangeOptions
Properties
-
end:
number
The ending value of the numeric range.
-
start:
number
The starting value of the numeric range.
-
endInclusive?:
boolean
Whether to include the
end
value in the range.Default:
false
-
state?:
'idle' | 'selected'
The current facet value state.
Default:
idle
NumericRangeRequest
Properties
-
end:
number
The end value of the range.
-
endInclusive:
boolean
Whether to include the
end
value in the range. -
start:
number
The start value of the range.
-
state:
'idle' | 'selected'
The current facet value state.
Unsubscribe
Call signatures
-
(): void