Custom query

Tricks & Techniques
1

Rather than using the usual syntax to execute a query, it’s possible to directly call the index.queryLuaObjects function associated with lua.parseExpression. This will allow you to program the where clause and, if necessary, pass variables as parameters. The result can then be processed with js.tolua.

Syntax and structure

The syntax for queryLuaObjects function is:

function queryLuaObjects(
  tag: string,
  query: LuaCollectionQuery,
  scopedVariables?: Record<string, any>,
  ttlSecs?: number,
)

note scopedVariables: variables to inject into the Lua environment
Variables injected via scopeVariables are available throughout the LIQ expression. This approach works for any collection, not just the index. Variables can be of any supported JavaScript/Lua type

The structure of a LuaCollectionQuery is:

  LuaCollectionQuery = {
    objectVariable?: string;      // Variable name for each element (default is: _)
    where?: LuaExpression;    // Filter condition
    orderBy?: LuaOrderBy[];   // Sorting criteria (array of LuaOrderBy objects)
    select?: LuaExpression;    // Projection of results
    limit?: number;                   // Maximum number of results
    offset?: number;                // Offset for paging
    distinct?: boolean;            // Eliminate duplicates
  };

These fields accept LuaExpression which can be created with lua.parseExpression. The function parses a character string containing a Lua expression and returns its AST (Abstract Syntax Tree).

note The LuaExpression type can represent any valid Lua expression
Expressions have access to injected variables via scopedVariables (see: queryLuaObjects()).

Complete example

local results = index.queryLuaObjects(“page”, {
objectVariable = “p”,
where = lua.parseExpression(“p.lastModified > minDate and string.contains(p.name, searchTerm)”),
orderBy = {
{ expr = lua.parseExpression(“p.lastModified”), desc = true },
{ expr = lua.parseExpression(“p.name”), desc = false }
},
select = lua.parseExpression(“{ name = p.name, modified = p.lastModified }”),
limit = 10,
distinct = true
}, {
minDate = “2025-01-01”,
searchTerm = “project”
})

Then, js.tolua converts the JavaScript value to its Lua equivalent (the same as with query).

This technique is used in Task Explorer’s built-in queryer.
To see a list of examples and test how it works on tasks, you can take a look here:

1 Like