Query Module

The Query Module supports the creation and re-use of Expressions using AdapTableQL.

These Expressions - which can contain multiple conditions and operators - perform a powerful search function.

caution

Expressions can have any return type (e.g. Calculated Columns use Scalar Expressions); however the Expression used by the Query Module must always return a Boolean (true / false) value.

When a Query is run, AdapTableQL only returns those rows that match all the Conditions in the Expression.

note

Users can create multiple Queries (and then re-use them in other functions if required) but only one Query can be run at a time.

See AdapTableQL for detailed instructions on how to create Expressions - either by hand or using the Expression Editor.

Named Queries

Queries can be created and run at any time and then cleared when no longer needed.

However, if required, they can also be named and saved in order to be re-used.

A Named Query is typically used in 2 scenarios:

  • The Query Module: the Named Query is available for selection in the 'Load Query' dropdown in the Query Toolbar and Tool Panel

  • Other Expressions: the Named Query is automatically available in any Module that uses Expressions (e.g. Conditional Styles or Alerts).

    note

    Named Queries are available in AdapTableQL by using the QUERY function

Query Predefined Config

The Query Predefined Config is defined as follows:

PropertyDescription
CurrentQueryExpression used for the Query currently being run
NamedQueriesNamed Queries - can be referenced in other Expressions

As can be seen it has just 2 properties:

  • CurrentQuery - a BooleanExpression which will run as a 'Search'. This can be provided via Predefined Config but is more typically persisted at run-time after having been run by a user.

    note

    Only the actual Expression string itself is persisted here

  • NamedQueries - Queries that have been named and saved and so can be re-used in other Modules in AdapTable (e.g. Reports, Conditional Styles).

UI Elements

Query includes the following UI Elements:

  • Expression Editor - an easy to use UI, with a host of helpful features, that allows users quickly and easily to create expressions

  • Popup - Shows a list of existing Queries with Edit and Delete buttons, plus an Add button to start the Query Wizard which facilitates the creation and editing of Queries.

  • Toolbar - Assists running, creating, editing and saving Queries. Contains:

    • Large input to enable users to write a Query by hand if required
    • 'Run' button to perform the Search
    • 'Clear' button to cancel a Search
    • 'Expand' button to open the Expression Editor if UI support is needed
    • 'Save' button to allow the query to be named - and then re-used elsewhere
    • A dropdown showing all NamedQueries together with the last 5 unsaved queries that were run.
  • Tool Panel - Same as Toolbar above

UI Entitlements

UI Entitlements behaviour is as expected for Full and Hidden Access Levels.

The ReadOnly Entitlement behaviour is that Existing Queries can be run, and new Queries can be created (but they cannot be saved as Named Queries).

note

This restriction extends to Modules which allow Named Query creation (e.g. Conditional Style)

Query API

The Query API section of Adaptable API contains a lot of query-related functions:

MethodDescription
clearCurrentQuery()Clears the Current Query
getAllNamedQuery()Gets all Named Queries in Adaptable State
getCurrentQuery()Retuns the Current Query
getNamedQueryByName(namedQueryName)Retrieves Named Query with given name from State
getNamedQueryModuleReferences(namedQueryName)Returns all the references in the AdaptableState of the NamedQuery with the given name
getQueryState()Retrieves Query section from Adaptable State
getReferencedNamedQueryNames(expression)Returns the name of all the referenced Named Queries as an array of strings
isValidNamedQueryName(namedQuery)Checks if the given Named Query has a valid name
setCurrentQuery(query)Set a Query as Current Query
showExpandedQueryPopup()Opens Expanded Query Popup screen
showQueryPopup()Opens Query Popup screen

FAQ

Can we run Queries on the server?

Yes, through setting the serverSearchOptions property in Search Options.

See Server Searching for more information.

important

This option is only available if you are using the Client Side Row Model.

Does the Query get reapplied if I edit the data in the grid?

Yes, as soon as you make an edit AdapTable will re-evaluate if that row should be visible or not and react accordingly.

note

This is the default behaviour. You can change this to Never, or only after a ThrottleDelay by setting the filterActionOnUserDataChange property in Filter Options

Does Query update if the underlying data changes?

That depends on what you have specified for the filterActionOnExternalDataChange property in Filter Options.

The default is Never meaning Queries won't update as ticking data changes or the underlying data set changes. But you can change this to Always or after a ThrottleDelay.

Can we re-use the same query in different Functions - e.g. create a Query in Plus / Minus and use it also in Report?

Yes - by using a Named Query. This allows you to use the same Query for searching, styling, reports setc.

More Information