How to create an InfluxDB 3 Core table schema

Creating an InfluxDB 3 Core table schema defines tag columns and field types before production writes reach a database. It is useful when the first write should not decide tag order, when a dashboard expects stable column names, or when an ingestion job should fail early if it sends the wrong field type.

Core can create tables automatically from line protocol, but an explicit table creation request sets the schema before clients start writing data. Tags become dictionary-backed string columns and join time in the table primary key, while fields hold measured values such as floats, integers, booleans, and strings.

Start with an existing target database and a token that can create tables, inspect schema, and write a test point. Use a table name that maps to one measurement-style workload, keep high-priority query tags first, and avoid using the same name for both a tag and a field.

1. Set the admin token for the current shell.

   $ export INFLUXDB3_AUTH_TOKEN='INFLUXDB_ADMIN_TOKEN'

   Use a token with table creation and write access to the target database. Keep raw tokens out of shared logs, screenshots, and shell history.

2. Choose the target database, table name, tag order, and field columns.

   Use sensors as the scratch database and weather as the table when reproducing the transcript. The tag columns are room and sensor_id, and the field columns are temperature, humidity, and status. The CLI field type for string values is utf8.

3. Create the table with ordered tags and typed fields.

   $ influxdb3 create table --database sensors --tags room,sensor_id --fields temperature:float64,humidity:float64,status:utf8 weather
   Table "sensors"."weather" created successfully

   Tables must include at least one tag. Field columns are optional at creation time and can be added later by writes, but predefining them catches type drift before clients rely on the table.

4. Inspect the created table columns.

   $ influxdb3 query --database sensors "SHOW COLUMNS FROM weather"
   +---------------+--------------+------------+-------------+-------------------------+-------------+
   | table_catalog | table_schema | table_name | column_name | data_type               | is_nullable |
   +---------------+--------------+------------+-------------+-------------------------+-------------+
   | public        | iox          | weather    | humidity    | Float64                 | YES         |
   | public        | iox          | weather    | room        | Dictionary(Int32, Utf8) | YES         |
   | public        | iox          | weather    | sensor_id   | Dictionary(Int32, Utf8) | YES         |
   | public        | iox          | weather    | status      | Utf8                    | YES         |
   | public        | iox          | weather    | temperature | Float64                 | YES         |
   | public        | iox          | weather    | time        | Timestamp(ns)           | NO          |
   +---------------+--------------+------------+-------------+-------------------------+-------------+

   Dictionary(Int32, Utf8) identifies tag columns. The field type utf8 appears as Utf8 in SQL schema output.

5. Write one point that matches the table schema.

   $ influxdb3 write --database sensors 'weather,room=lab,sensor_id=t-01 temperature=21.8,humidity=41.2,status="ok" 1710000000000000000'
   696ms: 1 request (1.44 requests/sec), 1 lines (1 lines/s), 94B (135B/s)

   Use a scratch database or a clearly disposable test series when a production table should not receive validation points. String field values in line protocol need quotes.

6. Query the inserted point from the table.

   $ influxdb3 query --database sensors "SELECT time, room, sensor_id, temperature, humidity, status FROM weather ORDER BY time"
   +---------------------+------+-----------+-------------+----------+--------+
   | time                | room | sensor_id | temperature | humidity | status |
   +---------------------+------+-----------+-------------+----------+--------+
   | 2024-03-09T16:00:00 | lab  | t-01      | 21.8        | 41.2     | ok     |
   +---------------------+------+-----------+-------------+----------+--------+

   A returned row with the tag values and typed fields confirms the schema accepts the intended line protocol shape.
   Related: How to run an SQL query in InfluxDB 3 Core