Time Series Database:TSQL 構文と機能

2. クエリ構文

TSQL クエリは、メタデータクエリと時系列データクエリの 2 つのタイプに分類されます。

2.1 メタデータクエリ

2.1.1 TSDB からテーブルまたはメトリックをクエリする

SHOW TABLES ステートメントを実行して、テーブルをクエリできます。

SHOW TABLES FROM TSDB

多数のメトリックを含む TSDB インスタンスからデータテーブルをクエリするために SHOW TABLES ステートメントを実行すると、長い遅延が発生します。 TSDB が提供する /api/suggest オペレーションを呼び出して、特定のメトリックをクエリすることをお勧めします。

2.1.2 TSDB から特定の条件を満たすテーブルまたはメトリックをクエリする

たとえば、次のステートメントを実行して、名前が cpu で始まるテーブルをクエリできます。

SHOW TABLES FROM TSDB WHERE TABLE_NAME like 'cpu%'

2.1.3 データテーブルの列に関する情報をクエリする

DESCRIBE ステートメントを実行して、データテーブルのすべての列に関する情報をクエリできます。各列の名前とデータ型が返されます。

DESCRIBE TSDB.`cpu.usage_system`
+----------------------+--------------------+--------------+
|     COLUMN_NAME      |     DATA_TYPE      | IS_NULLABLE  |
+----------------------+--------------------+--------------+
| hostname             | CHARACTER VARYING  | YES          |
| rack                 | CHARACTER VARYING  | YES          |
| service_environment  | CHARACTER VARYING  | YES          |
| os                   | CHARACTER VARYING  | YES          |
| service              | CHARACTER VARYING  | YES          |
| datacenter           | CHARACTER VARYING  | YES          |
| arch                 | CHARACTER VARYING  | YES          |
| service_version      | CHARACTER VARYING  | YES          |
| team                 | CHARACTER VARYING  | YES          |
| region               | CHARACTER VARYING  | YES          |
| timestamp            | TIMESTAMP          | NO           |
| value                | DOUBLE             | YES          |
+----------------------+--------------------+--------------+

2.2 時系列データをクエリする

TSQL では、SELECT ステートメントを実行して時系列データをクエリできます。 SELECT ステートメントには、クエリ式と、FROM、WHERE、GROUP BY、ORDER BY などの SQL 句が含まれています。次のコードは、SELECT ステートメントの構文を示しています。

select_stmt = 
        SELECT exp_list 
        FROM from_clause 
        [where_clause]  
        [groupby_clause] 
        [having_clause] 
        [orderby_clause] 
        [limit_clause]

2.2.1 予約語

すべての SQL 予約語については、SQL 標準を参照してください。クエリするテーブル、列、または関数の名前に特殊文字または予約語が含まれている場合は、エスケープ文字 (`) を使用して名前を囲む必要があります。この処理方法は、MySQL の字句解析と同じです。たとえば、クエリで予約語 timestamp と value を使用する場合は、実行する SELECT ステートメントを次の形式にする必要があります。

SELECT `timestamp`, `value` from tsdb.table_name

たとえば、名前にピリオド (.) が含まれる cpu.usage_system メトリックをクエリする場合は、ステートメントでエスケープ文字 (`) のペアを使用してメトリック名を囲みます。次のコードは構文を示しています。

SELECT * from tsdb.`cpu.usage_system`

3. 時系列データクエリ

3.1 フィルター

3.1.1 時間ベースのフィルター

時間ベースのフィルターは、timestamp 列のフィルター条件です。次の表に、サポートされている時間ベースのフィルターを示します。

上記のフィルターを使用する前に、次の点に注意してください。

• デフォルトでは、yyyy-MM-dd HH:mm:ss.SSS 形式のタイムスタンプは UTC タイムスタンプとして識別されます。
• ミリ秒単位のエポックタイムスタンプを時間範囲の開始時刻と終了時刻として指定できます。エポックタイムスタンプは LONG データ型である必要があり、文字列にすることはできません。
• TSQL クエリには時間ベースのフィルターが必要です。 TSQL クエリを実行するときに時間ベースのフィルターを指定しないと、大量のデータがスキャンされます。これにより、システムパフォーマンスが低下します。
• 日付と時刻の形式で時間範囲の開始時刻または終了時刻を指定する場合は、yyyy-MM-dd HH:mm:ss.SSS 形式のタイムスタンプを指定する必要があります。そうしないと、TSQL はタイムスタンプを解析できません。その結果、TSQL はタイムスタンプを varchar として処理し、予期しない結果を返します。

3.1.2 サポートされているタイムゾーン

3.1.2.1 V2.5.9 より前の TSDB バージョンでサポートされているタイムゾーン

/api/version オペレーションを呼び出して、TSDB バージョンを確認できます。 V2.5.9 より前の TSDB バージョンには、次のルールが適用されます。

• TSQL クエリで指定されるタイムスタンプは、yyyy-MM-dd HH:mm:ss.SSS 形式である必要があります。デフォルトでは、タイムスタンプは UTC タイムスタンプとして識別されます。たとえば、指定するタイムスタンプが 2019-03-01 00:00:00:00.000 の場合、文字列は 2019-03-01 00:00:00:00.00 (UTC+0) に解析されます。 UTC+0 タイムゾーンはグリニッジ標準時 (GMT) と呼ばれます。 UTC+8 タイムゾーンを使用する場合、時刻は 2019-03-01 08:00:00.00 (UTC+8) です。
• デフォルトでは、クエリ結果のタイムスタンプは UTC タイムスタンプです。

例:

select hostname, `timestamp`, `value` 
from tsdb.`cpu.usage_system` 
where `timestamp` between '2019-03-01 00:00:00' and '2019-03-01 00:00:10' 
limit 2;
+-----------+------------------------+---------------------+
| hostname  |       timestamp        |        value        |
+-----------+------------------------+---------------------+
| host_7    | 2019-03-01 00:00:00.0  | 14.568605774857241  |
| host_7    | 2019-03-01 00:00:10.0  | 14.722472083963408  |
+-----------+------------------------+---------------------+

この例では、GMT 2019-03-01 00:00:00 と GMT 2019-03-01 00:00:10 の間に生成されたレコードがクエリされます。 timestamp 列に返されるタイムスタンプは GMT タイムスタンプです。

3.1.2.2 TSDB V2.5.9 以降でサポートされているタイムゾーン

UTC 以外のタイムゾーンは、TSDB V2.5.9 以降でサポートされています。

• クエリ内のタイムスタンプは yyyy-MM-dd HH:mm:ss.SSS ZZZ 形式です。 ZZZ はタイムゾーンのオフセットを指定し、オプションです。 UTC+8 をタイムゾーンとして使用する場合は、ZZZ を +0800 に設定します。たとえば、2019-03-01 08:00.00 +0800 は、2019 年 3 月 1 日 08:00 (UTC+8) を示します。
• localtime(timestamp, timezoneOffset) 関数は、特定のタイムスタンプを指定されたタイムゾーンの現地時刻に変換するために使用されます。 timestamp パラメーターはタイムスタンプを指定します。 timezoneOffset パラメーターはタイムゾーンのオフセットを指定します。たとえば、UTC+8 の現地時刻を取得する場合は、localtime(timestamp, '+0800') 関数を呼び出します。

例:

select hostname, localtime(`timestamp`, '+0800') as ltime, `value` 
from tsdb.`cpu.usage_system` 
where `timestamp` between '2019-03-01 08:00:00 +0800' and '2019-03-01 08:00:10 +0800' 
limit 2;
+-----------+------------------------+---------------------+
| hostname  |         ltime          |        value        |
+-----------+------------------------+---------------------+
| host_7    | 2019-03-01 08:00:00.0  | 14.568605774857241  |
| host_7    | 2019-03-01 08:00:10.0  | 14.722472083963408  |
+-----------+------------------------+---------------------+

前の例では、localtime() は 2019-03-01 00:00:00 UTC+8 と 2019-03-01 00:00:10 UTC+8 の間に生成されたレコードを返します。 ltime 列のタイムスタンプは UTC+8 です。この例で返されるレコードは、3.1.2.1 セクションで示した例で返されるレコードと同じですが、タイムスタンプは異なるタイムゾーンに基づいて表示されます。

V2.5.9 以降の TSDB のバージョンは、V2.5.9 より前のバージョンで使用されるクエリ構文と互換性があります。これにより、アプリケーションで使用される UTC タイムスタンプはすべてのバージョンでサポートされます。

localtime() 関数は、tumble() 関数の結果に使用できます。次のコードは例を示しています。

select 
    count(*) as cnt,   
    localtime(tumble(`timestamp`, interval '5' second),  '+0800') as ltime 
from tsdb.`cpu.usage_system` 
where `timestamp` between '2019-03-01 08:00:00 +0800' and '2019-03-01 08:00:10 +0800' 
group by ltime;
+------+------------------------+
| cnt  |         ltime          |
+------+------------------------+
| 10   | 2019-03-01 08:00:00.0  |
| 10   | 2019-03-01 08:00:10.0  |
+------+------------------------+

3.1.3 タグベースのフィルター

TSQL は、「等しい」や「等しくない」などのさまざまな単純なタグベースのフィルターをサポートしています。また、複数の値のリストを取得することでデータをフィルターすることもできます。さらに、列に適用された関数によって返された値を比較することで、データをフィルターすることもできます。タグベースのフィルターは、AND および OR 論理演算子を使用して組み合わせて、高度な条件付きフィルターを実行できます。

3.1.4 メトリック値ベースのフィルター

TSQL では、メトリック値に基づいてデータポイントをフィルターできます。次の表に、サポートされているメトリック値ベースのフィルターを示します。

3.2 グループ化と集計

SQL クエリで GROUP BY 句を使用してグループ化ルールを指定し、前の表にリストされている集計関数を使用して各グループのデータを集計できます。データポイントのグループ化ルールは、タグベース、タイムスタンプベース、タグとタイムスタンプベースの 3 つのタイプに分類できます。集計関数の詳細については、「TSQL 関数」トピックで説明されている集計関数のリストを参照してください。

3.2.1 タグベースのグループ化と集計

TSDB では、GROUP BY 句にタグまたはタグ式を追加して、データポイントをグループ化および集計できます。

次のコードは例を示しています。次のステートメントを実行すると、システムは datacenter と hostname の値の最初の 3 文字に基づいてデータポイントをグループ化し、各グループのメトリック値の最大値、最小値、平均値を計算します。

select
  datacenter,
  substr(hostname, 1,3) preHost,
  max(`value`) maxV,
  min(`value`) minV,
  avg(`value`) avgV
from tsdb.`cpu.usage_system`
where `timestamp` >='2016-01-01' and
  `timestamp` <= '2016-01-02'
group by datacenter, prehost

3.2.2 ダウンサンプリング: タイムスタンプベースのグループ化と集計

TSQL は tumple() 関数を提供します。 tumple() 関数を使用すると、指定された間隔に基づいて一連のタイムスタンプを重複しない複数の時間ウィンドウに分割できます。この関数を呼び出して、指定されたタイムスタンプ間隔に基づいてデータポイントをグループに分割できます。

• tumble

tumble(timestamp_column, interval_expression)

tumble(`timestamp`, interval '1' hour) 関数を呼び出すと、関数はタイムスタンプを 1 時間の間隔に基づいてウィンドウに分割します。 tumble(`timestamp`, interval '5' minute) 関数を呼び出すと、関数はタイムスタンプを 5 分の間隔に基づいてウィンドウに分割します。

たとえば、次のステートメントを実行して、1 日のタイムラインのデータポイントをクエリできます。この例では、タイムスタンプは 1 時間の間隔に基づいてウィンドウに分割されます。各グループのデータポイントの最大値、最小値、平均値が返されます。

select
  tumble(`timestamp`, interval '1' hour) ts,
  max(`value`) maxV,
  min(`value`) minV,
  avg(`value`) avgV
from tsdb.`cpu.usage_system`
where `timestamp` >='2016-01-01' and
  `timestamp` <= '2016-01-02'
group by  ts

タイムスタンプベースのグループ化と集計機能は、ダウンサンプリング機能と同様の機能を提供します。ただし、タイムスタンプベースのグループ化と集計機能とダウンサンプリング機能には複数の違いがあります。次の情報は、違いを詳述しています。

• ダウンサンプリング機能は、単一のタイムラインに対して /api/query オペレーションを呼び出すことによって使用できます。タイムスタンプベースのグループ化と集計は、複数のタイムラインで実行できます。
• TSQL は、単一のタイムラインと複数のタイムラインのタイムスタンプベースの集計に同じ集計関数を使用します。タイムスタンプベースの集計用に TSDB によって提供される集計関数は、ダウンサンプリングに使用される集計関数とは異なります。

3.2.3 タグ列とタイムスタンプ間隔に基づいてデータポイントをグループ化および集計する

TSQL では、タグ列とタイムスタンプ間隔に基づいてデータポイントをグループ化および集計できます。タグ列を指定するには、GROUP BY 句に列名または列の式を含めます。次のコードは例を示しています。次のステートメントを実行すると、システムはデータポイントのホスト名の最初の 3 文字と 1 時間間隔のタイムスタンプに基づいてデータポイントをグループ化します。次に、システムは各グループのメトリック値の最大値、最小値、平均値を計算します。

select
  datacenter,
  substr(hostname, 1,3) preHost,
  tumble(`timestamp`, interval '1' hour) ts,
  max(`value`) maxV,
  min(`value`) minV,
  avg(`value`) avgV
from tsdb.`cpu.usage_system`
where `timestamp` >='2016-01-01' and
  `timestamp` <= '2016-01-02'
group by datacenter, preHost, ts

3.2.4 タイムラインの最初と最新のデータポイントをクエリする

ts_last() 関数を呼び出してタイムラインの最新のデータポイントを取得し、ts_first() 関数を呼び出してタイムラインの最初のデータポイントを取得できます。

select
  hostname,
  ts_last(`value`, `timestamp`) as v_last,
  max(`timestamp`) maxT
from tsdb.`cpu.usage_system`
where `timestamp` >='2016-01-01 00:00:00' and
  `timestamp` <= '2016-01-01 01:00:00'
group by hostname
order by hostname

前のステートメントを実行すると、指定された時間範囲で生成された最新のデータポイントのメトリック値とタイムスタンプが返されます。

3.2.5 タグキー列とタイムスタンプ間隔に基づいて分割された各グループの最初と最新のデータポイントをクエリする

タグキー列とタイムスタンプ間隔に基づいてデータポイントを集計のためにグループに分割し、各グループの最初と最新のデータポイントをクエリできます。タグキー列を指定するには、GROUP BY 句に列名を含めます。タイムスタンプ間隔を取得するには、tumble() 関数を呼び出します。

select
  hostname, 
  tumble(`timestamp`, interval '10' minute) ts,
  ts_last(`value`, `timestamp`) as v_last,
  max(`timestamp`) maxT
from tsdb.`cpu.usage_system`
where `timestamp` >='2016-01-01 00:00:00' and
  `timestamp` <= '2016-01-01 01:00:00'
group by hostname, ts
order by hostname, ts

3.3 関連分析のために複数のメトリックを結合する

TSQL クエリエンジンを使用すると、関連分析のために複数のタイムラインを結合できます。 TSQL クエリエンジンを使用して、名前が異なるメトリックを分析できます。複数のメトリックを結合する前に、メトリックが同じである必要がある属性を指定する必要があります。属性は、次のいずれかの項目です。

• タイムスタンプ
• 特定のタグ

たとえば、次のステートメントを実行して、cpu.usage_system メトリックと cpu.usage_idle メトリックを関連分析のために結合します。次に、システムは同じ hostname と同じ timestamp を持つメトリック値を返します。

select t1.`timestamp`, t1.`value` as value1, t2.`value` as value2, t1.hostname
from tsdb.`cpu.usage_system` t1, tsdb.`cpu.usage_idle` t2
where t1.`timestamp` >='2016-01-01' and t1.`timestamp` <= '2016-01-02' 
 and t1.hostname = t2.hostname
 and t1.`timestamp`= t2.`timestamp`
 limit 100

次のコードは別の例を示しています。この例では、結合条件は前の例で指定されたものと同じです。次のステートメントが実行されると、タグとタイムスタンプが調整され、メトリック値は hostname に基づいて集計のためにグループに分割されます。次に、メトリックの平均値が計算されて返されます。

select t1.hostname, avg(t1.`value`) as avg_sys, avg(t2.`value`) as avg_idle
from tsdb.`cpu.usage_system` t1, tsdb.`cpu.usage_idle` t2
where t1.`timestamp` >='2016-01-01' and t1.`timestamp` <= '2016-01-02' 
 and t1.hostname = t2.hostname
 and t1.`timestamp`= t2.`timestamp`
group by t1.hostname