---
title: "Update a table"
method: PUT
path: "/v2/storage/tables/{tableId}"
tags: ["Tables"]
---

# Update a table

`PUT /v2/storage/tables/{tableId}`

## Request

- Base URL: `https://connection.keboola.com`
- URL: `https://connection.keboola.com/v2/storage/tables/{tableId}`
- Auth: one of:
  - API key in header `X-StorageApi-Token`
  - API key in header `X-KBC-ManageApiToken`
  - HTTP bearer
- TypeScript: <https://skmtc.dev/keboola/apis/keboola-storage-api/docs/v2/storage/tables/:tableId/put.ts> (a function with typed inputs; its response is checked against the schema)

Renames a table by setting a new display name. With `async=true` the rename is enqueued as a storage job (202). The synchronous variant is deprecated and returns the updated table directly. Linked copies of the table in other projects are renamed as well.

Initial response returns job details [JobResponse](#model-JobResponse). The result of the asynchronous job can be fetched via `/v2/storage/jobs/{id}`. When the job completes, final result is [TableUpdateJobResult](#model-TableUpdateJobResult).

 Parameters of job will be [TableUpdateJobParams](#components-schemas-TableUpdateJobParams).

[Deprecated] This endpoint can be used synchronously as well. In that case, the final result is returned directly in the response [TableUpdateResponse](#model-TableUpdateResponse).

## Path parameters

- `tableId` string, required

## Query parameters

- `async` boolean

## Request body

- TableUpdateRequest: Table properties to update. The display name is the only updatable property.
  - `displayName` string, required: The name of a bucket or a table. - Allowed characters: `A-Z`, `a-z`, `0-9`, dash `-` and underscore `_`. Anything else — a space, a dot, an accented letter — is rejected, not transliterated. - 1 to 96 characters. - Cannot start with an underscore. A dash or a digit as the first character is fine. - Registered (external) buckets follow this same rule, dashes included. - Uniqueness is case-insensitive within a stage: creating `MyBucket` next to `mybucket` fails with `storage.buckets.alreadyExists`, and for tables with `storage.buckets.tableAlreadyExists` or `storage.validation.tableAlreadyExists`. - To turn arbitrary user input into a name that satisfies this rule, call `POST /v2/storage/webalize/display-name` instead of reimplementing the transformation. It unaccents the input, replaces every run of disallowed characters with a single `-`, trims `-` from both ends, strips leading underscores, and truncates to 96 characters.

## Response `200`

The updated table (synchronous, deprecated).

- TableUpdateResponse: The updated table with its columns, metadata and bucket payload. Returned only by the deprecated synchronous variant of the endpoint.
  - `uri` string, required: Table API URI
  - `id` string, required: Table ID
  - `name` string, required: Table name
  - `displayName` string, required: Table display name
  - `transactional` boolean, required: Is transactional
  - `primaryKey` string[], required: Primary key columns
  - `indexType` string, nullable, required: Index type
  - `indexKey` string[], required: Index key columns
  - `distributionType` string, nullable, required: Distribution type
  - `distributionKey` string[], required: Distribution key columns
  - `syntheticPrimaryKeyEnabled` boolean, required: Synthetic primary key enabled
  - `created` string, nullable, required: Created timestamp, ISO 8601 with a `+hhmm` offset.
  - `lastImportDate` string, nullable, required: Last import date, ISO 8601 with a `+hhmm` offset.
  - `lastChangeDate` string, nullable, required: Last change date, ISO 8601 with a `+hhmm` offset.
  - `rowsCount` integer, nullable, required: Rows count (null for a filtered alias)
  - `dataSizeBytes` integer, nullable, required: Data size in bytes (null for a filtered alias)
  - `isAlias` boolean, required: Is alias
  - `isAliasable` boolean, required: Is aliasable
  - `isTyped` boolean, required: Is typed table
  - `isDescriptionSystemManaged` boolean, required: Whether the description is managed by the system
  - `timestampType` string, required: Timestamp column type
  - `tableType` string, required: Table type
  - `path` string, required: Table path
  - `columns` string[], required: Column names
  - `columnMetadata` object, required: Metadata entries per column, keyed by column name
  - `attributes` object[], required: Always an empty array, kept for backward compatibility
  - `metadata` MetadataItemResponse[], required: Table metadata entries
    - `id` string, required: Metadata record identifier
    - `key` string, required: Metadata key
    - `value` string, nullable, required: Metadata value
    - `provider` string, required: Id of the component that created the metadata
    - `timestamp` string, required: When the metadata was created or last updated, ISO 8601 with a `+hhmm` offset
  - `bucket` TableBucketResponse, required: The bucket a table lives in, as embedded in table responses. Built by Model_Row_Bucket::toApiResponse() and extended with `metadata` by the table response provider. Unlike the standalone bucket detail response, `tables` here is the bucket URI, not a list of table objects, and there is no `scheduledTasks`, `listing` or `linkedBy`.
    - `uri` string, required: API URI of the bucket.
    - `id` string, required: Bucket identifier (`{stage}.{name}`).
    - `name` string, required: Bucket name (prefixed with `c-`).
    - `displayName` string, required: Human-readable display name shown in the UI.
    - `idBranch` integer, required: ID of the branch the bucket belongs to.
    - `stage` 'in' | 'out' | 'sys', required: Bucket stage.
    - `description` string, required: Bucket description.
    - `tables` string, required: The same URI as `uri`, kept for backward compatibility.
    - `created` string, required: Creation timestamp, ISO 8601 with a `+hhmm` offset; `""` when none was recorded.
    - `lastChangeDate` string, nullable, required: Timestamp of the last data change in the bucket, ISO 8601 with a `+hhmm` offset.
    - `updated` string, nullable, required: Timestamp of the last bucket update, ISO 8601 with a `+hhmm` offset.
    - `isReadOnly` boolean, required: Whether the bucket is read-only (linked or external buckets).
    - `dataSizeBytes` integer, required: Total data size in bytes.
    - `rowsCount` integer, required: Total number of rows.
    - `isMaintenance` boolean, required: Whether the bucket is in maintenance mode.
    - `backend` string, required: Storage backend of the bucket: `snowflake`, `bigquery` or `postgres` (external buckets); older buckets may carry another backend name.
    - `sharing` 'organization' | 'organization-project' | 'specific-projects' | 'specific-users' | 'null', nullable, required: Sharing type of the bucket; `null` when the bucket is not shared.
    - `hasExternalSchema` boolean, required: Whether the bucket is an external (registered) bucket.
    - `databaseName` string, required: Database of a Snowflake external bucket or of a linked bucket's source; `""` otherwise.
    - `path` string, required: Dot-separated path of the bucket on the backend.
    - `isSnowflakeSharedDatabase` boolean, required: Whether the external bucket uses a Snowflake Secure Data Share.
    - `isLinkedBucket` boolean, required: Whether this bucket is linked from another project.
    - `color` string, nullable, required: CSS color of the bucket.
    - `bucketSharingAllowed` boolean, required: Whether the bucket can be shared.
    - `sharingParameters` union: Who the bucket is shared with. Present only when the bucket is shared; an empty array `[]` when it is shared with the organization or its projects.
      - object
        - `projects` object[]: Present when `sharing` is `specific-projects`.
          - `id` integer, required
          - `name` string, required
        - `users` object[]: Present when `sharing` is `specific-users`.
          - `id` integer, required
          - `name` string, required
          - `email` string, required
      - unknown[]
        - unknown
    - `sharedBy` object: Token that shared the bucket. Present only when the bucket is shared.
      - `id` integer, nullable, required
      - `name` string, nullable, required
      - `date` string, required: ISO 8601 with a `+hhmm` offset; `""` when none was recorded.
    - `sharedByActor` ActorResponse, required: Who performed the action and through which credential.
      - `type` 'token' | 'session' | 'pat' | 'system', required: Credential the action came through: a Storage token, a programmatic session, a personal access token, or system work.
      - `id` string, required: Token id as a string, session or personal access token UUID, or the system subject.
      - `name` string, required: Token description, the admin email for a session or personal access token, or the system label, as it was when the action happened.
      - `adminId` integer, nullable, required: Admin behind the credential; null for a token without an admin, for system work, and when the admin was not recorded (an object whose creator is known only from its token columns, including rows backfilled from them).
    - `owner` object, nullable, required: Bucket owner; `null` when no owner is set.
      - `id` integer, required
      - `name` string, required
      - `email` string, required
    - `sourceBucket` SharedBucketResponse: Shared bucket as seen from another project (also used as `sourceBucket` of a linked bucket).
      - `id` string, required: Bucket identifier in the source project.
      - `name` string, required: Bucket name.
      - `displayName` string, required: Bucket display name.
      - `stage` 'in' | 'out' | 'sys', required: Bucket stage.
      - `description` string, required: Bucket description.
      - `sharing` 'organization' | 'organization-project' | 'specific-projects' | 'specific-users' | 'null', nullable, required: Sharing type.
      - `created` string, required: Creation timestamp, ISO 8601 with a `+hhmm` offset; `""` when none was recorded.
      - `lastChangeDate` string, nullable, required: Timestamp of the last data change, ISO 8601 with a `+hhmm` offset.
      - `dataSizeBytes` integer, required
      - `rowsCount` integer, required
      - `backend` string, required: Storage backend of the bucket: `snowflake`, `bigquery` or `postgres` (external buckets); older buckets may carry another backend name.
      - `hasExternalSchema` boolean, required: Whether the bucket is an external (registered) bucket.
      - `databaseName` string, required: Database of a Snowflake external bucket or of a linked bucket's source; `""` otherwise.
      - `path` string, required: Dot-separated path of the bucket on the backend.
      - `project` object, required: Project owning the bucket.
        - `id` integer, required
        - `name` string, required
      - `color` string, nullable, required
      - `tables` object[]: Tables in the shared bucket (filtered aliases are omitted). Absent from a `sourceBucket` inside a table list or search with `include=bucketsWithoutSourceTables`.
        - `id` string, required
        - `name` string, required
        - `displayName` string, required
        - `path` string, required: Internal Storage path of the table (`/{bucket numeric id}-{table name}`); may be `""`.
      - `sharingParameters` union: Who the bucket is shared with. Present only when the bucket is shared; an empty array `[]` when it is shared with the organization or its projects.
        - object
          - `projects` object[]: Present when `sharing` is `specific-projects`.
            - `id` integer, required
            - `name` string, required
          - `users` object[]: Present when `sharing` is `specific-users`.
            - `id` integer, required
            - `name` string, required
            - `email` string, required
        - unknown[]
          - unknown
      - `sharedBy` object: Token that shared the bucket. Present only when the bucket is shared.
        - `id` integer, nullable, required
        - `name` string, nullable, required
        - `date` string, required: ISO 8601 with a `+hhmm` offset; `""` when none was recorded.
      - `sharedByActor` ActorResponse, required: Who performed the action and through which credential.
        - `type` 'token' | 'session' | 'pat' | 'system', required: Credential the action came through: a Storage token, a programmatic session, a personal access token, or system work.
        - `id` string, required: Token id as a string, session or personal access token UUID, or the system subject.
        - `name` string, required: Token description, the admin email for a session or personal access token, or the system label, as it was when the action happened.
        - `adminId` integer, nullable, required: Admin behind the credential; null for a token without an admin, for system work, and when the admin was not recorded (an object whose creator is known only from its token columns, including rows backfilled from them).
      - `owner` object, nullable, required: Bucket owner; `null` when no owner is set.
        - `id` integer, required
        - `name` string, required
        - `email` string, required
      - `metadata` MetadataItemResponse[]: Bucket metadata. Present only on the shared-buckets list with `include` containing `metadata`.
        - `id` string, required: Metadata record identifier
        - `key` string, required: Metadata key
        - `value` string, nullable, required: Metadata value
        - `provider` string, required: Id of the component that created the metadata
        - `timestamp` string, required: When the metadata was created or last updated, ISO 8601 with a `+hhmm` offset
    - `backendPath` string[], required: Full path of the bucket on the backend (e.g. database and schema).
    - `metadata` MetadataItemResponse[]: Bucket metadata records. Present only in the table detail and the synchronous table update.
      - `id` string, required: Metadata record identifier
      - `key` string, required: Metadata key
      - `value` string, nullable, required: Metadata value
      - `provider` string, required: Id of the component that created the metadata
      - `timestamp` string, required: When the metadata was created or last updated, ISO 8601 with a `+hhmm` offset
  - `sourceTable` object: Source table info. Present only for aliases with a resolved source table. Carries the source table `columnMetadata` when the alias propagates metadata.
    - `id` string, required: Source table ID
    - `uri` string, required: Source table URI
    - `project` object, required
      - `id` integer, required: Project ID
      - `name` string, required: Project name
    - `columnMetadata` object: Metadata entries of the root source table, keyed by column name. Present only for an alias with column auto-sync.
  - `aliasColumnsAutoSync` boolean: Alias columns auto sync. Present only for simple aliases.
  - `aliasFilter` object: The filter applied to the alias. Present only for filtered simple aliases.
    - `column` string, required: Filtered column name
    - `operator` string, required: Filter operator (eq or ne)
    - `values` string[], required: Filter values
  - `selectSql` string: The alias SQL. Present only for custom SQL aliases.
  - `isPersisted` boolean: Whether the alias is persisted. Present only for aliases.

## Other responses

- `202`: Job accepted; returns job details.
- `400`: The display name failed validation (`storage.tables.validation`) or another table in the same bucket already uses it (`storage.buckets.tableAlreadyExists`).
- `403`: Write access to the table was denied.
- `404`: The table or its bucket was not found.
- `503`: The bucket or its backend is under maintenance.

---

[API](https://skmtc.dev/keboola/apis/keboola-storage-api.md) - [All operations](https://skmtc.dev/keboola/apis/keboola-storage-api/llms.txt) - [OpenAPI document](https://skmtc.dev/keboola/apis/keboola-storage-api/revisions/34b5ceac0317?raw)