翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。 # Microsoft SQL Server データソースに接続する Microsoft SQL Server (MSSQL) データソースを使用して、Microsoft Azure SQL Database を含む Microsoft SQL Server 2005 以降からのデータをクエリおよび視覚化します。 **重要** Grafana バージョン 8.0 は、Microsoft SQL Server、Postgres、MySQL のデータフレームの基盤となるデータ構造を変更します。その結果、時系列のクエリ結果が幅広い形式で返されます。詳細については、Grafana データフレームドキュメントの「[ワイドフォーマット](https://grafana.com/developers/plugin-tools/introduction/data-frames#wide-format)」を参照してください。 視覚エフェクトを以前と同じように機能させるには、手動による移行が必要になる場合があります。1 つの解決策は、Github の 「[Postgres/MySQL/MSSQL: Breaking change in v8.0 related to time series queries and ordering of data column](https://github.com/grafana/grafana/issues/35534)」に記載されています。 ## データソースの追加 1. 上部ヘッダーの Grafana アイコンを選択して、サイドメニューを開きます。 1. リンク下のサイドメニューの **[設定]** に、**[データソース]** リンクがあります。 1. 上部ヘッダーの **[\$1 データソースの追加]** ボタンを選択します。 1. **[タイプ]** ドロップダウンリストから **[Microsoft SQL Server]** を選択します。 ### データソースオプション | 名前 | 説明 | | --- | --- | | Name | データソース名。これは、パネルとクエリ内へのデータソースの表示のされ方です。 | | Default | デフォルトのデータソースは、新しいパネル用に事前に選択されたデータソースです。 | | Host | MSSQL インスタンスの IP アドレス/ホスト名とオプションのポート。ポートを省略すると、デフォルトのポート 1433 が使用されます。 | | Database | MSSQL データベースの名前。 | | User | データベースユーザーのログイン/ユーザー名。 | | Password | データベースユーザーのパスワード。 | | Encrypt | このオプションは、安全な SSL TCP/IP 接続をサーバーとネゴシエートするかどうか、またはどの程度までネゴシエートするかを決定します。デフォルトは false です(Grafana v5.4 以降)。 | | Max open | データベースへのオープン接続の最大数。デフォルトは unlimited です (Grafana v5.4 以降)。 | | Max idle | アイドル接続プールの最大接続数。デフォルトは 2 です (Grafana v5.4 以降)。 | | Max lifetime | 接続を再利用できる秒単位の最大時間。デフォルトは 14400/4 時間です。 | ### 最小時間間隔 `$_interval` `$_interval_ms` 変数の下限。データを 1 分ごとに書き込む場合は `1m` など、書き込み頻度に設定することをお勧めします。このオプションは、[Data Source] (データソース) オプションのダッシュボードパネルで上書き/設定することもできます。この値は、`1m` (1 分) や `30s` (30 秒) など、有効な時間識別子が続く数値としてフォーマットする**必要があります**。以下の時間識別子がサポートされています。 | 識別子 | 説明 | | --- | --- | | y | 年 | | M | 月 | | w | 週 | | d | 日 | | h | 時間 | | m | 分 | | s | 秒 | | ms | ミリ秒 | ### データベースユーザーのアクセス許可 **重要** データソースを追加するときに指定するデータベースユーザーには、クエリする指定されたデータベースとテーブルに対してのみ SELECT アクセス許可を付与する必要があります。Grafana は、クエリが安全であることを検証しません。クエリには任意の SQL ステートメントを含めることができます。例えば、 `DELETE FROM user;` や`DROP TABLE user;` などのステートメントが実行されます。これを防ぐために、アクセス許可が制限された特定の MSSQL ユーザーを作成することを強くお勧めします。 次のコード例は、アクセス許可が制限された特定の MSSQL ユーザーの作成を示しています。 ``` CREATE USER grafanareader WITH PASSWORD 'password' GRANT SELECT ON dbo.YourTable3 TO grafanareader ``` ユーザーがパブリックロールから不要なアクセス許可を付与されていないことを確認します。 ### 既知の問題 2008 や 2008R2 などの古いバージョンの Microsoft SQL Server を使用している場合は、暗号化を無効にしないと接続できないことがあります。可能な場合は、最適な互換性を得るために利用可能な最新のサービスパックを適用することをお勧めします。 ## クエリエディタ MSSQL クエリエディタは、Graph、Singlestat、または Table パネルの編集モードの [メトリクス] タブにあります。パネルタイトルを選択し、[編集] を選択して編集モードに入ります。エディタでは、視覚化するデータを選択する SQL クエリを定義できます。 1. *[Format as]* `Time series` (Graph または Singlestat パネルなどで使用) または `Table` (Table パネルなどで使用) を選択します。 1. これは、SQL クエリを記述する実際のエディタです。 1. クエリエディタの下に MSSQL のヘルプセクションを表示します。 1. 実行された SQL クエリを表示します。クエリが正常に実行された後、最初に使用可能になります。 1. 追加のクエリエディターが表示される場所に、追加のクエリを追加します。 ## マクロ 構文を簡素化し、日付範囲フィルターなどの動的部分を許可するため、クエリにマクロを含めることができます。 | マクロの例 | 説明 | | --- | --- | | \$1\$1\$1time(dateColumn) | 列の名前を時間 に変更する式に置き換えられます。例えば、dateColumn が時間に置き換えられます。 | | \$1\$1\$1timeEpoch(dateColumn) | DATETIME 列タイプを Unix タイムスタンプに変換し、名前を時間 に変更する式に置き換えられます。例えば、DATEDIFF(second, "1970-01-01", dateColumn) が時間に置き換えられます。 | | \$1\$1\$1timeFilter(dateColumn) | 指定された列名を使用して時間範囲フィルターに置き換えられます。例えば、dateColumn BETWEEN "2017-04-21T05:01:17Z" AND "2017-04-21T05:06:17Z"です。 | | \$1\$1\$1timeFrom() | 現在アクティブな時間選択の開始に置き換えられます。例えば、"2017-04-21T05:01:17Z" です。 | | \$1\$1\$1timeTo() | 現在アクティブな時間選択の終了に置き換えられます。例えば、"2017-04-21T05:06:17Z" です。 | | \$1\$1\$1timeGroup(dateColumn,'5m'[, fillvalue]) | GROUP BY 句で使用できる式に置き換えられます。[fillValue] に [NULL] または[浮動値]を指定すると、時間範囲内の空のシリーズにその値が自動的に入力されます。例えば、CAST(ROUND(DATEDIFF(second, "1970-01-01", time\$1column)/300.0, 0) as bigint)\$1300 です。 | | \$1\$1\$1timeGroup(dateColumn,'5m', 0) | 前述と同じですが、fill パラメーターがあるため、その系列の欠落しているポイントは grafana によって追加され、0 が値として使用されます。 | | \$1\$1\$1timeGroup(dateColumn,'5m', NULL) | 上記と同じですが、NULL は欠落ポイントの値として使用されます。 | | \$1\$1\$1timeGroup(dateColumn,'5m', previous) | 上記と同じですが、その系列の前の値がフィル値として使用されます。まだ値が見つからない場合は NULL が使用されます (Grafana 5.3 以降でのみ使用可能) 。 | クエリエディタには、パネル編集モードでクエリが実行された後に表示される**[生成 SQL]** リンクがあります。これを選択すると、実行された未加工の補間 SQL 文字列が展開されて表示されます。 ## テーブルクエリ クエリオプションが**[Format as]****[テーブル]**として設定されている場合、基本的に任意のタイプの 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] ``` 結果のテーブルパネル: ## 時系列クエリ 例えば Graph パネルで使用するために **[Format as]** を **[時系列]**に設定した場合、クエリは SQL 日時または Unix エポックを表す任意の数値データ型を返す `time` という名前の列が必要です。値列のメトリクス名として使用される `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) ``` 次のコード例は、1 列 `value` と 1 列 `metric` を示しています。 ``` SELECT time, valueOne, measurement as metric FROM metric_values WHERE $__timeFilter(time) ORDER BY 1 ``` 前述のクエリがグラフパネルで使用されると、`Metric A` と `Metric B` という名前の 2 つのシリーズが生成され、値 `valueOne` と `valueTwo` が `time` にプロットされます。 次のコード例は、複数の `value` 列を示しています。 ``` SELECT time, valueOne, valueTwo FROM metric_values WHERE $__timeFilter(time) ORDER BY 1 ``` 前述のクエリがグラフパネルで使用されると、`Metric A` と `Metric B` という名前の 2 つのシリーズが生成され、値 `valueOne` と `valueTwo` が `time` にプロットされます。 次のコード例は、\$1\$1\$1timeGroup マクロの使用を示しています。 ``` 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` という名前の 2 つのシリーズが生成され、値 `valueOne` と `valueTwo` が `time` にプロットされます。3 分間のウィンドウに値がない 2 つのシリーズでは、その 2 つの行の間に線がレンダリングされます。右側のグラフがゼロに下がらないことがわかります。 次のコード例では、fill パラメータを 0 に設定した上での \$1\$1\$1 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` という名前の 2 つのシリーズで、`valueTwo` の合計が `time` にプロットされます。3 分間のウィンドウで値が欠落しているシリーズの値は 0 になり、右側のグラフに表示されます。 ## テンプレート作成 メトリクスクエリでサーバー、アプリケーション、センサー名などのものをハードコーディングする代わりに変数を使用できます。変数は、ダッシュボードの上部にドロップダウン選択ボックスとして表示されます。これらのドロップダウンボックスを使用して、ダッシュボードに表示されるデータを変更できます。 テンプレート作成とテンプレート変数の詳細については、「[テンプレートおよび変数](templates-and-variables.md)」を参照してください。 ### クエリ変数 タイプ `Query` のテンプレート変数を追加すると、測定名、キー名、ドロップダウン選択ボックスとして表示されるキー値などを返すことができる MSSQL クエリを記述できます。 例えば、テンプレート変数*クエリ*設定でこのようなクエリを指定した場合、テーブル内の `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] ``` もう 1 つのオプションは、キー/値変数を作成できるクエリです。クエリは、 `__text` と `__value` という名前の 2 つの列を返します。`__text` 列の値は一意である必要があります (一意でない場合は、最初の値が使用されます)。ドロップダウンリストのオプションには、わかりやすい名前をテキストとして、ID を値として指定できるテキストと値があります。`hostname` をテキスト、`id` を値とするクエリの例: ``` SELECT hostname __text, id __value FROM host ``` ネストされた変数も作成できます。例えば、`region` という名前の別の変数がある場合です。次に、ホスト変数に、このようなクエリを含む、現在選択されているリージョンからのホストのみを表示させることができます (`region` が複数値変数の場合は、`=` を使用して複数の値と照合するのではなく、`IN` 比較演算子を使用します）。 ``` SELECT hostname FROM host WHERE region IN ($region) ``` ### クエリでの変数の使用 **注記** テンプレート変数の値は、テンプレート変数が `multi-value` の場合にのみ引用符で囲まれます。 変数が複数値の変数の場合は、`=` を使用して複数の値と照合するのではなく、`IN` 比較演算子を使用します。 2 つの構文があります。 `$` `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}` 変数形式オプションの詳細については、「[テンプレートおよび変数](templates-and-variables.md)」を参照してください。 ## ‏注釈 注釈を使用して、グラフの上にリッチイベント情報をオーバーレイできます。ダッシュボードメニュー/注釈ビューを使用して注釈クエリを追加します。詳細については、「[‏注釈](dashboard-annotations.md)」を参照してください。 **列** | 名前 | 説明 | | --- | --- | | time | 日付/時刻フィールドの名前。ネイティブ SQL 日付/時刻データ型またはエポック値を持つ列にすることができます。 | | timeend | 終了日時フィールドのオプション名。ネイティブ SQL 日付/時刻データ型またはエポック値を持つ列にすることができます。 | | text | イベントの説明フィールド。 | | tags | カンマ区切り文字列としてイベントタグに使用するオプションのフィールド名。 | 次のコード例は、データベーステーブルを示しています。 ``` CREATE TABLE [events] ( time_sec bigint, description nvarchar(100), tags nvarchar(100), ) ``` また、[時系列クエリ](#mssql-time-series-queries) で定義されているデータベーステーブルも使用します。 次のコード例は、エポック値を持つ時間列を使用したクエリを示しています。 ``` SELECT time_sec as time, description as [text], tags FROM [events] WHERE $__unixEpochFilter(time_sec) ORDER BY 1 ``` 次のコード例は、エポック値を持つ時間列と 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 日付/時刻データ型の時刻列を使用したクエリを示しています。 ``` 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` のすべての組み合わせなど、グラフパネル内の 4 つのシリーズを視覚化するとします。右側のグラフパネルは、達成したいことを視覚化します。これを解決するには、次の 2 つのクエリを使用する必要があります。 次のコード例は、1 つ目のクエリを示しています。 ``` 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 ``` 次のコード例は、2 つ目のクエリを示しています。 ``` 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 ``` #### エポック形式の時間を使用したストアドプロシージャ 上記のようなグラフパネルで 4 つのシリーズをレンダリングするために、必要なすべてのデータを返すストアドプロシージャを定義できます。この場合、ストアドプロシージャは、`int` データ型の 2 つのパラメータ `@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 ``` #### 日時形式の時刻を使用したストアドプロシージャ 上記のようなグラフパネルで 4 つのシリーズをレンダリングするために、必要なすべてのデータを返すストアドプロシージャを定義できます。この場合、ストアドプロシージャは、`datetime` データ型の 2 つのパラメータ `@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 ``` ## [アラート] 時系列クエリは、アラート条件で機能します。テーブル形式のクエリは、アラートルール条件ではまだサポートされていません。