Add columns to a table

Use the influxdb3 update table command or the HTTP API to add tag and field columns to an existing table in InfluxDB 3 Enterprise.

Adding columns is additive only. You can’t remove, rename, or change the type of an existing column. Adding a column that already exists with the same data type is a no-op. Adding a column that already exists with a different data type returns an error.

This works for tables in databases that use either schema mode.

In a database that uses explicit schema mode, declaring a column is what allows writes that reference it to succeed. For more information, see Enforce a schema.

• Add columns using the influxdb3 CLI
• Add columns using the HTTP API

Add columns using the influxdb3 CLI

Use the influxdb3 update table command with --tags, --fields, or both, and provide the following:

• Required: The name of the database containing the table
• Required: The name of the table to update
• Required: At least one of --tags or --fields

--tags accepts one or more values, so place the table name before it or follow it with another option, as in the examples below.

# Add tag columns
influxdb3 update table \
  --database 
DATABASE_NAME
 \
  --token 
AUTH_TOKEN
 \
  
TABLE_NAME
 \
  --tags rack,zone

# Add field columns
influxdb3 update table \
  --database 
DATABASE_NAME
 \
  --token 
AUTH_TOKEN
 \
  --fields temp:float64,active:bool \
  
TABLE_NAME

# Add tag and field columns in one command
influxdb3 update table \
  --database 
DATABASE_NAME
 \
  --token 
AUTH_TOKEN
 \
  --tags rack \
  --fields temp:float64 \
  
TABLE_NAME

Replace the following:

• DATABASE_NAME: the name of the database containing the table
• TABLE_NAME: the name of the table to update
• AUTH_TOKEN: your admin token

See Field data types for the list of valid field types.

Add columns using the HTTP API

To add columns using the HTTP API, send a PATCH request to the /api/v3/configure/table endpoint:

PATCH http://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 the columns to add
  • db (string, required): Database name
  • table (string, required): Table name
  • tags (array, optional): Tag column names to add
  • fields (array, optional): Field definitions to add, each with a name and a type

Provide at least one of tags or fields.

# Add tag columns
curl --request PATCH "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": ["rack", "zone"],
    "fields": []
  }'

# Add field columns
curl --request PATCH "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": [],
    "fields": [
      {"name": "temp", "type": "float64"},
      {"name": "active", "type": "bool"}
    ]
  }'

Replace the following:

• DATABASE_NAME: the name of the database containing the table
• TABLE_NAME: the name of the table to update
• AUTH_TOKEN: your admin token

Response

A successful request returns HTTP status 200 with no content body.

Example error responses

An empty request that names no tags and no fields returns HTTP status 400:

invalid request: at least one of tags or fields is required

Adding a column that already exists with a different data type returns HTTP status 400.

Patching a table that doesn’t exist returns HTTP status 404. Use POST /api/v3/configure/table to create the table first.