Chart Block 配置说明¶

Chart Block 用于在 Markdown 笔记中插入可实时渲染的图表。与静态图片不同，Chart Block 仅需配置图表类型、查询语句和展示参数，预览时由平台图表组件自动执行查询并渲染结果。

基本写法¶

在 Markdown 中使用 fenced code block，语言标记固定写 chart：

version: chart/v1
type: sequence
name: 服务 P99 延迟
time:
  range: 1h
queries:
  - code: A
    qtype: dql
    namespace: metric
    q: 'M::`service_latency`:(p99(`duration`)) { service = "checkout" }'
settings:
  chartType: line
  legendPostion: bottom
  isTimeInterval: true
  xAxisShowType: time
  mainMeasurementQueryCode: A
  unitType: custom
  globalUnit:
    - custom
    - ms

支持的图表类型¶

图表	`type`	说明
时序折线图	`sequence`	展示随时间变化的趋势，常用于指标、日志数量、延迟、错误率等
概览图	`singlestat`	展示一个核心数值，可用于总量、峰值、平均值等
表格图	`table`	展示明细或聚合后的多列数据
柱状图	`bar`	展示分类对比，例如按来源、状态码、服务分组统计
直方图	`histogram`	展示分布情况，例如耗时分布、bucket 分布
饼图	`pie`	展示占比，例如错误类型占比、来源占比

通用字段¶

字段	是否必填	说明
`version`	是	固定为 `chart/v1`
`type`	是	图表类型，只能使用当前支持的 6 种类型
`name`	是	图表标题，渲染在图表卡片头部
`description`	否	图表说明，目前主要用于配置可读性
`time.range`	否	查询时间范围，例如 `15m`、`1h`、`1d`；不填时默认按 `1h` 预览
`queries`	是	查询列表，必须是非空数组
`settings`	否	图表展示配置，不同图表类型可使用不同字段

注意

如果 Chart Block 前一行 Markdown 标题与 name 完全一致，预览时将自动隐藏外部标题，避免标题重复显示。

queries 字段¶

queries 为数组，每个查询项表示一条图表查询。

字段	是否必填	说明
`code`	是	查询编号，推荐使用 `A`、`B`、`C`
`qtype`	是	查询语言，支持 `dql`、`promql`
`namespace`	否	查询命名空间，DQL 常用：`metric`、`log`、`object`、`event`、`tracing`、`rum`
`q`	是	查询语句
`name`	否	查询展示名；不填时使用 `code`

建议将 q 用单引号包裹，以避免 YAML 对特殊字符的解析异常：

q: 'L::re(`.*`):(count(`*`)) BY `source`'

若查询语句本身包含单引号，需在 YAML 单引号字符串中将其写为两个单引号：

q: 'L::re(`.*`):(count(`*`)) { `service` = ''checkout'' }'

settings 通用配置¶

settings 会透传到平台现有图表组件中。常用字段如下：

字段	说明
`chartType`	图表内部形态，例如 `line`、`areaLine`、`bar`、`pie`、`doughnut`、`histogram`
`legendPostion`	图例位置，常用 `bottom`、`right`、`hide`。注意字段名是 `legendPostion`
`precision`	小数精度，建议写字符串，例如 `"2"`
`isTimeInterval`	是否按时间序列展示，时序图通常为 `true`，分组类图通常为 `false`
`xAxisShowType`	X 轴展示方式，时序常用 `time`，分类常用 `groupBy`
`mainMeasurementQueryCode`	主查询编号，常用 `A`
`mainMeasurementSort`	主指标排序，常用 `top`、`bottom`
`mainMeasurementLimit`	展示数量上限，例如 `10`、`20`
`unitType`	单位类型，常用 `custom`
`globalUnit`	全局单位，例如 `['custom', 'ms']`、`['custom', 'count']`
`showLine`	概览图是否展示趋势线
`openStack`	是否开启堆叠
`stackType`	堆叠类型
`enableCombine`	饼图是否合并小占比项
`combine`	饼图合并规则
`promqlType`	PromQL 查询类型，常用 `rangeQuery`

各图表示例¶

时序折线图 sequence¶

适合展示某个指标随时间变化的趋势。

version: chart/v1
type: sequence
name: 服务 P99 延迟
time:
  range: 1h
queries:
  - code: A
    qtype: dql
    namespace: metric
    q: 'M::`service_latency`:(p99(`duration`)) { service = "checkout" }'
settings:
  chartType: line
  legendPostion: bottom
  isTimeInterval: true
  xAxisShowType: time
  mainMeasurementQueryCode: A
  unitType: custom
  globalUnit:
    - custom
    - ms

概览图 singlestat¶

适合展示一个核心指标值，例如错误总数、峰值、平均值。

version: chart/v1
type: singlestat
name: 近 1 小时错误数
time:
  range: 1h
queries:
  - code: A
    qtype: dql
    namespace: log
    q: 'L::re(`.*`):(count(`*`)) { status = "error" }'
settings:
  precision: "0"
  isTimeInterval: false
  showLine: false
  unitType: custom
  globalUnit:
    - custom
    - count

表格图 table¶

适合展示 Top 列表、明细列表或聚合结果。

version: chart/v1
type: table
name: Top 慢接口
time:
  range: 1h
queries:
  - code: A
    qtype: dql
    namespace: log
    q: 'L::re(`.*`):(`time`, `source`, `message`) LIMIT 20'
settings:
  queryMode: toGroupColumn
  showColumns:
    - time
    - source
    - message
  mainMeasurementQueryCode: A
  mainMeasurementSort: top
  mainMeasurementLimit: 20

柱状图 bar¶

适合展示分类对比，例如错误来源分布、状态码分布。

version: chart/v1
type: bar
name: 日志来源分布
time:
  range: 1h
queries:
  - code: A
    qtype: dql
    namespace: log
    q: 'L::re(`.*`):(count(`*`)) BY `source`'
settings:
  direction: vertical
  xAxisShowType: groupBy
  isTimeInterval: false
  showTopSize: false
  aliasVersion: 2
  mainMeasurementLimit: 10
  unitType: custom
  globalUnit:
    - custom
    - count

直方图 histogram¶

适合展示分布。PromQL 场景可用于 bucket/histogram 查询。

version: chart/v1
type: histogram
name: 请求耗时分布
time:
  range: 1h
queries:
  - code: A
    qtype: promql
    q: 'histogram_quantile(0.95, sum(rate(http_request_duration_seconds_bucket[5m])) by (le))'
settings:
  chartType: histogram
  direction: vertical
  legendPostion: bottom
  isTimeInterval: false
  promqlType: rangeQuery
  unitType: custom
  globalUnit:
    - custom
    - ms

饼图 pie¶

适合展示占比，例如错误类型占比、来源占比。

version: chart/v1
type: pie
name: 错误来源占比
time:
  range: 1h
queries:
  - code: A
    qtype: dql
    namespace: log
    q: 'L::re(`.*`):(count(`*`)) { status = "error" } BY `source`'
settings:
  chartType: doughnut
  legendPostion: right
  mainMeasurementQueryCode: A
  mainMeasurementSort: top
  mainMeasurementLimit: 8
  enableCombine: true
  combine:
    percent: "5"
    operator: lt
  unitType: custom
  globalUnit:
    - custom
    - count

字段废弃说明¶

chart/v1 不再使用以下旧字段名，新配置请使用对应替代字段：

废弃字段	替代字段
`title`	`name`
`view`	`settings`
`queries[].id`	`queries[].code`
`queries[].lang`	`queries[].qtype`
`queries[].datasource`	`queries[].namespace`

错误示例：

version: chart/v1
type: sequence
title: 服务延迟
queries:
  - id: q1
    lang: dql
    datasource: metric
    q: 'M::x'
view:
  chartType: line

正确示例：

version: chart/v1
type: sequence
name: 服务延迟
queries:
  - code: A
    qtype: dql
    namespace: metric
    q: 'M::x'
settings:
  chartType: line

配置校验规则¶

Chart Block 在渲染前会进行以下校验：

version 必须是 chart/v1。
type 必须是 sequence、singlestat、table、bar、histogram、pie 之一。
name 不能为空。
queries 必须是非空数组。
每个 query 必须包含 code、qtype、q。
qtype 只能是 dql 或 promql。
YAML 必须能被正确解析。

校验失败时，预览区将展示错误卡片及原始配置内容，不影响笔记中其他 Markdown 内容的正常显示。

配置建议¶

Chart Block 仅用于配置查询和展示参数，请勿在其中写入静态数据，例如 data、items、series。
查询语句建议来自实际可执行的查询，确保渲染结果准确。
如需插入多张图表，可连续编写多个 chart block，每个 block 对应一张图表。
如仅需文字说明，直接使用 Markdown 编写即可，无需使用 Chart Block。
若图表渲染结果为空，建议优先检查时间范围、查询条件、命名空间及查询语句是否正确。

旧 chart_json 兼容说明¶

系统仍可解析旧版 chart_json fenced block，以兼容历史笔记数据。新建笔记及 AI 生成内容请统一使用 chart/v1。