OpenTSDB Line Protocol

Introduction

A single line of text is used in OpenTSDB line protocol to represent one row of data. OpenTSDB employs a single column data model, so each line can only contain a single data column. There can be multiple tags. Each line contains 4 parts as below:

1. <metric> <timestamp> <value> <tagk_1>=<tagv_1>[ <tagk_n>=<tagv_n>]
  • metric will be used as the STable name.
  • timestamp is the timestamp of current row of data. The time precision will be determined automatically based on the length of the timestamp. Second and millisecond time precision are supported.
  • value is a metric which must be a numeric value, The corresponding column name is “value”.
  • The last part is the tag set separated by spaces, all tags will be converted to NCHAR type automatically.

For example:

1. meters.current 1648432611250 11.3 location=California.LosAngeles groupid=3
  • The child table name is created automatically in a rule to guarantee its uniqueness. But you can configure smlChildTableName in taos.cfg to specify a tag value as the table names if the tag value is unique globally. For example, if a tag is called tname and you set smlChildTableName=tname in taos.cfg, when you insert st,tname=cpu1,t1=4 c1=3 1626006833639000000, the child table cpu1 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. Please refer to OpenTSDB Telnet API for more details.

Examples

  • Java
  • Python
  • Go
  • Node.js
  • C#
  • C
1. package com.taos.example;

3. import com.taosdata.jdbc.SchemalessWriter;
4. import com.taosdata.jdbc.enums.SchemalessProtocolType;
5. import com.taosdata.jdbc.enums.SchemalessTimestampType;

7. import java.sql.Connection;
8. import java.sql.DriverManager;
9. import java.sql.SQLException;
10. import java.sql.Statement;

12. public class TelnetLineProtocolExample {
13. // format: <metric> <timestamp> <value> <tagk_1>=<tagv_1>[ <tagk_n>=<tagv_n>]
14. private static String[] lines = { "meters.current 1648432611249 10.3 location=California.SanFrancisco groupid=2",
15. "meters.current 1648432611250 12.6 location=California.SanFrancisco groupid=2",
16. "meters.current 1648432611249 10.8 location=California.LosAngeles groupid=3",
17. "meters.current 1648432611250 11.3 location=California.LosAngeles groupid=3",
18. "meters.voltage 1648432611249 219 location=California.SanFrancisco groupid=2",
19. "meters.voltage 1648432611250 218 location=California.SanFrancisco groupid=2",
20. "meters.voltage 1648432611249 221 location=California.LosAngeles groupid=3",
21. "meters.voltage 1648432611250 217 location=California.LosAngeles groupid=3",
22. };

24. private static Connection getConnection() throws SQLException {
25. String jdbcUrl = "jdbc:TAOS://localhost:6030?user=root&password=taosdata";
26. return DriverManager.getConnection(jdbcUrl);
27. }

29. private static void createDatabase(Connection conn) throws SQLException {
30. try (Statement stmt = conn.createStatement()) {
31. // the default precision is ms (microsecond), but we use us(microsecond) here.
32. stmt.execute("CREATE DATABASE IF NOT EXISTS test precision 'us'");
33. stmt.execute("USE test");
34. }
35. }

37. public static void main(String[] args) throws SQLException {
38. try (Connection conn = getConnection()) {
39. createDatabase(conn);
40. SchemalessWriter writer = new SchemalessWriter(conn);
41. writer.write(lines, SchemalessProtocolType.TELNET, SchemalessTimestampType.NOT_CONFIGURED);
42. }
43. }

45. }

view source code

1. import taos
2. from taos import SmlProtocol, SmlPrecision

4. # format: <metric> <timestamp> <value> <tagk_1>=<tagv_1>[ <tagk_n>=<tagv_n>]
5. lines = ["meters.current 1648432611249 10.3 location=California.SanFrancisco groupid=2",
6. "meters.current 1648432611250 12.6 location=California.SanFrancisco groupid=2",
7. "meters.current 1648432611249 10.8 location=California.LosAngeles groupid=3",
8. "meters.current 1648432611250 11.3 location=California.LosAngeles groupid=3",
9. "meters.voltage 1648432611249 219 location=California.SanFrancisco groupid=2",
10. "meters.voltage 1648432611250 218 location=California.SanFrancisco groupid=2",
11. "meters.voltage 1648432611249 221 location=California.LosAngeles groupid=3",
12. "meters.voltage 1648432611250 217 location=California.LosAngeles groupid=3",
13. ]

16. # create connection use firstEp in taos.cfg.
17. def get_connection():
18. return taos.connect()

21. def create_database(conn):
22. conn.execute("CREATE DATABASE test")
23. conn.execute("USE test")

26. def insert_lines(conn):
27. affected_rows = conn.schemaless_insert(
28. lines, SmlProtocol.TELNET_PROTOCOL, SmlPrecision.NOT_CONFIGURED)
29. print(affected_rows)  # 8

32. if __name__ == '__main__':
33. connection = get_connection()
34. try:
35. create_database(connection)
36. insert_lines(connection)
37. finally:
38. connection.close()

view source code

1. package main

3. import (
4. "log"

6. "github.com/taosdata/driver-go/v3/af"
7. )

9. func prepareDatabase(conn *af.Connector) {
10. _, err := conn.Exec("CREATE DATABASE test")
11. if err != nil {
12. panic(err)
13. }
14. _, err = conn.Exec("USE test")
15. if err != nil {
16. panic(err)
17. }
18. }

20. func main() {
21. conn, err := af.Open("localhost", "root", "taosdata", "", 6030)
22. if err != nil {
23. log.Fatalln("fail to connect, err:", err)
24. }
25. defer conn.Close()
26. prepareDatabase(conn)
27. var lines = []string{
28. "meters.current 1648432611249 10.3 location=California.SanFrancisco groupid=2",
29. "meters.current 1648432611250 12.6 location=California.SanFrancisco groupid=2",
30. "meters.current 1648432611249 10.8 location=California.LosAngeles groupid=3",
31. "meters.current 1648432611250 11.3 location=California.LosAngeles groupid=3",
32. "meters.voltage 1648432611249 219 location=California.SanFrancisco groupid=2",
33. "meters.voltage 1648432611250 218 location=California.SanFrancisco groupid=2",
34. "meters.voltage 1648432611249 221 location=California.LosAngeles groupid=3",
35. "meters.voltage 1648432611250 217 location=California.LosAngeles groupid=3",
36. }

38. err = conn.OpenTSDBInsertTelnetLines(lines)
39. if err != nil {
40. log.Fatalln("insert error:", err)
41. }
42. }

view source code

1. const taos = require("@tdengine/client");

3. const conn = taos.connect({
4. host: "localhost",
5. });

7. const cursor = conn.cursor();

9. function createDatabase() {
10. cursor.execute("CREATE DATABASE test");
11. cursor.execute("USE test");
12. }

14. function insertData() {
15. const lines = [
16. "meters.current 1648432611249 10.3 location=California.SanFrancisco groupid=2",
17. "meters.current 1648432611250 12.6 location=California.SanFrancisco groupid=2",
18. "meters.current 1648432611249 10.8 location=California.LosAngeles groupid=3",
19. "meters.current 1648432611250 11.3 location=California.LosAngeles groupid=3",
20. "meters.voltage 1648432611249 219 location=California.SanFrancisco groupid=2",
21. "meters.voltage 1648432611250 218 location=California.SanFrancisco groupid=2",
22. "meters.voltage 1648432611249 221 location=California.LosAngeles groupid=3",
23. "meters.voltage 1648432611250 217 location=California.LosAngeles groupid=3",
24. ];
25. cursor.schemalessInsert(
26. lines,
27. taos.SCHEMALESS_PROTOCOL.TSDB_SML_TELNET_PROTOCOL,
28. taos.SCHEMALESS_PRECISION.TSDB_SML_TIMESTAMP_NOT_CONFIGURED
29. );
30. }

32. try {
33. createDatabase();
34. insertData();
35. } finally {
36. cursor.close();
37. conn.close();
38. }

view source code

1. using TDengineDriver;

3. namespace TDengineExample
4. {
5. internal class OptsTelnetExample
6. {
7. static void Main()
8. {
9. IntPtr conn = GetConnection();
10. try
11. {
12. PrepareDatabase(conn);
13. string[] lines = {
14. "meters.current 1648432611249 10.3 location=California.SanFrancisco groupid=2",
15. "meters.current 1648432611250 12.6 location=California.SanFrancisco groupid=2",
16. "meters.current 1648432611249 10.8 location=California.LosAngeles groupid=3",
17. "meters.current 1648432611250 11.3 location=California.LosAngeles groupid=3",
18. "meters.voltage 1648432611249 219 location=California.SanFrancisco groupid=2",
19. "meters.voltage 1648432611250 218 location=California.SanFrancisco groupid=2",
20. "meters.voltage 1648432611249 221 location=California.LosAngeles groupid=3",
21. "meters.voltage 1648432611250 217 location=California.LosAngeles groupid=3",
22. };
23. IntPtr res = TDengine.SchemalessInsert(conn, lines, lines.Length, (int)TDengineSchemalessProtocol.TSDB_SML_TELNET_PROTOCOL, (int)TDengineSchemalessPrecision.TSDB_SML_TIMESTAMP_NOT_CONFIGURED);
24. if (TDengine.ErrorNo(res) != 0)
25. {
26. throw new Exception("SchemalessInsert failed since " + TDengine.Error(res));
27. }
28. else
29. {
30. int affectedRows = TDengine.AffectRows(res);
31. Console.WriteLine($"SchemalessInsert success, affected {affectedRows} rows");
32. }
33. TDengine.FreeResult(res);
34. }
35. catch
36. {
37. TDengine.Close(conn);
38. }
39. }
40. static IntPtr GetConnection()
41. {
42. string host = "localhost";
43. short port = 6030;
44. string username = "root";
45. string password = "taosdata";
46. string dbname = "";
47. var conn = TDengine.Connect(host, username, password, dbname, port);
48. if (conn == IntPtr.Zero)
49. {
50. throw new Exception("Connect to TDengine failed");
51. }
52. else
53. {
54. Console.WriteLine("Connect to TDengine success");
55. }
56. return conn;
57. }

59. static void PrepareDatabase(IntPtr conn)
60. {
61. IntPtr res = TDengine.Query(conn, "CREATE DATABASE test");
62. if (TDengine.ErrorNo(res) != 0)
63. {
64. throw new Exception("failed to create database, reason: " + TDengine.Error(res));
65. }
66. res = TDengine.Query(conn, "USE test");
67. if (TDengine.ErrorNo(res) != 0)
68. {
69. throw new Exception("failed to change database, reason: " + TDengine.Error(res));
70. }
71. }
72. }
73. }

view source code

1. int main() {
2. TAOS *taos = taos_connect("localhost", "root", "taosdata", "", 6030);
3. if (taos == NULL) {
4. printf("failed to connect to server\n");
5. exit(EXIT_FAILURE);
6. }
7. executeSQL(taos, "DROP DATABASE IF EXISTS test");
8. executeSQL(taos, "CREATE DATABASE test");
9. executeSQL(taos, "USE test");
10. char *lines[] = {
11. "meters.current 1648432611249 10.3 location=California.SanFrancisco groupid=2",
12. "meters.current 1648432611250 12.6 location=California.SanFrancisco groupid=2",
13. "meters.current 1648432611249 10.8 location=California.LosAngeles groupid=3",
14. "meters.current 1648432611250 11.3 location=California.LosAngeles groupid=3",
15. "meters.voltage 1648432611249 219 location=California.SanFrancisco groupid=2",
16. "meters.voltage 1648432611250 218 location=California.SanFrancisco groupid=2",
17. "meters.voltage 1648432611249 221 location=California.LosAngeles groupid=3",
18. "meters.voltage 1648432611250 217 location=California.LosAngeles groupid=3",
19. };
20. TAOS_RES *res = taos_schemaless_insert(taos, lines, 8, TSDB_SML_TELNET_PROTOCOL, TSDB_SML_TIMESTAMP_NOT_CONFIGURED);
21. if (taos_errno(res) != 0) {
22. printf("failed to insert schema-less data, reason: %s\n", taos_errstr(res));
23. } else {
24. int affectedRow = taos_affected_rows(res);
25. printf("successfully inserted %d rows\n", affectedRow);
26. }

28. taos_free_result(res);
29. taos_close(taos);
30. taos_cleanup();
31. }
32. // output:
33. // successfully inserted 8 rows

view source code

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

1. taos> use test;
2. Database changed.

4. taos> show stables;
5. name              |
6. =================================
7. meters.current                 |
8. meters.voltage                 |
9. Query OK, 2 row(s) in set (0.002544s)

11. taos> select tbname, * from `meters.current`;
12. tbname             |           _ts            |           _value           | groupid |            location            |
13. ==================================================================================================================================
14. t_0e7bcfa21a02331c06764f275... | 2022-03-28 09:56:51.249 |              10.800000000 | 3       | California.LosAngeles                |
15. t_0e7bcfa21a02331c06764f275... | 2022-03-28 09:56:51.250 |              11.300000000 | 3       | California.LosAngeles                |
16. t_7e7b26dd860280242c6492a16... | 2022-03-28 09:56:51.249 |              10.300000000 | 2       | California.SanFrancisco               |
17. t_7e7b26dd860280242c6492a16... | 2022-03-28 09:56:51.250 |              12.600000000 | 2       | California.SanFrancisco               |
18. Query OK, 4 row(s) in set (0.005399s)

Query Examples

If you want query the data of location=California.LosAngeles groupid=3，here is the query SQL:

1. SELECT * FROM `meters.current` WHERE location = "California.LosAngeles" AND groupid = 3;