diff --git a/docs/namespaces.mdx b/docs/namespaces.mdx
index 21abf26..570c45b 100644
--- a/docs/namespaces.mdx
+++ b/docs/namespaces.mdx
@@ -51,15 +51,24 @@ See the Python example below for how to use namespaces in practice.
 ```python Python icon="python"
 import lancedb
 
-# App config: only the catalog endpoint/root is configured once.
-db = lancedb.connect("s3://my-lakehouse/catalog")
+# Local namespace-backed catalog root (DirectoryNamespace)
+db = lancedb.connect_namespace("dir", {"root": "./namespace_test"})
 
 # Business identifier + namespace path (stable app-level IDs)
 namespace = ["prod", "recommendations"]
 table_name = "user_profiles"
 
+# Create namespace hierarchy sequentially
+for i in range(1, len(namespace) + 1):
+    db.create_namespace(namespace[:i], mode="exist_ok")
+
 # Good: resolve table through catalog + namespace
-table = db.open_table(table_name, namespace=namespace)
+table = db.create_table(
+    table_name,
+    data=[{"id": 1, "vector": [0.1, 0.2], "name": "alice"}],
+    namespace=namespace,
+    mode="overwrite",
+)
 
 # Bad: Avoid hard-coded physical object-store table paths
 # (it's bad for maintainability reasons)
diff --git a/docs/snippets/connection.mdx b/docs/snippets/connection.mdx
index 0159183..a9f69d7 100644
--- a/docs/snippets/connection.mdx
+++ b/docs/snippets/connection.mdx
@@ -12,9 +12,9 @@ export const PyConnectObjectStorage = "import lancedb\n\nuri = \"s3://your-bucke
 
 export const PyConnectObjectStorageAsync = "import lancedb\n\nuri = \"s3://your-bucket/path\"\n# You can also use \"gs://your-bucket/path\" or \"az://your-container/path\".\nasync_db = await lancedb.connect_async(uri)\n";
 
-export const PyNamespaceAdminOps = "import lancedb\n\ndb = lancedb.connect(\"./data/sample-lancedb\")\ndb.create_namespace([\"prod\"])\ndb.create_namespace([\"prod\", \"search\"])\n\nchild_namespaces = db.list_namespaces(namespace=[\"prod\"]).namespaces\nmetadata = db.describe_namespace([\"prod\", \"search\"])\n\ndb.drop_namespace([\"prod\", \"search\"], mode=\"skip\")\ndb.drop_namespace([\"prod\"], mode=\"skip\")\n";
+export const PyNamespaceAdminOps = "import lancedb\n\ndb = lancedb.connect_namespace(\"dir\", {\"root\": \"./data/sample-lancedb\"})\nnamespace = [\"prod\", \"search\"]\n\nfor i in range(1, len(namespace) + 1):\n    db.create_namespace(namespace[:i], mode=\"exist_ok\")\n\nchild_namespaces = db.list_namespaces(namespace=[\"prod\"]).namespaces\nmetadata = db.describe_namespace([\"prod\", \"search\"])\n\ndb.drop_namespace([\"prod\", \"search\"], mode=\"skip\")\ndb.drop_namespace([\"prod\"], mode=\"skip\")\n";
 
-export const PyNamespaceTableOps = "import lancedb\n\ndb = lancedb.connect(\"./data/sample-lancedb\")\nnamespace = [\"prod\", \"search\"]\n\ndb.create_table(\n    \"users\",\n    data=[{\"id\": 1, \"name\": \"alice\"}],\n    mode=\"overwrite\",\n    namespace=namespace,\n)\n\ntable = db.open_table(\"users\", namespace=namespace)\ntables = db.list_tables(namespace=namespace).tables\n\ndb.drop_table(\"users\", namespace=namespace)\n# drop_all_tables is namespace-aware as well:\n# db.drop_all_tables(namespace=namespace)\n";
+export const PyNamespaceTableOps = "import lancedb\n\ndb = lancedb.connect_namespace(\"dir\", {\"root\": \"./data/sample-lancedb\"})\nnamespace = [\"prod\", \"search\"]\n\nfor i in range(1, len(namespace) + 1):\n    db.create_namespace(namespace[:i], mode=\"exist_ok\")\n\ndb.create_table(\n    \"users\",\n    data=[{\"id\": 1, \"vector\": [0.1, 0.2], \"name\": \"alice\"}],\n    mode=\"overwrite\",\n    namespace=namespace,\n)\n\ntable = db.open_table(\"users\", namespace=namespace)\ntables = db.list_tables(namespace=namespace).tables\n\ndb.drop_table(\"users\", namespace=namespace)\n# drop_all_tables is namespace-aware as well:\n# db.drop_all_tables(namespace=namespace)\n";
 
 export const TsConnect = "import * as lancedb from \"@lancedb/lancedb\";\n\nasync function connectExample(uri: string) {\n  const db = await lancedb.connect(uri);\n  return db;\n}\n";
 
diff --git a/docs/tables/namespaces.mdx b/docs/tables/namespaces.mdx
index 94abc34..e2b96e4 100644
--- a/docs/tables/namespaces.mdx
+++ b/docs/tables/namespaces.mdx
@@ -55,6 +55,8 @@ the `data/` directory.
 
 You can open/create/drop tables inside a namespace path (like `["prod", "search"]`).
 The Python and Rust SDKs expose namespace lifecycle operations directly.
+In Python, use `lancedb.connect_namespace(...)` when calling namespace lifecycle methods such as
+`create_namespace`, `list_namespaces`, `describe_namespace`, and `drop_namespace`.
 
 <CodeGroup>
     <CodeBlock filename="Python" language="Python" icon="python">
diff --git a/tests/py/test_connection.py b/tests/py/test_connection.py
index 7886afa..4d7c1fe 100644
--- a/tests/py/test_connection.py
+++ b/tests/py/test_connection.py
@@ -58,12 +58,15 @@ def namespace_table_ops_example():
     # --8<-- [start:namespace_table_ops]
     import lancedb
 
-    db = lancedb.connect("./data/sample-lancedb")
+    db = lancedb.connect_namespace("dir", {"root": "./data/sample-lancedb"})
     namespace = ["prod", "search"]
 
+    for i in range(1, len(namespace) + 1):
+        db.create_namespace(namespace[:i], mode="exist_ok")
+
     db.create_table(
         "users",
-        data=[{"id": 1, "name": "alice"}],
+        data=[{"id": 1, "vector": [0.1, 0.2], "name": "alice"}],
         mode="overwrite",
         namespace=namespace,
     )
@@ -82,9 +85,11 @@ def namespace_admin_ops_example():
     # --8<-- [start:namespace_admin_ops]
     import lancedb
 
-    db = lancedb.connect("./data/sample-lancedb")
-    db.create_namespace(["prod"])
-    db.create_namespace(["prod", "search"])
+    db = lancedb.connect_namespace("dir", {"root": "./data/sample-lancedb"})
+    namespace = ["prod", "search"]
+
+    for i in range(1, len(namespace) + 1):
+        db.create_namespace(namespace[:i], mode="exist_ok")
 
     child_namespaces = db.list_namespaces(namespace=["prod"]).namespaces
     metadata = db.describe_namespace(["prod", "search"])