Write time series data - Tablestore SDK for Java - Tablestore

Use Tablestore SDK for Java to write one or more rows of time series data and obtain error information for failed rows.

Prerequisites

Install the Tablestore SDK for Java and initialize a time series client.

Description

Call putTimeseriesData to write one or more rows of data to a time series table. Each row consists of time series identifiers, a data point timestamp, and data fields. The response contains the rows that failed to be written and their error information.

public PutTimeseriesDataResponse putTimeseriesData(PutTimeseriesDataRequest request) throws TableStoreException, ClientException

The following example writes three data points for the same time series to example_timeseries_table and checks the result of each row.

TimeseriesClient timeseriesClient = client.asTimeseriesClient();

String tableName = "example_timeseries_table";
List<TimeseriesRow> rows = new ArrayList<>();

Map<String, String> tags = new HashMap<>();
tags.put("region", "cn-hangzhou");
tags.put("host", "host_0");
TimeseriesKey timeseriesKey = new TimeseriesKey("cpu", "source_0", tags);

long baseTimeInUs = System.currentTimeMillis() * 1000L;
for (int i = 0; i < 3; i++) {
    TimeseriesRow row = new TimeseriesRow(timeseriesKey, baseTimeInUs + i * 1000L);
    row.addField("cpu_usage", ColumnValue.fromDouble(10.0 + i));
    row.addField("status", ColumnValue.fromString("ok"));
    rows.add(row);
}

PutTimeseriesDataRequest request = new PutTimeseriesDataRequest(tableName);
request.setRows(rows);
PutTimeseriesDataResponse response = timeseriesClient.putTimeseriesData(request);

for (PutTimeseriesDataResponse.FailedRowResult result : response.getFailedRows()) {
    System.out.println(result.getIndex());
    System.out.println(result.getError());
}

Parameters

PutTimeseriesDataRequest contains the following parameters.

Name	Type	Description
timeseriesTableName (required)	`String`	The time series table name.
rows (required)	`List<TimeseriesRow>`	The rows of time series data to write.
metaUpdateMode (optional)	`PutTimeseriesDataRequest.MetaUpdateMode`	The time series metadata update mode. Default: `NORMAL`, which allows the server to determine whether to update the time series metadata index. If this parameter is set to `IGNORE`, the current write does not update the metadata index. This may affect time series metadata queries and SQL queries.

Time series data rows

Each element in rows[] is of the TimeseriesRow type and contains the following parameters.

Name	Type	Description
timeseriesKey (required)	`TimeseriesKey`	The time series identifiers.
timeInUs (required)	`long`	The data point timestamp in microseconds since 1970-01-01 00:00:00 UTC. The value must be greater than or equal to `0`.
fields (required)	`SortedMap<String, ColumnValue>`	The data fields, which consist of one or more field names and field values.

Time series identifiers

rows[].timeseriesKey is of the TimeseriesKey type and contains the following parameters.

Name	Type	Description
measurementName (required)	`String`	The measurement name. Tablestore SDK for Java 5.17.2 or later allows this parameter to be empty.
dataSource (optional)	`String`	The data source identifier. This parameter can be empty.
tags (optional)	`SortedMap<String, String>`	The tags as string key-value pairs. An empty map is used if this parameter is not specified.

Response

PutTimeseriesDataResponse contains the following operation-specific field.

Field	Type	Description
`failedRows`	`List<PutTimeseriesDataResponse.FailedRowResult>`	Call `getFailedRows()` to obtain the rows that failed to be written. An empty list is returned if all rows are written. You can also call `isAllSuccess()` to determine whether all rows are written.

Failed row information

Each element in failedRows[] is of the PutTimeseriesDataResponse.FailedRowResult type and contains the following fields.

Field	Type	Description
`index`	`int`	Call `getIndex()` to obtain the index of the failed row in the `rows` list of the request.
`error`	`Error`	Call `getError()` to obtain the failure reason.