docs: update warehouse SQL (#3059)

Author: everpcpc

docs/en/sql-reference/10-sql-commands/00-ddl/19-warehouse/alter-warehouse.md

@@ -23,6 +23,12 @@ ALTER WAREHOUSE <warehouse_name>
     [ WITH ] max_cluster_count = <nullable_unsigned_number>
     [ WITH ] min_cluster_count = <nullable_unsigned_number>
     [ WITH ] comment = '<string_literal>'
+
+ALTER WAREHOUSE <warehouse_name> SET TAG <tag_name> = '<tag_value>' [ , <tag_name> = '<tag_value>' ... ]
+
+ALTER WAREHOUSE <warehouse_name> UNSET TAG <tag_name> [ , <tag_name> ... ]
+
+ALTER WAREHOUSE <warehouse_name> RENAME TO <new_name>
 ```
 
 | Parameter | Description |
@@ -46,6 +52,9 @@ The `SET` clause accepts the same options as [CREATE WAREHOUSE](create-warehouse
 
 - `NULL` is valid for numeric options to reset them to `0`.
 - Supplying `SET` with no options raises an error.
+- `SET TAG` adds or updates one or more tags. Multiple tags can be set in a single statement separated by commas.
+- `UNSET TAG` removes one or more tags by their keys. Non-existent tag keys are silently ignored.
+- `RENAME TO` requires the warehouse to be suspended and uses the same naming rules as `CREATE`.
 
 ## Examples
 
@@ -75,3 +84,12 @@ Disable auto-suspend:
 ```sql
 ALTER WAREHOUSE my_wh SET auto_suspend = NULL;
 ```
+
+Manage tags:
+
+```sql
+ALTER WAREHOUSE wh_hot SET TAG environment = 'production';
+ALTER WAREHOUSE wh_hot SET TAG environment = 'staging', owner = 'john', cost_center = 'eng';
+ALTER WAREHOUSE wh_hot UNSET TAG environment;
+ALTER WAREHOUSE wh_hot UNSET TAG environment, owner, cost_center;
+```

docs/en/sql-reference/10-sql-commands/00-ddl/19-warehouse/create-warehouse.md

@@ -20,6 +20,7 @@ CREATE WAREHOUSE [ IF NOT EXISTS ] <warehouse_name>
     [ WITH ] max_cluster_count = <nullable_unsigned_number>
     [ WITH ] min_cluster_count = <nullable_unsigned_number>
     [ WITH ] comment = '<string_literal>'
+    [ WITH ] TAG ( <tag_name> = '<tag_value>' [ , <tag_name> = '<tag_value>' , ... ] )
 ```
 
 | Parameter | Description |
@@ -38,6 +39,7 @@ CREATE WAREHOUSE [ IF NOT EXISTS ] <warehouse_name>
 | `MAX_CLUSTER_COUNT` | `NULL` or non-negative integer | `0` | Upper bound for auto-scaling clusters. `0` disables auto-scale. |
 | `MIN_CLUSTER_COUNT` | `NULL` or non-negative integer | `0` | Lower bound for auto-scaling clusters; should be ≤ `MAX_CLUSTER_COUNT`. |
 | `COMMENT` | String | Empty | Free-form text surfaced by `SHOW WAREHOUSES`. |
+| `TAG` | Key-value pairs: `TAG ( key1 = 'value1', key2 = 'value2' )` | None | Resource tags for categorization and organization (similar to AWS tags). Used for cost allocation, environment identification, or team ownership. |
 
 - Options may appear in any order and may repeat (the later value wins).
 - `AUTO_SUSPEND`, `MAX_CLUSTER_COUNT`, and `MIN_CLUSTER_COUNT` accept `= NULL` to reset to `0`.
@@ -54,7 +56,8 @@ CREATE WAREHOUSE IF NOT EXISTS etl_wh
     auto_resume = FALSE
     max_cluster_count = 4
     min_cluster_count = 2
-    comment = 'Nightly ETL warehouse';
+    comment = 'Nightly ETL warehouse'
+    TAG (environment = 'production', team = 'data-engineering', cost_center = 'analytics');
 ```
 
 This example creates a basic Small warehouse:

docs/en/sql-reference/10-sql-commands/00-ddl/19-warehouse/index.md

@@ -8,10 +8,44 @@ Warehouse-related SQL commands for Databend Cloud.
 ## General Rules
 
 - **Warehouse naming**: 3–63 characters, `A-Z`, `a-z`, `0-9`, and `-` only.
-- **Identifiers**: Bare identifiers may omit quotes when they contain no spaces or special characters; otherwise enclose with single quotes.
-- **Numeric parameters**: Accept integers or `NULL`. Supplying `NULL` resets the value to default (e.g., `AUTO_SUSPEND = NULL` equals `0`).
+- **Strings and identifiers**: Bare identifiers may omit quotes when they contain no spaces; otherwise enclose with single quotes. Grammar allows keywords or numeric/boolean literals as names, but runtime validation still applies.
+- **Numeric parameters**: `nullable_unsigned_number` / `nullable_signed_number` accept integers or `NULL`. Supplying `NULL` resets the value (for example, `AUTO_SUSPEND = NULL` equals `0`).
+- **Time parameters**: `QUERY_HISTORY` uses `YYYY-MM-DD HH:MM:SS` (UTC or explicit timezone). Missing fractional seconds are interpreted as whole seconds.
 - **Boolean parameters**: Only `TRUE`/`FALSE` are accepted.
-- **`WITH` keyword**: May appear before the entire option list or ahead of each option. Options are whitespace-separated.
+- **`WITH` keyword**: May appear before the entire option list or ahead of each option. Options are whitespace-separated; commas are not part of the grammar.
+
+## Warehouse Management
+
+Tags are key-value pairs that help categorize and organize warehouses, similar to AWS resource tags. They are commonly used for:
+
+- **Cost allocation**: Track warehouse costs by team, project, or cost center
+- **Environment identification**: Mark warehouses as dev, staging, or production
+- **Team ownership**: Identify which team owns or manages a warehouse
+- **Custom metadata**: Add any arbitrary metadata for organizational purposes
+
+Tag keys and values are arbitrary strings (enclosed in quotes if they contain spaces or special characters). Tags can be:
+- Added at warehouse creation time using `WITH TAG (key = 'value', ...)`
+- Updated or added later using `ALTER WAREHOUSE ... SET TAG key = 'value'`
+- Removed using `ALTER WAREHOUSE ... UNSET TAG key`
+
+Tags are returned in API responses and visible through `SHOW WAREHOUSES`.
+
+**Tag Limits:**
+- Maximum 10 tags per warehouse
+- Tag name (key) maximum length: 128 characters
+- Tag value maximum length: 256 characters
+
+## Supported Statements
+
+| Statement           | Purpose                      | Notes                                                               |
+| ------------------- | ---------------------------- | ------------------------------------------------------------------- |
+| `CREATE WAREHOUSE`  | Create a warehouse           | Supports `IF NOT EXISTS` and option list                            |
+| `REPLACE WAREHOUSE` | Recreate a warehouse         | Same semantics as `CREATE WAREHOUSE`, handy for overwriting configs |
+| `ALTER WAREHOUSE`   | Suspend/resume/mutate/rename | `SUSPEND`/`RESUME`, `SET <options>`, or `RENAME TO <name>`          |
+| `DROP WAREHOUSE`    | Delete a warehouse           | Optional `IF EXISTS`                                                |
+| `USE WAREHOUSE`     | Bind the current session     | Validates existence only                                            |
+| `SHOW WAREHOUSES`   | List warehouses              | Optional `LIKE` filter                                              |
+| `QUERY_HISTORY`     | Inspect query logs           | Filter by warehouse, time range, limit                              |
 
 ## Warehouse Management
 

docs/en/sql-reference/10-sql-commands/00-ddl/19-warehouse/query-history.md

@@ -22,8 +22,8 @@ QUERY_HISTORY
 | Parameter | Description |
 |-----------|-------------|
 | `BY WAREHOUSE` | Optional. Filters logs to a specific warehouse. Empty names raise an error. |
-| `FROM` | Optional. Start timestamp for the query range. Format: `YYYY-MM-DD HH:MM:SS`. Defaults to 1 hour before `TO`. |
-| `TO` | Optional. End timestamp for the query range. Format: `YYYY-MM-DD HH:MM:SS`. Defaults to current time. |
+| `FROM` | Optional. Start timestamp for the query range. Format: `YYYY-MM-DD HH:MM:SS` (UTC or explicit timezone). Defaults to 1 hour before `TO`. |
+| `TO` | Optional. End timestamp for the query range. Format: `YYYY-MM-DD HH:MM:SS` (UTC or explicit timezone). Defaults to current time. |
 | `LIMIT` | Optional. Maximum number of records to return. Defaults to `10`. Must be a positive integer. |
 
 ## Output Columns

docs/en/sql-reference/10-sql-commands/00-ddl/19-warehouse/replace-warehouse.md

@@ -20,6 +20,7 @@ REPLACE WAREHOUSE <warehouse_name>
     [ WITH ] max_cluster_count = <nullable_unsigned_number>
     [ WITH ] min_cluster_count = <nullable_unsigned_number>
     [ WITH ] comment = '<string_literal>'
+    [ WITH ] TAG ( <tag_name> = '<tag_value>' [ , <tag_name> = '<tag_value>' , ... ] )
 ```
 
 | Parameter | Description |

docs/en/sql-reference/10-sql-commands/00-ddl/19-warehouse/show-warehouses.md

@@ -12,12 +12,13 @@ Lists all warehouses visible to the current tenant.
 ## Syntax
 
 ```sql
-SHOW WAREHOUSES [ LIKE '<pattern>' ]
+SHOW WAREHOUSES [ LIKE '<pattern>' ] [ <pattern_without_like> ]
 ```
 
 | Parameter | Description |
 |-----------|-------------|
 | `LIKE '<pattern>'` | Optional. Filters warehouse names using SQL `LIKE` semantics (`%` matches any sequence, `_` matches any single character). |
+| `<pattern_without_like>` | Optional. When `LIKE` is omitted but a literal follows, it is treated as `LIKE '<literal>'`. |
 
 ## Output Columns
 
@@ -30,7 +31,10 @@ SHOW WAREHOUSES [ LIKE '<pattern>' ]
 | `auto_resume` | Whether auto-resume is enabled |
 | `min_cluster_count` | Minimum cluster count for auto-scaling |
 | `max_cluster_count` | Maximum cluster count for auto-scaling |
+| `role` | Warehouse role |
 | `comment` | User-defined comment |
+| `tags` | Warehouse tags as a JSON-formatted string |
+| `created_by` | Creator |
 | `created_on` | Creation timestamp |
 
 ## Examples
@@ -46,3 +50,9 @@ List warehouses matching a pattern:
 ```sql
 SHOW WAREHOUSES LIKE '%prod%';
 ```
+
+Use a literal without `LIKE`:
+
+```sql
+SHOW WAREHOUSES nightly_etl;
+```