A Dynatrace notebook is stored as a JSON document. Understanding the structure helps you create and modify notebooks using the API.
A notebook document consists of version, defaultTimeframe, defaultSegments, and sections. Sections are ordered sequentially and stack vertically in the order they appear in the array. Each section is either a Markdown block or a DQL query with its own visualization and query settings.
{"version": "7","defaultTimeframe": { "from": "now()-2h", "to": "now()" },"defaultSegments": [],"sections": []}
| Property | Type | Description |
|---|---|---|
| string | Schema version. Always |
| object | Default timeframe applied when opening the notebook. Has |
| array | Default segment filters applied to all DQL sections. Typically an empty array. |
| array | Ordered array of section definitions. See Sections. |
Sections are stored in sections as an ordered array. The order in the array is the display order in the notebook. There are three section types: markdown, dql, and function.
Sections stack vertically in array order.
A markdown section displays static text content formatted with Markdown.
{"id": "97eae716-f594-4d8a-90ea-bcc00d1c0db4","type": "markdown","markdown": "# Title\n\nSection content."}
| Property | Required | Description |
|---|---|---|
| Yes | Unique identifier for the section. Use a UUID. |
| Yes | Always |
| Yes | Markdown content string. |
| No | Show or hide the section title. |
A DQL section runs a query and displays the results as a visualization. Query and visualization properties are nested inside a state object.
{"id": "5151a253-30a3-4e54-95d4-816e48c7e08f","type": "dql","title": "Query Section","height": 293,"showInput": true,"filterSegments": [],"drilldownPath": [],"previousFilterSegments": [],"state": {"input": {"value": "fetch logs | summarize count()","timeframe": { "from": "now()-2h", "to": "now()" }},"visualization": "table","visualizationSettings": {"autoSelectVisualization": true,"chartSettings": {}},"querySettings": {"maxResultRecords": 1000,"defaultScanLimitGbytes": 500,"maxResultMegaBytes": 1,"defaultSamplingRatio": 10,"enableSampling": false}}}
Section-level properties:
| Property | Required | Description |
|---|---|---|
| Yes | Unique identifier for the section. Use a UUID. |
| Yes | Always |
| No | Displayed above the section. |
| No | Section height in pixels. Defaults to approximately 400. |
| No | Show or hide the query editor. Defaults to |
| No | Show or hide the section title. |
| No | Segment filters applied to this section. Overrides |
| No | Active drilldown path for the section. Managed by the UI. |
| No | Previous segment filter state used for drilldown navigation. Managed by the UI. |
state properties:
| Property | Required | Description |
|---|---|---|
| Yes | DQL query string. |
| No | Section-specific timeframe override. Object with |
| No | Visualization type. See Visualization types. Required when |
| Yes | Visualization settings object. Set |
| Yes | Query execution settings object. |
A function section runs a JavaScript function in the Dynatrace Functions runtime and optionally displays the result as a visualization.
{"id": "54beb22f-3ef2-4809-93aa-06a3cab3f702","type": "function","title": "Users fetched from API","showTitle": true,"showInput": true,"drilldownPath": [],"state": {"input": {"value": "export default async function () {\n const res = await fetch('https://example.com/api/data');\n return res.json();\n}"},"visualization": "table","visualizationSettings": {"autoSelectVisualization": true}}}
| Property | Required | Description |
|---|---|---|
| Yes | Unique identifier. Use a UUID. |
| Yes | Always |
| No | Displayed above the section. |
| No | Show or hide the code editor in the section. |
| Yes | JavaScript source code as a string. The default export is called when the section runs. |
| No | Visualization type for the function output. See Visualization types. |
| No | Visualization configuration object. |
Notebooks support the following visualization types for DQL sections:
davis, table, histogram, honeycomb, singleValue, donutChart, pieChart, categoricalBarChart, dotMap, choropleth, bubbleMap, connectionMap, meterBar, gauge, heatmap, lineChart, areaChart, barChart, bandChart, scatterplot, raw, recordView, treemap
Setting "autoSelectVisualization": true in state.visualizationSettings lets Dynatrace choose the most appropriate visualization for the query result automatically. Use this unless you need a specific type.
For field type requirements per visualization type, see Visualization types.