mirror of
https://github.com/lancedb/lancedb.git
synced 2026-11-13 14:16:54 +00:00
docs: adopt Embedded/Distributed terminology across docs and SDKs (#4713)
## Summary Adopts the product terminology guide across the docs site pages, SDK docstrings and error messages. "LanceDB OSS" and local mode become **LanceDB Embedded**. "Remote" as the execution model becomes **LanceDB Distributed**, which LanceDB Enterprise provides. Where free vs paid is the point, pages contrast "LanceDB Embedded (open source)" with "LanceDB Enterprise". This is a first trial of the Embedded name, so reviewers can judge it in context. - **Embedded vs Distributed** for where execution runs (`optimize()`, consistency, branching, maintenance). Main pages define it once: "LanceDB Enterprise runs LanceDB Distributed: …" - **LanceDB Cloud** is kept only for legacy-Cloud specifics (`db://` region, the brute-force KNN limit) and marked legacy. "Cloud and Enterprise" becomes Enterprise or Distributed. - **Plan executor** becomes "executor" or the fleet name. - **Error messages** change, e.g. `optimize is not supported for remote tables.` → `... in LanceDB Distributed.` Tests that match on them are updated. - **Vale rules** (`EmbeddedName`, `OSSProduct`, `RemoteExecution`, `DistributedEnterprise`, `LegacyCloud`, `InternalNames`) enforce the terms in prose. Unchanged: identifiers (`availability.oss`, the `remote` module and feature, `RemoteTable`, `db://`), heading anchors, internal code comments, and Geneva. ## Evidence - Rust lib tests for the changed messages and the Python tests in `test_remote_db.py`, `test_materialized_views.py` and `test_table.py` pass locally. - Not run locally: - The Node tests: `remote.test.ts` and `table.test.ts` have updated assertions. - Vale. - The `experimental_functions`-marked materialized-view tests. - `docs/src` API reference was hand-edited to match the docstrings rather than regenerated. ## Merge Risk **Door:** two-way; prose and message text only. **Blast Radius:** `docs`, `error-messages`: callers matching on old error strings would break. Companion PRs: lancedb/docs (assembler labels, STYLE.md) and sophon (Enterprise pages). 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
co-authored by
Claude Opus 5.5
parent
b4cbaf2f67
commit
4d7a64712f
+17
-17
@@ -27,8 +27,8 @@ connect, per-table storage and write options on create, and `index_cache_size`,
|
||||
Omit these options to use server-managed storage and caching. Connection-level
|
||||
`storage_options` supported by an Enterprise deployment remain available.
|
||||
|
||||
The synchronous remote `create_table` uses the same positional order as the
|
||||
local API: `name, data, schema, mode, exist_ok, on_bad_vectors, fill_value,
|
||||
The synchronous LanceDB Distributed `create_table` uses the same positional order as the
|
||||
LanceDB Embedded API: `name, data, schema, mode, exist_ok, on_bad_vectors, fill_value,
|
||||
embedding_functions`. Prefer keyword arguments for optional parameters.
|
||||
|
||||
## Connections (Synchronous)
|
||||
@@ -227,14 +227,14 @@ async for entry in catalog.authz.list_acls(subject=Subject.role("reader")):
|
||||
|
||||
## Remote SQL
|
||||
|
||||
Submit SQL against a remote LanceDB database through the connection.
|
||||
Submit SQL against a LanceDB Distributed database through the connection.
|
||||
The connected database and `default_namespace_path=["public"]` are used for
|
||||
unqualified tables. Fully qualified references can still query other databases
|
||||
and namespaces available to the same deployment. `execute_query` returns a
|
||||
reader as soon as its initial result stream is available. `execute_query_async`
|
||||
returns a query handle once submission is accepted; use it to inspect progress, open a reader,
|
||||
or cancel the query. The SQL client is initialized by the first query and
|
||||
retained for the lifetime of the remote connection. Query ids are random,
|
||||
retained for the lifetime of the connection. Query ids are random,
|
||||
connection-scoped references rather than encoded SQL or durable resume tokens.
|
||||
|
||||
Both APIs start with one Flight call. The server can stream results on that
|
||||
@@ -308,24 +308,24 @@ listing a storage directory.
|
||||
|
||||
## Tables (Synchronous)
|
||||
|
||||
Local and remote tables use the same arguments for index creation, deletion,
|
||||
LanceDB Embedded and LanceDB Distributed tables use the same arguments for index creation, deletion,
|
||||
index statistics, and search. For example, `table.delete(where="id = 1")`,
|
||||
`table.create_index("cosine", 2)` (the deprecated vector API), and
|
||||
`table.search([1.0, 1.0], fast_search=True)` work with either backend.
|
||||
`fast_search=True` excludes rows that have not been indexed.
|
||||
|
||||
`create_scalar_index` defaults to `replace=True` on both backends. Both scalar
|
||||
and full-text index creation accept `wait_timeout`. Remote maintenance methods
|
||||
accept the local options: cleanup and compaction warn that they are no-ops,
|
||||
and full-text index creation accept `wait_timeout`. LanceDB Distributed maintenance methods
|
||||
accept the LanceDB Embedded options: cleanup and compaction warn that they are no-ops,
|
||||
while `optimize` reports an unsupported operation. Removed Tantivy options
|
||||
produce the same explanatory errors on both backends.
|
||||
|
||||
The old remote keyword names `predicate` for `delete`, `index_name` for
|
||||
The old LanceDB Distributed keyword names `predicate` for `delete`, `index_name` for
|
||||
`drop_index`, `index_uuid` for `index_stats`, and `column` for `create_fts_index`
|
||||
remain available with deprecation warnings. Use `where`, `name`, `index_name`,
|
||||
and `field_names`, respectively. For positional calls, use the argument order
|
||||
documented by `Table` below; specify index options by keyword when migrating
|
||||
code that used the former remote-only argument order.
|
||||
code that used the former LanceDB Distributed-only argument order.
|
||||
|
||||
::: lancedb.table.Table
|
||||
|
||||
@@ -429,14 +429,14 @@ scoped to each invocation and support `read`, `readinto`, `seek`, `tell`,
|
||||
|
||||
## Materialized Views (Synchronous)
|
||||
|
||||
In the 0.41 SDK release, local materialized-view creation and refresh require a
|
||||
In the 0.41 SDK release, LanceDB Embedded materialized-view creation and refresh require a
|
||||
source build with the `experimental-functions` Cargo feature. Published Python
|
||||
packages leave it disabled. Opening, reading, listing and dropping existing views
|
||||
remain available, as do remote Cloud and Enterprise operations. The same feature
|
||||
requirement applies to local SQL computed-column declaration and refresh; ordinary
|
||||
remain available, as do LanceDB Distributed operations. The same feature
|
||||
requirement applies to LanceDB Embedded SQL computed-column declaration and refresh; ordinary
|
||||
eager `add_columns` transforms remain available.
|
||||
|
||||
On Cloud and Enterprise, creation accepts `auto_refresh_enabled` and
|
||||
In LanceDB Distributed, creation accepts `auto_refresh_enabled` and
|
||||
`auto_refresh_interval_seconds`:
|
||||
|
||||
```python
|
||||
@@ -581,13 +581,13 @@ pylance, LanceDB uses a matching `lance.blob.v2` extension type so blob columns
|
||||
still work. Native table queries return descriptors. Call
|
||||
[`fetch_blob_files`][lancedb.table.Table.fetch_blob_files] for lazy reads or
|
||||
[`fetch_blobs`][lancedb.table.Table.fetch_blobs] for eager bytes.
|
||||
Local tables support these fetch APIs for both legacy blob v1 columns
|
||||
LanceDB Embedded supports these fetch APIs for both legacy blob v1 columns
|
||||
(`lance-encoding:blob`) and blob v2 columns. For legacy columns, obtain row IDs
|
||||
with `search().with_row_id(True).to_arrow()` and pass the result to the fetch API.
|
||||
One missing or deleted row ID rejects the entire blob-read batch; the APIs do
|
||||
not return partial results.
|
||||
|
||||
Remote SQL returns blob bytes by default. Select `blob_descriptor(video)` to
|
||||
LanceDB Distributed SQL returns blob bytes by default. Select `blob_descriptor(video)` to
|
||||
return an openable reference instead, then use
|
||||
[`open_blob_file`][lancedb.table.Table.open_blob_file] or the lazy iterable
|
||||
[`open_blob_files`][lancedb.table.Table.open_blob_files]:
|
||||
@@ -604,7 +604,7 @@ for row in rows.to_pylist():
|
||||
frame = extract_frame(video, row["timestamp"])
|
||||
```
|
||||
|
||||
This example uses a remote SQL connection that produces source-bearing
|
||||
This example uses a LanceDB Distributed SQL connection that produces source-bearing
|
||||
descriptors. The descriptor contains `kind`, `position`, `size`, `blob_id`,
|
||||
`blob_uri`, and a `source` struct with `uri`, `version`, `committed_at_micros`,
|
||||
`branch`, `column`, `row_reference`, and `row_is_address`. The opener verifies
|
||||
@@ -636,7 +636,7 @@ async for video in async_videos.open_blob_files(rows["video"]):
|
||||
```
|
||||
|
||||
Payload bytes load on reads. Opening an external blob with unspecified size
|
||||
can issue a metadata-only HEAD request. Remote reads use authenticated range
|
||||
can issue a metadata-only HEAD request. LanceDB Distributed reads use authenticated range
|
||||
requests that validate the captured URI and commit timestamp.
|
||||
|
||||
Blobs inside lists can be written and queried as descriptors. They are omitted
|
||||
|
||||
Reference in New Issue
Block a user