> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-home-button.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> The Alias table engine creates a transparent proxy to another table. All operations are forwarded to the target table while the alias itself stores no data.

# Alias table engine

export const ExperimentalBadge = () => {
  return <div className="experimentalBadge">
            <div className="experimentalIcon">
            <svg width="16" height="16" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
                <path strokeWidth="1.25" d="M5.5 2H10.5" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
                <path strokeWidth="1.25" d="M9.50015 2V6.19625L13.4283 12.7425C13.4738 12.8183 13.4985 12.9049 13.4996 12.9934C13.5008 13.0818 13.4785 13.169 13.435 13.246C13.3914 13.323 13.3283 13.3871 13.2519 13.4317C13.1755 13.4764 13.0886 13.4999 13.0002 13.5H3.00015C2.91164 13.5 2.8247 13.4766 2.74822 13.432C2.67174 13.3874 2.60847 13.3233 2.56487 13.2463C2.52126 13.1693 2.49889 13.082 2.50004 12.9935C2.50119 12.905 2.52582 12.8184 2.5714 12.7425L6.50015 6.19625V2" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
                <path strokeWidth="1.25" d="M4.47656 9.56754C5.30344 9.41254 6.47656 9.47942 7.99969 10.25C10.0153 11.2707 11.4216 11.0569 12.2184 10.7282" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
            </svg>
        </div>
            Experimental feature. <u><a href="/docs/beta-and-experimental-features#experimental-features">Learn more.</a></u>
        </div>;
};

The `Alias` engine creates a proxy to another table. All read and write operations are forwarded to the target table, while the alias itself stores no data and only maintains a reference to the target table.

<Info>
  This is an experimental feature that may change in backwards-incompatible ways in the future releases.
  Enable usage of the Alias table engine
  with [allow\_experimental\_alias\_table\_engine](/reference/settings/session-settings#allow_experimental_alias_table_engine) setting.
  Input the command `set allow_experimental_alias_table_engine = 1`.
</Info>

<h2 id="creating-a-table">
  Creating a Table
</h2>

```sql theme={null}
CREATE TABLE [db_name.]alias_name
ENGINE = Alias(target_table)
```

Or with explicit database name:

```sql theme={null}
CREATE TABLE [db_name.]alias_name
ENGINE = Alias(target_db, target_table)
```

<Note>
  The `Alias` table does not support explicit column definitions. Columns are automatically inherited from the target table. This ensures that the alias always matches the target table's schema.
</Note>

<h2 id="engine-parameters">
  Engine Parameters
</h2>

* **`target_db (optional)`** — Name of the database containing the target table.
* **`target_table`** — Name of the target table.

<Note>
  When `target_db` is omitted and `target_table` is not fully qualified (e.g., `Alias('my_table')`), the target is resolved to the same database as the alias itself, not the session's current database.
</Note>

<h2 id="supported-operations">
  Supported Operations
</h2>

The `Alias` table engine supports all major operations.

<h3 id="operations-on-target">
  Operations on Target Table
</h3>

These operations are proxied to the target table:

| Operation                    | Support | Description                                         |
| ---------------------------- | ------- | --------------------------------------------------- |
| `SELECT`                     | ✅       | Read data from target table                         |
| `INSERT`                     | ✅       | Write data to target table                          |
| `INSERT SELECT`              | ✅       | Batch insert into target table                      |
| `ALTER TABLE ADD COLUMN`     | ✅       | Add columns to target table                         |
| `ALTER TABLE MODIFY SETTING` | ✅       | Modify target table settings                        |
| `ALTER TABLE PARTITION`      | ✅       | Partition operations (DETACH/ATTACH/DROP) on target |
| `ALTER TABLE UPDATE`         | ✅       | Update rows in target table (mutation)              |
| `ALTER TABLE DELETE`         | ✅       | Delete rows from target table (mutation)            |
| `OPTIMIZE TABLE`             | ✅       | Optimize target table (merge parts)                 |
| `TRUNCATE TABLE`             | ✅       | Truncate target table                               |

<h3 id="operations-on-alias">
  Operations on Alias Itself
</h3>

These operations only affect the alias, **not** the target table:

| Operation      | Support | Description                                           |
| -------------- | ------- | ----------------------------------------------------- |
| `DROP TABLE`   | ✅       | Drop the alias only, target table remains unchanged   |
| `RENAME TABLE` | ✅       | Rename the alias only, target table remains unchanged |

<h2 id="usage-examples">
  Usage Examples
</h2>

<h3 id="basic-alias-creation">
  Basic Alias Creation
</h3>

Create a simple alias in the same database:

```sql theme={null}
-- Create source table
CREATE TABLE source_data (
    id UInt32,
    name String,
    value Float64
) ENGINE = MergeTree
ORDER BY id;

-- Insert some data
INSERT INTO source_data VALUES (1, 'one', 10.1), (2, 'two', 20.2);

-- Create alias
CREATE TABLE data_alias ENGINE = Alias('source_data');

-- Query through alias
SELECT * FROM data_alias;
```

```text theme={null}
┌─id─┬─name─┬─value─┐
│  1 │ one  │  10.1 │
│  2 │ two  │  20.2 │
└────┴──────┴───────┘
```

<h3 id="cross-database-alias">
  Cross-Database Alias
</h3>

Create an alias pointing to a table in a different database:

```sql theme={null}
-- Create databases
CREATE DATABASE db1;
CREATE DATABASE db2;

-- Create source table in db1
CREATE TABLE db1.events (
    timestamp DateTime,
    event_type String,
    user_id UInt32
) ENGINE = MergeTree
ORDER BY timestamp;

-- Create alias in db2 pointing to db1.events
CREATE TABLE db2.events_alias ENGINE = Alias('db1', 'events');

-- Or using database.table format
CREATE TABLE db2.events_alias2 ENGINE = Alias('db1.events');

-- Both aliases work identically
INSERT INTO db2.events_alias VALUES (now(), 'click', 100);
SELECT * FROM db2.events_alias2;
```

<h3 id="write-operations">
  Write Operations Through Alias
</h3>

All write operations are forwarded to the target table:

```sql theme={null}
CREATE TABLE metrics (
    ts DateTime,
    metric_name String,
    value Float64
) ENGINE = MergeTree
ORDER BY ts;

CREATE TABLE metrics_alias ENGINE = Alias('metrics');

-- Insert through alias
INSERT INTO metrics_alias VALUES 
    (now(), 'cpu_usage', 45.2),
    (now(), 'memory_usage', 78.5);

-- Insert with SELECT
INSERT INTO metrics_alias 
SELECT now(), 'disk_usage', number * 10 
FROM system.numbers 
LIMIT 5;

-- Verify data is in the target table
SELECT count() FROM metrics;  -- Returns 7
SELECT count() FROM metrics_alias;  -- Returns 7
```

<h3 id="schema-modification">
  Schema Modification
</h3>

Alter operations modify the target table schema:

```sql theme={null}
CREATE TABLE users (
    id UInt32,
    name String
) ENGINE = MergeTree
ORDER BY id;

CREATE TABLE users_alias ENGINE = Alias('users');

-- Add column through alias
ALTER TABLE users_alias ADD COLUMN email String DEFAULT '';

-- Column is added to target table
DESCRIBE users;
```

```text theme={null}
┌─name──┬─type───┬─default_type─┬─default_expression─┐
│ id    │ UInt32 │              │                    │
│ name  │ String │              │                    │
│ email │ String │ DEFAULT      │ ''                 │
└───────┴────────┴──────────────┴────────────────────┘
```

<h3 id="data-mutations">
  Data Mutations
</h3>

UPDATE and DELETE operations are supported:

```sql theme={null}
CREATE TABLE products (
    id UInt32,
    name String,
    price Float64,
    status String DEFAULT 'active'
) ENGINE = MergeTree
ORDER BY id;

CREATE TABLE products_alias ENGINE = Alias('products');

INSERT INTO products_alias VALUES 
    (1, 'item_one', 100.0, 'active'),
    (2, 'item_two', 200.0, 'active'),
    (3, 'item_three', 300.0, 'inactive');

-- Update through alias
ALTER TABLE products_alias UPDATE price = price * 1.1 WHERE status = 'active';

-- Delete through alias
ALTER TABLE products_alias DELETE WHERE status = 'inactive';

-- Changes are applied to target table
SELECT * FROM products ORDER BY id;
```

```text theme={null}
┌─id─┬─name─────┬─price─┬─status─┐
│  1 │ item_one │ 110.0 │ active │
│  2 │ item_two │ 220.0 │ active │
└────┴──────────┴───────┴────────┘
```

<h3 id="partition-operations">
  Partition Operations
</h3>

For partitioned tables, partition operations are forwarded:

```sql theme={null}
CREATE TABLE logs (
    date Date,
    level String,
    message String
) ENGINE = MergeTree
PARTITION BY toYYYYMM(date)
ORDER BY date;

CREATE TABLE logs_alias ENGINE = Alias('logs');

INSERT INTO logs_alias VALUES 
    ('2024-01-15', 'INFO', 'message1'),
    ('2024-02-15', 'ERROR', 'message2'),
    ('2024-03-15', 'INFO', 'message3');

-- Detach partition through alias
ALTER TABLE logs_alias DETACH PARTITION '202402';

SELECT count() FROM logs_alias;  -- Returns 2 (partition 202402 detached)

-- Attach partition back
ALTER TABLE logs_alias ATTACH PARTITION '202402';

SELECT count() FROM logs_alias;  -- Returns 3
```

<h3 id="table-optimization">
  Table Optimization
</h3>

Optimize operations merge parts in the target table:

```sql theme={null}
CREATE TABLE events (
    id UInt32,
    data String
) ENGINE = MergeTree
ORDER BY id;

CREATE TABLE events_alias ENGINE = Alias('events');

-- Multiple inserts create multiple parts
INSERT INTO events_alias VALUES (1, 'data1');
INSERT INTO events_alias VALUES (2, 'data2');
INSERT INTO events_alias VALUES (3, 'data3');

-- Check parts count
SELECT count() FROM system.parts 
WHERE database = currentDatabase() 
  AND table = 'events' 
  AND active;

-- Optimize through alias
OPTIMIZE TABLE events_alias FINAL;

-- Parts are merged in target table
SELECT count() FROM system.parts 
WHERE database = currentDatabase() 
  AND table = 'events' 
  AND active;  -- Returns 1
```

<h3 id="alias-management">
  Alias Management
</h3>

Aliases can be renamed or dropped independently:

```sql theme={null}
CREATE TABLE important_data (
    id UInt32,
    value String
) ENGINE = MergeTree
ORDER BY id;

INSERT INTO important_data VALUES (1, 'critical'), (2, 'important');

CREATE TABLE old_alias ENGINE = Alias('important_data');

-- Rename alias (target table unchanged)
RENAME TABLE old_alias TO new_alias;

-- Create another alias to same table
CREATE TABLE another_alias ENGINE = Alias('important_data');

-- Drop one alias (target table and other aliases unchanged)
DROP TABLE new_alias;

SELECT * FROM another_alias;  -- Still works
SELECT count() FROM important_data;  -- Data intact, returns 2
```