---
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值。为了让用户可以指定生成的表名，可以通过在taos.cfg里配置 smlChildTableName 参数来指定。
举例如下：配置 smlChildTableName=tname 插入数据为 meters.current 1648432611250 11.3 tname=cpu1 location=California.LosAngeles groupid=3 则创建的表名为 cpu1，注意如果多行数据 tname 相同，但是后面的 tag_set 不同，则使用第一行自动建表时指定的 tag_set，其他的行会忽略）。
参考[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)
```
## 查询示例：
想要查询 location=California.LosAngeles groupid=3 的数据，可以通过如下sql:
select * from `meters.voltage` where location="California.LosAngeles" and groupid=3