Tablestore SDK で時系列モデルを使用するには、時系列テーブルを作成し、そのテーブルに時系列データを書き込みます。その後、時系列を取得して時系列データをクエリする必要があります。
前提条件
-
時系列モデル用のインスタンスが作成されていること。詳細については、「時系列モデル用のインスタンスの作成」をご参照ください。
-
クライアントが初期化されていること。詳細については、「Tablestore クライアントの初期化」をご参照ください。
使用上の注意
時系列モデルは、中国 (杭州)、中国 (上海)、中国 (北京)、中国 (張家口)、中国 (ウランチャブ)、中国 (深圳)、中国 (成都)、中国 (香港)、日本 (東京)、マレーシア (クアラルンプール)、ドイツ (フランクフルト)、インドネシア (ジャカルタ)、英国 (ロンドン)、米国 (シリコンバレー)、米国 (バージニア)、 サウジアラビア (リヤド - パートナーリージョン)、 シンガポールの各リージョンでサポートされています。
Tablestore SDK の使用
時系列モデルを使い始めるには、次の Tablestore SDK を使用できます。このトピックでは、Tablestore SDK for Java を使用します。
ステップ 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」で、かつ「os」タグの値が「Ubuntu」で始まるすべての時系列をクエリします。 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 操作を呼び出して、時系列内の指定した条件を満たす時系列データをクエリします。
次のサンプルコードは、時系列テーブル内の指定した条件を満たす時系列データをクエリする例です。
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());
}
}
よくある質問
参考情報
Tablestore コンソールまたは Tablestore CLI を使って時系列モデルを使い始めることもできます。詳細については、「Tablestore コンソールでの時系列モデルの使用」および「Tablestore CLI での時系列モデルの使用」をご参照ください。