Parse a DQL query in Dynatrace Query API and return its canonical tree structure, including optional nodes and token positions for editor features.
| POST | SaaS | https://{your-environment-id}.apps.dynatrace.com/platform/storage/query/v1/query:parse |
For information about the required permissions see the Bucket and table permissions in Grail documentation.
Returns the parsed query as a tree, containing the structure of the canonical query. Tree-nodes can contain references to the token position where they originate from. This may help to provide hover effects, show canonical forms, mark optional items, and more.
The query tree consists of nodes that contain different additional information (everything optional):
Field | Mandatory | Description ----------------------- | — | – tokenPosition | no | optional. If present, it represents the position within the query string where the node refers to. isOptional | no | whether this node could be left out and the result would still be the same query (semantically).
contains start (inclusive) and end (inclusive), both contain index (0 based; fur substrings), line
and column (both 1-based; for readability).
tokenPosition is present, it always contains start and end with all fieldstokenPosition is not present, there might still be nested nodes that do contain a positionstart == end, the position refers to a single characterstart > end, we know for sure that something was inserted.We can always check whether the canonical representation of a node matches the text in the tokenPosition to see whether something was inserted, removed, or changed.
only present if it is true.
Optional nodes can e.g. be optional braces that make a query more readable, but are not necessary. This could be used to enter ghost braces and implicit functions in the user's input field; maybe with different formatting (using the tokenPosition of sibling nodes we can also check whether the user wrote these or not).
each node is of one of following types and may contain more fields:
can be identified by checking whether canonicalString is present
Field | Mandatory | Description
— | — | —
type | yes | the type of the terminal node - do not confuse with the type of container nodes
canonicalString | yes | the canonical string representation. Concatenating the canonicalString of all nested terminal nodes provides the canonical form of the query.
isMandatoryOnUserOrder | no | may only be present if (type="BRACE_OPEN" or type="BRACE_CLOSE") and isOptional=true. For usage see section Special node type: PARAMETERS
can be identified by checking whether children is present
Field | Mandatory | Description ----------------------- | — | – type | yes | the type of the container node - do not confuse with the type of terminal nodes children | yes | the children for the node. might be of any type
can contain children representing the parameters. Every second child is of type PARAMETER_SEPARATOR.
You may reorder the children based on their tokenPosition to get the user order. However, in this case,
you need to consider isMandatoryOnUserOrder to determine whether the grouping braces are mandatory or not.
For the query SORT a, {direction:"descending", b}, the canonical form is:
SORT a, {b, direction:"descending"}
This is the order, in which the parameters are returned in the query tree.
Parameters are {a} and {{b} and {direction:"descending"}}. In this case, the braces are optional.
SORT a, {b, direction:"descending"} is equivalent to SORT a, b, direction:"descending"
However, if you reorder the children by tokenPosition, the braces are not optional, because
SORT a, direction:"descending", b is interpreted as SORT {a, direction:"descending"}, b
So, if the children in PARAMETERS are re-ordered by tokenPosition, braces (or in general: TerminalNodes)
are only optional if isOptional && !isMandatoryOnUserOrder.
A container node of type FUNCTION may contain nodes of type FUNCTION_PART.
If those FUNCTION_PARTs are marked as optional, this means you have to either include all or none of these
optional function parts.
Example:
filter anyMatch(a.b == 1, input:a)
The optional function parts are anyMatch( and , input:a). If you leave out both, the command will still work:
filter a.b == 1 and return the same result. Using one of these optional function parts and removing the other will lead
to an invalid query.
can be identified by checking whether alternatives is present
Field | Mandatory | Description ----------------------- | — | – alternatives | yes | Type: Map<AlternativeType, DQLNode>
When displaying the query, pick one option. You may use the other options for hovering, replacing, and more.
Examples:
CANONICAL is not present, USER is present: user's nodes are optional, but not canonical (usually optional nodes
are still canonical)
CANONICAL is present, USER is not present: same as if the canonical node was optional. If this happens, it is
likely that there is also an INFO node
CANONICAL is present, USER is present: there are different alternatives
INFO is present: usually if CANONICAL is not present (e.g. the parameter key for FILTER a == 1), there is an info node
for FILTER condition:a == 1. This condition: was neither written by the user nor is it canonical; but it might be
used to help the user understand what this parameter means.
To execute this request, you need a platform token or OAuth access token with one of the following scopes:
storage:bizevents:readstorage:buckets:readstorage:entities:readstorage:events:readstorage:fieldsets:readstorage:logs:readstorage:metrics:readstorage:spans:readstorage:system:readTo learn how to obtain and use it, see Tokens and authentication.
| Parameter | Type | Description | In | Required |
|---|---|---|---|---|
| dt-client-context | string | The dt-client-context header is an optional string parameter used for monitoring purposes. When included in a request, it helps retrieve information about the execution of the query. It shouldn't hold sensitive information. | header | Optional |
| body | Parse | All parameters have to be passed via JSON in the POST body. | body | Required |
ParseRequest object| Element | Type | Description | Required |
|---|---|---|---|
| locale | string | The query locale. If none specified, then a language/country neutral locale is chosen. The input values take the ISO-639 Language code with an optional ISO-3166 country code appended to it with an underscore. For instance, both values are valid 'en' or 'en_US'. | Optional |
| query | string | The full query string. | Required |
| queryOptions | Query | Query options enhance query functionality for Dynatrace internal services. | Optional |
| timezone | string | The query timezone. If none is specified, UTC is used as fallback. The list of valid input values matches that of the IANA Time Zone Database (TZDB). It accepts values in their canonical names like 'Europe/Paris', the abbreviated version like CET or the UTC offset format like '+01:00' | Optional |
QueryOptions objectQuery options enhance query functionality for Dynatrace internal services.
This is a model of the request body, showing the possible elements. It has to be adjusted for usage in an actual request.
{"locale": "en_US","query": "fetch events \n| filter event.type == \"davis\" AND davis.status != \"CLOSED\" \n| fields timestamp, davis.title, davis.underMaintenance, davis.status \n| sort timestamp \n| limit 10","queryOptions": null,"timezone": "UTC"}
| Code | Type | Description |
|---|---|---|
| 200 | D | A node containing more nodes, a node offering different (semantically equivalent) versions of the query parts, or a terminal node that shows the canonical form. |
| 400 | - | - |
| 401 | - | - |
| 403 | - | - |
| 405 | - | - |
| 415 | - | - |
| 500 | - | - |
| 503 | - | - |
| 504 | - | - |
DQLNode objectGeneral Node in the DQL query.
| Element | Type | Description |
|---|---|---|
| isOptional | boolean | True if the node is optional. |
| nodeType | string | The type of the node. The element can hold these values
|
| tokenPosition | Token | The position of a token in a query string used for errors and notification to map the message to a specific part of the query. |
TokenPosition objectThe position of a token in a query string used for errors and notification to map the message to a specific part of the query.
| Element | Type | Description |
|---|---|---|
| end | Position | The exact position in the query string. |
| start | Position | The exact position in the query string. |
PositionInfo objectThe exact position in the query string.
| Element | Type | Description |
|---|---|---|
| column | integer | Query position column zero based index. |
| index | integer | Query position index. |
| line | integer | Query position line zero based index. |
{"children": [{"children": [{"canonicalString": "fetch","nodeType": "TERMINAL","tokenPosition": {"end": {"column": 5,"index": 4,"line": 1},"start": {"column": 1,"index": 0,"line": 1}},"type": "COMMAND_NAME"},{"canonicalString": " ","nodeType": "TERMINAL","type": "SPACE"},{"children": [{"children": [{"children": [{"alternatives": {"INFO": {"children": [{"canonicalString": "sourceId","nodeType": "TERMINAL","tokenPosition": {"end": {"column": 14,"index": 13,"line": 1},"start": {"column": 7,"index": 6,"line": 1}},"type": "PARAMETER_KEY"},{"canonicalString": ":","nodeType": "TERMINAL","type": "COLON"}],"isOptional": true,"nodeType": "CONTAINER","type": "PARAMETER_NAMING"},"USER": {"children": [{"canonicalString": "sourceId","nodeType": "TERMINAL","tokenPosition": {"end": {"column": 14,"index": 13,"line": 1},"start": {"column": 7,"index": 6,"line": 1}},"type": "PARAMETER_KEY"},{"canonicalString": ":","nodeType": "TERMINAL","type": "COLON"}],"isOptional": true,"nodeType": "CONTAINER","type": "PARAMETER_NAMING"}},"nodeType": "ALTERNATIVE"},{"children": [{"canonicalString": "logs","nodeType": "TERMINAL","tokenPosition": {"end": {"column": 19,"index": 18,"line": 1},"start": {"column": 16,"index": 15,"line": 1}},"type": "SIMPLE_IDENTIFIER"}],"nodeType": "CONTAINER","tokenPosition": {"end": {"column": 19,"index": 18,"line": 1},"start": {"column": 16,"index": 15,"line": 1}},"type": "SOURCE_ID"}],"nodeType": "CONTAINER","tokenPosition": {"end": {"column": 19,"index": 18,"line": 1},"start": {"column": 16,"index": 15,"line": 1}},"type": "PARAMETER_WITH_KEY"}],"nodeType": "CONTAINER","type": "PARAMETERS"}],"nodeType": "CONTAINER","tokenPosition": {"end": {"column": 19,"index": 18,"line": 1},"start": {"column": 16,"index": 15,"line": 1}},"type": "GROUP"}],"nodeType": "CONTAINER","tokenPosition": {"end": {"column": 19,"index": 18,"line": 1},"start": {"column": 1,"index": 0,"line": 1}},"type": "COMMAND"}],"nodeType": "CONTAINER","tokenPosition": {"end": {"column": 19,"index": 18,"line": 1},"start": {"column": 1,"index": 0,"line": 1}},"type": "QUERY"}