数据平面契约 - 技术规范
状态：草稿 版本：0.1
文档目标
详细定义从数据源返回的数据的常见查询响应模式。这将改善功能和数据源开发者的体验。这也将通过更高的可靠性和质量来改善用户体验，从而将更多开发时间投入到改善体验中。
种类和格式
存在逻辑上的种类（例如时间序列数据、数值型、直方图等），以及一种种类可以具有的格式。
在本框架中，数据类型定义或声明包含种类和格式。例如，“TimeSeriesWide”是：种类：“时间序列”，格式：“Wide”。
基于维度集合的种类
在数据类型（种类+格式）中，可以存在多个项目，这些数据项目是通过唯一标识来区分的。这形成了一个集合的数据项目。例如，在数值型种类中，可以存在一组数字，或者，在时间序列种类中，可以存在一组时间序列 :-)。
集合中的每个数据项目都通过其名称和维度来唯一标识。
维度是数据的方面（例如“位置”或“主机”），它们具有相应的数值。例如，{"host"="a", "location"="new york"}。
在数据帧中，维度位于字段的 Labels 属性或字符串字段中。
所有基于维度集合的种类共享的属性
- 当存在多个具有相同名称的项目时，它们应该具有不同的维度（例如标签），以唯一标识每个项目1.
- 项目名称应该出现在每个值（数值型或布尔型）字段的 Name 属性中，标签也应该出现2
- 响应中可以包含不同的项目名称（注意：SSE 目前不支持此功能）
剩余数据
数据被编码到数据帧中，因此所有类型都实现为数据帧数组。
数据帧中可能存在不属于数据类型数据的额外数据。此额外数据是剩余数据。读者选择如何处理此数据是开放的。但是，基于此契约的库必须清楚地区分剩余数据和属于该类型的数据。
哪些数据成为剩余数据取决于数据类型并由数据类型指定。一般来说，它可以是额外的帧和/或特定字段类型的额外字段。
无效数据
虽然存在剩余数据，但仍然存在读者应该报错的情况。这种情况发生在数据类型说明符存在于帧中，但未遵循关于该类型的规则时。
“无数据”和空
当响应缺少数据且没有错误时，存在两种命名情况。
“无数据”是指当我们从数据源检索到响应，但该响应没有数据项目时。该形式的类型的编码是一个数据帧，其中包含数据类型声明和零长度的字段（null 或 []）。这是指整个集合没有项目的情况。无数据也可以是没有任何帧（且没有错误）的响应。但是，在这种情况下，类型和其他元数据无法返回——因此，单帧形式通常更可取。
我们从数据源检索到一个或多个数据项目，但某个项目没有值，则该项目被称为“空值”。在这种情况下，所需的数据帧字段应该仍然存在（但字段本身都没有值）。
错误响应
错误通过 DataResponse 上的 Error 和 Status 属性从数据帧外部返回。
当 DataResponse 返回错误时，可能还会包含一个没有字段的单帧。如果存在错误，则不应将其视为“无数据”。此帧包含在内，以便元数据（特别是帧的 ExecutedQueryString）能够与错误一起返回给调用者。
注意：在后端插件中，错误可以从 DataQueryHandler 调用中返回。此功能仅应在整个请求（所有查询）都将失败时使用。
多数据类型响应
响应在单个结果中包含多个数据类型（在 RefID 内）的情况存在，但目前不在本规范的版本范围内。
但是，需要能够支持此情况。目前，建议使用以下逻辑
- 每个数据类型在响应中应仅使用一种格式。例如：可以存在 TimeSeriesWide 和 NumericLong，但不应存在 TimeSeriesWide 和 TimeSeriesLong。
- 类型之间的边界是从共享相同数据类型的相邻帧（在帧数组内）派生的。
- 如果读者没有选择加入多类型响应，则应该能够获得第一个与读者正在查找的内容匹配的数据类型。
版本控制
本契约的目标是尽可能稳定。当达到1.0时，更改应该仅限于增强功能，直到2.0版本，这通常应该在数据类型版本中避免。
契约版本控制
契约版本仅用于影响契约总体概念（例如错误处理或多数据类型响应）的概念。
添加新数据类型或更改数据类型不会影响契约版本。
数据类型版本
每个单独的数据类型都会获得主/次版本形式（x.x）。该版本位于 Frame.Meta.TypeVersion 属性中。
- 版本
0.0表示数据类型要么是契约之前的，要么处于非常早期的开发阶段。 - 版本
0.x表示数据类型在契约中已定义明确，但可能会根据针对更广泛使用情况的学习内容而发生更改。 - 版本
1.0应该是一个稳定的数据类型，并且应该与之前的版本没有区别。 - 超出
1.0的次要版本更改必须与数据读取器实现向后兼容。它们还必须与其他1.x版本向前兼容，以供读取器使用（但不支持增强功能）。
要添加的注意事项/待办事项
- 元数据（帧和字段）
- 如果声明了类型/模式，是否需要支持以下情况：出于某种原因，可以将类型视为多种种类？
- 到目前为止，顺序被忽略（例如，TimeSeriesWide 中值字段的顺序或 TimeSeriesMulti 中帧的顺序）。需要决定顺序是否有任何语法意义，如果有，那么是什么，并将其视为在格式之间转换的属性。
- 注意：关于顺序的问题 https://github.com/grafana/grafana-plugin-sdk-go/issues/366，目前尚不清楚是否是显示问题。