Просмотр кода страницы Структура документа Ключ-АСТРОМ — Блокноты


= Структура документа Ключ-АСТРОМ — Блокноты =
Блокнот Ключ-АСТРОМ хранится как документ '''JSON'''. Понимание структуры помогает создавать и изменять блокноты через '''API'''.

== Обзор ==
Документ блокнота состоит из <code>version</code>, <code>defaultTimeframe</code>, <code>defaultSegments</code> и <code>sections</code>. Разделы упорядочены последовательно и располагаются вертикально в том порядке, в котором они идут в массиве. Каждый раздел — это либо блок Markdown, либо запрос '''DQL''' с собственными настройками визуализации и запроса.

== Структура верхнего уровня ==
<pre>{
  "version": "7",
  "defaultTimeframe": { "from": "now()-2h", "to": "now()" },
  "defaultSegments": [],
  "sections": []
}</pre>
{| class="wikitable"
!Свойство
!Тип
!Описание
|-
|<code>version</code>
|string
|Версия схемы. Всегда <code>"7"</code>. Примечание: это строка, в отличие от версии дашборда, которая является числом.
|-
|<code>defaultTimeframe</code>
|object
|Временной диапазон по умолчанию, применяемый при открытии блокнота. Имеет строковые свойства <code>from</code> и <code>to</code>, использующие выражения времени '''DQL''', такие как <code>"now()-2h"</code>. По умолчанию — последние 2 часа.
|-
|<code>defaultSegments</code>
|array
|Фильтры сегментов по умолчанию, применяемые ко всем разделам '''DQL'''. Обычно пустой массив.
|-
|<code>sections</code>
|array
|Упорядоченный массив определений разделов. См. '''Разделы'''.
|}

== Разделы ==
Разделы хранятся в <code>sections</code> как упорядоченный массив. Порядок в массиве — это порядок отображения в блокноте. Существует три типа разделов: <code>markdown</code>, <code>dql</code> и <code>function</code>.

Разделы располагаются вертикально в порядке массива.

=== Раздел Markdown ===
Раздел Markdown отображает статическое текстовое содержимое, отформатированное с помощью Markdown.<pre>{
  "id": "97eae716-f594-4d8a-90ea-bcc00d1c0db4",
  "type": "markdown",
  "markdown": "# Title\n\nSection content."
}</pre>
{| class="wikitable"
!Свойство
!Обязательно
!Описание
|-
|<code>id</code>
|Да
|Уникальный идентификатор раздела. Используйте '''UUID'''.
|-
|<code>type</code>
|Да
|Всегда <code>"markdown"</code>.
|-
|<code>markdown</code>
|Да
|Строка содержимого Markdown.
|-
|<code>showTitle</code>
|Нет
|Показывать или скрывать заголовок раздела.
|}

=== Раздел DQL ===
Раздел '''DQL''' выполняет запрос и отображает результаты в виде визуализации. Свойства запроса и визуализации вложены в объект <code>state</code>.<pre>{
  "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
    }
  }
}</pre>Свойства уровня раздела:
{| class="wikitable"
!Свойство
!Обязательно
!Описание
|-
|<code>id</code>
|Да
|Уникальный идентификатор раздела. Используйте '''UUID'''.
|-
|<code>type</code>
|Да
|Всегда <code>"dql"</code>.
|-
|<code>title</code>
|Нет
|Отображается над разделом.
|-
|<code>height</code>
|Нет
|Высота раздела в пикселях. По умолчанию — примерно 400.
|-
|<code>showInput</code>
|Нет
|Показывать или скрывать редактор запроса. По умолчанию <code>true</code>.
|-
|<code>showTitle</code>
|Нет
|Показывать или скрывать заголовок раздела.
|-
|<code>filterSegments</code>
|Нет
|Фильтры сегментов, применяемые к этому разделу. При установке переопределяет <code>defaultSegments</code>.
|-
|<code>drilldownPath</code>
|Нет
|Активный путь детализации для раздела. Управляется '''UI'''.
|-
|<code>previousFilterSegments</code>
|Нет
|Предыдущее состояние фильтра сегментов, используемое для навигации с детализацией. Управляется '''UI'''.
|}
Свойства <code>state</code>:
{| class="wikitable"
!Свойство
!Обязательно
!Описание
|-
|<code>state.input.value</code>
|Да
|Строка запроса '''DQL'''.
|-
|<code>state.input.timeframe</code>
|Нет
|Переопределение временного диапазона для конкретного раздела. Объект со свойствами <code>from</code> и <code>to</code>.
|-
|<code>state.visualization</code>
|Нет
|Тип визуализации. См. '''Типы визуализаций'''. Обязательно, когда <code>autoSelectVisualization</code> имеет значение <code>false</code>.
|-
|<code>state.visualizationSettings</code>
|Да
|Объект настроек визуализации. Установите <code>autoSelectVisualization: true</code>, чтобы Ключ-АСТРОМ автоматически выбирал лучший тип.
|-
|<code>state.querySettings</code>
|Да
|Объект настроек выполнения запроса.
|}

=== Раздел Function ===
Раздел Function выполняет функцию '''JavaScript''' в среде выполнения Astromkey Functions и при необходимости отображает результат в виде визуализации.<pre>{
  "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
    }
  }
}</pre>
{| class="wikitable"
!Свойство
!Обязательно
!Описание
|-
|<code>id</code>
|Да
|Уникальный идентификатор. Используйте '''UUID'''.
|-
|<code>type</code>
|Да
|Всегда <code>"function"</code>.
|-
|<code>title</code>
|Нет
|Отображается над разделом.
|-
|<code>showInput</code>
|Нет
|Показывать или скрывать редактор кода в разделе.
|-
|<code>state.input.value</code>
|Да
|Исходный код '''JavaScript''' в виде строки. Экспорт по умолчанию вызывается при запуске раздела.
|-
|<code>state.visualization</code>
|Нет
|Тип визуализации для вывода функции. См. '''Типы визуализаций'''.
|-
|<code>state.visualizationSettings</code>
|Нет
|Объект конфигурации визуализации.
|}

== Типы визуализаций ==
Блокноты поддерживают следующие типы визуализаций для разделов '''DQL''':

<code>davis</code>, <code>table</code>, <code>histogram</code>, <code>honeycomb</code>, <code>singleValue</code>, <code>donutChart</code>, <code>pieChart</code>, <code>categoricalBarChart</code>, <code>dotMap</code>, <code>choropleth</code>, <code>bubbleMap</code>, <code>connectionMap</code>, <code>meterBar</code>, <code>gauge</code>, <code>heatmap</code>, <code>lineChart</code>, <code>areaChart</code>, <code>barChart</code>, <code>bandChart</code>, <code>scatterplot</code>, <code>raw</code>, <code>recordView</code>, <code>treemap</code>

Установка <code>"autoSelectVisualization": true</code> в <code>state.visualizationSettings</code> позволяет Ключ-АСТРОМ автоматически выбирать наиболее подходящую визуализацию для результата запроса. Используйте это, если вам не нужен конкретный тип.

Требования к типам полей для каждого типа визуализации см. в разделе '''Типы визуализаций'''.