Query

The Query Module wraps, and runs, an Adaptable Query - a function which can contain multiple conditions and operators - as a powerful search facility.

warning

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 the Query is run, the AdapTable Parser will only return those rows that match all of the Conditions in the Query.

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 Adaptable Query 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 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 the parser by using the QUERY function

Query State

The Query Predefined Config includes 2 main elements:

  • CurrentQuery - an Expression 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. Only the actual Expression string itself is persisted here.

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

SearchOptions

The Search Options section of Adaptable Options comains a number of useful properties for managing Queries.

These include:

  • expressionFunctions - sets which parser functions (including custom ones) are available in the Query

  • queryableColumns - a list of Columns which can be used in an Expression - typically used if the users are running the Expression remotely (see Server Functionality Guide).

    tip

    By default ALL columns are queryable so only provide a list if there some columns need to be excluded from Expressions

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

Entitlements

Query Entitlement Rules:

  • Full: Everything is available to the User

  • Hidden: Everything is hidden from the User

  • ReadOnly: User can run Queries in Predefined Config but not edit or delete them, nor add others.

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 Query update 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 that this is the default behaviour. You can change this to Never, or only after a ThrottleDelay by setting the filterActionOnUserDataChange property in Search Options.

Does Query update if the underlying data changes?

That depends on what you have specified for the filterActionOnExternalDataChange property in Search 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