すべてのプロダクト
Search

このプロダクト

    :時系列の最新データポイントの照会

    ドキュメントセンター

    :時系列の最新データポイントの照会

    最終更新日:Mar 29, 2026

    1 つ以上の時系列における最新のデータポイントを照会します。OpenTSDB と完全互換です。

    エンドポイント

    POST /api/query/last

    リクエストパラメーター

    パラメーター型必須説明例
    queries配列はい実行するサブクエリ。各サブクエリは、メトリックまたは TSUID を対象とします。「サブクエリパラメーター」をご参照ください。
    timestampLongいいえ照会対象の UNIX タイムスタンプ（秒またはミリ秒単位）。省略した場合、現在時刻のタイムスタンプが使用されます。1539763573
    hintマップいいえクエリエンジンが使用するインデックスを制御するクエリヒント。リクエスト内のすべてのサブクエリに適用されます。「hint」をご参照ください。
    limitマップいいえ時系列ごとに 1 つのデータポイントではなく、複数の最新データポイントを返します。「limit」をご参照ください。

    サブクエリパラメーター

    queries 配列内の各サブクエリは、メトリックまたは TSUID のいずれかを対象とする必要があります。

    メトリックサブクエリ

    パラメーター型必須説明例
    metric文字列はい照会対象のメトリック。cpu.usage
    tagsマップいいえ照会をフィルターするためのタグのキーと値のペア。{"host_name": "host1"}
    hintマップいいえこのサブクエリにのみスコープを限定したクエリヒント。「hint」をご参照ください。
    重要

    フィルターには tags パラメーターのみがサポートされています。filters パラメーターはサポートされていません。

    TSUID サブクエリ

    パラメーター型必須説明例
    tsuids配列はい照会対象の時系列の TSUID。["00005B00005C0000F000005D0000EE00005E0000EF"]
    重要

    時系列の TSUID を取得するには、/api/search/lookup 操作を呼び出してください。TSDB High-availability Edition: tsuid パラメーターは受け付けられますが、効果はありません。/api/search/lookup 操作は、High-availability Edition では TSUID を返しません。

    1 つのリクエストに、メトリックサブクエリと TSUID サブクエリの両方を含めることができます。

    リクエストの例

    以下のリクエストでは、cpu.usage のメトリックサブクエリ（ホスト host1）と、2 つの時系列に対する TSUID サブクエリの計 2 つのサブクエリを実行します。

    POST /api/query/last
    {
    "queries": [
        {
            "metric": "cpu.usage",
            "tags": {
                "host_name": "host1"
            }
        },
        {
            "tsuids": [
                "00005B00005C00002E00005D0000EE00005E0000EF",
                "00005B00005C0000F000005D0000EE00005E0000EF"
            ]
        }
    ]
}

    レスポンス要素

    200 の状態コードは成功を示します。レスポンスボディは JSON 配列であり、各オブジェクトは一致した時系列の最新データポイントを表します。照会条件に一致する時系列がない場合は、空の配列が返されます。

    パラメーター説明
    metricメトリック名。
    timestamp最新データポイントのタイムスタンプ。
    valueそのタイムスタンプにおけるメトリック値。
    tagsデータポイントのタグペア。各タグはタグキーとタグ値で構成されます。
    tsuid時系列の ID。

    レスポンスの例

    [{
    "metric": "cpu.usage",
    "timestamp": 1556418300000,
    "value": 30.3,
    "tags": {
        "host_name": "host1"
    },
    "tsuid": "00005B00005C00001D"
}, {
    "metric": "cpu.usage",
    "timestamp": 1556418300000,
    "value": 25.6,
    "tags": {
        "host_name": "host2",
        "cluster": "cluster1",
        "zone": "zone1"
    },
    "tsuid": "00005B00005C00002E00005D0000EE00005E0000EFE"
}, {
    "metric": "cpu.usage",
    "timestamp": 1556418300000,
    "value": 43.1,
    "tags": {
        "host_name": "host3",
        "cluster": "cluster1",
        "zone": "zone1"
    },
    "tsuid": "00005B00005C0000F000005D0000EE00005E0000EF"
}]

    hint

    クエリヒントを使用すると、クエリエンジンが使用するインデックスを制御することで応答時間を短縮できます。

    対応バージョン： TSDB V2.6.1 以降

    ヒント内では、tagk パラメーターのみがサポートされています。各タグキーを 0 または 1 に設定します。

    • 0：このタグキーに対してインデックスを使用しない

    • 1：このタグキーに対してインデックスを使用する

    tagk 内のすべての値は同一である必要があります。0 と 1 を 1 つのヒント内で混在させると、エラーが発生します。

    ヒントは、単一のサブクエリに適用することも、リクエスト全体に適用することもできます。サブクエリオブジェクト内に hint を設定すると、そのサブクエリにのみスコープが限定されます。トップレベルに hint を設定すると、すべてのサブクエリに適用されます。

    サブクエリにスコープを限定したヒント

    {
    "queries": [
        {
            "metric": "sys.cpu.nice",
            "tags": {
                "host": "web01"
            },
            "hint": {
                "tagk": {
                    "dc": 1
                }
            }
        }
    ]
}

    すべてのサブクエリに適用されるヒント

    {
    "queries": [
        {
            "metric": "sys.cpu.nice",
            "tags": {
                "host": "web01"
            }
        }
    ],
    "hint": {
        "tagk": {
            "dc": 1
        }
    }
}

    エラー事例

    同一の 0 と 1 を tagk マップ内で混在させると、HTTP 400 エラーが返されます。以下のリクエストがこのエラーをトリガーします。

    {
    "start": 1346846400,
    "end": 1346846400,
    "queries": [
        {
            "aggregator": "none",
            "metric": "sys.cpu.nice",
            "tags": {
                "dc": "lga",
                "host": "web01"
            }
        }
    ],
    "hint": {
        "tagk": {
            "dc": 1,
            "host": 0
        }
    }
}
    {
    "error": {
        "code": 400,
        "message": "The value of hint should only be 0 or 1, and there should not be both 0 and 1",
        "details": "TSQuery(start_time=1346846400, end_time=1346846400, subQueries[TSSubQuery(metric=sys.cpu.nice, filters=[filter_name=literal_or, tagk=dc, literals=[lga], group_by=true, filter_name=literal_or, tagk=host, literals=[web01], group_by=true], tsuids=[], agg=none, downsample=null, ds_interval=0, rate=false, rate_options=null, delta=false, delta_options=null, top=0, granularity=null, granularityDownsample=null, explicit_tags=explicit_tags, index=0, realTimeSeconds=-1, useData=auto, limit=0, offset=0, dpValue=null, preDpValue=null, startTime=1346846400000, endTime=1346846400000, Query_ID=null)] padding=false, no_annotations=false, with_global_annotations=false, show_tsuids=false, ms_resolution=false, options=[])"
    }
}

    0 または 1 以外の値（例：100）を指定した場合も、HTTP 400 エラーが返されます。以下のリクエストがこのエラーをトリガーします。

    {
    "start": 1346846400,
    "end": 1346846400,
    "queries": [
        {
            "aggregator": "none",
            "metric": "sys.cpu.nice",
            "tags": {
                "dc": "lga",
                "host": "web01"
            }
        }
    ],
    "hint": {
        "tagk": {
            "dc": 100
        }
    }
}
    {
    "error": {
        "code": 400,
        "message": "The value of hint can only be 0 or 1, and it is detected that '100' is passed in",
        "details": "TSQuery(start_time=1346846400, end_time=1346846400, subQueries[TSSubQuery(metric=sys.cpu.nice, filters=[filter_name=literal_or, tagk=dc, literals=[lga], group_by=true, filter_name=literal_or, tagk=host, literals=[web01], group_by=true], tsuids=[], agg=none, downsample=null, ds_interval=0, rate=false, rate_options=null, delta=false, delta_options=null, top=0, granularity=null, granularityDownsample=null, explicit_tags=explicit_tags, index=0, realTimeSeconds=-1, useData=auto, limit=0, offset=0, dpValue=null, preDpValue=null, startTime=1346846400000, endTime=1346846400000, Query_ID=null)] padding=false, no_annotations=false, with_global_annotations=false, show_tsuids=false, ms_resolution=false, options=[])"
    }
}

    limit

    デフォルトでは、/api/query/last は時系列ごとに 1 つのデータポイントを返します。limit パラメーターを設定すると、指定された時間範囲内で時系列ごとに複数の最新データポイントを返すことができます。

    パラメーター型必須説明例
    size整数はい時系列ごとに返すデータポイントの最大数。5
    fromLongはい照会対象の時間範囲の開始時刻（UNIX タイムスタンプ）。1346846400

    例

    以下のデータが 4 つの時系列に書き込まれており、各時系列に 2 つのデータポイントがあります。

    [
    {"metric": "testmetric", "tags": {"testmetric1_tagk": "testmetric1_tagv1"}, "timestamp": 1514736040, "value": 1},
    {"metric": "testmetric", "tags": {"testmetric2_tagk": "testmetric2_tagv1"}, "timestamp": 1514736050, "value": 2},
    {"metric": "testmetric", "tags": {"testmetric1_tagk": "testmetric1_tagv1"}, "timestamp": 1514736060, "value": 3},
    {"metric": "testmetric", "tags": {"testmetric2_tagk": "testmetric2_tagv1"}, "timestamp": 1514736070, "value": 4},
    {"metric": "testmetric", "tags": {"testmetric1_tagk": "testmetric1_tagv2"}, "timestamp": 1514736080, "value": 5},
    {"metric": "testmetric", "tags": {"testmetric2_tagk": "testmetric2_tagv2"}, "timestamp": 1514736090, "value": 6},
    {"metric": "testmetric", "tags": {"testmetric1_tagk": "testmetric1_tagv2"}, "timestamp": 1514736100, "value": 7},
    {"metric": "testmetric", "tags": {"testmetric2_tagk": "testmetric2_tagv2"}, "timestamp": 1514736110, "value": 8}
]

    このリクエストでは、size を 2 に設定し、時間範囲 1514736040 ～ 1514736100（7 つのデータポイントを含む）を照会します。

    {
    "timestamp": 1514736100,
    "limit": {
        "size": 2,
        "from": 1514736040
    },
    "queries": [
        {
            "metric": "testmetric"
        }
    ]
}

    レスポンスでは、時間範囲内で時系列ごとに最大 2 つのデータポイントが返されます。

    [
    {
        "metric": "testmetric",
        "timestamp": 1514736060000,
        "value": 3.0,
        "tags": {
            "testmetric1_tagk": "testmetric1_tagv1"
        },
        "tsuid": "0200000200000200****",
        "version": 0,
        "dps": {
            "1514736040000": 1.0,
            "1514736060000": 3.0
        }
    },
    {
        "metric": "testmetric",
        "timestamp": 1514736100000,
        "value": 7.0,
        "tags": {
            "testmetric1_tagk": "testmetric1_tagv2"
        },
        "tsuid": "0400000200000200****",
        "version": 0,
        "dps": {
            "1514736080000": 5.0,
            "1514736100000": 7.0
        }
    },
    {
        "metric": "testmetric",
        "timestamp": 1514736070000,
        "value": 4.0,
        "tags": {
            "testmetric2_tagk": "testmetric2_tagv1"
        },
        "tsuid": "0E00000200000300****",
        "version": 0,
        "dps": {
            "1514736050000": 2.0,
            "1514736070000": 4.0
        }
    },
    {
        "metric": "testmetric",
        "timestamp": 1514736090000,
        "value": 6.0,
        "tags": {
            "testmetric2_tagk": "testmetric2_tagv2"
        },
        "tsuid": "1000000200000300****",
        "version": 0,
        "dps": {
            "1514736090000": 6.0
        }
    }
]