From bd5af775b07b1612d529b45572b450ade30b5dd5 Mon Sep 17 00:00:00 2001
From: Voyagerroc-Code <325343927+Voyagerroc-Code@users.noreply.github.com>
Date: Fri, 18 Sep 2026 08:43:59 +0300
Subject: [PATCH] Document Fabric catalog state

---
 docs/fabric-catalog-state.md | 11 +++++++++++
 1 file changed, 11 insertions(+)
 create mode 100644 docs/fabric-catalog-state.md

diff --git a/docs/fabric-catalog-state.md b/docs/fabric-catalog-state.md
new file mode 100644
index 0000000000..94cb537fbf
--- /dev/null
+++ b/docs/fabric-catalog-state.md
@@ -0,0 +1,11 @@
+# Fabric catalog state
+
+Fabric does not persist `USE` statements between independent sessions. The
+adapter therefore keeps the logical target catalog separate from the catalog
+used by the open connection. Restoring a scoped operation to the neutral state
+updates the logical target without unnecessarily closing a connection; an
+actual catalog switch closes the thread-local connection before it is reused.
+
+Tests for this behaviour are in `tests/core/engine_adapter/test_fabric.py`.
+When changing catalog creation or deletion, cover both the configured default
+catalog and a non-default warehouse.