StringFacet

Save PDF

Last Updated: May 5, 2026
5 minute read

MarkLogic Server
Documentation

The StringFacet widget displays a summary of values and counts for a faceted property in search results. Users can constrain a search by a facet value by clicking a check box.

StringFacet MarkLogic setup

Faceted search in MarkLogic requires a range index on the faceted property. Add a range index for a property to the database configuration using the Admin Interface or one of MarkLogic's programmatic APIs.

This example shows a path range index added to the status property in the Admin Interface:

After the index is setup, a constraint can be configured in the query options for the search application. The constraint returns facets for the property in the search results. For example:

<?xml version="1.0" encoding="UTF-8"?>
<options xmlns="http://marklogic.com/appservices/search">
  <constraint name="status">
    <range type="xs:string" facet="true" collation="http://marklogic.com/collation/codepoint">
      <path-index>/envelope/status</path-index>
      <facet-option>limit=25</facet-option>
      <facet-option>frequency-order</facet-option>
      <facet-option>descending</facet-option>
    </range>
  </constraint>
  <return-facets>true</return-facets>
</options>

The constraint settings correspond to the settings for the index. return-facets is set to true so that facet results are returned with search results. This example shows the status facet information returned in the search 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 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",
                            "image": "person-1001.jpg",
                        }
                    }
                ]
            }
        },
        // ...
    ],
    "facets": {
        "status": {
            "type": "xs:string",
            "facetValues": [
                {
                    "name": "Inactive",
                    "count": 52,
                    "value": "Inactive"
                },
                {
                    "name": "Active",
                    "count": 48,
                    "value": "Active"
                }
            ]
        }
    },
    // ...
}

StringFacet example rendering

This example shows the StringFacet widget rendering values for a status property from a set of documents. Documents in the set have status values of either Active or Inactive. Clicking a value applies the constraint for the facet. After a value is clicked, the UI is updated to display results with the constraint applied. In this example, only documents with the status property set to Active will be returned and displayed.

The Active checkbox selected on the StringFacet widget.

StringFacet example configuration

This example shows how to import and configure the StringFacet widget in a React application:

import { useContext } from "react";
import './App.css';
import { MarkLogicContext, SearchBox, ResultsSnippet, StringFacet } 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?.status &&
              <StringFacet
                title="Status"
                name="status"
                data={context.searchResponse?.facets?.status}
                onSelect={handleFacetClick}
              />
            }
          </div>
      </div>
    </div>
  );
}

export default App;

Code explanation

In the StringFacet example configuration:

The facet in the data prop is the facet displayed from the search response object.
The onSelect callback handles check box clicks and receives a selection object from the widget. It can then set the facet constraint in the application context using the addStringFacetConstraint method.

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:

<StringFacet
  ...
  logicConfig={{
    notConfig: {}
  }}
/>

To combine NOT logic with AND/OR operators:

<StringFacet
  ...
  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.

StringFacet API

Prop	Type	Description
data	{ type: string; facetValues: FacetValue[]; }	Facet data to display from search results.
title	string	Facet title for the collapsible header. If not provided, `name` will be used as the facet key.
subTitle	String	Facet subtitle for the collapsible header.
name	string	The unique key used to identify this facet. Required if `title` is not provided.
threshold	number	The number of items to display before showing the show more option.
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	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 `true`, hides the NOT toggle button. Default: `false`.
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: `{ textDecoration: 'line-through' }`.
logicConfig.notConfig.ButtonProps	ButtonProps	KendoReact ButtonProps for the NOT toggle button.
selectedFacets	Record<string, IFacetValue<string>>	The default selected facets. This value is used only on the initial render and does not update after the component is mounted.
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;
}

Develop with FastTrack

StringFacet

Table of Contents

StringFacet

StringFacet MarkLogic setup

StringFacet example rendering

StringFacet example configuration

Code explanation

Setting and resetting the widget

Configuring AND/OR logic

Configuring NOT logic

StringFacet API

IFacetValue API