You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/api-reference/index.mdx
+27-12Lines changed: 27 additions & 12 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,7 +1,7 @@
1
1
---
2
-
title: Client SDKs
2
+
title: SDKs and REST API Reference
3
3
sidebarTitle: "SDKs"
4
-
description: "SDK & REST API reference for LanceDB"
4
+
description: "SDK and REST API reference for LanceDB Enterprise and OSS."
5
5
6
6
---
7
7
@@ -15,20 +15,35 @@ If you're looking for conceptual and practical namespace guidance before diving
15
15
16
16
## Supported SDKs
17
17
18
-
Python, Typescript and Rust SDKs are officially supported by LanceDB.
18
+
Python, Typescript and Rust SDKs are officially supported by LanceDB. You can use these SDKs to interact with both LanceDB OSS and Enterprise deployments.
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).
27
+
If you want to go deeper, see the Lance format [namespace documentation](https://lance.org/format/namespace/).
28
+
29
+
## Directory namespaces
27
30
28
31
The simplest namespace model in LanceDB is a single root namespace, often represented by one
29
32
directory:
30
33
31
34
```bash
32
-
/data/ # root namespace
33
-
├─ users.lance # table ["users"] in root
34
-
└─ orders.lance # table ["orders"] in root
35
+
./local_lancedb (root)
36
+
└── prod
37
+
└── search
38
+
└── user (table)
39
+
└── data (table)
35
40
```
36
41
37
-
As a user of LanceDB, you might never notice namespaces at first, because LanceDB exposes the single-level
38
-
hierarchy shown above, with the data stored in the `data/` directory, where the root namespace
39
-
is implicit. In alternative setups, you could have multiple namespaces that we won't cover here,
40
-
but you can learn more about them in the [namespace documentation](https://lance.org/format/namespace/) for the Lance format.
42
+
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:
41
43
42
-
## Best-practice guidance
44
+
```python Python icon="python"
45
+
import lancedb
43
46
44
-
- Use the default, single-level root namespace in LanceDB for locally stored, single-application, or early-stage projects.
45
-
- For remote storage locations, introduce explicit namespaces when multiple teams, environments, or domains share the same catalog.
46
-
- Treat namespace paths as stable identifiers (for example `"prod/search"`, `"staging/recs"`).
- For simple use cases in LanceDB OSS, you don't need to go too deep into namespaces.
72
+
- To integrate LanceDB with external catalogs and to use it as a true **multimodal lakehouse**, it's useful to understant the different namespace implementations and how to use them in your organization's setup.
73
+
</Info>
74
+
75
+
## Remote or external catalog namespaces
76
+
77
+
The example above showed local directory-baed namespaces. LanceDB also supports namespaces backed by remote object stores and external catalogs, via the REST namespace implementation.
78
+
79
+
For remote object stores with central metadata/catalog services (either commercial or open source), use the REST namespace implementation,
80
+
This is backed by REST routes
81
+
(for example `POST /v1/namespace/{id}/create` and `GET /v1/namespace/{id}/list`) and server-provided table locations.
82
+
83
+
For authentication, any property prefixed with `headers` is forwarded as an HTTP header
84
+
(for example `headers.Authorization` becomes `Authorization`, and `headers.X-API-Key` becomes `X-API-Key`).
[LanceDB Enterprise](/enterprise) operates a REST namespace server on top of the Lance format, so any REST client that can speak the REST namespace API
103
+
contract can be used to interact with it. For authentication examples in LanceDB Enterprise, visit
104
+
the [Namespaces in SDKs](/tables/namespaces#namespaces-in-lancedb-enterprise) page.
79
105
80
-
## SDK usage
106
+
## Best practices
81
107
82
-
1. For language-specific examples of `namespace` usage across Python, TypeScript, and Rust, see "[Using namespaces in SDKs](/tables/namespaces)".
83
-
2. For REST-level operations, see the [REST API Reference](/api-reference/rest).
108
+
Below, we list some best practices for working with namespaces:
109
+
- For simple use cases and single, stand-alone applications, the directory-based root namespace is sufficient and requires no special configuration.
110
+
- For remote storage locations, introduce explicit namespaces when multiple teams, environments, or domains share the same catalog.
111
+
- Treat namespace paths as stable identifiers (for example `"prod/search"`, `"staging/recs"`).
112
+
- For maintainability reasons, avoid hard-coding object-store table paths in application code -- instead, prefer catalog identifiers + namespaces.
exportconst 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";
exportconst PyNamespaceAdminOps ="import lancedb\n\ndb = lancedb.connect_namespace(\"dir\", {\"root\": \"./local_lancedb\"})\nnamespace = [\"prod\", \"search\"]\n\ndb.create_namespace([\"prod\"])\ndb.create_namespace([\"prod\", \"search\"])\n\nchild_namespaces = db.list_namespaces(namespace=[\"prod\"]).namespaces\nprint(f\"Child namespaces under {namespace}: {child_namespaces}\")\n# Child namespaces under ['prod', 'search']: ['search']\n\nmetadata = db.describe_namespace([\"prod\", \"search\"])\nprint(f\"Metadata for namespace {namespace}: {metadata}\")\n# Metadata for namespace ['prod', 'search']: properties=None\n\ndb.drop_namespace([\"prod\", \"search\"], mode=\"skip\")\ndb.drop_namespace([\"prod\"], mode=\"skip\")\n";
16
16
17
-
exportconst 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";
17
+
export const PyNamespaceTableOps = "import lancedb\n\ndb = lancedb.connect_namespace(\"dir\", {\"root\": \"./local_lancedb\"})\n\n# Create namespace tree: prod/search\ndb.create_namespace([\"prod\"], mode=\"exist_ok\")\ndb.create_namespace([\"prod\", \"search\"], mode=\"exist_ok\")\ndb.create_namespace([\"prod\", \"recommendations\"], mode=\"exist_ok\")\n\ndb.create_table(\n \"user\",\n data=[{\"id\": 1, \"vector\": [0.1, 0.2], \"name\": \"alice\"}],\n namespace=[\"prod\", \"search\"],\n mode=\"create\", # use \"overwrite\" only if you want to replace existing table\n)\n\ndb.create_table(\n \"user\",\n data=[{\"id\": 2, \"vector\": [0.3, 0.4], \"name\": \"bob\"}],\n namespace=[\"prod\", \"recommendations\"],\n mode=\"create\", # use \"overwrite\" only if you want to replace existing table\n)\n\n# Verify\nprint(db.list_namespaces()) # ['prod']\nprint(db.list_namespaces(namespace=[\"prod\"])) # ['recommendations', 'search']\nprint(db.list_tables(namespace=[\"prod\", \"search\"])) # ['user']\nprint(db.list_tables(namespace=[\"prod\", \"recommendations\"])) # ['user']\n";
18
18
19
19
exportconst 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";
20
20
21
21
exportconst TsConnectCloud ="const uri = \"db://your-database-uri\";\nconst apiKey = \"your-api-key\";\nconst region = \"us-east-1\";\n";
22
22
23
23
exportconst TsConnectObjectStorage ="async function connectObjectStorageExample() {\n const uri = \"s3://your-bucket/path\";\n // You can also use \"gs://your-bucket/path\" or \"az://your-container/path\".\n const db = await lancedb.connect(uri);\n return db;\n}\n";
exportconst RsConnect ="async fn connect_example(uri: &str) {\n let db = connect(uri).execute().await.unwrap();\n let _ = db;\n}\n";
28
26
29
27
exportconst RsConnectCloud ="let uri = \"db://your-database-uri\";\nlet api_key = \"your-api-key\";\nlet region = \"us-east-1\";\n";
30
28
31
29
exportconst RsConnectObjectStorage ="let uri = \"s3://your-bucket/path\";\n// You can also use \"gs://your-bucket/path\" or \"az://your-container/path\".\n";
0 commit comments