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
If you haven’t already, download and install the
influxdb3
CLI.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
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 inTABLE_NAME
: the name of the table to createAUTH_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 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 tokenContent-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"}
]
}'
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
Underscore prefix reserved for system use
Names starting with an underscore (_
) may be reserved for InfluxDB system use.
While InfluxDB 3 Core 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!
Support and feedback
Thank you for being part of our community! We welcome and encourage your feedback and bug reports for InfluxDB 3 Core and this documentation. To find support, use the following resources:
Customers with an annual or support contract can contact InfluxData Support.