Tablestore:Tablestore SDK を使用して TimeSeries モデルを使用する

前提条件

• TimeSeries モデルのインスタンスが作成されていること。詳細については、「TimeSeries モデルのインスタンスを作成する」をご参照ください。

• クライアントが初期化されていること。詳細については、「Tablestore クライアントを初期化する」をご参照ください。

使用上の注意

TimeSeries モデルは、中国 (杭州)、中国 (上海)、中国 (北京)、中国 (張家口)、中国 (ウランチャブ)、中国 (深セン)、中国 (成都)、中国 (香港)、日本 (東京)、マレーシア (クアラルンプール)、ドイツ (フランクフルト)、インドネシア (ジャカルタ)、英国 (ロンドン)、米国 (シリコンバレー)、米国 (バージニア)、SAU (リヤド - パートナーリージョン)、およびシンガポールでサポートされています。

Tablestore SDK の使用

TimeSeries モデルを使い始めるには、次の Tablestore SDK を使用できます。このトピックでは、Tablestore SDK for Java を使用します。

• Tablestore SDK for Java: TimeSeries モデル

• Tablestore SDK for Go: TimeSeries モデル

• Tablestore SDK for Python: TimeSeries モデル

ステップ 1: 時系列テーブルを作成する

CreateTimeseriesTable 操作を呼び出して、時系列データを格納する時系列テーブルを作成します。

次のサンプルコードは、データの有効期限が切れない test_timeseries_table という名前の時系列テーブルを作成する方法の例を示しています。

private static void createTimeseriesTable(TimeseriesClient client) {
    String tableName = "test_timeseries_table";
    TimeseriesTableMeta timeseriesTableMeta = new TimeseriesTableMeta(tableName);
    int timeToLive = -1;
    timeseriesTableMeta.setTimeseriesTableOptions(new TimeseriesTableOptions(timeToLive));
    CreateTimeseriesTableRequest request = new CreateTimeseriesTableRequest(timeseriesTableMeta);
    // デフォルトの分析ストアが作成されないように指定します。
    request.setEnableAnalyticalStore(false);    
    client.createTimeseriesTable(request);
}

ステップ 2: 時系列データを書き込む

時系列テーブルを作成した後、PutTimeseriesData 操作を呼び出して、複数の時系列データレコードを同時に時系列テーブルに書き込みます。

次のサンプルコードは、test_timeseries_table という名前の時系列テーブルに複数の行の時系列データを書き込む方法の例を示しています。

private static void putTimeseriesData(TimeseriesClient client) {
    List<TimeseriesRow> rows = new ArrayList<TimeseriesRow>();
    for (int i = 0; i < 10; i++) {
        Map<String, String> tags = new HashMap<String, String>();
        tags.put("region", "hangzhou");
        tags.put("os", "Ubuntu16.04");
        // 時系列のメジャー名、データソース、およびタグを指定して、時系列の識別子を構築します。
        TimeseriesKey timeseriesKey = new TimeseriesKey("cpu", "host_" + i, tags);
        // timeseriesKey パラメーターと timeInUs パラメーターを指定して、時系列データの行を作成します。
        TimeseriesRow row = new TimeseriesRow(timeseriesKey, System.currentTimeMillis() * 1000 + i);
        // データ値を追加します。
        row.addField("cpu_usage", ColumnValue.fromDouble(10.0));
        row.addField("cpu_sys", ColumnValue.fromDouble(5.0));
        rows.add(row);
    }
    String tableName = "test_timeseries_table";
    PutTimeseriesDataRequest putTimeseriesDataRequest = new PutTimeseriesDataRequest(tableName);
    putTimeseriesDataRequest.setRows(rows);
    // 複数の行の時系列データを同時に書き込みます。
    PutTimeseriesDataResponse putTimeseriesDataResponse = client.putTimeseriesData(putTimeseriesDataRequest);
    // すべてのデータが時系列テーブルに書き込まれたかどうかを確認します。
    if (!putTimeseriesDataResponse.isAllSuccess()) {
        for (PutTimeseriesDataResponse.FailedRowResult failedRowResult : putTimeseriesDataResponse.getFailedRows()) {
            System.out.println(failedRowResult.getIndex());
            System.out.println(failedRowResult.getError());
        }
    }
}

ステップ 3: 時系列を取得する

クエリする時系列の情報 (メトリック名、データソースなど) がわからない場合は、QueryTimeseriesMeta 操作を呼び出して、指定した条件を満たす時系列を取得するための条件を指定します。

次のサンプルコードは、時系列テーブルで、メトリック名が cpu で、値がUbuntu で始まるプレフィックスを持つ os タグを持つすべての時系列をクエリする方法の例を示しています。

private static void queryTimeseriesMeta(TimeseriesClient client) {
    // 時系列テーブルの名前を指定します。
    String tableName = "<TIME_SERIES_TABLE>";
    QueryTimeseriesMetaRequest queryTimeseriesMetaRequest = new QueryTimeseriesMetaRequest(tableName);
    // メトリック名が cpu で、値が Ubuntu で始まるプレフィックスを持つ os タグを持つすべての時系列をクエリします。measurement_name="cpu" and have_prefix(os, "Ubuntu")
    CompositeMetaQueryCondition compositeMetaQueryCondition = new CompositeMetaQueryCondition(MetaQueryCompositeOperator.OP_AND);
    compositeMetaQueryCondition.addSubCondition(new MeasurementMetaQueryCondition(MetaQuerySingleOperator.OP_EQUAL, "cpu"));
    compositeMetaQueryCondition.addSubCondition(new TagMetaQueryCondition(MetaQuerySingleOperator.OP_PREFIX, "os", "Ubuntu"));
    queryTimeseriesMetaRequest.setCondition(compositeMetaQueryCondition);
    queryTimeseriesMetaRequest.setGetTotalHits(true);
    // 1 回のリクエストで返される時系列メタデータエントリの最大数を指定します。
    queryTimeseriesMetaRequest.setLimit(100);
    // クエリを開始します。
    QueryTimeseriesMetaResponse queryTimeseriesMetaResponse = client.queryTimeseriesMeta(queryTimeseriesMetaRequest);
    // クエリ条件を満たす時系列の総数を表示します。
    System.out.println(queryTimeseriesMetaResponse.getTotalHits());

    // リクエスト結果を保存します。
    List<TimeseriesMeta> timeseriesMetas = new ArrayList<TimeseriesMeta>();
    timeseriesMetas.addAll(queryTimeseriesMetaResponse.getTimeseriesMetas());

    // NextToken がレスポンスに含まれている場合は、新しいリクエストを開始して残りの結果を取得できます。
    while (queryTimeseriesMetaResponse.getNextToken() != null) {
        queryTimeseriesMetaRequest.setNextToken(queryTimeseriesMetaResponse.getNextToken());
        queryTimeseriesMetaResponse = client.queryTimeseriesMeta(queryTimeseriesMetaRequest);
        timeseriesMetas.addAll(queryTimeseriesMetaResponse.getTimeseriesMetas());
        // 返される時系列の最大数を指定します。
        if (timeseriesMetas.size() >= 1000) {
            break;
        }
    }

    System.out.println(timeseriesMetas.size());
    for (TimeseriesMeta timeseriesMeta : timeseriesMetas) {
        System.out.println(timeseriesMeta.getTimeseriesKey().getMeasurementName());
        System.out.println(timeseriesMeta.getTimeseriesKey().getDataSource());
        System.out.println(timeseriesMeta.getTimeseriesKey().getTags());
        System.out.println(timeseriesMeta.getAttributes());
        System.out.println(timeseriesMeta.getUpdateTimeInUs());
    }
}

ステップ 4: 時系列データをクエリする

GetTimeseriesData 操作を呼び出して、時系列で指定された条件を満たす時系列データをクエリします。

次のサンプルコードは、時系列テーブルで指定された条件を満たす時系列データをクエリする方法の例を示しています。

private static void getTimeseriesData(TimeseriesClient client) {
    String tableName = "<TIMESERIES_TABLE_NAME>";
    GetTimeseriesDataRequest getTimeseriesDataRequest = new GetTimeseriesDataRequest(tableName);
    Map<String, String> tags = new HashMap<String, String>();
    tags.put("region", "hangzhou");
    tags.put("os", "Ubuntu16.04");
    // 時系列のメジャー名、データソース、およびタグを指定して、時系列の識別子を構築します。
    TimeseriesKey timeseriesKey = new TimeseriesKey("cpu", "host_0", tags);
    getTimeseriesDataRequest.setTimeseriesKey(timeseriesKey);
    // 時間範囲を指定します。
    getTimeseriesDataRequest.setTimeRange(0, (System.currentTimeMillis() + 60 * 1000) * 1000);
    // 返す行の最大数を指定します。
    getTimeseriesDataRequest.setLimit(10);
    // オプション。クエリ結果を逆時系列順にソートするかどうかを指定します。デフォルト値: false。このパラメーターを true に設定すると、クエリ結果は逆時系列順にソートされます。
    getTimeseriesDataRequest.setBackward(false);
    // オプション。返す列を指定します。このパラメーターを指定しない場合は、すべての列が返されます。
    getTimeseriesDataRequest.addFieldToGet("string_1", ColumnType.STRING);
    getTimeseriesDataRequest.addFieldToGet("long_1", ColumnType.INTEGER);
    
    GetTimeseriesDataResponse getTimeseriesDataResponse = client.getTimeseriesData(getTimeseriesDataRequest);
    System.out.println(getTimeseriesDataResponse.getRows().size());
    
    // nextToken パラメーターが空でない場合は、別のリクエストを開始して残りの行を取得できます。
    if (getTimeseriesDataResponse.getNextToken() != null) {
        // nextToken 値をクエリします。
        byte[] nextToken = getTimeseriesDataResponse.getNextToken();
        
        // nextToken を永続化したり、nextToken をフロントエンドページに転送したりする場合は、Base64 を使用して nextToken を文字列にエンコードできます。
        {
            // トークンは文字列ではありません。new String(nextToken) を使用してトークンを文字列にエンコードすると、トークンに関する情報が失われます。
            String tokenAsString = Base64.toBase64String(nextToken);
            // 文字列をバイトにデコードします。
            byte[] tokenAsByte = Base64.fromBase64String(tokenAsString);
        }
        
        getTimeseriesDataRequest.setNextToken(nextToken);
        getTimeseriesDataResponse = client.getTimeseriesData(getTimeseriesDataRequest);
        System.out.println(getTimeseriesDataResponse.getRows().size());
    }
}

FAQ

• 時系列データを更新するにはどうすればよいですか？

• 時系列データを削除するにはどうすればよいですか？

• 時系列テーブルに書き込んだデータをすぐにクエリできますか？