Skip to main content
Despite its name, LanceDB is not a “database” in the traditional sense — it is a Multimodal Lakehouse that builds on the table abstraction, similar to many other lakehouse projects. LanceDB exposes a catalog-level abstraction over the Lance table format, via a namespace spec. Lance provides the file and table formats to store and manage your data and indexes. LanceDB operates at the catalog layer (used to organize, discover, and operate on many Lance tables) and provides a compute engine on top of the Lance format. This is why many SDK methods in LanceDB, like create_table, open_table, drop_table, and rename_table, accept a namespace parameter as input.

​
Namespace hierarchy

Namespaces are generalizations of catalog specs that give platform developers a clean way to present Lance tables in the structures users expect. The diagram below shows how the hierarchy can go beyond a single level. A namespace can contain a collection of tables, and it can also contain namespaces recursively. Before diving into examples, it helps to keep two terms in mind: the namespace client is the abstraction that presents a consistent namespace API, while the namespace implementation is the concrete backend that resolves namespaces and table locations (for example, a local directory or an external catalog). If you want to go deeper, see the Lance format namespace documentation.

​
Directory namespaces

The simplest namespace model in LanceDB is a single root namespace, often represented by one directory: 
./local_lancedb/      # catalog root ({"root": "./local_lancedb"})
└─ data/              # root namespace
   ├─ users.lance     # table ["users"] in root
   └─ orders.lance    # table ["orders"] in root
As a user of LanceDB OSS, you might never notice namespaces at first, because LanceDB exposes the single-level hierarchy shown above, with the data stored in the data/ directory, where the root namespace is implicit. Connecting to this namespace is as simple as connecting to the catalog root:
Python
import lancedb

# Connect to the directory namespace root
db = lancedb.connect("./local_lancedb")
You can also explicitly connect to this namespace in Python using lancedb.connect_namespace(...) with the directory namespace implementation:
Python
import lancedb

# Local namespace-backed catalog root (DirectoryNamespace)
# See https://lance.org/format/namespace/dir/catalog-spec/
db = lancedb.connect_namespace(
    "dir",
    {
        "root": "./local_lancedb"
    },
)
For simple search use cases in LanceDB OSS, you don’t need to go too deep into namespaces. However, to integrate LanceDB with external catalogs and to use it as a true multimodal lakehouse, understanding the different namespace implementations and how to use them in your organization’s setup is beneficial.

​
Remote or external catalog namespaces

For remote object stores with central metadata/catalog services (either commercial or open source), use the REST namespace implementation. In LanceDB, this is the same namespace API surface as local directory namespaces, but backed by REST routes (for example POST /v1/namespace/{id}/create and GET /v1/namespace/{id}/list) and server-provided table locations. For authentication, any property prefixed with headers is forwarded as an HTTP header (for example headers.Authorization becomes Authorization, and headers.X-API-Key becomes X-API-Key).
Python
import os
import lancedb

# Remote namespace-backed catalog root (RestNamespace)
# See https://lance.org/format/namespace/rest/catalog-spec/
db = lancedb.connect_namespace(
    "rest",
    {
        "uri": "https://<your_catalog>.internal.<your_org>.com",
        "headers.x-api-key": os.environ["API_KEY"],
        # or:
        # "headers.Authorization": f"Bearer {os.environ['REST_AUTH_TOKEN']}",
    },
)
LanceDB Enterprise operates a REST namespace server on top of the Lance format, so any REST client that can speak the REST namespace API contract can be used to interact with it. For authentication examples in LanceDB Enterprise, visit the Namespaces in SDKs page.

​
Best practices

Below, we list some best practices for working with namespaces:
  • For simple use cases and single, stand-alone applications, the directory-based root namespace is sufficient and requires no special configuration.
  • For remote storage locations, introduce explicit namespaces when multiple teams, environments, or domains share the same catalog.
  • Treat namespace paths as stable identifiers (for example "prod/search", "staging/recs").
  • For maintainability reasons, avoid hard-coding object-store table paths in application code — instead, prefer catalog identifiers + namespaces.