# Curation
While Typesense makes it really easy and intuitive to deliver great search results, sometimes you might want to promote certain documents over others. Or, you might want to exclude certain documents from a query's result set.
Using overrides, you can include or exclude specific documents for a given query.
Precedence
When using Synonyms and Overrides together, Overrides are handled first since the rules can contain instructions to replace the query. Synonyms will then work on the modified query.
# Create or update an override
# Including or excluding documents
In the following example, we will:
- Use the
includes
condition to place the documents with ids422
and54
in the first and second positions respectively. - Use the
excludes
condition to remove the document with id287
from the results.
Typesense allows you to use both includes
and excludes
or just one of them for curation.
Note how we are applying these overrides to an exact
match of the query apple
. Instead, if we want to match all
queries containing the word apple
, we will use the contains
match instead.
# Sample Response
# Dynamic filtering
In the following example, we will apply a filter dynamically to a query that matches a rule.
With this override in effect, any query that contains a brand will automatically be filtered on the matching brand directly. In addition, the brand will also be removed from the original query tokens, so that the search is made only on the remaining tokens.
For example, if someone searches for sony ericsson phone
, the query will be re-written as phone
and a
sony ericsson
brand filter will be directly applied. If you don't wish to remove matching tokens from the query,
set remove_matched_tokens
to false
. By default, this parameter is set to true
.
Note
Fields used in the query for dynamic filtering should have facet: true
in their field definition in the schema.
# Curation and filtering
includes
is used to fix documents at certain positions in the results, but it's possible for these documents to
be filtered out when using filter_curated_hits: true
.
When this happens, Typesense "slides" any remaining documents added by includes
up in the results.
For example, say you have a collection of product records that look like this when sorted on a ranking
field:
1. ABC123 (in stock)
2. DEF456 (sold out)
3. XYZ999 (sold out)
4. QWE127 (in stock)
5. BNM847 (in stock)
6. JKL999 (in stock)
7. CVB333 (in stock)
Let's say an override is created that uses includes
to pin the following records to specific positions. The override also has
filter_curated_hits
set to true, so the documents added by includes
can be filtered out if they don't match any
filter_by
conditions:
- QWE127 pinned to position 1
- DEF456 pinned to position 2
- CVB333 pinned to position 3
When this override is applied to a search, the result will be:
1. QWE127 (in stock) <- Position set by includes
2. DEF456 (sold out) <- Position set by includes
3. CVB333 (in stock) <- Position set by includes
4. ABC123 (in stock)
5. XYZ999 (sold out)
6. BNM847 (in stock)
7. JKL999 (in stock)
If a status:=in stock
filter is then added to the search, the sold-out records are removed. This includes DEF456
,
even though it's one of the records the override is trying to add via includes
(because it's out of stock and the
override has filter_curated_hits: true
). The end result is that the two in-stock records from the override appear at
positions 1 and 2, with the remaining records below them:
1. QWE127 (in stock) <- Position set by includes
2. CVB333 (in stock) <- Position set by includes (moved up)
3. ABC123 (in stock)
4. BNM847 (in stock)
5. JKL999 (in stock)
Document CVB333
"slides up" to position 2, to take the place of DEF456
(which has been filtered out).
# Override parameters
# Definition
PUT ${TYPESENSE_HOST}/collections/:collection/overrides/:id
# Parameters
Parameter | Required | Description |
---|---|---|
rule.query | One of either rule.query or rule.filter_by is required. | Indicates what search queries should be overridden. |
rule.match | no | Indicates whether the match on the query term should be exact or contains . Required when rule.query is set. |
rule.filter_by | One of either rule.query or rule.filter_by is required. | Indicates that the override should apply when the filter_by parameter in a search query exactly matches the string specified here (including backticks, spaces, brackets, etc). |
excludes | no | List of document id s that should be excluded from the search results. |
includes | no | List of document id s that should be included in the search results with their corresponding positions . |
filter_by | no | A filter by clause that is applied to any search query that matches the override rule. |
sort_by | no | A sort by clause that is applied to any search query that matches the override rule. |
replace_query | no | Replaces the current search query with this value, when the search query matches the override rule. |
remove_matched_tokens | no | Indicates whether search query tokens that exist in the override's rule should be removed from the search query. Default: true . |
filter_curated_hits | no | When set to true , the filter conditions of the query is applied to the curated records as well. Default: false . |
effective_from_ts | no | A Unix timestamp that indicates the date/time from which the override will be active. You can use this to create override rules that start applying from a future point in time. |
effective_to_ts | no | A Unix timestamp that indicates the date/time until which the override will be active. You can use this to create override rules that stop applying after a period of time. |
stop_processing | no | When set to true , override processing will stop at the first matching rule. When set to false override processing will continue and multiple override actions will be triggered in sequence. Overrides are processed in the lexical sort order of their id field.Default: true . |
# List all overrides
Listing all overrides associated with a given collection.
# Sample Response
# Definition
GET ${TYPESENSE_HOST}/collections/:collection/overrides
# Retrieve an override
Fetch an individual override associated with a collection.
# Sample Response
# Definition
GET ${TYPESENSE_HOST}/collections/:collection/overrides/:id
# Delete an override
Deleting an override associated with a collection.
# Sample Response
# Definition
DELETE ${TYPESENSE_HOST}/collections/:collection/overrides/:id