DQL query action for Workflows
- Latest Dynatrace
- Reference
- 1-min read
The Execute DQL Query action for Workflows enables you to query data from Grail using DQL and use the results in subsequent tasks.
Input
- DQL query: The DQL query to run.
- Filter segment: One or more filter segments to apply to the query. Filter segments narrow the data visible to the query based on predefined criteria.
- Timezone: The timezone used for time-based DQL functions such as
toTimestamp(). Defaults to UTC when not set. - Fail on empty result: When enabled, the action will fail if the query returns no records.
Result
The result of the Execute DQL Query action is the response of the Grail query API, which includes the following top-level properties:
records: Array of result records. The fields in each record correspond to the columns projected by the DQL query.types: Type metadata describing the schema of the records.metadata: Query execution metadata such as the analyzed timeframe, scanned bytes, and a query ID for debugging.
Differences from interactive DQL usage in apps
The Execute DQL Query action, like any other action, is non-interactive. It runs in an automated fashion as part of your workflow. This is especially relevant as you might have expectations from using DQL in apps like 
Notebooks and 
Dashboards, which come with their own behavior built on top of the Grail query API. This means:
- Timezone: The API defaults to UTC. Notebooks and Dashboards automatically apply your browser locale or configured user settings timezone, but the Execute DQL Query action has no access to user settings. If your results depend on local time, use the Timezone input field or set the timezone explicitly in the query. This also affects calendar-aligned anchor expressions—expressions that snap to a calendar boundary, such as
-1M@M(start of last month), are evaluated relative to the Timezone field, which may produce different results than a notebook where your local timezone is applied automatically. - Timeframe: If no timeframe is specified in the query, the API default applies (last 2 hours). To set an explicit timeframe, use the
fromandtoparameters of thefetchcommand. - Record limit: The default result limit is 1,000 records. Use the
limitkeyword in the query to retrieve more. The actual upper bound is the general action result size limit.
Query the triggering event
When a workflow is started by an event trigger, the execution might already be processing while the triggering event has not yet been persisted in Grail. An Execute DQL Query task in your workflow that looks up the event via fetch ... may therefore return no results. To work around this, either set a Wait before delay of 30–45 seconds in the task options, or pass the event directly into the DQL query using the data command—the triggering event is available in the workflow execution context via {{ event() }}:
data json:"""{{ event()|to_json }}"""| fields timestamp, event.name, event.id
Use DQL results in conditions
A task with state Success means the action ran without error—it does not mean the query returned records.
To branch on whether any records were returned, enable Fail on empty result on the DQL task. The task then fails when the query returns no records. Then use a condition on downstream tasks to decide to run or not, depending on success or error of the query task.
If you leave Fail on empty result disabled, the records array may be empty even when the task succeeds. Accessing a specific record without first checking the array length will cause a condition error.
Use the | length filter to check for records before accessing them:
{{ result("dql_task")["records"] | length > 0 }}
To safely access the first record in a condition:
{{ result("dql_task")["records"] | length > 0 and result("dql_task")["records"][0]["field_name"] == "expected_value" }}