---
title: Add columns to a table
description: Use the influxdb3 update table command or the HTTP API to add tag and field columns to an existing table in InfluxDB 3 Enterprise.
url: https://docs.influxdata.com/influxdb3/enterprise/admin/tables/update/
estimated_tokens: 1463
product: InfluxDB 3 Enterprise
version: enterprise
publisher: InfluxData
canonical: https://docs.influxdata.com/influxdb3/enterprise/admin/tables/update/
date: '2026-09-29T11:52:29-04:00'
lastmod: '2026-09-29T11:52:29-04:00'
---

Use the [`influxdb3 update table` command](/influxdb3/enterprise/reference/cli/influxdb3/update/table/)or the [HTTP API](/influxdb3/enterprise/api/v3/) 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](/influxdb3/enterprise/admin/databases/create/#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](/influxdb3/enterprise/admin/databases/enforce-schema/).

* [Add columns using the influxdb3 CLI](#add-columns-using-the-influxdb3-cli)
* [Add columns using the HTTP API](#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.

```sh
# 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](/influxdb3/enterprise/admin/tokens/)

See [Field data types](/influxdb3/enterprise/reference/cli/influxdb3/create/table/#field-data-types)for the list of valid field types.

> [!Important]
> #### Add columns and update retention in separate commands
>
> `--tags` and `--fields` add columns to the table.`--retention-period` updates the table’s retention period.
> These are separate operations against separate API endpoints, so
> InfluxDB 3 Enterprise rejects a command that combines `--retention-period`with `--tags` or `--fields`.
> Run them as separate commands.
> For more information about table retention periods, see[Data retention](/influxdb3/enterprise/reference/internals/data-retention/).

## 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`.

```bash
# 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](/influxdb3/enterprise/admin/tokens/)

### 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`:

```text
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`](/influxdb3/enterprise/admin/tables/create/#create-a-table-using-the-http-api)to create the table first.

> [!Note]
> `PATCH /api/v3/configure/table` adds columns only and never touches
> the table’s retention period.
> To update a table’s retention period, use `PUT /api/v3/configure/table`.

> [!Important]
> #### PUT doesn’t add columns
>
> `PUT /api/v3/configure/table` updates only the retention period.
> The endpoint ignores a `tags` or `fields` array in the request body and still returns HTTP status `200`.
> In a database that uses `explicit` schema mode, the next write that references the undeclared column fails.
> To add columns, use `PATCH /api/v3/configure/table` or `influxdb3 update table`.

#### Related

* [influxdb3 update table](/influxdb3/enterprise/reference/cli/influxdb3/update/table/)
* [influxdb3 create table](/influxdb3/enterprise/reference/cli/influxdb3/create/table/)
* [Table API reference](/influxdb3/enterprise/api/v3/#tag/Table)
* [Enforce a schema](/influxdb3/enterprise/admin/databases/enforce-schema/)