命名限制和约定

InfluxDB 3 对数据库、表、标签、字段和其他标识符具有特定的命名限制和约定。了解这些限制有助于确保您的数据模型能够与所有查询语言正确协同工作，并避免命名冲突。

数据库名称

数据库名称必须遵循以下限制

• 长度：最多 64 个字符
• 允许的字符：仅限字母数字字符（a-z、A-Z、0-9）、下划线（_）、连字符（-）和斜杠（/）
• 禁止的字符：不能包含空格、标点符号或其他特殊字符
• 起始字符：应以字母或数字开头，不应以下划线 (_) 开头
• 区分大小写：数据库名称区分大小写

示例

有效的数据库名称

mydb
sensor_data
prod-metrics
logs/application
webserver123

无效的数据库名称

my database        # Contains whitespace
sensor.data        # Contains period
app@server         # Contains special character
_internal          # Starts with underscore (not recommended)
very_long_database_name_that_exceeds_sixty_four_character_limit  # Too long

表（度量）名称

InfluxDB 3 Core 中的表名称遵循行协议度量命名规则

• 长度：没有明确限制，但性能会影响实际限制
• 允许的字符：字母数字字符（a-z、A-Z、0-9）、下划线（_）、连字符（-）
• 起始字符：应以字母或数字开头，不应以下划线 (_) 开头
• 区分大小写：表名称区分大小写
• 引用：当名称包含特殊字符或空格时，请使用双引号

示例

有效的表名称

temperature
cpu_usage
http-requests
sensor123
웹서버_메트릭스  # UTF-8 characters

查询中需要引用的名称

"my table"         # Contains whitespace
"cpu.usage"        # Contains period
"http@requests"    # Contains special character

无效的表名称

_internal          # Starts with underscore (not recommended)

标签键和字段键

标签键和字段键遵循以下限制

• 长度：没有明确限制，但较短的名称可以提高性能
• 允许的字符：字母数字字符（a-z、A-Z、0-9）、下划线（_）、连字符（-）
• 起始字符：应以字母或数字开头，不应以下划线 (_) 开头
• 区分大小写：标签和字段键区分大小写
• 引用：当名称包含特殊字符或空格时，请使用双引号

示例

有效的标签和字段键

host
region
temperature
cpu_usage
http-status
sensor123

查询中需要引用的键

"host name"        # Contains whitespace
"cpu.usage"        # Contains period
"http@status"      # Contains special character

无效的标签和字段键

_internal          # Starts with underscore (not recommended)

标签值和字段值

标签和字段值具有不同的限制

标签值

• 类型：必须是字符串
• 长度：没有明确限制
• 字符：允许任何 UTF-8 字符
• 区分大小写：标签值区分大小写
• 空值：允许（不包含在主键中）

字段值

• 类型：可以是整数、浮点数、字符串、布尔值或无符号整数
• 长度：字符串没有明确限制
• 字符：字符串允许任何 UTF-8 字符
• 区分大小写：字符串字段值区分大小写
• 空值：允许（但每行至少必须有一个非空字段）

特定于查询语言的注意事项

不同的查询语言有额外的命名要求

SQL 标识符

当使用 SQL 查询 InfluxDB 3 Core 时

• 未引用的标识符：必须以字母或下划线开头，仅包含字母、数字或下划线
• 引用的标识符：使用双引号（"）来表示包含特殊字符、空格的名称，或保留大小写
• 区分大小写：未引用的标识符不区分大小写，引用的标识符区分大小写
• 保留关键字：当用作标识符时，SQL 关键字必须被引用

InfluxQL 标识符

当使用 InfluxQL 查询 InfluxDB 3 Core 时

• 未引用的标识符：必须以 ASCII 字母或下划线开头，仅包含 ASCII 字母、数字或下划线
• 引用的标识符：使用双引号（"）来表示包含特殊字符或空格的名称
• 区分大小写：所有标识符都区分大小写
• 保留关键字：当用作标识符时，InfluxQL 关键字必须被引用
• 字符编码：支持 UTF-8 编码

保留的命名空间

系统保留前缀

以下前缀可能被保留供系统使用

• _（下划线）：可能被保留用于系统数据库、度量和字段键
• iox_：保留供 InfluxDB 内部元数据使用

常用保留关键字

避免在不加引号的情况下将这些常用保留关键字用作标识符

SQL 关键字（部分列表）

• SELECT, FROM, WHERE, GROUP, ORDER, BY
• CREATE, DROP, ALTER, INSERT, UPDATE, DELETE
• TABLE, DATABASE, INDEX, VIEW
• TIME, TIMESTAMP, INTERVAL

InfluxQL 关键字（部分列表）

• SELECT, FROM, WHERE, GROUP, ORDER, BY
• SHOW, DROP, CREATE, DELETE
• MEASUREMENT, TAG, FIELD, TIME
• LIMIT, OFFSET, SLIMIT, SOFFSET

如需完整列表，请参阅

• SQL 关键字
• InfluxQL 关键字

最佳实践

命名约定

1. 使用描述性名称：选择能清晰描述数据的名称
2. 保持名称简单：尽可能避免使用特殊字符
3. 使用一致的大小写：建立并遵循一致的大小写约定
4. 避免使用保留关键字：不要将 SQL 或 InfluxQL 关键字用作标识符
5. 使用下划线分隔：优先使用 cpu_usage 而不是 cpu-usage 或 cpuUsage

性能注意事项

1. 较短的名称：较短的名称可以提高查询性能并减少存储
2. 避免过高的标签基数：过多的唯一标签值会影响性能
3. 限制列数：使列数（标签 + 字段）保持合理
4. 一致的命名：在相关表之间使用相同的名称

示例命名策略

# Database naming
prod-metrics
dev-logs
sensor-data

# Table naming
cpu_usage
memory_utilization
http_requests
disk_io

# Tag keys
host
region
service
environment

# Field keys
value
count
duration_ms
bytes_sent

引用标识符

当标识符包含特殊字符、空格或保留关键字时，必须在查询中引用它们

SQL 示例

-- Quoted database and table names
SELECT * FROM "my-database"."my table";

-- Quoted column names
SELECT "cpu usage", "memory.available" FROM metrics;

-- Reserved keyword as identifier
SELECT "group" FROM "user-data";

InfluxQL 示例

-- Quoted measurement name
SELECT * FROM "http requests";

-- Quoted tag key with special characters
SELECT * FROM metrics WHERE "host.name" = 'server01';

-- Reserved keyword as field
SELECT "time" FROM "system-metrics";

命名问题疑难解答

常见错误模式

1. 未引用的特殊字符：在包含特殊字符的标识符周围使用双引号
2. 保留关键字冲突：在将保留关键字用作标识符时进行引用
3. 大小写敏感性问题：检查您所用查询语言的大小写敏感性规则
4. 下划线前缀警告：避免以“_”开头命名，以防止冲突

验证技巧

1. 在查询中测试名称：验证名称在目标查询语言中是否正常工作
2. 检查保留关键字：将名称与关键字列表进行交叉对照
3. 验证字符编码：确保 UTF-8 字符正确编码
4. 考虑未来兼容性：选择在不同查询语言中都能正常工作的名称