DQL Query

Exposes an API to fetch records stored in Grail

@dynatrace-sdk/client-query

v1.17.0

npm install @dynatrace-sdk/client-query

queryAssistanceClient

import { queryAssistanceClient } from '@dynatrace-sdk/client-query';

queryAutocomplete

queryAssistanceClient.queryAutocomplete(config): Promise<AutocompleteResponse>

Get a structured list of suggestions for the query at the given position.

For information about the required permissions see the Bucket and table permissions in Grail documentation.

Overview

We provide a list of suggestions that may be used after the cursor position. The following queries will all provide the same results:

• query: "f"
• query: "f", cursorPosition:1
• query: "fetch ", cursorPosition:1

Available fields:

Field	Description
suggestions	a list of suggestions. Each item is a separate possible suggestion, despite they might have the same outputs.
optional	whether the suggestion is optional. If true, the query until the cursor position might work. If false, the query is definitely incomplete or invalid if cut at the cursor position.

Fields in the suggestions

Field	Description
suggestion	a string representing the whole suggestion. This information could also be derived from the parts.
alreadyTypedCharacters	how many characters of this suggestion have already been typed (and will be overridden by the suggestion).
parts	a list of semantically enriched information on what are the parts of a suggestion.

Fields in parts

Field	Description
suggestion	a string representing the current part of the suggestion.
type	current types: SPACE, PIPE, COMMAND (may be extended)

The type helps to treat specific parts of the suggestion different to others; either by a different visualization, a link to docs, etc.

Parameters

Name	Type
config.body*required	AutocompleteRequest

Returns

Return type	Description
Promise<AutocompleteResponse>	A list of structured autocomplete suggestions.

Throws

Error Type	Error Message
ErrorEnvelopeError	The supplied request is wrong. Either the query itself or other parameters are wrong. | An internal server error has occurred.

Code example

import { queryAssistanceClient } from "@dynatrace-sdk/client-query";

const data = await queryAssistanceClient.queryAutocomplete({
  body: {
    query:
      'fetch events | filter event.type == "davis" AND davis.status != "CLOSED" | fields timestamp, davis.title, davis.underMaintenance, davis.status | sort timestamp | limit 10',
  },
});

queryParse

queryAssistanceClient.queryParse(config): Promise<DQLNode>

Get a structured tree of the canonical form of the query.

For information about the required permissions see the Bucket and table permissions in Grail documentation.

Overview

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.

Details

The query tree consists of nodes that contain different additional information (everything optional):

General Fields

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).

tokenPosition

contains start (inclusive) and end (inclusive), both contain index (0 based; fur substrings), line and column (both 1-based; for readability).

• If tokenPosition is present, it always contains start and end with all fields
• If tokenPosition is not present, there might still be nested nodes that do contain a position
• If start == end, the position refers to a single character
• If start > 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.

isOptional

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).

Advanced Token Types

each node is of one of following types and may contain more fields:

• Terminal Node
• ContainerNode
• Alternative Node

Terminal Node

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

Current types of terminal nodes (list might grow):

• SPACE
• LINEBREAK
• INDENT
• PIPE
• DOT
• COLON
• COMMA
• BRACE_OPEN
• BRACE_CLOSE
• BRACKET_OPEN
• BRACKET_CLOSE
• PARENTHESIS_OPEN
• PARENTHESIS_CLOSE
• QUOTE
• SLASH
• BOOLEAN_TRUE
• BOOLEAN_FALSE
• NULL
• COMMAND_NAME
• PARAMETER_KEY
• PARAMETER_VALUE_SCOPE
• FUNCTION_NAME
• OPERATOR
• TRAVERSAL_OPERATOR
• TRAVERSAL_RELATION_NAME
• TRAVERSAL_HOP_COUNT
• SIMPLE_IDENTIFIER
• NUMBER
• STRING
• TIME_UNIT
• TIMESTAMP_VALUE
• METRIC_KEY
• VARIABLE

ContainerNode

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

Current types of container nodes (list might grow):

• QUERY
• EXECUTION_BLOCK
• COMMAND
• COMMAND_SEPARATOR
• PARAMETER_WITH_KEY
• GROUP
• PARAMETERS - check examples further down
• PARAMETER_NAMING
• PARAMETER_SEPARATOR
• FUNCTION
• FUNCTION_PART - check examples further down
• EXPRESSION
• IDENTIFIER
• SOURCE_ID
• DURATION
• TIMESTAMP
• TIMEFRAME
• TRAVERSAL_PATH
• TRAVERSAL_STEP

Special node type: PARAMETERS

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.

Example

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.

Special node type: FUNCTION_PART

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.

Alternative Node

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.

Current values of AlternativeType (list might grow):

• CANONICAL: This node is the one we will use for our canonical form
• USER: An alternative that is also valid, but not canonical; and this version was picked by the user.
• INFO: only if the canonical version is not present

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.

Parameters

Name	Type
config.body*required	ParseRequest

Returns

Return type	Description
Promise<DQLNode>	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.

Throws

Error Type	Error Message
ErrorEnvelopeError	The supplied request is wrong. Either the query itself or other parameters are wrong. | An internal server error has occurred.

Code example

import { queryAssistanceClient } from "@dynatrace-sdk/client-query";

const data = await queryAssistanceClient.queryParse({
  body: {
    query:
      'fetch events | filter event.type == "davis" AND davis.status != "CLOSED" | fields timestamp, davis.title, davis.underMaintenance, davis.status | sort timestamp | limit 10',
  },
});

queryVerify

queryAssistanceClient.queryVerify(config): Promise<VerifyResponse>

Verifies a query without executing it.

For information about the required permissions see the Bucket and table permissions in Grail documentation.

Overview

Verifies the supplied query string and other query parameters for lack of any errors, but without actually submitting the query for execution.

Parameters

Name	Type
config.body*required	VerifyRequest

Returns

Return type	Description
Promise<VerifyResponse>	Supplied query and parameters were verified.

Throws

Error Type	Error Message
ErrorEnvelopeError	The supplied request is wrong. | An internal server error has occurred.

Code example

import { queryAssistanceClient } from "@dynatrace-sdk/client-query";

const data = await queryAssistanceClient.queryVerify({
  body: {
    query:
      'fetch events | filter event.type == "davis" AND davis.status != "CLOSED" | fields timestamp, davis.title, davis.underMaintenance, davis.status | sort timestamp | limit 10',
  },
});

queryExecutionClient

import { queryExecutionClient } from '@dynatrace-sdk/client-query';

queryCancel

queryExecutionClient.queryCancel(config): Promise<void | QueryPollResponse>

Cancels the query and returns the result if the query was already finished, otherwise discards it.

For information about the required permissions see the Bucket and table permissions in Grail documentation.

Overview:

Cancels a running Grail query and returns a list of records if the query already finished.

The response format:

If the query was already finished, a response body including the result will be returned. Otherwise the response will contain no body.

The result has three main sections:

• the 'records' section contains the individual records, where each record consists of a set of fields and their corresponding values.
• the 'types' section describes the corresponding data types that a record field has.
• the 'metadata' section contains information about the query like 'analysisTimeframe', 'timezone' or 'locale'.

Every record has an implicit 'index' according to the position in the 'records' JSON array. The types section has a list of 1..N possible type 'buckets'. Each such bucket has an 'indexRange' which indicates which records will find their field types in which bucket. The index range has two values start & end and can be thought of as [startIndex, endIndex).

A field part of a record with index 'i' will find its corresponding field type by first locating the bucket that satisfies:

startIndex <= i <= endIndex

Once the bucket is found the 'mappings' object has an entry for all the fields that are part of that record with index 'i'.

Since enforcement of a particular schema is absent at ingestion time, it is possible to have records that share the same field name but their values are of a different type. This phenomenon will hence forth be named as a "collision". When a collision does occur, we will create a new type 'bucket' that will have a different index range where the new record field types will be placed. It is guaranteed that every field of every record will have a corresponding type. Clients should always take the included types into account when consuming records!

Parameters

Name	Type	Description
config.enrich	string	If set additional data will be available in the metadata section.
config.requestToken*required	string	The request-token of the query.

Returns

Return type	Description
Promise<QueryPollResponse	void>

Throws

Error Type	Error Message
ErrorEnvelopeError	The supplied request is wrong. Either the query itself or other parameters are wrong. | An internal server error has occurred.

Code example

import { queryExecutionClient } from "@dynatrace-sdk/client-query";

const data = await queryExecutionClient.queryCancel({
  requestToken: "...",
});

queryExecute

queryExecutionClient.queryExecute(config): Promise<QueryStartResponse>

Starts a Grail query.

For information about the required permissions see the Bucket and table permissions in Grail documentation.

Overview:

Executes a query and returns a list of records.

For details about the query language see the Dynatrace Query Language documentation.

The response format:

The json response will contain the state of the started query. If the query succeeded, the result will be included. Otherwise the response will contain a request token to reference the query in future polling requests.

The result has two main sections:

• The 'records' section contains the individual records, where each record consists of a set of fields and their corresponding values.
• The 'types' section describes the corresponding data types that a record field has.

Every record has an implicit 'index' according to the position in the 'records' JSON array. The types section has a list of 1..N possible type 'buckets'. Each such bucket has an 'indexRange' which indicates which records will find their field types in which bucket. The index range has two values start & end and can be thought of as [startIndex, endIndex).

A field part of a record with index 'i' will find its corresponding field type by first locating the bucket that satisfies:

startIndex <= i <= endIndex

Once the bucket is found the 'mappings' object has an entry for all the fields that are part of that record with index 'i'.

Since enforcement of a particular schema is absent at ingestion time, it is possible to have records that share the same field name but their values are of a different type. This phenomenon will hence forth be named as a "collision". When a collision does occur, we will create a new type 'bucket' that will have a different index range where the new record field types will be placed. It is guaranteed that every field of every record will have a corresponding type. Clients should always take the included types into account when consuming records!

Parameters

Name	Type	Description
config.body*required	ExecuteRequest
config.enrich	string	If set additional data will be available in the metadata section.

Returns

Return type	Description
Promise<QueryStartResponse>	The final status and results of the supplied query if it finished within a supplied requestTimeoutMilliseconds. | The status of the query to start.

Throws

Error Type	Error Message
ErrorEnvelopeError	The supplied request is wrong. Either the query itself or other parameters are wrong. | Too many requests. | An internal server error has occurred. | Service is unavailable. | Client error. | Server error.
InsufficientPermission	Insufficient permissions.

Code example

import { queryExecutionClient } from "@dynatrace-sdk/client-query";

const data = await queryExecutionClient.queryExecute({
  body: {
    query:
      'fetch events | filter event.type == "davis" AND davis.status != "CLOSED" | fields timestamp, davis.title, davis.underMaintenance, davis.status | sort timestamp | limit 10',
  },
});

queryPoll

queryExecutionClient.queryPoll(config): Promise<QueryPollResponse>

Retrieves query status and final result from Grail.

For information about the required permissions see the Bucket and table permissions in Grail documentation.

Overview:

Polls the status of a Grail query. Returns the status of the query, including the result if the query finished.

The response format:

The json response will contain the state of the query. If the query succeeded, the result will be included.

The result has two main sections:

• The 'records' section contains the individual records, where each record consists of a set of fields and their corresponding values.
• The 'types' section describes the corresponding data types that a record field has.

Every record has an implicit 'index' according to the position in the 'records' JSON array. The types section has a list of 1..N possible type 'buckets'. Each such bucket has an 'indexRange' which indicates which records will find their field types in which bucket. The index range has two values start & end and can be thought of as [startIndex, endIndex).

A field part of a record with index 'i' will find its corresponding field type by first locating the bucket that satisfies:

startIndex <= i <= endIndex

Once the bucket is found the 'mappings' object has an entry for all the fields that are part of that record with index 'i'.

Since enforcement of a particular schema is absent at ingestion time, it is possible to have records that share the same field name but their values are of a different type. This phenomenon will hence forth be named as a "collision". When a collision does occur, we will create a new type 'bucket' that will have a different index range where the new record field types will be placed. It is guaranteed that every field of every record will have a corresponding type. Clients should always take the included types into account when consuming records!

Parameters

Name	Type	Description
config.enrich	string	If set additional data will be available in the metadata section.
config.requestTimeoutMilliseconds	number	The time a client is willing to wait for the query result. In case the query finishes within the specified timeout, the query result is returned. Otherwise, the query status is returned.
config.requestToken*required	string	The request-token of the query.

Returns

Return type	Description
Promise<QueryPollResponse>	The current status and results of the supplied query.

Throws

Error Type	Error Message
ErrorEnvelopeError	The supplied request is wrong. Either the query itself or other parameters are wrong. | An internal server error has occurred.

Code example

import { queryExecutionClient } from "@dynatrace-sdk/client-query";

const data = await queryExecutionClient.queryPoll({
  requestToken: "...",
});

Types

AutocompleteRequest

Name	Type	Description
cursorPosition	number
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'.
maxDataSuggestions	number
query*required	string	The full query string.
queryOptions	QueryOptions	Query options enhance query functionality for Dynatrace internal services.
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'

AutocompleteResponse

The response of the autocomplete call.

Name	Type	Description
optional*required	boolean	True if the suggestions are optional.
suggestedTtlSeconds	number	Suggested duration in seconds, for how long the response may be cached and reused by the client. It is derived from the volatility of the suggestions on the server (if the suggestions are static, how long the server will cache the volatile suggestions, ...). If not provided, then the result may be cached for long time. Value below 1 means that the result should not be cached.
suggestions*required	Array<AutocompleteSuggestion>	The list of suggestions.

AutocompleteSuggestion

Single suggestion for completion of the query.

Name	Type	Description
alreadyTypedCharacters*required	number	Number of characters that the user already typed for this suggestion.
parts*required	Array<AutocompleteSuggestionPart>	List of suggestion parts.
suggestion*required	string	The suggested continuation of the query.

AutocompleteSuggestionPart

Part of the suggestion.

Name	Type	Description
info	string	The type of the suggestion.
suggestion*required	string	The suggested continuation of the query.
synopsis	string	The synopsis of the suggestion.
type*required	"SPACE" | "LINEBREAK" | "INDENT" | "PIPE" | "DOT" | "COLON" | "COMMA" | "ASSIGNMENT" | "BRACE_OPEN" | "BRACE_CLOSE" | "BRACKET_OPEN" | "BRACKET_CLOSE" | "PARENTHESIS_OPEN" | "PARENTHESIS_CLOSE" | "QUOTE" | "SINGLE_QUOTE" | "SLASH" | "BOOLEAN_TRUE" | "BOOLEAN_FALSE" | "NULL" | "COMMAND_NAME" | "PARAMETER_KEY" | "PARAMETER_VALUE_SCOPE" | "FUNCTION_NAME" | "TIMESERIES_AGGREGATION" | "TIMESERIES_AGGREGATION_EXPRESSION" | "OPERATOR" | "TRAVERSAL_OPERATOR" | "TRAVERSAL_RELATION_NAME" | "TRAVERSAL_HOP_COUNT" | "SIMPLE_IDENTIFIER" | "DATA_OBJECT" | "NUMBER" | "STRING" | "TIME_UNIT" | "TIMESTAMP_VALUE" | "METRIC_KEY" | "VARIABLE" | "END_COMMENT" | "UID_VALUE" | "PARSE_PATTERN" | "FIELD_PATTERN" | "ENTITY_SELECTOR_PART" | "FIELD_MODIFIER" | "ENTITY_TYPE" | "ENTITY_ATTRIBUTE" | "SMARTSCAPE_ID_VALUE"	The type of the autocomplete token.

DQLAlternativeNode

The DQL node that has alternatives.

Name	Type	Description
alternatives	object	The different alternatives.
isOptional*required	boolean	True if the node is optional.
nodeType*required	"TERMINAL" | "CONTAINER" | "ALTERNATIVE"	The type of the node.
tokenPosition	TokenPosition	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.

DQLContainerNode

The DQL node that contains other nodes.

Name	Type	Description
children	Array<DQLNode>	The list of children nodes.
isOptional*required	boolean	True if the node is optional.
nodeType*required	"TERMINAL" | "CONTAINER" | "ALTERNATIVE"	The type of the node.
tokenPosition	TokenPosition	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.
type	"QUERY" | "EXECUTION_BLOCK" | "COMMAND" | "COMMAND_SEPARATOR" | "PARAMETER_WITH_KEY" | "GROUP" | "PARAMETERS" | "PARAMETER_NAMING" | "PARAMETER_ASSIGNMENT" | "PARAMETER_SEPARATOR" | "FUNCTION" | "FUNCTION_PART" | "EXPRESSION" | "IDENTIFIER" | "SOURCE_ID" | "DURATION" | "TIMESTAMP" | "TIMEFRAME" | "TRAVERSAL_PATH" | "TRAVERSAL_STEP"	The type of the node.

DQLNode

General Node in the DQL query.

Name	Type	Description
isOptional*required	boolean	True if the node is optional.
nodeType*required	"TERMINAL" | "CONTAINER" | "ALTERNATIVE"	The type of the node.
tokenPosition	TokenPosition	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.

DQLTerminalNode

Node that represents single token.

Name	Type	Description
canonicalString	string	Canonical form.
isMandatoryOnUserOrder	boolean	For optional items only: whether this node becomes mandatory when user order is used. True only for some optional 'ghost braces'
isOptional*required	boolean	True if the node is optional.
nodeType*required	"TERMINAL" | "CONTAINER" | "ALTERNATIVE"	The type of the node.
tokenPosition	TokenPosition	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.
type	"SPACE" | "LINEBREAK" | "INDENT" | "PIPE" | "DOT" | "COLON" | "COMMA" | "ASSIGNMENT" | "BRACE_OPEN" | "BRACE_CLOSE" | "BRACKET_OPEN" | "BRACKET_CLOSE" | "PARENTHESIS_OPEN" | "PARENTHESIS_CLOSE" | "QUOTE" | "SINGLE_QUOTE" | "SLASH" | "BOOLEAN_TRUE" | "BOOLEAN_FALSE" | "NULL" | "COMMAND_NAME" | "PARAMETER_KEY" | "PARAMETER_VALUE_SCOPE" | "FUNCTION_NAME" | "TIMESERIES_AGGREGATION" | "TIMESERIES_AGGREGATION_EXPRESSION" | "OPERATOR" | "TRAVERSAL_OPERATOR" | "TRAVERSAL_RELATION_NAME" | "TRAVERSAL_HOP_COUNT" | "SIMPLE_IDENTIFIER" | "DATA_OBJECT" | "NUMBER" | "STRING" | "TIME_UNIT" | "TIMESTAMP_VALUE" | "METRIC_KEY" | "VARIABLE" | "END_COMMENT" | "UID_VALUE" | "PARSE_PATTERN" | "FIELD_PATTERN" | "ENTITY_SELECTOR_PART" | "FIELD_MODIFIER" | "ENTITY_TYPE" | "ENTITY_ATTRIBUTE" | "SMARTSCAPE_ID_VALUE"	The type of the autocomplete token.

ErrorEnvelope

An 'envelope' error object that has the mandatory error object.

Name	Type	Description
error*required	ErrorResponse	The response for error state

ErrorResponse

The response for error state

Name	Type	Description
code*required	number	Error code, which normally matches the HTTP error code.
details	ErrorResponseDetails	Detailed information about the error.
message*required	string	A short, clear error message without details

ErrorResponseDetails

Detailed information about the error.

Name	Type	Description
arguments	Array<string>	The arguments for the message format.
constraintViolations	Array<ErrorResponseDetailsConstraintViolationsItem>	Information about an input parameter that violated some validation rule of the service API.
errorMessage	string	Complete error message.
errorMessageFormat	string	The message format of the error message, string.format based.
errorMessageFormatSpecifierTypes	Array<string>	The corresponding DQL format specifier types for each format specifier used in the error message format.
errorType	string	The error type, e.g. COMMAND_NAME_MISSING
exceptionType	string	The exception type.
missingPermissions	Array<string>	List of missing IAM permissions necessary to successfully execute the request.
missingScopes	Array<string>	List of missing IAM scopes necessary to successfully execute the request.
queryId	string
queryString	string	Submitted query string.
syntaxErrorPosition	TokenPosition	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.

ErrorResponseDetailsConstraintViolationsItem

Name	Type	Description
message*required	string	Message describing the error.
parameterDescriptor	string	Describes the violating parameter.
parameterLocation	string	Describes the general location of the violating parameter.

ExecuteRequest

Name	Type	Description
defaultSamplingRatio	number	In case not specified in the DQL string, the sampling ratio defined here is applied. Note that this is only applicable to log queries.
defaultScanLimitGbytes	number	Limit in gigabytes for the amount data that will be scanned during read.
defaultTimeframeEnd	string	The query timeframe 'end' timestamp in ISO-8601 or RFC3339 format. If the timeframe 'start' parameter is missing, the whole timeframe is ignored. Note that if a timeframe is specified within the query string (query) then it has precedence over this query request parameter.
defaultTimeframeStart	string	The query timeframe 'start' timestamp in ISO-8601 or RFC3339 format. If the timeframe 'end' parameter is missing, the whole timeframe is ignored. Note that if a timeframe is specified within the query string (query) then it has precedence over this query request parameter.
enablePreview	boolean	Request preview results. If a preview is available within the requestTimeoutMilliseconds, then it will be returned as part of the response.
fetchTimeoutSeconds	number	The query will stop reading data after reaching the fetch-timeout. The query execution will continue, providing a partial result based on the read data.
filterSegments	FilterSegments	Represents a collection of filter segments.
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'.
maxResultBytes	number	The maximum number of result bytes that this query will return.
maxResultRecords	number	The maximum number of result records that this query will return.
query*required	string	The full query string.
queryOptions	QueryOptions	Query options enhance query functionality for Dynatrace internal services.
requestTimeoutMilliseconds	number	The time a client is willing to wait for the query result. In case the query finishes within the specified timeout, the query result is returned. Otherwise, the requestToken is returned, allowing polling for the result.
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'

FieldType

The possible type of a field in DQL.

Name	Type
type*required	"string" | "boolean" | "undefined" | "binary" | "double" | "long" | "timestamp" | "timeframe" | "duration" | "ip_address" | "geo_point" | "array" | "record" | "uid" | "smartscape_id"
types	Array<RangedFieldTypes>

FilterSegment

A filter segment is identified by an ID. Each segment includes a list of variable definitions.

Name	Type
id*required	string
variables	Array<FilterSegmentVariableDefinition>

FilterSegmentVariableDefinition

Defines a variable with a name and a list of values.

Name	Type
name*required	string
values*required	Array<string>

FilterSegments

Represents a collection of filter segments.

type: Array<FilterSegment>

GeoPoint

DQL data type representing a geolocation point.

Name	Type	Description
latitude*required	number	The coordinate that specifies the north-south position of a point on the surface of the earth.
longitude*required	number	The coordinate that specifies the east-west position of a point on the surface of the earth.

GrailMetadata

Collects various bits of metadata information.

Name	Type	Description
analysisTimeframe	Timeframe	DQL data type timeframe.
canonicalQuery	string	The canonical form of the query. It has normalized spaces and canonical constructs.
dqlVersion	string	The version of DQL that was used to process the query request.
executionTimeMilliseconds	number	The time it took to execute the query.
locale	string	Effective locale for the query.
notifications	Array<MetadataNotification>	Collected messages during the execution of the query.
query	string	The submitted query.
queryId	string	The id of the query
sampled	boolean	True if sampling was used for at least one segment.
scannedBytes	number	Number of scanned bytes during the query execution.
scannedDataPoints	number
scannedRecords	number	Number of scanned records during the query execution.
timezone	string	Effective timezone for the query.

Metadata

Collects various bits of metadata information.

Name	Type	Description
grail	GrailMetadata	Collects various bits of metadata information.
metrics	Array<MetricMetadata>

MetadataNotification

The message that provides additional information about the execution of the query.

Name	Type	Description
arguments	Array<string>	The arguments for the message format.
message	string	The complete message of the notification.
messageFormat	string	The message format of the notification, string.format based
messageFormatSpecifierTypes	Array<string>	The corresponding DQL format specifier types for each format specifier used in the error message format.
notificationType	string	The notification type, e.g. LIMIT_ADDED.
severity	string	The severity of the notification, currently: INFO, WARN, ERROR.
syntaxPosition	TokenPosition	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.

MetricMetadata

An object that defines additional metric metadata.

Name	Type	Description
description	string	The description of the metadata.
displayName	string	The display name of the metadata.
fieldName	string	The name of the associated field used in the query.
metric.key	string	The metric key.
rate	string	The specified rate normalization parameter.
rollup	string	Metadata about the rollup type.
shifted	boolean	Indicates if the shifted parameter was used.
unit	string	The unit used.

ParseRequest

Name	Type	Description
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'.
query*required	string	The full query string.
queryOptions	QueryOptions	Query options enhance query functionality for Dynatrace internal services.
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'

PositionInfo

The exact position in the query string.

Name	Type	Description
column*required	number	Query position column zero based index.
index*required	number	Query position index.
line*required	number	Query position line zero based index.

QueryOptions

Query options enhance query functionality for Dynatrace internal services.

type: Record<string, string | undefined>

QueryPollResponse

The response of GET query:execute call.

Name	Type	Description
progress	number	The progress of the query from 0 to 100.
result	QueryResult	The result of the DQL query.
state*required	"NOT_STARTED" | "RUNNING" | "SUCCEEDED" | "RESULT_GONE" | "CANCELLED" | "FAILED"	Possible state of the query.
ttlSeconds	number	Time to live in seconds.

QueryResult

The result of the DQL query.

Name	Type	Description
metadata*required	Metadata	Collects various bits of metadata information.
records*required	Array<null | ResultRecord>	List of records containing the result fields data.
types*required	Array<RangedFieldTypes>	The data types for the result records.

QueryStartResponse

The response when starting a query.

Name	Type	Description
progress	number	The progress of the query from 0 to 100.
requestToken	string	The token returned by the POST query:execute call.
result	QueryResult	The result of the DQL query.
state*required	"NOT_STARTED" | "RUNNING" | "SUCCEEDED" | "RESULT_GONE" | "CANCELLED" | "FAILED"	Possible state of the query.
ttlSeconds	number	Time to live in seconds.

RangedFieldTypes

The field type in range.

Name	Type	Description
indexRange	Array<number>	The range of elements at use this type in arrays (null for records).
mappings*required	RangedFieldTypesMappings	The mapping between the field name and data type.

RangedFieldTypesMappings

The mapping between the field name and data type.

type: Record<string, FieldType | undefined>

ResultRecord

Single record that contains the result fields.

type: Record<string, ResultRecordValue | null | undefined>

Timeframe

DQL data type timeframe.

Name	Type	Description
end	Date	The end time of the timeframe.
start	Date	The start time of the timeframe.

TokenPosition

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.

Name	Type	Description
end*required	PositionInfo	The exact position in the query string.
start*required	PositionInfo	The exact position in the query string.

VerifyRequest

Name	Type	Description
generateCanonicalQuery	boolean	default: false
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'.
query*required	string	The full query string.
queryOptions	QueryOptions	Query options enhance query functionality for Dynatrace internal services.
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'

VerifyResponse

Verify response.

Name	Type	Description
canonicalQuery	string
notifications	Array<MetadataNotification>	The notifications related to the supplied DQL query string.
valid*required	boolean	True if the supplied DQL query string is valid.

Enums

DQLNodeNodeType

The type of the node.

Enum keys

Alternative | Container | Terminal

FieldTypeType

Enum keys

Array | Binary | Boolean | Double | Duration | GeoPoint | IpAddress | Long | Record | SmartscapeId | String | Timeframe | Timestamp | Uid | Undefined

QueryState

Possible state of the query.

Enum keys

Cancelled | Failed | NotStarted | ResultGone | Running | Succeeded

TokenType

The type of the autocomplete token.

Enum keys

Assignment | BooleanFalse | BooleanTrue | BraceClose | BraceOpen | BracketClose | BracketOpen | Colon | Comma | CommandName | DataObject | Dot | EndComment | EntityAttribute | EntitySelectorPart | EntityType | FieldModifier | FieldPattern | FunctionName | Indent | Linebreak | MetricKey | Null | Number | Operator | ParameterKey | ParameterValueScope | ParenthesisClose | ParenthesisOpen | ParsePattern | Pipe | Quote | SimpleIdentifier | SingleQuote | Slash | SmartscapeIdValue | Space | String | TimeUnit | TimeseriesAggregation | TimeseriesAggregationExpression | TimestampValue | TraversalHopCount | TraversalOperator | TraversalRelationName | UidValue | Variable