The Query Module wraps, and runs, an Adaptable Query - a function which can contain multiple conditions and operators - as a powerful search facility.
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.
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.
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
Named Queries are available in the parser by using the QUERY function
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.
The Search Options section of Adaptable Options comains a number of useful properties for managing Queries.
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).
By default ALL columns are queryable so only provide a list if there some columns need to be excluded from Expressions
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
NamedQueriestogether with the last 5 unsaved queries that were run.
Tool Panel - Same as Toolbar above
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.
Can we run Queries on the server?
Yes, through setting the
ServerSearchOptions property in Search Options.
See Server Searching for more information.
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.