Reactivesearch.io Docs - Search stack for Elasticsearch, OpenSearch, Solr, MongoDB

This guide helps you to learn more about the each property of ReactiveSearch API and explains that how to use those properties to build the query for different use-cases.

This guide only contains the fields supported for the Solr search engine.

ReactiveSearch API request body can be divided into two parts, query and settings. The query key is an Array of objects where each object represents a ReactiveSearch query to retrieve the results. Settings(settings) is an optional key which can be used to control the search experience. Here is an example of the request body of ReactiveSearch API to get the results for which the title field matches with iphone.

Copy

{
    query: [{
        id: "phone-search",
        dataField: "title",
        size: 10,
        value: "iphone"
    }],
    settings: { // optional
        recordAnalytics: true, // to enable the analytics
        enableQueryRules: true, // to enable the query rules
    }
}

Query parameters

Reactivesearch API supports all the query parameters supported by solr search API.

query

This is a required field

Supported Engines Not dependent on engine, works for all.

id

This is a required field

Supported Engines elasticsearch, mongodb, solr, opensearch

The unique identifier for the query can be referenced in the react property of other queries. The response of the ReactiveSearch API is a map of query ids to Elasticsearch response which means that id is also useful to retrieve the response for a particular query.

Type	Applicable on query of type	Required
`string`	`all`	true

type

Supported Engines elasticsearch, mongodb, solr, opensearch

This property represents the type of the query which is defaults to search, valid values are search, suggestion, term, range & geo. You can read more here.

Type	Applicable on query of type	Required
`string`	`all`	false

Following values are supported for this field

search, term, range, geo, suggestion

react

Supported Engines elasticsearch, mongodb, solr, opensearch

To specify dependent queries to update that particular query for which the react prop is defined. You can read more about it here.

Type	Applicable on query of type e	Required
`Object`	`all`	false

Example Playground:

highlight

This property can be used to enable the highlighting in the returned results. If set to false, highlightField and highlightConfig values will be ignored.

Type	Applicable on query of type	Required
`bool`	`all`	false

Try out an example in ReactiveSearch Playground

queryFormat

Supported Engines elasticsearch, mongodb, solr, opensearch

Sets the query format, can be or, and and date format. Defaults to or.

or returns all the results matching any of the search query text's parameters. For example, searching for "bat man" with or will return all the results matching either "bat" or "man".
On the other hand with and, only results matching both "bat" and "man" will be returned. It returns the results matching all of the search query text's parameters."
queryFormat can be set as Elasticsearch date format for range type of queries. It allows Elasticsearch to parse the range values (dates) to a specified format before querying the data. You can find the valid date formats at here.

Type	Applicable on query of type	Required
`string`	`all`	false

Try out an example in ReactiveSearch Playground

dataField

Supported Engines elasticsearch, mongodb, solr, opensearch

database field(s) to be queried against, useful for applying search across multiple fields. It accepts the following formats:

string
DataField
Array<string|DataField>

The DataField type has the following shape:

Copy

type DataField = {
    field: string;
    weight: float;
};

For examples,

dataField without field weights

Copy

    dataField: ['title', 'title.search']

dataField with field weights

Copy

    dataField: [
        {
            "field": "title",
            "weight": 1
        },
        {
            "field": "title.search",
            "weight": 3
        }
    ]

dataField with and without field weights

Copy

    dataField: [
        {
            "field": "title",
            "weight": 1
        },
        {
            "field": "title.search",
            "weight": 3
        },
        "description"
    ]

Type	Applicable on query of type	Required
`string	DataField	Array`

Note: Multiple dataFields are not applicable for term and geo queries.

Try out an example in ReactiveSearch Playground

from

Supported Engines elasticsearch, mongodb, solr, opensearch

Starting document offset. Defaults to 0.

Type	Applicable on query of type	Required
`int`	`search`,`suggestion`,`geo`,`range`	false

Try out an example in ReactiveSearch Playground

size

Supported Engines elasticsearch, mongodb, solr, opensearch

To set the number of results to be returned by a query.

Type	Applicable on query of type	Required
`int`	`all`	false

Try out an example in ReactiveSearch Playground

aggregationSize

Supported Engines elasticsearch, mongodb, solr, opensearch

To set the number of buckets to be returned by aggregations.

Type	Applicable on query of type	Required
`int`	`term`	false

Note:

This property can also be used for search and suggestion type of queries when aggregationField or categoryField is set.

This is a new feature and only available for appbase versions >= 7.41.0.

Try out an example in ReactiveSearch Playground

sortBy

Supported Engines elasticsearch, mongodb, solr, opensearch

This property can be used to sort the results in a particular format. The valid values are:

asc, sorts the results in ascending order,
desc, sorts the results in descending order,
count, sorts the aggregations by count.

Type	Applicable on query of type	Required
`string`	`all`*	false

Note:

Please note that the count value can only be applied when the query type is of term. In addition, the pagination property for the query needs to be set to false (default behavior). When pagination is true, a composite aggregation is used under the hood, which doesn't support ordering by count.

The sortBy value by default is set according to the following criterion:

If field is _score, set as desc.
If field is anything other than _score, set as asc

Following values are supported for this field

asc, desc, count

Try out an example in ReactiveSearch Playground

sortField

Supported Engines elasticsearch, solr, opensearch

This field should indicate the field that sort will be applied to. If not passed, then the first entry in the dataField (if passed as object or array) or the dataField itself (if passed as string) will be used.

Type	Applicable on query of type e	Required
`String`, `array of strings`, `array of string and objects`	`all`	false

The sortField key accepts different types of values:

1. `string`

String can be passed where the string is a dataField where sorting is supposed to be done on, following is an example:

Copy

{
    "sortField": "title"
}

In the above example, title is the dataField on which sorting will be done.

In the above example, the sorting method will be the value of sortBy (if passed) else the default value (which is asc for any field other than _score).

2. Array of string

An array of string can also be passed. This can be done in the following way:

Copy

{
    "sortField": [
        "title",
        "author",
        "price"
    ]
}

In the above example, title, author and price are valid dataFields on which sorting will be done.

In the above example, the sorting order will be based on the value of sortBy key if passed, or default to asc order. _score is a special field to sort by relevance, if specified, it is always sorted in desc order

3. Array of string / object

sortField also accepts a combined array where some fields are passed as object. Following is an example:

Copy

{
    "sortField": [
        "title",
        {"author": "desc"},
        {"price": "asc"}
    ]
}

In the above example, the sort order for title field will be asc (i.e. ascending). For the other fields, it will be as passed. The object should have the dataField as the key and the sort order as its value, only asc or desc are valid values here.

value

Supported Engines elasticsearch, mongodb, solr, opensearch

Represents the value for a particular query type, each kind of query has the different type of value format.

Type	Applicable on query of type e	Required
`any`	`all`	false

You can check the value format for different type of queries:

format for `search` and `suggestion` type

The value can be a string or int. Example Playground:

format for `term` type

The value can be a string or Array<string>. Example Playground:

format for `range` type

The value should be an Object in the following shape:

Copy

{
   "start": int | double | date, // optional
   "end": int | double | date, // optional
   "boost": int
}

Note:

Either start or end property must present in the value.

Example Playground:

format for `geo` type

The value should be an Object in the following shape:

Copy

{
   // The following properties can be used to get the results within a particular distance and location.
   "distance": int,
   "location": string, // must be in `{lat}, {lon}` format
   "unit": string,
   // The following properties can be used to get the results for a particular geo bounding box.
   "geoBoundingBox": {
       topLeft: string, // required, must be in `{lat}, {lon}` format
       bottomRight: string, // required, must be in `{lat}, {lon}` format
   }
}

Note: The geoBoundingBox property can not be used with location property, if both are defined than geoBoundingBox value will be ignored.

The below example represents a geo distance query:

Copy

    {
        "id": "distance_filter",
        "type": "geo",
        "dataField": ["location"],
        "value":  {
            "distance":10,
            "location":"22.3184816, 73.17065699999999",
            "unit": "mi/yd/ft/km/m/cm/mm/nmi"
        }
    }

The below example represents a geo bounding box query:

Copy

    {
        "id": "bounding_box_filter",
        "type": "geo",
        "dataField": ["location"],
        "value":  {
            "geoBoundingBox": {
                "topLeft": "40.73, -74.1",
                "bottomRight": "40.01, -71.12",
            }
        }
    }

Example Playground:

includeNullValues

Supported Engines elasticsearch, mongodb, solr, opensearch

If you have sparse data or documents or items not having the value in the specified field or mapping, then this prop enables you to show that data.

Type	Applicable on query of type	Required
`bool`	`range`	false

Try out an example in ReactiveSearch Playground

includeFields

Supported Engines elasticsearch, mongodb, solr, opensearch

Data fields to be included in search results. Defaults to [*] which means all fields are included.

Type	Applicable on query of type e	Required
`Array<string>`	`all`	false

Try out an example in ReactiveSearch Playground

excludeFields

Supported Engines elasticsearch, mongodb, solr, opensearch

Data fields to be excluded in search results.

Type	Applicable on query of type e	Required
`Array<string>`	`all`	false

highlight

Supported Engines elasticsearch, mongodb, solr, opensearch

This property can be used to enable the highlighting in the returned results. If set to false, highlightField and highlightConfig values will be ignored.

Type	Applicable on query of type	Required
`bool`	`all`	false

Try out an example in ReactiveSearch Playground

highlightField

Supported Engines elasticsearch, mongodb, solr, opensearch

When highlighting is enabled, this property allows specifying the fields which should be returned with the matching highlights. When not specified, it defaults to apply highlights on the field(s) specified in the dataField prop.

Type	Applicable on query of type	Required
`Array<string>`	`all`	false

highlightConfig

Supported Engines elasticsearch, mongodb, solr, opensearch

It can be used to set the custom highlight settings. You can read the Elasticsearch docs for the highlight options at here.

Type	Applicable on query of type	Required
`Object`	`all`	false

Try out an example in ReactiveSearch Playground

interval

Supported Engines elasticsearch, mongodb, solr, opensearch

To set the histogram bar interval, applicable when aggregations value is set to ["histogram"]. Defaults to Math.ceil((range.end - range.start) / 100) || 1.

Type	Applicable on query of type	Required
`int`	`range`	false

aggregations

Supported Engines elasticsearch, mongodb, solr, opensearch

It helps you to utilize the built-in aggregations for range type of queries directly, valid values are:

max: to retrieve the maximum value for a dataField,
min: to retrieve the minimum value for a dataField,
histogram: to retrieve the histogram aggregations for a particular interval

Type	Applicable on query of type	Required
`Array<string>`	`range`	false

Try out an example in ReactiveSearch Playground

showMissing

Supported Engines elasticsearch, mongodb, solr, opensearch

Defaults to false. When set to true then it also retrieves the aggregations for missing fields.

Type	Applicable on query of type	Required
`bool`	`term`	false

Try out an example in ReactiveSearch Playground

defaultQuery

Supported Engines elasticsearch, mongodb, solr, opensearch

This property is useful to customize the source query, as defined in Elasticsearch Query DSL. It is different from the customQuery in a way that it doesn't get leaked to other queries(dependent queries by react prop) and only modifies the query for which it has been applied.

You can read more about the defaultQuery usage over here.

Type	Applicable on query of type	Required
`Object`	`all`	false

Try out an example in ReactiveSearch Playground

customQuery

Supported Engines elasticsearch, mongodb, solr, opensearch

Custom query property will be applied to the dependent queries by react property, as defined in Elasticsearch Query DSL. You can read more about the customQuery usage over here.

Note:

It'll not affect that particular query for which it has been defined, it'll only affect the query for dependent queries. If you want to customize the source query then use the defaultQuery property instead.

Type	Applicable on query of type	Required
`Object`	`all`	false

Try out an example in ReactiveSearch Playground

execute

Supported Engines elasticsearch, mongodb, solr, opensearch

Sometimes it may require that you want to apply some query for results with the help of react property but want to avoid any un-necessary query execution for the performance reasons. If you set execute to false for a particular query then you can use it with react prop without executing it. For example, consider a scenario where we want to filter the search query by some range. To implement it with RS API we need to define two queries(search & range type). Since you defined the two queries then by default both queries will get executed, however you can avoid this by setting execute to false for the range query.

Type	Applicable on query of type	Required
`bool`	`all`	false

Try out an example in ReactiveSearch Playground

enableSynonyms

Supported Engines elasticsearch, mongodb, solr, opensearch

This property can be used to control (enable/disable) the synonyms behavior for a particular query. Defaults to true, if set to false then fields having .synonyms suffix will not affect the query.

Type	Applicable on query of type	Required
`bool`	`search`,`suggestion`	false

Try out an example in ReactiveSearch Playground

enablePopularSuggestions

Supported Engines elasticsearch, mongodb, solr, opensearch

When set to true, popular searches based on aggregate end-user data are returned as suggestions as per the popular suggestions config (either defaults, or as set through popularSuggestionsConfig or via Popular Suggestions settings in the control plane)

Type	Applicable on query of type	Required
`bool`	`suggestion`	false

popularSuggestionsConfig

Supported Engines elasticsearch, solr, opensearch

Specify additional options for fetching popular suggestions. It can accept the following keys:

size: int Maximum number of popular suggestions to return. Defaults to 5.
minCount: int Return only popular suggestions that have been searched at least minCount times. There is no default minimum count-based restriction.
minChars: int Return only popular suggestions that have minimum characters, as set in this property. There is no default minimum character-based restriction.
showGlobal: Boolean Defaults to true. When set to false, return popular suggestions only based on the current user's past searches.
index: string Index(es) from which to return the popular suggestions from. Defaults to searching the entire cluster.

Note: It is possible to define multiple indices using a comma separated pattern, for e.g products,categories.

customEvents Object Custom analytics events to filter the popular suggestions.

For example,

Copy

    "popularSuggestionsConfig": {
        "customEvents": {
            "browser": "Chrome",
            "user_id": "john@appbase.io"
        }
    }

sectionLabel: string To define the section title for popular suggestions.

Type	Applicable on query of type	Required
`Object`	`suggestion`	false

showDistinctSuggestions

Supported Engines elasticsearch, solr, opensearch

enablePredictiveSuggestions

Supported Engines elasticsearch, solr, opensearch

When set to true, it predicts the next relevant words from the value of a field based on the search query typed by the user. When set to false (default), the matching document field's value would be displayed.

Type	Applicable on query of type	Required
`bool`	`suggestion`	false

maxPredictedWords

Supported Engines elasticsearch, solr, opensearch

Defaults to 2. This property allows configuring the maximum number of relevant words that are predicted. Valid values are between [1, 5].

Type	Applicable on query of type	Required
`int`	`suggestion`	false

urlField

Supported Engines elasticsearch, solr, opensearch

Data field whose value contains a URL. This is a convenience prop that allows returning the URL value in the suggestion's response.

Type	Applicable on query of type	Required
`string`	`suggestion`	false

Try out an example in ReactiveSearch Playground

applyStopwords

Supported Engines elasticsearch, solr, opensearch

When set to true, it would not predict a suggestion which starts or ends with a stopword. You can use searchLanguage property to apply language specific stopwords.

Type	Applicable on query of type	Required
`bool`	`suggestion`	false

customStopwords

Supported Engines elasticsearch, solr, opensearch

It allows you to define a list of custom stopwords. You can also set it through Index settings in the control plane.

Type	Applicable on query of type	Required
`array`	`suggestion`	false

searchLanguage

Supported Engines elasticsearch, solr, opensearch

Search language is useful to apply language specific stopwords for predictive suggestions. Defaults to english language.

We support following languages:

Type	Applicable on query of type	Required
`string`	`suggestion`	false

calendarInterval

Supported Engines elasticsearch, solr, opensearch

enableFeaturedSuggestions

Supported Engines elasticsearch, solr, opensearch

When set to true, featured searches are returned as suggestions as per the featured suggestions config (either defaults, or as set through featuredSuggestionsConfig.

Type	Applicable on query of type	Required
`bool`	`suggestion`	false

featuredSuggestionsConfig

Supported Engines elasticsearch, solr, opensearch

To define options to apply featured suggestions. It can accept the following keys:

maxSuggestionsPerSection: int To restrict the number of featured suggestions per section.
sectionsOrder: Array<string> To define the order of sections to be displayed in UI. For e.g, [\'document\', \'pages\', \'help\'].

Type	Applicable on query of type	Required
`Object`	`suggestion`	false

enableIndexSuggestions

Supported Engines elasticsearch, solr, opensearch

This property can be used to disable the index suggestions. If set the false, Appbase would not query the search backend to fetch the suggestions.

Type	Applicable on query of type	Required
`bool`	`suggestion`	false

enableEndpointSuggestions

Supported Engines elasticsearch, solr, opensearch

indexSuggestionsConfig

Supported Engines elasticsearch, solr, opensearch

Specify the additional options for index suggestions. It accepts following keys:

sectionLabel: string To define the section title for index suggestions.

Type	Applicable on query of type	Required
`Object`	`suggestion`	false

deepPagination

Supported Engines elasticsearch, solr, opensearch

This flag tells RS whether to use the deep pagination functionality provided by the Backend to extract more than 10k results.

More about deepPagination can be read here for ElasticSearch

More about deepPagination can be read here for Solr

Type	Applicable on query of type	Required
`Boolean`	`all`	false

deepPaginationConfig

Supported Engines elasticsearch, solr, opensearch

Specify the configuration for using deep pagination in the respective backend.

ElasticSearch

For ElasticSearch, the deepPaginationConfig.cursor field should contain the sort array's first element of the last hits.hits item.

So if hits.hits is of length 10, then the deepPaginationConfig.cursor should be the sort field of the 9th index item of the search result.

Solr

For Solr, the deepPaginationConfig.cursor field should contain the nextCursorMark value received in the root of the response body in the first request.

endpoint

Supported Engines elasticsearch, solr, opensearch

This field indicates the backend of ReactiveSearch. Backend implies the search service being used to store the data.

As of now, the backend field supports the following values:

elasticsearch: ElasticSearch
opensearch: OpenSearch

where elasticsearch is the default value.

This field is necessary if backend is OpenSearch and the kNN reordering of scripts are to be used.

Following example indicates how to use this field to use kNN reordering with OpenSearch as backend:

Copy

{
    "query": [
        {
            "value": "sudoku",
            "vectorDataField": "name_vector",
            "queryVector": [1.0, -0.2],
        }
    ],
    "settings": {
        "backend": "opensearch"
    }
}

includeValues

Supported Engines elasticsearch, solr, opensearch

This fields indicates which values should be included in the terms aggregation (if done so). Only applied for term type of queries.

This should be of type array of strings:

Copy

{
    "query": [{
        "includeValues": ["someterm"]
    }]
}

NOTE: The string can be a regex as well but only for ElasticSearch backend, not Solr.

ElasticSearch

For ElasticSearch this maps to the include field inside the term query.

Solr

For Solr, this maps to the facet.contains field.

settings

Supported Engines Not dependent on engine, works for all.

recordAnalytics

Supported Engines elasticsearch, solr, opensearch

bool defaults to false. If true then it'll enable the recording of ReactiveSearch.io analytics.

backend

Supported Engines elasticsearch, solr, opensearch

This field indicates the backend of ReactiveSearch. Backend implies the search service being used to store the data.

As of now, the backend field supports the following values:

elasticsearch: ElasticSearch
opensearch: OpenSearch

where elasticsearch is the default value.

This field is necessary if backend is OpenSearch and the kNN reordering of scripts are to be used.

Following example indicates how to use this field to use kNN reordering with OpenSearch as backend:

Copy

{
    "query": [
        {
            "value": "sudoku",
            "vectorDataField": "name_vector",
            "queryVector": [1.0, -0.2],
        }
    ],
    "settings": {
        "backend": "opensearch"
    }
}

Following values are supported for this field

elasticsearch, opensearch, mongodb, solr, zinc

metadata

Supported Engines Not dependent on engine, works for all.

ReactiveSearch API for Solr

Query parameters

query

id

type

react

highlight

queryFormat

dataField

from

size

aggregationSize

sortBy

sortField

1. string

2. Array of string

3. Array of string / object

value

format for search and suggestion type

format for term type

format for range type

format for geo type

includeNullValues

includeFields

excludeFields

highlight

highlightField

highlightConfig

interval

aggregations

showMissing

defaultQuery

customQuery

execute

enableSynonyms

enablePopularSuggestions

popularSuggestionsConfig

showDistinctSuggestions

enablePredictiveSuggestions

maxPredictedWords

urlField

applyStopwords

customStopwords

searchLanguage

calendarInterval

enableFeaturedSuggestions

featuredSuggestionsConfig

enableIndexSuggestions

enableEndpointSuggestions

indexSuggestionsConfig

deepPagination

deepPaginationConfig

ElasticSearch

Solr

endpoint

includeValues

ElasticSearch

Solr

settings

recordAnalytics

backend

metadata

Getting Started

Product

Integrations

Use Cases

Company

1. `string`

format for `search` and `suggestion` type

format for `term` type

format for `range` type

format for `geo` type