Documentation

InfluxDB OSS v2

Get started writing data

  • 2 / 5

InfluxDB 提供了许多不同的选项用于摄取或写入数据，包括以下内容

本教程将引导您了解使用行协议将数据写入 InfluxDB 的基本原理。如果使用 Telegraf 或 InfluxDB 客户端库等工具，它们将为您构建行协议，但了解行协议的工作原理是很有好处的。

Line protocol

所有写入 InfluxDB 的数据都使用行协议写入，这是一种基于文本的格式，可让您提供必要的信息以将数据点写入 InfluxDB。本教程涵盖了行协议的基础知识，但有关详细信息，请参阅行协议参考。

行协议元素

行协议的每一行都包含以下元素

* 必需
  • * measurement（测量）：标识要将数据存储在其中的measurement（测量）的字符串。
  • tag set（标签集）：逗号分隔的键值对列表，每个键值对代表一个标签。标签键和值是不带引号的字符串。空格、逗号和等号字符必须转义。
  • * field set（字段集）：逗号分隔的键值对列表，每个键值对代表一个字段。字段键是不带引号的字符串。空格和逗号必须转义。字段值可以是 strings（字符串）（带引号）、floats（浮点数）、integers（整数）、unsigned integers（无符号整数）或 booleans（布尔值）。
  • timestamp（时间戳）：与数据关联的 Unix 时间戳。 InfluxDB 支持纳秒级精度。如果时间戳的精度不是纳秒，则在将数据写入 InfluxDB 时必须指定精度。

行协议元素解析

  • measurement（测量）：第一个未转义的逗号之前的第一个空格之前的所有内容。
  • tag set（标签集）：第一个未转义的逗号和第一个未转义的空格之间的键值对。
  • field set（字段集）：第一个和第二个未转义的空格之间的键值对。
  • timestamp（时间戳）：第二个未转义的空格之后的整数值。
  • 行由换行符 (\n) 分隔。行协议对空格敏感。

myMeasurement,tag1=val1,tag2=val2 field1="v1",field2=1i 0000000000000000000

有关模式设计建议，请参阅 InfluxDB 模式设计。

构建行协议

在基本了解行协议之后，您现在可以构建行协议并将数据写入 InfluxDB。考虑一个用例，您从家中的传感器收集数据。每个传感器收集温度、湿度和一氧化碳读数。要收集此数据，请使用以下模式

  • measurement（测量）：home
    • tags（标签）
      • room：Living Room 或 Kitchen
    • fields（字段）
      • temp：温度，单位为 °C（浮点数）
      • hum：湿度百分比（浮点数）
      • co：一氧化碳，单位为百万分之几 (ppm)（整数）
    • timestamp（时间戳）：秒精度的 Unix 时间戳

数据从 2022-01-01T08:00:00Z (UTC) 开始每小时收集一次，直到 2022-01-01T20:00:00Z (UTC)。生成的行协议将如下所示

家庭传感器数据行协议
home,room=Living\ Room temp=21.1,hum=35.9,co=0i 1641024000
home,room=Kitchen temp=21.0,hum=35.9,co=0i 1641024000
home,room=Living\ Room temp=21.4,hum=35.9,co=0i 1641027600
home,room=Kitchen temp=23.0,hum=36.2,co=0i 1641027600
home,room=Living\ Room temp=21.8,hum=36.0,co=0i 1641031200
home,room=Kitchen temp=22.7,hum=36.1,co=0i 1641031200
home,room=Living\ Room temp=22.2,hum=36.0,co=0i 1641034800
home,room=Kitchen temp=22.4,hum=36.0,co=0i 1641034800
home,room=Living\ Room temp=22.2,hum=35.9,co=0i 1641038400
home,room=Kitchen temp=22.5,hum=36.0,co=0i 1641038400
home,room=Living\ Room temp=22.4,hum=36.0,co=0i 1641042000
home,room=Kitchen temp=22.8,hum=36.5,co=1i 1641042000
home,room=Living\ Room temp=22.3,hum=36.1,co=0i 1641045600
home,room=Kitchen temp=22.8,hum=36.3,co=1i 1641045600
home,room=Living\ Room temp=22.3,hum=36.1,co=1i 1641049200
home,room=Kitchen temp=22.7,hum=36.2,co=3i 1641049200
home,room=Living\ Room temp=22.4,hum=36.0,co=4i 1641052800
home,room=Kitchen temp=22.4,hum=36.0,co=7i 1641052800
home,room=Living\ Room temp=22.6,hum=35.9,co=5i 1641056400
home,room=Kitchen temp=22.7,hum=36.0,co=9i 1641056400
home,room=Living\ Room temp=22.8,hum=36.2,co=9i 1641060000
home,room=Kitchen temp=23.3,hum=36.9,co=18i 1641060000
home,room=Living\ Room temp=22.5,hum=36.3,co=14i 1641063600
home,room=Kitchen temp=23.1,hum=36.6,co=22i 1641063600
home,room=Living\ Room temp=22.2,hum=36.4,co=17i 1641067200
home,room=Kitchen temp=22.7,hum=36.5,co=26i 1641067200

将行协议写入 InfluxDB

使用 InfluxDB UI、influx CLI 或 InfluxDB API 将上面的行协议写入 InfluxDB。

InfluxDB UI influx CLI InfluxDB API

  1. 在浏览器中访问 localhost:8086

    以登录并访问 InfluxDB UI。

  2. 使用左侧导航栏导航到 Load Data（加载数据） > Buckets（Bucket）。

Load Data

  1. 在要写入数据的 bucket 上，单击 Add Data（添加数据），然后选择 Line Protocol（行协议）。
  2. 选择 Enter Manually（手动输入）。
  3. Important（重要） 在行协议文本字段上方的 Precision（精度）下拉菜单中，选择 Seconds（秒）（以匹配行协议中时间戳的精度）。
  4. 复制上面的行协议并将其粘贴到行协议文本字段中。
  5. 单击 Write Data（写入数据）。

UI 将确认数据已成功写入。

  1. 如果您尚未执行此操作，请下载、安装和配置 influx CLI。

  2. 使用 influx write 命令将上面的行协议写入 InfluxDB。

    提供以下内容:

    • 带有要写入的 bucket 名称或 ID 的 -b, --bucket 或 --bucket-id 标志。
    • 带有时间戳精度的 -p, --precision 标志 (s)。
    • 字符串编码的行协议。
    • 连接和身份验证凭据
    influx write \
  --bucket get-started \
  --precision s "
home,room=Living\ Room temp=21.1,hum=35.9,co=0i 1641024000
home,room=Kitchen temp=21.0,hum=35.9,co=0i 1641024000
home,room=Living\ Room temp=21.4,hum=35.9,co=0i 1641027600
home,room=Kitchen temp=23.0,hum=36.2,co=0i 1641027600
home,room=Living\ Room temp=21.8,hum=36.0,co=0i 1641031200
home,room=Kitchen temp=22.7,hum=36.1,co=0i 1641031200
home,room=Living\ Room temp=22.2,hum=36.0,co=0i 1641034800
home,room=Kitchen temp=22.4,hum=36.0,co=0i 1641034800
home,room=Living\ Room temp=22.2,hum=35.9,co=0i 1641038400
home,room=Kitchen temp=22.5,hum=36.0,co=0i 1641038400
home,room=Living\ Room temp=22.4,hum=36.0,co=0i 1641042000
home,room=Kitchen temp=22.8,hum=36.5,co=1i 1641042000
home,room=Living\ Room temp=22.3,hum=36.1,co=0i 1641045600
home,room=Kitchen temp=22.8,hum=36.3,co=1i 1641045600
home,room=Living\ Room temp=22.3,hum=36.1,co=1i 1641049200
home,room=Kitchen temp=22.7,hum=36.2,co=3i 1641049200
home,room=Living\ Room temp=22.4,hum=36.0,co=4i 1641052800
home,room=Kitchen temp=22.4,hum=36.0,co=7i 1641052800
home,room=Living\ Room temp=22.6,hum=35.9,co=5i 1641056400
home,room=Kitchen temp=22.7,hum=36.0,co=9i 1641056400
home,room=Living\ Room temp=22.8,hum=36.2,co=9i 1641060000
home,room=Kitchen temp=23.3,hum=36.9,co=18i 1641060000
home,room=Living\ Room temp=22.5,hum=36.3,co=14i 1641063600
home,room=Kitchen temp=23.1,hum=36.6,co=22i 1641063600
home,room=Living\ Room temp=22.2,hum=36.4,co=17i 1641067200
home,room=Kitchen temp=22.7,hum=36.5,co=26i 1641067200
"

要使用 InfluxDB HTTP API 将数据写入 InfluxDB，请使用 POST 请求方法向 InfluxDB API /api/v2/write 端点发送请求。

POST http://localhost:8086/api/v2/write

在请求中包含以下内容

  • 标头:
    • Authorization: Token <INFLUX_TOKEN>
    • Content-Type: text/plain; charset=utf-8
    • Accept: application/json
  • 查询参数:
    • org: InfluxDB 组织名称
    • bucket: InfluxDB bucket 名称
    • precision: 时间戳精度（默认为 ns）
  • Request body（请求正文）：纯文本格式的行协议

以下示例使用 cURL 和 InfluxDB API 将行协议写入 InfluxDB

export INFLUX_HOST=http://localhost:8086
export INFLUX_ORG=<YOUR_INFLUXDB_ORG>
export INFLUX_TOKEN=<YOUR_INFLUXDB_API_TOKEN>

curl --request POST \
"$INFLUX_HOST/api/v2/write?org=$INFLUX_ORG&bucket=get-started&precision=s" \
  --header "Authorization: Token $INFLUX_TOKEN" \
  --header "Content-Type: text/plain; charset=utf-8" \
  --header "Accept: application/json" \
  --data-binary "
home,room=Living\ Room temp=21.1,hum=35.9,co=0i 1641024000
home,room=Kitchen temp=21.0,hum=35.9,co=0i 1641024000
home,room=Living\ Room temp=21.4,hum=35.9,co=0i 1641027600
home,room=Kitchen temp=23.0,hum=36.2,co=0i 1641027600
home,room=Living\ Room temp=21.8,hum=36.0,co=0i 1641031200
home,room=Kitchen temp=22.7,hum=36.1,co=0i 1641031200
home,room=Living\ Room temp=22.2,hum=36.0,co=0i 1641034800
home,room=Kitchen temp=22.4,hum=36.0,co=0i 1641034800
home,room=Living\ Room temp=22.2,hum=35.9,co=0i 1641038400
home,room=Kitchen temp=22.5,hum=36.0,co=0i 1641038400
home,room=Living\ Room temp=22.4,hum=36.0,co=0i 1641042000
home,room=Kitchen temp=22.8,hum=36.5,co=1i 1641042000
home,room=Living\ Room temp=22.3,hum=36.1,co=0i 1641045600
home,room=Kitchen temp=22.8,hum=36.3,co=1i 1641045600
home,room=Living\ Room temp=22.3,hum=36.1,co=1i 1641049200
home,room=Kitchen temp=22.7,hum=36.2,co=3i 1641049200
home,room=Living\ Room temp=22.4,hum=36.0,co=4i 1641052800
home,room=Kitchen temp=22.4,hum=36.0,co=7i 1641052800
home,room=Living\ Room temp=22.6,hum=35.9,co=5i 1641056400
home,room=Kitchen temp=22.7,hum=36.0,co=9i 1641056400
home,room=Living\ Room temp=22.8,hum=36.2,co=9i 1641060000
home,room=Kitchen temp=23.3,hum=36.9,co=18i 1641060000
home,room=Living\ Room temp=22.5,hum=36.3,co=14i 1641063600
home,room=Kitchen temp=23.1,hum=36.6,co=22i 1641063600
home,room=Living\ Room temp=22.2,hum=36.4,co=17i 1641067200
home,room=Kitchen temp=22.7,hum=36.5,co=26i 1641067200
"

查看写入的数据

Congratulations!（恭喜！） 您已将数据写入 InfluxDB。上面描述的方法是手动写入数据的方式，但还有其他选项可用

现在数据已存储在 InfluxDB 中，让我们查询它。

Was this page helpful?

Thank you for your feedback!

© 2025 InfluxData, Inc.

What is your InfluxDB OSS URL?

Customize your InfluxDB OSS URL and we’ll update code examples for you.

Default
Custom

For more information, see InfluxDB OSS URLs.

Thank you for your feedback!

Let us know what we can do better

Thank you!

No thanks

The future of Flux

Flux is going into maintenance mode. You can continue using it as you currently are without any changes to your code.

Read more

Now Generally Available

InfluxDB 3 Core and Enterprise

Start fast. Scale faster.

Get the Updates

InfluxDB 3 Core is an open source, high-speed, recent-data engine that collects and processes data in real-time and persists it to local disk or object storage. InfluxDB 3 Enterprise builds on Core’s foundation, adding high availability, read replicas, enhanced security, and data compaction for faster queries and optimized storage. A free tier of InfluxDB 3 Enterprise is available for non-commercial at-home or hobbyist use.

For more information, check out