连接到 Microsoft SQL Server 数据来源

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

使用 Microsoft SQL Server（MSSQL）数据来源查询和可视化来自任何 Microsoft SQL Server 2005 或更高版本（包括 Microsoft Azure SQL 数据库）的数据。

添加数据来源

数据来源选项

最小时间间隔

$_interval $_interval_ms 变量的下限。建议设置以写入频率，例如，如果您的数据每分钟写入一次，则为 1m。也可以在控制面板的数据来源选项下覆盖/配置此选项。此值的格式必须为数字，后跟有效的时间标识符；例如，1m（1 分钟）或 30s（30 秒）。支持以下时间标识符。

数据库用户权限

以下示例代码显示了如何创建具有受限权限的特定 MSSQL 用户。

 CREATE USER grafanareader WITH PASSWORD 'password'
 GRANT SELECT ON dbo.YourTable3 TO grafanareader

确保用户没有从公有角色获得任何不需要的权限。

已知问题

如果您使用的是旧版本的 Microsoft SQL Server，比如 2008 和 2008R2，则可能需要禁用加密才能连接。如果可能，建议您使用最新的服务包，以获得最佳兼容性。

查询编辑器

在图形、Singlestat 或表面板编辑模式的“指标”选项卡中，您可以找到 MSSQL 查询编辑器。要进入编辑模式，请选择面板标题，然后选择“编辑”。您可以使用编辑器定义 SQL 查询以选择要可视化的数据。

宏

为了简化语法并允许动态部分（如日期范围筛选器），查询可包含宏。

在面板编辑模式下，查询编辑器有一个生成式 SQL 链接，并在查询运行后显示。选择之后，将会展开并显示运行的原始插值 SQL 字符串。

表查询

如果查询选项设置为格式化为表，则基本上可以执行任何类型的 SQL 查询。表面板将自动显示查询返回的任何列和行的结果。

以下示例代码显示了一个数据库表。

CREATE TABLE [event] (
  time_sec bigint,
  description nvarchar(100),
  tags nvarchar(100),
)

CREATE TABLE [mssql_types] (
  c_bit bit, c_tinyint tinyint, c_smallint smallint, c_int int, c_bigint bigint, c_money money, c_smallmoney smallmoney, c_numeric numeric(10,5),
  c_real real, c_decimal decimal(10,2), c_float float,
  c_char char(10), c_varchar varchar(10), c_text text,
  c_nchar nchar(12), c_nvarchar nvarchar(12), c_ntext ntext,
  c_datetime datetime,  c_datetime2 datetime2, c_smalldatetime smalldatetime, c_date date, c_time time, c_datetimeoffset datetimeoffset
)

INSERT INTO [mssql_types]
SELECT
  1, 5, 20020, 980300, 1420070400, '$20000.15', '£2.15', 12345.12,
  1.11, 2.22, 3.33,
  'char10', 'varchar10', 'text',
  N'☺nchar12☺', N'☺nvarchar12☺', N'☺text☺',
  GETDATE(), CAST(GETDATE() AS DATETIME2), CAST(GETDATE() AS SMALLDATETIME), CAST(GETDATE() AS DATE), CAST(GETDATE() AS TIME), SWITCHOFFSET(CAST(GETDATE() AS DATETIMEOFFSET), '-07:00')

以下示例代码显示了一个查询。

SELECT * FROM [mssql_types]

您可以使用常规 AS SQL 列选择语法来控制表面板列的名称，如以下示例代码所示。

SELECT
  c_bit as [column1], c_tinyint as [column2]
FROM
  [mssql_types]

生成的表面板：

时间序列查询

如果将格式化为设置为时间序列，例如在图形面板中使用，查询必须有一个名为 time 的列，该列返回 SQL 日期时间或任何表示 Unix 纪元（秒）的数字数据类型。您可以返回一个名为 metric 的列，该列用作值列的指标名称。除 time 和 metric 之外的任何列都被视为值列。如果省略 metric 列，则值列的名称为指标名称。您可以选择多个值列，每个值列都将使用其名称作为指标。如果返回多个值列和一个名为的 metric 列，则此列将用作序列名称的前缀。

时间序列查询的结果集必须按时间排序。

以下示例代码显示了一个数据库表。

CREATE TABLE [event] (
  time_sec bigint,
  description nvarchar(100),
  tags nvarchar(100),
)

CREATE TABLE metric_values (
  time datetime,
  measurement nvarchar(100),
  valueOne int,
  valueTwo int,
)

INSERT metric_values (time, measurement, valueOne, valueTwo) VALUES('2018-03-15 12:30:00', 'Metric A', 62, 6)
INSERT metric_values (time, measurement, valueOne, valueTwo) VALUES('2018-03-15 12:30:00', 'Metric B', 49, 11)
...
INSERT metric_values (time, measurement, valueOne, valueTwo) VALUES('2018-03-15 13:55:00', 'Metric A', 14, 25)
INSERT metric_values (time, measurement, valueOne, valueTwo) VALUES('2018-03-15 13:55:00', 'Metric B', 48, 10)

以下示例代码显示了一个 value 列和一个 metric 列。

SELECT
  time,
  valueOne,
  measurement as metric
FROM
  metric_values
WHERE
  $__timeFilter(time)
ORDER BY 1

在图形面板中使用上述查询时，将生成两个名为 Metric A 和 Metric B 的序列，其值 valueOne 和 valueTwo 绘制在 time 上。

以下示例代码显示了多个 value 列。

SELECT
  time,
  valueOne,
  valueTwo
FROM
  metric_values
WHERE
  $__timeFilter(time)
ORDER BY 1

在图形面板中使用上述查询时，将生成两个名为 Metric A 和 Metric B 的序列，其值 valueOne 和 valueTwo 绘制在 time 上。

以下示例代码演示了如何使用 $__TimeGroup 宏。

SELECT
  $__timeGroup(time, '3m') as time,
  measurement as metric,
  avg(valueOne)
FROM
  metric_values
WHERE
  $__timeFilter(time)
GROUP BY
  $__timeGroup(time, '3m'),
  measurement
ORDER BY 1

在图形面板中使用上述查询时，将生成两个名为 Metric A 和 Metric B 的序列，其值 valueOne 和 valueTwo 绘制在 time 上。在三分钟的窗口中，任何两个序列缺少一个值，都会在这两条线之间呈现一条线。您会注意到，右侧的图形永远不会下降到零。

以下示例代码演示了如何使用 $__TimeGroup 宏并将填充参数设置为零。

SELECT
  $__timeGroup(time, '3m', 0) as time,
  measurement as metric,
  sum(valueTwo)
FROM
  metric_values
WHERE
  $__timeFilter(time)
GROUP BY
  $__timeGroup(time, '3m'),
  measurement
ORDER BY 1

在图形面板中使用此查询时，结果是两个名为 Metric A 和 Metric B 的序列，其中 valueTwo 的总和绘制在 time 上。在三分钟窗口内缺少值的任何序列都将具有零值，可在右侧的图形中看到此值。

模板化

您可以在指标查询中使用变量来代替服务器、应用程序和传感器名称等硬编码。变量显示为控制面板顶部的下拉选择框。您可以使用这些下拉框来更改控制面板中显示的数据。

有关模板化和模板变量的更多信息，请参阅 模板和变量。

查询变量

如果添加 Query 类型的模板变量，则可以编写一个 MSSQL 查询，该查询可以返回测量名称、键名或键值等显示为下拉选择框的内容。

例如，如果在模板变量 Query 设置中指定了这样的查询，则会有一个变量，其中包含表中 hostname 列的所有值的。

SELECT hostname FROM host

查询可以返回多列，Grafana 会自动根据这些列创建一个列表。例如，以下查询将返回一个列表，其中包含来自 hostname 和 hostname2 的值。

SELECT [host].[hostname], [other_host].[hostname2] FROM host JOIN other_host ON [host].[city] = [other_host].[city]

另一个选项是可以创建键/值变量的查询。该查询应返回名为 __text 和 __value 的两列。__text 列值应该是唯一的（如果它不是唯一的，则使用第一个值）。下拉列表中的选项包含文本和值，允许将友好名称作为文本，将 id 作为值。以 hostname 作为文本，以 id 作为值的示例查询：

SELECT hostname __text, id __value FROM host

您还可以创建嵌套变量。例如，您还有一个名为 region 的变量。然后，您可以让主机变量仅显示来自当前所选区域的主机，并使用以下查询（如果 region 是多值变量，则使用 IN 比较运算符而不是 = 与多个值匹配）。

SELECT hostname FROM host WHERE region IN ($region)

在查询中使用变量

如果该变量是多值变量，则使用 IN 比较运算符而不是 = 与多个值匹配。

共有两种语法：

$<varname> 名为 hostname 的模板变量的示例：

SELECT
  atimestamp time,
  aint value
FROM table
WHERE $__timeFilter(atimestamp) and hostname in($hostname)
ORDER BY atimestamp

[[varname]] 名为 hostname 的模板变量的示例：

SELECT
  atimestamp as time,
  aint as value
FROM table
WHERE $__timeFilter(atimestamp) and hostname in([[hostname]])
ORDER BY atimestamp

关闭多值变量的引用

Grafana 会自动为多值变量创建带引号、以逗号分隔的字符串。例如，如果选择 server01 和 server02，则其格式为：'server01', 'server02'。要关闭引用，请对变量使用 csv 格式选项。

${servers:csv}

有关变量格式选项的更多信息，请参阅 模板和变量。

Annotations

您可以使用注释在图形上叠加丰富的事件信息。您可以通过控制面板菜单/注释视图添加注释查询。有关更多信息，请参阅 Annotations。

列：

以下示例代码显示了数据库表。

CREATE TABLE [events] (
  time_sec bigint,
  description nvarchar(100),
  tags nvarchar(100),
)

我们还使用 时间序列查询 中定义的数据库表。

以下示例代码演示了一个查询，该查询使用具有纪元值的 time 列。

SELECT
  time_sec as time,
  description as [text],
  tags
FROM
  [events]
WHERE
  $__unixEpochFilter(time_sec)
ORDER BY 1

以下示例代码演示了一个区域查询，该查询使用具有纪元值的 time 和 timeend 列。

SELECT
  time_sec as time,
  time_end_sec as timeend,
  description as [text],
  tags
FROM
  [events]
WHERE
  $__unixEpochFilter(time_sec)
ORDER BY 1

以下示例代码演示了一个查询，该查询使用本地 SQL 日期/时间数据类型的 time 列。

SELECT
  time,
  measurement as text,
  convert(varchar, valueOne) + ',' + convert(varchar, valueTwo) as tags
FROM
  metric_values
WHERE
  $__timeFilter(time_column)
ORDER BY 1

存储过程支持

存储过程已经过验证，可以正常工作。但在某些边缘情况下，可能无法按您的预期工作。表、时间序列和注释查询应支持存储过程，前提是您使用与前面各节所述相同的列命名，并以相同的格式返回数据。

宏函数在存储过程中不起作用。

示例

对于以下示例，数据库表是在时间序列查询中定义的。假设您要在图形面板中可视化四个序列，例如 valueOne、valueTwo 和 measurement 列的任意组合。右侧的图形面板直观地展示了我们想要实现的目标。要解决此问题，您必须使用两个查询：

以下示例代码显示了第一个查询。

SELECT
  $__timeGroup(time, '5m') as time,
  measurement + ' - value one' as metric,
  avg(valueOne) as valueOne
FROM
  metric_values
WHERE
  $__timeFilter(time)
GROUP BY
  $__timeGroup(time, '5m'),
  measurement
ORDER BY 1

以下示例代码显示了第二个查询。

SELECT
  $__timeGroup(time, '5m') as time,
  measurement + ' - value two' as metric,
  avg(valueTwo) as valueTwo
FROM
  metric_values
GROUP BY
  $__timeGroup(time, '5m'),
  measurement
ORDER BY 1

使用纪元格式时间的存储过程

您可以定义一个存储过程，该过程将返回在图形面板中呈现四个序列所需的所有数据，如上所示。在此情况下，存储过程接受两个参数 @from 和 @to，数据类型为 int，这应该是纪元格式的时间范围（from-to），用于筛选从存储过程返回的数据。

这模仿了 select 和 group by 表达式中的 $__timeGroup(time, '5m')，这就是为什么需要大量冗长的表达式。如果需要，可将其提取到 MSSQL 函数中。

CREATE PROCEDURE sp_test_epoch(
  @from int,
  @to   int
)   AS
BEGIN
  SELECT
    cast(cast(DATEDIFF(second, {d '1970-01-01'}, DATEADD(second, DATEDIFF(second,GETDATE(),GETUTCDATE()), time))/600 as int)*600 as int) as time,
    measurement + ' - value one' as metric,
    avg(valueOne) as value
  FROM
    metric_values
  WHERE
    time >= DATEADD(s, @from, '1970-01-01') AND time <= DATEADD(s, @to, '1970-01-01')
  GROUP BY
    cast(cast(DATEDIFF(second, {d '1970-01-01'}, DATEADD(second, DATEDIFF(second,GETDATE(),GETUTCDATE()), time))/600 as int)*600 as int),
    measurement
  UNION ALL
  SELECT
    cast(cast(DATEDIFF(second, {d '1970-01-01'}, DATEADD(second, DATEDIFF(second,GETDATE(),GETUTCDATE()), time))/600 as int)*600 as int) as time,
    measurement + ' - value two' as metric,
    avg(valueTwo) as value
  FROM
    metric_values
  WHERE
    time >= DATEADD(s, @from, '1970-01-01') AND time <= DATEADD(s, @to, '1970-01-01')
  GROUP BY
    cast(cast(DATEDIFF(second, {d '1970-01-01'}, DATEADD(second, DATEDIFF(second,GETDATE(),GETUTCDATE()), time))/600 as int)*600 as int),
    measurement
  ORDER BY 1
END

然后，您可以对图形面板使用以下查询。

DECLARE
  @from int = $__unixEpochFrom(),
  @to int = $__unixEpochTo()

EXEC dbo.sp_test_epoch @from, @to

使用日期时间格式的时间存储过程

您可以定义一个存储过程，该过程将返回在图形面板中呈现四个序列所需的所有数据，如上所示。在此情况下，存储过程接受两个参数 @from 和 @to，数据类型为 datetime，这应该是时间范围（from-to），用于筛选从存储过程返回的数据。

这模仿了 select 和 group by 表达式中的 $__timeGroup(time, '5m')，这就是为什么需要大量冗长的表达式。如果需要，可将其提取到 MSSQL 函数中。

CREATE PROCEDURE sp_test_datetime(
  @from datetime,
  @to   datetime
)   AS
BEGIN
  SELECT
    cast(cast(DATEDIFF(second, {d '1970-01-01'}, time)/600 as int)*600 as int) as time,
    measurement + ' - value one' as metric,
    avg(valueOne) as value
  FROM
    metric_values
  WHERE
    time >= @from AND time <= @to
  GROUP BY
    cast(cast(DATEDIFF(second, {d '1970-01-01'}, time)/600 as int)*600 as int),
    measurement
  UNION ALL
  SELECT
    cast(cast(DATEDIFF(second, {d '1970-01-01'}, time)/600 as int)*600 as int) as time,
    measurement + ' - value two' as metric,
    avg(valueTwo) as value
  FROM
    metric_values
  WHERE
    time >= @from AND time <= @to
  GROUP BY
    cast(cast(DATEDIFF(second, {d '1970-01-01'}, time)/600 as int)*600 as int),
    measurement
  ORDER BY 1
END

然后，您可以对图形面板使用以下查询。

DECLARE
  @from datetime = $__timeFrom(),
  @to datetime = $__timeTo()

EXEC dbo.sp_test_datetime @from, @to

警报

时间序列查询应在警报条件下工作。警报规则条件尚不支持表格式查询。