diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a13086061..1e111fdf2 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -94,7 +94,7 @@ what the capability is, and what the embedded form does instead. A separate private repository supplies the fuller version of each, which replaces the page at the same path when the published site is assembled. -Two things to know before editing: +Three things to know before editing: **Code examples are not written into the pages.** They live in real tests under `docs/web-tests/{py,ts,rs}`, are extracted into `docs/web/snippets/`, and are @@ -116,6 +116,27 @@ Enterprise pages attach their additions to the right section, so they are assigned once and never regenerated. Leave an existing anchor alone even when you reword the heading above it; only new headings need a new one. +**A page can declare where it applies.** Its frontmatter says whether LanceDB +OSS and LanceDB Enterprise have the feature -- `available`, `unavailable`, or +`varies` when it depends on version or configuration -- and one sentence that +says how: + +```yaml +availability: + oss: unavailable + enterprise: available + summary: >- + Requests to a deployment carry an API key or an OAuth token. Embedded + LanceDB has no server to sign in to. +``` + +The assembled site renders this as a label above the page's content, as a +sidebar tag when only one offering has the feature, and as the page's row in +the comparison on [OSS and Enterprise](docs/web/basics/offerings.mdx). Do not +also open the page with a badge of its own, and keep a qualification that only +one section needs in that section's text. A `mint dev` preview of `docs/web` +alone renders neither the labels nor the comparison. + ## Release process For information on the release process, see: [release_process.md](release_process.md) diff --git a/docs/web/enterprise/authentication.mdx b/docs/web/enterprise/authentication.mdx index f41603fdf..4d04120fc 100644 --- a/docs/web/enterprise/authentication.mdx +++ b/docs/web/enterprise/authentication.mdx @@ -4,14 +4,15 @@ sidebarTitle: "Authentication" description: "Authentication modes for LanceDB Enterprise: API keys and OAuth credentials." icon: key keywords: ["authentication", "oauth", "api key", "azure managed identity", "client credentials"] +availability: + oss: unavailable + enterprise: available + summary: >- + Requests to a deployment carry an API key or an OAuth token, whichever it is + configured to accept. Embedded LanceDB has no server to sign in to; see + [Architecture](/architecture). --- -Enterprise - -This page describes a LanceDB Enterprise capability. The embedded form -of LanceDB has no server to provide it -- see -[Architecture](/architecture) for what differs between the two. - A deployment authenticates every request before [authorization](/governance/authorization) decides what it may do, against a `db://` remote table, in one of two ways: @@ -50,6 +51,10 @@ from an OIDC issuer and attach them to every request. Token acquisition, caching, and refresh are handled inside the client -- your application code only provides the configuration. +A deployment accepts these tokens only when its administrator has configured +it with your identity provider. Ask them for the issuer URL, client ID and +scopes to use. + In Python, OAuth is supported through `lancedb.connect_async`. The synchronous `connect` entry point continues to use API key authentication for `db://` diff --git a/docs/web/feature-engineering/materialized-views.mdx b/docs/web/feature-engineering/materialized-views.mdx index 7b00a6ce4..f8750e2d9 100644 --- a/docs/web/feature-engineering/materialized-views.mdx +++ b/docs/web/feature-engineering/materialized-views.mdx @@ -4,6 +4,13 @@ sidebarTitle: "Materialized View Refresh" description: "A lakehouse object: a table defined by a query over another table, brought up to date by each refresh." icon: table keywords: ["materialized view", "create_materialized_view", "refresh", "full refresh"] +availability: + oss: available + enterprise: varies + summary: >- + The SDK creates and refreshes a local view in your process. On a deployment, + views are off by default, and how they work depends on its version and + configuration; see [Against a deployment](#availability). --- import { @@ -80,8 +87,8 @@ argument; every local refresh is a full one. `create_materialized_view` and `refresh` also work on a `db://` connection. There the SDK sends them to the deployment as SQL -- `CREATE MATERIALIZED VIEW` and `REFRESH MATERIALIZED VIEW` -- and the work runs on the cluster rather than -in your process. `source_version` is for local views only; the SDK refuses it -on a remote refresh. +in your process. `with_no_data` and `source_version` are for local views only; +the SDK refuses them on a `db://` connection. Materialized views are off by default on a deployment and have to be enabled there. How a deployment refreshes a view -- rebuilding the whole view, as above, diff --git a/docs/web/governance/authorization.mdx b/docs/web/governance/authorization.mdx index 044db158e..b47f32351 100644 --- a/docs/web/governance/authorization.mdx +++ b/docs/web/governance/authorization.mdx @@ -4,15 +4,15 @@ sidebarTitle: "Authorization" description: "Who may do what: privileges granted on catalog objects to principals, groups, roles, and API keys." icon: shield-halved keywords: ["authorization", "authz", "privileges", "rbac", "access control"] +availability: + oss: unavailable + enterprise: varies + summary: >- + A deployment checks privileges on its databases, namespaces and tables only + when its administrator has configured it to. Embedded LanceDB has no such + layer: access is whatever the object store allows. --- -Enterprise - -This page describes a LanceDB Enterprise capability. Embedded LanceDB has no -such layer -- access is whatever the object store enforces on the bucket or -directory, which is coarser and has no concept of a table. See -[Architecture](/architecture) for what differs between the two. - [Authentication](/enterprise/authentication) establishes who is calling. Authorization decides what they may do. diff --git a/docs/web/search/vector-search.mdx b/docs/web/search/vector-search.mdx index c7324701a..f6c793e78 100644 --- a/docs/web/search/vector-search.mdx +++ b/docs/web/search/vector-search.mdx @@ -3,6 +3,13 @@ title: "Vector Search" sidebarTitle: "Vector Search" description: "Learn how to run vector search queries in LanceDB. Includes best practices, tips and examples." icon: "arrow-up-right-dots" +availability: + oss: available + enterprise: available + summary: >- + Vector search runs in the embedded library and on a deployment. A few query + options depend on the SDK or on the deployment's version; their sections + say so. --- import { @@ -208,7 +215,7 @@ The supported values are: | `normal` | Use the default balance between query latency and recall. This only has an effect for RQ indexes built with `num_bits > 1`. | | `accurate` | Prefer higher recall, which can increase query latency. | -You can change `approx_mode` per query without rebuilding the index. For RQ indexes built with `num_bits=1`, `normal` uses the same one-bit scoring path as `fast`. If you also set `refine_factor`, LanceDB first uses `approx_mode` while finding candidates, then reranks the selected candidates on full vectors. +Only the Rust SDK sets `approx_mode`; the Python and TypeScript SDKs do not expose it. You can change `approx_mode` per query without rebuilding the index. For RQ indexes built with `num_bits=1`, `normal` uses the same one-bit scoring path as `fast`. If you also set `refine_factor`, LanceDB first uses `approx_mode` while finding candidates, then reranks the selected candidates on full vectors. ### Tuning `nprobes` @@ -223,6 +230,8 @@ You can change `approx_mode` per query without rebuilding the index. For RQ inde For filtered ANN searches, you can also set `minimum_nprobes` and `maximum_nprobes`. LanceDB starts with the minimum and can scan more partitions up to the maximum if the filter leaves too few candidates. Calling `nprobes(n)` fixes both values to `n`, which disables that adaptive behavior. +Whether a deployment honors this range depends on its version; one that does not searches exactly +`minimum_nprobes` partitions. ### Vector Search with Prefiltering