Naming restrictions and conventions

InfluxDB 3 has specific naming restrictions and conventions that apply to databases, tables, tags, fields, and other identifiers. Understanding these restrictions helps ensure your data model works correctly with all query languages and avoids naming conflicts.

Database names

Database names must follow these restrictions:

• Length: Maximum 64 characters
• Allowed characters: Only alphanumeric characters (a-z, A-Z, 0-9), underscore (_), dash (-), and forward-slash (/)
• Prohibited characters: Cannot contain whitespace, punctuation, or other special characters
• Starting character: Should start with a letter or number and should not start with underscore (_)
• Case sensitivity: Database names are case-sensitive

Examples

Valid database names:

mydb sensor_data prod-metrics logs/application webserver123

Invalid database names:

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

Table (measurement) names

Table names in InfluxDB Cloud Dedicated follow line protocol measurement naming rules:

• Length: No explicit limit, but practical limits apply for performance
• Allowed characters: Alphanumeric characters (a-z, A-Z, 0-9), underscore (_), dash (-)
• Starting character: Should start with a letter or number and should not start with underscore (_)
• Case sensitivity: Table names are case-sensitive
• Quoting: Use double quotes when names contain special characters or whitespace

Examples

Valid table names:

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

Names requiring quotes in queries:

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

Invalid table names:

_internal # Starts with underscore (not recommended)

Tag keys and field keys

Tag keys and field keys follow these restrictions:

• Length: No explicit limit, but shorter names improve performance
• Allowed characters: Alphanumeric characters (a-z, A-Z, 0-9), underscore (_), dash (-)
• Starting character: Should start with a letter or number and should not start with underscore (_)
• Case sensitivity: Tag and field keys are case-sensitive
• Quoting: Use double quotes when names contain special characters or whitespace

Examples

Valid tag and field keys:

host region temperature cpu_usage http-status sensor123

Keys requiring quotes in queries:

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

Invalid tag and field keys:

_internal # Starts with underscore (not recommended)

Tag values and field values

Tag and field values have different restrictions:

Tag values

• Type: Must be strings
• Length: No explicit limit
• Characters: Any UTF-8 characters allowed
• Case sensitivity: Tag values are case-sensitive
• Null values: Allowed (excluded from primary key)

Field values

• Type: Can be integers, floats, strings, booleans, or unsigned integers
• Length: No explicit limit for strings
• Characters: Any UTF-8 characters allowed for strings
• Case sensitivity: String field values are case-sensitive
• Null values: Allowed (but at least one field must be non-null per row)

Query language specific considerations

Different query languages have additional naming requirements:

SQL identifiers

When using SQL to query InfluxDB Cloud Dedicated:

• Unquoted identifiers: Must start with letter or underscore, contain only letters, digits, or underscores
• Quoted identifiers: Use double quotes (") for names with special characters, whitespace, or to preserve case
• Case sensitivity: Unquoted identifiers are case-insensitive, quoted identifiers are case-sensitive
• Reserved keywords: SQL keywords must be quoted when used as identifiers

InfluxQL identifiers

When using InfluxQL to query InfluxDB Cloud Dedicated:

• Unquoted identifiers: Must start with ASCII letter or underscore, contain only ASCII letters, digits, or underscores
• Quoted identifiers: Use double quotes (") for names with special characters or whitespace
• Case sensitivity: All identifiers are case-sensitive
• Reserved keywords: InfluxQL keywords must be quoted when used as identifiers
• Character encoding: UTF-8 encoding supported

Reserved namespaces

System reserved prefixes

The following prefixes may be reserved for system use:

• _ (underscore): May be reserved for system databases, measurements, and field keys
• iox_: Reserved for InfluxDB internal metadata

Common reserved keywords

Avoid using these common reserved keywords as identifiers without quoting:

SQL keywords (partial list):

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

InfluxQL keywords (partial list):

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

For complete lists, see:

• SQL keywords
• InfluxQL keywords

Best practices

Naming conventions

1. Use descriptive names: Choose names that clearly describe the data
2. Keep names simple: Avoid special characters when possible
3. Use consistent casing: Establish and follow a consistent case convention
4. Avoid reserved keywords: Don’t use SQL or InfluxQL keywords as identifiers
5. Use underscores for separation: Prefer cpu_usage over cpu-usage or cpuUsage

Performance considerations

1. Shorter names: Shorter names improve query performance and reduce storage
2. Avoid excessive tag cardinality: Too many unique tag values can impact performance
3. Limit column count: Keep the number of columns (tags + fields) reasonable
4. Consistent naming: Use the same names across related tables

Example naming strategy

# 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

Quoting identifiers

When identifiers contain special characters, whitespace, or reserved keywords, they must be quoted in queries:

SQL examples

-- 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 examples

-- 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";

Troubleshooting naming issues

Common error patterns

1. Unquoted special characters: Use double quotes around identifiers with special characters
2. Reserved keyword conflicts: Quote reserved keywords when used as identifiers
3. Case sensitivity issues: Check case sensitivity rules for your query language
4. Underscore prefix warnings: Avoid starting names with underscore to prevent conflicts

Validation tips

1. Test names in queries: Verify names work correctly in your target query language
2. Check for reserved keywords: Cross-reference names against keyword lists
3. Validate character encoding: Ensure UTF-8 characters are properly encoded
4. Consider future compatibility: Choose names that work across different query languages