Skip to content

Commit 1b08172

Browse files
docs: document namespace_exists and table_exists existence checks
1 parent a36d7e1 commit 1b08172

1 file changed

Lines changed: 39 additions & 0 deletions

File tree

docs/namespaces/usage.mdx

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -102,6 +102,45 @@ Listing APIs return the immediate children of the requested namespace path. Use
102102
returned `page_token` to page through large catalogs; pass an empty namespace path (`[]`) when you
103103
want to list from the root namespace.
104104

105+
## Check whether a namespace or table exists
106+
107+
When you write branching logic like "create the namespace only if it isn't there yet" or "open the
108+
table only if it already exists", use the existence-check APIs instead of catching a
109+
`NamespaceNotFoundError` or `TableNotFoundError` from `describe_namespace` or `open_table`.
110+
111+
In Python, a namespace-connected database exposes two methods that return a boolean:
112+
113+
- `namespace_exists(namespace_id=[...])` returns `True` when the given namespace path resolves to
114+
an existing namespace, and `False` otherwise.
115+
- `table_exists(table_id=[...])` returns `True` when the given fully qualified table identifier
116+
(namespace segments followed by the table name) resolves to an existing table, and `False`
117+
otherwise.
118+
119+
Both methods take a list of path components, matching the same identifier shape used by
120+
`create_namespace`, `describe_namespace`, `create_table`, and `open_table`.
121+
122+
```python Python icon="python"
123+
import lancedb
124+
125+
db = lancedb.connect_namespace("dir", {"root": "./local_lancedb"})
126+
127+
# Check whether a namespace exists before creating it.
128+
if not db.namespace_exists(namespace_id=["prod", "search"]):
129+
db.create_namespace(["prod"], mode="exist_ok")
130+
db.create_namespace(["prod", "search"])
131+
132+
# Check whether a table exists before opening it. The table identifier is the
133+
# full path: namespace segments followed by the table name.
134+
if db.table_exists(table_id=["prod", "search", "user"]):
135+
table = db.open_table("user", namespace_path=["prod", "search"])
136+
```
137+
138+
<Note>
139+
These existence checks are available on connections created with `lancedb.connect_namespace(...)`.
140+
Calling them on a plain `lancedb.connect(...)` connection raises `NotImplementedError`, since that
141+
connection type doesn't expose namespace lifecycle operations.
142+
</Note>
143+
105144
## Namespaces in LanceDB Enterprise
106145

107146
In LanceDB Enterprise deployments, configure namespace-backed federated databases in a TOML file under your deployment's `config` directory.

0 commit comments

Comments
 (0)