---
title: "Create a table alias in a bucket"
method: POST
path: "/v2/storage/buckets/{bucketId}/table-aliases"
tags: ["Buckets"]
---

# Create a table alias in a bucket

`POST /v2/storage/buckets/{bucketId}/table-aliases`

## Request

- Base URL: `https://connection.keboola.com`
- URL: `https://connection.keboola.com/v2/storage/buckets/{bucketId}/table-aliases`
- 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/buckets/:bucketId/table-aliases/post.ts> (a function with typed inputs; its response is checked against the schema)

Creates an alias table in the given bucket over a table from another bucket. The alias can
expose a subset of the source columns and can be restricted by a filter. On backends that
keep a persisted VIEW for aliases the work is delegated to an asynchronous job, otherwise the
alias is created directly and returned with 201.

An alias cannot be created from a table that lives in an external bucket or in a development
branch. Additionally, the destination bucket itself cannot be an external bucket or a
development branch bucket.

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 [AliasCreateJobResult](#model-AliasCreateJobResult).

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

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

## Path parameters

- `bucketId` string, required

## Request body

- CreateTableAliasRequest: Request body of POST /buckets/{bucket_id}/table-aliases.
  - `sourceTable` string, required: Id of the table the alias reads from (e.g. `in.c-main.users`).
  - `name` string, nullable: Name of the new alias table. Defaults to the source table name.
  - `aliasColumns` string[], nullable: Columns exposed by the alias. When omitted the alias mirrors all source columns and keeps them in sync.
  - `aliasColumnsAutosync` boolean, nullable: Deprecated and ignored - auto-sync is derived from whether aliasColumns is given.
  - `aliasFilter` object, nullable: Restricts the alias to rows matching a single column filter.
    - `column` string
    - `values` string[]
    - `operator` 'eq' | 'ne'

## Response `201`

The created alias detail, including its columns and the destination bucket detail.

- CreateTableAliasResponse: Detail of the created alias table, including a flat list of its column names.
  - `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
  - `dataSizeBytes` integer, nullable, required: Data size in bytes
  - `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` 'MANAGED' | 'SELFMANAGED' | 'NONE', required: How the `_timestamp` column is managed
  - `tableType` string, required: Table type
  - `path` string, required: Table path
  - `columns` string[], required: Names of the columns exposed by the alias.
  - `sourceTable` SourceTableResponse
    - `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
    - `isAlias` boolean: Whether the source table is itself an alias
  - `aliasColumnsAutoSync` boolean: Alias columns auto sync. Present only for simple aliases.
  - `aliasFilter` AliasFilterResponse: Row filter of a filtered simple alias, as returned by Model_Row_MetadataTable::getAliasFilter().
    - `column` string, required: Filtered column name.
    - `operator` 'eq' | 'ne', required: Filter operator: `eq` (can be used with multiple values) or `ne`.
    - `values` string[], required: Values compared against the filtered column.
  - `selectSql` string: Custom SQL of the alias. Present only for custom SQL aliases.
  - `isPersisted` boolean: Whether the alias is persisted as a table in the backend. Present only for aliases.
  - `bucket` BucketResponse: Bucket object.
    - `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); `[]` on backends without one.

## Other responses

- `202`: Job accepted; returns job details.
- `400`: The alias cannot be created - invalid request body, an external bucket on either side, a bucket in a development branch, a filter the source table does not support, or a source that reads a linked or external bucket while the destination bucket is exposed on Snowflake (`storage.tables.aliasSourceOutsideProjectInExposedBucket`).
- `403`: Write access to the destination bucket or read access to the source bucket was denied.
- `404`: The destination bucket, the source bucket or the source table was not found.
- `503`: The destination 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)