From caa6a991bb24a65536db8c4369c4546802dfafcc Mon Sep 17 00:00:00 2001
From: Manfred Moser <manfred@simpligility.ca>
Date: Wed, 5 Feb 2025 16:23:16 -0800
Subject: [PATCH] Add docs for WITH SESSION

---
 docs/src/main/sphinx/release/release-470.md |  4 ++--
 docs/src/main/sphinx/sql/select.md          | 25 +++++++++++++++++++++
 2 files changed, 27 insertions(+), 2 deletions(-)

diff --git a/docs/src/main/sphinx/release/release-470.md b/docs/src/main/sphinx/release/release-470.md
index 475da2571c79..a30e8833724e 100644
--- a/docs/src/main/sphinx/release/release-470.md
+++ b/docs/src/main/sphinx/release/release-470.md
@@ -4,8 +4,8 @@
 
 * Add [](/connector/duckdb). ({issue}`18031`)
 * Add [](/connector/loki). ({issue}`23053`)
-* Add support for `WITH SESSION` to set per-query session properties with
-  `SELECT` queries. ({issue}`24889`)
+* Add support for the [](select-with-session) to set per-query session
+  properties with `SELECT` queries. ({issue}`24889`)
 * Improve compatibility of fault-tolerant exchange storage with S3-compliant
   object stores. ({issue}`24822`)
 * Allow skipping directory schema validation to improve compatibility of
diff --git a/docs/src/main/sphinx/sql/select.md b/docs/src/main/sphinx/sql/select.md
index 756048fca74a..54dc3c1fb767 100644
--- a/docs/src/main/sphinx/sql/select.md
+++ b/docs/src/main/sphinx/sql/select.md
@@ -69,6 +69,31 @@ ROLLUP ( column [, ...] )
 
 Retrieve rows from zero or more tables.
 
+(select-with-session)=
+## WITH SESSION clause
+
+The `WITH SESSION` clause allows you to [set session and catalog session
+property values](/sql/set-session) applicable for the processing of the current
+SELECT statement only. The defined values override any other configuration and
+session property settings. Multiple properties are separated by commas.
+
+The following example overrides the global configuration property
+`query.max-execution-time` with the session property `query_max_execution_time`
+to reduce the time to `2h`. It also overrides the catalog property
+`iceberg.query-partition-filter-required` from the `example` catalog using
+[](/connector/iceberg) setting the catalog session property
+`query_partition_filter_required` to `true`:
+
+```sql
+WITH 
+  SESSION
+    query_max_execution_time='2h',
+    example.query_partition_filter_required=true
+SELECT * 
+FROM example.default.thetable
+LIMIT 100;
+```
+
 ## WITH FUNCTION clause
 
 The `WITH FUNCTION` clause allows you to define a list of [](udf-inline) that