Skip to content

Commit d0a3b94

Browse files
lilin90lilin90
committed
lake: incremental updates till 0509
1 parent 56534fc commit d0a3b94

13 files changed

Lines changed: 325 additions & 64 deletions

‎TOC-tidb-cloud-lake.md‎

Lines changed: 12 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -342,7 +342,9 @@
342342
- [DROP CONNECTION](/tidb-cloud-lake/sql/drop-connection.md)
343343
- [SHOW CONNECTIONS](/tidb-cloud-lake/sql/show-connections.md)
344344
- Catalog
345+
- [Overview](/tidb-cloud-lake/sql/catalog.md)
345346
- [SHOW CATALOGS](/tidb-cloud-lake/sql/show-catalogs.md)
347+
- [SHOW CREATE CATALOG](/tidb-cloud-lake/sql/show-create-catalog.md)
346348
- File Format
347349
- [Overview](/tidb-cloud-lake/sql/file-format.md)
348350
- [CREATE FILE FORMAT](/tidb-cloud-lake/sql/create-file-format.md)
@@ -422,6 +424,11 @@
422424
- [RENAME DICTIONARY](/tidb-cloud-lake/sql/rename-dictionary.md)
423425
- [SHOW CREATE DICTIONARY](/tidb-cloud-lake/sql/show-create-dictionary.md)
424426
- [SHOW DICTIONARIES](/tidb-cloud-lake/sql/show-dictionaries.md)
427+
- Pipe
428+
- [Overview](/tidb-cloud-lake/sql/pipe.md)
429+
- [CREATE PIPE](/tidb-cloud-lake/sql/create-pipe.md)
430+
- [DESCRIBE PIPE](/tidb-cloud-lake/sql/describe-pipe.md)
431+
- [DROP PIPE](/tidb-cloud-lake/sql/drop-pipe.md)
425432
- Transaction
426433
- [BEGIN](/tidb-cloud-lake/sql/begin.md)
427434
- [COMMIT](/tidb-cloud-lake/sql/commit.md)
@@ -442,12 +449,14 @@
442449
- [SHOW PROCEDURES](/tidb-cloud-lake/sql/show-procedures.md)
443450
- Warehouse
444451
- [Overview](/tidb-cloud-lake/sql/warehouse-overview.md)
445-
- [ALTER WAREHOUSE](/tidb-cloud-lake/sql/alter-warehouse.md)
446452
- [CREATE WAREHOUSE](/tidb-cloud-lake/sql/create-warehouse.md)
453+
- [USE WAREHOUSE](/tidb-cloud-lake/sql/use-warehouse.md)
454+
- [SHOW WAREHOUSES](/tidb-cloud-lake/sql/show-warehouses.md)
455+
- [ALTER WAREHOUSE](/tidb-cloud-lake/sql/alter-warehouse.md)
456+
- [ALTER WAREHOUSE ASSIGN NODES](/tidb-cloud-lake/sql/alter-warehouse-assign-nodes.md)
457+
- [ALTER WAREHOUSE UNASSIGN NODES](/tidb-cloud-lake/sql/alter-warehouse-unassign-nodes.md)
447458
- [DROP WAREHOUSE](/tidb-cloud-lake/sql/drop-warehouse.md)
448459
- [QUERY_HISTORY](/tidb-cloud-lake/sql/query-history.md)
449-
- [SHOW WAREHOUSES](/tidb-cloud-lake/sql/show-warehouses.md)
450-
- [USE WAREHOUSE](/tidb-cloud-lake/sql/use-warehouse.md)
451460
- Worker
452461
- [Overview](/tidb-cloud-lake/sql/worker-overview.md)
453462
- [CREATE WORKER](/tidb-cloud-lake/sql/create-worker.md)

‎tidb-cloud-lake/guides/mcp-client-integration.md‎

Lines changed: 88 additions & 45 deletions
Original file line numberDiff line numberDiff line change
@@ -5,53 +5,57 @@ summary: "{{{ .lake }}} MCP connects AI assistants to {{{ .lake }}} via Model Co
55

66
# MCP Client Integration
77

8-
[{{{ .lake }}} MCP](https://github.com/databendlabs/mcp-databend) connects AI assistants to {{{ .lake }}} via Model Context Protocol. Works with Claude Code, Codex, Cursor, Claude Desktop, VS Code, and other MCP-compatible clients.
8+
[{{{ .lake }}} MCP](https://github.com/databendlabs/mcp-databend) connects AI assistants to {{{ .lake }}} through the Model Context Protocol. It works with Codex, Kimi Code, Cursor, Claude Code, Claude Desktop, Gemini CLI, VS Code, and other MCP-compatible clients.
99

1010
**What you can do:**
1111

12-
- Generate complex SQL queries based on your requirements
13-
- Create and manage scheduled data pipeline tasks
14-
- Explore database schemas and validate query syntax
15-
- Build ETL workflows with COPY, MERGE, and Stage operations
12+
- Generate complex SQL queries from natural language requirements.
13+
- Explore databases, tables, schemas, stages, and connections.
14+
- Validate query syntax before running it.
15+
- Build ETL workflows with COPY, MERGE, and Stage operations.
16+
- Create and manage scheduled data pipeline tasks.
1617

17-
For example: _"Create a scheduled task that copies parquet files from @my_stage to the orders table every minute, and verify it's running correctly."_
18+
For example: "Create a scheduled task that copies parquet files from @my_stage to the orders table every minute, and verify that it is running correctly."
1819

1920
## Installation
2021

21-
### 1. Get {{{ .lake }}} Connection
22+
### 1. Get a {{{ .lake }}} Connection
2223

2324
We recommend using **{{{ .lake }}}** for the best experience.
2425

2526
1. Log in to [{{{ .lake }}}](https://app.lake.tidbcloud.com).
26-
2. Click **Use with AI Tools** in the navigation bar.
27-
3. Select regular connection information (Host, User, Password, etc.).
28-
4. Copy your DSN, which looks like `lake://user:pwd@host:443/database?warehouse=warehouse_name`.
27+
2. Click **Use with AI Tools**.
28+
3. Choose the database and warehouse for the MCP server.
29+
4. Keep **Session Sandbox Safety** enabled unless you explicitly need the agent to write to production objects.
30+
5. Copy the DSN, which looks like `lake://user:password@host:443/database?warehouse=warehouse_name`.
2931

3032
![Use with AI Tools](/media/tidb-cloud-lake/ai-tools.png)
3133

3234
### 2. Configure Your MCP Client
3335

36+
Use `DATABEND_MCP_SAFE_MODE=true` by default. In safe mode, production data remains read-only for AI agents, while write operations are scoped to session sandbox objects.
37+
3438
<SimpleTab groupId="mcp-clients">
3539

3640
<div label="Codex" value="codex">
3741

3842
```bash
3943
codex mcp add databend \
40-
--env DATABEND_DSN='lake://user:password@host:port/database?warehouse=your_warehouse' \
41-
--env SAFE_MODE='false' \
42-
-- uv tool run mcp-databend
44+
--env DATABEND_DSN='lake://user:password@host:443/database?warehouse=your_warehouse' \
45+
--env DATABEND_MCP_SAFE_MODE=true \
46+
-- uv tool run --from mcp-databend@latest mcp-databend
4347
```
4448

4549
Or add to `~/.codex/config.toml`:
4650

4751
```toml
4852
[mcp_servers.databend]
4953
command = "uv"
50-
args = ["tool", "run", "mcp-databend"]
54+
args = ["tool", "run", "--from", "mcp-databend@latest", "mcp-databend"]
5155

5256
[mcp_servers.databend.env]
53-
DATABEND_DSN = "lake://user:password@host:port/database?warehouse=your_warehouse"
54-
SAFE_MODE = "false"
57+
DATABEND_DSN = "lake://user:password@host:443/database?warehouse=your_warehouse"
58+
DATABEND_MCP_SAFE_MODE = "true"
5559
```
5660

5761
</div>
@@ -60,26 +64,33 @@ SAFE_MODE = "false"
6064

6165
```bash
6266
claude mcp add databend \
63-
--env DATABEND_DSN='lake://user:password@host:port/database?warehouse=your_warehouse' \
64-
--env SAFE_MODE='false' \
65-
-- uv tool run mcp-databend
67+
--env DATABEND_DSN='lake://user:password@host:443/database?warehouse=your_warehouse' \
68+
--env DATABEND_MCP_SAFE_MODE=true \
69+
-- uv tool run --from mcp-databend@latest mcp-databend
6670
```
6771

6872
</div>
6973

70-
<div label="Gemini CLI" value="gemini-cli">
74+
<div label="Kimi Code" value="kimi-code">
7175

72-
Add to `~/.gemini/settings.json`:
76+
```bash
77+
kimi mcp add --transport stdio databend \
78+
--env DATABEND_DSN='lake://user:password@host:443/database?warehouse=your_warehouse' \
79+
--env DATABEND_MCP_SAFE_MODE=true \
80+
-- uv tool run --from mcp-databend@latest mcp-databend
81+
```
82+
83+
Or add to `~/.kimi/mcp.json`:
7384

7485
```json
7586
{
7687
"mcpServers": {
7788
"databend": {
7889
"command": "uv",
79-
"args": ["tool", "run", "mcp-databend"],
90+
"args": ["tool", "run", "--from", "mcp-databend@latest", "mcp-databend"],
8091
"env": {
81-
"DATABEND_DSN": "lake://user:password@host:port/database?warehouse=your_warehouse",
82-
"SAFE_MODE": "false"
92+
"DATABEND_DSN": "lake://user:password@host:443/database?warehouse=your_warehouse",
93+
"DATABEND_MCP_SAFE_MODE": "true"
8394
}
8495
}
8596
}
@@ -97,10 +108,31 @@ Add to `~/.cursor/mcp.json`:
97108
"mcpServers": {
98109
"databend": {
99110
"command": "uv",
100-
"args": ["tool", "run", "mcp-databend"],
111+
"args": ["tool", "run", "--from", "mcp-databend@latest", "mcp-databend"],
101112
"env": {
102-
"DATABEND_DSN": "lake://user:password@host:port/database?warehouse=your_warehouse",
103-
"SAFE_MODE": "false"
113+
"DATABEND_DSN": "lake://user:password@host:443/database?warehouse=your_warehouse",
114+
"DATABEND_MCP_SAFE_MODE": "true"
115+
}
116+
}
117+
}
118+
}
119+
```
120+
121+
</div>
122+
123+
<div label="Gemini CLI" value="gemini-cli">
124+
125+
Add to `~/.gemini/settings.json`:
126+
127+
```json
128+
{
129+
"mcpServers": {
130+
"databend": {
131+
"command": "uv",
132+
"args": ["tool", "run", "--from", "mcp-databend@latest", "mcp-databend"],
133+
"env": {
134+
"DATABEND_DSN": "lake://user:password@host:443/database?warehouse=your_warehouse",
135+
"DATABEND_MCP_SAFE_MODE": "true"
104136
}
105137
}
106138
}
@@ -111,17 +143,17 @@ Add to `~/.cursor/mcp.json`:
111143

112144
<div label="Claude Desktop" value="claude-desktop">
113145

114-
Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%/Claude/claude_desktop_config.json` (Windows):
146+
Add to `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS, or `%APPDATA%\Claude\claude_desktop_config.json` on Windows:
115147

116148
```json
117149
{
118150
"mcpServers": {
119151
"databend": {
120152
"command": "uv",
121-
"args": ["tool", "run", "mcp-databend"],
153+
"args": ["tool", "run", "--from", "mcp-databend@latest", "mcp-databend"],
122154
"env": {
123-
"DATABEND_DSN": "lake://user:password@host:port/database?warehouse=your_warehouse",
124-
"SAFE_MODE": "false"
155+
"DATABEND_DSN": "lake://user:password@host:443/database?warehouse=your_warehouse",
156+
"DATABEND_MCP_SAFE_MODE": "true"
125157
}
126158
}
127159
}
@@ -132,17 +164,17 @@ Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)
132164

133165
<div label="VS Code" value="vscode">
134166

135-
Add to `.vscode/mcp.json`:
167+
Open **Preferences: Open User Settings (JSON)** and add:
136168

137169
```json
138170
{
139-
"mcpServers": {
171+
"mcp.servers": {
140172
"databend": {
141173
"command": "uv",
142-
"args": ["tool", "run", "mcp-databend"],
174+
"args": ["tool", "run", "--from", "mcp-databend@latest", "mcp-databend"],
143175
"env": {
144-
"DATABEND_DSN": "lake://user:password@host:port/database?warehouse=your_warehouse",
145-
"SAFE_MODE": "false"
176+
"DATABEND_DSN": "lake://user:password@host:443/database?warehouse=your_warehouse",
177+
"DATABEND_MCP_SAFE_MODE": "true"
146178
}
147179
}
148180
}
@@ -154,15 +186,26 @@ Add to `.vscode/mcp.json`:
154186
<div label="Manual" value="manual">
155187

156188
```bash
157-
export DATABEND_DSN="lake://user:password@host:port/database?warehouse=your_warehouse"
158-
export SAFE_MODE="false"
189+
export DATABEND_DSN="lake://user:password@host:443/database?warehouse=your_warehouse"
190+
export DATABEND_MCP_SAFE_MODE=true
159191

160-
uv tool run mcp-databend
192+
uv tool run --from mcp-databend@latest mcp-databend
161193
```
162194

163195
</div>
164196
</SimpleTab>
165197

198+
## Session Sandbox Safety
199+
200+
`DATABEND_MCP_SAFE_MODE` controls whether the MCP server runs with session sandbox protection.
201+
202+
| Value | Behavior | Recommended usage |
203+
| ----- | -------- | ----------------- |
204+
| `true` | Production objects are read-only for the agent. Write operations are allowed only on session sandbox objects such as `mcp_sandbox_{session_id}_*`. | Default and recommended for AI tools. |
205+
| `false` | The MCP server can write to objects allowed by the {{{ .lake}}} user permissions. | Use only with trusted agents and least-privilege {{{ .lake}}} users. |
206+
207+
Keep safe mode enabled for most workflows. Disable it only when the agent must modify real production objects and the {{{ .lake}}} user already has the minimum required permissions.
208+
166209
## Available Tools
167210

168211
### Database Operations
@@ -171,7 +214,7 @@ uv tool run mcp-databend
171214
| ---------------- | ------------------------------------------------ |
172215
| `execute_sql` | Execute SQL queries with timeout protection |
173216
| `show_databases` | List all databases |
174-
| `show_tables` | List tables in a database (with optional filter) |
217+
| `show_tables` | List tables in a database with optional filter |
175218
| `describe_table` | Get table schema information |
176219

177220
### Stage Management
@@ -190,10 +233,10 @@ uv tool run mcp-databend
190233

191234
## Configuration
192235

193-
| Variable | Description | Default |
194-
| ------------------------ | ------------------------------------------------------- | -------- |
195-
| `DATABEND_DSN` | Connection string | Required |
196-
| `SAFE_MODE` | Block dangerous SQL operations (`DROP`, `DELETE`, etc.) | `true` |
197-
| `DATABEND_QUERY_TIMEOUT` | Query timeout in seconds | `300` |
236+
| Variable | Description | Default |
237+
| ------------------------ | ---------------------------------------------- | -------- |
238+
| `DATABEND_DSN` | {{{ .lake }}} connection string | Required |
239+
| `DATABEND_MCP_SAFE_MODE` | Enable session sandbox protection for AI tools | `true` |
240+
| `DATABEND_QUERY_TIMEOUT` | Query timeout in seconds | `300` |
198241

199242
For more details on building conversational BI tools, see [MCP Server Guide](/tidb-cloud-lake/guides/mcp-server.md).

‎tidb-cloud-lake/guides/track-metrics.md‎

Lines changed: 16 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -100,28 +100,29 @@ The following is a list of storage metrics available in {{{ .lake }}}:
100100

101101
| Name | Type | Labels | Description |
102102
| ----------------------------- | ----- | ------ | ----------------------------------------------------- |
103-
| storage_total_size | Guage | tenant | Total size for backend object storage |
104-
| storage_staged_size | Guage | tenant | Total size for staged files on backend object storage |
105-
| storage_table_compressed_size | Guage | tenant | Total size for current tables backend object storage |
106-
| storage_non_current_size | Guage | tenant | Total size for non-current objects in backend storage |
103+
| storage_total_size | Gauge | tenant | Total size for backend object storage |
104+
| storage_staged_size | Gauge | tenant | Total size for staged files on backend object storage |
105+
| storage_table_compressed_size | Gauge | tenant | Total size for current tables backend object storage |
106+
| storage_non_current_size | Gauge | tenant | Total size for non-current objects in backend storage |
107107

108108
### Warehouse Metrics
109109

110110
The following is a list of warehouse metrics available in {{{ .lake }}}:
111111

112112
| Name | Type | Labels | Description |
113113
| -------------------------------- | ------- | ---------------------------- | --------------------------------------------------- |
114-
| warehouse_status | Guage | tenant,warehouse,size,status | Flag for warehouse status (Suspended,Running, etc.) |
115-
| warehouse_connections | Guage | tenant,warehouse | Session Count currently |
116-
| warehouse_queries_queued | Guage | tenant,warehouse | Queries waiting in queue currently |
117-
| warehouse_queries_running | Guage | tenant,warehouse | Queries running currently |
118-
| warehouse_queries_start_total | Counter | tenant,warehouse | Queries started total |
119-
| warehouse_queries_failed_total | Counter | tenant,warehouse | Queries failed total |
120-
| warehouse_queries_success_total | Counter | tenant,warehouse | Queries success total |
121-
| warehouse_storage_requests_total | Counter | tenant,warehouse,scheme,op | Requests count to backend storage |
122-
| warehouse_storage_requests_bytes | Counter | tenant,warehouse,scheme,op | Requests bytes from backend storage |
123-
| warehouse_data_scan_rows | Counter | tenant,warehouse | Data rows scanned from backend storage |
124-
| warehouse_data_write_rows | Counter | tenant,warehouse | Data rows written to backend storage |
114+
| warehouse_status | Gauge | tenant,warehouse,size,status | Flag for warehouse status (Suspended,Running, etc.) |
115+
| warehouse_running_clusters | Gauge | tenant,warehouse | Number of running clusters for a warehouse (multi-cluster warehouses only) |
116+
| warehouse_connections | Gauge | tenant,warehouse,warehouse_cluster | Session Count currently |
117+
| warehouse_queries_queued | Gauge | tenant,warehouse,warehouse_cluster | Queries waiting in queue currently |
118+
| warehouse_queries_running | Gauge | tenant,warehouse,warehouse_cluster | Queries running currently |
119+
| warehouse_queries_start_total | Counter | tenant,warehouse,warehouse_cluster | Queries started total |
120+
| warehouse_queries_failed_total | Counter | tenant,warehouse,warehouse_cluster | Queries failed total |
121+
| warehouse_queries_success_total | Counter | tenant,warehouse,warehouse_cluster | Queries success total |
122+
| warehouse_storage_requests_total | Counter | tenant,warehouse,warehouse_cluster,scheme,op | Requests count to backend storage |
123+
| warehouse_storage_requests_bytes | Counter | tenant,warehouse,warehouse_cluster,scheme,op | Requests bytes from backend storage |
124+
| warehouse_data_scan_rows | Counter | tenant,warehouse,warehouse_cluster | Data rows scanned from backend storage |
125+
| warehouse_data_write_rows | Counter | tenant,warehouse,warehouse_cluster | Data rows written to backend storage |
125126

126127
### Task Metrics
127128

‎tidb-cloud-lake/sql/alter-warehouse-assign-nodes.md‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
---
2+
title: ALTER WAREHOUSE ASSIGN NODES
3+
summary: "Learn how to use the ALTER WAREHOUSE ASSIGN NODES command to assign nodes to clusters in a warehouse in {{{ .lake }}}."
4+
---
5+
6+
# ALTER WAREHOUSE ASSIGN NODES
7+
8+
Assigns nodes to one or more clusters in a warehouse.
9+
10+
> **Note:**
11+
>
12+
> This command requires system management support and an enterprise license.
13+
14+
## Syntax
15+
16+
```sql
17+
ALTER WAREHOUSE <warehouse_name> ASSIGN NODES
18+
(
19+
ASSIGN <node_count> NODES [ FROM '<node_group>' ] FOR <cluster_name>
20+
[ , ASSIGN <node_count> NODES [ FROM '<node_group>' ] FOR <cluster_name> , ... ]
21+
)
22+
```
23+
24+
## Parameters
25+
26+
| Parameter | Description |
27+
|-----------|-------------|
28+
| `<warehouse_name>` | The target warehouse. |
29+
| `<node_count>` | Number of nodes to assign. |
30+
| `FROM '<node_group>'` | Optional node group selector. |
31+
| `<cluster_name>` | The target cluster inside the warehouse. |
32+
33+
## Example
34+
35+
```sql
36+
ALTER WAREHOUSE etl_wh ASSIGN NODES
37+
(
38+
ASSIGN 2 NODES FOR c1,
39+
ASSIGN 1 NODES FROM 'default' FOR c2
40+
);
41+
```

0 commit comments

Comments
 (0)