---
sidebar_label: OpenTSDB 行协议
title: OpenTSDB 行协议
---

import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";
import JavaTelnet from "./_java_opts_telnet.mdx";
import PyTelnet from "./_py_opts_telnet.mdx";
import GoTelnet from "./_go_opts_telnet.mdx";
import RustTelnet from "./_rust_opts_telnet.mdx";
import NodeTelnet from "./_js_opts_telnet.mdx";
import CsTelnet from "./_cs_opts_telnet.mdx";
import CTelnet from "./_c_opts_telnet.mdx";

## 协议介绍

OpenTSDB 行协议同样采用一行字符串来表示一行数据。OpenTSDB 采用的是单列模型，因此一行只能包含一个普通数据列。标签列依然可以有多个。分为四部分，具体格式约定如下：

```txt
<metric> <timestamp> <value> <tagk_1>=<tagv_1>[ <tagk_n>=<tagv_n>]
```

- metric 将作为超级表名；
- timestamp 本行数据对应的时间戳。根据时间戳的长度自动识别时间精度。支持秒和毫秒两种时间精度；
- value 度量值，必须为一个数值。对应的列名是 “\_value”；
- 最后一部分是标签集， 用空格分隔不同标签， 所有标签自动转化为 NCHAR 数据类型。

例如：

```txt
meters.current 1648432611250 11.3 location=California.LosAngeles groupid=3
```

- 默认生产的子表名是根据规则生成的唯一 ID 值。用户也可以通过在client端的 taos.cfg 里配置 smlChildTableName 参数来指定某个标签值作为子表名。该标签值应该具有全局唯一性。举例如下：假设有个标签名为tname, 配置 smlChildTableName=tname, 插入数据为 meters.current 1648432611250 11.3 tname=cpu1 location=California.LosAngeles groupid=3 则创建的表名为 cpu1，注意如果多行数据 tname 相同，但是后面的 tag_set 不同，则使用第一行自动建表时指定的 tag_set，其他的行会忽略）。
- 由于sql建表表名不支持点号（.），所以schemaless也对点号（.）做了处理，自动替换为下划线（_）。
  参考 [OpenTSDB Telnet API 文档](http://opentsdb.net/docs/build/html/api_telnet/put.html)。

## 示例代码

<Tabs defaultValue="java" groupId="lang">
  <TabItem label="Java" value="java">
    <JavaTelnet />
  </TabItem>
  <TabItem label="Python" value="Python">
    <PyTelnet />
  </TabItem>
  <TabItem label="Go" value="go">
    <GoTelnet />
  </TabItem>
  <TabItem label="Node.js" value="nodejs">
    <NodeTelnet />
  </TabItem>
  <TabItem label="C#" value="csharp">
    <CsTelnet />
  </TabItem>
  <TabItem label="C" value="c">
    <CTelnet />
  </TabItem>
</Tabs>

以上示例代码会自动创建 2 个超级表， 每个超级表有 4 条数据。

```cmd
taos> USE test;
Database changed.

taos> SHOW STABLES;
              name              |
=================================
 meters_current                 |
 meters_voltage                 |
Query OK, 2 row(s) in set (0.002544s)

taos> SELECT TBNAME, * FROM `meters_current`;
             tbname             |           _ts            |           _value           | groupid |            location            |
==================================================================================================================================
 t_0e7bcfa21a02331c06764f275... | 2022-03-28 09:56:51.249 |              10.800000000 | 3       | California.LosAngeles                |
 t_0e7bcfa21a02331c06764f275... | 2022-03-28 09:56:51.250 |              11.300000000 | 3       | California.LosAngeles                |
 t_7e7b26dd860280242c6492a16... | 2022-03-28 09:56:51.249 |              10.300000000 | 2       | California.SanFrancisco               |
 t_7e7b26dd860280242c6492a16... | 2022-03-28 09:56:51.250 |              12.600000000 | 2       | California.SanFrancisco               |
Query OK, 4 row(s) in set (0.005399s)
```

## SQL 查询示例

`meters_current` 是插入数据的超级表名。

可以通过超级表的 TAG 来过滤数据，比如查询 `location=California.LosAngeles groupid=3` 可以通过如下 SQL：

```sql
SELECT * FROM `meters_current` WHERE location = "California.LosAngeles" AND groupid = 3;
```