feat(secrets): address Secrets by namespace path

A binding names a Secret by its parts -- `{name, namespace_path}` -- rather than by one string that has to be parsed back apart. A joined id needs a delimiter, and a delimiter has to be excluded from every name and every segment forever, agreed on by both sides, and re-agreed each time either grows a new way to be configured. `ClientConfig.id_delimiter` is exactly that: it already governs table identifiers and is advertised on every request, so an id joined on a fixed `$` would contradict a delimiter the same request declares. Naming the parts settles all of it at the cost of one object. Nothing is parsed, so nothing can parse two ways; the charset is the service's storage rule rather than a delimiter's shadow; and the Secret verbs already send `namespace_path` as a field, so the binding now matches them instead of being the one place that flattens. A root binding omits the path entirely, so its wire shape is byte-identical to one written before namespaces existed. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01UfmeJ533rQDnPBkMtjerV6
fix(secrets): admit periods in Secret names and namespace segments
2026-09-11 15:52:17 +00:00 · 2026-09-11 15:38:12 +00:00 · 2026-09-11 15:32:05 +00:00 · 2026-09-09 17:33:59 +00:00 · 2026-09-09 16:59:40 +00:00 · 2026-09-09 16:59:40 +00:00
94 changed files with 8319 additions and 1069 deletions
@@ -1,5 +1,5 @@
 [tool.bumpversion]
-current_version = "0.39.0-beta.1"
+current_version = "0.39.0-beta.4"
 parse = """(?x)
    (?P<major>0|[1-9]\\d*)\\.
    (?P<minor>0|[1-9]\\d*)\\.
@@ -232,7 +232,10 @@ jobs:
          ALL_FEATURES=`cargo metadata --format-version=1 --no-deps \
            | jq -r '.packages[] | .features | keys | .[]' \
            | grep -v s3-test | sort | uniq | paste -s -d "," -`
-          cargo test --profile ci --features $ALL_FEATURES --locked
+          # Run doctests before test binaries fill the runner disk. Examples are
+          # already built by the Linux job, so avoid retaining them here.
+          cargo test --profile ci --features $ALL_FEATURES --locked --doc
+          cargo test --profile ci --features $ALL_FEATURES --locked --lib --tests

  windows:
    strategy:
@@ -332,6 +332,34 @@ dependencies = [
 "num-traits",
 ]

+[[package]]
+name = "arrow-flight"
+version = "58.4.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b2dbe34824c639e43136af8f106992792ab456540d54b880bc320a3192502d2e"
+dependencies = [
+ "arrow-arith",
+ "arrow-array",
+ "arrow-buffer",
+ "arrow-cast",
+ "arrow-data",
+ "arrow-ipc",
+ "arrow-ord",
+ "arrow-row",
+ "arrow-schema",
+ "arrow-select",
+ "arrow-string",
+ "base64 0.22.1",
+ "bytes",
+ "futures",
+ "once_cell",
+ "paste",
+ "prost",
+ "prost-types",
+ "tonic",
+ "tonic-prost",
+]
+
 [[package]]
 name = "arrow-ipc"
 version = "58.4.0"
@@ -1129,7 +1157,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "edca88bc138befd0323b20752846e6587272d3b03b0343c8ea28a6f819e6e71f"
 dependencies = [
 "async-trait",
- "axum-core",
+ "axum-core 0.4.5",
 "bytes",
 "futures-util",
 "http 1.5.0",
@@ -1138,7 +1166,7 @@ dependencies = [
 "hyper 1.9.0",
 "hyper-util",
 "itoa",
- "matchit",
+ "matchit 0.7.3",
 "memchr",
 "mime",
 "percent-encoding",
@@ -1156,6 +1184,31 @@ dependencies = [
 "tracing",
 ]

+[[package]]
+name = "axum"
+version = "0.8.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "31b698c5f9a010f6573133b09e0de5408834d0c82f8d7475a89fc1867a71cd90"
+dependencies = [
+ "axum-core 0.5.6",
+ "bytes",
+ "futures-util",
+ "http 1.5.0",
+ "http-body 1.1.0",
+ "http-body-util",
+ "itoa",
+ "matchit 0.8.4",
+ "memchr",
+ "mime",
+ "percent-encoding",
+ "pin-project-lite",
+ "serde_core",
+ "sync_wrapper",
+ "tower",
+ "tower-layer",
+ "tower-service",
+]
+
 [[package]]
 name = "axum-core"
 version = "0.4.5"
@@ -1177,6 +1230,24 @@ dependencies = [
 "tracing",
 ]

+[[package]]
+name = "axum-core"
+version = "0.5.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "08c78f31d7b1291f7ee735c1c6780ccde7785daae9a9206026862dab7d8792d1"
+dependencies = [
+ "bytes",
+ "futures-core",
+ "http 1.5.0",
+ "http-body 1.1.0",
+ "http-body-util",
+ "mime",
+ "pin-project-lite",
+ "sync_wrapper",
+ "tower-layer",
+ "tower-service",
+]
+
 [[package]]
 name = "backoff"
 version = "0.4.0"
@@ -3455,8 +3526,8 @@ checksum = "42703706b716c37f96a77aea830392ad231f44c9e9a67872fa5548707e11b11c"

 [[package]]
 name = "fsst"
-version = "12.0.0-beta.11"
-source = "git+https://github.com/lance-format/lance.git?tag=v12.0.0-beta.11#4a0e26895729feb86d0cb9c09d551bfd619c6472"
+version = "12.0.0-beta.14"
+source = "git+https://github.com/lance-format/lance.git?tag=v12.0.0-beta.14#a8a101774a1c9647065cc60137094feadbe55296"
 dependencies = [
 "arrow-array",
 "rand 0.9.5",
@@ -4815,8 +4886,8 @@ checksum = "e037a2e1d8d5fdbd49b16a4ea09d5d6401c1f29eca5ff29d03d3824dba16256a"

 [[package]]
 name = "lance"
-version = "12.0.0-beta.11"
-source = "git+https://github.com/lance-format/lance.git?tag=v12.0.0-beta.11#4a0e26895729feb86d0cb9c09d551bfd619c6472"
+version = "12.0.0-beta.14"
+source = "git+https://github.com/lance-format/lance.git?tag=v12.0.0-beta.14#a8a101774a1c9647065cc60137094feadbe55296"
 dependencies = [
 "arc-swap",
 "arrow",
@@ -4888,8 +4959,8 @@ dependencies = [

 [[package]]
 name = "lance-arrow"
-version = "12.0.0-beta.11"
-source = "git+https://github.com/lance-format/lance.git?tag=v12.0.0-beta.11#4a0e26895729feb86d0cb9c09d551bfd619c6472"
+version = "12.0.0-beta.14"
+source = "git+https://github.com/lance-format/lance.git?tag=v12.0.0-beta.14#a8a101774a1c9647065cc60137094feadbe55296"
 dependencies = [
 "arrow-array",
 "arrow-buffer",
@@ -4911,7 +4982,7 @@ dependencies = [
 [[package]]
 name = "lance-arrow-scalar"
 version = "58.0.0"
-source = "git+https://github.com/lance-format/lance.git?tag=v12.0.0-beta.11#4a0e26895729feb86d0cb9c09d551bfd619c6472"
+source = "git+https://github.com/lance-format/lance.git?tag=v12.0.0-beta.14#a8a101774a1c9647065cc60137094feadbe55296"
 dependencies = [
 "arrow-array",
 "arrow-buffer",
@@ -4925,7 +4996,7 @@ dependencies = [
 [[package]]
 name = "lance-arrow-stats"
 version = "58.0.0"
-source = "git+https://github.com/lance-format/lance.git?tag=v12.0.0-beta.11#4a0e26895729feb86d0cb9c09d551bfd619c6472"
+source = "git+https://github.com/lance-format/lance.git?tag=v12.0.0-beta.14#a8a101774a1c9647065cc60137094feadbe55296"
 dependencies = [
 "arrow-array",
 "arrow-schema",
@@ -4934,8 +5005,8 @@ dependencies = [

 [[package]]
 name = "lance-bitpacking"
-version = "12.0.0-beta.11"
-source = "git+https://github.com/lance-format/lance.git?tag=v12.0.0-beta.11#4a0e26895729feb86d0cb9c09d551bfd619c6472"
+version = "12.0.0-beta.14"
+source = "git+https://github.com/lance-format/lance.git?tag=v12.0.0-beta.14#a8a101774a1c9647065cc60137094feadbe55296"
 dependencies = [
 "arrayref",
 "crunchy",
@@ -4945,8 +5016,8 @@ dependencies = [

 [[package]]
 name = "lance-core"
-version = "12.0.0-beta.11"
-source = "git+https://github.com/lance-format/lance.git?tag=v12.0.0-beta.11#4a0e26895729feb86d0cb9c09d551bfd619c6472"
+version = "12.0.0-beta.14"
+source = "git+https://github.com/lance-format/lance.git?tag=v12.0.0-beta.14#a8a101774a1c9647065cc60137094feadbe55296"
 dependencies = [
 "arrow-array",
 "arrow-buffer",
@@ -4983,8 +5054,8 @@ dependencies = [

 [[package]]
 name = "lance-datafusion"
-version = "12.0.0-beta.11"
-source = "git+https://github.com/lance-format/lance.git?tag=v12.0.0-beta.11#4a0e26895729feb86d0cb9c09d551bfd619c6472"
+version = "12.0.0-beta.14"
+source = "git+https://github.com/lance-format/lance.git?tag=v12.0.0-beta.14#a8a101774a1c9647065cc60137094feadbe55296"
 dependencies = [
 "arrow",
 "arrow-array",
@@ -5014,8 +5085,8 @@ dependencies = [

 [[package]]
 name = "lance-datagen"
-version = "12.0.0-beta.11"
-source = "git+https://github.com/lance-format/lance.git?tag=v12.0.0-beta.11#4a0e26895729feb86d0cb9c09d551bfd619c6472"
+version = "12.0.0-beta.14"
+source = "git+https://github.com/lance-format/lance.git?tag=v12.0.0-beta.14#a8a101774a1c9647065cc60137094feadbe55296"
 dependencies = [
 "arrow",
 "arrow-array",
@@ -5032,8 +5103,8 @@ dependencies = [

 [[package]]
 name = "lance-derive"
-version = "12.0.0-beta.11"
-source = "git+https://github.com/lance-format/lance.git?tag=v12.0.0-beta.11#4a0e26895729feb86d0cb9c09d551bfd619c6472"
+version = "12.0.0-beta.14"
+source = "git+https://github.com/lance-format/lance.git?tag=v12.0.0-beta.14#a8a101774a1c9647065cc60137094feadbe55296"
 dependencies = [
 "proc-macro2",
 "quote",
@@ -5042,8 +5113,8 @@ dependencies = [

 [[package]]
 name = "lance-encoding"
-version = "12.0.0-beta.11"
-source = "git+https://github.com/lance-format/lance.git?tag=v12.0.0-beta.11#4a0e26895729feb86d0cb9c09d551bfd619c6472"
+version = "12.0.0-beta.14"
+source = "git+https://github.com/lance-format/lance.git?tag=v12.0.0-beta.14#a8a101774a1c9647065cc60137094feadbe55296"
 dependencies = [
 "arrow-arith",
 "arrow-array",
@@ -5076,8 +5147,8 @@ dependencies = [

 [[package]]
 name = "lance-file"
-version = "12.0.0-beta.11"
-source = "git+https://github.com/lance-format/lance.git?tag=v12.0.0-beta.11#4a0e26895729feb86d0cb9c09d551bfd619c6472"
+version = "12.0.0-beta.14"
+source = "git+https://github.com/lance-format/lance.git?tag=v12.0.0-beta.14#a8a101774a1c9647065cc60137094feadbe55296"
 dependencies = [
 "arrow-arith",
 "arrow-array",
@@ -5108,8 +5179,8 @@ dependencies = [

 [[package]]
 name = "lance-index"
-version = "12.0.0-beta.11"
-source = "git+https://github.com/lance-format/lance.git?tag=v12.0.0-beta.11#4a0e26895729feb86d0cb9c09d551bfd619c6472"
+version = "12.0.0-beta.14"
+source = "git+https://github.com/lance-format/lance.git?tag=v12.0.0-beta.14#a8a101774a1c9647065cc60137094feadbe55296"
 dependencies = [
 "arc-swap",
 "arrow",
@@ -5173,8 +5244,8 @@ dependencies = [

 [[package]]
 name = "lance-index-core"
-version = "12.0.0-beta.11"
-source = "git+https://github.com/lance-format/lance.git?tag=v12.0.0-beta.11#4a0e26895729feb86d0cb9c09d551bfd619c6472"
+version = "12.0.0-beta.14"
+source = "git+https://github.com/lance-format/lance.git?tag=v12.0.0-beta.14#a8a101774a1c9647065cc60137094feadbe55296"
 dependencies = [
 "arrow-array",
 "arrow-schema",
@@ -5196,8 +5267,8 @@ dependencies = [

 [[package]]
 name = "lance-io"
-version = "12.0.0-beta.11"
-source = "git+https://github.com/lance-format/lance.git?tag=v12.0.0-beta.11#4a0e26895729feb86d0cb9c09d551bfd619c6472"
+version = "12.0.0-beta.14"
+source = "git+https://github.com/lance-format/lance.git?tag=v12.0.0-beta.14#a8a101774a1c9647065cc60137094feadbe55296"
 dependencies = [
 "arrow",
 "arrow-array",
@@ -5237,8 +5308,8 @@ dependencies = [

 [[package]]
 name = "lance-linalg"
-version = "12.0.0-beta.11"
-source = "git+https://github.com/lance-format/lance.git?tag=v12.0.0-beta.11#4a0e26895729feb86d0cb9c09d551bfd619c6472"
+version = "12.0.0-beta.14"
+source = "git+https://github.com/lance-format/lance.git?tag=v12.0.0-beta.14#a8a101774a1c9647065cc60137094feadbe55296"
 dependencies = [
 "arrow-array",
 "arrow-schema",
@@ -5252,27 +5323,29 @@ dependencies = [

 [[package]]
 name = "lance-namespace"
-version = "12.0.0-beta.11"
-source = "git+https://github.com/lance-format/lance.git?tag=v12.0.0-beta.11#4a0e26895729feb86d0cb9c09d551bfd619c6472"
+version = "12.0.0-beta.14"
+source = "git+https://github.com/lance-format/lance.git?tag=v12.0.0-beta.14#a8a101774a1c9647065cc60137094feadbe55296"
 dependencies = [
 "arrow",
 "async-trait",
 "bytes",
 "lance-core",
 "lance-namespace-reqwest-client",
+ "serde",
+ "serde_json",
 "snafu 0.9.0",
 ]

 [[package]]
 name = "lance-namespace-impls"
-version = "12.0.0-beta.11"
-source = "git+https://github.com/lance-format/lance.git?tag=v12.0.0-beta.11#4a0e26895729feb86d0cb9c09d551bfd619c6472"
+version = "12.0.0-beta.14"
+source = "git+https://github.com/lance-format/lance.git?tag=v12.0.0-beta.14#a8a101774a1c9647065cc60137094feadbe55296"
 dependencies = [
 "arrow",
 "arrow-ipc",
 "arrow-schema",
 "async-trait",
- "axum",
+ "axum 0.7.9",
 "base64 0.22.1",
 "bytes",
 "chrono",
@@ -5305,9 +5378,9 @@ dependencies = [

 [[package]]
 name = "lance-namespace-reqwest-client"
-version = "0.11.1"
+version = "0.12.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "1d06b1fbb5d41f93bc652b61e2872af92e8a6c5f6b4ce8839a8ecfa05365d359"
+checksum = "d8d23e54b1634d5bbb434f8dd33dc3c05f6e58d876a9a27b3b4aef58ddbe11af"
 dependencies = [
 "reqwest 0.12.28",
 "serde",
@@ -5319,8 +5392,8 @@ dependencies = [

 [[package]]
 name = "lance-select"
-version = "12.0.0-beta.11"
-source = "git+https://github.com/lance-format/lance.git?tag=v12.0.0-beta.11#4a0e26895729feb86d0cb9c09d551bfd619c6472"
+version = "12.0.0-beta.14"
+source = "git+https://github.com/lance-format/lance.git?tag=v12.0.0-beta.14#a8a101774a1c9647065cc60137094feadbe55296"
 dependencies = [
 "arrow-array",
 "arrow-buffer",
@@ -5334,8 +5407,8 @@ dependencies = [

 [[package]]
 name = "lance-table"
-version = "12.0.0-beta.11"
-source = "git+https://github.com/lance-format/lance.git?tag=v12.0.0-beta.11#4a0e26895729feb86d0cb9c09d551bfd619c6472"
+version = "12.0.0-beta.14"
+source = "git+https://github.com/lance-format/lance.git?tag=v12.0.0-beta.14#a8a101774a1c9647065cc60137094feadbe55296"
 dependencies = [
 "arrow",
 "arrow-array",
@@ -5375,8 +5448,8 @@ dependencies = [

 [[package]]
 name = "lance-testing"
-version = "12.0.0-beta.11"
-source = "git+https://github.com/lance-format/lance.git?tag=v12.0.0-beta.11#4a0e26895729feb86d0cb9c09d551bfd619c6472"
+version = "12.0.0-beta.14"
+source = "git+https://github.com/lance-format/lance.git?tag=v12.0.0-beta.14#a8a101774a1c9647065cc60137094feadbe55296"
 dependencies = [
 "arrow-array",
 "arrow-schema",
@@ -5389,8 +5462,8 @@ dependencies = [

 [[package]]
 name = "lance-tokenizer"
-version = "12.0.0-beta.11"
-source = "git+https://github.com/lance-format/lance.git?tag=v12.0.0-beta.11#4a0e26895729feb86d0cb9c09d551bfd619c6472"
+version = "12.0.0-beta.14"
+source = "git+https://github.com/lance-format/lance.git?tag=v12.0.0-beta.14#a8a101774a1c9647065cc60137094feadbe55296"
 dependencies = [
 "frostem",
 "icu_segmenter",
@@ -5403,7 +5476,7 @@ dependencies = [

 [[package]]
 name = "lancedb"
-version = "0.39.0-beta.1"
+version = "0.39.0-beta.4"
 dependencies = [
 "ahash",
 "anyhow",
@@ -5412,6 +5485,7 @@ dependencies = [
 "arrow-buffer",
 "arrow-cast",
 "arrow-data",
+ "arrow-flight",
 "arrow-ipc",
 "arrow-ord",
 "arrow-schema",
@@ -5467,6 +5541,7 @@ dependencies = [
 "polars",
 "polars-arrow",
 "pprof 0.14.1",
+ "prost",
 "rand 0.9.5",
 "random_word",
 "regex",
@@ -5483,6 +5558,7 @@ dependencies = [
 "test-log",
 "tokenizers",
 "tokio",
+ "tonic",
 "url",
 "urlencoding",
 "uuid",
@@ -5491,7 +5567,7 @@ dependencies = [

 [[package]]
 name = "lancedb-nodejs"
-version = "0.39.0-beta.1"
+version = "0.39.0-beta.4"
 dependencies = [
 "arrow-array",
 "arrow-buffer",
@@ -5516,7 +5592,7 @@ dependencies = [

 [[package]]
 name = "lancedb-python"
-version = "0.39.0-beta.1"
+version = "0.39.0-beta.4"
 dependencies = [
 "arrow",
 "async-trait",
@@ -5540,6 +5616,7 @@ dependencies = [
 "serde_json",
 "snafu 0.8.9",
 "tokio",
+ "uuid",
 ]

 [[package]]
@@ -5860,6 +5937,12 @@ version = "0.7.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "0e7465ac9959cc2b1404e8e2367b43684a6d13790fe23056cc8c6c5a6b7bcb94"

+[[package]]
+name = "matchit"
+version = "0.8.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "47e1ffaa40ddd1f3ed91f717a33c8c0ee23fff369e3aa8772b9605cc1d22f4c3"
+
 [[package]]
 name = "matrixmultiply"
 version = "0.3.10"
@@ -7735,6 +7818,7 @@ dependencies = [
 "pyo3-build-config",
 "pyo3-ffi",
 "pyo3-macros",
+ "uuid",
 ]

 [[package]]
@@ -10087,6 +10171,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "ac2a5518c70fa84342385732db33fb3f44bc4cc748936eb5833d2df34d6445ef"
 dependencies = [
 "async-trait",
+ "axum 0.8.9",
 "base64 0.22.1",
 "bytes",
 "h2 0.4.16",
@@ -10098,9 +10183,11 @@ dependencies = [
 "hyper-util",
 "percent-encoding",
 "pin-project",
+ "rustls-native-certs",
 "socket2 0.6.3",
 "sync_wrapper",
 "tokio",
+ "tokio-rustls 0.26.4",
 "tokio-stream",
 "tower",
 "tower-layer",
@@ -13,20 +13,20 @@ categories = ["database-implementations"]
 rust-version = "1.91.0"

 [workspace.dependencies]
-lance = { "version" = "=12.0.0-beta.11", default-features = false, "tag" = "v12.0.0-beta.11", "git" = "https://github.com/lance-format/lance.git" }
-lance-core = { "version" = "=12.0.0-beta.11", "tag" = "v12.0.0-beta.11", "git" = "https://github.com/lance-format/lance.git" }
-lance-datagen = { "version" = "=12.0.0-beta.11", "tag" = "v12.0.0-beta.11", "git" = "https://github.com/lance-format/lance.git" }
-lance-file = { "version" = "=12.0.0-beta.11", "tag" = "v12.0.0-beta.11", "git" = "https://github.com/lance-format/lance.git" }
-lance-io = { "version" = "=12.0.0-beta.11", default-features = false, "tag" = "v12.0.0-beta.11", "git" = "https://github.com/lance-format/lance.git" }
-lance-index = { "version" = "=12.0.0-beta.11", "tag" = "v12.0.0-beta.11", "git" = "https://github.com/lance-format/lance.git" }
-lance-linalg = { "version" = "=12.0.0-beta.11", "tag" = "v12.0.0-beta.11", "git" = "https://github.com/lance-format/lance.git" }
-lance-namespace = { "version" = "=12.0.0-beta.11", "tag" = "v12.0.0-beta.11", "git" = "https://github.com/lance-format/lance.git" }
-lance-namespace-impls = { "version" = "=12.0.0-beta.11", default-features = false, "tag" = "v12.0.0-beta.11", "git" = "https://github.com/lance-format/lance.git" }
-lance-table = { "version" = "=12.0.0-beta.11", "tag" = "v12.0.0-beta.11", "git" = "https://github.com/lance-format/lance.git" }
-lance-testing = { "version" = "=12.0.0-beta.11", "tag" = "v12.0.0-beta.11", "git" = "https://github.com/lance-format/lance.git" }
-lance-datafusion = { "version" = "=12.0.0-beta.11", "tag" = "v12.0.0-beta.11", "git" = "https://github.com/lance-format/lance.git" }
-lance-encoding = { "version" = "=12.0.0-beta.11", "tag" = "v12.0.0-beta.11", "git" = "https://github.com/lance-format/lance.git" }
-lance-arrow = { "version" = "=12.0.0-beta.11", "tag" = "v12.0.0-beta.11", "git" = "https://github.com/lance-format/lance.git" }
+lance = { "version" = "=12.0.0-beta.14", default-features = false, "tag" = "v12.0.0-beta.14", "git" = "https://github.com/lance-format/lance.git" }
+lance-core = { "version" = "=12.0.0-beta.14", "tag" = "v12.0.0-beta.14", "git" = "https://github.com/lance-format/lance.git" }
+lance-datagen = { "version" = "=12.0.0-beta.14", "tag" = "v12.0.0-beta.14", "git" = "https://github.com/lance-format/lance.git" }
+lance-file = { "version" = "=12.0.0-beta.14", "tag" = "v12.0.0-beta.14", "git" = "https://github.com/lance-format/lance.git" }
+lance-io = { "version" = "=12.0.0-beta.14", default-features = false, "tag" = "v12.0.0-beta.14", "git" = "https://github.com/lance-format/lance.git" }
+lance-index = { "version" = "=12.0.0-beta.14", "tag" = "v12.0.0-beta.14", "git" = "https://github.com/lance-format/lance.git" }
+lance-linalg = { "version" = "=12.0.0-beta.14", "tag" = "v12.0.0-beta.14", "git" = "https://github.com/lance-format/lance.git" }
+lance-namespace = { "version" = "=12.0.0-beta.14", "tag" = "v12.0.0-beta.14", "git" = "https://github.com/lance-format/lance.git" }
+lance-namespace-impls = { "version" = "=12.0.0-beta.14", default-features = false, "tag" = "v12.0.0-beta.14", "git" = "https://github.com/lance-format/lance.git" }
+lance-table = { "version" = "=12.0.0-beta.14", "tag" = "v12.0.0-beta.14", "git" = "https://github.com/lance-format/lance.git" }
+lance-testing = { "version" = "=12.0.0-beta.14", "tag" = "v12.0.0-beta.14", "git" = "https://github.com/lance-format/lance.git" }
+lance-datafusion = { "version" = "=12.0.0-beta.14", "tag" = "v12.0.0-beta.14", "git" = "https://github.com/lance-format/lance.git" }
+lance-encoding = { "version" = "=12.0.0-beta.14", "tag" = "v12.0.0-beta.14", "git" = "https://github.com/lance-format/lance.git" }
+lance-arrow = { "version" = "=12.0.0-beta.14", "tag" = "v12.0.0-beta.14", "git" = "https://github.com/lance-format/lance.git" }
 lancedb = { path = "rust/lancedb", default-features = false }
 ahash = "0.8"
 # Note that this one does not include pyarrow
@@ -39,6 +39,7 @@ arrow-ord = "58.0.0"
 arrow-schema = "58.0.0"
 arrow-select = "58.0.0"
 arrow-cast = "58.0.0"
+arrow-flight = { version = "58.0.0", features = ["flight-sql-experimental"] }
 async-trait = "0"
 bytes = "1"
 datafusion = { version = "54.0.0", default-features = false }
@@ -71,7 +72,8 @@ 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"] }
+tonic = { version = "0.14", features = ["tls-native-roots", "tls-ring"] }
+uuid = { version = "1.7.0", features = ["v4", "v7"] }
 chrono = { version = "0.4", default-features = false, features = ["clock"] }

 [profile.ci]
@@ -14,7 +14,7 @@ Add the following dependency to your `pom.xml`:
 <dependency>
    <groupId>com.lancedb</groupId>
    <artifactId>lancedb-core</artifactId>
-    <version>0.39.0-beta.1</version>
+    <version>0.39.0-beta.4</version>
 </dependency>
 ```

@@ -448,26 +448,6 @@ on the returned job to know when cleanup has finished.

 ***

-### getJob()
-
-```ts
-abstract getJob(jobId): Promise<null | JobDescription>
-```
-
-Describe a single server-side job by id.
-
-Resolves to `null` when the server has no such job.
-
-#### Parameters
-
-* **jobId**: `string`
-
-#### Returns
-
-`Promise`&lt;`null` \| [`JobDescription`](../interfaces/JobDescription.md)&gt;
-
-***
-
 ### isOpen()

 ```ts
@@ -482,48 +462,6 @@ Return true if the connection has not been closed

 ***

-### job()
-
-```ts
-abstract job(jobId): Job
-```
-
-A [Job](Job.md) handle for a server-side job by id.
-
-The handle is constructed without a server round trip; an unknown id
-surfaces when the handle is used. Dropping the handle has no effect on
-the job itself.
-
-#### Parameters
-
-* **jobId**: `string`
-
-#### Returns
-
-[`Job`](Job.md)
-
-***
-
-### jobHistory()
-
-```ts
-abstract jobHistory(jobId?): Promise<Table<any>>
-```
-
-The lifecycle event history of a server-side job, as an Arrow table.
-
-Lists history across all jobs when `jobId` is omitted.
-
-#### Parameters
-
-* **jobId?**: `string`
-
-#### Returns
-
-`Promise`&lt;`Table`&lt;`any`&gt;&gt;
-
-***
-
 ### listJobs()

 ```ts
@@ -648,6 +586,30 @@ A page of table names and an

 ***

+### openJob()
+
+```ts
+abstract openJob(jobId): Promise<Job>
+```
+
+Open a server-side job by id, returning a handle with its record already
+populated. Rejects when the server has no such job, the way
+[Connection.openTable](Connection.md#opentable) does for a missing table.
+
+The returned [Job](Job.md) answers for its own state, specification,
+result, failure and event history, so there is no separate
+connection-level call for any of them.
+
+#### Parameters
+
+* **jobId**: `string`
+
+#### Returns
+
+`Promise`&lt;[`Job`](Job.md)&gt;
+
+***
+
 ### openMaterializedView()

 ```ts
@@ -8,19 +8,46 @@

 A handle to an operation that may still be running.

-## Constructors
+The operation may already be complete when the handle is created.

-### new Job()
+The detail getters read what the handle last observed. Submitting an
+operation returns only a job id, so populating them eagerly would cost an
+extra round trip on every call:
+
+- [Job.refresh](Job.md#refresh) and [Job.status](Job.md#status) fetch the whole record.
+- [Job.wait](Job.md#wait) records the terminal state it establishes, but not the
+  rest of the record.
+- Everything is null until one of those runs.
+
+## Accessors
+
+### creationMs

 ```ts
-new Job(): Job
+get creationMs(): null | number
 ```

+When the job was created, in milliseconds since the epoch.
+
 #### Returns

-[`Job`](Job.md)
+`null` \| `number`

-## Accessors
+***
+
+### failure
+
+```ts
+get failure(): null | JobFailureInfo
+```
+
+Why the job failed, when it failed and the server reports a reason.
+
+#### Returns
+
+`null` \| [`JobFailureInfo`](../interfaces/JobFailureInfo.md)
+
+***

 ### id

@@ -28,8 +55,69 @@ new Job(): Job
 get id(): null | string
 ```

-Identifies the operation on the server that is running it. Operations
-that run in this process have no server id. The value is opaque.
+Identifies the operation on the server that is running it.
+
+Operations that run in this process have no server id. The value is
+opaque: parsing it or storing it to resume the job later is not supported.
+
+#### Returns
+
+`null` \| `string`
+
+***
+
+### jobType
+
+```ts
+get jobType(): null | string
+```
+
+The job's type, as the server names it. Null for an in-process job, which
+has no server-side record.
+
+#### Returns
+
+`null` \| `string`
+
+***
+
+### result
+
+```ts
+get result(): any
+```
+
+The job-type-specific terminal result. Null until the job succeeds, so a
+job that never terminates reports its progress through [Job.events](Job.md#events)
+instead.
+
+#### Returns
+
+`any`
+
+***
+
+### spec
+
+```ts
+get spec(): any
+```
+
+The job-type-specific specification it was submitted with.
+
+#### Returns
+
+`any`
+
+***
+
+### state
+
+```ts
+get state(): null | string
+```
+
+The last observed lifecycle state, without contacting the backend.

 #### Returns

@@ -51,18 +139,61 @@ Request cancellation. Cancelling a finished operation is a no-op.

 ***

+### events()
+
+```ts
+events(options?): Promise<Table<any>>
+```
+
+This job's recorded lifecycle events.
+
+Where the getters above report a terminal result only once the job reaches
+one, events are written as the job runs and outlive the workers that
+produced them. A distributed job records a `claim`/`claim_complete` pair
+per unit of work, each carrying `rows_processed`, so a job that never
+finishes still accounts for what it did.
+
+The server caps results at 1000 rows by default and 10,000 at most, and
+truncates without saying so, so pass `limit` for a job that emits an event
+per fragment. `filter` is a SQL-like expression over the `state`,
+`updated_by`, `emitted_from`, `emitted_by`, and `claim_entity` columns.
+
+#### Parameters
+
+* **options?**: [`JobEventsOptions`](../interfaces/JobEventsOptions.md)
+
+#### Returns
+
+`Promise`&lt;`Table`&lt;`any`&gt;&gt;
+
+***
+
+### refresh()
+
+```ts
+refresh(): Promise<void>
+```
+
+Ask the backend for this job's current state, and for a server-side job
+its full record, then cache it for the getters above.
+
+#### Returns
+
+`Promise`&lt;`void`&gt;
+
+***
+
 ### status()

 ```ts
 status(): Promise<string>
 ```

-The operation's current lifecycle state: "running", "finished",
-"failed", or "cancelled".
+The operation's current lifecycle state: "running", "finished", "failed",
+or "cancelled".

-A point snapshot; unlike [Job.wait](Job.md#wait) it does not block or reject
-on a terminal failure state. States a newer server reports that this
-client version does not know pass through as-is.
+A point snapshot; unlike [Job.wait](Job.md#wait) it does not block or reject on a
+terminal failure state. Also refreshes the getters above.

 #### Returns

@@ -70,6 +201,22 @@ client version does not know pass through as-is.

 ***

+### toString()
+
+```ts
+toString(): string
+```
+
+Every field the handle currently knows, one per line, with the JSON
+payloads indented -- a refresh job's spec and result are the point of
+printing it.
+
+#### Returns
+
+`string`
+
+***
+
 ### wait()

 ```ts
@@ -96,7 +96,7 @@
 - [IvfFlatOptions](interfaces/IvfFlatOptions.md)
 - [IvfPqOptions](interfaces/IvfPqOptions.md)
 - [IvfRqOptions](interfaces/IvfRqOptions.md)
- [JobDescription](interfaces/JobDescription.md)
+- [JobEventsOptions](interfaces/JobEventsOptions.md)
 - [JobFailureInfo](interfaces/JobFailureInfo.md)
 - [JobInfo](interfaces/JobInfo.md)
 - [ListNamespacesOptions](interfaces/ListNamespacesOptions.md)
@@ -50,7 +50,7 @@ If this is false, and another index already exists on the same columns
 and the same name, then an error will be returned.  This is true even if
 that index is out of date.

-The default is false
+The default is true

 ***

@@ -1,66 +0,0 @@
-[**@lancedb/lancedb**](../README.md) • **Docs**
-
-***
-
-[@lancedb/lancedb](../globals.md) / JobDescription
-
-# Interface: JobDescription
-
-A described job from `Connection.getJob`.
-
-## Properties
-
-### creationMs
-
-```ts
-creationMs: number;
-```
-
-When the job was created, in milliseconds since the epoch.
-
-***
-
-### failure?
-
-```ts
-optional failure: JobFailureInfo;
-```
-
-Why the job failed, when the job is failed and the server reports a
-reason.
-
-***
-
-### jobId
-
-```ts
-jobId: string;
-```
-
-***
-
-### jobType
-
-```ts
-jobType: string;
-```
-
-***
-
-### specJson?
-
-```ts
-optional specJson: string;
-```
-
-The job-type-specific specification as a JSON string, when present.
-
-***
-
-### state
-
-```ts
-state: string;
-```
-
-Lifecycle state: "running", "finished", "failed", or "cancelled".
@@ -0,0 +1,29 @@
+[**@lancedb/lancedb**](../README.md) • **Docs**
+
+***
+
+[@lancedb/lancedb](../globals.md) / JobEventsOptions
+
+# Interface: JobEventsOptions
+
+Which of a job's events [Job.events](../classes/Job.md#events) returns.
+
+## Properties
+
+### filter?
+
+```ts
+optional filter: string;
+```
+
+SQL-like filter over the event columns.
+
+***
+
+### limit?
+
+```ts
+optional limit: number;
+```
+
+Maximum event rows to return, up to the server maximum of 10,000.
@@ -26,7 +26,7 @@ When the job was created, in milliseconds since the epoch.
 jobId: string;
 ```

-The job id -- what `Connection.getJob` and `Connection.cancelJob`
+The job id -- what `Connection.openJob` and `Connection.cancelJob`
 accept.

 ***
@@ -28,6 +28,59 @@ is also an [asynchronous API client](#connections-asynchronous).

 ::: lancedb.Session

+## Remote SQL
+
+Submit SQL against a remote LanceDB database through the connection.
+The connected database and `default_namespace_path=["public"]` are used for
+unqualified tables. Fully qualified references can still query other databases
+and namespaces available to the same deployment. `execute_query` returns a
+reader as soon as its initial result stream is available. `execute_query_async`
+returns a query handle immediately; use it to inspect progress, open a reader,
+or cancel the query. The SQL client is initialized by the first query and
+retained for the lifetime of the remote connection. Query ids are random,
+connection-scoped references rather than encoded SQL or durable resume tokens:
+
+```python
+import lancedb
+
+db = lancedb.connect(
+    "db://analytics",
+    api_key="ldb_...",
+    host_override="https://api.example.com",
+    sql_host_override="grpc+tls://sql.example.com:10026",
+)
+reader = db.execute_query(
+    """
+    SELECT events.id, accounts.name
+    FROM analytics.public.events AS events
+    JOIN users.public.accounts AS accounts ON events.user_id = accounts.id
+    """,
+    default_namespace_path=["public"],
+)
+for batch in reader:
+    print(batch.num_rows)
+
+query = db.execute_query_async("SELECT * FROM events")
+print(query.id)
+print(query.describe().status)
+for batch in query.reader():
+    print(batch.num_rows)
+
+# The async connection exposes the same lifecycle without blocking:
+# async_db = await lancedb.connect_async(
+#     "db://analytics",
+#     api_key="ldb_...",
+#     host_override="https://api.example.com",
+#     sql_host_override="grpc+tls://sql.example.com:10026",
+# )
+# reader = await async_db.execute_query("SELECT * FROM events")
+# query = await async_db.execute_query_async("SELECT * FROM events")
+# description = await async_db.describe_query(query.id)
+# async for batch in await query.reader():
+#     print(batch.num_rows)
+# await query.cancel()
+```
+
 ## Namespaces (Synchronous)

 A namespace-backed connection resolves tables through a
@@ -72,6 +125,10 @@ listing a storage directory.

 ::: lancedb.functions.UdfDefinition

+::: lancedb.secrets.EnvVarSecret
+
+::: lancedb.secrets.SecretInfo
+
 ::: lancedb.functions.FunctionRegistrationRequest

 ::: lancedb.functions.FunctionArtifactRequest
@@ -94,6 +151,8 @@ listing a storage directory.

 ::: lancedb.functions.OutputMapping

+::: lancedb.functions.AssignmentMapping
+
 ::: lancedb.functions.FunctionBinding

 ::: lancedb.functions.RefreshColumnResult
@@ -102,6 +161,18 @@ listing a storage directory.

 ::: lancedb.job.AsyncJob

+::: lancedb.job.JobInfo
+
+::: lancedb.job.JobDescription
+
+::: lancedb.job.JobFailureInfo
+
+::: lancedb.sql.Query
+
+::: lancedb.sql.AsyncQuery
+
+::: lancedb.sql.QueryDescription
+
 ## Materialized Views (Synchronous)

 ::: lancedb.materialized_view.MaterializedView
@@ -249,6 +320,12 @@ still work. Queries return descriptors. Call

 ::: lancedb.exceptions.MissingColumnError

+::: lancedb.exceptions.JobNotFoundError
+
+::: lancedb.exceptions.JobFailedError
+
+::: lancedb.exceptions.JobCancelledError
+
 ## Integrations

 ## Pydantic
@@ -8,7 +8,7 @@
    <parent>
      <groupId>com.lancedb</groupId>
      <artifactId>lancedb-parent</artifactId>
-      <version>0.39.0-beta.1</version>
+      <version>0.39.0-beta.4</version>
      <relativePath>../pom.xml</relativePath>
    </parent>

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

    <groupId>com.lancedb</groupId>
    <artifactId>lancedb-parent</artifactId>
-    <version>0.39.0-beta.1</version>
+    <version>0.39.0-beta.4</version>
    <packaging>pom</packaging>
    <name>${project.artifactId}</name>
    <description>LanceDB Java SDK Parent POM</description>
@@ -28,7 +28,7 @@
    <properties>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <arrow.version>15.0.0</arrow.version>
-        <lance-core.version>12.0.0-beta.11</lance-core.version>
+        <lance-core.version>12.0.0-beta.14</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.39.0-beta.1"
+version = "0.39.0-beta.4"
 publish = false
 license.workspace = true
 description.workspace = true
@@ -939,6 +939,7 @@ describe("remote connection jobs surface", () => {
    const { tableFromArrays, tableToIPC } = await import("apache-arrow");
    const eventsTable = tableFromArrays({ state: ["created", "succeeded"] });
    const eventsBody = Buffer.from(tableToIPC(eventsTable, "stream"));
+    const queryEventsPayloads: Record<string, unknown>[] = [];

    await withMockDatabase(
      (req, res) => {
@@ -967,6 +968,16 @@ describe("remote connection jobs surface", () => {
                );
            }
          } else if (req.url === "/v1/jobs/describe") {
+            if (payload["job_id"] === "job-2") {
+              res
+                .writeHead(200, { "Content-Type": "application/json" })
+                .end(
+                  '{"job_id": "job-2", "job_type": "refresh_column", ' +
+                    '"job_state": "DONE", "creation_ms": 2000, ' +
+                    '"result": {"rows_assigned": 1000000}}',
+                );
+              return;
+            }
            if (payload["job_id"] !== "job-1") {
              res.writeHead(404).end("no such job");
              return;
@@ -988,6 +999,7 @@ describe("remote connection jobs surface", () => {
              .writeHead(200, { "Content-Type": "application/json" })
              .end('{"job_id": "job-1"}');
          } else if (req.url === "/v1/jobs/query_events") {
+            queryEventsPayloads.push(payload);
            res
              .writeHead(200, {
                "Content-Type": "application/vnd.apache.arrow.stream",
@@ -1004,22 +1016,65 @@ describe("remote connection jobs surface", () => {
        expect(jobs[0].state).toEqual("running");
        expect(jobs[1].state).toEqual("finished");

-        const description = await db.getJob("job-1");
-        expect(description?.state).toEqual("failed");
-        expect(JSON.parse(description?.specJson ?? "")).toEqual({
-          column: "vec",
-        });
-        expect(description?.failure?.message).toEqual("worker died");
-        expect(await db.getJob("missing")).toBeNull();
-
        expect(await db.cancelJob("job-1")).toBe(true);
        expect(await db.cancelJob("missing")).toBe(false);

-        const history = await db.jobHistory("job-1");
-        expect(history.numRows).toEqual(2);
+        // Opening a job hands back a populated handle; a missing one rejects.
+        await expect(db.openJob("missing")).rejects.toThrow("not found");
+        const finished = await db.openJob("job-2");
+        expect(finished.state).toEqual("finished");
+        expect(finished.result).toEqual({
+          // biome-ignore lint/style/useNamingConvention: snake_case mandated by the server wire format
+          rows_assigned: 1000000,
+        });

-        const job = db.job("job-1");
+        const job = await db.openJob("job-1");
        expect(job.id).toEqual("job-1");
+
+        // openJob already populated the handle; refresh() re-reads it.
+        expect(job.state).toEqual("failed");
+        await job.refresh();
+        expect(job.state).toEqual("failed");
+        expect(job.jobType).toEqual("create_index");
+        expect(job.creationMs).toEqual(1000);
+        expect(job.spec).toEqual({ column: "vec" });
+        expect(job.result).toBeNull();
+        expect(job.failure?.message).toEqual("worker died");
+
+        // The handle reaches its own events, supplying its job id.
+        const jobEvents = await job.events({
+          limit: 500,
+          filter: "state = 'claim_complete'",
+        });
+        expect(jobEvents.numRows).toEqual(2);
+        expect(queryEventsPayloads.pop()).toEqual({
+          // biome-ignore lint/style/useNamingConvention: snake_case mandated by the server wire format
+          job_id: "job-1",
+          limit: 500,
+          filter: "state = 'claim_complete'",
+        });
+
+        // Printing lays every known field out on its own line, with the JSON
+        // payloads indented rather than crammed onto one line.
+        expect(`${job}`).toEqual(
+          [
+            "Job(",
+            '    id="job-1",',
+            '    state="failed",',
+            '    jobType="create_index",',
+            "    creationMs=1000,",
+            "    spec={",
+            '        "column": "vec"',
+            "    },",
+            "    failure={",
+            '        "phase": "execute",',
+            '        "message": "worker died",',
+            '        "retryable": true',
+            "    },",
+            ")",
+          ].join("\n"),
+        );
+
        expect(await job.status()).toEqual("failed");
        await expect(job.wait()).rejects.toThrow("worker died");
      },
@@ -1526,7 +1526,11 @@ describe("When creating an index", () => {

  it("should allow me to replace (or not) an existing index", async () => {
    await tbl.createIndex("id");
-    await expect(tbl.createIndex("id")).rejects.toThrow("already exists");
+    // Default is replace=true
+    await tbl.createIndex("id");
+    await expect(tbl.createIndex("id", { replace: false })).rejects.toThrow(
+      "already exists",
+    );
    await tbl.createIndex("id", { replace: true });
  });

@@ -1,7 +1,6 @@
 // SPDX-License-Identifier: Apache-2.0
 // SPDX-FileCopyrightText: Copyright The LanceDB Authors

-import { tableFromIPC } from "apache-arrow";
 import {
  Data,
  SchemaLike,
@@ -16,6 +15,7 @@ import {
  makeEmptyTable,
 } from "./arrow";
 import { EmbeddingFunctionConfig, getRegistry } from "./embedding/registry";
+import { Job } from "./job";
 import {
  MaterializedView,
  MaterializedViewSelect,
@@ -27,8 +27,6 @@ import type {
  CreateNamespaceResponse,
  DescribeNamespaceResponse,
  DropNamespaceResponse,
-  Job,
-  JobDescription,
  JobInfo,
  ListNamespacesResponse,
  ListTablesResponse,
@@ -557,24 +555,19 @@ export abstract class Connection {
  ): Promise<void>;

  /**
-   * A {@link Job} handle for a server-side job by id.
+   * Open a server-side job by id, returning a handle with its record already
+   * populated. Rejects when the server has no such job, the way
+   * {@link Connection.openTable} does for a missing table.
   *
-   * The handle is constructed without a server round trip; an unknown id
-   * surfaces when the handle is used. Dropping the handle has no effect on
-   * the job itself.
+   * The returned {@link Job} answers for its own state, specification,
+   * result, failure and event history, so there is no separate
+   * connection-level call for any of them.
   */
-  abstract job(jobId: string): Job;
+  abstract openJob(jobId: string): Promise<Job>;

  /** List server-side jobs across the database's tables. */
  abstract listJobs(): Promise<JobInfo[]>;

-  /**
-   * Describe a single server-side job by id.
-   *
-   * Resolves to `null` when the server has no such job.
-   */
-  abstract getJob(jobId: string): Promise<JobDescription | null>;
-
  /**
   * Request cancellation of a server-side job by id.
   *
@@ -582,13 +575,6 @@ export abstract class Connection {
   * such job exists. Cancelling an already-terminal job is a no-op success.
   */
  abstract cancelJob(jobId: string): Promise<boolean>;
-
-  /**
-   * The lifecycle event history of a server-side job, as an Arrow table.
-   *
-   * Lists history across all jobs when `jobId` is omitted.
-   */
-  abstract jobHistory(jobId?: string): Promise<ArrowTable>;
 }

 /** @hideconstructor */
@@ -869,7 +855,7 @@ export class LocalConnection extends Connection {
  }

  async dropTableAsync(name: string, namespacePath?: string[]): Promise<Job> {
-    return this.inner.dropTableAsync(name, namespacePath ?? []);
+    return new Job(await this.inner.dropTableAsync(name, namespacePath ?? []));
  }

  async dropAllTables(namespacePath?: string[]): Promise<void> {
@@ -928,29 +914,17 @@ export class LocalConnection extends Connection {
    );
  }

-  job(jobId: string): Job {
-    return this.inner.job(jobId);
+  async openJob(jobId: string): Promise<Job> {
+    return new Job(await this.inner.openJob(jobId));
  }

  async listJobs(): Promise<JobInfo[]> {
    return this.inner.listJobs();
  }

-  async getJob(jobId: string): Promise<JobDescription | null> {
-    return this.inner.getJob(jobId);
-  }
-
  async cancelJob(jobId: string): Promise<boolean> {
    return this.inner.cancelJob(jobId);
  }
-
-  async jobHistory(jobId?: string): Promise<ArrowTable> {
-    const buf = await this.inner.jobHistory(jobId);
-    if (buf.length === 0) {
-      return new ArrowTable();
-    }
-    return tableFromIPC(buf);
-  }
 }

 /**
@@ -94,13 +94,9 @@ export {
  RenameTableOptions,
 } from "./connection";

-export {
-  Job,
-  JobDescription,
-  JobFailureInfo,
-  JobInfo,
-  Session,
-} from "./native.js";
+export { JobFailureInfo, JobInfo, Session } from "./native.js";
+
+export { Job, JobEventsOptions } from "./job";

 export {
  AutoQuery,
@@ -841,7 +841,7 @@ export interface IndexOptions {
   * and the same name, then an error will be returned.  This is true even if
   * that index is out of date.
   *
-   * The default is false
+   * The default is true
   */
  replace?: boolean;

@@ -0,0 +1,188 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright The LanceDB Authors
+
+import { Table as ArrowTable, tableFromIPC } from "apache-arrow";
+import { JobFailureInfo, Job as NativeJob } from "./native";
+
+/** Which of a job's events {@link Job.events} returns. */
+export interface JobEventsOptions {
+  /** Maximum event rows to return, up to the server maximum of 10,000. */
+  limit?: number;
+  /** SQL-like filter over the event columns. */
+  filter?: string;
+}
+
+/**
+ * A handle to an operation that may still be running.
+ *
+ * The operation may already be complete when the handle is created.
+ *
+ * The detail getters read what the handle last observed. Submitting an
+ * operation returns only a job id, so populating them eagerly would cost an
+ * extra round trip on every call:
+ *
+ * - {@link Job.refresh} and {@link Job.status} fetch the whole record.
+ * - {@link Job.wait} records the terminal state it establishes, but not the
+ *   rest of the record.
+ * - Everything is null until one of those runs.
+ *
+ * @hideconstructor
+ */
+export class Job {
+  private readonly inner: NativeJob;
+
+  constructor(inner: NativeJob) {
+    this.inner = inner;
+  }
+
+  /**
+   * Identifies the operation on the server that is running it.
+   *
+   * Operations that run in this process have no server id. The value is
+   * opaque: parsing it or storing it to resume the job later is not supported.
+   */
+  get id(): string | null {
+    return this.inner.id ?? null;
+  }
+
+  /** The last observed lifecycle state, without contacting the backend. */
+  get state(): string | null {
+    return this.inner.state ?? null;
+  }
+
+  /**
+   * The job's type, as the server names it. Null for an in-process job, which
+   * has no server-side record.
+   */
+  get jobType(): string | null {
+    return this.inner.jobType ?? null;
+  }
+
+  /** When the job was created, in milliseconds since the epoch. */
+  get creationMs(): number | null {
+    return this.inner.creationMs ?? null;
+  }
+
+  /** The job-type-specific specification it was submitted with. */
+  // biome-ignore lint/suspicious/noExplicitAny: shape varies by job type
+  get spec(): any | null {
+    return parseJson(this.inner.specJson);
+  }
+
+  /**
+   * The job-type-specific terminal result. Null until the job succeeds, so a
+   * job that never terminates reports its progress through {@link Job.events}
+   * instead.
+   */
+  // biome-ignore lint/suspicious/noExplicitAny: shape varies by job type
+  get result(): any | null {
+    return parseJson(this.inner.resultJson);
+  }
+
+  /** Why the job failed, when it failed and the server reports a reason. */
+  get failure(): JobFailureInfo | null {
+    return this.inner.failure ?? null;
+  }
+
+  /**
+   * The operation's current lifecycle state: "running", "finished", "failed",
+   * or "cancelled".
+   *
+   * A point snapshot; unlike {@link Job.wait} it does not block or reject on a
+   * terminal failure state. Also refreshes the getters above.
+   */
+  async status(): Promise<string> {
+    return this.inner.status();
+  }
+
+  /** Wait until the operation reaches a terminal state. */
+  async wait(): Promise<void> {
+    return this.inner.wait();
+  }
+
+  /** Request cancellation. Cancelling a finished operation is a no-op. */
+  async cancel(): Promise<void> {
+    return this.inner.cancel();
+  }
+
+  /**
+   * Ask the backend for this job's current state, and for a server-side job
+   * its full record, then cache it for the getters above.
+   */
+  async refresh(): Promise<void> {
+    return this.inner.refresh();
+  }
+
+  /**
+   * This job's recorded lifecycle events.
+   *
+   * Where the getters above report a terminal result only once the job reaches
+   * one, events are written as the job runs and outlive the workers that
+   * produced them. A distributed job records a `claim`/`claim_complete` pair
+   * per unit of work, each carrying `rows_processed`, so a job that never
+   * finishes still accounts for what it did.
+   *
+   * The server caps results at 1000 rows by default and 10,000 at most, and
+   * truncates without saying so, so pass `limit` for a job that emits an event
+   * per fragment. `filter` is a SQL-like expression over the `state`,
+   * `updated_by`, `emitted_from`, `emitted_by`, and `claim_entity` columns.
+   */
+  async events(options?: JobEventsOptions): Promise<ArrowTable> {
+    const buf = await this.inner.events(options?.limit, options?.filter);
+    if (buf.length === 0) {
+      return new ArrowTable();
+    }
+    return tableFromIPC(buf);
+  }
+
+  /**
+   * Every field the handle currently knows, one per line, with the JSON
+   * payloads indented -- a refresh job's spec and result are the point of
+   * printing it.
+   */
+  toString(): string {
+    if (this.state === null) {
+      const known = this.id === null ? "" : `id=${JSON.stringify(this.id)}, `;
+      return `Job(${known}not refreshed)`;
+    }
+    const fields: string[] = [];
+    if (this.id !== null) {
+      fields.push(`id=${JSON.stringify(this.id)}`);
+    }
+    fields.push(`state=${JSON.stringify(this.state)}`);
+    if (this.jobType !== null) {
+      fields.push(`jobType=${JSON.stringify(this.jobType)}`);
+    }
+    if (this.creationMs !== null) {
+      fields.push(`creationMs=${this.creationMs}`);
+    }
+    for (const [name, value] of [
+      ["spec", this.spec],
+      ["result", this.result],
+    ] as const) {
+      if (value !== null) {
+        fields.push(`${name}=${indentJson(value)}`);
+      }
+    }
+    if (this.failure !== null) {
+      fields.push(`failure=${indentJson(this.failure)}`);
+    }
+    return `Job(${fields.map((field) => `\n${REPR_INDENT}${field},`).join("")}\n)`;
+  }
+
+  [Symbol.for("nodejs.util.inspect.custom")](): string {
+    return this.toString();
+  }
+}
+
+const REPR_INDENT = "    ";
+
+// biome-ignore lint/suspicious/noExplicitAny: shape varies by job type
+function indentJson(value: any): string {
+  return JSON.stringify(value, null, 4).replace(/\n/g, `\n${REPR_INDENT}`);
+}
+
+// biome-ignore lint/suspicious/noExplicitAny: shape varies by job type
+function parseJson(raw: string | null | undefined): any | null {
+  return raw === null || raw === undefined ? null : JSON.parse(raw);
+}
@@ -19,6 +19,7 @@ import {

 import { EmbeddingFunctionConfig, getRegistry } from "./embedding/registry";
 import { IndexOptions } from "./indices";
+import { Job } from "./job";
 import { MergeInsertBuilder } from "./merge";
 import {
  AddColumnsResult,
@@ -30,7 +31,6 @@ import {
  DropColumnsResult,
  IndexConfig,
  IndexStatistics,
-  Job,
  LsmStats,
  Branches as NativeBranches,
  OptimizeStats,
@@ -1124,13 +1124,15 @@ export class LocalTable extends Table {
  ): Promise<Job> {
    // biome-ignore lint/suspicious/noExplicitAny: skip
    const nativeIndex = (options?.config as any)?.inner;
-    return await this.inner.createIndexAsync(
-      nativeIndex,
-      column,
-      options?.replace,
-      options?.waitTimeoutSeconds,
-      options?.name,
-      options?.train,
+    return new Job(
+      await this.inner.createIndexAsync(
+        nativeIndex,
+        column,
+        options?.replace,
+        options?.waitTimeoutSeconds,
+        options?.name,
+        options?.train,
+      ),
    );
  }

@@ -1313,7 +1315,7 @@ export class LocalTable extends Table {
  }

  async refreshColumnAsync(column: string): Promise<Job> {
-    return await this.inner.refreshColumnAsync(column);
+    return new Job(await this.inner.refreshColumnAsync(column));
  }

  async refreshMaterializedView(
@@ -1,6 +1,6 @@
 {
 	"name": "@lancedb/lancedb-darwin-arm64",
-	"version": "0.39.0-beta.1",
+	"version": "0.39.0-beta.4",
 	"os": ["darwin"],
 	"cpu": ["arm64"],
 	"main": "lancedb.darwin-arm64.node",
@@ -1,6 +1,6 @@
 {
 	"name": "@lancedb/lancedb-linux-arm64-gnu",
-	"version": "0.39.0-beta.1",
+	"version": "0.39.0-beta.4",
 	"os": ["linux"],
 	"cpu": ["arm64"],
 	"main": "lancedb.linux-arm64-gnu.node",
@@ -1,6 +1,6 @@
 {
 	"name": "@lancedb/lancedb-linux-arm64-musl",
-	"version": "0.39.0-beta.1",
+	"version": "0.39.0-beta.4",
 	"os": ["linux"],
 	"cpu": ["arm64"],
 	"main": "lancedb.linux-arm64-musl.node",
@@ -1,6 +1,6 @@
 {
 	"name": "@lancedb/lancedb-linux-x64-gnu",
-	"version": "0.39.0-beta.1",
+	"version": "0.39.0-beta.4",
 	"os": ["linux"],
 	"cpu": ["x64"],
 	"main": "lancedb.linux-x64-gnu.node",
@@ -1,6 +1,6 @@
 {
 	"name": "@lancedb/lancedb-linux-x64-musl",
-	"version": "0.39.0-beta.1",
+	"version": "0.39.0-beta.4",
 	"os": ["linux"],
 	"cpu": ["x64"],
 	"main": "lancedb.linux-x64-musl.node",
@@ -1,6 +1,6 @@
 {
  "name": "@lancedb/lancedb-win32-arm64-msvc",
-  "version": "0.39.0-beta.1",
+  "version": "0.39.0-beta.4",
  "os": [
    "win32"
  ],
@@ -1,6 +1,6 @@
 {
 	"name": "@lancedb/lancedb-win32-x64-msvc",
-	"version": "0.39.0-beta.1",
+	"version": "0.39.0-beta.4",
 	"os": ["win32"],
 	"cpu": ["x64"],
 	"main": "lancedb.win32-x64-msvc.node",
@@ -11,7 +11,7 @@
    "ann"
  ],
  "private": false,
-  "version": "0.39.0-beta.1",
+  "version": "0.39.0-beta.4",
  "main": "dist/index.js",
  "exports": {
    ".": "./dist/index.js",
@@ -41,7 +41,7 @@ importers:
        version: 3.7.0(@emnapi/core@1.10.0)(@emnapi/runtime@1.11.3)(@types/node@22.7.4)
      '@opentelemetry/sdk-metrics':
        specifier: ^2.10.0
-        version: 2.10.0(@opentelemetry/api@1.9.1)
+        version: 2.11.0(@opentelemetry/api@1.9.1)
      '@types/axios':
        specifier: ^0.14.0
        version: 0.14.4
@@ -80,7 +80,7 @@ importers:
        version: 0.2.7
      ts-jest:
        specifier: ^29.1.2
-        version: 29.4.9(@babel/core@7.29.7)(@jest/transform@29.7.0)(@jest/types@29.6.3)(babel-jest@29.7.0(@babel/core@7.29.7))(jest-util@29.7.0)(jest@29.7.0(@types/node@22.7.4))(typescript@5.5.4)
+        version: 29.4.12(@babel/core@7.29.7)(@jest/transform@29.7.0)(@jest/types@29.6.3)(babel-jest@29.7.0(@babel/core@7.29.7))(jest-util@29.7.0)(jest@29.7.0(@types/node@22.7.4))(typescript@5.5.4)
      typedoc:
        specifier: 0.26.4
        version: 0.26.4(typescript@5.5.4)
@@ -1394,20 +1394,20 @@ packages:
    resolution: {integrity: sha512-gLyJlPHPZYdAk1JENA9LeHejZe1Ti77/pTeFm/nMXmQH/HFZlcS/O2XJB+L8fkbrNSqhdtlvjBVjxwUYanNH5Q==}
    engines: {node: '>=8.0.0'}

-  '@opentelemetry/core@2.10.0':
-    resolution: {integrity: sha512-/wNZ8twnEQQA4HoHu22+vcsdru6pWPWxW+7w+FlxT6Id7PE/WIbZmVKkte+PF72e0F2dnImFeHD2syyE1Mw6MQ==}
+  '@opentelemetry/core@2.11.0':
+    resolution: {integrity: sha512-7YP44XH0tV6+Mb54x2YGf84i7yi+31MBZlE8JwvozkxyTvXbSp10X7cI7YE49ChJ3shMJoBmCJF3+1QFBJctGA==}
    engines: {node: ^18.19.0 || >=20.6.0}
    peerDependencies:
      '@opentelemetry/api': '>=1.0.0 <1.10.0'

-  '@opentelemetry/resources@2.10.0':
-    resolution: {integrity: sha512-q6MMm2zhggzsHVNbabYwut+a6nbuQQe3URUoxaojM/8K1IBfwwPzvxIjNi2/lI1TFe+fMHMW9MWhrtDLEXEnkA==}
+  '@opentelemetry/resources@2.11.0':
+    resolution: {integrity: sha512-Ie7+8q8MDF4FAEQCKVMTx3ReUvxiIAgIiiW3c9JdmP8+HMcDy20puT+AHjexnExgnbvBxjQ9fjkFDWrikJ2jQA==}
    engines: {node: ^18.19.0 || >=20.6.0}
    peerDependencies:
      '@opentelemetry/api': '>=1.3.0 <1.10.0'

-  '@opentelemetry/sdk-metrics@2.10.0':
-    resolution: {integrity: sha512-t6r1VSvXNtSDnPXU1FbZeetJb7yyovHmgu0wRSoftxtE0g2rSNhQZQUy69sRUCL+iioJpX8SN/S6wq6ZtvLySQ==}
+  '@opentelemetry/sdk-metrics@2.11.0':
+    resolution: {integrity: sha512-7GXXcObyHyDUUSG+L+kJoquty01bzm7ivE7+SSgXXJcHuPzGviptxwARmI2c+bnnxjexGQbJnyNlN8HxBP/Y7A==}
    engines: {node: ^18.19.0 || >=20.6.0}
    peerDependencies:
      '@opentelemetry/api': '>=1.9.0 <1.10.0'
@@ -1480,6 +1480,7 @@ packages:
  '@smithy/core@3.24.1':
    resolution: {integrity: sha512-3mT7o4qQyUWttYnVK3A0Z/u3Xha3E81tXn32Tz6vjZiUXhBrkEivpw1hBYfh84iFF9CSzkBU9Y1DJ3Q6RQ231g==}
    engines: {node: '>=18.0.0'}
+    deprecated: Deprecated due to bug in browser bundling instructions https://github.com/smithy-lang/smithy-typescript/issues/2025

  '@smithy/credential-provider-imds@4.3.1':
    resolution: {integrity: sha512-0S/acwHnqX4WrjXzhdiDRxsG2s9SC0cpPIK9nZ1R6UOHd+j7uL28+4bHu22urbLk2TVw3fkp6na/+fkUt/pLNQ==}
@@ -3238,8 +3239,8 @@ packages:
    peerDependencies:
      typescript: '>=4.2.0'

-  ts-jest@29.4.9:
-    resolution: {integrity: sha512-LTb9496gYPMCqjeDLdPrKuXtncudeV1yRZnF4Wo5l3SFi0RYEnYRNgMrFIdg+FHvfzjCyQk1cLncWVqiSX+EvQ==}
+  ts-jest@29.4.12:
+    resolution: {integrity: sha512-Ov6ClY53Fflh6BGAnY2DlTq1hYDrTycz2PVTXBWFW2CU+9zrEqAp9fWdGXl42EXO5RLSFAcAZ2JFKbP+zBTFfw==}
    engines: {node: ^14.15.0 || ^16.10.0 || ^18.0.0 || >=20.0.0}
    hasBin: true
    peerDependencies:
@@ -5110,22 +5111,22 @@ snapshots:

  '@opentelemetry/api@1.9.1': {}

-  '@opentelemetry/core@2.10.0(@opentelemetry/api@1.9.1)':
+  '@opentelemetry/core@2.11.0(@opentelemetry/api@1.9.1)':
    dependencies:
      '@opentelemetry/api': 1.9.1
      '@opentelemetry/semantic-conventions': 1.43.0

-  '@opentelemetry/resources@2.10.0(@opentelemetry/api@1.9.1)':
+  '@opentelemetry/resources@2.11.0(@opentelemetry/api@1.9.1)':
    dependencies:
      '@opentelemetry/api': 1.9.1
-      '@opentelemetry/core': 2.10.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/core': 2.11.0(@opentelemetry/api@1.9.1)
      '@opentelemetry/semantic-conventions': 1.43.0

-  '@opentelemetry/sdk-metrics@2.10.0(@opentelemetry/api@1.9.1)':
+  '@opentelemetry/sdk-metrics@2.11.0(@opentelemetry/api@1.9.1)':
    dependencies:
      '@opentelemetry/api': 1.9.1
-      '@opentelemetry/core': 2.10.0(@opentelemetry/api@1.9.1)
-      '@opentelemetry/resources': 2.10.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/core': 2.11.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/resources': 2.11.0(@opentelemetry/api@1.9.1)

  '@opentelemetry/semantic-conventions@1.43.0': {}

@@ -5574,7 +5575,7 @@ snapshots:
      globby: 11.1.0
      is-glob: 4.0.3
      minimatch: 9.0.9
-      semver: 7.8.0
+      semver: 7.8.5
      ts-api-utils: 1.4.3(typescript@5.5.4)
    optionalDependencies:
      typescript: 5.5.4
@@ -6426,7 +6427,7 @@ snapshots:
      '@babel/parser': 7.29.3
      '@istanbuljs/schema': 0.1.6
      istanbul-lib-coverage: 3.2.2
-      semver: 7.8.0
+      semver: 7.8.5
    transitivePeerDependencies:
      - supports-color

@@ -6705,7 +6706,7 @@ snapshots:
      jest-util: 29.7.0
      natural-compare: 1.4.0
      pretty-format: 29.7.0
-      semver: 7.8.0
+      semver: 7.8.5
    transitivePeerDependencies:
      - supports-color

@@ -6828,7 +6829,7 @@ snapshots:

  make-dir@4.0.0:
    dependencies:
-      semver: 7.8.0
+      semver: 7.8.5

  make-error@1.3.6: {}

@@ -7162,8 +7163,7 @@ snapshots:

  semver@7.8.0: {}

-  semver@7.8.5:
-    optional: true
+  semver@7.8.5: {}

  sharp@0.35.4(@types/node@22.7.4):
    dependencies:
@@ -7327,7 +7327,7 @@ snapshots:
    dependencies:
      typescript: 5.5.4

-  ts-jest@29.4.9(@babel/core@7.29.7)(@jest/transform@29.7.0)(@jest/types@29.6.3)(babel-jest@29.7.0(@babel/core@7.29.7))(jest-util@29.7.0)(jest@29.7.0(@types/node@22.7.4))(typescript@5.5.4):
+  ts-jest@29.4.12(@babel/core@7.29.7)(@jest/transform@29.7.0)(@jest/types@29.6.3)(babel-jest@29.7.0(@babel/core@7.29.7))(jest-util@29.7.0)(jest@29.7.0(@types/node@22.7.4))(typescript@5.5.4):
    dependencies:
      bs-logger: 0.2.6
      fast-json-stable-stringify: 2.1.0
@@ -7336,7 +7336,7 @@ snapshots:
      json5: 2.2.3
      lodash.memoize: 4.1.2
      make-error: 1.3.6
-      semver: 7.8.0
+      semver: 7.8.5
      type-fest: 4.41.0
      typescript: 5.5.4
      yargs-parser: 21.1.1
@@ -442,13 +442,15 @@ impl Connection {
        self.get_inner()?.drop_all_tables(&ns).await.default_error()
    }

-    /// A `Job` handle for a server-side job by id.
+    /// Open a server-side job by id, returning a handle with its record
+    /// already populated. Rejects when the server has no such job.
    ///
-    /// The handle is constructed without a server round trip; an unknown id
-    /// surfaces when the handle is used.
-    #[napi]
-    pub fn job(&self, job_id: String) -> napi::Result<crate::job::Job> {
-        let job = self.get_inner()?.job(job_id).default_error()?;
+    /// The returned handle answers for its own state, specification, result,
+    /// failure and event history, so there is no separate connection-level
+    /// call for any of them.
+    #[napi(catch_unwind)]
+    pub async fn open_job(&self, job_id: String) -> napi::Result<crate::job::Job> {
+        let job = self.get_inner()?.open_job(&job_id).await.default_error()?;
        Ok(crate::job::Job::new(job))
    }

@@ -459,17 +461,6 @@ impl Connection {
        Ok(jobs.into_iter().map(Into::into).collect())
    }

-    /// Describe a single server-side job by id. `null` when the server has
-    /// no such job.
-    #[napi(catch_unwind)]
-    pub async fn get_job(
-        &self,
-        job_id: String,
-    ) -> napi::Result<Option<crate::job::JobDescription>> {
-        let description = self.get_inner()?.get_job(&job_id).await.default_error()?;
-        Ok(description.map(Into::into))
-    }
-
    /// Request cancellation of a server-side job by id. Returns true if the
    /// server accepted the cancellation, false if no such job exists.
    #[napi(catch_unwind)]
@@ -477,34 +468,6 @@ impl Connection {
        self.get_inner()?.cancel_job(&job_id).await.default_error()
    }

-    /// The lifecycle event history of a server-side job (all jobs when
-    /// `job_id` is null), as an Arrow IPC stream buffer. Empty when there is
-    /// no history.
-    #[napi(catch_unwind)]
-    pub async fn job_history(&self, job_id: Option<String>) -> napi::Result<Buffer> {
-        let batches = self
-            .get_inner()?
-            .job_history(job_id.as_deref())
-            .await
-            .default_error()?;
-        let Some(first) = batches.first() else {
-            return Ok(Buffer::from(Vec::<u8>::new()));
-        };
-        let mut out = Vec::new();
-        let mut writer = arrow_ipc::writer::StreamWriter::try_new(&mut out, &first.schema())
-            .map_err(|e| napi::Error::from_reason(e.to_string()))?;
-        for batch in &batches {
-            writer
-                .write(batch)
-                .map_err(|e| napi::Error::from_reason(e.to_string()))?;
-        }
-        writer
-            .finish()
-            .map_err(|e| napi::Error::from_reason(e.to_string()))?;
-        drop(writer);
-        Ok(Buffer::from(out))
-    }
-
    #[napi(catch_unwind)]
    /// Describe a namespace and return its properties.
    pub async fn describe_namespace(
@@ -3,6 +3,9 @@

 use std::sync::Arc;

+use arrow_array::RecordBatch;
+use lancedb::job::JobEventsRequest;
+use napi::bindgen_prelude::Buffer;
 use napi_derive::napi;

 use crate::error::NapiErrorExt;
@@ -55,12 +58,98 @@ impl Job {
    pub async fn cancel(&self) -> napi::Result<()> {
        self.inner.cancel().await.default_error()
    }
+
+    /// Ask the backend for this job's current state, and for a server-side job
+    /// its full record, then cache it for the getters below.
+    ///
+    /// They are all null until this runs, because submitting an operation
+    /// returns only a job id. {@link Job.status} fetches the whole record too;
+    /// {@link Job.wait} records only the terminal state it establishes.
+    #[napi(catch_unwind)]
+    pub async fn refresh(&self) -> napi::Result<()> {
+        self.inner.refresh().await.default_error()
+    }
+
+    /// The last observed lifecycle state, without contacting the backend.
+    #[napi(getter)]
+    pub fn state(&self) -> Option<String> {
+        self.inner.state()
+    }
+
+    /// The job's type, as the server names it. Null for an in-process job,
+    /// which has no server-side record.
+    #[napi(getter)]
+    pub fn job_type(&self) -> Option<String> {
+        self.inner.job_type()
+    }
+
+    /// When the job was created, in milliseconds since the epoch.
+    #[napi(getter)]
+    pub fn creation_ms(&self) -> Option<i64> {
+        self.inner.creation_ms()
+    }
+
+    /// The job-type-specific specification as a JSON string, when present.
+    #[napi(getter)]
+    pub fn spec_json(&self) -> Option<String> {
+        self.inner.spec().map(|spec| spec.to_string())
+    }
+
+    /// The job-type-specific terminal result as a JSON string. Null until the
+    /// job succeeds, so a job that never terminates reports its progress
+    /// through {@link Job.events} instead.
+    #[napi(getter)]
+    pub fn result_json(&self) -> Option<String> {
+        self.inner.result().map(|result| result.to_string())
+    }
+
+    /// Why the job failed, when it failed and the server reports a reason.
+    #[napi(getter)]
+    pub fn failure(&self) -> Option<JobFailureInfo> {
+        self.inner.failure().map(|failure| JobFailureInfo {
+            phase: failure.phase,
+            message: failure.message,
+            retryable: failure.retryable,
+        })
+    }
+
+    /// This job's recorded lifecycle events, as an Arrow IPC stream buffer.
+    /// The TypeScript wrapper turns it into an Arrow table.
+    #[napi(catch_unwind)]
+    pub async fn events(&self, limit: Option<u32>, filter: Option<String>) -> napi::Result<Buffer> {
+        let batches = self
+            .inner
+            .events(JobEventsRequest { limit, filter })
+            .await
+            .default_error()?;
+        batches_to_ipc_buffer(&batches)
+    }
+}
+
+/// Serialise Arrow batches as a single IPC stream for the TypeScript layer.
+fn batches_to_ipc_buffer(batches: &[RecordBatch]) -> napi::Result<Buffer> {
+    let Some(first) = batches.first() else {
+        return Ok(Buffer::from(Vec::<u8>::new()));
+    };
+    let mut out = Vec::new();
+    let mut writer = arrow_ipc::writer::StreamWriter::try_new(&mut out, &first.schema())
+        .map_err(|e| napi::Error::from_reason(e.to_string()))?;
+    for batch in batches {
+        writer
+            .write(batch)
+            .map_err(|e| napi::Error::from_reason(e.to_string()))?;
+    }
+    writer
+        .finish()
+        .map_err(|e| napi::Error::from_reason(e.to_string()))?;
+    drop(writer);
+    Ok(Buffer::from(out))
 }

 /// A row from `Connection.listJobs`: one server-side job.
 #[napi(object)]
 pub struct JobInfo {
-    /// The job id -- what `Connection.getJob` and `Connection.cancelJob`
+    /// The job id -- what `Connection.openJob` and `Connection.cancelJob`
    /// accept.
    pub job_id: String,
    /// The table the job runs against, without URI or namespace.
@@ -91,36 +180,3 @@ pub struct JobFailureInfo {
    pub message: Option<String>,
    pub retryable: Option<bool>,
 }
-
-/// A described job from `Connection.getJob`.
-#[napi(object)]
-pub struct JobDescription {
-    pub job_id: String,
-    pub job_type: String,
-    /// Lifecycle state: "running", "finished", "failed", or "cancelled".
-    pub state: String,
-    /// When the job was created, in milliseconds since the epoch.
-    pub creation_ms: i64,
-    /// The job-type-specific specification as a JSON string, when present.
-    pub spec_json: Option<String>,
-    /// Why the job failed, when the job is failed and the server reports a
-    /// reason.
-    pub failure: Option<JobFailureInfo>,
-}
-
-impl From<lancedb::database::JobDescription> for JobDescription {
-    fn from(description: lancedb::database::JobDescription) -> Self {
-        Self {
-            job_id: description.job_id,
-            job_type: description.job_type,
-            state: description.state,
-            creation_ms: description.creation_ms,
-            spec_json: (!description.spec.is_null()).then(|| description.spec.to_string()),
-            failure: description.failure.map(|failure| JobFailureInfo {
-                phase: failure.phase,
-                message: failure.message,
-                retryable: failure.retryable,
-            }),
-        }
-    }
-}
@@ -1,6 +1,6 @@
 [package]
 name = "lancedb-python"
-version = "0.39.0-beta.1"
+version = "0.39.0-beta.4"
 publish = false
 edition.workspace = true
 description = "Python bindings for LanceDB"
@@ -28,7 +28,7 @@ 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"] }
+pyo3 = { version = "0.28", features = ["abi3-py310", "chrono", "uuid"] }
 chrono.workspace = true
 pyo3-async-runtimes = { version = "0.28", features = [
    "attributes",
@@ -40,6 +40,7 @@ serde.workspace = true
 serde_json.workspace = true
 snafu.workspace = true
 tokio.workspace = true
+uuid.workspace = true
 libc = "0.2"

 [build-dependencies]
@@ -139,6 +139,7 @@ include = [
    "python/lancedb/exceptions.py",
    "python/lancedb/background_loop.py",
    "python/lancedb/schema.py",
+    "python/lancedb/sql.py",
    "python/lancedb/remote/__init__.py",
    "python/lancedb/remote/errors.py",
    "python/lancedb/embeddings/__init__.py",
@@ -22,7 +22,11 @@ from .remote.db import RemoteDBConnection
 from .expr import Expr, col, lit, func
 from .schema import blob, vector
 from .job import AsyncJob, Job
+from .sql import AsyncQuery as AsyncSqlQuery
+from .sql import Query as SqlQuery
+from .sql import QueryDescription
 from .functions import (
+    AssignmentMapping as AssignmentMapping,
    FunctionArtifactRequest as FunctionArtifactRequest,
    FunctionApplication as FunctionApplication,
    FunctionBinding as FunctionBinding,
@@ -33,6 +37,8 @@ from .functions import (
    UdfDefinition as UdfDefinition,
    udf as udf,
 )
+from .secrets import EnvVarSecret as EnvVarSecret
+from .secrets import SecretInfo as SecretInfo
 from .materialized_view import (
    AsyncMaterializedView,
    MaterializedView,
@@ -101,6 +107,7 @@ def connect(
    api_key: Optional[str] = None,
    region: str = "us-east-1",
    host_override: Optional[str] = None,
+    sql_host_override: Optional[str] = None,
    read_consistency_interval: Optional[timedelta] = None,
    request_thread_pool: Optional[Union[int, ThreadPoolExecutor]] = None,
    client_config: Union[ClientConfig, Dict[str, Any], None] = None,
@@ -129,6 +136,9 @@ def connect(
        The region to use for LanceDB Cloud.
    host_override: str, optional
        The override url for LanceDB Cloud.
+    sql_host_override: str, optional
+        The remote SQL service endpoint override. The client connects lazily when SQL
+        is first executed and retains that connection.
    read_consistency_interval: timedelta, default None
        The interval at which to check for updates to the table from other
        processes. If None, then consistency is not checked. For performance
@@ -270,6 +280,7 @@ def connect(
            api_key,
            region,
            host_override,
+            sql_host_override=sql_host_override,
            # TODO: remove this (deprecation warning downstream)
            request_thread_pool=request_thread_pool,
            client_config=client_config,
@@ -412,6 +423,7 @@ def deserialize_conn(
            parsed["api_key"],
            parsed.get("region", "us-east-1"),
            host_override=parsed.get("host_override"),
+            sql_host_override=parsed.get("sql_host_override"),
            client_config=parsed.get("client_config"),
            storage_options=storage_options,
        )
@@ -425,6 +437,7 @@ async def connect_async(
    api_key: Optional[str] = None,
    region: str = "us-east-1",
    host_override: Optional[str] = None,
+    sql_host_override: Optional[str] = None,
    read_consistency_interval: Optional[timedelta] = None,
    client_config: Optional[Union[ClientConfig, Dict[str, Any]]] = None,
    storage_options: Optional[Dict[str, str]] = None,
@@ -447,6 +460,9 @@ async def connect_async(
        The region to use for LanceDB Cloud.
    host_override: str, optional
        The override url for LanceDB Cloud.
+    sql_host_override: str, optional
+        The remote SQL service endpoint override. The client connects lazily when SQL
+        is first executed and retains that connection.
    read_consistency_interval: timedelta, default None
        The interval at which to check for updates to the table from other
        processes. If None, then consistency is not checked. For performance
@@ -534,6 +550,7 @@ async def connect_async(
            api_key,
            region,
            host_override,
+            sql_host_override,
            read_consistency_interval_secs,
            client_config,
            storage_options,
@@ -556,6 +573,7 @@ __all__ = [
    "connect_namespace_async",
    "AsyncConnection",
    "AsyncJob",
+    "AsyncSqlQuery",
    "AsyncLanceNamespaceDBConnection",
    "AsyncTable",
    "FtsToken",
@@ -570,6 +588,8 @@ __all__ = [
    "vector",
    "DBConnection",
    "Job",
+    "QueryDescription",
+    "SqlQuery",
    "LanceDBConnection",
    "LanceNamespaceDBConnection",
    "LsmWriteSpec",
@@ -1,6 +1,7 @@
 from datetime import date, datetime, timedelta
 from decimal import Decimal
 from typing import Dict, List, Optional, Tuple, Any, TypedDict, Union, Literal
+from uuid import UUID

 import pyarrow as pa

@@ -147,17 +148,31 @@ class Connection(object):
        start_after: Optional[str],
        limit: Optional[int],
    ) -> list[str]: ...  # Deprecated: Use list_tables instead
-    def job(self, job_id: str) -> Job: ...
+    async def open_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_functions(self) -> List[str]: ...
    async def drop_function(self, name: str, version: str) -> bool: ...
+    async def create_secret(
+        self, name: str, value: str, namespace_path: List[str]
+    ) -> None: ...
+    async def alter_secret(
+        self, name: str, value: str, namespace_path: List[str]
+    ) -> None: ...
+    async def list_secrets(self, namespace_path: List[str]) -> List[str]: ...
+    async def drop_secret(self, name: str, namespace_path: List[str]) -> None: ...
+    async def describe_secret(
+        self, name: str, namespace_path: List[str]
+    ) -> Dict[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: ...
-    async def job_history(
-        self, job_id: Optional[str] = None
-    ) -> List[pa.RecordBatch]: ...
+    async def execute_query_async(
+        self,
+        query: str,
+        *,
+        default_namespace_path: Optional[List[str]] = None,
+    ) -> SqlQuery: ...
+    async def describe_query(self, query_id: UUID) -> QueryDescription: ...
    async def create_table(
        self,
        name: str,
@@ -236,9 +251,20 @@ class BlobFile:
 class Job:
    @property
    def id(self) -> Optional[str]: ...
+    @property
+    def _state(self) -> Optional[str]: ...
+    @property
+    def _description(self) -> Optional[JobDescription]: ...
    async def status(self) -> str: ...
    async def wait(self) -> Optional[str]: ...
    async def cancel(self) -> None: ...
+    async def refresh(self) -> None: ...
+    async def events(
+        self,
+        *,
+        limit: Optional[int] = None,
+        filter: Optional[str] = None,
+    ) -> pa.Table: ...

 class JobInfo:
    @property
@@ -270,10 +296,33 @@ class JobDescription:
    @property
    def creation_ms(self) -> int: ...
    @property
-    def spec_json(self) -> Optional[str]: ...
+    def _spec_json(self) -> Optional[str]: ...
+    @property
+    def _result_json(self) -> Optional[str]: ...
+    @property
+    def spec(self) -> Optional[Any]: ...
+    @property
+    def result(self) -> Optional[Any]: ...
    @property
    def failure(self) -> Optional[JobFailureInfo]: ...

+class SqlQuery:
+    @property
+    def id(self) -> UUID: ...
+    async def describe(self) -> QueryDescription: ...
+    async def reader(self) -> RecordBatchStream: ...
+    async def cancel(self) -> None: ...
+
+class QueryDescription:
+    @property
+    def id(self) -> UUID: ...
+    @property
+    def status(self) -> str: ...
+    @property
+    def progress(self) -> Optional[float]: ...
+    @property
+    def expires_at(self) -> Optional[datetime]: ...
+
 class Table:
    def name(self) -> str: ...
    def __repr__(self) -> str: ...
@@ -452,6 +501,7 @@ async def connect(
    api_key: Optional[str],
    region: Optional[str],
    host_override: Optional[str],
+    sql_host_override: Optional[str],
    read_consistency_interval: Optional[float],
    client_config: Optional[Union[ClientConfig, Dict[str, Any]]],
    storage_options: Optional[Dict[str, str]],
@@ -17,8 +17,10 @@ from typing import (
    List,
    Literal,
    Optional,
+    Sequence,
    Union,
 )
+from uuid import UUID

 if sys.version_info >= (3, 12):
    from typing import override
@@ -47,12 +49,21 @@ 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 .sql import AsyncQuery as AsyncSqlQuery
+from .sql import Query as SqlQuery
+from .sql import QueryDescription
 from .materialized_view import (
    AsyncMaterializedView,
    MaterializedView,
    SelectArg,
    normalize_select,
 )
+from .secrets import (
+    EnvVarSecret,
+    SecretInfo,
+    validate_namespace_path,
+    validate_secret_name,
+)
 from .table import (
    AsyncTable,
    LanceTable,
@@ -68,10 +79,11 @@ import deprecation

 if TYPE_CHECKING:
    import pyarrow as pa
+    from .arrow import AsyncRecordBatchReader
    from .pydantic import LanceModel

    from ._lancedb import Connection as LanceDbConnection
-    from ._lancedb import JobDescription, JobInfo
+    from ._lancedb import JobInfo
    from .common import DATA, URI
    from .embeddings import EmbeddingFunctionConfig
    from ._lancedb import Session
@@ -687,15 +699,47 @@ class DBConnection(EnforceOverrides):
        """
        raise NotImplementedError("serialize is not supported for this connection type")

-    def create_function(self, definition: UdfDefinition) -> FunctionVersion:
+    def create_function(
+        self,
+        definition: UdfDefinition,
+        *,
+        secrets: Optional[Sequence[EnvVarSecret]] = None,
+    ) -> 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]:
+        Parameters
+        ----------
+        definition : UdfDefinition
+            A callable decorated with [udf][lancedb.udf].
+        secrets : sequence of EnvVarSecret, optional
+            One [EnvVarSecret][lancedb.secrets.EnvVarSecret] per credential the
+            Function needs, each naming a Secret and the environment variable
+            its value arrives in. The Function's source is unchanged by this;
+            it reads the variable the way it already did.
+
+        Examples
+        --------
+        ```python
+        db.create_secret("openai-prod", os.environ["OPENAI_API_KEY"])
+        db.create_function(
+            analyze_caption,
+            secrets=[
+                EnvVarSecret(secret="openai-prod", env_variable="OPENAI_API_KEY")
+            ],
+        )
+        ```
+        """
+        return self.create_function_async(definition, secrets=secrets).wait()
+
+    def create_function_async(
+        self,
+        definition: UdfDefinition,
+        *,
+        secrets: Optional[Sequence[EnvVarSecret]] = None,
+    ) -> Job[FunctionVersion]:
        """Register a scalar Python UDF through the remote Function catalog.

        Submission returns a typed job. The immutable Function version becomes
@@ -740,26 +784,87 @@ class DBConnection(EnforceOverrides):
            "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.
+    def create_secret(
+        self, name: str, value: str, *, namespace_path: Optional[List[str]] = None
+    ) -> None:
+        """Create a named Secret in this database.

-        The handle is constructed without a server round trip; an unknown id
-        surfaces when the handle is used. Dropping the handle has no effect
-        on the job itself.
+        Fails if the name is taken, so a create never silently becomes a
+        rotation. Nothing reads the value back: it is bound to a Function by
+        name and resolved by the service when that Function runs. Local
+        connections raise ``NotImplementedError``.
        """
-        raise NotImplementedError("job is not supported for this connection type")
+        raise NotImplementedError(
+            "Secret operations are not supported for this connection type"
+        )
+
+    def alter_secret(
+        self, name: str, value: str, *, namespace_path: Optional[List[str]] = None
+    ) -> None:
+        """Replace the credential behind an existing Secret.
+
+        Fails if it does not exist. Every Function bound to the Secret uses the
+        new value from its next job, and no new Function version is created --
+        which is how a rotation reaches columns pinned to a version registered
+        before it. Local connections raise ``NotImplementedError``.
+        """
+        raise NotImplementedError(
+            "Secret operations are not supported for this connection type"
+        )
+
+    def list_secrets(self, *, namespace_path: Optional[List[str]] = None) -> List[str]:
+        """The names of every Secret in this database.
+
+        Names only. No method returns a stored credential, by construction
+        rather than by policy. Local connections raise ``NotImplementedError``.
+        """
+        raise NotImplementedError(
+            "Secret operations are not supported for this connection type"
+        )
+
+    def drop_secret(
+        self, name: str, *, namespace_path: Optional[List[str]] = None
+    ) -> None:
+        """Drop a Secret.
+
+        Functions bound to it fail at their next job, naming the Secret; that
+        is the revocation path. The name becomes free to reuse, and a new
+        Secret under it is picked up by everything still bound to that name.
+        Local connections raise ``NotImplementedError``.
+        """
+        raise NotImplementedError(
+            "Secret operations are not supported for this connection type"
+        )
+
+    def describe_secret(
+        self, name: str, *, namespace_path: Optional[List[str]] = None
+    ) -> SecretInfo:
+        """What this database records about a Secret: name and timestamps.
+
+        Never the value -- there is no code path that could return one. Local
+        connections raise ``NotImplementedError``.
+        """
+        raise NotImplementedError(
+            "Secret operations are not supported for this connection type"
+        )
+
+    def open_job(self, job_id: str) -> Job:
+        """Open a server-side job by id, returning a handle with its record
+        already populated.
+
+        The returned [Job][lancedb.job.Job] answers for its own state,
+        specification, result, failure and event history, so there is no
+        separate connection-level call for any of them.
+
+        Raises `JobNotFoundError` when the server has no such job, the way
+        `open_table` does for a missing table.
+        """
+        raise NotImplementedError("open_job is not supported for this connection type")

    def list_jobs(self) -> List[JobInfo]:
        """List server-side jobs across the database's tables."""
        raise NotImplementedError("list_jobs is not supported for this connection type")

-    def get_job(self, job_id: str) -> Optional[JobDescription]:
-        """Describe a single server-side job by id.
-
-        Returns None when the server has no such job.
-        """
-        raise NotImplementedError("get_job is not supported for this connection type")
-
    def cancel_job(self, job_id: str) -> bool:
        """Request cancellation of a server-side job by id.

@@ -771,14 +876,38 @@ class DBConnection(EnforceOverrides):
            "cancel_job is not supported for this connection type"
        )

-    def job_history(self, job_id: Optional[str] = None) -> List[pa.RecordBatch]:
-        """The lifecycle event history of a server-side job, as Arrow batches.
+    def execute_query(
+        self,
+        query: str,
+        *,
+        default_namespace_path: Optional[List[str]] = None,
+    ) -> pa.RecordBatchReader:
+        """Execute SQL and return a blocking Arrow reader.

-        Lists history across all jobs when `job_id` is None.
+        This submits through :meth:`execute_query_async` and waits until the
+        initial result stream is readable. It does not wait for the full query
+        to finish.
        """
-        raise NotImplementedError(
-            "job_history is not supported for this connection type"
-        )
+        return self.execute_query_async(
+            query,
+            default_namespace_path=default_namespace_path,
+        ).reader()
+
+    def execute_query_async(
+        self,
+        query: str,
+        *,
+        default_namespace_path: Optional[List[str]] = None,
+    ) -> SqlQuery:
+        """Start executing SQL and return its query handle.
+
+        Local connections do not support SQL.
+        """
+        raise NotImplementedError("SQL is not supported for this connection type")
+
+    def describe_query(self, query_id: UUID) -> QueryDescription:
+        """Describe a submitted SQL query by its connection-scoped id."""
+        raise NotImplementedError("SQL is not supported for this connection type")


 class LanceDBConnection(DBConnection):
@@ -875,6 +1004,7 @@ class LanceDBConnection(DBConnection):
                None,
                None,
                None,
+                None,
                read_consistency_interval_secs,
                None,
                storage_options,
@@ -1423,18 +1553,20 @@ class LanceDBConnection(DBConnection):
        )

    @override
-    def job(self, job_id: str) -> Job:
-        """A [Job][lancedb.job.Job] handle for a server-side job by id.
-
-        The handle is constructed without a server round trip; an unknown id
-        surfaces when the handle is used. Dropping the handle has no effect
-        on the job itself.
+    def open_job(self, job_id: str) -> Job:
+        """Open a server-side job by id. See
+        [DBConnection.open_job][lancedb.db.DBConnection.open_job].
        """
-        return Job(self._conn.job(job_id))
+        return Job(LOOP.run(self._conn.open_job(job_id)))

    @override
-    def create_function_async(self, definition: UdfDefinition) -> Job[FunctionVersion]:
-        job = LOOP.run(self._conn.create_function_async(definition))
+    def create_function_async(
+        self,
+        definition: UdfDefinition,
+        *,
+        secrets: Optional[Sequence[EnvVarSecret]] = None,
+    ) -> Job[FunctionVersion]:
+        job = LOOP.run(self._conn.create_function_async(definition, secrets=secrets))
        return Job(job)

    @override
@@ -1449,19 +1581,39 @@ class LanceDBConnection(DBConnection):
    def drop_function(self, name: str, *, version: str) -> bool:
        return LOOP.run(self._conn.drop_function(name, version=version))

+    @override
+    def create_secret(
+        self, name: str, value: str, *, namespace_path: Optional[List[str]] = None
+    ) -> None:
+        LOOP.run(self._conn.create_secret(name, value, namespace_path=namespace_path))
+
+    @override
+    def alter_secret(
+        self, name: str, value: str, *, namespace_path: Optional[List[str]] = None
+    ) -> None:
+        LOOP.run(self._conn.alter_secret(name, value, namespace_path=namespace_path))
+
+    @override
+    def list_secrets(self, *, namespace_path: Optional[List[str]] = None) -> List[str]:
+        return LOOP.run(self._conn.list_secrets(namespace_path=namespace_path))
+
+    @override
+    def drop_secret(
+        self, name: str, *, namespace_path: Optional[List[str]] = None
+    ) -> None:
+        LOOP.run(self._conn.drop_secret(name, namespace_path=namespace_path))
+
+    @override
+    def describe_secret(
+        self, name: str, *, namespace_path: Optional[List[str]] = None
+    ) -> SecretInfo:
+        return LOOP.run(self._conn.describe_secret(name, namespace_path=namespace_path))
+
    @override
    def list_jobs(self) -> List[JobInfo]:
        """List server-side jobs across the database's tables."""
        return LOOP.run(self._conn.list_jobs())

-    @override
-    def get_job(self, job_id: str) -> Optional[JobDescription]:
-        """Describe a single server-side job by id.
-
-        Returns None when the server has no such job.
-        """
-        return LOOP.run(self._conn.get_job(job_id))
-
    @override
    def cancel_job(self, job_id: str) -> bool:
        """Request cancellation of a server-side job by id.
@@ -1472,14 +1624,6 @@ class LanceDBConnection(DBConnection):
        """
        return LOOP.run(self._conn.cancel_job(job_id))

-    @override
-    def job_history(self, job_id: Optional[str] = None) -> List[pa.RecordBatch]:
-        """The lifecycle event history of a server-side job, as Arrow batches.
-
-        Lists history across all jobs when `job_id` is None.
-        """
-        return LOOP.run(self._conn.job_history(job_id))
-
    @override
    def namespace_client(self) -> LanceNamespace:
        """Get the equivalent namespace client for this connection.
@@ -2250,29 +2394,30 @@ class AsyncConnection(object):
            namespace_path = []
        await self._inner.drop_all_tables(namespace_path=namespace_path)

-    def job(self, job_id: str) -> AsyncJob:
-        """An [AsyncJob][lancedb.job.AsyncJob] handle for a server-side job
-        by id.
-
-        The handle is constructed without a server round trip; an unknown id
-        surfaces when the handle is used. Dropping the handle has no effect
-        on the job itself.
+    async def open_job(self, job_id: str) -> AsyncJob:
+        """Open a server-side job by id. See
+        [DBConnection.open_job][lancedb.db.DBConnection.open_job].
        """
-        return AsyncJob(self._inner.job(job_id))
+        return AsyncJob(await self._inner.open_job(job_id))

    async def create_function_async(
-        self, definition: UdfDefinition
+        self,
+        definition: UdfDefinition,
+        *,
+        secrets: Optional[Sequence[EnvVarSecret]] = None,
    ) -> AsyncJob[FunctionVersion]:
        """Register a scalar Python UDF through the remote Function catalog.

        The returned typed job resolves to the immutable Function version.
-        Local connections raise ``NotImplementedError``.
+        ``secrets`` is a sequence of
+        [EnvVarSecret][lancedb.secrets.EnvVarSecret], each naming a Secret and
+        the environment variable its value arrives in. Local connections raise
+        ``NotImplementedError``.
        """
        if not isinstance(definition, UdfDefinition):
            raise TypeError("create_function_async requires a @udf definition")
-        inner = await self._inner.create_function_async(
-            definition.registration_request.to_canonical_json()
-        )
+        request = definition.bind_secrets(secrets)
+        inner = await self._inner.create_function_async(request.to_canonical_json())
        return _typed_job(inner, FunctionVersion.from_json)

    async def get_function(self, name: str, *, version: str) -> FunctionVersion:
@@ -2294,17 +2439,65 @@ class AsyncConnection(object):
        """Drop one exact immutable Function version from the remote catalog."""
        return await self._inner.drop_function(name, version)

+    async def create_secret(
+        self, name: str, value: str, *, namespace_path: Optional[List[str]] = None
+    ) -> None:
+        """Create a named Secret in this database.
+
+        Fails if the name is taken, so a create never silently becomes a
+        rotation. Nothing reads the value back.
+        """
+        await self._inner.create_secret(
+            validate_secret_name(name),
+            value,
+            list(validate_namespace_path(namespace_path)),
+        )
+
+    async def alter_secret(
+        self, name: str, value: str, *, namespace_path: Optional[List[str]] = None
+    ) -> None:
+        """Replace the credential behind an existing Secret.
+
+        Fails if it does not exist. Bound Functions use the new value from
+        their next job, with no new Function version.
+        """
+        await self._inner.alter_secret(
+            validate_secret_name(name),
+            value,
+            list(validate_namespace_path(namespace_path)),
+        )
+
+    async def list_secrets(
+        self, *, namespace_path: Optional[List[str]] = None
+    ) -> List[str]:
+        """The names of every Secret in this database. Names only."""
+        return await self._inner.list_secrets(
+            list(validate_namespace_path(namespace_path))
+        )
+
+    async def drop_secret(
+        self, name: str, *, namespace_path: Optional[List[str]] = None
+    ) -> None:
+        """Drop a Secret. Bound Functions fail at their next job."""
+        await self._inner.drop_secret(
+            validate_secret_name(name), list(validate_namespace_path(namespace_path))
+        )
+
+    async def describe_secret(
+        self, name: str, *, namespace_path: Optional[List[str]] = None
+    ) -> SecretInfo:
+        """What this database records about a Secret. Never the value."""
+        return SecretInfo.from_json(
+            await self._inner.describe_secret(
+                validate_secret_name(name),
+                list(validate_namespace_path(namespace_path)),
+            )
+        )
+
    async def list_jobs(self) -> List[JobInfo]:
        """List server-side jobs across the database's tables."""
        return await self._inner.list_jobs()

-    async def get_job(self, job_id: str) -> Optional[JobDescription]:
-        """Describe a single server-side job by id.
-
-        Returns None when the server has no such job.
-        """
-        return await self._inner.get_job(job_id)
-
    async def cancel_job(self, job_id: str) -> bool:
        """Request cancellation of a server-side job by id.

@@ -2314,12 +2507,46 @@ class AsyncConnection(object):
        """
        return await self._inner.cancel_job(job_id)

-    async def job_history(self, job_id: Optional[str] = None) -> List[pa.RecordBatch]:
-        """The lifecycle event history of a server-side job, as Arrow batches.
+    async def execute_query(
+        self,
+        query: str,
+        *,
+        default_namespace_path: Optional[List[str]] = None,
+    ) -> AsyncRecordBatchReader:
+        """Execute SQL and return an asynchronous Arrow reader.

-        Lists history across all jobs when `job_id` is None.
+        This submits through :meth:`execute_query_async` and waits until the
+        initial result stream is readable. It does not wait for the full query
+        to finish.
        """
-        return await self._inner.job_history(job_id)
+        submitted = await self.execute_query_async(
+            query,
+            default_namespace_path=default_namespace_path,
+        )
+        return await submitted.reader()
+
+    async def execute_query_async(
+        self,
+        query: str,
+        *,
+        default_namespace_path: Optional[List[str]] = None,
+    ) -> AsyncSqlQuery:
+        """Start executing SQL and return its query handle.
+
+        The database from ``connect_async`` is used for unqualified database
+        references. The namespace defaults to ``["public"]``. Local
+        connections raise ``NotImplementedError``.
+        """
+        return AsyncSqlQuery(
+            await self._inner.execute_query_async(
+                query,
+                default_namespace_path=default_namespace_path,
+            )
+        )
+
+    async def describe_query(self, query_id: UUID) -> QueryDescription:
+        """Describe a submitted SQL query by its connection-scoped id."""
+        return await self._inner.describe_query(query_id)

    async def namespace_client(self) -> LanceNamespace:
        """Get the equivalent namespace client for this connection.
@@ -35,3 +35,9 @@ class JobCancelledError(RuntimeError):
    """Exception raised when an asynchronous job was cancelled."""

    pass
+
+
+class JobNotFoundError(ValueError):
+    """Exception raised when opening a job the server does not have."""
+
+    pass
@@ -4,7 +4,7 @@
 """Canonical Function values exchanged with LanceDB Enterprise services.

 These immutable models contain client/wire state only. Catalog persistence,
-environment bake, and execution are owned by Sophon.
+environment bake, secret resolution, and execution are owned by Sophon.
 ``RefreshColumnResult`` is also the backend-neutral result of a local
 expression-backed refresh job.
 """
@@ -25,7 +25,7 @@ import re
 import sys
 import textwrap
 import types
-from collections.abc import Mapping
+from collections.abc import Mapping, Sequence
 from datetime import date, datetime
 from typing import (
    Annotated,
@@ -50,6 +50,7 @@ from pydantic import (
 )

 from .schema import is_blob_v2_field as _is_blob_v2_field
+from .secrets import EnvVarSecret

 _Int32 = conint(strict=True, ge=-(2**31), le=2**31 - 1)
 _UInt32 = conint(strict=True, ge=0, le=2**32 - 1)
@@ -226,6 +227,19 @@ class FunctionOutput(_OpenRemoteValue):
    fields: tuple[FunctionResultField, ...] = ()


+class SecretReference(_RemoteValue):
+    """Where a Secret lives, carried as its parts rather than as one string.
+
+    A joined id would need a delimiter, and a delimiter has to be excluded from
+    every name and segment forever, agreed on by both sides, and re-agreed each
+    time either grows a new way to be configured. Naming the parts settles all
+    of that: nothing here is parsed, so nothing can parse two ways.
+    """
+
+    name: str
+    namespace_path: tuple[str, ...] = ()
+
+
 class FunctionSignature(_RemoteValue):
    inputs: tuple[FunctionParameter, ...]
    output: FunctionOutput
@@ -309,6 +323,7 @@ class FunctionVersion(_RemoteValue):
    runtime: PythonRuntimeSpec
    runtime_digest: str
    environment_digest: str
+    secret_env_bindings: Mapping[str, SecretReference] = {}
    created_at: str

    def __call__(self, **inputs: Any) -> FunctionApplication:
@@ -370,12 +385,18 @@ class FunctionVersion(_RemoteValue):


 class FunctionRegistrationRequest(_RemoteValue):
-    """Stable remote registration envelope produced by :func:`udf`."""
+    """Stable remote registration envelope produced by :func:`udf`.
+
+    Credential values deliberately have no field here. The only secret-shaped
+    thing a client sends is ``secret_env_bindings``: the name of a Secret the
+    database already holds, which the remote service resolves at execution.
+    """

    name: str
    artifact: FunctionArtifactRequest
    signature: FunctionSignature
    runtime: PythonRuntimeSpec
+    secret_env_bindings: Mapping[str, SecretReference] = {}


 class FunctionVersionRef(_OpenRemoteValue):
@@ -470,11 +491,7 @@ class InputBinding(_RemoteValue):


 class OutputMapping(_RemoteValue):
-    """One stable result-field mapping.
-
-    Assignment state is outside the Slice 1 client contract. During the NULL
-    transition Lance exposes no public cell-flag identifier to persist here.
-    """
+    """One stable result-field mapping."""

    result_field: str
    output_name: str
@@ -484,6 +501,13 @@ class OutputMapping(_RemoteValue):
    nullable: bool


+class AssignmentMapping(_RemoteValue):
+    """Internal physical column preserving flattened struct validity."""
+
+    output_name: str
+    output_field_id: _Int32
+
+
 class FunctionBinding(_RemoteValue):
    """Immutable Function binding persisted by the Enterprise table service."""

@@ -491,6 +515,7 @@ class FunctionBinding(_RemoteValue):
    function: FunctionVersionRef
    inputs: tuple[InputBinding, ...]
    outputs: tuple[OutputMapping, ...]
+    assignment: Optional[AssignmentMapping] = None
    input_schema: Optional[Mapping[str, Any]] = None
    output_schema: Optional[Mapping[str, Any]] = None

@@ -520,6 +545,8 @@ class RefreshColumnResult(_RemoteValue):


 _FUNCTION_NAME = re.compile(r"^[A-Za-z_][A-Za-z0-9_.-]*$")
+_DECLARED_SECRET = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
+
 _FUNCTION_BLOB_V2_TYPE = "blob_v2"
 _ARROW_EXTENSION_NAME_KEY = "ARROW:extension:name"
 _BLOB_V2_EXTENSION_NAME = "lance.blob.v2"
@@ -911,8 +938,6 @@ def _function_output(output: pa.DataType | pa.Field | pa.Schema) -> FunctionOutp

    if not fields:
        raise ValueError("named-struct Function output must contain at least one field")
-    if any(field.nullable for field in fields):
-        raise ValueError("Function output fields must be non-nullable")
    for field in fields:
        _validate_exact_arrow_field(field)
    names = [field.name for field in fields]
@@ -924,7 +949,7 @@ def _function_output(output: pa.DataType | pa.Field | pa.Schema) -> FunctionOutp
            FunctionResultField(
                name=field.name,
                arrow_type=_canonical_arrow_field(field),
-                nullable=False,
+                nullable=field.nullable,
            )
            for field in fields
        ),
@@ -1263,9 +1288,63 @@ class UdfDefinition:

    @property
    def registration_request(self) -> FunctionRegistrationRequest:
-        """The immutable request sent by ``create_function_async``."""
+        """The immutable request sent by ``create_function_async``.
+
+        Carries no secret bindings. Binding is a registration-time decision,
+        so a Function bound to Secrets is registered through :meth:`bind_secrets`,
+        which is what ``create_function`` calls.
+        """
        return self._request

+    def bind_secrets(
+        self, secrets: Optional[Sequence[EnvVarSecret]]
+    ) -> FunctionRegistrationRequest:
+        """The registration request for this definition bound to ``secrets``.
+
+        Binding does not change the Function's source: each
+        [EnvVarSecret][lancedb.secrets.EnvVarSecret] names a Secret and the
+        environment variable its value should arrive in, and the Function reads
+        that variable the way it already did. Whether the named Secrets exist is
+        the server's answer, not this one.
+        """
+        bindings = () if secrets is None else tuple(secrets)
+        wrong_type = [
+            binding for binding in bindings if not isinstance(binding, EnvVarSecret)
+        ]
+        if wrong_type:
+            kinds = sorted({type(binding).__name__ for binding in wrong_type})
+            raise TypeError(
+                f"Function secrets must be EnvVarSecret values, not {kinds!r}; a "
+                "credential value is never sent to this API"
+            )
+        variables = [binding.env_variable for binding in bindings]
+        duplicates = sorted({name for name in variables if variables.count(name) > 1})
+        if duplicates:
+            raise ValueError(
+                "a Function binds each environment variable once; duplicated: "
+                f"{duplicates!r}"
+            )
+        # `env` is ordinary configuration carried in the definition, so a name in
+        # both would have a value visible in the Function's record and a value
+        # that is not. Refuse rather than pick.
+        environment = self._request.runtime.env or {}
+        overlap = sorted(set(environment) & set(variables))
+        if overlap:
+            raise ValueError(
+                f"Function env and secret bindings must be disjoint: {overlap!r}"
+            )
+        if not bindings:
+            return self._request
+        # The binding records the full id -- path plus name -- because that is
+        # what the service resolves. At the root it is the bare name.
+        resolved = {
+            binding.env_variable: SecretReference(
+                name=binding.secret, namespace_path=tuple(binding.namespace_path)
+            )
+            for binding in bindings
+        }
+        return self._request._copy(update={"secret_env_bindings": resolved})
+
    def __call__(self, *args, **kwargs):
        return self._function(*args, **kwargs)

@@ -1307,8 +1386,9 @@ def udf(

    Input and output signatures are inferred from supported annotations. For
    Arrow types annotations cannot express precisely, pass ``input_schema``
-    and ``output_schema`` together. Nullable outputs are rejected because V1
-    uses physical NULL to represent unassigned computed-column rows.
+    and ``output_schema`` together. Scalar outputs must be non-nullable. Every
+    named-struct field may be nullable; Enterprise preserves the struct's
+    validity when the result is expanded into sibling columns.

    Parameters
    ----------
@@ -1320,8 +1400,8 @@ def udf(
        Explicit input fields in the exact order of the callable parameters.
        Must be provided together with ``output_schema``.
    output_schema : pyarrow.DataType, pyarrow.Field, or pyarrow.Schema, optional
-        Explicit scalar or named-struct output. Must be non-nullable and be
-        provided together with ``input_schema``.
+        Explicit scalar or named-struct output. Scalar outputs must be
+        non-nullable. Must be provided together with ``input_schema``.
    pip : sequence of str, optional
        Pip requirements for the remote environment.
    conda : sequence of str, optional
@@ -1329,7 +1409,9 @@ def udf(
    conda_channels : sequence of str, optional
        Conda channels in priority order; requires ``conda``.
    env : mapping of str to str, optional
-        Environment variables included in the Function definition.
+        Environment variables included in the Function definition. Not for
+        credentials -- these are ordinary configuration, stored with the
+        Function and visible wherever it is.
    python_version : str, optional
        Remote Python major/minor version. Defaults to the client version.
    gpu : bool, default False
@@ -1387,6 +1469,7 @@ def udf(


 __all__ = [
+    "AssignmentMapping",
    "ApplicationInput",
    "FunctionApplication",
    "FunctionArtifact",
@@ -4,15 +4,27 @@
 """Handles to operations a server may run asynchronously."""

 import asyncio
+import json
 from datetime import timedelta
 from typing import Any, Callable, Generic, Optional, TypeVar, cast

+import pyarrow as pa
+
 from lancedb.background_loop import LOOP

 from . import _lancedb
+from ._lancedb import JobDescription, JobFailureInfo, JobInfo

 T = TypeVar("T")

+__all__ = [
+    "AsyncJob",
+    "Job",
+    "JobDescription",
+    "JobFailureInfo",
+    "JobInfo",
+]
+

 class AsyncJob(Generic[T]):
    """A handle to an operation that may still be running.
@@ -78,6 +90,149 @@ class AsyncJob(Generic[T]):
            return
        await self._inner.cancel()

+    async def refresh(self) -> None:
+        """Ask the backend for this job's current state, and for a server-side
+        job its full record, then cache it for the properties below.
+
+        The properties are all `None` until this runs, because submitting an
+        operation returns only a job id. `status` fetches the whole record too;
+        `wait` records only the terminal state it establishes.
+        """
+        if self._inner is None:
+            return
+        await self._inner.refresh()
+
+    @property
+    def state(self) -> Optional[str]:
+        """The last observed lifecycle state, without contacting the backend.
+
+        `None` until the handle has talked to it. See :meth:`AsyncJob.refresh`.
+        """
+        if self._inner is None:
+            return "finished"
+        return self._inner._state
+
+    @property
+    def job_type(self) -> Optional[str]:
+        """The job's type, as the server names it.
+
+        `None` for an in-process job, which has no server-side record.
+        """
+        return self._field("job_type")
+
+    @property
+    def creation_ms(self) -> Optional[int]:
+        """When the job was created, in milliseconds since the epoch."""
+        return self._field("creation_ms")
+
+    @property
+    def spec(self) -> Optional[Any]:
+        """The job-type-specific specification it was submitted with."""
+        return self._field("spec")
+
+    @property
+    def result(self) -> Optional[Any]:
+        """The job-type-specific terminal result, as reported data rather than
+        the typed model :meth:`AsyncJob.wait` returns.
+
+        `None` until the job succeeds, so a job that never terminates reports
+        its progress through :meth:`AsyncJob.events` instead.
+        """
+        return self._field("result")
+
+    @property
+    def failure(self) -> Optional[JobFailureInfo]:
+        """Why the job failed, when it failed and the server reports a reason."""
+        return self._field("failure")
+
+    @property
+    def _spec_json(self) -> Optional[str]:
+        return self._field("_spec_json")
+
+    @property
+    def _result_json(self) -> Optional[str]:
+        return self._field("_result_json")
+
+    def _field(self, name: str) -> Optional[Any]:
+        description = self._inner._description if self._inner is not None else None
+        return getattr(description, name) if description is not None else None
+
+    async def events(
+        self,
+        *,
+        limit: Optional[int] = None,
+        filter: Optional[str] = None,
+    ) -> "pa.Table":
+        """This job's recorded lifecycle events.
+
+        Where the properties above report a terminal result only once the job
+        reaches one, events are written as the job runs and outlive the workers
+        that produced them. A distributed job records a `claim`/`claim_complete`
+        pair per unit of work, each carrying `rows_processed`, so a job that
+        never finishes still accounts for what it did.
+
+        Parameters
+        ----------
+        limit: int, optional
+            Maximum event rows to return. The server caps results at 1000 by
+            default and 10,000 at most, and truncates without saying so, so
+            pass this for a job that emits an event per fragment.
+        filter: str, optional
+            SQL-like expression over the `state`, `updated_by`, `emitted_from`,
+            `emitted_by`, and `claim_entity` columns, such as
+            ``state = 'claim_complete'``.
+        """
+        if self._inner is None:
+            raise NotImplementedError(
+                "job event history is only available for server-side jobs"
+            )
+        return await self._inner.events(limit=limit, filter=filter)
+
+    def __repr__(self) -> str:
+        return _job_repr("AsyncJob", self)
+
+
+_REPR_INDENT = " " * 4
+
+
+def _repr_payload(value: Any) -> str:
+    """Render a job payload as indented JSON, aligned under its field."""
+    try:
+        rendered = json.dumps(value, indent=4)
+    except TypeError:
+        return repr(value)
+    return rendered.replace("\n", "\n" + _REPR_INDENT)
+
+
+def _job_repr(kind: str, job: Any) -> str:
+    """Render every field the handle currently knows, omitting the rest.
+
+    One field per line, with the JSON payloads indented, because a refresh
+    job's spec and result are the point of printing it.
+    """
+    state = job.state
+    if state is None:
+        # Nothing has been fetched yet, so there is nothing to lay out.
+        known = f"id={job.id!r}, " if job.id is not None else ""
+        return f"{kind}({known}not refreshed)"
+
+    fields = []
+    if job.id is not None:
+        fields.append(f"id={job.id!r}")
+    fields.append(f"state={state!r}")
+    for name in ("job_type", "creation_ms"):
+        value = getattr(job, name)
+        if value is not None:
+            fields.append(f"{name}={value!r}")
+    for name in ("spec", "result"):
+        value = getattr(job, name)
+        if value is not None:
+            fields.append(f"{name}={_repr_payload(value)}")
+    if job.failure is not None:
+        fields.append(f"failure={job.failure!r}")
+    body = "".join(f"\n{_REPR_INDENT}{field}," for field in fields)
+    return f"{kind}({body}\n)"
+

 class Job(Generic[T]):
    """Synchronous counterpart of `AsyncJob` with the same result type."""
@@ -122,6 +277,75 @@ class Job(Generic[T]):
            return
        LOOP.run(self._inner.cancel())

+    def refresh(self) -> None:
+        """Ask the backend for this job's current state and record.
+
+        See :meth:`AsyncJob.refresh`.
+        """
+        if self._inner is None:
+            return
+        LOOP.run(self._inner.refresh())
+
+    @property
+    def state(self) -> Optional[str]:
+        """The last observed lifecycle state. See :attr:`AsyncJob.state`."""
+        return self._inner.state if self._inner is not None else "finished"
+
+    @property
+    def job_type(self) -> Optional[str]:
+        """The job's type. See :attr:`AsyncJob.job_type`."""
+        return self._field("job_type")
+
+    @property
+    def creation_ms(self) -> Optional[int]:
+        """When the job was created. See :attr:`AsyncJob.creation_ms`."""
+        return self._field("creation_ms")
+
+    @property
+    def spec(self) -> Optional[Any]:
+        """The job's specification. See :attr:`AsyncJob.spec`."""
+        return self._field("spec")
+
+    @property
+    def result(self) -> Optional[Any]:
+        """The job's terminal result. See :attr:`AsyncJob.result`."""
+        return self._field("result")
+
+    @property
+    def failure(self) -> Optional[JobFailureInfo]:
+        """Why the job failed. See :attr:`AsyncJob.failure`."""
+        return self._field("failure")
+
+    @property
+    def _spec_json(self) -> Optional[str]:
+        return self._field("_spec_json")
+
+    @property
+    def _result_json(self) -> Optional[str]:
+        return self._field("_result_json")
+
+    def _field(self, name: str) -> Optional[Any]:
+        return getattr(self._inner, name) if self._inner is not None else None
+
+    def events(
+        self,
+        *,
+        limit: Optional[int] = None,
+        filter: Optional[str] = None,
+    ) -> "pa.Table":
+        """This job's recorded lifecycle events.
+
+        See :meth:`AsyncJob.events`.
+        """
+        if self._inner is None:
+            raise NotImplementedError(
+                "job event history is only available for server-side jobs"
+            )
+        return LOOP.run(self._inner.events(limit=limit, filter=filter))
+
+    def __repr__(self) -> str:
+        return _job_repr("Job", self)
+

 def _typed_job(
    inner: "_lancedb.Job", result_decoder: Callable[[str], T]
@@ -12,6 +12,7 @@ from __future__ import annotations

 import sys
 from typing import TYPE_CHECKING, Any, Dict, Iterable, List, Optional, Union
+from uuid import UUID

 if sys.version_info >= (3, 12):
    from typing import override
@@ -48,8 +49,11 @@ from lancedb._lancedb import (
    connect_namespace_client as _connect_namespace_client,
 )
 from lancedb.background_loop import LOOP
+from lancedb.arrow import AsyncRecordBatchReader
 from lancedb.db import AsyncConnection, DBConnection
 from lancedb.job import AsyncJob, Job
+from lancedb.sql import AsyncQuery as AsyncSqlQuery
+from lancedb.sql import QueryDescription
 from lance_namespace import (
    LanceNamespace,
    connect as namespace_connect,
@@ -1447,6 +1451,37 @@ class AsyncLanceNamespaceDBConnection:
            namespace_path=namespace_path, page_token=page_token, limit=limit
        )

+    async def execute_query(
+        self,
+        query: str,
+        *,
+        default_namespace_path: Optional[List[str]] = None,
+    ) -> AsyncRecordBatchReader:
+        """Execute SQL when supported by the underlying connection."""
+        return await self._inner.execute_query(
+            query,
+            default_namespace_path=default_namespace_path,
+        )
+
+    async def execute_query_async(
+        self,
+        query: str,
+        *,
+        default_namespace_path: Optional[List[str]] = None,
+    ) -> AsyncSqlQuery:
+        """Start executing SQL when supported by the underlying connection.
+
+        Namespace-backed local connections do not support SQL.
+        """
+        return await self._inner.execute_query_async(
+            query,
+            default_namespace_path=default_namespace_path,
+        )
+
+    async def describe_query(self, query_id: UUID) -> QueryDescription:
+        """Describe a submitted SQL query when supported."""
+        return await self._inner.describe_query(query_id)
+
    async def namespace_client(self) -> LanceNamespace:
        """Get the namespace client for this connection.

@@ -7,8 +7,18 @@ import json
 import logging
 from concurrent.futures import ThreadPoolExecutor
 import sys
-from typing import TYPE_CHECKING, Any, Dict, Iterable, List, Optional, Union
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Dict,
+    Iterable,
+    List,
+    Optional,
+    Sequence,
+    Union,
+)
 from urllib.parse import urlparse
+from uuid import UUID
 import warnings

 if sys.version_info >= (3, 12):
@@ -25,10 +35,13 @@ from ..common import DATA
 from ..db import DBConnection, LOOP
 from ..functions import FunctionVersion, UdfDefinition
 from ..job import AsyncJob, Job
+from ..sql import Query as SqlQuery
+from ..sql import QueryDescription
 from ..materialized_view import MaterializedView, SelectArg
+from ..secrets import EnvVarSecret, SecretInfo

 if TYPE_CHECKING:
-    from .._lancedb import JobDescription, JobInfo
+    from .._lancedb import JobInfo
 from ..embeddings import EmbeddingFunctionConfig
 from lance_namespace import (
    LanceNamespace,
@@ -116,6 +129,7 @@ class RemoteDBConnection(DBConnection):
        read_timeout: Optional[float] = None,
        storage_options: Optional[Dict[str, str]] = None,
        read_consistency_interval: Optional[timedelta] = None,
+        sql_host_override: Optional[str] = None,
    ):
        """Connect to a remote LanceDB database."""
        if isinstance(client_config, dict):
@@ -161,6 +175,7 @@ class RemoteDBConnection(DBConnection):
        self.api_key = api_key
        self.region = region
        self.host_override = host_override
+        self.sql_host_override = sql_host_override
        self.storage_options = storage_options
        self.db_name = parsed.netloc

@@ -175,6 +190,7 @@ class RemoteDBConnection(DBConnection):
                api_key=api_key,
                region=region,
                host_override=host_override,
+                sql_host_override=sql_host_override,
                client_config=client_config,
                storage_options=storage_options,
                read_consistency_interval=read_consistency_interval,
@@ -193,6 +209,7 @@ class RemoteDBConnection(DBConnection):
                "api_key": self.api_key,
                "region": self.region,
                "host_override": self.host_override,
+                "sql_host_override": self.sql_host_override,
                "client_config": _client_config_to_dict(self.client_config),
                "storage_options": self.storage_options,
            }
@@ -732,18 +749,21 @@ class RemoteDBConnection(DBConnection):
        )

    @override
-    def job(self, job_id: str) -> Job:
-        """A [Job][lancedb.job.Job] handle for a server-side job by id.
-
-        The handle is constructed without a server round trip; an unknown id
-        surfaces when the handle is used. Dropping the handle has no effect
-        on the job itself.
+    def open_job(self, job_id: str) -> Job:
+        """Open a server-side job by id. See
+        [DBConnection.open_job][lancedb.db.DBConnection.open_job].
        """
-        return Job(self._conn.job(job_id))
+        return Job(LOOP.run(self._conn.open_job(job_id)))

    @override
-    def create_function_async(self, definition: UdfDefinition) -> Job[FunctionVersion]:
-        return Job(LOOP.run(self._conn.create_function_async(definition)))
+    def create_function_async(
+        self,
+        definition: UdfDefinition,
+        *,
+        secrets: Optional[Sequence[EnvVarSecret]] = None,
+    ) -> Job[FunctionVersion]:
+        job = LOOP.run(self._conn.create_function_async(definition, secrets=secrets))
+        return Job(job)

    @override
    def get_function(self, name: str, *, version: str) -> FunctionVersion:
@@ -757,19 +777,39 @@ class RemoteDBConnection(DBConnection):
    def drop_function(self, name: str, *, version: str) -> bool:
        return LOOP.run(self._conn.drop_function(name, version=version))

+    @override
+    def create_secret(
+        self, name: str, value: str, *, namespace_path: Optional[List[str]] = None
+    ) -> None:
+        LOOP.run(self._conn.create_secret(name, value, namespace_path=namespace_path))
+
+    @override
+    def alter_secret(
+        self, name: str, value: str, *, namespace_path: Optional[List[str]] = None
+    ) -> None:
+        LOOP.run(self._conn.alter_secret(name, value, namespace_path=namespace_path))
+
+    @override
+    def describe_secret(
+        self, name: str, *, namespace_path: Optional[List[str]] = None
+    ) -> SecretInfo:
+        return LOOP.run(self._conn.describe_secret(name, namespace_path=namespace_path))
+
+    @override
+    def list_secrets(self, *, namespace_path: Optional[List[str]] = None) -> List[str]:
+        return LOOP.run(self._conn.list_secrets(namespace_path=namespace_path))
+
+    @override
+    def drop_secret(
+        self, name: str, *, namespace_path: Optional[List[str]] = None
+    ) -> None:
+        LOOP.run(self._conn.drop_secret(name, namespace_path=namespace_path))
+
    @override
    def list_jobs(self) -> List["JobInfo"]:
        """List server-side jobs across the database's tables."""
        return LOOP.run(self._conn.list_jobs())

-    @override
-    def get_job(self, job_id: str) -> Optional["JobDescription"]:
-        """Describe a single server-side job by id.
-
-        Returns None when the server has no such job.
-        """
-        return LOOP.run(self._conn.get_job(job_id))
-
    @override
    def cancel_job(self, job_id: str) -> bool:
        """Request cancellation of a server-side job by id.
@@ -781,12 +821,35 @@ class RemoteDBConnection(DBConnection):
        return LOOP.run(self._conn.cancel_job(job_id))

    @override
-    def job_history(self, job_id: Optional[str] = None) -> List[pa.RecordBatch]:
-        """The lifecycle event history of a server-side job, as Arrow batches.
+    def execute_query_async(
+        self,
+        query: str,
+        *,
+        default_namespace_path: Optional[List[str]] = None,
+    ) -> SqlQuery:
+        """Start executing SQL through this remote connection.

-        Lists history across all jobs when `job_id` is None.
+        Unqualified tables use this connection's database and the
+        ``["public"]`` namespace by default. Fully qualified table names may
+        reference other databases available to the same deployment.
        """
-        return LOOP.run(self._conn.job_history(job_id))
+        return SqlQuery(
+            LOOP.run(
+                self._conn.execute_query_async(
+                    query,
+                    default_namespace_path=default_namespace_path,
+                )
+            )
+        )
+
+    @override
+    def describe_query(self, query_id: UUID) -> QueryDescription:
+        """Describe a submitted SQL query by its connection-scoped id."""
+        return LOOP.run(
+            self._conn.describe_query(
+                query_id,
+            )
+        )

    @override
    def namespace_client(self) -> LanceNamespace:
@@ -177,4 +177,7 @@ class OAuthProvider(HeaderProvider):
        if not self._current_token:
            raise RuntimeError("Failed to obtain OAuth token")

-        return {"Authorization": f"Bearer {self._current_token}"}
+        return {
+            "Authorization": f"Bearer {self._current_token}",
+            "x-lancedb-credential-type": "oidc",
+        }
@@ -402,7 +402,6 @@ class RemoteTable(Table):
        /,
        *,
        config: IndexConfigType,
-        replace: bool = ...,
        wait_timeout: Optional[timedelta] = ...,
        name: Optional[str] = ...,
        train: bool = ...,
@@ -417,7 +416,7 @@ class RemoteTable(Table):
        index_cache_size: Optional[int] = ...,
        num_partitions: Optional[int] = ...,
        num_sub_vectors: Optional[int] = ...,
-        replace: bool = ...,
+        replace: Optional[bool] = ...,
        accelerator: Optional[str] = ...,
        index_type: Literal[
            "VECTOR", "IVF_FLAT", "IVF_SQ", "IVF_PQ", "IVF_HNSW_SQ", "IVF_HNSW_PQ"
@@ -436,7 +435,7 @@ class RemoteTable(Table):
        index_cache_size: Optional[int] = None,
        num_partitions: Optional[int] = None,
        num_sub_vectors: Optional[int] = None,
-        replace: bool = False,
+        replace: Optional[bool] = None,
        accelerator: Optional[str] = None,
        index_type="vector",
        wait_timeout: Optional[timedelta] = None,
@@ -480,6 +479,7 @@ class RemoteTable(Table):
            vector_column_name,
            accelerator,
            index_cache_size,
+            replace,
        )

        if is_legacy:
@@ -503,6 +503,12 @@ class RemoteTable(Table):
                    "If you have 100M+ vectors to index,"
                    "please contact us at contact@lancedb.com"
                )
+            if replace is not None:
+                logging.warning(
+                    "replace is not supported on LanceDB cloud."
+                    "Existing indexes will always be replaced."
+                )
+
            idx_type = index_type.upper()
            if idx_type == "VECTOR" or idx_type == "IVF_PQ":
                config = IvfPq(
@@ -555,7 +561,7 @@ class RemoteTable(Table):
        column: str,
        *,
        config: IndexConfigType,
-        replace: bool = False,
+        replace: Optional[bool] = None,
        wait_timeout: Optional[timedelta] = None,
        name: Optional[str] = None,
        train: bool = True,
@@ -587,6 +593,7 @@ class RemoteTable(Table):
        vector_column_name: str,
        accelerator: Optional[str],
        index_cache_size: Optional[int],
+        replace: Optional[bool],
    ) -> bool:
        """Detect if this is a legacy create_index call."""
        if config is not None:
@@ -598,6 +605,7 @@ class RemoteTable(Table):
                num_sub_vectors,
                accelerator,
                index_cache_size,
+                replace,
            )
        ):
            return True
@@ -0,0 +1,208 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright The LanceDB Authors
+
+"""Named Secrets, and the bindings that deliver them to Functions.
+
+A Secret is a database-scoped named credential. Nothing in this module holds a
+value: :class:`EnvVarSecret` names one and says which environment variable it
+should arrive in, and the value is resolved by the remote service when a
+Function bound to it runs. No API returns a stored credential, by construction
+rather than by policy -- there is no code path that could.
+"""
+
+from __future__ import annotations
+
+import re
+
+# The same characters LanceDB already admits in a namespace or table name, and
+# no positional rule on top of them: a segment may begin with `_`, `-` or `.`
+# today, so anything narrower would put Secrets out of reach inside namespaces
+# that already exist. Matches the service, which admits the same set.
+_SECRET_NAME = re.compile(r"^[A-Za-z0-9_.-]{1,255}$")
+_ENV_VARIABLE = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
+
+
+def validate_secret_name(name: str) -> str:
+    """Check a Secret name locally and return it unchanged."""
+    if not isinstance(name, str):
+        raise TypeError(f"Secret name must be a string, not {type(name).__name__}")
+    if not _SECRET_NAME.fullmatch(name):
+        raise ValueError(f"invalid Secret name: {name!r}")
+    return name
+
+
+def validate_namespace_path(namespace_path=None):
+    """Check a namespace path locally and return it as a tuple.
+
+    ``None`` and ``[]`` both mean the root namespace. Segments follow the same
+    rule as Secret names: a binding carries the path and the name as separate
+    fields, so neither is ever parsed out of the other.
+    """
+    if namespace_path is None:
+        return ()
+    if isinstance(namespace_path, str):
+        raise TypeError(
+            "namespace_path must be a list of segments, not a string; "
+            f"did you mean [{namespace_path!r}]?"
+        )
+    segments = tuple(namespace_path)
+    for segment in segments:
+        if not isinstance(segment, str):
+            raise TypeError(
+                f"namespace path segment must be a string, not {type(segment).__name__}"
+            )
+        if not _SECRET_NAME.fullmatch(segment):
+            raise ValueError(f"invalid namespace path segment: {segment!r}")
+    return segments
+
+
+def validate_env_variable(name: str) -> str:
+    """Check an environment variable name locally and return it unchanged."""
+    if not isinstance(name, str):
+        raise TypeError(
+            f"environment variable name must be a string, not {type(name).__name__}"
+        )
+    if not _ENV_VARIABLE.fullmatch(name):
+        raise ValueError(f"invalid environment variable name: {name!r}")
+    return name
+
+
+class EnvVarSecret:
+    """A Secret bound to the environment variable a Function's library reads.
+
+    Pass these in the ``secrets`` sequence of
+    [DBConnection.create_function][lancedb.db.DBConnection.create_function]. The
+    Function's source is unchanged by binding: it reads ``OPENAI_API_KEY`` the
+    way it always did, and the binding is what puts a value there.
+
+    This is a local value. Constructing it contacts no server, so it always
+    succeeds and says nothing about whether the Secret exists; that is checked
+    at registration, where a mistyped Secret name surfaces as a clear "does not
+    exist" naming both the Secret and the variable bound to it. A mistyped
+    *variable* name cannot be caught anywhere -- nothing knows which variables a
+    Function reads -- so it surfaces on the first rows instead.
+
+    The type exists so a credential cannot be passed by accident. A bare string
+    in the same position is a plausible-looking mistake with the opposite
+    meaning, and it reads identically in a diff.
+
+    Parameters
+    ----------
+    secret : str
+        The Secret's database-scoped name.
+    env_variable : str
+        The environment variable the Function reads it from.
+
+    Examples
+    --------
+    >>> from lancedb import EnvVarSecret
+    >>> binding = EnvVarSecret(secret="openai-prod", env_variable="OPENAI_API_KEY")
+    >>> binding.secret, binding.env_variable
+    ('openai-prod', 'OPENAI_API_KEY')
+    """
+
+    __slots__ = ("_secret", "_env_variable", "_namespace_path")
+
+    def __init__(self, secret: str, env_variable: str, *, namespace_path=None):
+        self._secret = validate_secret_name(secret)
+        self._env_variable = validate_env_variable(env_variable)
+        self._namespace_path = validate_namespace_path(namespace_path)
+
+    @property
+    def secret(self) -> str:
+        """The Secret's database-scoped name."""
+        return self._secret
+
+    @property
+    def env_variable(self) -> str:
+        """The environment variable the value is delivered in."""
+        return self._env_variable
+
+    @property
+    def namespace_path(self):
+        """The namespace path the Secret is addressed within, root when empty."""
+        return list(self._namespace_path)
+
+    def __repr__(self) -> str:
+        path = (
+            f", namespace_path={list(self._namespace_path)!r}"
+            if self._namespace_path
+            else ""
+        )
+        return (
+            f"EnvVarSecret(secret={self._secret!r}, "
+            f"env_variable={self._env_variable!r}{path})"
+        )
+
+    def __eq__(self, other: object) -> bool:
+        return (
+            isinstance(other, EnvVarSecret)
+            and other._secret == self._secret
+            and other._env_variable == self._env_variable
+            and other._namespace_path == self._namespace_path
+        )
+
+    def __hash__(self) -> int:
+        return hash(
+            (EnvVarSecret, self._secret, self._env_variable, self._namespace_path)
+        )
+
+
+class SecretInfo:
+    """What a database records about a Secret. Never its value.
+
+    Returned by
+    [DBConnection.describe_secret][lancedb.db.DBConnection.describe_secret].
+    """
+
+    __slots__ = ("_name", "_created_at", "_updated_at")
+
+    def __init__(self, name: str, created_at: str, updated_at: str):
+        self._name = name
+        self._created_at = created_at
+        self._updated_at = updated_at
+
+    @property
+    def name(self) -> str:
+        """The Secret's database-scoped name."""
+        return self._name
+
+    @property
+    def created_at(self) -> str:
+        """When the Secret was created, as an RFC 3339 timestamp."""
+        return self._created_at
+
+    @property
+    def updated_at(self) -> str:
+        """When the Secret's value was last rotated, as an RFC 3339 timestamp."""
+        return self._updated_at
+
+    @classmethod
+    def from_json(cls, value: dict) -> "SecretInfo":
+        return cls(
+            name=value["name"],
+            created_at=value["created_at"],
+            updated_at=value["updated_at"],
+        )
+
+    def __repr__(self) -> str:
+        return (
+            f"SecretInfo(name={self._name!r}, created_at={self._created_at!r}, "
+            f"updated_at={self._updated_at!r})"
+        )
+
+    def __eq__(self, other: object) -> bool:
+        return (
+            isinstance(other, SecretInfo)
+            and other._name == self._name
+            and other._created_at == self._created_at
+            and other._updated_at == self._updated_at
+        )
+
+
+__all__ = [
+    "EnvVarSecret",
+    "SecretInfo",
+    "validate_env_variable",
+    "validate_secret_name",
+]
@@ -0,0 +1,88 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright The LanceDB Authors
+
+"""Handles to SQL queries running on a remote database."""
+
+from uuid import UUID
+
+import pyarrow as pa
+
+from lancedb.background_loop import LOOP
+
+from . import _lancedb
+from .arrow import AsyncRecordBatchReader
+
+QueryDescription = _lancedb.QueryDescription
+
+
+class AsyncQuery:
+    """A handle to a submitted SQL query on an asynchronous connection."""
+
+    def __init__(self, inner: "_lancedb.SqlQuery"):
+        self._inner = inner
+
+    @property
+    def id(self) -> UUID:
+        """The stable identifier scoped to the connection that submitted it."""
+        return self._inner.id
+
+    async def describe(self) -> QueryDescription:
+        """Get a point-in-time description of the query."""
+        return await self._inner.describe()
+
+    async def reader(self) -> AsyncRecordBatchReader:
+        """Wait for the initial result stream and return its Arrow reader.
+
+        Results are single-consumer. Calling this method more than once on the
+        same query raises an error. Later batches are streamed as they become
+        available without waiting for the full query to finish.
+        """
+        return AsyncRecordBatchReader(await self._inner.reader())
+
+    async def cancel(self) -> None:
+        """Request cancellation of the query."""
+        await self._inner.cancel()
+
+
+class Query:
+    """Synchronous counterpart of :class:`AsyncQuery`."""
+
+    def __init__(self, inner: AsyncQuery):
+        self._inner = inner
+
+    @property
+    def id(self) -> UUID:
+        """The stable identifier scoped to the connection that submitted it."""
+        return self._inner.id
+
+    def describe(self) -> QueryDescription:
+        """Get a point-in-time description of the query."""
+        return LOOP.run(self._inner.describe())
+
+    def reader(self) -> pa.RecordBatchReader:
+        """Wait for the initial result stream and return a blocking reader.
+
+        Results are single-consumer. Calling this method more than once on the
+        same query raises an error. Later batches block only until they become
+        available, without waiting for the full query to finish.
+        """
+        reader = LOOP.run(self._inner.reader())
+
+        def next_batch():
+            try:
+                return LOOP.run(reader.__anext__())
+            except StopAsyncIteration:
+                return None
+
+        def batches():
+            while (batch := next_batch()) is not None:
+                yield batch
+
+        return pa.RecordBatchReader.from_batches(reader.schema, batches())
+
+    def cancel(self) -> None:
+        """Request cancellation of the query."""
+        LOOP.run(self._inner.cancel())
+
+
+__all__ = ["AsyncQuery", "Query", "QueryDescription"]
@@ -1132,7 +1132,7 @@ class Table(ABC):
        num_partitions: Optional[int] = None,
        num_sub_vectors: Optional[int] = None,
        vector_column_name: str = VECTOR_COLUMN_NAME,
-        replace: bool = False,
+        replace: bool = True,
        accelerator: Optional[str] = None,
        index_cache_size: Optional[int] = None,
        *,
@@ -1166,7 +1166,7 @@ class Table(ABC):
            The index configuration object. If provided, uses the new unified API.
            Can be one of: IvfFlat, IvfPq, IvfSq, IvfRq, HnswPq, HnswSq,
            BTree, Bitmap, LabelList, Fm, FTS.
-        replace : bool, default False
+        replace : bool, default True
            Whether to replace an existing index on this column.
        wait_timeout : timedelta, optional
            Timeout to wait for async indexing to complete.
@@ -1198,7 +1198,7 @@ class Table(ABC):
        column: str,
        *,
        config: IndexConfigType,
-        replace: bool = False,
+        replace: Optional[bool] = None,
        wait_timeout: Optional[timedelta] = None,
        name: Optional[str] = None,
        train: bool = True,
@@ -1260,7 +1260,7 @@ class Table(ABC):
        self,
        column: str,
        *,
-        replace: bool = False,
+        replace: bool = True,
        index_type: ScalarIndexType = "BTREE",
        wait_timeout: Optional[timedelta] = None,
        name: Optional[str] = None,
@@ -1272,7 +1272,7 @@ class Table(ABC):
        column : str
            The column to be indexed.  Must be a boolean, integer, float,
            or string column.
-        replace : bool, default False
+        replace : bool, default True
            Replace the existing index if it exists.
        index_type: Literal["BTREE", "BITMAP", "LABEL_LIST"], default "BTREE"
            The type of index to create.
@@ -1793,6 +1793,9 @@ class Table(ABC):
        The result has the same length and order as ``row_ids``. Null blobs
        produce null slots; valid empty blobs produce ``b""``.

+        ``_rowid`` values stay valid after compaction when the table has stable
+        row ids.
+
        Convenience for small payloads. For large values use
        :meth:`fetch_blob_files`.
        """
@@ -1810,6 +1813,9 @@ class Table(ABC):
        The result has the same length and order as ``requests``; null blobs
        produce null slots and empty ranges on non-null blobs produce ``b""``.

+        ``_rowid`` values stay valid after compaction when the table has stable
+        row ids.
+
        Row IDs can be obtained from a query with ``with_row_id(True)``. This
        API is currently supported only by local tables.
        """
@@ -1825,6 +1831,9 @@ class Table(ABC):
        ``_rowid`` or a ``_lance_row_id`` field on the blob descriptor. Null
        rows are ``None``. Remote tables require LanceDB Cloud server 0.5.0 or
        newer.
+
+        ``_rowid`` values stay valid after compaction when the table has stable
+        row ids.
        """

    @abstractmethod
@@ -2988,7 +2997,7 @@ class LanceTable(Table):
        num_partitions: Optional[int] = None,
        num_sub_vectors: Optional[int] = None,
        vector_column_name: str = VECTOR_COLUMN_NAME,
-        replace: bool = False,
+        replace: bool = True,
        accelerator: Optional[str] = None,
        index_cache_size: Optional[int] = None,
        num_bits: int = 8,
@@ -3030,7 +3039,7 @@ class LanceTable(Table):
            The index configuration object. If provided, uses the new unified API.
            Can be one of: IvfFlat, IvfPq, IvfSq, IvfRq, HnswPq, HnswSq,
            BTree, Bitmap, LabelList, Fm, FTS.
-        replace : bool, default False
+        replace : bool, default True
            Whether to replace an existing index on this column.
        wait_timeout : timedelta, optional
            Timeout to wait for async indexing to complete.
@@ -3169,7 +3178,7 @@ class LanceTable(Table):
        column: str,
        *,
        config: IndexConfigType,
-        replace: bool = False,
+        replace: Optional[bool] = None,
        wait_timeout: Optional[timedelta] = None,
        name: Optional[str] = None,
        train: bool = True,
@@ -3424,7 +3433,7 @@ class LanceTable(Table):
        self,
        column: str,
        *,
-        replace: bool = False,
+        replace: bool = True,
        index_type: ScalarIndexType = "BTREE",
        name: Optional[str] = None,
    ):
@@ -5313,7 +5322,7 @@ class AsyncTable:
        self,
        column: str,
        *,
-        replace: bool = False,
+        replace: Optional[bool] = None,
        config: Optional[
            Union[
                IvfFlat,
@@ -5344,14 +5353,14 @@ class AsyncTable:
        ----------
        column: str
            The column to index.
-        replace: bool, default False
+        replace: bool, default True
            Whether to replace the existing index

            If this is false, and another index already exists on the same columns
            and the same name, then an error will be returned.  This is true even if
            that index is out of date.

-            The default is False
+            The default is True
        config: default None
            For advanced configuration you can specify the type of index you would
            like to create.   You can also specify index-specific parameters when
@@ -5409,7 +5418,7 @@ class AsyncTable:
        self,
        column: str,
        *,
-        replace: bool = False,
+        replace: Optional[bool] = None,
        config: Optional[
            Union[
                IvfFlat,
@@ -66,6 +66,25 @@ def _row_ids_by_id(table):
    return dict(zip(hits["id"].to_pylist(), hits["_rowid"].to_pylist()))


+def _assert_missing_blob_row_ids(exc_info):
+    message = str(exc_info.value)
+    assert "row ids" in message
+    assert "rowaddr" not in message
+    assert "fragment" not in message
+
+
+def _assert_fetch_apis_reject_missing_row_ids(table, row_ids):
+    with pytest.raises(ValueError) as exc_info:
+        table.fetch_blobs("image", row_ids)
+    _assert_missing_blob_row_ids(exc_info)
+    with pytest.raises(ValueError) as exc_info:
+        table.fetch_blob_files("image", row_ids)
+    _assert_missing_blob_row_ids(exc_info)
+    with pytest.raises(ValueError) as exc_info:
+        table.fetch_blob_ranges("image", [(row_id, 0, 1) for row_id in row_ids])
+    _assert_missing_blob_row_ids(exc_info)
+
+
 def test_blob_factory_declares_v2_field():
    field = lancedb.blob("image")
    assert isinstance(field.type, pa.ExtensionType)
@@ -691,6 +710,25 @@ def test_fetch_blobs_accepts_query_result():
    assert {blobs[i].as_py() for i in range(len(blobs))} == {b"gamma"}


+def test_fetch_blobs_after_compact_with_stable_row_ids(tmp_path):
+    db = lancedb.connect(
+        tmp_path, storage_options={"new_table_enable_stable_row_ids": "true"}
+    )
+    schema = pa.schema([pa.field("id", pa.int64()), lancedb.blob("image")])
+    table = db.create_table("t", schema=schema)
+    table.add([{"id": 1, "image": b"frag-one"}])
+    table.add([{"id": 2, "image": b"frag-two"}])
+    by_id = _row_ids_by_id(table)
+    ids = [by_id[1], by_id[2]]
+
+    table.optimize()
+
+    blobs = table.fetch_blobs("image", ids)
+    assert blobs.to_pylist() == [b"frag-one", b"frag-two"]
+    ranges = table.fetch_blob_ranges("image", [(ids[0], 5, 3), (ids[1], 5, 3)])
+    assert ranges.to_pylist() == [b"one", b"two"]
+
+
 def test_fetch_blobs_preserves_null_and_empty_values():
    table = _blob_table(
        "nulls",
@@ -739,8 +777,25 @@ def test_fetch_blob_ranges_validates_requests():
    with pytest.raises(ValueError, match="offset \\+ length overflowed"):
        table.fetch_blob_ranges("image", [(row_id, 2**64 - 1, 1)])

-    with pytest.raises(ValueError, match="row IDs"):
+    with pytest.raises(ValueError) as exc_info:
        table.fetch_blob_ranges("image", [(2**64 - 1, 0, 1)])
+    _assert_missing_blob_row_ids(exc_info)
+
+
+def test_fetch_blob_apis_reject_missing_fragment_row_addr():
+    table = _blob_table("missing_frag", [{"id": 1, "image": b"x"}])
+    live = _row_ids_by_id(table)[1]
+    _assert_fetch_apis_reject_missing_row_ids(table, [1 << 32, live])
+
+
+def test_fetch_blob_apis_reject_deleted_row_ids():
+    table = _blob_table(
+        "deleted_rows",
+        [{"id": 1, "image": b"one"}, {"id": 2, "image": b"two"}],
+    )
+    by_id = _row_ids_by_id(table)
+    table.delete("id = 2")
+    _assert_fetch_apis_reject_missing_row_ids(table, [by_id[2], by_id[1]])


 def test_fetch_blob_ranges_empty_requests_returns_empty_array():
@@ -14,6 +14,7 @@ from lancedb.functions import (
    FunctionVersion,
    PythonRuntimeSpec,
    RefreshColumnResult,
+    SecretReference,
 )
 from lancedb.table import AsyncTable

@@ -37,6 +38,22 @@ def job_result(name: str) -> dict:
    return json.loads(fixture(name))["result"]


+def assert_no_secret_values(value):
+    """No client value models a resolved credential, at any nesting depth."""
+    if isinstance(value, dict):
+        for key, child in value.items():
+            assert key not in {
+                "secret_value",
+                "secret_values",
+                "resolved_secret",
+                "resolved_secrets",
+            }
+            assert_no_secret_values(child)
+    elif isinstance(value, list):
+        for child in value:
+            assert_no_secret_values(child)
+
+
 def test_public_function_values_are_in_api_reference():
    docs = Path(__file__).parents[3] / "docs" / "src" / "python" / "python.md"
    rendered = docs.read_text()
@@ -94,6 +111,9 @@ def test_function_version_identity_is_immutable_and_exact():
    version = FunctionVersion.from_json(json.dumps(value))
    assert version.name == "embed"
    assert version.version == "fv_01K3EXACT"
+    assert dict(version.secret_env_bindings) == {
+        "HF_TOKEN": SecretReference(name="hf-prod")
+    }

    with pytest.raises((TypeError, ValueError)):
        version.version = "fv_changed"
@@ -276,6 +296,25 @@ def test_refresh_result_rejects_non_u64_values(field):
        RefreshColumnResult.from_json(json.dumps(value))


+def test_canonical_client_values_carry_bindings_and_no_credentials():
+    """A binding names a Secret; the credential behind it has no client field."""
+    version = FunctionVersion.from_json(
+        json.dumps(job_result("remote_function_job.json"))
+    )
+    canonical = json.loads(version.to_canonical_json())
+    assert canonical["secret_env_bindings"] == {"HF_TOKEN": {"name": "hf-prod"}}
+    assert_no_secret_values(canonical)
+
+
+def test_a_version_without_bindings_keeps_the_original_wire_shape():
+    """Every Function registered before Secrets existed serializes unchanged."""
+    value = job_result("remote_function_job.json")
+    del value["secret_env_bindings"]
+    version = FunctionVersion.from_json(json.dumps(value))
+    assert dict(version.secret_env_bindings) == {}
+    assert "secret_env_bindings" not in json.loads(version.to_canonical_json())
+
+
 class _FunctionDeclarationInner:
    def __init__(self):
        self.calls = []
@@ -11,6 +11,7 @@ import types
 from datetime import date
 import http.server
 import json
+import os
 from pathlib import Path
 import subprocess
 import sys
@@ -21,13 +22,16 @@ import pyarrow as pa
 import pytest

 import lancedb
+from lancedb.background_loop import LOOP
 from lancedb.functions import (
    PythonRuntimeSpec,
+    SecretReference,
    UdfDefinition,
    _canonical_arrow_type,
    _GRAMMAR_PRIMITIVES,
    udf,
 )
+from lancedb.secrets import EnvVarSecret

 THRESHOLD = 20
 _CACHE = None
@@ -53,6 +57,15 @@ def normalize_score(value: float) -> float:
    return value / 100.0


+@udf(
+    pip=["openai==3.7.0"],
+    env={"MODE": "test"},
+    python_version="3.12",
+)
+def analyze_caption(caption: str) -> str:
+    return caption.strip()
+
+
 def test_scalar_udf_matches_shared_registration_golden_and_remains_callable():
    assert isinstance(normalize_score, UdfDefinition)
    assert normalize_score(25.0) == 0.25
@@ -69,6 +82,298 @@ def test_scalar_udf_matches_shared_registration_golden_and_remains_callable():
    }


+def test_secret_bound_udf_matches_its_shared_registration_golden():
+    assert analyze_caption("  hello  ") == "hello"
+    bound = analyze_caption.bind_secrets(
+        [EnvVarSecret(secret="openai-prod", env_variable="OPENAI_API_KEY")]
+    )
+    assert (
+        bound.to_canonical_json()
+        == (FIXTURES / "remote_function_secret_registration_request.canonical.json")
+        .read_text()
+        .strip()
+    )
+
+
+def test_a_namespaced_binding_records_the_path_and_the_name():
+    """A binding names the parts, so nothing has to be parsed back out.
+
+    A root binding carries no path at all, which is what keeps its wire shape
+    identical to one written before namespaces existed.
+    """
+    root = EnvVarSecret(secret="openai-prod", env_variable="OPENAI_API_KEY")
+    assert root.namespace_path == []
+
+    nested = EnvVarSecret(
+        secret="openai-prod",
+        env_variable="OPENAI_API_KEY",
+        namespace_path=["prod", "vision"],
+    )
+    assert nested.namespace_path == ["prod", "vision"]
+    assert nested != root
+
+    bound = analyze_caption.bind_secrets([nested])
+    assert bound.secret_env_bindings == {
+        "OPENAI_API_KEY": SecretReference(
+            name="openai-prod", namespace_path=("prod", "vision")
+        )
+    }
+
+    at_root = analyze_caption.bind_secrets([root])
+    assert at_root.secret_env_bindings == {
+        "OPENAI_API_KEY": SecretReference(name="openai-prod")
+    }
+    canonical = json.loads(at_root.to_canonical_json())
+    assert canonical["secret_env_bindings"] == {
+        "OPENAI_API_KEY": {"name": "openai-prod"}
+    }
+
+
+def test_a_namespace_path_is_validated_locally():
+    # The charset is the service's, not a delimiter's: a reference is never
+    # joined, so a segment cannot make anything parse two ways.
+    with pytest.raises(ValueError):
+        EnvVarSecret(
+            secret="openai-prod", env_variable="K", namespace_path=["with$delim"]
+        )
+    with pytest.raises(ValueError):
+        EnvVarSecret(secret="openai-prod", env_variable="K", namespace_path=["a/b"])
+    # A bare string is a plausible mistake with the wrong meaning.
+    with pytest.raises(TypeError):
+        EnvVarSecret(secret="openai-prod", env_variable="K", namespace_path="prod")
+
+
+def test_an_unbound_request_carries_no_binding_at_all():
+    """Binding is a registration-time decision, so the definition holds none.
+
+    The decorator declares nothing about secrets, which is what makes the PRD's
+    claim true: a Function's source and its registration request are identical
+    whether or not a credential is later bound to it.
+    """
+    unbound = json.loads(analyze_caption.registration_request.to_canonical_json())
+    assert "secret_env_bindings" not in unbound
+    assert "OPENAI_API_KEY" not in json.dumps(unbound)
+
+
+def test_binding_a_secret_leaves_the_packaged_artifact_untouched():
+    """The artifact is source bytes and nothing else, with or without secrets."""
+    bound = analyze_caption.bind_secrets(
+        [EnvVarSecret(secret="openai-prod", env_variable="OPENAI_API_KEY")]
+    )
+    assert bound.artifact == analyze_caption.registration_request.artifact
+    assert bound.artifact.digest == analyze_caption.registration_request.artifact.digest
+
+
+def test_a_function_declaring_no_secret_is_registered_exactly_as_before():
+    """The compatibility claim: nothing about the no-secret path moves."""
+    assert (
+        normalize_score.bind_secrets(None).to_canonical_json()
+        == normalize_score.registration_request.to_canonical_json()
+    )
+    assert (
+        "secret_env_bindings"
+        not in normalize_score.registration_request.to_canonical_json()
+    )
+
+
+def test_a_function_binds_each_variable_once():
+    with pytest.raises(ValueError, match="binds each environment variable once"):
+        analyze_caption.bind_secrets(
+            [
+                EnvVarSecret(secret="openai-prod", env_variable="OPENAI_API_KEY"),
+                EnvVarSecret(secret="openai-staging", env_variable="OPENAI_API_KEY"),
+            ]
+        )
+
+
+def test_bindings_may_not_collide_with_plain_configuration():
+    """`env` is stored with the Function; a Secret is not. Refuse, do not pick."""
+    with pytest.raises(ValueError, match="must be disjoint"):
+        analyze_caption.bind_secrets(
+            [EnvVarSecret(secret="mode-prod", env_variable="MODE")]
+        )
+
+
+def test_a_function_binds_at_most_sixteen_secrets():
+    """The cap lives in Rust, so no language surface can be talked past it.
+
+    Registering through the typed API and hand-rolling the request envelope
+    reach the same boundary, and neither reaches the wire.
+    """
+    bindings = [
+        EnvVarSecret(secret=f"secret-{index}", env_variable=f"TOKEN_{index}")
+        for index in range(17)
+    ]
+    with _mock_remote_function_catalog() as (host, state):
+        db = lancedb.connect(
+            "db://dev",
+            api_key="fake",
+            host_override=host,
+            client_config={"retry_config": {"retries": 0}},
+        )
+        with pytest.raises(ValueError, match="at most 16 secrets"):
+            db.create_function(normalize_score, secrets=bindings)
+
+        envelope = json.loads(normalize_score.registration_request.to_canonical_json())
+        envelope["secret_env_bindings"] = {
+            f"TOKEN_{index}": {"name": f"secret-{index}"} for index in range(17)
+        }
+
+        async def submit_envelope():
+            return await db._conn._inner.create_function_async(json.dumps(envelope))
+
+        with pytest.raises(ValueError, match="at most 16 secrets"):
+            LOOP.run(submit_envelope())
+
+    assert state["requests"] == []
+
+
+def test_binding_names_are_validated_below_the_python_api():
+    """The low-level entry point reaches the same validator the typed API does.
+
+    Registration envelopes can be hand-rolled past ``bind_secrets``, so the
+    grammar and the disjointness rule live in Rust, above the backend.
+    """
+    with _mock_remote_function_catalog() as (host, state):
+        db = lancedb.connect(
+            "db://dev",
+            api_key="fake",
+            host_override=host,
+            client_config={"retry_config": {"retries": 0}},
+        )
+        envelope = json.loads(analyze_caption.registration_request.to_canonical_json())
+        envelope["secret_env_bindings"] = {
+            "BAD=NAME": {"name": "openai-prod"},
+            "TOKEN_0": {"name": "secret-0"},
+        }
+        envelope["runtime"]["env"]["TOKEN_0"] = "public"
+
+        async def submit_envelope():
+            return await db._conn._inner.create_function_async(json.dumps(envelope))
+
+        with pytest.raises(ValueError, match="portable"):
+            LOOP.run(submit_envelope())
+
+    assert state["requests"] == []
+
+
+_SECRET_DEBUG_LOG_SOURCE = """
+import http.server
+import json
+import threading
+
+import lancedb
+
+
+class Handler(http.server.BaseHTTPRequestHandler):
+    def log_message(self, *args):
+        pass
+
+    def do_POST(self):
+        self.rfile.read(int(self.headers.get("Content-Length", "0")))
+        payload = json.dumps({}).encode()
+        self.send_response(200)
+        self.send_header("Content-Type", "application/json")
+        self.send_header("Content-Length", str(len(payload)))
+        self.end_headers()
+        self.wfile.write(payload)
+
+
+server = http.server.ThreadingHTTPServer(("localhost", 0), Handler)
+threading.Thread(target=server.serve_forever, daemon=True).start()
+try:
+    db = lancedb.connect(
+        "db://dev",
+        api_key="API_KEY_SENTINEL",
+        host_override="http://localhost:%d" % server.server_address[1],
+        client_config={"retry_config": {"retries": 0}},
+    )
+    db.create_secret("openai-prod", "SECRET_VALUE_SENTINEL")
+finally:
+    server.shutdown()
+"""
+
+
+def test_a_credential_never_reaches_a_debug_log(tmp_path):
+    """The logger sees the serialized body, so no value-side redaction reaches it.
+
+    Runs in a subprocess because the Rust logger reads ``LANCEDB_LOG`` once, at
+    import.
+    """
+    script = tmp_path / "write_secret.py"
+    script.write_text(_SECRET_DEBUG_LOG_SOURCE)
+
+    result = subprocess.run(
+        [sys.executable, str(script)],
+        check=True,
+        capture_output=True,
+        text=True,
+        env={**os.environ, "LANCEDB_LOG": "debug"},
+    )
+    output = result.stdout + result.stderr
+
+    # Without this the test passes when debug logging is simply off.
+    assert "Sending request_id=" in output, output
+    assert "SECRET_VALUE_SENTINEL" not in output
+    assert "API_KEY_SENTINEL" not in output
+
+
+def test_a_credential_value_is_rejected_in_the_binding_position():
+    """The one mistake the typed binding exists to stop."""
+    with pytest.raises(TypeError, match="EnvVarSecret"):
+        analyze_caption.bind_secrets(["sk-live-0001"])
+
+
+@pytest.mark.parametrize(
+    ("secret", "variable", "message"),
+    [
+        ("openai-prod", "not-a-var", "invalid environment variable name"),
+        ("openai-prod", "API-TOKEN", "invalid environment variable name"),
+        ("not a name", "API_TOKEN", "invalid Secret name"),
+        ("openai$prod", "API_TOKEN", "invalid Secret name"),
+    ],
+)
+def test_a_binding_validates_both_names_locally(secret, variable, message):
+    with pytest.raises(ValueError, match=message):
+        EnvVarSecret(secret=secret, env_variable=variable)
+
+
+def test_a_secret_name_admits_what_a_namespace_name_does():
+    """A Secret has to be nameable wherever a namespace already is.
+
+    LanceDB namespace and table names are `[A-Za-z0-9_.-]` with no rule about
+    which character comes first, so a name may lead with `_`, `-` or `.`.
+    Anything narrower here would leave Secrets unaddressable inside namespaces
+    that already exist -- the reason periods are admitted is the reason the
+    edges are too.
+    """
+    for name in ["openai.prod.v1", ".hidden", "_internal", "-lead", "trailing."]:
+        binding = EnvVarSecret(secret=name, env_variable="OPENAI_API_KEY")
+        assert binding.secret == name
+
+    for name in ["", "with/slash", "with$delimiter", "a" * 256]:
+        with pytest.raises(ValueError, match="invalid Secret name"):
+            EnvVarSecret(secret=name, env_variable="OPENAI_API_KEY")
+
+    # A namespace segment follows the same rule, and LanceDB already admits
+    # these shapes as namespace names -- so a Secret is addressable inside one.
+    for segment in [".hidden", "_internal", "-lead", "trailing."]:
+        binding = EnvVarSecret(
+            secret="openai-prod",
+            env_variable="OPENAI_API_KEY",
+            namespace_path=[segment],
+        )
+        assert binding.namespace_path == [segment]
+
+    for segment in ["", "with/slash", "with$delimiter"]:
+        with pytest.raises(ValueError, match="invalid namespace path segment"):
+            EnvVarSecret(
+                secret="openai-prod",
+                env_variable="OPENAI_API_KEY",
+                namespace_path=[segment],
+            )
+
+
 def _main_udf_source(
    *, threshold: int = 20, input_annotation: str = "int", comparison: str = ">="
 ) -> str:
@@ -850,6 +1155,43 @@ def test_named_struct_function_can_include_a_blob_result_field():
    ]


+def test_named_struct_function_preserves_nullable_result_fields():
+    @udf(
+        input_schema=pa.schema([pa.field("value", pa.int64(), nullable=False)]),
+        output_schema=pa.schema(
+            [
+                pa.field("result", pa.int64(), nullable=True),
+                pa.field("failure_code", pa.int32(), nullable=False),
+            ]
+        ),
+    )
+    def nullable_result(value):
+        return {"result": value, "failure_code": 0}
+
+    output = nullable_result.registration_request.signature.output
+    assert [(field.name, field.nullable) for field in output.fields] == [
+        ("result", True),
+        ("failure_code", False),
+    ]
+
+    @udf(
+        input_schema=pa.schema([pa.field("value", pa.int64(), nullable=False)]),
+        output_schema=pa.schema(
+            [
+                pa.field("result", pa.int64(), nullable=True),
+                pa.field("failure_code", pa.int32(), nullable=True),
+            ]
+        ),
+    )
+    def all_nullable(value):
+        return {"result": value, "failure_code": None}
+
+    assert all(
+        field.nullable
+        for field in all_nullable.registration_request.signature.output.fields
+    )
+
+
 def test_metadata_marked_blob_field_uses_the_semantic_type():
    extension = lancedb.blob("image", nullable=False).type
    storage = (
@@ -1193,6 +1535,7 @@ def _mock_remote_function_catalog():
                    "runtime": body["runtime"],
                    "runtime_digest": "sha256:runtime",
                    "environment_digest": "sha256:environment",
+                    "secret_env_bindings": body.get("secret_env_bindings", {}),
                    "created_at": "2026-08-21T00:00:00Z",
                }
                response = {"job_id": "job-register"}
@@ -1233,6 +1576,21 @@ def _mock_remote_function_catalog():
                    "version": "fv_exact",
                }
                response = {"dropped": True}
+            elif self.path in ("/v1/secrets/create", "/v1/secrets/alter"):
+                assert set(body) == {"name", "value"}
+                response = {}
+            elif self.path == "/v1/secrets/list":
+                if "page_token" not in body:
+                    response = {
+                        "secrets": [{"name": "openai-prod"}],
+                        "page_token": "next",
+                    }
+                else:
+                    assert body["page_token"] == "next"
+                    response = {"secrets": [{"name": "hf-prod"}]}
+            elif self.path == "/v1/secrets/drop":
+                assert body == {"name": "openai-prod"}
+                response = {}
            else:
                status = 404
                response = {"error": "not found"}
@@ -1275,6 +1633,75 @@ def test_remote_registration_job_and_exact_version_reopen_round_trip():
    )


+def test_remote_registration_sends_bindings_and_never_a_credential():
+    with _mock_remote_function_catalog() as (host, state):
+        db = lancedb.connect(
+            "db://dev",
+            api_key="fake",
+            host_override=host,
+            client_config={"retry_config": {"retries": 0}},
+        )
+        created = db.create_function(
+            analyze_caption,
+            secrets=[EnvVarSecret(secret="openai-prod", env_variable="OPENAI_API_KEY")],
+        )
+
+    assert dict(created.secret_env_bindings) == {
+        "OPENAI_API_KEY": SecretReference(name="openai-prod")
+    }
+    path, create_request = state["requests"][0]
+    assert path == "/v1/functions/create"
+    assert create_request["secret_env_bindings"] == {
+        "OPENAI_API_KEY": {"name": "openai-prod"}
+    }
+    # The request names a Secret and carries nothing that could be one.
+    assert create_request == json.loads(
+        analyze_caption.bind_secrets(
+            [EnvVarSecret(secret="openai-prod", env_variable="OPENAI_API_KEY")]
+        ).to_canonical_json()
+    )
+
+
+def test_remote_secret_verbs_round_trip():
+    with _mock_remote_function_catalog() as (host, state):
+        db = lancedb.connect(
+            "db://dev",
+            api_key="fake",
+            host_override=host,
+            client_config={"retry_config": {"retries": 0}},
+        )
+        assert db.create_secret("openai-prod", "sk-live-0001") is None
+        assert db.alter_secret("openai-prod", "sk-live-0002") is None
+        assert db.list_secrets() == ["openai-prod", "hf-prod"]
+        assert db.drop_secret("openai-prod") is None
+
+    routes = [path for path, _ in state["requests"]]
+    assert routes == [
+        "/v1/secrets/create",
+        "/v1/secrets/alter",
+        "/v1/secrets/list",
+        "/v1/secrets/list",
+        "/v1/secrets/drop",
+    ]
+    assert state["requests"][0][1] == {"name": "openai-prod", "value": "sk-live-0001"}
+    # The listing returns names, and the client has no way to ask for more.
+    assert state["requests"][2][1] == {}
+
+
+def test_building_a_binding_contacts_no_server():
+    """A binding is a local value: it says nothing about whether the Secret exists.
+
+    Existence is the server's answer at registration, where a mistyped name is a
+    clear error rather than a client-side check that was already stale.
+    """
+    with _mock_remote_function_catalog() as (_host, state):
+        binding = EnvVarSecret(secret="openai-prod", env_variable="OPENAI_API_KEY")
+        assert binding.secret == "openai-prod"
+        assert binding.env_variable == "OPENAI_API_KEY"
+
+    assert state["requests"] == []
+
+
 def test_blocking_remote_registration_returns_function_version():
    with _mock_remote_function_catalog() as (host, state):
        db = lancedb.connect(
@@ -54,7 +54,10 @@ class TestOAuthProvider:
        provider = OAuthProvider(fetcher)
        headers = provider.get_headers()

-        assert headers == {"Authorization": "Bearer token123"}
+        assert headers == {
+            "Authorization": "Bearer token123",
+            "x-lancedb-credential-type": "oidc",
+        }
        assert provider._current_token == "token123"
        assert provider._token_expires_at is not None

@@ -73,14 +76,20 @@ class TestOAuthProvider:

        # First call
        headers1 = provider.get_headers()
-        assert headers1 == {"Authorization": "Bearer token1"}
+        assert headers1 == {
+            "Authorization": "Bearer token1",
+            "x-lancedb-credential-type": "oidc",
+        }

        # Wait for token to expire
        time.sleep(1.1)

        # Second call should refresh
        headers2 = provider.get_headers()
-        assert headers2 == {"Authorization": "Bearer token2"}
+        assert headers2 == {
+            "Authorization": "Bearer token2",
+            "x-lancedb-credential-type": "oidc",
+        }
        assert call_count == 2

    def test_no_expiry_info(self):
@@ -92,12 +101,18 @@ class TestOAuthProvider:
        provider = OAuthProvider(fetcher)
        headers = provider.get_headers()

-        assert headers == {"Authorization": "Bearer permanent_token"}
+        assert headers == {
+            "Authorization": "Bearer permanent_token",
+            "x-lancedb-credential-type": "oidc",
+        }
        assert provider._token_expires_at is None

        # Should not refresh on second call
        headers2 = provider.get_headers()
-        assert headers2 == {"Authorization": "Bearer permanent_token"}
+        assert headers2 == {
+            "Authorization": "Bearer permanent_token",
+            "x-lancedb-credential-type": "oidc",
+        }

    def test_missing_access_token(self):
        """Test error handling when access_token is missing."""
@@ -121,7 +136,10 @@ class TestOAuthProvider:
        provider = OAuthProvider(fetcher)
        headers = provider.get_headers()

-        assert headers == {"Authorization": "Bearer sync_token"}
+        assert headers == {
+            "Authorization": "Bearer sync_token",
+            "x-lancedb-credential-type": "oidc",
+        }


 class TestClientConfigIntegration:
@@ -97,9 +97,6 @@ async def test_create_index_async_returns_done_job(some_table: AsyncTable):
 async def test_create_scalar_index(some_table: AsyncTable):
    # Can create
    await some_table.create_index("id")
-    # Can't recreate by default
-    with pytest.raises(RuntimeError, match="already exists"):
-        await some_table.create_index("id")
    # Can recreate if replace=True
    await some_table.create_index("id", replace=True)
    indices = await some_table.list_indices()
@@ -113,7 +110,7 @@ async def test_create_scalar_index(some_table: AsyncTable):
    with pytest.raises(RuntimeError, match="already exists"):
        await some_table.create_index("id", replace=False)
    # can also specify index type
-    await some_table.create_index("id", config=BTree(), replace=True)
+    await some_table.create_index("id", config=BTree())

    await some_table.drop_index("id_idx")
    indices = await some_table.list_indices()
@@ -354,18 +351,13 @@ async def test_full_text_search_index(some_table: AsyncTable):
 async def test_create_vector_index(some_table: AsyncTable):
    # Can create
    await some_table.create_index("vector")
-    # Can't recreate by default
-    with pytest.raises(RuntimeError, match="already exists"):
-        await some_table.create_index("vector")
    # Can recreate if replace=True
    await some_table.create_index("vector", replace=True)
    # Can't recreate if replace=False
    with pytest.raises(RuntimeError, match="already exists"):
        await some_table.create_index("vector", replace=False)
    # Can also specify index type
-    await some_table.create_index(
-        "vector", config=IvfPq(num_partitions=100), replace=True
-    )
+    await some_table.create_index("vector", config=IvfPq(num_partitions=100))
    indices = await some_table.list_indices()
    assert len(indices) == 1
    assert indices[0].index_type == "IvfPq"
@@ -834,7 +834,7 @@ def test_table_create_indices():
        vector_req = received_requests[2]
        assert "name" in vector_req
        assert vector_req["name"] == "custom_vector_idx"
-        assert vector_req["replace"] is False
+        assert "replace" not in vector_req

        table.wait_for_index(["custom_scalar_idx"], timedelta(seconds=2))
        table.wait_for_index(
@@ -2467,7 +2467,7 @@ def test_remote_blob_byte_apis_not_supported_on_old_server():


 def test_remote_connection_jobs_surface():
-    from lancedb.exceptions import JobFailedError
+    from lancedb.exceptions import JobFailedError, JobNotFoundError

    schema = pa.schema([("state", pa.string())])
    batch = pa.record_batch([pa.array(["created", "done"])], schema=schema)
@@ -2475,6 +2475,7 @@ def test_remote_connection_jobs_surface():
    with pa.ipc.new_stream(sink, schema) as writer:
        writer.write_batch(batch)
    events_body = sink.getvalue().to_pybytes()
+    query_events_payloads = []

    def handler(request):
        content_len = int(request.headers.get("Content-Length", 0))
@@ -2512,6 +2513,22 @@ def test_remote_connection_jobs_surface():
            request.end_headers()
            request.wfile.write(json.dumps(rsp).encode())
        elif request.path == "/v1/jobs/describe":
+            if payload["job_id"] == "job-2":
+                request.send_response(200)
+                request.send_header("Content-Type", "application/json")
+                request.end_headers()
+                request.wfile.write(
+                    json.dumps(
+                        dict(
+                            job_id="job-2",
+                            job_type="refresh_column",
+                            job_state="DONE",
+                            creation_ms=2000,
+                            result=dict(rows_assigned=1000000, rows_failed=0),
+                        )
+                    ).encode()
+                )
+                return
            if payload["job_id"] != "job-1":
                request.send_response(404)
                request.end_headers()
@@ -2543,7 +2560,7 @@ def test_remote_connection_jobs_surface():
            request.end_headers()
            request.wfile.write(b'{"job_id": "job-1"}')
        elif request.path == "/v1/jobs/query_events":
-            assert payload["job_id"] == "job-1"
+            query_events_payloads.append(payload)
            request.send_response(200)
            request.send_header("Content-Type", "application/vnd.apache.arrow.stream")
            request.end_headers()
@@ -2559,24 +2576,109 @@ def test_remote_connection_jobs_surface():
        assert jobs[0].table == "t1"
        assert jobs[1].state == "finished"

-        description = db.get_job("job-1")
-        assert description.job_type == "create_index"
-        assert description.state == "failed"
-        assert json.loads(description.spec_json) == {"column": "vec"}
-        assert description.failure.message == "worker died"
-        assert description.failure.retryable is True
-        assert db.get_job("missing") is None
-
        assert db.cancel_job("job-1") is True
        assert db.cancel_job("missing") is False

-        batches = db.job_history("job-1")
-        assert len(batches) == 1
-        assert batches[0].num_rows == 2
-        assert batches[0].column("state").to_pylist() == ["created", "done"]
+        # Opening a job hands back a populated handle; a missing one fails.
+        with pytest.raises(JobNotFoundError, match="missing"):
+            db.open_job("missing")
+        finished = db.open_job("job-2")
+        assert finished.state == "finished"
+        assert finished.result == {"rows_assigned": 1000000, "rows_failed": 0}

-        job = db.job("job-1")
+        job = db.open_job("job-1")
        assert job.id == "job-1"
+        # Opening already populated the handle.
+        assert job.state == "failed"
+        assert job.spec == {"column": "vec"}
+        assert job.failure.message == "worker died"
        assert job.status() == "failed"
        with pytest.raises(JobFailedError, match="worker died"):
            job.wait(timeout=timedelta(seconds=5))
+
+
+def test_remote_job_handle_reports_its_own_detail():
+    schema = pa.schema([("state", pa.string())])
+    batch = pa.record_batch([pa.array(["claim_complete"])], schema=schema)
+    sink = pa.BufferOutputStream()
+    with pa.ipc.new_stream(sink, schema) as writer:
+        writer.write_batch(batch)
+    events_body = sink.getvalue().to_pybytes()
+    event_payloads = []
+
+    def handler(request):
+        content_len = int(request.headers.get("Content-Length", 0))
+        body = request.rfile.read(content_len) if content_len > 0 else b""
+        payload = json.loads(body) if body else {}
+        if request.path == "/v1/jobs/describe":
+            request.send_response(200)
+            request.send_header("Content-Type", "application/json")
+            request.end_headers()
+            request.wfile.write(
+                json.dumps(
+                    dict(
+                        job_id="job-1",
+                        job_type="refresh_column",
+                        job_state="DONE",
+                        creation_ms=2000,
+                        spec=dict(column="vec"),
+                        result=dict(rows_assigned=1000000),
+                    )
+                ).encode()
+            )
+        elif request.path == "/v1/jobs/query_events":
+            event_payloads.append(payload)
+            request.send_response(200)
+            request.send_header("Content-Type", "application/vnd.apache.arrow.stream")
+            request.end_headers()
+            request.wfile.write(events_body)
+        else:
+            request.send_response(404)
+            request.end_headers()
+
+    with mock_lancedb_connection(handler) as db:
+        job = db.open_job("job-1")
+
+        # Opening populates the handle in the same round trip.
+        assert job.state == "finished"
+        job.refresh()
+        assert job.job_type == "refresh_column"
+        assert job.creation_ms == 2000
+        assert job.spec == {"column": "vec"}
+        assert job.result == {"rows_assigned": 1000000}
+        assert job.failure is None
+        # The JSON payloads stay reachable, but as internal APIs.
+        assert json.loads(job._spec_json) == {"column": "vec"}
+        assert json.loads(job._result_json) == {"rows_assigned": 1000000}
+
+        # print() shows everything the handle knows and nothing it does not.
+        # print() lays every known field out on its own line, with the JSON
+        # payloads indented rather than crammed onto one line.
+        assert repr(job) == "\n".join(
+            [
+                "Job(",
+                "    id='job-1',",
+                "    state='finished',",
+                "    job_type='refresh_column',",
+                "    creation_ms=2000,",
+                "    spec={",
+                '        "column": "vec"',
+                "    },",
+                "    result={",
+                '        "rows_assigned": 1000000',
+                "    },",
+                ")",
+            ]
+        )
+        # Nothing it does not know shows up.
+        assert "failure" not in repr(job)
+
+        events = job.events(filter="state = 'claim_complete'", limit=500)
+        assert isinstance(events, pa.Table)
+        assert events.column("state").to_pylist() == ["claim_complete"]
+        # The handle supplies job_id; the caller only narrows the query.
+        assert event_payloads[-1] == {
+            "job_id": "job-1",
+            "limit": 500,
+            "filter": "state = 'claim_complete'",
+        }
@@ -0,0 +1,162 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright The LanceDB Authors
+
+from uuid import UUID
+
+import pytest
+import pyarrow as pa
+
+import lancedb
+from lancedb import _lancedb
+from lancedb.arrow import AsyncRecordBatchReader
+from lancedb.db import AsyncConnection
+from lancedb.remote.db import RemoteDBConnection
+from lancedb.sql import AsyncQuery, Query
+
+NIL_QUERY_ID = UUID(int=0)
+
+
+class FakeNativeQuery:
+    id = UUID("0198f1b2-c3d4-7e5f-8123-456789abcdef")
+
+    async def reader(self):
+        return pa.table({"value": [1, 2]})
+
+
+class FakeNativeConnection:
+    async def execute_query_async(self, query, *, default_namespace_path=None):
+        return FakeNativeQuery()
+
+
+class FakeAsyncConnection:
+    async def execute_query_async(self, query, *, default_namespace_path=None):
+        return AsyncQuery(FakeNativeQuery())
+
+
+def remote_connection(sql_host_override=None):
+    return lancedb.connect(
+        "db://analytics",
+        api_key="test-key",
+        host_override="http://localhost:10024",
+        sql_host_override=sql_host_override,
+    )
+
+
+def test_sql_is_connection_scoped():
+    assert hasattr(lancedb, "sql")
+    assert not callable(lancedb.sql)
+    assert not hasattr(_lancedb, "sql")
+    assert not hasattr(remote_connection(), "sql")
+    assert hasattr(remote_connection(), "execute_query")
+    assert hasattr(remote_connection(), "execute_query_async")
+    assert hasattr(remote_connection(), "describe_query")
+
+
+def test_query_id_is_uuid():
+    query = AsyncQuery(FakeNativeQuery())
+    assert isinstance(query.id, UUID)
+    assert Query(query).id == query.id
+
+
+def test_connection_serializes_sql_host_override():
+    endpoint = "grpc+tls://sql.example.com:10026"
+    restored = lancedb.deserialize_conn(
+        remote_connection(sql_host_override=endpoint).serialize()
+    )
+    assert restored.sql_host_override == endpoint
+
+
+@pytest.mark.asyncio
+async def test_async_sql_reader_is_record_batch_stream():
+    reader = await AsyncQuery(FakeNativeQuery()).reader()
+    assert isinstance(reader, AsyncRecordBatchReader)
+    assert (await reader.read_all())[0].column(0).to_pylist() == [1, 2]
+
+
+def test_sync_sql_reader_is_record_batch_reader():
+    reader = Query(AsyncQuery(FakeNativeQuery())).reader()
+    assert isinstance(reader, pa.RecordBatchReader)
+    assert reader.read_all().column(0).to_pylist() == [1, 2]
+
+
+def test_execute_query_returns_blocking_reader():
+    connection = RemoteDBConnection.__new__(RemoteDBConnection)
+    connection._conn = FakeAsyncConnection()
+    reader = connection.execute_query("SELECT 1")
+    assert isinstance(reader, pa.RecordBatchReader)
+    assert reader.read_all().column(0).to_pylist() == [1, 2]
+
+
+@pytest.mark.asyncio
+async def test_async_execute_query_returns_async_reader():
+    connection = AsyncConnection(FakeNativeConnection())
+    reader = await connection.execute_query("SELECT 1")
+    assert isinstance(reader, AsyncRecordBatchReader)
+    assert (await reader.read_all())[0].column(0).to_pylist() == [1, 2]
+
+
+def test_local_connection_rejects_sql(tmp_path):
+    connection = lancedb.connect(tmp_path)
+    with pytest.raises(NotImplementedError, match="SQL"):
+        connection.execute_query("SELECT 1")
+    with pytest.raises(NotImplementedError, match="SQL"):
+        connection.execute_query_async("SELECT 1")
+    with pytest.raises(NotImplementedError, match="SQL"):
+        connection.describe_query(NIL_QUERY_ID)
+
+
+@pytest.mark.asyncio
+async def test_local_async_connection_rejects_sql(tmp_path):
+    connection = await lancedb.connect_async(tmp_path)
+    with pytest.raises(NotImplementedError, match="SQL"):
+        await connection.execute_query("SELECT 1")
+    with pytest.raises(NotImplementedError, match="SQL"):
+        await connection.execute_query_async("SELECT 1")
+    with pytest.raises(NotImplementedError, match="SQL"):
+        await connection.describe_query(NIL_QUERY_ID)
+
+
+@pytest.mark.asyncio
+async def test_async_namespace_connection_rejects_sql(tmp_path):
+    connection = lancedb.connect_namespace_async("dir", {"root": str(tmp_path)})
+    with pytest.raises(NotImplementedError, match="SQL"):
+        await connection.execute_query("SELECT 1")
+    with pytest.raises(NotImplementedError, match="SQL"):
+        await connection.execute_query_async("SELECT 1")
+    with pytest.raises(NotImplementedError, match="SQL"):
+        await connection.describe_query(NIL_QUERY_ID)
+
+
+def test_describe_query_requires_uuid():
+    with pytest.raises(TypeError, match="UUID"):
+        remote_connection().describe_query(str(NIL_QUERY_ID))
+
+
+@pytest.mark.parametrize(
+    "default_namespace_path",
+    ["public", ("public",), [1]],
+)
+def test_execute_query_async_requires_namespace_path_list(default_namespace_path):
+    with pytest.raises(ValueError, match="default_namespace_path"):
+        remote_connection().execute_query_async(
+            "SELECT 1", default_namespace_path=default_namespace_path
+        )
+
+
+def test_execute_query_async_rejects_invalid_endpoint():
+    connection = remote_connection(sql_host_override="invalid://localhost")
+    with pytest.raises(ValueError, match="sql_host_override"):
+        connection.execute_query_async("SELECT 1")
+
+
+@pytest.mark.parametrize(
+    "default_namespace_path",
+    [[""], ["café"], ["pub\tlic"], ["events$raw"]],
+)
+def test_execute_query_async_rejects_invalid_namespace_components(
+    default_namespace_path,
+):
+    with pytest.raises(ValueError, match="default_namespace_path"):
+        remote_connection().execute_query_async(
+            "SELECT 1", default_namespace_path=default_namespace_path
+        )
@@ -1600,7 +1600,7 @@ def test_create_index_method(mock_create_index, mem_db: DBConnection):
    )
    mock_create_index.assert_called_with(
        "my_vector",
-        replace=False,
+        replace=True,
        config=expected_config,
        wait_timeout=None,
        name=None,
@@ -1620,7 +1620,7 @@ def test_create_index_method(mock_create_index, mem_db: DBConnection):
    )
    mock_create_index.assert_called_with(
        "my_vector",
-        replace=False,
+        replace=True,
        config=expected_config,
        wait_timeout=None,
        name=None,
@@ -1646,7 +1646,7 @@ def test_create_index_name_and_train_parameters(
    expected_config = IvfPq()  # Default config
    mock_create_index.assert_called_with(
        "vector",
-        replace=False,
+        replace=True,
        config=expected_config,
        wait_timeout=None,
        name="my_custom_index",
@@ -1657,7 +1657,7 @@ def test_create_index_name_and_train_parameters(
    table.create_index(vector_column_name="vector", train=False)
    mock_create_index.assert_called_with(
        "vector",
-        replace=False,
+        replace=True,
        config=expected_config,
        wait_timeout=None,
        name=None,
@@ -1668,7 +1668,7 @@ def test_create_index_name_and_train_parameters(
    table.create_index(vector_column_name="vector", name="my_index_name", train=True)
    mock_create_index.assert_called_with(
        "vector",
-        replace=False,
+        replace=True,
        config=expected_config,
        wait_timeout=None,
        name="my_index_name",
@@ -1705,7 +1705,7 @@ def test_create_index_new_api(mock_create_index, mem_db: DBConnection):
        table.create_index("vector", config=IvfPq(distance_type="l2"))
    mock_create_index.assert_called_with(
        "vector",
-        replace=False,
+        replace=True,
        config=IvfPq(distance_type="l2"),
        wait_timeout=None,
        name=None,
@@ -1716,7 +1716,7 @@ def test_create_index_new_api(mock_create_index, mem_db: DBConnection):
    table.create_index("category", config=BTree())
    mock_create_index.assert_called_with(
        "category",
-        replace=False,
+        replace=True,
        config=BTree(),
        wait_timeout=None,
        name=None,
@@ -1727,7 +1727,7 @@ def test_create_index_new_api(mock_create_index, mem_db: DBConnection):
    table.create_index("text", config=FTS(with_position=True))
    mock_create_index.assert_called_with(
        "text",
-        replace=False,
+        replace=True,
        config=FTS(with_position=True),
        wait_timeout=None,
        name=None,
@@ -13,11 +13,7 @@ use crate::{
    runtime::future_into_py,
    table::Table,
 };
-use arrow::{
-    datatypes::Schema,
-    ffi_stream::ArrowArrayStreamReader,
-    pyarrow::{FromPyArrow, ToPyArrow},
-};
+use arrow::{datatypes::Schema, ffi_stream::ArrowArrayStreamReader, pyarrow::FromPyArrow};
 use lancedb::{
    connection::Connection as LanceConnection,
    connection::NamespaceClientPushdownOperation,
@@ -28,7 +24,7 @@ use pyo3::{
    Bound, FromPyObject, Py, PyAny, PyRef, PyResult, Python,
    exceptions::{PyRuntimeError, PyValueError},
    pyclass, pyfunction, pymethods,
-    types::{PyDict, PyDictMethods, PyList, PyListMethods},
+    types::{PyAnyMethods, PyDict, PyDictMethods, PyList},
 };

 #[pyclass]
@@ -86,6 +82,24 @@ impl Connection {
    }
 }

+fn parse_default_namespace_path(path: Option<Bound<'_, PyAny>>) -> PyResult<Vec<String>> {
+    match path {
+        Some(path) => {
+            if !path.is_instance_of::<PyList>() {
+                return Err(PyValueError::new_err(
+                    "Connection.execute_query_async default_namespace_path must be a list",
+                ));
+            }
+            path.extract::<Vec<String>>().map_err(|_| {
+                PyValueError::new_err(
+                    "Connection.execute_query_async default_namespace_path components must be strings",
+                )
+            })
+        }
+        None => Ok(vec!["public".to_string()]),
+    }
+}
+
 #[pymethods]
 impl Connection {
    fn __repr__(&self) -> String {
@@ -108,6 +122,40 @@ impl Connection {
        self.get_inner().map(|inner| inner.uri().to_string())
    }

+    #[pyo3(signature = (query, *, default_namespace_path=None))]
+    pub fn execute_query_async<'a>(
+        self_: PyRef<'a, Self>,
+        query: String,
+        default_namespace_path: Option<Bound<'_, PyAny>>,
+    ) -> PyResult<Bound<'a, PyAny>> {
+        let inner = self_.get_inner()?.clone();
+        let default_namespace_path = parse_default_namespace_path(default_namespace_path)?;
+        future_into_py(self_.py(), async move {
+            let operation = inner
+                .execute_query_async(query)
+                .default_namespace_path(default_namespace_path);
+            operation
+                .execute()
+                .await
+                .map(crate::sql::Query::new)
+                .infer_error()
+        })
+    }
+
+    pub fn describe_query<'a>(
+        self_: PyRef<'a, Self>,
+        query_id: uuid::Uuid,
+    ) -> PyResult<Bound<'a, PyAny>> {
+        let inner = self_.get_inner()?.clone();
+        future_into_py(self_.py(), async move {
+            inner
+                .describe_query(query_id)
+                .await
+                .map(crate::sql::QueryDescription::from)
+                .infer_error()
+        })
+    }
+
    #[pyo3(signature = ())]
    pub fn get_read_consistency_interval(self_: PyRef<'_, Self>) -> PyResult<Bound<'_, PyAny>> {
        let inner = self_.get_inner()?.clone();
@@ -592,9 +640,12 @@ impl Connection {
        })
    }

-    pub fn job(&self, job_id: String) -> PyResult<crate::job::Job> {
-        let inner = self.get_inner()?.clone();
-        Ok(crate::job::Job::new(inner.job(job_id).infer_error()?))
+    pub fn open_job(self_: PyRef<'_, Self>, job_id: String) -> PyResult<Bound<'_, PyAny>> {
+        let inner = self_.get_inner()?.clone();
+        future_into_py(self_.py(), async move {
+            let job = inner.open_job(&job_id).await.infer_error()?;
+            Ok(crate::job::Job::new(job))
+        })
    }

    pub fn create_function_async(
@@ -653,6 +704,78 @@ impl Connection {
        })
    }

+    pub fn create_secret(
+        self_: PyRef<'_, Self>,
+        name: String,
+        value: String,
+        namespace_path: Vec<String>,
+    ) -> PyResult<Bound<'_, PyAny>> {
+        let inner = self_.get_inner()?.clone();
+        future_into_py(self_.py(), async move {
+            inner
+                .create_secret(name, value, &namespace_path)
+                .await
+                .infer_error()
+        })
+    }
+
+    pub fn alter_secret(
+        self_: PyRef<'_, Self>,
+        name: String,
+        value: String,
+        namespace_path: Vec<String>,
+    ) -> PyResult<Bound<'_, PyAny>> {
+        let inner = self_.get_inner()?.clone();
+        future_into_py(self_.py(), async move {
+            inner
+                .alter_secret(name, value, &namespace_path)
+                .await
+                .infer_error()
+        })
+    }
+
+    pub fn list_secrets(
+        self_: PyRef<'_, Self>,
+        namespace_path: Vec<String>,
+    ) -> PyResult<Bound<'_, PyAny>> {
+        let inner = self_.get_inner()?.clone();
+        future_into_py(self_.py(), async move {
+            inner.list_secrets(&namespace_path).await.infer_error()
+        })
+    }
+
+    pub fn drop_secret(
+        self_: PyRef<'_, Self>,
+        name: String,
+        namespace_path: Vec<String>,
+    ) -> PyResult<Bound<'_, PyAny>> {
+        let inner = self_.get_inner()?.clone();
+        future_into_py(self_.py(), async move {
+            inner.drop_secret(name, &namespace_path).await.infer_error()
+        })
+    }
+
+    /// Name and timestamps as a plain mapping. `SecretInfo` carries no value,
+    /// so there is none to filter out here.
+    pub fn describe_secret(
+        self_: PyRef<'_, Self>,
+        name: String,
+        namespace_path: Vec<String>,
+    ) -> PyResult<Bound<'_, PyAny>> {
+        let inner = self_.get_inner()?.clone();
+        future_into_py(self_.py(), async move {
+            let info = inner
+                .describe_secret(name, &namespace_path)
+                .await
+                .infer_error()?;
+            Ok(HashMap::from([
+                ("name".to_string(), info.name),
+                ("created_at".to_string(), info.created_at),
+                ("updated_at".to_string(), info.updated_at),
+            ]))
+        })
+    }
+
    pub fn list_jobs(self_: PyRef<'_, Self>) -> PyResult<Bound<'_, PyAny>> {
        let inner = self_.get_inner()?.clone();
        future_into_py(self_.py(), async move {
@@ -664,42 +787,16 @@ impl Connection {
        })
    }

-    pub fn get_job(self_: PyRef<'_, Self>, job_id: String) -> PyResult<Bound<'_, PyAny>> {
-        let inner = self_.get_inner()?.clone();
-        future_into_py(self_.py(), async move {
-            let description = inner.get_job(&job_id).await.infer_error()?;
-            Ok(description.map(crate::job::JobDescription::from))
-        })
-    }
-
    pub fn cancel_job(self_: PyRef<'_, Self>, job_id: String) -> PyResult<Bound<'_, PyAny>> {
        let inner = self_.get_inner()?.clone();
        future_into_py(self_.py(), async move {
            inner.cancel_job(&job_id).await.infer_error()
        })
    }
-
-    #[pyo3(signature = (job_id=None))]
-    pub fn job_history(
-        self_: PyRef<'_, Self>,
-        job_id: Option<String>,
-    ) -> PyResult<Bound<'_, PyAny>> {
-        let inner = self_.get_inner()?.clone();
-        future_into_py(self_.py(), async move {
-            let batches = inner.job_history(job_id.as_deref()).await.infer_error()?;
-            Python::attach(|py| {
-                let list = PyList::empty(py);
-                for batch in batches {
-                    list.append(batch.to_pyarrow(py)?)?;
-                }
-                Ok(list.unbind())
-            })
-        })
-    }
 }

 #[pyfunction]
-#[pyo3(signature = (uri, api_key=None, region=None, host_override=None, read_consistency_interval=None, client_config=None, storage_options=None, session=None, manifest_enabled=false, namespace_client_properties=None, oauth_config=None))]
+#[pyo3(signature = (uri, api_key=None, region=None, host_override=None, sql_host_override=None, read_consistency_interval=None, client_config=None, storage_options=None, session=None, manifest_enabled=false, namespace_client_properties=None, oauth_config=None))]
 #[allow(clippy::too_many_arguments)]
 pub fn connect(
    py: Python<'_>,
@@ -707,6 +804,7 @@ pub fn connect(
    api_key: Option<String>,
    region: Option<String>,
    host_override: Option<String>,
+    sql_host_override: Option<String>,
    read_consistency_interval: Option<f64>,
    client_config: Option<PyClientConfig>,
    storage_options: Option<HashMap<String, String>>,
@@ -726,6 +824,12 @@ pub fn connect(
        if let Some(host_override) = host_override {
            builder = builder.host_override(&host_override);
        }
+        #[cfg(feature = "remote")]
+        if let Some(sql_host_override) = sql_host_override {
+            builder = builder.sql_host_override(&sql_host_override);
+        }
+        #[cfg(not(feature = "remote"))]
+        let _ = sql_host_override;
        if let Some(read_consistency_interval) = read_consistency_interval {
            let read_consistency_interval = Duration::from_secs_f64(read_consistency_interval);
            builder = builder.read_consistency_interval(read_consistency_interval);
@@ -114,6 +114,12 @@ impl<T> PythonErrorExt<T> for std::result::Result<T, LanceError> {
                        .getattr(intern!(py, "JobCancelledError"))?;
                    Err(PyErr::from_value(cls.call1((err.to_string(),))?))
                }),
+                LanceError::JobNotFound { .. } => Python::attach(|py| {
+                    let cls = py
+                        .import(intern!(py, "lancedb.exceptions"))?
+                        .getattr(intern!(py, "JobNotFoundError"))?;
+                    Err(PyErr::from_value(cls.call1((err.to_string(),))?))
+                }),
                _ => self.runtime_error(),
            },
        }
@@ -4,11 +4,50 @@
 use std::sync::Arc;

 use crate::runtime::future_into_py;
-use pyo3::{Bound, PyAny, PyRef, PyResult, pyclass, pymethods};
+use arrow::{
+    datatypes::Schema,
+    pyarrow::{IntoPyArrow, Table as PyArrowTable},
+};
+use lancedb::job::JobEventsRequest;
+use pyo3::{
+    Bound, PyAny, PyRef, PyResult, Python,
+    exceptions::PyValueError,
+    pyclass, pymethods,
+    types::{PyAnyMethods, PyDict, PyDictMethods},
+};
 use serde::Serialize;

 use crate::error::PythonErrorExt;

+const REPR_INDENT: &str = "    ";
+
+/// Parse a stored JSON payload into Python data. The bindings carry these as
+/// strings because that is what crosses the boundary cheaply; the public
+/// Python surface is the parsed form.
+fn parse_json_payload<'py>(
+    py: Python<'py>,
+    raw: Option<&str>,
+) -> PyResult<Option<Bound<'py, PyAny>>> {
+    match raw {
+        None => Ok(None),
+        Some(raw) => Ok(Some(py.import("json")?.call_method1("loads", (raw,))?)),
+    }
+}
+
+/// A payload rendered as indented JSON, aligned under the field that holds it.
+fn pretty_json_payload(py: Python<'_>, raw: Option<&str>) -> PyResult<Option<String>> {
+    let Some(parsed) = parse_json_payload(py, raw)? else {
+        return Ok(None);
+    };
+    let kwargs = PyDict::new(py);
+    kwargs.set_item("indent", 4)?;
+    let rendered: String = py
+        .import("json")?
+        .call_method("dumps", (parsed,), Some(&kwargs))?
+        .extract()?;
+    Ok(Some(rendered.replace('\n', &format!("\n{REPR_INDENT}"))))
+}
+
 #[pyclass]
 pub struct Job {
    inner: Arc<lancedb::Job<std::result::Result<Option<String>, String>>>,
@@ -67,6 +106,48 @@ impl Job {
            Ok(())
        })
    }
+
+    pub fn refresh(self_: PyRef<'_, Self>) -> PyResult<Bound<'_, PyAny>> {
+        let inner = self_.inner.clone();
+        future_into_py(self_.py(), async move {
+            inner.refresh().await.infer_error()?;
+            Ok(())
+        })
+    }
+
+    /// The last observed lifecycle state, without contacting the backend.
+    #[getter]
+    pub fn _state(&self) -> Option<String> {
+        self.inner.state()
+    }
+
+    /// The last observed server-side record. `None` for an in-process job.
+    #[getter]
+    pub fn _description(&self) -> Option<JobDescription> {
+        self.inner.description().map(JobDescription::from)
+    }
+
+    #[pyo3(signature = (*, limit=None, filter=None))]
+    pub fn events(
+        self_: PyRef<'_, Self>,
+        limit: Option<u32>,
+        filter: Option<String>,
+    ) -> PyResult<Bound<'_, PyAny>> {
+        let inner = self_.inner.clone();
+        let request = JobEventsRequest { limit, filter };
+        future_into_py(self_.py(), async move {
+            let batches = inner.events(request).await.infer_error()?;
+            Python::attach(|py| {
+                let schema = batches
+                    .first()
+                    .map(|batch| batch.schema())
+                    .unwrap_or_else(|| Arc::new(Schema::empty()));
+                let table = PyArrowTable::try_new(batches, schema)
+                    .map_err(|err| PyValueError::new_err(err.to_string()))?;
+                table.into_pyarrow(py).map(|table| table.unbind())
+            })
+        })
+    }
 }

 /// A row from `Connection.list_jobs`: one server-side job.
@@ -121,7 +202,7 @@ impl JobFailureInfo {
    }
 }

-/// A described job from `Connection.get_job`.
+/// The server-side record behind a `Job` handle.
 #[pyclass(get_all, skip_from_py_object)]
 #[derive(Clone)]
 pub struct JobDescription {
@@ -129,17 +210,49 @@ pub struct JobDescription {
    job_type: String,
    state: String,
    creation_ms: i64,
-    spec_json: Option<String>,
+    /// Internal: the wire form behind the `spec` property.
+    _spec_json: Option<String>,
+    /// Internal: the wire form behind the `result` property.
+    _result_json: Option<String>,
    failure: Option<JobFailureInfo>,
 }

 #[pymethods]
 impl JobDescription {
-    fn __repr__(&self) -> String {
-        format!(
-            "JobDescription(job_id={:?}, job_type={:?}, state={:?}, creation_ms={})",
-            self.job_id, self.job_type, self.state, self.creation_ms
-        )
+    /// The job-type-specific specification it was submitted with.
+    #[getter]
+    fn spec<'py>(&self, py: Python<'py>) -> PyResult<Option<Bound<'py, PyAny>>> {
+        parse_json_payload(py, self._spec_json.as_deref())
+    }
+
+    /// The job-type-specific terminal result. `None` until the job succeeds.
+    #[getter]
+    fn result<'py>(&self, py: Python<'py>) -> PyResult<Option<Bound<'py, PyAny>>> {
+        parse_json_payload(py, self._result_json.as_deref())
+    }
+
+    fn __repr__(&self, py: Python<'_>) -> PyResult<String> {
+        let mut fields = vec![
+            format!("job_id={:?}", self.job_id),
+            format!("job_type={:?}", self.job_type),
+            format!("state={:?}", self.state),
+            format!("creation_ms={}", self.creation_ms),
+        ];
+        // Lay the payloads out as indented JSON, the same way the `Job` repr
+        // does, so the two agree on how the same data looks.
+        for (name, payload) in [("spec", &self._spec_json), ("result", &self._result_json)] {
+            if let Some(rendered) = pretty_json_payload(py, payload.as_deref())? {
+                fields.push(format!("{name}={rendered}"));
+            }
+        }
+        if let Some(failure) = &self.failure {
+            fields.push(format!("failure={}", failure.__repr__()));
+        }
+        let body = fields
+            .iter()
+            .map(|field| format!("\n{REPR_INDENT}{field},"))
+            .collect::<String>();
+        Ok(format!("JobDescription({body}\n)"))
    }
 }

@@ -150,7 +263,11 @@ impl From<lancedb::database::JobDescription> for JobDescription {
            job_type: description.job_type,
            state: description.state,
            creation_ms: description.creation_ms,
-            spec_json: (!description.spec.is_null()).then(|| description.spec.to_string()),
+            _spec_json: (!description.spec.is_null()).then(|| description.spec.to_string()),
+            _result_json: description
+                .result
+                .filter(|result| !result.is_null())
+                .map(|result| result.to_string()),
            failure: description.failure.map(|failure| JobFailureInfo {
                phase: failure.phase,
                message: failure.message,
@@ -34,6 +34,7 @@ pub mod permutation;
 pub mod query;
 pub mod runtime;
 pub mod session;
+pub mod sql;
 pub mod table;
 pub mod util;

@@ -50,6 +51,8 @@ pub fn _lancedb(_py: Python, m: &Bound<'_, PyModule>) -> PyResult<()> {
    m.add_class::<crate::job::JobInfo>()?;
    m.add_class::<crate::job::JobDescription>()?;
    m.add_class::<crate::job::JobFailureInfo>()?;
+    m.add_class::<crate::sql::Query>()?;
+    m.add_class::<crate::sql::QueryDescription>()?;
    m.add_class::<PyBlobFile>()?;
    m.add_class::<IndexConfig>()?;
    m.add_class::<Query>()?;
@@ -0,0 +1,90 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright The LanceDB Authors
+
+use std::sync::Arc;
+
+use chrono::{DateTime, Utc};
+use pyo3::{Bound, PyAny, PyRef, PyResult, pyclass, pymethods};
+use uuid::Uuid;
+
+use crate::arrow::RecordBatchStream;
+use crate::error::PythonErrorExt;
+use crate::runtime::future_into_py;
+
+#[pyclass(name = "SqlQuery")]
+pub struct Query {
+    inner: Arc<lancedb::sql::Query>,
+}
+
+impl Query {
+    pub(crate) fn new(inner: lancedb::sql::Query) -> Self {
+        Self {
+            inner: Arc::new(inner),
+        }
+    }
+}
+
+#[pymethods]
+impl Query {
+    #[getter]
+    pub fn id(&self) -> Uuid {
+        self.inner.id()
+    }
+
+    pub fn describe(self_: PyRef<'_, Self>) -> PyResult<Bound<'_, PyAny>> {
+        let inner = self_.inner.clone();
+        future_into_py(self_.py(), async move {
+            inner
+                .describe()
+                .await
+                .map(QueryDescription::from)
+                .infer_error()
+        })
+    }
+
+    pub fn reader(self_: PyRef<'_, Self>) -> PyResult<Bound<'_, PyAny>> {
+        let inner = self_.inner.clone();
+        future_into_py(self_.py(), async move {
+            let stream = inner.reader().await.infer_error()?;
+            Ok(RecordBatchStream::new(stream))
+        })
+    }
+
+    pub fn cancel(self_: PyRef<'_, Self>) -> PyResult<Bound<'_, PyAny>> {
+        let inner = self_.inner.clone();
+        future_into_py(self_.py(), async move {
+            inner.cancel().await.infer_error()?;
+            Ok(())
+        })
+    }
+}
+
+#[pyclass(get_all, skip_from_py_object)]
+#[derive(Clone)]
+pub struct QueryDescription {
+    id: Uuid,
+    status: String,
+    progress: Option<f64>,
+    expires_at: Option<DateTime<Utc>>,
+}
+
+#[pymethods]
+impl QueryDescription {
+    fn __repr__(&self) -> String {
+        format!(
+            "QueryDescription(id={:?}, status={:?}, progress={:?}, expires_at={:?})",
+            self.id, self.status, self.progress, self.expires_at
+        )
+    }
+}
+
+impl From<lancedb::sql::QueryDescription> for QueryDescription {
+    fn from(description: lancedb::sql::QueryDescription) -> Self {
+        Self {
+            id: description.id,
+            status: description.status.to_string(),
+            progress: description.progress,
+            expires_at: description.expires_at,
+        }
+    }
+}
@@ -10,6 +10,9 @@ resolution-markers = [
    "python_full_version < '3.11'",
 ]

+[options]
+prerelease-mode = "allow"
+
 [[package]]
 name = "accelerate"
 version = "1.14.0"
@@ -799,7 +802,7 @@ name = "cuda-bindings"
 version = "13.3.1"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
-    { name = "cuda-pathfinder", marker = "(python_full_version < '3.14' and sys_platform == 'emscripten') or (python_full_version < '3.14' and sys_platform == 'win32') or (sys_platform != 'emscripten' and sys_platform != 'win32')" },
+    { name = "cuda-pathfinder" },
 ]
 wheels = [
    { url = "https://files.pythonhosted.org/packages/a9/21/8464d133752951c154feafb3b65c297e7d80f301183d220bec4c830f1441/cuda_bindings-13.3.1-cp310-cp310-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:120fcc53d57903df529c3486962c56528cba5b7d6c57c99537320ed9922c8b86", size = 6073403, upload-time = "2026-05-29T23:11:36.22Z" },
@@ -834,37 +837,37 @@ wheels = [

 [package.optional-dependencies]
 cublas = [
-    { name = "nvidia-cublas", marker = "(python_full_version < '3.14' and sys_platform == 'win32') or sys_platform == 'linux'" },
+    { name = "nvidia-cublas" },
 ]
 cudart = [
-    { name = "nvidia-cuda-runtime", marker = "(python_full_version < '3.14' and sys_platform == 'win32') or sys_platform == 'linux'" },
+    { name = "nvidia-cuda-runtime" },
 ]
 cufft = [
-    { name = "nvidia-cufft", marker = "(python_full_version < '3.14' and sys_platform == 'win32') or sys_platform == 'linux'" },
+    { name = "nvidia-cufft" },
 ]
 cufile = [
-    { name = "nvidia-cufile", marker = "sys_platform == 'linux'" },
+    { name = "nvidia-cufile" },
 ]
 cupti = [
-    { name = "nvidia-cuda-cupti", marker = "(python_full_version < '3.14' and sys_platform == 'win32') or sys_platform == 'linux'" },
+    { name = "nvidia-cuda-cupti" },
 ]
 curand = [
-    { name = "nvidia-curand", marker = "(python_full_version < '3.14' and sys_platform == 'win32') or sys_platform == 'linux'" },
+    { name = "nvidia-curand" },
 ]
 cusolver = [
-    { name = "nvidia-cusolver", marker = "(python_full_version < '3.14' and sys_platform == 'win32') or sys_platform == 'linux'" },
+    { name = "nvidia-cusolver" },
 ]
 cusparse = [
-    { name = "nvidia-cusparse", marker = "(python_full_version < '3.14' and sys_platform == 'win32') or sys_platform == 'linux'" },
+    { name = "nvidia-cusparse" },
 ]
 nvjitlink = [
-    { name = "nvidia-nvjitlink", marker = "(python_full_version < '3.14' and sys_platform == 'win32') or sys_platform == 'linux'" },
+    { name = "nvidia-nvjitlink" },
 ]
 nvrtc = [
-    { name = "nvidia-cuda-nvrtc", marker = "(python_full_version < '3.14' and sys_platform == 'win32') or sys_platform == 'linux'" },
+    { name = "nvidia-cuda-nvrtc" },
 ]
 nvtx = [
-    { name = "nvidia-nvtx", marker = "(python_full_version < '3.14' and sys_platform == 'win32') or sys_platform == 'linux'" },
+    { name = "nvidia-nvtx" },
 ]

 [[package]]
@@ -1023,7 +1026,7 @@ name = "exceptiongroup"
 version = "1.3.1"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
-    { name = "typing-extensions", marker = "python_full_version < '3.11'" },
+    { name = "typing-extensions" },
 ]
 sdist = { url = "https://files.pythonhosted.org/packages/50/79/66800aadf48771f6b62f7eb014e352e5d06856655206165d775e675a02c9/exceptiongroup-1.3.1.tar.gz", hash = "sha256:8b412432c6055b0b7d14c310000ae93352ed6754f70fa8f7c34141f91c4e3219", size = 30371, upload-time = "2025-11-21T23:01:54.787Z" }
 wheels = [
@@ -1440,16 +1443,16 @@ resolution-markers = [
    "python_full_version < '3.11'",
 ]
 dependencies = [
-    { name = "cachetools", marker = "python_full_version < '3.11'" },
-    { name = "certifi", marker = "python_full_version < '3.11'" },
-    { name = "httpx", marker = "python_full_version < '3.11'" },
-    { name = "ibm-cos-sdk", marker = "python_full_version < '3.11'" },
-    { name = "lomond", marker = "python_full_version < '3.11'" },
-    { name = "packaging", marker = "python_full_version < '3.11'" },
-    { name = "pandas", version = "2.2.3", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11'" },
-    { name = "requests", marker = "python_full_version < '3.11'" },
-    { name = "tabulate", marker = "python_full_version < '3.11'" },
-    { name = "urllib3", marker = "python_full_version < '3.11'" },
+    { name = "cachetools" },
+    { name = "certifi" },
+    { name = "httpx" },
+    { name = "ibm-cos-sdk" },
+    { name = "lomond" },
+    { name = "packaging" },
+    { name = "pandas", version = "2.2.3", source = { registry = "https://pypi.org/simple" } },
+    { name = "requests" },
+    { name = "tabulate" },
+    { name = "urllib3" },
 ]
 sdist = { url = "https://files.pythonhosted.org/packages/c7/56/2e3df38a1f13062095d7bde23c87a92f3898982993a15186b1bfecbd206f/ibm_watsonx_ai-1.3.42.tar.gz", hash = "sha256:ee5be59009004245d957ce97d1227355516df95a2640189749487614fef674ff", size = 688651, upload-time = "2025-10-01T13:35:41.527Z" }
 wheels = [
@@ -1468,17 +1471,17 @@ resolution-markers = [
    "python_full_version == '3.11.*'",
 ]
 dependencies = [
-    { name = "cachetools", marker = "python_full_version >= '3.11'" },
-    { name = "certifi", marker = "python_full_version >= '3.11'" },
-    { name = "httpx", marker = "python_full_version >= '3.11'" },
-    { name = "ibm-cos-sdk", marker = "python_full_version >= '3.11'" },
-    { name = "lomond", marker = "python_full_version >= '3.11'" },
-    { name = "packaging", marker = "python_full_version >= '3.11'" },
-    { name = "pandas", version = "2.3.3", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.11' and python_full_version < '3.14'" },
+    { name = "cachetools" },
+    { name = "certifi" },
+    { name = "httpx" },
+    { name = "ibm-cos-sdk" },
+    { name = "lomond" },
+    { name = "packaging" },
+    { name = "pandas", version = "2.3.3", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.14'" },
    { name = "pandas", version = "3.0.3", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.14'" },
-    { name = "requests", marker = "python_full_version >= '3.11'" },
-    { name = "tabulate", marker = "python_full_version >= '3.11'" },
-    { name = "urllib3", marker = "python_full_version >= '3.11'" },
+    { name = "requests" },
+    { name = "tabulate" },
+    { name = "urllib3" },
 ]
 sdist = { url = "https://files.pythonhosted.org/packages/29/a3/c756b534696ab2f3f29882fdb7ca7198b7a5c94e10c0a3a327853d6d6b79/ibm_watsonx_ai-1.5.14.tar.gz", hash = "sha256:a756488bd57e87c0fc51be42dcba871143cfe0ac1e805c497c5047e1e4f13e9d", size = 735804, upload-time = "2026-06-22T12:32:43.85Z" }
 wheels = [
@@ -1554,17 +1557,17 @@ resolution-markers = [
    "python_full_version < '3.11'",
 ]
 dependencies = [
-    { name = "colorama", marker = "python_full_version < '3.11' and sys_platform == 'win32'" },
-    { name = "decorator", marker = "python_full_version < '3.11'" },
-    { name = "exceptiongroup", marker = "python_full_version < '3.11'" },
-    { name = "jedi", marker = "python_full_version < '3.11'" },
-    { name = "matplotlib-inline", marker = "python_full_version < '3.11'" },
-    { name = "pexpect", marker = "python_full_version < '3.11' and sys_platform != 'emscripten' and sys_platform != 'win32'" },
-    { name = "prompt-toolkit", marker = "python_full_version < '3.11'" },
-    { name = "pygments", marker = "python_full_version < '3.11'" },
-    { name = "stack-data", marker = "python_full_version < '3.11'" },
-    { name = "traitlets", marker = "python_full_version < '3.11'" },
-    { name = "typing-extensions", marker = "python_full_version < '3.11'" },
+    { name = "colorama", marker = "sys_platform == 'win32'" },
+    { name = "decorator" },
+    { name = "exceptiongroup" },
+    { name = "jedi" },
+    { name = "matplotlib-inline" },
+    { name = "pexpect", marker = "sys_platform != 'emscripten' and sys_platform != 'win32'" },
+    { name = "prompt-toolkit" },
+    { name = "pygments" },
+    { name = "stack-data" },
+    { name = "traitlets" },
+    { name = "typing-extensions" },
 ]
 sdist = { url = "https://files.pythonhosted.org/packages/40/18/f8598d287006885e7136451fdea0755af4ebcbfe342836f24deefaed1164/ipython-8.39.0.tar.gz", hash = "sha256:4110ae96012c379b8b6db898a07e186c40a2a1ef5d57a7fa83166047d9da7624", size = 5513971, upload-time = "2026-03-27T10:02:13.94Z" }
 wheels = [
@@ -1583,18 +1586,18 @@ resolution-markers = [
    "python_full_version == '3.11.*'",
 ]
 dependencies = [
-    { name = "colorama", marker = "python_full_version >= '3.11' and sys_platform == 'win32'" },
-    { name = "decorator", marker = "python_full_version >= '3.11'" },
-    { name = "ipython-pygments-lexers", marker = "python_full_version >= '3.11'" },
-    { name = "jedi", marker = "python_full_version >= '3.11'" },
-    { name = "matplotlib-inline", marker = "python_full_version >= '3.11'" },
-    { name = "pexpect", marker = "python_full_version >= '3.11' and sys_platform != 'emscripten' and sys_platform != 'win32'" },
-    { name = "prompt-toolkit", marker = "python_full_version >= '3.11'" },
-    { name = "psutil", marker = "python_full_version >= '3.11' and sys_platform != 'cygwin' and sys_platform != 'emscripten'" },
-    { name = "pygments", marker = "python_full_version >= '3.11'" },
-    { name = "stack-data", marker = "python_full_version >= '3.11'" },
-    { name = "traitlets", marker = "python_full_version >= '3.11'" },
-    { name = "typing-extensions", marker = "python_full_version == '3.11.*'" },
+    { name = "colorama", marker = "sys_platform == 'win32'" },
+    { name = "decorator" },
+    { name = "ipython-pygments-lexers" },
+    { name = "jedi" },
+    { name = "matplotlib-inline" },
+    { name = "pexpect", marker = "sys_platform != 'emscripten' and sys_platform != 'win32'" },
+    { name = "prompt-toolkit" },
+    { name = "psutil", marker = "sys_platform != 'cygwin' and sys_platform != 'emscripten'" },
+    { name = "pygments" },
+    { name = "stack-data" },
+    { name = "traitlets" },
+    { name = "typing-extensions", marker = "python_full_version < '3.12'" },
 ]
 sdist = { url = "https://files.pythonhosted.org/packages/53/59/165d3b4d75cc34add3122c4417ecb229085140ac573103c223cd01dde96f/ipython-9.15.0.tar.gz", hash = "sha256:da2819ce2aa83135257df830660b1176d986c3d2876db24df01974fa955b2756", size = 4442580, upload-time = "2026-06-26T11:03:35.913Z" }
 wheels = [
@@ -1606,7 +1609,7 @@ name = "ipython-pygments-lexers"
 version = "1.1.1"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
-    { name = "pygments", marker = "python_full_version >= '3.11'" },
+    { name = "pygments" },
 ]
 sdist = { url = "https://files.pythonhosted.org/packages/ef/4c/5dd1d8af08107f88c7f741ead7a40854b8ac24ddf9ae850afbcf698aa552/ipython_pygments_lexers-1.1.1.tar.gz", hash = "sha256:09c0138009e56b6854f9535736f4171d855c8c08a563a0dcd8022f78355c7e81", size = 8393, upload-time = "2025-01-17T11:24:34.505Z" }
 wheels = [
@@ -2858,7 +2861,7 @@ name = "nvidia-cudnn-cu13"
 version = "9.19.0.56"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
-    { name = "nvidia-cublas", marker = "(python_full_version < '3.14' and sys_platform == 'emscripten') or (python_full_version < '3.14' and sys_platform == 'win32') or (sys_platform != 'emscripten' and sys_platform != 'win32')" },
+    { name = "nvidia-cublas" },
 ]
 wheels = [
    { url = "https://files.pythonhosted.org/packages/f1/84/26025437c1e6b61a707442184fa0c03d083b661adf3a3eecfd6d21677740/nvidia_cudnn_cu13-9.19.0.56-py3-none-manylinux_2_27_aarch64.whl", hash = "sha256:6ed29ffaee1176c612daf442e4dd6cfeb6a0caa43ddcbeb59da94953030b1be4", size = 433781201, upload-time = "2026-02-03T20:40:53.805Z" },
@@ -2870,7 +2873,7 @@ name = "nvidia-cufft"
 version = "12.0.0.61"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
-    { name = "nvidia-nvjitlink", marker = "(python_full_version < '3.14' and sys_platform == 'emscripten') or (python_full_version < '3.14' and sys_platform == 'win32') or (sys_platform != 'emscripten' and sys_platform != 'win32')" },
+    { name = "nvidia-nvjitlink" },
 ]
 wheels = [
    { url = "https://files.pythonhosted.org/packages/8b/ae/f417a75c0259e85c1d2f83ca4e960289a5f814ed0cea74d18c353d3e989d/nvidia_cufft-12.0.0.61-py3-none-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:2708c852ef8cd89d1d2068bdbece0aa188813a0c934db3779b9b1faa8442e5f5", size = 214053554, upload-time = "2025-09-04T08:31:38.196Z" },
@@ -2900,9 +2903,9 @@ name = "nvidia-cusolver"
 version = "12.0.4.66"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
-    { name = "nvidia-cublas", marker = "(python_full_version < '3.14' and sys_platform == 'emscripten') or (python_full_version < '3.14' and sys_platform == 'win32') or (sys_platform != 'emscripten' and sys_platform != 'win32')" },
-    { name = "nvidia-cusparse", marker = "(python_full_version < '3.14' and sys_platform == 'emscripten') or (python_full_version < '3.14' and sys_platform == 'win32') or (sys_platform != 'emscripten' and sys_platform != 'win32')" },
-    { name = "nvidia-nvjitlink", marker = "(python_full_version < '3.14' and sys_platform == 'emscripten') or (python_full_version < '3.14' and sys_platform == 'win32') or (sys_platform != 'emscripten' and sys_platform != 'win32')" },
+    { name = "nvidia-cublas" },
+    { name = "nvidia-cusparse" },
+    { name = "nvidia-nvjitlink" },
 ]
 wheels = [
    { url = "https://files.pythonhosted.org/packages/c8/c3/b30c9e935fc01e3da443ec0116ed1b2a009bb867f5324d3f2d7e533e776b/nvidia_cusolver-12.0.4.66-py3-none-manylinux_2_27_aarch64.whl", hash = "sha256:02c2457eaa9e39de20f880f4bd8820e6a1cfb9f9a34f820eb12a155aa5bc92d2", size = 223467760, upload-time = "2025-09-04T08:33:04.222Z" },
@@ -2914,7 +2917,7 @@ name = "nvidia-cusparse"
 version = "12.6.3.3"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
-    { name = "nvidia-nvjitlink", marker = "(python_full_version < '3.14' and sys_platform == 'emscripten') or (python_full_version < '3.14' and sys_platform == 'win32') or (sys_platform != 'emscripten' and sys_platform != 'win32')" },
+    { name = "nvidia-nvjitlink" },
 ]
 wheels = [
    { url = "https://files.pythonhosted.org/packages/f8/94/5c26f33738ae35276672f12615a64bd008ed5be6d1ebcb23579285d960a9/nvidia_cusparse-12.6.3.3-py3-none-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:80bcc4662f23f1054ee334a15c72b8940402975e0eab63178fc7e670aa59472c", size = 162155568, upload-time = "2025-09-04T08:33:42.864Z" },
@@ -3091,10 +3094,10 @@ resolution-markers = [
    "python_full_version < '3.11'",
 ]
 dependencies = [
-    { name = "numpy", version = "2.2.6", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11'" },
-    { name = "python-dateutil", marker = "python_full_version < '3.11'" },
-    { name = "pytz", marker = "python_full_version < '3.11'" },
-    { name = "tzdata", marker = "python_full_version < '3.11'" },
+    { name = "numpy", version = "2.2.6", source = { registry = "https://pypi.org/simple" } },
+    { name = "python-dateutil" },
+    { name = "pytz" },
+    { name = "tzdata" },
 ]
 sdist = { url = "https://files.pythonhosted.org/packages/9c/d6/9f8431bacc2e19dca897724cd097b1bb224a6ad5433784a44b587c7c13af/pandas-2.2.3.tar.gz", hash = "sha256:4f18ba62b61d7e192368b84517265a99b4d7ee8912f8708660fb4a366cc82667", size = 4399213, upload-time = "2024-09-20T13:10:04.827Z" }
 wheels = [
@@ -3143,11 +3146,11 @@ resolution-markers = [
    "python_full_version == '3.11.*'",
 ]
 dependencies = [
-    { name = "numpy", version = "2.4.6", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version == '3.11.*'" },
+    { name = "numpy", version = "2.4.6", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.12' or python_full_version >= '3.14'" },
    { name = "numpy", version = "2.5.1", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.12' and python_full_version < '3.14'" },
-    { name = "python-dateutil", marker = "python_full_version >= '3.11' and python_full_version < '3.14'" },
-    { name = "pytz", marker = "python_full_version >= '3.11' and python_full_version < '3.14'" },
-    { name = "tzdata", marker = "python_full_version >= '3.11' and python_full_version < '3.14'" },
+    { name = "python-dateutil" },
+    { name = "pytz" },
+    { name = "tzdata" },
 ]
 sdist = { url = "https://files.pythonhosted.org/packages/33/01/d40b85317f86cf08d853a4f495195c73815fdf205eef3993821720274518/pandas-2.3.3.tar.gz", hash = "sha256:e05e1af93b977f7eafa636d043f9f94c7ee3ac81af99c13508215942e64c993b", size = 4495223, upload-time = "2025-09-29T23:34:51.853Z" }
 wheels = [
@@ -3210,9 +3213,9 @@ resolution-markers = [
    "python_full_version >= '3.14' and sys_platform != 'emscripten' and sys_platform != 'win32'",
 ]
 dependencies = [
-    { name = "numpy", version = "2.5.1", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.14'" },
-    { name = "python-dateutil", marker = "python_full_version >= '3.14'" },
-    { name = "tzdata", marker = "(python_full_version >= '3.14' and sys_platform == 'emscripten') or (python_full_version >= '3.14' and sys_platform == 'win32')" },
+    { name = "numpy", version = "2.5.1", source = { registry = "https://pypi.org/simple" } },
+    { name = "python-dateutil" },
+    { name = "tzdata", marker = "sys_platform == 'emscripten' or sys_platform == 'win32'" },
 ]
 sdist = { url = "https://files.pythonhosted.org/packages/f8/87/4341c6252d1c47b08768c3d25ac487362bf403f0313ddae4a2a26c9b1b4c/pandas-3.0.3.tar.gz", hash = "sha256:696a4a00a2a2a35d4e5deb3fc946641b96c944f02230e4f76137fe35d806c4fc", size = 4651414, upload-time = "2026-05-11T18:54:29.21Z" }
 wheels = [
@@ -3320,7 +3323,7 @@ name = "pexpect"
 version = "4.9.0"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
-    { name = "ptyprocess", marker = "(python_full_version < '3.14' and sys_platform == 'emscripten') or (python_full_version < '3.14' and sys_platform == 'win32') or (sys_platform != 'emscripten' and sys_platform != 'win32')" },
+    { name = "ptyprocess" },
 ]
 sdist = { url = "https://files.pythonhosted.org/packages/42/92/cc564bf6381ff43ce1f4d06852fc19a2f11d180f23dc32d9588bee2f149d/pexpect-4.9.0.tar.gz", hash = "sha256:ee7d41123f3c9911050ea2c2dac107568dc43b2d3b0c7557a33212c398ead30f", size = 166450, upload-time = "2023-11-25T09:07:26.339Z" }
 wheels = [
@@ -3912,8 +3915,8 @@ crypto = [

 [[package]]
 name = "pylance"
-version = "7.0.0"
-source = { registry = "https://pypi.org/simple" }
+version = "9.0.0rc1"
+source = { registry = "https://pypi.fury.io/lance-format/" }
 dependencies = [
    { name = "lance-namespace" },
    { name = "numpy", version = "2.2.6", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11'" },
@@ -3922,12 +3925,12 @@ dependencies = [
    { name = "pyarrow" },
 ]
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/ac/ad/2f64921bf346e7075aef24a72595db44821724a3d89a9a92dd24e79632aa/pylance-7.0.0-cp39-abi3-macosx_11_0_arm64.whl", hash = "sha256:98422021975be76e72b1572f41b8c9abb3bee5bdc9bfa5e9ce731110a65ed4d1", size = 62134146, upload-time = "2026-05-27T21:59:37.459Z" },
-    { url = "https://files.pythonhosted.org/packages/73/1c/c5a01bee0160b55d9a98895cbd33091d038f0a0995b121ab72e629008d02/pylance-7.0.0-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:4bec86ee5b6fbd8bfc493e653f0a1fba0303cfe5492b9b46fc25ab908edc7183", size = 65373684, upload-time = "2026-05-27T22:04:01.584Z" },
-    { url = "https://files.pythonhosted.org/packages/eb/da/1fe8b8f7dbfe734d76af76acc994fc360a0d0c79a4874ef69f5a72a58fe3/pylance-7.0.0-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:881491432c53184e52f8d1db8d5f872f39a03f36fb104bec77b33d379519d8b5", size = 69458555, upload-time = "2026-05-27T22:16:50.567Z" },
-    { url = "https://files.pythonhosted.org/packages/76/f0/dd505cf3fd0226ab9d94759acd713125af1d3bfacfd80bbd52e3b9f89509/pylance-7.0.0-cp39-abi3-manylinux_2_28_aarch64.whl", hash = "sha256:18453999e7fff4f76b16d6b7882c9df0628bd142ff95e2461bd7dd5ee3fe0af3", size = 65394430, upload-time = "2026-05-27T22:05:30.923Z" },
-    { url = "https://files.pythonhosted.org/packages/17/ba/2357b81034f28eb00790e258ed140289a6a887a7468ca9df6349fd186b27/pylance-7.0.0-cp39-abi3-manylinux_2_28_x86_64.whl", hash = "sha256:04a58051d408c60fe76d41a220dcaf8fea8fb6d1aa0ca78a709b60bc3cc8d19a", size = 69473470, upload-time = "2026-05-27T22:17:18.935Z" },
-    { url = "https://files.pythonhosted.org/packages/1f/ec/5c00b6303a67d787f9475141832cbdc513d674ac3dcaeef8a7b169905e65/pylance-7.0.0-cp39-abi3-win_amd64.whl", hash = "sha256:467d4864af047eaab4e1370e2f1e88e2c6f507c079874421116cb41d78bc3629", size = 74792863, upload-time = "2026-05-27T22:19:23.875Z" },
+    { url = "https://pypi.fury.io/lance-format/-/ver_vEHBE/pylance-9.0.0rc1-cp310-abi3-macosx_11_0_arm64.whl", hash = "sha256:f0b6b02a1808bb3072ee7fe4e36614cae6f86302513e73ec7f55b2234a963b24" },
+    { url = "https://pypi.fury.io/lance-format/-/ver_1Jipm4/pylance-9.0.0rc1-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:30f0ebf0d88034301819eb964f9236ce555aaa58e7ab89c5975a3e2250bbb405" },
+    { url = "https://pypi.fury.io/lance-format/-/ver_IvKxo/pylance-9.0.0rc1-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:44609ea2615ea6e684b85478d1694af2026458f61cf7895ecc75e238bfd17aa8" },
+    { url = "https://pypi.fury.io/lance-format/-/ver_2hidj1/pylance-9.0.0rc1-cp310-abi3-manylinux_2_28_aarch64.whl", hash = "sha256:182167a8dba9eeabffbffd53bd5b8548613d4d459b7cd7b34a840dd00cbb806f" },
+    { url = "https://pypi.fury.io/lance-format/-/ver_1dFx3r/pylance-9.0.0rc1-cp310-abi3-manylinux_2_28_x86_64.whl", hash = "sha256:8a63b11e814b7eab758bcaf0d6f97eb05ea86203d9fb0af718c462c24c7d6c9c" },
+    { url = "https://pypi.fury.io/lance-format/-/ver_2a8dSh/pylance-9.0.0rc1-cp310-abi3-win_amd64.whl", hash = "sha256:2ff8b953ae2b0550490c1a7efd210aa91bc223d200ffac28849056cfd7436d97" },
 ]

 [[package]]
@@ -4683,10 +4686,10 @@ resolution-markers = [
    "python_full_version < '3.11'",
 ]
 dependencies = [
-    { name = "joblib", marker = "python_full_version < '3.11'" },
-    { name = "numpy", version = "2.2.6", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11'" },
-    { name = "scipy", version = "1.15.3", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11'" },
-    { name = "threadpoolctl", marker = "python_full_version < '3.11'" },
+    { name = "joblib" },
+    { name = "numpy", version = "2.2.6", source = { registry = "https://pypi.org/simple" } },
+    { name = "scipy", version = "1.15.3", source = { registry = "https://pypi.org/simple" } },
+    { name = "threadpoolctl" },
 ]
 sdist = { url = "https://files.pythonhosted.org/packages/98/c2/a7855e41c9d285dfe86dc50b250978105dce513d6e459ea66a6aeb0e1e0c/scikit_learn-1.7.2.tar.gz", hash = "sha256:20e9e49ecd130598f1ca38a1d85090e1a600147b9c02fa6f15d69cb53d968fda", size = 7193136, upload-time = "2025-09-09T08:21:29.075Z" }
 wheels = [
@@ -4734,13 +4737,13 @@ resolution-markers = [
    "python_full_version == '3.11.*'",
 ]
 dependencies = [
-    { name = "joblib", marker = "python_full_version >= '3.11'" },
-    { name = "narwhals", marker = "python_full_version >= '3.11'" },
-    { name = "numpy", version = "2.4.6", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version == '3.11.*'" },
+    { name = "joblib" },
+    { name = "narwhals" },
+    { name = "numpy", version = "2.4.6", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.12'" },
    { name = "numpy", version = "2.5.1", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.12'" },
-    { name = "scipy", version = "1.17.1", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version == '3.11.*'" },
+    { name = "scipy", version = "1.17.1", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.12'" },
    { name = "scipy", version = "1.18.0", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.12'" },
-    { name = "threadpoolctl", marker = "python_full_version >= '3.11'" },
+    { name = "threadpoolctl" },
 ]
 sdist = { url = "https://files.pythonhosted.org/packages/fa/6f/37092bdb25f712817231799fc5674d8e704066a8a70c1d2d40517e18b4ab/scikit_learn-1.9.0.tar.gz", hash = "sha256:8833266989d3a5110178a9fae30783675460724d0e1efb13b14901d2c660c557", size = 7750767, upload-time = "2026-06-02T11:54:32.706Z" }
 wheels = [
@@ -4784,7 +4787,7 @@ resolution-markers = [
    "python_full_version < '3.11'",
 ]
 dependencies = [
-    { name = "numpy", version = "2.2.6", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11'" },
+    { name = "numpy", version = "2.2.6", source = { registry = "https://pypi.org/simple" } },
 ]
 sdist = { url = "https://files.pythonhosted.org/packages/0f/37/6964b830433e654ec7485e45a00fc9a27cf868d622838f6b6d9c5ec0d532/scipy-1.15.3.tar.gz", hash = "sha256:eae3cf522bc7df64b42cad3925c876e1b0b6c35c1337c93e12c0f366f55b0eaf", size = 59419214, upload-time = "2025-05-08T16:13:05.955Z" }
 wheels = [
@@ -4843,7 +4846,7 @@ resolution-markers = [
    "python_full_version == '3.11.*'",
 ]
 dependencies = [
-    { name = "numpy", version = "2.4.6", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version == '3.11.*'" },
+    { name = "numpy", version = "2.4.6", source = { registry = "https://pypi.org/simple" } },
 ]
 sdist = { url = "https://files.pythonhosted.org/packages/7a/97/5a3609c4f8d58b039179648e62dd220f89864f56f7357f5d4f45c29eb2cc/scipy-1.17.1.tar.gz", hash = "sha256:95d8e012d8cb8816c226aef832200b1d45109ed4464303e997c5b13122b297c0", size = 30573822, upload-time = "2026-02-23T00:26:24.851Z" }
 wheels = [
@@ -4920,7 +4923,7 @@ resolution-markers = [
    "python_full_version >= '3.12' and python_full_version < '3.14'",
 ]
 dependencies = [
-    { name = "numpy", version = "2.5.1", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.12'" },
+    { name = "numpy", version = "2.5.1", source = { registry = "https://pypi.org/simple" } },
 ]
 sdist = { url = "https://files.pythonhosted.org/packages/a7/25/c2700dfaf6442b4effaa91af24ebce5dc9d31bb4a69706313aae70d72cd0/scipy-1.18.0.tar.gz", hash = "sha256:67b2ad2ad54c72ca6d04975a9b2df8c3638c34ddd5b28738e94fc2b57929d378", size = 30774447, upload-time = "2026-06-19T15:01:43.456Z" }
 wheels = [
@@ -1,6 +1,6 @@
 [package]
 name = "lancedb"
-version = "0.39.0-beta.1"
+version = "0.39.0-beta.4"
 edition.workspace = true
 description = "LanceDB: A serverless, low-latency vector database for AI applications"
 license.workspace = true
@@ -21,6 +21,8 @@ arrow-select = { workspace = true }
 arrow-ord = { workspace = true }
 arrow-cast = { workspace = true }
 arrow-ipc.workspace = true
+arrow-flight = { workspace = true, optional = true }
+prost = { version = "0.14", optional = true }
 chrono = { workspace = true }
 datafusion-catalog.workspace = true
 datafusion-common.workspace = true
@@ -77,6 +79,7 @@ reqwest = { version = "0.12.0", default-features = false, features = [
    "rustls-tls-native-roots",
    "stream",
 ], optional = true }
+tonic = { workspace = true, optional = true }
 http = { version = "1", optional = true } # Matching what is in reqwest
 urlencoding = { version = "2", optional = true }
 uuid = { workspace = true, features = ["v5"] }
@@ -145,8 +148,11 @@ huggingface = [
 ]
 dynamodb = ["lance/dynamodb", "aws"]
 remote = [
+    "dep:arrow-flight",
+    "dep:prost",
    "dep:reqwest",
    "dep:http",
+    "dep:tonic",
    "dep:urlencoding",
    "lance-namespace-impls/rest",
    "lance-namespace-impls/rest-adapter",
@@ -7,7 +7,9 @@
 //! raw `Binary` / `LargeBinary` into the blob struct layout. Queries return
 //! small descriptors, not bytes.
 //!
-//! Blob tables require Lance file format >= 2.2 and stable row ids at create.
+//! Blob tables require Lance file format >= 2.2. `_rowid` values stay valid
+//! after compaction when the table has stable row ids. Overwrite is a new
+//! create and does not keep the previous table's stable row id setting.

 use std::ops::Range;
 use std::sync::Arc;
@@ -324,6 +326,7 @@ pub(crate) fn blob_column_names(schema: &Schema) -> Vec<String> {
 }

 /// Bumps storage format to at least [`LanceFileVersion::V2_2`] for blob schemas.
+/// Leaves `enable_stable_row_ids` unchanged.
 pub(crate) fn ensure_blob_storage_version(schema: &Schema, params: &mut WriteParams) {
    if !has_blob_columns(schema) {
        return;
@@ -385,6 +388,30 @@ fn ensure_all_row_ids_resolved(column: &str, requested: usize, resolved: usize)
    }
 }

+/// Lance take reports a missing physical row address as NotSupported or InvalidInput.
+fn map_blob_take_error(column: &str, requested: usize, err: lance::Error) -> Error {
+    let missing_row_addr = match &err {
+        lance::Error::NotSupported { source, .. } => {
+            source.to_string().contains("must not target deleted rows")
+        }
+        lance::Error::InvalidInput { source, .. } => source
+            .to_string()
+            .contains("belongs to non-existent fragment"),
+        _ => false,
+    };
+
+    if missing_row_addr {
+        Error::InvalidInput {
+            message: format!(
+                "blob read for column '{column}' requested {requested} row ids but some \
+                 do not exist in the table; pass row ids collected from this table"
+            ),
+        }
+    } else {
+        err.into()
+    }
+}
+
 /// Materialize blob-local ranges (same length and order as `requests`, nulls preserved).
 pub(crate) async fn take_blob_ranges_aligned(
    dataset: &Arc<Dataset>,
@@ -405,7 +432,8 @@ pub(crate) async fn take_blob_ranges_aligned(
        .with_row_ids(lance_requests)
        .preserve_order(true)
        .execute()
-        .await?;
+        .await
+        .map_err(|err| map_blob_take_error(column, requests.len(), err))?;
    ensure_all_row_ids_resolved(column, requests.len(), payloads.len())?;

    let mut builder = LargeBinaryBuilder::new();
@@ -434,7 +462,8 @@ pub(crate) async fn take_blobs_aligned(
        .with_row_ids(row_ids.to_vec())
        .preserve_order(true)
        .execute()
-        .await?;
+        .await
+        .map_err(|err| map_blob_take_error(column, row_ids.len(), err))?;
    ensure_all_row_ids_resolved(column, row_ids.len(), payloads.len())?;

    let mut builder = LargeBinaryBuilder::new();
@@ -458,7 +487,10 @@ pub(crate) async fn take_blob_files_aligned(
        return Ok(Vec::new());
    }

-    let handles = dataset.take_blobs(row_ids, column).await?;
+    let handles = dataset
+        .take_blobs(row_ids, column)
+        .await
+        .map_err(|err| map_blob_take_error(column, row_ids.len(), err))?;
    ensure_all_row_ids_resolved(column, row_ids.len(), handles.len())?;
    Ok(handles
        .into_iter()
@@ -504,6 +536,21 @@ mod tests {
            params.data_storage_version.unwrap().resolve(),
            ConcreteFileVersion::V2_2
        );
+        assert!(!params.enable_stable_row_ids);
+    }
+
+    #[test]
+    fn storage_version_leaves_stable_row_ids_enabled() {
+        let mut params = WriteParams {
+            enable_stable_row_ids: true,
+            ..Default::default()
+        };
+        ensure_blob_storage_version(&blob_schema(), &mut params);
+        assert!(params.enable_stable_row_ids);
+        assert_eq!(
+            params.data_storage_version.unwrap().resolve(),
+            ConcreteFileVersion::V2_2
+        );
    }

    #[test]
@@ -576,5 +623,6 @@ mod tests {
        let mut params = WriteParams::default();
        ensure_blob_storage_version(&schema, &mut params);
        assert!(params.data_storage_version.is_none());
+        assert!(!params.enable_stable_row_ids);
    }
 }
@@ -23,15 +23,18 @@ use crate::connection::create_table::CreateTableBuilder;
 use crate::data::scannable::Scannable;
 use crate::database::listing::ListingDatabase;
 use crate::database::{
-    CloneTableRequest, Database, DatabaseOptions, JobDescription, JobInfo, OpenTableRequest,
-    ReadConsistency, TableNamesRequest,
+    CloneTableRequest, Database, DatabaseOptions, JobInfo, OpenTableRequest, ReadConsistency,
+    SecretInfo, TableNamesRequest,
 };
 use crate::embeddings::{EmbeddingRegistry, MemoryRegistry};
 use crate::error::{Error, Result};
 #[cfg(feature = "remote")]
 use crate::remote::{
    client::ClientConfig,
-    db::{OPT_REMOTE_API_KEY, OPT_REMOTE_HOST_OVERRIDE, OPT_REMOTE_REGION},
+    db::{
+        OPT_REMOTE_API_KEY, OPT_REMOTE_HOST_OVERRIDE, OPT_REMOTE_REGION,
+        OPT_REMOTE_SQL_HOST_OVERRIDE,
+    },
 };
 use lance::io::ObjectStoreParams;
 pub use lance_file::version::LanceFileVersion;
@@ -322,6 +325,43 @@ pub struct CloneTableBuilder {
    request: CloneTableRequest,
 }

+/// Builder for asynchronously executing a SQL statement on a remote database.
+pub struct ExecuteQueryAsyncBuilder {
+    parent: Arc<dyn Database>,
+    query: String,
+    default_namespace_path: Vec<String>,
+}
+
+impl ExecuteQueryAsyncBuilder {
+    fn new(parent: Arc<dyn Database>, query: String) -> Self {
+        Self {
+            parent,
+            query,
+            default_namespace_path: vec!["public".to_string()],
+        }
+    }
+
+    /// Set the namespace used for unqualified table names.
+    ///
+    /// An empty path is treated as `public`, which is the SQL name for the
+    /// root Lance namespace.
+    pub fn default_namespace_path<I, S>(mut self, path: I) -> Self
+    where
+        I: IntoIterator<Item = S>,
+        S: Into<String>,
+    {
+        self.default_namespace_path = path.into_iter().map(Into::into).collect();
+        self
+    }
+
+    /// Start the statement and return its asynchronous query handle.
+    pub async fn execute(self) -> Result<crate::sql::Query> {
+        self.parent
+            .execute_query_async(&self.query, &self.default_namespace_path)
+            .await
+    }
+}
+
 impl CloneTableBuilder {
    fn new(parent: Arc<dyn Database>, target_table_name: String, source_uri: String) -> Self {
        Self {
@@ -405,6 +445,51 @@ impl Connection {
        &self.internal
    }

+    /// Start executing SQL on a remote LanceDB database.
+    ///
+    /// The query can reference tables in other databases with SQL dot notation.
+    /// Use [`ExecuteQueryAsyncBuilder::default_namespace_path`] to avoid qualifying
+    /// tables in the default namespace. Local connections return
+    /// [`Error::NotSupported`].
+    ///
+    /// # Example
+    ///
+    /// ```no_run
+    /// # async fn query(db: &lancedb::Connection) -> lancedb::Result<()> {
+    /// use futures::TryStreamExt;
+    ///
+    /// let query = db
+    ///     .execute_query_async("SELECT * FROM events LIMIT 10")
+    ///     .default_namespace_path(["public"])
+    ///     .execute()
+    ///     .await?;
+    /// println!("query id: {}", query.id());
+    /// let mut batches = query.reader().await?;
+    /// while let Some(batch) = batches.try_next().await? {
+    ///     println!("received {} rows", batch.num_rows());
+    /// }
+    /// # Ok(())
+    /// # }
+    /// ```
+    pub fn execute_query_async(&self, query: impl Into<String>) -> ExecuteQueryAsyncBuilder {
+        ExecuteQueryAsyncBuilder::new(self.internal.clone(), query.into())
+    }
+
+    /// Describe a submitted SQL query by its connection-scoped id.
+    ///
+    /// This performs one bounded status poll using state retained by this
+    /// connection. Running state with a live query handle is not evicted;
+    /// abandoned state has bounded retention, and server expiration is
+    /// honored. Terminal state is retained briefly.
+    /// Query ids are not portable to another connection. Local connections
+    /// return [`Error::NotSupported`].
+    pub async fn describe_query(
+        &self,
+        query_id: uuid::Uuid,
+    ) -> Result<crate::sql::QueryDescription> {
+        self.internal.describe_query(query_id).await
+    }
+
    /// Get the names of all tables in the database
    ///
    /// The names will be returned in lexicographical order (ascending)
@@ -501,10 +586,15 @@ impl Connection {
    /// Registration is remote-only and always asynchronous. Waiting on the
    /// returned typed job yields the durable [`crate::function::FunctionVersion`].
    /// Local databases return [`Error::NotSupported`].
+    ///
+    /// The request's binding shape is validated here rather than in any one
+    /// language binding, so every client surface rejects the same envelopes
+    /// before one reaches the wire.
    pub async fn create_function_async(
        &self,
        request: crate::function::FunctionRegistrationRequest,
    ) -> Result<crate::job::Job<crate::function::FunctionVersion>> {
+        request.validate()?;
        self.internal.create_function_async(request).await
    }

@@ -560,6 +650,85 @@ impl Connection {
            .await
    }

+    /// Create a named Secret in this database.
+    ///
+    /// Fails if the name is taken, so a create can never silently become a
+    /// rotation. There is no API that reads a stored credential back; the only
+    /// consumer is a Function that binds the Secret by name. Local databases
+    /// return [`Error::NotSupported`].
+    pub async fn create_secret(
+        &self,
+        name: impl AsRef<str>,
+        value: impl AsRef<str>,
+        namespace_path: &[String],
+    ) -> Result<()> {
+        let value = value.as_ref();
+        crate::function::validate_secret_value(value)?;
+        self.internal
+            .create_secret(name.as_ref(), value, namespace_path)
+            .await
+    }
+
+    /// Replace the credential behind an existing Secret.
+    ///
+    /// Fails if it does not exist. Every Function bound to the Secret resolves
+    /// the new value from its next execution, and no new Function version is
+    /// minted -- which is what lets a rotation reach columns pinned to a
+    /// version registered before it. Local databases return
+    /// [`Error::NotSupported`].
+    pub async fn alter_secret(
+        &self,
+        name: impl AsRef<str>,
+        value: impl AsRef<str>,
+        namespace_path: &[String],
+    ) -> Result<()> {
+        let value = value.as_ref();
+        crate::function::validate_secret_value(value)?;
+        self.internal
+            .alter_secret(name.as_ref(), value, namespace_path)
+            .await
+    }
+
+    /// The names of every Secret in this database.
+    ///
+    /// Names only. No path in this API returns a stored credential, by
+    /// construction rather than by policy. Local databases return
+    /// [`Error::NotSupported`].
+    pub async fn list_secrets(&self, namespace_path: &[String]) -> Result<Vec<String>> {
+        self.internal.list_secrets(namespace_path).await
+    }
+
+    /// Drop a Secret.
+    ///
+    /// Functions bound to it fail at their next job, naming the Secret; that
+    /// is the revocation path. The name becomes free to reuse, and a new
+    /// Secret under it is picked up by everything still bound to that name.
+    /// Local databases return [`Error::NotSupported`].
+    pub async fn drop_secret(
+        &self,
+        name: impl AsRef<str>,
+        namespace_path: &[String],
+    ) -> Result<()> {
+        self.internal
+            .drop_secret(name.as_ref(), namespace_path)
+            .await
+    }
+
+    /// What this database records about one Secret: its name and timestamps.
+    ///
+    /// Never the value. The type it returns has no field for one, so this is a
+    /// property of the API rather than of what the caller chooses to read.
+    /// Local databases return [`Error::NotSupported`].
+    pub async fn describe_secret(
+        &self,
+        name: impl AsRef<str>,
+        namespace_path: &[String],
+    ) -> Result<SecretInfo> {
+        self.internal
+            .describe_secret(name.as_ref(), namespace_path)
+            .await
+    }
+
    /// Rename a table in the database.
    ///
    /// This is only supported in LanceDB Cloud.
@@ -585,14 +754,34 @@ impl Connection {
        self.internal.read_consistency().await
    }

-    /// A [`crate::job::Job`] handle for a server-side job by id, suitable for
-    /// waiting on or cancelling the job.
+    /// Open a server-side job by id, returning a handle with its record
+    /// already populated. Fails with [`crate::Error::JobNotFound`] when the
+    /// server has no such job, the way [`Connection::open_table`] does for a
+    /// missing table.
    ///
-    /// The handle is constructed without a server round trip; an unknown id
-    /// surfaces when the handle is used. Only server-backed databases support
-    /// job handles by id.
-    pub fn job(&self, job_id: impl AsRef<str>) -> Result<crate::job::Job> {
-        self.internal.job(job_id.as_ref())
+    /// This is the one way in: the returned [`crate::job::Job`] answers for
+    /// its own state, specification, result, failure and event history, so
+    /// there is no separate connection-level call for any of them.
+    ///
+    /// # Example
+    ///
+    /// ```no_run
+    /// # use lancedb::job::JobEventsRequest;
+    /// # async fn open_job(
+    /// #     connection: &lancedb::Connection,
+    /// #     job_id: &str,
+    /// # ) -> Result<(), Box<dyn std::error::Error>> {
+    /// let job = connection.open_job(job_id).await?;
+    /// println!("{:?} {:?}", job.state(), job.result());
+    /// let done = job
+    ///     .events(JobEventsRequest::default().filter("state = 'claim_complete'"))
+    ///     .await?;
+    /// println!("{} completions", done.iter().map(|b| b.num_rows()).sum::<usize>());
+    /// # Ok(())
+    /// # }
+    /// ```
+    pub async fn open_job(&self, job_id: impl AsRef<str>) -> Result<crate::job::Job> {
+        self.internal.open_job(job_id.as_ref()).await
    }

    /// List server-side jobs across the database's tables.
@@ -600,24 +789,12 @@ impl Connection {
        self.internal.list_jobs().await
    }

-    /// Describe a single server-side job by id. `None` when the server has no
-    /// such job.
-    pub async fn get_job(&self, job_id: impl AsRef<str>) -> Result<Option<JobDescription>> {
-        self.internal.get_job(job_id.as_ref()).await
-    }
-
    /// Request cancellation of a server-side job by id. Returns true if the
    /// server accepted the cancellation, false if no such job exists.
    pub async fn cancel_job(&self, job_id: impl AsRef<str>) -> Result<bool> {
        self.internal.cancel_job(job_id.as_ref()).await
    }

-    /// The lifecycle event history of a server-side job (all jobs when
-    /// `job_id` is `None`), as recorded Arrow batches.
-    pub async fn job_history(&self, job_id: Option<&str>) -> Result<Vec<RecordBatch>> {
-        self.internal.job_history(job_id).await
-    }
-
    /// Drop a table in the database.
    ///
    /// # Arguments
@@ -864,6 +1041,19 @@ impl ConnectBuilder {
        self
    }

+    /// Set the SQL service host override for a remote connection.
+    ///
+    /// The SQL client is initialized lazily when the connection first executes
+    /// SQL and is retained for the connection's lifetime.
+    #[cfg(feature = "remote")]
+    pub fn sql_host_override(mut self, sql_host_override: &str) -> Self {
+        self.request.options.insert(
+            OPT_REMOTE_SQL_HOST_OVERRIDE.to_string(),
+            sql_host_override.to_string(),
+        );
+        self
+    }
+
    /// Set the database specific options
    ///
    /// See [crate::database::listing::ListingDatabaseOptions] for the options available for
@@ -1053,6 +1243,7 @@ impl ConnectBuilder {

        let mut merged_options = self.request.options.clone();
        Self::apply_env_defaults(&ENV_VARS_TO_STORAGE_OPTS, &mut merged_options);
+        let sql_host_override = merged_options.get(OPT_REMOTE_SQL_HOST_OVERRIDE).cloned();
        let options = RemoteDatabaseOptions::parse_from_map(&merged_options)?;

        let region = options.region.ok_or_else(|| Error::InvalidInput {
@@ -1094,11 +1285,15 @@ impl ConnectBuilder {
        }

        let storage_options = StorageOptions(options.storage_options.clone());
+        let host_overrides = crate::remote::db::RemoteHostOverrides {
+            rest: options.host_override,
+            sql: sql_host_override,
+        };
        let internal = Arc::new(crate::remote::db::RemoteDatabase::try_new(
            &self.request.uri,
            &api_key,
            &region,
-            options.host_override,
+            host_overrides,
            client_config,
            storage_options.into(),
            self.request.read_consistency_interval,
@@ -1392,6 +1587,23 @@ mod tests {
        assert_eq!(tc.connection.uri(), tc.uri);
    }

+    #[tokio::test]
+    async fn test_local_connection_rejects_sql_queries() {
+        let directory = tempdir().unwrap();
+        let connection = connect(directory.path().to_str().unwrap())
+            .execute()
+            .await
+            .unwrap();
+        assert!(matches!(
+            connection.execute_query_async("SELECT 1").execute().await,
+            Err(Error::NotSupported { .. })
+        ));
+        assert!(matches!(
+            connection.describe_query(uuid::Uuid::nil()).await,
+            Err(Error::NotSupported { .. })
+        ));
+    }
+
    #[cfg(feature = "remote")]
    #[test]
    fn test_apply_env_defaults() {
@@ -18,8 +18,6 @@ use std::collections::HashMap;
 use std::sync::Arc;
 use std::time::Duration;

-use arrow_array::RecordBatch;
-
 use lance::dataset::ReadParams;
 use lance_namespace::LanceNamespace;
 use lance_namespace::models::{
@@ -206,8 +204,8 @@ pub enum ReadConsistency {
 /// compaction, column refresh, ...).
 #[derive(Debug, Clone)]
 pub struct JobInfo {
-    /// The job id -- what [`Database::get_job`] and [`Database::cancel_job`]
-    /// accept.
+    /// The job id -- what [`Database::open_job`] and
+    /// [`Database::cancel_job`] accept.
    pub job_id: String,
    /// The table the job runs against, without URI or namespace.
    pub table: String,
@@ -218,8 +216,8 @@ pub struct JobInfo {
    pub created_at_millis: i64,
 }

-/// A described job from [`Database::get_job`]: lifecycle state plus the
-/// job-type-specific specification.
+/// The server-side record behind a [`crate::job::Job`] handle: lifecycle
+/// state plus the job-type-specific specification and result.
 #[derive(Debug, Clone)]
 pub struct JobDescription {
    pub job_id: String,
@@ -230,6 +228,10 @@ pub struct JobDescription {
    pub creation_ms: i64,
    /// The job-type-specific specification. Null when the server omits it.
    pub spec: serde_json::Value,
+    /// The job-type-specific terminal result, for job types that define one.
+    /// `None` until the job succeeds, so a job that never terminates reports
+    /// its progress through [`crate::job::Job::events`] instead.
+    pub result: Option<serde_json::Value>,
    /// Why the job failed, when the job is failed and the server reports a
    /// reason.
    pub failure: Option<crate::error::JobFailure>,
@@ -247,9 +249,29 @@ fn function_catalog_not_supported<T>() -> Result<T> {
    })
 }

+fn secret_catalog_not_supported<T>() -> Result<T> {
+    Err(crate::error::Error::NotSupported {
+        message: "Secret operations are not supported by this database".to_string(),
+    })
+}
+
 /// The `Database` trait defines the interface for database implementations.
 ///
 /// A database is responsible for managing tables and their metadata.
+/// What a database records about a Secret. Never its value.
+///
+/// Returned by [`crate::connection::Connection::describe_secret`]. There is no
+/// field for the credential and no method that could produce one.
+#[derive(Debug, Clone, PartialEq, Eq, serde::Deserialize)]
+pub struct SecretInfo {
+    /// The Secret's database-scoped name.
+    pub name: String,
+    /// When the Secret was created, as an RFC 3339 timestamp.
+    pub created_at: String,
+    /// When the Secret's value was last rotated, as an RFC 3339 timestamp.
+    pub updated_at: String,
+}
+
 #[async_trait::async_trait]
 pub trait Database:
    Send + Sync + std::any::Any + std::fmt::Debug + std::fmt::Display + 'static
@@ -315,30 +337,75 @@ pub trait Database:
    async fn drop_function(&self, _name: &str, _version: &str) -> Result<bool> {
        function_catalog_not_supported()
    }
-    /// A [`crate::job::Job`] handle for a server-side job by id, suitable for
-    /// waiting on or cancelling the job. The handle is constructed without a
-    /// server round trip; an unknown id surfaces when the handle is used.
-    fn job(&self, _job_id: &str) -> Result<crate::job::Job> {
-        job_op_not_supported("job")
+    /// Create a named Secret in this database. Fails if the name is taken, so
+    /// a create can never silently become a rotation.
+    async fn create_secret(
+        &self,
+        _name: &str,
+        _value: &str,
+        _namespace_path: &[String],
+    ) -> Result<()> {
+        secret_catalog_not_supported()
+    }
+    /// Replace the credential behind an existing Secret. Fails if it does not
+    /// exist. Every Function bound to it resolves the new value from its next
+    /// execution, with no new Function version.
+    async fn alter_secret(
+        &self,
+        _name: &str,
+        _value: &str,
+        _namespace_path: &[String],
+    ) -> Result<()> {
+        secret_catalog_not_supported()
+    }
+    /// The names of every Secret in this database.
+    ///
+    /// Names only. No API path returns a stored credential, by construction
+    /// rather than by policy.
+    async fn list_secrets(&self, _namespace_path: &[String]) -> Result<Vec<String>> {
+        secret_catalog_not_supported()
+    }
+    /// Drop a Secret. Functions bound to it fail at their next job, which is
+    /// the revocation path.
+    async fn drop_secret(&self, _name: &str, _namespace_path: &[String]) -> Result<()> {
+        secret_catalog_not_supported()
+    }
+    /// What the database records about one Secret: its name and timestamps,
+    /// never its value.
+    async fn describe_secret(&self, _name: &str, _namespace_path: &[String]) -> Result<SecretInfo> {
+        secret_catalog_not_supported()
+    }
+    /// Open a job by id, returning a handle with its record already
+    /// populated. Fails with [`crate::Error::JobNotFound`] when the server has
+    /// no such job.
+    async fn open_job(&self, _job_id: &str) -> Result<crate::job::Job> {
+        job_op_not_supported("open_job")
    }
    /// List server-side jobs across the database's tables.
    async fn list_jobs(&self) -> Result<Vec<JobInfo>> {
        job_op_not_supported("list_jobs")
    }
-    /// Describe a single job by id. `None` when the server has no such job.
-    async fn get_job(&self, _job_id: &str) -> Result<Option<JobDescription>> {
-        job_op_not_supported("get_job")
-    }
    /// Request cancellation of a job by id. Returns true if the server
    /// accepted the cancellation, false if no such job exists. Cancelling an
    /// already-terminal job is a no-op success.
    async fn cancel_job(&self, _job_id: &str) -> Result<bool> {
        job_op_not_supported("cancel_job")
    }
-    /// The lifecycle event history of a job (all jobs when `job_id` is
-    /// `None`), as recorded Arrow batches.
-    async fn job_history(&self, _job_id: Option<&str>) -> Result<Vec<RecordBatch>> {
-        job_op_not_supported("job_history")
+    /// Start executing a SQL statement on a remote database.
+    async fn execute_query_async(
+        &self,
+        _query: &str,
+        _default_namespace_path: &[String],
+    ) -> Result<crate::sql::Query> {
+        Err(crate::error::Error::NotSupported {
+            message: "SQL is not supported by this database".to_string(),
+        })
+    }
+    /// Describe a submitted SQL query by its connection-scoped id.
+    async fn describe_query(&self, _query_id: uuid::Uuid) -> Result<crate::sql::QueryDescription> {
+        Err(crate::error::Error::NotSupported {
+            message: "SQL is not supported by this database".to_string(),
+        })
    }
    /// Open a table in the database
    async fn open_table(&self, request: OpenTableRequest) -> Result<Arc<dyn BaseTable>>;
@@ -18,7 +18,7 @@ use lance_table::io::commit::commit_handler_from_url;
 use object_store::local::LocalFileSystem;
 use snafu::ResultExt;

-use crate::blob::{ensure_blob_storage_version, has_blob_columns};
+use crate::blob::ensure_blob_storage_version;
 use crate::connection::ConnectRequest;
 use crate::database::ReadConsistency;
 use crate::database::namespace::LanceNamespaceDatabase;
@@ -827,7 +827,6 @@ impl ListingDatabase {
        if let Some(enable_stable_row_ids) = overrides
            .enable_stable_row_ids
            .or(self.new_table_config.enable_stable_row_ids)
-            .or(has_blob_columns(&data_schema).then_some(true))
        {
            write_params.enable_stable_row_ids = enable_stable_row_ids;
        }
@@ -23,7 +23,7 @@ use lance_namespace_impls::ConnectBuilder;
 use lance_table::io::commit::CommitHandler;
 use lance_table::io::commit::external_manifest::ExternalManifestCommitHandler;

-use crate::blob::{ensure_blob_storage_version, has_blob_columns};
+use crate::blob::ensure_blob_storage_version;
 use crate::connection::NamespaceClientPushdownOperation;
 use crate::database::ReadConsistency;
 use crate::database::listing::{NewTableConfig, take_request_creation_overrides};
@@ -217,7 +217,6 @@ impl LanceNamespaceDatabase {
        if let Some(enable_stable_row_ids) = overrides
            .enable_stable_row_ids
            .or(self.new_table_config.enable_stable_row_ids)
-            .or(has_blob_columns(data_schema.as_ref()).then_some(true))
        {
            params.enable_stable_row_ids = enable_stable_row_ids;
        }
@@ -102,6 +102,8 @@ pub enum Error {
    },
    #[snafu(display("Job{} was cancelled", job_id.as_ref().map(|id| format!(" {id}")).unwrap_or_default()))]
    JobCancelled { job_id: Option<String> },
+    #[snafu(display("Job '{job_id}' was not found"))]
+    JobNotFound { job_id: String },

    // 3rd party / external errors
    #[snafu(display("object_store error: {source}"))]
@@ -5,7 +5,7 @@
 //! backend-neutral terminal result of a computed-column refresh.
 //!
 //! This module contains client/wire values only. Catalog persistence,
-//! environment bake, and execution are owned by Sophon.
+//! environment bake, secret resolution, and execution are owned by Sophon.

 use std::collections::BTreeMap;

@@ -409,6 +409,8 @@ pub struct FunctionVersion {
    runtime: PythonRuntimeSpec,
    runtime_digest: String,
    environment_digest: String,
+    #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
+    secret_env_bindings: BTreeMap<String, SecretReference>,
    created_at: String,
 }

@@ -441,6 +443,16 @@ impl FunctionVersion {
        &self.environment_digest
    }

+    /// Declared environment variable name to the Secret each one resolves.
+    ///
+    /// Bindings are part of this version's identity; the credentials behind
+    /// them are not, and resolve at execution. Rotating a bound Secret
+    /// therefore changes what the same version runs with, and no value has a
+    /// field in this model.
+    pub fn secret_env_bindings(&self) -> &BTreeMap<String, SecretReference> {
+        &self.secret_env_bindings
+    }
+
    pub fn created_at(&self) -> &str {
        &self.created_at
    }
@@ -481,13 +493,186 @@ pub struct FunctionArtifactRequest {
    pub adapter: PythonAdapterSpec,
 }

+/// A Function binds at most this many Secrets to environment variables.
+///
+/// Each bound Secret is one extra read on the launch path of every fragment, so
+/// the count needs a bound for the same reason a credential needs a size limit.
+pub const MAX_FUNCTION_SECRET_ENV_BINDINGS: usize = 16;
+
+/// Where a Secret lives, carried as its parts rather than as one string.
+///
+/// A joined id would need a delimiter, and a delimiter has to be excluded from
+/// every name and segment forever, agreed on by both sides, and re-agreed each
+/// time either grows a new way to be configured. Naming the parts costs one
+/// object and settles all of that: nothing here is parsed, so nothing can parse
+/// two ways.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct SecretReference {
+    pub name: String,
+    /// The namespace holding the Secret. Empty is the root, and is omitted from
+    /// the wire so a root binding carries no trace of a feature it does not use.
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
+    pub namespace_path: Vec<String>,
+}
+
+impl SecretReference {
+    /// A Secret in the root namespace.
+    pub fn new(name: impl Into<String>) -> Self {
+        Self {
+            name: name.into(),
+            namespace_path: Vec::new(),
+        }
+    }
+
+    /// A Secret in `namespace_path`.
+    pub fn in_namespace(name: impl Into<String>, namespace_path: Vec<String>) -> Self {
+        Self {
+            name: name.into(),
+            namespace_path,
+        }
+    }
+
+    fn validate(&self) -> Result<()> {
+        validate_secret_component("Secret name", &self.name)?;
+        for segment in &self.namespace_path {
+            validate_secret_component("Secret namespace path segment", segment)?;
+        }
+        Ok(())
+    }
+}
+
+/// A Secret name or one namespace path segment.
+///
+/// Periods are legal here and delimiters are not a concern: a reference is
+/// never joined into one string, so the only rule left is the character set the
+/// service stores.
+fn validate_secret_component(what: &str, value: &str) -> Result<()> {
+    if value.is_empty() || value.len() > MAX_SECRET_NAME_BYTES {
+        return Err(Error::InvalidInput {
+            message: format!(
+                "{what} must be 1..={MAX_SECRET_NAME_BYTES} bytes, got {}",
+                value.len()
+            ),
+        });
+    }
+    if let Some(bad) = value
+        .chars()
+        .find(|c| !c.is_ascii_alphanumeric() && *c != '_' && *c != '-' && *c != '.')
+    {
+        return Err(Error::InvalidInput {
+            message: format!("{what} must match [A-Za-z0-9_.-], and {bad:?} does not"),
+        });
+    }
+    Ok(())
+}
+
+/// Longest Secret name or namespace path segment, matching the service.
+pub const MAX_SECRET_NAME_BYTES: usize = 255;
+
+/// Largest credential a Secret may hold, matching the limit the service
+/// enforces. Bounded because the value is destined for a process environment.
+pub const MAX_SECRET_VALUE_BYTES: usize = 64 * 1024;
+
+/// Whether `name` is a portable POSIX environment variable name.
+///
+/// Leading letter or underscore, then letters, digits, or underscores. Names
+/// reserved by the execution sandbox are deliberately not checked here: that
+/// list belongs to the runtime that owns it, and a copy in the client would
+/// drift from it silently.
+fn is_portable_env_name(name: &str) -> bool {
+    let mut bytes = name.bytes();
+    bytes
+        .next()
+        .is_some_and(|byte| byte == b'_' || byte.is_ascii_alphabetic())
+        && bytes.all(|byte| byte == b'_' || byte.is_ascii_alphanumeric())
+}
+
+/// Reject a credential the service would refuse on size alone.
+///
+/// Checked before the request body is built, so an oversized value is never
+/// serialized or uploaded.
+pub(crate) fn validate_secret_value(value: &str) -> Result<()> {
+    if value.is_empty() {
+        return Err(Error::InvalidInput {
+            message: "a Secret value must not be empty".to_string(),
+        });
+    }
+    if value.contains('\0') {
+        return Err(Error::InvalidInput {
+            message: "a Secret value must not contain NUL".to_string(),
+        });
+    }
+    if value.len() > MAX_SECRET_VALUE_BYTES {
+        return Err(Error::InvalidInput {
+            message: format!(
+                "a Secret value is at most {MAX_SECRET_VALUE_BYTES} bytes, not {}",
+                value.len()
+            ),
+        });
+    }
+    Ok(())
+}
+
 /// Stable request envelope for remote immutable Function registration.
+///
+/// Credential values deliberately have no field here. The only secret-shaped
+/// thing a client sends is `secret_env_bindings`: the name of a Secret the
+/// database already holds, which Sophon resolves inside the remote runtime.
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
 pub struct FunctionRegistrationRequest {
    pub name: String,
    pub artifact: FunctionArtifactRequest,
    pub signature: FunctionSignature,
    pub runtime: PythonRuntimeSpec,
+    /// Declared environment variable name to the Secret it binds. A binding is
+    /// a reference: whether the Secret exists is answered when a column is
+    /// declared against this version, not here.
+    #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
+    pub secret_env_bindings: BTreeMap<String, SecretReference>,
+}
+
+impl FunctionRegistrationRequest {
+    /// Reject a registration whose bindings exceed what a launch can deliver.
+    ///
+    /// Shape only, and deliberately not a check that each bound Secret exists:
+    /// that is the service's answer, and it is asked for the first time when a
+    /// column is declared against the registered version.
+    pub fn validate(&self) -> Result<()> {
+        if self.secret_env_bindings.len() > MAX_FUNCTION_SECRET_ENV_BINDINGS {
+            return Err(Error::InvalidInput {
+                message: format!(
+                    "a Function binds at most {MAX_FUNCTION_SECRET_ENV_BINDINGS} secrets, not {}",
+                    self.secret_env_bindings.len()
+                ),
+            });
+        }
+        for (variable, secret) in &self.secret_env_bindings {
+            secret.validate()?;
+            if !is_portable_env_name(variable) {
+                return Err(Error::InvalidInput {
+                    message: format!(
+                        "secret_env_bindings key '{variable}' is not a portable \
+                         environment variable name"
+                    ),
+                });
+            }
+            // `env` travels with the Function and is readable wherever its
+            // record is; a bound Secret is not. One name carrying both would
+            // resolve by delivery order, so refuse rather than pick.
+            if self
+                .runtime
+                .env()
+                .is_some_and(|env| env.contains_key(variable))
+            {
+                return Err(Error::InvalidInput {
+                    message: format!(
+                        "secret_env_bindings key '{variable}' is already set by runtime.env"
+                    ),
+                });
+            }
+        }
+        Ok(())
+    }
 }

 impl_json!(FunctionRegistrationRequest);
@@ -582,8 +767,8 @@ pub struct InputBinding {

 /// Ordered result-field to table-field mapping for a Function binding.
 ///
-/// Assignment state is not part of the Slice 1 client contract. During the
-/// NULL transition there is no public Lance cell-flag identifier to persist.
+/// `nullable` describes the logical Function result. Physical computed-column
+/// fields remain nullable while unassigned.
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
 pub struct OutputMapping {
    pub result_field: String,
@@ -594,6 +779,14 @@ pub struct OutputMapping {
    pub nullable: bool,
 }

+/// Internal physical column preserving the parent validity of a flattened
+/// named-struct result.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct AssignmentMapping {
+    pub output_name: String,
+    pub output_field_id: i32,
+}
+
 /// Immutable Function binding persisted by the Enterprise table service.
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
 pub struct FunctionBinding {
@@ -601,6 +794,8 @@ pub struct FunctionBinding {
    function: FunctionVersionRef,
    inputs: Vec<InputBinding>,
    outputs: Vec<OutputMapping>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    assignment: Option<AssignmentMapping>,
    /// Exact Arrow schema presented to the Function, encoded with the Lance
    /// Namespace Arrow JSON representation.
    #[serde(default, skip_serializing_if = "Option::is_none")]
@@ -627,6 +822,10 @@ impl FunctionBinding {
        &self.outputs
    }

+    pub fn assignment(&self) -> Option<&AssignmentMapping> {
+        self.assignment.as_ref()
+    }
+
    pub fn input_schema(&self) -> Option<&Value> {
        self.input_schema.as_ref()
    }
@@ -200,14 +200,14 @@ impl IndexBuilder {
            parent,
            index,
            columns,
-            replace: false,
+            replace: true,
            train: true,
            wait_timeout: None,
            name: None,
        }
    }

-    /// Whether to replace the existing index, the default is `false`.
+    /// Whether to replace the existing index, the default is `true`.
    ///
    /// If this is false, and another index already exists on the same columns
    /// and the same name, then an error will be returned.  This is true even if
@@ -3,16 +3,53 @@

 //! Handles to operations a server may run asynchronously.

-use std::sync::Arc;
+use std::sync::{Arc, RwLock, RwLockReadGuard, RwLockWriteGuard};

+use arrow_array::RecordBatch;
 use async_trait::async_trait;
 use serde::{Serialize, de::DeserializeOwned};
 use serde_json::Value;
 use tokio::sync::watch;
 use tokio::task::{AbortHandle, JoinHandle};

+use crate::database::JobDescription;
 use crate::error::{Error, JobFailure, Result};

+/// Which of a job's events [`Job::events`] returns.
+///
+/// The handle already knows which job to ask about, so this narrows the
+/// query rather than naming one.
+#[derive(Debug, Clone, Default)]
+pub struct JobEventsRequest {
+    /// Maximum event rows to return. The server applies its own default
+    /// (1000 rows) and maximum (10,000 rows) when this is `None`, and
+    /// truncates without saying so, which matters for a job with one event
+    /// per fragment.
+    pub limit: Option<u32>,
+    /// SQL-like filter over the event columns `state`, `updated_by`,
+    /// `emitted_from`, `emitted_by`, and `claim_entity`. For example
+    /// `state = 'claim_complete'` selects only per-claim completions.
+    pub filter: Option<String>,
+}
+
+impl JobEventsRequest {
+    pub fn limit(mut self, limit: u32) -> Self {
+        self.limit = Some(limit);
+        self
+    }
+
+    pub fn filter(mut self, filter: impl Into<String>) -> Self {
+        self.filter = Some(filter.into());
+        self
+    }
+}
+
+fn job_detail_not_supported<T>(what: &str) -> Result<T> {
+    Err(Error::NotSupported {
+        message: format!("{what} is only available for server-side jobs"),
+    })
+}
+
 /// Backend-specific tracking for an asynchronous operation.
 #[async_trait]
 pub(crate) trait JobHandle: Send + Sync {
@@ -23,6 +60,15 @@ pub(crate) trait JobHandle: Send + Sync {
    async fn status(&self) -> Result<String>;
    async fn wait(&self) -> Result<TerminalResult>;
    async fn cancel(&self) -> Result<()>;
+    /// The job's full server-side record. Backends that run the operation in
+    /// this process have none and keep the default.
+    async fn describe(&self) -> Result<JobDescription> {
+        job_detail_not_supported("describing a job")
+    }
+    /// The job's recorded lifecycle events.
+    async fn events(&self, _request: JobEventsRequest) -> Result<Vec<RecordBatch>> {
+        job_detail_not_supported("job event history")
+    }
 }

 /// A backend-neutral successful terminal result.
@@ -40,7 +86,6 @@ impl TerminalResult {
        }
    }

-    #[cfg(feature = "remote")]
    pub(crate) fn remote(value: Option<Value>, request_id: String) -> Self {
        Self {
            value,
@@ -48,46 +93,30 @@ impl TerminalResult {
        }
    }

-    #[cfg(feature = "remote")]
    pub(crate) fn value(&self) -> Option<&Value> {
        self.value.as_ref()
    }

    fn decode<T: DeserializeOwned>(self) -> Result<T> {
-        let value = self.value.ok_or_else(|| {
-            #[cfg(feature = "remote")]
-            if let Some(request_id) = &self.request_id {
-                return Error::Http {
-                    source: "successful typed job response did not contain a result".into(),
-                    request_id: request_id.clone(),
-                    status_code: None,
-                };
-            }
-            Error::Runtime {
+        let value = self.value.ok_or_else(|| match &self.request_id {
+            Some(request_id) => Error::Http {
+                source: "successful typed job response did not contain a result".into(),
+                request_id: request_id.clone(),
+                status_code: None,
+            },
+            None => Error::Runtime {
                message: "successful typed job did not contain a result".to_string(),
-            }
+            },
        })?;
-        serde_json::from_value(value).map_err(|error| {
-            #[cfg(feature = "remote")]
-            {
-                match self.request_id {
-                    Some(request_id) => Error::Http {
-                        source: format!("failed to parse typed job result: {error}").into(),
-                        request_id,
-                        status_code: None,
-                    },
-                    None => Error::Runtime {
-                        message: format!("failed to parse typed job result: {error}"),
-                    },
-                }
-            }
-            #[cfg(not(feature = "remote"))]
-            {
-                let _ = self.request_id;
-                Error::Runtime {
-                    message: format!("failed to parse typed job result: {error}"),
-                }
-            }
+        serde_json::from_value(value).map_err(|error| match self.request_id {
+            Some(request_id) => Error::Http {
+                source: format!("failed to parse typed job result: {error}").into(),
+                request_id,
+                status_code: None,
+            },
+            None => Error::Runtime {
+                message: format!("failed to parse typed job result: {error}"),
+            },
        })
    }
 }
@@ -102,16 +131,34 @@ enum JobInner<T> {
    Completed(T),
 }

+/// What a handle last learned about its job. `state` is separate because an
+/// in-process job can report one but has no server-side record behind it.
+#[derive(Default)]
+struct JobCache {
+    state: Option<String>,
+    description: Option<JobDescription>,
+}
+
 /// A handle to an operation that may still be running.
 ///
 /// The operation may already be complete when the handle is created. `T` is
 /// the endpoint's successful terminal result; unit-result operations use the
 /// default `Job<()>`.
+///
+/// The detail accessors ([`Job::state`], [`Job::job_type`], ...) read what the
+/// handle last observed. Submitting an operation returns only a job id, so
+/// populating them eagerly would cost an extra round trip on every call:
+///
+/// - [`Job::refresh`] and [`Job::status`] fetch the whole record.
+/// - [`Job::wait`] records the terminal state it establishes, but not the rest
+///   of the record; call [`Job::refresh`] for that.
+/// - Everything is `None` until one of those runs.
 pub struct Job<T = ()>
 where
    T: Clone + Send + Sync + 'static,
 {
    inner: JobInner<T>,
+    cache: RwLock<JobCache>,
 }

 impl<T> std::fmt::Debug for Job<T>
@@ -119,30 +166,64 @@ where
    T: Clone + Send + Sync + 'static,
 {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
-        f.debug_struct("Job")
-            .field("id", &self.id())
-            .field("done", &matches!(self.inner, JobInner::Completed(_)))
-            .finish()
+        let cache = self.cache_read();
+        let mut out = f.debug_struct("Job");
+        out.field("id", &self.id())
+            .field("done", &matches!(self.inner, JobInner::Completed(_)));
+        if let Some(state) = &cache.state {
+            out.field("state", state);
+        }
+        if let Some(description) = &cache.description {
+            out.field("job_type", &description.job_type)
+                .field("creation_ms", &description.creation_ms);
+            if !description.spec.is_null() {
+                out.field("spec", &description.spec);
+            }
+            if let Some(result) = &description.result {
+                out.field("result", result);
+            }
+            if let Some(failure) = &description.failure {
+                out.field("failure", failure);
+            }
+        }
+        out.finish()
    }
 }

 impl Job<()> {
-    /// A job whose operation finished before the handle was created.
+    /// A job whose operation finished before the handle was created. Its
+    /// state is known without asking anyone, so the cache starts populated.
    pub(crate) fn new_done() -> Self {
        Self {
            inner: JobInner::Completed(()),
+            cache: RwLock::new(JobCache {
+                state: Some("finished".to_string()),
+                description: None,
+            }),
        }
    }

-    #[cfg(feature = "remote")]
    pub(crate) fn new(handle: Box<dyn JobHandle>) -> Self {
        Self {
            inner: JobInner::Handle {
                handle,
                decode: Arc::new(|_| Ok(())),
            },
+            cache: RwLock::default(),
        }
    }
+
+    /// A handle whose record the caller has already fetched, so the detail
+    /// accessors answer without a second round trip.
+    pub(crate) fn opened(handle: Box<dyn JobHandle>, description: JobDescription) -> Self {
+        let job = Self::new(handle);
+        {
+            let mut cache = job.cache_write();
+            cache.state = Some(description.state.clone());
+            cache.description = Some(description);
+        }
+        job
+    }
 }

 impl<T> Job<T>
@@ -156,6 +237,7 @@ where
                handle,
                decode: Arc::new(TerminalResult::decode::<T>),
            },
+            cache: RwLock::default(),
        }
    }
 }
@@ -187,16 +269,124 @@ where
        }
    }

+    fn cache_read(&self) -> RwLockReadGuard<'_, JobCache> {
+        self.cache.read().unwrap_or_else(|err| err.into_inner())
+    }
+
+    fn cache_write(&self) -> RwLockWriteGuard<'_, JobCache> {
+        self.cache.write().unwrap_or_else(|err| err.into_inner())
+    }
+
+    /// Asks the backend for this job's current state, and for a server-side
+    /// job its full record, then caches the answer for the detail accessors.
+    ///
+    /// In-process operations have no server-side record, so only
+    /// [`Job::state`] is populated for them.
+    pub async fn refresh(&self) -> Result<()> {
+        self.refresh_state().await.map(|_| ())
+    }
+
+    /// Refreshes and reports the state, which every backend can answer.
+    async fn refresh_state(&self) -> Result<String> {
+        let JobInner::Handle { handle, .. } = &self.inner else {
+            let state = "finished".to_string();
+            self.cache_write().state = Some(state.clone());
+            return Ok(state);
+        };
+        match handle.describe().await {
+            Ok(description) => {
+                let state = description.state.clone();
+                let mut cache = self.cache_write();
+                cache.state = Some(state.clone());
+                cache.description = Some(description);
+                Ok(state)
+            }
+            // An in-process job knows its own state and nothing more.
+            Err(Error::NotSupported { .. }) => {
+                let state = handle.status().await?;
+                self.cache_write().state = Some(state.clone());
+                Ok(state)
+            }
+            Err(err) => Err(err),
+        }
+    }
+
    /// The operation's current lifecycle state: "running", "finished",
    /// "failed", or "cancelled".
    ///
    /// A point snapshot; unlike [`Job::wait`] it does not block, raise on a
    /// terminal failure state, or retry. States a newer server reports that
-    /// this client version does not know pass through as-is.
+    /// this client version does not know pass through as-is. Also refreshes
+    /// the detail accessors.
    pub async fn status(&self) -> Result<String> {
+        self.refresh_state().await
+    }
+
+    /// The last lifecycle state this handle observed, without contacting the
+    /// backend. `None` until the handle has.
+    pub fn state(&self) -> Option<String> {
+        self.cache_read().state.clone()
+    }
+
+    /// The whole server-side record this handle last observed. The accessors
+    /// below read individual fields out of it. `None` for an in-process job,
+    /// which has no such record.
+    pub fn description(&self) -> Option<JobDescription> {
+        self.cache_read().description.clone()
+    }
+
+    /// The job's type, as the server names it. `None` for an in-process job.
+    pub fn job_type(&self) -> Option<String> {
+        self.with_description(|description| description.job_type.clone())
+    }
+
+    /// When the job was created, in milliseconds since the epoch. `None` for
+    /// an in-process job.
+    pub fn creation_ms(&self) -> Option<i64> {
+        self.with_description(|description| description.creation_ms)
+    }
+
+    /// The job-type-specific specification it was submitted with.
+    pub fn spec(&self) -> Option<Value> {
+        self.with_description(|description| description.spec.clone())
+            .filter(|spec| !spec.is_null())
+    }
+
+    /// The job-type-specific terminal result, as reported data rather than the
+    /// typed model [`Job::wait`] returns. `None` until the job succeeds.
+    pub fn result(&self) -> Option<Value> {
+        self.with_description(|description| description.result.clone())
+            .flatten()
+    }
+
+    /// Why the job failed, when it failed and the server reports a reason.
+    pub fn failure(&self) -> Option<JobFailure> {
+        self.with_description(|description| description.failure.clone())
+            .flatten()
+    }
+
+    fn with_description<R>(&self, read: impl FnOnce(&JobDescription) -> R) -> Option<R> {
+        self.cache_read().description.as_ref().map(read)
+    }
+
+    /// This job's recorded lifecycle events.
+    ///
+    /// Unlike the detail accessors, which report a terminal result only once
+    /// the job reaches one, events are written as the job runs and outlive the
+    /// workers that produced them. A distributed job records a
+    /// `claim`/`claim_complete` pair per unit of work, each carrying
+    /// `rows_processed`, so a job that never finishes still accounts for what
+    /// it did. In-process operations keep no event history.
+    pub async fn events(&self, request: JobEventsRequest) -> Result<Vec<RecordBatch>> {
        match &self.inner {
-            JobInner::Handle { handle, .. } => handle.status().await,
-            JobInner::Completed(_) => Ok("finished".to_string()),
+            JobInner::Handle { handle, .. } => handle.events(request).await,
+            // The operation finished before the handle existed, so there is no
+            // id to query with even when a server ran it.
+            JobInner::Completed(_) => Err(Error::NotSupported {
+                message: "this operation completed before its handle was created, so it \
+                          carries no job id to query events with"
+                    .to_string(),
+            }),
        }
    }

@@ -208,8 +398,19 @@ where
    /// [`crate::Error::JobCancelled`] if it was cancelled.
    pub async fn wait(&self) -> Result<T> {
        match &self.inner {
-            JobInner::Handle { handle, decode } => (decode)(handle.wait().await?),
-            JobInner::Completed(result) => Ok(result.clone()),
+            JobInner::Handle { handle, decode } => {
+                let settled = handle.wait().await;
+                // Waiting already established a terminal state; record it so
+                // the detail accessors do not need another round trip for it.
+                if let Some(state) = terminal_state(&settled) {
+                    self.cache_write().state = Some(state.to_string());
+                }
+                (decode)(settled?)
+            }
+            JobInner::Completed(result) => {
+                self.cache_write().state = Some("finished".to_string());
+                Ok(result.clone())
+            }
        }
    }

@@ -242,20 +443,36 @@ where
        U: Clone + Send + Sync + 'static,
        F: Fn(T) -> U + Send + Sync + 'static,
    {
-        match self.inner {
+        // The mapped handle tracks the same job, so it inherits what this one
+        // has already learned about it.
+        let Self { inner, cache } = self;
+        match inner {
            JobInner::Handle { handle, decode } => Job {
                inner: JobInner::Handle {
                    handle,
                    decode: Arc::new(move |result| Ok(map((decode)(result)?))),
                },
+                cache,
            },
            JobInner::Completed(result) => Job {
                inner: JobInner::Completed(map(result)),
+                cache,
            },
        }
    }
 }

+/// The lifecycle state a settled [`JobHandle::wait`] implies.
+fn terminal_state(settled: &Result<TerminalResult>) -> Option<&'static str> {
+    match settled {
+        Ok(_) => Some("finished"),
+        Err(Error::JobFailed { .. }) => Some("failed"),
+        Err(Error::JobCancelled { .. }) => Some("cancelled"),
+        // Anything else is a transport failure, not a verdict on the job.
+        Err(_) => None,
+    }
+}
+
 /// How an in-process operation ended. Cloneable so every waiter can be given
 /// the outcome; [`Error`] is not, so failures share one behind an [`Arc`].
 #[derive(Clone)]
@@ -195,6 +195,7 @@ pub mod query;
 #[cfg(feature = "remote")]
 pub mod remote;
 pub mod rerankers;
+pub mod sql;
 pub mod table;
 #[cfg(test)]
 pub mod test_utils;
@@ -11,6 +11,7 @@ pub(crate) mod db;
 pub(crate) mod job;
 pub mod oauth;
 mod retry;
+pub(crate) mod sql;
 pub(crate) mod table;
 pub(crate) mod util;

@@ -404,6 +404,18 @@ fn validate_dns_hostname(hostname: &str) -> Result<()> {
    Ok(())
 }

+/// Whether a route's request body is a credential rather than a description of
+/// one.
+///
+/// Matched on the path segment rather than a versioned prefix, so a `/v2/` bump
+/// or a route added under the namespace later is covered without anyone
+/// remembering to extend this. Every secrets route is denied, not only the two
+/// that carry a value: their bodies hold names and page tokens, which are worth
+/// nothing in a debug log next to the risk of a new verb landing here unnoticed.
+fn route_carries_credential(path: &str) -> bool {
+    path.split('/').any(|segment| segment == "secrets")
+}
+
 impl RestfulLanceDbClient<Sender> {
    fn get_timeout(passed: Option<Duration>, env_var: &str) -> Result<Option<Duration>> {
        if let Some(passed) = passed {
@@ -610,12 +622,14 @@ impl<S: HttpSend> RestfulLanceDbClient<S> {
    ) -> Result<HeaderMap> {
        let mut headers = HeaderMap::new();
        if !api_key.is_empty() {
-            headers.insert(
-                HeaderName::from_static("x-api-key"),
-                HeaderValue::from_str(api_key).map_err(|_| Error::InvalidInput {
-                    message: "non-ascii api key provided".to_string(),
-                })?,
-            );
+            // `log_request` prints the request's Debug, which prints headers.
+            // Marking the value sensitive is what makes that print `Sensitive`
+            // instead of the key itself.
+            let mut key = HeaderValue::from_str(api_key).map_err(|_| Error::InvalidInput {
+                message: "non-ascii api key provided".to_string(),
+            })?;
+            key.set_sensitive(true);
+            headers.insert(HeaderName::from_static("x-api-key"), key);
        }
        if region == "local" {
            let host = format!("{}.local.api.lancedb.com", db_name);
@@ -845,7 +859,12 @@ impl<S: HttpSend> RestfulLanceDbClient<S> {
                .headers()
                .get("content-type")
                .map(|v| v.to_str().unwrap());
-            if content_type == Some("application/json") {
+            if route_carries_credential(request.url().path()) {
+                debug!(
+                    "Sending request_id={}: {:?} with body suppressed",
+                    request_id, request
+                );
+            } else if content_type == Some("application/json") {
                let body = request.body().as_ref().unwrap().as_bytes().unwrap();
                let body = String::from_utf8_lossy(body);
                debug!(
@@ -1192,6 +1211,56 @@ mod tests {
        assert_eq!(headers.get("x-api-key").unwrap(), "api-key");
    }

+    /// `log_request` prints the request's Debug, and Debug for a request prints
+    /// its headers. Marking the value sensitive is the only thing standing
+    /// between the API key and every debug line; assert on the header map's own
+    /// Debug, which is what that printing reduces to.
+    #[test]
+    fn test_api_key_is_redacted_in_debug_output() {
+        let headers = RestfulLanceDbClient::<Sender>::default_headers(
+            "sk-live-sentinel",
+            "us-east-1",
+            "db-name",
+            false,
+            &RemoteOptions::default(),
+            None,
+            &ClientConfig::default(),
+        )
+        .unwrap();
+
+        assert_eq!(headers.get("x-api-key").unwrap(), "sk-live-sentinel");
+        assert!(
+            !format!("{:?}", headers).contains("sk-live-sentinel"),
+            "the API key must not survive Debug formatting"
+        );
+    }
+
+    /// Denial follows the path segment, so a verb that does not exist yet and a
+    /// future API version are both covered without an edit here.
+    #[test]
+    fn test_secrets_routes_never_log_a_body() {
+        for route in [
+            "/v1/secrets/create",
+            "/v1/secrets/alter",
+            "/v1/secrets/list",
+            "/v1/secrets/drop",
+            "/v1/secrets/describe",
+            "/v2/secrets/rotate",
+        ] {
+            assert!(
+                route_carries_credential(route),
+                "{route} must never log a body"
+            );
+        }
+        for route in [
+            "/v1/functions/create",
+            "/v1/table/foo/query",
+            "/v1/jobs/list",
+        ] {
+            assert!(!route_carries_credential(route), "{route} is not a secret");
+        }
+    }
+
    #[test]
    fn test_rejects_invalid_cloud_dns_hostname() {
        let invalid_database_names = ["a".repeat(64), "invalid..database".to_string()];
@@ -20,19 +20,20 @@ use lance_namespace::models::{

 use crate::Error;
 use crate::database::{
-    CloneTableRequest, CreateTableMode, CreateTableRequest, Database, DatabaseOptions,
-    JobDescription, JobInfo, OpenTableRequest, ReadConsistency, TableNamesRequest,
+    CloneTableRequest, CreateTableMode, CreateTableRequest, Database, DatabaseOptions, JobInfo,
+    OpenTableRequest, ReadConsistency, SecretInfo, TableNamesRequest,
 };
 use crate::error::Result;
 use crate::function::{FunctionRegistrationRequest, FunctionVersion};
 use crate::job::Job;
-use crate::remote::job::{DescribeJobResponse, RemoteJob, job_state_to_client};
+use crate::remote::job::{RemoteJob, job_state_to_client};
 use crate::remote::util::stream_as_body;
 use crate::table::BaseTable;

 use super::client::{
    ClientConfig, HeaderProvider, HttpSend, RequestResultExt, RestfulLanceDbClient, Sender,
 };
+use super::sql::SqlClient;
 use super::table::RemoteTable;
 use super::util::parse_server_version;
 use super::{ARROW_STREAM_CONTENT_TYPE, extract_job_id};
@@ -97,6 +98,7 @@ pub const OPT_REMOTE_PREFIX: &str = "remote_database_";
 pub const OPT_REMOTE_API_KEY: &str = "remote_database_api_key";
 pub const OPT_REMOTE_REGION: &str = "remote_database_region";
 pub const OPT_REMOTE_HOST_OVERRIDE: &str = "remote_database_host_override";
+pub const OPT_REMOTE_SQL_HOST_OVERRIDE: &str = "remote_database_sql_host_override";
 // TODO: add support for configuring client config via key/value options

 #[derive(Clone, Debug, Default)]
@@ -212,6 +214,7 @@ pub struct RemoteDatabase<S: HttpSend = Sender> {
    namespace_context_provider: Option<Arc<dyn DynamicContextProvider>>,
    /// TLS configuration for mTLS support
    tls_config: Option<super::client::TlsConfig>,
+    sql_client: Option<SqlClient>,
 }

 #[derive(Clone)]
@@ -269,22 +272,51 @@ impl DynamicContextProvider for NamespaceHeaderProviderContext {
    }
 }

+pub struct RemoteHostOverrides {
+    pub rest: Option<String>,
+    pub sql: Option<String>,
+}
+
+/// Attach a namespace path to a Secret request body.
+///
+/// A root path is omitted rather than sent empty, so a root request is byte
+/// identical to one from a client that predates namespace addressing.
+fn add_namespace_path(body: &mut serde_json::Value, namespace_path: &[String]) {
+    if namespace_path.is_empty() {
+        return;
+    }
+    body["namespace_path"] = serde_json::Value::Array(
+        namespace_path
+            .iter()
+            .map(|segment| serde_json::Value::String(segment.clone()))
+            .collect(),
+    );
+}
+
 impl RemoteDatabase {
-    pub fn try_new(
+    pub(crate) fn try_new(
        uri: &str,
        api_key: &str,
        region: &str,
-        host_override: Option<String>,
+        host_overrides: RemoteHostOverrides,
        client_config: ClientConfig,
        options: RemoteOptions,
        read_consistency_interval: Option<std::time::Duration>,
    ) -> Result<Self> {
        let parsed = super::client::parse_db_url(uri)?;
+        let sql_client = SqlClient::new(
+            parsed.db_name.clone(),
+            parsed.db_prefix.clone(),
+            api_key.to_string(),
+            host_overrides.rest.clone(),
+            host_overrides.sql,
+            client_config.clone(),
+        );
        let header_map = RestfulLanceDbClient::<Sender>::default_headers(
            api_key,
            region,
            &parsed.db_name,
-            host_override.is_some(),
+            host_overrides.rest.is_some(),
            &options,
            parsed.db_prefix.as_deref(),
            &client_config,
@@ -312,7 +344,7 @@ impl RemoteDatabase {
        let client = RestfulLanceDbClient::try_new(
            &parsed,
            region,
-            host_override,
+            host_overrides.rest,
            header_map,
            client_config.clone(),
            read_consistency_interval,
@@ -330,11 +362,34 @@ impl RemoteDatabase {
            namespace_headers,
            namespace_context_provider,
            tls_config: client_config.tls_config,
+            sql_client: Some(sql_client),
        })
    }
 }

 impl<S: HttpSend> RemoteDatabase<S> {
+    /// `create` and `alter` differ only in which name state the server
+    /// requires, so they share one request shape. The value is a request field
+    /// and never a path segment or query parameter, which keeps it out of
+    /// access logs and proxy traces.
+    async fn write_secret(
+        &self,
+        route: &str,
+        name: &str,
+        value: &str,
+        namespace_path: &[String],
+    ) -> Result<()> {
+        let mut body = serde_json::json!({
+            "name": name,
+            "value": value,
+        });
+        add_namespace_path(&mut body, namespace_path);
+        let req = self.client.post(route).json(&body);
+        let (request_id, response) = self.client.send(req).await?;
+        self.client.check_response(&request_id, response).await?;
+        Ok(())
+    }
+
    async fn submit_drop_table(
        &self,
        name: &str,
@@ -427,6 +482,7 @@ mod test_utils {
                namespace_headers: HashMap::new(),
                namespace_context_provider: None,
                tls_config: None,
+                sql_client: None,
            }
        }

@@ -449,6 +505,7 @@ mod test_utils {
                namespace_headers: config.extra_headers.clone(),
                namespace_context_provider,
                tls_config: config.tls_config.clone(),
+                sql_client: None,
            }
        }
    }
@@ -551,6 +608,21 @@ struct RemoteDropFunctionResponse {
    dropped: bool,
 }

+#[derive(serde::Deserialize)]
+struct RemoteListSecretsResponse {
+    #[serde(default)]
+    secrets: Vec<RemoteListedSecret>,
+    #[serde(default)]
+    page_token: Option<String>,
+}
+
+/// An object rather than a bare name so a later listing can carry a Secret's
+/// type or last-updated time without breaking this one.
+#[derive(serde::Deserialize)]
+struct RemoteListedSecret {
+    name: String,
+}
+
 /// Bound on `list_jobs` page walking; a warning is logged when the listing
 /// is truncated at this many pages.
 const MAX_LIST_JOBS_PAGES: usize = 100;
@@ -652,11 +724,84 @@ impl<S: HttpSend> Database for RemoteDatabase<S> {
        Ok(response.dropped)
    }

-    fn job(&self, job_id: &str) -> Result<crate::job::Job> {
-        Ok(crate::job::Job::new(Box::new(super::job::RemoteJob::new(
-            self.client.clone(),
-            job_id.to_string(),
-        ))))
+    async fn create_secret(
+        &self,
+        name: &str,
+        value: &str,
+        namespace_path: &[String],
+    ) -> Result<()> {
+        self.write_secret("/v1/secrets/create", name, value, namespace_path)
+            .await
+    }
+
+    async fn alter_secret(&self, name: &str, value: &str, namespace_path: &[String]) -> Result<()> {
+        self.write_secret("/v1/secrets/alter", name, value, namespace_path)
+            .await
+    }
+
+    async fn list_secrets(&self, namespace_path: &[String]) -> Result<Vec<String>> {
+        let mut names = Vec::new();
+        let mut page_token: Option<String> = None;
+        let mut seen_page_tokens = HashSet::new();
+        loop {
+            let mut body = serde_json::json!({});
+            if let Some(token) = &page_token {
+                body["page_token"] = serde_json::Value::String(token.clone());
+            }
+            add_namespace_path(&mut body, namespace_path);
+            let req = self.client.post("/v1/secrets/list").json(&body);
+            let (request_id, response) = self.client.send(req).await?;
+            let response = self.client.check_response(&request_id, response).await?;
+            let status = response.status();
+            let response: RemoteListSecretsResponse =
+                response.json().await.err_to_http(request_id.clone())?;
+            names.extend(response.secrets.into_iter().map(|secret| secret.name));
+            let Some(next_page_token) = response.page_token.filter(|token| !token.is_empty())
+            else {
+                break;
+            };
+            if !seen_page_tokens.insert(next_page_token.clone()) {
+                return Err(Error::Http {
+                    source: "Secret listing response repeated a page_token".into(),
+                    request_id,
+                    status_code: Some(status),
+                });
+            }
+            page_token = Some(next_page_token);
+        }
+        Ok(names)
+    }
+
+    async fn drop_secret(&self, name: &str, namespace_path: &[String]) -> Result<()> {
+        let mut body = serde_json::json!({ "name": name });
+        add_namespace_path(&mut body, namespace_path);
+        let req = self.client.post("/v1/secrets/drop").json(&body);
+        let (request_id, response) = self.client.send(req).await?;
+        self.client.check_response(&request_id, response).await?;
+        Ok(())
+    }
+
+    async fn describe_secret(&self, name: &str, namespace_path: &[String]) -> Result<SecretInfo> {
+        let mut body = serde_json::json!({ "name": name });
+        add_namespace_path(&mut body, namespace_path);
+        let req = self.client.post("/v1/secrets/describe").json(&body);
+        let (request_id, response) = self.client.send(req).await?;
+        let response = self.client.check_response(&request_id, response).await?;
+        response.json().await.err_to_http(request_id)
+    }
+
+    async fn open_job(&self, job_id: &str) -> Result<Job> {
+        let handle = super::job::RemoteJob::new(self.client.clone(), job_id.to_string());
+        match crate::job::JobHandle::describe(&handle).await {
+            Ok(description) => Ok(Job::opened(Box::new(handle), description)),
+            Err(Error::Http {
+                status_code: Some(StatusCode::NOT_FOUND),
+                ..
+            }) => Err(Error::JobNotFound {
+                job_id: job_id.to_string(),
+            }),
+            Err(err) => Err(err),
+        }
    }

    async fn list_jobs(&self) -> Result<Vec<JobInfo>> {
@@ -693,31 +838,6 @@ impl<S: HttpSend> Database for RemoteDatabase<S> {
        Ok(out)
    }

-    async fn get_job(&self, job_id: &str) -> Result<Option<JobDescription>> {
-        let req = self
-            .client
-            .post("/v1/jobs/describe")
-            .json(&serde_json::json!({ "job_id": job_id }));
-        let (request_id, rsp) = self.client.send(req).await?;
-        let rsp = match self.client.check_response(&request_id, rsp).await {
-            Ok(rsp) => rsp,
-            Err(Error::Http {
-                status_code: Some(StatusCode::NOT_FOUND),
-                ..
-            }) => return Ok(None),
-            Err(err) => return Err(err),
-        };
-        let body: DescribeJobResponse = rsp.json().await.err_to_http(request_id)?;
-        Ok(Some(JobDescription {
-            job_id: body.job_id,
-            job_type: body.job_type,
-            state: job_state_to_client(&body.job_state),
-            creation_ms: body.creation_ms,
-            spec: body.spec,
-            failure: body.failure.map(|reported| reported.into_job_failure()),
-        }))
-    }
-
    async fn cancel_job(&self, job_id: &str) -> Result<bool> {
        let req = self
            .client
@@ -734,19 +854,28 @@ impl<S: HttpSend> Database for RemoteDatabase<S> {
        }
    }

-    async fn job_history(&self, job_id: Option<&str>) -> Result<Vec<arrow_array::RecordBatch>> {
-        let mut body = serde_json::json!({});
-        if let Some(job_id) = job_id {
-            body["job_id"] = serde_json::Value::String(job_id.to_string());
-        }
-        let req = self.client.post("/v1/jobs/query_events").json(&body);
-        let (request_id, rsp) = self.client.send(req).await?;
-        let rsp = self.client.check_response(&request_id, rsp).await?;
-        let bytes = rsp.bytes().await.err_to_http(request_id)?;
-        let reader = arrow_ipc::reader::StreamReader::try_new(std::io::Cursor::new(bytes), None)?;
-        reader
-            .collect::<std::result::Result<Vec<_>, _>>()
-            .map_err(Into::into)
+    async fn execute_query_async(
+        &self,
+        query: &str,
+        default_namespace_path: &[String],
+    ) -> Result<crate::sql::Query> {
+        let client = self
+            .sql_client
+            .as_ref()
+            .ok_or_else(|| Error::NotSupported {
+                message: "SQL is unavailable for this remote database client".to_string(),
+            })?;
+        client.submit(query, default_namespace_path).await
+    }
+
+    async fn describe_query(&self, query_id: uuid::Uuid) -> Result<crate::sql::QueryDescription> {
+        let client = self
+            .sql_client
+            .as_ref()
+            .ok_or_else(|| Error::NotSupported {
+                message: "SQL is unavailable for this remote database client".to_string(),
+            })?;
+        client.describe(query_id).await
    }

    async fn table_names(&self, request: TableNamesRequest) -> Result<Vec<String>> {
@@ -1264,6 +1393,7 @@ mod tests {
    use crate::{
        Connection, Error,
        database::CreateTableMode,
+        job::JobEventsRequest,
        remote::{ARROW_STREAM_CONTENT_TYPE, ClientConfig, HeaderProvider, JSON_CONTENT_TYPE},
    };

@@ -2612,7 +2742,7 @@ mod tests {
    }

    #[tokio::test]
-    async fn test_get_job() {
+    async fn test_open_job() {
        let conn = Connection::new_with_handler(|request| {
            assert_eq!(request.method(), &reqwest::Method::POST);
            assert_eq!(request.url().path(), "/v1/jobs/describe");
@@ -2626,51 +2756,55 @@ mod tests {
                )
                .unwrap()
        });
-        let job = conn.get_job("job-1").await.unwrap().unwrap();
-        assert_eq!(job.job_id, "job-1");
-        assert_eq!(job.job_type, "create_index");
-        assert_eq!(job.state, "failed");
-        assert_eq!(job.creation_ms, 1000);
-        assert_eq!(job.spec["column"], "vec");
-        let failure = job.failure.unwrap();
+        // Opening populates the handle, so the accessors answer without a
+        // second round trip.
+        let job = conn.open_job("job-1").await.unwrap();
+        assert_eq!(job.id(), Some("job-1"));
+        assert_eq!(job.job_type().as_deref(), Some("create_index"));
+        assert_eq!(job.state().as_deref(), Some("failed"));
+        assert_eq!(job.creation_ms(), Some(1000));
+        assert_eq!(job.spec().unwrap()["column"], "vec");
+        assert!(job.result().is_none());
+        let failure = job.failure().unwrap();
        assert_eq!(failure.phase.as_deref(), Some("execute"));
        assert_eq!(failure.message.as_deref(), Some("worker died"));
        assert_eq!(failure.retryable, Some(true));
    }

    #[tokio::test]
-    async fn test_get_job_missing_is_none() {
+    async fn test_open_job_reports_the_terminal_result() {
        let conn = Connection::new_with_handler(|_| {
-            http::Response::builder()
-                .status(404)
-                .body("no such job")
-                .unwrap()
-        });
-        assert!(conn.get_job("nope").await.unwrap().is_none());
-    }
-
-    #[tokio::test]
-    async fn test_cancel_job() {
-        let conn = Connection::new_with_handler(|request| {
-            assert_eq!(request.url().path(), "/v1/jobs/cancel");
            http::Response::builder()
                .status(200)
-                .body(r#"{"job_id": "job-1"}"#)
+                .body(
+                    r#"{"job_id": "job-1", "job_type": "refresh_column", "job_state": "DONE", "creation_ms": 1000, "result": {"rows_assigned": 1000000, "rows_failed": 0}}"#,
+                )
                .unwrap()
        });
-        assert!(conn.cancel_job("job-1").await.unwrap());
+        let job = conn.open_job("job-1").await.unwrap();
+        assert_eq!(job.state().as_deref(), Some("finished"));
+        let result = job.result().unwrap();
+        assert_eq!(result["rows_assigned"], 1_000_000);
+        assert_eq!(result["rows_failed"], 0);
+    }

+    #[tokio::test]
+    async fn test_open_job_missing_fails() {
        let conn = Connection::new_with_handler(|_| {
            http::Response::builder()
                .status(404)
                .body("no such job")
                .unwrap()
        });
-        assert!(!conn.cancel_job("nope").await.unwrap());
+        let err = conn.open_job("nope").await.unwrap_err();
+        assert!(
+            matches!(&err, Error::JobNotFound { job_id } if job_id == "nope"),
+            "{err:?}"
+        );
    }

    #[tokio::test]
-    async fn test_job_history_parses_arrow_stream() {
+    async fn test_job_events_scope_to_that_job() {
        let schema = Arc::new(Schema::new(vec![Field::new(
            "state",
            DataType::Utf8,
@@ -2679,29 +2813,198 @@ mod tests {
        let batch = RecordBatch::try_new(
            schema.clone(),
            vec![Arc::new(arrow_array::StringArray::from(vec![
-                "created", "done",
+                "claim_complete",
            ]))],
        )
        .unwrap();
-        let mut body = Vec::new();
+        let mut events = Vec::new();
        {
-            let mut writer = arrow_ipc::writer::StreamWriter::try_new(&mut body, &schema).unwrap();
+            let mut writer =
+                arrow_ipc::writer::StreamWriter::try_new(&mut events, &schema).unwrap();
            writer.write(&batch).unwrap();
            writer.finish().unwrap();
        }
        let conn = Connection::new_with_handler(move |request| {
-            assert_eq!(request.url().path(), "/v1/jobs/query_events");
-            let req_body: serde_json::Value =
+            let body: serde_json::Value =
                serde_json::from_slice(request.body().unwrap().as_bytes().unwrap()).unwrap();
-            assert_eq!(req_body["job_id"], "job-1");
+            if request.url().path() == "/v1/jobs/describe" {
+                return http::Response::builder()
+                    .status(200)
+                    .body(
+                        r#"{"job_id": "job-1", "job_type": "refresh_column", "job_state": "IN_PROGRESS", "creation_ms": 1}"#
+                            .as_bytes()
+                            .to_vec(),
+                    )
+                    .unwrap();
+            }
+            assert_eq!(request.url().path(), "/v1/jobs/query_events");
+            // The handle supplies job_id; the caller only narrows the query.
+            assert_eq!(body["job_id"], "job-1");
+            assert_eq!(body["limit"], 500);
+            assert_eq!(body["filter"], "state = 'claim_complete'");
            http::Response::builder()
                .status(200)
-                .body(body.clone())
+                .body(events.clone())
                .unwrap()
        });
-        let batches = conn.job_history(Some("job-1")).await.unwrap();
+        let job = conn.open_job("job-1").await.unwrap();
+        let batches = job
+            .events(
+                JobEventsRequest::default()
+                    .limit(500)
+                    .filter("state = 'claim_complete'"),
+            )
+            .await
+            .unwrap();
        assert_eq!(batches.len(), 1);
-        assert_eq!(batches[0].num_rows(), 2);
+        assert_eq!(batches[0].num_rows(), 1);
+    }
+
+    #[tokio::test]
+    async fn test_job_events_keep_the_schema_when_nothing_matches() {
+        let schema = Arc::new(Schema::new(vec![Field::new(
+            "state",
+            DataType::Utf8,
+            false,
+        )]));
+        let mut events = Vec::new();
+        {
+            let mut writer =
+                arrow_ipc::writer::StreamWriter::try_new(&mut events, &schema).unwrap();
+            writer.finish().unwrap();
+        }
+        let conn = Connection::new_with_handler(move |request| {
+            if request.url().path() == "/v1/jobs/describe" {
+                return http::Response::builder()
+                    .status(200)
+                    .body(
+                        r#"{"job_id": "job-1", "job_type": "refresh_column", "job_state": "IN_PROGRESS", "creation_ms": 1}"#
+                            .as_bytes()
+                            .to_vec(),
+                    )
+                    .unwrap();
+            }
+            let body: serde_json::Value =
+                serde_json::from_slice(request.body().unwrap().as_bytes().unwrap()).unwrap();
+            // Only the job id when the caller narrows nothing.
+            assert_eq!(body, serde_json::json!({ "job_id": "job-1" }));
+            http::Response::builder()
+                .status(200)
+                .body(events.clone())
+                .unwrap()
+        });
+        let job = conn.open_job("job-1").await.unwrap();
+        let batches = job.events(JobEventsRequest::default()).await.unwrap();
+        assert_eq!(batches.len(), 1);
+        assert_eq!(batches[0].num_rows(), 0);
+        assert_eq!(batches[0].schema(), schema);
+    }
+
+    #[tokio::test]
+    async fn test_create_and_alter_secret_send_the_value_in_the_request_body() {
+        for (route, call) in [("/v1/secrets/create", true), ("/v1/secrets/alter", false)] {
+            let conn = Connection::new_with_handler(move |request| {
+                assert_eq!(request.method(), &reqwest::Method::POST);
+                assert_eq!(request.url().path(), route);
+                // Never a path segment or query parameter, which is what keeps
+                // it out of access logs and proxy traces.
+                assert!(request.url().query().is_none(), "{:?}", request.url());
+                let body: serde_json::Value =
+                    serde_json::from_slice(request.body().unwrap().as_bytes().unwrap()).unwrap();
+                assert_eq!(body["name"], "openai-prod");
+                assert_eq!(body["value"], "sk-live-0001");
+                http::Response::builder().status(200).body("{}").unwrap()
+            });
+            if call {
+                conn.create_secret("openai-prod", "sk-live-0001", &[])
+                    .await
+                    .unwrap();
+            } else {
+                conn.alter_secret("openai-prod", "sk-live-0001", &[])
+                    .await
+                    .unwrap();
+            }
+        }
+    }
+
+    #[tokio::test]
+    async fn test_list_secrets_walks_pages_and_returns_names_only() {
+        let conn = Connection::new_with_handler(|request| {
+            assert_eq!(request.url().path(), "/v1/secrets/list");
+            let body: serde_json::Value =
+                serde_json::from_slice(request.body().unwrap().as_bytes().unwrap()).unwrap();
+            let page = body.get("page_token").and_then(|token| token.as_str());
+            let body = match page {
+                None => r#"{"secrets":[{"name":"openai-prod"}],"page_token":"p2"}"#,
+                Some("p2") => r#"{"secrets":[{"name":"hf-prod"}]}"#,
+                Some(other) => panic!("unexpected page token: {other}"),
+            };
+            http::Response::builder().status(200).body(body).unwrap()
+        });
+        assert_eq!(
+            conn.list_secrets(&[]).await.unwrap(),
+            vec!["openai-prod".to_string(), "hf-prod".to_string()]
+        );
+    }
+
+    /// A server that keeps handing back the same token would otherwise spin
+    /// forever.
+    #[tokio::test]
+    async fn test_list_secrets_rejects_a_repeated_page_token() {
+        let conn = Connection::new_with_handler(|_| {
+            http::Response::builder()
+                .status(200)
+                .body(r#"{"secrets":[{"name":"openai-prod"}],"page_token":"same"}"#)
+                .unwrap()
+        });
+        let error = conn.list_secrets(&[]).await.unwrap_err();
+        assert!(
+            error.to_string().contains("repeated a page_token"),
+            "{error}"
+        );
+    }
+
+    #[tokio::test]
+    async fn test_drop_secret_posts_the_name_alone() {
+        let conn = Connection::new_with_handler(|request| {
+            assert_eq!(request.url().path(), "/v1/secrets/drop");
+            let body: serde_json::Value =
+                serde_json::from_slice(request.body().unwrap().as_bytes().unwrap()).unwrap();
+            assert_eq!(body, serde_json::json!({"name": "openai-prod"}));
+            http::Response::builder().status(200).body("{}").unwrap()
+        });
+        conn.drop_secret("openai-prod", &[]).await.unwrap();
+    }
+
+    /// A namespace path is sent when there is one and omitted when there is
+    /// not, so a root request stays byte identical to one from a client that
+    /// predates namespace addressing -- which is what lets the parameter ship
+    /// before every server implements it.
+    #[tokio::test]
+    async fn test_a_namespace_path_is_sent_only_when_it_is_not_root() {
+        let conn = Connection::new_with_handler(|request| {
+            let body: serde_json::Value =
+                serde_json::from_slice(request.body().unwrap().as_bytes().unwrap()).unwrap();
+            assert_eq!(
+                body,
+                serde_json::json!({
+                    "name": "openai-prod",
+                    "namespace_path": ["prod", "vision"],
+                })
+            );
+            http::Response::builder().status(200).body("{}").unwrap()
+        });
+        conn.drop_secret("openai-prod", &["prod".to_string(), "vision".to_string()])
+            .await
+            .unwrap();
+
+        let conn = Connection::new_with_handler(|request| {
+            let body: serde_json::Value =
+                serde_json::from_slice(request.body().unwrap().as_bytes().unwrap()).unwrap();
+            assert!(body.get("namespace_path").is_none(), "{body}");
+            http::Response::builder().status(200).body("{}").unwrap()
+        });
+        conn.drop_secret("openai-prod", &[]).await.unwrap();
    }

    #[tokio::test]
@@ -2896,7 +3199,9 @@ mod tests {
        let polls_ref = polls.clone();
        let conn = Connection::new_with_handler(move |request| {
            assert_eq!(request.url().path(), "/v1/jobs/describe");
-            let state = if polls_ref.fetch_add(1, Ordering::SeqCst) == 0 {
+            // Two in-progress answers: one for the load, one for the first
+            // status poll.
+            let state = if polls_ref.fetch_add(1, Ordering::SeqCst) < 2 {
                "IN_PROGRESS"
            } else {
                "DONE"
@@ -2909,11 +3214,13 @@ mod tests {
                ))
                .unwrap()
        });
-        let job = conn.job("job-1").unwrap();
+        let job = conn.open_job("job-1").await.unwrap();
        assert_eq!(job.id(), Some("job-1"));
+        // Opening already answered the state; no extra call needed for it.
+        assert_eq!(job.state().as_deref(), Some("running"));
        assert_eq!(job.status().await.unwrap(), "running");
        job.wait().await.unwrap();
        assert_eq!(job.status().await.unwrap(), "finished");
-        assert!(polls.load(Ordering::SeqCst) >= 3);
+        assert!(polls.load(Ordering::SeqCst) >= 4);
    }
 }
@@ -5,13 +5,15 @@

 use std::time::Duration;

+use arrow_array::RecordBatch;
 use async_trait::async_trait;
 use tokio::time::sleep;

 use serde::Deserialize;

+use crate::database::JobDescription;
 use crate::error::{Error, JobFailure, Result};
-use crate::job::{JobHandle, TerminalResult};
+use crate::job::{JobEventsRequest, JobHandle, TerminalResult};
 use crate::remote::client::{HttpSend, RequestResultExt, RestfulLanceDbClient};

 /// Delay before the second job-state poll; doubles up to [`MAX_POLL_INTERVAL`].
@@ -86,7 +88,7 @@ pub(super) struct DescribeJobResponse {
    #[serde(default)]
    pub(super) spec: serde_json::Value,
    #[serde(default)]
-    result: Option<serde_json::Value>,
+    pub(super) result: Option<serde_json::Value>,
    #[serde(default)]
    pub(super) failure: Option<ReportedFailure>,
 }
@@ -110,6 +112,39 @@ impl DescribeJobResponse {
    fn into_terminal_result(self, request_id: String) -> TerminalResult {
        TerminalResult::remote(self.result, request_id)
    }
+
+    /// The public description this wire envelope stands for.
+    pub(super) fn into_description(self) -> JobDescription {
+        JobDescription {
+            job_id: self.job_id,
+            job_type: self.job_type,
+            state: JobState::from(self.job_state.as_str()).client_label(),
+            creation_ms: self.creation_ms,
+            spec: self.spec,
+            result: self.result,
+            failure: self.failure.map(ReportedFailure::into_job_failure),
+        }
+    }
+}
+
+/// One `/v1/jobs/query_events` round trip.
+pub(super) async fn fetch_job_events<S: HttpSend>(
+    client: &RestfulLanceDbClient<S>,
+    body: serde_json::Value,
+) -> Result<Vec<RecordBatch>> {
+    let request = client.post("/v1/jobs/query_events").json(&body);
+    let (request_id, response) = client.send(request).await?;
+    let response = client.check_response(&request_id, response).await?;
+    let bytes = response.bytes().await.err_to_http(request_id)?;
+    let reader = arrow_ipc::reader::StreamReader::try_new(std::io::Cursor::new(bytes), None)?;
+    let schema = reader.schema();
+    let mut batches = reader.collect::<std::result::Result<Vec<_>, _>>()?;
+    // A query that matched nothing still describes the event columns.
+    // Keep that schema so callers can build a typed empty result.
+    if batches.is_empty() {
+        batches.push(RecordBatch::new_empty(schema));
+    }
+    Ok(batches)
 }

 pub struct RemoteJob<S: HttpSend> {
@@ -123,7 +158,7 @@ impl<S: HttpSend> RemoteJob<S> {
    }

    /// One `/v1/jobs/describe` round trip.
-    async fn describe(&self) -> Result<(String, DescribeJobResponse)> {
+    async fn fetch_description(&self) -> Result<(String, DescribeJobResponse)> {
        let request = self
            .client
            .post("/v1/jobs/describe")
@@ -148,13 +183,28 @@ impl<S: HttpSend> JobHandle for RemoteJob<S> {
    }

    async fn status(&self) -> Result<String> {
-        Ok(self.describe().await?.1.state().client_label())
+        Ok(self.fetch_description().await?.1.state().client_label())
+    }
+
+    async fn describe(&self) -> Result<JobDescription> {
+        Ok(self.fetch_description().await?.1.into_description())
+    }
+
+    async fn events(&self, request: JobEventsRequest) -> Result<Vec<RecordBatch>> {
+        let mut body = serde_json::json!({ "job_id": self.job_id });
+        if let Some(limit) = request.limit {
+            body["limit"] = serde_json::Value::from(limit);
+        }
+        if let Some(filter) = request.filter {
+            body["filter"] = serde_json::Value::String(filter);
+        }
+        fetch_job_events(&self.client, body).await
    }

    async fn wait(&self) -> Result<TerminalResult> {
        let mut interval = INITIAL_POLL_INTERVAL;
        loop {
-            let (request_id, description) = self.describe().await?;
+            let (request_id, description) = self.fetch_description().await?;
            match description.state() {
                JobState::Done => return Ok(description.into_terminal_result(request_id)),
                JobState::Failed => {
@@ -466,7 +466,9 @@ impl TokenSource for AzureImdsSource {
 /// OAuth header provider that manages the full token lifecycle.
 ///
 /// Implements [`HeaderProvider`] to inject `Authorization: Bearer <token>`
-/// headers into every LanceDB request, with automatic token refresh.
+/// headers into every LanceDB request, with automatic token refresh. It also
+/// identifies the bearer credential as OIDC so LanceDB's SQL service selects
+/// OIDC validation instead of API-key validation.
 pub struct OAuthHeaderProvider {
    token_source: Box<dyn TokenSource>,
    token_state: Arc<RwLock<TokenState>>,
@@ -554,10 +556,10 @@ impl OAuthHeaderProvider {
 impl HeaderProvider for OAuthHeaderProvider {
    async fn get_headers(&self) -> Result<HashMap<String, String>> {
        let token = self.get_valid_token().await?;
-        Ok(HashMap::from([(
-            "authorization".to_string(),
-            format!("Bearer {token}"),
-        )]))
+        Ok(HashMap::from([
+            ("authorization".to_string(), format!("Bearer {token}")),
+            ("x-lancedb-credential-type".to_string(), "oidc".to_string()),
+        ]))
    }
 }

@@ -264,6 +264,17 @@ impl<S: HttpSend> crate::job::JobHandle for FreshnessJob<S> {
        crate::job::JobHandle::status(&self.inner).await
    }

+    async fn describe(&self) -> Result<crate::database::JobDescription> {
+        crate::job::JobHandle::describe(&self.inner).await
+    }
+
+    async fn events(
+        &self,
+        request: crate::job::JobEventsRequest,
+    ) -> Result<Vec<arrow_array::RecordBatch>> {
+        crate::job::JobHandle::events(&self.inner, request).await
+    }
+
    async fn wait(&self) -> Result<crate::job::TerminalResult> {
        let result = crate::job::JobHandle::wait(&self.inner).await?;
        let version = self.version.read().await;
@@ -524,10 +535,13 @@ impl<S: HttpSend> RemoteTable<S> {
            _ => resolve_arrow_field_path(&schema, &column)?,
        };
        let mut body = serde_json::json!({
-            "column": canonical_column,
-            "replace": index.replace,
+            "column": canonical_column
        });

+        if !index.replace {
+            body["replace"] = false.into();
+        }
+
        // Add name parameter if provided (for backwards compatibility, only include if Some)
        if let Some(ref name) = index.name {
            body["name"] = serde_json::Value::String(name.clone());
@@ -6306,7 +6320,6 @@ mod tests {
                            let mut expected_body = expected_body.clone();
                            expected_body["column"] = "a".into();
                            expected_body[INDEX_TYPE_KEY] = index_type.into();
-                            expected_body["replace"] = false.into();

                            assert_eq!(body, expected_body);

@@ -6325,7 +6338,7 @@ mod tests {
    }

    #[tokio::test]
-    async fn test_create_index_forwards_default_replace_false_on_existing_route() {
+    async fn test_create_index_forwards_replace_false_on_existing_route() {
        let table = Table::new_with_handler("my_table", move |request| {
            assert_eq!(request.method(), "POST");
            match request.url().path() {
@@ -6352,40 +6365,7 @@ mod tests {

        table
            .create_index(&["a"], Index::BTree(Default::default()))
-            .execute()
-            .await
-            .unwrap();
-    }
-
-    #[tokio::test]
-    async fn test_create_index_forwards_explicit_replace_true_on_existing_route() {
-        let table = Table::new_with_handler("my_table", move |request| {
-            assert_eq!(request.method(), "POST");
-            match request.url().path() {
-                "/v1/table/my_table/describe/" => {
-                    let schema = Schema::new(vec![Field::new("a", DataType::Int32, false)]);
-                    http::Response::builder()
-                        .status(200)
-                        .body(describe_response(&schema))
-                        .unwrap()
-                }
-                "/v1/table/my_table/create_index/" => {
-                    let body = request.body().unwrap().as_bytes().unwrap();
-                    let body: serde_json::Value = serde_json::from_slice(body).unwrap();
-                    assert_eq!(body["replace"], json!(true));
-
-                    http::Response::builder()
-                        .status(200)
-                        .body("{}".to_string())
-                        .unwrap()
-                }
-                path => panic!("Unexpected path: {}", path),
-            }
-        });
-
-        table
-            .create_index(&["a"], Index::BTree(Default::default()))
-            .replace(true)
+            .replace(false)
            .execute()
            .await
            .unwrap();
@@ -6616,46 +6596,38 @@ mod tests {
            json!({
                "column": "rowId",
                "index_type": "BTREE",
-                "replace": false,
            }),
            json!({
                "column": "`row-id`",
                "index_type": "BTREE",
-                "replace": false,
            }),
            json!({
                "column": "userId",
                "index_type": "BTREE",
-                "replace": false,
            }),
            json!({
                "column": "MetaData.userId",
                "index_type": "BTREE",
-                "replace": false,
            }),
            json!({
                "column": "metadata.user_id",
                "index_type": "BTREE",
-                "replace": false,
            }),
            json!({
                "column": "image.embedding",
                "index_type": "IVF_PQ",
                "metric_type": "l2",
-                "replace": false,
            }),
            {
                let mut body = serde_json::to_value(InvertedIndexParams::default()).unwrap();
                body["column"] = "payload.text".into();
                body["index_type"] = "FTS".into();
-                body["replace"] = false.into();
                body
            },
            {
                let mut body = serde_json::to_value(InvertedIndexParams::default()).unwrap();
                body["column"] = "docs.content".into();
                body["index_type"] = "FTS".into();
-                body["replace"] = false.into();
                body
            },
            {
@@ -6663,18 +6635,15 @@ mod tests {
                body["column"] = "docs.content".into();
                body["index_type"] = "FTS".into();
                body["document_granularity"] = "list_element".into();
-                body["replace"] = false.into();
                body
            },
            json!({
                "column": "`meta-data`.`user-id`",
                "index_type": "BTREE",
-                "replace": false,
            }),
            json!({
                "column": "literal.`a.b`",
                "index_type": "BTREE",
-                "replace": false,
            }),
        ]);
        let request_idx = Arc::new(AtomicUsize::new(0));
@@ -8024,6 +7993,72 @@ mod tests {
        );
    }

+    /// The refresh handle is wrapped for read-freshness tracking, so it has to
+    /// forward the detail APIs too -- this is the job an operator is holding
+    /// when a backfill goes quiet.
+    #[tokio::test]
+    async fn test_refresh_job_handle_reports_detail_and_events() {
+        let schema = Arc::new(Schema::new(vec![Field::new(
+            "state",
+            DataType::Utf8,
+            false,
+        )]));
+        let batch = RecordBatch::try_new(
+            schema.clone(),
+            vec![Arc::new(arrow_array::StringArray::from(vec![
+                "claim_complete",
+            ]))],
+        )
+        .unwrap();
+        let mut events = Vec::new();
+        {
+            let mut writer =
+                arrow_ipc::writer::StreamWriter::try_new(&mut events, &schema).unwrap();
+            writer.write(&batch).unwrap();
+            writer.finish().unwrap();
+        }
+        let table = Table::new_with_handler("my_table", move |request| {
+            match request.url().path() {
+                "/v1/table/my_table/backfill_column" => http::Response::builder()
+                    .status(202)
+                    .body(br#"{"job_id": "j-42"}"#.to_vec())
+                    .unwrap(),
+                "/v1/jobs/describe" => http::Response::builder()
+                    .status(200)
+                    .body(
+                        r#"{"job_id": "j-42", "job_type": "refresh_column", "job_state": "IN_PROGRESS", "creation_ms": 7, "spec": {"column": "doubled"}}"#
+                            .as_bytes()
+                            .to_vec(),
+                    )
+                    .unwrap(),
+                "/v1/jobs/query_events" => {
+                    let body: serde_json::Value =
+                        serde_json::from_slice(request.body().unwrap().as_bytes().unwrap())
+                            .unwrap();
+                    assert_eq!(body["job_id"], "j-42");
+                    http::Response::builder()
+                        .status(200)
+                        .body(events.clone())
+                        .unwrap()
+                }
+                other => panic!("unexpected path {other}"),
+            }
+        });
+
+        let job = table.refresh_column_async("doubled").await.unwrap();
+        job.refresh().await.unwrap();
+        assert_eq!(job.state().as_deref(), Some("running"));
+        assert_eq!(job.job_type().as_deref(), Some("refresh_column"));
+        assert_eq!(job.creation_ms(), Some(7));
+        assert_eq!(job.spec().unwrap()["column"], "doubled");
+
+        let batches = job
+            .events(crate::job::JobEventsRequest::default())
+            .await
+            .unwrap();
+        assert_eq!(batches.iter().map(|b| b.num_rows()).sum::<usize>(), 1);
+    }
+
    #[tokio::test]
    async fn test_refresh_submission_uses_add_columns_version_fence() {
        let table = Table::new_with_handler("my_table", |request| match request.url().path() {
@@ -0,0 +1,124 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright The LanceDB Authors
+
+//! Handles to SQL queries running on a remote database.
+
+use std::{fmt, sync::Arc};
+
+use async_trait::async_trait;
+use chrono::{DateTime, Utc};
+use uuid::Uuid;
+
+use crate::{Result, arrow::SendableRecordBatchStream};
+
+/// The externally visible lifecycle state of a submitted SQL query.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum QueryStatus {
+    /// The server is still executing the query.
+    Running,
+    /// The server has made the complete result available.
+    Finished,
+    /// The server accepted cancellation but has not confirmed it yet.
+    Cancelling,
+    /// The server confirmed cancellation.
+    Cancelled,
+}
+
+impl fmt::Display for QueryStatus {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        formatter.write_str(match self {
+            Self::Running => "running",
+            Self::Finished => "finished",
+            Self::Cancelling => "cancelling",
+            Self::Cancelled => "cancelled",
+        })
+    }
+}
+
+/// A point-in-time description of a submitted SQL query.
+#[derive(Clone, Debug, PartialEq)]
+pub struct QueryDescription {
+    /// The stable, connection-scoped identifier assigned when the query was submitted.
+    pub id: Uuid,
+    /// The server-visible lifecycle state.
+    pub status: QueryStatus,
+    /// Server-reported completion progress, when known. Values are in `[0.0, 1.0]`,
+    /// with `1.0` meaning complete.
+    pub progress: Option<f64>,
+    /// When the server may stop accepting this query's continuation token.
+    pub expires_at: Option<DateTime<Utc>>,
+}
+
+#[async_trait]
+pub(crate) trait QueryHandle: Send + Sync {
+    fn id(&self) -> Uuid;
+    async fn describe(&self) -> Result<QueryDescription>;
+    async fn reader(&self) -> Result<SendableRecordBatchStream>;
+    async fn cancel(&self) -> Result<()>;
+}
+
+/// A handle to a submitted SQL query.
+///
+/// The handle can be inspected, opened as an Arrow reader, or cancelled.
+/// Dropping it does not cancel the server-side query.
+/// Identifier lookup is scoped to the connection that submitted the query and
+/// is not a durable resume mechanism.
+pub struct Query {
+    handle: Arc<dyn QueryHandle>,
+}
+
+impl std::fmt::Debug for Query {
+    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        formatter
+            .debug_struct("Query")
+            .field("id", &self.id())
+            .finish()
+    }
+}
+
+impl Query {
+    #[cfg(feature = "remote")]
+    pub(crate) fn new(handle: Arc<dyn QueryHandle>) -> Self {
+        Self { handle }
+    }
+
+    /// Return the stable, connection-scoped identifier for this query.
+    pub fn id(&self) -> Uuid {
+        self.handle.id()
+    }
+
+    /// Get a point-in-time description of the query.
+    pub async fn describe(&self) -> Result<QueryDescription> {
+        self.handle.describe().await
+    }
+
+    /// Wait for the initial result stream and return its Arrow record batches.
+    ///
+    /// The stream can begin yielding partial results before query execution is
+    /// complete. It continues polling for newly available result endpoints
+    /// until the query finishes and all endpoints have been consumed.
+    ///
+    /// Results are single-consumer. Calling this method more than once on the
+    /// same handle returns an error.
+    pub async fn reader(&self) -> Result<SendableRecordBatchStream> {
+        self.handle.reader().await
+    }
+
+    /// Request cancellation of the query.
+    pub async fn cancel(&self) -> Result<()> {
+        self.handle.cancel().await
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::QueryStatus;
+
+    #[test]
+    fn query_status_display_is_stable() {
+        assert_eq!(QueryStatus::Running.to_string(), "running");
+        assert_eq!(QueryStatus::Finished.to_string(), "finished");
+        assert_eq!(QueryStatus::Cancelling.to_string(), "cancelling");
+        assert_eq!(QueryStatus::Cancelled.to_string(), "cancelled");
+    }
+}
@@ -1192,6 +1192,9 @@ impl Table {
    /// valid empty blobs contain empty byte strings. Prefer
    /// [`Self::fetch_blob_files`] for large selections.
    ///
+    /// `_rowid` values stay valid after compaction when the table has stable
+    /// row ids.
+    ///
    /// ```
    /// use arrow_array::UInt64Array;
    /// use futures::TryStreamExt;
@@ -1233,6 +1236,9 @@ impl Table {
    /// the requests. Null blobs produce null output slots; empty ranges on
    /// non-null blobs produce empty byte strings.
    ///
+    /// `_rowid` values stay valid after compaction when the table has stable
+    /// row ids.
+    ///
    /// ```
    /// use lancedb::blob::BlobRangeRequest;
    ///
@@ -1271,6 +1277,9 @@ impl Table {
    /// Same length and order as `row_ids`. Null rows are `None`. Bytes are not
    /// read from disk until a call to [`BlobFile::read`].
    ///
+    /// `_rowid` values stay valid after compaction when the table has stable
+    /// row ids.
+    ///
    /// ```
    /// # use lancedb::Table;
    /// # async fn lazy_read(table: &Table, row_ids: &[u64]) -> Result<(), Box<dyn std::error::Error>> {
@@ -60,6 +60,10 @@ pub const FUNCTION_BINDING_ID_META_KEY: &str = "computed_column.function.binding
 /// Field metadata key holding this sibling's ordered Function output ordinal.
 pub const FUNCTION_OUTPUT_ORDINAL_META_KEY: &str = "computed_column.function.output_ordinal";

+/// Reserved Function output ordinal for an internal flattened-result
+/// assignment column.
+pub const FUNCTION_ASSIGNMENT_OUTPUT_ORDINAL: u32 = u32::MAX;
+
 /// Schema metadata key holding all immutable Function bindings.
 pub const FUNCTION_BINDINGS_META_KEY: &str = "lancedb::function_bindings";

@@ -312,22 +316,29 @@ pub(crate) fn ensure_supported_function_metadata(schema: &ArrowSchema) -> Result
                                binding_id
                            ),
                        })?;
-                let output = binding
-                    .outputs()
-                    .get(output_ordinal as usize)
-                    .ok_or_else(|| Error::InvalidInput {
-                        message: format!(
-                            "Function output '{}' has invalid ordinal {}",
-                            field.name(),
-                            output_ordinal
-                        ),
-                    })?;
-                if output.output_name != field.name().as_str() {
+                let destination = if output_ordinal == FUNCTION_ASSIGNMENT_OUTPUT_ORDINAL {
+                    binding
+                        .assignment()
+                        .map(|assignment| assignment.output_name.as_str())
+                } else {
+                    binding
+                        .outputs()
+                        .get(output_ordinal as usize)
+                        .map(|output| output.output_name.as_str())
+                }
+                .ok_or_else(|| Error::InvalidInput {
+                    message: format!(
+                        "Function output '{}' has invalid ordinal {}",
+                        field.name(),
+                        output_ordinal
+                    ),
+                })?;
+                if destination != field.name().as_str() {
                    return Err(Error::InvalidInput {
                        message: format!(
                            "Function output '{}' does not match binding destination '{}'",
                            field.name(),
-                            output.output_name
+                            destination
                        ),
                    });
                }
@@ -498,6 +509,7 @@ fn ensure_known_binding_shape(value: &Value) -> Result<()> {
            "function",
            "inputs",
            "outputs",
+            "assignment",
            "input_schema",
            "output_schema",
        ],
@@ -546,6 +558,13 @@ fn ensure_known_binding_shape(value: &Value) -> Result<()> {
            "output mapping",
        )?;
    }
+    if let Some(assignment) = object.get("assignment") {
+        reject_unknown_object_fields(
+            assignment,
+            &["output_name", "output_field_id"],
+            "assignment mapping",
+        )?;
+    }
    Ok(())
 }

@@ -740,14 +759,33 @@ fn function_output_field(name: &str, nullable: bool, raw: &str) -> Result<JsonAr
    Ok(field)
 }

-fn function_output_field_matches(expected: &ArrowField, actual: &ArrowField) -> bool {
-    expected.name() == actual.name()
-        && expected.is_nullable() == actual.is_nullable()
-        && if expected.is_blob_v2() {
+/// Whether two fields describe the same Function output.
+///
+/// `compare_identity` covers the field's own name and nullability. Struct
+/// children carry both as part of the declaration and compare with it on. List
+/// children do not: Lance rewrites a list item's name and nullability when it
+/// writes, so a stored `fixed_size_list<item: float not null>` comes back as
+/// `fixed_size_list<item: float>` and never matches the declaration again.
+/// Comparing those by type alone keeps this agreeing with the server, which
+/// draws the same distinction and is what accepted the column when it was
+/// declared.
+fn function_output_field_matches(
+    expected: &ArrowField,
+    actual: &ArrowField,
+    compare_identity: bool,
+) -> bool {
+    if compare_identity
+        && (expected.name() != actual.name() || expected.is_nullable() != actual.is_nullable())
+    {
+        return false;
+    }
+    match (expected.is_blob_v2(), actual.is_blob_v2()) {
+        (false, false) => function_output_type_matches(expected.data_type(), actual.data_type()),
+        (true, true) => {
            has_supported_blob_v2_layout(expected) && has_supported_blob_v2_layout(actual)
-        } else {
-            function_output_type_matches(expected.data_type(), actual.data_type())
        }
+        _ => false,
+    }
 }

 fn function_output_type_matches(expected: &DataType, actual: &DataType) -> bool {
@@ -760,33 +798,19 @@ fn function_output_type_matches(expected: &DataType, actual: &DataType) -> bool
                && expected
                    .iter()
                    .zip(actual)
-                    .all(|(expected, actual)| function_output_field_matches(expected, actual))
+                    .all(|(expected, actual)| function_output_field_matches(expected, actual, true))
        }
        (DataType::List(expected), DataType::List(actual))
        | (DataType::LargeList(expected), DataType::LargeList(actual)) => {
-            function_output_field_matches(expected, actual)
+            function_output_field_matches(expected, actual, false)
        }
        (
            DataType::FixedSizeList(expected, expected_size),
            DataType::FixedSizeList(actual, actual_size),
-        ) => expected_size == actual_size && function_output_field_matches(expected, actual),
+        ) => expected_size == actual_size && function_output_field_matches(expected, actual, false),
        (DataType::Map(expected, expected_sorted), DataType::Map(actual, actual_sorted)) => {
-            expected_sorted == actual_sorted && function_output_field_matches(expected, actual)
-        }
-        _ => false,
-    }
-}
-
-fn function_output_type_has_blob(data_type: &DataType) -> bool {
-    match data_type {
-        DataType::Struct(fields) => fields
-            .iter()
-            .any(|field| field.is_blob_v2() || function_output_type_has_blob(field.data_type())),
-        DataType::List(field)
-        | DataType::LargeList(field)
-        | DataType::FixedSizeList(field, _)
-        | DataType::Map(field, _) => {
-            field.is_blob_v2() || function_output_type_has_blob(field.data_type())
+            expected_sorted == actual_sorted
+                && function_output_field_matches(expected, actual, true)
        }
        _ => false,
    }
@@ -865,23 +889,20 @@ fn ensure_binding_matches_schema(schema: &ArrowSchema, binding: &FunctionBinding
                output.output_name
            ))
        })?;
-        if field.name() != &output.output_name || !field.is_nullable() || output.nullable {
+        if field.name() != &output.output_name || !field.is_nullable() {
            return Err(invalid_function(format!(
                "Function output '{}' no longer matches binding '{}'",
                output.output_name,
                binding.binding_id()
            )));
        }
-        let (type_matches, has_semantic_blob) = if output.arrow_type == FUNCTION_BLOB_V2_TYPE {
-            (has_supported_blob_v2_layout(field), true)
+        let type_matches = if output.arrow_type == FUNCTION_BLOB_V2_TYPE {
+            has_supported_blob_v2_layout(field)
        } else {
            let expected_type = parse_output_arrow_type(&output.arrow_type)?;
            let expected_type = lance_namespace::schema::convert_json_arrow_type(&expected_type)
                .map_err(|e| invalid_function(format!("invalid Function output type: {e}")))?;
-            (
-                function_output_type_matches(&expected_type, field.data_type()),
-                function_output_type_has_blob(&expected_type),
-            )
+            function_output_type_matches(&expected_type, field.data_type())
        };
        if !type_matches {
            return Err(invalid_function(format!(
@@ -912,19 +933,71 @@ fn ensure_binding_matches_schema(schema: &ArrowSchema, binding: &FunctionBinding
                binding.binding_id()
            )));
        }
-        if has_semantic_blob {
-            output_fields.push(function_output_field(
-                field.name(),
-                true,
-                &output.arrow_type,
-            )?);
-        } else {
-            let json = lance_namespace::schema::arrow_schema_to_json(&ArrowSchema::new(vec![
-                ArrowField::new(field.name().clone(), field.data_type().clone(), true),
-            ]))
-            .map_err(|e| invalid_function(format!("invalid Function output schema: {e}")))?;
-            output_fields.push(json.fields.into_iter().next().unwrap());
+        // Rebuild from the declaration rather than from the stored field. The
+        // stored field carries Lance's write-time normalization, which would
+        // never round-trip back to the schema the binding recorded -- the same
+        // reason list children compare by type above. Whether the column on
+        // disk still matches is settled by that comparison, not here.
+        output_fields.push(function_output_field(
+            field.name(),
+            true,
+            &output.arrow_type,
+        )?);
+    }
+    if let Some(assignment) = binding.assignment() {
+        if binding
+            .outputs()
+            .iter()
+            .any(|output| output.result_field == WHOLE_RESULT_FIELD)
+        {
+            return Err(invalid_function(format!(
+                "Function binding '{}' cannot attach an assignment column to a whole result",
+                binding.binding_id()
+            )));
        }
+        let field = schema
+            .field_with_name(&assignment.output_name)
+            .map_err(|_| {
+                invalid_function(format!(
+                    "Function binding '{}' assignment column '{}' is missing",
+                    binding.binding_id(),
+                    assignment.output_name
+                ))
+            })?;
+        let metadata = field.metadata();
+        if field.data_type() != &DataType::Boolean
+            || !field.is_nullable()
+            || metadata.get(COMPUTED_COLUMN_META_KEY).map(String::as_str) != Some("true")
+            || metadata.get(KIND_META_KEY).map(String::as_str) != Some(FUNCTION_KIND)
+            || metadata
+                .get(FUNCTION_BINDING_ID_META_KEY)
+                .map(String::as_str)
+                != Some(binding.binding_id())
+            || metadata
+                .get(FUNCTION_OUTPUT_ORDINAL_META_KEY)
+                .and_then(|value| value.parse::<u32>().ok())
+                != Some(FUNCTION_ASSIGNMENT_OUTPUT_ORDINAL)
+        {
+            return Err(invalid_function(format!(
+                "Function binding '{}' assignment column no longer matches its declaration",
+                binding.binding_id()
+            )));
+        }
+        let json = lance_namespace::schema::arrow_schema_to_json(&ArrowSchema::new(vec![
+            ArrowField::new(assignment.output_name.clone(), DataType::Boolean, true),
+        ]))
+        .map_err(|e| invalid_function(format!("invalid Function assignment schema: {e}")))?;
+        output_fields.push(json.fields.into_iter().next().unwrap());
+    } else if binding.outputs().iter().all(|output| output.nullable)
+        && binding
+            .outputs()
+            .iter()
+            .all(|output| output.result_field != WHOLE_RESULT_FIELD)
+    {
+        return Err(invalid_function(format!(
+            "Function binding '{}' has no flattened-result assignment column",
+            binding.binding_id()
+        )));
    }
    let output_schema = JsonArrowSchema::new(output_fields);
    let output_schema = serde_json::to_value(output_schema).map_err(|e| {
@@ -1081,11 +1154,6 @@ pub(crate) fn plan_function_application(
                    "named-struct Function result field names must be unique",
                ));
            }
-            if output.fields.iter().any(|field| field.nullable) {
-                return Err(invalid_function(
-                    "Function logical outputs must be non-nullable during NULL assignment",
-                ));
-            }
            let unknown = application
                .columns()
                .keys()
@@ -1107,7 +1175,9 @@ pub(crate) fn plan_function_application(
                let fields = output
                    .fields
                    .iter()
-                    .map(|field| function_output_field(&field.name, false, &field.arrow_type))
+                    .map(|field| {
+                        function_output_field(&field.name, field.nullable, &field.arrow_type)
+                    })
                    .collect::<Result<Vec<_>>>()?;
                let mut data_type = JsonArrowDataType::new("struct".to_string());
                data_type.fields = Some(fields);
@@ -1744,6 +1814,69 @@ mod tests {
        assert!(super::validate_declarations(schema, &declarations).is_err());
    }

+    #[test]
+    fn list_children_match_by_type_but_struct_children_by_identity() {
+        use arrow_schema::Field as F;
+
+        // Lance rewrites a list item's name and nullability on write, so the
+        // stored field is no longer identical to what was declared. Comparing
+        // those by type keeps a table with a vector output usable.
+        let declared =
+            DataType::FixedSizeList(Arc::new(F::new("item", DataType::Float32, false)), 4);
+        let stored = DataType::FixedSizeList(Arc::new(F::new("item", DataType::Float32, true)), 4);
+        assert!(super::function_output_type_matches(&declared, &stored));
+
+        let renamed =
+            DataType::FixedSizeList(Arc::new(F::new("element", DataType::Float32, true)), 4);
+        assert!(super::function_output_type_matches(&declared, &renamed));
+
+        // The dimension is still part of the declaration.
+        let resized = DataType::FixedSizeList(Arc::new(F::new("item", DataType::Float32, true)), 8);
+        assert!(!super::function_output_type_matches(&declared, &resized));
+
+        // Struct children keep comparing by name and nullability.
+        let struct_declared =
+            DataType::Struct(vec![F::new("changed", DataType::Boolean, false)].into());
+        let struct_nullable =
+            DataType::Struct(vec![F::new("changed", DataType::Boolean, true)].into());
+        let struct_renamed =
+            DataType::Struct(vec![F::new("altered", DataType::Boolean, false)].into());
+        assert!(super::function_output_type_matches(
+            &struct_declared,
+            &struct_declared
+        ));
+        assert!(!super::function_output_type_matches(
+            &struct_declared,
+            &struct_nullable
+        ));
+        assert!(!super::function_output_type_matches(
+            &struct_declared,
+            &struct_renamed
+        ));
+
+        // A list nested inside a struct gets the list rule.
+        let nested_declared = DataType::Struct(
+            vec![F::new(
+                "tokens",
+                DataType::List(Arc::new(F::new("item", DataType::Utf8, false))),
+                true,
+            )]
+            .into(),
+        );
+        let nested_stored = DataType::Struct(
+            vec![F::new(
+                "tokens",
+                DataType::List(Arc::new(F::new("item", DataType::Utf8, true))),
+                true,
+            )]
+            .into(),
+        );
+        assert!(super::function_output_type_matches(
+            &nested_declared,
+            &nested_stored
+        ));
+    }
+
    #[test]
    fn output_arrow_type_grammar_matches_the_shared_golden() {
        let golden: serde_json::Value = serde_json::from_str(include_str!(
@@ -2858,6 +2991,17 @@ mod tests {
                    &inputs,
                ));
        }
+        if let Some(assignment) = binding.assignment() {
+            fields.push(
+                ArrowField::new(&assignment.output_name, DataType::Boolean, true).with_metadata(
+                    function_computed_column_metadata(
+                        binding.binding_id(),
+                        FUNCTION_ASSIGNMENT_OUTPUT_ORDINAL,
+                        &inputs,
+                    ),
+                ),
+            );
+        }
        ArrowSchema::new(fields)
    }

@@ -2875,6 +3019,74 @@ mod tests {
        .unwrap();
    }

+    #[test]
+    fn test_binding_preserves_all_nullable_outputs_with_an_assignment_column() {
+        let mut raw_binding: Value = serde_json::from_str(include_str!(
+            "../../tests/fixtures/first_class_functions/v1/remote_function_binding.json"
+        ))
+        .unwrap();
+        raw_binding["outputs"][0]["nullable"] = Value::Bool(true);
+        raw_binding["outputs"][1]["nullable"] = Value::Bool(true);
+        let without_assignment: FunctionBinding =
+            serde_json::from_value(raw_binding.clone()).unwrap();
+        let error = ensure_binding_matches_schema(
+            &valid_function_binding_schema(true, true, &without_assignment),
+            &without_assignment,
+        )
+        .unwrap_err();
+        assert!(
+            error
+                .to_string()
+                .contains("flattened-result assignment column")
+        );
+
+        raw_binding["assignment"] = serde_json::json!({
+            "output_name": "__function_assignment_fb_01K3TEXT",
+            "output_field_id": -1,
+        });
+        raw_binding["output_schema"]["fields"]
+            .as_array_mut()
+            .unwrap()
+            .push(serde_json::json!({
+                "name": "__function_assignment_fb_01K3TEXT",
+                "nullable": true,
+                "type": {"type": "bool"},
+            }));
+        let binding: FunctionBinding = serde_json::from_value(raw_binding).unwrap();
+        ensure_binding_matches_schema(
+            &valid_function_binding_schema(true, true, &binding),
+            &binding,
+        )
+        .unwrap();
+
+        let schema = ArrowSchema::new_with_metadata(
+            valid_function_binding_schema(true, true, &binding)
+                .fields()
+                .to_vec(),
+            HashMap::from([(
+                FUNCTION_BINDINGS_META_KEY.to_string(),
+                function_bindings_metadata(std::slice::from_ref(&binding)).unwrap(),
+            )]),
+        );
+        ensure_supported_function_metadata(&schema).unwrap();
+
+        let mut metadata: Value =
+            serde_json::from_str(schema.metadata().get(FUNCTION_BINDINGS_META_KEY).unwrap())
+                .unwrap();
+        metadata["bindings"][0]["assignment"]["future"] = Value::Bool(true);
+        let future_schema = ArrowSchema::new_with_metadata(
+            schema.fields().to_vec(),
+            HashMap::from([(
+                FUNCTION_BINDINGS_META_KEY.to_string(),
+                serde_json::to_string(&metadata).unwrap(),
+            )]),
+        );
+        assert!(matches!(
+            ensure_supported_function_metadata(&future_schema),
+            Err(Error::NotSupported { .. })
+        ));
+    }
+
    #[test]
    fn test_nullable_function_input_cannot_bind_to_non_nullable_parameter() {
        let mut raw_binding: Value = serde_json::from_str(include_str!(
@@ -3094,6 +3306,35 @@ mod tests {
        );
    }

+    #[test]
+    fn test_named_struct_plan_preserves_nullable_result_fields() {
+        let mut value = serde_json::to_value(named_struct_application("{}")).unwrap();
+        value["output"]["fields"][0]["nullable"] = Value::Bool(true);
+        value["output"]["fields"][1]["nullable"] = Value::Bool(true);
+        let application = FunctionApplication::from_json(&value.to_string()).unwrap();
+
+        let expanded =
+            plan_function_application(&function_input_schema(), &application, None).unwrap();
+        assert!(
+            expanded
+                .output_schema
+                .fields
+                .iter()
+                .all(|field| field.nullable)
+        );
+
+        let whole =
+            plan_function_application(&function_input_schema(), &application, Some("features"))
+                .unwrap();
+        let fields = whole.output_schema.fields[0]
+            .r#type
+            .fields
+            .as_ref()
+            .unwrap();
+        assert!(fields[0].nullable);
+        assert!(fields[1].nullable);
+    }
+
    #[test]
    fn test_blob_function_plans_semantic_input_and_scalar_output() {
        let schema = ArrowSchema::new(vec![crate::blob("image", false)]);
@@ -3110,6 +3351,70 @@ mod tests {
        assert!(output_schema.field(0).is_blob_v2());
    }

+    #[test]
+    fn binding_accepts_a_lance_normalized_list_child() {
+        // The whole guard, not just the type helper: this also reaches the
+        // output-schema comparison at the end of ensure_binding_matches_schema,
+        // which used to rebuild the schema from the stored field and so failed
+        // on exactly the same normalization.
+        let input = ArrowField::new("value", DataType::Int64, false);
+        let application = FunctionApplication::from_json(
+            &serde_json::json!({
+                "function": {"name": "embed", "version": "fv_embed"},
+                "inputs": [{
+                    "parameter": "value",
+                    "kind": "column",
+                    "value": {"path": "value"}
+                }],
+                "output": {
+                    "kind": "scalar",
+                    "arrow_type": "fixed_size_list<float32, 4>",
+                    "nullable": false
+                }
+            })
+            .to_string(),
+        )
+        .unwrap();
+        let plan = plan_function_application(
+            &ArrowSchema::new(vec![input.clone()]),
+            &application,
+            Some("embedding"),
+        )
+        .unwrap();
+        let binding = binding_from_plan(&plan);
+
+        // The declaration says the item is non-nullable; Lance rewrites it to
+        // nullable on write, so this is what the column looks like on disk.
+        let stored = DataType::FixedSizeList(
+            Arc::new(ArrowField::new("item", DataType::Float32, true)),
+            4,
+        );
+        let output = ArrowField::new("embedding", stored, true).with_metadata(
+            function_computed_column_metadata(binding.binding_id(), 0, &["value".into()]),
+        );
+
+        ensure_binding_matches_schema(&ArrowSchema::new(vec![input.clone(), output]), &binding)
+            .unwrap();
+
+        // A different element type is still a mismatch.
+        let wrong = ArrowField::new(
+            "embedding",
+            DataType::FixedSizeList(
+                Arc::new(ArrowField::new("item", DataType::Float64, true)),
+                4,
+            ),
+            true,
+        )
+        .with_metadata(function_computed_column_metadata(
+            binding.binding_id(),
+            0,
+            &["value".into()],
+        ));
+        assert!(
+            ensure_binding_matches_schema(&ArrowSchema::new(vec![input, wrong]), &binding).is_err()
+        );
+    }
+
    #[test]
    fn test_blob_scalar_binding_accepts_full_logical_layout() {
        let input = crate::blob("image", false);
@@ -725,11 +725,12 @@ mod tests {
            .await
            .unwrap();

-        // Rebuilding the same index without explicit replace fails once the build
+        // Rebuilding the same index without replace fails once the build
        // starts, so the failure reaches the job rather than execute_async.
        let job = Arc::new(
            table
                .create_index(&["id"], Index::BTree(BTreeIndexBuilder::default()))
+                .replace(false)
                .execute_async()
                .await
                .unwrap(),
@@ -768,6 +769,7 @@ mod tests {

        let job = table
            .create_index(&["id"], Index::BTree(BTreeIndexBuilder::default()))
+            .replace(false)
            .execute_async()
            .await
            .unwrap();
@@ -1104,7 +1106,6 @@ mod tests {
        // Can also specify btree
        table
            .create_index(&["i"], Index::BTree(BTreeIndexBuilder::default()))
-            .replace(true)
            .execute()
            .await
            .unwrap();
@@ -5,12 +5,17 @@
 //!
 //! [`super::cast::cast_to_table_schema`] calls [`coerce_blob_expr`].

+use std::fmt;
+use std::hash::{Hash, Hasher};
 use std::sync::Arc;

-use arrow_schema::{DataType, Field, FieldRef, Fields};
+use arrow_array::{Array, BooleanArray, RecordBatch};
+use arrow_schema::{DataType, Field, FieldRef, Fields, Schema};
+use arrow_select::nullif::nullif;
 use datafusion::functions::core::{get_field, named_struct};
 use datafusion_common::ScalarValue;
 use datafusion_common::config::ConfigOptions;
+use datafusion_expr::ColumnarValue;
 use datafusion_physical_expr::ScalarFunctionExpr;
 use datafusion_physical_expr::expressions::{CastExpr, Literal};
 use datafusion_physical_plan::PhysicalExpr;
@@ -133,16 +138,102 @@ pub(super) fn coerce_blob_expr(
        ns_args.push(value);
    }

-    let expr: Arc<dyn PhysicalExpr> = Arc::new(ScalarFunctionExpr::new(
+    let built: Arc<dyn PhysicalExpr> = Arc::new(ScalarFunctionExpr::new(
        &format!("named_struct({})", table_field.name()),
        named_struct(),
        ns_args,
        table_field.clone(),
        config.clone(),
    ));
+
+    // `named_struct` always yields a valid struct, so a null input would land
+    // as a row that set neither `data` nor `uri` -- not an absent blob but a
+    // malformed one, which Lance rejects on write.
+    let expr: Arc<dyn PhysicalExpr> = Arc::new(AbsentBlobIsNull {
+        source: input_expr,
+        built,
+        field: table_field.clone(),
+    });
    Ok((expr, table_field.clone()))
 }

+/// Carries the source column's nullity onto the struct built for it.
+///
+/// This is its own expression rather than a `CASE` because the projection
+/// takes its output field from `return_field`, and the generic implementation
+/// rebuilds a bare field -- which would drop the `lance.blob.v2` extension
+/// metadata and stop the column being recognised as a blob at all.
+#[derive(Debug, Clone)]
+struct AbsentBlobIsNull {
+    source: Arc<dyn PhysicalExpr>,
+    built: Arc<dyn PhysicalExpr>,
+    field: FieldRef,
+}
+
+impl fmt::Display for AbsentBlobIsNull {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        write!(f, "absent_blob_is_null({}, {})", self.source, self.built)
+    }
+}
+
+impl PartialEq for AbsentBlobIsNull {
+    fn eq(&self, other: &Self) -> bool {
+        self.source.eq(&other.source) && self.built.eq(&other.built) && self.field == other.field
+    }
+}
+
+impl Eq for AbsentBlobIsNull {}
+
+impl Hash for AbsentBlobIsNull {
+    fn hash<H: Hasher>(&self, state: &mut H) {
+        self.source.hash(state);
+        self.built.hash(state);
+        self.field.hash(state);
+    }
+}
+
+impl PhysicalExpr for AbsentBlobIsNull {
+    fn return_field(&self, _input_schema: &Schema) -> datafusion_common::Result<FieldRef> {
+        Ok(self.field.clone())
+    }
+
+    fn nullable(&self, _input_schema: &Schema) -> datafusion_common::Result<bool> {
+        Ok(true)
+    }
+
+    fn evaluate(&self, batch: &RecordBatch) -> datafusion_common::Result<ColumnarValue> {
+        let rows = batch.num_rows();
+        let built = self.built.evaluate(batch)?.into_array(rows)?;
+        let source = self.source.evaluate(batch)?.into_array(rows)?;
+        let Some(nulls) = source.logical_nulls() else {
+            return Ok(ColumnarValue::Array(built));
+        };
+        // `nullif` nulls the rows the mask marks true, which is where the
+        // source had no value.
+        let absent = BooleanArray::new(!nulls.inner(), None);
+        Ok(ColumnarValue::Array(nullif(built.as_ref(), &absent)?))
+    }
+
+    fn children(&self) -> Vec<&Arc<dyn PhysicalExpr>> {
+        vec![&self.source, &self.built]
+    }
+
+    fn with_new_children(
+        self: Arc<Self>,
+        children: Vec<Arc<dyn PhysicalExpr>>,
+    ) -> datafusion_common::Result<Arc<dyn PhysicalExpr>> {
+        Ok(Arc::new(Self {
+            source: children[0].clone(),
+            built: children[1].clone(),
+            field: self.field.clone(),
+        }))
+    }
+
+    fn fmt_sql(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        write!(f, "{self}")
+    }
+}
+
 enum BlobInputShape<'a> {
    Bytes,
    String,
@@ -313,6 +404,11 @@ mod tests {
        let data = image.column_by_name("data").unwrap();
        assert!(!data.is_null(0));
        assert!(data.is_null(1));
+        // The row itself has to be null, not merely a struct whose children
+        // are. A present-but-empty struct set neither `data` nor `uri`, which
+        // Lance rejects as malformed rather than reading as an absent blob.
+        assert!(!image.is_null(0));
+        assert!(image.is_null(1));
    }

    #[tokio::test]
@@ -111,7 +111,7 @@ async fn query_image_struct(table: &Table) -> StructArray {
 }

 #[tokio::test]
-async fn declaring_blob_column_bumps_format_and_enables_stable_row_ids() -> Result<()> {
+async fn declaring_blob_column_uses_v2_2_and_default_row_ids() -> Result<()> {
    let tmp = tempdir().unwrap();
    let db = connect(tmp.path().to_str().unwrap()).execute().await?;
    let table = db
@@ -120,12 +120,12 @@ async fn declaring_blob_column_bumps_format_and_enables_stable_row_ids() -> Resu
        .await?;

    assert!(supports_blob_v2(storage_format_version(&table).await));
-    assert!(uses_stable_row_ids(&table).await);
+    assert!(!uses_stable_row_ids(&table).await);
    Ok(())
 }

 #[tokio::test]
-async fn explicit_stable_row_id_setting_wins_over_blob_default() -> Result<()> {
+async fn blob_create_honors_disabled_stable_row_ids() -> Result<()> {
    let tmp = tempdir().unwrap();
    let db = connect(tmp.path().to_str().unwrap()).execute().await?;
    let table = db
@@ -179,7 +179,7 @@ async fn creating_with_blob_data_bumps_format() -> Result<()> {
    let table = db.create_table("t", batch).execute().await?;

    assert!(supports_blob_v2(storage_format_version(&table).await));
-    assert!(uses_stable_row_ids(&table).await);
+    assert!(!uses_stable_row_ids(&table).await);
    assert_eq!(table.count_rows(None).await?, 1);
    Ok(())
 }
@@ -277,7 +277,7 @@ async fn add_rejects_uncoercible_blob_input() -> Result<()> {
 }

 #[tokio::test]
-async fn connection_level_stable_row_id_setting_wins_over_blob_default() -> Result<()> {
+async fn connection_disables_stable_row_ids_on_blob_create() -> Result<()> {
    let tmp = tempdir().unwrap();
    let db = connect(tmp.path().to_str().unwrap())
        .storage_option(OPT_NEW_TABLE_ENABLE_STABLE_ROW_IDS, "false")
@@ -294,7 +294,7 @@ async fn connection_level_stable_row_id_setting_wins_over_blob_default() -> Resu
 }

 #[tokio::test]
-async fn namespace_create_applies_blob_defaults() -> Result<()> {
+async fn namespace_blob_create_uses_v2_2_and_default_row_ids() -> Result<()> {
    let tmp = tempdir().unwrap();
    let mut properties = std::collections::HashMap::new();
    properties.insert("root".to_string(), tmp.path().to_str().unwrap().to_string());
@@ -304,6 +304,23 @@ async fn namespace_create_applies_blob_defaults() -> Result<()> {
        .execute()
        .await?;

+    assert!(supports_blob_v2(storage_format_version(&table).await));
+    assert!(!uses_stable_row_ids(&table).await);
+    Ok(())
+}
+
+#[tokio::test]
+async fn namespace_create_honors_enabled_stable_row_ids() -> Result<()> {
+    let tmp = tempdir().unwrap();
+    let mut properties = std::collections::HashMap::new();
+    properties.insert("root".to_string(), tmp.path().to_str().unwrap().to_string());
+    let db = connect_namespace("dir", properties).execute().await?;
+    let table = db
+        .create_empty_table("t", blob_table_schema())
+        .storage_option(OPT_NEW_TABLE_ENABLE_STABLE_ROW_IDS, "true")
+        .execute()
+        .await?;
+
    assert!(supports_blob_v2(storage_format_version(&table).await));
    assert!(uses_stable_row_ids(&table).await);
    Ok(())
@@ -430,6 +447,35 @@ async fn collect_id_rowid(table: &Table) -> Result<Vec<(i64, u64)>> {
        .collect())
 }

+fn assert_missing_blob_row_ids(err: &Error) {
+    assert!(matches!(err, Error::InvalidInput { .. }), "got {err:?}");
+    let message = err.to_string();
+    assert!(message.contains("row ids"), "{message}");
+    assert!(!message.contains("rowaddr"), "{message}");
+    assert!(!message.contains("fragment"), "{message}");
+}
+
+async fn assert_fetch_apis_reject_missing_row_ids(table: &Table, row_ids: &[u64]) -> Result<()> {
+    let err = table.fetch_blobs("image", row_ids).await.unwrap_err();
+    assert_missing_blob_row_ids(&err);
+
+    let err = table.fetch_blob_files("image", row_ids).await.unwrap_err();
+    assert_missing_blob_row_ids(&err);
+
+    let err = table
+        .fetch_blob_ranges(
+            "image",
+            row_ids
+                .iter()
+                .copied()
+                .map(|row_id| BlobRangeRequest::new(row_id, 0, 1)),
+        )
+        .await
+        .unwrap_err();
+    assert_missing_blob_row_ids(&err);
+    Ok(())
+}
+
 #[tokio::test]
 async fn fetch_blobs_round_trips_bytes() -> Result<()> {
    let tmp = tempdir().unwrap();
@@ -482,7 +528,7 @@ async fn fetch_blobs_round_trips_nested_blob_column() -> Result<()> {
    let table = db.create_table("t", batch).execute().await?;

    assert!(supports_blob_v2(storage_format_version(&table).await));
-    assert!(uses_stable_row_ids(&table).await);
+    assert!(!uses_stable_row_ids(&table).await);

    let ids = collect_row_ids(&table).await?;
    let bytes = table.fetch_blobs("info.blob", &ids).await?;
@@ -656,8 +702,7 @@ async fn fetch_blob_ranges_validates_requests() -> Result<()> {
        .fetch_blob_ranges("image", [BlobRangeRequest::new(u64::MAX, 0, 1)])
        .await
        .unwrap_err();
-    assert!(matches!(&err, Error::InvalidInput { .. }), "got {err:?}");
-    assert!(err.to_string().contains("row IDs"));
+    assert_missing_blob_row_ids(&err);
    Ok(())
 }

@@ -690,7 +735,21 @@ async fn fetch_blobs_out_of_range_id_errors_without_panic() -> Result<()> {
    let table = create_inline_blob_table(&db, "t", &[1], &[Some(b"x".as_slice())]).await?;

    let err = table.fetch_blobs("image", &[u64::MAX]).await.unwrap_err();
-    assert!(err.to_string().contains("row IDs"));
+    assert_missing_blob_row_ids(&err);
+    Ok(())
+}
+
+#[tokio::test]
+async fn fetch_blob_files_rejects_missing_fragment_row_addr() -> Result<()> {
+    let tmp = tempdir().unwrap();
+    let db = connect(tmp.path().to_str().unwrap()).execute().await?;
+    let table = create_inline_blob_table(&db, "t", &[1], &[Some(b"x".as_slice())]).await?;
+
+    let err = table
+        .fetch_blob_files("image", &[1u64 << 32])
+        .await
+        .unwrap_err();
+    assert_missing_blob_row_ids(&err);
    Ok(())
 }

@@ -700,24 +759,25 @@ async fn fetch_blob_apis_reject_mixed_valid_and_missing_row_ids() -> Result<()>
    let db = connect(tmp.path().to_str().unwrap()).execute().await?;
    let table = create_inline_blob_table(&db, "t", &[1], &[Some(b"x".as_slice())]).await?;
    let row_id = collect_row_ids(&table).await?[0];
-    let row_ids = [u64::MAX, row_id];
+    let missing_row_addr = 1u64 << 32;
+    let row_ids = [missing_row_addr, row_id];
+    assert_fetch_apis_reject_missing_row_ids(&table, &row_ids).await
+}

-    let err = table.fetch_blobs("image", &row_ids).await.unwrap_err();
-    assert!(matches!(&err, Error::InvalidInput { .. }), "got {err:?}");
-    assert!(err.to_string().contains("row IDs"));
+#[tokio::test]
+async fn fetch_blob_apis_reject_deleted_row_ids() -> Result<()> {
+    let tmp = tempdir().unwrap();
+    let db = connect(tmp.path().to_str().unwrap()).execute().await?;
+    let table =
+        create_inline_blob_table(&db, "t", &[1, 2], &[Some(b"one".as_slice()), Some(b"two")])
+            .await?;
+    let pairs = collect_id_rowid(&table).await?;
+    let deleted_row_addr = pairs.iter().find(|(id, _)| *id == 2).unwrap().1;
+    let live_row_addr = pairs.iter().find(|(id, _)| *id == 1).unwrap().1;

-    let err = table.fetch_blob_files("image", &row_ids).await.unwrap_err();
-    assert!(matches!(&err, Error::InvalidInput { .. }), "got {err:?}");
-    assert!(err.to_string().contains("row IDs"));
+    table.delete("id = 2").await?;

-    let requests = row_ids.map(|row_id| BlobRangeRequest::new(row_id, 0, 1));
-    let err = table
-        .fetch_blob_ranges("image", requests)
-        .await
-        .unwrap_err();
-    assert!(matches!(&err, Error::InvalidInput { .. }), "got {err:?}");
-    assert!(err.to_string().contains("row IDs"));
-    Ok(())
+    assert_fetch_apis_reject_missing_row_ids(&table, &[deleted_row_addr, live_row_addr]).await
 }

 #[tokio::test]
@@ -920,7 +980,10 @@ async fn fetch_blobs_after_delete() -> Result<()> {
 #[tokio::test]
 async fn fetch_blobs_with_precompaction_row_ids_survives_compaction() -> Result<()> {
    let tmp = tempdir().unwrap();
-    let db = connect(tmp.path().to_str().unwrap()).execute().await?;
+    let db = connect(tmp.path().to_str().unwrap())
+        .storage_option(OPT_NEW_TABLE_ENABLE_STABLE_ROW_IDS, "true")
+        .execute()
+        .await?;
    let table = create_inline_blob_table(&db, "t", &[1], &[Some(b"frag-one".as_slice())]).await?;
    table
        .add(binary_input_batch(&[2], &[Some(b"frag-two".as_slice())]))
@@ -1,11 +1,12 @@
 // SPDX-License-Identifier: Apache-2.0
 // SPDX-FileCopyrightText: Copyright The LanceDB Authors

+use std::collections::BTreeMap;
 use std::fs;
 use std::path::PathBuf;

 use lancedb::function::{
-    FunctionApplication, FunctionBinding, FunctionVersion, RefreshColumnResult,
+    FunctionApplication, FunctionBinding, FunctionVersion, RefreshColumnResult, SecretReference,
 };
 use serde_json::Value;

@@ -20,6 +21,26 @@ fn job_result(name: &str) -> Value {
    serde_json::from_str::<Value>(&fixture(name)).expect("remote Job fixture")["result"].clone()
 }

+/// No client value models a resolved credential, at any nesting depth.
+fn assert_no_secret_values(value: &Value) {
+    match value {
+        Value::Object(values) => {
+            for (key, value) in values {
+                assert!(
+                    !matches!(
+                        key.as_str(),
+                        "secret_value" | "secret_values" | "resolved_secret" | "resolved_secrets"
+                    ),
+                    "client canonical value must not model resolved secret material"
+                );
+                assert_no_secret_values(value);
+            }
+        }
+        Value::Array(values) => values.iter().for_each(assert_no_secret_values),
+        _ => {}
+    }
+}
+
 #[test]
 fn function_version_job_result_matches_shared_canonical_golden() {
    let result = job_result("remote_function_job.json");
@@ -28,6 +49,10 @@ fn function_version_job_result_matches_shared_canonical_golden() {
    assert_eq!(version.name(), "embed");
    assert_eq!(version.version(), "fv_01K3EXACT");
    assert_eq!(version.runtime_digest(), "sha256:runtime");
+    assert_eq!(
+        version.secret_env_bindings(),
+        &BTreeMap::from([("HF_TOKEN".to_string(), SecretReference::new("hf-prod"))])
+    );
    assert_eq!(
        version.to_canonical_json().expect("canonical JSON"),
        fixture("remote_function_version.canonical.json").trim()
@@ -142,3 +167,40 @@ fn floating_point_application_literals_are_rejected_consistently() {
            .contains("floating-point Function literals")
    );
 }
+
+#[test]
+fn canonical_client_values_carry_bindings_and_no_credentials() {
+    let result = job_result("remote_function_job.json");
+    let version = FunctionVersion::from_json(&result.to_string()).expect("FunctionVersion result");
+    let canonical: Value = serde_json::from_str(
+        &version
+            .to_canonical_json()
+            .expect("canonical FunctionVersion"),
+    )
+    .expect("canonical JSON");
+
+    assert_eq!(
+        canonical["secret_env_bindings"],
+        serde_json::json!({"HF_TOKEN": {"name": "hf-prod"}})
+    );
+    assert_no_secret_values(&canonical);
+}
+
+/// Every Function registered before Secrets existed serializes unchanged.
+#[test]
+fn a_version_without_bindings_keeps_the_original_wire_shape() {
+    let mut result = job_result("remote_function_job.json");
+    result
+        .as_object_mut()
+        .expect("Function version object")
+        .remove("secret_env_bindings");
+    let version = FunctionVersion::from_json(&result.to_string()).expect("FunctionVersion result");
+
+    assert!(version.secret_env_bindings().is_empty());
+    assert!(
+        !version
+            .to_canonical_json()
+            .expect("canonical FunctionVersion")
+            .contains("secret_env_bindings")
+    );
+}
@@ -5,7 +5,11 @@ use std::fs;
 use std::path::PathBuf;

 use lancedb::Error;
-use lancedb::function::FunctionRegistrationRequest;
+use lancedb::function::{
+    FunctionRegistrationRequest, MAX_FUNCTION_SECRET_ENV_BINDINGS, MAX_SECRET_VALUE_BYTES,
+    SecretReference,
+};
+use serde_json::Value;

 fn fixture(name: &str) -> String {
    let path = PathBuf::from(env!("CARGO_MANIFEST_DIR"))
@@ -14,6 +18,26 @@ fn fixture(name: &str) -> String {
    fs::read_to_string(path).expect("fixture must be readable")
 }

+/// A registration request never models a resolved credential, at any depth.
+fn assert_no_secret_values(value: &Value) {
+    match value {
+        Value::Object(values) => {
+            for (key, value) in values {
+                assert!(
+                    !matches!(
+                        key.as_str(),
+                        "secret_value" | "secret_values" | "resolved_secret" | "resolved_secrets"
+                    ),
+                    "registration requests must not model resolved secret material"
+                );
+                assert_no_secret_values(value);
+            }
+        }
+        Value::Array(values) => values.iter().for_each(assert_no_secret_values),
+        _ => {}
+    }
+}
+
 #[test]
 fn registration_request_matches_shared_canonical_golden() {
    let request = FunctionRegistrationRequest::from_json(&fixture(
@@ -22,10 +46,45 @@ fn registration_request_matches_shared_canonical_golden() {
    .expect("registration request");
    assert_eq!(request.name, "normalize_score");
    assert_eq!(request.artifact.adapter.kind, "scalar_to_arrow_batch");
+    // The unchanged path: a Function that binds nothing serializes today's
+    // bytes, with no `secret_env_bindings` key at all.
+    assert!(request.secret_env_bindings.is_empty());
    assert_eq!(
        request.to_canonical_json().expect("canonical request"),
        fixture("remote_function_registration_request.canonical.json").trim()
    );
+
+    let value: Value =
+        serde_json::from_str(&request.to_canonical_json().expect("canonical request"))
+            .expect("request JSON");
+    assert_no_secret_values(&value);
+}
+
+/// The same shared golden as the Python suite builds from `@udf(secrets=...)`
+/// plus `bind_secrets`, so both clients agree byte for byte on a bound request.
+#[test]
+fn secret_bound_registration_request_matches_shared_canonical_golden() {
+    let request = FunctionRegistrationRequest::from_json(&fixture(
+        "remote_function_secret_registration_request.json",
+    ))
+    .expect("registration request");
+    assert_eq!(request.name, "analyze_caption");
+    assert_eq!(
+        request.secret_env_bindings,
+        std::collections::BTreeMap::from([(
+            "OPENAI_API_KEY".to_string(),
+            SecretReference::new("openai-prod")
+        )])
+    );
+    assert_eq!(
+        request.to_canonical_json().expect("canonical request"),
+        fixture("remote_function_secret_registration_request.canonical.json").trim()
+    );
+
+    let value: Value =
+        serde_json::from_str(&request.to_canonical_json().expect("canonical request"))
+            .expect("request JSON");
+    assert_no_secret_values(&value);
 }

 #[tokio::test]
@@ -57,3 +116,111 @@ async fn local_function_catalog_operations_return_stable_not_supported() {
        ));
    }
 }
+
+/// The cap is enforced above the backend, so every database and every language
+/// surface rejects the same envelope. A local connection would otherwise answer
+/// `NotSupported` first, which is what makes it the honest probe here.
+#[tokio::test]
+async fn a_function_binds_at_most_sixteen_secrets() {
+    let directory = tempfile::tempdir().unwrap();
+    let connection = lancedb::connect(directory.path().to_str().unwrap())
+        .execute()
+        .await
+        .unwrap();
+    let mut request = FunctionRegistrationRequest::from_json(&fixture(
+        "remote_function_registration_request.json",
+    ))
+    .unwrap();
+    request.secret_env_bindings = (0..=MAX_FUNCTION_SECRET_ENV_BINDINGS)
+        .map(|index| {
+            (
+                format!("TOKEN_{index}"),
+                SecretReference::new(format!("secret-{index}")),
+            )
+        })
+        .collect();
+
+    let error = connection.create_function_async(request).await.unwrap_err();
+    assert!(matches!(
+        error,
+        Error::InvalidInput { message } if message.contains("at most 16 secrets")
+    ));
+}
+
+/// The binding contract is enforced above the backend in full, not just its
+/// count: a caller that skips a language binding still cannot register a name
+/// the runtime could not deliver.
+#[tokio::test]
+async fn binding_names_are_validated_before_dispatch() {
+    let directory = tempfile::tempdir().unwrap();
+    let connection = lancedb::connect(directory.path().to_str().unwrap())
+        .execute()
+        .await
+        .unwrap();
+
+    let mut invalid_name = FunctionRegistrationRequest::from_json(&fixture(
+        "remote_function_registration_request.json",
+    ))
+    .unwrap();
+    invalid_name.secret_env_bindings =
+        [("BAD=NAME".to_string(), SecretReference::new("openai-prod"))].into();
+    let error = connection
+        .create_function_async(invalid_name)
+        .await
+        .unwrap_err();
+    assert!(matches!(
+        error,
+        Error::InvalidInput { message } if message.contains("portable")
+    ));
+
+    // `env` is readable wherever the Function's record is; a bound Secret is
+    // not. The same name cannot mean both.
+    let mut overlapping = FunctionRegistrationRequest::from_json(&fixture(
+        "remote_function_registration_request.json",
+    ))
+    .unwrap();
+    let bound = overlapping
+        .runtime
+        .env()
+        .and_then(|env| env.keys().next().cloned())
+        .expect("fixture runtime declares env");
+    overlapping.secret_env_bindings = [(bound.clone(), SecretReference::new("openai-prod"))].into();
+    let error = connection
+        .create_function_async(overlapping)
+        .await
+        .unwrap_err();
+    assert!(matches!(
+        error,
+        Error::InvalidInput { message } if message.contains("already set by runtime.env")
+    ));
+}
+
+/// An oversized credential is refused before a body is built, so it is never
+/// serialized or uploaded to be refused by the service instead.
+#[tokio::test]
+async fn an_oversized_secret_value_is_refused_before_the_wire() {
+    let directory = tempfile::tempdir().unwrap();
+    let connection = lancedb::connect(directory.path().to_str().unwrap())
+        .execute()
+        .await
+        .unwrap();
+
+    for value in ["", &"x".repeat(MAX_SECRET_VALUE_BYTES + 1)] {
+        let error = connection
+            .create_secret("openai-prod", value, &[])
+            .await
+            .unwrap_err();
+        assert!(
+            matches!(error, Error::InvalidInput { .. }),
+            "expected InvalidInput, got {error:?}"
+        );
+    }
+
+    // A local database refuses the verb outright, which is what proves the
+    // size check ran ahead of the backend rather than instead of it.
+    let error = connection
+        .create_secret("openai-prod", "x".repeat(MAX_SECRET_VALUE_BYTES), &[])
+        .await
+        .unwrap_err();
+    assert!(matches!(error, Error::NotSupported { .. }));
+}
@@ -3,7 +3,9 @@
  "job_type": "create_function",
  "job_state": "DONE",
  "creation_ms": 1787270400000,
-  "spec": {"name": "embed"},
+  "spec": {
+    "name": "embed"
+  },
  "result": {
    "name": "embed",
    "version": "fv_01K3EXACT",
@@ -13,18 +15,42 @@
      "entrypoint": "embed"
    },
    "signature": {
-      "inputs": [{"name": "text", "arrow_type": "utf8", "nullable": true}],
-      "output": {"kind": "scalar", "arrow_type": "list<float32>", "nullable": false}
+      "inputs": [
+        {
+          "name": "text",
+          "arrow_type": "utf8",
+          "nullable": true
+        }
+      ],
+      "output": {
+        "kind": "scalar",
+        "arrow_type": "list<float32>",
+        "nullable": false
+      }
    },
    "runtime": {
      "kind": "python",
      "python_version": "3.12",
-      "environment": {"kind": "pip", "packages": ["sentence-transformers>=3"]},
-      "env": {"TOKENIZERS_PARALLELISM": "false"}
+      "environment": {
+        "kind": "pip",
+        "packages": [
+          "sentence-transformers>=3"
+        ]
+      },
+      "env": {
+        "TOKENIZERS_PARALLELISM": "false"
+      }
    },
    "runtime_digest": "sha256:runtime",
    "environment_digest": "sha256:environment",
+    "secret_env_bindings": {
+      "HF_TOKEN": {
+        "name": "hf-prod"
+      }
+    },
    "created_at": "2026-08-21T00:00:00Z"
  },
-  "future_job": {"trace_id": "trace-1"}
+  "future_job": {
+    "trace_id": "trace-1"
+  }
 }
@@ -0,0 +1 @@
+{"artifact":{"adapter":{"kind":"scalar_to_arrow_batch","version":1},"content":{"data":"ZnJvbSBfX2Z1dHVyZV9fIGltcG9ydCBhbm5vdGF0aW9ucwoKZGVmIGFuYWx5emVfY2FwdGlvbihjYXB0aW9uOiBzdHIpIC0+IHN0cjoKICAgIHJldHVybiBjYXB0aW9uLnN0cmlwKCkK","encoding":"base64"},"digest":"sha256:800462c9ad15151a80f83f85b8912ff149300c1563e07f58448f099afcd0d077","entrypoint":"analyze_caption","kind":"python_callable"},"name":"analyze_caption","runtime":{"env":{"MODE":"test"},"environment":{"kind":"pip","packages":["openai==3.7.0"]},"kind":"python","python_version":"3.12"},"secret_env_bindings":{"OPENAI_API_KEY":{"name":"openai-prod"}},"signature":{"inputs":[{"arrow_type":"utf8","name":"caption","nullable":false}],"output":{"arrow_type":"utf8","kind":"scalar","nullable":false}}}
@@ -0,0 +1,48 @@
+{
+  "artifact": {
+    "adapter": {
+      "kind": "scalar_to_arrow_batch",
+      "version": 1
+    },
+    "content": {
+      "data": "ZnJvbSBfX2Z1dHVyZV9fIGltcG9ydCBhbm5vdGF0aW9ucwoKZGVmIGFuYWx5emVfY2FwdGlvbihjYXB0aW9uOiBzdHIpIC0+IHN0cjoKICAgIHJldHVybiBjYXB0aW9uLnN0cmlwKCkK",
+      "encoding": "base64"
+    },
+    "digest": "sha256:800462c9ad15151a80f83f85b8912ff149300c1563e07f58448f099afcd0d077",
+    "entrypoint": "analyze_caption",
+    "kind": "python_callable"
+  },
+  "name": "analyze_caption",
+  "runtime": {
+    "env": {
+      "MODE": "test"
+    },
+    "environment": {
+      "kind": "pip",
+      "packages": [
+        "openai==3.7.0"
+      ]
+    },
+    "kind": "python",
+    "python_version": "3.12"
+  },
+  "secret_env_bindings": {
+    "OPENAI_API_KEY": {
+      "name": "openai-prod"
+    }
+  },
+  "signature": {
+    "inputs": [
+      {
+        "arrow_type": "utf8",
+        "name": "caption",
+        "nullable": false
+      }
+    ],
+    "output": {
+      "arrow_type": "utf8",
+      "kind": "scalar",
+      "nullable": false
+    }
+  }
+}
@@ -1 +1 @@
-{"artifact":{"digest":"sha256:code","entrypoint":"embed","kind":"python_callable"},"created_at":"2026-08-21T00:00:00Z","environment_digest":"sha256:environment","name":"embed","runtime":{"env":{"TOKENIZERS_PARALLELISM":"false"},"environment":{"kind":"pip","packages":["sentence-transformers>=3"]},"kind":"python","python_version":"3.12"},"runtime_digest":"sha256:runtime","signature":{"inputs":[{"arrow_type":"utf8","name":"text","nullable":true}],"output":{"arrow_type":"list<float32>","kind":"scalar","nullable":false}},"version":"fv_01K3EXACT"}
+{"artifact":{"digest":"sha256:code","entrypoint":"embed","kind":"python_callable"},"created_at":"2026-08-21T00:00:00Z","environment_digest":"sha256:environment","name":"embed","runtime":{"env":{"TOKENIZERS_PARALLELISM":"false"},"environment":{"kind":"pip","packages":["sentence-transformers>=3"]},"kind":"python","python_version":"3.12"},"runtime_digest":"sha256:runtime","secret_env_bindings":{"HF_TOKEN":{"name":"hf-prod"}},"signature":{"inputs":[{"arrow_type":"utf8","name":"text","nullable":true}],"output":{"arrow_type":"list<float32>","kind":"scalar","nullable":false}},"version":"fv_01K3EXACT"}
				`@@ -0,0 +1 @@`
				{"artifact":{"adapter":{"kind":"scalar_to_arrow_batch","version":1},"content":{"data":"ZnJvbSBfX2Z1dHVyZV9fIGltcG9ydCBhbm5vdGF0aW9ucwoKZGVmIGFuYWx5emVfY2FwdGlvbihjYXB0aW9uOiBzdHIpIC0+IHN0cjoKICAgIHJldHVybiBjYXB0aW9uLnN0cmlwKCkK","encoding":"base64"},"digest":"sha256:800462c9ad15151a80f83f85b8912ff149300c1563e07f58448f099afcd0d077","entrypoint":"analyze_caption","kind":"python_callable"},"name":"analyze_caption","runtime":{"env":{"MODE":"test"},"environment":{"kind":"pip","packages":["openai==3.7.0"]},"kind":"python","python_version":"3.12"},"secret_env_bindings":{"OPENAI_API_KEY":{"name":"openai-prod"}},"signature":{"inputs":[{"arrow_type":"utf8","name":"caption","nullable":false}],"output":{"arrow_type":"utf8","kind":"scalar","nullable":false}}}