ClickHouse/docs/en/sql-reference/statements/attach.md

82 lines
2.3 KiB
Markdown
Raw Normal View History

2020-07-11 11:05:49 +00:00
---
sidebar_position: 40
sidebar_label: ATTACH
2020-07-11 11:05:49 +00:00
---
2022-06-02 10:55:18 +00:00
# ATTACH Statement
2020-07-11 11:05:49 +00:00
2021-08-01 13:02:35 +00:00
Attaches a table or a dictionary, for example, when moving a database to another server.
**Syntax**
``` sql
2021-08-01 16:17:50 +00:00
ATTACH TABLE|DICTIONARY [IF NOT EXISTS] [db.]name [ON CLUSTER cluster] ...
2021-08-01 13:02:35 +00:00
```
2020-07-11 11:05:49 +00:00
2021-08-01 16:17:50 +00:00
The query does not create data on the disk, but assumes that data is already in the appropriate places, and just adds information about the table or the dictionary to the server. After executing the `ATTACH` query, the server will know about the existence of the table or the dictionary.
2020-07-11 11:05:49 +00:00
2021-08-01 16:17:50 +00:00
If a table was previously detached ([DETACH](../../sql-reference/statements/detach.md) query), meaning that its structure is known, you can use shorthand without defining the structure.
2021-08-01 13:02:35 +00:00
2022-06-02 10:55:18 +00:00
## Attach Existing Table
2021-04-04 12:14:09 +00:00
2021-08-01 13:02:35 +00:00
**Syntax**
2020-07-11 11:05:49 +00:00
``` sql
ATTACH TABLE [IF NOT EXISTS] [db.]name [ON CLUSTER cluster]
```
2021-03-12 16:28:04 +00:00
This query is used when starting the server. The server stores table metadata as files with `ATTACH` queries, which it simply runs at launch (with the exception of some system tables, which are explicitly created on the server).
If the table was detached permanently, it won't be reattached at the server start, so you need to use `ATTACH` query explicitly.
2022-06-02 10:55:18 +00:00
## Create New Table And Attach Data
2021-04-04 12:14:09 +00:00
2022-06-02 10:55:18 +00:00
### With Specified Path to Table Data
2021-04-04 12:14:09 +00:00
2021-08-03 20:47:09 +00:00
The query creates a new table with provided structure and attaches table data from the provided directory in `user_files`.
2021-08-01 13:02:35 +00:00
**Syntax**
2021-04-04 12:14:09 +00:00
```sql
ATTACH TABLE name FROM 'path/to/data/' (col1 Type1, ...)
```
**Example**
Query:
```sql
DROP TABLE IF EXISTS test;
INSERT INTO TABLE FUNCTION file('01188_attach/test/data.TSV', 'TSV', 's String, n UInt8') VALUES ('test', 42);
ATTACH TABLE test FROM '01188_attach/test' (s String, n UInt8) ENGINE = File(TSV);
SELECT * FROM test;
```
Result:
```sql
┌─s────┬──n─┐
│ test │ 42 │
└──────┴────┘
```
2022-06-02 10:55:18 +00:00
### With Specified Table UUID
2021-08-03 20:47:09 +00:00
This query creates a new table with provided structure and attaches data from the table with the specified UUID.
It is supported by the [Atomic](../../engines/database-engines/atomic.md) database engine.
**Syntax**
2021-04-04 12:14:09 +00:00
```sql
ATTACH TABLE name UUID '<uuid>' (col1 Type1, ...)
```
2022-06-02 10:55:18 +00:00
## Attach Existing Dictionary
2021-08-01 13:02:35 +00:00
2021-08-03 20:47:09 +00:00
Attaches a previously detached dictionary.
2021-08-01 13:02:35 +00:00
**Syntax**
``` sql
ATTACH DICTIONARY [IF NOT EXISTS] [db.]name [ON CLUSTER cluster]
```