Tablestore:Tablestore SDK を使用した時系列モデルの使用

前提条件

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

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

注意事項

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

Tablestore SDK の使用

次の Tablestore SDK を使用して、時系列モデルの利用を開始できます。このトピックでは、Tablestore SDK for Java を使用します。

• Tablestore SDK for Java：時系列モデル

• Tablestore SDK for Go：時系列モデル

• Tablestore SDK for Python：時系列モデル

ステップ 1：時系列テーブルの作成

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

次のサンプルコードは、データ保持期間が無期限の 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 API を呼び出して、複数の時系列データレコードを時系列テーブルに同時に書き込みます。

次のサンプルコードは、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 パラメーターを指定して、1 行の時系列データを作成します。
        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 API を呼び出して条件を指定し、指定した条件を満たす時系列を取得します。

次のサンプルコードは、時系列テーブル内で、メジャーメント名が 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());
        // 取得した時系列が 1000 件に達した場合、ループを終了します。
        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 API を呼び出して、時系列内で指定した条件を満たす時系列データをクエリします。

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

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("cpu_usage", ColumnType.DOUBLE);
    getTimeseriesDataRequest.addFieldToGet("cpu_sys", ColumnType.DOUBLE);
    
    GetTimeseriesDataResponse getTimeseriesDataResponse = client.getTimeseriesData(getTimeseriesDataRequest);
    System.out.println(getTimeseriesDataResponse.getRows().size());
    
    // nextToken パラメーターが空でない場合は、別のリクエストを開始して残りの行を取得できます。
    if (getTimeseriesDataResponse.getNextToken() != null) {
        // nextToken 値を取得します。
        byte[] nextToken = getTimeseriesDataResponse.getNextToken();
        
        // 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());
    }
}

よくある質問

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

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

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