管理存储桶模式

使用显式存储桶模式来强制执行数据的列名称、标签、字段和数据类型。显式存储桶模式确保测量值具有特定的列和数据类型，并防止不符合规范的写入请求。

创建存储桶模式后，您可以开始将数据写入存储桶。

• 创建显式存储桶和模式
  • 使用influx CLI创建存储桶模式
  • 使用InfluxDB HTTP API创建存储桶模式
  • 编写有效的模式
• 查看存储桶模式类型和模式
  • 在InfluxDB UI中查看模式类型和模式
  • 使用influx CLI查看模式类型和模式
  • 使用InfluxDB HTTP API查看模式类型和模式
• 更新存储桶模式
  • 使用influx CLI更新存储桶模式
  • 使用InfluxDB HTTP API更新存储桶模式
• 故障排除存储桶模式错误
• 故障排除写入错误

创建显式存储桶和模式

要为您的数据创建显式存储桶和模式，请执行以下操作

1. 如果您还没有，请创建一个强制执行显式模式的存储桶。
2. 创建存储桶模式.

创建存储桶模式

在显式存储桶中，您预先定义了测量值的测量模式，包括测量值的列名称、标签、字段和数据类型。测量模式具有以下属性

• name：测量名称。名称必须与数据中的测量列匹配，遵守命名规则，并在存储桶中是唯一的。
• columns：测量值的列定义列表。

有关测量名称和列的规则，请参阅如何编写有效的模式。

使用influx CLI或InfluxDB HTTP API为测量创建显式存储桶模式。

• 使用influx CLI创建存储桶模式
• 使用InfluxDB HTTP API创建存储桶模式

使用influx CLI创建存储桶模式

1. 使用您的文本编辑器为要添加的每个测量值创建一个模式列文件。格式化为CSV、JSON或换行分隔JSON (NDJSON)，如下例所示

   usage-resources.csv usage-cpu.json sensor.ndjson

   name,type,dataType
   time,timestamp,
   host,tag,
   service,tag,
   fsRead,field,float
   fsWrite,field,float
   

   [
     {"name": "time", "type": "timestamp"},
     {"name": "service", "type": "tag"},
     {"name": "host", "type": "tag"},
     {"name": "usage_user", "type": "field", "dataType": "float"},
     {"name": "usage_system", "type": "field", "dataType": "float"}
   ]
   

   {"name": "time", "type": "timestamp"}
   {"name": "service", "type": "tag"}
   {"name": "sensor", "type": "tag"}
   {"name": "temperature", "type": "field", "dataType": "float"}
   {"name": "humidity", "type": "field", "dataType": "float"}
   

2. 使用influx bucket-schema create命令定义一个显式存储桶测量模式。在您的命令中指定以下标志的值

   • --name: 测量名称。
   • --columns-file: 包含您测量 列定义 的文件的存储位置。

   例如，以下每个命令都将唯一的测量模式添加到存储桶中

   influx bucket-schema create \
   --bucket my_explicit_bucket \
   --name usage_resources \
   --columns-file usage-resources.csv
   
   influx bucket-schema create \
   --bucket my_explicit_bucket \
   --name usage_cpu \
   --columns-file usage-cpu.json
   
   influx bucket-schema create \
   --bucket my_explicit_bucket \
   --name sensor \
   --columns-file sensor.ndjson     
   

使用InfluxDB HTTP API创建存储桶模式

向 HTTP API 的 /api/v2/buckets/{BUCKET_ID}/schema/measurements 端点 发送请求，并在请求正文中设置以下属性

• name: 测量名称。
• columns: 您测量 列定义 的数组。

例如，以下请求定义了 airSensors 测量的 显式 存储桶测量模式

POST https://cloud2.influxdata.com/api/v2/buckets/{BUCKET_ID}/schema/measurements

{
	"name": "airSensors",
	"columns": [
          {"name": "time", "type": "timestamp"},
          {"name": "sensorId", "type": "tag"},
          {"name": "temperature", "type": "field"},
          {"name": "humidity", "type": "field", "dataType": "float"}
	]
}

编写有效的模式

为确保您的模式有效，请查阅 InfluxDB 数据元素。在创建您的模式列文件时，请遵循以下规则

1. 使用有效的测量和列名称，它们
   • 在模式中是唯一的
   • 长度为 1 到 128 个字符
   • 仅包含 Unicode 字符
   • 不以下划线 _ 开头
   • 不以数字 0-9 开头
   • 不包含单引号 ' 或双引号 "
2. 包含一个具有 timestamp 类型的列。
3. 包含至少一个具有 field 类型（没有字段，则没有时间序列数据）的列，如下例所示

有效：具有 timestamp 和 field 列的模式。

[
  {"name":"time","type":"timestamp"},
  {"name":"fsWrite","type":"field"}
]

无效：没有 field 列的模式。

[
  {"name":"time","type":"timestamp"},
  {"name":"host","type":"tag"}
]

默认的 字段数据类型 是 string。要设置字段列的数据类型，请提供 dataType 属性和有效的 字段数据类型 (string、float、integer 或 boolean)，如下例所示

[
  {"name":"time","type":"timestamp"},
  {"name":"fsWrite","type":"field","dataType":"float"}
]

查看存储桶模式类型和模式

使用 InfluxDB UI、influx CLI 或 InfluxDB HTTP API 查看存储桶的模式类型和模式。

在InfluxDB UI中查看模式类型和模式

1. 查看桶.
2. 在存储桶列表中，在每个存储桶名称后的元数据中查看 Schema Type。
3. 具有 Schema Type: Explicit 的存储桶显示 Show Schema 按钮。单击 Show Schema 以查看存储桶的测量模式。

使用influx CLI查看模式类型和模式

要列出存储桶的模式，请使用 influx bucket-schema list 命令。要查看模式列定义和元数据，请指定 --json 标志。

使用InfluxDB HTTP API查看模式类型和模式

要列出存储桶的模式，请向 InfluxDB HTTP 的 /api/v2/buckets/{BUCKET_ID}/schema/measurements 端点 发送请求

GET https://cloud2.influxdata.com/api/v2/buckets/{BUCKET_ID}/schema/measurements

更新存储桶模式

使用 influx CLI 或 InfluxDB HTTP API 向显式存储桶模式添加新列。您不能修改或删除存储桶模式中的列。

• 使用influx CLI更新存储桶模式
• 使用InfluxDB HTTP API更新存储桶模式

使用influx CLI更新存储桶模式

1. 查看现有的测量模式 并将 columns 列表保存到文件中。

2. 在您的文本编辑器或终端中，将上一步骤中的新列添加到列表中。以下示例将列 CO2 添加到原始的 sensor.ndjson 模式文件中

   # sensor.ndjson
   {"name": "time", "type": "timestamp"}
       {"name": "service", "type": "tag"}
       {"name": "sensor", "type": "tag"}
       {"name": "temperature", "type": "field", "dataType": "float"}
       {"name": "humidity", "type": "field", "dataType": "float"}
   
   

   echo '{"name": "CO2", "type": "field", "dataType": "float"}' >> sensor.ndjson
   

3. 要更新存储桶模式，请使用 influx bucket-schema update 命令 并使用 --columns-file 标志指定列文件。

   influx bucket-schema update \
     --bucket my_explicit_bucket \
     --name sensor \
     --columns-file sensor.ndjson
   

使用InfluxDB HTTP API更新存储桶模式

1. 查看现有的测量模式 并复制 columns 列表。

2. 向 HTTP API 的 /api/v2/buckets/{BUCKET_ID}/schema/measurements/{MEASUREMENT_ID} 端点 发送请求。

   在请求体中，将 columns 属性设置为测量模式的老版和新版列定义的列表——例如，以下请求将新列 CO2 添加到上一步骤检索到的 columns 中

   PATCH https://cloud2.influxdata.com/api/v2/buckets/{BUCKET_ID}/schema/measurements/{MEASUREMENT_ID}

   {
     "columns": [
             {"name": "time", "type": "timestamp"},
             {"name": "sensorId", "type": "tag"},
             {"name": "temperature", "type": "field"},
             {"name": "humidity", "type": "field", "dataType": "float"},
             {"name": "CO2", "type": "field", "dataType": "float"}
       ]
   }
   

故障排除存储桶模式错误

找不到桶

创建和更新桶模式需要桶的 WRITE 权限。
如果您的 API 令牌 没有桶的 WRITE 权限，InfluxDB 返回以下错误

Error: bucket "my_explicit_bucket" not found

创建测量失败

桶中的每个测量可以有一个模式。如果您尝试为现有测量创建模式，InfluxDB 会拒绝新模式并返回以下错误

Error: failed to create measurement: 422 Unprocessable Entity

故障排除写入错误

InfluxDB 返回错误的原因如下

• 写入请求中的数据不符合定义的模式。
• 写入请求中的数据没有为桶定义模式。
• 写入请求中的数据有无效的语法。

要解决失败和部分写入，请参阅如何 排查写入问题。