Query Builder

View as Markdown

Summary

  • Builds Boolean Expressions using dropdowns rather than typed AQL
  • Each condition is Subject (a Column, Field, the whole Row or $SCOPE) → Operator → Value
  • Values can be a typed value, another Column, or a Field
  • Nested AND / OR groups are supported
  • Shows a live Output Expression as you build

The Query Builder allows Boolean Expressions to be created at run-time without writing AdapTableQL by hand.

Hint

  • There are some Expressions which the Query Builder cannot display e.g. advanced keywords or invalid AQL
  • For these Expressions you need to use the Expression Editor

It is available wherever Boolean Expressions are edited - including Grid Filter, Alerts, Format Columns and Column Filter.

Hint

Use expressionOptions.editorOptions to choose which editors are offered and which opens first

Note

In a Column Filter (and a Badge Style rule) the Query Builder is always used, and the Subject is fixed to that Column - editorOptions does not apply there

AdapTableQL Query Builder
Fork
  • This demo opens the Grid Filter Settings Panel so the full Query Builder is visible
  • The Grid Filter includes a column comparison (Github Stars greater than Github Watchers) plus an AND / OR group
Loading demo…

Condition

A Query must contain at least one Condition.

Each Condition consists of 3 elements which are displayed in order: subject, operator and value.

Subject

The Subject is what the Condition tests. It is chosen from a dropdown, and can be one of:

SubjectWhat it testsAvailable
ColumnA cell value in the rowAlways
FieldA Field in the row dataWhen Fields have been provided
RowThe whole row, using row operators such as ANY_CONTAINS (any cell contains some text)Always
ScopeThe current Column, via the Scope FunctionWhere the Module supplies a Column Scope

Operator

The Operator is selected via a dropdown next to the subject.

The list is the Boolean Expression Functions that apply to the Subject's Data Type.

Note

This includes Custom Functions that return boolean and take 1 or 2 operands

Value

The Value is what the Subject is compared against.

There are 4 different possible values that can be selected:

  • An existing Column Value
  • A new value (not currently in the Column)
  • Another Column in the same row (a column comparison, e.g. [bid] > [ask])
  • A Field (if one has been defined)

Note

If the IN operator is used then a list of column values can be selected

AND / OR Groups

Conditions can be combined in AND / OR groups.

  • AND - every Condition in the group must be true
  • OR - at least one Condition in the group must be true

Groups can be nested, so a Query can mix both (e.g. a column comparison and an OR of two language checks).

Use Add Condition to add a row, and Add Group to nest another AND / OR block.

Output Expression

The Query Builder shows a live Output Expression under the conditions.

This is the AdapTableQL string that will be saved and evaluated.

It updates in real time as you change subjects, operators, values and groups.

Validation

Because conditions are built from dropdowns, most syntax errors cannot happen.

The Output Expression is still validated as you build. Incomplete conditions and type issues are flagged, and Apply / Run / Save stay disabled until the Expression is a valid boolean.

Hint

An Expression that is already invalid — or uses constructs the Builder cannot represent — cannot be edited here. See Query Builder Limitations.

Query Builder Limitations

The Query Builder is designed for standard Boolean predicate trees.

This means it will not open the condition editor if the current Expression:

  • is not Boolean (i.e. it returns a value other than true / false)
  • uses advanced keywords which the Builder cannot represent (e.g. QUERY)
  • is invalid, or has type / missing-column issues

In those cases the Builder explains why and asks the user to edit the Expression in the Expression Editor.

Empty / new Expressions still open in the Query Builder when it is the default editor.

Hint

To only use the Query Builder, set availableEditors in expressionOptions.editorOptions to ['QueryBuilder']