feat(remote): route list_tables by what the server serves

`list_tables` asked for `/v2` unconditionally, which 404s against every server that is not a recent Phalanx -- including `RestAdapter`, the namespace spec's own reference implementation. The connection now asks `/v1/version` once, before its first listing, and keeps the one bit it needs: whether this server serves the `/v2` listing. Servers that do not keep the listing they have always served, which is correct and merely slower. The answer has to be known before the first page rather than learned from it. The two routes resume from different things, so a walk that started on one cannot finish on the other, and a walk that learned from its own first page would hand `/v2` a token `/v1` minted. What is cached is that bit, not the `ServerVersion` it came from. A server that sends no version header is indistinguishable from one running the oldest version we know of, so caching the version would let a stripped header switch off multivector, structural FTS, multipart write and blobs for the life of the connection. A missing header can only cost a listing its pushdown. `table_names` is untouched: it stays on `/v1`, where `page_token` is a table name to resume after that its callers build themselves.
chore: pin lance to the read_dir_page branch
2026-08-27 16:38:31 +00:00 · 2026-08-19 17:05:27 -07:00 · 2026-08-19 13:32:34 -07:00 · 2026-08-19 13:30:26 -07:00 · 2026-08-19 13:28:26 -07:00
186 changed files with 3660 additions and 17270 deletions
@@ -5,3 +5,7 @@ This directory contains repo-scoped code agent skills for the LanceDB project.
 Each skill is a folder that contains a required `SKILL.md` and optional bundled resources.

 Codex discovers skills from `.agents/skills` in the current working directory and parent directories.
+
+The `lancedb` skill lives in the `plugins/lancedb` plugin (see `plugins/lancedb/skills/lancedb`)
+so it can be installed via the plugin marketplaces (`.claude-plugin/marketplace.json` and
+`.agents/plugins/marketplace.json`); the `lancedb` entry here is a symlink into that plugin.
@@ -0,0 +1 @@
+../../plugins/lancedb/skills/lancedb
@@ -1,5 +1,5 @@
 [tool.bumpversion]
-current_version = "0.38.0-beta.7"
+current_version = "0.38.0-beta.2"
 parse = """(?x)
    (?P<major>0|[1-9]\\d*)\\.
    (?P<minor>0|[1-9]\\d*)\\.
@@ -9,18 +9,6 @@ debug = true
 codegen-units = 16
 lto = "thin"

-[profile.release-no-lto]
-inherits = "release"
-debug = true
-lto = false
-# Prioritize compile time when LTO is not relevant to the measurement.
-codegen-units = 16
-
-[profile.bench]
-inherits = "release"
-lto = "thin"
-codegen-units = 16
-
 [target.'cfg(all())']
 rustflags = [
    "-Wclippy::all",
@@ -17,18 +17,6 @@ updates:
    # newer minimum versions.
    versioning-strategy: lockfile-only
    groups:
-      # The arrow-rs and datafusion crates are released in lockstep and have to
-      # move together, so keep them in one PR instead of one per sub-crate.
-      # Listed first: a dependency joins the first group it matches.
-      arrow-datafusion:
-        patterns:
-          - arrow
-          - arrow-*
-          - parquet
-          - parquet-*
-          - datafusion
-          - datafusion-*
-          - object_store
      rust-minor-patch:
        update-types:
          - minor
@@ -1,30 +0,0 @@
-name: CI scripts
-
-on:
-  push:
-    branches:
-      - main
-    paths:
-      - ci/set_lance_version.py
-      - ci/tests/**
-      - .github/workflows/ci-scripts.yml
-  pull_request:
-    paths:
-      - ci/set_lance_version.py
-      - ci/tests/**
-      - .github/workflows/ci-scripts.yml
-
-permissions:
-  contents: read
-
-jobs:
-  test:
-    name: Test CI scripts
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v6
-      - uses: actions/setup-python@v6
-        with:
-          python-version: "3.13"
-      - name: Run tests
-        run: python -m unittest discover -s ci/tests -v
@@ -129,12 +129,6 @@ jobs:
      # 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
    steps:
      - uses: actions/checkout@v6
        with:
@@ -229,8 +229,7 @@ jobs:
      # Make sure wheels are not included in the Rust cache
      - name: Delete wheels
        run: rm -rf target/wheels
-  min-deps:
-    name: "Minimum dependencies"
+  pydantic1x:
    timeout-minutes: 60
    runs-on: "ubuntu-24.04"
    defaults:
@@ -260,7 +259,8 @@ jobs:
          save-if: ${{ github.ref == 'refs/heads/main' }}
      - name: Install lancedb
        run: |
-          pip install "pydantic==2.7.4" "pyarrow==16"
+          pip install "pydantic<2"
+          pip install pyarrow==16
          pip install --extra-index-url https://pypi.fury.io/lance-format/ --extra-index-url https://pypi.fury.io/lancedb/ -e .[tests]
      - name: Run tests
        run: pytest -m "not slow and not s3_test" -x -v --durations=30 python/tests
@@ -121,6 +121,7 @@ jobs:
      # Need up-to-date compilers for kernels
      CC: clang-18
      CXX: clang++-18
+      GH_TOKEN: ${{ secrets.SOPHON_READ_TOKEN }}
    steps:
      - uses: actions/checkout@v6
        with:
@@ -164,40 +165,11 @@ jobs:
      - name: Run feature tests
        run: CARGO_ARGS="--profile ci" make -C ./lancedb feature-tests
      - name: Run examples
-        run: cargo run --profile ci --all-features --example simple --locked
-
-  remote:
-    timeout-minutes: 30
-    # Running this requires access to secrets, so skip if this is a PR from a
-    # fork. Keep it separate from the all-features build so Cargo does not
-    # retain both dependency graphs in one target directory.
-    if: github.event_name != 'pull_request' || !github.event.pull_request.head.repo.fork
-    runs-on: ubuntu-2404-4x-x64
-    defaults:
-      run:
-        shell: bash
-        working-directory: rust
-    env:
-      CC: clang-18
-      CXX: clang++-18
-      GH_TOKEN: ${{ secrets.SOPHON_READ_TOKEN }}
-    steps:
-      - uses: actions/checkout@v6
-        with:
-          fetch-depth: 0
-          lfs: true
-      - uses: Swatinem/rust-cache@v2
-        with:
-          # Remote tests use a different feature graph from the main Linux
-          # job. Cache downloads, but build into a fresh target directory.
-          cache-targets: false
-          save-if: ${{ github.ref == 'refs/heads/main' }}
-      - name: Install dependencies
-        run: |
-          sudo apt update
-          sudo apt install -y protobuf-compiler libssl-dev
-      - uses: rui314/setup-mold@v1
+        run: cargo run  --profile ci --example simple --locked
      - name: Run remote tests
+        # Running this requires access to secrets, so skip if this is
+        # a PR from a fork.
+        if: github.event_name != 'pull_request' || !github.event.pull_request.head.repo.fork
        run: CARGO_ARGS="--profile ci" make -C ./lancedb remote-tests

  macos:
@@ -18,9 +18,6 @@ Common commands:
 * Run specific test: `cargo test --quiet --features remote -p <package_name> --test <test_name>`
 * Lint: `cargo clippy --quiet --features remote --tests --examples`
 * Format Rust: `cargo fmt --all`
-* Use repository-defined Cargo profiles instead of ad hoc LTO overrides.
-* Use `release-with-debug` for benchmarks and profiling so optimized builds keep debug symbols without a rebuild.
-* Use `release-no-lto` only for local debugging, IO-bound benchmarks, or compile-time-sensitive performance investigation where LTO would not affect the measured bottleneck.
 * Format Python: `ruff format .`
 * Lint Python: `ruff check .`
 * Bootstrap Python dev env: `cd python && uv run --extra tests --extra dev maturin develop --extras tests,dev`
@@ -1740,9 +1740,9 @@ dependencies = [

 [[package]]
 name = "cmov"
-version = "0.5.4"
+version = "0.5.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "0c9ea0ac24bc397ab3c98583a3c9ba74fa56b09a4449bbe172b9b1ddb016027a"
+checksum = "3f88a43d011fc4a6876cb7344703e297c71dda42494fee094d5f7c76bf13f746"

 [[package]]
 name = "colorchoice"
@@ -3455,8 +3455,8 @@ checksum = "42703706b716c37f96a77aea830392ad231f44c9e9a67872fa5548707e11b11c"

 [[package]]
 name = "fsst"
-version = "11.0.0-beta.22"
-source = "git+https://github.com/lance-format/lance.git?tag=v11.0.0-beta.22#ea3cb4d799c468232735e9bcb43959487aca5c20"
+version = "11.0.0-beta.15"
+source = "git+https://github.com/lance-format/lance.git?rev=d7b1d570461c6d2adde8f3a84ae88db4823c726f#d7b1d570461c6d2adde8f3a84ae88db4823c726f"
 dependencies = [
 "arrow-array",
 "rand 0.9.5",
@@ -4815,8 +4815,8 @@ checksum = "e037a2e1d8d5fdbd49b16a4ea09d5d6401c1f29eca5ff29d03d3824dba16256a"

 [[package]]
 name = "lance"
-version = "11.0.0-beta.22"
-source = "git+https://github.com/lance-format/lance.git?tag=v11.0.0-beta.22#ea3cb4d799c468232735e9bcb43959487aca5c20"
+version = "11.0.0-beta.15"
+source = "git+https://github.com/lance-format/lance.git?rev=d7b1d570461c6d2adde8f3a84ae88db4823c726f#d7b1d570461c6d2adde8f3a84ae88db4823c726f"
 dependencies = [
 "arc-swap",
 "arrow",
@@ -4888,8 +4888,8 @@ dependencies = [

 [[package]]
 name = "lance-arrow"
-version = "11.0.0-beta.22"
-source = "git+https://github.com/lance-format/lance.git?tag=v11.0.0-beta.22#ea3cb4d799c468232735e9bcb43959487aca5c20"
+version = "11.0.0-beta.15"
+source = "git+https://github.com/lance-format/lance.git?rev=d7b1d570461c6d2adde8f3a84ae88db4823c726f#d7b1d570461c6d2adde8f3a84ae88db4823c726f"
 dependencies = [
 "arrow-array",
 "arrow-buffer",
@@ -4911,7 +4911,7 @@ dependencies = [
 [[package]]
 name = "lance-arrow-scalar"
 version = "58.0.0"
-source = "git+https://github.com/lance-format/lance.git?tag=v11.0.0-beta.22#ea3cb4d799c468232735e9bcb43959487aca5c20"
+source = "git+https://github.com/lance-format/lance.git?rev=d7b1d570461c6d2adde8f3a84ae88db4823c726f#d7b1d570461c6d2adde8f3a84ae88db4823c726f"
 dependencies = [
 "arrow-array",
 "arrow-buffer",
@@ -4925,7 +4925,7 @@ dependencies = [
 [[package]]
 name = "lance-arrow-stats"
 version = "58.0.0"
-source = "git+https://github.com/lance-format/lance.git?tag=v11.0.0-beta.22#ea3cb4d799c468232735e9bcb43959487aca5c20"
+source = "git+https://github.com/lance-format/lance.git?rev=d7b1d570461c6d2adde8f3a84ae88db4823c726f#d7b1d570461c6d2adde8f3a84ae88db4823c726f"
 dependencies = [
 "arrow-array",
 "arrow-schema",
@@ -4934,8 +4934,8 @@ dependencies = [

 [[package]]
 name = "lance-bitpacking"
-version = "11.0.0-beta.22"
-source = "git+https://github.com/lance-format/lance.git?tag=v11.0.0-beta.22#ea3cb4d799c468232735e9bcb43959487aca5c20"
+version = "11.0.0-beta.15"
+source = "git+https://github.com/lance-format/lance.git?rev=d7b1d570461c6d2adde8f3a84ae88db4823c726f#d7b1d570461c6d2adde8f3a84ae88db4823c726f"
 dependencies = [
 "arrayref",
 "crunchy",
@@ -4945,8 +4945,8 @@ dependencies = [

 [[package]]
 name = "lance-core"
-version = "11.0.0-beta.22"
-source = "git+https://github.com/lance-format/lance.git?tag=v11.0.0-beta.22#ea3cb4d799c468232735e9bcb43959487aca5c20"
+version = "11.0.0-beta.15"
+source = "git+https://github.com/lance-format/lance.git?rev=d7b1d570461c6d2adde8f3a84ae88db4823c726f#d7b1d570461c6d2adde8f3a84ae88db4823c726f"
 dependencies = [
 "arrow-array",
 "arrow-buffer",
@@ -4983,8 +4983,8 @@ dependencies = [

 [[package]]
 name = "lance-datafusion"
-version = "11.0.0-beta.22"
-source = "git+https://github.com/lance-format/lance.git?tag=v11.0.0-beta.22#ea3cb4d799c468232735e9bcb43959487aca5c20"
+version = "11.0.0-beta.15"
+source = "git+https://github.com/lance-format/lance.git?rev=d7b1d570461c6d2adde8f3a84ae88db4823c726f#d7b1d570461c6d2adde8f3a84ae88db4823c726f"
 dependencies = [
 "arrow",
 "arrow-array",
@@ -5013,8 +5013,8 @@ dependencies = [

 [[package]]
 name = "lance-datagen"
-version = "11.0.0-beta.22"
-source = "git+https://github.com/lance-format/lance.git?tag=v11.0.0-beta.22#ea3cb4d799c468232735e9bcb43959487aca5c20"
+version = "11.0.0-beta.15"
+source = "git+https://github.com/lance-format/lance.git?rev=d7b1d570461c6d2adde8f3a84ae88db4823c726f#d7b1d570461c6d2adde8f3a84ae88db4823c726f"
 dependencies = [
 "arrow",
 "arrow-array",
@@ -5031,8 +5031,8 @@ dependencies = [

 [[package]]
 name = "lance-derive"
-version = "11.0.0-beta.22"
-source = "git+https://github.com/lance-format/lance.git?tag=v11.0.0-beta.22#ea3cb4d799c468232735e9bcb43959487aca5c20"
+version = "11.0.0-beta.15"
+source = "git+https://github.com/lance-format/lance.git?rev=d7b1d570461c6d2adde8f3a84ae88db4823c726f#d7b1d570461c6d2adde8f3a84ae88db4823c726f"
 dependencies = [
 "proc-macro2",
 "quote",
@@ -5041,8 +5041,8 @@ dependencies = [

 [[package]]
 name = "lance-encoding"
-version = "11.0.0-beta.22"
-source = "git+https://github.com/lance-format/lance.git?tag=v11.0.0-beta.22#ea3cb4d799c468232735e9bcb43959487aca5c20"
+version = "11.0.0-beta.15"
+source = "git+https://github.com/lance-format/lance.git?rev=d7b1d570461c6d2adde8f3a84ae88db4823c726f#d7b1d570461c6d2adde8f3a84ae88db4823c726f"
 dependencies = [
 "arrow-arith",
 "arrow-array",
@@ -5075,8 +5075,8 @@ dependencies = [

 [[package]]
 name = "lance-file"
-version = "11.0.0-beta.22"
-source = "git+https://github.com/lance-format/lance.git?tag=v11.0.0-beta.22#ea3cb4d799c468232735e9bcb43959487aca5c20"
+version = "11.0.0-beta.15"
+source = "git+https://github.com/lance-format/lance.git?rev=d7b1d570461c6d2adde8f3a84ae88db4823c726f#d7b1d570461c6d2adde8f3a84ae88db4823c726f"
 dependencies = [
 "arrow-arith",
 "arrow-array",
@@ -5107,8 +5107,8 @@ dependencies = [

 [[package]]
 name = "lance-index"
-version = "11.0.0-beta.22"
-source = "git+https://github.com/lance-format/lance.git?tag=v11.0.0-beta.22#ea3cb4d799c468232735e9bcb43959487aca5c20"
+version = "11.0.0-beta.15"
+source = "git+https://github.com/lance-format/lance.git?rev=d7b1d570461c6d2adde8f3a84ae88db4823c726f#d7b1d570461c6d2adde8f3a84ae88db4823c726f"
 dependencies = [
 "arc-swap",
 "arrow",
@@ -5172,8 +5172,8 @@ dependencies = [

 [[package]]
 name = "lance-index-core"
-version = "11.0.0-beta.22"
-source = "git+https://github.com/lance-format/lance.git?tag=v11.0.0-beta.22#ea3cb4d799c468232735e9bcb43959487aca5c20"
+version = "11.0.0-beta.15"
+source = "git+https://github.com/lance-format/lance.git?rev=d7b1d570461c6d2adde8f3a84ae88db4823c726f#d7b1d570461c6d2adde8f3a84ae88db4823c726f"
 dependencies = [
 "arrow-array",
 "arrow-schema",
@@ -5195,8 +5195,8 @@ dependencies = [

 [[package]]
 name = "lance-io"
-version = "11.0.0-beta.22"
-source = "git+https://github.com/lance-format/lance.git?tag=v11.0.0-beta.22#ea3cb4d799c468232735e9bcb43959487aca5c20"
+version = "11.0.0-beta.15"
+source = "git+https://github.com/lance-format/lance.git?rev=d7b1d570461c6d2adde8f3a84ae88db4823c726f#d7b1d570461c6d2adde8f3a84ae88db4823c726f"
 dependencies = [
 "arrow",
 "arrow-array",
@@ -5222,11 +5222,7 @@ dependencies = [
 "pin-project",
 "prost",
 "rand 0.9.5",
- "reqsign-core",
- "reqsign-file-read-tokio",
- "reqsign-google",
 "serde",
- "serde_json",
 "tempfile",
 "tokio",
 "tracing",
@@ -5236,8 +5232,8 @@ dependencies = [

 [[package]]
 name = "lance-linalg"
-version = "11.0.0-beta.22"
-source = "git+https://github.com/lance-format/lance.git?tag=v11.0.0-beta.22#ea3cb4d799c468232735e9bcb43959487aca5c20"
+version = "11.0.0-beta.15"
+source = "git+https://github.com/lance-format/lance.git?rev=d7b1d570461c6d2adde8f3a84ae88db4823c726f#d7b1d570461c6d2adde8f3a84ae88db4823c726f"
 dependencies = [
 "arrow-array",
 "arrow-schema",
@@ -5251,8 +5247,8 @@ dependencies = [

 [[package]]
 name = "lance-namespace"
-version = "11.0.0-beta.22"
-source = "git+https://github.com/lance-format/lance.git?tag=v11.0.0-beta.22#ea3cb4d799c468232735e9bcb43959487aca5c20"
+version = "11.0.0-beta.15"
+source = "git+https://github.com/lance-format/lance.git?rev=d7b1d570461c6d2adde8f3a84ae88db4823c726f#d7b1d570461c6d2adde8f3a84ae88db4823c726f"
 dependencies = [
 "arrow",
 "async-trait",
@@ -5264,8 +5260,8 @@ dependencies = [

 [[package]]
 name = "lance-namespace-impls"
-version = "11.0.0-beta.22"
-source = "git+https://github.com/lance-format/lance.git?tag=v11.0.0-beta.22#ea3cb4d799c468232735e9bcb43959487aca5c20"
+version = "11.0.0-beta.15"
+source = "git+https://github.com/lance-format/lance.git?rev=d7b1d570461c6d2adde8f3a84ae88db4823c726f#d7b1d570461c6d2adde8f3a84ae88db4823c726f"
 dependencies = [
 "arrow",
 "arrow-ipc",
@@ -5318,8 +5314,8 @@ dependencies = [

 [[package]]
 name = "lance-select"
-version = "11.0.0-beta.22"
-source = "git+https://github.com/lance-format/lance.git?tag=v11.0.0-beta.22#ea3cb4d799c468232735e9bcb43959487aca5c20"
+version = "11.0.0-beta.15"
+source = "git+https://github.com/lance-format/lance.git?rev=d7b1d570461c6d2adde8f3a84ae88db4823c726f#d7b1d570461c6d2adde8f3a84ae88db4823c726f"
 dependencies = [
 "arrow-array",
 "arrow-buffer",
@@ -5333,8 +5329,8 @@ dependencies = [

 [[package]]
 name = "lance-table"
-version = "11.0.0-beta.22"
-source = "git+https://github.com/lance-format/lance.git?tag=v11.0.0-beta.22#ea3cb4d799c468232735e9bcb43959487aca5c20"
+version = "11.0.0-beta.15"
+source = "git+https://github.com/lance-format/lance.git?rev=d7b1d570461c6d2adde8f3a84ae88db4823c726f#d7b1d570461c6d2adde8f3a84ae88db4823c726f"
 dependencies = [
 "arrow",
 "arrow-array",
@@ -5374,8 +5370,8 @@ dependencies = [

 [[package]]
 name = "lance-testing"
-version = "11.0.0-beta.22"
-source = "git+https://github.com/lance-format/lance.git?tag=v11.0.0-beta.22#ea3cb4d799c468232735e9bcb43959487aca5c20"
+version = "11.0.0-beta.15"
+source = "git+https://github.com/lance-format/lance.git?rev=d7b1d570461c6d2adde8f3a84ae88db4823c726f#d7b1d570461c6d2adde8f3a84ae88db4823c726f"
 dependencies = [
 "arrow-array",
 "arrow-schema",
@@ -5388,8 +5384,8 @@ dependencies = [

 [[package]]
 name = "lance-tokenizer"
-version = "11.0.0-beta.22"
-source = "git+https://github.com/lance-format/lance.git?tag=v11.0.0-beta.22#ea3cb4d799c468232735e9bcb43959487aca5c20"
+version = "11.0.0-beta.15"
+source = "git+https://github.com/lance-format/lance.git?rev=d7b1d570461c6d2adde8f3a84ae88db4823c726f#d7b1d570461c6d2adde8f3a84ae88db4823c726f"
 dependencies = [
 "frostem",
 "icu_segmenter",
@@ -5402,7 +5398,7 @@ dependencies = [

 [[package]]
 name = "lancedb"
-version = "0.38.0-beta.6"
+version = "0.38.0-beta.2"
 dependencies = [
 "ahash",
 "anyhow",
@@ -5490,7 +5486,7 @@ dependencies = [

 [[package]]
 name = "lancedb-nodejs"
-version = "0.38.0-beta.6"
+version = "0.38.0-beta.2"
 dependencies = [
 "arrow-array",
 "arrow-buffer",
@@ -5515,7 +5511,7 @@ dependencies = [

 [[package]]
 name = "lancedb-python"
-version = "0.38.0-beta.6"
+version = "0.38.0-beta.2"
 dependencies = [
 "arrow",
 "async-trait",
@@ -13,21 +13,23 @@ categories = ["database-implementations"]
 rust-version = "1.91.0"

 [workspace.dependencies]
-lance = { "version" = "=11.0.0-beta.22", default-features = false, "tag" = "v11.0.0-beta.22", "git" = "https://github.com/lance-format/lance.git" }
-lance-core = { "version" = "=11.0.0-beta.22", "tag" = "v11.0.0-beta.22", "git" = "https://github.com/lance-format/lance.git" }
-lance-datagen = { "version" = "=11.0.0-beta.22", "tag" = "v11.0.0-beta.22", "git" = "https://github.com/lance-format/lance.git" }
-lance-file = { "version" = "=11.0.0-beta.22", "tag" = "v11.0.0-beta.22", "git" = "https://github.com/lance-format/lance.git" }
-lance-io = { "version" = "=11.0.0-beta.22", default-features = false, "tag" = "v11.0.0-beta.22", "git" = "https://github.com/lance-format/lance.git" }
-lance-index = { "version" = "=11.0.0-beta.22", "tag" = "v11.0.0-beta.22", "git" = "https://github.com/lance-format/lance.git" }
-lance-linalg = { "version" = "=11.0.0-beta.22", "tag" = "v11.0.0-beta.22", "git" = "https://github.com/lance-format/lance.git" }
-lance-namespace = { "version" = "=11.0.0-beta.22", "tag" = "v11.0.0-beta.22", "git" = "https://github.com/lance-format/lance.git" }
-lance-namespace-impls = { "version" = "=11.0.0-beta.22", default-features = false, "tag" = "v11.0.0-beta.22", "git" = "https://github.com/lance-format/lance.git" }
-lance-table = { "version" = "=11.0.0-beta.22", "tag" = "v11.0.0-beta.22", "git" = "https://github.com/lance-format/lance.git" }
-lance-testing = { "version" = "=11.0.0-beta.22", "tag" = "v11.0.0-beta.22", "git" = "https://github.com/lance-format/lance.git" }
-lance-datafusion = { "version" = "=11.0.0-beta.22", "tag" = "v11.0.0-beta.22", "git" = "https://github.com/lance-format/lance.git" }
-lance-encoding = { "version" = "=11.0.0-beta.22", "tag" = "v11.0.0-beta.22", "git" = "https://github.com/lance-format/lance.git" }
-lance-arrow = { "version" = "=11.0.0-beta.22", "tag" = "v11.0.0-beta.22", "git" = "https://github.com/lance-format/lance.git" }
-lancedb = { path = "rust/lancedb", default-features = false }
+# TEMPORARY: `ObjectStore::read_dir_page` is not in a lance release yet, so these point at
+# lance-format/lance#8606 cherry-picked onto the v11.0.0-beta.15 tag. Put the tag back once that
+# PR has merged and shipped in a release.
+lance = { "version" = "=11.0.0-beta.15", default-features = false, "rev" = "d7b1d570461c6d2adde8f3a84ae88db4823c726f", "git" = "https://github.com/lance-format/lance.git" }
+lance-core = { "version" = "=11.0.0-beta.15", "rev" = "d7b1d570461c6d2adde8f3a84ae88db4823c726f", "git" = "https://github.com/lance-format/lance.git" }
+lance-datagen = { "version" = "=11.0.0-beta.15", "rev" = "d7b1d570461c6d2adde8f3a84ae88db4823c726f", "git" = "https://github.com/lance-format/lance.git" }
+lance-file = { "version" = "=11.0.0-beta.15", "rev" = "d7b1d570461c6d2adde8f3a84ae88db4823c726f", "git" = "https://github.com/lance-format/lance.git" }
+lance-io = { "version" = "=11.0.0-beta.15", default-features = false, "rev" = "d7b1d570461c6d2adde8f3a84ae88db4823c726f", "git" = "https://github.com/lance-format/lance.git" }
+lance-index = { "version" = "=11.0.0-beta.15", "rev" = "d7b1d570461c6d2adde8f3a84ae88db4823c726f", "git" = "https://github.com/lance-format/lance.git" }
+lance-linalg = { "version" = "=11.0.0-beta.15", "rev" = "d7b1d570461c6d2adde8f3a84ae88db4823c726f", "git" = "https://github.com/lance-format/lance.git" }
+lance-namespace = { "version" = "=11.0.0-beta.15", "rev" = "d7b1d570461c6d2adde8f3a84ae88db4823c726f", "git" = "https://github.com/lance-format/lance.git" }
+lance-namespace-impls = { "version" = "=11.0.0-beta.15", default-features = false, "rev" = "d7b1d570461c6d2adde8f3a84ae88db4823c726f", "git" = "https://github.com/lance-format/lance.git" }
+lance-table = { "version" = "=11.0.0-beta.15", "rev" = "d7b1d570461c6d2adde8f3a84ae88db4823c726f", "git" = "https://github.com/lance-format/lance.git" }
+lance-testing = { "version" = "=11.0.0-beta.15", "rev" = "d7b1d570461c6d2adde8f3a84ae88db4823c726f", "git" = "https://github.com/lance-format/lance.git" }
+lance-datafusion = { "version" = "=11.0.0-beta.15", "rev" = "d7b1d570461c6d2adde8f3a84ae88db4823c726f", "git" = "https://github.com/lance-format/lance.git" }
+lance-encoding = { "version" = "=11.0.0-beta.15", "rev" = "d7b1d570461c6d2adde8f3a84ae88db4823c726f", "git" = "https://github.com/lance-format/lance.git" }
+lance-arrow = { "version" = "=11.0.0-beta.15", "rev" = "d7b1d570461c6d2adde8f3a84ae88db4823c726f", "git" = "https://github.com/lance-format/lance.git" }
 ahash = "0.8"
 # Note that this one does not include pyarrow
 arrow = { version = "58.0.0", optional = false }
@@ -40,7 +42,6 @@ arrow-schema = "58.0.0"
 arrow-select = "58.0.0"
 arrow-cast = "58.0.0"
 async-trait = "0"
-bytes = "1"
 datafusion = { version = "54.0.0", default-features = false }
 datafusion-catalog = "54.0.0"
 datafusion-common = { version = "54.0.0", default-features = false }
@@ -67,12 +68,7 @@ url = "2"
 num-traits = "0.2"
 regex = "1.10"
 semver = "1.0.25"
-serde = "1"
-serde_json = "1"
-tempfile = "3.5.0"
-tokio = { version = "1.23", features = ["rt-multi-thread", "sync"] }
-uuid = { version = "1.7.0", features = ["v4"] }
-chrono = { version = "0.4", default-features = false, features = ["clock"] }
+chrono = "0.4"

 [profile.ci]
 debug = "line-tables-only"
@@ -2,7 +2,6 @@
 Check whether there are any breaking changes in the PRs between the base and head commits.
 If there are, assert that we have incremented the minor version.
 """
-
 import argparse
 import os
 from packaging.version import parse
@@ -28,7 +27,7 @@ if __name__ == "__main__":
    else:
        print("No breaking changes found.")
        exit(0)
-
+    
    last_stable_version = parse(args.last_stable_version)
    current_version = parse(args.current_version)
    if current_version.minor <= last_stable_version.minor:
@@ -1,6 +1,5 @@
 #!/usr/bin/env python3
 """Determine whether a newer Lance tag exists and expose results for CI."""
-
 from __future__ import annotations

 import argparse
@@ -37,16 +36,8 @@ class SemVer:
    prerelease: Tuple[Union[int, str], ...]

    def __lt__(self, other: "SemVer") -> bool:  # pragma: no cover - simple comparison
-        if (self.major, self.minor, self.patch) != (
-            other.major,
-            other.minor,
-            other.patch,
-        ):
-            return (self.major, self.minor, self.patch) < (
-                other.major,
-                other.minor,
-                other.patch,
-            )
+        if (self.major, self.minor, self.patch) != (other.major, other.minor, other.patch):
+            return (self.major, self.minor, self.patch) < (other.major, other.minor, other.patch)
        if self.prerelease == other.prerelease:
            return False
        if not self.prerelease:
@@ -151,9 +142,7 @@ def read_current_version(repo_root: Path) -> str:
        deps = data["workspace"]["dependencies"]
        entry = deps["lance"]
    except KeyError as exc:  # pragma: no cover - configuration guard
-        raise RuntimeError(
-            "Failed to locate workspace.dependencies.lance in Cargo.toml"
-        ) from exc
+        raise RuntimeError("Failed to locate workspace.dependencies.lance in Cargo.toml") from exc

    if isinstance(entry, str):
        raw_version = entry
@@ -1,7 +1,6 @@
 # SPDX-License-Identifier: Apache-2.0
 # SPDX-FileCopyrightText: Copyright The LanceDB Authors
 """A zero-dependency mock OpenAI embeddings API endpoint for testing purposes."""
-
 import argparse
 import json
 import http.server
@@ -23,13 +22,11 @@ class MockOpenAIRequestHandler(http.server.BaseHTTPRequestHandler):

        data = []
        for i in range(num_inputs):
-            data.append(
-                {
-                    "object": "embedding",
-                    "embedding": [0.1] * 1536,
-                    "index": i,
-                }
-            )
+            data.append({
+                "object": "embedding",
+                "embedding": [0.1] * 1536,
+                "index": i,
+            })

        response = {
            "object": "list",
@@ -38,7 +35,7 @@ class MockOpenAIRequestHandler(http.server.BaseHTTPRequestHandler):
            "usage": {
                "prompt_tokens": 0,
                "total_tokens": 0,
-            },
+            }
        }

        self.send_response(200)
@@ -7,7 +7,6 @@ from packaging.version import parse, InvalidVersion

 if __name__ == "__main__":
    import argparse
-
    parser = argparse.ArgumentParser()
    parser.add_argument("prefix", default="v")
    args = parser.parse_args()
@@ -22,7 +22,7 @@ def run_command(command: str) -> str:
 def get_latest_stable_version() -> str:
    version_line = run_command("cargo info lance | grep '^version:'")
    # Example output: "version: 0.35.0 (latest 0.37.0)"
-    match = re.search(r"\(latest ([0-9.]+)\)", version_line)
+    match = re.search(r'\(latest ([0-9.]+)\)', version_line)
    if match:
        return match.group(1)
    # Fallback: use the first version after 'version:'
@@ -69,7 +69,7 @@ def extract_default_features(line: str) -> bool:
    """
    import re

-    match = re.search(r"default-features\s*=\s*false", line)
+    match = re.search(r'default-features\s*=\s*false', line)
    return match is not None


@@ -104,7 +104,7 @@ def dict_to_toml_line(package_name: str, config: dict) -> str:
            # This shouldn't happen with our current usage
            parts.append(f'"{key}" = {json.dumps(value)}')

-    return f"{package_name} = {{ {', '.join(parts)} }}\n"
+    return f'{package_name} = {{ {", ".join(parts)} }}\n'


 def update_cargo_toml(line_updater):
@@ -119,7 +119,7 @@ def update_cargo_toml(line_updater):
    lance_line = ""
    is_parsing_lance_line = False
    for line in lines:
-        if re.match(r"^lance(?:\s|[-_])", line):
+        if line.startswith("lance"):
            # Check if this is a single-line or multi-line entry
            # Single-line entries either:
            # 1. End with } (complete inline table)
@@ -1,185 +0,0 @@
-import os
-import stat
-import subprocess
-import sys
-import tempfile
-import textwrap
-import unittest
-from pathlib import Path
-
-
-REPO_ROOT = Path(__file__).resolve().parents[2]
-SCRIPT = REPO_ROOT / "ci" / "set_lance_version.py"
-LANCE_GIT_URL = "https://github.com/lance-format/lance.git"
-
-CARGO_TOML = """\
-[workspace.dependencies]
-lance = { "version" = "=1.0.0", default-features = false, "features" = ["dynamodb"] }
-lance-core = "1.0.0"
-lance_datafusion = {
-    "version" = "=1.0.0",
-    "features" = ["substrait"]
-}
-lancedb = { path = "rust/lancedb", default-features = false }
-lancedb-common = { path = "rust/lancedb-common" }
-lancewood = "1.0.0"
-my-lance = "1.0.0"
-"""
-
-UNTOUCHED_DEPENDENCIES = """\
-lancedb = { path = "rust/lancedb", default-features = false }
-lancedb-common = { path = "rust/lancedb-common" }
-lancewood = "1.0.0"
-my-lance = "1.0.0"
-"""
-
-
-class SetLanceVersionTest(unittest.TestCase):
-    def test_supported_update_modes_only_rewrite_lance_dependencies(self):
-        cases = {
-            "stable": (
-                """\
-lance = { "version" = "=9.9.9", default-features = false, "features" = ["dynamodb"] }
-lance-core = "=9.9.9"
-lance_datafusion = { "version" = "=9.9.9", "features" = ["substrait"] }
-""",
-                ["cargo info lance", "cargo metadata"],
-            ),
-            "preview": (
-                f"""\
-lance = {{ "version" = "=10.0.0-beta.3", default-features = false, "features" = ["dynamodb"], "tag" = "v10.0.0-beta.3", "git" = "{LANCE_GIT_URL}" }}
-lance-core = {{ "version" = "=10.0.0-beta.3", "tag" = "v10.0.0-beta.3", "git" = "{LANCE_GIT_URL}" }}
-lance_datafusion = {{ "version" = "=10.0.0-beta.3", "features" = ["substrait"], "tag" = "v10.0.0-beta.3", "git" = "{LANCE_GIT_URL}" }}
-""",
-                ["git ls-remote --tags", "cargo metadata"],
-            ),
-            "local": (
-                """\
-lance = { "path" = "../lance/rust/lance", default-features = false, "features" = ["dynamodb"] }
-lance-core = { "path" = "../lance/rust/lance-core" }
-lance_datafusion = { "path" = "../lance/rust/lance_datafusion", "features" = ["substrait"] }
-""",
-                ["cargo metadata"],
-            ),
-            "v8.1.2": (
-                """\
-lance = { "version" = "=8.1.2", default-features = false, "features" = ["dynamodb"] }
-lance-core = "=8.1.2"
-lance_datafusion = { "version" = "=8.1.2", "features" = ["substrait"] }
-""",
-                ["cargo metadata"],
-            ),
-            "v8.2.0-beta.4": (
-                f"""\
-lance = {{ "version" = "=8.2.0-beta.4", default-features = false, "features" = ["dynamodb"], "tag" = "v8.2.0-beta.4", "git" = "{LANCE_GIT_URL}" }}
-lance-core = {{ "version" = "=8.2.0-beta.4", "tag" = "v8.2.0-beta.4", "git" = "{LANCE_GIT_URL}" }}
-lance_datafusion = {{ "version" = "=8.2.0-beta.4", "features" = ["substrait"], "tag" = "v8.2.0-beta.4", "git" = "{LANCE_GIT_URL}" }}
-""",
-                ["cargo metadata"],
-            ),
-        }
-
-        for version, (updated_dependencies, expected_commands) in cases.items():
-            with self.subTest(version=version), tempfile.TemporaryDirectory() as tmp:
-                workdir = Path(tmp)
-                (workdir / "Cargo.toml").write_text(CARGO_TOML)
-                command_log = workdir / "commands.log"
-                fake_bin = workdir / "bin"
-                fake_bin.mkdir()
-                self._write_fake_executables(fake_bin)
-                self._write_fake_python_dependencies(workdir)
-
-                env = os.environ.copy()
-                env["PATH"] = os.pathsep.join([str(fake_bin), env["PATH"]])
-                env["FAKE_COMMAND_LOG"] = str(command_log)
-                env["PYTHONPATH"] = os.pathsep.join(
-                    filter(None, [str(workdir), env.get("PYTHONPATH")])
-                )
-                result = subprocess.run(
-                    [sys.executable, str(SCRIPT), version],
-                    cwd=workdir,
-                    env=env,
-                    capture_output=True,
-                    text=True,
-                    timeout=10,
-                )
-
-                self.assertEqual(result.returncode, 0, result.stderr)
-                self.assertEqual(
-                    (workdir / "Cargo.toml").read_text(),
-                    "[workspace.dependencies]\n"
-                    + updated_dependencies
-                    + UNTOUCHED_DEPENDENCIES,
-                )
-                commands = command_log.read_text().splitlines()
-                for command in expected_commands:
-                    self.assertTrue(
-                        any(line.startswith(command) for line in commands),
-                        f"{command!r} not found in {commands!r}",
-                    )
-
-    def _write_fake_executables(self, fake_bin: Path) -> None:
-        cargo = fake_bin / "cargo"
-        cargo.write_text(
-            textwrap.dedent(
-                """\
-                #!/bin/sh
-                printf 'cargo %s\\n' "$*" >> "$FAKE_COMMAND_LOG"
-                case "$1" in
-                  info)
-                    printf '%s\\n' 'version: 8.8.8 (latest 9.9.9)'
-                    ;;
-                  metadata)
-                    ;;
-                  *)
-                    exit 2
-                    ;;
-                esac
-                """
-            )
-        )
-        cargo.chmod(cargo.stat().st_mode | stat.S_IXUSR)
-
-        git = fake_bin / "git"
-        git.write_text(
-            textwrap.dedent(
-                """\
-                #!/bin/sh
-                printf 'git %s\\n' "$*" >> "$FAKE_COMMAND_LOG"
-                if [ "$1" != "ls-remote" ]; then
-                  exit 2
-                fi
-                printf '%s\\n' \\
-                  '111111 refs/tags/v9.9.9' \\
-                  '222222 refs/tags/v10.0.0-beta.1' \\
-                  '333333 refs/tags/v10.0.0-beta.3'
-                """
-            )
-        )
-        git.chmod(git.stat().st_mode | stat.S_IXUSR)
-
-    def _write_fake_python_dependencies(self, workdir: Path) -> None:
-        packaging = workdir / "packaging"
-        packaging.mkdir()
-        (packaging / "__init__.py").write_text("")
-        (packaging / "version.py").write_text(
-            textwrap.dedent(
-                """\
-                class Version:
-                    def __init__(self, value):
-                        release, _, prerelease = value.partition("-beta.")
-                        self._key = (
-                            tuple(int(part) for part in release.split(".")),
-                            not prerelease,
-                            int(prerelease or 0),
-                        )
-
-                    def __lt__(self, other):
-                        return self._key < other._key
-                """
-            )
-        )
-
-
-if __name__ == "__main__":
-    unittest.main()
@@ -12,7 +12,7 @@ with open("Cargo.toml", "rb") as f:
            elif isinstance(dep, dict):
                # Version doesn't have the beta tag in it, so we instead look
                # at the git tag.
-                version = dep.get("tag", dep.get("version"))
+                version = dep.get('tag', dep.get('version'))
            else:
                raise ValueError("Unexpected type for dependency: " + str(dep))

@@ -177,11 +177,6 @@ multiple-versions = "warn"
 # Wildcard version requirements (`foo = "*"`) are a footgun — they let any
 # future release in without review. Ban them outright.
 wildcards = "deny"
-# Lint every dependency declared by a workspace member against the shared
-# `[workspace.dependencies]` table: any crate used by more than one member must
-# go through `workspace = true`, and entries nothing uses are an error. This
-# keeps versions from drifting between the core crate and the bindings.
-workspace-dependencies = { duplicates = "deny", unused = "deny" }
 # Internal workspace crates reference each other via `path = "..."`, which
 # cargo-deny sees as a wildcard version. That's fine for private workspace
 # members (not published to crates.io), so allow it specifically for paths.
@@ -5,5 +5,5 @@ mkdocs-autorefs>=0.5,<=1.0
 mkdocstrings[python]>=0.24,<1.0
 griffe>=0.40,<1.0
 mkdocs-render-swagger-plugin>=0.1.0
-pydantic>=2.7.4,<3
-mkdocs-redirects>=1.2.0
+pydantic>=2.0,<3.0
+mkdocs-redirects>=1.2.0
@@ -14,7 +14,7 @@ Add the following dependency to your `pom.xml`:
 <dependency>
    <groupId>com.lancedb</groupId>
    <artifactId>lancedb-core</artifactId>
-    <version>0.38.0-beta.7</version>
+    <version>0.38.0-beta.2</version>
 </dependency>
 ```

@@ -37,31 +37,6 @@ latest and stays writable.

 ***

-### cherryPick()
-
-```ts
-cherryPick(fromBranch, dryRun): Promise<CherryPickResult>
-```
-
-Cherry-pick a branch onto main.
-
-Set `dryRun` to `true` to preview. A failed cherry-pick resolves
-with `status: "failed"` instead of throwing.
-
-#### Parameters
-
-* **fromBranch**: `string`
-    Branch to cherry-pick from.
-
-* **dryRun**: `boolean` = `false`
-    When true, only preview. Defaults to false.
-
-#### Returns
-
-`Promise`&lt;[`CherryPickResult`](../interfaces/CherryPickResult.md)&gt;
-
-***
-
 ### create()

 ```ts
@@ -137,3 +112,28 @@ List all branches, mapping name to branch metadata.
 #### Returns

 `Promise`&lt;`Record`&lt;`string`, [`BranchContents`](BranchContents.md)&gt;&gt;
+
+***
+
+### merge()
+
+```ts
+merge(fromBranch, dryRun): Promise<MergeBranchResult>
+```
+
+Merge a branch into main.
+
+Set `dryRun` to `true` to preview the merge. A rejected merge resolves
+with `status: "rejected"` instead of throwing.
+
+#### Parameters
+
+* **fromBranch**: `string`
+    Branch to merge from.
+
+* **dryRun**: `boolean` = `false`
+    When true, only preview the merge. Defaults to false.
+
+#### Returns
+
+`Promise`&lt;[`MergeBranchResult`](../interfaces/MergeBranchResult.md)&gt;
@@ -169,45 +169,6 @@ Creates a new empty Table

 ***

-### createMaterializedView()
-
-```ts
-abstract createMaterializedView(
-   name,
-   source,
-   options?): Promise<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
-`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.
-
-#### Parameters
-
-* **name**: `string`
-
-* **source**: `string`
-
-* **options?**
-
-* **options.limit?**: `number`
-
-* **options.select?**: [`MaterializedViewSelect`](../type-aliases/MaterializedViewSelect.md)
-
-* **options.where?**: `string`
-
-#### Returns
-
-`Promise`&lt;[`MaterializedView`](MaterializedView.md)&gt;
-
-***
-
 ### createNamespace()

 ```ts
@@ -538,22 +499,6 @@ List server-side jobs across the database's tables.

 ***

-### listMaterializedViews()
-
-```ts
-abstract listMaterializedViews(): Promise<string[]>
-```
-
-The names of the materialized views in this database.
-
-Found by reading every table's schema, so this costs an open per table.
-
-#### Returns
-
-`Promise`&lt;`string`[]&gt;
-
-***
-
 ### listNamespaces()

 ```ts
@@ -584,23 +529,68 @@ Child namespace names and

 ***

-### openMaterializedView()
+### listTables()
+
+#### listTables(options)

 ```ts
-abstract openMaterializedView(name): Promise<MaterializedView>
+abstract listTables(options?): Promise<ListTablesResponse>
 ```

-Open the materialized view named `name`.
+List a page of tables in this database.

-Rejects a table that exists but is not a materialized view.
+Results may be paginated. To retrieve subsequent pages, pass the
+`pageToken` returned by a previous call. A page may be shorter than
+`limit` without being the last one, so walk until the response carries no
+page token:

-#### Parameters
+```ts
+const names = [];
+let pageToken = undefined;
+do {
+  const page = await conn.listTables({ pageToken, limit: 100 });
+  names.push(...page.tables);
+  pageToken = page.pageToken;
+} while (pageToken);
+```

-* **name**: `string`
+##### Parameters

-#### Returns
+* **options?**: `Partial`&lt;[`ListTablesOptions`](../interfaces/ListTablesOptions.md)&gt;
+    Pagination options
+    (`pageToken`, `limit`).

-`Promise`&lt;[`MaterializedView`](MaterializedView.md)&gt;
+##### Returns
+
+`Promise`&lt;[`ListTablesResponse`](../interfaces/ListTablesResponse.md)&gt;
+
+Table names and an optional token
+  for fetching the next page.
+
+#### listTables(namespacePath, options)
+
+```ts
+abstract listTables(namespacePath?, options?): Promise<ListTablesResponse>
+```
+
+List a page of tables in this database.
+
+##### Parameters
+
+* **namespacePath?**: `string`[]
+    The namespace path to list tables from
+    (defaults to root namespace)
+
+* **options?**: `Partial`&lt;[`ListTablesOptions`](../interfaces/ListTablesOptions.md)&gt;
+    Pagination options
+    (`pageToken`, `limit`).
+
+##### Returns
+
+`Promise`&lt;[`ListTablesResponse`](../interfaces/ListTablesResponse.md)&gt;
+
+Table names and an optional token
+  for fetching the next page.

 ***

@@ -613,13 +603,18 @@ abstract openTable(
   options?): Promise<Table>
 ```

+Open a table in the database.
+
 #### Parameters

 * **name**: `string`
+    The name of the table

 * **namespacePath?**: `string`[]
+    The namespace path of the table (defaults to root namespace)

 * **options?**: `Partial`&lt;[`OpenTableOptions`](../interfaces/OpenTableOptions.md)&gt;
+    Additional options

 #### Returns

@@ -660,7 +655,7 @@ a "not supported" error.

 ***

-### tableNames()
+### ~~tableNames()~~

 #### tableNames(options)

@@ -682,6 +677,10 @@ Tables will be returned in lexicographical order.

 `Promise`&lt;`string`[]&gt;

+##### Deprecated
+
+Use [Connection.listTables](Connection.md#listtables) instead.
+
 #### tableNames(namespacePath, options)

 ```ts
@@ -704,3 +703,7 @@ Tables will be returned in lexicographical order.
 ##### Returns

 `Promise`&lt;`string`[]&gt;
+
+##### Deprecated
+
+Use [Connection.listTables](Connection.md#listtables) instead.
@@ -1,101 +0,0 @@
-[**@lancedb/lancedb**](../README.md) • **Docs**
-
-***
-
-[@lancedb/lancedb](../globals.md) / MaterializedView
-
-# Class: MaterializedView
-
-A handle on a materialized view: its table plus its definition.
-
-Obtained from [Connection#createMaterializedView](Connection.md#creatematerializedview) or
-[Connection#openMaterializedView](Connection.md#openmaterializedview). The view is a normal table --
-queries, indexes and search all apply through [MaterializedView#table](MaterializedView.md#table)
-- whose contents are maintained by [MaterializedView#refresh](MaterializedView.md#refresh).
-
-## Constructors
-
-### new MaterializedView()
-
-```ts
-new MaterializedView(table): MaterializedView
-```
-
-#### Parameters
-
-* **table**: [`Table`](Table.md)
-
-#### Returns
-
-[`MaterializedView`](MaterializedView.md)
-
-## Accessors
-
-### name
-
-```ts
-get name(): string
-```
-
-#### Returns
-
-`string`
-
-## Methods
-
-### definition()
-
-```ts
-definition(): Promise<MaterializedViewDefinition>
-```
-
-The query that defines the view, read from its stored schema.
-
-#### Returns
-
-`Promise`&lt;[`MaterializedViewDefinition`](../interfaces/MaterializedViewDefinition.md)&gt;
-
-***
-
-### refresh()
-
-```ts
-refresh(options?): Promise<RefreshMaterializedViewResult>
-```
-
-Recompute the view from its source.
-
-The refresh is incremental when the source's changes can be reconciled
-into the view -- rows added, changed or removed since the last one --
-and otherwise rebuilds. `full` forces a rebuild; `sourceVersion`
-refreshes to that source version instead of the latest.
-
-Concurrent refreshes of one view do not duplicate its rows. Two that
-plan the same source rows conflict on commit, and the loser throws
-rather than writing them a second time.
-
-#### Parameters
-
-* **options?**
-
-* **options.full?**: `boolean`
-
-* **options.sourceVersion?**: `number`
-
-#### Returns
-
-`Promise`&lt;[`RefreshMaterializedViewResult`](../interfaces/RefreshMaterializedViewResult.md)&gt;
-
-***
-
-### table()
-
-```ts
-table(): Table
-```
-
-The view, as the table it is.
-
-#### Returns
-
-[`Table`](Table.md)
@@ -28,7 +28,6 @@
 - [Job](classes/Job.md)
 - [MakeArrowTableOptions](classes/MakeArrowTableOptions.md)
 - [MatchQuery](classes/MatchQuery.md)
- [MaterializedView](classes/MaterializedView.md)
 - [MergeInsertBuilder](classes/MergeInsertBuilder.md)
 - [MultiMatchQuery](classes/MultiMatchQuery.md)
 - [NativeJsHeaderProvider](classes/NativeJsHeaderProvider.md)
@@ -60,9 +59,6 @@
 - [BranchIndexSummary](interfaces/BranchIndexSummary.md)
 - [BranchRowCountSummary](interfaces/BranchRowCountSummary.md)
 - [BucketStats](interfaces/BucketStats.md)
- [CherryPickError](interfaces/CherryPickError.md)
- [CherryPickPreview](interfaces/CherryPickPreview.md)
- [CherryPickResult](interfaces/CherryPickResult.md)
 - [ClientConfig](interfaces/ClientConfig.md)
 - [ColumnAlteration](interfaces/ColumnAlteration.md)
 - [ColumnOrdering](interfaces/ColumnOrdering.md)
@@ -100,10 +96,14 @@
 - [JobInfo](interfaces/JobInfo.md)
 - [ListNamespacesOptions](interfaces/ListNamespacesOptions.md)
 - [ListNamespacesResponse](interfaces/ListNamespacesResponse.md)
+- [ListTablesOptions](interfaces/ListTablesOptions.md)
+- [ListTablesResponse](interfaces/ListTablesResponse.md)
 - [LsmStats](interfaces/LsmStats.md)
 - [LsmWriteSpec](interfaces/LsmWriteSpec.md)
- [MaterializedViewDefinition](interfaces/MaterializedViewDefinition.md)
 - [MemtableStats](interfaces/MemtableStats.md)
+- [MergeBlocker](interfaces/MergeBlocker.md)
+- [MergeBranchResult](interfaces/MergeBranchResult.md)
+- [MergePreview](interfaces/MergePreview.md)
 - [MergeResult](interfaces/MergeResult.md)
 - [NativeOAuthConfig](interfaces/NativeOAuthConfig.md)
 - [OAuthConfig](interfaces/OAuthConfig.md)
@@ -112,7 +112,6 @@
 - [OptimizeStats](interfaces/OptimizeStats.md)
 - [QueryExecutionOptions](interfaces/QueryExecutionOptions.md)
 - [RefreshColumnResult](interfaces/RefreshColumnResult.md)
- [RefreshMaterializedViewResult](interfaces/RefreshMaterializedViewResult.md)
 - [RemovalStats](interfaces/RemovalStats.md)
 - [RenameTableOptions](interfaces/RenameTableOptions.md)
 - [RestNamespaceConfig](interfaces/RestNamespaceConfig.md)
@@ -145,7 +144,6 @@
 - [FieldLike](type-aliases/FieldLike.md)
 - [IntoSql](type-aliases/IntoSql.md)
 - [IntoVector](type-aliases/IntoVector.md)
- [MaterializedViewSelect](type-aliases/MaterializedViewSelect.md)
 - [MultiVector](type-aliases/MultiVector.md)
 - [RecordBatchLike](type-aliases/RecordBatchLike.md)
 - [SchemaLike](type-aliases/SchemaLike.md)
@@ -50,14 +50,6 @@ changedColumns: BranchColumnChange[];

 ***

-### errors
-
-```ts
-errors: CherryPickError[];
-```
-
-***
-
 ### fromBranch

 ```ts
@@ -74,6 +66,22 @@ mainVersion: number;

 ***

+### mergeBlockers
+
+```ts
+mergeBlockers: MergeBlocker[];
+```
+
+***
+
+### mergeable
+
+```ts
+mergeable: boolean;
+```
+
+***
+
 ### parentVersion

 ```ts
@@ -1,17 +0,0 @@
-[**@lancedb/lancedb**](../README.md) • **Docs**
-
-***
-
-[@lancedb/lancedb](../globals.md) / CherryPickPreview
-
-# Interface: CherryPickPreview
-
-Changes that would be, or were, promoted by a cherry-pick.
-
-## Properties
-
-### promotedColumns
-
-```ts
-promotedColumns: string[];
-```
@@ -0,0 +1,33 @@
+[**@lancedb/lancedb**](../README.md) • **Docs**
+
+***
+
+[@lancedb/lancedb](../globals.md) / ListTablesOptions
+
+# Interface: ListTablesOptions
+
+## Properties
+
+### limit?
+
+```ts
+optional limit: number;
+```
+
+An upper bound on how many tables to return.
+
+A page may hold fewer than this and still not be the last one, so continue
+while the response carries a page token rather than while pages are full.
+
+***
+
+### pageToken?
+
+```ts
+optional pageToken: string;
+```
+
+Token from a previous response for pagination.
+
+The token is opaque: it carries whatever the database needs to resume, and
+callers should not construct or interpret one.
@@ -0,0 +1,23 @@
+[**@lancedb/lancedb**](../README.md) • **Docs**
+
+***
+
+[@lancedb/lancedb](../globals.md) / ListTablesResponse
+
+# Interface: ListTablesResponse
+
+## Properties
+
+### pageToken?
+
+```ts
+optional pageToken: string;
+```
+
+***
+
+### tables
+
+```ts
+tables: string[];
+```
@@ -1,59 +0,0 @@
-[**@lancedb/lancedb**](../README.md) • **Docs**
-
-***
-
-[@lancedb/lancedb](../globals.md) / MaterializedViewDefinition
-
-# Interface: MaterializedViewDefinition
-
-The query that defines a materialized view.
-
-## Properties
-
-### filter?
-
-```ts
-optional filter: 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.
-
-***
-
-### sourceTable
-
-```ts
-sourceTable: string;
-```
-
-Name of the source table, in the same database as the view.
@@ -2,11 +2,11 @@

 ***

-[@lancedb/lancedb](../globals.md) / CherryPickError
+[@lancedb/lancedb](../globals.md) / MergeBlocker

-# Interface: CherryPickError
+# Interface: MergeBlocker

-A reason why a cherry-pick cannot currently land.
+A reason why a branch cannot currently be merged.

 ## Properties

@@ -2,11 +2,11 @@

 ***

-[@lancedb/lancedb](../globals.md) / CherryPickResult
+[@lancedb/lancedb](../globals.md) / MergeBranchResult

-# Interface: CherryPickResult
+# Interface: MergeBranchResult

-Result of previewing or attempting a cherry-pick.
+Result of previewing or attempting a branch merge.

 ## Properties

@@ -29,7 +29,7 @@ optional mainVersionAfter: number;
 ### preview

 ```ts
-preview: CherryPickPreview;
+preview: MergePreview;
 ```

 ***
@@ -38,9 +38,9 @@ preview: CherryPickPreview;

 ```ts
 status:
-  | "failed"
  | "unknown"
+  | "rejected"
  | "ready"
  | "notImplemented"
-  | "cherryPicked";
+  | "merged";
 ```
@@ -0,0 +1,17 @@
+[**@lancedb/lancedb**](../README.md) • **Docs**
+
+***
+
+[@lancedb/lancedb](../globals.md) / MergePreview
+
+# Interface: MergePreview
+
+Changes that would be, or were, promoted by a branch merge.
+
+## Properties
+
+### promotedColumns
+
+```ts
+promotedColumns: string[];
+```
@@ -1,41 +0,0 @@
-[**@lancedb/lancedb**](../README.md) • **Docs**
-
-***
-
-[@lancedb/lancedb](../globals.md) / RefreshMaterializedViewResult
-
-# Interface: RefreshMaterializedViewResult
-
-## Properties
-
-### mode
-
-```ts
-mode: string;
-```
-
-How the view was brought up to date: "rebuild", "incremental" or "no_op".
-
-***
-
-### rowsWritten
-
-```ts
-rowsWritten: number;
-```
-
-***
-
-### sourceVersion
-
-```ts
-sourceVersion: number;
-```
-
-***
-
-### version
-
-```ts
-version: number;
-```
@@ -4,11 +4,16 @@

 [@lancedb/lancedb](../globals.md) / TableNamesOptions

-# Interface: TableNamesOptions
+# Interface: ~~TableNamesOptions~~
+
+## Deprecated
+
+Use [ListTablesOptions](ListTablesOptions.md) with [Connection.listTables](../classes/Connection.md#listtables)
+instead.

 ## Properties

-### limit?
+### ~~limit?~~

 ```ts
 optional limit: number;
@@ -18,7 +23,7 @@ An optional limit to the number of results to return.

 ***

-### startAfter?
+### ~~startAfter?~~

 ```ts
 optional startAfter: string;
@@ -25,12 +25,9 @@
 ### Type Aliases

 - [CreateReturnType](type-aliases/CreateReturnType.md)
- [EmbeddingMetadataEntry](type-aliases/EmbeddingMetadataEntry.md)
- [ResolvedEmbeddingFunctionConfig](type-aliases/ResolvedEmbeddingFunctionConfig.md)

 ### Functions

 - [LanceSchema](functions/LanceSchema.md)
 - [getRegistry](functions/getRegistry.md)
- [parseEmbeddingMetadata](functions/parseEmbeddingMetadata.md)
 - [register](functions/register.md)
@@ -1,22 +0,0 @@
-[**@lancedb/lancedb**](../../../README.md) • **Docs**
-
-***
-
-[@lancedb/lancedb](../../../globals.md) / [embedding](../README.md) / parseEmbeddingMetadata
-
-# Function: parseEmbeddingMetadata()
-
-```ts
-function parseEmbeddingMetadata(json): EmbeddingMetadataEntry[]
-```
-
-The single parser for `embedding_functions` schema metadata: every reader
-goes through here, so the wire contract cannot fork between them.
-
-## Parameters
-
-* **json**: `string`
-
-## Returns
-
-[`EmbeddingMetadataEntry`](../type-aliases/EmbeddingMetadataEntry.md)[]
@@ -1,40 +0,0 @@
-[**@lancedb/lancedb**](../../../README.md) • **Docs**
-
-***
-
-[@lancedb/lancedb](../../../globals.md) / [embedding](../README.md) / EmbeddingMetadataEntry
-
-# Type Alias: EmbeddingMetadataEntry
-
-```ts
-type EmbeddingMetadataEntry: object;
-```
-
-One entry of the `embedding_functions` schema metadata, with the column
-keys normalized across the bindings' spellings.
-
-## Type declaration
-
-### model
-
-```ts
-model: EmbeddingFunction["TOptions"];
-```
-
-### name
-
-```ts
-name: string;
-```
-
-### sourceColumn
-
-```ts
-sourceColumn: string;
-```
-
-### vectorColumn
-
-```ts
-vectorColumn: string;
-```
@@ -1,22 +0,0 @@
-[**@lancedb/lancedb**](../../../README.md) • **Docs**
-
-***
-
-[@lancedb/lancedb](../../../globals.md) / [embedding](../README.md) / ResolvedEmbeddingFunctionConfig
-
-# Type Alias: ResolvedEmbeddingFunctionConfig
-
-```ts
-type ResolvedEmbeddingFunctionConfig: EmbeddingFunctionConfig & object;
-```
-
-An [EmbeddingFunctionConfig] read back from table metadata, where the
-vector column is always recorded.
-
-## Type declaration
-
-### vectorColumn
-
-```ts
-vectorColumn: string;
-```
@@ -1,14 +0,0 @@
-[**@lancedb/lancedb**](../README.md) • **Docs**
-
-***
-
-[@lancedb/lancedb](../globals.md) / MaterializedViewSelect
-
-# Type Alias: MaterializedViewSelect
-
-```ts
-type MaterializedViewSelect: (string | [string, string])[] | Record<string, string>;
-```
-
-The view's columns: column names, `[alias, SQL expression]` pairs, or a
-record of the same. A bare name projects itself.
@@ -54,60 +54,6 @@ listing a storage directory.

 ::: lancedb.LsmWriteSpec

-## Functions and Jobs
-
-::: lancedb.functions.FunctionArtifact
-
-::: lancedb.functions.FunctionParameter
-
-::: lancedb.functions.FunctionResultField
-
-::: lancedb.functions.FunctionOutput
-
-::: lancedb.functions.FunctionSignature
-
-::: lancedb.functions.PythonEnvironmentSpec
-
-::: lancedb.functions.udf
-
-::: lancedb.functions.UdfDefinition
-
-::: lancedb.functions.FunctionRegistrationRequest
-
-::: lancedb.functions.FunctionArtifactRequest
-
-::: lancedb.functions.FunctionArtifactContent
-
-::: lancedb.functions.PythonAdapterSpec
-
-::: lancedb.functions.FunctionVersion
-
-::: lancedb.functions.PythonRuntimeSpec
-
-::: lancedb.functions.FunctionVersionRef
-
-::: lancedb.functions.ApplicationInput
-
-::: lancedb.functions.FunctionApplication
-
-::: lancedb.functions.InputBinding
-
-::: lancedb.functions.OutputMapping
-
-::: lancedb.functions.FunctionBinding
-
-::: lancedb.functions.RefreshColumnResult
-
-::: lancedb.job.Job
-
-::: lancedb.job.AsyncJob
-
-## Materialized Views (Synchronous)
-
-::: lancedb.materialized_view.MaterializedView
-
-::: lancedb.materialized_view.MaterializedViewDefinition
-
 ## Expressions

 Type-safe expression builder for filters and projections. Use these instead
@@ -207,9 +153,8 @@ The same option is available on `lancedb.tokenize(...)` and the deprecated
 ```python
 import lancedb

-tokens = list(
-    lancedb.tokenize("acme makes searchable data", custom_stop_words=["acme"])
-)
+tokens = list(lancedb.tokenize("acme makes searchable data",
+                               custom_stop_words=["acme"]))
 ```

 ::: lancedb.tokenize
@@ -261,8 +206,6 @@ instead of being materialized with the rest of the row.

 ::: lancedb.streaming.StreamingDataset

-::: lancedb.streaming.StreamingDataLoader
-
 ::: lancedb.permutation.permutation_builder

 ::: lancedb.permutation.PermutationBuilder
@@ -303,10 +246,6 @@ Table hold your actual data as a collection of records / rows.

 ::: lancedb.table.AsyncBranches

-## Materialized Views (Asynchronous)
-
-::: lancedb.materialized_view.AsyncMaterializedView
-
 ## Indices (Asynchronous)

 Indices can be created on a table to speed up queries. This section
@@ -8,7 +8,7 @@
    <parent>
      <groupId>com.lancedb</groupId>
      <artifactId>lancedb-parent</artifactId>
-      <version>0.38.0-beta.7</version>
+      <version>0.38.0-beta.2</version>
      <relativePath>../pom.xml</relativePath>
    </parent>

@@ -6,7 +6,7 @@

    <groupId>com.lancedb</groupId>
    <artifactId>lancedb-parent</artifactId>
-    <version>0.38.0-beta.7</version>
+    <version>0.38.0-beta.2</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>11.0.0-beta.22</lance-core.version>
+        <lance-core.version>11.0.0-beta.15</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>
@@ -1,7 +1,7 @@
 [package]
 name = "lancedb-nodejs"
 edition.workspace = true
-version = "0.38.0-beta.7"
+version = "0.38.0-beta.2"
 publish = false
 license.workspace = true
 description.workspace = true
@@ -16,12 +16,12 @@ crate-type = ["cdylib"]
 async-trait.workspace = true
 arrow-ipc.workspace = true
 arrow-array.workspace = true
-arrow-buffer.workspace = true
+arrow-buffer = "58.0.0"
 half.workspace = true
 arrow-schema.workspace = true
 env_logger.workspace = true
 futures.workspace = true
-lancedb.workspace = true
+lancedb = { path = "../rust/lancedb", default-features = false }
 lance-namespace.workspace = true
 napi = { version = "3.8.3", default-features = false, features = [
    "napi9",
@@ -29,8 +29,8 @@ napi = { version = "3.8.3", default-features = false, features = [
    "chrono_date",
    "serde-json",
 ] }
-chrono.workspace = true
-serde_json.workspace = true
+chrono = { version = "0.4", default-features = false, features = ["clock"] }
+serde_json = "1"
 napi-derive = "3.5.2"
 # Prevent dynamic linking of lzma, which comes from datafusion
 lzma-sys = { version = "0.1", features = ["static"] }
@@ -173,36 +173,6 @@ describe.each([arrow15, arrow16, arrow17, arrow18])(
    }

    describe("The function makeArrowTable", function () {
-      it("accepts snake_case embedding metadata like camelCase", function () {
-        const spellings = [
-          // biome-ignore lint/style/useNamingConvention: the Python wire spelling
-          { source_column: "text", vector_column: "vector" },
-          { sourceColumn: "text", vectorColumn: "vector" },
-        ];
-        for (const columns of spellings) {
-          const schema = new Schema(
-            [
-              new Field("text", new Utf8(), false),
-              new Field(
-                "vector",
-                new FixedSizeList(3, new Field("item", new Float32(), true)),
-                false,
-              ),
-            ],
-            new Map([
-              [
-                "embedding_functions",
-                JSON.stringify([{ name: "mock", model: {}, ...columns }]),
-              ],
-            ]),
-          );
-          // The vector field is non-nullable and absent from the data; only a
-          // recognized embedding config makes that acceptable.
-          const table = makeArrowTable([{ text: "hello" }], { schema });
-          expect(table.numRows).toBe(1);
-        }
-      });
-
      it("will use data types from a provided schema instead of inference", async function () {
        const schema = new Schema([
          new Field("a", new Int32(), false),
@@ -4,7 +4,13 @@
 import { readdirSync } from "fs";
 import { Field, Float64, Schema } from "apache-arrow";
 import * as tmp from "tmp";
-import { Connection, Table, connect, connectNamespace } from "../lancedb";
+import {
+  Connection,
+  ListTablesResponse,
+  Table,
+  connect,
+  connectNamespace,
+} from "../lancedb";
 import { LocalTable } from "../lancedb/table";

 describe("when connecting", () => {
@@ -129,6 +135,56 @@ describe("given a connection", () => {
    expect(tables).toEqual(["b", "c"]);
  });

+  it("should list tables with a page token", async () => {
+    const db = await connect(tmpDir.name);
+
+    await db.createTable("b", [{ id: 1 }]);
+    await db.createTable("a", [{ id: 1 }]);
+    await db.createTable("c", [{ id: 1 }]);
+
+    const all = await db.listTables();
+    expect(all.tables).toEqual(["a", "b", "c"]);
+    expect(all.pageToken).toBeUndefined();
+
+    const first = await db.listTables({ limit: 1 });
+    expect(first.tables).toEqual(["a"]);
+    expect(first.pageToken).toBeDefined();
+
+    const second = await db.listTables({
+      limit: 1,
+      pageToken: first.pageToken,
+    });
+    expect(second.tables).toEqual(["b"]);
+  });
+
+  it("should visit every table exactly once when paging", async () => {
+    const db = await connect(tmpDir.name);
+
+    const created = ["a", "b", "c", "d", "e"];
+    for (const name of created) {
+      await db.createTable(name, [{ id: 1 }]);
+    }
+
+    const seen: string[] = [];
+    let pageToken: string | undefined = undefined;
+    do {
+      const page: ListTablesResponse = await db.listTables({
+        limit: 2,
+        pageToken,
+      });
+      seen.push(...page.tables);
+      pageToken = page.pageToken;
+    } while (pageToken);
+
+    expect(seen.sort()).toEqual(created);
+  });
+
+  it("should reject listTables on a closed connection", async () => {
+    const db = await connect(tmpDir.name);
+    db.close();
+    await expect(db.listTables()).rejects.toThrow("Connection is closed");
+  });
+
  it("should create tables in v2 mode", async () => {
    const db = await connect(tmpDir.name);
    const data = [...Array(10000).keys()].map((i) => ({ id: i }));
@@ -487,52 +487,4 @@ describe("embedding functions", () => {
      expect(stringSchema3).toEqual(stringExpectedSchema);
    },
  );
-  test("parses one function writing several vector columns", async () => {
-    class MockEmbeddingFunction extends EmbeddingFunction<string> {
-      ndims() {
-        return 3;
-      }
-      embeddingDataType(): Float {
-        return new Float32();
-      }
-      async computeQueryEmbeddings(_data: string) {
-        return [1, 2, 3];
-      }
-      async computeSourceEmbeddings(data: string[]) {
-        return Array.from({ length: data.length }).fill([
-          1, 2, 3,
-        ]) as number[][];
-      }
-    }
-    const registry = getRegistry();
-    registry.register("multi_output_mock")(MockEmbeddingFunction);
-
-    // A materialized view can project one source vector column under two
-    // names, so a table's configuration names the same function twice.
-    const parsed = await registry.parseFunctions(
-      new Map([
-        [
-          "embedding_functions",
-          JSON.stringify([
-            {
-              name: "multi_output_mock",
-              sourceColumn: "text",
-              vectorColumn: "vector_a",
-              model: {},
-            },
-            {
-              name: "multi_output_mock",
-              sourceColumn: "text",
-              vectorColumn: "vector_b",
-              model: {},
-            },
-          ]),
-        ],
-      ]),
-    );
-
-    expect(
-      [...parsed.values()].map(({ vectorColumn }) => vectorColumn).sort(),
-    ).toEqual(["vector_a", "vector_b"]);
-  });
 });
@@ -1,147 +0,0 @@
-// SPDX-License-Identifier: Apache-2.0
-// SPDX-FileCopyrightText: Copyright The LanceDB Authors
-
-import * as tmp from "tmp";
-
-import { Connection, connect } from "../lancedb";
-import {
-  DEFINITION_META_KEY,
-  definitionFromMetadata,
-} from "../lancedb/materialized_view";
-
-describe("materialized views", () => {
-  let tmpDir: tmp.DirResult;
-  let db: Connection;
-
-  beforeEach(async () => {
-    tmpDir = tmp.dirSync({ unsafeCleanup: true });
-    db = await connect(tmpDir.name);
-    await db.createTable(
-      "people",
-      [
-        { name: "ada", age: 36 },
-        { name: "kid", age: 7 },
-        { name: "grace", age: 85 },
-      ],
-      { storageOptions: { newTableEnableStableRowIds: "true" } },
-    );
-  });
-  afterEach(() => tmpDir.removeCallback());
-
-  it("rejects a stored limit a number cannot carry", () => {
-    const big = new Map([
-      [
-        DEFINITION_META_KEY,
-        '{"kind":"select","source_table":"people","limit":9007199254740993}',
-      ],
-    ]);
-    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("creates, refreshes and queries a view", async () => {
-    const view = await db.createMaterializedView("adults", "people", {
-      select: ["name", ["shout", "upper(name)"]],
-      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);
-
-    const rows = await view.table().query().toArray();
-    expect(rows.map((r) => r.shout).sort()).toEqual(["ADA", "GRACE"]);
-  });
-
-  it("round-trips the definition", async () => {
-    await db.createMaterializedView("adults", "people", {
-      where: "age >= 18",
-    });
-    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"]);
-  });
-
-  it("refreshes incrementally after an append", async () => {
-    const view = await db.createMaterializedView("copy", "people");
-    await view.refresh();
-
-    const people = await db.openTable("people");
-    await people.add([{ name: "alan", age: 41 }]);
-    const result = await view.refresh();
-    expect(result.mode).toBe("incremental");
-    expect(Number(result.rowsWritten)).toBe(1);
-    expect(await view.table().countRows()).toBe(4);
-
-    expect((await view.refresh()).mode).toBe("no_op");
-  });
-
-  it("lists views and rejects non-views", async () => {
-    await db.createMaterializedView("adults", "people", {
-      where: "age >= 18",
-    });
-    expect(await db.listMaterializedViews()).toEqual(["adults"]);
-    await expect(db.openMaterializedView("people")).rejects.toThrow(
-      "not a materialized view",
-    );
-  });
-
-  it("rejects an invalid expression at create time", async () => {
-    await expect(
-      db.createMaterializedView("bad", "people", {
-        select: [["x", "missing + 1"]],
-      }),
-    ).rejects.toThrow("missing");
-  });
-
-  it("rejects invalid numeric options before creating anything", async () => {
-    for (const limit of [-5, 1.5, Infinity, NaN]) {
-      await expect(
-        db.createMaterializedView("bad", "people", { limit }),
-      ).rejects.toThrow("non-negative integer");
-    }
-    expect(await db.listMaterializedViews()).toEqual([]);
-
-    const view = await db.createMaterializedView("copy", "people");
-    for (const sourceVersion of [-1, 1.5, Infinity, NaN]) {
-      await expect(view.refresh({ sourceVersion })).rejects.toThrow(
-        "non-negative integer",
-      );
-    }
-  });
-
-  it("quotes bare select names", async () => {
-    await db.createTable("odd_names", [{ "order item": "widget" }], {
-      storageOptions: { newTableEnableStableRowIds: "true" },
-    });
-    const view = await db.createMaterializedView("quoted", "odd_names", {
-      select: ["order item"],
-    });
-    const result = await view.refresh();
-    expect(Number(result.rowsWritten)).toBe(1);
-  });
-
-  it("requires stable row ids on the source", async () => {
-    await db.createTable("plain", [{ x: 1 }]);
-    await expect(db.createMaterializedView("v", "plain")).rejects.toThrow(
-      "stable row ids",
-    );
-  });
-});
@@ -106,77 +106,6 @@ describe.each([arrow15, arrow16, arrow17, arrow18])("Registry", (arrow) => {
      'Embedding function with alias "mock-embedding" already exists',
    );
  });
-  test("parseFunctions keeps entries sharing a function name", async () => {
-    class MockEmbeddingFunction extends EmbeddingFunction<string> {
-      ndims() {
-        return 3;
-      }
-      embeddingDataType() {
-        return new arrow.Float32() as apiArrow.Float;
-      }
-      async computeSourceEmbeddings(data: string[]) {
-        return data.map(() => [1, 2, 3]);
-      }
-    }
-    register("mock-embedding")(MockEmbeddingFunction);
-    const parsed = await getRegistry().parseFunctions(
-      new Map([
-        [
-          "embedding_functions",
-          JSON.stringify([
-            {
-              name: "mock-embedding",
-              sourceColumn: "text",
-              vectorColumn: "vector_a",
-              model: {},
-            },
-            {
-              name: "mock-embedding",
-              sourceColumn: "text",
-              vectorColumn: "vector_b",
-              model: {},
-            },
-          ]),
-        ],
-      ]),
-    );
-    expect([...parsed.values()].map((f) => f.vectorColumn)).toEqual([
-      "vector_a",
-      "vector_b",
-    ]);
-
-    // The Python bindings write snake_case keys.
-    const snake = await getRegistry().parseFunctions(
-      new Map([
-        [
-          "embedding_functions",
-          JSON.stringify([
-            {
-              name: "mock-embedding",
-              // biome-ignore lint/style/useNamingConvention: the Python wire spelling
-              source_column: "text",
-              // biome-ignore lint/style/useNamingConvention: the Python wire spelling
-              vector_column: "vector_a",
-              model: {},
-            },
-            {
-              name: "mock-embedding",
-              // biome-ignore lint/style/useNamingConvention: the Python wire spelling
-              source_column: "text",
-              // biome-ignore lint/style/useNamingConvention: the Python wire spelling
-              vector_column: "vector_b",
-              model: {},
-            },
-          ]),
-        ],
-      ]),
-    );
-    expect([...snake.keys()]).toEqual(["vector_a", "vector_b"]);
-    expect([...snake.values()].map((f) => f.sourceColumn)).toEqual([
-      "text",
-      "text",
-    ]);
-  });
  test("schema should contain correct metadata", async () => {
    class MockEmbeddingFunction extends EmbeddingFunction<string> {
      constructor(args: FunctionOptions = {}) {
@@ -75,25 +75,6 @@ async function withMockDatabase(
 }

 describe("remote connection", () => {
-  it("refuses materialized views before issuing any request", async () => {
-    const paths: string[] = [];
-    await withMockDatabase(
-      (req, res) => {
-        paths.push(req.url ?? "");
-        res.writeHead(404).end();
-      },
-      async (db) => {
-        await expect(db.openMaterializedView("secret_table")).rejects.toThrow(
-          /only on local databases/,
-        );
-        await expect(db.listMaterializedViews()).rejects.toThrow(
-          /only on local databases/,
-        );
-        expect(paths).toEqual([]);
-      },
-    );
-  });
-
  it("should accept partial connection options", async () => {
    await connect("db://test", {
      apiKey: "fake",
@@ -330,7 +311,7 @@ describe("remote connection", () => {
    expect(createIndexBody?.["custom_stop_words"]).toEqual(["the"]);
  });

-  it("diffs and cherry-picks remote branches", async () => {
+  it("diffs and merges remote branches", async () => {
    const sampleDiff = {
      fromBranch: "exp",
      parentVersion: 1,
@@ -352,9 +333,10 @@ describe("remote connection", () => {
      changedColumns: [],
      addedIndexes: [],
      removedIndexes: [],
-      errors: [],
+      mergeable: true,
+      mergeBlockers: [],
    };
-    const cherryPickBodies: Record<string, unknown>[] = [];
+    const mergeBodies: Record<string, unknown>[] = [];

    await withMockDatabase(
      (req, res) => {
@@ -384,16 +366,17 @@ describe("remote connection", () => {
              .end(JSON.stringify(sampleDiff));
            return;
          }
-          if (path.endsWith("/branches/cherry_pick/")) {
-            cherryPickBodies.push(body);
+          if (path.endsWith("/branches/merge/")) {
+            mergeBodies.push(body);
            const dryRun = body["dry_run"] === true;
            const response = {
-              status: dryRun ? "ready" : "failed",
+              status: dryRun ? "ready" : "rejected",
              diff: dryRun
                ? sampleDiff
                : {
                    ...sampleDiff,
-                    errors: [
+                    mergeable: false,
+                    mergeBlockers: [
                      { code: "baseMoved", message: "main has advanced" },
                    ],
                  },
@@ -415,19 +398,19 @@ describe("remote connection", () => {

        await expect(branches.diff("exp")).resolves.toEqual(sampleDiff);

-        const failed = await branches.cherryPick("exp");
-        expect(failed.status).toBe("failed");
-        expect(failed.diff.errors).toEqual([
+        const rejected = await branches.merge("exp");
+        expect(rejected.status).toBe("rejected");
+        expect(rejected.diff.mergeBlockers).toEqual([
          { code: "baseMoved", message: "main has advanced" },
        ]);

-        const preview = await branches.cherryPick("exp", true);
+        const preview = await branches.merge("exp", true);
        expect(preview.status).toBe("ready");
        expect(preview.preview.promotedColumns).toEqual(["tag"]);
      },
    );

-    expect(cherryPickBodies).toEqual([
+    expect(mergeBodies).toEqual([
      // biome-ignore lint/style/useNamingConvention: snake_case mandated by the server wire format
      { from_branch: "exp", dry_run: false },
      // biome-ignore lint/style/useNamingConvention: snake_case mandated by the server wire format
@@ -2953,7 +2953,7 @@ describe("column name options", () => {
      .limit(10)
      .toArray();
    expect(results2.length).toBe(10);
-  }, 30_000);
+  });
 });

 describe("when creating an empty table", () => {
@@ -48,11 +48,7 @@ import {
 } from "apache-arrow";
 import { Buffers } from "apache-arrow/data";
 import { type EmbeddingFunction } from "./embedding/embedding_function";
-import {
-  EmbeddingFunctionConfig,
-  getRegistry,
-  parseEmbeddingMetadata,
-} from "./embedding/registry";
+import { EmbeddingFunctionConfig, getRegistry } from "./embedding/registry";
 import {
  sanitizeField,
  sanitizeSchema,
@@ -937,7 +933,7 @@ async function applyEmbeddingsFromMetadata(

  for (const functionEntry of functions.values()) {
    const sourceColumn = columns[functionEntry.sourceColumn];
-    const destColumn = functionEntry.vectorColumn;
+    const destColumn = functionEntry.vectorColumn ?? "vector";
    if (sourceColumn === undefined) {
      throw new Error(
        `Cannot apply embedding function because the source column '${functionEntry.sourceColumn}' was not present in the data`,
@@ -1389,10 +1385,11 @@ function validateSchemaEmbeddings(

        // Check schema metadata for embedding functions
        if (schema.metadata.has("embedding_functions")) {
-          const entries = parseEmbeddingMetadata(
+          const embeddings = JSON.parse(
            schema.metadata.get("embedding_functions")!,
          );
-          if (entries.some((f) => f.vectorColumn === field.name)) {
+          // biome-ignore lint/suspicious/noExplicitAny: we don't know the type of `f`
+          if (embeddings.find((f: any) => f["vectorColumn"] === field.name)) {
            hasEmbeddingFunction = true;
          }
        }
@@ -16,12 +16,6 @@ import {
  makeEmptyTable,
 } from "./arrow";
 import { EmbeddingFunctionConfig, getRegistry } from "./embedding/registry";
-import {
-  MaterializedView,
-  MaterializedViewSelect,
-  normalizeSelect,
-  validateNonNegativeInteger,
-} from "./materialized_view";
 import { Connection as LanceDbConnection } from "./native";
 import type {
  CreateNamespaceResponse,
@@ -31,12 +25,14 @@ import type {
  JobDescription,
  JobInfo,
  ListNamespacesResponse,
+  ListTablesResponse,
 } from "./native";
 export type {
  CreateNamespaceResponse,
  DescribeNamespaceResponse,
  DropNamespaceResponse,
  ListNamespacesResponse,
+  ListTablesResponse,
 };
 import { sanitizeTable } from "./sanitize";
 import { LocalTable, Table } from "./table";
@@ -134,6 +130,10 @@ export interface OpenTableOptions {
  indexCacheSize?: number;
 }

+/**
+ * @deprecated Use {@link ListTablesOptions} with {@link Connection.listTables}
+ * instead.
+ */
 export interface TableNamesOptions {
  /**
   * If present, only return names that come lexicographically after the
@@ -147,6 +147,23 @@ export interface TableNamesOptions {
  limit?: number;
 }

+export interface ListTablesOptions {
+  /**
+   * Token from a previous response for pagination.
+   *
+   * The token is opaque: it carries whatever the database needs to resume, and
+   * callers should not construct or interpret one.
+   */
+  pageToken?: string;
+  /**
+   * An upper bound on how many tables to return.
+   *
+   * A page may hold fewer than this and still not be the last one, so continue
+   * while the response carries a page token rather than while pages are full.
+   */
+  limit?: number;
+}
+
 export interface ListNamespacesOptions {
  /** Token from a previous response for pagination. */
  pageToken?: string;
@@ -231,6 +248,7 @@ export abstract class Connection {
   * @param {Partial<TableNamesOptions>} options - options to control the
   * paging / start point (backwards compatibility)
   *
+   * @deprecated Use {@link Connection.listTables} instead.
   */
  abstract tableNames(options?: Partial<TableNamesOptions>): Promise<string[]>;
  /**
@@ -241,53 +259,60 @@ export abstract class Connection {
   * @param {Partial<TableNamesOptions>} options - options to control the
   * paging / start point
   *
+   * @deprecated Use {@link Connection.listTables} instead.
   */
  abstract tableNames(
    namespacePath?: string[],
    options?: Partial<TableNamesOptions>,
  ): Promise<string[]>;

+  /**
+   * List a page of tables in this database.
+   *
+   * Results may be paginated. To retrieve subsequent pages, pass the
+   * `pageToken` returned by a previous call. A page may be shorter than
+   * `limit` without being the last one, so walk until the response carries no
+   * page token:
+   *
+   * ```ts
+   * const names = [];
+   * let pageToken = undefined;
+   * do {
+   *   const page = await conn.listTables({ pageToken, limit: 100 });
+   *   names.push(...page.tables);
+   *   pageToken = page.pageToken;
+   * } while (pageToken);
+   * ```
+   *
+   * @param {Partial<ListTablesOptions>} options - Pagination options
+   *   (`pageToken`, `limit`).
+   * @returns {Promise<ListTablesResponse>} Table names and an optional token
+   *   for fetching the next page.
+   */
+  abstract listTables(
+    options?: Partial<ListTablesOptions>,
+  ): Promise<ListTablesResponse>;
+  /**
+   * List a page of tables in this database.
+   *
+   * @param {string[]} namespacePath - The namespace path to list tables from
+   *   (defaults to root namespace)
+   * @param {Partial<ListTablesOptions>} options - Pagination options
+   *   (`pageToken`, `limit`).
+   * @returns {Promise<ListTablesResponse>} Table names and an optional token
+   *   for fetching the next page.
+   */
+  abstract listTables(
+    namespacePath?: string[],
+    options?: Partial<ListTablesOptions>,
+  ): Promise<ListTablesResponse>;
+
  /**
   * Open a table in the database.
   * @param {string} name - The name of the table
   * @param {string[]} namespacePath - The namespace path of the table (defaults to root namespace)
   * @param {Partial<OpenTableOptions>} options - Additional options
   */
-  /**
-   * 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 `newTableEnableStableRowIds` storage option); they keep the view's
-   * provenance valid across source compactions and cannot be enabled after
-   * a table exists. Local databases only.
-   */
-  abstract createMaterializedView(
-    name: string,
-    source: string,
-    options?: {
-      select?: MaterializedViewSelect;
-      where?: string;
-      limit?: number;
-    },
-  ): Promise<MaterializedView>;
-
-  /**
-   * Open the materialized view named `name`.
-   *
-   * Rejects a table that exists but is not a materialized view.
-   */
-  abstract openMaterializedView(name: string): Promise<MaterializedView>;
-
-  /**
-   * The names of the materialized views in this database.
-   *
-   * Found by reading every table's schema, so this costs an open per table.
-   */
-  abstract listMaterializedViews(): Promise<string[]>;
-
  abstract openTable(
    name: string,
    namespacePath?: string[],
@@ -572,33 +597,27 @@ export class LocalConnection extends Connection {
    );
  }

-  async createMaterializedView(
-    name: string,
-    source: string,
-    options?: {
-      select?: MaterializedViewSelect;
-      where?: string;
-      limit?: number;
-    },
-  ): Promise<MaterializedView> {
-    validateNonNegativeInteger(options?.limit, "limit");
-    const innerTable = await this.inner.createMaterializedView(
-      name,
-      source,
-      normalizeSelect(options?.select),
-      options?.where,
-      options?.limit,
+  async listTables(
+    namespacePathOrOptions?: string[] | Partial<ListTablesOptions>,
+    options?: Partial<ListTablesOptions>,
+  ): Promise<ListTablesResponse> {
+    // Detect if first argument is namespacePath array or options object
+    let namespacePath: string[] | undefined;
+    let listTablesOptions: Partial<ListTablesOptions> | undefined;
+
+    if (Array.isArray(namespacePathOrOptions)) {
+      namespacePath = namespacePathOrOptions;
+      listTablesOptions = options;
+    } else {
+      namespacePath = undefined;
+      listTablesOptions = namespacePathOrOptions;
+    }
+
+    return this.inner.listTables(
+      namespacePath ?? [],
+      listTablesOptions?.pageToken,
+      listTablesOptions?.limit,
    );
-    return new MaterializedView(new LocalTable(innerTable));
-  }
-
-  async openMaterializedView(name: string): Promise<MaterializedView> {
-    const innerTable = await this.inner.openMaterializedView(name);
-    return new MaterializedView(new LocalTable(innerTable));
-  }
-
-  async listMaterializedViews(): Promise<string[]> {
-    return await this.inner.listMaterializedViews();
  }

  async openTable(
@@ -104,29 +104,41 @@ export class EmbeddingFunctionRegistry {
  async parseFunctions(
    this: EmbeddingFunctionRegistry,
    metadata: Map<string, string>,
-  ): Promise<Map<string, ResolvedEmbeddingFunctionConfig>> {
+  ): Promise<Map<string, EmbeddingFunctionConfig>> {
    if (!metadata.has("embedding_functions")) {
      return new Map();
+    } else {
+      type FunctionConfig = {
+        name: string;
+        sourceColumn: string;
+        vectorColumn: string;
+        model: EmbeddingFunction["TOptions"];
+      };
+
+      const functions = <FunctionConfig[]>(
+        JSON.parse(metadata.get("embedding_functions")!)
+      );
+
+      const items: [string, EmbeddingFunctionConfig][] = await Promise.all(
+        functions.map(async (f) => {
+          const fn = this.get(f.name);
+          if (!fn) {
+            throw new Error(`Function "${f.name}" not found in registry`);
+          }
+          const func = await this.get(f.name)!.create(f.model);
+          return [
+            f.name,
+            {
+              sourceColumn: f.sourceColumn,
+              vectorColumn: f.vectorColumn,
+              function: func,
+            },
+          ];
+        }),
+      );
+
+      return new Map(items);
    }
-    const entries = parseEmbeddingMetadata(
-      metadata.get("embedding_functions")!,
-    );
-    const items = await Promise.all(
-      entries.map(async (f): Promise<ResolvedEmbeddingFunctionConfig> => {
-        const fn = this.get(f.name);
-        if (!fn) {
-          throw new Error(`Function "${f.name}" not found in registry`);
-        }
-        const func = await fn.create(f.model);
-        return {
-          sourceColumn: f.sourceColumn,
-          vectorColumn: f.vectorColumn,
-          function: func,
-        };
-      }),
-    );
-    // Keyed by output column: one function may serve several columns.
-    return new Map(items.map((config) => [config.vectorColumn, config]));
  }
  // biome-ignore lint/suspicious/noExplicitAny: <explanation>
  functionToMetadata(conf: EmbeddingFunctionConfig): Record<string, any> {
@@ -206,52 +218,3 @@ export interface EmbeddingFunctionConfig {
  vectorColumn?: string;
  function: EmbeddingFunction;
 }
-
-/** An [EmbeddingFunctionConfig] read back from table metadata, where the
- * vector column is always recorded. */
-export type ResolvedEmbeddingFunctionConfig = EmbeddingFunctionConfig & {
-  vectorColumn: string;
-};
-
-/** One entry of the `embedding_functions` schema metadata, with the column
- * keys normalized across the bindings' spellings. */
-export type EmbeddingMetadataEntry = {
-  name: string;
-  sourceColumn: string;
-  vectorColumn: string;
-  model: EmbeddingFunction["TOptions"];
-};
-
-/** The single parser for `embedding_functions` schema metadata: every reader
- * goes through here, so the wire contract cannot fork between them. */
-export function parseEmbeddingMetadata(json: string): EmbeddingMetadataEntry[] {
-  // The wire format, honestly: the Python bindings write snake_case keys.
-  type Raw = {
-    name: string;
-    sourceColumn?: string;
-    // biome-ignore lint/style/useNamingConvention: the Python wire spelling
-    source_column?: string;
-    vectorColumn?: string;
-    // biome-ignore lint/style/useNamingConvention: the Python wire spelling
-    vector_column?: string;
-    model: EmbeddingFunction["TOptions"];
-  };
-  const entries = <Raw[]>JSON.parse(json);
-  const seen = new Set<string>();
-  return entries.map((f) => {
-    const sourceColumn = f.sourceColumn ?? f.source_column;
-    const vectorColumn = f.vectorColumn ?? f.vector_column;
-    if (sourceColumn === undefined || vectorColumn === undefined) {
-      throw new Error(
-        `Embedding function "${f.name}" metadata names no source or vector column`,
-      );
-    }
-    if (seen.has(vectorColumn)) {
-      throw new Error(
-        `Multiple embedding configs claim vector column "${vectorColumn}"`,
-      );
-    }
-    seen.add(vectorColumn);
-    return { name: f.name, sourceColumn, vectorColumn, model: f.model };
-  });
-}
@@ -21,11 +21,6 @@ import type { BaseTokenizer } from "./indices";
 import type { FtsToken } from "./table";

 // Re-export native header provider for use with connectWithHeaderProvider
-export {
-  MaterializedView,
-  MaterializedViewDefinition,
-  MaterializedViewSelect,
-} from "./materialized_view";
 export { JsHeaderProvider as NativeJsHeaderProvider } from "./native.js";

 // OpenTelemetry metrics bridge. Only the high-level entry point is public; the
@@ -56,7 +51,6 @@ export {
  AddResult,
  AddColumnsResult,
  RefreshColumnResult,
-  RefreshMaterializedViewResult,
  AlterColumnsResult,
  UpdateFieldMetadataResult,
  DeleteResult,
@@ -81,11 +75,13 @@ export {
  Connection,
  CreateTableOptions,
  TableNamesOptions,
+  ListTablesOptions,
  OpenTableOptions,
  ListNamespacesOptions,
  CreateNamespaceOptions,
  DropNamespaceOptions,
  ListNamespacesResponse,
+  ListTablesResponse,
  CreateNamespaceResponse,
  DropNamespaceResponse,
  DescribeNamespaceResponse,
@@ -141,10 +137,10 @@ export {
  BranchColumnChange,
  BranchIndexSummary,
  BranchRowCountSummary,
-  CherryPickError,
+  MergeBlocker,
  BranchDiff,
-  CherryPickPreview,
-  CherryPickResult,
+  MergePreview,
+  MergeBranchResult,
  AddDataOptions,
  UpdateOptions,
  OptimizeOptions,
@@ -1,161 +0,0 @@
-// SPDX-License-Identifier: Apache-2.0
-// SPDX-FileCopyrightText: Copyright The LanceDB Authors
-
-import { RefreshMaterializedViewResult } from "./native";
-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. */
-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[];
-}
-
-/**
- * The view's columns: column names, `[alias, SQL expression]` pairs, or a
- * record of the same. A bare name projects itself.
- */
-export type MaterializedViewSelect =
-  | (string | [string, string])[]
-  | Record<string, string>;
-
-/**
- * @internal Reject a numeric option N-API would otherwise silently coerce:
- * `Infinity` reaches Rust as 0, `1.5` as 1.
- */
-export function validateNonNegativeInteger(
-  value: number | undefined,
-  name: string,
-): void {
-  if (value !== undefined && !(Number.isSafeInteger(value) && value >= 0)) {
-    throw new Error(`${name} must be a non-negative integer`);
-  }
-}
-
-/** @internal Quote a column name as a Lance SQL identifier (backticks). */
-function quoteIdentifier(name: string): string {
-  return "`" + name.replace(/`/g, "``") + "`";
-}
-
-/**
- * @internal Normalize a select argument into `[alias, expression]` pairs.
- * A bare name projects itself and is quoted, so any valid column name works;
- * pair and record entries are kept verbatim because their right side is an
- * expression.
- */
-export function normalizeSelect(
-  select?: MaterializedViewSelect,
-): [string, string][] | undefined {
-  if (select === undefined) {
-    return undefined;
-  }
-  if (Array.isArray(select)) {
-    return select.map((item) =>
-      typeof item === "string" ? [item, quoteIdentifier(item)] : item,
-    );
-  }
-  return Object.entries(select);
-}
-
-/** @internal Parse a definition off a table's stored schema metadata. */
-export function definitionFromMetadata(
-  metadata: Map<string, string>,
-  name: string,
-): MaterializedViewDefinition {
-  const raw = metadata.get(DEFINITION_META_KEY);
-  if (raw === undefined) {
-    throw new Error(`Table '${name}' is not a materialized view`);
-  }
-  // biome-ignore lint/suspicious/noExplicitAny: raw JSON
-  const value: any = JSON.parse(raw);
-  if (value.kind !== "select") {
-    throw new Error(
-      `materialized view '${name}' is defined by '${value.kind}', which this ` +
-        "version of lancedb cannot refresh",
-    );
-  }
-  const limit = value.limit ?? undefined;
-  // JSON.parse rounds integers past 2^53; every exact u64 parses to a safe
-  // integer and every rounded one does not, so this rejects precisely the
-  // values a number cannot carry.
-  if (limit !== undefined && !Number.isSafeInteger(limit)) {
-    throw new Error(
-      `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 ?? [],
-  };
-}
-
-/**
- * A handle on a materialized view: its table plus its definition.
- *
- * Obtained from {@link Connection#createMaterializedView} or
- * {@link Connection#openMaterializedView}. The view is a normal table --
- * queries, indexes and search all apply through {@link MaterializedView#table}
- * -- whose contents are maintained by {@link MaterializedView#refresh}.
- */
-export class MaterializedView {
-  private readonly inner: Table;
-
-  constructor(table: Table) {
-    this.inner = table;
-  }
-
-  get name(): string {
-    return this.inner.name;
-  }
-
-  /** The view, as the table it is. */
-  table(): Table {
-    return this.inner;
-  }
-
-  /** The query that defines the view, read from its stored schema. */
-  async definition(): Promise<MaterializedViewDefinition> {
-    const schema = await this.inner.schema();
-    return definitionFromMetadata(schema.metadata, this.name);
-  }
-
-  /**
-   * Recompute the view from its source.
-   *
-   * The refresh is incremental when the source's changes can be reconciled
-   * into the view -- rows added, changed or removed since the last one --
-   * and otherwise rebuilds. `full` forces a rebuild; `sourceVersion`
-   * refreshes to that source version instead of the latest.
-   *
-   * Concurrent refreshes of one view do not duplicate its rows. Two that
-   * plan the same source rows conflict on commit, and the loser throws
-   * rather than writing them a second time.
-   */
-  async refresh(options?: {
-    full?: boolean;
-    sourceVersion?: number;
-  }): Promise<RefreshMaterializedViewResult> {
-    validateNonNegativeInteger(options?.sourceVersion, "sourceVersion");
-    return await this.inner.refreshMaterializedView(
-      options?.full,
-      options?.sourceVersion,
-    );
-  }
-}
@@ -35,7 +35,6 @@ import {
  Branches as NativeBranches,
  OptimizeStats,
  RefreshColumnResult,
-  RefreshMaterializedViewResult,
  TableStatistics,
  Tags,
  UpdateFieldMetadataResult,
@@ -603,18 +602,6 @@ export abstract class Table {
   */
  abstract refreshColumnAsync(column: string): Promise<Job>;

-  /**
-   * 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.
-   * @ignore
-   */
-  abstract refreshMaterializedView(
-    full?: boolean,
-    sourceVersion?: number,
-  ): Promise<RefreshMaterializedViewResult>;
-
  /**
   * Alter the name or nullability of columns.
   * @param {ColumnAlteration[]} columnAlterations One or more alterations to
@@ -1277,13 +1264,6 @@ export class LocalTable extends Table {
    return await this.inner.refreshColumnAsync(column);
  }

-  async refreshMaterializedView(
-    full?: boolean,
-    sourceVersion?: number,
-  ): Promise<RefreshMaterializedViewResult> {
-    return await this.inner.refreshMaterializedView(full, sourceVersion);
-  }
-
  async alterColumns(
    columnAlterations: ColumnAlteration[],
  ): Promise<AlterColumnsResult> {
@@ -1577,8 +1557,8 @@ export interface BranchRowCountSummary {
  deltaAvailable: boolean;
 }

-/** A reason why a cherry-pick cannot currently land. */
-export interface CherryPickError {
+/** A reason why a branch cannot currently be merged. */
+export interface MergeBlocker {
  code: string;
  message: string;
 }
@@ -1598,19 +1578,20 @@ export interface BranchDiff {
  changedColumns: BranchColumnChange[];
  addedIndexes: BranchIndexSummary[];
  removedIndexes: BranchIndexSummary[];
-  errors: CherryPickError[];
+  mergeable: boolean;
+  mergeBlockers: MergeBlocker[];
 }

-/** Changes that would be, or were, promoted by a cherry-pick. */
-export interface CherryPickPreview {
+/** Changes that would be, or were, promoted by a branch merge. */
+export interface MergePreview {
  promotedColumns: string[];
 }

-/** Result of previewing or attempting a cherry-pick. */
-export interface CherryPickResult {
-  status: "ready" | "failed" | "notImplemented" | "cherryPicked" | "unknown";
+/** Result of previewing or attempting a branch merge. */
+export interface MergeBranchResult {
+  status: "ready" | "rejected" | "notImplemented" | "merged" | "unknown";
  diff: BranchDiff;
-  preview: CherryPickPreview;
+  preview: MergePreview;
  mainVersionAfter?: number;
 }

@@ -1673,21 +1654,21 @@ export class Branches {
  }

  /**
-   * Cherry-pick a branch onto main.
+   * Merge a branch into main.
   *
-   * Set `dryRun` to `true` to preview. A failed cherry-pick resolves
-   * with `status: "failed"` instead of throwing.
+   * Set `dryRun` to `true` to preview the merge. A rejected merge resolves
+   * with `status: "rejected"` instead of throwing.
   *
-   * @param fromBranch Branch to cherry-pick from.
-   * @param dryRun When true, only preview. Defaults to false.
+   * @param fromBranch Branch to merge from.
+   * @param dryRun When true, only preview the merge. Defaults to false.
   */
-  async cherryPick(
+  async merge(
    fromBranch: string,
    dryRun: boolean = false,
-  ): Promise<CherryPickResult> {
-    return (await this.#inner.cherryPick(
+  ): Promise<MergeBranchResult> {
+    return (await this.#inner.merge(
      fromBranch,
      dryRun,
-    )) as unknown as CherryPickResult;
+    )) as unknown as MergeBranchResult;
  }
 }
@@ -1,6 +1,6 @@
 {
 	"name": "@lancedb/lancedb-darwin-arm64",
-	"version": "0.38.0-beta.7",
+	"version": "0.38.0-beta.2",
 	"os": ["darwin"],
 	"cpu": ["arm64"],
 	"main": "lancedb.darwin-arm64.node",
@@ -1,6 +1,6 @@
 {
 	"name": "@lancedb/lancedb-linux-arm64-gnu",
-	"version": "0.38.0-beta.7",
+	"version": "0.38.0-beta.2",
 	"os": ["linux"],
 	"cpu": ["arm64"],
 	"main": "lancedb.linux-arm64-gnu.node",
@@ -1,6 +1,6 @@
 {
 	"name": "@lancedb/lancedb-linux-arm64-musl",
-	"version": "0.38.0-beta.7",
+	"version": "0.38.0-beta.2",
 	"os": ["linux"],
 	"cpu": ["arm64"],
 	"main": "lancedb.linux-arm64-musl.node",
@@ -1,6 +1,6 @@
 {
 	"name": "@lancedb/lancedb-linux-x64-gnu",
-	"version": "0.38.0-beta.7",
+	"version": "0.38.0-beta.2",
 	"os": ["linux"],
 	"cpu": ["x64"],
 	"main": "lancedb.linux-x64-gnu.node",
@@ -1,6 +1,6 @@
 {
 	"name": "@lancedb/lancedb-linux-x64-musl",
-	"version": "0.38.0-beta.7",
+	"version": "0.38.0-beta.2",
 	"os": ["linux"],
 	"cpu": ["x64"],
 	"main": "lancedb.linux-x64-musl.node",
@@ -1,6 +1,6 @@
 {
  "name": "@lancedb/lancedb-win32-arm64-msvc",
-  "version": "0.38.0-beta.7",
+  "version": "0.38.0-beta.2",
  "os": [
    "win32"
  ],
@@ -1,6 +1,6 @@
 {
 	"name": "@lancedb/lancedb-win32-x64-msvc",
-	"version": "0.38.0-beta.7",
+	"version": "0.38.0-beta.2",
 	"os": ["win32"],
 	"cpu": ["x64"],
 	"main": "lancedb.win32-x64-msvc.node",
@@ -1,12 +1,12 @@
 {
  "name": "@lancedb/lancedb",
-  "version": "0.38.0-beta.6",
+  "version": "0.38.0-beta.2",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "@lancedb/lancedb",
-      "version": "0.38.0-beta.6",
+      "version": "0.38.0-beta.2",
      "cpu": [
        "x64",
        "arm64"
@@ -11,7 +11,7 @@
    "ann"
  ],
  "private": false,
-  "version": "0.38.0-beta.7",
+  "version": "0.38.0-beta.2",
  "main": "dist/index.js",
  "exports": {
    ".": "./dist/index.js",
@@ -36,6 +36,12 @@ pub struct ListNamespacesResponse {
    pub page_token: Option<String>,
 }

+#[napi(object)]
+pub struct ListTablesResponse {
+    pub tables: Vec<String>,
+    pub page_token: Option<String>,
+}
+
 #[napi(object)]
 pub struct CreateNamespaceResponse {
    pub properties: Option<HashMap<String, String>>,
@@ -189,6 +195,8 @@ impl Connection {

    /// List all tables in the dataset.
    #[napi(catch_unwind)]
+    // Deprecated in favour of `list_tables`, but still exposed to JavaScript.
+    #[allow(deprecated)]
    pub async fn table_names(
        &self,
        namespace_path: Option<Vec<String>>,
@@ -206,6 +214,29 @@ impl Connection {
        op.execute().await.default_error()
    }

+    /// List a page of tables in the database.
+    #[napi(catch_unwind)]
+    pub async fn list_tables(
+        &self,
+        namespace_path: Option<Vec<String>>,
+        page_token: Option<String>,
+        limit: Option<u32>,
+    ) -> napi::Result<ListTablesResponse> {
+        let mut op = self.get_inner()?.list_tables();
+        op = op.namespace(namespace_path.unwrap_or_default());
+        if let Some(page_token) = page_token {
+            op = op.page_token(page_token);
+        }
+        if let Some(limit) = limit {
+            op = op.limit(limit);
+        }
+        let resp = op.execute().await.default_error()?;
+        Ok(ListTablesResponse {
+            tables: resp.tables,
+            page_token: resp.page_token,
+        })
+    }
+
    /// Create table from a Apache Arrow IPC (file) buffer.
    ///
    /// Parameters:
@@ -266,58 +297,6 @@ impl Connection {
        Ok(Table::new(tbl))
    }

-    #[napi(catch_unwind)]
-    pub async fn create_materialized_view(
-        &self,
-        name: String,
-        source: String,
-        projections: Option<Vec<Vec<String>>>,
-        filter: Option<String>,
-        limit: Option<i64>,
-    ) -> napi::Result<Table> {
-        let mut builder = self.get_inner()?.create_materialized_view(name, source);
-        if let Some(projections) = projections {
-            let mut pairs = Vec::with_capacity(projections.len());
-            for pair in projections {
-                let [output, expression]: [String; 2] = pair.try_into().map_err(|_| {
-                    napi::Error::from_reason("each projection must be an [output, expression] pair")
-                })?;
-                pairs.push((output, expression));
-            }
-            builder = builder.select(pairs);
-        }
-        if let Some(filter) = filter {
-            builder = builder.only_if(filter);
-        }
-        if let Some(limit) = limit {
-            let limit = u64::try_from(limit)
-                .map_err(|_| napi::Error::from_reason("limit must be a non-negative integer"))?;
-            builder = builder.limit(limit);
-        }
-        let view = builder.execute().await.default_error()?;
-        Ok(Table::new(view.table().clone()))
-    }
-
-    #[napi(catch_unwind)]
-    pub async fn open_materialized_view(&self, name: String) -> napi::Result<Table> {
-        let view = self
-            .get_inner()?
-            .open_materialized_view(&name)
-            .await
-            .default_error()?;
-        Ok(Table::new(view.table().clone()))
-    }
-
-    #[napi(catch_unwind)]
-    pub async fn list_materialized_views(&self) -> napi::Result<Vec<String>> {
-        let views = self
-            .get_inner()?
-            .list_materialized_views()
-            .await
-            .default_error()?;
-        Ok(views.into_iter().map(|v| v.name).collect())
-    }
-
    #[napi(catch_unwind)]
    pub async fn open_table(
        &self,
@@ -14,12 +14,9 @@ pub struct Job {
 }

 impl Job {
-    pub(crate) fn new<T>(inner: lancedb::Job<T>) -> Self
-    where
-        T: Clone + Send + Sync + 'static,
-    {
+    pub(crate) fn new(inner: lancedb::Job) -> Self {
        Self {
-            inner: Arc::new(inner.map(|_| ())),
+            inner: Arc::new(inner),
        }
    }
 }
@@ -1,10 +1,6 @@
 // SPDX-License-Identifier: Apache-2.0
 // SPDX-FileCopyrightText: Copyright The LanceDB Authors

-// The materialized-view refresh future deepens the type graph past the
-// default trait-recursion depth; same raise as the core crate applies.
-#![recursion_limit = "256"]
-
 use std::collections::HashMap;

 use env_logger::Env;
@@ -381,26 +381,6 @@ impl Table {
        Ok(crate::job::Job::new(job))
    }

-    #[napi(catch_unwind)]
-    pub async fn refresh_materialized_view(
-        &self,
-        full: Option<bool>,
-        source_version: Option<i64>,
-    ) -> napi::Result<RefreshMaterializedViewResult> {
-        let view = lancedb::MaterializedView::from_table(self.inner_ref()?.clone())
-            .await
-            .default_error()?;
-        let mut builder = view.refresh().full(full.unwrap_or(false));
-        if let Some(version) = source_version {
-            let version = u64::try_from(version).map_err(|_| {
-                napi::Error::from_reason("sourceVersion must be a non-negative integer")
-            })?;
-            builder = builder.source_version(version);
-        }
-        let result = builder.execute().await.default_error()?;
-        Ok(result.into())
-    }
-
    #[napi(catch_unwind)]
    pub async fn add_columns_with_schema(
        &self,
@@ -1407,31 +1387,6 @@ pub struct RefreshColumnResult {
    pub version: i64,
 }

-#[napi(object)]
-pub struct RefreshMaterializedViewResult {
-    /// How the view was brought up to date: "rebuild", "incremental" or "no_op".
-    pub mode: String,
-    pub rows_written: i64,
-    pub source_version: i64,
-    pub version: i64,
-}
-
-impl From<lancedb::RefreshMaterializedViewResult> for RefreshMaterializedViewResult {
-    fn from(value: lancedb::RefreshMaterializedViewResult) -> Self {
-        let mode = match value.mode {
-            lancedb::RefreshMode::Rebuild => "rebuild",
-            lancedb::RefreshMode::Incremental => "incremental",
-            lancedb::RefreshMode::NoOp => "no_op",
-        };
-        Self {
-            mode: mode.to_string(),
-            rows_written: value.rows_written as i64,
-            source_version: value.source_version as i64,
-            version: value.version as i64,
-        }
-    }
-}
-
 impl From<lancedb::table::RefreshColumnResult> for RefreshColumnResult {
    fn from(value: lancedb::table::RefreshColumnResult) -> Self {
        Self {
@@ -1650,18 +1605,18 @@ impl Branches {
    }

    #[napi(ts_return_type = "Promise<Record<string, unknown>>")]
-    pub async fn cherry_pick(
+    pub async fn merge(
        &self,
        from_branch: String,
        dry_run: Option<bool>,
    ) -> napi::Result<serde_json::Value> {
        let result = self
            .inner
-            .cherry_pick(&from_branch, dry_run.unwrap_or(false))
+            .merge_branch(&from_branch, dry_run.unwrap_or(false))
            .await
            .default_error()?;
        serde_json::to_value(result).map_err(|err| {
-            napi::Error::from_reason(format!("failed to serialize cherry-pick result: {err}"))
+            napi::Error::from_reason(format!("failed to serialize branch merge result: {err}"))
        })
    }
 }
@@ -0,0 +1,21 @@
+{
+  "name": "lancedb",
+  "description": "Write, review, debug, and document LanceDB pipelines in Python and TypeScript that work across local LanceDB OSS tables and remote LanceDB Enterprise/Cloud tables, with idiomatic query/search patterns and performance defaults for ingestion, indexing, filtering, and diagnostics.",
+  "version": "0.1.0",
+  "author": {
+    "name": "LanceDB"
+  },
+  "homepage": "https://www.lancedb.com",
+  "keywords": [
+    "lancedb",
+    "vector-search",
+    "full-text-search",
+    "hybrid-search",
+    "python",
+    "typescript",
+    "pipelines",
+    "ingestion",
+    "indexing",
+    "performance"
+  ]
+}
@@ -0,0 +1,33 @@
+{
+  "name": "lancedb",
+  "version": "0.1.0",
+  "description": "Codex plugin for building LanceDB pipelines in Python and TypeScript.",
+  "author": {
+    "name": "LanceDB"
+  },
+  "keywords": [
+    "lancedb",
+    "vector-search",
+    "full-text-search",
+    "hybrid-search",
+    "python",
+    "typescript",
+    "pipelines"
+  ],
+  "skills": "./skills/",
+  "interface": {
+    "displayName": "LanceDB",
+    "shortDescription": "Build LanceDB pipelines in Python and TypeScript.",
+    "longDescription": "Write, review, debug, and document LanceDB pipelines in Python and TypeScript that work across local LanceDB OSS tables and remote LanceDB Enterprise/Cloud tables, with idiomatic query/search patterns and performance defaults for ingestion, indexing, filtering, and diagnostics.",
+    "developerName": "LanceDB",
+    "websiteURL": "https://www.lancedb.com",
+    "category": "Developer Tools",
+    "capabilities": [
+      "Developer Tools"
+    ],
+    "defaultPrompt": "Create a LanceDB table, embed sample text, and run a vector search.",
+    "composerIcon": "./assets/logo.png",
+    "logo": "./assets/logo.png",
+    "logoDark": "./assets/logo-dark.png"
+  }
+}
@@ -0,0 +1,87 @@
+---
+name: lancedb
+description: Use when writing, reviewing, debugging, or documenting LanceDB pipelines in Python or TypeScript, especially code that should work across local LanceDB OSS tables and remote LanceDB Enterprise/Cloud tables. Helps avoid non-portable full-table materialization, choose idiomatic query/search patterns, apply LanceDB performance defaults for ingestion, indexing, filtering, and diagnostics, and resolve connections to the remote server for Enterprise-only operations such as jobs.
+---
+
+# Building LanceDB Pipelines
+
+Use this skill to produce LanceDB pipelines that are portable between local and remote tables (for LanceDB Enterprise/Cloud) and idiomatic for the selected SDK.
+
+## LanceDB Table Modes
+
+LanceDB has two common execution modes:
+
+- **Local table**: embedded, open source, in-process LanceDB. The client opens data from a local path or object storage URI and executes queries in the application process.
+- **Remote table**: LanceDB Enterprise/Cloud table opened through a `db://...` URI. The data may be very large, commonly backed by object storage, and queried through a remote service.
+
+Do NOT assume local-only table helpers exist on remote tables. If the user asks for LanceDB Enterprise, Cloud, `db://...`, production remote access, or a remote table, focus on the remote table path: use `search()` / `query()`, keep reads bounded with `select()` and `limit()`, and avoid table-level full materialization APIs.
+
+## Workflow
+
+1. Identify the SDK: Python, TypeScript, or both.
+2. Identify the table mode: local/embedded OSS, remote Enterprise/Cloud, or portable across both. If the user says "LanceDB Enterprise", choose the remote table path. If the task involves jobs in any way (listing, inspecting, creating, or canceling jobs), it is always the remote path and requires a remote server connection — see "Connecting to the LanceDB remote server" below before doing anything else.
+3. Read the matching language branch before writing or changing code:
+   - Python patterns: `references/python/patterns.md`
+   - Python API quick reference: `references/python/api_reference.md`
+   - Python performance guidance: `references/python/performance.md`
+   - TypeScript patterns: `references/typescript/patterns.md`
+   - TypeScript API quick reference: `references/typescript/api_reference.md`
+   - TypeScript performance guidance: `references/typescript/performance.md`
+   - Column metadata authoring (both SDKs): `references/column_metadata.md`
+   - Branch operations (both SDKs): `references/branch_ops.md`
+   - Remote server connection resolution (jobs, raw REST): `references/remote_connect.md`
+   - Job operations REST API (list/describe/cancel/query_events): `references/remote_jobs.md`
+4. Start with `patterns.md` for the selected SDK. Read `api_reference.md` when choosing method names or return collectors. Read `performance.md` when the task involves ingestion, indexing, filtering, query tuning, diagnostics, or large datasets. Read `column_metadata.md` when the task is documenting, tagging, classifying, or grouping table columns (field descriptions, `lancedb:tag:*` tags, logical column families). Read `branch_ops.md` when the task involves branch lifecycle (list/create/delete), writing to a non-main branch, or verifying a change stayed off main. Read `remote_connect.md` when the task involves jobs or direct REST access to an Enterprise deployment, and `remote_jobs.md` for the job REST methods themselves (list, describe, cancel, query_events).
+5. For Python schemas, favor Pydantic models and validate records before writing. Use PyArrow schemas when Arrow-native, streaming, or highly dynamic data makes them materially better suited.
+6. Prefer `search()` or `query()` builders with explicit `select()` and `limit()` for reads.
+7. Avoid table-level full materialization in remote or portable code. This is the main local-vs-remote read pitfall.
+8. After a successful embedded OSS ingestion, call `table.optimize()`. Do not call it for Enterprise/Cloud; remote maintenance is automatic.
+9. For remote Enterprise/Cloud writes, never drop-then-reuse or `mode="overwrite"` the same table name — see "Enterprise: never drop-then-reuse the same table name" below. This is the main local-vs-remote write pitfall.
+10. If reviewing an existing file or repo, run `scripts/check_materialization.py` on the relevant paths and inspect each finding before editing.
+11. Cross-check unfamiliar or non-trivial API claims against the source tree instead of relying on memory.
+
+## Core Portability Rule
+
+Do not write code that assumes a local table API will exist on a remote table. Remote tables can be very large, so whole-table materialization helpers are intentionally unavailable or unsafe.
+
+This does **not** mean result conversion is forbidden. Bounded query/search result collection is normal:
+
+- Python: `table.search(...).select([...]).limit(10).to_pandas()`
+- TypeScript: `await table.search(...).select([...]).limit(10).toArray()`
+
+The unsafe pattern is table-level or unbounded collection, plus local-only dataset escape hatches in remote code:
+
+- Python: `table.to_pandas()`, `table.to_arrow()`, `table.to_polars()`; `table.to_lance()` is local/OSS-only dataset access, not materialization
+- TypeScript: `await table.toArrow()`, `await table.query().toArray()` without `limit()`
+
+## Enterprise: never drop-then-reuse the same table name
+
+LanceDB Enterprise/Cloud splits a **control plane** (DDL: create/drop/rename) from a **data plane** (query nodes that serve reads). Query nodes cache the resolved dataset for a table name for up to `table_cache_ttl` — **default 300 seconds (5 minutes)**. After you drop or overwrite a table, the control plane updates immediately but the data plane keeps serving the *old* dataset until that cache entry expires. During the window the two planes disagree.
+
+The failure this causes: you `drop_table("t")` then immediately `create_table("t", ...)` (or `create_table("t", ..., mode="overwrite")`). The DDL returns success, but every query against `t` returns **`500 Internal Server Error`** (the query node resolves the stale/deleted dataset), and a fresh `describe` may still show the *old* schema/version. It looks like your write silently failed; it didn't — the name is cached.
+
+**`mode="overwrite"` has the same problem** — it is a drop+create of the same name under the hood.
+
+Rules for portable Enterprise ingestion:
+
+1. **Never reuse a table name you just dropped/overwrote within the cache TTL.** Do not use `mode="overwrite"` to replace an existing Enterprise table in place.
+2. To (re)load data, **write to a fresh table name** (e.g. `<table>_v2`, or a run-stamped suffix). A brand-new name has no cached data-plane entry, so writes and reads work immediately.
+3. Before creating, `list_tables()` and **fail loudly if the name already exists** rather than overwriting — prompt for a new name.
+4. To land on a specific final name that is currently occupied by an old table: drop the old table, **wait out the TTL (~5 min), then `rename_table(fresh_name, final_name)`**. Renaming onto a name whose old dataset is still cached hits the same race, so the wait is mandatory. `rename_table` is a supported control-plane op.
+5. When you hand a table name back to a human, tell them which step still needs the propagation wait (usually: "the old `t` was dropped; run the rename in ~5 minutes").
+
+This is Enterprise/Cloud-specific. Local/OSS tables have no separate data plane, so `mode="overwrite"` and immediate same-name reuse are fine there.
+
+## Connecting to the LanceDB remote server
+
+LanceDB Enterprise/Cloud deployments are served by a server implementing the lance-namespace OpenAPI spec (<https://github.com/lance-format/lance-namespace/blob/main/docs/src/spec.yaml>). Every remote (`db://...`) connection talks to such a server, and some operations exist only there. In particular, **all operations around jobs (listing, inspecting, creating, or canceling jobs) run server-side** — there is no local/OSS equivalent. Before any job work, or any direct REST call to an Enterprise deployment, read `references/remote_connect.md` to resolve the base URL, credentials, and database header and to validate the connection. Then use the four job REST methods documented in `references/remote_jobs.md` (list, describe, cancel, query_events).
+
+## Script
+
+Run the scanner when reviewing or modifying an existing codebase:
+
+```bash
+python skills/lancedb/scripts/check_materialization.py path/to/file_or_dir
+```
+
+The script reports likely unsafe full-table materialization in Python and TypeScript. Treat results as review prompts, not automatic proof of a bug.
@@ -0,0 +1,6 @@
+interface:
+  display_name: "LanceDB"
+  short_description: "Build LanceDB pipelines in Python and TypeScript"
+  default_prompt: "Use $lancedb to create a table, embed sample text, and run a vector search."
+  icon_small: "./assets/icon.png"
+  icon_large: "./assets/icon.png"
@@ -0,0 +1,182 @@
+# Branch Operations
+
+Manage branches on a LanceDB table: list what exists, create new ones, delete stale ones, and direct read/write operations at a specific branch without touching main. Use for branch lifecycle tasks, experimental/isolated table versions, targeting an operation at a non-main branch, or confirming a mutation did not affect main.
+
+Works on local/OSS and remote Enterprise/Cloud tables, except merging a branch into main, which is Enterprise-only.
+
+## The branch model (important)
+
+Branches are isolated, writable lines of history forked from another branch (or a specific version). Writes on a branch never affect `main`.
+
+There is **no global "switch branch" state** — you never repoint the whole table at a branch. Instead, **operations are scoped by which table handle you use**:
+
+- The handle you got from `open_table(name)` / `openTable(name)` targets `main`.
+- `branches.create(...)` and `branches.checkout(...)` return a **new table handle scoped to that branch**. Every read/write on that handle (add, update, `update_field_metadata`, `create_index`, search, …) lands on the branch.
+- The original main handle is unaffected — keep it around to verify isolation.
+
+`branches.list()` returns only non-main branches. Main always exists and is not listed.
+
+## Python
+
+`table.branches` is a property returning the branch manager; `table.current_branch()` tells you what a handle is scoped to (`None` = main).
+
+```python
+table = db.open_table("products")            # scoped to main
+
+# list — dict of name -> metadata (parent_branch, parent_version, ...); {} = only main
+table.branches.list()
+
+# create: forks from main by default and returns a handle scoped to the new branch
+exp = table.branches.create("experiment-reindex")
+exp = table.branches.create("exp2", from_ref="main", from_version=None)  # optional fork point
+
+# checkout an existing branch -> branch-scoped handle
+wip = table.branches.checkout("wip-branch")
+# with version= it pins to that version (read-only detached view); omit to track latest, writable
+
+# operate on the branch simply by using its handle
+wip.update_field_metadata(
+    {"path": "category", "metadata": {"lancedb:description": "Product category label."}}
+)
+wip.create_scalar_index("category")
+
+# delete: removes only the branch pointer; main and row data remain intact
+table.branches.delete("stale-2024")
+
+# alternatively, open a branch handle directly from the connection
+wip = db.open_table("products", branch="wip-branch")
+
+exp.current_branch()    # "experiment-reindex"
+table.current_branch()  # None (main)
+```
+
+Async: same shape — `table.branches` returns `AsyncBranches`; `await table.branches.create(...)` etc.
+
+## TypeScript
+
+`table.branches()` is an **async method** returning the `Branches` manager; `table.currentBranch()` returns the scoped branch or `null` for main.
+
+```typescript
+const table = await db.openTable("products"); // scoped to main
+const branches = await table.branches();
+
+// list — Record<string, BranchContents>; {} = only main
+await branches.list();
+
+// create: forks from main by default, returns a Table scoped to the new branch
+const exp = await branches.create("experiment-reindex");
+const exp2 = await branches.create("exp2", "main" /* fromRef */, undefined /* fromVersion */);
+
+// checkout an existing branch -> branch-scoped Table
+const wip = await branches.checkout("wip-branch");
+// with a version arg it pins (read-only detached view); omit to track latest, writable
+
+// operate on the branch simply by using its handle
+await wip.updateFieldMetadata([
+  { path: "category", metadata: { "lancedb:description": "Product category label." } },
+]);
+await wip.createIndex("category");
+
+// delete: removes only the branch pointer; main and row data remain intact
+await branches.delete("stale-2024");
+
+// alternatively, open a branch handle directly from the connection
+const wip2 = await db.openTable("products", { branch: "wip-branch" });
+
+exp.currentBranch();   // "experiment-reindex"
+table.currentBranch(); // null (main)
+```
+
+## Verifying isolation
+
+After writing to a branch, confirm the change did NOT land on main by reading through both handles:
+
+```python
+wip = table.branches.checkout("wip-branch")
+wip.update_field_metadata({"path": "category", "metadata": {"lancedb:description": "..."}})
+
+assert b"lancedb:description" in (wip.schema.field("category").metadata or {})
+assert b"lancedb:description" not in (table.schema.field("category").metadata or {})  # main untouched
+```
+
+Two handles on the same branch see each other's writes (e.g. `table.branches.create("exp")` and `db.open_table(name, branch="exp")`); main stays isolated.
+
+## Merging a branch into main (Enterprise only)
+
+Merge is available through the SDKs (`table.branches.merge(...)`) on **Enterprise tables only** — it is not supported on Cloud or local/OSS tables, which raise `NotSupported`.
+
+`merge` takes the branch to merge **from** and a `dry_run` flag. Both the SDK method and the underlying REST endpoint **actually merge by default** (`dry_run=False`); pass `dry_run=True` to only preview. A rejected merge is **not an exception** — it returns a result with `status="rejected"` rather than raising, so inspect the return value. Use `branches.diff(from_branch)` to inspect a branch's pending diff without attempting a merge.
+
+```python
+exp = "experiment-reindex"
+
+# preview only — returns status="ready" if it would merge cleanly
+preview = table.branches.merge(exp, dry_run=True)
+
+# actually merge (default)
+result = table.branches.merge(exp)
+if result["status"] == "merged":
+    print("landed at", result["mainVersionAfter"])
+elif result["status"] == "rejected":
+    print(result["diff"]["mergeBlockers"])   # why it was refused
+
+# inspect a branch's pending diff without merging
+diff = table.branches.diff(exp)
+```
+
+Async: `await table.branches.merge(exp)`, `await table.branches.diff(exp)`.
+
+```typescript
+const branches = await table.branches();
+const exp = "experiment-reindex";
+
+// preview only (second arg is dryRun)
+const preview = await branches.merge(exp, true);
+
+// actually merge (default)
+const result = await branches.merge(exp);
+if (result.status === "merged") {
+  console.log("landed at", result.mainVersionAfter);
+} else if (result.status === "rejected") {
+  console.log(result.diff.mergeBlockers);
+}
+
+const diff = await branches.diff(exp);
+```
+
+The result is the wire JSON, containing `status` (`ready` on a passing dry run, `merged` on success, `rejected` when refused — also `notImplemented`/`unknown`), the branch `diff` (including `mergeBlockers` explaining any rejection), a `preview` of the columns that would be promoted, and — after a real merge — `mainVersionAfter`.
+
+### Merge preconditions
+
+Merge only **promotes newly added columns** onto main; it does not replay arbitrary commits. Practically, a branch is mergeable only if it has **exactly one commit since it was created, and that commit added a column**. The merge is rejected (`status: "rejected"`, with `mergeBlockers` set) if:
+
+- the branch was forked from another branch rather than directly from main
+- main has advanced since the branch was forked
+- the branch's rows changed since the fork (row counts must match main exactly)
+- the branch removed columns or changed a column's type/nullability
+- the branch added no columns (index-only changes are not merged)
+
+### Adding a column in a single commit
+
+Because the branch must contain just one column-adding commit, add the column with its values in one operation rather than add-then-backfill:
+
+1. **SQL transformation** — `add_columns` with a SQL expression computed from existing columns, so the column lands populated in one commit.
+2. **Precompute the values** — compute the column's values externally, then add the fully-populated column in a single operation (e.g. via `merge_insert`/`add_columns` with the data ready).
+3. **Lance-format-level data evolution (pylance)** — use Lance's data evolution with backfill, documented at <https://lance.org/guide/data_evolution/#with-data-backfill>.
+
+## Quick reference
+
+| Goal | Python | TypeScript |
+|------|--------|------------|
+| List branches (non-main) | `table.branches.list()` | `await (await table.branches()).list()` |
+| Create branch (off main) | `table.branches.create(name)` → branch handle | `await branches.create(name)` → branch `Table` |
+| Create from a fork point | `table.branches.create(name, from_ref=..., from_version=...)` | `await branches.create(name, fromRef, fromVersion)` |
+| Get a branch handle | `table.branches.checkout(name)` or `db.open_table(t, branch=name)` | `await branches.checkout(name)` or `await db.openTable(t, { branch: name })` |
+| Pin to a branch version (read-only) | `table.branches.checkout(name, version=v)` | `await branches.checkout(name, v)` |
+| Delete branch | `table.branches.delete(name)` | `await branches.delete(name)` |
+| Which branch is this handle on? | `table.current_branch()` (`None` = main) | `table.currentBranch()` (`null` = main) |
+| Target main | use the original (non-branch) handle | use the original (non-branch) handle |
+| Merge branch into main (Enterprise only) | `table.branches.merge(from_branch, dry_run=False)` | `await branches.merge(fromBranch, dryRun)` |
+| Preview a branch's pending diff (Enterprise only) | `table.branches.diff(from_branch)` | `await branches.diff(fromBranch)` |
+
+Branch names must be non-empty; empty names raise a validation error.
@@ -0,0 +1,183 @@
+# Column Metadata Authoring
+
+Write column-level descriptions, tags, and logical groupings onto a LanceDB table's schema. Use this when the user wants to document, annotate, tag, or classify what their table columns ARE (embeddings vs labels vs eval metrics, model provenance, version families, etc.).
+
+Works on local/OSS and remote Enterprise/Cloud tables alike — read the schema through the table handle, write through `update_field_metadata` (Python) / `updateFieldMetadata` (TypeScript).
+
+## Metadata key conventions
+
+All metadata uses namespaced keys:
+
+| Key | Purpose | Example value |
+|-----|---------|---------------|
+| `lancedb:description` | Human-readable explanation of what the column contains | `"CLIP ViT-L/14 image embedding, L2-normalized (768-dim)"` |
+| `lancedb:tag:<name>` | Flexible key-value tag; the suffix names the tag category | `lancedb:tag:field_type: "embedding"`, `lancedb:tag:model: "clip"`, `lancedb:tag:project_id: "foo"` |
+| `lancedb:logical-column` | Logical group/family this column belongs to | `"clip_features"` |
+
+Tags are open-ended — use whatever key suffix and value make sense given the user's intent. The tag suffix should describe *what is being classified* (e.g., `field_type`, `model`, `project_id`) and the value describes *how*. Multiple tags on the same column are fine — each is a separate key. All values are strings.
+
+## Step 1: Read the schema and existing metadata
+
+Read existing metadata before writing, to avoid redundant updates.
+
+Python — `table.schema` (sync property; async: `await table.schema()`) returns a `pyarrow.Schema`. **Arrow field metadata is bytes-keyed in Python**:
+
+```python
+schema = table.schema
+for field in schema:
+    meta = field.metadata or {}  # dict[bytes, bytes], e.g. {b"lancedb:description": b"..."}
+    print(field.name, field.type, field.nullable, meta)
+```
+
+TypeScript — `await table.schema()` returns an Arrow `Schema`; field metadata is a `Map<string, string>`:
+
+```typescript
+const schema = await table.schema();
+for (const field of schema.fields) {
+  console.log(field.name, field.type, field.nullable, field.metadata); // Map
+  // field.metadata.get("lancedb:description")
+}
+```
+
+For struct/nested fields, recurse into the field's children and address them as dot-paths (e.g., `parent.child`).
+
+If the user hasn't specified which columns to update, work with all columns.
+
+## Step 2: Generate metadata
+
+Decide what to generate based on the user's request.
+
+### Descriptions (`lancedb:description`)
+
+Base descriptions on:
+- The column name and Arrow type (e.g., `FixedSizeList` of floats → likely an embedding)
+- User-supplied context (upstream pipeline, sample values, domain knowledge)
+- Name patterns: `_embedding`/`_vec`/`_embed` → vector; `_label`/`_class` → label; `_score`/`_eval`/`_metric` → evaluation metric
+
+Be specific and concise. Good: `"Sentence-BERT embedding of the query text (768-dim)."` Not: `"An embedding column."`
+
+### Tags (`lancedb:tag:<name>`)
+
+Choose tag key names that match what the user asked to annotate. Common patterns:
+
+- Semantic field type → `lancedb:tag:field_type: "embedding"` / `"text"` / `"image"` / `"label"` / `"eval"` / `"id"` / `"metadata"`
+- Model or source → `lancedb:tag:model: "clip"` / `"bert"` / `"vit"`
+- Project affiliation → `lancedb:tag:project_id: "<name>"`
+- Version → `lancedb:tag:version: "v3"` (and `lancedb:tag:latest: "true"` for the newest)
+
+Use Arrow type as a hint: `FixedSizeList` + float → embedding; `Utf8`/`LargeUtf8` → text; `Binary` → image or blob.
+
+### Logical groupings (`lancedb:logical-column`)
+
+Look for naming patterns across columns:
+- `clip_v1`, `clip_v2`, `clip_v3` → logical column `"clip"`, latest is `v3`
+- `text_embed_20240101`, `text_embed_20240601` → logical column `"text_embed"`, latest is the most recent date suffix
+
+Write `lancedb:logical-column` on all members of a group. Mark the newest with `lancedb:tag:latest: "true"` (in addition to its version tag).
+
+## Step 3: Write the metadata
+
+Each update names a field by dot-path and carries a metadata map. Semantics (identical in both SDKs):
+
+- **Merge by default** (`replace` omitted/false) — preserves existing metadata the user didn't ask to change
+- `replace: true` swaps the field's entire metadata map — only if the user explicitly asks to overwrite
+- A value of `None`/`null` deletes that specific key
+- Batch all field updates into a single call when possible
+- Returns the new table version
+
+Python (sync and async take one dict per field, as varargs):
+
+```python
+res = table.update_field_metadata(
+    {
+        "path": "clip_v3",
+        "metadata": {
+            "lancedb:description": "CLIP ViT-L/14 image embedding, L2-normalized (1024-dim).",
+            "lancedb:tag:field_type": "embedding",
+            "lancedb:tag:model": "clip",
+            "lancedb:tag:version": "v3",
+            "lancedb:tag:latest": "true",
+            "lancedb:logical-column": "clip",
+        },
+    },
+    {
+        "path": "clip_v2",
+        "metadata": {
+            "lancedb:description": "CLIP ViT-B/32 image embedding (768-dim), superseded by v3.",
+            "lancedb:tag:field_type": "embedding",
+            "lancedb:tag:model": "clip",
+            "lancedb:tag:version": "v2",
+            "lancedb:logical-column": "clip",
+        },
+    },
+)
+print(res.version)  # new table version
+
+# merge semantics: add a key, delete one via None, keep the rest
+table.update_field_metadata(
+    {"path": "clip_v2", "metadata": {"lancedb:tag:archived": "true", "lancedb:tag:latest": None}}
+)
+```
+
+(`replace_field_metadata` is deprecated — use `update_field_metadata`.)
+
+TypeScript (takes an array of `FieldMetadataUpdate`):
+
+```typescript
+const res = await table.updateFieldMetadata([
+  {
+    path: "clip_v3",
+    metadata: {
+      "lancedb:description": "CLIP ViT-L/14 image embedding, L2-normalized (1024-dim).",
+      "lancedb:tag:field_type": "embedding",
+      "lancedb:tag:model": "clip",
+      "lancedb:tag:version": "v3",
+      "lancedb:tag:latest": "true",
+      "lancedb:logical-column": "clip",
+    },
+  },
+  {
+    path: "clip_v2",
+    metadata: {
+      "lancedb:description": "CLIP ViT-B/32 image embedding (768-dim), superseded by v3.",
+      "lancedb:tag:field_type": "embedding",
+      "lancedb:tag:model": "clip",
+      "lancedb:tag:version": "v2",
+      "lancedb:logical-column": "clip",
+    },
+  },
+]);
+console.log(res.version); // new table version
+
+// merge semantics: add a key, delete one via null, keep the rest
+await table.updateFieldMetadata([
+  { path: "clip_v2", metadata: { "lancedb:tag:archived": "true", "lancedb:tag:latest": null } },
+]);
+```
+
+## Step 4: Confirm
+
+Report back:
+- Which columns were updated and what was written
+- The new table version number (from the result)
+- Any columns skipped (e.g., already had up-to-date metadata)
+
+## Quick examples
+
+**"Write descriptions for all columns in the `product_embeddings` table"**
+1. Read `table.schema` → all fields + existing metadata
+2. Generate a `lancedb:description` for each column based on name + type
+3. One `update_field_metadata` call with all descriptions
+4. Report
+
+**"Tag the columns in `model_outputs` with their field type and model"**
+1. Read the schema
+2. For each field, classify by name + Arrow type → set `lancedb:tag:field_type` and `lancedb:tag:model` where applicable
+3. Write in one batched call
+4. Report
+
+**"Group the feature columns in `training_features` into logical families and mark the latest version"**
+1. Read the schema
+2. Find version patterns → assign `lancedb:logical-column` and `lancedb:tag:version`; mark newest with `lancedb:tag:latest: "true"`
+3. Write in one batched call
+4. Show the grouping
@@ -0,0 +1,138 @@
+# Python API Reference
+
+Quick method reference for Python LanceDB code. Cross-check source for non-trivial claims.
+
+## Connect
+
+If you're connecting to a remote database, use this:
+```python
+import lancedb
+
+db = lancedb.connect("db://my-db", api_key=api_key, host_override=host_override) # remote
+```
+(values may be found in LANCEDB_API_KEY and LANCEDB_HOST_OVERRIDE, either in env vars or a .env file)
+
+If you're connecting to a local table using OSS LanceDB, use this:
+```python
+db = lancedb.connect("./camelot-db") # local/OSS
+```
+If you're not sure which, or if you can't find the api_key or host_override params, ask the user.
+
+**Place the local database directory next to the script/entrypoint that opens it** (i.e. resolve the path relative to the script, `Path(__file__).parent / "camelot-db"`), not buried under a shared `data/` folder. The Lance dataset is the database, not a data file — keeping it beside its code makes ownership obvious and paths stable regardless of the working directory the script is launched from.
+
+**Do not name the directory `lancedb`** (e.g. `./lancedb`, `./data/lancedb`). It collides with the imported `lancedb` package name, which is confusing to read and easy to shadow in scripts. Give it a name derived from the repo or dataset with a clear prefix/suffix — for example `./<dataset>-db`, `./<repo>_lancedb`, or `./vectordb`.
+
+Async:
+
+```python
+db = await lancedb.connect_async("./camelot-db")
+```
+
+## Table Reads
+
+| Task | Preferred API |
+| --- | --- |
+| Vector search | `table.search(query_vector).limit(k)` |
+| Full scan with filters/projection (sync) | `table.search().where(...).select(...).limit(...)` |
+| Full scan with filters/projection (async) | `table.query().where(...).select(...).limit(...)` |
+| Filter | `.where("col > 10")` |
+| Projection | `.select(["id", "text"])` |
+| Bound result count | `.limit(20)` |
+| Collect bounded result as Python objects (default, no extra deps) | `.to_list()` on query/search result |
+| Collect bounded result as Arrow (default, `pyarrow` always available) | `.to_arrow()` on query/search result |
+| Collect bounded result as pandas (only if project uses pandas) | `.to_pandas()` on query/search result |
+| Collect bounded result as Polars (only if project uses polars) | `.to_polars()` on query/search result |
+
+## Sync vs Async Scan API
+
+The plain-scan entry point differs between the sync and async clients. **Verified against `lancedb` 0.34.0** — re-check if the pinned version changes:
+
+- **Sync** (`lancedb.connect(...)`): the table has **no `.query()` method**. Use `.search()` with no argument for a plain scan; it returns a query builder that supports `.where()`, `.select()`, `.limit()`, and the `.to_list()` / `.to_arrow()` / `.to_pandas()` / `.to_polars()` collectors.
+  ```python
+  rows = table.search().where("status = 'ready'").select(["id", "text"]).limit(20).to_list()
+  ```
+- **Async** (`lancedb.connect_async(...)`): the table has **both** `.query()` and `.search()`. Use `.query()` for a plain scan.
+  ```python
+  rows = await async_table.query().where("status = 'ready'").select(["id", "text"]).limit(20).to_list()
+  ```
+
+Do not call `table.query()` on a sync table — it raises `AttributeError`.
+
+## Local vs Remote Table Methods
+
+| API | Local table | Remote table | Agent guidance |
+| --- | --- | --- | --- |
+| `table.search(...)` | Yes | Yes | Preferred read path (sync + async) |
+| `table.query()` | Async only | Async only | Sync scan path is `table.search()`; `.query()` is the async scan builder |
+| `table.to_pandas()` | Yes | No / unsafe for portability | Avoid in portable code |
+| `table.to_arrow()` | Yes | No / unsafe for portability | Avoid in portable code |
+| `table.to_polars()` | Yes | No / unsafe for portability | Avoid in portable code |
+| `table.to_lance()` | Yes | No | Local/OSS escape hatch only |
+
+## Indexes
+
+Use `create_index(...)` for vector indexes and modern index configs. Use scalar indexes for filtered or merge keys.
+
+Common calls:
+
+```python
+table.create_index("vector")
+table.create_scalar_index("status")
+table.create_fts_index("text")
+```
+
+Check source docs before specifying advanced index config names or parameters.
+
+## Filtering And Recall Knobs
+
+```python
+table.search(query_vector).where("status = 'ready'")  # pre-filter by default
+table.search(query_vector).where("status = 'ready'", prefilter=False)
+table.search(query_vector).limit(10).refine_factor(20)
+table.search(query_vector).limit(10).nprobes(50)
+```
+
+Use post-filtering only when fewer than `limit` results are acceptable.
+
+## Diagnostics
+
+```python
+print(table.search(query_vector).where("year > 2000").limit(10).analyze_plan())
+print(table.index_stats("vector_idx"))
+```
+
+Use these before changing indexes or search tuning.
+
+## Column (Field) Metadata
+
+```python
+schema = table.schema                       # sync property; async: await table.schema()
+meta = schema.field("category").metadata    # dict[bytes, bytes] — Arrow metadata is bytes-keyed
+res = table.update_field_metadata(          # varargs: one dict per field; works local + remote
+    {"path": "category", "metadata": {"lancedb:description": "...", "lancedb:tag:field_type": "label"}}
+)
+res.version  # new table version
+```
+
+Merges by default; a `None` value deletes that key; `"replace": True` swaps the whole map. Nested fields use dot-paths (`"a.b.c"`). `replace_field_metadata` is deprecated. See `references/column_metadata.md` for key conventions (`lancedb:description`, `lancedb:tag:<name>`, `lancedb:logical-column`) and the authoring workflow.
+
+## Branches
+
+```python
+table.branches.list()                          # non-main branches; {} = only main
+exp = table.branches.create("exp")             # fork off main -> handle scoped to the branch
+wip = table.branches.checkout("wip")           # existing branch -> scoped handle (version= pins read-only)
+wip = db.open_table("t", branch="wip")         # or open scoped directly
+table.branches.delete("stale")                 # removes only the branch pointer
+table.current_branch()                         # None = main
+```
+
+There is no global switch — scoping is per table handle: any read/write on a branch handle lands on that branch; the original handle keeps targeting main. See `references/branch_ops.md` for the model and isolation checks.
+
+## Maintenance
+
+```python
+table.optimize()
+```
+
+Call this after every successful local/OSS ingestion. It handles compaction, cleanup of old versions according to retention, and index optimization. Do not add this for LanceDB Enterprise/Cloud remote tables; Enterprise handles compaction and cleanup automatically from cluster configuration.
@@ -0,0 +1,173 @@
+# Python Patterns
+
+Use these patterns when writing Python code with `lancedb`.
+
+## Before Writing Code
+
+Choose the output type from what the project actually depends on. **Do not assume `pandas` or `polars` is installed** — they are heavy dependencies that many LanceDB projects do not use. `pyarrow`, by contrast, ships as a LanceDB dependency and is always available, so it is a safe default to lean on.
+
+Default output (after applying `select()` and `limit()`):
+
+- **Python objects**: `.to_list()` — a list of dicts, no extra dependencies. Prefer this for scripts, examples, and agent-generated code unless there is a reason to do otherwise.
+- **PyArrow**: `.to_arrow()` — a `pyarrow.Table`, when the surrounding code is Arrow-native or you need columnar/zero-copy handoff.
+
+Only reach for a DataFrame when the project *already* declares that dependency:
+
+- Pandas projects (pandas in `pyproject.toml`/requirements): `.to_pandas()`.
+- Polars projects (polars declared): `.to_polars()`.
+
+If unsure, check the dependency manifest or the imports in surrounding files. When in doubt, use `.to_list()` or `.to_arrow()`.
+
+## Schema Design and Validation
+
+Favor `LanceModel` and Pydantic validation for Python schemas. They keep field
+types readable, validate source records before a write, and map directly to a
+LanceDB schema. Use `Vector(dimension)` for fixed-size vectors:
+
+```python
+from lancedb.pydantic import LanceModel, Vector
+
+class Document(LanceModel):
+    id: int
+    text: str
+    vector: Vector(384, nullable=False)
+
+rows = [Document.model_validate(row) for row in source_rows]
+table = db.create_table("documents", schema=Document)
+table.add(rows)
+```
+
+Use PyArrow schemas instead when the pipeline is already Arrow-native, needs
+record-batch streaming, or has runtime schema requirements that would make a
+Pydantic model harder to understand. Declare Pydantic as a direct project
+dependency when application code imports it, even if LanceDB also depends on it.
+
+## Recommended Patterns
+
+### Bounded search or query
+
+Use this for application reads, examples, notebooks, and agent-generated scripts:
+
+```python
+results = (
+    table.search(query_vector)
+    .where("status = 'ready'")
+    .select(["id", "text"])
+    .limit(20)
+    .to_list()  # or .to_arrow(); .to_pandas()/.to_polars() only if the project uses them
+)
+```
+
+Why: `search()` works across local and remote tables and on both the sync and async clients. `select()` avoids fetching unused columns. `limit()` prevents accidental full-table reads. `.to_list()` and `.to_arrow()` avoid assuming pandas/polars is installed (see "Before Writing Code").
+
+For a **plain scan** (no query vector), the entry point differs by client:
+
+```python
+# Sync client: no .query() method — use .search() with no argument.
+rows = table.search().where("status = 'ready'").select(["id", "text"]).limit(20).to_list()
+
+# Async client: use .query().
+rows = await async_table.query().where("status = 'ready'").select(["id", "text"]).limit(20).to_list()
+```
+
+`table.query()` on a sync table raises `AttributeError` (verified on `lancedb` 0.34.0). See the "Sync vs Async Scan API" section in `api_reference.md`.
+
+### Bounded query result conversion
+
+It is fine to collect bounded query/search results:
+
+```python
+arrow_table = table.search().select(["id"]).limit(100).to_arrow()  # sync plain scan
+rows = table.search(query_vector).limit(10).to_list()
+df = table.search(query_vector).limit(10).to_pandas()  # only if pandas is a project dep
+```
+
+### Local-only Lance dataset API
+
+`table.to_lance()` does not itself materialize the full dataset. It returns the underlying `lance.LanceDataset`, making the table accessible through the PyLance dataset API. Use it when the task is explicitly local/OSS and needs Lance dataset methods not exposed by LanceDB:
+
+```python
+# Local/OSS only: RemoteTable does not expose table.to_lance().
+ds = table.to_lance()
+for batch in ds.to_batches(columns=["id", "text"], batch_size=10_000):
+    process(batch)
+```
+
+### Async Python
+
+Keep the same shape and bound the result before collecting:
+
+```python
+results = await (
+    async_table.query()
+    .where("status = 'ready'")
+    .select(["id", "text"])
+    .limit(20)
+    .to_list()  # or .to_arrow()
+)
+```
+
+## Anti-Patterns
+
+**Avoid the following anti-patterns in your code.**
+
+### Table-level full materialization
+
+Avoid whole-table collectors in portable or large-table code:
+
+```python
+df = table.to_pandas()
+arrow_table = table.to_arrow()
+polars_df = table.to_polars()
+```
+
+Why: local tables expose these whole-table collectors, but remote tables intentionally do not — a remote production table can be far larger than a local development table, so it is easy to accidentally pull the entire table into memory.
+
+`table.to_lance()` is different: it is not a full materialization call, but it is still local/OSS-only and should not appear in code meant to run against remote Enterprise tables.
+
+### Unbounded result collection
+
+Avoid query/search collection without a meaningful limit:
+
+```python
+rows = table.search().to_list()               # unbounded plain scan
+rows = table.search(query_vector).to_list()   # unbounded vector search
+```
+
+Prefer `select(...).limit(...)` before collecting; for large reads, stream in batches instead.
+
+### Per-row writes
+
+Avoid loops that write one row per call:
+
+```python
+for row in rows:
+    table.add([row])  # one commit + fragment per row
+```
+
+Each `add()` creates a new version and fragment. Pass the whole batch in a single call, or chunk very large inputs:
+
+```python
+table.add(rows)  # single commit
+# for very large inputs, add batches of several thousand rows
+```
+
+After the final successful write to an embedded OSS table, call
+`table.optimize()`. Skip this for Enterprise/Cloud tables because their
+maintenance is automatic.
+
+### Drop-then-reuse the same table name (Enterprise/Cloud)
+
+Avoid dropping or overwriting a remote table and then reusing that name right away:
+
+```python
+db.drop_table("my_table")
+table = db.create_table("my_table", data=rows)          # reads 500 for ~5 min
+table = db.create_table("my_table", data=rows, mode="overwrite")  # same problem
+```
+
+Why: Enterprise/Cloud splits DDL (control plane) from query serving (data plane). The data plane caches the dataset behind a table name for up to `table_cache_ttl` (default 300s / 5 min), so after a drop/overwrite the DDL succeeds but queries against the reused name return `500 Internal Server Error` until the cache expires — and a fresh `describe` may still show the old schema. Instead, write to a **fresh name**, use `list_tables()` and fail if it already exists, then `rename_table(fresh, final)` onto the final name only after the old table's drop has propagated (~5 min). See the "Enterprise: never drop-then-reuse the same table name" section in `SKILL.md`. Local/OSS tables have no separate data plane — overwrite freely there.
+
+### Guessing performance fixes
+
+Avoid changing `nprobes`, `refine_factor`, or index types before checking the query plan and index stats. Diagnose first, then tune one knob at a time.
@@ -0,0 +1,131 @@
+# Python Performance Guidance
+
+Use this when writing Python code that ingests data, queries large tables, builds indexes, or investigates latency.
+
+## Ingestion
+
+### Recommended: validate schemas and records with Pydantic
+
+Favor `LanceModel` for readable Python schema definitions and validate source
+records before writing. Use PyArrow directly for Arrow-native or streaming
+pipelines where it is the clearer representation.
+
+```python
+from lancedb.pydantic import LanceModel, Vector
+
+class Document(LanceModel):
+    id: int
+    text: str
+    vector: Vector(384, nullable=False)
+
+rows = [Document.model_validate(row) for row in source_rows]
+table = db.create_table("documents", schema=Document)
+table.add(rows)
+```
+
+### Recommended: bulk ingestion for materialized data
+
+```python
+table.add(arrow_table)
+table.add(df)
+table.add(pa.dataset("data/", format="parquet"))
+```
+
+For very large initial loads, create the table empty first, then call `add(...)`. Passing data directly to `create_table(name, data)` can skip the auto-parallel write path.
+
+### Recommended: iterator ingestion for generated or streamed data
+
+```python
+def batches():
+    for raw in source:
+        vectors = model.encode(raw["text"])
+        yield pa.RecordBatch.from_pydict({**raw, "vector": vectors})
+
+table.add(batches())
+```
+
+Use chunks of several thousand rows or more when practical. Tiny batches and per-row writes create many small fragments.
+
+### Anti-pattern: per-row `add()`
+
+```python
+for row in rows:
+    table.add([row])
+```
+
+Each call creates a version and fragment. This slows ingestion and later queries.
+
+## Indexing
+
+- Build a vector index once brute-force vector search becomes too slow. As a rule of thumb, local brute force is fine below roughly 100K vectors; beyond that, build an index.
+- Use `IVF_PQ` as the general-purpose default. Enterprise builds this automatically.
+- Use scalar indexes for filtered columns and merge/upsert keys.
+- Use `BTREE` for mostly distinct numeric/string/temporal columns, `BITMAP` for booleans and low-cardinality columns, and `LABEL_LIST` for list membership queries.
+- Keep full-text defaults unless phrase queries require position data.
+
+## Querying
+
+Always be explicit:
+
+```python
+table.search(query_vector).select(["id", "title"]).limit(20)
+```
+
+- `select()` reduces bytes read and transferred.
+- `limit()` prevents accidental full-table materialization.
+- Pre-filtering is the default and guarantees returned rows satisfy the predicate.
+- Use post-filtering only when fewer than `limit` results are acceptable.
+
+## Recall Tuning
+
+Tune one knob at a time:
+
+- Quantized indexes: raise `refine_factor` to rescore more candidates on full vectors.
+- HNSW-backed indexes: raise `ef`; start around `1.5 * k`, increase toward `10 * k` if recall is short.
+- IVF candidate breadth: `nprobes` is auto-tuned; override only when a selective pre-filter leaves too few neighbors.
+
+## Maintenance
+
+After every successful embedded OSS/local ingestion, call `table.optimize()`.
+Do not add this to LanceDB Enterprise/Cloud remote table code; remote compaction
+and cleanup are handled automatically based on the Enterprise cluster
+configuration.
+
+Why local maintenance is needed:
+
+- Frequent writes can create many small fragments. Queries then need to scan across more files, which can increase latency.
+- Updates, deletes, and appends create new table versions. Old versions are retained for time travel and rollback, which can grow disk usage.
+- Indexes may have newly added rows that are not yet fully optimized into the index structure.
+
+For local/OSS tables, run `optimize()` after the final successful ingestion
+write. Also run it after later batches of update/delete operations or on a
+regular maintenance schedule:
+
+```python
+table.optimize()
+```
+
+If the user wants more aggressive local disk cleanup, pass a shorter cleanup retention window:
+
+```python
+from datetime import timedelta
+
+table.optimize(cleanup_older_than=timedelta(days=1))
+```
+
+Do not use very short cleanup windows when the application depends on time travel, rollback, or old versions.
+
+## Diagnostics
+
+Before changing code or indexes, inspect:
+
+```python
+print(table.search(query_vector).where("year > 2000").limit(10).analyze_plan())
+print(table.index_stats("vector_idx"))
+```
+
+Look for high scan bytes, missing indexes, fragmented data, and unindexed rows.
+
+## Python Multiprocessing
+
+When using multiprocessing, use `spawn` rather than `fork`. LanceDB is multi-threaded internally, and `fork` plus a multi-threaded process is unsafe.
@@ -0,0 +1,45 @@
+# Connecting to a LanceDB remote server
+
+LanceDB Enterprise/Cloud deployments are served by a server implementing the
+lance-namespace OpenAPI spec
+(<https://github.com/lance-format/lance-namespace/blob/main/docs/src/spec.yaml>).
+Every remote (`db://...`) connection talks to such a server, and some operations
+exist only there. In particular, all operations around jobs (listing, inspecting,
+creating, or canceling jobs) run server-side — there is no local/OSS equivalent, so
+resolve a server connection before attempting any job work. The job REST methods
+themselves are documented in `references/remote_jobs.md`.
+
+Every request needs two things:
+
+1. **Base URL** — the server endpoint
+2. **Credentials** — an API key (`x-api-key` header over REST), and usually a database name (`x-lancedb-database` header)
+
+## Resolution steps
+
+1. If the user already gave a URL and API key (or said which environment they're working against), use that.
+2. Otherwise, look for credentials already available in the environment:
+   - Env vars like `LANCEDB_URI` / `LANCEDB_HOST` / `LANCEDB_API_KEY`
+   - A server endpoint already running or port-forwarded locally (the REST default port is 2333, i.e. `http://localhost:2333`)
+3. If you didn't find both pieces, ask the user directly: **"What's your LanceDB endpoint's URL, and what's your API key?"** Also ask which database to use if it isn't obvious. Don't guess or probe further — the user knows their deployment.
+
+## Validating the connection
+
+Make a cheap authenticated request and check the status before starting real work:
+
+```bash
+curl -s -w "\n%{http_code}" "{base_url}/v1/table/?limit=1" \
+  -H "x-api-key: <key>" \
+  -H "x-lancedb-database: <database>"
+```
+
+- `200` — connection, key, and database header all good
+- `401` — API key missing or wrong
+- `400` mentioning a database header — this deployment expects `x-lancedb-database`
+
+## Non-REST equivalents
+
+The same credentials work through the SDKs and CLI:
+
+- Python SDK: `lancedb.connect("db://<database>", api_key="<key>", host_override="<base_url>")`
+- TypeScript SDK: `await lancedb.connect("db://<database>", { apiKey: "<key>", hostOverride: "<base_url>" })`
+- `lancedb` CLI: a `[profiles.<name>]` entry in `~/.lancedb/config.toml` with `http_server_url`, `api_key`, `database`
@@ -0,0 +1,151 @@
+# Job operations over the LanceDB remote server REST API
+
+Jobs are server-side background operations on LanceDB Enterprise/Cloud — index builds,
+column backfills, materialized view refreshes, and similar async work. Endpoints that
+trigger async work (e.g. the column backfill or materialized view refresh endpoints)
+return a `job_id`; these four methods are how you track and manage those jobs.
+
+Resolve the connection first — see `references/remote_connect.md`. All four methods
+are **POST** requests under `{base_url}/v1/jobs/` with JSON bodies, and take the usual
+`x-api-key` / `x-lancedb-database` headers. If every job call returns `501`, job APIs
+are disabled on that deployment (the server has no job registry configured) — report
+that rather than retrying.
+
+## 1. List jobs — `POST /v1/jobs/list`
+
+The body is optional; an empty body lists everything. All fields are filters:
+
+```json
+{
+  "limit": 100,
+  "table_name": "my_table",
+  "job_type": "...",
+  "job_subtype": "...",
+  "state": "...",
+  "page_token": "..."
+}
+```
+
+```bash
+curl -s -X POST "{base_url}/v1/jobs/list" \
+  -H "x-api-key: <key>" -H "x-lancedb-database: <database>" \
+  -H "content-type: application/json" \
+  -d '{"table_name": "my_table"}'
+```
+
+Response:
+
+```json
+{
+  "jobs": [
+    {
+      "job_id": "...",
+      "table": "my_table",
+      "job_type": "...",
+      "job_subtype": "...",
+      "state": "done",
+      "created_at_millis": 1720000000000
+    }
+  ],
+  "page_token": "..."
+}
+```
+
+A `page_token` in the response means there are more results — pass it back in the next
+request to continue. Note list rows use a lowercase `state` string, while describe uses
+an uppercase `job_state`.
+
+## 2. Describe a job — `POST /v1/jobs/describe`
+
+Body: `{"job_id": "<id>"}`. Returns full detail for one job:
+
+```json
+{
+  "job_id": "...",
+  "job_type": "...",
+  "job_subtype": "...",
+  "job_state": "IN_PROGRESS",
+  "creation_ms": 1720000000000,
+  "spec": {},
+  "status": {}
+}
+```
+
+`job_state` is one of `IN_PROGRESS`, `CANCELLED`, `FAILED`, `DONE`. `spec` and `status`
+are job-type-specific JSON objects (the job's input specification and its current
+progress/status). Returns `404` for an unknown job id.
+
+## 3. Cancel a job — `POST /v1/jobs/cancel`
+
+Body: `{"job_id": "<id>"}`; response echoes `{"job_id": "<id>"}`. Cancellation is a
+service-level operation requiring the same administrative authorization as the
+`/admin` routes — a database-scoped API key that can list and describe jobs may still
+get a permission error here. Other errors: `404` unknown job, `409` state conflict
+(e.g. already in a terminal state), `429` too much write contention (safe to retry).
+
+## 4. Query job event history — `POST /v1/jobs/query_events`
+
+Returns the event history (state transitions, progress updates) for one or more jobs.
+Body: `{"job_id": "<id>"}` for one job, or `{"job_ids": ["<id>", ...]}` for a batch.
+Optional fields: `limit` (max event rows), `limit_per_job` (per job in a batch query),
+and `filter` — a SQL-like expression over the columns `state`, `updated_by`,
+`owner_component`, and `claim_entity`. (`full_text_search` is reserved and currently
+rejected as not implemented.)
+
+The response is **not JSON** — it is an Arrow IPC stream
+(`content-type: application/vnd.apache.arrow.stream`). Decode it, e.g. in Python:
+
+```python
+import pyarrow.ipc
+import requests
+
+resp = requests.post(
+    f"{base_url}/v1/jobs/query_events",
+    headers={"x-api-key": key, "x-lancedb-database": database},
+    json={"job_id": job_id},
+)
+resp.raise_for_status()
+events = pyarrow.ipc.open_stream(resp.content).read_all()
+```
+
+## Feature engineering (Geneva) jobs
+
+Feature engineering jobs — UDF column backfills and materialized view refreshes run
+through Geneva — are tracked **separately** from the `/v1/jobs` registry above. Their
+records live in a `geneva_jobs` table inside the database itself (in the `__system`
+namespace), and you access them through a Python `geneva` connection rather than the
+REST endpoints above:
+
+```python
+import geneva
+from geneva.jobs import JobStateManager
+
+# Same credentials as lancedb.connect / the REST API
+conn = geneva.connect("db://<database>", api_key="<key>", host_override="<base_url>")
+jsm = JobStateManager(conn)
+
+# List jobs. NOTE: status defaults to "RUNNING"; pass status=None for all jobs.
+# Statuses: PENDING | RUNNING | DONE | FAILED | CANCELLED
+jobs = jsm.list_jobs(table_name="my_table", status=None)
+
+# Fetch one job by id (returns a list of JobRecord)
+records = jsm.get("<job_id>")
+```
+
+Each `JobRecord` has `table_name`, `column_name`, `job_id`, `job_type`, `status`,
+`launched_at`, `completed_at`, `config`, `launched_by`, `manifest_id`, `cluster_name`,
+`metrics` (progress counters), `events` (human-readable history), and `updated_at`.
+For filters `list_jobs` doesn't support (e.g. time ranges), query the underlying table
+directly: `jsm.get_table(True).search().where("launched_at >= TIMESTAMP '...'")` —
+pass `True` to check out the latest version, since other processes update job state.
+
+Stale-status caveat: nothing reaps dead Geneva jobs, so a job can sit in
+`RUNNING`/`PENDING` forever if its worker died. Treat a job as effectively `FAILED`
+when it has been running longer than ~36 hours, or its `updated_at` is more than ~2
+hours old (this matches the heuristic the Geneva console UI applies on read).
+
+## Workflow tips
+
+- To wait for async work (a backfill, an index build), poll `describe` until
+  `job_state` leaves `IN_PROGRESS`; on `FAILED`, pull `status` and `query_events` for
+  the failure detail.
@@ -0,0 +1,105 @@
+# TypeScript API Reference
+
+Quick method reference for TypeScript LanceDB code. Cross-check source for non-trivial claims.
+
+## Connect
+
+```typescript
+import * as lancedb from "@lancedb/lancedb";
+
+const db = await lancedb.connect("./camelot-db");
+```
+
+**Place the local database directory next to the script/entrypoint that opens it** (resolve the path relative to the module, e.g. via `import.meta.dirname` / `__dirname`), not buried under a shared `data/` folder. The Lance dataset is the database, not a data file — keeping it beside its code makes ownership obvious and paths stable regardless of the working directory the script is launched from.
+
+**Do not name the directory `lancedb`** (e.g. `./lancedb`, `./data/lancedb`). It collides with the imported `lancedb` package/namespace, which is confusing to read. Give it a name derived from the repo or dataset with a clear prefix/suffix — for example `./<dataset>-db`, `./<repo>_lancedb`, or `./vectordb`.
+
+Remote connections use `db://...` plus Enterprise/Cloud credentials and deployment settings. Check current source/docs for exact connection options.
+
+## Table Reads
+
+| Task | Preferred API |
+| --- | --- |
+| Vector search | `table.search(queryVector).limit(k)` |
+| Full scan with filters/projection | `table.query().where(...).select(...).limit(...)` |
+| Filter | `.where("col > 10")` |
+| Projection | `.select(["id", "text"])` |
+| Bound result count | `.limit(20)` |
+| Collect bounded result as objects | `.toArray()` on query/search result |
+| Collect bounded result as Arrow | `.toArrow()` on query/search result |
+| Stream result batches | `for await (const batch of table.query()...)` |
+
+## Local vs Remote Safety
+
+| API | Agent guidance |
+| --- | --- |
+| `table.search(...)` | Preferred read path |
+| `table.query()` | Preferred scan/filter path |
+| `await table.toArrow()` | Avoid in portable or large-table code |
+| `await table.query().toArray()` with no `limit()` | Avoid; unbounded collection |
+| `await table.query().toArrow()` with no `limit()` | Avoid; unbounded collection |
+
+## Indexes
+
+```typescript
+await table.createIndex("vector");
+await table.createIndex("status");
+```
+
+Use vector indexes for large vector search workloads and scalar indexes for filtered columns or merge/upsert keys. Check source/docs before specifying advanced index options.
+
+## Filtering And Recall Knobs
+
+```typescript
+await table.search(queryVector).where("status = 'ready'").limit(10).toArray();
+await table.search(queryVector).limit(10).refineFactor(20).toArray();
+await table.search(queryVector).limit(10).nprobes(50).toArray();
+await table.search(queryVector).limit(10).ef(100).toArray();
+await table.search(queryVector).where("status = 'ready'").postfilter().limit(10).toArray();
+```
+
+Use `postfilter()` only when fewer than `limit` results are acceptable.
+
+## Diagnostics
+
+```typescript
+console.log(await table.search(queryVector).where("year > 2000").limit(10).analyzePlan());
+console.log(await table.indexStats("vector_idx"));
+```
+
+Use these before changing indexes or search tuning.
+
+## Column (Field) Metadata
+
+```typescript
+const schema = await table.schema();
+const meta = schema.fields.find((f) => f.name === "category")?.metadata; // Map<string, string>
+const res = await table.updateFieldMetadata([
+  { path: "category", metadata: { "lancedb:description": "...", "lancedb:tag:field_type": "label" } },
+]);
+res.version; // new table version
+```
+
+Merges by default; a `null` value deletes that key; `replace: true` swaps the whole map. Nested fields use dot-paths (`"a.b.c"`). See `references/column_metadata.md` for key conventions (`lancedb:description`, `lancedb:tag:<name>`, `lancedb:logical-column`) and the authoring workflow.
+
+## Branches
+
+```typescript
+const branches = await table.branches();       // async manager
+await branches.list();                         // non-main branches; {} = only main
+const exp = await branches.create("exp");      // fork off main -> Table scoped to the branch
+const wip = await branches.checkout("wip");    // existing branch -> scoped Table (version arg pins read-only)
+const wip2 = await db.openTable("t", { branch: "wip" }); // or open scoped directly
+await branches.delete("stale");                // removes only the branch pointer
+table.currentBranch();                         // null = main
+```
+
+There is no global switch — scoping is per table handle: any read/write on a branch handle lands on that branch; the original handle keeps targeting main. See `references/branch_ops.md` for the model and isolation checks.
+
+## Maintenance
+
+```typescript
+await table.optimize();
+```
+
+Call this after every successful local/OSS ingestion. It handles compaction, cleanup of old versions according to retention, and index optimization. Do not add this for LanceDB Enterprise/Cloud remote tables; Enterprise handles compaction and cleanup automatically from cluster configuration.
@@ -0,0 +1,100 @@
+# TypeScript Patterns
+
+Use these patterns when writing TypeScript code with `@lancedb/lancedb`.
+
+## Recommended Patterns
+
+### Bounded query
+
+Use this for application reads, scripts, and examples:
+
+```typescript
+const rows = await table
+  .query()
+  .where("status = 'ready'")
+  .select(["id", "text"])
+  .limit(20)
+  .toArray();
+```
+
+### Bounded vector search
+
+```typescript
+const rows = await table
+  .search(queryVector)
+  .select(["id", "text"])
+  .limit(20)
+  .toArray();
+```
+
+### Batch streaming for larger reads
+
+When the task needs many rows, avoid collecting everything at once:
+
+```typescript
+for await (const batch of table
+  .query()
+  .where("status = 'ready'")
+  .select(["id", "text"])
+  .limit(10_000)) {
+  process(batch);
+}
+```
+
+## Anti-Patterns
+
+**Avoid the following anti-patterns in your code.**
+
+### Table-level full materialization
+
+Avoid whole-table collectors in portable or large-table code:
+
+```typescript
+const tableArrow = await table.toArrow();
+```
+
+Why: local tables expose these whole-table collectors, but remote tables intentionally do not — a remote production table can be far larger than a local development table, so it is easy to accidentally pull the entire table into memory.
+
+### Unbounded result collection
+
+Avoid query/search collection without a meaningful limit:
+
+```typescript
+const rows = await table.query().toArray();              // unbounded plain scan
+const rows = await table.search(queryVector).toArray();  // unbounded vector search
+```
+
+Prefer `select(...).limit(...)` before collecting; for large reads, stream in batches instead.
+
+### Per-row writes
+
+Avoid loops that write one row per call:
+
+```typescript
+for (const row of rows) {
+  await table.add([row]); // one commit + fragment per row
+}
+```
+
+Each `add()` creates a new version and fragment. Pass the whole batch in a single call, or chunk very large inputs:
+
+```typescript
+await table.add(rows); // single commit
+// for very large inputs, add in chunks of several thousand rows
+```
+
+### Drop-then-reuse the same table name (Enterprise/Cloud)
+
+Avoid dropping or overwriting a remote table and then reusing that name right away:
+
+```typescript
+await db.dropTable("my_table");
+const table = await db.createTable("my_table", rows);                    // reads 500 for ~5 min
+const table = await db.createTable("my_table", rows, { mode: "overwrite" }); // same problem
+```
+
+Why: Enterprise/Cloud splits DDL (control plane) from query serving (data plane). The data plane caches the dataset behind a table name for up to `table_cache_ttl` (default 300s / 5 min), so after a drop/overwrite the DDL succeeds but queries against the reused name return `500 Internal Server Error` until the cache expires — and a fresh `describe` may still show the old schema. Instead, write to a **fresh name**, use `tableNames()` and fail if it already exists, then `renameTable(fresh, final)` onto the final name only after the old table's drop has propagated (~5 min). See the "Enterprise: never drop-then-reuse the same table name" section in `SKILL.md`. Local/OSS tables have no separate data plane — overwrite freely there.
+
+### Guessing performance fixes
+
+Avoid changing `nprobes`, `refineFactor`, `ef`, or index settings before checking `analyzePlan()` and `indexStats(...)`. Diagnose first, then tune one knob at a time.
@@ -0,0 +1,78 @@
+# TypeScript Performance Guidance
+
+Use this when writing TypeScript code that ingests data, queries large tables, builds indexes, or investigates latency.
+
+## Ingestion
+
+- Prefer bulk or batched writes.
+- Avoid per-row write loops; they create many small commits/fragments.
+- For generated data, accumulate reasonable batches before adding.
+- For file-backed data, prefer APIs that stream from Arrow/Parquet-style inputs when available.
+
+## Indexing
+
+- Build a vector index once brute-force vector search becomes too slow. As a rule of thumb, local brute force is fine below roughly 100K vectors; beyond that, build an index.
+- Use the general-purpose vector index defaults unless the task has explicit recall/latency requirements.
+- Build scalar indexes for filtered columns and merge/upsert keys.
+- Use full-text index phrase options only when phrase queries require them.
+
+## Querying
+
+Always be explicit:
+
+```typescript
+await table.search(queryVector).select(["id", "title"]).limit(20).toArray();
+```
+
+- `select()` reduces bytes read and transferred.
+- `limit()` prevents accidental full-table collection.
+- Pre-filtering is the default behavior. Use `postfilter()` only when fewer than `limit` results are acceptable.
+
+## Recall Tuning
+
+Tune one knob at a time:
+
+- Quantized indexes: raise `refineFactor(...)` to rescore more candidates on full vectors.
+- HNSW-backed indexes: raise `ef(...)`; start around `1.5 * k`, increase toward `10 * k` if recall is short.
+- IVF candidate breadth: `nprobes(...)` is usually auto-tuned; override only when a selective pre-filter leaves too few neighbors.
+
+## Maintenance
+
+After every successful embedded OSS/local ingestion, call `table.optimize()`.
+Do not add this to LanceDB Enterprise/Cloud remote table code; remote compaction
+and cleanup are handled automatically based on the Enterprise cluster
+configuration.
+
+Why local maintenance is needed:
+
+- Frequent writes can create many small fragments. Queries then need to scan across more files, which can increase latency.
+- Updates, deletes, and appends create new table versions. Old versions are retained for time travel and rollback, which can grow disk usage.
+- Indexes may have newly added rows that are not yet fully optimized into the index structure.
+
+For local/OSS tables, run `optimize()` after the final successful ingestion
+write. Also run it after later batches of update/delete operations or on a
+regular maintenance schedule:
+
+```typescript
+await table.optimize();
+```
+
+If the user wants more aggressive local disk cleanup, pass a shorter cleanup retention window:
+
+```typescript
+const olderThan = new Date(Date.now() - 24 * 60 * 60 * 1000);
+await table.optimize({ cleanupOlderThan: olderThan });
+```
+
+Do not use very short cleanup windows when the application depends on time travel, rollback, or old versions.
+
+## Diagnostics
+
+Before changing code or indexes, inspect:
+
+```typescript
+console.log(await table.search(queryVector).where("year > 2000").limit(10).analyzePlan());
+console.log(await table.indexStats("vector_idx"));
+```
+
+Look for high scan cost, missing indexes, fragmented data, and unindexed rows.
@@ -0,0 +1,135 @@
+#!/usr/bin/env python3
+"""Scan Python and TypeScript for likely unsafe LanceDB materialization."""
+
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+
+PY_FULL_TABLE = re.compile(r"\b\w+\.(to_pandas|to_arrow|to_polars)\s*\(")
+TS_TABLE_TO_ARROW = re.compile(r"\b\w+\.toArrow\s*\(")
+TS_QUERY_COLLECTOR = re.compile(r"\.query\s*\(\s*\)[\s\S]*?\.to(Array|Arrow)\s*\(")
+
+
+@dataclass
+class Finding:
+    path: Path
+    line: int
+    message: str
+    text: str
+
+
+def iter_files(paths: list[Path]) -> list[Path]:
+    files: list[Path] = []
+    for path in paths:
+        if path.is_dir():
+            files.extend(
+                p
+                for p in path.rglob("*")
+                if p.suffix in {".py", ".ts", ".tsx"} and "node_modules" not in p.parts
+            )
+        elif path.suffix in {".py", ".ts", ".tsx"}:
+            files.append(path)
+    return sorted(set(files))
+
+
+def line_number(text: str, offset: int) -> int:
+    return text.count("\n", 0, offset) + 1
+
+
+def scan_python(path: Path, text: str) -> list[Finding]:
+    findings: list[Finding] = []
+    for match in PY_FULL_TABLE.finditer(text):
+        line_start = text.rfind("\n", 0, match.start()) + 1
+        line_end = text.find("\n", match.start())
+        if line_end == -1:
+            line_end = len(text)
+        line = text[line_start:line_end].strip()
+        if ".search(" in line or ".query(" in line:
+            continue
+        findings.append(
+            Finding(
+                path,
+                line_number(text, match.start()),
+                f"Review Python `{match.group(1)}()` call; table-level materialization is not portable to remote tables.",
+                line,
+            )
+        )
+    return findings
+
+
+def statement_around(text: str, start: int, end: int) -> str:
+    before = max(text.rfind(";", 0, start), text.rfind("\n\n", 0, start))
+    after_candidates = [pos for pos in (text.find(";", end), text.find("\n\n", end)) if pos != -1]
+    after = min(after_candidates) if after_candidates else len(text)
+    return text[before + 1 : after].strip()
+
+
+def scan_typescript(path: Path, text: str) -> list[Finding]:
+    findings: list[Finding] = []
+    for match in TS_TABLE_TO_ARROW.finditer(text):
+        stmt = statement_around(text, match.start(), match.end())
+        if ".query(" in stmt or ".search(" in stmt:
+            continue
+        findings.append(
+            Finding(
+                path,
+                line_number(text, match.start()),
+                "Review TypeScript `table.toArrow()`-style call; table-level materialization is not portable for large/remote tables.",
+                stmt.splitlines()[0].strip(),
+            )
+        )
+
+    for match in TS_QUERY_COLLECTOR.finditer(text):
+        stmt = statement_around(text, match.start(), match.end())
+        if ".limit(" in stmt:
+            continue
+        findings.append(
+            Finding(
+                path,
+                line_number(text, match.start()),
+                "Review unbounded TypeScript query collection; add `limit()` or stream batches.",
+                stmt.splitlines()[0].strip(),
+            )
+        )
+    return findings
+
+
+def scan_file(path: Path) -> list[Finding]:
+    text = path.read_text(encoding="utf-8", errors="replace")
+    if path.suffix == ".py":
+        return scan_python(path, text)
+    if path.suffix in {".ts", ".tsx"}:
+        return scan_typescript(path, text)
+    return []
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("paths", nargs="+", type=Path)
+    parser.add_argument(
+        "--no-fail", action="store_true", help="Always exit 0 after reporting findings."
+    )
+    args = parser.parse_args()
+
+    findings: list[Finding] = []
+    for path in iter_files(args.paths):
+        findings.extend(scan_file(path))
+
+    for finding in findings:
+        print(f"{finding.path}:{finding.line}: {finding.message}")
+        print(f"  {finding.text}")
+
+    if findings:
+        print(
+            f"\n{len(findings)} finding(s). Review manually; bounded query result conversion may be OK."
+        )
+    return 0 if args.no_fail or not findings else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())
@@ -1,6 +1,6 @@
 [package]
 name = "lancedb-python"
-version = "0.38.0-beta.7"
+version = "0.38.0-beta.2"
 publish = false
 edition.workspace = true
 description = "Python bindings for LanceDB"
@@ -15,10 +15,10 @@ name = "_lancedb"
 crate-type = ["cdylib"]

 [dependencies]
-arrow = { workspace = true, features = ["pyarrow"] }
-async-trait.workspace = true
-bytes.workspace = true
-lancedb.workspace = true
+arrow = { version = "58.0.0", features = ["pyarrow"] }
+async-trait = "0.1"
+bytes = "1"
+lancedb = { path = "../rust/lancedb", default-features = false }
 datafusion-common.workspace = true
 lance-core.workspace = true
 lance-namespace.workspace = true
@@ -26,24 +26,25 @@ lance-namespace-impls.workspace = true
 lance-io.workspace = true
 env_logger.workspace = true
 log.workspace = true
-# Maturin enables extension-module mode for Python builds. Keeping it out of
-# Cargo features lets Rust unit tests link against libpython.
-pyo3 = { version = "0.28", features = ["abi3-py310", "chrono"] }
-chrono.workspace = true
+pyo3 = { version = "0.28", features = ["extension-module", "abi3-py310", "chrono"] }
+chrono = { version = "0.4", default-features = false, features = ["clock"] }
 pyo3-async-runtimes = { version = "0.28", features = [
    "attributes",
    "tokio-runtime",
 ] }
-pin-project.workspace = true
+pin-project = "1.1.5"
 futures.workspace = true
-serde.workspace = true
-serde_json.workspace = true
+serde = "1"
+serde_json = "1"
 snafu.workspace = true
-tokio.workspace = true
+tokio = { version = "1.40", features = ["sync", "rt-multi-thread"] }
 libc = "0.2"

 [build-dependencies]
-pyo3-build-config = { version = "0.28", features = ["abi3-py310"] }
+pyo3-build-config = { version = "0.28", features = [
+    "extension-module",
+    "abi3-py310",
+] }

 [features]
 default = ["remote", "lancedb/aws", "lancedb/gcs", "lancedb/azure", "lancedb/dynamodb", "lancedb/oss", "lancedb/huggingface", "lancedb/cos", "lancedb/goosefs", "lancedb/metrics-otel"]
@@ -38,25 +38,6 @@ Stable releases are created about every 2 weeks. For the latest features and bug
 pip install --pre --extra-index-url https://pypi.fury.io/lancedb/ lancedb
 ```

-### Threading in CPU-limited containers
-
-LanceDB uses separate pools for compute work and storage I/O. On a container with
-two visible CPUs, current releases intentionally use one compute worker by default;
-no manual configuration is needed. If every query logs an I/O core reservation
-warning on a two-CPU container, upgrade from LanceDB 0.21.1 or earlier.
-
-The two commonly tuned environment variables control different resources:
-
- `LANCE_CPU_THREADS` overrides the number of compute workers. One worker is the
-  appropriate setting for a two-CPU container when an explicit override is needed.
- `LANCE_IO_THREADS` controls concurrent storage operations, not reserved CPU
-  cores. Its default can be greater than the number of CPUs because I/O workers
-  spend much of their time waiting for storage.
-
-Keep the defaults unless measurements show that the workload benefits from an
-override. See the [Lance threading model](https://lance.org/guide/performance/#threading-model)
-for the current defaults and tuning guidance.
-
 ## Usage

 ### Basic Example
@@ -8,7 +8,7 @@ dependencies = [
    "overrides>=0.7; python_version<'3.12'",
    "packaging>=23.0",
    "pyarrow>=16",
-    "pydantic>=2.7.4,<3",
+    "pydantic>=1.10",
    "tqdm>=4.27.0",
    "lance-namespace>=0.3.2"
 ]
@@ -103,7 +103,7 @@ python-source = "python"
 module-name = "lancedb._lancedb"

 [build-system]
-requires = ["maturin>=1.9.4"]
+requires = ["maturin>=1.4"]
 build-backend = "maturin"

 [tool.ruff.lint]
@@ -22,22 +22,6 @@ from .remote.db import RemoteDBConnection
 from .expr import Expr, col, lit, func
 from .schema import blob, vector, BlobType
 from .job import AsyncJob, Job
-from .functions import (
-    FunctionArtifactRequest as FunctionArtifactRequest,
-    FunctionApplication as FunctionApplication,
-    FunctionBinding as FunctionBinding,
-    FunctionRegistrationRequest as FunctionRegistrationRequest,
-    FunctionVersion as FunctionVersion,
-    PythonRuntimeSpec as PythonRuntimeSpec,
-    RefreshColumnResult as RefreshColumnResult,
-    UdfDefinition as UdfDefinition,
-    udf as udf,
-)
-from .materialized_view import (
-    AsyncMaterializedView,
-    MaterializedView,
-    MaterializedViewDefinition,
-)
 from .table import AsyncTable, Table
 from .types import BaseTokenizerType
 from ._lancedb import Session
@@ -512,9 +496,6 @@ async def connect_async(


 __all__ = [
-    "AsyncMaterializedView",
-    "MaterializedView",
-    "MaterializedViewDefinition",
    "connect",
    "connect_async",
    "tokenize",
@@ -147,8 +147,6 @@ class Connection(object):
        limit: Optional[int],
    ) -> list[str]: ...  # Deprecated: Use list_tables instead
    def job(self, job_id: str) -> Job: ...
-    async def create_function_async(self, request_json: str) -> Job: ...
-    async def get_function(self, name: str, version: str) -> str: ...
    async def list_jobs(self) -> List[JobInfo]: ...
    async def get_job(self, job_id: str) -> Optional[JobDescription]: ...
    async def cancel_job(self, job_id: str) -> bool: ...
@@ -197,15 +195,6 @@ class Connection(object):
        cur_namespace_path: Optional[List[str]] = None,
        new_namespace_path: Optional[List[str]] = None,
    ) -> None: ...
-    async def create_materialized_view(
-        self,
-        name: str,
-        source: str,
-        projections: Optional[List[Tuple[str, str]]] = None,
-        filter: Optional[str] = None,
-        limit: Optional[int] = None,
-    ) -> Table: ...
-    async def list_materialized_views(self) -> List[str]: ...
    async def drop_table(
        self, name: str, namespace_path: Optional[List[str]] = None
    ) -> None: ...
@@ -234,7 +223,7 @@ class Job:
    @property
    def id(self) -> Optional[str]: ...
    async def status(self) -> str: ...
-    async def wait(self) -> Optional[str]: ...
+    async def wait(self) -> None: ...
    async def cancel(self) -> None: ...

 class JobInfo:
@@ -352,14 +341,8 @@ class Table:
    async def add_computed_columns(
        self, columns: list[tuple[str, str]]
    ) -> AddColumnsResult: ...
-    async def add_function_columns(
-        self, application_json: str, output_name: Optional[str]
-    ) -> AddColumnsResult: ...
    async def refresh_column(self, column: str) -> RefreshColumnResult: ...
    async def refresh_column_async(self, column: str) -> Job: ...
-    async def refresh_materialized_view(
-        self, full: bool = False, source_version: Optional[int] = None
-    ) -> RefreshMaterializedViewResult: ...
    async def add_columns_with_schema(self, schema: pa.Schema) -> AddColumnsResult: ...
    async def alter_columns(
        self, columns: list[dict[str, Any]]
@@ -425,7 +408,7 @@ class Branches:
    async def checkout(self, name: str, version: Optional[int] = None) -> Table: ...
    async def delete(self, name: str) -> None: ...
    async def diff(self, from_branch: str) -> Dict[str, Any]: ...
-    async def cherry_pick(
+    async def merge(
        self, from_branch: str, dry_run: bool = False
    ) -> Dict[str, Any]: ...

@@ -709,12 +692,6 @@ class RefreshColumnResult:
    rows_filled: int
    version: int

-class RefreshMaterializedViewResult:
-    mode: str
-    rows_written: int
-    source_version: int
-    version: int
-
 class AlterColumnsResult:
    version: int

@@ -45,14 +45,7 @@ from lance_namespace.errors import NamespaceNotEmptyError, TableNotFoundError

 from . import __version__
 from ._lancedb import connect as lancedb_connect  # type: ignore
-from .functions import FunctionVersion, UdfDefinition
-from .job import AsyncJob, Job, _typed_job
-from .materialized_view import (
-    AsyncMaterializedView,
-    MaterializedView,
-    SelectArg,
-    normalize_select,
-)
+from .job import AsyncJob, Job
 from .table import (
    AsyncTable,
    LanceTable,
@@ -516,70 +509,6 @@ class DBConnection(EnforceOverrides):
        """
        raise NotImplementedError

-    def create_materialized_view(
-        self,
-        name: str,
-        source: str,
-        *,
-        select: SelectArg = None,
-        where: Optional[str] = None,
-        limit: Optional[int] = None,
-    ) -> 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 source table must have stable row ids (create it with the
-        ``new_table_enable_stable_row_ids`` storage option): they keep the
-        view's provenance valid across source compactions, and cannot be
-        enabled after a table exists.
-
-        Parameters
-        ----------
-        name: str
-            The name of the view.
-        source: str
-            The name of the source table, in this database.
-        select: list or dict, optional
-            The view's columns: column names, ``(alias, SQL expression)``
-            pairs, or a dict of the same. Omitting it selects every source
-            column, expanded against the source schema at creation time.
-        where: str, optional
-            SQL predicate; only matching source rows appear in the view.
-        limit: int, optional
-            Cap the view at this many rows, in materialization order.
-
-        Returns
-        -------
-        MaterializedView
-        """
-        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``.
-
-        Raises ``ValueError`` if the table exists but is not a materialized
-        view.
-        """
-        raise NotImplementedError(
-            "materialized views are not supported on this connection type"
-        )
-
-    def list_materialized_views(self) -> List[str]:
-        """The names of the materialized views in this database.
-
-        Found by reading every table's schema, so this costs an open per
-        table.
-        """
-        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.

@@ -687,31 +616,6 @@ 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.
-
-        This is the blocking counterpart of :meth:`create_function_async`.
-        Local connections raise ``NotImplementedError``.
-        """
-        return self.create_function_async(definition).wait()
-
-    def create_function_async(self, definition: UdfDefinition) -> Job[FunctionVersion]:
-        """Register a scalar Python UDF through the remote Function catalog.
-
-        Submission returns a typed job. The immutable Function version becomes
-        available only when :meth:`Job.wait` succeeds. Local connections raise
-        ``NotImplementedError``.
-        """
-        raise NotImplementedError(
-            "Function catalog operations are not supported for this connection type"
-        )
-
-    def get_function(self, name: str, *, version: str) -> FunctionVersion:
-        """Open one exact immutable Function version from the remote catalog."""
-        raise NotImplementedError(
-            "Function catalog operations are not supported for this connection type"
-        )
-
    def job(self, job_id: str) -> Job:
        """A [Job][lancedb.job.Job] handle for a server-side job by id.

@@ -1206,58 +1110,6 @@ class LanceDBConnection(DBConnection):
            tbl.checkout(version)
        return tbl

-    @override
-    def create_materialized_view(
-        self,
-        name: str,
-        source: str,
-        *,
-        select: SelectArg = None,
-        where: Optional[str] = None,
-        limit: Optional[int] = None,
-    ) -> MaterializedView:
-        """Define a materialized view named ``name`` over the table ``source``.
-        See
-        [DBConnection.create_materialized_view][lancedb.DBConnection.create_materialized_view].
-
-        Examples
-        --------
-        >>> import lancedb
-        >>> db = lancedb.connect(
-        ...     "./.lancedb",
-        ...     storage_options={"new_table_enable_stable_row_ids": "true"},
-        ... )
-        >>> data = [{"name": "ada", "age": 36}, {"name": "kid", "age": 7}]
-        >>> table = db.create_table("people", data)
-        >>> view = db.create_materialized_view(
-        ...     "adults",
-        ...     "people",
-        ...     select=["name", ("shout", "upper(name)")],
-        ...     where="age >= 18",
-        ... )
-        >>> result = view.refresh()
-        >>> result.rows_written
-        1
-        """
-        LOOP.run(
-            self._conn.create_materialized_view(
-                name, source, select=select, where=where, limit=limit
-            )
-        )
-        return MaterializedView(self.open_table(name))
-
-    @override
-    def open_materialized_view(self, name: str) -> MaterializedView:
-        """Open the materialized view named ``name``."""
-        view = MaterializedView(self.open_table(name))
-        view.definition
-        return view
-
-    @override
-    def list_materialized_views(self) -> List[str]:
-        """The names of the materialized views in this database."""
-        return LOOP.run(self._conn.list_materialized_views())
-
    def clone_table(
        self,
        target_table_name: str,
@@ -1404,15 +1256,6 @@ class LanceDBConnection(DBConnection):
        """
        return Job(self._conn.job(job_id))

-    @override
-    def create_function_async(self, definition: UdfDefinition) -> Job[FunctionVersion]:
-        job = LOOP.run(self._conn.create_function_async(definition))
-        return Job(job)
-
-    @override
-    def get_function(self, name: str, *, version: str) -> FunctionVersion:
-        return LOOP.run(self._conn.get_function(name, version=version))
-
    @override
    def list_jobs(self) -> List[JobInfo]:
        """List server-side jobs across the database's tables."""
@@ -2028,50 +1871,6 @@ class AsyncConnection(object):
            await tbl.checkout(version)
        return tbl

-    async def create_materialized_view(
-        self,
-        name: str,
-        source: str,
-        *,
-        select: SelectArg = None,
-        where: Optional[str] = None,
-        limit: Optional[int] = None,
-    ) -> AsyncMaterializedView:
-        """Define a materialized view named ``name`` over the table ``source``.
-        See
-        [DBConnection.create_materialized_view][lancedb.DBConnection.create_materialized_view].
-        """
-        inner = await self._inner.create_materialized_view(
-            name,
-            source,
-            projections=normalize_select(select),
-            filter=where,
-            limit=limit,
-        )
-        return AsyncMaterializedView(AsyncTable(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
-
-    async def list_materialized_views(self) -> List[str]:
-        """The names of the materialized views in this database.
-
-        Found by reading every table's schema, so this costs an open per
-        table.
-        """
-        return await self._inner.list_materialized_views()
-
    async def clone_table(
        self,
        target_table_name: str,
@@ -2224,25 +2023,6 @@ class AsyncConnection(object):
        """
        return AsyncJob(self._inner.job(job_id))

-    async def create_function_async(
-        self, definition: UdfDefinition
-    ) -> AsyncJob[FunctionVersion]:
-        """Register a scalar Python UDF through the remote Function catalog.
-
-        The returned typed job resolves to the immutable Function version.
-        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()
-        )
-        return _typed_job(inner, FunctionVersion.from_json)
-
-    async def get_function(self, name: str, *, version: str) -> FunctionVersion:
-        """Open one exact immutable Function version from the remote catalog."""
-        return FunctionVersion.from_json(await self._inner.get_function(name, version))
-
    async def list_jobs(self) -> List[JobInfo]:
        """List server-side jobs across the database's tables."""
        return await self._inner.list_jobs()
@@ -26,6 +26,7 @@ class EmbeddingFunction(BaseModel, ABC):
    3. ndims() which returns the number of dimensions of the vector column
    """

+    __slots__ = ("__weakref__",)  # pydantic 1.x compatibility
    max_retries: int = (
        7  # Setting 0 disables retires. Maybe this should not be enabled by default,
    )
@@ -7,7 +7,8 @@ from functools import cached_property
 from typing import List, Union

 import numpy as np
-from pydantic import ConfigDict
+
+from lancedb.pydantic import PYDANTIC_VERSION

 from ..util import attempt_import_or_raise
 from .base import TextEmbeddingFunction
@@ -66,7 +67,13 @@ class BedRockText(TextEmbeddingFunction):
    source_input_type: str = "search_document"
    query_input_type: str = "search_query"

-    model_config = ConfigDict(ignored_types=(cached_property,))
+    if PYDANTIC_VERSION.major < 2:  # Pydantic 1.x compat
+
+        class Config:
+            keep_untouched = (cached_property,)
+    else:
+        model_config = dict()
+        model_config["ignored_types"] = (cached_property,)

    def ndims(self):
        # return len(self._generate_embedding("test"))
@@ -7,7 +7,8 @@ from functools import cached_property
 from typing import List, Optional, Union

 import numpy as np
-from pydantic import ConfigDict
+
+from lancedb.pydantic import PYDANTIC_VERSION

 from ..util import attempt_import_or_raise
 from .base import TextEmbeddingFunction
@@ -86,7 +87,13 @@ class GeminiText(TextEmbeddingFunction):
    query_task_type: str = "retrieval_query"
    source_task_type: str = "retrieval_document"

-    model_config = ConfigDict(ignored_types=(cached_property,))
+    if PYDANTIC_VERSION.major < 2:  # Pydantic 1.x compat
+
+        class Config:
+            keep_untouched = (cached_property,)
+    else:
+        model_config = dict()
+        model_config["ignored_types"] = (cached_property,)

    def ndims(self):
        if self.dim:
@@ -7,13 +7,14 @@ from typing import List, Union

 import numpy as np
 import pyarrow as pa
-from pydantic import ConfigDict

 from ..util import attempt_import_or_raise
 from .base import EmbeddingFunction
 from .registry import register
 from .utils import AUDIO, IMAGES, TEXT

+from lancedb.pydantic import PYDANTIC_VERSION
+

@register("imagebind")
 class ImageBindEmbeddings(EmbeddingFunction):
@@ -30,7 +31,13 @@ class ImageBindEmbeddings(EmbeddingFunction):
    device: str = "cpu"
    normalize: bool = False

-    model_config = ConfigDict(ignored_types=(cached_property,))
+    if PYDANTIC_VERSION.major < 2:  # Pydantic 1.x compat
+
+        class Config:
+            keep_untouched = (cached_property,)
+    else:
+        model_config = dict()
+        model_config["ignored_types"] = (cached_property,)

    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)
@@ -7,7 +7,8 @@ from typing import List, Any

 import numpy as np

-from pydantic import ConfigDict, PrivateAttr
+from pydantic import PrivateAttr
+from lancedb.pydantic import PYDANTIC_VERSION

 from ..util import attempt_import_or_raise
 from .base import EmbeddingFunction
@@ -58,7 +59,13 @@ class TransformersEmbeddingFunction(EmbeddingFunction):
        )
        self._model.to(self.device)

-    model_config = ConfigDict(ignored_types=(cached_property,))
+    if PYDANTIC_VERSION.major < 2:  # Pydantic 1.x compat
+
+        class Config:
+            keep_untouched = (cached_property,)
+    else:
+        model_config = dict()
+        model_config["ignored_types"] = (cached_property,)

    def ndims(self):
        self._ndims = self._model.config.hidden_size
--- a/Show More
+++ b/Show More
Author	SHA1	Message	Date
Will Jones	b7dbef971e	feat(remote): route list_tables by what the server serves `list_tables` asked for `/v2` unconditionally, which 404s against every server that is not a recent Phalanx -- including `RestAdapter`, the namespace spec's own reference implementation. The connection now asks `/v1/version` once, before its first listing, and keeps the one bit it needs: whether this server serves the `/v2` listing. Servers that do not keep the listing they have always served, which is correct and merely slower. The answer has to be known before the first page rather than learned from it. The two routes resume from different things, so a walk that started on one cannot finish on the other, and a walk that learned from its own first page would hand `/v2` a token `/v1` minted. What is cached is that bit, not the `ServerVersion` it came from. A server that sends no version header is indistinguishable from one running the oldest version we know of, so caching the version would let a stripped header switch off multivector, structural FTS, multipart write and blobs for the life of the connection. A missing header can only cost a listing its pushdown. `table_names` is untouched: it stays on `/v1`, where `page_token` is a table name to resume after that its callers build themselves.	2026-08-19 17:05:27 -07:00
Will Jones	71202dd3e6	chore: pin lance to the read_dir_page branch TEMPORARY. `ObjectStore::read_dir_page` is not in a lance release yet, so the lance crates point at lance-format/lance#8606 cherry-picked onto the v11.0.0-beta.2 tag. Put the tag back once that PR has merged and shipped. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>	2026-08-19 13:32:34 -07:00
Will Jones	0ab435f2d7	fix(listing): paginate table listing instead of enumerating the database `ListingDatabase::list_tables` listed every table directory under the database prefix before applying `limit` and `page_token`. The cost of a request was set by the size of the database rather than the size of the page, so listing one table out of ten thousand took ten S3 round trips instead of one. List through `ObjectStore::read_dir_page`, which pushes the resume position and the page size into the store's list request. Stores with no paginated list API list the level in full and page it locally, which is what every store did before. Children that are not tables leave a page short of its limit, and one page is one request, so the listing asks again until the page is full or the database runs out. Two behaviour changes come with it: - `page_token` is opaque. It was a table name; it is now whatever resumes the store the database sits on, which for S3, GCS and Azure is a continuation token. Callers hand it back and do not construct or interpret one. Nothing validates it, so a token a caller invents resumes from the wrong place rather than failing. - Tables are reported in the order the store lists directories, which differs from sorting by name only between a name and one that extends it: `users-archive` now precedes `users`, because the `-` of `users-archive.lance` sorts below the `.` of `users.lance`. Pagination cannot report an order other than the one it resumes in. `table_names` is left on the full listing it has today: its `start_after` is a table name, which cannot be pushed into a store that resumes from a continuation token, and it is deprecated. A pushed-down listing does not pass through `WrappingObjectStore::wrap`, so every wrapper here says whether the pushdown survives it: the mirroring wrapper keeps it, since only writes are mirrored, and the test IO tracker gives it up rather than let a listing go around the counter. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>	2026-08-19 13:30:26 -07:00
Will Jones	fcc6a89b92	feat: builder API for list_tables, deprecate table_names `Connection::list_tables` took a `lance_namespace::models::ListTablesRequest` directly, so its generated shape -- including `identity`, `context` and `include_declared`, none of which lancedb reads -- was part of the public API, and Node had no binding at all. Replaces it with a `ListTablesBuilder` carrying `page_token`, `limit` and `namespace`, matching every other operation on `Connection`. This is a breaking change for Rust callers. Node gains `listTables` with `ListTablesOptions` and `ListTablesResponse`; Python's public API is unchanged, since it already had `list_tables` everywhere. `table_names` and `TableNamesBuilder` are deprecated. Its `start_after` takes a table name rather than an opaque token, which cannot be pushed down into a store that resumes from a continuation token. Also fixes the page boundary in `ListingDatabase::list_tables`: the token was the first name of the next page while resuming skips names at or before the token, so one table was dropped per boundary. Walking `[a, b, c, d, e]` with a limit of 2 returned `[a, b, d, e]`. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>	2026-08-19 13:28:26 -07:00