Skip to content

Commit dfae5df

Browse files
authored
Update 92-attach-table.md
1 parent 2f395f8 commit dfae5df

File tree

1 file changed

+104
-41
lines changed

1 file changed

+104
-41
lines changed

docs/en/sql-reference/10-sql-commands/00-ddl/01-table/92-attach-table.md

Lines changed: 104 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -11,70 +11,133 @@ import EEFeature from '@site/src/components/EEFeature';
1111

1212
<EEFeature featureName='ATTACH TABLE'/>
1313

14-
Attaches an existing table to another one. The command moves the data and schema of a table from one database to another, but without actually copying the data. Instead, it creates a link that points to the original table data for accessing the data.
14+
ATTACH TABLE creates a read-only link to existing table data without copying it. This command is ideal for data sharing across environments, especially when migrating from a private Databend deployment to [Databend Cloud](https://www.databend.com).
1515

16-
- Attach Table enables you to seamlessly connect a table in the cloud service platform to an existing table deployed in a private deployment environment without the need to physically move the data. This is particularly useful when you want to migrate data from a private deployment of Databend to [Databend Cloud](https://www.databend.com) while minimizing the data transfer overhead.
16+
## Key Features
1717

18-
- The attached table operates in READ_ONLY mode. In this mode, changes in the source table are instantly reflected in the attached table. However, the attached table is exclusively for querying purposes and does not support updates. This means INSERT, UPDATE, and DELETE operations are not allowed on the attached table; only SELECT queries can be executed.
18+
- **Zero-Copy Data Access**: Links to source data without physical data movement
19+
- **Real-Time Updates**: Changes in the source table are instantly visible in attached tables
20+
- **Read-Only Mode**: Only supports SELECT queries (no INSERT, UPDATE, or DELETE operations)
21+
- **Column-Level Access**: Optionally include only specific columns for security and performance
1922

2023
## Syntax
2124

2225
```sql
2326
ATTACH TABLE <target_table_name> [ ( <column_list> ) ] '<source_table_data_URI>'
24-
CONNECTION = ( <connection_parameters> )
27+
CONNECTION = ( CONNECTION_NAME = '<connection_name>' )
2528
```
26-
- `<column_list>`: An optional, comma-separated list of columns to include from the source table, allowing users to specify only the necessary columns instead of including all of them. If not specified, all columns from the source table will be included.
2729

28-
- Renaming an included column in the source table updates its name in the attached table, and it must be accessed using the new name.
29-
- Dropping an included column in the source table makes it inaccessible in the attached table.
30-
- Changes to non-included columns, such as renaming or dropping them in the source table, do not affect the attached table.
30+
### Parameters
3131

32-
- `<source_table_data_URI>` represents the path to the source table's data. For S3-like object storage, the format is `s3://<bucket-name>/<database_ID>/<table_ID>`, for example, _s3://databend-toronto/1/23351/_, which represents the exact path to the table folder within the bucket.
32+
- **`<target_table_name>`**: Name of the new attached table to create
3333

34-
![Alt text](/img/sql/attach.png)
34+
- **`<column_list>`**: Optional list of columns to include from the source table
35+
- When omitted, all columns are included
36+
- Provides column-level security and access control
37+
- Example: `(customer_id, product, amount)`
3538

36-
To obtain the database ID and table ID of a table, use the [FUSE_SNAPSHOT](../../../20-sql-functions/16-system-functions/fuse_snapshot.md) function. In the example below, the part **1/23351/** in the value of _snapshot_location_ indicates that the database ID is **1**, and the table ID is **23351**.
39+
- **`<source_table_data_URI>`**: Path to the source table data in object storage
40+
- Format: `s3://<bucket-name>/<database_ID>/<table_ID>/`
41+
- Example: `s3://databend-toronto/1/23351/`
3742

38-
```sql
39-
SELECT * FROM FUSE_SNAPSHOT('default', 'employees');
43+
- **`CONNECTION_NAME`**: References a connection created with [CREATE CONNECTION](../13-connection/create-connection.md)
4044

41-
Name |Value |
42-
--------------------+---------------------------------------------------+
43-
snapshot_id |d6cd1f3afc3f4ad4af298ad94711ead1 |
44-
snapshot_location |1/23351/_ss/d6cd1f3afc3f4ad4af298ad94711ead1_v4.mpk|
45-
format_version |4 |
46-
previous_snapshot_id| |
47-
segment_count |1 |
48-
block_count |1 |
49-
row_count |3 |
50-
bytes_uncompressed |122 |
51-
bytes_compressed |523 |
52-
index_size |470 |
53-
timestamp |2023-07-11 05:38:27.0 |
54-
```
45+
### Finding the Source Table Path
5546

56-
- `CONNECTION` specifies the connection parameters required for establishing a link to the object storage where the source table's data is stored. The connection parameters vary for different storage services based on their specific requirements and authentication mechanisms. For more information, see [Connection Parameters](../../../00-sql-reference/51-connect-parameters.md).
47+
Use the [FUSE_SNAPSHOT](../../../20-sql-functions/16-system-functions/fuse_snapshot.md) function to get the database and table IDs:
5748

58-
## Tutorials
49+
```sql
50+
SELECT snapshot_location FROM FUSE_SNAPSHOT('default', 'employees');
51+
-- Result contains: 1/23351/_ss/... → Path is s3://your-bucket/1/23351/
52+
```
5953

60-
- [Linking Tables with ATTACH TABLE](/tutorials/databend-cloud/link-tables)
54+
## Data Sharing Benefits
55+
56+
### How It Works
57+
58+
```
59+
Object Storage (S3, MinIO, Azure, etc.)
60+
┌─────────────┐
61+
│ Source Data │
62+
└──────┬──────┘
63+
64+
┌───────────────────────┼───────────────────────┐
65+
│ │ │
66+
▼ ▼ ▼
67+
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
68+
│ Marketing │ │ Finance │ │ Sales │
69+
│ Team View │ │ Team View │ │ Team View │
70+
└─────────────┘ └─────────────┘ └─────────────┘
71+
```
72+
73+
### Key Advantages
74+
75+
| Traditional Approach | Databend ATTACH TABLE |
76+
|---------------------|----------------------|
77+
| Multiple data copies | Single copy shared by all |
78+
| ETL delays, sync issues | Real-time, always current |
79+
| Complex maintenance | Zero maintenance |
80+
| More copies = more security risk | Fine-grained column access |
81+
| Slower due to data movement | Full optimization on original data |
82+
83+
### Security and Performance
84+
85+
- **Column-Level Security**: Teams see only the columns they need
86+
- **Real-Time Updates**: Source changes instantly visible in all attached tables
87+
- **Strong Consistency**: Always see complete data snapshots, never partial updates
88+
- **Full Performance**: Inherit all source table indexes and optimizations
6189

6290
## Examples
6391

64-
This example creates an attached table, which includes all columns from a source table stored in AWS S3:
92+
### Basic Usage
6593

6694
```sql
67-
ATTACH TABLE population_all_columns 's3://databend-doc/1/16/' CONNECTION = (
68-
ACCESS_KEY_ID = '<your_aws_key_id>',
69-
SECRET_ACCESS_KEY = '<your_aws_secret_key>'
70-
);
95+
-- Step 1: Create a connection to your storage
96+
CREATE CONNECTION my_s3_connection
97+
STORAGE_TYPE = 's3'
98+
ACCESS_KEY_ID = '<your_aws_key_id>'
99+
SECRET_ACCESS_KEY = '<your_aws_secret_key>';
100+
101+
-- Step 2: Attach a table with all columns
102+
ATTACH TABLE population_all_columns 's3://databend-doc/1/16/'
103+
CONNECTION = (CONNECTION_NAME = 'my_s3_connection');
71104
```
72105

73-
This example creates an attached table, which includes only selected columns (`city` and `population`) from a source table stored in AWS S3:
106+
### Column Selection for Security
74107

75108
```sql
76-
ATTACH TABLE population_only (city, population) 's3://databend-doc/1/16/' CONNECTION = (
77-
ACCESS_KEY_ID = '<your_aws_key_id>',
78-
SECRET_ACCESS_KEY = '<your_aws_secret_key>'
79-
);
80-
```
109+
-- Attach only specific columns for data security
110+
ATTACH TABLE population_selected (city, population) 's3://databend-doc/1/16/'
111+
CONNECTION = (CONNECTION_NAME = 'my_s3_connection');
112+
```
113+
114+
### Using IAM Role Authentication
115+
116+
```sql
117+
-- Create a connection using IAM role (more secure than access keys)
118+
CREATE CONNECTION s3_role_connection
119+
STORAGE_TYPE = 's3'
120+
ROLE_ARN = 'arn:aws:iam::123456789012:role/databend-role';
121+
122+
-- Attach table using the IAM role connection
123+
ATTACH TABLE population_all_columns 's3://databend-doc/1/16/'
124+
CONNECTION = (CONNECTION_NAME = 's3_role_connection');
125+
```
126+
127+
### Team-Specific Views
128+
129+
```sql
130+
-- Marketing: Customer behavior analysis
131+
ATTACH TABLE marketing_view (customer_id, product, amount, order_date)
132+
's3://your-bucket/1/23351/'
133+
CONNECTION = (CONNECTION_NAME = 'my_s3_connection');
134+
135+
-- Finance: Revenue tracking (different columns)
136+
ATTACH TABLE finance_view (order_id, amount, profit, order_date)
137+
's3://your-bucket/1/23351/'
138+
CONNECTION = (CONNECTION_NAME = 'my_s3_connection');
139+
```
140+
141+
## Learn More
142+
143+
- [Linking Tables with ATTACH TABLE](/tutorials/databend-cloud/link-tables)

0 commit comments

Comments
 (0)