mirror of
https://github.com/lancedb/lancedb.git
synced 2026-10-30 15:26:52 +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:
Will Jones
co-authored by
Claude Opus 5.5
Claude Opus 5.5
parent
b4cbaf2f67
commit
4d7a64712f
@@ -115,14 +115,14 @@ describe("remote connection", () => {
|
||||
...options,
|
||||
mode: "overwrite",
|
||||
}),
|
||||
).rejects.toThrow(/write_options.*remote/);
|
||||
).rejects.toThrow(/write_options.*LanceDB Distributed/);
|
||||
await expect(
|
||||
db.createEmptyTable(
|
||||
"test",
|
||||
new Schema([new Field("value", new Int64(), true)]),
|
||||
options,
|
||||
),
|
||||
).rejects.toThrow(/write_options.*remote/);
|
||||
).rejects.toThrow(/write_options.*LanceDB Distributed/);
|
||||
},
|
||||
);
|
||||
expect(requests).toEqual([]);
|
||||
@@ -140,7 +140,9 @@ describe("remote connection", () => {
|
||||
async (db) => {
|
||||
await expect(
|
||||
db.openTable("test", undefined, options),
|
||||
).rejects.toThrow(/not supported for remote/);
|
||||
).rejects.toThrow(
|
||||
/not supported for table access in LanceDB Distributed/,
|
||||
);
|
||||
},
|
||||
);
|
||||
expect(requests).toEqual([]);
|
||||
@@ -316,7 +318,7 @@ describe("remote connection", () => {
|
||||
],
|
||||
];
|
||||
for (const [run, operation] of cases) {
|
||||
let message = `LanceDBError: not supported: ${operation} is not supported for remote tables.`;
|
||||
let message = `LanceDBError: not supported: ${operation} is not supported in LanceDB Distributed.`;
|
||||
if (operation === "IVF_HNSW_PQ") {
|
||||
message += " Please use IVF_HNSW_SQ instead.";
|
||||
}
|
||||
@@ -463,7 +465,7 @@ describe("remote connection", () => {
|
||||
table.add([{ id: 1n }], {
|
||||
allowExternalBlobOutsideBases: true,
|
||||
}),
|
||||
).rejects.toThrow("only supported on local tables");
|
||||
).rejects.toThrow("only supported in LanceDB Embedded");
|
||||
expect(insertRequests).toBe(0);
|
||||
|
||||
await expect(table.add([{ id: 2n }])).resolves.toMatchObject({
|
||||
|
||||
@@ -4526,14 +4526,14 @@ describe.each(arrowVersions)(
|
||||
];
|
||||
const table = await db.createTable("prewarm_data_test", data);
|
||||
|
||||
// prewarmData is only supported on remote tables. We verify the call
|
||||
// prewarmData is only supported in LanceDB Distributed. We verify the call
|
||||
// is wired through napi and surfaces the expected error for both
|
||||
// arg shapes (undefined and string[]).
|
||||
await expect(table.prewarmData()).rejects.toThrow(
|
||||
"prewarm_data is currently only supported on remote tables",
|
||||
"prewarm_data is currently only supported in LanceDB Distributed",
|
||||
);
|
||||
await expect(table.prewarmData(["text"])).rejects.toThrow(
|
||||
"prewarm_data is currently only supported on remote tables",
|
||||
"prewarm_data is currently only supported in LanceDB Distributed",
|
||||
);
|
||||
});
|
||||
|
||||
@@ -5506,7 +5506,7 @@ describe("computed columns", () => {
|
||||
const db = await connect(tmpDir.name);
|
||||
const table = await db.createTable("errors_local", [{ x: 1 }]);
|
||||
await expect(table.functionErrors()).rejects.toThrow(
|
||||
"LanceDB Cloud and Enterprise",
|
||||
"recorded only in LanceDB Distributed",
|
||||
);
|
||||
});
|
||||
|
||||
|
||||
@@ -274,7 +274,7 @@ export class BlobFile {
|
||||
export type BlobReadOptions = {
|
||||
/**
|
||||
* Cancels the read. The call rejects with `signal.reason`, and the native
|
||||
* read stops, including in-flight requests to a remote table.
|
||||
* read stops, including in-flight requests to a LanceDB Distributed table.
|
||||
*/
|
||||
signal?: AbortSignal;
|
||||
};
|
||||
|
||||
@@ -270,9 +270,9 @@ export abstract class Connection {
|
||||
/**
|
||||
* Define a materialized view named `name` over the table `source`.
|
||||
*
|
||||
* Local creation and refresh require a source build with the
|
||||
* LanceDB Embedded creation and refresh require a source build with the
|
||||
* `experimental-functions` Cargo feature, disabled in published packages.
|
||||
* Remote Cloud/Enterprise operations do not require this feature.
|
||||
* LanceDB Distributed operations do not require this feature.
|
||||
*
|
||||
* The view is populated before creation returns. Set `withNoData` to create
|
||||
* only its definition and empty backing table. The view is a normal table:
|
||||
@@ -559,7 +559,7 @@ export abstract class Connection {
|
||||
/**
|
||||
* Rename a table.
|
||||
*
|
||||
* Currently only supported by LanceDB Cloud. Local OSS connections and
|
||||
* Currently only supported in LanceDB Distributed. LanceDB Embedded connections and
|
||||
* namespace-backed connections (via {@link connectNamespace}) reject with
|
||||
* a "not supported" error.
|
||||
*
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
// SPDX-FileCopyrightText: Copyright The LanceDB Authors
|
||||
|
||||
/**
|
||||
* Header providers for LanceDB remote connections.
|
||||
* Header providers for LanceDB Enterprise connections.
|
||||
*
|
||||
* This module provides a flexible header management framework for LanceDB remote
|
||||
* connections, allowing users to implement custom header strategies for
|
||||
|
||||
@@ -288,11 +288,11 @@ export async function tokenize(
|
||||
*
|
||||
* Accepted formats:
|
||||
*
|
||||
* - `/path/to/database` - local database
|
||||
* - `/path/to/database` - database on the local file system
|
||||
* - `s3://bucket/path/to/database` or `gs://bucket/path/to/database` - database on cloud storage
|
||||
* - `db://host:port` - remote database (LanceDB cloud)
|
||||
* - `db://host:port` - LanceDB Enterprise or LanceDB Cloud (legacy) database
|
||||
* @param {string} uri - The uri of the database. If the database uri starts
|
||||
* with `db://` then it connects to a remote database.
|
||||
* with `db://` then it connects to LanceDB Enterprise or LanceDB Cloud (legacy).
|
||||
* @see {@link ConnectionOptions} for more details on the URI format.
|
||||
* @param options - The options to use when connecting to the database
|
||||
* @example
|
||||
@@ -333,9 +333,9 @@ export async function connect(
|
||||
*
|
||||
* Accepted formats:
|
||||
*
|
||||
* - `/path/to/database` - local database
|
||||
* - `/path/to/database` - database on the local file system
|
||||
* - `s3://bucket/path/to/database` or `gs://bucket/path/to/database` - database on cloud storage
|
||||
* - `db://host:port` - remote database (LanceDB cloud)
|
||||
* - `db://host:port` - LanceDB Enterprise or LanceDB Cloud (legacy) database
|
||||
* @param options - The options to use when connecting to the database
|
||||
* @see {@link ConnectionOptions} for more details on the URI format.
|
||||
* @example
|
||||
@@ -533,7 +533,7 @@ function restConfigToProperties(
|
||||
* Connect to a LanceDB database through a namespace.
|
||||
*
|
||||
* Unlike {@link connect}, which routes by URI scheme (local path vs.
|
||||
* `db://` cloud), `connectNamespace` always returns a namespace-backed
|
||||
* `db://`), `connectNamespace` always returns a namespace-backed
|
||||
* connection. The `implName` selects the namespace implementation:
|
||||
*
|
||||
* - `"dir"` — directory namespace, configured with {@link DirNamespaceConfig}.
|
||||
|
||||
+16
-15
@@ -128,8 +128,8 @@ export interface AddDataOptions {
|
||||
/**
|
||||
* Whether blob URIs outside registered external bases may be written.
|
||||
*
|
||||
* Defaults to `false`. This option is supported only for local/native
|
||||
* tables; remote tables return an error when it is enabled. An enabled write
|
||||
* Defaults to `false`. This option is supported only in LanceDB Embedded;
|
||||
* LanceDB Distributed returns an error when it is enabled. An enabled write
|
||||
* stores the absolute URI reference without registering a base or copying
|
||||
* the external object into the database. The object must remain accessible
|
||||
* when the blob is read later.
|
||||
@@ -438,7 +438,7 @@ export abstract class Table {
|
||||
* Large columns (e.g. high-dimensional vectors or binary data) may not be
|
||||
* practical to prewarm.
|
||||
*
|
||||
* This feature is currently only supported on remote tables.
|
||||
* This feature is currently only supported in LanceDB Distributed.
|
||||
*/
|
||||
abstract prewarmData(columns?: string[]): Promise<void>;
|
||||
|
||||
@@ -594,9 +594,9 @@ export abstract class Table {
|
||||
/**
|
||||
* Add new columns with defined values.
|
||||
*
|
||||
* Local computed-column declaration and refresh require a source build with
|
||||
* the `experimental-functions` Cargo feature. Published packages disable it;
|
||||
* remote Cloud/Enterprise operations remain available.
|
||||
* LanceDB Embedded computed-column declaration and refresh require a source
|
||||
* build with the `experimental-functions` Cargo feature. Published packages
|
||||
* disable it; LanceDB Distributed operations remain available.
|
||||
*
|
||||
* The `{ computed }` form stores the expression rather than evaluating it
|
||||
* now: the column is committed with no values, and rows get them from
|
||||
@@ -608,7 +608,7 @@ export abstract class Table {
|
||||
* declaration reads a column, that column cannot be renamed, retyped or
|
||||
* dropped.
|
||||
*
|
||||
* On LanceDB Cloud and Enterprise the expression is planned by the
|
||||
* In LanceDB Distributed the expression is planned by the
|
||||
* server, and the refresh runs as a server job -- see
|
||||
* {@link Table#refreshColumnAsync}.
|
||||
* @param {AddColumnsSql[] | Field | Field[] | Schema} newColumnTransforms Either:
|
||||
@@ -640,8 +640,8 @@ export abstract class Table {
|
||||
*
|
||||
* Rows appended since the last refresh are filled by the next one, and
|
||||
* rows whose inputs changed since they were computed are recomputed;
|
||||
* everything else is left as it is. Local tables only: a remote refresh
|
||||
* runs as a server job, through {@link Table#refreshColumnAsync}.
|
||||
* everything else is left as it is. LanceDB Embedded only: in LanceDB
|
||||
* Distributed a refresh runs as a server job, through {@link Table#refreshColumnAsync}.
|
||||
* @param {string} column The name of the computed column to fill.
|
||||
* @returns {Promise<RefreshColumnResult>} A promise that resolves to the
|
||||
* number of rows filled and the new version number of the table.
|
||||
@@ -651,14 +651,15 @@ export abstract class Table {
|
||||
/**
|
||||
* Like {@link Table#refreshColumn}, but returns a handle to the refresh
|
||||
* job instead of blocking until it completes.
|
||||
* Local refresh requires a source build with `experimental-functions`.
|
||||
* Remote Cloud/Enterprise jobs do not require this feature.
|
||||
* LanceDB Embedded refresh requires a source build with
|
||||
* `experimental-functions`. LanceDB Distributed jobs do not require this
|
||||
* feature.
|
||||
*
|
||||
* The job may already be complete when returned; callers must not assume
|
||||
* the column is filled until {@link Job.wait} resolves. Invalid input --
|
||||
* an unknown column, or one that is not computed -- rejects here rather
|
||||
* than failing the job. On local tables the job runs in-process; on
|
||||
* LanceDB Cloud and Enterprise it is the server's backfill job.
|
||||
* than failing the job. In LanceDB Embedded the job runs in-process; in
|
||||
* LanceDB Distributed it is the server's backfill job.
|
||||
* @param {string} column The name of the computed column to fill.
|
||||
* @example
|
||||
* ```ts
|
||||
@@ -675,7 +676,7 @@ export abstract class Table {
|
||||
* A refresh running under a skip policy records each row it skipped with
|
||||
* the input that failed and the error. This lists those records, newest
|
||||
* job first, plus a summary for any fragment whose per-row detail was
|
||||
* capped. LanceDB Cloud and Enterprise only; reading errors needs read
|
||||
* capped. LanceDB Distributed only; reading errors needs read
|
||||
* access to the table, since a message carries the value that failed.
|
||||
* @param {FunctionErrorsOptions} options Optional filters: `jobId`,
|
||||
* `column`, and `limit` (server default 10000, cap 100000).
|
||||
@@ -994,7 +995,7 @@ export abstract class Table {
|
||||
* Specify exactly one of `column` or `indexName`.
|
||||
*
|
||||
* Model-backed tokenizers such as `jieba/*` and `lindera/*` are rebuilt in
|
||||
* the client process from index metadata. For remote tables, this means the
|
||||
* the client process from index metadata. In LanceDB Distributed, this means the
|
||||
* same tokenizer model files must also exist locally (under
|
||||
* `LANCE_LANGUAGE_MODEL_HOME`) and must match the files the server uses. A
|
||||
* mismatch cannot be detected: the returned tokens may differ from what the
|
||||
|
||||
+10
-10
@@ -54,34 +54,34 @@ pub struct ConnectionOptions {
|
||||
/// often each read pays the cost of checking for updates against object
|
||||
/// storage, raising per-read latency and cost.
|
||||
pub read_consistency_interval: Option<f64>,
|
||||
/// (For LanceDB OSS only): configuration for object storage.
|
||||
/// (For LanceDB Embedded only): configuration for object storage.
|
||||
///
|
||||
/// The available options are described at https://docs.lancedb.com/storage/
|
||||
pub storage_options: Option<HashMap<String, String>>,
|
||||
/// (For LanceDB OSS only): use directory namespace manifests as the source
|
||||
/// (For LanceDB Embedded only): use directory namespace manifests as the source
|
||||
/// of truth for table metadata. Existing directory-listed root tables are
|
||||
/// migrated into the manifest on access.
|
||||
pub manifest_enabled: Option<bool>,
|
||||
/// (For LanceDB OSS only): extra properties for the backing namespace
|
||||
/// (For LanceDB Embedded only): extra properties for the backing namespace
|
||||
/// client used by manifest-enabled native connections.
|
||||
pub namespace_client_properties: Option<HashMap<String, String>>,
|
||||
/// (For LanceDB OSS only): the session to use for this connection. Holds
|
||||
/// (For LanceDB Embedded only): the session to use for this connection. Holds
|
||||
/// shared caches and other session-specific state.
|
||||
pub session: Option<session::Session>,
|
||||
|
||||
/// (For LanceDB cloud only): configuration for the remote HTTP client.
|
||||
/// (For LanceDB Enterprise or LanceDB Cloud only): configuration for the HTTP client.
|
||||
pub client_config: Option<remote::ClientConfig>,
|
||||
/// (For LanceDB cloud only): the API key to use with LanceDB Cloud.
|
||||
/// (For LanceDB Enterprise or LanceDB Cloud only): the API key to use.
|
||||
///
|
||||
/// Can also be set via the environment variable `LANCEDB_API_KEY`.
|
||||
pub api_key: Option<String>,
|
||||
/// (For LanceDB cloud only): the region to use for LanceDB cloud.
|
||||
/// (For LanceDB Cloud only): the region to use for LanceDB Cloud (legacy).
|
||||
/// Defaults to 'us-east-1'.
|
||||
pub region: Option<String>,
|
||||
/// (For LanceDB cloud only): the host to use for LanceDB cloud. Used
|
||||
/// for testing purposes.
|
||||
/// (For LanceDB Enterprise only): the host of the LanceDB Enterprise
|
||||
/// deployment to connect to.
|
||||
pub host_override: Option<String>,
|
||||
/// (For LanceDB cloud only): OAuth configuration for IdP-based
|
||||
/// (For LanceDB Enterprise only): OAuth configuration for IdP-based
|
||||
/// authentication (e.g., Azure Entra ID). When set, token acquisition
|
||||
/// and refresh are handled entirely in Rust. TypeScript users should pass
|
||||
/// the public `OAuthConfig` type exported from `@lancedb/lancedb`.
|
||||
|
||||
@@ -108,7 +108,7 @@ pub struct ClientConfig {
|
||||
pub tls_config: Option<TlsConfig>,
|
||||
/// User identifier for tracking purposes.
|
||||
///
|
||||
/// This is sent as the `x-lancedb-user-id` header in requests to LanceDB Cloud/Enterprise.
|
||||
/// This is sent as the `x-lancedb-user-id` header in requests to LanceDB Enterprise.
|
||||
/// It can be set directly, or via the `LANCEDB_USER_ID` environment variable.
|
||||
/// Alternatively, set `LANCEDB_USER_ID_ENV_KEY` to specify another environment
|
||||
/// variable that contains the user ID value.
|
||||
|
||||
+16
-15
@@ -831,7 +831,7 @@ impl Table {
|
||||
self.inner_ref()?
|
||||
.as_native()
|
||||
.ok_or_else(|| lancedb::Error::NotSupported {
|
||||
message: "uses_v2_manifest_paths is not supported for remote tables.".into(),
|
||||
message: "uses_v2_manifest_paths is not supported in LanceDB Distributed.".into(),
|
||||
})
|
||||
.default_error()?
|
||||
.uses_v2_manifest_paths()
|
||||
@@ -844,7 +844,8 @@ impl Table {
|
||||
self.inner_ref()?
|
||||
.as_native()
|
||||
.ok_or_else(|| lancedb::Error::NotSupported {
|
||||
message: "migrate_manifest_paths_v2 is not supported for remote tables.".into(),
|
||||
message: "migrate_manifest_paths_v2 is not supported in LanceDB Distributed."
|
||||
.into(),
|
||||
})
|
||||
.default_error()?
|
||||
.migrate_manifest_paths_v2()
|
||||
@@ -867,40 +868,40 @@ pub struct IndexConfig {
|
||||
pub columns: Vec<String>,
|
||||
/// The UUID of the first segment of the index.
|
||||
///
|
||||
/// `undefined` for remote tables, which do not yet surface this.
|
||||
/// `undefined` in LanceDB Distributed, which does not yet surface this.
|
||||
pub index_uuid: Option<String>,
|
||||
/// The protobuf type URL, a precise type identifier for the index.
|
||||
///
|
||||
/// `undefined` for remote tables.
|
||||
/// `undefined` in LanceDB Distributed.
|
||||
pub type_url: Option<String>,
|
||||
/// When the index was created.
|
||||
///
|
||||
/// `undefined` for remote tables or indices created before timestamps were tracked.
|
||||
/// `undefined` in LanceDB Distributed or indices created before timestamps were tracked.
|
||||
pub created_at: Option<DateTime<Utc>>,
|
||||
/// The number of rows indexed, across all segments.
|
||||
///
|
||||
/// May be `undefined` for remote tables if the server does not report it.
|
||||
/// May be `undefined` in LanceDB Distributed if the server does not report it.
|
||||
pub num_indexed_rows: Option<i64>,
|
||||
/// The number of rows not yet covered by this index.
|
||||
///
|
||||
/// May be `undefined` for remote tables if the server does not report it.
|
||||
/// May be `undefined` in LanceDB Distributed if the server does not report it.
|
||||
pub num_unindexed_rows: Option<i64>,
|
||||
/// The total size in bytes of all index files across all segments.
|
||||
///
|
||||
/// `undefined` for remote tables or indices without size tracking.
|
||||
/// `undefined` in LanceDB Distributed or indices without size tracking.
|
||||
pub size_bytes: Option<i64>,
|
||||
/// The number of segments that make up the index.
|
||||
///
|
||||
/// `undefined` for remote tables.
|
||||
/// `undefined` in LanceDB Distributed.
|
||||
pub num_segments: Option<i32>,
|
||||
/// The on-disk index format version.
|
||||
///
|
||||
/// `undefined` for remote tables.
|
||||
/// `undefined` in LanceDB Distributed.
|
||||
pub index_version: Option<i32>,
|
||||
/// Index-type-specific details parsed as a JavaScript object.
|
||||
///
|
||||
/// Falls back to a raw string if JSON parsing fails. `undefined` for
|
||||
/// remote tables or when details are unavailable.
|
||||
/// Falls back to a raw string if JSON parsing fails. `undefined` in
|
||||
/// LanceDB Distributed or when details are unavailable.
|
||||
pub index_details: Option<serde_json::Value>,
|
||||
}
|
||||
|
||||
@@ -1616,11 +1617,11 @@ impl From<lancedb::function::FunctionErrors> for FunctionErrors {
|
||||
|
||||
#[napi(object)]
|
||||
pub struct RefreshMaterializedViewResult {
|
||||
/// How the view was brought up to date: "rebuild", or absent for remote SQL refreshes.
|
||||
/// How the view was brought up to date: "rebuild", or absent for LanceDB Distributed SQL refreshes.
|
||||
pub mode: Option<String>,
|
||||
/// Rows written by this refresh, or absent for remote SQL refreshes.
|
||||
/// Rows written by this refresh, or absent for LanceDB Distributed SQL refreshes.
|
||||
pub rows_written: Option<i64>,
|
||||
/// Source version refreshed to, or absent for remote SQL refreshes.
|
||||
/// Source version refreshed to, or absent for LanceDB Distributed SQL refreshes.
|
||||
pub source_version: Option<i64>,
|
||||
pub version: i64,
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user