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.
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.
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.
The Expression syntax is designed to be human readable and writable (though Expressions are typically created via the Expression Editor).
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.
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.
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.
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
The Uuid property should be something guaranteed to be unique (as it will be referenced elsewhere)
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.
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 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
SharedQueriestogether with the last 5 unsaved queries that were run.
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 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.