docs: add PARTITION BY for COPY INTO <location> (#3077)

* docs: add PARTITION BY support for COPY INTO <location> (databend#19390)

* docs: fix PARTITION BY example to correctly demonstrate _NULL_ folder

Author: sundy-li

docs/en/sql-reference/10-sql-commands/10-dml/dml-copy-into-location.md

@@ -5,7 +5,7 @@ sidebar_label: "COPY INTO <location>"
 
 import FunctionDescription from '@site/src/components/FunctionDescription';
 
-<FunctionDescription description="Introduced or updated: v1.2.647"/>
+<FunctionDescription description="Introduced or updated: v1.2.881"/>
 
 COPY INTO allows you to unload data from a table or query into one or more files in one of the following locations:
 
@@ -19,6 +19,7 @@ See also: [`COPY INTO <table>`](dml-copy-into-table.md)
 ```sql
 COPY INTO { internalStage | externalStage | externalLocation }
 FROM { [<database_name>.]<table_name> | ( <query> ) }
+[ PARTITION BY ( <expr> ) ]
 [ FILE_FORMAT = (
          FORMAT_NAME = '<your-custom-format>'
          | TYPE = { CSV | TSV | NDJSON | PARQUET } [ formatTypeOptions ]
@@ -118,6 +119,22 @@ For the connection parameters available for accessing Tencent Cloud Object Stora
 
 See [Input & Output File Formats](../../00-sql-reference/50-file-format-options.md) for details.
 
+### PARTITION BY
+
+Specifies an expression used to partition the unloaded data into separate folders. The expression must evaluate to a `STRING` type. Each distinct value produced by the expression creates a subfolder in the destination path, and the corresponding rows are written into files under that subfolder.
+
+- If the expression evaluates to `NULL`, the rows are placed in a special `_NULL_` folder.
+- The expression can reference any columns from the source table or query.
+- Path traversal (`..`) is not allowed in partition values.
+
+The following options are incompatible with `PARTITION BY` and will cause an error if set:
+
+| Option              | Restriction                                      |
+| ------------------- | ------------------------------------------------ |
+| SINGLE              | Cannot be `TRUE` when using `PARTITION BY`.      |
+| OVERWRITE           | Cannot be `TRUE` when using `PARTITION BY`.      |
+| INCLUDE_QUERY_ID    | Cannot be `FALSE` when using `PARTITION BY`.     |
+
 ### copyOptions
 
 ```sql
@@ -289,3 +306,46 @@ COPY INTO 's3://databend'
 ```
 
 ![Alt text](/img/sql/copy-into-bucket.png)
+
+### Example 4: Unloading with PARTITION BY
+
+This example unloads data into partitioned folders based on a derived expression:
+
+```sql
+-- Create a sample table
+CREATE TABLE sales_data (
+    sale_date DATE,
+    region VARCHAR,
+    amount INT
+);
+
+INSERT INTO sales_data VALUES
+    ('2025-01-15', 'east', 100),
+    ('2025-01-20', 'west', 200),
+    ('2025-02-10', 'east', 150),
+    (NULL, 'west', 50);
+
+-- Create an internal stage
+CREATE STAGE partitioned_stage;
+
+-- Unload data partitioned by year-month derived from sale_date
+-- When sale_date is NULL, to_varchar() returns NULL, so the entire
+-- concatenation evaluates to NULL and the row lands in the _NULL_ folder.
+COPY INTO @partitioned_stage
+    FROM sales_data
+    PARTITION BY ('month=' || to_varchar(sale_date, 'YYYY-MM'))
+    FILE_FORMAT = (TYPE = PARQUET);
+
+-- Verify the partitioned folder layout
+SELECT name FROM list_stage(location => '@partitioned_stage') ORDER BY name;
+
+┌──────────────────────────────────────────────────────────────────┐
+│                              name                                │
+├──────────────────────────────────────────────────────────────────┤
+│ _NULL_/data_<query_id>_0000_00000000.parquet                     │
+│ month=2025-01/data_<query_id>_0000_00000000.parquet              │
+│ month=2025-02/data_<query_id>_0000_00000000.parquet              │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+When the partition expression evaluates to `NULL`, the data is placed in a `_NULL_` folder. Each unique partition value creates its own subfolder containing the corresponding data files.