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>
2026-10-30 23:36:52 +00:00 · 2026-10-28 14:04:41 -07:00
parent b4cbaf2f67
commit 4d7a64712f
148 changed files with 981 additions and 755 deletions
@@ -1,8 +1,16 @@
 # LanceDB prose rules

-These five rule files are copied unchanged from the `LanceDB.zip` asset of
-`lancedb/docs` release `vale-lancedb-v0.1.0`. The archive SHA-256 is
+`Dashes`, `PlainLanguage`, `ProductNames`, `VagueHeadings` and `VaguePhrases`
+come from the `LanceDB.zip` asset of `lancedb/docs` release
+`vale-lancedb-v0.1.0`, whose archive SHA-256 is
 `0730a43e919774121068811d5687c61dfc7a0421cff78e1393f5e565b622cb0f`.
+`ProductNames` no longer swaps in "LanceDB OSS".
+
+The product-terminology rules were added here: `EmbeddedName`,
+`RemoteExecution`, `OSSProduct`, `DistributedEnterprise`, `InternalNames`
+(warnings) and `LegacyCloud` (suggestion). They enforce the names in the
+docs repository's `STYLE.md#names`. Run every rule's tests from
+`.github/vale` with `vale test --coverage styles`.

 Keeping the rules here lets contributors and CI run Vale without access to the
 source repository. The root `.vale.ini` preserves the release's MDX settings
@@ -0,0 +1,19 @@
+extends: existence
+message: "'%s' reads as two products. LanceDB Enterprise provides LanceDB Distributed: name the product or the execution model, not both."
+link: https://github.com/lancedb/docs/blob/main/STYLE.md#names
+level: warning
+ignorecase: false
+tokens:
+  - 'Distributed(?:\s+(?:and|or)\s+|\s*/\s*)(?:LanceDB\s+)?Enterprise'
+  - 'Enterprise(?:\s+(?:and|or)\s+|\s*/\s*)(?:LanceDB\s+)?Distributed'
+tests:
+  - name: flags Distributed and Enterprise side by side
+    input: Choose Distributed or Enterprise. LanceDB Enterprise and LanceDB Distributed differ, and so does Distributed/Enterprise.
+    want: |
+      1:8:LanceDB.DistributedEnterprise:'Distributed or Enterprise' reads as two products. LanceDB Enterprise provides LanceDB Distributed: name the product or the execution model, not both.
+      1:43:LanceDB.DistributedEnterprise:'Enterprise and LanceDB Distributed' reads as two products. LanceDB Enterprise provides LanceDB Distributed: name the product or the execution model, not both.
+      1:98:LanceDB.DistributedEnterprise:'Distributed/Enterprise' reads as two products. LanceDB Enterprise provides LanceDB Distributed: name the product or the execution model, not both.
+  - name: leaves the defining sentence and the Embedded pair alone
+    input: |
+      LanceDB Enterprise runs LanceDB Distributed. Compare Embedded and Distributed execution. Distributed search and enterprise teams are fine.
+    want: ''
@@ -0,0 +1,22 @@
+extends: substitution
+message: "Use '%s' instead of '%s'."
+link: https://github.com/lancedb/docs/blob/main/STYLE.md#names
+level: warning
+ignorecase: false
+# The in-process execution model is LanceDB Embedded, whether the data is on
+# local disk or in object storage. Identifiers such as the `oss` product key
+# are code, and code is never prose.
+swap:
+  'LanceDB\s+(?:OSS|Oss|oss|Local|local)': LanceDB Embedded
+  '[Ll]ocal\s+mode': LanceDB Embedded
+tests:
+  - name: replaces the old names of the execution model
+    input: Start with LanceDB OSS, also called LanceDB Local, and move off local mode later.
+    want: |
+      1:12:LanceDB.EmbeddedName:Use 'LanceDB Embedded' instead of 'LanceDB OSS'.
+      1:37:LanceDB.EmbeddedName:Use 'LanceDB Embedded' instead of 'LanceDB Local'.
+      1:65:LanceDB.EmbeddedName:Use 'LanceDB Embedded' instead of 'local mode'.
+  - name: leaves the current name, other uses of local, and code alone
+    input: |
+      LanceDB Embedded reads local disk or object storage. Run LanceDB locally, set `availability.oss`, or call `LanceDB OSS` in a literal.
+    want: ''
@@ -0,0 +1,25 @@
+extends: substitution
+message: "Use '%s' instead of the internal name '%s'."
+link: https://github.com/lancedb/docs/blob/main/STYLE.md#names
+level: warning
+ignorecase: false
+# Internal component names stay out of public text. Environment variables such
+# as `PHALANX_*` and Helm keys such as `planExecutorNodes` are code. Geneva is
+# a product name and is not listed.
+swap:
+  Phalanx: query node
+  '[Pp]lan\s+[Ee]xecutor': executor
+  '[Pp]lan\s+[Ee]xecutors': executors
+  Sophon: LanceDB Enterprise
+tests:
+  - name: replaces internal component names
+    input: Phalanx sends work to a Plan Executor. Plan executors cache data in Sophon.
+    want: |
+      1:1:LanceDB.InternalNames:Use 'query node' instead of the internal name 'Phalanx'.
+      1:25:LanceDB.InternalNames:Use 'executor' instead of the internal name 'Plan Executor'.
+      1:40:LanceDB.InternalNames:Use 'executors' instead of the internal name 'Plan executors'.
+      1:69:LanceDB.InternalNames:Use 'LanceDB Enterprise' instead of the internal name 'Sophon'.
+  - name: leaves Geneva, configuration keys and code alone
+    input: |
+      Geneva runs on the executor + cache fleet. Set `PHALANX_REMOTE_FTS_SCORER` and `planExecutorNodes`.
+    want: ''
@@ -0,0 +1,21 @@
+extends: existence
+message: "'%s' is the legacy hosted service. Unless the text is specific to it, write 'LanceDB Enterprise' or 'LanceDB Distributed'."
+link: https://github.com/lancedb/docs/blob/main/STYLE.md#names
+level: suggestion
+ignorecase: false
+# A suggestion, because `db://` URIs, `api_key` and `region` for the hosted
+# service are still documented as LanceDB Cloud.
+tokens:
+  - 'LanceDB\s+Cloud'
+  - 'Cloud\s*/\s*Enterprise'
+  - 'Enterprise\s*/\s*Cloud'
+tests:
+  - name: suggests checking each LanceDB Cloud mention
+    input: Connect to LanceDB Cloud with an API key. Cloud/Enterprise users get the cache.
+    want: |
+      1:12:LanceDB.LegacyCloud:'LanceDB Cloud' is the legacy hosted service. Unless the text is specific to it, write 'LanceDB Enterprise' or 'LanceDB Distributed'.
+      1:43:LanceDB.LegacyCloud:'Cloud/Enterprise' is the legacy hosted service. Unless the text is specific to it, write 'LanceDB Enterprise' or 'LanceDB Distributed'.
+  - name: leaves other clouds and code alone
+    input: |
+      Deploy into your own cloud account on Google Cloud. Pass `LanceDB Cloud` as a literal.
+    want: ''
@@ -0,0 +1,28 @@
+extends: existence
+message: "Avoid '%s'. OSS is not a product name: write 'LanceDB Embedded', or 'open source' as a property."
+link: https://github.com/lancedb/docs/blob/main/STYLE.md#names
+level: warning
+ignorecase: false
+# Bare OSS used as a product, as in "OSS and Enterprise" or "in OSS". "LanceDB
+# OSS" is reported by LanceDB.EmbeddedName.
+tokens:
+  - 'OSS(?:\s+(?:and|or|vs\.?|versus)\s+|\s*/\s*)(?:LanceDB\s+)?Enterprise'
+  - 'Enterprise(?:\s+(?:and|or|vs\.?|versus)\s+|\s*/\s*)OSS'
+  - '(?:in|on|from|using|than)\s+OSS'
+tests:
+  - name: flags OSS presented as a product
+    input: Compare OSS vs Enterprise. It works in OSS and on OSS, unlike OSS/Enterprise.
+    want: |
+      1:9:LanceDB.OSSProduct:Avoid 'OSS vs Enterprise'. OSS is not a product name: write 'LanceDB Embedded', or 'open source' as a property.
+      1:37:LanceDB.OSSProduct:Avoid 'in OSS'. OSS is not a product name: write 'LanceDB Embedded', or 'open source' as a property.
+      1:48:LanceDB.OSSProduct:Avoid 'on OSS'. OSS is not a product name: write 'LanceDB Embedded', or 'open source' as a property.
+      1:63:LanceDB.OSSProduct:Avoid 'OSS/Enterprise'. OSS is not a product name: write 'LanceDB Embedded', or 'open source' as a property.
+  - name: flags the pair in either order
+    input: Both OSS and LanceDB Enterprise ship it, as do Enterprise or OSS.
+    want: |
+      1:6:LanceDB.OSSProduct:Avoid 'OSS and LanceDB Enterprise'. OSS is not a product name: write 'LanceDB Embedded', or 'open source' as a property.
+      1:48:LanceDB.OSSProduct:Avoid 'Enterprise or OSS'. OSS is not a product name: write 'LanceDB Embedded', or 'open source' as a property.
+  - name: leaves open source, identifiers and code alone
+    input: |
+      LanceDB Embedded (open source) and LanceDB Enterprise share the format. Set `oss: available` or read `in OSS` literally.
+    want: ''
@@ -9,7 +9,6 @@ swap:
  '(?:Lancedb|LanceDb|lanceDB|LANCEDB|Lance DB)': LanceDB
  'LanceDB (?:cloud|CLOUD)': LanceDB Cloud
  'LanceDB (?:enterprise|ENTERPRISE)': LanceDB Enterprise
-  'LanceDB (?:oss|Oss)': LanceDB OSS
  '(?:HuggingFace|Huggingface|Hugging face)': Hugging Face
  Langchain: LangChain
  Typescript: TypeScript
@@ -0,0 +1,33 @@
+extends: existence
+message: "Avoid '%s'. Write 'LanceDB Distributed' for the execution model or 'LanceDB Enterprise' for the product."
+link: https://github.com/lancedb/docs/blob/main/STYLE.md#names
+level: warning
+ignorecase: false
+# Remote storage, remote URLs and a git remote are other things and stay. Class
+# names such as `RemoteTable` are code, and code is never prose.
+tokens:
+  - '[Rr]emote\s+(?:mode|tables?|connections?|databases?)'
+tests:
+  - name: flags remote as the execution model
+    input: In remote mode, a remote table is opened through a remote connection.
+    want: |
+      1:4:LanceDB.RemoteExecution:Avoid 'remote mode'. Write 'LanceDB Distributed' for the execution model or 'LanceDB Enterprise' for the product.
+      1:19:LanceDB.RemoteExecution:Avoid 'remote table'. Write 'LanceDB Distributed' for the execution model or 'LanceDB Enterprise' for the product.
+      1:52:LanceDB.RemoteExecution:Avoid 'remote connection'. Write 'LanceDB Distributed' for the execution model or 'LanceDB Enterprise' for the product.
+  - name: flags plurals and a heading
+    input: |
+      ## Remote tables
+
+      Remote databases hold remote tables.
+    want: |
+      1:4:LanceDB.RemoteExecution:Avoid 'Remote tables'. Write 'LanceDB Distributed' for the execution model or 'LanceDB Enterprise' for the product.
+      3:1:LanceDB.RemoteExecution:Avoid 'Remote databases'. Write 'LanceDB Distributed' for the execution model or 'LanceDB Enterprise' for the product.
+      3:23:LanceDB.RemoteExecution:Avoid 'remote tables'. Write 'LanceDB Distributed' for the execution model or 'LanceDB Enterprise' for the product.
+  - name: leaves other remotes and code alone
+    input: |
+      Push to the git remote, read remote storage and fetch a remote URL. `open_table` returns a `RemoteTable`; see `remote table` in the API.
+
+      ```python
+      remote_table = db.open_table("remote table")
+      ```
+    want: ''