flexsearch/doc/resolver.md

Resolver (Complex Queries)

Retrieve an unresolved result:

const raw = index.search("a short query", { 
    resolve: false
});

You can apply and chain different resolver methods to the raw result, e.g.:

raw.and( ... )
   .and( ... )
   .boost(2)
   .or( ... ,  ... )
   .limit(100)
   .xor( ... )
   .not( ... )
   // final resolve
   .resolve({
       limit: 10,
       offset: 0,
       enrich: true
   });

The default resolver:

const raw = index.search("a short query", { 
    resolve: false
});
const result = raw.resolve();

Alternatively you can create a Resolver by passing an initial query:

import { Resolver } from "flexsearch";
const raw = new Resolver({
    // pass the index is required when query was set
    index: index,
    query: "a short query"
});
const result = raw.resolve();

Chainable Boolean Operations

The basic concept explained:

// 1. get one or multiple unresolved results
const raw1 = index.search("a short query", { 
    resolve: false
});
const raw2 = index.search("another query", {
    resolve: false,
    boost: 2
});

// 2. apply and chain resolver operations
const raw3 = raw1.and(raw2, /* ... */);
// raw1 has changed, raw2 is same, raw3 refers to raw1
// you can access the raw result by
console.log("The aggregated result is:", raw3.result)
// apply further operations ...

// 3. resolve final result
const result = raw3.resolve({
    limit: 100,
    offset: 0
});
console.log("The final result is:", result)

Chain operations and nest inline queries:

const result = index.search("further query", {
    // set resolve to false on the first query
    resolve: false,
    // boost the first query
    boost: 2
})
.or({
    // nested expression
    and: [{
        query: "a query"
    },{
        query: "another query"
    }]
})
.not({
    query: "some query"
})
// resolve the result
.resolve({
    limit: 100,
    offset: 0
});

Alternatively you can create a Resolver by passing an initial query:

import { Resolver } from "flexsearch";
const result = new Resolver({
    // pass the index is required when query was set
    index: index,
    query: "further query",
    boost: 2
})
.or({
    and: [{
        query: "a query"
    },{
        // you can bind a different index for this
        // query when IDs are from same source
        index: index,
        query: "another query"
    }]
})
.not({
    index: index,
    query: "some query"
})
.resolve({
    limit: 100,
    offset: 0
});

When all queries are made against the same index, you can skip the index in every resolver stage followed after initially calling new Resolve({ index: ... }):

import { Resolver } from "flexsearch";
const result = new Resolver({
    index: index,
    query: "a query"
})
.and({ query: "another query" })
.or ({ query: "further query", boost: 2 })
.not({ query: "some query" })
.resolve(100);

Resolver Tasks

Method	Description	Return
.and(options,...) .or(options,...) .not(options,...) .xor(options,...)	Apply an operation	Returns a Resolver when resolve was not set to false within the options, otherwise it returns the result (or promise in async context).
.limit(number) .offset(number) .boost(number)	Apply boost, limit and offset to the result	Returns a Resolver
.resolve(options)	Resolve results	Returns the final result or promise in async context (can't be executed twice)

Resolver Options

Option	Values	Description	Default
Resolver Task Options:
query	String	The search query
index	Index Document	Assign the index where the query should be applied to
suggest	Boolean	Enables suggestions in results	false
boost	Number	Boost or reduce the score of this query	0
async	Boolean	Use a parallel processing workflow	false
queue	Boolean	Use a queued processing workflow	false
and or not xor	Array<ResolverOptions>	Apply nested queries
resolve	Boolean	Resolve the result immediately or not. When set to true all final resolve options are also allowed and there can't exist any further resolver operations.	false
Document Resolver Options:
field pluck	String	Select the Document field on which the query should apply to.
Final Resolve Options:
enrich	Boolean	Enrich IDs from the results with the corresponding documents (for Document Indexes only)	true
highlight	Highlighting Options String	Highlight query matches in the result (for Document Indexes only)
limit	Number	Sets the limit of results	100
offset	Boolean	Apply offset (skip items)	0

Using Cached Queries

import { Resolver } from "flexsearch";
const result = new Resolver({
    index: index,
    query: "a query",
    cache: true
})
.and({ 
    query: "another query",
    cache: true
})
.resolve(100);

Async Resolver

Using Async Queries (incl. Runtime Balancer)

All async tasks will run in parallel, balanced by the runtime observer:

import { Resolver } from "flexsearch";
const resolver = new Resolver({
    index: index,
    query: "a query",
    async: true
})
.and({ 
    query: "another query",
    async: true
})
.or({
    query: "some query",
    async: true
});
const result = await resolver.resolve(100);

When you need to access the raw result resolver.result you should await for the task completion of all added resolver stages up to this point.

const resolver = new Resolver({
    index: index,
    query: "a query",
    async: true
})
.and({ 
    query: "another query",
    async: true
});

// await for the task completion
await resolver.await;
// get the raw result
const raw = resolver.result;
// continue adding further tasks ...

Queuing Async Queries

All queued tasks will run consecutively, also balanced by the runtime observer:

import { Resolver } from "flexsearch";
const resolver = await new Resolver({
    index: index,
    query: "a query",
    async: true
})
.and({ 
    query: "another query",
    queue: true
})
.or({
    query: "some query",
    queue: true
})
.resolve(100);

When tasks are processed consecutively, it will skip specific resolver stages when there is no result expected.

Compare Parallel VS. Consecutive

When using the parallel workflow by passing { async: true }, all resolver stages will send their requests (including nested tasks) to the DB immediately and calculate the results in the right order as soon as the request resolves. When the overall workload of your applications has some free resources, a parallel request workflow improves performance compared to the consecutive counterpart.

When using the consecutive workflow by passing { queue: true }, all resolver stages will send their requests (including nested tasks) to the DB only when the previous request resolves. The advantage of this variant is when a stage becomes invalid because of the previous result, it can skip the request completely and continue with the next stage. This can reduce the overall workload.