Search model

The below table represents all the fields that are present in the FlexSearch search query object. This object is used whenever you wish to execute a search against the engine.

Model Definition
Required Properties
indexName
queryString
All PropertiesTypeDefault Value
queryNamestring
columnsarray of string
countinteger10
highlightsComplex Object, Please refer: API Reference
indexNamestring
orderBystringscore
orderByDirectionstring (Enum: Ascending Descending )Ascending
cutOffnumber
distinctBystring
skipinteger
queryStringstring
returnScorebooleantrue
preSearchScriptstring
overridePredefinedQueryOptionsbooleanfalse
returnEmptyStringForNullbooleantrue
variablesobject of map<string, string>
For more indepth description of properties please refer to the API reference.

The search functionality is exposed over both get and post request types at the below endpoints:

GET \indices\{indexName}\search?q={queryParameters} HTTP/1.1
POST \indices\{indexName}\search?q={queryParameters} HTTP/1.1

{
    "QueryString" : ""
}

Model properties description

In this section we will go through some of the more important properties of the search query model. Index name and query string are the only two fields which are mandatory.

Columns

This property is used to define the columns which should be returned as part of search results.

  • If this property is omitted then no columns will be returned as we would like users to be explicit about the requirement.

  • * can be passed if you need all the available columns.

Query string parameter

Columns can also be requested using q in the URI parameters. This parameter is a string and not an array.

GET \indices\search?q=col1,col2 HTTP/1.1
GET \indices\search?q=* HTTP/1.1

Paging Properties

OrderBy & OrderByDirection

OrderBy by and OrderByDirection parameters can be used to sort the results coming from the engine. By default the sort order is relevance. This means the records which are more relevant to the search query will be at the top followed by less relevant results. The _score property in the returned document is the quantification of the relevance.

Skip & Count

Skip and count provides basic paging capability to the engine. Count is used to define the number of results that should be returned by a query. When count is used in conjunction with skip, it acts as page count property. Thus defining the number of records but page.

Filtering Properties

Filtering properties are a special set of properties which are used to filter out the results returned by the engine.This filtering happens after the main search logic has been executed and before returning the results to the user. Think of it as a way of looking at a table of result and identifying the ones which don’t meet the specific criteria. So this is excluding the documents from the result was search rather then excluding them through the search criteria.

The below diagram explains the concept. In the platform box once the platform logic is finished the sequence of documents are fed into the filtering criteria engine.

Search request receivedUserModePreSearch script executionPlatformPlatform logic exectionApply search time filters like distinctBy and cutOffUserModePost search script executionResult compilationResult is returned back to the caller

CutOff

Cut off criteria is used to filter out all the documents which score below a certain percentage. Due to the nature of Lucene it is not possible to have deterministic scores. So, here the percentages are calculated in respect of the highest scoring document. Thus keeping the cut-off relevant to the particular search query.

This feature is especially useful for duplicate detection. For example you want to identify duplicates of a given document. You already know that this particular document exist in the index. You can execute a search where this document should come out at the top of the search results. Then you can simply define that any other document which is within 10% range of this document can be deemed as duplicate. The formula used for cut-off is:

Current Document Score/Max score * 100

Cut-off value should be defined between 1 to 100.

DistinctBy

Think of distant by filter as the distinct by clause of SQL. Like other filters it runs post search and removes all the documents where the value of a particular field is not unique.

For example, you want to get a list of customers who purchase from you more than once but, you only want to get one customer per postcode. In such a situation distinct by will filter out all records where the value of postcode is not unique. The order by clause will dictate which records are filtered out.

Control properties

ReturnScore

This property signifies if the scored associated with the document should be returned as part of the search result.

PreSearchScript

This property can be used to define the name of the script which should be executed before executing the core logic. The script should be present on the server in order to be picked up. Refer to predefined query section to know more about this feature.

Variables

Variables are a way to provide dynamic values to the search query. You can simply define variables in your input query using @ symbol. For example the below query has a variable called fname.

allOf(firstname, @fname)

The advantages of this approach is that you can provide dynamic values to a query.

ReturnEmptyStringForNull

This property is useful when you don’t want to return null objects as part of your JSON response. In case of null values the engine will simply return blank strings.

OverridePredefinedQueryOptions

Predefined query’s are essentially a search query which has an associated name. Just like a normal query a predefined query can be configured using all the properties available on a normal search query object. There are times when you may want to override the values defined in the predefined query with the query object that you are passed to the server to execute the search.

For example, let’s say in a predefined query called findcustomer you have set the number of results to be returned to be 5. In a particular case you want to get more than 5 results back, in such a case you can set overridePredefinedQuery option to true and set the count property of the query to 10.