Query

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

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.

warning

Expressions can have any return type - as demonstrated by Calculated Columns (which use Expressions); however the Expression used by a query must always return a Boolean (true / false) value.

AdapTable Expressions

The Expression syntax is designed to be human readable and writable (though Expressions are typically created via the Expression Editor).

tip

We provide the Caption in the Expression Editor to help you identify the column more easily together with an option to see the Id value instead.

Expresions use common operators and functions and can include paranetheses, AND and OR support, and ternary logic.

For more informations on the syntax of Expressions, and the UI provided to build them, see Adaptable Expression.

Shared Queries

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

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

Once saved the Query is described as a Shared Query and is now available not only in the Query function but in any Adaptable Function that uses queries (e.g. Conditional Styles or Alerts).

Shared Queries in Config

It is possible to create a Shared Query in Query Predefined Config so that it is immediately available in other AdapTable Functions.

Indeed, other Predefined Config sections can themselves reference this Shared Query.

There is one 'gotcha' to be aware of however if this is being done: unlike with all other AdapTable functions the Uuid property must be included in the Config.

note

AdapTable typically creates the Uuid property internally when reading Predefined Config so the User doesn't need to be provided it; but since this object is immediately shared, the Uuid property is required

caution

The Uuid property should be something guaranteed to be unique (as it will be referenced elsewhere)

Query State

The Query Predefined Config includes 3 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.

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

  • 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 that allows users quickly and easily to create expressions. It has a number of useful features including:

    • Drag n Drop of Columns into the Editor

    • List of all the available functions as buttons or in a dropdown so they are immediately applied in the Editor

    • Provides the first row in the grid as (editable) 'dummy data'

    • Displays the return value of the Expression (using data from the first row of the Grid)

    • Context sensitive Support / Help for each available function

  • 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 - Provides a large input to enable users to write (and then run) a Query by hand if required. Also contains:

    • '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 SharedQueries together with the last 5 unsaved queries that were run.

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 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 Shared Query. This allows you to use the same Query for searching, styling, reports setc.

More Information