Documentation

Create a table

Use the influxdb3 create table command or the HTTP API to create a table in a specified database in InfluxDB 3 Enterprise.

With InfluxDB 3 Enterprise, tables and measurements are synonymous. Typically, tables are created automatically on write using the table name specified in line protocol written to InfluxDB. However, you can manually create tables to define a custom schema or apply custom settings before writing data.

Create a table using the influxdb3 CLI

  1. If you haven’t already, download and install the influxdb3 CLI.

  2. Run the influxdb3 create table command and provide the following:

    • Required: The name of the database to create the table in

    • Required: The name of the table to create (see Table naming restrictions)

    • Required: Tag columns to include in the table (must have at least one tag column)

    • Optional: Field columns and their data types to include in the table

    • Optional: A retention period for the table

    Tables must include at least one tag column. Field columns are optional and can be added later when you write data.

    Tag order affects query performance

    When considering your schema and creating your table, order your tags by query priority. Place the most commonly queried tags first. Columns that appear earlier are typically faster to filter and access during query execution.

    For more information, see Optimize writes.

influxdb3 create table \
  --tags tag1,tag2,tag3 \
  --database 
DATABASE_NAME
\
--token
AUTH_TOKEN
\
TABLE_NAME

Replace the following:

  • DATABASE_NAME: the name of the database to create the table in
  • TABLE_NAME: the name of the table to create
  • AUTH_TOKEN: your admin token

Create a table with field columns

To define specific field columns and their data types when creating the table, use the --fields flag:

influxdb3 create table \
  --tags room,sensor_id \
  --fields temp:float64,hum:float64,co:int64 \
  --database 
DATABASE_NAME
\
--token
AUTH_TOKEN
\
TABLE_NAME

Create a table with a retention period

To set a specific retention period for the table, use the --retention-period flag:

influxdb3 create table \
  --tags room,sensor_id \
  --fields temp:float64,hum:float64 \
  --retention-period 7d \
  --database 
DATABASE_NAME
\
--token
AUTH_TOKEN
\
TABLE_NAME

Create a table using the HTTP API

To create a table using the HTTP API, send a POST request to the /api/v3/configure/table endpoint:

POST localhost:8181/api/v3/configure/table

Include the following in your request:

  • Headers:
    • Authorization: Bearer with your authentication token
    • Content-Type: application/json
  • Request body: JSON object with table configuration
curl -X POST "http://localhost:8181/api/v3/configure/table" \
  --header "Authorization: Bearer 
AUTH_TOKEN
"
\
--header "Content-Type: application/json" \ --data '{ "db": "
DATABASE_NAME
",
"table": "
TABLE_NAME
",
"tags": ["tag1", "tag2", "tag3"] }'

Create a table with field columns using the API

curl -X POST "localhost:8181/api/v3/configure/table" \
  --header "Authorization: Bearer 
AUTH_TOKEN
"
\
--header "Content-Type: application/json" \ --data '{ "db": "
DATABASE_NAME
",
"table": "
TABLE_NAME
",
"tags": ["room", "sensor_id"], "fields": [ {"name": "temp", "type": "float64"}, {"name": "hum", "type": "float64"}, {"name": "co", "type": "int64"} ] }'

Create a table with a retention period using the API

curl -X POST "localhost:8181/api/v3/configure/table" \
  --header "Authorization: Bearer 
AUTH_TOKEN
"
\
--header "Content-Type: application/json" \ --data '{ "db": "
DATABASE_NAME
",
"table": "
TABLE_NAME
",
"tags": ["room", "sensor_id"], "fields": [ {"name": "temp", "type": "float64"}, {"name": "hum", "type": "float64"} ], "retention_period": "7d" }'

Table naming restrictions

Table names in InfluxDB 3 Enterprise 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

Underscore prefix reserved for system use

Names starting with an underscore (_) may be reserved for InfluxDB system use. While InfluxDB 3 Enterprise 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.


Was this page helpful?

Thank you for your feedback!


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

New in InfluxDB 3.4

Key enhancements in InfluxDB 3.4 and the InfluxDB 3 Explorer 1.2.

See the Blog Post

InfluxDB 3.4 is now available for both Core and Enterprise, which introduces offline token generation for use in automated deployments and configurable license type selection that lets you bypass the interactive license prompt. InfluxDB 3 Explorer 1.2 is also available, which includes InfluxDB cache management and other new features.

For more information, check out: