Merge remote-tracking branch 'origin/main' into feature/wal-hybrid-pk

.bumpversion.toml

@@ -1,5 +1,5 @@
 [tool.bumpversion]
-current_version = "0.39.0-beta.6"
+current_version = "0.40.0-beta.8"
 parse = """(?x)
     (?P<major>0|[1-9]\\d*)\\.
     (?P<minor>0|[1-9]\\d*)\\.

.github/workflows/nodejs.yml

@@ -207,4 +207,4 @@ jobs:
         pnpm tsc
     - name: Test
       run: |
-        pnpm test
+        pnpm test --runInBand

.github/workflows/pypi-publish.yml

@@ -21,7 +21,7 @@ permissions:
   contents: read
 
 # Without this, a force-push to a PR leaves the previous run going -- including
-# a ~74 minute Windows job and a billed arm64 wheel build.
+# a long fat-LTO Windows job and a billed arm64 wheel build.
 concurrency:
   group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
   cancel-in-progress: true
@@ -123,18 +123,17 @@ jobs:
           path: target/wheels/lancedb-*.whl
           if-no-files-found: error
   windows:
-    timeout-minutes: 90
-    runs-on: windows-latest
+    # The fat-LTO build of the `lancedb` crate does not finish within 90 minutes
+    # on the 4-core standard runner, so use the 8-core larger runner with extra
+    # headroom.
+    timeout-minutes: 150
+    runs-on: windows-2025-8x-x64
     env:
       # link.exe is single-threaded and the long pole on Windows builds. Use
       # rustc's bundled lld-link instead.
       CARGO_TARGET_X86_64_PC_WINDOWS_MSVC_LINKER: rust-lld
-      # Fat LTO of the cdylib is single-threaded and the peak-memory step of the
-      # build. ThinLTO parallelizes it across the runner's cores, at some cost
-      # to runtime performance on our least performance-sensitive platform.
-      # Matches what the nodejs Windows builds already do in npm-publish.yml.
-      CARGO_PROFILE_RELEASE_LTO: thin
-      CARGO_PROFILE_RELEASE_CODEGEN_UNITS: 16
+      # Keep the repository's fat LTO / 1 codegen unit release profile to leave
+      # headroom below PyPI's file-size limit for Windows wheels.
     steps:
       - uses: actions/checkout@v6
         with:
@@ -149,7 +148,7 @@ jobs:
       # or the default branch -- so with no run on main there is nothing that
       # can populate an entry the release build would be allowed to read. Fixing
       # this needs a main/nightly trigger (which would also catch wheel-build
-      # breakage before a release); the ~74 minutes here is otherwise dominated
+      # breakage before a release); the build time here is otherwise dominated
       # by the fat-LTO link, which no cache avoids.
       - uses: ./.github/workflows/build_windows_wheel
         with:

.github/workflows/python.yml

@@ -156,7 +156,7 @@ jobs:
       - name: Test without pylance or pandas
         run: |
           pip uninstall -y pylance pandas
-          pytest -vv python/tests/test_table.py
+          pytest -vv python/tests/test_table.py python/tests/test_namespace_no_pylance.py
       # Make sure wheels are not included in the Rust cache
       - name: Delete wheels
         run: rm -rf target/wheels

CLAUDE.md

@@ -1 +0,0 @@
-AGENTS.md

Cargo.toml

@@ -13,20 +13,20 @@ categories = ["database-implementations"]
 rust-version = "1.91.0"
 
 [workspace.dependencies]
-lance = { "version" = "=12.0.0-beta.16", default-features = false, "tag" = "v12.0.0-beta.16", "git" = "https://github.com/lance-format/lance.git" }
-lance-core = { "version" = "=12.0.0-beta.16", "tag" = "v12.0.0-beta.16", "git" = "https://github.com/lance-format/lance.git" }
-lance-datagen = { "version" = "=12.0.0-beta.16", "tag" = "v12.0.0-beta.16", "git" = "https://github.com/lance-format/lance.git" }
-lance-file = { "version" = "=12.0.0-beta.16", "tag" = "v12.0.0-beta.16", "git" = "https://github.com/lance-format/lance.git" }
-lance-io = { "version" = "=12.0.0-beta.16", default-features = false, "tag" = "v12.0.0-beta.16", "git" = "https://github.com/lance-format/lance.git" }
-lance-index = { "version" = "=12.0.0-beta.16", "tag" = "v12.0.0-beta.16", "git" = "https://github.com/lance-format/lance.git" }
-lance-linalg = { "version" = "=12.0.0-beta.16", "tag" = "v12.0.0-beta.16", "git" = "https://github.com/lance-format/lance.git" }
-lance-namespace = { "version" = "=12.0.0-beta.16", "tag" = "v12.0.0-beta.16", "git" = "https://github.com/lance-format/lance.git" }
-lance-namespace-impls = { "version" = "=12.0.0-beta.16", default-features = false, "tag" = "v12.0.0-beta.16", "git" = "https://github.com/lance-format/lance.git" }
-lance-table = { "version" = "=12.0.0-beta.16", "tag" = "v12.0.0-beta.16", "git" = "https://github.com/lance-format/lance.git" }
-lance-testing = { "version" = "=12.0.0-beta.16", "tag" = "v12.0.0-beta.16", "git" = "https://github.com/lance-format/lance.git" }
-lance-datafusion = { "version" = "=12.0.0-beta.16", "tag" = "v12.0.0-beta.16", "git" = "https://github.com/lance-format/lance.git" }
-lance-encoding = { "version" = "=12.0.0-beta.16", "tag" = "v12.0.0-beta.16", "git" = "https://github.com/lance-format/lance.git" }
-lance-arrow = { "version" = "=12.0.0-beta.16", "tag" = "v12.0.0-beta.16", "git" = "https://github.com/lance-format/lance.git" }
+lance = { "version" = "=13.0.0-beta.8", default-features = false, "tag" = "v13.0.0-beta.8", "git" = "https://github.com/lance-format/lance.git" }
+lance-core = { "version" = "=13.0.0-beta.8", "tag" = "v13.0.0-beta.8", "git" = "https://github.com/lance-format/lance.git" }
+lance-datagen = { "version" = "=13.0.0-beta.8", "tag" = "v13.0.0-beta.8", "git" = "https://github.com/lance-format/lance.git" }
+lance-file = { "version" = "=13.0.0-beta.8", "tag" = "v13.0.0-beta.8", "git" = "https://github.com/lance-format/lance.git" }
+lance-io = { "version" = "=13.0.0-beta.8", default-features = false, "tag" = "v13.0.0-beta.8", "git" = "https://github.com/lance-format/lance.git" }
+lance-index = { "version" = "=13.0.0-beta.8", "tag" = "v13.0.0-beta.8", "git" = "https://github.com/lance-format/lance.git" }
+lance-linalg = { "version" = "=13.0.0-beta.8", "tag" = "v13.0.0-beta.8", "git" = "https://github.com/lance-format/lance.git" }
+lance-namespace = { "version" = "=13.0.0-beta.8", "tag" = "v13.0.0-beta.8", "git" = "https://github.com/lance-format/lance.git" }
+lance-namespace-impls = { "version" = "=13.0.0-beta.8", default-features = false, "tag" = "v13.0.0-beta.8", "git" = "https://github.com/lance-format/lance.git" }
+lance-table = { "version" = "=13.0.0-beta.8", "tag" = "v13.0.0-beta.8", "git" = "https://github.com/lance-format/lance.git" }
+lance-testing = { "version" = "=13.0.0-beta.8", "tag" = "v13.0.0-beta.8", "git" = "https://github.com/lance-format/lance.git" }
+lance-datafusion = { "version" = "=13.0.0-beta.8", "tag" = "v13.0.0-beta.8", "git" = "https://github.com/lance-format/lance.git" }
+lance-encoding = { "version" = "=13.0.0-beta.8", "tag" = "v13.0.0-beta.8", "git" = "https://github.com/lance-format/lance.git" }
+lance-arrow = { "version" = "=13.0.0-beta.8", "tag" = "v13.0.0-beta.8", "git" = "https://github.com/lance-format/lance.git" }
 lancedb = { path = "rust/lancedb", default-features = false }
 ahash = "0.8"
 # Note that this one does not include pyarrow
@@ -41,6 +41,8 @@ arrow-select = "58.0.0"
 arrow-cast = "58.0.0"
 arrow-flight = { version = "58.0.0", features = ["flight-sql-experimental"] }
 async-trait = "0"
+# Smithy JSON 0.63 requires the pre-1.7 Document representation; allow the MSRV pin.
+aws-smithy-types = ">=1.3.6, <1.7"
 bytes = "1"
 datafusion = { version = "54.0.0", default-features = false }
 datafusion-catalog = "54.0.0"
@@ -60,12 +62,13 @@ log = "0.4"
 metrics = "0.24"
 metrics-util = "0.19"
 moka = { version = "0.12", features = ["future"] }
-object_store = "0.13.2"
+object_store = "0.14.1"
 pin-project = "1.0.7"
 rand = "0.9"
 snafu = "0.8"
 url = "2"
 num-traits = "0.2"
+oauth2 = { version = "5.0", default-features = false }
 regex = "1.10"
 semver = "1.0.25"
 serde = "1"

docs/src/java/java.md

@@ -14,7 +14,7 @@ Add the following dependency to your `pom.xml`:
 <dependency>
     <groupId>com.lancedb</groupId>
     <artifactId>lancedb-core</artifactId>
-    <version>0.39.0-beta.6</version>
+    <version>0.40.0-beta.8</version>
 </dependency>
 ```
 

docs/src/js/classes/BlobFile.md

@@ -0,0 +1,62 @@
+[**@lancedb/lancedb**](../README.md) • **Docs**
+
+***
+
+[@lancedb/lancedb](../globals.md) / BlobFile
+
+# Class: BlobFile
+
+A lazy handle to blob bytes. Create one with [Table.fetchBlobFiles](Table.md#fetchblobfiles).
+
+## Methods
+
+### read()
+
+```ts
+read(): Promise<Buffer>
+```
+
+Reads from the cursor to the end and advances the cursor.
+
+A second call returns an empty buffer. [BlobFile.readRange](BlobFile.md#readrange) does
+not move the cursor.
+
+#### Returns
+
+`Promise`&lt;`Buffer`&gt;
+
+***
+
+### readRange()
+
+```ts
+readRange(start, end): Promise<Buffer>
+```
+
+Reads the half-open byte range `[start, end)`.
+
+Fails when `end` is past the blob size. Does not move the cursor.
+
+#### Parameters
+
+* **start**: `bigint`
+
+* **end**: `bigint`
+
+#### Returns
+
+`Promise`&lt;`Buffer`&gt;
+
+***
+
+### size()
+
+```ts
+size(): bigint
+```
+
+Returns the blob size in bytes.
+
+#### Returns
+
+`bigint`

docs/src/js/classes/Catalog.md

@@ -0,0 +1,107 @@
+[**@lancedb/lancedb**](../README.md) • **Docs**
+
+***
+
+[@lancedb/lancedb](../globals.md) / Catalog
+
+# Class: Catalog
+
+A remote catalog manages databases through the server's root namespace.
+
+## Accessors
+
+### uri
+
+```ts
+get uri(): string
+```
+
+The root namespace endpoint.
+
+#### Returns
+
+`string`
+
+## Methods
+
+### connectDatabase()
+
+```ts
+connectDatabase(name): Promise<Connection>
+```
+
+Connect to an existing database by its logical name.
+
+#### Parameters
+
+* **name**: `string`
+
+#### Returns
+
+`Promise`&lt;[`Connection`](Connection.md)&gt;
+
+***
+
+### createDatabase()
+
+```ts
+createDatabase(name, options): Promise<Connection>
+```
+
+Create a database, or open an existing database when existOk is true.
+
+#### Parameters
+
+* **name**: `string`
+
+* **options** = `{}`
+
+* **options.existOk?**: `boolean`
+
+#### Returns
+
+`Promise`&lt;[`Connection`](Connection.md)&gt;
+
+***
+
+### dropDatabase()
+
+```ts
+dropDatabase(name, options): Promise<void>
+```
+
+Drop an empty database. The server rejects nonempty databases.
+
+#### Parameters
+
+* **name**: `string`
+
+* **options** = `{}`
+
+* **options.ignoreMissing?**: `boolean`
+
+#### Returns
+
+`Promise`&lt;`void`&gt;
+
+***
+
+### listDatabases()
+
+```ts
+listDatabases(options): Promise<ListDatabasesResponse>
+```
+
+List one page of databases; pass pageToken from a response for the next page.
+
+#### Parameters
+
+* **options** = `{}`
+
+* **options.limit?**: `number`
+
+* **options.pageToken?**: `string`
+
+#### Returns
+
+`Promise`&lt;[`ListDatabasesResponse`](../interfaces/ListDatabasesResponse.md)&gt;

docs/src/js/classes/Connection.md

@@ -180,13 +180,13 @@ abstract createMaterializedView(
 
 Define a materialized view named `name` over the table `source`.
 
-The view is created empty, with the query recorded in its schema
-metadata; `view.refresh()` computes the rows. The view is a normal
-table: it can be queried, indexed and searched, and it appears in
-`tableNames`. The source table must have stable row ids (create it with
+The view is populated before creation returns. Set `withNoData` to create
+only its definition and empty backing table. The view is a normal table:
+it can be queried, indexed and searched, and it appears in `tableNames`.
+The source table must have stable row ids (create it with
 the `newTableEnableStableRowIds` storage option); they keep the view's
 provenance valid across source compactions and cannot be enabled after
-a table exists. Local databases only.
+a table exists.
 
 #### Parameters
 
@@ -202,6 +202,8 @@ a table exists. Local databases only.
 
 * **options.where?**: `string`
 
+* **options.withNoData?**: `boolean`
+
 #### Returns
 
 `Promise`<[`MaterializedView`](MaterializedView.md)>
@@ -317,6 +319,38 @@ Creates a new Table and initialize it with new data.
 
 ***
 
+### createView()
+
+```ts
+abstract createView(
+   name,
+   query,
+   namespacePath?): Promise<ViewDescription>
+```
+
+Create a view: a named query the database plans on every read.
+
+The query is planned once, at creation, so one that cannot be planned is
+rejected now rather than at the first read. A view holds no rows, and its
+readers see its sources as they are at read time.
+
+There is no replace: a name already taken is an error, and changing a
+view is a drop followed by a create.
+
+#### Parameters
+
+* **name**: `string`
+
+* **query**: `string`
+
+* **namespacePath?**: `string`[]
+
+#### Returns
+
+`Promise`&lt;[`ViewDescription`](../interfaces/ViewDescription.md)&gt;
+
+***
+
 ### describeNamespace()
 
 ```ts
@@ -340,6 +374,27 @@ The namespace's properties
 
 ***
 
+### describeView()
+
+```ts
+abstract describeView(name, namespacePath?): Promise<ViewDescription>
+```
+
+What this database records about the view named `name`: its defining
+query and the schema that query resolved to.
+
+#### Parameters
+
+* **name**: `string`
+
+* **namespacePath?**: `string`[]
+
+#### Returns
+
+`Promise`&lt;[`ViewDescription`](../interfaces/ViewDescription.md)&gt;
+
+***
+
 ### display()
 
 ```ts
@@ -373,6 +428,54 @@ Drop all tables in the database.
 
 ***
 
+### dropMaterializedView()
+
+```ts
+abstract dropMaterializedView(name, namespacePath?): Promise<void>
+```
+
+Drop the materialized view named `name`.
+
+The view may become unavailable before physical cleanup finishes. Use
+[dropMaterializedViewAsync](Connection.md#dropmaterializedviewasync) to retain and wait for the cleanup job.
+
+Rejects a table that exists but is not a materialized view.
+
+#### Parameters
+
+* **name**: `string`
+
+* **namespacePath?**: `string`[]
+
+#### Returns
+
+`Promise`&lt;`void`&gt;
+
+***
+
+### dropMaterializedViewAsync()
+
+```ts
+abstract dropMaterializedViewAsync(name, namespacePath?): Promise<Job>
+```
+
+Start dropping the materialized view named `name` and return its cleanup
+job without waiting for completion.
+
+Rejects a table that exists but is not a materialized view.
+
+#### Parameters
+
+* **name**: `string`
+
+* **namespacePath?**: `string`[]
+
+#### Returns
+
+`Promise`&lt;[`Job`](Job.md)&gt;
+
+***
+
 ### dropNamespace()
 
 ```ts
@@ -448,6 +551,28 @@ on the returned job to know when cleanup has finished.
 
 ***
 
+### dropView()
+
+```ts
+abstract dropView(name, namespacePath?): Promise<void>
+```
+
+Drop the view named `name`.
+
+The tables it reads are untouched: a view holds no rows of its own.
+
+#### Parameters
+
+* **name**: `string`
+
+* **namespacePath?**: `string`[]
+
+#### Returns
+
+`Promise`&lt;`void`&gt;
+
+***
+
 ### isOpen()
 
 ```ts
@@ -586,6 +711,26 @@ A page of table names and an
 
 ***
 
+### listViews()
+
+```ts
+abstract listViews(namespacePath?): Promise<string[]>
+```
+
+The names of the views in one namespace.
+
+Names only; a definition comes from [describeView](Connection.md#describeview).
+
+#### Parameters
+
+* **namespacePath?**: `string`[]
+
+#### Returns
+
+`Promise`&lt;`string`[]&gt;
+
+***
+
 ### openJob()
 
 ```ts

docs/src/js/classes/MaterializedView.md

@@ -49,7 +49,7 @@ get name(): string
 definition(): Promise<MaterializedViewDefinition>
 ```
 
-The query that defines the view, read from its stored schema.
+The query that defines the view.
 
 #### Returns
 

docs/src/js/classes/OAuthSession.md

@@ -0,0 +1,105 @@
+[**@lancedb/lancedb**](../README.md) • **Docs**
+
+***
+
+[@lancedb/lancedb](../globals.md) / OAuthSession
+
+# Class: OAuthSession
+
+Explicit OAuth session lifecycle for the persistent token cache: eager
+`login`, non-secret `status`, and local `logout`.
+
+A session is built from the same [OAuthConfig](../interfaces/OAuthConfig.md) used to connect
+(including its `tokenCache` options). A connection created with the same
+configuration shares the cache, so logging in here prepares tokens for
+later processes without any database request.
+
+`login` always runs the configured interactive flow and replaces the cached
+session (the most recent login wins). `logout` removes only the local
+credential; it does not revoke anything with the provider and does not sign
+out of a browser SSO session.
+
+## Example
+
+```typescript
+const config: OAuthConfig = {
+  issuerUrl: "https://issuer.example.com",
+  clientId: "my-app",
+  scopes: ["openid", "offline_access"],
+  flow: OAuthFlowType.DeviceCode,
+  tokenCache: { cacheDir: "/tmp/my-app/oauth-cache" },
+};
+const session = new OAuthSession(config);
+const status = await session.login();
+```
+
+## Constructors
+
+### new OAuthSession()
+
+```ts
+new OAuthSession(config): OAuthSession
+```
+
+Create a session manager for the given OAuth configuration.
+
+#### Parameters
+
+* **config**: [`OAuthConfig`](../interfaces/OAuthConfig.md)
+
+#### Returns
+
+[`OAuthSession`](OAuthSession.md)
+
+## Methods
+
+### login()
+
+```ts
+login(): Promise<SessionStatus>
+```
+
+Eagerly run the configured authentication flow and store the session.
+
+A successful login always replaces any prior cached session for this
+identity; if the provider does not issue a refresh token (for example
+without `offline_access`), the previous record is removed and the status
+reports `refreshable == false`.
+
+#### Returns
+
+`Promise`&lt;[`SessionStatus`](../interfaces/SessionStatus.md)&gt;
+
+***
+
+### logout()
+
+```ts
+logout(): Promise<SessionLogout>
+```
+
+Remove the matching local cached credential.
+
+This only deletes the local cache entry. It does not revoke the refresh
+token with the provider and does not sign out of a browser SSO session.
+Repeated calls succeed; `removed` reports whether a credential existed.
+
+#### Returns
+
+`Promise`&lt;[`SessionLogout`](../interfaces/SessionLogout.md)&gt;
+
+***
+
+### status()
+
+```ts
+status(): Promise<SessionStatus>
+```
+
+Report whether a matching cached session exists, with safe metadata.
+
+This never contacts the identity provider and never exposes token values.
+
+#### Returns
+
+`Promise`&lt;[`SessionStatus`](../interfaces/SessionStatus.md)&gt;

docs/src/js/classes/Table.md

@@ -74,10 +74,10 @@ now: the column is committed with no values, and rows get them from
 [Table#refreshColumn](Table.md#refreshcolumn). Declaring one therefore costs the same on a
 large table as on an empty one.
 
-A refresh does not revisit rows it has already filled, so mutating an
-input leaves the value computed at fill time; recomputing means dropping
-the column and declaring it again. While a declaration reads a column,
-that column cannot be renamed, retyped or dropped.
+A refresh also recomputes the rows whose inputs changed since they were
+computed, so a mutated input is reflected by the next refresh. While a
+declaration reads a column, that column cannot be renamed, retyped or
+dropped.
 
 On LanceDB Cloud and Enterprise the expression is planned by the
 server, and the refresh runs as a server job -- see
@@ -137,6 +137,20 @@ containing the new version number of the table after altering the columns.
 
 ***
 
+### blobColumns()
+
+```ts
+abstract blobColumns(): Promise<string[]>
+```
+
+Blob v2 columns, including nested dotted paths.
+
+#### Returns
+
+`Promise`&lt;`string`[]&gt;
+
+***
+
 ### branches()
 
 ```ts
@@ -499,6 +513,54 @@ Drop an index from the table.
 
 ***
 
+### fetchBlobFiles()
+
+```ts
+abstract fetchBlobFiles(column, rowIds): Promise<(null | BlobFile)[]>
+```
+
+Opens lazy blob handles for `column` at the given row IDs using the
+table's current checkout.
+
+Preserves input order, duplicates, and nulls. Use this for large payloads.
+See [Table.fetchBlobs](Table.md#fetchblobs) for row-ID validity across versions.
+
+#### Parameters
+
+* **column**: `string`
+
+* **rowIds**: readonly (`number` \| `bigint`)[]
+
+#### Returns
+
+`Promise`&lt;(`null` \| [`BlobFile`](BlobFile.md))[]&gt;
+
+***
+
+### fetchBlobs()
+
+```ts
+abstract fetchBlobs(column, rowIds): Promise<(null | Buffer)[]>
+```
+
+Bytes for `column` at row IDs from [Query.withRowId](Query.md#withrowid).
+
+Reads the table's current checkout. IDs from another version can fail after
+compaction unless stable row ids are enabled. Results keep input order and
+duplicates. Null blobs are `null`. Empty blobs are empty buffers.
+
+#### Parameters
+
+* **column**: `string`
+
+* **rowIds**: readonly (`number` \| `bigint`)[]
+
+#### Returns
+
+`Promise`&lt;(`null` \| `Buffer`)[]&gt;
+
+***
+
 ### flushLsm()
 
 ```ts
@@ -516,6 +578,41 @@ so this is safe to call repeatedly.
 
 ***
 
+### functionErrors()
+
+```ts
+abstract functionErrors(options?): Promise<FunctionErrors>
+```
+
+The per-row errors Function refreshes recorded on this 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
+access to the table, since a message carries the value that failed.
+
+#### Parameters
+
+* **options?**: [`FunctionErrorsOptions`](../interfaces/FunctionErrorsOptions.md)
+    Optional filters: `jobId`,
+    `column`, and `limit` (server default 10000, cap 100000).
+
+#### Returns
+
+`Promise`&lt;[`FunctionErrors`](../interfaces/FunctionErrors.md)&gt;
+
+The records, the capped fragments,
+and whether the listing stopped at its limit.
+
+#### Example
+
+```ts
+const { records, truncated } = await table.functionErrors({ column: "embedding" });
+```
+
+***
+
 ### getLsmStats()
 
 ```ts
@@ -854,10 +951,10 @@ abstract refreshColumn(column): Promise<RefreshColumnResult>
 
 Fill the rows of a computed column that hold no value yet.
 
-Rows appended since the last refresh are filled by the next one; rows
-already filled are left as they are, so the call is idempotent and does
-not observe a mutated input. Local tables only: a remote refresh runs
-as a server job, through [Table#refreshColumnAsync](Table.md#refreshcolumnasync).
+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 [Table#refreshColumnAsync](Table.md#refreshcolumnasync).
 
 #### Parameters
 

docs/src/js/enumerations/ClientAuthMethod.md

@@ -0,0 +1,48 @@
+[**@lancedb/lancedb**](../README.md) • **Docs**
+
+***
+
+[@lancedb/lancedb](../globals.md) / ClientAuthMethod
+
+# Enumeration: ClientAuthMethod
+
+How the client authenticates to the OAuth token endpoint.
+
+The method applies to every OAuth request that carries client
+authentication: client-credentials, authorization-code exchange,
+refresh-token, and device-authorization requests. The Azure managed
+identity flow ignores this option.
+
+## Enumeration Members
+
+### ClientSecretBasic
+
+```ts
+ClientSecretBasic: "client_secret_basic";
+```
+
+HTTP Basic authentication. This is the RFC 6749 recommended method and
+the normal default for confidential clients, including default Okta
+applications. Requires `clientSecret`.
+
+***
+
+### ClientSecretPost
+
+```ts
+ClientSecretPost: "client_secret_post";
+```
+
+Credentials in the request body, for providers configured to require it.
+Requires `clientSecret`.
+
+***
+
+### None
+
+```ts
+None: "none";
+```
+
+No client authentication, for public clients using PKCE or the device
+flow. Cannot be combined with `clientSecret`.

docs/src/js/enumerations/OAuthFlowType.md

@@ -10,6 +10,16 @@ OAuth authentication flow types.
 
 ## Enumeration Members
 
+### AuthorizationCode
+
+```ts
+AuthorizationCode: "authorization_code";
+```
+
+Interactive Authorization Code grant, using PKCE by default.
+
+***
+
 ### AzureManagedIdentity
 
 ```ts
@@ -27,3 +37,13 @@ ClientCredentials: "client_credentials";
 ```
 
 Client Credentials grant (service-to-service / M2M).
+
+***
+
+### DeviceCode
+
+```ts
+DeviceCode: "device_code";
+```
+
+Device Authorization grant for CLI and headless environments.

docs/src/js/functions/blob.md

@@ -0,0 +1,55 @@
+[**@lancedb/lancedb**](../README.md) • **Docs**
+
+***
+
+[@lancedb/lancedb](../globals.md) / blob
+
+# Function: blob()
+
+```ts
+function blob(name, options): Field
+```
+
+Declares a `lance.blob.v2` column.
+
+Query results are descriptors, not payload bytes. Use [Table.fetchBlobs](../classes/Table.md#fetchblobs)
+or [Table.fetchBlobFiles](../classes/Table.md#fetchblobfiles) to read bytes.
+
+## Parameters
+
+* **name**: `string`
+
+* **options**: [`BlobOptions`](../type-aliases/BlobOptions.md) = `{}`
+
+## Returns
+
+`Field`
+
+## Example
+
+```ts
+import { readFile } from "node:fs/promises";
+import { Field, Int64, Schema } from "apache-arrow";
+import { blob, connect } from "@lancedb/lancedb";
+
+const db = await connect("./data");
+const video = await readFile("clip.mp4");
+const table = await db.createTable(
+  "videos",
+  [{ id: 1n, video }],
+  {
+    schema: new Schema([
+      new Field("id", new Int64()),
+      blob("video"),
+    ]),
+  },
+);
+
+const rows = await table.query().select(["id"]).withRowId().toArray();
+const rowIds = rows.map((row) => row._rowid as bigint);
+const bytes = await table.fetchBlobs("video", rowIds);
+
+const [handle] = await table.fetchBlobFiles("video", rowIds);
+const size = handle!.size();
+const header = await handle!.readRange(0n, size < 65536n ? size : 65536n);
+```

docs/src/js/functions/connectCatalog.md

@@ -0,0 +1,32 @@
+[**@lancedb/lancedb**](../README.md) • **Docs**
+
+***
+
+[@lancedb/lancedb](../globals.md) / connectCatalog
+
+# Function: connectCatalog()
+
+```ts
+function connectCatalog(endpoint, options): Promise<Catalog>
+```
+
+Connect to an HTTP(S) catalog endpoint. Catalog requests omit database-selection
+headers; opened database connections inherit authentication and client options.
+
+## Parameters
+
+* **endpoint**: `string`
+
+* **options**: [`CatalogOptions`](../interfaces/CatalogOptions.md) = `{}`
+
+## Returns
+
+`Promise`&lt;[`Catalog`](../classes/Catalog.md)&gt;
+
+## Example
+
+```ts
+const catalog = await connectCatalog("https://my-server.example", { apiKey: "secret" });
+const db = await catalog.createDatabase("analytics", { existOk: true });
+const page = await catalog.listDatabases({ limit: 20 });
+```

docs/src/js/functions/isBlobField.md

@@ -0,0 +1,22 @@
+[**@lancedb/lancedb**](../README.md) • **Docs**
+
+***
+
+[@lancedb/lancedb](../globals.md) / isBlobField
+
+# Function: isBlobField()
+
+```ts
+function isBlobField(field): boolean
+```
+
+Checks for the `lance.blob.v2` extension marker. Does not validate the
+field's storage type.
+
+## Parameters
+
+* **field**: `Field`<`any`>
+
+## Returns
+
+`boolean`

docs/src/js/functions/makeJsonField.md

@@ -0,0 +1,36 @@
+[**@lancedb/lancedb**](../README.md) • **Docs**
+
+***
+
+[@lancedb/lancedb](../globals.md) / makeJsonField
+
+# Function: makeJsonField()
+
+```ts
+function makeJsonField(name, nullable): Field
+```
+
+Create an Arrow field backed by LanceDB's JSON extension type.
+
+## Parameters
+
+* **name**: `string`
+    The field name.
+
+* **nullable**: `boolean` = `true`
+    Whether the field accepts null values.
+
+## Returns
+
+`Field`
+
+## Example
+
+```ts
+import { connect, makeJsonField } from "@lancedb/lancedb";
+import { Schema } from "apache-arrow";
+
+const schema = new Schema([makeJsonField("metadata")]);
+const db = await connect("/path/to/database");
+await db.createTable("items", [{ metadata: '{"source":"api"}' }], { schema });
+```

docs/src/js/globals.md

@@ -11,6 +11,7 @@
 
 ## Enumerations
 
+- [ClientAuthMethod](enumerations/ClientAuthMethod.md)
 - [FullTextQueryType](enumerations/FullTextQueryType.md)
 - [OAuthFlowType](enumerations/OAuthFlowType.md)
 - [Occur](enumerations/Occur.md)
@@ -19,10 +20,12 @@
 ## Classes
 
 - [AutoQuery](classes/AutoQuery.md)
+- [BlobFile](classes/BlobFile.md)
 - [BooleanQuery](classes/BooleanQuery.md)
 - [BoostQuery](classes/BoostQuery.md)
 - [BranchContents](classes/BranchContents.md)
 - [Branches](classes/Branches.md)
+- [Catalog](classes/Catalog.md)
 - [Connection](classes/Connection.md)
 - [HeaderProvider](classes/HeaderProvider.md)
 - [Index](classes/Index.md)
@@ -34,6 +37,7 @@
 - [MultiMatchQuery](classes/MultiMatchQuery.md)
 - [NativeJsHeaderProvider](classes/NativeJsHeaderProvider.md)
 - [OAuthHeaderProvider](classes/OAuthHeaderProvider.md)
+- [OAuthSession](classes/OAuthSession.md)
 - [PermutationBuilder](classes/PermutationBuilder.md)
 - [PhraseQuery](classes/PhraseQuery.md)
 - [Query](classes/Query.md)
@@ -61,6 +65,7 @@
 - [BranchIndexSummary](interfaces/BranchIndexSummary.md)
 - [BranchRowCountSummary](interfaces/BranchRowCountSummary.md)
 - [BucketStats](interfaces/BucketStats.md)
+- [CatalogOptions](interfaces/CatalogOptions.md)
 - [CherryPickError](interfaces/CherryPickError.md)
 - [CherryPickPreview](interfaces/CherryPickPreview.md)
 - [CherryPickResult](interfaces/CherryPickResult.md)
@@ -87,6 +92,10 @@
 - [FtsToken](interfaces/FtsToken.md)
 - [FullTextQuery](interfaces/FullTextQuery.md)
 - [FullTextSearchOptions](interfaces/FullTextSearchOptions.md)
+- [FunctionErrorFragment](interfaces/FunctionErrorFragment.md)
+- [FunctionErrorRecord](interfaces/FunctionErrorRecord.md)
+- [FunctionErrors](interfaces/FunctionErrors.md)
+- [FunctionErrorsOptions](interfaces/FunctionErrorsOptions.md)
 - [GenerationStats](interfaces/GenerationStats.md)
 - [HnswPqOptions](interfaces/HnswPqOptions.md)
 - [HnswSqOptions](interfaces/HnswSqOptions.md)
@@ -99,6 +108,7 @@
 - [JobEventsOptions](interfaces/JobEventsOptions.md)
 - [JobFailureInfo](interfaces/JobFailureInfo.md)
 - [JobInfo](interfaces/JobInfo.md)
+- [ListDatabasesResponse](interfaces/ListDatabasesResponse.md)
 - [ListNamespacesOptions](interfaces/ListNamespacesOptions.md)
 - [ListNamespacesResponse](interfaces/ListNamespacesResponse.md)
 - [ListTablesOptions](interfaces/ListTablesOptions.md)
@@ -121,6 +131,8 @@
 - [RestNamespaceConfig](interfaces/RestNamespaceConfig.md)
 - [RetryConfig](interfaces/RetryConfig.md)
 - [ScannableOptions](interfaces/ScannableOptions.md)
+- [SessionLogout](interfaces/SessionLogout.md)
+- [SessionStatus](interfaces/SessionStatus.md)
 - [ShuffleOptions](interfaces/ShuffleOptions.md)
 - [SplitCalculatedOptions](interfaces/SplitCalculatedOptions.md)
 - [SplitHashOptions](interfaces/SplitHashOptions.md)
@@ -130,12 +142,14 @@
 - [TableStatistics](interfaces/TableStatistics.md)
 - [TimeoutConfig](interfaces/TimeoutConfig.md)
 - [TlsConfig](interfaces/TlsConfig.md)
+- [TokenCacheOptions](interfaces/TokenCacheOptions.md)
 - [TokenResponse](interfaces/TokenResponse.md)
 - [TokenizeOptions](interfaces/TokenizeOptions.md)
 - [UpdateFieldMetadataResult](interfaces/UpdateFieldMetadataResult.md)
 - [UpdateOptions](interfaces/UpdateOptions.md)
 - [UpdateResult](interfaces/UpdateResult.md)
 - [Version](interfaces/Version.md)
+- [ViewDescription](interfaces/ViewDescription.md)
 - [WriteExecutionOptions](interfaces/WriteExecutionOptions.md)
 - [WriteProgress](interfaces/WriteProgress.md)
 
@@ -143,6 +157,7 @@
 
 - [AnalyzePlanDistributedMetrics](type-aliases/AnalyzePlanDistributedMetrics.md)
 - [BaseTokenizer](type-aliases/BaseTokenizer.md)
+- [BlobOptions](type-aliases/BlobOptions.md)
 - [Data](type-aliases/Data.md)
 - [DataLike](type-aliases/DataLike.md)
 - [FieldLike](type-aliases/FieldLike.md)
@@ -158,10 +173,14 @@
 ## Functions
 
 - [RecordBatchIterator](functions/RecordBatchIterator.md)
+- [blob](functions/blob.md)
 - [connect](functions/connect.md)
+- [connectCatalog](functions/connectCatalog.md)
 - [connectNamespace](functions/connectNamespace.md)
 - [instrumentLanceDbMetrics](functions/instrumentLanceDbMetrics.md)
+- [isBlobField](functions/isBlobField.md)
 - [makeArrowTable](functions/makeArrowTable.md)
+- [makeJsonField](functions/makeJsonField.md)
 - [packBits](functions/packBits.md)
 - [permutationBuilder](functions/permutationBuilder.md)
 - [tokenize](functions/tokenize.md)

docs/src/js/interfaces/CatalogOptions.md

@@ -0,0 +1,81 @@
+[**@lancedb/lancedb**](../README.md) • **Docs**
+
+***
+
+[@lancedb/lancedb](../globals.md) / CatalogOptions
+
+# Interface: CatalogOptions
+
+Options shared by a catalog and the database connections it returns.
+
+## Extends
+
+- `Omit`<`NativeCatalogOptions`, `"oauthConfig"`>
+
+## Properties
+
+### apiKey?
+
+```ts
+optional apiKey: string;
+```
+
+#### Inherited from
+
+`Omit.apiKey`
+
+***
+
+### clientConfig?
+
+```ts
+optional clientConfig: ClientConfig;
+```
+
+#### Inherited from
+
+`Omit.clientConfig`
+
+***
+
+### headerProvider?
+
+```ts
+optional headerProvider: HeaderProvider | () => Record<string, string> | Promise<Record<string, string>>;
+```
+
+Called for each request to supply authentication headers.
+
+***
+
+### oauthConfig?
+
+```ts
+optional oauthConfig: OAuthConfig;
+```
+
+***
+
+### readConsistencyInterval?
+
+```ts
+optional readConsistencyInterval: number;
+```
+
+#### Inherited from
+
+`Omit.readConsistencyInterval`
+
+***
+
+### sqlHostOverride?
+
+```ts
+optional sqlHostOverride: string;
+```
+
+SQL service endpoint inherited by database connections.
+
+#### Inherited from
+
+`Omit.sqlHostOverride`

docs/src/js/interfaces/ClientConfig.md

@@ -22,6 +22,10 @@ optional extraHeaders: Record<string, string>;
 optional idDelimiter: string;
 ```
 
+The delimiter joining a namespace path and a name into one object
+identifier. `"$"` is the only supported value, and leaving this unset is
+how to get it; anything else is rejected when the connection is created.
+
 ***
 
 ### retryConfig?

docs/src/js/interfaces/FunctionErrorFragment.md

@@ -0,0 +1,42 @@
+[**@lancedb/lancedb**](../README.md) • **Docs**
+
+***
+
+[@lancedb/lancedb](../globals.md) / FunctionErrorFragment
+
+# Interface: FunctionErrorFragment
+
+A fragment whose per-row error detail was capped: `rowsSkipped` rows
+failed, of which only `rowsRecorded` have a record of their own.
+
+## Properties
+
+### fragmentId
+
+```ts
+fragmentId: number;
+```
+
+***
+
+### jobId
+
+```ts
+jobId: string;
+```
+
+***
+
+### rowsRecorded
+
+```ts
+rowsRecorded: number;
+```
+
+***
+
+### rowsSkipped
+
+```ts
+rowsSkipped: number;
+```

docs/src/js/interfaces/FunctionErrorRecord.md

@@ -0,0 +1,92 @@
+[**@lancedb/lancedb**](../README.md) • **Docs**
+
+***
+
+[@lancedb/lancedb](../globals.md) / FunctionErrorRecord
+
+# Interface: FunctionErrorRecord
+
+One row a Function refresh skipped, as the server recorded it.
+
+## Properties
+
+### column
+
+```ts
+column: string;
+```
+
+***
+
+### createdAtMillis
+
+```ts
+createdAtMillis: number;
+```
+
+***
+
+### errorMessage
+
+```ts
+errorMessage: string;
+```
+
+***
+
+### errorType
+
+```ts
+errorType: string;
+```
+
+***
+
+### fragmentId
+
+```ts
+fragmentId: number;
+```
+
+***
+
+### function
+
+```ts
+function: string;
+```
+
+***
+
+### functionVersion
+
+```ts
+functionVersion: string;
+```
+
+***
+
+### jobId
+
+```ts
+jobId: string;
+```
+
+***
+
+### rowOffset?
+
+```ts
+optional rowOffset: number;
+```
+
+The row's offset within the fragment; absent when the fragment's
+detail was capped.
+
+***
+
+### tableVersion
+
+```ts
+tableVersion: number;
+```

docs/src/js/interfaces/FunctionErrors.md

@@ -0,0 +1,39 @@
+[**@lancedb/lancedb**](../README.md) • **Docs**
+
+***
+
+[@lancedb/lancedb](../globals.md) / FunctionErrors
+
+# Interface: FunctionErrors
+
+A table's per-row Function errors.
+
+## Properties
+
+### fragments
+
+```ts
+fragments: FunctionErrorFragment[];
+```
+
+Fragments whose detail was capped.
+
+***
+
+### records
+
+```ts
+records: FunctionErrorRecord[];
+```
+
+The recorded rows, newest job first.
+
+***
+
+### truncated
+
+```ts
+truncated: boolean;
+```
+
+Whether the listing stopped at its limit.

docs/src/js/interfaces/FunctionErrorsOptions.md

@@ -0,0 +1,39 @@
+[**@lancedb/lancedb**](../README.md) • **Docs**
+
+***
+
+[@lancedb/lancedb](../globals.md) / FunctionErrorsOptions
+
+# Interface: FunctionErrorsOptions
+
+Which per-row Function errors to list; every filter is optional.
+
+## Properties
+
+### column?
+
+```ts
+optional column: string;
+```
+
+Only errors on this column.
+
+***
+
+### jobId?
+
+```ts
+optional jobId: string;
+```
+
+Only errors recorded by this job.
+
+***
+
+### limit?
+
+```ts
+optional limit: number;
+```
+
+At most this many records (server default 10000, cap 100000).

docs/src/js/interfaces/ListDatabasesResponse.md

@@ -0,0 +1,23 @@
+[**@lancedb/lancedb**](../README.md) • **Docs**
+
+***
+
+[@lancedb/lancedb](../globals.md) / ListDatabasesResponse
+
+# Interface: ListDatabasesResponse
+
+## Properties
+
+### databases
+
+```ts
+databases: string[];
+```
+
+***
+
+### pageToken?
+
+```ts
+optional pageToken: string;
+```

docs/src/js/interfaces/MaterializedViewDefinition.md

@@ -6,64 +6,17 @@
 
 # Interface: MaterializedViewDefinition
 
-The query that defines a materialized view.
+The query that defines a materialized view, as stored:
+`SELECT columns FROM [ns.]table [, function(args) AS alias | , UNNEST(column) AS alias]
+[WHERE predicate] [GROUP BY expr, ...] [LIMIT n]`. A Function in `FROM`
+position yields one row per element it returns.
 
 ## Properties
 
-### filter?
+### query
 
 ```ts
-optional filter: string;
+query: string;
 ```
 
-SQL predicate selecting the source rows the view holds.
-
-***
-
-### inputs
-
-```ts
-inputs: string[];
-```
-
-Source columns the projections and filter read.
-
-***
-
-### limit?
-
-```ts
-optional limit: number;
-```
-
-Cap on the number of rows the view holds.
-
-***
-
-### projections
-
-```ts
-projections: [string, string][];
-```
-
-`[output column, SQL expression]` pairs, in view schema order.
-
-***
-
-### sourceNamespace
-
-```ts
-sourceNamespace: string[];
-```
-
-Namespace holding the source table; empty is the root namespace.
-
-***
-
-### sourceTable
-
-```ts
-sourceTable: string;
-```
-
-Name of the source table, in the same database as the view.
+The defining query, in the canonical spelling the server stores.

docs/src/js/interfaces/NativeOAuthConfig.md

@@ -15,6 +15,39 @@ All token acquisition and refresh is handled in the Rust layer.
 
 ## Properties
 
+### audience?
+
+```ts
+optional audience: string;
+```
+
+Optional provider-specific audience for authorization and token requests.
+
+***
+
+### callbackPort?
+
+```ts
+optional callbackPort: number;
+```
+
+Port for the authorization_code loopback callback server.
+
+***
+
+### clientAuthMethod?
+
+```ts
+optional clientAuthMethod: string;
+```
+
+How the client authenticates to the token endpoint: "none",
+"client_secret_basic", or "client_secret_post". Defaults to
+"client_secret_basic" when a client secret is set, and "none" for
+public clients.
+
+***
+
 ### clientId
 
 ```ts
@@ -41,7 +74,8 @@ Client secret (required for client_credentials).
 optional flow: string;
 ```
 
-Authentication flow: "client_credentials" or "azure_managed_identity"
+Authentication flow: "client_credentials", "authorization_code",
+"device_code", or "azure_managed_identity"
 
 ***
 
@@ -66,6 +100,16 @@ Client ID for user-assigned managed identity (azure_managed_identity).
 
 ***
 
+### redirectUri?
+
+```ts
+optional redirectUri: string;
+```
+
+Loopback redirect URI for authorization_code.
+
+***
+
 ### refreshBufferSecs?
 
 ```ts
@@ -78,6 +122,16 @@ the TTL, each request refreshes the token.
 
 ***
 
+### resource?
+
+```ts
+optional resource: string;
+```
+
+Optional resource indicator for authorization and token requests.
+
+***
+
 ### scopes
 
 ```ts
@@ -86,3 +140,24 @@ scopes: string[];
 
 OAuth scopes to request. For Azure managed identity, exactly one scope
 or resource is required. For example: `["api://{app_id}/.default"]`
+
+***
+
+### tokenCache?
+
+```ts
+optional tokenCache: TokenCacheOptions;
+```
+
+Opt in to the persistent token cache so short-lived processes reuse
+one session. Only refresh tokens are persisted.
+
+***
+
+### usePkce?
+
+```ts
+optional usePkce: boolean;
+```
+
+Whether authorization_code uses S256 PKCE (default: true).

docs/src/js/interfaces/OAuthConfig.md

@@ -26,6 +26,18 @@ const config: OAuthConfig = {
 };
 ```
 
+Providers requiring an explicit target can set `resource` and/or `audience`:
+```typescript
+const targeted: OAuthConfig = {
+  issuerUrl: "https://issuer.example.com",
+  clientId: "app-id",
+  clientSecret: "secret",
+  scopes: ["read"],
+  resource: "https://api.example.com",
+  audience: "lancedb-api",
+};
+```
+
 ```typescript
 const config: OAuthConfig = {
   issuerUrl: "https://login.microsoftonline.com/{tenant}/v2.0",
@@ -35,8 +47,57 @@ const config: OAuthConfig = {
 };
 ```
 
+The authorization URL is written to stderr before LanceDB tries to open a
+browser, so it can be copied in headless environments.
+```typescript
+const config: OAuthConfig = {
+  issuerUrl: "https://login.microsoftonline.com/{tenant}/v2.0",
+  clientId: "app-id",
+  scopes: ["openid", "api://lancedb-api/access"],
+  flow: OAuthFlowType.AuthorizationCode,
+};
+```
+
+Device Authorization writes the verification URL and user code to stderr
+before polling begins.
+
 ## Properties
 
+### audience?
+
+```ts
+optional audience: string;
+```
+
+Provider-specific audience, forwarded to authorization and token endpoints,
+including refresh requests. Not supported for Azure managed identity.
+
+***
+
+### callbackPort?
+
+```ts
+optional callbackPort: number;
+```
+
+Port for the AuthorizationCode loopback callback server (default: 8400).
+
+***
+
+### clientAuthMethod?
+
+```ts
+optional clientAuthMethod: ClientAuthMethod;
+```
+
+How the client authenticates to the token endpoint (default: auto).
+With a `clientSecret` the default is `ClientAuthMethod.ClientSecretBasic`,
+which matches the RFC 6749 recommendation and the default configuration
+of Okta confidential applications; without a secret the client is public
+and no client authentication is sent.
+
+***
+
 ### clientId
 
 ```ts
@@ -88,6 +149,16 @@ Client ID for user-assigned managed identity (AzureManagedIdentity).
 
 ***
 
+### redirectUri?
+
+```ts
+optional redirectUri: string;
+```
+
+Loopback redirect URI for AuthorizationCode.
+
+***
+
 ### refreshBufferSecs?
 
 ```ts
@@ -100,6 +171,18 @@ the TTL, each request refreshes the token.
 
 ***
 
+### resource?
+
+```ts
+optional resource: string;
+```
+
+Resource indicator (RFC 8707), forwarded verbatim to authorization and token
+endpoints, including refresh requests. Must be an absolute URI without a
+fragment. Not supported for Azure managed identity.
+
+***
+
 ### scopes
 
 ```ts
@@ -109,3 +192,26 @@ scopes: string[];
 OAuth scopes to request.
 For Azure managed identity, exactly one scope or resource is required.
 For example: `["api://{app_id}/.default"]`
+
+***
+
+### tokenCache?
+
+```ts
+optional tokenCache: TokenCacheOptions;
+```
+
+Opt in to the persistent token cache so short-lived processes reuse one
+session. Only refresh tokens are persisted. Only supported by
+AuthorizationCode and DeviceCode; Azure managed identity is rejected.
+Default: unset (memory only).
+
+***
+
+### usePkce?
+
+```ts
+optional usePkce: boolean;
+```
+
+Protect AuthorizationCode with S256 PKCE (default: true).

docs/src/js/interfaces/OptimizeOptions.md

@@ -26,7 +26,8 @@ const olderThan = new Date();
 olderThan.setDate(olderThan.getDate() - 1));
 tbl.optimize({cleanupOlderThan: olderThan});
 
-// Delete all versions except the current version
+// Delete versions committed before this point. Versions created by the
+// optimize call itself are newer than the cutoff and will be retained.
 tbl.optimize({cleanupOlderThan: new Date()});
 ```
 

docs/src/js/interfaces/SessionLogout.md

@@ -0,0 +1,20 @@
+[**@lancedb/lancedb**](../README.md) • **Docs**
+
+***
+
+[@lancedb/lancedb](../globals.md) / SessionLogout
+
+# Interface: SessionLogout
+
+Result of [OAuthSession.logout](../classes/OAuthSession.md#logout).
+
+## Properties
+
+### removed
+
+```ts
+removed: boolean;
+```
+
+Whether a cached credential was removed. `false` means no matching
+session was cached; logout is idempotent.

docs/src/js/interfaces/SessionStatus.md

@@ -0,0 +1,94 @@
+[**@lancedb/lancedb**](../README.md) • **Docs**
+
+***
+
+[@lancedb/lancedb](../globals.md) / SessionStatus
+
+# Interface: SessionStatus
+
+Safe, non-secret view of a cached OAuth session, returned by
+[OAuthSession.status](../classes/OAuthSession.md#status) and [OAuthSession.login](../classes/OAuthSession.md#login).
+
+## Properties
+
+### audience?
+
+```ts
+optional audience: string;
+```
+
+Provider-specific audience used to obtain the cached session, if configured.
+
+***
+
+### clientId
+
+```ts
+clientId: string;
+```
+
+Client ID of the cached session.
+
+***
+
+### flow
+
+```ts
+flow: string;
+```
+
+Flow that produced the cached session.
+
+***
+
+### issuerUrl
+
+```ts
+issuerUrl: string;
+```
+
+Canonical issuer URL of the cached session.
+
+***
+
+### obtainedAt?
+
+```ts
+optional obtainedAt: number;
+```
+
+When the cached session was obtained, as Unix seconds.
+
+***
+
+### refreshable
+
+```ts
+refreshable: boolean;
+```
+
+Whether a cached session exists that can obtain tokens without
+interactive authentication. Because access tokens are not persisted,
+this is `true` exactly when a refresh token is cached; the next
+connection refreshes with it rather than opening a browser or device
+prompt.
+
+***
+
+### resource?
+
+```ts
+optional resource: string;
+```
+
+Resource indicator used to obtain the cached session, if configured.
+
+***
+
+### scopes
+
+```ts
+scopes: string[];
+```
+
+Canonical (sorted, de-duplicated) scope set of the cached session.

docs/src/js/interfaces/TokenCacheOptions.md

@@ -0,0 +1,41 @@
+[**@lancedb/lancedb**](../README.md) • **Docs**
+
+***
+
+[@lancedb/lancedb](../globals.md) / TokenCacheOptions
+
+# Interface: TokenCacheOptions
+
+Options for the persistent OAuth token cache.
+
+The cache is opt-in: it is only used when set as `tokenCache` on
+[OAuthConfig](OAuthConfig.md). Only refresh tokens are persisted, in a private
+directory with owner-only permissions, so short-lived processes can reuse
+an authenticated session instead of re-prompting on every start.
+
+Multiple identities (issuer, client, scopes, resource, audience, flow, client authentication)
+get separate cache entries. Within one identity the most recent login wins.
+
+## Properties
+
+### cacheDir?
+
+```ts
+optional cacheDir: string;
+```
+
+Directory that holds cached credentials. Defaults to
+`$XDG_CACHE_HOME/lancedb/oauth`, `$HOME/.cache/lancedb/oauth` on Unix,
+or `%LOCALAPPDATA%\\lancedb\\oauth` on Windows. The directory is created
+with owner-only permissions (`0700`) when missing.
+
+***
+
+### lockTimeoutSecs?
+
+```ts
+optional lockTimeoutSecs: number;
+```
+
+How long to wait for the cross-process refresh lock before failing, in
+seconds (default: 30).

docs/src/js/interfaces/ViewDescription.md

@@ -0,0 +1,78 @@
+[**@lancedb/lancedb**](../README.md) • **Docs**
+
+***
+
+[@lancedb/lancedb](../globals.md) / ViewDescription
+
+# Interface: ViewDescription
+
+What a database records about one view.
+
+A view holds no rows: it stores the statement that defines it and the
+schema that statement resolved to, so a reader sees its sources as they
+are at read time.
+
+## Properties
+
+### defaultDatabase
+
+```ts
+defaultDatabase: string;
+```
+
+The database that unqualified table names in [query](ViewDescription.md#query) resolve against.
+
+***
+
+### defaultNamespacePath
+
+```ts
+defaultNamespacePath: string[];
+```
+
+The namespace path those unqualified names resolve against; empty is the
+root namespace.
+
+Recorded with the view because it outlives the session that declared it:
+a reader resolving the query against its own default namespace could read
+a different table than the view was defined over.
+
+***
+
+### name
+
+```ts
+name: string;
+```
+
+The view's name within its namespace.
+
+***
+
+### namespacePath
+
+```ts
+namespacePath: string[];
+```
+
+The namespace holding the view; empty is the root namespace.
+
+***
+
+### query
+
+```ts
+query: string;
+```
+
+The defining query, as the database stores it.
+
+***
+
+### schema
+
+```ts
+schema: Schema<any>;
+```
+
+The schema the defining query resolved to when the view was created.

docs/src/js/type-aliases/BlobOptions.md

@@ -0,0 +1,48 @@
+[**@lancedb/lancedb**](../README.md) • **Docs**
+
+***
+
+[@lancedb/lancedb](../globals.md) / BlobOptions
+
+# Type Alias: BlobOptions
+
+```ts
+type BlobOptions: object;
+```
+
+## Type declaration
+
+### dedicatedSizeThreshold?
+
+```ts
+optional dedicatedSizeThreshold: number;
+```
+
+Max payload bytes stored in a packed sidecar before a dedicated file. Must
+be a positive safe integer.
+
+### inlineSizeThreshold?
+
+```ts
+optional inlineSizeThreshold: number;
+```
+
+Max payload bytes kept inline in the data file. Zero is allowed. Must be a
+safe integer.
+
+### nullable?
+
+```ts
+optional nullable: boolean;
+```
+
+Defaults to true.
+
+### packFileSizeThreshold?
+
+```ts
+optional packFileSizeThreshold: number;
+```
+
+Max bytes in one packed sidecar before starting another. Must be a positive
+safe integer.

docs/src/python/python.md

@@ -28,6 +28,17 @@ is also an [asynchronous API client](#connections-asynchronous).
 
 ::: lancedb.Session
 
+## Catalogs (Synchronous)
+
+Remote catalogs manage databases through a server's root namespace. Opened databases
+are ordinary connections. Dropping a database requires it to be empty.
+
+::: lancedb.connect_catalog
+
+::: lancedb.catalog.Catalog
+
+::: lancedb.catalog.ListDatabasesResponse
+
 ## Remote SQL
 
 Submit SQL against a remote LanceDB database through the connection.
@@ -125,6 +136,10 @@ listing a storage directory.
 
 ::: lancedb.functions.UdfDefinition
 
+::: lancedb.secrets.EnvVarSecret
+
+::: lancedb.secrets.SecretInfo
+
 ::: lancedb.functions.FunctionRegistrationRequest
 
 ::: lancedb.functions.FunctionArtifactRequest
@@ -133,6 +148,8 @@ listing a storage directory.
 
 ::: lancedb.functions.PythonAdapterSpec
 
+::: lancedb.functions.FunctionImage
+
 ::: lancedb.functions.FunctionVersion
 
 ::: lancedb.functions.PythonRuntimeSpec
@@ -153,6 +170,12 @@ listing a storage directory.
 
 ::: lancedb.functions.RefreshColumnResult
 
+::: lancedb.FunctionErrors
+
+::: lancedb.FunctionErrorRecord
+
+::: lancedb.FunctionErrorFragment
+
 ::: lancedb.job.Job
 
 ::: lancedb.job.AsyncJob
@@ -175,6 +198,10 @@ listing a storage directory.
 
 ::: lancedb.materialized_view.MaterializedViewDefinition
 
+## Views
+
+::: lancedb.view.ViewDescription
+
 ## Expressions
 
 Type-safe expression builder for filters and projections. Use these instead
@@ -359,6 +386,10 @@ still work. Queries return descriptors. Call
 
 ## Connections (Asynchronous)
 
+::: lancedb.connect_catalog_async
+
+::: lancedb.catalog.AsyncCatalog
+
 Connections represent a connection to a LanceDb database and
 can be used to create, list, or open tables.
 

java/lancedb-core/pom.xml

@@ -8,7 +8,7 @@
     <parent>
       <groupId>com.lancedb</groupId>
       <artifactId>lancedb-parent</artifactId>
-      <version>0.39.0-beta.6</version>
+      <version>0.40.0-beta.8</version>
       <relativePath>../pom.xml</relativePath>
     </parent>
 

java/pom.xml

@@ -6,7 +6,7 @@
 
     <groupId>com.lancedb</groupId>
     <artifactId>lancedb-parent</artifactId>
-    <version>0.39.0-beta.6</version>
+    <version>0.40.0-beta.8</version>
     <packaging>pom</packaging>
     <name>${project.artifactId}</name>
     <description>LanceDB Java SDK Parent POM</description>
@@ -28,7 +28,7 @@
     <properties>
         <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
         <arrow.version>15.0.0</arrow.version>
-        <lance-core.version>12.0.0-beta.16</lance-core.version>
+        <lance-core.version>13.0.0-beta.8</lance-core.version>
         <spotless.skip>false</spotless.skip>
         <spotless.version>2.30.0</spotless.version>
         <spotless.java.googlejavaformat.version>1.7</spotless.java.googlejavaformat.version>

nodejs/CLAUDE.md

@@ -1 +0,0 @@
-AGENTS.md

nodejs/Cargo.toml

@@ -1,7 +1,7 @@
 [package]
 name = "lancedb-nodejs"
 edition.workspace = true
-version = "0.39.0-beta.6"
+version = "0.40.0-beta.8"
 publish = false
 license.workspace = true
 description.workspace = true
@@ -37,8 +37,9 @@ lzma-sys = { version = "0.1", features = ["static"] }
 log.workspace = true
 
 # Pin to resolve build failures; update periodically for security patches.
-aws-lc-sys = "=0.40.0"
-aws-lc-rs = "=1.16.3"
+# rustls >= 0.23.45 (RUSTSEC-2026-0285) needs aws-lc-rs >= 1.18.
+aws-lc-sys = "=0.45.0"
+aws-lc-rs = "=1.18.1"
 
 [build-dependencies]
 napi-build = "2.3.1"

nodejs/__test__/arrow.test.ts

@@ -20,6 +20,7 @@ import {
   fromTableToBuffer,
   makeArrowTable,
   makeEmptyTable,
+  makeJsonField,
 } from "../lancedb/arrow";
 import {
   EmbeddingFunction,
@@ -28,6 +29,21 @@ import {
 import { EmbeddingFunctionConfig } from "../lancedb/embedding/registry";
 import { sanitizeTable } from "../lancedb/sanitize";
 
+it("creates a nullable JSON field with the Arrow extension metadata", () => {
+  const field = makeJsonField("metadata");
+
+  expect(field.name).toBe("metadata");
+  expect(field.type).toEqual(new arrow15.Utf8());
+  expect(field.nullable).toBe(true);
+  expect(field.metadata).toEqual(
+    new Map([["ARROW:extension:name", "arrow.json"]]),
+  );
+});
+
+it("allows JSON fields to be non-nullable", () => {
+  expect(makeJsonField("metadata", false).nullable).toBe(false);
+});
+
 // biome-ignore lint/suspicious/noExplicitAny: skip
 function sampleRecords(): Array<Record<string, any>> {
   return [

nodejs/__test__/blob.test.ts

@@ -0,0 +1,185 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright The LanceDB Authors
+
+import { Field, Int64, List, Schema, Struct, Utf8 } from "apache-arrow";
+import { makeArrowTable } from "../lancedb/arrow";
+import { BlobFile, blob, coerceBlobValue, isBlobField } from "../lancedb/blob";
+
+describe("blob()", () => {
+  it("marks the field as lance.blob.v2", () => {
+    const field = blob("image", { nullable: false });
+    expect(field.nullable).toBe(false);
+    expect(isBlobField(field)).toBe(true);
+    expect(field.metadata.get("ARROW:extension:name")).toBe("lance.blob.v2");
+  });
+
+  it("writes encoding thresholds as field metadata", () => {
+    const field = blob("video", {
+      inlineSizeThreshold: 1024,
+      dedicatedSizeThreshold: 2 * 1024 * 1024,
+      packFileSizeThreshold: 64 * 1024 * 1024,
+    });
+    expect(
+      field.metadata.get("lance-encoding:blob-inline-size-threshold"),
+    ).toBe("1024");
+    expect(
+      field.metadata.get("lance-encoding:blob-dedicated-size-threshold"),
+    ).toBe(String(2 * 1024 * 1024));
+    expect(
+      field.metadata.get("lance-encoding:blob-pack-file-size-threshold"),
+    ).toBe(String(64 * 1024 * 1024));
+  });
+
+  it("rejects invalid thresholds", () => {
+    expect(() => blob("image", { inlineSizeThreshold: -1 })).toThrow(
+      /inlineSizeThreshold must be non-negative/,
+    );
+    expect(() => blob("image", { dedicatedSizeThreshold: 0 })).toThrow(
+      /dedicatedSizeThreshold must be positive/,
+    );
+    expect(() => blob("image", { packFileSizeThreshold: 1.5 })).toThrow(
+      /packFileSizeThreshold must be a safe integer/,
+    );
+    expect(() =>
+      blob("image", { dedicatedSizeThreshold: Number.MAX_SAFE_INTEGER + 1 }),
+    ).toThrow(/dedicatedSizeThreshold must be a safe integer/);
+  });
+});
+
+describe("coerceBlobValue", () => {
+  it.each([
+    ["Buffer", Buffer.from("x"), { data: Buffer.from("x"), uri: null }],
+    [
+      "Uint8Array",
+      new Uint8Array([120]),
+      { data: new Uint8Array([120]), uri: null },
+    ],
+    ["URI string", "s3://bucket/key", { data: null, uri: "s3://bucket/key" }],
+    [
+      "data struct",
+      { data: Buffer.from("y") },
+      { data: Buffer.from("y"), uri: null },
+    ],
+    [
+      "uri struct",
+      { uri: "s3://bucket/key" },
+      { data: null, uri: "s3://bucket/key" },
+    ],
+    ["null", null, null],
+  ])("accepts %s", (_name, input, expected) => {
+    expect(coerceBlobValue(input)).toEqual(expected);
+  });
+
+  it.each([
+    ["empty URI", "", /uri cannot be empty/],
+    ["object without data or uri", { position: 0 }, /data' or 'uri/],
+    [
+      "Int16Array",
+      new Int16Array([1]),
+      /Blob data must be Buffer or Uint8Array/,
+    ],
+    [
+      "both data and uri",
+      { data: Buffer.from("y"), uri: "s3://bucket/key" },
+      /exactly one of 'data' or 'uri'/,
+    ],
+    [
+      "neither data nor uri",
+      { data: null, uri: null },
+      /exactly one of 'data' or 'uri'/,
+    ],
+  ])("rejects %s", (_name, input, message) => {
+    expect(() => coerceBlobValue(input)).toThrow(message);
+  });
+});
+
+describe("BlobFile", () => {
+  it("rejects constructing BlobFile without a native handle", () => {
+    expect(() => new (BlobFile as unknown as { new (): BlobFile })()).toThrow(
+      /fetchBlobFiles/,
+    );
+  });
+});
+
+describe("makeArrowTable blob columns", () => {
+  it("coerces Buffer input onto a blob field", () => {
+    const schema = new Schema([
+      new Field("id", new Int64(), true),
+      blob("image"),
+    ]);
+    const table = makeArrowTable([{ id: 1n, image: Buffer.from("hello") }], {
+      schema,
+    });
+    expect(isBlobField(table.schema.fields[1])).toBe(true);
+    const image = table.getChild("image")!;
+    expect(image.nullCount).toBe(0);
+    expect(image.getChild("uri")!.get(0)).toBeNull();
+    expect(image.getChild("data")!.nullCount).toBe(0);
+    expect(Buffer.from(image.getChild("data")!.get(0)!).toString()).toBe(
+      "hello",
+    );
+  });
+
+  it("coerces Buffer elements inside a list and keeps null slots", () => {
+    const schema = new Schema([
+      new Field("id", new Int64(), true),
+      new Field("images", new List(blob("image")), true),
+    ]);
+    const table = makeArrowTable(
+      [
+        { id: 1n, images: [Buffer.from("a"), Buffer.from("bb")] },
+        { id: 2n, images: null },
+        { id: 3n, images: [Buffer.from("c"), null] },
+        { id: 4n, images: [] },
+      ],
+      { schema },
+    );
+    const images = table.getChild("images")!;
+    expect(images.nullCount).toBe(1);
+    const rows = images.toArray();
+    expect(rows[1]).toBeNull();
+    expect(Array.from(rows[3] as Iterable<unknown>)).toHaveLength(0);
+    const first = Array.from(rows[0] as Iterable<{ data: Uint8Array | null }>);
+    expect(Buffer.from(first[0].data!).toString()).toBe("a");
+    expect(Buffer.from(first[1].data!).toString()).toBe("bb");
+    const third = Array.from(
+      rows[2] as Iterable<{ data: Uint8Array | null } | null>,
+    );
+    expect(Buffer.from(third[0]!.data!).toString()).toBe("c");
+    expect(third[1]).toBeNull();
+  });
+
+  it("coerces Buffer fields inside list structs", () => {
+    const schema = new Schema([
+      new Field("id", new Int64(), true),
+      new Field(
+        "items",
+        new List(
+          new Field(
+            "item",
+            new Struct([new Field("name", new Utf8(), true), blob("image")]),
+            true,
+          ),
+        ),
+        true,
+      ),
+    ]);
+    const table = makeArrowTable(
+      [
+        {
+          id: 1n,
+          items: [{ name: "one", image: Buffer.from("alpha") }],
+        },
+      ],
+      { schema },
+    );
+    const items = Array.from(
+      table.getChild("items")!.toArray()[0] as Iterable<{
+        name: string;
+        image: { data: Uint8Array | null };
+      }>,
+    );
+    expect(items[0].name).toBe("one");
+    expect(Buffer.from(items[0].image.data!).toString()).toBe("alpha");
+  });
+});

nodejs/__test__/catalog.test.ts

@@ -0,0 +1,142 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright The LanceDB Authors
+
+import * as http from "http";
+import { Catalog, connectCatalog } from "../lancedb";
+
+type RecordedRequest = {
+  url: string;
+  headers: http.IncomingHttpHeaders;
+  body: Record<string, unknown>;
+};
+
+async function withCatalog(
+  responses: [number, unknown][],
+  callback: (catalog: Catalog, requests: RecordedRequest[]) => Promise<void>,
+) {
+  const requests: RecordedRequest[] = [];
+  const server = http.createServer(async (req, res) => {
+    const chunks: Buffer[] = [];
+    for await (const chunk of req) chunks.push(Buffer.from(chunk));
+    const body = Buffer.concat(chunks).toString();
+    requests.push({
+      url: req.url ?? "",
+      headers: req.headers,
+      body: body ? JSON.parse(body) : {},
+    });
+    const [status, response] = responses.shift() ?? [
+      500,
+      { error: "Unexpected request" },
+    ];
+    res.writeHead(status, { "content-type": "application/json" });
+    res.end(status === 204 ? undefined : JSON.stringify(response));
+  });
+  await new Promise<void>((resolve) => server.listen(0, "127.0.0.1", resolve));
+  const address = server.address();
+  if (!address || typeof address === "string")
+    throw new Error("Missing server address");
+  try {
+    const catalog = await connectCatalog(`http://127.0.0.1:${address.port}`, {
+      apiKey: "secret",
+      sqlHostOverride: "grpc+tls://sql.example.com:10026",
+      clientConfig: {
+        extraHeaders: {
+          "X-LanceDB-Database": "wrong-static",
+          "X-LanceDB-Database-Prefix": "wrong",
+        },
+      },
+      headerProvider: () => ({
+        "X-LanceDB-Database": "wrong-dynamic",
+        "X-LanceDB-Database-Prefix": "wrong",
+        authorization: "Bearer refreshed",
+      }),
+    });
+    await callback(catalog, requests);
+    expect(responses).toHaveLength(0);
+  } finally {
+    server.closeAllConnections();
+    await new Promise<void>((resolve) => server.close(() => resolve()));
+  }
+}
+
+describe("remote catalog", () => {
+  it("uses root namespace routes and preserves independent database scope", async () => {
+    await withCatalog(
+      [
+        [204, null],
+        [200, { tables: [] }],
+        [200, {}],
+        [200, { tables: [] }],
+        [200, { tables: [] }],
+        // biome-ignore lint/style/useNamingConvention: server wire format
+        [200, { namespaces: ["team/search"], page_token: "next" }],
+        [204, null],
+      ],
+      async (catalog, requests) => {
+        const first = await catalog.createDatabase("team/search", {
+          existOk: true,
+        });
+        expect(await first.tableNames()).toEqual([]);
+        const second = await catalog.connectDatabase("other");
+        expect(await second.tableNames()).toEqual([]);
+        expect(await first.tableNames()).toEqual([]);
+        expect(
+          await catalog.listDatabases({ limit: 1, pageToken: "a/b" }),
+        ).toEqual({ databases: ["team/search"], pageToken: "next" });
+        await catalog.dropDatabase("team/search", { ignoreMissing: true });
+        expect(requests[0].url).toBe("/v1/namespace/team%2Fsearch/create");
+        expect(requests[0].body).toEqual({ mode: "ExistOk" });
+        expect(requests[5].url).toBe(
+          "/v1/namespace/$/list?limit=1&page_token=a%2Fb",
+        );
+        expect(requests[6].body).toEqual({
+          mode: "Skip",
+          behavior: "Restrict",
+        });
+        for (const [i, request] of requests.entries()) {
+          expect(request.headers["x-lancedb-database"]).toBe(
+            i === 1 || i === 4 ? "team/search" : i === 3 ? "other" : undefined,
+          );
+          expect(request.headers["x-lancedb-database-prefix"]).toBeUndefined();
+          expect(request.headers.authorization).toBe("Bearer refreshed");
+        }
+      },
+    );
+  });
+
+  it("propagates lifecycle errors and sends restricted drops", async () => {
+    await withCatalog(
+      [
+        [404, {}],
+        [409, {}],
+        [400, {}],
+        [404, {}],
+      ],
+      async (catalog, requests) => {
+        await expect(catalog.connectDatabase("missing")).rejects.toThrow(
+          "missing",
+        );
+        await expect(catalog.createDatabase("exists")).rejects.toThrow(
+          "exists",
+        );
+        await expect(catalog.dropDatabase("full")).rejects.toThrow();
+        await catalog.dropDatabase("missing", { ignoreMissing: true });
+        expect(requests[2].body).toEqual({
+          mode: "Fail",
+          behavior: "Restrict",
+        });
+      },
+    );
+  });
+
+  it("validates endpoints and pagination", async () => {
+    await expect(connectCatalog("/tmp/catalog")).rejects.toThrow();
+    const catalog = await connectCatalog("http://127.0.0.1:1");
+    for (const limit of [0, -1, 1.5, 2147483648]) {
+      await expect(catalog.listDatabases({ limit })).rejects.toThrow("limit");
+    }
+    await expect(catalog.connectDatabase("a$b")).rejects.toThrow(
+      "Invalid database name",
+    );
+  });
+});

nodejs/__test__/fixtures/oauth_browser.cmd

@@ -0,0 +1,3 @@
+@rem SPDX-License-Identifier: Apache-2.0
+@rem SPDX-FileCopyrightText: Copyright The LanceDB Authors
+@exit /b 0

nodejs/__test__/materialized_view.test.ts

@@ -28,6 +28,39 @@ describe("materialized views", () => {
   });
   afterEach(() => tmpDir.removeCallback());
 
+  it("reads stored queries and legacy layouts", () => {
+    const read = (stored: string) =>
+      definitionFromMetadata(new Map([[DEFINITION_META_KEY, stored]]), "v");
+    const query =
+      "SELECT id, c.chunk FROM ns.docs, UNNEST(chunks) AS c WHERE id > 1";
+    expect(read(`{"format":1,"query":${JSON.stringify(query)}}`).query).toBe(
+      query,
+    );
+
+    // The structured layout written before the format number reads as the
+    // query it described, under either of its kind tags.
+    expect(
+      read(
+        '{"kind":"namespaced_select","source_table":"people","source_namespace":["ns"],' +
+          '"projections":[{"output":"name","expression":"`name`"},' +
+          '{"output":"Shout","expression":"upper(name)"}],"filter":"age >= 18","limit":42}',
+      ).query,
+    ).toBe(
+      "SELECT `name`, upper(name) AS `Shout` FROM ns.people WHERE age >= 18 LIMIT 42",
+    );
+    expect(read('{"kind":"select","source_table":"people"}').query).toBe(
+      "SELECT * FROM people",
+    );
+
+    // A newer writer's layout is reported, never guessed at.
+    for (const newer of [
+      `{"format":3,"query":${JSON.stringify(query)}}`,
+      '{"kind":"select_v3","source_table":"people"}',
+    ]) {
+      expect(() => read(newer)).toThrow(/cannot refresh/);
+    }
+  });
+
   it("rejects a stored limit a number cannot carry", () => {
     const big = new Map([
       [
@@ -38,36 +71,6 @@ describe("materialized views", () => {
     expect(() => definitionFromMetadata(big, "v")).toThrow(
       /too large to represent exactly/,
     );
-
-    const safe = new Map([
-      [
-        DEFINITION_META_KEY,
-        '{"kind":"select","source_table":"people","limit":42}',
-      ],
-    ]);
-    expect(definitionFromMetadata(safe, "v").limit).toBe(42);
-  });
-
-  it("reads the namespaced select kind and refuses unknown kinds", () => {
-    // "namespaced_select" is the namespaced form of "select": same shape, a
-    // separate kind so readers that predate it refuse instead of resolving
-    // the source at the root.
-    const namespaced = new Map([
-      [
-        DEFINITION_META_KEY,
-        '{"kind":"namespaced_select","source_table":"people","source_namespace":["ns"]}',
-      ],
-    ]);
-    const definition = definitionFromMetadata(namespaced, "v");
-    expect(definition.sourceTable).toBe("people");
-    expect(definition.sourceNamespace).toEqual(["ns"]);
-
-    const unknown = new Map([
-      [DEFINITION_META_KEY, '{"kind":"select_v3","source_table":"people"}'],
-    ]);
-    expect(() => definitionFromMetadata(unknown, "v")).toThrow(
-      /cannot refresh/,
-    );
   });
 
   it("creates, refreshes and queries a view", async () => {
@@ -76,11 +79,7 @@ describe("materialized views", () => {
       where: "age >= 18",
     });
     expect(view.name).toBe("adults");
-    expect(await view.table().countRows()).toBe(0);
-
-    const result = await view.refresh();
-    expect(result.mode).toBe("rebuild");
-    expect(Number(result.rowsWritten)).toBe(2);
+    expect(await view.table().countRows()).toBe(2);
 
     const rows = await view.table().query().toArray();
     expect(rows.map((r) => r.shout).sort()).toEqual(["ADA", "GRACE"]);
@@ -92,17 +91,15 @@ describe("materialized views", () => {
     });
     const view = await db.openMaterializedView("adults");
     const definition = await view.definition();
-    expect(definition.sourceTable).toBe("people");
-    expect(definition.filter).toBe("age >= 18");
-    expect(definition.projections).toEqual([
-      ["name", "`name`"],
-      ["age", "`age`"],
-    ]);
-    expect(definition.inputs).toEqual(["age", "name"]);
+    expect(definition.query).toBe(
+      "SELECT name, age FROM people WHERE age >= 18",
+    );
   });
 
   it("refreshes incrementally after an append", async () => {
-    const view = await db.createMaterializedView("copy", "people");
+    const view = await db.createMaterializedView("copy", "people", {
+      withNoData: true,
+    });
     await view.refresh();
 
     const people = await db.openTable("people");
@@ -123,6 +120,21 @@ describe("materialized views", () => {
     await expect(db.openMaterializedView("people")).rejects.toThrow(
       "not a materialized view",
     );
+    await expect(db.dropMaterializedView("people")).rejects.toThrow(
+      "not a materialized view",
+    );
+
+    await db.dropMaterializedView("adults");
+    expect(await db.listMaterializedViews()).toEqual([]);
+  });
+
+  it("returns a job when dropping a view asynchronously", async () => {
+    await db.createMaterializedView("adults", "people");
+
+    const job = await db.dropMaterializedViewAsync("adults");
+    expect(job.id).toBeNull();
+    await job.wait();
+    expect(await db.listMaterializedViews()).toEqual([]);
   });
 
   it("rejects an invalid expression at create time", async () => {
@@ -155,6 +167,7 @@ describe("materialized views", () => {
     });
     const view = await db.createMaterializedView("quoted", "odd_names", {
       select: ["order item"],
+      withNoData: true,
     });
     const result = await view.refresh();
     expect(Number(result.rowsWritten)).toBe(1);

nodejs/__test__/oauth.test.ts

@@ -0,0 +1,245 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright The LanceDB Authors
+
+import * as fs from "fs";
+import * as http from "http";
+import { execFileSync } from "node:child_process";
+import * as os from "os";
+import * as path from "path";
+import { OAuthConfig, OAuthFlowType, OAuthSession } from "../lancedb/oauth";
+
+function tempCacheDir(): string {
+  return fs.mkdtempSync(path.join(os.tmpdir(), "lancedb-oauth-cache-"));
+}
+
+function deviceConfig(issuerUrl: string, cacheDir: string): OAuthConfig {
+  return {
+    issuerUrl,
+    clientId: "client-id",
+    scopes: ["openid"],
+    flow: OAuthFlowType.DeviceCode,
+    tokenCache: { cacheDir },
+  };
+}
+
+describe("OAuthSession", () => {
+  beforeAll(() => {
+    // Child processes inherit the real environment, just as Rust reads it.
+    // Fail before login if the browser override only exists in Jest's sandbox.
+    const browser = execFileSync(
+      process.execPath,
+      ["-p", "process.env.LANCEDB_OAUTH_BROWSER ?? ''"],
+      { encoding: "utf8" },
+    ).trim();
+    expect(browser).not.toBe("");
+    expect(browser).toBe(process.env.LANCEDB_OAUTH_BROWSER);
+  });
+
+  it("reports an absent session and logout is idempotent", async () => {
+    const cacheDir = tempCacheDir();
+    const session = new OAuthSession(
+      deviceConfig("https://issuer.example.com", cacheDir),
+    );
+
+    const status = await session.status();
+    expect(status.refreshable).toBe(false);
+    expect(status.issuerUrl).toBe("https://issuer.example.com");
+    expect(status.clientId).toBe("client-id");
+    expect(status.scopes).toEqual(["openid"]);
+    expect(status.flow).toBe("device_code");
+    expect(status.obtainedAt).toBeUndefined();
+
+    const logout = await session.logout();
+    expect(logout.removed).toBe(false);
+  });
+
+  it("requires token cache options", () => {
+    const config: OAuthConfig = {
+      issuerUrl: "https://issuer.example.com",
+      clientId: "client-id",
+      scopes: ["openid"],
+      flow: OAuthFlowType.DeviceCode,
+    };
+    expect(() => new OAuthSession(config)).toThrow(/token/);
+  });
+
+  it("rejects azure managed identity persistence", () => {
+    const config: OAuthConfig = {
+      issuerUrl: "https://login.microsoftonline.com/tenant/v2.0",
+      clientId: "app-id",
+      scopes: ["api://app/.default"],
+      flow: OAuthFlowType.AzureManagedIdentity,
+      tokenCache: { cacheDir: tempCacheDir() },
+    };
+    expect(() => new OAuthSession(config)).toThrow(/AzureManagedIdentity/);
+  });
+
+  it.each([
+    {},
+    {
+      resource: "https://api.example.com/a?x=1&y=two",
+      audience: "audience + & / ü",
+    },
+  ])(
+    "logs in via device flow with target %j, caches, and logs out",
+    async (target) => {
+      const server = new MockIdp();
+      await server.start();
+      try {
+        const cacheDir = tempCacheDir();
+        const issuerUrl = server.issuerUrl();
+
+        const config = { ...deviceConfig(issuerUrl, cacheDir), ...target };
+        const session = new OAuthSession(config);
+        const status = await session.login();
+        expect(status.refreshable).toBe(true);
+        expect(status.resource).toBe(config.resource);
+        expect(status.audience).toBe(config.audience);
+        expect(status.obtainedAt).toBeGreaterThan(0);
+        expect(server.state.deviceAuthorizations).toBe(1);
+
+        // An independent session (a fresh "process") sees the cached login.
+        const other = new OAuthSession(config);
+        const cached = await other.status();
+        expect(cached.refreshable).toBe(true);
+
+        const logout = await other.logout();
+        expect(logout.removed).toBe(true);
+        const again = await session.logout();
+        expect(again.removed).toBe(false);
+        expect((await session.status()).refreshable).toBe(false);
+
+        // Only the initial login used the interactive device flow.
+        expect(server.state.deviceAuthorizations).toBe(1);
+        expect(server.state.refreshGrants).toBe(0);
+        expect(server.requests).toHaveLength(2);
+        for (const params of server.requests) {
+          expect(params.getAll("resource")).toEqual(
+            config.resource === undefined ? [] : [config.resource],
+          );
+          expect(params.getAll("audience")).toEqual(
+            config.audience === undefined ? [] : [config.audience],
+          );
+        }
+      } finally {
+        server.close();
+      }
+    },
+    15000,
+  );
+});
+
+/** Mock IdP with discovery, device authorization, and rotating refresh. */
+class MockIdp {
+  readonly requests: URLSearchParams[] = [];
+  readonly state = {
+    deviceAuthorizations: 0,
+    refreshGrants: 0,
+    accessTokensIssued: 0,
+    currentRefresh: null as string | null,
+  };
+  private server?: http.Server;
+  private port = 0;
+
+  issuerUrl(): string {
+    return `http://127.0.0.1:${this.port}`;
+  }
+
+  async start(): Promise<void> {
+    const server = http.createServer((req, res) => {
+      const chunks: Buffer[] = [];
+      req.on("data", (chunk) => chunks.push(chunk));
+      req.on("end", () => {
+        const body = Buffer.concat(chunks).toString();
+        const params = new URLSearchParams(body);
+        this.handle(req.url ?? "", params, res);
+      });
+    });
+    await new Promise<void>((resolve) => {
+      server.listen(0, "127.0.0.1", () => resolve());
+    });
+    const address = server.address();
+    if (address && typeof address === "object") {
+      this.port = address.port;
+    }
+    this.server = server;
+  }
+
+  private handle(
+    url: string,
+    params: URLSearchParams,
+    res: http.ServerResponse,
+  ): void {
+    const respond = (status: number, payload: unknown): void => {
+      const body = JSON.stringify(payload);
+      res.writeHead(status, {
+        "Content-Type": "application/json",
+        "Content-Length": Buffer.byteLength(body),
+      });
+      res.end(body);
+    };
+
+    if (url === "/.well-known/openid-configuration") {
+      respond(200, {
+        // biome-ignore lint/style/useNamingConvention: OAuth wire format
+        token_endpoint: `${this.issuerUrl()}/token`,
+        // biome-ignore lint/style/useNamingConvention: OAuth wire format
+        device_authorization_endpoint: `${this.issuerUrl()}/device`,
+      });
+      return;
+    }
+
+    if (url === "/device" || url === "/token") {
+      this.requests.push(params);
+    }
+
+    if (url === "/device") {
+      this.state.deviceAuthorizations += 1;
+      respond(200, {
+        // biome-ignore lint/style/useNamingConvention: OAuth wire format
+        device_code: "device-code",
+        // biome-ignore lint/style/useNamingConvention: OAuth wire format
+        user_code: "ABCD-EFGH",
+        // biome-ignore lint/style/useNamingConvention: OAuth wire format
+        verification_uri: `${this.issuerUrl()}/verify`,
+        // biome-ignore lint/style/useNamingConvention: OAuth wire format
+        expires_in: 60,
+        interval: 1,
+      });
+      return;
+    }
+
+    if (url === "/token") {
+      const grantType = params.get("grant_type") ?? "";
+      if (grantType === "refresh_token") {
+        this.state.refreshGrants += 1;
+        if (params.get("refresh_token") !== this.state.currentRefresh) {
+          respond(400, { error: "invalid_grant" });
+          return;
+        }
+      } else if (!grantType.includes("device_code")) {
+        respond(400, { error: "unsupported_grant_type" });
+        return;
+      }
+      this.state.accessTokensIssued += 1;
+      const number = this.state.accessTokensIssued;
+      const refresh = `refresh-${number}`;
+      this.state.currentRefresh = refresh;
+      respond(200, {
+        // biome-ignore lint/style/useNamingConvention: OAuth wire format
+        access_token: `access-${number}`,
+        // biome-ignore lint/style/useNamingConvention: OAuth wire format
+        refresh_token: refresh,
+        // biome-ignore lint/style/useNamingConvention: OAuth wire format
+        expires_in: 3600,
+      });
+      return;
+    }
+
+    respond(404, {});
+  }
+
+  close(): void {
+    this.server?.close();
+  }
+}

nodejs/__test__/remote.test.ts

@@ -5,9 +5,12 @@ import * as http from "http";
 import { RequestListener } from "http";
 import packageJson = require("../package.json");
 import {
+  ClientAuthMethod,
   ClientConfig,
   Connection,
   ConnectionOptions,
+  OAuthConfig,
+  OAuthFlowType,
   TlsConfig,
   connect,
 } from "../lancedb";
@@ -82,21 +85,78 @@ async function withMockDatabase(
 }
 
 describe("remote connection", () => {
-  it("refuses materialized views before issuing any request", async () => {
-    const paths: string[] = [];
+  it("lists materialized views through the namespace route", async () => {
     await withMockDatabase(
       (req, res) => {
-        paths.push(req.url ?? "");
-        res.writeHead(404).end();
+        expect(req.method).toBe("GET");
+        expect(req.url).toBe("/v1/namespace/$/materialized_view/list");
+        res
+          .writeHead(200, { "content-type": "application/json" })
+          .end(JSON.stringify({ views: ["daily_sales"] }));
       },
       async (db) => {
-        await expect(db.openMaterializedView("secret_table")).rejects.toThrow(
-          /only on local databases/,
+        expect(await db.listMaterializedViews()).toEqual(["daily_sales"]);
+      },
+    );
+  });
+
+  it("creates a view and decodes the schema it resolved to", async () => {
+    await withMockDatabase(
+      (req, res) => {
+        expect(req.method).toBe("POST");
+        expect(req.url).toBe("/v1/view/analytics$adults/create");
+        res.writeHead(200, { "content-type": "application/json" }).end(
+          JSON.stringify({
+            name: "adults",
+            namespace: ["analytics"],
+            query: "SELECT name FROM people",
+            // biome-ignore lint/style/useNamingConvention: the wire field is snake_case
+            default_database: "db",
+            // biome-ignore lint/style/useNamingConvention: the wire field is snake_case
+            default_namespace: ["analytics"],
+            schema: {
+              fields: [
+                { name: "name", nullable: true, type: { type: "utf8" } },
+              ],
+            },
+          }),
         );
-        await expect(db.listMaterializedViews()).rejects.toThrow(
-          /only on local databases/,
-        );
-        expect(paths).toEqual([]);
+      },
+      async (db) => {
+        const view = await db.createView("adults", "SELECT name FROM people", [
+          "analytics",
+        ]);
+        expect(view.name).toBe("adults");
+        expect(view.namespacePath).toEqual(["analytics"]);
+        expect(view.query).toBe("SELECT name FROM people");
+        expect(view.defaultDatabase).toBe("db");
+        expect(view.defaultNamespacePath).toEqual(["analytics"]);
+        expect(view.schema.fields.map((f) => f.name)).toEqual(["name"]);
+      },
+    );
+  });
+
+  it("lists and drops views through their own routes", async () => {
+    await withMockDatabase(
+      (req, res) => {
+        expect(req.url).toBe("/v1/namespace/$/view/list");
+        res
+          .writeHead(200, { "content-type": "application/json" })
+          .end(JSON.stringify({ views: ["adults"] }));
+      },
+      async (db) => {
+        expect(await db.listViews()).toEqual(["adults"]);
+      },
+    );
+
+    await withMockDatabase(
+      (req, res) => {
+        expect(req.method).toBe("POST");
+        expect(req.url).toBe("/v1/view/adults/drop");
+        res.writeHead(200, { "content-type": "application/json" }).end("{}");
+      },
+      async (db) => {
+        await db.dropView("adults");
       },
     );
   });
@@ -196,6 +256,66 @@ describe("remote connection", () => {
     );
   });
 
+  it("lists the rows a Function refresh skipped", async () => {
+    const bodies: unknown[] = [];
+    await withMockDatabase(
+      (req, res) => {
+        const path = req.url ?? "";
+        if (path.endsWith("/describe/")) {
+          res.writeHead(200, { "Content-Type": "application/json" }).end(
+            JSON.stringify({
+              name: "docs",
+              version: 1,
+              schema: { fields: [] },
+            }),
+          );
+          return;
+        }
+        if (path === "/v1/table/docs/errors") {
+          let body = "";
+          req.on("data", (chunk) => {
+            body += chunk;
+          });
+          req.on("end", () => {
+            bodies.push(JSON.parse(body));
+            res.writeHead(200, { "Content-Type": "application/json" }).end(
+              `{"records": [{"job_id": "j-7", "fragment_id": 3, "row_offset": 9,
+                "column": "embedding", "function": "embed", "function_version": "2",
+                "table_version": 11, "error_type": "ValueError",
+                "error_message": "bad input 'x'", "created_at_millis": 1700000000000}],
+                "fragments": [{"job_id": "j-7", "fragment_id": 4, "rows_skipped": 500,
+                "rows_recorded": 100}], "truncated": true}`,
+            );
+          });
+          return;
+        }
+        res.writeHead(404).end();
+      },
+      async (db) => {
+        const table = await db.openTable("docs");
+        const errors = await table.functionErrors({
+          jobId: "j-7",
+          column: "embedding",
+          limit: 2,
+        });
+        expect(errors.truncated).toBe(true);
+        expect(errors.records.map((r) => r.errorMessage)).toEqual([
+          "bad input 'x'",
+        ]);
+        expect(errors.records[0].rowOffset).toBe(9);
+        expect(errors.fragments[0].rowsSkipped).toBe(500);
+        await table.functionErrors();
+        await expect(table.functionErrors({ limit: -1 })).rejects.toThrow(
+          "limit must be a non-negative integer",
+        );
+      },
+    );
+    expect(bodies).toEqual([
+      JSON.parse('{"job_id": "j-7", "column": "embedding", "limit": 2}'),
+      {},
+    ]);
+  });
+
   it("surfaces JSON server errors from remote table operations", async () => {
     await withMockDatabase(
       (req, res) => {
@@ -442,6 +562,40 @@ describe("remote connection", () => {
     ]);
   });
 
+  describe("OAuthConfig", () => {
+    it("should expose client auth method values", () => {
+      expect(ClientAuthMethod.None).toBe("none");
+      expect(ClientAuthMethod.ClientSecretBasic).toBe("client_secret_basic");
+      expect(ClientAuthMethod.ClientSecretPost).toBe("client_secret_post");
+    });
+
+    it("should accept a confidential client with basic auth", () => {
+      const config: OAuthConfig = {
+        issuerUrl: "https://issuer.example.com",
+        clientId: "client-id",
+        clientSecret: "secret",
+        scopes: ["openid"],
+        flow: OAuthFlowType.AuthorizationCode,
+        clientAuthMethod: ClientAuthMethod.ClientSecretBasic,
+      };
+
+      expect(config.clientAuthMethod).toBe(ClientAuthMethod.ClientSecretBasic);
+    });
+
+    it("should accept a public PKCE client without auth method or secret", () => {
+      const config: OAuthConfig = {
+        issuerUrl: "https://issuer.example.com",
+        clientId: "client-id",
+        scopes: ["openid"],
+        flow: OAuthFlowType.AuthorizationCode,
+        usePkce: true,
+      };
+
+      expect(config.clientSecret).toBeUndefined();
+      expect(config.clientAuthMethod).toBeUndefined();
+    });
+  });
+
   describe("TlsConfig", () => {
     it("should create TlsConfig with all fields", () => {
       const tlsConfig: TlsConfig = {

nodejs/__test__/table.test.ts

@@ -18,6 +18,7 @@ import {
   Query,
   Table,
   VectorQuery,
+  blob,
   connect,
   tokenize,
 } from "../lancedb";
@@ -52,6 +53,7 @@ import {
   Operator,
   instanceOfFullTextQuery,
 } from "../lancedb/query";
+import { LocalTable } from "../lancedb/table";
 
 describe.each([arrow15, arrow16, arrow17, arrow18])(
   "Given a table",
@@ -2401,6 +2403,276 @@ describe("when dealing with versioning", () => {
   });
 });
 
+describe("when dealing with blob columns", () => {
+  let tmpDir: tmp.DirResult;
+  beforeEach(() => {
+    tmpDir = tmp.dirSync({ unsafeCleanup: true });
+  });
+  afterEach(() => {
+    tmpDir.removeCallback();
+  });
+
+  it("discovers blob columns", async () => {
+    const { table } = await openBlobTable();
+    expect(await table.blobColumns()).toEqual(["image"]);
+  });
+
+  it("preserves order, duplicates, and nulls", async () => {
+    const { table, rowIds } = await openBlobTable();
+    const [alphaId, betaId, nullId] = rowIds;
+    const bytes = await table.fetchBlobs("image", [
+      betaId,
+      alphaId,
+      betaId,
+      nullId,
+    ]);
+    expect(bytes.map((b) => (b == null ? null : b.toString()))).toEqual([
+      "beta",
+      "alpha",
+      "beta",
+      null,
+    ]);
+    const files = await table.fetchBlobFiles("image", [
+      betaId,
+      nullId,
+      alphaId,
+    ]);
+    expect(files.map((f) => f == null)).toEqual([false, true, false]);
+  });
+
+  it("reads full blob contents", async () => {
+    const { table, rowIds, alpha, beta } = await openBlobTable();
+    const bytes = await table.fetchBlobs("image", rowIds);
+    expect(bytes[0]!.equals(alpha)).toBe(true);
+    expect(bytes[1]!.equals(beta)).toBe(true);
+    const files = await table.fetchBlobFiles("image", rowIds);
+    expect(files[0]!.size()).toBe(BigInt(alpha.length));
+    expect(Buffer.from(await files[0]!.read()).toString()).toBe("alpha");
+    expect(Buffer.from(await files[1]!.read()).toString()).toBe("beta");
+  });
+
+  it("reads a half-open range", async () => {
+    const { table, rowIds } = await openBlobTable();
+    const files = await table.fetchBlobFiles("image", rowIds);
+    expect(Buffer.from(await files[0]!.readRange(0n, 2n)).toString()).toBe(
+      "al",
+    );
+  });
+
+  it("readRange does not move the cursor", async () => {
+    const { table, rowIds, alpha } = await openBlobTable();
+    const [handle] = await table.fetchBlobFiles("image", rowIds);
+    expect((await handle!.readRange(1n, 3n)).toString()).toBe("lp");
+    expect(await handle!.read()).toEqual(alpha);
+    expect(await handle!.read()).toEqual(Buffer.alloc(0));
+  });
+
+  it("fails when readRange end is past the blob size", async () => {
+    const { table, rowIds, alpha } = await openBlobTable();
+    const files = await table.fetchBlobFiles("image", rowIds);
+    await expect(
+      files[0]!.readRange(0n, BigInt(alpha.length + 1)),
+    ).rejects.toThrow(/exceeds blob size/);
+  });
+
+  it("rejects fetchBlobs on a non-blob column", async () => {
+    const { table, rowIds } = await openBlobTable();
+    await expect(table.fetchBlobs("id", rowIds)).rejects.toThrow(/blob/i);
+  });
+
+  it("discovers and fetches nested blob columns", async () => {
+    const db = await connect(tmpDir.name);
+    const schema = new Schema([
+      new Field("id", new Int64(), true),
+      new Field("info", new Struct([blob("image")]), true),
+    ]);
+    const payload = Buffer.from("nested");
+    const table = await db.createTable(
+      "nested_blobs",
+      [{ id: 1n, info: { image: payload } }],
+      { schema },
+    );
+    expect(await table.blobColumns()).toEqual(["info.image"]);
+    const rows = await table.query().withRowId().toArray();
+    const bytes = await table.fetchBlobs("info.image", [
+      rows[0]._rowid as bigint,
+    ]);
+    expect(bytes[0]!.equals(payload)).toBe(true);
+  });
+
+  it("creates and adds list blob columns", async () => {
+    const db = await connect(tmpDir.name);
+    const schema = new Schema([
+      new Field("id", new Int64(), true),
+      new Field("images", new List(blob("image")), true),
+    ]);
+    const alpha = Buffer.from("alpha");
+    const beta = Buffer.from("beta");
+    const gamma = Buffer.from("gamma");
+    const table = await db.createTable(
+      "list_blobs",
+      [{ id: 1n, images: [alpha, beta] }],
+      { schema },
+    );
+    await table.add([
+      { id: 2n, images: null },
+      { id: 3n, images: [gamma, null] },
+      { id: 4n, images: [] },
+    ]);
+    expect(await table.blobColumns()).toEqual(["images.image"]);
+    const rows = await table.query().toArray();
+    const byId = new Map(rows.map((row) => [Number(row.id), row]));
+    expect(descriptorSizes(byId.get(1)!.images)).toEqual([
+      alpha.length,
+      beta.length,
+    ]);
+    expect(byId.get(2)!.images).toBeNull();
+    expect(descriptorSizes(byId.get(3)!.images)).toEqual([gamma.length, null]);
+    expect(Array.from(byId.get(4)!.images as Iterable<unknown>)).toHaveLength(
+      0,
+    );
+  });
+
+  it("creates and adds list struct blob columns", async () => {
+    const db = await connect(tmpDir.name);
+    const schema = new Schema([
+      new Field("id", new Int64(), true),
+      new Field(
+        "items",
+        new List(
+          new Field(
+            "item",
+            new Struct([new Field("name", new Utf8(), true), blob("image")]),
+            true,
+          ),
+        ),
+        true,
+      ),
+    ]);
+    const alpha = Buffer.from("nested-alpha");
+    const beta = Buffer.from("nested-beta");
+    const table = await db.createTable(
+      "list_struct_blobs",
+      [{ id: 1n, items: [{ name: "one", image: alpha }] }],
+      { schema },
+    );
+    await table.add([
+      {
+        id: 2n,
+        items: [
+          { name: "two", image: beta },
+          { name: "three", image: null },
+        ],
+      },
+    ]);
+    const rows = await table.query().toArray();
+    const byId = new Map(rows.map((row) => [Number(row.id), row]));
+    expect(
+      descriptorSizes(
+        Array.from(byId.get(1)!.items as Iterable<{ image: unknown }>).map(
+          (item) => item.image,
+        ),
+      ),
+    ).toEqual([alpha.length]);
+    expect(
+      descriptorSizes(
+        Array.from(byId.get(2)!.items as Iterable<{ image: unknown }>).map(
+          (item) => item.image,
+        ),
+      ),
+    ).toEqual([beta.length, null]);
+  });
+
+  it("rejects blob fields inside a fixed-size list", async () => {
+    const db = await connect(tmpDir.name);
+    const schema = new Schema([
+      new Field("id", new Int64(), true),
+      new Field("frames", new FixedSizeList(2, blob("frame")), true),
+    ]);
+    await expect(
+      db.createTable(
+        "fsl_blobs",
+        [{ id: 1n, frames: [Buffer.from("a"), Buffer.from("b")] }],
+        { schema },
+      ),
+    ).rejects.toThrow(
+      "Blob fields inside FixedSizeList are not supported. Use List instead.",
+    );
+  });
+
+  it("rejects blob fields inside a nested fixed-size list", async () => {
+    const db = await connect(tmpDir.name);
+    const schema = new Schema([
+      new Field("id", new Int64(), true),
+      new Field(
+        "clip",
+        new Struct([
+          new Field("frames", new FixedSizeList(2, blob("frame")), true),
+        ]),
+        true,
+      ),
+    ]);
+    await expect(
+      db.createTable(
+        "nested_fsl_blobs",
+        [
+          {
+            id: 1n,
+            clip: { frames: [Buffer.from("a"), Buffer.from("b")] },
+          },
+        ],
+        { schema },
+      ),
+    ).rejects.toThrow(
+      "Blob fields inside FixedSizeList are not supported. Use List instead.",
+    );
+  });
+
+  it("rejects an Arrow table with blob fields inside a fixed-size list", async () => {
+    const db = await connect(tmpDir.name);
+    const schema = new Schema([
+      new Field("id", new Int64(), true),
+      new Field("frames", new FixedSizeList(2, blob("frame")), true),
+    ]);
+    await expect(
+      db.createTable("fsl_blobs_ipc", new ArrowTable(schema)),
+    ).rejects.toThrow(
+      "Blob fields inside FixedSizeList are not supported. Use List instead.",
+    );
+  });
+
+  function descriptorSizes(values: unknown): (number | null)[] {
+    return Array.from(
+      values as Iterable<{ size?: bigint | number } | null>,
+    ).map((value) => (value == null ? null : Number(value.size)));
+  }
+
+  async function openBlobTable() {
+    const db = await connect(tmpDir.name);
+    const schema = new Schema([
+      new Field("id", new Int64(), true),
+      blob("image"),
+    ]);
+    const alpha = Buffer.from("alpha");
+    const beta = Buffer.from("beta");
+    const table = await db.createTable(
+      "blobs",
+      [
+        { id: 1n, image: alpha },
+        { id: 2n, image: beta },
+        { id: 3n, image: null },
+      ],
+      { schema },
+    );
+    const rows = await table.query().withRowId().toArray();
+    const rowIdById = new Map(
+      rows.map((r) => [Number(r.id), r._rowid as bigint]),
+    );
+    const rowIds = [1, 2, 3].map((id) => rowIdById.get(id)!);
+    return { table, rowIds, alpha, beta };
+  }
+});
+
 describe("when dealing with tags", () => {
   let tmpDir: tmp.DirResult;
   beforeEach(() => {
@@ -2494,6 +2766,15 @@ describe("when dealing with tags", () => {
   });
 });
 
+/** Returns a Date strictly later than every instant observed before the call. */
+async function nextMillisecond(): Promise<Date> {
+  const start = Date.now();
+  while (Date.now() <= start) {
+    await new Promise((resolve) => setTimeout(resolve, 1));
+  }
+  return new Date();
+}
+
 describe("when optimizing a dataset", () => {
   let tmpDir: tmp.DirResult;
   let table: Table;
@@ -2516,9 +2797,14 @@ describe("when optimizing a dataset", () => {
   });
 
   it("cleanups old versions", async () => {
-    const stats = await table.optimize({ cleanupOlderThan: new Date() });
+    // Lance stores version timestamps with nanosecond precision while a JS
+    // Date only has millisecond precision. A cutoff captured in the same
+    // millisecond as the last commit would truncate to *before* that commit
+    // and leave it in place, so wait for the clock to tick over first.
+    const cutoff = await nextMillisecond();
+    const stats = await table.optimize({ cleanupOlderThan: cutoff });
     expect(stats.prune.bytesRemoved).toBeGreaterThan(0);
-    expect(stats.prune.oldVersionsRemoved).toBe(3);
+    expect(stats.prune.oldVersionsRemoved).toBe(2);
   });
 
   it("delete unverified", async () => {
@@ -2539,6 +2825,24 @@ describe("when optimizing a dataset", () => {
   });
 });
 
+it("passes cleanupOlderThan to the native binding as an absolute timestamp", async () => {
+  const optimize = jest.fn().mockResolvedValue({
+    compaction: {
+      filesAdded: 0,
+      filesRemoved: 0,
+      fragmentsAdded: 0,
+      fragmentsRemoved: 0,
+    },
+    prune: { bytesRemoved: 0, oldVersionsRemoved: 0 },
+  });
+  const table = new LocalTable({ optimize } as never);
+  const cutoff = new Date("2020-01-02T03:04:05.678Z");
+
+  await table.optimize({ cleanupOlderThan: cutoff, deleteUnverified: true });
+
+  expect(optimize).toHaveBeenCalledWith(cutoff.getTime(), true);
+});
+
 describe.each([arrow15, arrow16, arrow17, arrow18])(
   "when optimizing a dataset",
   // biome-ignore lint/suspicious/noExplicitAny: <explanation>
@@ -4054,6 +4358,14 @@ describe("computed columns", () => {
     expect(rows.map((r) => r.doubled).sort()).toEqual([2, 4]);
   });
 
+  it("records Function errors only on remote tables", async () => {
+    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",
+    );
+  });
+
   it("returns a job handle from refreshColumnAsync", async () => {
     const db = await connect(tmpDir.name);
     const table = await db.createTable("computed_job", [{ x: 1 }, { x: 2 }]);

nodejs/jest.config.js

@@ -1,3 +1,12 @@
+const path = require("node:path");
+
+// Set the real process environment before Jest creates its sandbox and workers.
+// Assigning process.env inside a test does not reach Rust's std::env.
+process.env.LANCEDB_OAUTH_BROWSER =
+  process.platform === "win32"
+    ? path.join(__dirname, "__test__/fixtures/oauth_browser.cmd")
+    : "/usr/bin/true";
+
 /** @type {import('ts-jest').JestConfigWithTsJest} */
 module.exports = {
   preset: "ts-jest",

nodejs/lancedb/arrow.ts

@@ -40,6 +40,7 @@ import {
 } from "apache-arrow";
 import { Buffers } from "apache-arrow/data";
 import { typedArrayToArrowType } from "./arrow_type";
+import { coerceBlobValue, isBlobField } from "./blob";
 import { type EmbeddingFunction } from "./embedding/embedding_function";
 import {
   EmbeddingFunctionConfig,
@@ -71,6 +72,30 @@ export type FieldLike =
       metadata?: Map<string, string>;
     };
 
+/**
+ * Create an Arrow field backed by LanceDB's JSON extension type.
+ *
+ * @param name - The field name.
+ * @param nullable - Whether the field accepts null values.
+ * @example
+ * ```ts
+ * import { connect, makeJsonField } from "@lancedb/lancedb";
+ * import { Schema } from "apache-arrow";
+ *
+ * const schema = new Schema([makeJsonField("metadata")]);
+ * const db = await connect("/path/to/database");
+ * await db.createTable("items", [{ metadata: '{"source":"api"}' }], { schema });
+ * ```
+ */
+export function makeJsonField(name: string, nullable = true): Field {
+  return new Field(
+    name,
+    new Utf8(),
+    nullable,
+    new Map([["ARROW:extension:name", "arrow.json"]]),
+  );
+}
+
 export type DataLike =
   | import("apache-arrow").Data
   | {
@@ -430,12 +455,14 @@ export function makeArrowTable(
       throw new Error("A schema must be provided if data is empty");
     } else {
       schema = new Schema(schema.fields, schemaMetadata);
+      validateBlobSchema(schema);
       return new ArrowTable(schema);
     }
   }
 
   let inferredSchema = inferSchema(data, schema, opt);
   inferredSchema = new Schema(inferredSchema.fields, schemaMetadata);
+  validateBlobSchema(inferredSchema);
 
   const finalColumns: Record<string, Vector> = {};
   for (const field of inferredSchema.fields) {
@@ -445,6 +472,35 @@ export function makeArrowTable(
   return new ArrowTable(inferredSchema, finalColumns);
 }
 
+function validateBlobSchema(schema: Schema): void {
+  for (const field of schema.fields) {
+    validateBlobField(field);
+  }
+}
+
+function validateBlobField(field: Field): void {
+  if (
+    isFixedSizeList(field.type) &&
+    containsBlobField(field.type.children[0])
+  ) {
+    throw new Error(
+      "Blob fields inside FixedSizeList are not supported. Use List instead.",
+    );
+  }
+  for (const child of field.type.children ?? []) {
+    validateBlobField(child);
+  }
+}
+
+function containsBlobField(field: Field): boolean {
+  if (isBlobField(field)) {
+    return true;
+  }
+  return (field.type.children ?? []).some((child: Field) =>
+    containsBlobField(child),
+  );
+}
+
 function isObject(value: unknown): value is Record<string, unknown> {
   return (
     typeof value === "object" &&
@@ -480,6 +536,32 @@ function transposeData(
   path: string[] = [],
 ): Vector {
   const valuesPath = [...path, field.name];
+  if (isBlobField(field) && field.type instanceof Struct) {
+    const blobRows = data.map((datum) =>
+      coerceBlobValue(valueAtPath(datum, valuesPath)),
+    );
+    const childVectors = field.type.children.map((child) => {
+      const values = blobRows.map((row) =>
+        row == null ? null : (row[child.name as "data" | "uri"] ?? null),
+      );
+      return makeVector(values, child.type, undefined, child.nullable);
+    });
+    const nullCount = blobRows.filter((row) => row === null).length;
+    const structData = makeData({
+      type: field.type,
+      length: blobRows.length,
+      nullCount,
+      nullBitmap:
+        nullCount > 0
+          ? arrowUtil.packBools(blobRows.map((row) => row !== null))
+          : undefined,
+      children: childVectors.map((v) => v.data[0]),
+    });
+    return arrowMakeVector(structData);
+  }
+  if (isList(field.type) && containsBlobField(field.type.children[0])) {
+    return transposeListData(data, field, valuesPath);
+  }
   const values = data.map((datum) => valueAtPath(datum, valuesPath));
   if (field.type instanceof Struct) {
     const childFields = field.type.children;
@@ -495,7 +577,7 @@ function transposeData(
         nullCount > 0
           ? arrowUtil.packBools(values.map((value) => value !== null))
           : undefined,
-      children: childVectors as unknown as ArrowData<DataType>[],
+      children: childVectors.map((v) => v.data[0]),
     });
     return arrowMakeVector(structData);
   } else {
@@ -503,6 +585,48 @@ function transposeData(
   }
 }
 
+function transposeListData(
+  data: Record<string, unknown>[],
+  field: Field,
+  valuesPath: string[],
+): Vector {
+  const listType = field.type as List;
+  const childField = listType.children[0];
+  const lists = data.map((datum) => valueAtPath(datum, valuesPath));
+  const flattened: Record<string, unknown>[] = [];
+  const validity: boolean[] = [];
+  const offsets: number[] = [0];
+
+  for (const list of lists) {
+    if (list == null) {
+      validity.push(false);
+      offsets.push(flattened.length);
+      continue;
+    }
+    if (!Array.isArray(list)) {
+      throw new Error(`expected an array for list field '${field.name}'`);
+    }
+    validity.push(true);
+    for (const element of list) {
+      flattened.push({ [childField.name]: element });
+    }
+    offsets.push(flattened.length);
+  }
+
+  const childVector = transposeData(flattened, childField, []);
+  const nullCount = validity.filter((valid) => !valid).length;
+  return arrowMakeVector(
+    makeData({
+      type: listType,
+      length: lists.length,
+      nullCount,
+      nullBitmap: nullCount > 0 ? arrowUtil.packBools(validity) : undefined,
+      valueOffsets: Int32Array.from(offsets),
+      child: childVector.data[0],
+    }),
+  );
+}
+
 /**
  * Create an empty Arrow table with the provided schema
  */
@@ -952,6 +1076,7 @@ export async function fromTableToBuffer(
     schema = sanitizeSchema(schema);
   }
   const tableWithEmbeddings = await applyEmbeddings(table, embeddings, schema);
+  validateBlobSchema(tableWithEmbeddings.schema);
   const writer = RecordBatchFileWriter.writeAll(tableWithEmbeddings);
   return Buffer.from(await writer.toUint8Array());
 }

nodejs/lancedb/blob.ts

@@ -0,0 +1,236 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright The LanceDB Authors
+
+import { Field, LargeBinary, Struct, Utf8 } from "apache-arrow";
+import { BlobFile as NativeBlobFile } from "./native";
+
+const BLOB_V2_EXTENSION_NAME = "lance.blob.v2";
+
+const INLINE_SIZE_THRESHOLD_KEY = "lance-encoding:blob-inline-size-threshold";
+const DEDICATED_SIZE_THRESHOLD_KEY =
+  "lance-encoding:blob-dedicated-size-threshold";
+const PACK_FILE_SIZE_THRESHOLD_KEY =
+  "lance-encoding:blob-pack-file-size-threshold";
+
+export type BlobInput = {
+  data: Buffer | Uint8Array | null;
+  uri: string | null;
+};
+
+export type BlobOptions = {
+  /** Defaults to true. */
+  nullable?: boolean;
+  /**
+   * Max payload bytes kept inline in the data file. Zero is allowed. Must be a
+   * safe integer.
+   */
+  inlineSizeThreshold?: number;
+  /**
+   * Max payload bytes stored in a packed sidecar before a dedicated file. Must
+   * be a positive safe integer.
+   */
+  dedicatedSizeThreshold?: number;
+  /**
+   * Max bytes in one packed sidecar before starting another. Must be a positive
+   * safe integer.
+   */
+  packFileSizeThreshold?: number;
+};
+
+/**
+ * Declares a `lance.blob.v2` column.
+ *
+ * Query results are descriptors, not payload bytes. Use {@link Table.fetchBlobs}
+ * or {@link Table.fetchBlobFiles} to read bytes.
+ *
+ * @example
+ * ```ts
+ * import { readFile } from "node:fs/promises";
+ * import { Field, Int64, Schema } from "apache-arrow";
+ * import { blob, connect } from "@lancedb/lancedb";
+ *
+ * const db = await connect("./data");
+ * const video = await readFile("clip.mp4");
+ * const table = await db.createTable(
+ *   "videos",
+ *   [{ id: 1n, video }],
+ *   {
+ *     schema: new Schema([
+ *       new Field("id", new Int64()),
+ *       blob("video"),
+ *     ]),
+ *   },
+ * );
+ *
+ * const rows = await table.query().select(["id"]).withRowId().toArray();
+ * const rowIds = rows.map((row) => row._rowid as bigint);
+ * const bytes = await table.fetchBlobs("video", rowIds);
+ *
+ * const [handle] = await table.fetchBlobFiles("video", rowIds);
+ * const size = handle!.size();
+ * const header = await handle!.readRange(0n, size < 65536n ? size : 65536n);
+ * ```
+ */
+export function blob(name: string, options: BlobOptions = {}): Field {
+  const metadata = new Map<string, string>([
+    ["ARROW:extension:name", BLOB_V2_EXTENSION_NAME],
+  ]);
+  setThreshold(
+    metadata,
+    INLINE_SIZE_THRESHOLD_KEY,
+    "inlineSizeThreshold",
+    options.inlineSizeThreshold,
+    0,
+  );
+  setThreshold(
+    metadata,
+    DEDICATED_SIZE_THRESHOLD_KEY,
+    "dedicatedSizeThreshold",
+    options.dedicatedSizeThreshold,
+    1,
+  );
+  setThreshold(
+    metadata,
+    PACK_FILE_SIZE_THRESHOLD_KEY,
+    "packFileSizeThreshold",
+    options.packFileSizeThreshold,
+    1,
+  );
+  return new Field(
+    name,
+    new Struct([
+      new Field("data", new LargeBinary(), true),
+      new Field("uri", new Utf8(), true),
+    ]),
+    options.nullable ?? true,
+    metadata,
+  );
+}
+
+/**
+ * Checks for the `lance.blob.v2` extension marker. Does not validate the
+ * field's storage type.
+ */
+export function isBlobField(field: Field): boolean {
+  return field.metadata?.get("ARROW:extension:name") === BLOB_V2_EXTENSION_NAME;
+}
+
+/**
+ * A lazy handle to blob bytes. Create one with {@link Table.fetchBlobFiles}.
+ *
+ * @hideconstructor
+ */
+export class BlobFile {
+  private readonly inner: NativeBlobFile;
+
+  private constructor(inner: NativeBlobFile) {
+    if (!(inner instanceof NativeBlobFile)) {
+      throw new Error("BlobFile handles come from Table.fetchBlobFiles");
+    }
+    this.inner = inner;
+  }
+
+  /** @ignore */
+  static fromNative(inner: NativeBlobFile): BlobFile {
+    return new BlobFile(inner);
+  }
+
+  /** Returns the blob size in bytes. */
+  size(): bigint {
+    return this.inner.size();
+  }
+
+  /**
+   * Reads from the cursor to the end and advances the cursor.
+   *
+   * A second call returns an empty buffer. {@link BlobFile.readRange} does
+   * not move the cursor.
+   */
+  read(): Promise<Buffer> {
+    return this.inner.read();
+  }
+
+  /**
+   * Reads the half-open byte range `[start, end)`.
+   *
+   * Fails when `end` is past the blob size. Does not move the cursor.
+   */
+  readRange(start: bigint, end: bigint): Promise<Buffer> {
+    return this.inner.readRange(start, end);
+  }
+}
+
+export function coerceBlobValue(value: unknown): BlobInput | null {
+  if (value == null) {
+    return null;
+  }
+  if (isBlobBytes(value)) {
+    return { data: value, uri: null };
+  }
+  if (ArrayBuffer.isView(value)) {
+    throw new Error("Blob data must be Buffer or Uint8Array");
+  }
+  if (typeof value === "string") {
+    if (value === "") {
+      throw new Error("Blob uri cannot be empty");
+    }
+    return { data: null, uri: value };
+  }
+  if (typeof value === "object") {
+    const record = value as Record<string, unknown>;
+    if (!("data" in record) && !("uri" in record)) {
+      throw new Error(
+        "Blob struct values must include a 'data' or 'uri' field",
+      );
+    }
+    const uri = record.uri;
+    if (uri === "") {
+      throw new Error("Blob uri cannot be empty");
+    }
+    if (uri != null && typeof uri !== "string") {
+      throw new Error(`Blob uri must be a string or null, got ${typeof uri}`);
+    }
+    const data = record.data;
+    if (data != null && !isBlobBytes(data)) {
+      throw new Error("Blob data must be Buffer, Uint8Array, or null");
+    }
+    const bytes = (data as Buffer | Uint8Array | null | undefined) ?? null;
+    const uriValue = uri ?? null;
+    if ((bytes == null) === (uriValue == null)) {
+      throw new Error(
+        "Blob struct values must set exactly one of 'data' or 'uri'",
+      );
+    }
+    return { data: bytes, uri: uriValue };
+  }
+  throw new Error(
+    "Blob column values must be Buffer, Uint8Array, a URI string, null, or { data?, uri? }",
+  );
+}
+
+function isBlobBytes(value: unknown): value is Buffer | Uint8Array {
+  return Buffer.isBuffer(value) || value instanceof Uint8Array;
+}
+
+function setThreshold(
+  metadata: Map<string, string>,
+  key: string,
+  optionName: string,
+  value: number | undefined,
+  minimum: number,
+): void {
+  if (value === undefined) {
+    return;
+  }
+  if (!Number.isSafeInteger(value)) {
+    throw new Error(`${optionName} must be a safe integer`);
+  }
+  if (value < minimum) {
+    throw new Error(
+      minimum <= 0
+        ? `${optionName} must be non-negative`
+        : `${optionName} must be positive`,
+    );
+  }
+  metadata.set(key, String(value));
+}

nodejs/lancedb/catalog.ts

@@ -0,0 +1,103 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright The LanceDB Authors
+
+import { Connection, LocalConnection } from "./connection";
+import { HeaderProvider } from "./header";
+import {
+  JsHeaderProvider,
+  ListDatabasesResponse,
+  Catalog as NativeCatalog,
+  CatalogOptions as NativeCatalogOptions,
+} from "./native.js";
+import { OAuthConfig } from "./oauth";
+
+/** Options shared by a catalog and the database connections it returns. */
+export interface CatalogOptions
+  extends Omit<NativeCatalogOptions, "oauthConfig"> {
+  oauthConfig?: OAuthConfig;
+  /** Called for each request to supply authentication headers. */
+  headerProvider?:
+    | HeaderProvider
+    | (() => Record<string, string> | Promise<Record<string, string>>);
+}
+
+export type { ListDatabasesResponse } from "./native.js";
+
+/** A remote catalog manages databases through the server's root namespace. */
+export class Catalog {
+  /** @hidden */
+  constructor(private readonly inner: NativeCatalog) {}
+
+  /** The root namespace endpoint. */
+  get uri(): string {
+    return this.inner.uri;
+  }
+
+  /** Create a database, or open an existing database when existOk is true. */
+  async createDatabase(
+    name: string,
+    options: { existOk?: boolean } = {},
+  ): Promise<Connection> {
+    return new LocalConnection(
+      await this.inner.createDatabase(name, options.existOk),
+    );
+  }
+
+  /** Connect to an existing database by its logical name. */
+  async connectDatabase(name: string): Promise<Connection> {
+    return new LocalConnection(await this.inner.connectDatabase(name));
+  }
+
+  /** Drop an empty database. The server rejects nonempty databases. */
+  async dropDatabase(
+    name: string,
+    options: { ignoreMissing?: boolean } = {},
+  ): Promise<void> {
+    await this.inner.dropDatabase(name, options.ignoreMissing);
+  }
+
+  /** List one page of databases; pass pageToken from a response for the next page. */
+  async listDatabases(
+    options: { limit?: number; pageToken?: string } = {},
+  ): Promise<ListDatabasesResponse> {
+    if (
+      options.limit !== undefined &&
+      (!Number.isInteger(options.limit) ||
+        options.limit <= 0 ||
+        options.limit > 2147483647)
+    ) {
+      throw new Error(
+        "Database list limit must be an integer between 1 and 2147483647",
+      );
+    }
+    return this.inner.listDatabases(options.limit, options.pageToken);
+  }
+}
+
+/**
+ * Connect to an HTTP(S) catalog endpoint. Catalog requests omit database-selection
+ * headers; opened database connections inherit authentication and client options.
+ *
+ * @example
+ * ```ts
+ * const catalog = await connectCatalog("https://my-server.example", { apiKey: "secret" });
+ * const db = await catalog.createDatabase("analytics", { existOk: true });
+ * const page = await catalog.listDatabases({ limit: 20 });
+ * ```
+ */
+export async function connectCatalog(
+  endpoint: string,
+  options: CatalogOptions = {},
+): Promise<Catalog> {
+  const { headerProvider, ...nativeOptions } = options;
+  const provider = headerProvider
+    ? new JsHeaderProvider(async () =>
+        typeof headerProvider === "function"
+          ? headerProvider()
+          : headerProvider.getHeaders(),
+      )
+    : undefined;
+  return new Catalog(
+    await NativeCatalog.new(endpoint, nativeOptions, provider),
+  );
+}

nodejs/lancedb/connection.ts

@@ -31,6 +31,7 @@ import type {
   ListNamespacesResponse,
   ListTablesResponse,
 } from "./native";
+import { ViewDescription, viewDescriptionFromNative } from "./view";
 export type {
   CreateNamespaceResponse,
   DescribeNamespaceResponse,
@@ -320,13 +321,13 @@ export abstract class Connection {
   /**
    * Define a materialized view named `name` over the table `source`.
    *
-   * The view is created empty, with the query recorded in its schema
-   * metadata; `view.refresh()` computes the rows. The view is a normal
-   * table: it can be queried, indexed and searched, and it appears in
-   * `tableNames`. The source table must have stable row ids (create it with
+   * The view is populated before creation returns. Set `withNoData` to create
+   * only its definition and empty backing table. The view is a normal table:
+   * it can be queried, indexed and searched, and it appears in `tableNames`.
+   * The source table must have stable row ids (create it with
    * the `newTableEnableStableRowIds` storage option); they keep the view's
    * provenance valid across source compactions and cannot be enabled after
-   * a table exists. Local databases only.
+   * a table exists.
    */
   abstract createMaterializedView(
     name: string,
@@ -335,6 +336,7 @@ export abstract class Connection {
       select?: MaterializedViewSelect;
       where?: string;
       limit?: number;
+      withNoData?: boolean;
     },
   ): Promise<MaterializedView>;
 
@@ -352,6 +354,69 @@ export abstract class Connection {
    */
   abstract listMaterializedViews(): Promise<string[]>;
 
+  /**
+   * Drop the materialized view named `name`.
+   *
+   * The view may become unavailable before physical cleanup finishes. Use
+   * {@link dropMaterializedViewAsync} to retain and wait for the cleanup job.
+   *
+   * Rejects a table that exists but is not a materialized view.
+   */
+  abstract dropMaterializedView(
+    name: string,
+    namespacePath?: string[],
+  ): Promise<void>;
+
+  /**
+   * Start dropping the materialized view named `name` and return its cleanup
+   * job without waiting for completion.
+   *
+   * Rejects a table that exists but is not a materialized view.
+   */
+  abstract dropMaterializedViewAsync(
+    name: string,
+    namespacePath?: string[],
+  ): Promise<Job>;
+
+  /**
+   * Create a view: a named query the database plans on every read.
+   *
+   * The query is planned once, at creation, so one that cannot be planned is
+   * rejected now rather than at the first read. A view holds no rows, and its
+   * readers see its sources as they are at read time.
+   *
+   * There is no replace: a name already taken is an error, and changing a
+   * view is a drop followed by a create.
+   */
+  abstract createView(
+    name: string,
+    query: string,
+    namespacePath?: string[],
+  ): Promise<ViewDescription>;
+
+  /**
+   * What this database records about the view named `name`: its defining
+   * query and the schema that query resolved to.
+   */
+  abstract describeView(
+    name: string,
+    namespacePath?: string[],
+  ): Promise<ViewDescription>;
+
+  /**
+   * Drop the view named `name`.
+   *
+   * The tables it reads are untouched: a view holds no rows of its own.
+   */
+  abstract dropView(name: string, namespacePath?: string[]): Promise<void>;
+
+  /**
+   * The names of the views in one namespace.
+   *
+   * Names only; a definition comes from {@link describeView}.
+   */
+  abstract listViews(namespacePath?: string[]): Promise<string[]>;
+
   abstract openTable(
     name: string,
     namespacePath?: string[],
@@ -631,6 +696,7 @@ export class LocalConnection extends Connection {
       select?: MaterializedViewSelect;
       where?: string;
       limit?: number;
+      withNoData?: boolean;
     },
   ): Promise<MaterializedView> {
     validateNonNegativeInteger(options?.limit, "limit");
@@ -640,6 +706,7 @@ export class LocalConnection extends Connection {
       normalizeSelect(options?.select),
       options?.where,
       options?.limit,
+      options?.withNoData ?? false,
     );
     return new MaterializedView(new LocalTable(innerTable));
   }
@@ -653,6 +720,49 @@ export class LocalConnection extends Connection {
     return await this.inner.listMaterializedViews();
   }
 
+  async dropMaterializedView(
+    name: string,
+    namespacePath?: string[],
+  ): Promise<void> {
+    return this.inner.dropMaterializedView(name, namespacePath ?? []);
+  }
+
+  async dropMaterializedViewAsync(
+    name: string,
+    namespacePath?: string[],
+  ): Promise<Job> {
+    return new Job(
+      await this.inner.dropMaterializedViewAsync(name, namespacePath ?? []),
+    );
+  }
+
+  async createView(
+    name: string,
+    query: string,
+    namespacePath?: string[],
+  ): Promise<ViewDescription> {
+    return viewDescriptionFromNative(
+      await this.inner.createView(name, query, namespacePath ?? []),
+    );
+  }
+
+  async describeView(
+    name: string,
+    namespacePath?: string[],
+  ): Promise<ViewDescription> {
+    return viewDescriptionFromNative(
+      await this.inner.describeView(name, namespacePath ?? []),
+    );
+  }
+
+  async dropView(name: string, namespacePath?: string[]): Promise<void> {
+    return this.inner.dropView(name, namespacePath ?? []);
+  }
+
+  async listViews(namespacePath?: string[]): Promise<string[]> {
+    return this.inner.listViews(namespacePath ?? []);
+  }
+
   async listTables(
     namespacePathOrOptions?: string[] | Partial<ListTablesOptions>,
     options?: Partial<ListTablesOptions>,

nodejs/lancedb/index.ts

@@ -26,6 +26,7 @@ export {
   MaterializedViewDefinition,
   MaterializedViewSelect,
 } from "./materialized_view";
+export { ViewDescription } from "./view";
 export { JsHeaderProvider as NativeJsHeaderProvider } from "./native.js";
 
 // OpenTelemetry metrics bridge. Only the high-level entry point is public; the
@@ -56,6 +57,10 @@ export {
   AddResult,
   AddColumnsResult,
   RefreshColumnResult,
+  FunctionErrors,
+  FunctionErrorsOptions,
+  FunctionErrorRecord,
+  FunctionErrorFragment,
   RefreshMaterializedViewResult,
   AlterColumnsResult,
   UpdateFieldMetadataResult,
@@ -72,11 +77,15 @@ export {
 
 export {
   makeArrowTable,
+  makeJsonField,
   MakeArrowTableOptions,
   Data,
   VectorColumnOptions,
 } from "./arrow";
 
+export { blob, isBlobField, BlobFile } from "./blob";
+export type { BlobOptions } from "./blob";
+
 export {
   Connection,
   CreateTableOptions,
@@ -167,7 +176,15 @@ export {
   TokenResponse,
 } from "./header";
 
-export { OAuthConfig, OAuthFlowType } from "./oauth";
+export {
+  ClientAuthMethod,
+  OAuthConfig,
+  OAuthFlowType,
+  OAuthSession,
+  SessionLogout,
+  SessionStatus,
+  TokenCacheOptions,
+} from "./oauth";
 
 export { MergeInsertBuilder, WriteExecutionOptions } from "./merge";
 
@@ -617,3 +634,10 @@ export async function connectNamespace(
   );
   return new LocalConnection(nativeConn);
 }
+
+export {
+  Catalog,
+  CatalogOptions,
+  ListDatabasesResponse,
+  connectCatalog,
+} from "./catalog";

nodejs/lancedb/materialized_view.ts

@@ -7,20 +7,21 @@ import { Table } from "./table";
 /** Schema metadata key holding a materialized view's definition. */
 export const DEFINITION_META_KEY = "mv.definition";
 
-/** The query that defines a materialized view. */
+/**
+ * The newest stored layout this version reads: `{"format": N, "query": "<SQL>"}`,
+ * format 2 being a query with `GROUP BY`.
+ */
+export const DEFINITION_FORMAT = 2;
+
+/**
+ * The query that defines a materialized view, as stored:
+ * `SELECT columns FROM [ns.]table [, function(args) AS alias | , UNNEST(column) AS alias]
+ * [WHERE predicate] [GROUP BY expr, ...] [LIMIT n]`. A Function in `FROM`
+ * position yields one row per element it returns.
+ */
 export interface MaterializedViewDefinition {
-  /** Name of the source table, in the same database as the view. */
-  sourceTable: string;
-  /** `[output column, SQL expression]` pairs, in view schema order. */
-  projections: [string, string][];
-  /** SQL predicate selecting the source rows the view holds. */
-  filter?: string;
-  /** Cap on the number of rows the view holds. */
-  limit?: number;
-  /** Source columns the projections and filter read. */
-  inputs: string[];
-  /** Namespace holding the source table; empty is the root namespace. */
-  sourceNamespace: string[];
+  /** The defining query, in the canonical spelling the server stores. */
+  query: string;
 }
 
 /**
@@ -78,13 +79,31 @@ export function definitionFromMetadata(
   if (raw === undefined) {
     throw new Error(`Table '${name}' is not a materialized view`);
   }
+  return definitionFromJson(raw, name);
+}
+
+/** @internal Parse the backend-independent definition returned by native code. */
+export function definitionFromJson(
+  raw: string,
+  name: string,
+): MaterializedViewDefinition {
   // biome-ignore lint/suspicious/noExplicitAny: raw JSON
   const value: any = JSON.parse(raw);
-  // "namespaced_select" keeps older readers from resolving the source at root.
+  if (value.format !== undefined) {
+    // A newer writer's layout is reported, never guessed at.
+    if (!Number.isInteger(value.format) || value.format > DEFINITION_FORMAT) {
+      throw new Error(
+        `materialized view '${name}' is stored in format ${value.format}, ` +
+          "which this version of lancedb cannot refresh",
+      );
+    }
+    return { query: value.query };
+  }
+  // The structured layout written before the format number.
   if (value.kind !== "select" && value.kind !== "namespaced_select") {
     throw new Error(
-      `materialized view '${name}' is defined by '${value.kind}', which this ` +
-        "version of lancedb cannot refresh",
+      `materialized view '${name}' is stored in format kind '${value.kind}', ` +
+        "which this version of lancedb cannot refresh",
     );
   }
   const limit = value.limit ?? undefined;
@@ -96,18 +115,41 @@ export function definitionFromMetadata(
       `materialized view '${name}' has a stored limit too large to represent exactly`,
     );
   }
-  return {
-    sourceTable: value.source_table,
-    // biome-ignore lint/suspicious/noExplicitAny: raw JSON
-    projections: (value.projections ?? []).map((p: any) => [
-      p.output,
-      p.expression,
-    ]),
-    filter: value.filter ?? undefined,
-    limit,
-    inputs: value.inputs ?? [],
-    sourceNamespace: value.source_namespace ?? [],
-  };
+  return { query: legacyQuery(value, limit) };
+}
+
+function legacyIdent(name: string): string {
+  return /^[a-z_][a-z0-9_]*$/.test(name)
+    ? name
+    : `\`${name.replace(/`/g, "``")}\``;
+}
+
+/** Render the pre-format structured layout as the query it described. */
+// biome-ignore lint/suspicious/noExplicitAny: raw JSON
+function legacyQuery(value: any, limit: number | undefined): string {
+  // biome-ignore lint/suspicious/noExplicitAny: raw JSON
+  const projections: any[] = value.projections ?? [];
+  const columns =
+    projections.length === 0
+      ? "*"
+      : projections
+          .map((p) =>
+            p.expression === p.output || p.expression === `\`${p.output}\``
+              ? p.expression
+              : `${p.expression} AS ${legacyIdent(p.output)}`,
+          )
+          .join(", ");
+  const table = [...(value.source_namespace ?? []), value.source_table]
+    .map(legacyIdent)
+    .join(".");
+  let query = `SELECT ${columns} FROM ${table}`;
+  if (value.filter !== undefined && value.filter !== null) {
+    query += ` WHERE ${value.filter}`;
+  }
+  if (limit !== undefined) {
+    query += ` LIMIT ${limit}`;
+  }
+  return query;
 }
 
 /**
@@ -134,10 +176,12 @@ export class MaterializedView {
     return this.inner;
   }
 
-  /** The query that defines the view, read from its stored schema. */
+  /** The query that defines the view. */
   async definition(): Promise<MaterializedViewDefinition> {
-    const schema = await this.inner.schema();
-    return definitionFromMetadata(schema.metadata, this.name);
+    return definitionFromJson(
+      await this.inner.materializedViewDefinition(),
+      this.name,
+    );
   }
 
   /**

nodejs/lancedb/oauth.ts

@@ -1,16 +1,79 @@
 // SPDX-License-Identifier: Apache-2.0
 // SPDX-FileCopyrightText: Copyright The LanceDB Authors
 
+import {
+  OAuthConfig as NativeOAuthConfig,
+  OAuthSession as NativeOAuthSession,
+} from "./native";
+
 /**
  * OAuth authentication flow types.
  */
 export enum OAuthFlowType {
   /** Client Credentials grant (service-to-service / M2M). */
   ClientCredentials = "client_credentials",
+  /** Interactive Authorization Code grant, using PKCE by default. */
+  AuthorizationCode = "authorization_code",
+  /** Device Authorization grant for CLI and headless environments. */
+  DeviceCode = "device_code",
   /** Azure Managed Identity via IMDS. */
   AzureManagedIdentity = "azure_managed_identity",
 }
 
+/**
+ * Options for the persistent OAuth token cache.
+ *
+ * The cache is opt-in: it is only used when set as `tokenCache` on
+ * {@link OAuthConfig}. Only refresh tokens are persisted, in a private
+ * directory with owner-only permissions, so short-lived processes can reuse
+ * an authenticated session instead of re-prompting on every start.
+ *
+ * Multiple identities (issuer, client, scopes, resource, audience, flow, client authentication)
+ * get separate cache entries. Within one identity the most recent login wins.
+ */
+export interface TokenCacheOptions {
+  /**
+   * Directory that holds cached credentials. Defaults to
+   * `$XDG_CACHE_HOME/lancedb/oauth`, `$HOME/.cache/lancedb/oauth` on Unix,
+   * or `%LOCALAPPDATA%\\lancedb\\oauth` on Windows. The directory is created
+   * with owner-only permissions (`0700`) when missing.
+   */
+  cacheDir?: string;
+
+  /**
+   * How long to wait for the cross-process refresh lock before failing, in
+   * seconds (default: 30).
+   */
+  lockTimeoutSecs?: number;
+}
+
+/**
+ * How the client authenticates to the OAuth token endpoint.
+ *
+ * The method applies to every OAuth request that carries client
+ * authentication: client-credentials, authorization-code exchange,
+ * refresh-token, and device-authorization requests. The Azure managed
+ * identity flow ignores this option.
+ */
+export enum ClientAuthMethod {
+  /**
+   * No client authentication, for public clients using PKCE or the device
+   * flow. Cannot be combined with `clientSecret`.
+   */
+  None = "none",
+  /**
+   * HTTP Basic authentication. This is the RFC 6749 recommended method and
+   * the normal default for confidential clients, including default Okta
+   * applications. Requires `clientSecret`.
+   */
+  ClientSecretBasic = "client_secret_basic",
+  /**
+   * Credentials in the request body, for providers configured to require it.
+   * Requires `clientSecret`.
+   */
+  ClientSecretPost = "client_secret_post",
+}
+
 /**
  * OAuth configuration for LanceDB authentication.
  *
@@ -31,6 +94,18 @@ export enum OAuthFlowType {
  * };
  * ```
  *
+ * Providers requiring an explicit target can set `resource` and/or `audience`:
+ * ```typescript
+ * const targeted: OAuthConfig = {
+ *   issuerUrl: "https://issuer.example.com",
+ *   clientId: "app-id",
+ *   clientSecret: "secret",
+ *   scopes: ["read"],
+ *   resource: "https://api.example.com",
+ *   audience: "lancedb-api",
+ * };
+ * ```
+ *
  * @example Azure Managed Identity:
  * ```typescript
  * const config: OAuthConfig = {
@@ -40,6 +115,21 @@ export enum OAuthFlowType {
  *   flow: OAuthFlowType.AzureManagedIdentity,
  * };
  * ```
+ *
+ * @example Authorization Code with PKCE:
+ * The authorization URL is written to stderr before LanceDB tries to open a
+ * browser, so it can be copied in headless environments.
+ * ```typescript
+ * const config: OAuthConfig = {
+ *   issuerUrl: "https://login.microsoftonline.com/{tenant}/v2.0",
+ *   clientId: "app-id",
+ *   scopes: ["openid", "api://lancedb-api/access"],
+ *   flow: OAuthFlowType.AuthorizationCode,
+ * };
+ * ```
+ *
+ * Device Authorization writes the verification URL and user code to stderr
+ * before polling begins.
  */
 export interface OAuthConfig {
   /**
@@ -58,12 +148,43 @@ export interface OAuthConfig {
    */
   scopes: string[];
 
+  /**
+   * Resource indicator (RFC 8707), forwarded verbatim to authorization and token
+   * endpoints, including refresh requests. Must be an absolute URI without a
+   * fragment. Not supported for Azure managed identity.
+   */
+  resource?: string;
+
+  /**
+   * Provider-specific audience, forwarded to authorization and token endpoints,
+   * including refresh requests. Not supported for Azure managed identity.
+   */
+  audience?: string;
+
   /** Authentication flow (default: ClientCredentials). */
   flow?: OAuthFlowType;
 
   /** Client secret (required for ClientCredentials). */
   clientSecret?: string;
 
+  /**
+   * How the client authenticates to the token endpoint (default: auto).
+   * With a `clientSecret` the default is `ClientAuthMethod.ClientSecretBasic`,
+   * which matches the RFC 6749 recommendation and the default configuration
+   * of Okta confidential applications; without a secret the client is public
+   * and no client authentication is sent.
+   */
+  clientAuthMethod?: ClientAuthMethod;
+
+  /** Loopback redirect URI for AuthorizationCode. */
+  redirectUri?: string;
+
+  /** Port for the AuthorizationCode loopback callback server (default: 8400). */
+  callbackPort?: number;
+
+  /** Protect AuthorizationCode with S256 PKCE (default: true). */
+  usePkce?: boolean;
+
   /** Client ID for user-assigned managed identity (AzureManagedIdentity). */
   managedIdentityClientId?: string;
 
@@ -73,4 +194,125 @@ export interface OAuthConfig {
    * the TTL, each request refreshes the token.
    */
   refreshBufferSecs?: number;
+
+  /**
+   * Opt in to the persistent token cache so short-lived processes reuse one
+   * session. Only refresh tokens are persisted. Only supported by
+   * AuthorizationCode and DeviceCode; Azure managed identity is rejected.
+   * Default: unset (memory only).
+   */
+  tokenCache?: TokenCacheOptions;
+}
+
+/**
+ * Safe, non-secret view of a cached OAuth session, returned by
+ * {@link OAuthSession.status} and {@link OAuthSession.login}.
+ */
+export interface SessionStatus {
+  /**
+   * Whether a cached session exists that can obtain tokens without
+   * interactive authentication. Because access tokens are not persisted,
+   * this is `true` exactly when a refresh token is cached; the next
+   * connection refreshes with it rather than opening a browser or device
+   * prompt.
+   */
+  refreshable: boolean;
+
+  /** Canonical issuer URL of the cached session. */
+  issuerUrl: string;
+
+  /** Client ID of the cached session. */
+  clientId: string;
+
+  /** Canonical (sorted, de-duplicated) scope set of the cached session. */
+  scopes: string[];
+
+  /** Resource indicator used to obtain the cached session, if configured. */
+  resource?: string;
+
+  /** Provider-specific audience used to obtain the cached session, if configured. */
+  audience?: string;
+
+  /** Flow that produced the cached session. */
+  flow: string;
+
+  /** When the cached session was obtained, as Unix seconds. */
+  obtainedAt?: number;
+}
+
+/** Result of {@link OAuthSession.logout}. */
+export interface SessionLogout {
+  /**
+   * Whether a cached credential was removed. `false` means no matching
+   * session was cached; logout is idempotent.
+   */
+  removed: boolean;
+}
+
+/**
+ * Explicit OAuth session lifecycle for the persistent token cache: eager
+ * `login`, non-secret `status`, and local `logout`.
+ *
+ * A session is built from the same {@link OAuthConfig} used to connect
+ * (including its `tokenCache` options). A connection created with the same
+ * configuration shares the cache, so logging in here prepares tokens for
+ * later processes without any database request.
+ *
+ * `login` always runs the configured interactive flow and replaces the cached
+ * session (the most recent login wins). `logout` removes only the local
+ * credential; it does not revoke anything with the provider and does not sign
+ * out of a browser SSO session.
+ *
+ * @example
+ * ```typescript
+ * const config: OAuthConfig = {
+ *   issuerUrl: "https://issuer.example.com",
+ *   clientId: "my-app",
+ *   scopes: ["openid", "offline_access"],
+ *   flow: OAuthFlowType.DeviceCode,
+ *   tokenCache: { cacheDir: "/tmp/my-app/oauth-cache" },
+ * };
+ * const session = new OAuthSession(config);
+ * const status = await session.login();
+ * ```
+ */
+export class OAuthSession {
+  private readonly inner: NativeOAuthSession;
+
+  /** Create a session manager for the given OAuth configuration. */
+  constructor(config: OAuthConfig) {
+    this.inner = new NativeOAuthSession(config as unknown as NativeOAuthConfig);
+  }
+
+  /**
+   * Eagerly run the configured authentication flow and store the session.
+   *
+   * A successful login always replaces any prior cached session for this
+   * identity; if the provider does not issue a refresh token (for example
+   * without `offline_access`), the previous record is removed and the status
+   * reports `refreshable == false`.
+   */
+  async login(): Promise<SessionStatus> {
+    return this.inner.login();
+  }
+
+  /**
+   * Report whether a matching cached session exists, with safe metadata.
+   *
+   * This never contacts the identity provider and never exposes token values.
+   */
+  async status(): Promise<SessionStatus> {
+    return this.inner.status();
+  }
+
+  /**
+   * Remove the matching local cached credential.
+   *
+   * This only deletes the local cache entry. It does not revoke the refresh
+   * token with the provider and does not sign out of a browser SSO session.
+   * Repeated calls succeed; `removed` reports whether a credential existed.
+   */
+  async logout(): Promise<SessionLogout> {
+    return this.inner.logout();
+  }
 }

nodejs/lancedb/table.ts

@@ -17,9 +17,11 @@ import {
   tableFromIPC,
 } from "./arrow";
 
+import { BlobFile } from "./blob";
 import { EmbeddingFunctionConfig, getRegistry } from "./embedding/registry";
 import { IndexOptions } from "./indices";
 import { Job } from "./job";
+import { validateNonNegativeInteger } from "./materialized_view";
 import { MergeInsertBuilder } from "./merge";
 import {
   AddColumnsResult,
@@ -29,6 +31,8 @@ import {
   BranchContents,
   DeleteResult,
   DropColumnsResult,
+  FunctionErrors,
+  FunctionErrorsOptions,
   IndexConfig,
   IndexStatistics,
   LsmStats,
@@ -147,7 +151,8 @@ export interface OptimizeOptions {
    * olderThan.setDate(olderThan.getDate() - 1));
    * tbl.optimize({cleanupOlderThan: olderThan});
    *
-   * // Delete all versions except the current version
+   * // Delete versions committed before this point. Versions created by the
+   * // optimize call itself are newer than the cutoff and will be retained.
    * tbl.optimize({cleanupOlderThan: new Date()});
    */
   cleanupOlderThan: Date;
@@ -510,6 +515,35 @@ export abstract class Table {
    */
   abstract takeRowIds(rowIds: readonly (bigint | number)[]): TakeQuery;
 
+  /**
+   * Blob v2 columns, including nested dotted paths.
+   */
+  abstract blobColumns(): Promise<string[]>;
+
+  /**
+   * Bytes for `column` at row IDs from {@link Query.withRowId}.
+   *
+   * Reads the table's current checkout. IDs from another version can fail after
+   * compaction unless stable row ids are enabled. Results keep input order and
+   * duplicates. Null blobs are `null`. Empty blobs are empty buffers.
+   */
+  abstract fetchBlobs(
+    column: string,
+    rowIds: readonly (bigint | number)[],
+  ): Promise<(Buffer | null)[]>;
+
+  /**
+   * Opens lazy blob handles for `column` at the given row IDs using the
+   * table's current checkout.
+   *
+   * Preserves input order, duplicates, and nulls. Use this for large payloads.
+   * See {@link Table.fetchBlobs} for row-ID validity across versions.
+   */
+  abstract fetchBlobFiles(
+    column: string,
+    rowIds: readonly (bigint | number)[],
+  ): Promise<(BlobFile | null)[]>;
+
   /**
    * Create a search query to find the nearest neighbors
    * of the given query
@@ -542,10 +576,10 @@ export abstract class Table {
    * {@link Table#refreshColumn}. Declaring one therefore costs the same on a
    * large table as on an empty one.
    *
-   * A refresh does not revisit rows it has already filled, so mutating an
-   * input leaves the value computed at fill time; recomputing means dropping
-   * the column and declaring it again. While a declaration reads a column,
-   * that column cannot be renamed, retyped or dropped.
+   * A refresh also recomputes the rows whose inputs changed since they were
+   * computed, so a mutated input is reflected by the next refresh. While a
+   * declaration reads a column, that column cannot be renamed, retyped or
+   * dropped.
    *
    * On LanceDB Cloud and Enterprise the expression is planned by the
    * server, and the refresh runs as a server job -- see
@@ -576,10 +610,10 @@ export abstract class Table {
   /**
    * Fill the rows of a computed column that hold no value yet.
    *
-   * Rows appended since the last refresh are filled by the next one; rows
-   * already filled are left as they are, so the call is idempotent and does
-   * not observe a mutated input. Local tables only: a remote refresh runs
-   * as a server job, through {@link Table#refreshColumnAsync}.
+   * 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}.
    * @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.
@@ -605,11 +639,32 @@ export abstract class Table {
    */
   abstract refreshColumnAsync(column: string): Promise<Job>;
 
+  /**
+   * The per-row errors Function refreshes recorded on this 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
+   * 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).
+   * @returns {Promise<FunctionErrors>} The records, the capped fragments,
+   * and whether the listing stopped at its limit.
+   * @example
+   * ```ts
+   * const { records, truncated } = await table.functionErrors({ column: "embedding" });
+   * ```
+   */
+  abstract functionErrors(
+    options?: FunctionErrorsOptions,
+  ): Promise<FunctionErrors>;
+
   /**
    * Recompute this table's contents from its materialized-view definition.
    *
    * Plumbing for {@link MaterializedView.refresh}, which is the way to call
-   * it: rejects tables that carry no view definition. Local tables only.
+   * it: rejects tables that carry no view definition.
    * @ignore
    */
   abstract refreshMaterializedView(
@@ -617,6 +672,9 @@ export abstract class Table {
     sourceVersion?: number,
   ): Promise<RefreshMaterializedViewResult>;
 
+  /** @ignore */
+  abstract materializedViewDefinition(): Promise<string>;
+
   /**
    * Alter the name or nullability of columns.
    * @param {ColumnAlteration[]} columnAlterations One or more alterations to
@@ -1160,23 +1218,34 @@ export class LocalTable extends Table {
   }
 
   takeRowIds(rowIds: readonly (bigint | number)[]): TakeQuery {
-    const ids = rowIds.map((id) => {
-      if (typeof id === "bigint") {
-        return id;
-      }
-      if (!Number.isInteger(id)) {
-        throw new Error("Row id must be an integer (or bigint)");
-      }
-      if (id < 0) {
-        throw new Error("Row id cannot be negative");
-      }
-      if (!Number.isSafeInteger(id)) {
-        throw new Error("Row id is too large for number; use bigint instead");
-      }
-      return BigInt(id);
-    });
+    return new TakeQuery(this.inner.takeRowIds(rowIdsToBigInts(rowIds)));
+  }
 
-    return new TakeQuery(this.inner.takeRowIds(ids));
+  blobColumns(): Promise<string[]> {
+    return this.inner.blobColumns();
+  }
+
+  async fetchBlobs(
+    column: string,
+    rowIds: readonly (bigint | number)[],
+  ): Promise<(Buffer | null)[]> {
+    const values = await this.inner.fetchBlobs(column, rowIdsToBigInts(rowIds));
+    // N-API Option maps missing values to undefined. Collapse those to null.
+    return values.map((value) => value ?? null);
+  }
+
+  async fetchBlobFiles(
+    column: string,
+    rowIds: readonly (bigint | number)[],
+  ): Promise<(BlobFile | null)[]> {
+    const files = await this.inner.fetchBlobFiles(
+      column,
+      rowIdsToBigInts(rowIds),
+    );
+    // N-API Option maps missing values to undefined. Collapse those to null.
+    return files.map((file) =>
+      file == null ? null : BlobFile.fromNative(file),
+    );
   }
 
   query(): Query {
@@ -1318,6 +1387,13 @@ export class LocalTable extends Table {
     return new Job(await this.inner.refreshColumnAsync(column));
   }
 
+  async functionErrors(
+    options?: FunctionErrorsOptions,
+  ): Promise<FunctionErrors> {
+    validateNonNegativeInteger(options?.limit, "limit");
+    return await this.inner.functionErrors(options);
+  }
+
   async refreshMaterializedView(
     full?: boolean,
     sourceVersion?: number,
@@ -1325,6 +1401,10 @@ export class LocalTable extends Table {
     return await this.inner.refreshMaterializedView(full, sourceVersion);
   }
 
+  async materializedViewDefinition(): Promise<string> {
+    return await this.inner.materializedViewDefinition();
+  }
+
   async alterColumns(
     columnAlterations: ColumnAlteration[],
   ): Promise<AlterColumnsResult> {
@@ -1445,16 +1525,8 @@ export class LocalTable extends Table {
   }
 
   async optimize(options?: Partial<OptimizeOptions>): Promise<OptimizeStats> {
-    let cleanupOlderThanMs;
-    if (
-      options?.cleanupOlderThan !== undefined &&
-      options?.cleanupOlderThan !== null
-    ) {
-      cleanupOlderThanMs =
-        new Date().getTime() - options.cleanupOlderThan.getTime();
-    }
     return await this.inner.optimize(
-      cleanupOlderThanMs,
+      options?.cleanupOlderThan?.getTime(),
       options?.deleteUnverified,
     );
   }
@@ -1733,3 +1805,21 @@ export class Branches {
     )) as unknown as CherryPickResult;
   }
 }
+
+function rowIdsToBigInts(rowIds: readonly (bigint | number)[]): bigint[] {
+  return rowIds.map((id) => {
+    if (typeof id === "bigint") {
+      return id;
+    }
+    if (!Number.isInteger(id)) {
+      throw new Error("Row id must be an integer (or bigint)");
+    }
+    if (id < 0) {
+      throw new Error("Row id cannot be negative");
+    }
+    if (!Number.isSafeInteger(id)) {
+      throw new Error("Row id is too large for number; use bigint instead");
+    }
+    return BigInt(id);
+  });
+}

nodejs/lancedb/view.ts

@@ -0,0 +1,48 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright The LanceDB Authors
+
+import { Schema, tableFromIPC } from "apache-arrow";
+import { ViewDescription as NativeViewDescription } from "./native";
+
+/**
+ * What a database records about one view.
+ *
+ * A view holds no rows: it stores the statement that defines it and the
+ * schema that statement resolved to, so a reader sees its sources as they
+ * are at read time.
+ */
+export interface ViewDescription {
+  /** The view's name within its namespace. */
+  name: string;
+  /** The namespace holding the view; empty is the root namespace. */
+  namespacePath: string[];
+  /** The defining query, as the database stores it. */
+  query: string;
+  /** The database that unqualified table names in {@link query} resolve against. */
+  defaultDatabase: string;
+  /**
+   * The namespace path those unqualified names resolve against; empty is the
+   * root namespace.
+   *
+   * Recorded with the view because it outlives the session that declared it:
+   * a reader resolving the query against its own default namespace could read
+   * a different table than the view was defined over.
+   */
+  defaultNamespacePath: string[];
+  /** The schema the defining query resolved to when the view was created. */
+  schema: Schema;
+}
+
+/** Decode the schema the binding hands over as an Arrow IPC file. */
+export function viewDescriptionFromNative(
+  view: NativeViewDescription,
+): ViewDescription {
+  return {
+    name: view.name,
+    namespacePath: view.namespacePath,
+    query: view.query,
+    defaultDatabase: view.defaultDatabase,
+    defaultNamespacePath: view.defaultNamespacePath,
+    schema: tableFromIPC(view.schema).schema,
+  };
+}

nodejs/npm/darwin-arm64/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@lancedb/lancedb-darwin-arm64",
-	"version": "0.39.0-beta.6",
+	"version": "0.40.0-beta.8",
 	"os": ["darwin"],
 	"cpu": ["arm64"],
 	"main": "lancedb.darwin-arm64.node",

nodejs/npm/linux-arm64-gnu/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@lancedb/lancedb-linux-arm64-gnu",
-	"version": "0.39.0-beta.6",
+	"version": "0.40.0-beta.8",
 	"os": ["linux"],
 	"cpu": ["arm64"],
 	"main": "lancedb.linux-arm64-gnu.node",

nodejs/npm/linux-arm64-musl/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@lancedb/lancedb-linux-arm64-musl",
-	"version": "0.39.0-beta.6",
+	"version": "0.40.0-beta.8",
 	"os": ["linux"],
 	"cpu": ["arm64"],
 	"main": "lancedb.linux-arm64-musl.node",

nodejs/npm/linux-x64-gnu/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@lancedb/lancedb-linux-x64-gnu",
-	"version": "0.39.0-beta.6",
+	"version": "0.40.0-beta.8",
 	"os": ["linux"],
 	"cpu": ["x64"],
 	"main": "lancedb.linux-x64-gnu.node",

nodejs/npm/linux-x64-musl/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@lancedb/lancedb-linux-x64-musl",
-	"version": "0.39.0-beta.6",
+	"version": "0.40.0-beta.8",
 	"os": ["linux"],
 	"cpu": ["x64"],
 	"main": "lancedb.linux-x64-musl.node",

nodejs/npm/win32-arm64-msvc/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lancedb/lancedb-win32-arm64-msvc",
-  "version": "0.39.0-beta.6",
+  "version": "0.40.0-beta.8",
   "os": [
     "win32"
   ],

nodejs/npm/win32-x64-msvc/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@lancedb/lancedb-win32-x64-msvc",
-	"version": "0.39.0-beta.6",
+	"version": "0.40.0-beta.8",
 	"os": ["win32"],
 	"cpu": ["x64"],
 	"main": "lancedb.win32-x64-msvc.node",

nodejs/package.json

@@ -11,7 +11,7 @@
     "ann"
   ],
   "private": false,
-  "version": "0.39.0-beta.6",
+  "version": "0.40.0-beta.8",
   "main": "dist/index.js",
   "exports": {
     ".": "./dist/index.js",

nodejs/src/blob.rs

@@ -0,0 +1,95 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright The LanceDB Authors
+
+use std::ops::Range;
+use std::sync::Arc;
+
+use arrow_array::{Array, LargeBinaryArray};
+use lancedb::blob::BlobFile as LanceBlobFile;
+use napi::bindgen_prelude::*;
+use napi_derive::napi;
+
+use crate::error::convert_error;
+
+#[napi]
+pub struct BlobFile {
+    inner: Arc<LanceBlobFile>,
+}
+
+impl BlobFile {
+    pub(crate) fn new(inner: LanceBlobFile) -> Self {
+        Self {
+            inner: Arc::new(inner),
+        }
+    }
+}
+
+#[napi]
+impl BlobFile {
+    #[napi]
+    pub fn size(&self) -> BigInt {
+        BigInt::from(self.inner.size())
+    }
+
+    #[napi]
+    pub async fn read(&self) -> napi::Result<Buffer> {
+        let bytes = self.inner.read().await.map_err(|err| convert_error(&err))?;
+        Ok(Buffer::from(bytes.as_ref()))
+    }
+
+    #[napi]
+    pub async fn read_range(&self, start: BigInt, end: BigInt) -> napi::Result<Buffer> {
+        let range = bigint_range(start, end)?;
+        let bytes = self
+            .inner
+            .read_range(range)
+            .await
+            .map_err(|err| convert_error(&err))?;
+        Ok(Buffer::from(bytes.as_ref()))
+    }
+}
+
+fn bigint_range(start: BigInt, end: BigInt) -> napi::Result<Range<u64>> {
+    let start = parse_u64(start, "start")?;
+    let end = parse_u64(end, "end")?;
+    if start > end {
+        return Err(napi::Error::from_reason(format!(
+            "invalid blob range: start ({start}) > end ({end})"
+        )));
+    }
+    Ok(start..end)
+}
+
+fn parse_u64(value: BigInt, name: &str) -> napi::Result<u64> {
+    let (negative, value, lossless) = value.get_u64();
+    if negative {
+        return Err(napi::Error::from_reason(format!(
+            "{name} cannot be negative"
+        )));
+    }
+    if !lossless {
+        return Err(napi::Error::from_reason(format!(
+            "{name} is too large to fit in u64"
+        )));
+    }
+    Ok(value)
+}
+
+pub fn parse_row_ids(row_ids: Vec<BigInt>) -> napi::Result<Vec<u64>> {
+    row_ids
+        .into_iter()
+        .map(|id| parse_u64(id, "row id"))
+        .collect()
+}
+
+pub fn copy_blob_buffers(array: LargeBinaryArray) -> Vec<Option<Buffer>> {
+    (0..array.len())
+        .map(|i| {
+            if array.is_null(i) {
+                None
+            } else {
+                Some(Buffer::from(array.value(i).to_vec()))
+            }
+        })
+        .collect()
+}

nodejs/src/catalog.rs

@@ -0,0 +1,123 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright The LanceDB Authors
+
+use std::sync::Arc;
+use std::time::Duration;
+
+use lancedb::catalog::{
+    CatalogConnection, CreateDatabaseRequest, DropDatabaseRequest, ListDatabasesRequest,
+};
+use napi::bindgen_prelude::*;
+use napi_derive::napi;
+
+use crate::connection::Connection;
+use crate::error::NapiErrorExt;
+use crate::header::JsHeaderProvider;
+use crate::remote::{ClientConfig, OAuthConfig};
+
+#[napi(object)]
+pub struct CatalogOptions {
+    pub api_key: Option<String>,
+    pub client_config: Option<ClientConfig>,
+    /// SQL service endpoint inherited by database connections.
+    pub sql_host_override: Option<String>,
+    pub read_consistency_interval: Option<f64>,
+    pub oauth_config: Option<OAuthConfig>,
+}
+
+#[napi(object)]
+pub struct ListDatabasesResponse {
+    pub databases: Vec<String>,
+    pub page_token: Option<String>,
+}
+
+#[napi]
+pub struct Catalog {
+    inner: CatalogConnection,
+}
+
+#[napi]
+impl Catalog {
+    #[napi(factory)]
+    pub async fn new(
+        endpoint: String,
+        options: CatalogOptions,
+        header_provider: Option<&JsHeaderProvider>,
+    ) -> Result<Self> {
+        let mut builder = lancedb::connect_catalog(endpoint);
+        if let Some(key) = options.api_key {
+            builder = builder.api_key(key);
+        }
+        let mut config: lancedb::remote::ClientConfig =
+            options.client_config.unwrap_or_default().into();
+        if let Some(provider) = header_provider {
+            config.header_provider = Some(Arc::new(provider.clone()));
+        }
+        builder = builder.client_config(config);
+        if let Some(endpoint) = options.sql_host_override {
+            builder = builder.sql_host_override(endpoint);
+        }
+        if let Some(interval) = options.read_consistency_interval {
+            let interval = Duration::try_from_secs_f64(interval).map_err(|err| {
+                Error::from_reason(format!("Invalid read consistency interval: {err}"))
+            })?;
+            builder = builder.read_consistency_interval(interval);
+        }
+        if let Some(oauth) = options.oauth_config {
+            builder = builder.oauth_config(oauth.try_into().default_error()?);
+        }
+        Ok(Self {
+            inner: builder.execute().await.default_error()?,
+        })
+    }
+
+    #[napi(getter)]
+    pub fn uri(&self) -> String {
+        self.inner.uri().to_string()
+    }
+
+    #[napi]
+    pub async fn create_database(
+        &self,
+        name: String,
+        exist_ok: Option<bool>,
+    ) -> Result<Connection> {
+        self.inner
+            .create_database(CreateDatabaseRequest::new(name).exist_ok(exist_ok.unwrap_or(false)))
+            .await
+            .map(Connection::inner_new)
+            .default_error()
+    }
+    #[napi]
+    pub async fn connect_database(&self, name: String) -> Result<Connection> {
+        self.inner
+            .connect_database(name)
+            .await
+            .map(Connection::inner_new)
+            .default_error()
+    }
+    #[napi]
+    pub async fn drop_database(&self, name: String, ignore_missing: Option<bool>) -> Result<()> {
+        self.inner
+            .drop_database(
+                DropDatabaseRequest::new(name).ignore_missing(ignore_missing.unwrap_or(false)),
+            )
+            .await
+            .default_error()
+    }
+    #[napi]
+    pub async fn list_databases(
+        &self,
+        limit: Option<u32>,
+        page_token: Option<String>,
+    ) -> Result<ListDatabasesResponse> {
+        let mut request = ListDatabasesRequest::default();
+        request.limit = limit;
+        request.page_token = page_token;
+        let response = self.inner.list_databases(request).await.default_error()?;
+        Ok(ListDatabasesResponse {
+            databases: response.databases,
+            page_token: response.page_token,
+        })
+    }
+}

nodejs/src/connection.rs

@@ -55,6 +55,32 @@ pub struct DropNamespaceResponse {
     pub transaction_id: Option<Vec<String>>,
 }
 
+/// What a database records about one view.
+#[napi(object)]
+pub struct ViewDescription {
+    pub name: String,
+    pub namespace_path: Vec<String>,
+    pub query: String,
+    pub default_database: String,
+    pub default_namespace_path: Vec<String>,
+    /// The view's schema as an empty Arrow IPC file, the way a table reports
+    /// its own.
+    pub schema: Buffer,
+}
+
+impl ViewDescription {
+    fn from_inner(view: lancedb::view::ViewDescription) -> napi::Result<Self> {
+        Ok(Self {
+            name: view.name,
+            namespace_path: view.namespace_path,
+            query: view.query,
+            default_database: view.default_database,
+            default_namespace_path: view.default_namespace_path,
+            schema: crate::util::schema_to_buffer(&view.schema)?,
+        })
+    }
+}
+
 impl Connection {
     pub(crate) fn inner_new(inner: LanceDBConnection) -> Self {
         Self { inner: Some(inner) }
@@ -308,6 +334,7 @@ impl Connection {
         projections: Option<Vec<Vec<String>>>,
         filter: Option<String>,
         limit: Option<i64>,
+        with_no_data: bool,
     ) -> napi::Result<Table> {
         let mut builder = self.get_inner()?.create_materialized_view(name, source);
         if let Some(projections) = projections {
@@ -328,6 +355,7 @@ impl Connection {
                 .map_err(|_| napi::Error::from_reason("limit must be a non-negative integer"))?;
             builder = builder.limit(limit);
         }
+        builder = builder.with_no_data(with_no_data);
         let view = builder.execute().await.default_error()?;
         Ok(Table::new(view.table().clone()))
     }
@@ -349,7 +377,94 @@ impl Connection {
             .list_materialized_views()
             .await
             .default_error()?;
-        Ok(views.into_iter().map(|v| v.name).collect())
+        Ok(views)
+    }
+
+    /// Drop a materialized view.
+    #[napi(catch_unwind)]
+    pub async fn drop_materialized_view(
+        &self,
+        name: String,
+        namespace_path: Option<Vec<String>>,
+    ) -> napi::Result<()> {
+        let ns = namespace_path.unwrap_or_default();
+        self.get_inner()?
+            .drop_materialized_view(&name, &ns)
+            .await
+            .default_error()
+    }
+
+    /// Create a view: a named query planned on every read.
+    #[napi(catch_unwind)]
+    pub async fn create_view(
+        &self,
+        name: String,
+        query: String,
+        namespace_path: Option<Vec<String>>,
+    ) -> napi::Result<ViewDescription> {
+        let ns = namespace_path.unwrap_or_default();
+        let view = self
+            .get_inner()?
+            .create_view(&name, &query, &ns)
+            .await
+            .default_error()?;
+        ViewDescription::from_inner(view)
+    }
+
+    /// What the database records about one view.
+    #[napi(catch_unwind)]
+    pub async fn describe_view(
+        &self,
+        name: String,
+        namespace_path: Option<Vec<String>>,
+    ) -> napi::Result<ViewDescription> {
+        let ns = namespace_path.unwrap_or_default();
+        let view = self
+            .get_inner()?
+            .describe_view(&name, &ns)
+            .await
+            .default_error()?;
+        ViewDescription::from_inner(view)
+    }
+
+    /// Drop a view. The tables it reads are untouched.
+    #[napi(catch_unwind)]
+    pub async fn drop_view(
+        &self,
+        name: String,
+        namespace_path: Option<Vec<String>>,
+    ) -> napi::Result<()> {
+        let ns = namespace_path.unwrap_or_default();
+        self.get_inner()?
+            .drop_view(&name, &ns)
+            .await
+            .default_error()
+    }
+
+    /// The names of the views in one namespace.
+    #[napi(catch_unwind)]
+    pub async fn list_views(
+        &self,
+        namespace_path: Option<Vec<String>>,
+    ) -> napi::Result<Vec<String>> {
+        let ns = namespace_path.unwrap_or_default();
+        self.get_inner()?.list_views(&ns).await.default_error()
+    }
+
+    /// Start dropping a materialized view and return its cleanup job.
+    #[napi(catch_unwind)]
+    pub async fn drop_materialized_view_async(
+        &self,
+        name: String,
+        namespace_path: Option<Vec<String>>,
+    ) -> napi::Result<crate::job::Job> {
+        let ns = namespace_path.unwrap_or_default();
+        let job = self
+            .get_inner()?
+            .drop_materialized_view_async(&name, &ns)
+            .await
+            .default_error()?;
+        Ok(crate::job::Job::new(job))
     }
 
     #[napi(catch_unwind)]

nodejs/src/lib.rs

@@ -10,6 +10,8 @@ use std::collections::HashMap;
 use env_logger::Env;
 use napi_derive::*;
 
+mod blob;
+mod catalog;
 mod connection;
 mod error;
 mod header;

nodejs/src/remote.rs

@@ -6,6 +6,8 @@ use std::collections::HashMap;
 use lancedb::error::Error;
 use napi_derive::*;
 
+use crate::error::NapiErrorExt;
+
 /// Timeout configuration for remote HTTP client.
 #[napi(object)]
 #[derive(Debug)]
@@ -91,6 +93,9 @@ pub struct ClientConfig {
     pub retry_config: Option<RetryConfig>,
     pub timeout_config: Option<TimeoutConfig>,
     pub extra_headers: Option<HashMap<String, String>>,
+    /// The delimiter joining a namespace path and a name into one object
+    /// identifier. `"$"` is the only supported value, and leaving this unset is
+    /// how to get it; anything else is rejected when the connection is created.
     pub id_delimiter: Option<String>,
     pub tls_config: Option<TlsConfig>,
     /// User identifier for tracking purposes.
@@ -141,6 +146,34 @@ impl From<TlsConfig> for lancedb::remote::TlsConfig {
     }
 }
 
+/// Options for the persistent OAuth token cache.
+///
+/// The cache is opt-in: it is only used when set as `tokenCache` on
+/// `OAuthConfig`. Only refresh tokens are persisted, in a private directory
+/// with owner-only permissions, so short-lived processes can reuse an
+/// authenticated session instead of re-prompting on every start.
+#[napi(object)]
+#[derive(Clone, Debug, Default)]
+pub struct TokenCacheOptions {
+    /// Directory that holds cached credentials. Defaults to
+    /// `$XDG_CACHE_HOME/lancedb/oauth`, `$HOME/.cache/lancedb/oauth` on Unix,
+    /// or `%LOCALAPPDATA%\lancedb\oauth` on Windows. The directory is created
+    /// with owner-only permissions (`0700`) when missing.
+    pub cache_dir: Option<String>,
+    /// How long to wait for the cross-process refresh lock before failing,
+    /// in seconds (default: 30).
+    pub lock_timeout_secs: Option<u32>,
+}
+
+impl From<TokenCacheOptions> for lancedb::remote::TokenCacheOptions {
+    fn from(options: TokenCacheOptions) -> Self {
+        Self {
+            cache_dir: options.cache_dir.map(std::path::PathBuf::from),
+            lock_timeout_secs: options.lock_timeout_secs.map(|secs| secs as u64),
+        }
+    }
+}
+
 /// OAuth configuration for LanceDB authentication.
 ///
 /// This is the generated napi-rs binding shape. TypeScript users should prefer
@@ -158,16 +191,35 @@ pub struct OAuthConfig {
     /// OAuth scopes to request. For Azure managed identity, exactly one scope
     /// or resource is required. For example: `["api://{app_id}/.default"]`
     pub scopes: Vec<String>,
-    /// Authentication flow: "client_credentials" or "azure_managed_identity"
+    /// Optional resource indicator for authorization and token requests.
+    pub resource: Option<String>,
+    /// Optional provider-specific audience for authorization and token requests.
+    pub audience: Option<String>,
+    /// Authentication flow: "client_credentials", "authorization_code",
+    /// "device_code", or "azure_managed_identity"
     pub flow: Option<String>,
     /// Client secret (required for client_credentials).
     pub client_secret: Option<String>,
+    /// How the client authenticates to the token endpoint: "none",
+    /// "client_secret_basic", or "client_secret_post". Defaults to
+    /// "client_secret_basic" when a client secret is set, and "none" for
+    /// public clients.
+    pub client_auth_method: Option<String>,
+    /// Loopback redirect URI for authorization_code.
+    pub redirect_uri: Option<String>,
+    /// Port for the authorization_code loopback callback server.
+    pub callback_port: Option<u16>,
+    /// Whether authorization_code uses S256 PKCE (default: true).
+    pub use_pkce: Option<bool>,
     /// Client ID for user-assigned managed identity (azure_managed_identity).
     pub managed_identity_client_id: Option<String>,
     /// Seconds before expiry to trigger proactive refresh (default: 300).
     /// Keep this well below the token TTL; if it is greater than or equal to
     /// the TTL, each request refreshes the token.
     pub refresh_buffer_secs: Option<u32>,
+    /// Opt in to the persistent token cache so short-lived processes reuse
+    /// one session. Only refresh tokens are persisted.
+    pub token_cache: Option<TokenCacheOptions>,
 }
 
 impl std::fmt::Debug for OAuthConfig {
@@ -176,16 +228,23 @@ impl std::fmt::Debug for OAuthConfig {
             .field("issuer_url", &self.issuer_url)
             .field("client_id", &self.client_id)
             .field("scopes", &self.scopes)
+            .field("resource", &self.resource)
+            .field("audience", &self.audience)
             .field("flow", &self.flow)
             .field(
                 "client_secret",
                 &self.client_secret.as_deref().map(|_| "<redacted>"),
             )
+            .field("client_auth_method", &self.client_auth_method)
+            .field("redirect_uri", &self.redirect_uri)
+            .field("callback_port", &self.callback_port)
+            .field("use_pkce", &self.use_pkce)
             .field(
                 "managed_identity_client_id",
                 &self.managed_identity_client_id,
             )
             .field("refresh_buffer_secs", &self.refresh_buffer_secs)
+            .field("token_cache", &self.token_cache)
             .finish()
     }
 }
@@ -194,10 +253,22 @@ impl TryFrom<OAuthConfig> for lancedb::remote::oauth::OAuthConfig {
     type Error = Error;
 
     fn try_from(config: OAuthConfig) -> Result<Self, Self::Error> {
-        use lancedb::remote::oauth::OAuthFlow;
+        use lancedb::remote::oauth::{AuthorizationCodeOptions, OAuthFlow};
 
         let flow = match config.flow.as_deref().unwrap_or("client_credentials") {
             "client_credentials" => OAuthFlow::ClientCredentials,
+            "authorization_code" => {
+                let mut options =
+                    AuthorizationCodeOptions::new().use_pkce(config.use_pkce.unwrap_or(true));
+                if let Some(redirect_uri) = config.redirect_uri {
+                    options = options.redirect_uri(redirect_uri);
+                }
+                if let Some(callback_port) = config.callback_port {
+                    options = options.callback_port(callback_port);
+                }
+                OAuthFlow::AuthorizationCode(options)
+            }
+            "device_code" => OAuthFlow::DeviceCode,
             "azure_managed_identity" => OAuthFlow::AzureManagedIdentity {
                 client_id: config.managed_identity_client_id,
             },
@@ -208,17 +279,147 @@ impl TryFrom<OAuthConfig> for lancedb::remote::oauth::OAuthConfig {
             }
         };
 
+        let client_auth_method = match config.client_auth_method.as_deref() {
+            Some("none") => Some(lancedb::remote::oauth::ClientAuthMethod::None),
+            Some("client_secret_basic") => {
+                Some(lancedb::remote::oauth::ClientAuthMethod::ClientSecretBasic)
+            }
+            Some("client_secret_post") => {
+                Some(lancedb::remote::oauth::ClientAuthMethod::ClientSecretPost)
+            }
+            None => None,
+            Some(other) => {
+                return Err(Error::InvalidInput {
+                    message: format!("Unknown OAuth client auth method: {other}"),
+                });
+            }
+        };
+
         Ok(Self {
             issuer_url: config.issuer_url,
             client_id: config.client_id,
             client_secret: config.client_secret,
+            client_auth_method,
             scopes: config.scopes,
+            resource: config.resource,
+            audience: config.audience,
             flow,
             refresh_buffer_secs: config.refresh_buffer_secs.map(|v| v as u64),
+            token_cache: config.token_cache.map(Into::into),
         })
     }
 }
 
+/// Safe, non-secret view of a cached OAuth session, returned by
+/// `OAuthSession.status()` and `OAuthSession.login()`.
+#[napi(object)]
+#[derive(Clone, Debug)]
+pub struct SessionStatus {
+    /// Whether a cached session exists that can obtain tokens without
+    /// interactive authentication.
+    pub refreshable: bool,
+    /// Canonical issuer URL of the cached session.
+    pub issuer_url: String,
+    /// Client ID of the cached session.
+    pub client_id: String,
+    /// Canonical (sorted, de-duplicated) scopes of the cached session.
+    pub scopes: Vec<String>,
+    /// Optional resource indicator for authorization and token requests.
+    pub resource: Option<String>,
+    /// Optional provider-specific audience for authorization and token requests.
+    pub audience: Option<String>,
+    /// Flow that produced the cached session.
+    pub flow: String,
+    /// When the cached session was obtained, as Unix seconds.
+    pub obtained_at: Option<f64>,
+}
+
+/// Result of `OAuthSession.logout()`.
+#[napi(object)]
+#[derive(Clone, Debug)]
+pub struct SessionLogout {
+    /// Whether a cached credential was removed. `false` means no matching
+    /// session was cached; logout is idempotent.
+    pub removed: bool,
+}
+
+/// Explicit OAuth session lifecycle for the persistent token cache: eager
+/// `login`, non-secret `status`, and local `logout`.
+///
+/// A session is built from the same `OAuthConfig` used to connect (including
+/// its `tokenCache` options). A connection created with the same
+/// configuration shares the cache, so logging in here prepares tokens for
+/// later processes without any database request.
+#[napi]
+pub struct OAuthSession {
+    inner: lancedb::remote::OAuthSession,
+}
+
+#[napi]
+impl OAuthSession {
+    /// Create a session manager for the given OAuth configuration.
+    ///
+    /// The configuration must enable `tokenCache` options and use a flow that
+    /// supports persistent sessions (authorization code or device code).
+    #[napi(constructor)]
+    pub fn new(config: OAuthConfig) -> napi::Result<Self> {
+        let config: lancedb::remote::oauth::OAuthConfig = config.try_into().default_error()?;
+        let inner = lancedb::remote::OAuthSession::new(config).default_error()?;
+        Ok(Self { inner })
+    }
+
+    /// Eagerly run the configured authentication flow and store the session.
+    ///
+    /// A successful login always replaces any prior cached session for this
+    /// identity; if the provider does not issue a refresh token (for example
+    /// without `offline_access`), the previous record is removed and the
+    /// status reports `refreshable == false`.
+    #[napi(catch_unwind)]
+    pub async fn login(&self) -> napi::Result<SessionStatus> {
+        let status = self.inner.login().await.default_error()?;
+        Ok(SessionStatus::from(status))
+    }
+
+    /// Report whether a matching cached session exists, with safe metadata.
+    ///
+    /// This never contacts the identity provider and never exposes token
+    /// values.
+    #[napi(catch_unwind)]
+    pub async fn status(&self) -> napi::Result<SessionStatus> {
+        let status = self.inner.status().await.default_error()?;
+        Ok(SessionStatus::from(status))
+    }
+
+    /// Remove the matching local cached credential.
+    ///
+    /// This only deletes the local cache entry. It does not revoke the
+    /// refresh token with the provider and does not sign out of a browser
+    /// SSO session. Repeated calls succeed; `removed` reports whether a
+    /// credential existed.
+    #[napi(catch_unwind)]
+    pub async fn logout(&self) -> napi::Result<SessionLogout> {
+        let logout = self.inner.logout().await.default_error()?;
+        Ok(SessionLogout {
+            removed: logout.removed,
+        })
+    }
+}
+
+impl From<lancedb::remote::SessionStatus> for SessionStatus {
+    fn from(status: lancedb::remote::SessionStatus) -> Self {
+        Self {
+            refreshable: status.refreshable,
+            issuer_url: status.issuer_url,
+            client_id: status.client_id,
+            scopes: status.scopes,
+            resource: status.resource,
+            audience: status.audience,
+            flow: status.flow,
+            obtained_at: status.obtained_at.map(|secs| secs as f64),
+        }
+    }
+}
+
 impl From<ClientConfig> for lancedb::remote::ClientConfig {
     fn from(config: ClientConfig) -> Self {
         Self {
@@ -252,8 +453,15 @@ mod tests {
             scopes: vec!["scope".to_string()],
             flow: Some("typo".to_string()),
             client_secret: None,
+            client_auth_method: None,
+            redirect_uri: None,
+            callback_port: None,
+            use_pkce: None,
             managed_identity_client_id: None,
             refresh_buffer_secs: None,
+            resource: None,
+            audience: None,
+            token_cache: None,
         };
 
         let err = lancedb::remote::oauth::OAuthConfig::try_from(config).unwrap_err();
@@ -272,12 +480,136 @@ mod tests {
             scopes: vec!["scope".to_string()],
             flow: Some("client_credentials".to_string()),
             client_secret: Some("super-secret".to_string()),
+            client_auth_method: None,
+            redirect_uri: None,
+            callback_port: None,
+            use_pkce: None,
             managed_identity_client_id: None,
             refresh_buffer_secs: None,
+            resource: None,
+            audience: None,
+            token_cache: None,
         };
 
         let debug = format!("{config:?}");
         assert!(!debug.contains("super-secret"));
         assert!(debug.contains("client_secret: Some(\"<redacted>\")"));
     }
+
+    #[test]
+    fn test_authorization_code_conversion_preserves_options() {
+        let config = OAuthConfig {
+            issuer_url: "https://issuer.example.com".to_string(),
+            client_id: "client-id".to_string(),
+            scopes: vec!["openid".to_string()],
+            flow: Some("authorization_code".to_string()),
+            client_secret: Some("secret".to_string()),
+            client_auth_method: None,
+            redirect_uri: Some("http://127.0.0.1:9000/callback".to_string()),
+            callback_port: Some(9000),
+            use_pkce: Some(false),
+            managed_identity_client_id: None,
+            refresh_buffer_secs: None,
+            resource: Some("urn:resource".into()),
+            audience: Some("audience".into()),
+            token_cache: None,
+        };
+
+        let converted = lancedb::remote::oauth::OAuthConfig::try_from(config).unwrap();
+        let lancedb::remote::oauth::OAuthFlow::AuthorizationCode(options) = converted.flow else {
+            panic!("expected authorization code flow");
+        };
+        assert_eq!(
+            options.redirect_uri.as_deref(),
+            Some("http://127.0.0.1:9000/callback")
+        );
+        assert_eq!(options.callback_port, Some(9000));
+        assert!(!options.use_pkce);
+        assert_eq!(converted.resource.as_deref(), Some("urn:resource"));
+        assert_eq!(converted.audience.as_deref(), Some("audience"));
+    }
+
+    #[test]
+    fn test_device_code_conversion() {
+        let config = OAuthConfig {
+            issuer_url: "https://issuer.example.com".to_string(),
+            client_id: "client-id".to_string(),
+            scopes: vec!["openid".to_string()],
+            flow: Some("device_code".to_string()),
+            client_secret: None,
+            client_auth_method: None,
+            redirect_uri: None,
+            callback_port: None,
+            use_pkce: None,
+            managed_identity_client_id: None,
+            refresh_buffer_secs: None,
+            resource: None,
+            audience: None,
+            token_cache: None,
+        };
+
+        let converted = lancedb::remote::oauth::OAuthConfig::try_from(config).unwrap();
+        assert!(matches!(
+            converted.flow,
+            lancedb::remote::oauth::OAuthFlow::DeviceCode
+        ));
+    }
+
+    #[test]
+    fn test_client_auth_method_conversion() {
+        use lancedb::remote::oauth::ClientAuthMethod;
+
+        for (value, expected) in [
+            ("none", ClientAuthMethod::None),
+            ("client_secret_basic", ClientAuthMethod::ClientSecretBasic),
+            ("client_secret_post", ClientAuthMethod::ClientSecretPost),
+        ] {
+            let config = OAuthConfig {
+                issuer_url: "https://issuer.example.com".to_string(),
+                client_id: "client-id".to_string(),
+                scopes: vec!["openid".to_string()],
+                flow: Some("device_code".to_string()),
+                client_secret: None,
+                client_auth_method: Some(value.to_string()),
+                resource: None,
+                audience: None,
+                redirect_uri: None,
+                callback_port: None,
+                use_pkce: None,
+                managed_identity_client_id: None,
+                refresh_buffer_secs: None,
+                token_cache: None,
+            };
+
+            let converted = lancedb::remote::oauth::OAuthConfig::try_from(config).unwrap();
+            assert_eq!(converted.client_auth_method, Some(expected));
+        }
+    }
+
+    #[test]
+    fn test_unknown_client_auth_method_returns_invalid_input() {
+        let config = OAuthConfig {
+            issuer_url: "https://issuer.example.com".to_string(),
+            client_id: "client-id".to_string(),
+            scopes: vec!["openid".to_string()],
+            flow: Some("device_code".to_string()),
+            client_secret: None,
+            client_auth_method: Some("typo".to_string()),
+            resource: None,
+            audience: None,
+            redirect_uri: None,
+            callback_port: None,
+            use_pkce: None,
+            managed_identity_client_id: None,
+            refresh_buffer_secs: None,
+            token_cache: None,
+        };
+
+        let err = lancedb::remote::oauth::OAuthConfig::try_from(config).unwrap_err();
+        assert!(matches!(
+            err,
+            Error::InvalidInput { message }
+                if message == "Unknown OAuth client auth method: typo"
+        ));
+    }
 }

nodejs/src/table.rs

@@ -7,7 +7,7 @@ use chrono::{DateTime, Utc};
 
 use lancedb::ipc::{ipc_file_to_batches, ipc_file_to_schema};
 use lancedb::table::{
-    AddDataMode, ColumnAlteration as LanceColumnAlteration, Duration,
+    AddDataMode, ColumnAlteration as LanceColumnAlteration,
     FieldMetadataUpdate as LanceFieldMetadataUpdate, FtsToken as LanceDbFtsToken,
     NewColumnTransform, OptimizeAction, OptimizeOptions, Ref, Table as LanceDbTable,
 };
@@ -15,6 +15,7 @@ use napi::bindgen_prelude::*;
 use napi::threadsafe_function::{ThreadsafeFunction, ThreadsafeFunctionCallMode};
 use napi_derive::napi;
 
+use crate::blob::{BlobFile, copy_blob_buffers, parse_row_ids};
 use crate::error::NapiErrorExt;
 use crate::index::Index;
 use crate::merge::NativeMergeInsertBuilder;
@@ -329,6 +330,44 @@ impl Table {
         ))
     }
 
+    #[napi(catch_unwind)]
+    pub async fn blob_columns(&self) -> napi::Result<Vec<String>> {
+        self.inner_ref()?.blob_columns().await.default_error()
+    }
+
+    #[napi(catch_unwind)]
+    pub async fn fetch_blobs(
+        &self,
+        column: String,
+        row_ids: Vec<BigInt>,
+    ) -> napi::Result<Vec<Option<Buffer>>> {
+        let row_ids = parse_row_ids(row_ids)?;
+        let array = self
+            .inner_ref()?
+            .fetch_blobs(column.as_str(), &row_ids)
+            .await
+            .default_error()?;
+        Ok(copy_blob_buffers(array))
+    }
+
+    #[napi(catch_unwind)]
+    pub async fn fetch_blob_files(
+        &self,
+        column: String,
+        row_ids: Vec<BigInt>,
+    ) -> napi::Result<Vec<Option<BlobFile>>> {
+        let row_ids = parse_row_ids(row_ids)?;
+        let files = self
+            .inner_ref()?
+            .fetch_blob_files(column.as_str(), &row_ids)
+            .await
+            .default_error()?;
+        Ok(files
+            .into_iter()
+            .map(|file| file.map(BlobFile::new))
+            .collect())
+    }
+
     #[napi(catch_unwind)]
     pub fn vector_search(&self, vector: Float32Array) -> napi::Result<VectorQuery> {
         self.query()?.nearest_to(vector)
@@ -388,6 +427,32 @@ impl Table {
         Ok(crate::job::Job::new(job))
     }
 
+    #[napi(catch_unwind)]
+    pub async fn function_errors(
+        &self,
+        options: Option<FunctionErrorsOptions>,
+    ) -> napi::Result<FunctionErrors> {
+        let options = options.unwrap_or_default();
+        let limit = options
+            .limit
+            .map(|limit| {
+                usize::try_from(limit)
+                    .map_err(|_| napi::Error::from_reason("limit must be a non-negative integer"))
+            })
+            .transpose()?;
+        let request = lancedb::function::FunctionErrorsRequest {
+            job_id: options.job_id,
+            column: options.column,
+            limit,
+        };
+        let errors = self
+            .inner_ref()?
+            .function_errors(request)
+            .await
+            .default_error()?;
+        Ok(errors.into())
+    }
+
     #[napi(catch_unwind)]
     pub async fn refresh_materialized_view(
         &self,
@@ -408,6 +473,19 @@ impl Table {
         Ok(result.into())
     }
 
+    #[napi(catch_unwind)]
+    pub async fn materialized_view_definition(&self) -> napi::Result<String> {
+        let inner = self.inner_ref()?.clone();
+        let view = lancedb::MaterializedView::from_table(inner)
+            .await
+            .default_error()?;
+        view.definition().to_json().map_err(|err| {
+            napi::Error::from_reason(format!(
+                "failed to serialize materialized-view definition: {err}"
+            ))
+        })
+    }
+
     #[napi(catch_unwind)]
     pub async fn add_columns_with_schema(
         &self,
@@ -638,22 +716,20 @@ impl Table {
     #[napi(catch_unwind)]
     pub async fn optimize(
         &self,
-        older_than_ms: Option<i64>,
+        before_timestamp_ms: Option<i64>,
         delete_unverified: Option<bool>,
     ) -> napi::Result<OptimizeStats> {
         let inner = self.inner_ref()?;
 
-        let older_than = if let Some(ms) = older_than_ms {
-            if ms == i64::MIN {
-                return Err(napi::Error::from_reason(format!(
-                    "older_than_ms can not be {}",
-                    i32::MIN,
-                )));
-            }
-            Duration::try_milliseconds(ms)
-        } else {
-            None
-        };
+        let before_timestamp = before_timestamp_ms
+            .map(|ms| {
+                DateTime::from_timestamp_millis(ms).ok_or_else(|| {
+                    napi::Error::from_reason(format!(
+                        "cleanupOlderThan timestamp is out of range: {ms}"
+                    ))
+                })
+            })
+            .transpose()?;
 
         let compaction_stats = inner
             .optimize(OptimizeAction::Compact {
@@ -664,16 +740,22 @@ impl Table {
             .default_error()?
             .compaction
             .unwrap();
-        let prune_stats = inner
-            .optimize(OptimizeAction::Prune {
-                older_than,
-                delete_unverified,
-                error_if_tagged_old_versions: None,
-            })
-            .await
-            .default_error()?
-            .prune
-            .unwrap();
+        let prune_stats = if let Some(before_timestamp) = before_timestamp {
+            inner
+                .optimize_prune_before(before_timestamp, delete_unverified, None)
+                .await
+        } else {
+            inner
+                .optimize(OptimizeAction::Prune {
+                    older_than: None,
+                    delete_unverified,
+                    error_if_tagged_old_versions: None,
+                })
+                .await
+        }
+        .default_error()?
+        .prune
+        .unwrap();
         inner
             .optimize(lancedb::table::OptimizeAction::Index(
                 OptimizeOptions::default(),
@@ -1420,6 +1502,97 @@ pub struct RefreshColumnResult {
     pub version: i64,
 }
 
+/// Which per-row Function errors to list; every filter is optional.
+#[napi(object)]
+#[derive(Clone, Debug, Default)]
+pub struct FunctionErrorsOptions {
+    /// Only errors recorded by this job.
+    pub job_id: Option<String>,
+    /// Only errors on this column.
+    pub column: Option<String>,
+    /// At most this many records (server default 10000, cap 100000).
+    pub limit: Option<i64>,
+}
+
+/// One row a Function refresh skipped, as the server recorded it.
+#[napi(object)]
+#[derive(Clone, Debug)]
+pub struct FunctionErrorRecord {
+    pub job_id: String,
+    pub fragment_id: i64,
+    /// The row's offset within the fragment; absent when the fragment's
+    /// detail was capped.
+    pub row_offset: Option<i64>,
+    pub column: String,
+    pub function: String,
+    pub function_version: String,
+    pub table_version: i64,
+    pub error_type: String,
+    pub error_message: String,
+    pub created_at_millis: i64,
+}
+
+impl From<lancedb::function::FunctionErrorRecord> for FunctionErrorRecord {
+    fn from(record: lancedb::function::FunctionErrorRecord) -> Self {
+        Self {
+            job_id: record.job_id,
+            fragment_id: record.fragment_id as i64,
+            row_offset: record.row_offset.map(i64::from),
+            column: record.column,
+            function: record.function,
+            function_version: record.function_version,
+            table_version: record.table_version as i64,
+            error_type: record.error_type,
+            error_message: record.error_message,
+            created_at_millis: record.created_at_millis,
+        }
+    }
+}
+
+/// A fragment whose per-row error detail was capped: `rowsSkipped` rows
+/// failed, of which only `rowsRecorded` have a record of their own.
+#[napi(object)]
+#[derive(Clone, Debug)]
+pub struct FunctionErrorFragment {
+    pub job_id: String,
+    pub fragment_id: i64,
+    pub rows_skipped: i64,
+    pub rows_recorded: i64,
+}
+
+impl From<lancedb::function::FunctionErrorFragment> for FunctionErrorFragment {
+    fn from(fragment: lancedb::function::FunctionErrorFragment) -> Self {
+        Self {
+            job_id: fragment.job_id,
+            fragment_id: fragment.fragment_id as i64,
+            rows_skipped: fragment.rows_skipped as i64,
+            rows_recorded: fragment.rows_recorded as i64,
+        }
+    }
+}
+
+/// A table's per-row Function errors.
+#[napi(object)]
+#[derive(Clone, Debug)]
+pub struct FunctionErrors {
+    /// The recorded rows, newest job first.
+    pub records: Vec<FunctionErrorRecord>,
+    /// Fragments whose detail was capped.
+    pub fragments: Vec<FunctionErrorFragment>,
+    /// Whether the listing stopped at its limit.
+    pub truncated: bool,
+}
+
+impl From<lancedb::function::FunctionErrors> for FunctionErrors {
+    fn from(errors: lancedb::function::FunctionErrors) -> Self {
+        Self {
+            records: errors.records.into_iter().map(Into::into).collect(),
+            fragments: errors.fragments.into_iter().map(Into::into).collect(),
+            truncated: errors.truncated,
+        }
+    }
+}
+
 #[napi(object)]
 pub struct RefreshMaterializedViewResult {
     /// How the view was brought up to date: "rebuild", "incremental" or "no_op".

nodejs/typedoc.json

@@ -4,7 +4,8 @@
     "lancedb/native.d.ts:VectorQuery",
     "lancedb/native.d.ts:TakeQuery",
     "lancedb/native.d.ts:RecordBatchIterator",
-    "lancedb/native.d.ts:NativeMergeInsertBuilder"
+    "lancedb/native.d.ts:NativeMergeInsertBuilder",
+    "lancedb/native.d.ts:TokenCacheOptions"
   ],
   "useHTMLEncodedBrackets": true,
   "useCodeBlocks": true,

python/CLAUDE.md

@@ -1 +0,0 @@
-AGENTS.md

python/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "lancedb-python"
-version = "0.39.0-beta.6"
+version = "0.40.0-beta.8"
 publish = false
 edition.workspace = true
 description = "Python bindings for LanceDB"
@@ -15,6 +15,7 @@ name = "_lancedb"
 crate-type = ["cdylib"]
 
 [dependencies]
+arc-swap = "1.9"
 arrow = { workspace = true, features = ["pyarrow"] }
 async-trait.workspace = true
 bytes.workspace = true

python/pyproject.toml

@@ -63,7 +63,7 @@ tests = [
     "polars>=0.19, <=1.32.3",
     "pyarrow<25",
     "pyarrow-stubs>=16.0",
-    "pylance==9.0.0rc1",
+    "pylance==9.0.0",
     "requests>=2.31.0",
     "datafusion>=54,<55",
     "opentelemetry-sdk>=1.30.0",
@@ -126,6 +126,7 @@ include = [
     "python/lancedb/rerankers/util.py",
     "python/lancedb/rerankers/__init__.py",
     "python/lancedb/rerankers/voyageai.py",
+    "python/lancedb/rerankers/typesafe.py",
     "python/lancedb/rerankers/jinaai.py",
     "python/lancedb/rerankers/openai.py",
     "python/lancedb/rerankers/cross_encoder.py",

python/python/lancedb/__init__.py

@@ -12,6 +12,9 @@ __version__ = importlib.metadata.version("lancedb")
 
 from ._lancedb import connect as lancedb_connect
 from ._lancedb import FtsToken
+from ._lancedb import FunctionErrorFragment as FunctionErrorFragment
+from ._lancedb import FunctionErrorRecord as FunctionErrorRecord
+from ._lancedb import FunctionErrors as FunctionErrors
 from ._lancedb import LsmWriteSpec
 from ._lancedb import tokenize as _tokenize
 from .common import URI, sanitize_uri
@@ -37,11 +40,14 @@ from .functions import (
     UdfDefinition as UdfDefinition,
     udf as udf,
 )
+from .secrets import EnvVarSecret as EnvVarSecret
+from .secrets import SecretInfo as SecretInfo
 from .materialized_view import (
     AsyncMaterializedView,
     MaterializedView,
     MaterializedViewDefinition,
 )
+from .view import ViewDescription as ViewDescription
 from .table import AsyncTable, Table
 from .types import BaseTokenizerType
 from ._lancedb import Session
@@ -52,6 +58,14 @@ from .namespace import (
     AsyncLanceNamespaceDBConnection,
 )
 
+from .catalog import (
+    AsyncCatalog,
+    Catalog,
+    ListDatabasesResponse,
+    connect_catalog,
+    connect_catalog_async,
+)
+
 
 if TYPE_CHECKING:
     from lance.blob import BlobType as BlobType
@@ -561,9 +575,15 @@ async def connect_async(
 
 
 __all__ = [
+    "Catalog",
+    "AsyncCatalog",
+    "ListDatabasesResponse",
+    "connect_catalog",
+    "connect_catalog_async",
     "AsyncMaterializedView",
     "MaterializedView",
     "MaterializedViewDefinition",
+    "ViewDescription",
     "connect",
     "connect_async",
     "tokenize",

python/python/lancedb/_lancedb.pyi

@@ -153,6 +153,36 @@ class Connection(object):
     async def get_function(self, name: str, version: str) -> str: ...
     async def list_functions(self) -> List[str]: ...
     async def drop_function(self, name: str, version: str) -> bool: ...
+    async def drop_function_async(
+        self, name: str, version: str
+    ) -> Tuple[bool, Job]: ...
+    async def create_secret(
+        self, name: str, value: str, namespace_path: Optional[List[str]] = None
+    ) -> None: ...
+    async def alter_secret(
+        self, name: str, value: str, namespace_path: Optional[List[str]] = None
+    ) -> None: ...
+    async def list_secrets(
+        self, namespace_path: Optional[List[str]] = None
+    ) -> List[str]: ...
+    async def drop_secret(
+        self, name: str, namespace_path: Optional[List[str]] = None
+    ) -> None: ...
+    async def describe_secret(
+        self, name: str, namespace_path: Optional[List[str]] = None
+    ) -> Tuple[str, int, int]: ...
+    async def create_view(
+        self, name: str, query: str, namespace_path: Optional[List[str]] = None
+    ) -> Tuple[str, List[str], str, str, List[str], pa.Schema]: ...
+    async def describe_view(
+        self, name: str, namespace_path: Optional[List[str]] = None
+    ) -> Tuple[str, List[str], str, str, List[str], pa.Schema]: ...
+    async def drop_view(
+        self, name: str, namespace_path: Optional[List[str]] = None
+    ) -> None: ...
+    async def list_views(
+        self, namespace_path: Optional[List[str]] = None
+    ) -> List[str]: ...
     async def list_jobs(self) -> List[JobInfo]: ...
     async def cancel_job(self, job_id: str) -> bool: ...
     async def execute_query_async(
@@ -211,8 +241,24 @@ class Connection(object):
         projections: Optional[List[Tuple[str, str]]] = None,
         filter: Optional[str] = None,
         limit: Optional[int] = None,
+        with_no_data: bool = False,
     ) -> Table: ...
+    async def create_materialized_view_async(
+        self,
+        name: str,
+        source: str,
+        projections: Optional[List[Tuple[str, str]]] = None,
+        filter: Optional[str] = None,
+        limit: Optional[int] = None,
+        with_no_data: bool = False,
+    ) -> Job: ...
     async def list_materialized_views(self) -> List[str]: ...
+    async def drop_materialized_view(
+        self, name: str, namespace_path: Optional[List[str]] = None
+    ) -> None: ...
+    async def drop_materialized_view_async(
+        self, name: str, namespace_path: Optional[List[str]] = None
+    ) -> Job: ...
     async def drop_table(
         self, name: str, namespace_path: Optional[List[str]] = None
     ) -> None: ...
@@ -267,6 +313,37 @@ class JobInfo:
     @property
     def created_at_millis(self) -> int: ...
 
+class SessionStatus:
+    @property
+    def resource(self) -> Optional[str]: ...
+    @property
+    def audience(self) -> Optional[str]: ...
+    @property
+    def refreshable(self) -> bool: ...
+    @property
+    def issuer_url(self) -> str: ...
+    @property
+    def client_id(self) -> str: ...
+    @property
+    def scopes(self) -> List[str]: ...
+    @property
+    def flow(self) -> str: ...
+    @property
+    def obtained_at(self) -> Optional[int]: ...
+    def __repr__(self) -> str: ...
+
+class SessionLogout:
+    @property
+    def removed(self) -> bool: ...
+    def __repr__(self) -> str: ...
+
+class OAuthSession:
+    def __init__(self, config: Any) -> None: ...
+    async def login(self) -> SessionStatus: ...
+    async def status(self) -> SessionStatus: ...
+    async def logout(self) -> SessionLogout: ...
+    def __repr__(self) -> str: ...
+
 class JobFailureInfo:
     @property
     def phase(self) -> Optional[str]: ...
@@ -399,9 +476,19 @@ class Table:
     ) -> AddColumnsResult: ...
     async def refresh_column(self, column: str) -> RefreshColumnResult: ...
     async def refresh_column_async(self, column: str) -> Job: ...
+    async def function_errors(
+        self,
+        job_id: Optional[str] = None,
+        column: Optional[str] = None,
+        limit: Optional[int] = None,
+    ) -> FunctionErrors: ...
     async def refresh_materialized_view(
         self, full: bool = False, source_version: Optional[int] = None
     ) -> RefreshMaterializedViewResult: ...
+    async def refresh_materialized_view_async(
+        self, full: bool = False, source_version: Optional[int] = None
+    ) -> Job: ...
+    async def materialized_view_definition(self) -> str: ...
     async def add_columns_with_schema(self, schema: pa.Schema) -> AddColumnsResult: ...
     async def alter_columns(
         self, columns: list[dict[str, Any]]
@@ -756,7 +843,32 @@ class RefreshColumnResult:
     rows_filled: int
     version: int
 
+class FunctionErrorRecord:
+    job_id: str
+    fragment_id: int
+    row_offset: Optional[int]
+    column: str
+    function: str
+    function_version: str
+    table_version: int
+    error_type: str
+    error_message: str
+    created_at_millis: int
+
+class FunctionErrorFragment:
+    job_id: str
+    fragment_id: int
+    rows_skipped: int
+    rows_recorded: int
+
+class FunctionErrors:
+    records: list[FunctionErrorRecord]
+    fragments: list[FunctionErrorFragment]
+    truncated: bool
+
 class RefreshMaterializedViewResult:
+    @staticmethod
+    def from_json(value: str) -> RefreshMaterializedViewResult: ...
     mode: str
     rows_written: int
     source_version: int
@@ -805,3 +917,27 @@ def fts_query_to_json(query: Any) -> str: ...
 
 class PermutationReader:
     def __init__(self, base_table: Table, permutation_table: Table): ...
+
+class Catalog:
+    @property
+    def uri(self) -> str: ...
+    async def create_database(
+        self, name: str, *, exist_ok: bool = False
+    ) -> Connection: ...
+    async def connect_database(self, name: str) -> Connection: ...
+    async def drop_database(
+        self, name: str, *, ignore_missing: bool = False
+    ) -> None: ...
+    async def list_databases(
+        self, *, limit: Optional[int] = None, page_token: Optional[str] = None
+    ) -> tuple[list[str], Optional[str]]: ...
+
+async def connect_catalog(
+    endpoint: str,
+    *,
+    api_key: Optional[str] = None,
+    client_config: Optional[Any] = None,
+    sql_host_override: Optional[str] = None,
+    read_consistency_interval: Optional[float] = None,
+    oauth_config: Optional[Any] = None,
+) -> Catalog: ...

python/python/lancedb/catalog.py

@@ -0,0 +1,196 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright The LanceDB Authors
+
+"""Remote catalogs manage databases through a server's root namespace."""
+
+from dataclasses import dataclass
+from datetime import timedelta
+from typing import Any, Optional, Union
+
+from . import _lancedb
+from .background_loop import LOOP
+from .db import AsyncConnection, DBConnection
+from .remote import ClientConfig, OAuthConfig
+from .remote.db import RemoteDBConnection
+
+
+@dataclass
+class ListDatabasesResponse:
+    """A page of database names and an optional continuation token."""
+
+    databases: list[str]
+    page_token: Optional[str] = None
+
+
+class AsyncCatalog:
+    """An asynchronous remote catalog returned by
+    [connect_catalog_async][lancedb.connect_catalog_async].
+
+    Create/connect return ordinary [AsyncConnection][lancedb.db.AsyncConnection]
+    instances. Drop uses restricted behavior: remove the database's tables first.
+    """
+
+    def __init__(self, inner: _lancedb.Catalog):
+        self._inner = inner
+
+    @property
+    def uri(self) -> str:
+        """The catalog's root namespace endpoint."""
+        return self._inner.uri
+
+    async def create_database(
+        self, name: str, *, exist_ok: bool = False
+    ) -> AsyncConnection:
+        """Create a database, or open an existing one when ``exist_ok=True``."""
+        return AsyncConnection(
+            await self._inner.create_database(name, exist_ok=exist_ok)
+        )
+
+    async def connect_database(self, name: str) -> AsyncConnection:
+        """Connect to an existing database by its logical name."""
+        return AsyncConnection(await self._inner.connect_database(name))
+
+    async def list_databases(
+        self, *, limit: Optional[int] = None, page_token: Optional[str] = None
+    ) -> ListDatabasesResponse:
+        """List a page of databases. Pass the returned token for the next page."""
+        names, token = await self._inner.list_databases(
+            limit=limit, page_token=page_token
+        )
+        return ListDatabasesResponse(names, token)
+
+    async def drop_database(self, name: str, *, ignore_missing: bool = False) -> None:
+        """Drop an empty database. A nonempty database is an error."""
+        await self._inner.drop_database(name, ignore_missing=ignore_missing)
+
+
+class Catalog:
+    """A synchronous remote catalog returned by
+    [connect_catalog][lancedb.connect_catalog].
+
+    Examples
+    --------
+    ```python
+    catalog = lancedb.connect_catalog("https://my-server.example", api_key="secret")
+    db = catalog.create_database("analytics", exist_ok=True)
+    page = catalog.list_databases(limit=20)
+    ```
+    """
+
+    def __init__(
+        self,
+        inner: AsyncCatalog,
+        *,
+        api_key=None,
+        client_config=None,
+        sql_host_override: Optional[str] = None,
+        oauth_config: Optional[OAuthConfig] = None,
+    ):
+        self._inner = inner
+        self._api_key = api_key
+        self._client_config = client_config
+        self._sql_host_override = sql_host_override
+        self._oauth_config = oauth_config
+
+    @property
+    def uri(self) -> str:
+        """The catalog's root namespace endpoint."""
+        return self._inner.uri
+
+    def create_database(self, name: str, *, exist_ok: bool = False) -> DBConnection:
+        """Create a database, or open an existing one when ``exist_ok=True``."""
+        inner = LOOP.run(self._inner.create_database(name, exist_ok=exist_ok))
+        return self._wrap_database(name, inner)
+
+    def connect_database(self, name: str) -> DBConnection:
+        """Connect to an existing database by its logical name."""
+        return self._wrap_database(name, LOOP.run(self._inner.connect_database(name)))
+
+    def _wrap_database(self, name: str, inner: AsyncConnection) -> DBConnection:
+        return RemoteDBConnection._from_catalog(
+            inner,
+            name,
+            self.uri,
+            self._api_key,
+            self._client_config,
+            self._oauth_config,
+            self._sql_host_override,
+        )
+
+    def list_databases(
+        self, *, limit: Optional[int] = None, page_token: Optional[str] = None
+    ) -> ListDatabasesResponse:
+        """List a page of databases. Pass the returned token for the next page."""
+        return LOOP.run(self._inner.list_databases(limit=limit, page_token=page_token))
+
+    def drop_database(self, name: str, *, ignore_missing: bool = False) -> None:
+        """Drop an empty database. A nonempty database is an error."""
+        LOOP.run(self._inner.drop_database(name, ignore_missing=ignore_missing))
+
+
+async def connect_catalog_async(
+    endpoint: str,
+    *,
+    api_key: Optional[str] = None,
+    client_config: Optional[Union[ClientConfig, dict[str, Any]]] = None,
+    sql_host_override: Optional[str] = None,
+    read_consistency_interval: Optional[timedelta] = None,
+    oauth_config: Optional[OAuthConfig] = None,
+) -> AsyncCatalog:
+    """Connect to an HTTP(S) server's root catalog.
+
+    Root requests omit database-selection headers. API key, client configuration,
+    OAuth, and table read consistency settings are inherited by opened databases.
+    Database names containing slashes remain single logical names.
+    Set ``sql_host_override`` to the SQL service endpoint to execute SQL through
+    returned connections when the catalog endpoint uses HTTPS.
+    """
+    if isinstance(client_config, dict):
+        client_config = ClientConfig(**client_config)
+    if client_config is None:
+        client_config = ClientConfig()
+    inner = await _lancedb.connect_catalog(
+        endpoint,
+        api_key=api_key,
+        client_config=client_config,
+        sql_host_override=sql_host_override,
+        read_consistency_interval=(
+            read_consistency_interval.total_seconds()
+            if read_consistency_interval is not None
+            else None
+        ),
+        oauth_config=oauth_config,
+    )
+    return AsyncCatalog(inner)
+
+
+def connect_catalog(
+    endpoint: str,
+    *,
+    api_key: Optional[str] = None,
+    client_config: Optional[Union[ClientConfig, dict[str, Any]]] = None,
+    sql_host_override: Optional[str] = None,
+    read_consistency_interval: Optional[timedelta] = None,
+    oauth_config: Optional[OAuthConfig] = None,
+) -> Catalog:
+    """Connect synchronously to an HTTP(S) server's root catalog.
+
+    See [connect_catalog_async][lancedb.connect_catalog_async] for options.
+    Local filesystem and object-store catalogs are not supported.
+    """
+    return Catalog(
+        LOOP.run(
+            connect_catalog_async(
+                endpoint,
+                api_key=api_key,
+                client_config=client_config,
+                sql_host_override=sql_host_override,
+                read_consistency_interval=read_consistency_interval,
+                oauth_config=oauth_config,
+            )
+        ),
+        api_key=api_key,
+        client_config=client_config,
+        sql_host_override=sql_host_override,
+        oauth_config=oauth_config,
+    )

python/python/lancedb/db.py

@@ -17,6 +17,8 @@ from typing import (
     List,
     Literal,
     Optional,
+    Sequence,
+    Tuple,
     Union,
 )
 from uuid import UUID
@@ -57,6 +59,12 @@ from .materialized_view import (
     SelectArg,
     normalize_select,
 )
+from .secrets import (
+    EnvVarSecret,
+    SecretInfo,
+    validate_namespace_path,
+    validate_secret_name,
+)
 from .table import (
     AsyncTable,
     LanceTable,
@@ -67,6 +75,7 @@ from .util import (
     get_uri_scheme,
     validate_table_name,
 )
+from .view import ViewDescription
 
 import deprecation
 
@@ -88,6 +97,28 @@ from .namespace_utils import (
 )
 
 
+def _view_description(
+    described: Tuple[str, List[str], str, str, List[str], "pa.Schema"],
+) -> ViewDescription:
+    """Name the fields the binding returns positionally."""
+    (
+        name,
+        namespace_path,
+        query,
+        default_database,
+        default_namespace_path,
+        schema,
+    ) = described
+    return ViewDescription(
+        name=name,
+        query=query,
+        default_database=default_database,
+        schema=schema,
+        namespace_path=namespace_path,
+        default_namespace_path=default_namespace_path,
+    )
+
+
 class DBConnection(EnforceOverrides):
     """An active LanceDB connection interface."""
 
@@ -529,13 +560,14 @@ class DBConnection(EnforceOverrides):
         select: SelectArg = None,
         where: Optional[str] = None,
         limit: Optional[int] = None,
+        with_no_data: bool = False,
     ) -> MaterializedView:
         """Define a materialized view named ``name`` over the table ``source``.
 
-        The view is created empty, with the query recorded in its schema
-        metadata; ``view.refresh()`` computes the rows. The view is a normal
-        table: it can be queried, indexed and searched, and it appears in
-        ``table_names``. Local databases only.
+        The view is populated before creation returns. Pass
+        ``with_no_data=True`` to create only its definition and empty backing
+        table. The view is a normal table: it can be queried, indexed and
+        searched, and it appears in ``table_names``.
 
         The source table must have stable row ids (create it with the
         ``new_table_enable_stable_row_ids`` storage option): they keep the
@@ -556,6 +588,8 @@ class DBConnection(EnforceOverrides):
             SQL predicate; only matching source rows appear in the view.
         limit: int, optional
             Cap the view at this many rows, in materialization order.
+        with_no_data: bool, default False
+            Skip the initial refresh and leave the backing table empty.
 
         Returns
         -------
@@ -565,6 +599,27 @@ class DBConnection(EnforceOverrides):
             "materialized views are not supported on this connection type"
         )
 
+    def create_materialized_view_async(
+        self,
+        name: str,
+        source: str,
+        *,
+        select: SelectArg = None,
+        where: Optional[str] = None,
+        limit: Optional[int] = None,
+        with_no_data: bool = False,
+    ) -> Job[None]:
+        """Submit materialized-view creation and return its job.
+
+        The job may already be complete for a local database. On LanceDB
+        Cloud and Enterprise, its ``id`` is the server job identifier from
+        the ``202 Accepted`` create response. Wait for the job before opening
+        or querying the view.
+        """
+        raise NotImplementedError(
+            "materialized views are not supported on this connection type"
+        )
+
     def open_materialized_view(self, name: str) -> MaterializedView:
         """Open the materialized view named ``name``.
 
@@ -585,6 +640,32 @@ class DBConnection(EnforceOverrides):
             "materialized views are not supported on this connection type"
         )
 
+    def drop_materialized_view(
+        self, name: str, namespace_path: Optional[List[str]] = None
+    ) -> None:
+        """Drop a materialized view.
+
+        The view may become unavailable before physical cleanup finishes. Use
+        :meth:`drop_materialized_view_async` to retain and wait for the cleanup
+        job.
+        """
+        raise NotImplementedError(
+            "materialized views are not supported on this connection type"
+        )
+
+    def drop_materialized_view_async(
+        self, name: str, namespace_path: Optional[List[str]] = None
+    ) -> Job[None]:
+        """Start dropping a materialized view and return its cleanup job.
+
+        The job may already be complete for a local database. On LanceDB Cloud
+        and Enterprise, its ``id`` is the server job identifier from the
+        ``202 Accepted`` drop response.
+        """
+        raise NotImplementedError(
+            "materialized views are not supported on this connection type"
+        )
+
     def drop_table(self, name: str, namespace_path: Optional[List[str]] = None):
         """Drop a table from the database.
 
@@ -692,20 +773,55 @@ class DBConnection(EnforceOverrides):
         """
         raise NotImplementedError("serialize is not supported for this connection type")
 
-    def create_function(self, definition: UdfDefinition) -> FunctionVersion:
-        """Register a scalar Python UDF and wait for its immutable version.
+    def create_function(
+        self,
+        definition: UdfDefinition,
+        *,
+        secrets: Optional[Sequence[EnvVarSecret]] = None,
+    ) -> FunctionVersion:
+        """Build and register a scalar Python UDF, then return its version.
 
+        The server builds the OCI image and registers the completed artifact.
         This is the blocking counterpart of :meth:`create_function_async`.
         Local connections raise ``NotImplementedError``.
+
+        Parameters
+        ----------
+        definition : UdfDefinition
+            A callable decorated with [udf][lancedb.udf].
+        secrets : sequence of EnvVarSecret, optional
+            One [EnvVarSecret][lancedb.secrets.EnvVarSecret] per credential the
+            Function needs, each naming a Secret and the environment variable
+            its value arrives in. The Function's source is unchanged by this;
+            it reads the variable the way it already did.
+
+        Examples
+        --------
+        ```python
+        db.create_secret("openai-prod", os.environ["OPENAI_API_KEY"])
+        db.create_function(
+            analyze_caption,
+            secrets=[
+                EnvVarSecret(
+                    secret_name="openai-prod", env_variable="OPENAI_API_KEY"
+                )
+            ],
+        )
+        ```
         """
-        return self.create_function_async(definition).wait()
+        return self.create_function_async(definition, secrets=secrets).wait()
 
-    def create_function_async(self, definition: UdfDefinition) -> Job[FunctionVersion]:
-        """Register a scalar Python UDF through the remote Function catalog.
+    def create_function_async(
+        self,
+        definition: UdfDefinition,
+        *,
+        secrets: Optional[Sequence[EnvVarSecret]] = None,
+    ) -> Job[FunctionVersion]:
+        """Submit a scalar Python UDF for building and registration.
 
-        Submission returns a typed job. The immutable Function version becomes
-        available only when :meth:`Job.wait` succeeds. Local connections raise
-        ``NotImplementedError``.
+        The server-side job builds the OCI image, then registers the completed
+        artifact. Waiting on the job returns the immutable Function version.
+        Local connections raise ``NotImplementedError``.
         """
         raise NotImplementedError(
             "Function catalog operations are not supported for this connection type"
@@ -736,15 +852,157 @@ class DBConnection(EnforceOverrides):
         )
 
     def drop_function(self, name: str, *, version: str) -> bool:
-        """Drop one exact immutable Function version from the remote catalog.
+        """Drop a Function name and the object it was bound to.
 
-        Returns True when the version changed to Dropped and False for an
-        idempotent replay. Local connections raise NotImplementedError.
+        The requested version must exist in the currently named object. Returns
+        True when the name was removed and False when it was absent. The
+        object's content is deleted with it, which may finish after this
+        returns; use :meth:`drop_function_async` to wait for that. Local
+        connections raise NotImplementedError.
         """
         raise NotImplementedError(
             "Function catalog operations are not supported for this connection type"
         )
 
+    def drop_function_async(self, name: str, *, version: str) -> Tuple[bool, Job]:
+        """Drop a Function name and return its cleanup job.
+
+        The name is unbound before this returns; the object's content may still
+        be being deleted. Call :meth:`Job.wait` to wait for that to finish. When
+        the server deletes inline, or when nothing was bound, the returned job
+        is already finished and has no id. Local connections raise
+        NotImplementedError.
+        """
+        raise NotImplementedError(
+            "Function catalog operations are not supported for this connection type"
+        )
+
+    def create_secret(
+        self, name: str, value: str, *, namespace_path: Optional[List[str]] = None
+    ) -> None:
+        """Create a named Secret in this database.
+
+        Fails if the name is taken, so a create never silently becomes a
+        rotation. Nothing reads the value back: it is bound to a Function by
+        name and resolved by the service when that Function runs. Local
+        connections raise ``NotImplementedError``.
+        """
+        raise NotImplementedError(
+            "Secret operations are not supported for this connection type"
+        )
+
+    def alter_secret(
+        self, name: str, value: str, *, namespace_path: Optional[List[str]] = None
+    ) -> None:
+        """Replace the credential behind an existing Secret.
+
+        Fails if it does not exist. Every Function bound to the Secret uses the
+        new value from its next job, and no new Function version is created --
+        which is how a rotation reaches columns pinned to a version registered
+        before it. Local connections raise ``NotImplementedError``.
+        """
+        raise NotImplementedError(
+            "Secret operations are not supported for this connection type"
+        )
+
+    def list_secrets(self, *, namespace_path: Optional[List[str]] = None) -> List[str]:
+        """The names of every Secret in this database.
+
+        Names only. No method returns a stored credential, by construction
+        rather than by policy. Local connections raise ``NotImplementedError``.
+        """
+        raise NotImplementedError(
+            "Secret operations are not supported for this connection type"
+        )
+
+    def drop_secret(
+        self, name: str, *, namespace_path: Optional[List[str]] = None
+    ) -> None:
+        """Drop a Secret.
+
+        Functions bound to it fail at their next job, naming the Secret; that
+        is the revocation path. The name becomes free to reuse, and a new
+        Secret under it is picked up by everything still bound to that name.
+        Local connections raise ``NotImplementedError``.
+        """
+        raise NotImplementedError(
+            "Secret operations are not supported for this connection type"
+        )
+
+    def describe_secret(
+        self, name: str, *, namespace_path: Optional[List[str]] = None
+    ) -> SecretInfo:
+        """What this database records about a Secret: name and timestamps.
+
+        Never the value -- there is no code path that could return one. Local
+        connections raise ``NotImplementedError``.
+        """
+        raise NotImplementedError(
+            "Secret operations are not supported for this connection type"
+        )
+
+    def create_view(
+        self, name: str, query: str, *, namespace_path: Optional[List[str]] = None
+    ) -> ViewDescription:
+        """Create a view: a named query the database plans on every read.
+
+        The query is planned once, at creation, so one that cannot be planned
+        is refused now rather than at the first read. A view holds no rows, and
+        its readers see its sources as they are at read time.
+
+        There is no replace: a name already taken is an error, and changing a
+        view is a drop followed by a create. Local connections raise
+        ``NotImplementedError``.
+
+        >>> import lancedb
+        >>> db = lancedb.connect("db://my_database")  # doctest: +SKIP
+        >>> view = db.create_view(
+        ...     "adults", "SELECT name FROM people WHERE age >= 18"
+        ... )  # doctest: +SKIP
+        >>> view.schema  # doctest: +SKIP
+        name: string
+        """
+        raise NotImplementedError(
+            "View operations are not supported for this connection type"
+        )
+
+    def describe_view(
+        self, name: str, *, namespace_path: Optional[List[str]] = None
+    ) -> ViewDescription:
+        """What this database records about a view: its defining query and the
+        schema that query resolved to.
+
+        The schema is the one recorded at creation; a source altered since then
+        shows up when the view is read. Local connections raise
+        ``NotImplementedError``.
+        """
+        raise NotImplementedError(
+            "View operations are not supported for this connection type"
+        )
+
+    def drop_view(
+        self, name: str, *, namespace_path: Optional[List[str]] = None
+    ) -> None:
+        """Drop a view.
+
+        The tables it reads are untouched: a view holds no rows of its own.
+        Local connections raise ``NotImplementedError``.
+        """
+        raise NotImplementedError(
+            "View operations are not supported for this connection type"
+        )
+
+    def list_views(self, *, namespace_path: Optional[List[str]] = None) -> List[str]:
+        """The names of the views in one namespace.
+
+        Names only; a definition comes from
+        [describe_view][lancedb.db.DBConnection.describe_view]. Local
+        connections raise ``NotImplementedError``.
+        """
+        raise NotImplementedError(
+            "View operations are not supported for this connection type"
+        )
+
     def open_job(self, job_id: str) -> Job:
         """Open a server-side job by id, returning a handle with its record
         already populated.
@@ -1270,6 +1528,7 @@ class LanceDBConnection(DBConnection):
         select: SelectArg = None,
         where: Optional[str] = None,
         limit: Optional[int] = None,
+        with_no_data: bool = False,
     ) -> MaterializedView:
         """Define a materialized view named ``name`` over the table ``source``.
         See
@@ -1290,17 +1549,44 @@ class LanceDBConnection(DBConnection):
         ...     select=["name", ("shout", "upper(name)")],
         ...     where="age >= 18",
         ... )
-        >>> result = view.refresh()
-        >>> result.rows_written
+        >>> view.table.count_rows()
         1
         """
         LOOP.run(
             self._conn.create_materialized_view(
-                name, source, select=select, where=where, limit=limit
+                name,
+                source,
+                select=select,
+                where=where,
+                limit=limit,
+                with_no_data=with_no_data,
             )
         )
         return MaterializedView(self.open_table(name))
 
+    @override
+    def create_materialized_view_async(
+        self,
+        name: str,
+        source: str,
+        *,
+        select: SelectArg = None,
+        where: Optional[str] = None,
+        limit: Optional[int] = None,
+        with_no_data: bool = False,
+    ) -> Job[None]:
+        job = LOOP.run(
+            self._conn.create_materialized_view_async(
+                name,
+                source,
+                select=select,
+                where=where,
+                limit=limit,
+                with_no_data=with_no_data,
+            )
+        )
+        return Job(job)
+
     @override
     def open_materialized_view(self, name: str) -> MaterializedView:
         """Open the materialized view named ``name``."""
@@ -1313,6 +1599,25 @@ class LanceDBConnection(DBConnection):
         """The names of the materialized views in this database."""
         return LOOP.run(self._conn.list_materialized_views())
 
+    @override
+    def drop_materialized_view(
+        self, name: str, namespace_path: Optional[List[str]] = None
+    ) -> None:
+        if namespace_path is None:
+            namespace_path = []
+        LOOP.run(self._conn.drop_materialized_view(name, namespace_path=namespace_path))
+
+    @override
+    def drop_materialized_view_async(
+        self, name: str, namespace_path: Optional[List[str]] = None
+    ) -> Job[None]:
+        if namespace_path is None:
+            namespace_path = []
+        job = LOOP.run(
+            self._conn.drop_materialized_view_async(name, namespace_path=namespace_path)
+        )
+        return Job(job)
+
     def clone_table(
         self,
         target_table_name: str,
@@ -1457,8 +1762,13 @@ class LanceDBConnection(DBConnection):
         return Job(LOOP.run(self._conn.open_job(job_id)))
 
     @override
-    def create_function_async(self, definition: UdfDefinition) -> Job[FunctionVersion]:
-        job = LOOP.run(self._conn.create_function_async(definition))
+    def create_function_async(
+        self,
+        definition: UdfDefinition,
+        *,
+        secrets: Optional[Sequence[EnvVarSecret]] = None,
+    ) -> Job[FunctionVersion]:
+        job = LOOP.run(self._conn.create_function_async(definition, secrets=secrets))
         return Job(job)
 
     @override
@@ -1473,6 +1783,63 @@ class LanceDBConnection(DBConnection):
     def drop_function(self, name: str, *, version: str) -> bool:
         return LOOP.run(self._conn.drop_function(name, version=version))
 
+    @override
+    def drop_function_async(self, name: str, *, version: str) -> Tuple[bool, Job]:
+        dropped, job = LOOP.run(self._conn.drop_function_async(name, version=version))
+        return dropped, Job(job)
+
+    @override
+    def create_secret(
+        self, name: str, value: str, *, namespace_path: Optional[List[str]] = None
+    ) -> None:
+        LOOP.run(self._conn.create_secret(name, value, namespace_path=namespace_path))
+
+    @override
+    def alter_secret(
+        self, name: str, value: str, *, namespace_path: Optional[List[str]] = None
+    ) -> None:
+        LOOP.run(self._conn.alter_secret(name, value, namespace_path=namespace_path))
+
+    @override
+    def list_secrets(self, *, namespace_path: Optional[List[str]] = None) -> List[str]:
+        return LOOP.run(self._conn.list_secrets(namespace_path=namespace_path))
+
+    @override
+    def drop_secret(
+        self, name: str, *, namespace_path: Optional[List[str]] = None
+    ) -> None:
+        LOOP.run(self._conn.drop_secret(name, namespace_path=namespace_path))
+
+    @override
+    def describe_secret(
+        self, name: str, *, namespace_path: Optional[List[str]] = None
+    ) -> SecretInfo:
+        return LOOP.run(self._conn.describe_secret(name, namespace_path=namespace_path))
+
+    @override
+    def create_view(
+        self, name: str, query: str, *, namespace_path: Optional[List[str]] = None
+    ) -> ViewDescription:
+        return LOOP.run(
+            self._conn.create_view(name, query, namespace_path=namespace_path)
+        )
+
+    @override
+    def describe_view(
+        self, name: str, *, namespace_path: Optional[List[str]] = None
+    ) -> ViewDescription:
+        return LOOP.run(self._conn.describe_view(name, namespace_path=namespace_path))
+
+    @override
+    def drop_view(
+        self, name: str, *, namespace_path: Optional[List[str]] = None
+    ) -> None:
+        LOOP.run(self._conn.drop_view(name, namespace_path=namespace_path))
+
+    @override
+    def list_views(self, *, namespace_path: Optional[List[str]] = None) -> List[str]:
+        return LOOP.run(self._conn.list_views(namespace_path=namespace_path))
+
     @override
     def list_jobs(self) -> List[JobInfo]:
         """List server-side jobs across the database's tables."""
@@ -2080,6 +2447,7 @@ class AsyncConnection(object):
         select: SelectArg = None,
         where: Optional[str] = None,
         limit: Optional[int] = None,
+        with_no_data: bool = False,
     ) -> AsyncMaterializedView:
         """Define a materialized view named ``name`` over the table ``source``.
         See
@@ -2091,19 +2459,40 @@ class AsyncConnection(object):
             projections=normalize_select(select),
             filter=where,
             limit=limit,
+            with_no_data=with_no_data,
         )
         return AsyncMaterializedView(AsyncTable(inner))
 
+    async def create_materialized_view_async(
+        self,
+        name: str,
+        source: str,
+        *,
+        select: SelectArg = None,
+        where: Optional[str] = None,
+        limit: Optional[int] = None,
+        with_no_data: bool = False,
+    ) -> AsyncJob[None]:
+        """Submit materialized-view creation and return its job.
+
+        Wait for the returned job before opening or querying the view.
+        """
+        inner = await self._inner.create_materialized_view_async(
+            name,
+            source,
+            projections=normalize_select(select),
+            filter=where,
+            limit=limit,
+            with_no_data=with_no_data,
+        )
+        return AsyncJob(inner)
+
     async def open_materialized_view(self, name: str) -> AsyncMaterializedView:
         """Open the materialized view named ``name``.
 
         Raises ``ValueError`` if the table exists but is not a materialized
         view.
         """
-        if self.uri.startswith("db://"):
-            raise NotImplementedError(
-                "materialized views are supported only on local databases"
-            )
         view = AsyncMaterializedView(await self.open_table(name))
         await view.definition()
         return view
@@ -2116,6 +2505,41 @@ class AsyncConnection(object):
         """
         return await self._inner.list_materialized_views()
 
+    async def drop_materialized_view(
+        self,
+        name: str,
+        *,
+        namespace_path: Optional[List[str]] = None,
+    ) -> None:
+        """Drop a materialized view.
+
+        The view may become unavailable before physical cleanup finishes. Use
+        :meth:`drop_materialized_view_async` to retain and wait for the cleanup
+        job.
+        """
+        if namespace_path is None:
+            namespace_path = []
+        await self._inner.drop_materialized_view(name, namespace_path=namespace_path)
+
+    async def drop_materialized_view_async(
+        self,
+        name: str,
+        *,
+        namespace_path: Optional[List[str]] = None,
+    ) -> AsyncJob[None]:
+        """Start dropping a materialized view and return its cleanup job.
+
+        Await :meth:`AsyncJob.wait` before assuming physical cleanup has
+        finished.
+        """
+        if namespace_path is None:
+            namespace_path = []
+        return AsyncJob(
+            await self._inner.drop_materialized_view_async(
+                name, namespace_path=namespace_path
+            )
+        )
+
     async def clone_table(
         self,
         target_table_name: str,
@@ -2265,18 +2689,24 @@ class AsyncConnection(object):
         return AsyncJob(await self._inner.open_job(job_id))
 
     async def create_function_async(
-        self, definition: UdfDefinition
+        self,
+        definition: UdfDefinition,
+        *,
+        secrets: Optional[Sequence[EnvVarSecret]] = None,
     ) -> AsyncJob[FunctionVersion]:
-        """Register a scalar Python UDF through the remote Function catalog.
+        """Submit a scalar Python UDF for building and registration.
 
-        The returned typed job resolves to the immutable Function version.
-        Local connections raise ``NotImplementedError``.
+        The server-side job builds the OCI image, then registers the completed
+        artifact. Waiting on the job returns the immutable Function version.
+        ``secrets`` is a sequence of
+        [EnvVarSecret][lancedb.secrets.EnvVarSecret], each naming a Secret and
+        the environment variable its value arrives in. Local connections raise
+        ``NotImplementedError``.
         """
         if not isinstance(definition, UdfDefinition):
             raise TypeError("create_function_async requires a @udf definition")
-        inner = await self._inner.create_function_async(
-            definition.registration_request.to_canonical_json()
-        )
+        request = definition.bind_secrets(secrets)
+        inner = await self._inner.create_function_async(request.to_canonical_json())
         return _typed_job(inner, FunctionVersion.from_json)
 
     async def get_function(self, name: str, *, version: str) -> FunctionVersion:
@@ -2295,9 +2725,111 @@ class AsyncConnection(object):
         ]
 
     async def drop_function(self, name: str, *, version: str) -> bool:
-        """Drop one exact immutable Function version from the remote catalog."""
+        """Drop a Function name and the object it was bound to."""
         return await self._inner.drop_function(name, version)
 
+    async def drop_function_async(
+        self, name: str, *, version: str
+    ) -> Tuple[bool, AsyncJob]:
+        """Drop a Function name and return its cleanup job.
+
+        The name is unbound before this returns; the object's content may still
+        be being deleted. Await :meth:`AsyncJob.wait` to wait for that to
+        finish.
+        """
+        dropped, job = await self._inner.drop_function_async(name, version)
+        return dropped, AsyncJob(job)
+
+    async def create_secret(
+        self, name: str, value: str, *, namespace_path: Optional[List[str]] = None
+    ) -> None:
+        """Create a named Secret in this database.
+
+        Fails if the name is taken, so a create never silently becomes a
+        rotation. Nothing reads the value back.
+        """
+        await self._inner.create_secret(
+            validate_secret_name(name),
+            value,
+            list(validate_namespace_path(namespace_path)),
+        )
+
+    async def alter_secret(
+        self, name: str, value: str, *, namespace_path: Optional[List[str]] = None
+    ) -> None:
+        """Replace the credential behind an existing Secret.
+
+        Fails if it does not exist. Bound Functions use the new value from
+        their next job, with no new Function version.
+        """
+        await self._inner.alter_secret(
+            validate_secret_name(name),
+            value,
+            list(validate_namespace_path(namespace_path)),
+        )
+
+    async def list_secrets(
+        self, *, namespace_path: Optional[List[str]] = None
+    ) -> List[str]:
+        """The names of every Secret in this database. Names only."""
+        return await self._inner.list_secrets(
+            list(validate_namespace_path(namespace_path))
+        )
+
+    async def drop_secret(
+        self, name: str, *, namespace_path: Optional[List[str]] = None
+    ) -> None:
+        """Drop a Secret. Bound Functions fail at their next job."""
+        await self._inner.drop_secret(
+            validate_secret_name(name), list(validate_namespace_path(namespace_path))
+        )
+
+    async def describe_secret(
+        self, name: str, *, namespace_path: Optional[List[str]] = None
+    ) -> SecretInfo:
+        """What this database records about a Secret. Never the value."""
+        name, created_at_millis, updated_at_millis = await self._inner.describe_secret(
+            validate_secret_name(name),
+            list(validate_namespace_path(namespace_path)),
+        )
+        return SecretInfo(
+            name=name,
+            created_at_millis=created_at_millis,
+            updated_at_millis=updated_at_millis,
+        )
+
+    async def create_view(
+        self, name: str, query: str, *, namespace_path: Optional[List[str]] = None
+    ) -> ViewDescription:
+        """Create a view: a named query the database plans on every read.
+
+        See
+        [DBConnection.create_view][lancedb.DBConnection.create_view].
+        """
+        return _view_description(
+            await self._inner.create_view(name, query, list(namespace_path or []))
+        )
+
+    async def describe_view(
+        self, name: str, *, namespace_path: Optional[List[str]] = None
+    ) -> ViewDescription:
+        """What this database records about a view: query and schema."""
+        return _view_description(
+            await self._inner.describe_view(name, list(namespace_path or []))
+        )
+
+    async def drop_view(
+        self, name: str, *, namespace_path: Optional[List[str]] = None
+    ) -> None:
+        """Drop a view. The tables it reads are untouched."""
+        await self._inner.drop_view(name, list(namespace_path or []))
+
+    async def list_views(
+        self, *, namespace_path: Optional[List[str]] = None
+    ) -> List[str]:
+        """The names of the views in one namespace."""
+        return await self._inner.list_views(list(namespace_path or []))
+
     async def list_jobs(self) -> List[JobInfo]:
         """List server-side jobs across the database's tables."""
         return await self._inner.list_jobs()

python/python/lancedb/embeddings/open_clip.py

@@ -7,6 +7,7 @@ import io
 import os
 import urllib.parse as urlparse
 from typing import TYPE_CHECKING, List, Union
+from urllib.request import url2pathname
 
 import numpy as np
 import pyarrow as pa
@@ -154,7 +155,7 @@ class OpenClipEmbeddings(EmbeddingFunction):
             parsed = urlparse.urlparse(image)
             # TODO handle drive letter on windows.
             if parsed.scheme == "file":
-                return PIL_Image.open(parsed.path)
+                return PIL_Image.open(url2pathname(parsed.path))
             elif parsed.scheme == "":
                 return PIL_Image.open(image if os.name == "nt" else parsed.path)
             elif parsed.scheme.startswith("http"):

python/python/lancedb/embeddings/utils.py

@@ -249,7 +249,7 @@ def retry_with_exponential_backoff(
         initial_delay (float): Initial delay in seconds (default is 1).
         exponential_base (float): The base for exponential backoff (default is 2).
         jitter (bool): Whether to add jitter to the delay (default is True).
-        max_retries (int): Maximum number of retries (default is 10).
+        max_retries (int): Maximum number of retries (default is 7).
 
     Returns:
         function: The decorated function.

python/python/lancedb/materialized_view.py

@@ -7,10 +7,11 @@ maintained by refresh. See ``DBConnection.create_materialized_view``."""
 from __future__ import annotations
 
 import json
-from dataclasses import dataclass, field
+from dataclasses import dataclass
 from typing import TYPE_CHECKING, Dict, List, Optional, Sequence, Tuple, Union
 
 from .background_loop import LOOP
+from .job import AsyncJob, Job, _typed_job
 
 if TYPE_CHECKING:
     import pyarrow as pa
@@ -28,22 +29,25 @@ SelectArg = Union[
 ]
 
 
+DEFINITION_FORMAT = 2
+"""The newest stored layout this version reads: ``{"format": N, "query": "<SQL>"}``,
+format 2 being a query with ``GROUP BY``. A ``kind`` key beside it is for
+readers older than the format number."""
+
+
 @dataclass
 class MaterializedViewDefinition:
-    """The query that defines a materialized view."""
+    """The query that defines a materialized view, as stored::
 
-    source_table: str
-    """Name of the source table, in the same database as the view."""
-    projections: List[Tuple[str, str]]
-    """``(output column, SQL expression)`` pairs, in view schema order."""
-    filter: Optional[str] = None
-    """SQL predicate selecting the source rows the view holds."""
-    limit: Optional[int] = None
-    """Cap on the number of rows the view holds."""
-    inputs: List[str] = field(default_factory=list)
-    """Source columns the projections and filter read."""
-    source_namespace: List[str] = field(default_factory=list)
-    """Namespace holding the source table; empty is the root namespace."""
+        SELECT columns
+        FROM [ns.]table [, function(args) AS alias | , UNNEST(column) AS alias]
+        [WHERE predicate] [GROUP BY expr, ...] [LIMIT n]
+
+    A Function in ``FROM`` position yields one row per element it returns.
+    """
+
+    query: str
+    """The defining query, in the canonical spelling the server stores."""
 
 
 def _definition_from_schema(
@@ -53,24 +57,64 @@ def _definition_from_schema(
     raw = metadata.get(DEFINITION_META_KEY)
     if raw is None:
         raise ValueError(f"Table '{name}' is not a materialized view")
-    value = json.loads(raw)
+    return _definition_from_value(json.loads(raw), name)
+
+
+def _definition_from_json(raw: str, name: str = "") -> MaterializedViewDefinition:
+    """Parse the definition native code hands over, in its stored layout."""
+    return _definition_from_value(json.loads(raw), name)
+
+
+def _definition_from_value(value: dict, name: str) -> MaterializedViewDefinition:
+    fmt = value.get("format")
+    if fmt is not None:
+        # A newer writer's layout is reported, never guessed at.
+        if not isinstance(fmt, int) or fmt > DEFINITION_FORMAT:
+            raise NotImplementedError(
+                f"materialized view '{name}' is stored in format {fmt}, which "
+                "this version of lancedb cannot refresh"
+            )
+        return MaterializedViewDefinition(query=value["query"])
+    # The structured layout written before the format number.
     kind = value.get("kind")
-    # "namespaced_select" keeps older readers from resolving the source at root.
     if kind not in ("select", "namespaced_select"):
         raise NotImplementedError(
-            f"materialized view '{name}' is defined by '{kind}', which this "
-            "version of lancedb cannot refresh"
+            f"materialized view '{name}' is stored in format kind '{kind}', "
+            "which this version of lancedb cannot refresh"
         )
-    return MaterializedViewDefinition(
-        source_table=value["source_table"],
-        projections=[
-            (p["output"], p["expression"]) for p in value.get("projections", [])
-        ],
-        filter=value.get("filter"),
-        limit=value.get("limit"),
-        inputs=value.get("inputs", []),
-        source_namespace=value.get("source_namespace", []),
+    return MaterializedViewDefinition(query=_legacy_query(value))
+
+
+def _legacy_ident(name: str) -> str:
+    if name and all(c == "_" or c.islower() or c.isdigit() for c in name):
+        return name
+    return _quote_identifier(name)
+
+
+def _legacy_query(value: dict) -> str:
+    """Render the pre-format structured layout as the query it described."""
+    projections = value.get("projections", [])
+    if projections:
+        items = []
+        for p in projections:
+            output, expression = p["output"], p["expression"]
+            if expression in (output, _quote_identifier(output)):
+                items.append(expression)
+            else:
+                items.append(f"{expression} AS {_legacy_ident(output)}")
+        columns = ", ".join(items)
+    else:
+        columns = "*"
+    table = ".".join(
+        _legacy_ident(part)
+        for part in [*value.get("source_namespace", []), value["source_table"]]
     )
+    query = f"SELECT {columns} FROM {table}"
+    if value.get("filter") is not None:
+        query += f" WHERE {value['filter']}"
+    if value.get("limit") is not None:
+        query += f" LIMIT {value['limit']}"
+    return query
 
 
 def _quote_identifier(name: str) -> str:
@@ -126,8 +170,9 @@ class AsyncMaterializedView:
         return self._table
 
     async def definition(self) -> MaterializedViewDefinition:
-        """The query that defines the view, read from its stored schema."""
-        return _definition_from_schema(await self._table.schema(), self.name)
+        """The query that defines the view."""
+        raw = await self._table._inner.materialized_view_definition()
+        return _definition_from_json(raw)
 
     async def refresh(
         self, *, full: bool = False, source_version: Optional[int] = None
@@ -148,6 +193,24 @@ class AsyncMaterializedView:
             full=full, source_version=source_version
         )
 
+    async def refresh_async(
+        self, *, full: bool = False, source_version: Optional[int] = None
+    ) -> "AsyncJob[RefreshMaterializedViewResult]":
+        """Submit a refresh and return its job without waiting.
+
+        The job may already be complete for a local view. On LanceDB Cloud
+        and Enterprise, its ``id`` is the server job identifier returned by
+        the refresh endpoint.
+        """
+        from ._lancedb import RefreshMaterializedViewResult
+
+        return _typed_job(
+            await self._table._inner.refresh_materialized_view_async(
+                full=full, source_version=source_version
+            ),
+            RefreshMaterializedViewResult.from_json,
+        )
+
 
 class MaterializedView:
     """Synchronous variant of
@@ -171,8 +234,8 @@ class MaterializedView:
 
     @property
     def definition(self) -> MaterializedViewDefinition:
-        """The query that defines the view, read from its stored schema."""
-        return _definition_from_schema(self._table.schema, self.name)
+        """The query that defines the view."""
+        return LOOP.run(self._async.definition())
 
     def refresh(
         self, *, full: bool = False, source_version: Optional[int] = None
@@ -180,3 +243,17 @@ class MaterializedView:
         """Recompute the view from its source. See
         [AsyncMaterializedView.refresh][lancedb.materialized_view.AsyncMaterializedView.refresh]."""
         return LOOP.run(self._async.refresh(full=full, source_version=source_version))
+
+    def refresh_async(
+        self, *, full: bool = False, source_version: Optional[int] = None
+    ) -> "Job[RefreshMaterializedViewResult]":
+        """Submit a refresh and return its job without waiting.
+
+        See
+        [AsyncMaterializedView.refresh_async][lancedb.materialized_view.AsyncMaterializedView.refresh_async].
+        """
+        return Job(
+            LOOP.run(
+                self._async.refresh_async(full=full, source_version=source_version)
+            )
+        )

python/python/lancedb/namespace.py

@@ -637,6 +637,7 @@ class LanceNamespaceDBConnection(DBConnection):
         select: "SelectArg" = None,
         where: Optional[str] = None,
         limit: Optional[int] = None,
+        with_no_data: bool = False,
     ) -> "MaterializedView":
         """Define a materialized view over a table in the root namespace.
         See
@@ -646,12 +647,40 @@ class LanceNamespaceDBConnection(DBConnection):
             self.open_table(
                 LOOP.run(
                     self._inner.create_materialized_view(
-                        name, source, select=select, where=where, limit=limit
+                        name,
+                        source,
+                        select=select,
+                        where=where,
+                        limit=limit,
+                        with_no_data=with_no_data,
                     )
                 ).name
             )
         )
 
+    @override
+    def create_materialized_view_async(
+        self,
+        name: str,
+        source: str,
+        *,
+        select: "SelectArg" = None,
+        where: Optional[str] = None,
+        limit: Optional[int] = None,
+        with_no_data: bool = False,
+    ) -> Job[None]:
+        job = LOOP.run(
+            self._inner.create_materialized_view_async(
+                name,
+                source,
+                select=select,
+                where=where,
+                limit=limit,
+                with_no_data=with_no_data,
+            )
+        )
+        return Job(job)
+
     @override
     def open_materialized_view(self, name: str) -> "MaterializedView":
         """Open the materialized view named ``name``."""
@@ -664,6 +693,30 @@ class LanceNamespaceDBConnection(DBConnection):
         """The names of the materialized views in the root namespace."""
         return LOOP.run(self._inner.list_materialized_views())
 
+    @override
+    def drop_materialized_view(
+        self, name: str, namespace_path: Optional[List[str]] = None
+    ) -> None:
+        if namespace_path is None:
+            namespace_path = []
+        LOOP.run(
+            self._inner.drop_materialized_view(name, namespace_path=namespace_path)
+        )
+
+    @override
+    def drop_materialized_view_async(
+        self, name: str, namespace_path: Optional[List[str]] = None
+    ) -> Job[None]:
+        if namespace_path is None:
+            namespace_path = []
+        return Job(
+            LOOP.run(
+                self._inner.drop_materialized_view_async(
+                    name, namespace_path=namespace_path
+                )
+            )
+        )
+
     @override
     def drop_table(self, name: str, namespace_path: Optional[List[str]] = None):
         if namespace_path is None:
@@ -1194,15 +1247,41 @@ class AsyncLanceNamespaceDBConnection:
         select: "SelectArg" = None,
         where: Optional[str] = None,
         limit: Optional[int] = None,
+        with_no_data: bool = False,
     ) -> "AsyncMaterializedView":
         """Define a materialized view over a table in the root namespace."""
         view = await self._inner.create_materialized_view(
-            name, source, select=select, where=where, limit=limit
+            name,
+            source,
+            select=select,
+            where=where,
+            limit=limit,
+            with_no_data=with_no_data,
         )
         # Reopen through the namespace so the view's table carries the
         # namespace client and pushdown configuration a bare inner table lacks.
         return AsyncMaterializedView(await self.open_table(view.name))
 
+    async def create_materialized_view_async(
+        self,
+        name: str,
+        source: str,
+        *,
+        select: "SelectArg" = None,
+        where: Optional[str] = None,
+        limit: Optional[int] = None,
+        with_no_data: bool = False,
+    ) -> AsyncJob[None]:
+        """Submit materialized-view creation and return its job."""
+        return await self._inner.create_materialized_view_async(
+            name,
+            source,
+            select=select,
+            where=where,
+            limit=limit,
+            with_no_data=with_no_data,
+        )
+
     async def open_materialized_view(self, name: str) -> "AsyncMaterializedView":
         """Open the materialized view named ``name``."""
         view = AsyncMaterializedView(await self.open_table(name))
@@ -1213,6 +1292,24 @@ class AsyncLanceNamespaceDBConnection:
         """The names of the materialized views in the root namespace."""
         return await self._inner.list_materialized_views()
 
+    async def drop_materialized_view(
+        self, name: str, namespace_path: Optional[List[str]] = None
+    ) -> None:
+        """Drop a materialized view from the namespace."""
+        if namespace_path is None:
+            namespace_path = []
+        await self._inner.drop_materialized_view(name, namespace_path=namespace_path)
+
+    async def drop_materialized_view_async(
+        self, name: str, namespace_path: Optional[List[str]] = None
+    ) -> AsyncJob[None]:
+        """Start dropping a materialized view and return its cleanup job."""
+        if namespace_path is None:
+            namespace_path = []
+        return await self._inner.drop_materialized_view_async(
+            name, namespace_path=namespace_path
+        )
+
     async def drop_table(self, name: str, namespace_path: Optional[List[str]] = None):
         """Drop a table from the namespace."""
         if namespace_path is None:

python/python/lancedb/remote/__init__.py

@@ -9,7 +9,13 @@ from typing import List, Optional
 from lancedb import __version__
 
 from .header import HeaderProvider
-from .oauth import OAuthConfig, OAuthFlowType
+from .oauth import (
+    ClientAuthMethod,
+    OAuthConfig,
+    OAuthFlowType,
+    OAuthSession,
+    TokenCacheOptions,
+)
 
 # The API reference renders this module with a single mkdocstrings directive,
 # which only picks up names listed here. New public names must be added to this
@@ -22,6 +28,9 @@ __all__ = [
     "HeaderProvider",
     "OAuthConfig",
     "OAuthFlowType",
+    "ClientAuthMethod",
+    "OAuthSession",
+    "TokenCacheOptions",
 ]
 
 
@@ -164,7 +173,10 @@ class ClientConfig:
     extra_headers: Optional[dict]
         Additional headers to include in requests.
     id_delimiter: Optional[str]
-        The delimiter to use when constructing object identifiers.
+        The delimiter joining a namespace path and a name into one object
+        identifier. ``"$"`` is the only supported value, and leaving this
+        unset is how to get it; anything else is rejected when the connection
+        is created.
     tls_config: Optional[TlsConfig]
         TLS/mTLS configuration for secure connections.
     header_provider: Optional[HeaderProvider]

python/python/lancedb/remote/db.py

@@ -2,12 +2,23 @@
 # SPDX-FileCopyrightText: Copyright The LanceDB Authors
 
 
+from dataclasses import replace
 from datetime import timedelta
 import json
 import logging
 from concurrent.futures import ThreadPoolExecutor
 import sys
-from typing import TYPE_CHECKING, Any, Dict, Iterable, List, Optional, Union
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Dict,
+    Iterable,
+    List,
+    Optional,
+    Sequence,
+    Tuple,
+    Union,
+)
 from urllib.parse import urlparse
 from uuid import UUID
 import warnings
@@ -29,6 +40,8 @@ from ..job import AsyncJob, Job
 from ..sql import Query as SqlQuery
 from ..sql import QueryDescription
 from ..materialized_view import MaterializedView, SelectArg
+from ..secrets import EnvVarSecret, SecretInfo
+from ..view import ViewDescription
 
 if TYPE_CHECKING:
     from .._lancedb import JobInfo
@@ -187,11 +200,51 @@ class RemoteDBConnection(DBConnection):
             )
         )
 
+    @classmethod
+    def _from_catalog(
+        cls,
+        inner,
+        name,
+        endpoint,
+        api_key,
+        client_config,
+        oauth_config,
+        sql_host_override,
+    ):
+        config = (
+            ClientConfig(**client_config)
+            if isinstance(client_config, dict)
+            else (client_config or ClientConfig())
+        )
+        headers = {
+            key: value
+            for key, value in (config.extra_headers or {}).items()
+            if key.lower() not in ("x-lancedb-database", "x-lancedb-database-prefix")
+        }
+        headers["x-lancedb-database"] = name
+        result = cls.__new__(cls)
+        result.db_url = inner.uri
+        result.db_name = name
+        result.api_key = api_key or ""
+        result.region = "us-east-1"
+        result.host_override = endpoint
+        result.sql_host_override = sql_host_override
+        result.storage_options = None
+        result.client_config = replace(config, extra_headers=headers)
+        result._catalog_oauth = oauth_config is not None
+        result._conn = inner
+        return result
+
     def __repr__(self) -> str:
         return f"RemoteConnect(name={self.db_name})"
 
     @override
     def serialize(self) -> str:
+        if getattr(self, "_catalog_oauth", False):
+            raise ValueError(
+                "Cannot serialize a catalog connection using OAuth; "
+                "provide a worker-side connection factory"
+            )
         return json.dumps(
             {
                 "connection_type": "remote",
@@ -665,22 +718,80 @@ class RemoteDBConnection(DBConnection):
         select: SelectArg = None,
         where: Optional[str] = None,
         limit: Optional[int] = None,
+        with_no_data: bool = False,
     ) -> MaterializedView:
-        raise NotImplementedError(
-            "materialized views are supported only on local databases"
+        from .table import RemoteTable
+
+        view = LOOP.run(
+            self._conn.create_materialized_view(
+                name,
+                source,
+                select=select,
+                where=where,
+                limit=limit,
+                with_no_data=with_no_data,
+            )
         )
+        return MaterializedView(
+            RemoteTable(
+                view.table,
+                self.db_name,
+                connection_state=self.serialize,
+                namespace_path=[],
+            )
+        )
+
+    @override
+    def create_materialized_view_async(
+        self,
+        name: str,
+        source: str,
+        *,
+        select: SelectArg = None,
+        where: Optional[str] = None,
+        limit: Optional[int] = None,
+        with_no_data: bool = False,
+    ) -> Job[None]:
+        job = LOOP.run(
+            self._conn.create_materialized_view_async(
+                name,
+                source,
+                select=select,
+                where=where,
+                limit=limit,
+                with_no_data=with_no_data,
+            )
+        )
+        return Job(job)
 
     @override
     def open_materialized_view(self, name: str) -> MaterializedView:
-        raise NotImplementedError(
-            "materialized views are supported only on local databases"
-        )
+        view = MaterializedView(self.open_table(name))
+        view.definition
+        return view
 
     @override
     def list_materialized_views(self) -> List[str]:
-        raise NotImplementedError(
-            "materialized views are supported only on local databases"
+        return LOOP.run(self._conn.list_materialized_views())
+
+    @override
+    def drop_materialized_view(
+        self, name: str, namespace_path: Optional[List[str]] = None
+    ) -> None:
+        if namespace_path is None:
+            namespace_path = []
+        LOOP.run(self._conn.drop_materialized_view(name, namespace_path=namespace_path))
+
+    @override
+    def drop_materialized_view_async(
+        self, name: str, namespace_path: Optional[List[str]] = None
+    ) -> Job[None]:
+        if namespace_path is None:
+            namespace_path = []
+        job = LOOP.run(
+            self._conn.drop_materialized_view_async(name, namespace_path=namespace_path)
         )
+        return Job(job)
 
     @override
     def drop_table(self, name: str, namespace_path: Optional[List[str]] = None):
@@ -746,8 +857,14 @@ class RemoteDBConnection(DBConnection):
         return Job(LOOP.run(self._conn.open_job(job_id)))
 
     @override
-    def create_function_async(self, definition: UdfDefinition) -> Job[FunctionVersion]:
-        return Job(LOOP.run(self._conn.create_function_async(definition)))
+    def create_function_async(
+        self,
+        definition: UdfDefinition,
+        *,
+        secrets: Optional[Sequence[EnvVarSecret]] = None,
+    ) -> Job[FunctionVersion]:
+        job = LOOP.run(self._conn.create_function_async(definition, secrets=secrets))
+        return Job(job)
 
     @override
     def get_function(self, name: str, *, version: str) -> FunctionVersion:
@@ -761,6 +878,63 @@ class RemoteDBConnection(DBConnection):
     def drop_function(self, name: str, *, version: str) -> bool:
         return LOOP.run(self._conn.drop_function(name, version=version))
 
+    @override
+    def drop_function_async(self, name: str, *, version: str) -> Tuple[bool, Job]:
+        dropped, job = LOOP.run(self._conn.drop_function_async(name, version=version))
+        return dropped, Job(job)
+
+    @override
+    def create_secret(
+        self, name: str, value: str, *, namespace_path: Optional[List[str]] = None
+    ) -> None:
+        LOOP.run(self._conn.create_secret(name, value, namespace_path=namespace_path))
+
+    @override
+    def alter_secret(
+        self, name: str, value: str, *, namespace_path: Optional[List[str]] = None
+    ) -> None:
+        LOOP.run(self._conn.alter_secret(name, value, namespace_path=namespace_path))
+
+    @override
+    def describe_secret(
+        self, name: str, *, namespace_path: Optional[List[str]] = None
+    ) -> SecretInfo:
+        return LOOP.run(self._conn.describe_secret(name, namespace_path=namespace_path))
+
+    @override
+    def list_secrets(self, *, namespace_path: Optional[List[str]] = None) -> List[str]:
+        return LOOP.run(self._conn.list_secrets(namespace_path=namespace_path))
+
+    @override
+    def drop_secret(
+        self, name: str, *, namespace_path: Optional[List[str]] = None
+    ) -> None:
+        LOOP.run(self._conn.drop_secret(name, namespace_path=namespace_path))
+
+    @override
+    def create_view(
+        self, name: str, query: str, *, namespace_path: Optional[List[str]] = None
+    ) -> ViewDescription:
+        return LOOP.run(
+            self._conn.create_view(name, query, namespace_path=namespace_path)
+        )
+
+    @override
+    def describe_view(
+        self, name: str, *, namespace_path: Optional[List[str]] = None
+    ) -> ViewDescription:
+        return LOOP.run(self._conn.describe_view(name, namespace_path=namespace_path))
+
+    @override
+    def drop_view(
+        self, name: str, *, namespace_path: Optional[List[str]] = None
+    ) -> None:
+        LOOP.run(self._conn.drop_view(name, namespace_path=namespace_path))
+
+    @override
+    def list_views(self, *, namespace_path: Optional[List[str]] = None) -> List[str]:
+        return LOOP.run(self._conn.list_views(namespace_path=namespace_path))
+
     @override
     def list_jobs(self) -> List["JobInfo"]:
         """List server-side jobs across the database's tables."""

python/python/lancedb/remote/oauth.py

@@ -12,10 +12,72 @@ class OAuthFlowType(str, Enum):
     CLIENT_CREDENTIALS = "client_credentials"
     """Client Credentials grant (service-to-service / M2M)."""
 
+    AUTHORIZATION_CODE = "authorization_code"
+    """Interactive Authorization Code grant, using PKCE by default."""
+
+    DEVICE_CODE = "device_code"
+    """Device Authorization grant for CLI and headless environments."""
+
     AZURE_MANAGED_IDENTITY = "azure_managed_identity"
     """Azure Managed Identity via IMDS."""
 
 
+class ClientAuthMethod(str, Enum):
+    """How the client authenticates to the OAuth token endpoint.
+
+    The method applies to every OAuth request that carries client
+    authentication: client-credentials, authorization-code exchange,
+    refresh-token, and device-authorization requests. The Azure managed
+    identity flow ignores this option.
+    """
+
+    NONE = "none"
+    """No client authentication, for public clients using PKCE or the device
+    flow. Cannot be combined with ``client_secret``."""
+
+    CLIENT_SECRET_BASIC = "client_secret_basic"
+    """HTTP Basic authentication. This is the RFC 6749 recommended method and
+    the normal default for confidential clients, including default Okta
+    applications. Requires ``client_secret``."""
+
+    CLIENT_SECRET_POST = "client_secret_post"
+    """Credentials in the request body, for providers configured to require
+    it. Requires ``client_secret``."""
+
+
+@dataclass
+class TokenCacheOptions:
+    """Options for the persistent OAuth token cache.
+
+    The cache is opt-in: it is only used when set as ``token_cache`` on
+    :class:`OAuthConfig`. Only refresh tokens are persisted, in a private
+    directory with owner-only permissions, so short-lived processes can reuse
+    an authenticated session instead of re-prompting on every start.
+
+    Parameters
+    ----------
+    cache_dir : Optional[str]
+        Directory that holds cached credentials. Defaults to
+        ``$XDG_CACHE_HOME/lancedb/oauth``, ``$HOME/.cache/lancedb/oauth`` on
+        Unix, or ``%LOCALAPPDATA%\\lancedb\\oauth`` on Windows. The directory
+        is created with owner-only permissions (``0700``) when missing.
+    lock_timeout_secs : Optional[int]
+        How long to wait for the cross-process refresh lock before failing
+        (default: 30 seconds).
+
+    Examples
+    --------
+    >>> opts = TokenCacheOptions(cache_dir="/tmp/my-app/oauth-cache")
+
+    Multiple identities (issuer, client, scopes, flow, client
+    authentication) get separate cache entries. Within one identity the most
+    recent login wins.
+    """
+
+    cache_dir: Optional[str] = None
+    lock_timeout_secs: Optional[int] = None
+
+
 @dataclass
 class OAuthConfig:
     """OAuth configuration for LanceDB authentication.
@@ -38,12 +100,37 @@ class OAuthConfig:
         Authentication flow to use. Default: CLIENT_CREDENTIALS.
     client_secret : Optional[str]
         Client secret (required for CLIENT_CREDENTIALS).
+    client_auth_method : Optional[ClientAuthMethod]
+        How the client authenticates to the token endpoint (default: auto).
+        With a ``client_secret`` the default is
+        ``ClientAuthMethod.CLIENT_SECRET_BASIC``, which matches the RFC 6749
+        recommendation and the default configuration of Okta confidential
+        applications; without a secret the client is public and no client
+        authentication is sent.
+    redirect_uri : Optional[str]
+        Loopback redirect URI for AUTHORIZATION_CODE. The default is
+        ``http://127.0.0.1:{callback_port}/callback``.
+    callback_port : Optional[int]
+        Port for the AUTHORIZATION_CODE loopback callback server (default: 8400).
+    use_pkce : bool
+        Protect AUTHORIZATION_CODE with S256 PKCE (default: True).
     managed_identity_client_id : Optional[str]
         Client ID for user-assigned managed identity (AZURE_MANAGED_IDENTITY).
+    resource : Optional[str]
+        Resource indicator (RFC 8707), forwarded verbatim to authorization and
+        token endpoints, including refresh requests. Must be an absolute URI
+        without a fragment. Not supported for Azure managed identity.
+    audience : Optional[str]
+        Provider-specific audience, forwarded to authorization and token
+        endpoints, including refresh requests. Not supported for Azure managed identity.
     refresh_buffer_secs : Optional[int]
         Seconds before expiry to trigger proactive refresh (default: 300).
         Keep this well below the token TTL; if it is greater than or equal to
         the TTL, each request refreshes the token.
+    token_cache : Optional[TokenCacheOptions]
+        Opt in to the persistent token cache so short-lived processes reuse
+        one session. Only supported by AUTHORIZATION_CODE and DEVICE_CODE;
+        azure managed identity is rejected. Default: None (memory only).
 
     Examples
     --------
@@ -56,6 +143,12 @@ class OAuthConfig:
     ...     scopes=["api://lancedb-api/.default"],
     ... )
 
+    Providers that require an explicit target can use ``resource`` and/or
+    ``audience`` (these are forwarded unchanged):
+
+    >>> config.resource = "https://api.example.com"
+    >>> config.audience = "lancedb-api"
+
     Azure Managed Identity:
 
     >>> config = OAuthConfig(
@@ -64,6 +157,30 @@ class OAuthConfig:
     ...     scopes=["api://lancedb-api/.default"],
     ...     flow=OAuthFlowType.AZURE_MANAGED_IDENTITY,
     ... )
+
+    Authorization Code with PKCE:
+
+    The authorization URL is written to standard error before LanceDB tries to
+    open a browser, so it can be copied in headless environments.
+
+    >>> config = OAuthConfig(
+    ...     issuer_url="https://login.microsoftonline.com/{tenant}/v2.0",
+    ...     client_id="app-id",
+    ...     scopes=["openid", "api://lancedb-api/access"],
+    ...     flow=OAuthFlowType.AUTHORIZATION_CODE,
+    ... )
+
+    Device Authorization, with a persistent cache so later processes reuse
+    the session without a new device prompt. The verification URL and user
+    code are written to standard error before polling begins:
+
+    >>> config = OAuthConfig(
+    ...     issuer_url="https://login.microsoftonline.com/{tenant}/v2.0",
+    ...     client_id="app-id",
+    ...     scopes=["openid", "offline_access", "api://lancedb-api/access"],
+    ...     flow=OAuthFlowType.DEVICE_CODE,
+    ...     token_cache=TokenCacheOptions(),
+    ... )
     """
 
     issuer_url: str
@@ -71,5 +188,73 @@ class OAuthConfig:
     scopes: List[str]
     flow: OAuthFlowType = OAuthFlowType.CLIENT_CREDENTIALS
     client_secret: Optional[str] = field(default=None, repr=False)
+    client_auth_method: Optional[ClientAuthMethod] = None
+    redirect_uri: Optional[str] = None
+    callback_port: Optional[int] = None
+    use_pkce: bool = True
     managed_identity_client_id: Optional[str] = None
     refresh_buffer_secs: Optional[int] = None
+    token_cache: Optional[TokenCacheOptions] = None
+    resource: Optional[str] = None
+    audience: Optional[str] = None
+
+
+class OAuthSession:
+    """Explicit OAuth session lifecycle for the persistent token cache.
+
+    Built from the same :class:`OAuthConfig` used for
+    :func:`lancedb.connect_async` (including its ``token_cache`` options).
+    A connection created with the same configuration shares the cache, so
+    logging in here prepares tokens for later processes without any database
+    request.
+
+    ``login`` always runs the configured interactive flow and replaces the
+    cached session (the most recent login wins). ``logout`` removes only the
+    local credential; it does not revoke anything with the provider and does
+    not sign out of a browser SSO session.
+
+    Examples
+    --------
+    >>> config = OAuthConfig(
+    ...     issuer_url="https://issuer.example.com",
+    ...     client_id="my-app",
+    ...     scopes=["openid", "offline_access"],
+    ...     flow=OAuthFlowType.DEVICE_CODE,
+    ...     token_cache=TokenCacheOptions(),
+    ... )
+    >>> session = OAuthSession(config)  # doctest: +SKIP
+    >>> status = await session.login()  # doctest: +SKIP
+    >>> status.refreshable  # doctest: +SKIP
+    True
+    """
+
+    def __init__(self, config: OAuthConfig):
+        from lancedb._lancedb import OAuthSession as PyOAuthSession
+
+        self._inner: PyOAuthSession = PyOAuthSession(config)
+
+    async def login(self):
+        """Eagerly run the configured flow and store the session.
+
+        Returns a :class:`lancedb._lancedb.SessionStatus` describing the
+        cached session. A successful login always replaces any prior cached
+        session for this identity; if the provider does not issue a refresh
+        token (for example without ``offline_access``), the previous record
+        is removed and ``refreshable`` is ``False``.
+        """
+        return await self._inner.login()
+
+    async def status(self):
+        """Report whether a cached session exists, with safe metadata.
+
+        Never contacts the identity provider and never exposes token values.
+        """
+        return await self._inner.status()
+
+    async def logout(self):
+        """Remove the matching local cached credential.
+
+        Returns a :class:`lancedb._lancedb.SessionLogout` whose ``removed``
+        flag reports whether a credential existed. Logout is idempotent.
+        """
+        return await self._inner.logout()

python/python/lancedb/remote/table.py

@@ -982,6 +982,9 @@ class RemoteTable(Table):
         self,
         transforms: Dict[str, str | FunctionApplication]
         | FunctionApplication
+        | pa.Field
+        | List[pa.Field]
+        | pa.Schema
         | None = None,
         *,
         computed: Dict[str, str] | None = None,
@@ -994,6 +997,16 @@ class RemoteTable(Table):
     def refresh_column_async(self, column: str) -> Job[RefreshColumnResult]:
         return Job(LOOP.run(self._table.refresh_column_async(column)))
 
+    def function_errors(
+        self,
+        job_id: Optional[str] = None,
+        column: Optional[str] = None,
+        limit: Optional[int] = None,
+    ):
+        return LOOP.run(
+            self._table.function_errors(job_id=job_id, column=column, limit=limit)
+        )
+
     def alter_columns(
         self, *alterations: Iterable[Dict[str, str]]
     ) -> AlterColumnsResult:

python/python/lancedb/rerankers/__init__.py

@@ -11,6 +11,7 @@ from .jinaai import JinaReranker
 from .rrf import RRFReranker
 from .mrr import MRRReranker
 from .answerdotai import AnswerdotaiRerankers
+from .typesafe import TypeSafeReranker
 from .voyageai import VoyageAIReranker
 from .watsonx import WatsonxReranker
 
@@ -27,6 +28,7 @@ __all__ = [
     "JinaReranker",
     "RRFReranker",
     "AnswerdotaiRerankers",
+    "TypeSafeReranker",
     "VoyageAIReranker",
     "MRRReranker",
     "WatsonxReranker",

python/python/lancedb/rerankers/typesafe.py

@@ -0,0 +1,159 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright The LanceDB Authors
+
+
+from concurrent.futures import ThreadPoolExecutor
+from functools import cached_property
+from typing import Any, Dict, Mapping, Optional
+
+import pyarrow as pa
+
+from ..util import attempt_import_or_raise
+from .base import Reranker
+
+DEFAULT_INSTRUCTIONS = (
+    "Does the document contain information that answers or directly addresses "
+    "the query?"
+)
+DEFAULT_CRITERIA = {
+    "true": "The document answers the query or states facts the query asks about.",
+    "false": "The document is off-topic, or only shares keywords or a general "
+    "subject with the query without addressing it.",
+}
+# The key TypeSafe returns the answer under. It is not sent to the model.
+_QUESTION_ID = "relevance"
+
+
+class TypeSafeReranker(Reranker):
+    """
+    Reranks the results using the TypeSafe System One API.
+    https://docs.typesafe.ai/cookbooks/rerank_typesafe
+
+    Each result is scored independently: TypeSafe reads the query together with
+    the result's ``column`` value and answers a yes/no ("noul") question about
+    whether the document is relevant. The probability of "yes", between 0 and 1,
+    becomes the ``_relevance_score``. Because every score is an absolute
+    probability rather than a position in the list, scores are comparable
+    across queries and can be thresholded. They are model estimates, though,
+    and can vary slightly between identical calls, so results with close scores
+    may swap places when the same search is repeated.
+
+    One request is sent per result, up to ``max_concurrency`` at a time.
+
+    Parameters
+    ----------
+    model_name : str, default "jev-latest"
+        The TypeSafe model to use.
+    column : str, default "text"
+        The name of the column holding the document text to score.
+    instructions : str, optional
+        The yes/no question asked about each query and document pair. The state
+        TypeSafe reads is ``{"query": <query>, "document": <column value>}``.
+        Defaults to a generic relevance question.
+    criteria : Mapping[str, str], optional
+        What a "yes" and a "no" mean, as a mapping with the keys ``"true"`` and
+        ``"false"``. Domain-specific criteria usually rank better than the
+        generic default. Pass an empty mapping to send no criteria.
+    return_score : str, default "relevance"
+        Options are "relevance" or "all". If "all", keeps the vector and FTS
+        scores alongside the relevance score.
+    api_key : str, optional
+        The API key to use. If None, the TypeSafe SDK reads the
+        ``TYPESAFE_API_KEY`` environment variable.
+    max_concurrency : int, default 8
+        The maximum number of TypeSafe requests in flight for one rerank call.
+    """
+
+    def __init__(
+        self,
+        model_name: str = "jev-latest",
+        column: str = "text",
+        instructions: Optional[str] = None,
+        criteria: Optional[Mapping[str, str]] = None,
+        return_score: str = "relevance",
+        api_key: Optional[str] = None,
+        max_concurrency: int = 8,
+    ):
+        super().__init__(return_score)
+        if max_concurrency < 1:
+            raise ValueError("max_concurrency must be at least 1")
+        criteria = DEFAULT_CRITERIA if criteria is None else dict(criteria)
+        unknown = set(criteria) - {"true", "false"}
+        if unknown:
+            raise ValueError(
+                f"criteria keys must be 'true' or 'false', got {sorted(unknown)}"
+            )
+        self.model_name = model_name
+        self.column = column
+        self.instructions = instructions or DEFAULT_INSTRUCTIONS
+        self.criteria = criteria
+        self.api_key = api_key
+        self.max_concurrency = max_concurrency
+
+    def __str__(self):
+        return f"TypeSafeReranker(model_name={self.model_name})"
+
+    @cached_property
+    def _client(self):
+        typesafe_sdk = attempt_import_or_raise("typesafe_sdk", "typesafe-sdk")
+        return typesafe_sdk.TypeSafeClient(api_key=self.api_key)
+
+    @cached_property
+    def _question(self) -> Dict[str, Any]:
+        question: Dict[str, Any] = {"type": "noul", "instructions": self.instructions}
+        if self.criteria:
+            question["criteria"] = self.criteria
+        return question
+
+    def _score(self, query: str, document: Optional[str]) -> float:
+        if document is None:
+            return 0.0
+        response = self._client.system_one(
+            state={"query": query, "document": document},
+            questions={_QUESTION_ID: self._question},
+            model=self.model_name,
+        )
+        return response.answers[_QUESTION_ID].noul
+
+    def _rerank(self, result_set: pa.Table, query: str) -> pa.Table:
+        result_set = self._handle_empty_results(result_set)
+        if len(result_set) == 0:
+            return result_set
+        docs = result_set[self.column].to_pylist()
+        # Rerankers are also called synchronously from inside the async query
+        # APIs, so the requests run on threads rather than on an event loop.
+        with ThreadPoolExecutor(
+            max_workers=min(self.max_concurrency, len(docs))
+        ) as pool:
+            scores = list(pool.map(lambda doc: self._score(query, doc), docs))
+        result_set = result_set.append_column(
+            "_relevance_score", pa.array(scores, type=pa.float32())
+        )
+        return result_set.sort_by([("_relevance_score", "descending")])
+
+    def rerank_hybrid(
+        self,
+        query: str,
+        vector_results: pa.Table,
+        fts_results: pa.Table,
+    ):
+        if self.score == "all":
+            combined_results = self._merge_and_keep_scores(vector_results, fts_results)
+        else:
+            combined_results = self.merge_results(vector_results, fts_results)
+        combined_results = self._rerank(combined_results, query)
+        if self.score == "relevance":
+            combined_results = self._keep_relevance_score(combined_results)
+        return combined_results
+
+    def rerank_vector(self, query: str, vector_results: pa.Table):
+        vector_results = self._rerank(vector_results, query)
+        if self.score == "relevance":
+            vector_results = vector_results.drop_columns(["_distance"])
+        return vector_results
+
+    def rerank_fts(self, query: str, fts_results: pa.Table):
+        fts_results = self._rerank(fts_results, query)
+        if self.score == "relevance":
+            fts_results = fts_results.drop_columns(["_score"])
+        return fts_results

python/python/lancedb/secrets.py

@@ -0,0 +1,226 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright The LanceDB Authors
+
+"""Named Secrets, and the bindings that deliver them to Functions.
+
+A Secret is a database-scoped named credential. Nothing in this module holds a
+value: :class:`EnvVarSecret` names one and says which environment variable it
+should arrive in, and the value is resolved by the remote service when a
+Function bound to it runs. No API returns a stored credential, by construction
+rather than by policy -- there is no code path that could.
+"""
+
+from __future__ import annotations
+
+import re
+
+# The same characters LanceDB already admits in a namespace or table name, and
+# no positional rule on top of them: a segment may begin with `_`, `-` or `.`
+# today, so anything narrower would put Secrets out of reach inside namespaces
+# that already exist. Matches the service, which admits the same set.
+_SECRET_NAME = re.compile(r"^[A-Za-z0-9_.-]{1,255}$")
+_ENV_VARIABLE = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
+
+
+def validate_secret_name(name: str) -> str:
+    """Check a Secret name locally and return it unchanged."""
+    if not isinstance(name, str):
+        raise TypeError(f"Secret name must be a string, not {type(name).__name__}")
+    if not _SECRET_NAME.fullmatch(name):
+        raise ValueError(f"invalid Secret name: {name!r}")
+    return name
+
+
+def validate_namespace_path(namespace_path=None):
+    """Check a namespace path locally and return it as a tuple.
+
+    ``None`` and ``[]`` both mean the root namespace. Segments follow the same
+    rule as Secret names: a binding carries the path and the name as separate
+    fields, so neither is ever parsed out of the other.
+    """
+    if namespace_path is None:
+        return ()
+    if isinstance(namespace_path, str):
+        raise TypeError(
+            "namespace_path must be a list of segments, not a string; "
+            f"did you mean [{namespace_path!r}]?"
+        )
+    segments = tuple(namespace_path)
+    for segment in segments:
+        if not isinstance(segment, str):
+            raise TypeError(
+                f"namespace path segment must be a string, not {type(segment).__name__}"
+            )
+        if not _SECRET_NAME.fullmatch(segment):
+            raise ValueError(f"invalid namespace path segment: {segment!r}")
+    return segments
+
+
+def validate_env_variable(name: str) -> str:
+    """Check an environment variable name locally and return it unchanged."""
+    if not isinstance(name, str):
+        raise TypeError(
+            f"environment variable name must be a string, not {type(name).__name__}"
+        )
+    if not _ENV_VARIABLE.fullmatch(name):
+        raise ValueError(f"invalid environment variable name: {name!r}")
+    return name
+
+
+class EnvVarSecret:
+    """A Secret bound to the environment variable a Function's library reads.
+
+    Pass these in the ``secrets`` sequence of
+    [DBConnection.create_function][lancedb.db.DBConnection.create_function]. The
+    Function's source is unchanged by binding: it reads ``OPENAI_API_KEY`` the
+    way it always did, and the binding is what puts a value there.
+
+    This is a local value. Constructing it contacts no server, so it always
+    succeeds and says nothing about whether the Secret exists; that is checked
+    at registration, where a mistyped Secret name surfaces as a clear "does not
+    exist" naming both the Secret and the variable bound to it. A mistyped
+    *variable* name cannot be caught anywhere -- nothing knows which variables a
+    Function reads -- so it surfaces on the first rows instead.
+
+    The type exists so a credential cannot be passed by accident. A bare string
+    in the same position is a plausible-looking mistake with the opposite
+    meaning, and it reads identically in a diff.
+
+    Parameters
+    ----------
+    secret_name : str
+        The Secret's database-scoped name.
+    env_variable : str
+        The environment variable the Function reads it from.
+    secret_namespace_path : list of str, optional
+        The namespace the Secret is addressed within. ``None`` and ``[]`` both
+        mean the root namespace. Carried beside the name rather than joined
+        into it, so neither is ever parsed back out of the other.
+
+    Examples
+    --------
+    >>> from lancedb import EnvVarSecret
+    >>> binding = EnvVarSecret(
+    ...     secret_name="openai-prod", env_variable="OPENAI_API_KEY"
+    ... )
+    >>> binding.secret_name, binding.env_variable
+    ('openai-prod', 'OPENAI_API_KEY')
+    """
+
+    __slots__ = ("_secret_name", "_env_variable", "_secret_namespace_path")
+
+    def __init__(
+        self, secret_name: str, env_variable: str, *, secret_namespace_path=None
+    ):
+        self._secret_name = validate_secret_name(secret_name)
+        self._env_variable = validate_env_variable(env_variable)
+        self._secret_namespace_path = validate_namespace_path(secret_namespace_path)
+
+    @property
+    def secret_name(self) -> str:
+        """The Secret's database-scoped name."""
+        return self._secret_name
+
+    @property
+    def env_variable(self) -> str:
+        """The environment variable the value is delivered in."""
+        return self._env_variable
+
+    @property
+    def secret_namespace_path(self):
+        """The namespace path the Secret is addressed within, root when empty."""
+        return list(self._secret_namespace_path)
+
+    def __repr__(self) -> str:
+        path = (
+            f", secret_namespace_path={list(self._secret_namespace_path)!r}"
+            if self._secret_namespace_path
+            else ""
+        )
+        return (
+            f"EnvVarSecret(secret_name={self._secret_name!r}, "
+            f"env_variable={self._env_variable!r}{path})"
+        )
+
+    def __eq__(self, other: object) -> bool:
+        return (
+            isinstance(other, EnvVarSecret)
+            and other._secret_name == self._secret_name
+            and other._env_variable == self._env_variable
+            and other._secret_namespace_path == self._secret_namespace_path
+        )
+
+    def __hash__(self) -> int:
+        return hash(
+            (
+                EnvVarSecret,
+                self._secret_name,
+                self._env_variable,
+                self._secret_namespace_path,
+            )
+        )
+
+
+class SecretInfo:
+    """What a database records about a Secret. Never its value.
+
+    Returned by
+    [DBConnection.describe_secret][lancedb.db.DBConnection.describe_secret].
+    """
+
+    __slots__ = ("_name", "_created_at_millis", "_updated_at_millis")
+
+    def __init__(self, name: str, created_at_millis: int, updated_at_millis: int):
+        self._name = name
+        self._created_at_millis = created_at_millis
+        self._updated_at_millis = updated_at_millis
+
+    @property
+    def name(self) -> str:
+        """The Secret's database-scoped name."""
+        return self._name
+
+    @property
+    def created_at_millis(self) -> int:
+        """When the Secret was created, in milliseconds since the Unix epoch."""
+        return self._created_at_millis
+
+    @property
+    def updated_at_millis(self) -> int:
+        """When the Secret's value was last rotated, in epoch milliseconds.
+
+        The only observable that a rotation landed: no API returns a credential,
+        so a caller confirms ``alter_secret`` took effect by watching this move.
+        """
+        return self._updated_at_millis
+
+    @classmethod
+    def from_json(cls, value: dict) -> "SecretInfo":
+        return cls(
+            name=value["name"],
+            created_at_millis=value["created_at_millis"],
+            updated_at_millis=value["updated_at_millis"],
+        )
+
+    def __repr__(self) -> str:
+        return (
+            f"SecretInfo(name={self._name!r}, "
+            f"created_at_millis={self._created_at_millis!r}, "
+            f"updated_at_millis={self._updated_at_millis!r})"
+        )
+
+    def __eq__(self, other: object) -> bool:
+        return (
+            isinstance(other, SecretInfo)
+            and other._name == self._name
+            and other._created_at_millis == self._created_at_millis
+            and other._updated_at_millis == self._updated_at_millis
+        )
+
+
+__all__ = [
+    "EnvVarSecret",
+    "SecretInfo",
+    "validate_env_variable",
+    "validate_secret_name",
+]

python/python/lancedb/table.py

@@ -5,6 +5,7 @@ from __future__ import annotations
 
 import asyncio
 import inspect
+import json
 import deprecation
 import warnings
 from abc import ABC, abstractmethod
@@ -186,6 +187,7 @@ if TYPE_CHECKING:
         CompactionStats,
         Tag,
         AddColumnsResult,
+        FunctionErrors,
         RefreshColumnResult,
         AddResult,
         AlterColumnsResult,
@@ -265,12 +267,14 @@ def _into_pyarrow_reader(
 
         # convert to list of dict if data is a bunch of LanceModels
         if isinstance(data[0], LanceModel):
-            schema = data[0].__class__.to_arrow_schema()
+            model_schema = data[0].__class__.to_arrow_schema()
             data = [model_to_dict(d) for d in data]
-            return pa.Table.from_pylist(data, schema=schema).to_reader()
+            data = _serialize_json_values(data, schema or model_schema)
+            return pa.Table.from_pylist(data, schema=model_schema).to_reader()
         elif isinstance(data[0], pa.RecordBatch):
             return pa.Table.from_batches(data).to_reader()
         else:
+            data = _serialize_json_values(data, schema)
             return pa.Table.from_pylist(data).to_reader()
     elif _check_for_pandas(data) and isinstance(data, pd.DataFrame):
         table = pa.Table.from_pandas(data, preserve_index=False)
@@ -618,6 +622,108 @@ def _field_extension_name(field: pa.Field) -> Optional[str]:
     return extension_name
 
 
+def _is_json_field(field: pa.Field) -> bool:
+    return _field_extension_name(field) in ("arrow.json", "lance.json")
+
+
+@dataclass(frozen=True)
+class _JsonSerializationPlan:
+    arrow_field: pa.Field
+    children: Optional[Dict[str, "_JsonSerializationPlan"]] = None
+    item: Optional["_JsonSerializationPlan"] = None
+
+
+def _json_serialization_plan(field: pa.Field) -> Optional[_JsonSerializationPlan]:
+    if _is_json_field(field):
+        return _JsonSerializationPlan(field)
+
+    if pa.types.is_struct(field.type):
+        children: Dict[str, _JsonSerializationPlan] = {}
+        for child_field in field.type:
+            child_plan = _json_serialization_plan(child_field)
+            if child_plan is not None:
+                children[child_field.name] = child_plan
+        if children:
+            return _JsonSerializationPlan(field, children=children)
+
+    if _is_list_like(field.type):
+        item_plan = _json_serialization_plan(field.type.value_field)
+        if item_plan is not None:
+            return _JsonSerializationPlan(field, item=item_plan)
+
+    return None
+
+
+def _json_serialization_plans(
+    schema: pa.Schema,
+) -> Dict[str, _JsonSerializationPlan]:
+    plans: Dict[str, _JsonSerializationPlan] = {}
+    for field in schema:
+        plan = _json_serialization_plan(field)
+        if plan is not None:
+            plans[field.name] = plan
+    return plans
+
+
+def _serialize_json_value(value: Any, plan: _JsonSerializationPlan) -> Any:
+    if value is None or isinstance(value, str):
+        return value
+    if _is_json_field(plan.arrow_field):
+        if isinstance(value, (dict, list)):
+            return json.dumps(value)
+        return value
+
+    if plan.children is not None and isinstance(value, dict):
+        serialized = None
+        for child_name, child_plan in plan.children.items():
+            if child_name not in value:
+                continue
+            child_value = _serialize_json_value(value[child_name], child_plan)
+            if child_value is not value[child_name]:
+                if serialized is None:
+                    serialized = dict(value)
+                serialized[child_name] = child_value
+        return serialized if serialized is not None else value
+
+    if plan.item is not None and isinstance(value, list):
+        serialized = None
+        for index, item in enumerate(value):
+            serialized_item = _serialize_json_value(item, plan.item)
+            if serialized_item is not item:
+                if serialized is None:
+                    serialized = list(value)
+                serialized[index] = serialized_item
+        return serialized if serialized is not None else value
+
+    return value
+
+
+def _serialize_json_values(data: Any, target_schema: Optional[pa.Schema]) -> Any:
+    if target_schema is None or not isinstance(data, list):
+        return data
+
+    plans = _json_serialization_plans(target_schema)
+    if not plans:
+        return data
+
+    serialized_rows = []
+    for row in data:
+        if not isinstance(row, dict):
+            serialized_rows.append(row)
+            continue
+        serialized_row = None
+        for field_name, plan in plans.items():
+            if field_name not in row:
+                continue
+            value = _serialize_json_value(row[field_name], plan)
+            if value is not row[field_name]:
+                if serialized_row is None:
+                    serialized_row = dict(row)
+                serialized_row[field_name] = value
+        serialized_rows.append(serialized_row if serialized_row is not None else row)
+    return serialized_rows
+
+
 def _align_field_types(
     fields: List[pa.Field],
     target_fields: List[pa.Field],
@@ -634,26 +740,43 @@ def _align_field_types(
     return new_fields
 
 
-def _align_list_value_field(
-    value_field: pa.Field, target_value_field: pa.Field
-) -> pa.Field:
-    # A list has exactly one child, so the inferred child name ("item") aligns
-    # positionally and adopts the table's child name; pa.Table.cast renames it.
-    return _align_field(value_field, target_value_field).with_name(
-        target_value_field.name
-    )
+def _align_container_child(child: pa.Field, target_child: pa.Field) -> pa.Field:
+    # A list has one child, a map one key and one item, so an inferred child name
+    # ("item") aligns positionally and adopts the table's; pa.Table.cast renames it.
+    return _align_field(child, target_child).with_name(target_child.name)
+
+
+def _arrow_json_storage_type(input_type: pa.DataType) -> Optional[pa.DataType]:
+    """The storage type arrow.json would use for ``input_type``.
+
+    Returns None if the type cannot hold JSON text.
+    """
+    if pa.types.is_string(input_type) or pa.types.is_string_view(input_type):
+        return pa.string()
+    if pa.types.is_large_string(input_type):
+        return pa.large_string()
+    return None
 
 
 def _align_field(field: pa.Field, target_field: pa.Field) -> pa.Field:
-    # Preserve arrow.json input until it reaches Lance. LanceDB exposes stored
-    # JSON columns as lance.json (JSONB-backed LargeBinary), but casting the
-    # input to that storage type here merely relabels the raw JSON bytes as
+    # LanceDB exposes stored JSON columns as lance.json (JSONB-backed LargeBinary), but
+    # casting the input to that storage type here merely relabels the raw JSON bytes as
     # JSONB. Lance must see arrow.json so it can perform the JSONB encoding.
-    if (
-        _field_extension_name(field) == "arrow.json"
-        and _field_extension_name(target_field) == "lance.json"
-    ):
-        return field
+    if _field_extension_name(target_field) == "lance.json":
+        if _field_extension_name(field) == "arrow.json":
+            return field
+        # Plain JSON text, which is what pyarrow infers for a column of `str`, only
+        # needs the arrow.json label.
+        json_storage = _arrow_json_storage_type(field.type)
+        if json_storage is not None:
+            # Labelled through metadata rather than pa.json_(), which only exists on
+            # newer PyArrow; Lance reads the extension name off the field either way.
+            return pa.field(
+                field.name,
+                json_storage,
+                field.nullable,
+                {"ARROW:extension:name": "arrow.json"},
+            )
     if pa.types.is_struct(target_field.type):
         if pa.types.is_struct(field.type):
             new_type = pa.struct(
@@ -667,7 +790,7 @@ def _align_field(field: pa.Field, target_field: pa.Field) -> pa.Field:
     elif pa.types.is_list(target_field.type):
         if _is_list_like(field.type):
             new_type = pa.list_(
-                _align_list_value_field(
+                _align_container_child(
                     field.type.value_field, target_field.type.value_field
                 )
             )
@@ -676,7 +799,7 @@ def _align_field(field: pa.Field, target_field: pa.Field) -> pa.Field:
     elif pa.types.is_large_list(target_field.type):
         if _is_list_like(field.type):
             new_type = pa.large_list(
-                _align_list_value_field(
+                _align_container_child(
                     field.type.value_field, target_field.type.value_field
                 )
             )
@@ -685,13 +808,28 @@ def _align_field(field: pa.Field, target_field: pa.Field) -> pa.Field:
     elif pa.types.is_fixed_size_list(target_field.type):
         if _is_list_like(field.type):
             new_type = pa.list_(
-                _align_list_value_field(
+                _align_container_child(
                     field.type.value_field, target_field.type.value_field
                 ),
                 target_field.type.list_size,
             )
         else:
             new_type = target_field.type
+    elif pa.types.is_map(target_field.type):
+        if pa.types.is_map(field.type):
+            # A map has exactly one key and one item field, so like a list's child they
+            # align positionally and adopt the table's names.
+            new_type = pa.map_(
+                _align_container_child(
+                    field.type.key_field, target_field.type.key_field
+                ),
+                _align_container_child(
+                    field.type.item_field, target_field.type.item_field
+                ),
+                keys_sorted=target_field.type.keys_sorted,
+            )
+        else:
+            new_type = target_field.type
     else:
         new_type = target_field.type
     return pa.field(field.name, new_type, field.nullable, target_field.metadata)
@@ -2188,10 +2326,10 @@ class Table(ABC):
             Declaring one therefore costs the same on a large table as on an
             empty one.
 
-            A refresh does not revisit rows it has already filled, so mutating
-            an input leaves the value computed at fill time; recomputing means
-            dropping the column and declaring it again. While a declaration
-            reads a column, that column cannot be renamed, retyped or dropped.
+            A refresh also recomputes the rows whose inputs changed since they
+            were computed, so a mutated input is reflected by the next refresh.
+            While a declaration reads a column, that column cannot be renamed,
+            retyped or dropped.
 
             On LanceDB Cloud and Enterprise the expression is planned by the
             server, and the refresh runs as a server job -- see
@@ -2211,7 +2349,7 @@ class Table(ABC):
         >>> table.add_columns(computed={"doubled": "x * 2"})
         AddColumnsResult(version=2)
         >>> table.refresh_column("doubled")
-        RefreshColumnResult(rows_filled=2, version=3)
+        RefreshColumnResult(rows_filled=2, version=4)
         >>> table.to_arrow().sort_by("x").to_pandas()
            x  doubled
         0  1        2
@@ -2225,8 +2363,8 @@ class Table(ABC):
 
         Declared with ``add_columns(computed=...)``, a column starts empty and
         gets its values here. Rows appended since the last refresh are filled
-        by the next one; rows already filled are left as they are, so the call
-        is idempotent and does not observe a mutated input.
+        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
         [`refresh_column_async`][lancedb.table.Table.refresh_column_async].
@@ -2276,6 +2414,47 @@ class Table(ABC):
         'finished'
         """
 
+    @abstractmethod
+    def function_errors(
+        self,
+        job_id: Optional[str] = None,
+        column: Optional[str] = None,
+        limit: Optional[int] = None,
+    ) -> "FunctionErrors":
+        """
+        The per-row errors Function refreshes recorded on this 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 access to the table, since a message carries the value
+        that failed.
+
+        Parameters
+        ----------
+        job_id: str, optional
+            Only errors recorded by this job.
+        column: str, optional
+            Only errors on this column.
+        limit: int, optional
+            At most this many records (server default 10000, cap 100000).
+
+        Returns
+        -------
+        FunctionErrors
+            ``records``, ``fragments`` and ``truncated``, the last saying
+            whether the listing stopped at its limit.
+
+        Examples
+        --------
+        >>> errors = table.function_errors(column="embedding")  # doctest: +SKIP
+        >>> for record in errors.records:  # doctest: +SKIP
+        ...     print(record.job_id, record.row_offset, record.error_message)
+        >>> if errors.truncated:  # doctest: +SKIP
+        ...     print("listing stopped at the limit")
+        """
+
     @abstractmethod
     def alter_columns(self, *alterations: Iterable[Dict[str, str]]):
         """
@@ -4329,17 +4508,30 @@ class LanceTable(Table):
         return LOOP.run(self._table.add_columns(transforms, computed=computed))
 
     def refresh_column(self, column: str) -> "RefreshColumnResult":
-        """Fill a computed column's unfilled rows. See
+        """Fill a computed column's unfilled rows and recompute those whose
+        inputs changed. See
         [`AsyncTable.refresh_column`][lancedb.AsyncTable.refresh_column]."""
         return LOOP.run(self._table.refresh_column(column))
 
     def refresh_column_async(self, column: str) -> Job[RefreshColumnJobResult]:
-        """Fill a computed column's unfilled rows, returning a handle to the
-        refresh job. See
+        """Fill a computed column's unfilled rows and recompute those whose
+        inputs changed, returning a handle to the refresh job. See
         [`Table.refresh_column_async`][lancedb.table.Table.refresh_column_async].
         """
         return Job(LOOP.run(self._table.refresh_column_async(column)))
 
+    def function_errors(
+        self,
+        job_id: Optional[str] = None,
+        column: Optional[str] = None,
+        limit: Optional[int] = None,
+    ) -> "FunctionErrors":
+        """The per-row errors Function refreshes recorded on this table. See
+        [`Table.function_errors`][lancedb.table.Table.function_errors]."""
+        return LOOP.run(
+            self._table.function_errors(job_id=job_id, column=column, limit=limit)
+        )
+
     def alter_columns(
         self, *alterations: Iterable[Dict[str, str]]
     ) -> AlterColumnsResult:
@@ -5659,6 +5851,7 @@ class AsyncTable:
 
         """
         schema = await self.schema()
+        data = _serialize_json_values(data, schema)
         if on_bad_vectors is None:
             on_bad_vectors = "error"
         if fill_value is None:
@@ -6338,10 +6531,10 @@ class AsyncTable:
             them from
             [`refresh_column`][lancedb.table.AsyncTable.refresh_column].
 
-            A refresh does not revisit rows it has already filled, so mutating
-            an input leaves the value computed at fill time. While a
-            declaration reads a column, that column cannot be renamed, retyped
-            or dropped.
+            A refresh also recomputes the rows whose inputs changed since they
+            were computed, so a mutated input is reflected by the next refresh.
+            While a declaration reads a column, that column cannot be renamed,
+            retyped or dropped.
 
             On LanceDB Cloud and Enterprise the expression is planned by
             the server. Cannot be combined with ``transforms``.
@@ -6403,8 +6596,8 @@ class AsyncTable:
 
         Declared with ``add_columns(computed=...)``, a column starts empty and
         gets its values here. Rows appended since the last refresh are filled
-        by the next one; rows already filled are left as they are, so the call
-        is idempotent and does not observe a mutated input.
+        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
         [`refresh_column_async`][lancedb.table.Table.refresh_column_async].
@@ -6421,6 +6614,49 @@ class AsyncTable:
         """
         return await self._inner.refresh_column(column)
 
+    async def function_errors(
+        self,
+        job_id: Optional[str] = None,
+        column: Optional[str] = None,
+        limit: Optional[int] = None,
+    ) -> "FunctionErrors":
+        """
+        The per-row errors Function refreshes recorded on this 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 access to the table, since a message carries the value
+        that failed.
+
+        Parameters
+        ----------
+        job_id: str, optional
+            Only errors recorded by this job.
+        column: str, optional
+            Only errors on this column.
+        limit: int, optional
+            At most this many records (server default 10000, cap 100000).
+
+        Returns
+        -------
+        FunctionErrors
+            ``records``, ``fragments`` and ``truncated``, the last saying
+            whether the listing stopped at its limit.
+
+        Examples
+        --------
+        >>> errors = await table.function_errors(column="embedding")  # doctest: +SKIP
+        >>> for record in errors.records:  # doctest: +SKIP
+        ...     print(record.job_id, record.row_offset, record.error_message)
+        >>> if errors.truncated:  # doctest: +SKIP
+        ...     print("listing stopped at the limit")
+        """
+        return await self._inner.function_errors(
+            job_id=job_id, column=column, limit=limit
+        )
+
     async def refresh_column_async(
         self, column: str
     ) -> AsyncJob[RefreshColumnJobResult]:

python/python/lancedb/view.py

@@ -0,0 +1,40 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright The LanceDB Authors
+
+"""Views: a named query a database stores and plans on every read.
+
+A view holds no rows. What it stores is the statement that defines it and the
+schema that statement resolved to, so a reader sees the sources as they are
+now. See ``DBConnection.create_view``.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, List
+
+if TYPE_CHECKING:
+    import pyarrow as pa
+
+
+@dataclass(frozen=True)
+class ViewDescription:
+    """What a database records about one view."""
+
+    name: str
+    """The view's name within its namespace."""
+    query: str
+    """The defining query, as the database stores it."""
+    default_database: str
+    """The database that unqualified table names in ``query`` resolve against."""
+    schema: "pa.Schema"
+    """The schema the defining query resolved to when the view was created."""
+    namespace_path: List[str] = field(default_factory=list)
+    """The namespace holding the view; empty is the root namespace."""
+    default_namespace_path: List[str] = field(default_factory=list)
+    """The namespace path those unqualified names resolve against.
+
+    Recorded with the view because it outlives the session that declared it: a
+    reader resolving the query against its own default namespace could read a
+    different table than the view was defined over.
+    """

python/python/tests/test_blob.py

@@ -751,6 +751,80 @@ def test_fetch_blobs_preserves_null_and_empty_values():
     assert blobs[3].as_py() == b"present"
 
 
+def test_add_all_null_list_to_blob_column():
+    table = _blob_table("all_null_add", [{"id": 1, "image": None}])
+
+    hits = table.search().to_arrow()
+    blobs = table.fetch_blobs("image", hits)
+    assert len(blobs) == 1
+    assert blobs[0].as_py() is None
+
+
+def test_add_all_null_list_to_blob_column_with_sanitizer():
+    db = lancedb.connect("memory:///")
+    schema = pa.schema([pa.field("id", pa.int64()), lancedb.blob("image")])
+    table = db.create_table("all_null_sanitized_add", schema=schema)
+
+    table.add([{"id": 1, "image": None}], on_bad_vectors="fill")
+
+    hits = table.search().to_arrow()
+    blobs = table.fetch_blobs("image", hits)
+    assert len(blobs) == 1
+    assert blobs[0].as_py() is None
+
+
+def test_add_all_null_list_to_nested_blob_column():
+    db = lancedb.connect("memory:///")
+    blob_field = lancedb.blob("image")
+    info_field = pa.field("info", pa.struct([blob_field]))
+    info = pa.StructArray.from_arrays(
+        [_blob_array("image", [b"seed"])], fields=[blob_field]
+    )
+    seed = pa.Table.from_arrays(
+        [pa.array([0], type=pa.int64()), info],
+        schema=pa.schema([pa.field("id", pa.int64()), info_field]),
+    )
+    table = db.create_table("nested_null_add", data=seed)
+
+    table.add([{"id": 1, "info": {"image": None}}])
+    table.add([{"id": 2, "info": {"image": None}}], on_bad_vectors="fill")
+
+    hits = table.search().where("id > 0").to_arrow()
+    blobs = table.fetch_blobs("info.image", hits)
+    assert len(blobs) == 2
+    assert all(blob.as_py() is None for blob in blobs)
+
+
+@pytest.mark.parametrize("large_list", [False, True], ids=["list", "large_list"])
+def test_add_list_of_dicts_to_blob_list_column(large_list):
+    db = lancedb.connect("memory:///")
+    blob_field = lancedb.blob("image")
+    blob_values = _blob_array("image", [b"seed"])
+    if large_list:
+        items_field = pa.field("items", pa.large_list(blob_field))
+        items = pa.LargeListArray.from_arrays(
+            pa.array([0, 1], type=pa.int64()), blob_values
+        )
+    else:
+        items_field = pa.field("items", pa.list_(blob_field))
+        items = pa.ListArray.from_arrays(pa.array([0, 1], type=pa.int32()), blob_values)
+    seed = pa.Table.from_arrays(
+        [pa.array([0], type=pa.int64()), items],
+        schema=pa.schema([pa.field("id", pa.int64()), items_field]),
+    )
+    table = db.create_table(f"blob_{large_list}_list_add", data=seed)
+
+    table.add([{"id": 1, "items": [None]}])
+    table.add(
+        [{"id": 2, "items": [b"a", None]}],
+        on_bad_vectors="fill",
+    )
+
+    ids = table.search().select(["id"]).to_arrow()["id"].to_pylist()
+    assert sorted(ids) == [0, 1, 2]
+    assert pa.types.is_large_list(table.schema.field("items").type) is large_list
+
+
 def test_fetch_blob_ranges_aligns_repeated_ranges_and_nulls():
     table = _blob_table(
         "range_alignment",

python/python/tests/test_catalog.py

@@ -0,0 +1,140 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright The LanceDB Authors
+
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+import json
+from threading import Thread
+
+import pytest
+
+import lancedb
+from lancedb.db import AsyncConnection, DBConnection
+from lancedb.remote.errors import HttpError
+
+
+@pytest.fixture
+def catalog_server():
+    requests = []
+    responses = []
+
+    class Handler(BaseHTTPRequestHandler):
+        def handle_request(self):
+            body = self.rfile.read(int(self.headers.get("Content-Length", "0")))
+            requests.append(
+                (
+                    self.path,
+                    dict(self.headers.items()),
+                    json.loads(body) if body else None,
+                )
+            )
+            status, response = responses.pop(0)
+            self.send_response(status)
+            self.send_header("Content-Type", "application/json")
+            self.end_headers()
+            if status != 204:
+                self.wfile.write(json.dumps(response).encode())
+
+        do_GET = handle_request
+        do_POST = handle_request
+
+    with ThreadingHTTPServer(("127.0.0.1", 0), Handler) as server:
+        thread = Thread(target=server.serve_forever, daemon=True)
+        thread.start()
+        try:
+            yield f"http://127.0.0.1:{server.server_port}", requests, responses
+        finally:
+            server.shutdown()
+            thread.join()
+
+
+def test_catalog_sync_scope_and_serialization(catalog_server):
+    endpoint, requests, responses = catalog_server
+    responses.extend(
+        [
+            (204, None),
+            (200, {}),
+            (200, {"tables": []}),
+            (200, {"tables": []}),
+            (200, {"namespaces": ["team/search"], "page_token": "next"}),
+            (204, None),
+        ]
+    )
+    catalog = lancedb.connect_catalog(
+        endpoint,
+        api_key="secret",
+        sql_host_override="invalid://localhost",
+        client_config={
+            "extra_headers": {
+                "X-LanceDB-Database": "wrong",
+                "X-LanceDB-Database-Prefix": "wrong",
+            }
+        },
+    )
+    assert isinstance(catalog, lancedb.Catalog)
+    assert catalog.uri == endpoint
+    db = catalog.create_database("team/search", exist_ok=True)
+    assert isinstance(db, DBConnection)
+    with pytest.raises(ValueError, match="sql_host_override must use"):
+        db.execute_query_async("SELECT 1")
+    db = catalog.connect_database("team/search")
+    assert isinstance(db, DBConnection)
+    assert db.table_names() == []
+    restored = lancedb.deserialize_conn(db.serialize())
+    assert restored.sql_host_override == "invalid://localhost"
+    for connection in (db, restored):
+        with pytest.raises(ValueError, match="sql_host_override must use"):
+            connection.execute_query_async("SELECT 1")
+    assert restored.table_names() == []
+    page = catalog.list_databases(limit=1, page_token="a/b")
+    assert page == lancedb.ListDatabasesResponse(["team/search"], "next")
+    catalog.drop_database("team/search", ignore_missing=True)
+    assert requests[0][0] == "/v1/namespace/team%2Fsearch/create"
+    assert requests[0][2] == {"mode": "ExistOk"}
+    assert requests[1][0] == "/v1/namespace/team%2Fsearch/describe"
+    assert requests[4][0] == "/v1/namespace/$/list?limit=1&page_token=a%2Fb"
+    assert requests[5][2] == {"mode": "Skip", "behavior": "Restrict"}
+    for i, (_, headers, _) in enumerate(requests):
+        headers = {key.lower(): value for key, value in headers.items()}
+        assert headers.get("x-lancedb-database") == (
+            "team/search" if i in (2, 3) else None
+        )
+        assert "x-lancedb-database-prefix" not in headers
+        assert headers["x-api-key"] == "secret"
+
+
+@pytest.mark.asyncio
+async def test_catalog_async_and_errors(catalog_server):
+    endpoint, requests, responses = catalog_server
+    responses.extend(
+        [
+            (200, {}),
+            (200, {"tables": []}),
+            (404, {"error": "missing"}),
+            (409, {"error": "exists"}),
+            (400, {"error": "not empty"}),
+            (404, {"error": "missing"}),
+        ]
+    )
+    catalog = await lancedb.connect_catalog_async(
+        endpoint, sql_host_override="invalid://localhost"
+    )
+    assert isinstance(catalog, lancedb.AsyncCatalog)
+    db = await catalog.connect_database("analytics")
+    assert isinstance(db, AsyncConnection)
+    with pytest.raises(ValueError, match="sql_host_override must use"):
+        await db.execute_query_async("SELECT 1")
+    assert await db.table_names() == []
+    with pytest.raises(ValueError, match="missing"):
+        await catalog.connect_database("missing")
+    with pytest.raises(ValueError, match="exists"):
+        await catalog.create_database("exists")
+    with pytest.raises(HttpError):
+        await catalog.drop_database("full")
+    await catalog.drop_database("missing", ignore_missing=True)
+    assert requests[4][2] == {"mode": "Fail", "behavior": "Restrict"}
+
+
+@pytest.mark.parametrize("endpoint", ["/tmp/catalog", "s3://bucket", "db://db"])
+def test_catalog_requires_remote_endpoint(endpoint):
+    with pytest.raises(ValueError, match="endpoint"):
+        lancedb.connect_catalog(endpoint)

python/python/tests/test_embeddings.py

@@ -633,6 +633,18 @@ def test_url_retrieve_downloads_image():
     assert img.size[0] > 0 and img.size[1] > 0
 
 
+def test_open_clip_opens_percent_encoded_file_uri(tmp_path):
+    """OpenCLIP should decode local file URIs before opening them."""
+    Image = pytest.importorskip("PIL.Image")
+    from lancedb.embeddings.open_clip import OpenClipEmbeddings
+
+    image_path = tmp_path / "test image.png"
+    Image.new("RGB", (4, 4), color="red").save(image_path, format="PNG")
+
+    with OpenClipEmbeddings._to_pil(None, image_path.as_uri()) as image:
+        assert image.size == (4, 4)
+
+
 def test_jina_generate_image_input_dict_local_path(tmp_path):
     """
     JinaEmbeddings._generate_image_input_dict must accept a local image path

python/python/tests/test_first_class_function_slice1.py

@@ -13,7 +13,9 @@ from lancedb.functions import (
     FunctionBinding,
     FunctionVersion,
     PythonRuntimeSpec,
+    SecretBinding,
     RefreshColumnResult,
+    SecretReference,
 )
 from lancedb.table import AsyncTable
 
@@ -37,6 +39,22 @@ def job_result(name: str) -> dict:
     return json.loads(fixture(name))["result"]
 
 
+def assert_no_secret_values(value):
+    """No client value models a resolved credential, at any nesting depth."""
+    if isinstance(value, dict):
+        for key, child in value.items():
+            assert key not in {
+                "secret_value",
+                "secret_values",
+                "resolved_secret",
+                "resolved_secrets",
+            }
+            assert_no_secret_values(child)
+    elif isinstance(value, list):
+        for child in value:
+            assert_no_secret_values(child)
+
+
 def test_public_function_values_are_in_api_reference():
     docs = Path(__file__).parents[3] / "docs" / "src" / "python" / "python.md"
     rendered = docs.read_text()
@@ -65,6 +83,18 @@ def test_public_function_values_are_in_api_reference():
             FunctionBinding,
             False,
         ),
+        (
+            "remote_initialized_function_application.json",
+            "remote_initialized_function_application.canonical.json",
+            FunctionApplication,
+            False,
+        ),
+        (
+            "remote_initialized_function_binding.json",
+            "remote_initialized_function_binding.canonical.json",
+            FunctionBinding,
+            False,
+        ),
         (
             "remote_refresh_job.json",
             "remote_refresh_result.canonical.json",
@@ -93,16 +123,27 @@ def test_function_version_identity_is_immutable_and_exact():
     value = job_result("remote_function_job.json")
     version = FunctionVersion.from_json(json.dumps(value))
     assert version.name == "embed"
-    assert version.version == "fv_01K3EXACT"
+    assert version.version == "1"
+    assert version.image.manifest_digest.startswith("sha256:")
+    assert version.version != version.image.manifest_digest
+    assert list(version.secret_bindings) == [
+        SecretBinding(
+            kind="env", variable="HF_TOKEN", secret_ref=SecretReference(name="hf-prod")
+        )
+    ]
 
     with pytest.raises((TypeError, ValueError)):
-        version.version = "fv_changed"
+        version.version = "1"
     with pytest.raises(TypeError, match="immutable"):
-        version.runtime.env["TOKENIZERS_PARALLELISM"] = "true"
+        version.image.descriptor["format_version"] = "changed"
 
     changed = dict(value)
-    changed["version"] = "fv_changed"
+    changed["version"] = "2"
     assert FunctionVersion(**changed) != version
+    assert FunctionVersion(**changed).image == version.image
+    for invalid in [version.image.manifest_digest, "0", "01", "-1", str(2**64)]:
+        with pytest.raises(ValueError):
+            FunctionVersion(**{**value, "version": invalid})
 
 
 def test_function_version_binds_named_columns_as_one_immutable_application():
@@ -128,7 +169,7 @@ def test_function_version_binding_validates_names_and_direct_columns():
 
     with pytest.raises(TypeError, match=r"missing inputs: \['text'\]"):
         version()
-    with pytest.raises(TypeError, match=r"unknown inputs: \['body'\]"):
+    with pytest.raises(TypeError, match=r"unknown arguments: \['body'\]"):
         version(text=col("text"), body=col("body"))
     with pytest.raises(TypeError, match="direct col"):
         version(text=col("text").lower())
@@ -137,7 +178,7 @@ def test_function_version_binding_validates_names_and_direct_columns():
 def test_function_version_keeps_named_struct_outputs_in_one_application():
     value = job_result("remote_function_job.json")
     value["name"] = "text_features"
-    value["version"] = "fv_multi_output"
+    value["version"] = "1"
     value["signature"] = {
         "inputs": [
             {"name": "title", "arrow_type": "utf8", "nullable": True},
@@ -182,14 +223,14 @@ def test_function_version_keeps_named_struct_outputs_in_one_application():
 def test_unknown_fields_and_discriminators_are_forward_decodable():
     value = job_result("remote_function_job.json")
     value["future_version_metadata"] = {"retention_class": "catalog"}
-    value["runtime"] = {"kind": "wasm", "module_digest": "sha256:wasm"}
+    value["image"]["descriptor"]["future_interface"] = {"kind": "wasm"}
     value["signature"]["output"]["kind"] = "future_output_shape"
 
     version = FunctionVersion.from_json(json.dumps(value))
-    assert version.runtime.kind == "wasm"
-    assert version.runtime.python_version is None
-    assert version.runtime.environment is None
-    assert json.loads(version.to_canonical_json())["runtime"] == {"kind": "wasm"}
+    assert version.image.descriptor["future_interface"] == {"kind": "wasm"}
+    assert json.loads(version.to_canonical_json())["image"]["descriptor"][
+        "future_interface"
+    ] == {"kind": "wasm"}
     assert version.signature.output.kind == "future_output_shape"
 
 
@@ -222,7 +263,7 @@ def test_function_application_uses_rename_columns_only():
 
 def test_binding_and_refresh_result_keep_stable_remote_fields():
     binding = FunctionBinding.from_json(fixture("remote_function_binding.json"))
-    assert binding.function.version == "fv_01K3TEXT"
+    assert binding.function.version == "1"
     assert [output.output_ordinal for output in binding.outputs] == [0, 1]
     assert binding.input_schema is not None
     assert binding.output_schema is not None
@@ -240,6 +281,35 @@ def test_binding_and_refresh_result_keep_stable_remote_fields():
     assert RefreshColumnResult.from_json(result.to_canonical_json()) == result
 
 
+def test_initialization_travels_on_the_application_and_binding():
+    application = FunctionApplication.from_json(
+        fixture("remote_initialized_function_application.json")
+    )
+    assert application.initialization["temperature"] == 0.25
+    assert application.initialization["retry"]["backoff"] == (1, 2, 4)
+    application._ensure_declarable()
+
+    binding = FunctionBinding.from_json(
+        fixture("remote_initialized_function_binding.json")
+    )
+    assert binding.initialization_row() == {
+        "model": "text-embedding-3-small",
+        "dimensions": 512,
+    }
+    assert (
+        FunctionBinding.from_json(
+            fixture("remote_function_binding.json")
+        ).initialization_row()
+        is None
+    )
+
+    signature = FunctionVersion.from_json(
+        json.dumps(job_result("remote_function_job.json"))
+    ).signature
+    assert signature.initialization == ()
+    assert "initialization" not in json.loads(signature.to_canonical_json())
+
+
 def test_function_literal_numeric_domain_matches_rust():
     with pytest.raises(ValueError, match="floating-point Function literals"):
         FunctionApplication.from_json(fixture("remote_function_application_float.json"))
@@ -276,6 +346,31 @@ def test_refresh_result_rejects_non_u64_values(field):
         RefreshColumnResult.from_json(json.dumps(value))
 
 
+def test_canonical_client_values_carry_bindings_and_no_credentials():
+    """A binding names a Secret; the credential behind it has no client field."""
+    version = FunctionVersion.from_json(
+        json.dumps(job_result("remote_function_job.json"))
+    )
+    canonical = json.loads(version.to_canonical_json())
+    assert canonical["secret_bindings"] == [
+        {"kind": "env", "variable": "HF_TOKEN", "secret_ref": {"name": "hf-prod"}}
+    ]
+    assert_no_secret_values(canonical)
+
+
+def test_a_version_without_bindings_omits_the_field_in_both_directions():
+    """A Function that binds nothing carries no ``secret_bindings`` key.
+
+    Absent decodes as an empty list, and an empty list serializes back to
+    absent.
+    """
+    value = job_result("remote_function_job.json")
+    del value["secret_bindings"]
+    version = FunctionVersion.from_json(json.dumps(value))
+    assert list(version.secret_bindings) == []
+    assert "secret_bindings" not in json.loads(version.to_canonical_json())
+
+
 class _FunctionDeclarationInner:
     def __init__(self):
         self.calls = []
@@ -339,7 +434,16 @@ def test_rename_requires_named_struct_and_keeps_partial_mapping_immutable():
     scalar = FunctionApplication.from_json(
         json.dumps(
             {
-                "function": {"name": "embed", "version": "fv_exact"},
+                "function": {
+                    "name": "embed",
+                    "version": "1",
+                    "object_id": "fixture",
+                    "location": "memory:///fixture",
+                    "manifest_digest": (
+                        "sha256:"
+                        "7e22f815b6648e14f093a3979a8e5a2082fa773ebe1ec84b135cae7e84d6f8e6"
+                    ),
+                },
                 "inputs": [],
                 "output": {
                     "kind": "scalar",