InfluxDB Line Protocol

Introduction

In the InfluxDB Line protocol format, a single line of text is used to represent one row of data. Each line contains 4 parts as shown below.

  1. measurement,tag_set field_set timestamp
  • measurement will be used as the name of the STable Enter a comma (,) between measurement and tag_set.
  • tag_set will be used as tags, with format like <tag_key>=<tag_value>,<tag_key>=<tag_value> Enter a space between tag_set and field_set.
  • field_setwill be used as data columns, with format like <field_key>=<field_value>,<field_key>=<field_value> Enter a space between field_set and timestamp.
  • timestamp is the primary key timestamp corresponding to this row of data

For example:

  1. meters,location=California.LosAngeles,groupid=2 current=13.4,voltage=223,phase=0.29 1648432611249500
InfluxDB Line Protocol - 图1note
  • All the data in tag_set will be converted to NCHAR type automatically .
  • Each data in field_set must be self-descriptive for its data type. For example 1.2f32 means a value 1.2 of float type. Without the “f” type suffix, it will be treated as type double.
  • Multiple kinds of precision can be used for the timestamp field. Time precision can be from nanosecond (ns) to hour (h).
  • 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 created automatically. 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.
  • It is assumed that the order of field_set in a supertable is consistent, meaning that the first record contains all fields and subsequent records store fields in the same order. If the order is not consistent, set smlDataFormat in taos.cfg to false. Otherwise, data will be written out of order and a database error will occur.(smlDataFormat in taos.cfg default to false after version of 3.0.1.3)

For more details please refer to InfluxDB Line Protocol and TDengine Schemaless

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 LineProtocolExample {
  13.     // format: measurement,tag_set field_set timestamp
  14.     private static String[] lines = {
  15.             "meters,location=California.LosAngeles,groupid=2 current=11.8,voltage=221,phase=0.28 1648432611249000", // micro
  16.                                                                                                               // seconds
  17.             "meters,location=California.LosAngeles,groupid=2 current=13.4,voltage=223,phase=0.29 1648432611249500",
  18.             "meters,location=California.LosAngeles,groupid=3 current=10.8,voltage=223,phase=0.29 1648432611249300",
  19.             "meters,location=California.LosAngeles,groupid=3 current=11.3,voltage=221,phase=0.35 1648432611249800",
  20.     };
  22.     private static Connection getConnection() throws SQLException {
  23.         String jdbcUrl = "jdbc:TAOS://localhost:6030?user=root&password=taosdata";
  24.         return DriverManager.getConnection(jdbcUrl);
  25.     }
  27.     private static void createDatabase(Connection conn) throws SQLException {
  28.         try (Statement stmt = conn.createStatement()) {
  29.             // the default precision is ms (millisecond), but we use us(microsecond) here.
  30.             stmt.execute("CREATE DATABASE IF NOT EXISTS test PRECISION 'us'");
  31.             stmt.execute("USE test");
  32.         }
  33.     }
  35.     public static void main(String[] args) throws SQLException {
  36.         try (Connection conn = getConnection()) {
  37.             createDatabase(conn);
  38.             SchemalessWriter writer = new SchemalessWriter(conn);
  39.             writer.write(lines, SchemalessProtocolType.LINE, SchemalessTimestampType.MICRO_SECONDS);
  40.         }
  41.     }
  42. }

view source code

  1. import taos
  2. from taos import SmlProtocol, SmlPrecision
  4. lines = ["meters,location=California.LosAngeles,groupid=2 current=11.8,voltage=221,phase=0.28 1648432611249000",
  5.          "meters,location=California.LosAngeles,groupid=2 current=13.4,voltage=223,phase=0.29 1648432611249500",
  6.          "meters,location=California.LosAngeles,groupid=3 current=10.8,voltage=223,phase=0.29 1648432611249300",
  7.          "meters,location=California.LosAngeles,groupid=3 current=11.3,voltage=221,phase=0.35 1648432611249800",
  8.          ]
  11. def get_connection():
  12.     # create connection use firstEP in taos.cfg.
  13.     return taos.connect()
  16. def create_database(conn):
  17.     # the default precision is ms (microsecond), but we use us(microsecond) here.
  18.     conn.execute("CREATE DATABASE test precision 'us'")
  19.     conn.execute("USE test")
  22. def insert_lines(conn):
  23.     affected_rows = conn.schemaless_insert(
  24.         lines, SmlProtocol.LINE_PROTOCOL, SmlPrecision.MICRO_SECONDS)
  25.     print(affected_rows)  # 8
  28. if __name__ == '__main__':
  29.     connection = get_connection()
  30.     try:
  31.         create_database(connection)
  32.         insert_lines(connection)
  33.     finally:
  34.         connection.close()

view source code

  1. package main
  3. import (
  4.     "fmt"
  5.     "log"
  7.     "github.com/taosdata/driver-go/v3/af"
  8. )
  10. func prepareDatabase(conn *af.Connector) {
  11.     _, err := conn.Exec("CREATE DATABASE test")
  12.     if err != nil {
  13.         panic(err)
  14.     }
  15.     _, err = conn.Exec("USE test")
  16.     if err != nil {
  17.         panic(err)
  18.     }
  19. }
  21. func main() {
  22.     conn, err := af.Open("localhost", "root", "taosdata", "", 6030)
  23.     if err != nil {
  24.         fmt.Println("fail to connect, err:", err)
  25.     }
  26.     defer conn.Close()
  27.     prepareDatabase(conn)
  28.     var lines = []string{
  29.         "meters,location=California.LosAngeles,groupid=2 current=11.8,voltage=221,phase=0.28 1648432611249",
  30.         "meters,location=California.LosAngeles,groupid=2 current=13.4,voltage=223,phase=0.29 1648432611250",
  31.         "meters,location=California.LosAngeles,groupid=3 current=10.8,voltage=223,phase=0.29 1648432611249",
  32.         "meters,location=California.LosAngeles,groupid=3 current=11.3,voltage=221,phase=0.35 1648432611250",
  33.     }
  35.     err = conn.InfluxDBInsertLines(lines, "ms")
  36.     if err != nil {
  37.         log.Fatalln("insert error:", err)
  38.     }
  39. }

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,location=California.LosAngeles,groupid=2 current=11.8,voltage=221,phase=0.28 1648432611249",
  17.     "meters,location=California.LosAngeles,groupid=2 current=13.4,voltage=223,phase=0.29 1648432611250",
  18.     "meters,location=California.LosAngeles,groupid=3 current=10.8,voltage=223,phase=0.29 1648432611249",
  19.     "meters,location=California.LosAngeles,groupid=3 current=11.3,voltage=221,phase=0.35 1648432611250",
  20.   ];
  21.   cursor.schemalessInsert(
  22.     lines,
  23.     taos.SCHEMALESS_PROTOCOL.TSDB_SML_LINE_PROTOCOL,
  24.     taos.SCHEMALESS_PRECISION.TSDB_SML_TIMESTAMP_MILLI_SECONDS
  25.   );
  26. }
  28. try {
  29.   createDatabase();
  30.   insertData();
  31. } finally {
  32.   cursor.close(); 
  33.   conn.close();
  34. }

view source code

  1. using TDengineDriver;
  3. namespace TDengineExample
  4. {
  5.     internal class InfluxDBLineExample
  6.     {
  7.         static void Main()
  8.         {
  9.             IntPtr conn = GetConnection();
  10.             PrepareDatabase(conn);
  11.             string[] lines = {
  12.                 "meters,location=California.LosAngeles,groupid=2 current=11.8,voltage=221,phase=0.28 1648432611249",
  13.                 "meters,location=California.LosAngeles,groupid=2 current=13.4,voltage=223,phase=0.29 1648432611250",
  14.                 "meters,location=California.LosAngeles,groupid=3 current=10.8,voltage=223,phase=0.29 1648432611249",
  15.                 "meters,location=California.LosAngeles,groupid=3 current=11.3,voltage=221,phase=0.35 1648432611250"
  16.             };
  17.             IntPtr res = TDengine.SchemalessInsert(conn, lines, lines.Length, (int)TDengineSchemalessProtocol.TSDB_SML_LINE_PROTOCOL, (int)TDengineSchemalessPrecision.TSDB_SML_TIMESTAMP_MILLI_SECONDS);
  18.             if (TDengine.ErrorNo(res) != 0)
  19.             {
  20.                 throw new Exception("SchemalessInsert failed since " + TDengine.Error(res));
  21.             }
  22.             else
  23.             {
  24.                 int affectedRows = TDengine.AffectRows(res);
  25.                 Console.WriteLine($"SchemalessInsert success, affected {affectedRows} rows");
  26.             }
  27.             TDengine.FreeResult(res);
  29.         }
  30.         static IntPtr GetConnection()
  31.         {
  32.             string host = "localhost";
  33.             short port = 6030;
  34.             string username = "root";
  35.             string password = "taosdata";
  36.             string dbname = "";
  37.             var conn = TDengine.Connect(host, username, password, dbname, port);
  38.             if (conn == IntPtr.Zero)
  39.             {
  40.                 throw new Exception("Connect to TDengine failed");
  41.             }
  42.             else
  43.             {
  44.                 Console.WriteLine("Connect to TDengine success");
  45.             }
  46.             return conn;
  47.         }
  49.         static void PrepareDatabase(IntPtr conn)
  50.         {
  51.             IntPtr res = TDengine.Query(conn, "CREATE DATABASE test");
  52.             if (TDengine.ErrorNo(res) != 0)
  53.             {
  54.                 throw new Exception("failed to create database, reason: " + TDengine.Error(res));
  55.             }
  56.             res = TDengine.Query(conn, "USE test");
  57.             if (TDengine.ErrorNo(res) != 0)
  58.             {
  59.                 throw new Exception("failed to change database, reason: " + TDengine.Error(res));
  60.             }
  61.         }
  63.     }
  65. }

view source code

  1. int main() {
  2.   TAOS *taos = taos_connect("localhost", "root", "taosdata", "", 0);
  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[] = {"meters,location=California.LosAngeles,groupid=2 current=11.8,voltage=221,phase=0.28 1648432611249",
  11.                    "meters,location=California.LosAngeles,groupid=2 current=13.4,voltage=223,phase=0.29 1648432611250",
  12.                    "meters,location=California.LosAngeles,groupid=3 current=10.8,voltage=223,phase=0.29 1648432611249",
  13.                    "meters,location=California.LosAngeles,groupid=3 current=11.3,voltage=221,phase=0.35 1648432611250"};
  14.   TAOS_RES *res = taos_schemaless_insert(taos, lines, 4, TSDB_SML_LINE_PROTOCOL, TSDB_SML_TIMESTAMP_MILLI_SECONDS);
  15.   if (taos_errno(res) != 0) {
  16.     printf("failed to insert schema-less data, reason: %s\n", taos_errstr(res));
  17.   } else {
  18.     int affectedRows = taos_affected_rows(res);
  19.     printf("successfully inserted %d rows\n", affectedRows);
  20.   }
  21.   taos_free_result(res);
  22.   taos_close(taos);
  23.   taos_cleanup();
  24. }
  25. // output:
  26. // successfully inserted 4 rows

view source code

Query Examples

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

  1. SELECT * FROM meters WHERE location = "California.LosAngeles" AND groupid = 2;