Data operations

Prerequisites

The CLI with access credentials configured. For more information, see Tablestore CLI.
A time series table. For more information, see Time series table operations.

Before you write, import, or query data, select the target time series table:

use --ts -t <tableName>

Write time series data

Write a row of time series data to a specified timeline.

putts --k '<timeseriesKey>' --field '<fields_json>' --time <timestamp>

Parameter	Required	Description
--k	Yes	The timeline identifier, represented as a JSON array in the format `["measurement","dataSource",["tag1=value1","tag2=value2"]]`. The array includes: First element: the measurement name. Second element: the data source identifier. Third element: a tag array. Each tag is in tagKey=tagValue format.
--field	Yes	Data fields, represented as a JSON array. Each element contains the following properties: c (required): the column name. v (required): the column value. Supported types: string, Boolean, integer, and floating-point number. isint (optional): set to `true` to treat the value as an integer. Defaults to `false` (floating-point number).
--time	Yes	The timestamp of the data row, in microseconds (μs).

Example

Write CPU metrics for a monitored host in the Hangzhou region:

putts --k '["cpu","localhost",["region=hangzhou","os=ubuntu"]]' --field '[{"c":"usage_user","v":58,"isint":true},{"c":"usage_idle","v":24,"isint":true}]' --time 1635162859000000

Import time series data

Import time series data from a local file into a time series table.

Windows

import_timeseries --input D:\\localpath\\filename.txt

Linux and macOS

import_timeseries --input /localpath/filename.txt

Parameter	Required	Description
-i, --input	Yes	The path to the local data file.

Each line in the data file represents a row of time series data in the format measurement_name,tags fields timestamp.

Field	Required	Description
measurement_name	Yes	The measurement name.
tags	Yes	Each tag is in tagKey=tagValue format. The tagValue of the first tag is used as the data source identifier.
fields	Yes	Data fields in fieldKey=fieldValue format. Append `i` to a numeric value to indicate an integer. Values without `i` default to floating-point.
timestamp	Yes	The timestamp in nanoseconds (ns). The value is automatically converted to microseconds after import.

Example data file:

cpu,hostname=host_0,region=cn-hangzhou usage_user=58i,usage_system=2i,usage_idle=24i 1609459200000000000
cpu,hostname=host_1,region=cn-hangzhou usage_user=58i,usage_system=2i,usage_idle=24i 1609459200000000000

Example

Import time series data from a local file:

import_timeseries --input /tmp/import_timeseries.txt

Query time series data

Query time series data for a specified timeline within a time range.

getts --k '<timeseriesKey>' --time_start <start> --time_end <end> --limit <n>

Parameter	Required	Description
--k	Yes	The timeline identifier, in the same format as `--k` in the Write time series data section.
--time_start	Yes	The start time of the query, as a timestamp in microseconds.
--time_end	Yes	The end time of the query, as a timestamp in microseconds.
--limit	No	The maximum number of rows to return. Valid values: 1 to 5000.

Example

getts --k '["cpu","localhost",["region=hangzhou","os=ubuntu"]]' --time_start 0 --time_end 1667638230000000 --limit 100

Search for timelines

Search for timelines that match specified conditions. The shorthand for this command is qtm.

query_ts_meta --measurement <measurement> --datasource <dataSource> --limit <n>

Parameter	Required	Description
--measurement	No	The measurement name.
--datasource	No	The data source identifier.
--limit	No	The maximum number of rows to return. Valid values: 1 to 1000. The server may return fewer rows than the specified limit.
-e, --edit	No	Define complex search filters in JSON format. Supported filter types: COMPOSITE, MEASUREMENT, SOURCE, and TAG.

Example

Search for timelines where the measurement name is cpu and the data source identifier is localhost.

query_ts_meta --measurement cpu --datasource localhost --limit 10

To define complex search filters, use qtm -e. Example filter:

{
    "Type":"COMPOSITE",
    "QueryCondition":{
        "Operator":"AND",
        "SubConditions":[
            {
                "Type":"MEASUREMENT",
                "QueryCondition":{
                    "Operator":"EQUAL",
                    "Value":"CPU"
                }
            },
            {
                "Type":"SOURCE",
                "QueryCondition":{
                    "Operator":"EQUAL",
                    "Value":"127.0.0.1"
                }
            },
            {
                "Type":"TAG",
                "QueryCondition":{
                    "Operator":"GREATER_EQUAL",
                    "TagName":"Region",
                    "Value":"Jiangning"
                }
            }
        ]
    }
}

Scan timelines

Retrieve all or a limited number of timelines from a time series table. The shorthand for this command is qtm.

query_ts_meta --limit <n>

Parameter	Required	Description
--limit	No	The maximum number of rows to return. If not specified, all timelines are scanned.

Example

query_ts_meta --limit 10

Update timelines

Update the attributes of a timeline. If the target timeline does not exist, this command creates it. The shorthand for this command is utm.

update_ts_meta --k '<timeseriesKey>' --attrs '<attributes>'

Parameter	Required	Description
--k	Yes	The timeline identifier, in the same format as `--k` in the Write time series data section.
--attrs	No	The attributes of the timeline, represented as a JSON array. Each attribute is in key=value format.

Example

Set the city and region attributes for a monitored host:

update_ts_meta --k '["cpu","localhost",["region=hangzhou","os=ubuntu"]]' --attrs '["city=nanjing","region=jiangning"]'