Influxdata
/
docs-v2
mirror of https://github.com/influxdata/docs-v2.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Merge pull request #6214 from influxdata/jts-dar-515-naming 

feat(v3): Add naming restrictions reference and guidelines:
fix/api-docs-query-sql-field-names
Jason Stirnaman 2025-07-17 15:26:53 -05:00 committed by GitHub
parent 81c9d0ba76 b8598c7007
commit 7bccad9dcf
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
12 changed files with 496 additions and 26 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

57
content/influxdb3/cloud-dedicated/admin/databases/create.md
View File

@ -30,6 +30,7 @@ related:
- /influxdb3/cloud-dedicated/reference/cli/influxctl/database/create/
- /influxdb3/cloud-dedicated/admin/custom-partitions/
- /influxdb3/cloud-dedicated/reference/api/
- /influxdb3/cloud-dedicated/reference/naming-restrictions/
---
Use the Admin UI, the [`influxctl` CLI](/influxdb3/cloud-dedicated/reference/cli/influxctl/),
@ -306,11 +307,42 @@ For example, `2592000000000` means 30 days. A value of `0` keeps data indefinite
Database names must adhere to the following naming restrictions:
- Cannot contain whitespace, punctuation, or special characters.
Only alphanumeric, underscore (`_`), dash (`-`), and forward-slash
(`/`) characters are permitted.
- Should not start with an underscore (`_`).
- Maximum length of 64 characters.
- **Length**: Maximum 64 characters
- **Allowed characters**: 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
> [!Caution]
> #### Underscore prefix reserved for system use
>
> Names starting with an underscore (`_`) may be reserved for InfluxDB system use.
> While {{% product-name %}} might not explicitly reject these names, using them risks
> conflicts with current or future system features and may result in
> unexpected behavior or data loss.
#### Valid database name examples
```text
mydb
sensor_data
prod-metrics
logs/application
webserver123
```
#### Invalid database name examples
```text
my database # Contains whitespace
sensor.data # Contains period
app@server # Contains special character
_internal # Starts with underscore (reserved)
very_long_database_name_that_exceeds_sixty_four_character_limit # Too long
```
For comprehensive information about naming restrictions for all InfluxDB identifiers,
see [Naming restrictions and conventions](/influxdb3/cloud-dedicated/reference/naming-restrictions/).
### InfluxQL DBRP naming convention
@ -320,8 +352,11 @@ In {{% product-name %}}, databases and retention policies have been merged into
_databases_, where databases have a retention period, but retention policies
are no longer part of the data model.
Because InfluxQL uses the 1.x data model, a database must be mapped to a v1
database and retention policy (DBRP) to be queryable with InfluxQL.
**When naming a database that you want to query with InfluxQL**, use the following
naming convention:
naming convention to automatically map v1 DBRP combinations to an {{% product-name %}} database:
```text
database_name/retention_policy_name
@ -354,6 +389,16 @@ Your database's table limit can be raised beyond the default limit of 500.
InfluxData has production examples of clusters with 20,000+ active tables across
multiple databases.
> [!Warning]
> #### Excessive table counts can impact performance and stability
>
> High table counts, especially those concurrently receiving writes and queries,
> can increase catalog overhead which can affect performance and stability.
> What constitutes "excessive" depends on multiple factors such as query latency
> requirements, write bandwidth, and cluster capacity to handle rapid backfills.
> If you're considering more than doubling the default limit, test your
> configuration thoroughly.
Increasing your table limit affects your {{% product-name omit=" Clustered" %}}
cluster in the following ways:

2
content/influxdb3/cloud-dedicated/admin/tables/create.md
View File

@ -77,6 +77,7 @@ and managing tables.
{{< img-hd src="/img/influxdb3/cloud-dedicated-admin-ui-create-table-default.png" alt="Create table dialog" />}}
6. In the **Create table** dialog, provide a **Table name**.
For naming restrictions, see [Naming restrictions and conventions](/influxdb3/cloud-dedicated/reference/naming-restrictions/).
7. Leave **Use custom partitioning** set to **Off**.
By default, the table inherits the database's partition template.
If no custom partition template is applied to the database, the table inherits the default partitioning of `%Y-%m-%d` (daily).
@ -173,6 +174,7 @@ If a table doesn't have a custom partition template, it inherits the database's
{{< img-hd src="/img/influxdb3/cloud-dedicated-admin-ui-create-table-default.png" alt="Create table dialog" />}}
6. In the **Create table** dialog, provide a **Table name**.
For naming restrictions, see [Naming restrictions and conventions](/influxdb3/cloud-dedicated/reference/naming-restrictions/).
7. Toggle **Use custom partitioning** to **On**.
The **Custom partition template** section displays.

18
content/influxdb3/cloud-dedicated/reference/naming-restrictions.md Normal file
View File

@ -0,0 +1,18 @@
---
title: Naming restrictions and conventions
description: >
Learn about naming restrictions and conventions for databases, tables,
tags, fields, and other identifiers in {{% product-name %}}.
menu:
influxdb3_cloud_dedicated:
parent: Reference
weight: 108
related:
- /influxdb3/cloud-dedicated/admin/databases/create/
- /influxdb3/cloud-dedicated/reference/syntax/line-protocol/
- /influxdb3/cloud-dedicated/reference/sql/
- /influxdb3/cloud-dedicated/reference/influxql/
source: content/shared/influxdb3-reference/naming-restrictions.md
---
<!-- //SOURCE - content/shared/influxdb3-reference/naming-restrictions.md -->

39
content/influxdb3/clustered/admin/databases/create.md
View File

@ -21,6 +21,7 @@ list_code_example: |
related:
- /influxdb3/clustered/reference/cli/influxctl/database/create/
- /influxdb3/clustered/admin/custom-partitions/
- /influxdb3/clustered/reference/naming-restrictions/
---
Use the [`influxctl database create` command](/influxdb3/clustered/reference/cli/influxctl/database/create/)
@ -116,11 +117,39 @@ The retention period value cannot be negative or contain whitespace.
Database names must adhere to the following naming restrictions:
- Cannot contain whitespace, punctuation, or special characters.
Only alphanumeric, underscore (`_`), dash (`-`), and forward-slash
(`/`) characters are permitted.
- Should not start with an underscore (`_`).
- Maximum length of 64 characters.
- **Length**: Maximum 64 characters
- **Allowed characters**: 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
> [!Caution]
> #### Underscore prefix reserved for system use
>
> Names starting with an underscore (`_`) may be reserved for InfluxDB system use.
> While {{% product-name %}} might not explicitly reject these names, using them risks
> conflicts with current or future system features and may result in
> unexpected behavior or data loss.
### Valid database name examples
```text
mydb
sensor_data
prod-metrics
logs/application
webserver123
```
### Invalid database name examples
```text
my database # Contains whitespace
sensor.data # Contains period
app@server # Contains special character
_internal # Starts with underscore (reserved)
very_long_database_name_that_exceeds_sixty_four_character_limit # Too long
```
## InfluxQL DBRP naming convention

23
content/influxdb3/clustered/admin/tables/create.md
View File

@ -14,6 +14,7 @@ list_code_example: |
```
related:
- /influxdb3/clustered/reference/cli/influxctl/table/create/
- /influxdb3/clustered/reference/naming-restrictions/
- /influxdb3/clustered/admin/custom-partitions/
---
@ -38,7 +39,7 @@ to a table, you must manually create the table before you write any data to it.
that specifies the time format in the partition template and determines
the time interval to partition by _(default is `%Y-%m-%d`)_
- The name of the database to create the table in
- The name of the table to create
- The name of the table to create (see [Table naming restrictions](#table-naming-restrictions))
> [!Note]
> _{{< product-name >}} supports up to 7 total tags or tag buckets in the partition template._
@ -74,4 +75,22 @@ For more information, see [Manage data partitioning](/influxdb3/clustered/admin/
> #### Partition templates can only be applied on create
>
> You can only apply a partition template when creating a table.
> There is no way to update a partition template on an existing table.
> You can't update a partition template on an existing table.
## Table naming restrictions
Table names in {{< product-name >}} must adhere to the following naming restrictions:
- **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
> [!Caution]
> #### Underscore prefix reserved for system use
>
> Names starting with an underscore (`_`) may be reserved for InfluxDB system use.
> While {{< product-name >}} might not explicitly reject these names, using them risks
> conflicts with current or future system features and may result in
> unexpected behavior or data loss.

18
content/influxdb3/clustered/reference/naming-restrictions.md Normal file
View File

@ -0,0 +1,18 @@
---
title: Naming restrictions and conventions
description: >
Learn about naming restrictions and conventions for databases, tables,
tags, fields, and other identifiers in {{% product-name %}}.
menu:
influxdb3_clustered:
parent: Reference
weight: 108
related:
- /influxdb3/clustered/admin/databases/create/
- /influxdb3/clustered/reference/syntax/line-protocol/
- /influxdb3/clustered/reference/sql/
- /influxdb3/clustered/reference/influxql/
source: content/shared/influxdb3-reference/naming-restrictions.md
---
<!-- //SOURCE - content/shared/influxdb3-reference/naming-restrictions.md -->

3
content/influxdb3/core/admin/databases/create.md
View File

@ -17,10 +17,11 @@ list_code_example: |
{{% /code-placeholders %}}
related:
- /influxdb3/core/reference/cli/influxdb3/create/database/
- /influxdb3/core/reference/naming-restrictions/
- /influxdb3/explorer/manage-databases/
source: /shared/influxdb3-admin/databases/create.md
---
<!--
The content of this file is located at content/shared/influxdb3-admin/databases/create.md
//SOURCE content/shared/influxdb3-admin/databases/create.md
-->

18
content/influxdb3/core/reference/naming-restrictions.md Normal file
View File

@ -0,0 +1,18 @@
---
title: Naming restrictions and conventions
description: >
Learn about naming restrictions and conventions for databases, tables,
tags, fields, and other identifiers in {{% product-name %}}.
menu:
influxdb3_core:
parent: Reference
weight: 108
related:
- /influxdb3/core/admin/databases/create/
- /influxdb3/core/reference/line-protocol/
- /influxdb3/core/reference/sql/
- /influxdb3/core/reference/influxql/
source: content/shared/influxdb3-reference/naming-restrictions.md
---
<!-- //SOURCE - content/shared/influxdb3-reference/naming-restrictions.md -->

3
content/influxdb3/enterprise/admin/databases/create.md
View File

@ -17,10 +17,11 @@ list_code_example: |
{{% /code-placeholders %}}
related:
- /influxdb3/enterprise/reference/cli/influxdb3/create/database/
- /influxdb3/enterprise/reference/naming-restrictions/
- /influxdb3/explorer/manage-databases/
source: /shared/influxdb3-admin/databases/create.md
---
<!--
The content of this file is located at content/shared/influxdb3-admin/databases/create.md
//SOURCE content/shared/influxdb3-admin/databases/create.md
-->

18
content/influxdb3/enterprise/reference/naming-restrictions.md Normal file
View File

@ -0,0 +1,18 @@
---
title: Naming restrictions and conventions
description: >
Learn about naming restrictions and conventions for databases, tables,
tags, fields, and other identifiers in {{% product-name %}}.
menu:
influxdb3_enterprise:
parent: Reference
weight: 108
related:
- /influxdb3/enterprise/admin/databases/create/
- /influxdb3/enterprise/reference/line-protocol/
- /influxdb3/enterprise/reference/sql/
- /influxdb3/enterprise/reference/influxql/
source: content/shared/influxdb3-reference/naming-restrictions.md
---
<!-- //SOURCE - content/shared/influxdb3-reference/naming-restrictions.md -->

53
content/shared/influxdb3-admin/databases/create.md
View File

@ -66,24 +66,55 @@ The retention period value cannot be negative or contain whitespace.
Database names must adhere to the following naming restrictions:
- Alphanumeric characters
- Dashes (`-`), underscores (`_`), and forward slashes (`/`) are allowed
- Must start with a letter or number
- Maximum length of 64 characters
- **Length**: Maximum 64 characters
- **Allowed characters**: 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
> [!Caution]
> #### Underscore prefix reserved for system use
>
> Names starting with an underscore (`_`) may be reserved for InfluxDB system use.
> While {{% product-name %}} might not explicitly reject these names, using them risks
> conflicts with current or future system features and may result in
> unexpected behavior or data loss.
### Valid database name examples
```text
mydb
sensor_data
prod-metrics
logs/application
webserver123
```
### Invalid database name examples
```text
my database # Contains whitespace
sensor.data # Contains period
app@server # Contains special character
_internal # Starts with underscore (reserved)
very_long_database_name_that_exceeds_sixty_four_character_limit # Too long
```
For comprehensive information about naming restrictions for all InfluxDB identifiers,
see [Naming restrictions and conventions](/influxdb3/version/reference/naming-restrictions/).
## InfluxQL DBRP naming convention
In InfluxDB 1.x, data is stored in [databases](/influxdb/v1/concepts/glossary/#database)
and [retention policies](/influxdb/v1/concepts/glossary/#retention-policy-rp).
In {{% product-name %}}, databases and retention policies have been merged into
_databases_; retention policies are no longer part of the data model.
Because InfluxQL uses the 1.x data model, to support InfluxQL queries the use
databases and retention policies, an {{< product-name >}} database must
be mapped to a v1 database and retention policy (DBRP) to be queryable with InfluxQL.
_databases_, where databases have a retention period, but retention policies
are no longer part of the data model.
Because InfluxQL uses the 1.x data model, a database must be mapped to a v1
database and retention policy (DBRP) to be queryable with InfluxQL.
**When naming a database that you want to query with InfluxQL**, use the
following naming convention to automatically map v1 DBRP combinations to an
{{% product-name %}} database:
**When naming a database that you want to query with InfluxQL**, use the following
naming convention to automatically map v1 DBRP combinations to an {{% product-name %}} database:
```text
database_name/retention_policy_name

270
content/shared/influxdb3-reference/naming-restrictions.md Normal file
View File

@ -0,0 +1,270 @@
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:**
```text
mydb
sensor_data
prod-metrics
logs/application
webserver123
```
**Invalid database names:**
```text
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 {{% product-name %}} 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:**
```text
temperature
cpu_usage
http-requests
sensor123
웹서버_메트릭스 # UTF-8 characters
```
**Names requiring quotes in queries:**
```text
"my table" # Contains whitespace
"cpu.usage" # Contains period
"http@requests" # Contains special character
```
**Invalid table names:**
```text
_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:**
```text
host
region
temperature
cpu_usage
http-status
sensor123
```
**Keys requiring quotes in queries:**
```text
"host name" # Contains whitespace
"cpu.usage" # Contains period
"http@status" # Contains special character
```
**Invalid tag and field keys:**
```text
_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 {{% product-name %}}:
- **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](/influxdb3/clustered/reference/sql/#keywords) must be quoted when used as identifiers
### InfluxQL identifiers
When using InfluxQL to query {{% product-name %}}:
- **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](/influxdb3/clustered/reference/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
> [!Caution]
> #### Using underscore-prefixed names
>
> While InfluxDB might not explicitly reject names starting with underscore (`_`),
> using them risks conflicts with current or future system features and may
> result in unexpected behavior or data loss.
### 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](/influxdb3/clustered/reference/sql/#keywords)
- [InfluxQL keywords](/influxdb3/clustered/reference/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
```text
# 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
```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 examples
```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";
```
## 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