跳转到主要内容

数据平面合约 - 技术规范

状态：草案 版本：0.1

文档目标​

详细定义了从数据源返回的常见查询响应模式。这提高了功能和数据源开发者的体验。这还将通过更高的可靠性和质量来提高用户体验，从而将更多的时间投入到提高体验上。

种类和格式​

存在逻辑上的种类（如时间序列数据、数值型、直方图等），以及种类可以采取的格式。

本框架中的数据类型定义或声明包括一个种类和一个格式。例如，“TimeSeriesWide”是：种类：“时间序列”，格式：“宽”。

基于维数集的种类​

在一个数据类型（种类+格式）中，可以有多个唯一标识的数据项。这形成了一个数据项的集合。例如，在数值型种类中，可以有一个数字的集合，或者，在时间序列种类中，可以有一个时间序列的集合 :-)。

集合中的每个数据项都通过其名称和维度唯一标识。

维度是数据的方面（如“位置”或“主机”），具有相应的值。例如，{"host"="a", "location"="new york"}。

在数据框中，维度可以是字段标签属性中的字段，也可以是字符串字段。

所有基于维数集的种类共享的属性​

  • 当存在多个具有相同名称的项时，它们应该有不同（例如标签）的维度，以唯一标识每个项1。
  • 项目名称应出现在每个值（数值型或布尔型）字段的名称属性中，以及任何标签2中。
  • 响应可以具有响应中的不同项目名称（注意：SSE 目前无法处理此情况）

其余数据​

数据被编码到数据框中，因此所有类型都作为数据帧数组实现。

数据框中可能包含不属于数据类型的数据。这些额外数据被称为余数数据。读者如何处理这些数据是开放的。然而，基于此合约的库必须明确区分余数数据与类型中的数据。

哪些数据成为余数数据取决于数据类型，并在数据类型中指定。通常，这可以是指定的字段类型的额外数据框和/或额外字段。

无效数据​

尽管存在余数数据，但在某些情况下，读者仍应报错。这种情况发生在数据类型指定器存在于数据框上，但未遵循该类型的规则。

"无数据"和空​

当响应缺乏数据且没有错误时，存在两种命名情况。

"无数据"是指我们从数据源检索响应但没有数据项的情况。该类型的编码形式是一个单帧，包含数据类型声明和字段长度的零（null或[]）。这是整个集合没有项的情况。无数据也可能是没有数据框（没有错误）的响应。然而，在这种情况下，无法返回类型和其他元数据——因此，通常更倾向于单帧形式。

我们从数据源检索一个或多个数据项，但一个项没有值，该项被称为"空值"。在这种情况下，所需的DataFrame字段仍然存在（但字段本身没有值）。

错误响应​

使用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中框架的顺序）。需要决定顺序是否有任何符号意义，如果有，是什么，并考虑它是转换格式时的属性。

注释​

  1. 从理论上讲，它们仍然可以用于类似可视化的事物，因为字段在框架中具有数字顺序，但这不会与SSE/alerting等事物一起工作。↩
  2. 使用字段名称保持与TimeSeriesMulti格式（与使用框架名称）的命名一致性。↩