Create a table

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

With InfluxDB 3 Core, 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

• Create a table using the HTTP API

• Data retention

• Table naming restrictions

Create a table using the influxdb3 CLI

Use 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

# Create a table with tag columns
influxdb3 create table \
  --tags tag1,tag2,tag3 \
  --database 
DATABASE_NAME
 \
  --token 
AUTH_TOKEN
 \
  
TABLE_NAME

# Create a table with tag and field columns
influxdb3 create table \
  --tags room,sensor_id \
  --fields temp:float64,hum:float64,co:int64 \
  --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 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
  • db (string, required): Database name
  • table (string, required): Table name
  • tags (array, required): Tag column names
  • fields (array, optional): Field definitions with name and type

# Create a table with tag columns
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": ["tag1", "tag2", "tag3"]
  }'

# Create a table with tag and field columns
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"}
    ]
  }'

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

Data retention

In InfluxDB 3 Core, tables use the database retention period.

Points with timestamps outside of the database’s retention period are no longer queryable and are marked for deletion. To control data retention for your tables, set a retention period when creating the database.

For more information, see Data retention in InfluxDB 3 Core.

Table naming restrictions

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