/

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:​all

Matches all documents, useful in combination with query​Builder:​if.

query​Builder:​composite

Composes multiple query builders using the AND or OR operator.

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:​for​Field​Values

Matches documents containing any of the variable's values in the document field you provide.

query​Builder:​if

Builds the query using one of the two query builders you provide, depending on the value of a boolean input.

query​Builder:​none

Matches no documents, useful in combination with query​Builder:​if.

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",
  "distinct": false,
  "minOrMatches": 1,
  "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.

distinct

Type
boolean
Default
false
Required
no

If true, Lingo4G removes duplicate rows from the output of this component.

min​Or​Matches

Type
integer
Default
1
Constraints
value > 0
Required
no

Sets the minimum number of clauses that must match in a document for it to be included in the result. This setting applies only when operator is equal to O​R.

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:​all

Matches all documents.

{
  "type": "queryBuilder:all"
}

This query builder is useful as one of the branches of the query​Builder:​if query builder.

query​Builder:​composite

Composes a list of query builders using the A​N​D or O​R operators.

{
  "type": "queryBuilder:composite",
  "operator": "OR",
  "queryBuilders": []
}

operator

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

Declares the way to combine the query builders. The operator property supports the following values:

O​R

Produces the union of all unique documents from all query builders.

A​N​D

Produces the intersection of all documents from all query builders. A document must match all queries to appear in the output.

query​Builders

Type
array of queryBuilder
Default
[]
Required
no

The list of query builders to compose.

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:​for​Field​Values

Matches documents containing any of the variable's values in the document field you provide.

{
  "type": "queryBuilder:forFieldValues",
  "fieldName": null,
  "variable": null
}

field​Name

Type
string
Default
null
Required
yes

The name of the field to search.

variable

Type
queryBuilderVariable
Default
null
Required
yes

The variable that provides the values to search.

query​Builder:​if

Builds the query using one of the two query builders you provide, depending on the value of a boolean input.

{
  "type": "queryBuilder:if",
  "condition": true,
  "ifFalse": {
    "type": "queryBuilder:none"
  },
  "ifTrue": {
    "type": "queryBuilder:none"
  }
}

If you combine this builder with query​Builder:​composite, you can build queries with optional clauses that are enabled using a boolean variable.

condition

Type
boolean
Default
true
Required
no

The condition that determines which query builder to execute.

if​False

Type
queryBuilder
Default
{
  "type": "queryBuilder:none"
}
Required
no

The query builder to execute when condition is false.

if​True

Type
queryBuilder
Default
{
  "type": "queryBuilder:none"
}
Required
no

The query builder to execute when condition is true.

query​Builder:​none

Matches no documents.

{
  "type": "queryBuilder:none"
}

This query builder is useful as one of the branches of the query​Builder:​if query builder.

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. 

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

distinct

Type
boolean
Default
false
Required
no

If true, Lingo4G removes duplicate variable values before passing them to the query builder.

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.

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.

values

Type
valueCollector
Default
null
Required
yes

The collector that computes the value of this variable.

variable

Type
string
Default
null
Required
yes

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​Neighbors:​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:​composite
  • query​Builders
    • query​Builder:​filter
  • query​Builder
  • filter​Query​Builder
    • query​Builder:​if
  • if​True
  • if​False
    •