/

queryBuilder

query​Builder:​* components build search queries based on dynamically-changing inputs, such as values of document content fields.

You can use the following query​Builder:​* components in your analysis requests:

query​Builder:​aligned

Builds composite queries based on aligned lists of values of multi-value fields.

query​Builder:​filter

Narrows down the queries produced by the query builder you provide to the set of documents also matched by query produced by the filtering query builder.

query​Builder:​string

Builds queries based on a string template, substituting template variables with dynamic input.

query​Builder:​reference

References a query​Builder:​* component defined in the request or in the project's default components.

query​Builder:​aligned

Builds a composite query based on aligned lists of values of multi-value input.

{
  "type": "queryBuilder:aligned",
  "operator": "OR",
  "queryBuilder": {
    "type": "queryBuilder:reference",
    "auto": true
  },
  "variables": []
}

To build the final query, this builder performs the following steps:

  1. Collect lists of values for each input (e.g. document field).

  2. Build "rows" (tuples) of aligned input values, one row for each position in the input list of values. The number of rows is equal to the minimum number of values across the input lists of values.

  3. Invoke label​Filter of each query builder variable. If any input value of the row does not pass filtering, Lingo4G removes the entire row from further processing.

  4. Invoke the query​Builder for each "row" of values. Compose the resulting using the operator.

operator

Type
string
Default
"OR"
Constraints
one of [OR, AND]
Required
no

The operator Lingo4G uses to combine queries built from individual "rows" of values.

The operator property supports the following values:

O​R

Combines the queries using the OR (disjunction) operator.

A​N​D

Combines the queries using the AND (conjunction) operator.

query​Builder

Type
queryBuilder
Default
{
  "type": "queryBuilder:reference",
  "auto": true
}
Required
no

The query builder to invoke to build a query for each "row" of aligned input values.

The inputs to the query builder will be the variables you declare in the variables array.

variables

Type
array of queryBuilderVariable
Default
[]
Required
no

The input variables to make available for the nested query builder.

query​Builder:​filter

Narrows down the queries produced by the query builder you provide to the set of documents also matched by query produced by the filtering query builder. 

{
  "type": "queryBuilder:filter",
  "filterQueryBuilder": {
    "type": "queryBuilder:reference",
    "auto": true
  },
  "queryBuilder": {
    "type": "queryBuilder:reference",
    "auto": true
  }
}

filter​Query​Builder

Type
queryBuilder
Default
{
  "type": "queryBuilder:reference",
  "auto": true
}
Required
no

The query builder to supply the filtering queries.

query​Builder

Type
queryBuilder
Default
{
  "type": "queryBuilder:reference",
  "auto": true
}
Required
no

The query builder to supply the base queries.

query​Builder:​string

Builds queries based on a string template, substituting template variables with dynamic input, such as values of document content fields. 

{
  "type": "queryBuilder:string",
  "maxQueriesForDebugLogging": 0,
  "query": "",
  "queryParser": {
    "type": "queryParser:project",
    "queryParserKey": ""
  },
  "variables": []
}

max​Queries​For​Debug​Logging

Type
integer
Default
0
Required
no

The maximum number of queries to write to the analysis log.

Use this option to debug the query building process.

query

Type
string
Default
<empty string>
Required
no

The query template to use to build queries.

The query can use any syntax supported by the query​Parser, by default the enhanced query parser syntax.

Anywhere in the query template, you can use variable placeholders in the <​V​A​R> form, where V​A​R is the name of one of the variables declared in the variables array.

At query building time, Lingo4G replaces each variable placeholder with the variable value.

The following is an example query template referencing two variables: N​A​M​E and A​D​D​R​E​S​S: 

address_all:fn: maxwidth(20 fn: ordered("<NAME>" "<ADDRESS>"))

If you'd like to use the < character in the query template, escape it with the backslash character: \<.

query​Parser

Type
queryParser
Default
{
  "type": "queryParser:project",
  "queryParserKey": ""
}
Required
no

The query parser to use to parse the query.

variables

Type
array of queryBuilderVariable
Default
[]
Required
no

The variables to expose for use in the query template.

See the query builder variable documentation for more information.

query​Builder​Variable

Represents a single variable you can use to build dynamic queries. For top-level query builders, you can use values of document content fields as variable values. Additionally, you can use directly provided (constant) variable values. 

{
  "ifVariableValueNotAvailable": "IGNORE",
  "input": null,
  "labelFilter": {
    "type": "labelFilter:acceptAll"
  },
  "maxValues": 2147483647,
  "operator": "OR",
  "quote": false,
  "value": null,
  "variable": null
}

if​Variable​Value​Not​Available

Type
string
Default
"IGNORE"
Constraints
one of [FAIL, IGNORE]
Required
no

Determines what to do if values for the variable are not available.

It may happen that values for a variable may not be available. For example, this may happen if the content field that provides variable values is empty for some document.

The if​Variable​Value​Not​Available property supports the following values:

F​A​I​L

If variable values are not available for some document, the whole analysis fails with an error.

I​G​N​O​R​E

If variable values are not available for some document, proceed with processing.

Handling of missing values depends on the component that uses the variable. For example, the query​Builder:​string and query​Builder:​aligned components produce match-no-documents queries for documents with missing variable values.

input

Type
string
Default
null
Required
no

Determines the variable value to use.

For top-level query builders, use names of document content fields as variable inputs. At query building time, Lingo4G sets each variable value to the value(s) of the corresponding document's content field.

label​Filter

Type
labelFilter
Default
{
  "type": "labelFilter:acceptAll"
}
Required
no

Filters values of the variable.

Variable values that don't pass the filtering criteria will be removed from further processing.

max​Values

Type
integer
Default
2147483647
Constraints
value > 0
Required
no

The maximum number of multi-valued document field to use for processing.

operator

Type
string
Default
"OR"
Constraints
one of [OR, AND]
Required
no

The operator to use when joining variables having multiple values.

The operator property supports the following values:

O​R

Variable values will be joined using the O​R (disjunction) operator.

A​N​D

Variable values will be joined using the A​N​D (conjunction) operator.

quote

Type
boolean
Default
false
Required
no

If true, Lingo4G encloses each variable in double quotes before passing for further processing.

value

Type
string
Default
null
Required
no

The constant value to set the variable to.

You can use either input or value in the variable definition, you cannot use both.

variable

Type
string
Default
null
Required
no

The name of the variable.

Lingo4G uses variable names when processing query templates and when passing inputs for nested query builders.

Consumers of query​Builder:​*

The following stages and components take query​Builder:​* as input:

Stage or component Property
document​Scorer:​by​Query
  • query​Builder
    • matrix​Rows:​by​Query
  • query​Builder
    • query:​for​Document​Fields
  • query​Builder
    • query:​from​Query​Builder
  • query​Builder
    • query​Builder:​aligned
  • query​Builder
    • query​Builder:​filter
  • query​Builder
  • filter​Query​Builder
    •