Skip to main content

OpenTSDB JSON Protocol


A JSON string is used in OpenTSDB JSON to represent one or more rows of data, for example: For example:

"metric": "sys.cpu.nice",
"timestamp": 1346846400,
"value": 18,
"tags": {
"host": "web01",
"dc": "lga"
"metric": "sys.cpu.nice",
"timestamp": 1346846400,
"value": 9,
"tags": {
"host": "web02",
"dc": "lga"

Similar to OpenTSDB line protocol, metric will be used as the STable name, timestamp is the timestamp to be used, value represents the metric collected, tags are the tag sets.

Please refer to OpenTSDB HTTP API for more details.

  • In JSON protocol, strings will be converted to nchar type and numeric values will be converted to double type.
  • Only data in array format is accepted and so an array must be used even if there is only one row.
  • The defult child table name is generated by rules.You can configure smlChildTableName in taos.cfg to specify chile table names, for example, smlChildTableName=tname. You can insert "tags": { "host": "web02","dc": "lga","tname":"cpu1"} and the cpu1 table will be automatically created. Note that if multiple rows have the same tname but different tag_set values, the tag_set of the first row is used to create the table and the others are ignored.


package com.taos.example;

import com.taosdata.jdbc.SchemalessWriter;
import com.taosdata.jdbc.enums.SchemalessProtocolType;
import com.taosdata.jdbc.enums.SchemalessTimestampType;

import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.SQLException;
import java.sql.Statement;

public class JSONProtocolExample {
private static Connection getConnection() throws SQLException {
String jdbcUrl = "jdbc:TAOS://localhost:6030?user=root&password=taosdata";
return DriverManager.getConnection(jdbcUrl);

private static void createDatabase(Connection conn) throws SQLException {
try (Statement stmt = conn.createStatement()) {
stmt.execute("CREATE DATABASE IF NOT EXISTS test");
stmt.execute("USE test");

private static String getJSONData() {
return "[{\"metric\": \"meters.current\", \"timestamp\": 1648432611249, \"value\": 10.3, \"tags\": {\"location\": \"California.SanFrancisco\", \"groupid\": 2}}," +
" {\"metric\": \"meters.voltage\", \"timestamp\": 1648432611249, \"value\": 219, \"tags\": {\"location\": \"California.LosAngeles\", \"groupid\": 1}}, " +
"{\"metric\": \"meters.current\", \"timestamp\": 1648432611250, \"value\": 12.6, \"tags\": {\"location\": \"California.SanFrancisco\", \"groupid\": 2}}," +
" {\"metric\": \"meters.voltage\", \"timestamp\": 1648432611250, \"value\": 221, \"tags\": {\"location\": \"California.LosAngeles\", \"groupid\": 1}}]";

public static void main(String[] args) throws SQLException {
try (Connection conn = getConnection()) {
SchemalessWriter writer = new SchemalessWriter(conn);
String jsonData = getJSONData();
writer.write(jsonData, SchemalessProtocolType.JSON, SchemalessTimestampType.NOT_CONFIGURED);

view source code

2 STables will be created automatically and each STable has 2 rows of data in the above sample code.

taos> use test;
Database changed.

taos> show stables;
name |
meters.current |
meters.voltage |
Query OK, 2 row(s) in set (0.001954s)

taos> select * from `meters.current`;
_ts | _value | groupid | location |
2022-03-28 09:56:51.249 | 10.300000000 | 2.000000000 | California.SanFrancisco |
2022-03-28 09:56:51.250 | 12.600000000 | 2.000000000 | California.SanFrancisco |
Query OK, 2 row(s) in set (0.004076s)

Query Examples

If you want query the data of "tags": {"location": "California.LosAngeles", "groupid": 1},here is the query sql: select * from meters.voltage where location="California.LosAngeles" and groupid=1