rust/lancedb
1
0
Fork 0
mirror of https://github.com/lancedb/lancedb.git synced 2026-08-18 12:08:35 +00:00
Code Issues Packages Projects Releases Wiki Activity

build(rust): stage pinned Lance source artifact

Browse Source
This commit is contained in:
Gatefixer
2026-08-06 23:31:01 +00:00
parent 6a8146f376
commit 938beb35e9
837 changed files with 646376 additions and 182 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Cargo.lock
Generated
-21
View File
@@ -3456,7 +3456,6 @@ checksum = "42703706b716c37f96a77aea830392ad231f44c9e9a67872fa5548707e11b11c"
[[package]]
name = "fsst"
version = "11.0.0-beta.2"
source = "git+https://github.com/lance-format/lance.git?tag=v11.0.0-beta.2#35da5d920159b49d1b53032652f7615ab699c160"
dependencies = [
"arrow-array",
"rand 0.9.5",
@@ -4816,7 +4815,6 @@ checksum = "e037a2e1d8d5fdbd49b16a4ea09d5d6401c1f29eca5ff29d03d3824dba16256a"
[[package]]
name = "lance"
version = "11.0.0-beta.2"
source = "git+https://github.com/lance-format/lance.git?tag=v11.0.0-beta.2#35da5d920159b49d1b53032652f7615ab699c160"
dependencies = [
"arc-swap",
"arrow",
@@ -4891,7 +4889,6 @@ dependencies = [
[[package]]
name = "lance-arrow"
version = "11.0.0-beta.2"
source = "git+https://github.com/lance-format/lance.git?tag=v11.0.0-beta.2#35da5d920159b49d1b53032652f7615ab699c160"
dependencies = [
"arrow-array",
"arrow-buffer",
@@ -4913,7 +4910,6 @@ dependencies = [
[[package]]
name = "lance-arrow-scalar"
version = "58.0.0"
source = "git+https://github.com/lance-format/lance.git?tag=v11.0.0-beta.2#35da5d920159b49d1b53032652f7615ab699c160"
dependencies = [
"arrow-array",
"arrow-buffer",
@@ -4927,7 +4923,6 @@ dependencies = [
[[package]]
name = "lance-arrow-stats"
version = "58.0.0"
source = "git+https://github.com/lance-format/lance.git?tag=v11.0.0-beta.2#35da5d920159b49d1b53032652f7615ab699c160"
dependencies = [
"arrow-array",
"arrow-schema",
@@ -4937,7 +4932,6 @@ dependencies = [
[[package]]
name = "lance-bitpacking"
version = "11.0.0-beta.2"
source = "git+https://github.com/lance-format/lance.git?tag=v11.0.0-beta.2#35da5d920159b49d1b53032652f7615ab699c160"
dependencies = [
"arrayref",
"crunchy",
@@ -4948,7 +4942,6 @@ dependencies = [
[[package]]
name = "lance-core"
version = "11.0.0-beta.2"
source = "git+https://github.com/lance-format/lance.git?tag=v11.0.0-beta.2#35da5d920159b49d1b53032652f7615ab699c160"
dependencies = [
"arrow-array",
"arrow-buffer",
@@ -4989,7 +4982,6 @@ dependencies = [
[[package]]
name = "lance-datafusion"
version = "11.0.0-beta.2"
source = "git+https://github.com/lance-format/lance.git?tag=v11.0.0-beta.2#35da5d920159b49d1b53032652f7615ab699c160"
dependencies = [
"arrow",
"arrow-array",
@@ -5020,7 +5012,6 @@ dependencies = [
[[package]]
name = "lance-datagen"
version = "11.0.0-beta.2"
source = "git+https://github.com/lance-format/lance.git?tag=v11.0.0-beta.2#35da5d920159b49d1b53032652f7615ab699c160"
dependencies = [
"arrow",
"arrow-array",
@@ -5038,7 +5029,6 @@ dependencies = [
[[package]]
name = "lance-derive"
version = "11.0.0-beta.2"
source = "git+https://github.com/lance-format/lance.git?tag=v11.0.0-beta.2#35da5d920159b49d1b53032652f7615ab699c160"
dependencies = [
"proc-macro2",
"quote",
@@ -5048,7 +5038,6 @@ dependencies = [
[[package]]
name = "lance-encoding"
version = "11.0.0-beta.2"
source = "git+https://github.com/lance-format/lance.git?tag=v11.0.0-beta.2#35da5d920159b49d1b53032652f7615ab699c160"
dependencies = [
"arrow-arith",
"arrow-array",
@@ -5083,7 +5072,6 @@ dependencies = [
[[package]]
name = "lance-file"
version = "11.0.0-beta.2"
source = "git+https://github.com/lance-format/lance.git?tag=v11.0.0-beta.2#35da5d920159b49d1b53032652f7615ab699c160"
dependencies = [
"arrow-arith",
"arrow-array",
@@ -5115,7 +5103,6 @@ dependencies = [
[[package]]
name = "lance-index"
version = "11.0.0-beta.2"
source = "git+https://github.com/lance-format/lance.git?tag=v11.0.0-beta.2#35da5d920159b49d1b53032652f7615ab699c160"
dependencies = [
"arc-swap",
"arrow",
@@ -5183,7 +5170,6 @@ dependencies = [
[[package]]
name = "lance-index-core"
version = "11.0.0-beta.2"
source = "git+https://github.com/lance-format/lance.git?tag=v11.0.0-beta.2#35da5d920159b49d1b53032652f7615ab699c160"
dependencies = [
"arrow-array",
"arrow-schema",
@@ -5242,7 +5228,6 @@ dependencies = [
[[package]]
name = "lance-linalg"
version = "11.0.0-beta.2"
source = "git+https://github.com/lance-format/lance.git?tag=v11.0.0-beta.2#35da5d920159b49d1b53032652f7615ab699c160"
dependencies = [
"arrow-array",
"arrow-buffer",
@@ -5259,7 +5244,6 @@ dependencies = [
[[package]]
name = "lance-namespace"
version = "11.0.0-beta.2"
source = "git+https://github.com/lance-format/lance.git?tag=v11.0.0-beta.2#35da5d920159b49d1b53032652f7615ab699c160"
dependencies = [
"arrow",
"async-trait",
@@ -5272,7 +5256,6 @@ dependencies = [
[[package]]
name = "lance-namespace-impls"
version = "11.0.0-beta.2"
source = "git+https://github.com/lance-format/lance.git?tag=v11.0.0-beta.2#35da5d920159b49d1b53032652f7615ab699c160"
dependencies = [
"arrow",
"arrow-ipc",
@@ -5327,7 +5310,6 @@ dependencies = [
[[package]]
name = "lance-select"
version = "11.0.0-beta.2"
source = "git+https://github.com/lance-format/lance.git?tag=v11.0.0-beta.2#35da5d920159b49d1b53032652f7615ab699c160"
dependencies = [
"arrow-array",
"arrow-buffer",
@@ -5343,7 +5325,6 @@ dependencies = [
[[package]]
name = "lance-table"
version = "11.0.0-beta.2"
source = "git+https://github.com/lance-format/lance.git?tag=v11.0.0-beta.2#35da5d920159b49d1b53032652f7615ab699c160"
dependencies = [
"arrow",
"arrow-array",
@@ -5383,7 +5364,6 @@ dependencies = [
[[package]]
name = "lance-testing"
version = "11.0.0-beta.2"
source = "git+https://github.com/lance-format/lance.git?tag=v11.0.0-beta.2#35da5d920159b49d1b53032652f7615ab699c160"
dependencies = [
"arrow-array",
"arrow-schema",
@@ -5397,7 +5377,6 @@ dependencies = [
[[package]]
name = "lance-tokenizer"
version = "11.0.0-beta.2"
source = "git+https://github.com/lance-format/lance.git?tag=v11.0.0-beta.2#35da5d920159b49d1b53032652f7615ab699c160"
dependencies = [
"frostem",
"icu_segmenter",
Cargo.toml
+15 -2
View File
@@ -1,6 +1,6 @@
[workspace]
members = ["rust/lancedb", "nodejs", "python"]
exclude = ["vendor/lance-io"]
exclude = ["lance-artifact"]
resolver = "2"
[workspace.package]
@@ -69,7 +69,20 @@ semver = "1.0.25"
chrono = "0.4"
[patch."https://github.com/lance-format/lance.git"]
lance-io = { path = "vendor/lance-io" }
lance = { path = "lance-artifact/rust/lance" }
lance-arrow = { path = "lance-artifact/rust/lance-arrow" }
lance-core = { path = "lance-artifact/rust/lance-core" }
lance-datafusion = { path = "lance-artifact/rust/lance-datafusion" }
lance-datagen = { path = "lance-artifact/rust/lance-datagen" }
lance-encoding = { path = "lance-artifact/rust/lance-encoding" }
lance-file = { path = "lance-artifact/rust/lance-file" }
lance-index = { path = "lance-artifact/rust/lance-index" }
lance-io = { path = "lance-artifact/rust/lance-io" }
lance-linalg = { path = "lance-artifact/rust/lance-linalg" }
lance-namespace = { path = "lance-artifact/rust/lance-namespace" }
lance-namespace-impls = { path = "lance-artifact/rust/lance-namespace-impls" }
lance-table = { path = "lance-artifact/rust/lance-table" }
lance-testing = { path = "lance-artifact/rust/lance-testing" }
[profile.ci]
debug = "line-tables-only"
lance-artifact/Cargo.toml
+266
View File
@@ -0,0 +1,266 @@
[workspace]
members = [
"rust/examples",
"rust/lance",
"rust/lance-arrow",
"rust/lance-core",
"rust/lance-datagen",
"rust/lance-encoding",
"rust/lance-file",
"rust/lance-geo",
"rust/lance-index",
"rust/lance-index-core",
"rust/lance-io",
"rust/lance-linalg",
"rust/lance-namespace",
"rust/lance-namespace-impls",
"rust/lance-namespace-datafusion",
"rust/lance-select",
"rust/lance-tokenizer",
"rust/lance-table",
"rust/lance-derive",
"rust/lance-test-macros",
"rust/lance-testing",
"rust/lance-tools",
"rust/compression/fsst",
"rust/compression/bitpacking",
"rust/arrow-scalar",
"rust/arrow-stats",
]
exclude = ["python", "java/lance-jni"]
# Python package needs to be built by maturin.
resolver = "3"
[workspace.package]
version = "11.0.0-beta.2"
edition = "2024"
authors = ["Lance Devs <dev@lance.org>"]
license = "Apache-2.0"
repository = "https://github.com/lance-format/lance"
readme = "README.md"
description = "A columnar data format that is 100x faster than Parquet for random access."
keywords = [
"data-format",
"data-science",
"machine-learning",
"apache-arrow",
"data-analytics",
]
categories = [
"database-implementations",
"data-structures",
"development-tools",
"science",
]
rust-version = "1.91.0"
[workspace.dependencies]
arc-swap = "1.7"
libc = "0.2.176"
lance = { version = "=11.0.0-beta.2", path = "./rust/lance", default-features = false }
lance-arrow = { version = "=11.0.0-beta.2", path = "./rust/lance-arrow" }
lance-core = { version = "=11.0.0-beta.2", path = "./rust/lance-core" }
lance-datafusion = { version = "=11.0.0-beta.2", path = "./rust/lance-datafusion" }
lance-datagen = { version = "=11.0.0-beta.2", path = "./rust/lance-datagen" }
lance-derive = { version = "=11.0.0-beta.2", path = "./rust/lance-derive" }
lance-encoding = { version = "=11.0.0-beta.2", path = "./rust/lance-encoding" }
lance-file = { version = "=11.0.0-beta.2", path = "./rust/lance-file" }
lance-geo = { version = "=11.0.0-beta.2", path = "./rust/lance-geo" }
lance-index = { version = "=11.0.0-beta.2", path = "./rust/lance-index" }
lance-index-core = { version = "=11.0.0-beta.2", path = "./rust/lance-index-core" }
lance-io = { version = "=11.0.0-beta.2", path = "./rust/lance-io", default-features = false }
lance-linalg = { version = "=11.0.0-beta.2", path = "./rust/lance-linalg" }
lance-namespace = { version = "=11.0.0-beta.2", path = "./rust/lance-namespace" }
lance-namespace-impls = { version = "=11.0.0-beta.2", path = "./rust/lance-namespace-impls" }
lance-namespace-datafusion = { version = "=7.0.0-beta.9", path = "./rust/lance-namespace-datafusion" }
lance-namespace-reqwest-client = "0.8.6"
lance-select = { version = "=11.0.0-beta.2", path = "./rust/lance-select" }
lance-tokenizer = { version = "=11.0.0-beta.2", path = "./rust/lance-tokenizer" }
lance-table = { version = "=11.0.0-beta.2", path = "./rust/lance-table" }
lance-test-macros = { version = "=11.0.0-beta.2", path = "./rust/lance-test-macros" }
lance-testing = { version = "=11.0.0-beta.2", path = "./rust/lance-testing" }
approx = "0.5.1"
# Note that this one does not include pyarrow
arrow = { version = "58.0.0", optional = false, features = ["prettyprint"] }
lance-arrow-scalar = { version = "=58.0.0", path = "./rust/arrow-scalar" }
lance-arrow-stats = { version = "=58.0.0", path = "./rust/arrow-stats" }
arrow-arith = "58.0.0"
arrow-array = "58.0.0"
arrow-buffer = "58.0.0"
arrow-cast = "58.0.0"
arrow-data = "58.0.0"
arrow-ipc = { version = "58.0.0", features = ["zstd"] }
arrow-ord = "58.0.0"
arrow-row = "58.0.0"
arrow-schema = "58.0.0"
arrow-select = "58.0.0"
async-recursion = "1.0"
async-trait = "0.1"
axum = "0.7"
aws-config = "1.2.0"
aws-credential-types = "1.2.0"
aws-sdk-dynamodb = { version = "1.38.0", default-features = false }
aws-sdk-s3 = { version = "1.38.0", default-features = false }
half = { "version" = "2.1", default-features = false, features = [
"num-traits",
"std",
"bytemuck",
] }
lance-bitpacking = { version = "=11.0.0-beta.2", path = "./rust/compression/bitpacking" }
bitpacking = "0.9"
bitvec = "1"
blake3 = "1.8.5"
bytemuck = { version = "1", default-features = false, features = [
"extern_crate_alloc",
] }
bytes = "1.11.1"
byteorder = "1.5"
clap = { version = "4", features = ["derive"] }
chrono = { version = "0.4.41", default-features = false, features = [
"std",
"now",
"serde",
] }
criterion = { version = "0.8.2", features = [
"async",
"async_tokio",
"html_reports",
] }
crossbeam-queue = "0.3"
crossbeam-skiplist = "0.1"
datafusion = { version = "54.0.0", default-features = false, features = [
"crypto_expressions",
"datetime_expressions",
"encoding_expressions",
"nested_expressions",
"regex_expressions",
"sql",
"string_expressions",
"unicode_expressions",
] }
datafusion-common = "54.0.0"
datafusion-functions = { version = "54.0.0", default-features = false, features = ["regex_expressions"] }
datafusion-sql = "54.0.0"
datafusion-expr = "54.0.0"
datafusion-ffi = "54.0.0"
datafusion-physical-expr = "54.0.0"
datafusion-physical-plan = "54.0.0"
datafusion-substrait = { version = "54.0.0", default-features = false }
dirs = "6.0.0"
either = "1.0"
fst = { version = "0.4.7", features = ["levenshtein"] }
fsst = { version = "=11.0.0-beta.2", path = "./rust/compression/fsst" }
futures = "0.3"
geoarrow-array = "0.8"
geoarrow-schema = "0.8"
geodatafusion = "0.5.0"
geo-traits = "0.3.0"
geo-types = "0.7.16"
http = "1.1.0"
humantime = "2.2.0"
hyperloglogplus = { version = "0.4.1", features = ["const-loop"] }
icu_segmenter = { version = "2.2", default-features = false, features = ["compiled_data"] }
io-uring = "0.7"
itertools = "0.14"
jieba-rs = { version = "0.10.0", default-features = false }
jsonb = { version = "0.5.3", default-features = false, features = ["databend"] }
libm = "0.2.15"
log = "0.4"
metrics = { version = "0.24" }
metrics-util = { version = "0.19" }
mockall = { version = "0.14.0" }
mock_instant = { version = "0.6.0" }
moka = { version = "0.12", features = ["future", "sync"] }
ndarray = { version = "0.16.1", features = ["matrixmultiply-threading"] }
num-traits = "0.2"
object_store = { version = "0.13.2" }
opendal = { version = "0.58.1" }
object_store_opendal = { version = "0.58" }
pin-project = "1.0"
path_abs = "0.5"
pprof = { version = "0.15.0", features = ["flamegraph"] }
proptest = "1.3.1"
prost = "0.14.1"
prost-build = "0.14.1"
prost-types = "0.14.1"
rand = { version = "0.9.1", features = ["small_rng"] }
rand_distr = { version = "0.5.1" }
rand_xoshiro = "0.7.0"
rangemap = { version = "1.0" }
rayon = "1.10"
regex-syntax = "0.8.10"
roaring = "0.11.4"
rstest = "0.26.1"
serde = { version = "^1" }
serde_json = { version = "1" }
semver = "1.0"
serial_test = "3"
snafu = "0.9"
lindera = { version = "3.0.7" }
tempfile = "3"
test-log = { version = "0.2.15" }
tokio = { version = "1.23", features = [
"rt-multi-thread",
"macros",
"fs",
"sync",
] }
tokio-stream = "0.1.14"
tokio-util = { version = "0.7.16" }
tower = "0.5"
tower-http = "0.5"
tracing = "0.1"
tracing-mock = { version = "=0.1.0-beta.3" }
twox-hash = "2.0"
url = "2.5.7"
uuid = { version = "1.2", features = ["v4", "serde"] }
wiremock = "0.6"
pretty_assertions = "1.4.0"
[profile.bench]
opt-level = 3
debug = true
strip = false
[profile.ci]
debug = "line-tables-only"
inherits = "dev"
incremental = false
# This rule applies to every package except workspace members (dependencies
# such as `arrow` and `tokio`). It disables debug info and related features on
# dependencies so their binaries stay smaller, improving cache reuse.
[profile.ci.package."*"]
debug = false
debug-assertions = false
strip = "debuginfo"
incremental = false
[workspace.lints.rust]
unexpected_cfgs = { level = "warn", check-cfg = ['cfg(coverage,coverage_nightly)'] }
unsafe_op_in_unsafe_fn = "allow"
[workspace.lints.clippy]
all = { level = "deny", priority = -1 }
style = { level = "deny", priority = -1 }
cargo = { level = "deny", priority = -1 }
fallible_impl_from = "deny"
manual_let_else = "deny"
redundant_pub_crate = "deny"
string_add_assign = "deny"
string_add = "deny"
string_lit_as_bytes = "deny"
use_self = "deny"
dbg_macro = "deny"
trait_duplication_in_bounds = "deny"
redundant_clone = "deny"
# We should always use log instead of println
print_stdout = "deny"
print_stderr = "deny"
# not too much we can do to avoid multiple crate versions
multiple-crate-versions = "allow"
# We use Vec<Range<u64>> in a lot of places and it is very common to use a single range in the vec.
single_range_in_vec_init = "allow"
large_futures = "deny"
disallowed_macros = "deny"
vendor/lance-io/LANCEDB_PATCH.md → lance-artifact/LANCEDB_PATCH.md
+3 -6
View File
@@ -1,11 +1,8 @@
# LanceDB patch provenance
This directory vendors `lance-io` 11.0.0-beta.2 from Lance commit
`35da5d920159b49d1b53032652f7615ab699c160`.
`Cargo.toml` uses the equivalent standalone dependency metadata from the published crate. Upstream
benchmark and integration-test targets are omitted because this copy is compiled only as a patched
dependency; the library sources are otherwise retained.
This artifact vendors the Lance 11.0.0-beta.2 Rust workspace from Lance commit
`35da5d920159b49d1b53032652f7615ab699c160`. The complete workspace keeps all mutually coupled
Lance crates on one Cargo source identity when `lancedb` consumes the pinned artifact commit.
The local patch makes AWS credential-family merging atomic before backend selection and teaches
the built-in OpenDAL S3 path to refresh credential-only storage options. Keeping the change inside
lance-artifact/LICENSE
+255
View File
@@ -0,0 +1,255 @@
Apache License
Version 2.0, January 2004
http://www.apache.org/licenses/
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
1. Definitions.
"License" shall mean the terms and conditions for use, reproduction,
and distribution as defined by Sections 1 through 9 of this document.
"Licensor" shall mean the copyright owner or entity authorized by
the copyright owner that is granting the License.
"Legal Entity" shall mean the union of the acting entity and all
other entities that control, are controlled by, or are under common
control with that entity. For the purposes of this definition,
"control" means (i) the power, direct or indirect, to cause the
direction or management of such entity, whether by contract or
otherwise, or (ii) ownership of fifty percent (50%) or more of the
outstanding shares, or (iii) beneficial ownership of such entity.
"You" (or "Your") shall mean an individual or Legal Entity
exercising permissions granted by this License.
"Source" form shall mean the preferred form for making modifications,
including but not limited to software source code, documentation
source, and configuration files.
"Object" form shall mean any form resulting from mechanical
transformation or translation of a Source form, including but
not limited to compiled object code, generated documentation,
and conversions to other media types.
"Work" shall mean the work of authorship, whether in Source or
Object form, made available under the License, as indicated by a
copyright notice that is included in or attached to the work
(an example is provided in the Appendix below).
"Derivative Works" shall mean any work, whether in Source or Object
form, that is based on (or derived from) the Work and for which the
editorial revisions, annotations, elaborations, or other modifications
represent, as a whole, an original work of authorship. For the purposes
of this License, Derivative Works shall not include works that remain
separable from, or merely link (or bind by name) to the interfaces of,
the Work and Derivative Works thereof.
"Contribution" shall mean any work of authorship, including
the original version of the Work and any modifications or additions
to that Work or Derivative Works thereof, that is intentionally
submitted to Licensor for inclusion in the Work by the copyright owner
or by an individual or Legal Entity authorized to submit on behalf of
the copyright owner. For the purposes of this definition, "submitted"
means any form of electronic, verbal, or written communication sent
to the Licensor or its representatives, including but not limited to
communication on electronic mailing lists, source code control systems,
and issue tracking systems that are managed by, or on behalf of, the
Licensor for the purpose of discussing and improving the Work, but
excluding communication that is conspicuously marked or otherwise
designated in writing by the copyright owner as "Not a Contribution."
"Contributor" shall mean Licensor and any individual or Legal Entity
on behalf of whom a Contribution has been received by Licensor and
subsequently incorporated within the Work.
2. Grant of Copyright License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
copyright license to reproduce, prepare Derivative Works of,
publicly display, publicly perform, sublicense, and distribute the
Work and such Derivative Works in Source or Object form.
3. Grant of Patent License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
(except as stated in this section) patent license to make, have made,
use, offer to sell, sell, import, and otherwise transfer the Work,
where such license applies only to those patent claims licensable
by such Contributor that are necessarily infringed by their
Contribution(s) alone or by combination of their Contribution(s)
with the Work to which such Contribution(s) was submitted. If You
institute patent litigation against any entity (including a
cross-claim or counterclaim in a lawsuit) alleging that the Work
or a Contribution incorporated within the Work constitutes direct
or contributory patent infringement, then any patent licenses
granted to You under this License for that Work shall terminate
as of the date such litigation is filed.
4. Redistribution. You may reproduce and distribute copies of the
Work or Derivative Works thereof in any medium, with or without
modifications, and in Source or Object form, provided that You
meet the following conditions:
(a) You must give any other recipients of the Work or
Derivative Works a copy of this License; and
(b) You must cause any modified files to carry prominent notices
stating that You changed the files; and
(c) You must retain, in the Source form of any Derivative Works
that You distribute, all copyright, patent, trademark, and
attribution notices from the Source form of the Work,
excluding those notices that do not pertain to any part of
the Derivative Works; and
(d) If the Work includes a "NOTICE" text file as part of its
distribution, then any Derivative Works that You distribute must
include a readable copy of the attribution notices contained
within such NOTICE file, excluding those notices that do not
pertain to any part of the Derivative Works, in at least one
of the following places: within a NOTICE text file distributed
as part of the Derivative Works; within the Source form or
documentation, if provided along with the Derivative Works; or,
within a display generated by the Derivative Works, if and
wherever such third-party notices normally appear. The contents
of the NOTICE file are for informational purposes only and
do not modify the License. You may add Your own attribution
notices within Derivative Works that You distribute, alongside
or as an addendum to the NOTICE text from the Work, provided
that such additional attribution notices cannot be construed
as modifying the License.
You may add Your own copyright statement to Your modifications and
may provide additional or different license terms and conditions
for use, reproduction, or distribution of Your modifications, or
for any such Derivative Works as a whole, provided Your use,
reproduction, and distribution of the Work otherwise complies with
the conditions stated in this License.
5. Submission of Contributions. Unless You explicitly state otherwise,
any Contribution intentionally submitted for inclusion in the Work
by You to the Licensor shall be under the terms and conditions of
this License, without any additional terms or conditions.
Notwithstanding the above, nothing herein shall supersede or modify
the terms of any separate license agreement you may have executed
with Licensor regarding such Contributions.
6. Trademarks. This License does not grant permission to use the trade
names, trademarks, service marks, or product names of the Licensor,
except as required for reasonable and customary use in describing the
origin of the Work and reproducing the content of the NOTICE file.
7. Disclaimer of Warranty. Unless required by applicable law or
agreed to in writing, Licensor provides the Work (and each
Contributor provides its Contributions) on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
implied, including, without limitation, any warranties or conditions
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
PARTICULAR PURPOSE. You are solely responsible for determining the
appropriateness of using or redistributing the Work and assume any
risks associated with Your exercise of permissions under this License.
8. Limitation of Liability. In no event and under no legal theory,
whether in tort (including negligence), contract, or otherwise,
unless required by applicable law (such as deliberate and grossly
negligent acts) or agreed to in writing, shall any Contributor be
liable to You for damages, including any direct, indirect, special,
incidental, or consequential damages of any character arising as a
result of this License or out of the use or inability to use the
Work (including but not limited to damages for loss of goodwill,
work stoppage, computer failure or malfunction, or any and all
other commercial damages or losses), even if such Contributor
has been advised of the possibility of such damages.
9. Accepting Warranty or Additional Liability. While redistributing
the Work or Derivative Works thereof, You may choose to offer,
and charge a fee for, acceptance of support, warranty, indemnity,
or other liability obligations and/or rights consistent with this
License. However, in accepting such obligations, You may act only
on Your own behalf and on Your sole responsibility, not on behalf
of any other Contributor, and only if You agree to indemnify,
defend, and hold each Contributor harmless for any liability
incurred by, or claims asserted against, such Contributor by reason
of your accepting any such warranty or additional liability.
END OF TERMS AND CONDITIONS
APPENDIX: How to apply the Apache License to your work.
To apply the Apache License to your work, attach the following
boilerplate notice, with the fields enclosed by brackets "[]"
replaced with your own identifying information. (Don't include
the brackets!) The text should be enclosed in the appropriate
comment syntax for the file format. We also recommend that a
file or class name and description of purpose be included on the
same "printed page" as the copyright notice for easier
identification within third-party archives.
Copyright [yyyy] [name of copyright owner]
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
--------------------------------------------------------------------------------
This project includes code from Ritchie Vink's Polars project, which is licensed
under the MIT license:
Copyright (c) 2020 Ritchie Vink
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
https://github.com/pola-rs/polars/blob/main/LICENSE
--------------------------------------------------------------------------------
This project includes code adapted from the quickwit-oss/bitpacking crate, which
is licensed under the MIT license:
Copyright (c) 2016 Paul Masurel
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
https://github.com/quickwit-oss/bitpacking/blob/main/LICENSE
lance-artifact/README.md
+247
View File
@@ -0,0 +1,247 @@
<div align="center">
<p align="center">
<img width="257" alt="Lance Logo" src="https://user-images.githubusercontent.com/917119/199353423-d3e202f7-0269-411d-8ff2-e747e419e492.png">
**The Open Lakehouse Format for Multimodal AI**<br/>
**High-performance vector search, full-text search, random access, and feature engineering capabilities for the lakehouse.**<br/>
**Compatible with Pandas, DuckDB, Polars, PyArrow, Ray, Spark, and more integrations on the way.**
<a href="https://lance.org">Documentation</a> •
<a href="https://lance.org/community">Community</a> •
<a href="https://discord.gg/lance">Discord</a> •
<a href="https://groups.google.com/a/lance.org/g/dev">Mailing List</a>
[CI]: https://github.com/lance-format/lance/actions/workflows/rust.yml
[CI Badge]: https://github.com/lance-format/lance/actions/workflows/rust.yml/badge.svg
[Docs]: https://lance.org
[Docs Badge]: https://img.shields.io/badge/docs-passing-brightgreen
[crates.io]: https://crates.io/crates/lance
[crates.io badge]: https://img.shields.io/crates/v/lance.svg
[Python versions]: https://pypi.org/project/pylance/
[Python versions badge]: https://img.shields.io/pypi/pyversions/pylance
[![CI Badge]][CI]
[![Docs Badge]][Docs]
[![crates.io badge]][crates.io]
[![Python versions badge]][Python versions]
</p>
</div>
<hr />
Lance is an open lakehouse format for multimodal AI. It contains a file format, table format, and catalog spec that allows you to build a complete lakehouse on top of object storage to power your AI workflows. Lance is perfect for:
1. Building search engines and feature stores with hybrid search capabilities.
2. Large-scale ML training requiring high performance IO and random access.
3. Storing, querying, and managing multimodal data including images, videos, audio, text, and embeddings.
The key features of Lance include:
* **Expressive hybrid search:** Combine vector similarity search, full-text search (BM25), and SQL analytics on the same dataset with accelerated secondary indices.
* **Lightning-fast random access:** 100x faster than Parquet or Iceberg for random access without sacrificing scan performance.
* **Native multimodal data support:** Store images, videos, audio, text, and embeddings in a single unified format with efficient blob encoding and lazy loading.
* **Data evolution:** Efficiently add columns with backfilled values without full table rewrites, perfect for ML feature engineering.
* **Zero-copy versioning:** Automatic versioning with ACID transactions, time travel, tags, and branches—no extra infrastructure needed.
* **Rich ecosystem integrations:** Apache Arrow, Pandas, Polars, DuckDB, Apache Spark, Ray, Trino, Apache Flink, and open catalogs (Apache Polaris, Unity Catalog, Apache Gravitino).
For more details, see the full [Lance format specification](https://lance.org/format).
> [!TIP]
> Lance is in active development and we welcome contributions. Please see our [contributing guide](https://lance.org/community/contributing/) for more information.
## File format stability
Lance releases frequently because the SDKs, integrations, and performance work are moving quickly. This does not mean the Lance file format changes incompatibly in every release. The Lance file format is identified by the `data_storage_version` stored in each dataset, and stable storage versions are a long-term compatibility contract.
* Once a dataset is written with a stable `data_storage_version`, future Lance releases will continue to support reading that storage version.
* SDK and API compatibility is separate from file format compatibility. SDK/API changes follow semantic versioning and are documented in the [migration guide](https://lance.org/guide/migration/).
* Older Lance releases may not understand file format versions introduced later. If you run mixed Lance versions, pin `data_storage_version` for deterministic writes.
* The `next` file format alias is unstable and should only be used for experimentation, never for production data.
For production, write data with a stable `data_storage_version`. See the [format versioning guide](https://lance.org/format/file/versioning/) for the current compatibility matrix.
## Quick Start
**Installation**
```shell
pip install pylance
```
To install a preview release:
```shell
pip install --pre --extra-index-url https://pypi.fury.io/lance-format pylance
```
> [!TIP]
> Preview releases are released more often than full releases and contain the
> latest features and bug fixes. They receive the same level of testing as full releases.
> We guarantee they will remain published and available for download for at
> least 6 months. When you want to pin to a specific version, prefer a stable release.
**Converting to Lance**
```python
import lance
import pandas as pd
import pyarrow as pa
import pyarrow.dataset
df = pd.DataFrame({"a": [5], "b": [10]})
uri = "/tmp/test.parquet"
tbl = pa.Table.from_pandas(df)
pa.dataset.write_dataset(tbl, uri, format='parquet')
parquet = pa.dataset.dataset(uri, format='parquet')
lance.write_dataset(parquet, "/tmp/test.lance")
```
**Reading Lance data**
```python
dataset = lance.dataset("/tmp/test.lance")
assert isinstance(dataset, pa.dataset.Dataset)
```
**Pandas**
```python
df = dataset.to_table().to_pandas()
df
```
**DuckDB**
```python
import duckdb
# If this segfaults, make sure you have duckdb v0.7+ installed
duckdb.query("SELECT * FROM dataset LIMIT 10").to_df()
```
**Vector search**
Download the sift1m subset
```shell
wget ftp://ftp.irisa.fr/local/texmex/corpus/sift.tar.gz
tar -xzf sift.tar.gz
```
Convert it to Lance
```python
import lance
from lance.vector import vec_to_table
import numpy as np
import struct
nvecs = 1000000
ndims = 128
with open("sift/sift_base.fvecs", mode="rb") as fobj:
buf = fobj.read()
data = np.array(struct.unpack("<128000000f", buf[4 : 4 + 4 * nvecs * ndims])).reshape((nvecs, ndims))
dd = dict(zip(range(nvecs), data))
table = vec_to_table(dd)
uri = "vec_data.lance"
sift1m = lance.write_dataset(table, uri, max_rows_per_group=8192, max_rows_per_file=1024*1024)
```
Build the index
```python
sift1m.create_index("vector",
index_type="IVF_PQ",
num_partitions=256, # IVF
num_sub_vectors=16) # PQ
```
Search the dataset
```python
# Get top 10 similar vectors
import duckdb
dataset = lance.dataset(uri)
# Sample 100 query vectors. If this segfaults, make sure you have duckdb v0.7+ installed
sample = duckdb.query("SELECT vector FROM dataset USING SAMPLE 100").to_df()
query_vectors = np.array([np.array(x) for x in sample.vector])
# Get nearest neighbors for all of them
rs = [dataset.to_table(nearest={"column": "vector", "k": 10, "q": q})
for q in query_vectors]
```
## Directory structure
| Directory | Description |
|--------------------|--------------------------|
| [rust](./rust) | Core Rust implementation |
| [python](./python) | Python bindings (PyO3) |
| [java](./java) | Java bindings (JNI) |
| [docs](./docs) | Documentation source |
## Benchmarks
### Vector search
We used the SIFT dataset to benchmark our results with 1M vectors of 128D
1. For 100 randomly sampled query vectors, we get <1ms average response time (on a 2023 m2 MacBook Air)
![avg_latency.png](docs/src/images/avg_latency.png)
2. ANNs are always a trade-off between recall and performance
![avg_latency.png](docs/src/images/recall_vs_latency.png)
### Vs. parquet
We create a Lance dataset using the Oxford Pet dataset to do some preliminary performance testing of Lance as compared to Parquet and raw image/XMLs. For analytics queries, Lance is 50-100x better than reading the raw metadata. For batched random access, Lance is 100x better than both parquet and raw files.
![](docs/src/images/lance_perf.png)
## Why Lance for AI/ML workflows?
The machine learning development cycle involves multiple stages:
```mermaid
graph LR
A[Collection] --> B[Exploration];
B --> C[Analytics];
C --> D[Feature Engineer];
D --> E[Training];
E --> F[Evaluation];
F --> C;
E --> G[Deployment];
G --> H[Monitoring];
H --> A;
```
Traditional lakehouse formats were designed for SQL analytics and struggle with AI/ML workloads that require:
- **Vector search** for similarity and semantic retrieval
- **Fast random access** for sampling and interactive exploration
- **Multimodal data** storage (images, videos, audio alongside embeddings)
- **Data evolution** for feature engineering without full table rewrites
- **Hybrid search** combining vectors, full-text, and SQL predicates
While existing formats (Parquet, Iceberg, Delta Lake) excel at SQL analytics, they require additional specialized systems for AI capabilities. Lance brings these AI-first features directly into the lakehouse format.
A comparison of different formats across ML development stages:
| | Lance | Parquet & ORC | JSON & XML | TFRecord | Database | Warehouse |
|---------------------|-------|---------------|------------|----------|----------|-----------|
| Analytics | Fast | Fast | Slow | Slow | Decent | Fast |
| Feature Engineering | Fast | Fast | Decent | Slow | Decent | Good |
| Training | Fast | Decent | Slow | Fast | N/A | N/A |
| Exploration | Fast | Slow | Fast | Slow | Fast | Decent |
| Infra Support | Rich | Rich | Decent | Limited | Rich | Rich |
lance-artifact/protos/AGENTS.md
+19
View File
@@ -0,0 +1,19 @@
# Protobuf Guidelines
Also see [root AGENTS.md](../AGENTS.md) for cross-language standards.
## Compatibility
- Protobuf schemas that are part of a stable file format or any other stable persisted contract must remain backwards compatible. Never reuse or change their existing field numbers.
- Protobuf schemas used exclusively by an unstable file format follow the root file-format stability contract: do not preserve compatibility with prior unstable revisions. Before making a breaking protobuf change, verify that the schema is not shared with a stable format or another persisted contract.
## Schema Design
- Use `optional` when you need to distinguish "not set" from "zero value" — `optional` enables presence tracking (`has_*` methods) and maps to `Option<T>` in Rust. Bare proto3 fields have no presence semantics: they always hold a value (defaulting to zero), so you cannot tell if the sender explicitly set them.
- Use structured message types (e.g., `BasePath`) instead of plain scalars, and scope fields to operation-specific messages (e.g., `InsertTransaction`) rather than generic top-level ones.
- Don't duplicate data across messages — store each fact once and derive relationships. Prefer parallel sequences over maps when keys already exist in another field.
## Documentation
- Document the semantic meaning of both present and absent states for `optional` fields — explain when each case applies.
- Use precise domain terminology in field descriptions — avoid ambiguous abbreviations or terms that collide with domain concepts.
lance-artifact/protos/CLAUDE.md
Symlink
+1
View File
@@ -0,0 +1 @@
AGENTS.md
lance-artifact/protos/ann.proto
+72
View File
@@ -0,0 +1,72 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright The Lance Authors
syntax = "proto3";
package lance.pb;
import "table_identifier.proto";
import "table.proto";
import "index.proto";
// Query-time approximation mode for vector search.
//
// This currently only affects RQ-quantized vector indexes, such as IVF_RQ.
// Other index types ignore this setting.
enum VectorApproxMode {
// Use all RQ bits for query-time scoring with u8-quantized lookup tables.
Normal = 0;
// Use only one RQ bit for query-time scoring, even for multi-bit indexes.
Fast = 1;
// Use all RQ bits for query-time scoring with u16-quantized lookup tables
// to reduce estimator quantization error.
Accurate = 2;
}
// Serialized vector query parameters.
message VectorQueryProto {
// Query vector as Arrow IPC bytes (supports Float16, Float32, Float64, UInt8, etc.)
bytes query_vector_arrow_ipc = 1;
string column = 2;
uint32 k = 3;
optional float lower_bound = 4;
optional float upper_bound = 5;
optional uint32 minimum_nprobes = 6;
optional uint32 maximum_nprobes = 7;
optional uint32 ef = 8;
optional uint32 refine_factor = 9;
// Distance metric type. Absent means None (use the index's default metric).
optional lance.index.pb.VectorMetricType metric_type = 10;
bool use_index = 11;
optional float dist_q_c = 12;
optional int32 query_parallelism = 13;
// Query-time approximation mode. Currently only affects RQ-quantized vector
// indexes, such as IVF_RQ. Other index types ignore this setting.
VectorApproxMode approx_mode = 14;
}
// Serializable form of ANNIvfSubIndexExec — the IVF sub-index search node.
//
// The prefilter child ExecutionPlan is serialized by DataFusion's codec
// automatically via children() / with_new_children(). The prefilter_type
// field tells the decoder which PreFilterSource variant to use when
// reconstructing from the deserialized child inputs.
message ANNIvfSubIndexExecProto {
enum PreFilterType {
NONE = 0;
FILTERED_ROW_IDS = 1;
SCALAR_INDEX_QUERY = 2;
}
VectorQueryProto query = 1;
lance.datafusion.TableIdentifier table = 2;
repeated lance.table.IndexMetadata indices = 3;
PreFilterType prefilter_type = 4;
}
// Serializable form of ANNIvfPartitionExec — the IVF centroid routing node.
message ANNIvfPartitionExecProto {
VectorQueryProto query = 1;
lance.datafusion.TableIdentifier table = 2;
repeated string index_uuids = 3;
}
lance-artifact/protos/encodings_v2_0.proto
+347
View File
@@ -0,0 +1,347 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright The Lance Authors
syntax = "proto3";
package lance.encodings;
import "google/protobuf/empty.proto";
// This file contains a specification for encodings that can be used
// to store and load Arrow data into a Lance file for the 2.0 format. It
// has been superseded by encodings21.proto which is used for the 2.1 format.
//
// # Types
//
// This file assumes the user wants to load data into Arrow arrays and
// explains how to map Arrow arrays into Lance files. Encodings are divided
// into "array encoding" (which maps to an Arrow array and may contain multiple
// buffers) and "buffer encoding" (which encodes a single buffer of data).
//
// # Encoding Tree
//
// Most encodings are layered on top of each other. These form a tree of
// encodings with a single root node. To encode an array you will typically
// start with the root node and then take the output from that root encoding
// and feed it into child encodings. The decoding process works in reverse.
//
// # Multi-column Encodings
//
// Some Arrow arrays will map to more than one column of Lance data. For
// example, struct arrays and list arrays. This file only contains encodings
// for a single column. However, it does describe how multi-column arrays can
// be encoded.
// A pointer to a buffer in a Lance file
//
// A writer can place a buffer in three different locations. The buffer
// can go in the data page, in the column metadata, or in the file metadata.
// The writer is free to choose whatever is most appropriate (for example, a dictionary
// that is shared across all pages in a column will probably go in the column
// metadata). This specification does not dictate where the buffer should go.
message Buffer {
// The index of the buffer in the collection of buffers
uint32 buffer_index = 1;
// The collection holding the buffer
enum BufferType {
// The buffer is stored in the data page itself
page = 0;
// The buffer is stored in the column metadata
column = 1;
// The buffer is stored in the file metadata
file = 2;
};
BufferType buffer_type = 2;
}
// An encoding that adds nullability to another array encoding
//
// This can wrap any array encoding and add nullability information
message Nullable {
message NoNull {
ArrayEncoding values = 1;
}
message AllNull {}
message SomeNull {
ArrayEncoding validity = 1;
ArrayEncoding values = 2;
}
oneof nullability {
// The array has no nulls and there is a single buffer needed
NoNull no_nulls = 1;
// The array may have nulls and we need two buffers
SomeNull some_nulls = 2;
// All values are null (no buffers needed)
AllNull all_nulls = 3;
}
}
// An array encoding for variable-length list fields
message List {
// An array containing the offsets into an items array.
//
// This array will have num_rows items and will never
// have nulls.
//
// If the list at index i is not null then offsets[i] will
// contain `base + len(list)` where `base` is defined as:
// i == 0: 0
// i > 0: (offsets[i-1] % null_offset_adjustment)
//
// To help understand we can consider the following example list:
// [ [A, B], null, [], [C, D, E] ]
//
// The offsets will be [2, ?, 2, 5]
//
// If the incoming list at index i IS null then offsets[i] will
// contain `base + len(list) + null_offset_adjustment` where `base`
// is defined the same as above.
//
// To complete the above example let's assume that `null_offset_adjustment`
// is 7. Then the offsets will be [2, 9, 2, 5]
//
// If there are no nulls then the offsets we write here are exactly the
// same as the offsets in an Arrow list array (except we omit the leading
// 0 which is redundant)
//
// The reason we do this is so that reading a single list at index i only
// requires us to load the indices at i and i-1.
//
// If the offset at index i is greater than `null_offset_adjustment``
// then the list at index i is null.
//
// Otherwise the length of the list is `offsets[i] - base` where
// base is defined the same as above.
//
// Let's consider our example offsets: [2, 9, 2, 5]
//
// We can take any range of lists and determine how many list items are
// referenced by the sublist.
//
// 0..3: [_, 5] -> items 0..5 (base = 0* and end is 5)
// 0..2: [_, 2] -> items 0..2 (base = 0* and end is 2)
// 0..1: [_, 9] -> items 0..2 (base = 0* and end is 9 % 7)
// 1..3: [2, 5] -> items 2..5 (base = 2 and end is 5)
// 1..2: [2, 2] -> items 2..2 (base = 2 and end is 2)
// 2..3: [9, 5] -> items 2..5 (base = 9 % 7 and end is 5)
//
// * When the start of our range is the 0th item the base is always 0 and we only
// need to load a single index from disk to determine the range.
//
// The data type of the offsets array is flexible and does not need
// to match the data type of the destination array. Please note that the offsets
// array is very likely to be efficiently encoded by bit packing deltas.
ArrayEncoding offsets = 1;
// If a list is null then we add this value to the offset
//
// This value must be greater than the length of the items so that
// (offset + null_offset_adjustment) is never used by a non-null list.
//
// Note that this value cannot be equal to the length of the items
// because then a page with a single list would store [ X ] and we
// couldn't know if that is a null list or a list with X items.
//
// Therefore, the best choice for this value is 1 + # of items.
// Choosing this will maximize the bit packing that we can apply to the offsets.
uint64 null_offset_adjustment = 2;
// How many items are referenced by these offsets. This is needed in
// order to determine which items pages map to this offsets page.
uint64 num_items = 3;
}
// An array encoding for fixed-size list fields
message FixedSizeList {
/// The number of items in each list
uint32 dimension = 1;
/// True if the list is nullable
bool has_validity = 3;
/// The items in the list
ArrayEncoding items = 2;
}
message Compression {
string scheme = 1;
optional int32 level = 2;
}
// Fixed width items placed contiguously in a buffer
message Flat {
// the number of bits per value, must be greater than 0, does
// not need to be a multiple of 8
uint64 bits_per_value = 1;
// the buffer of values
Buffer buffer = 2;
// The Compression message can specify the compression scheme (e.g. zstd) and any
// other information that is needed for decompression.
//
// If this array is compressed then the bits_per_value refers to the uncompressed
// data.
Compression compression = 3;
}
// Compression algorithm where all values have a constant value
message Constant {
// The value (TODO: define encoding for literals?)
bytes value = 1;
}
// Items are bitpacked in a buffer
message Bitpacked {
// the number of bits used for a value in the buffer
uint64 compressed_bits_per_value = 1;
// the number of bits of the uncompressed value. e.g. for a u32, this will be 32
uint64 uncompressed_bits_per_value = 2;
// The items in the list
Buffer buffer = 3;
// Whether or not a sign bit is included in the bitpacked value
bool signed = 4;
}
// Items are bitpacked in a buffer
message BitpackedForNonNeg {
// the number of bits used for a value in the buffer
uint64 compressed_bits_per_value = 1;
// the number of bits of the uncompressed value. e.g. for a u32, this will be 32
uint64 uncompressed_bits_per_value = 2;
// The items in the list
Buffer buffer = 3;
}
// Opaque bitpacking variant where the bits per value are stored inline in the chunks themselves
message InlineBitpacking {
// the number of bits of the uncompressed value. e.g. for a u32, this will be 32
uint64 uncompressed_bits_per_value = 2;
}
// Transparent bitpacking variant where the number of bits per value is fixed through the whole buffer
message OutOfLineBitpacking {
// the number of bits of the uncompressed value. e.g. for a u32, this will be 32
uint64 uncompressed_bits_per_value = 2;
// The number of compressed bits per value, fixed across the entire buffer
uint64 compressed_bits_per_value = 3;
}
// An array encoding for shredded structs that will never be null
//
// There is no actual data in this column.
//
// TODO: Struct validity bitmaps will be placed here.
message SimpleStruct {}
// An array encoding for binary fields
message Binary {
ArrayEncoding indices = 1;
ArrayEncoding bytes = 2;
uint64 null_adjustment = 3;
}
message Variable {
uint32 bits_per_offset = 1;
}
message Fsst {
ArrayEncoding binary = 1;
bytes symbol_table = 2;
}
// An array encoding for dictionary-encoded fields
message Dictionary {
ArrayEncoding indices = 1;
ArrayEncoding items = 2;
uint32 num_dictionary_items = 3;
}
message PackedStruct {
repeated ArrayEncoding inner = 1;
Buffer buffer = 2;
}
message PackedStructFixedWidthMiniBlock {
ArrayEncoding Flat = 1;
repeated uint32 bits_per_values = 2;
}
message FixedSizeBinary {
ArrayEncoding bytes = 1;
uint32 byte_width = 2;
}
message Block {
string scheme = 1;
}
// Run-Length Encoding for miniblock format
message Rle {
// Number of bits per value (8, 16, 32, 64, or 128)
uint64 bits_per_value = 1;
}
// Byte Stream Split encoding for floating point values
message ByteStreamSplit {
// Number of bits per value (32 for float, 64 for double)
uint64 bits_per_value = 1;
}
// General miniblock encoding - wraps another miniblock encoding with compression
message GeneralMiniBlock {
// The inner miniblock encoding (e.g., Rle, Bitpacked, etc.)
ArrayEncoding inner = 1;
// The compression scheme to apply to the miniblock buffers
Compression compression = 2;
}
// Encodings that decode into an Arrow array
message ArrayEncoding {
oneof array_encoding {
Flat flat = 1;
Nullable nullable = 2;
FixedSizeList fixed_size_list = 3;
List list = 4;
SimpleStruct struct = 5;
Binary binary = 6;
Dictionary dictionary = 7;
Fsst fsst = 8;
PackedStruct packed_struct = 9;
Bitpacked bitpacked = 10;
FixedSizeBinary fixed_size_binary = 11;
BitpackedForNonNeg bitpacked_for_non_neg = 12;
Constant constant = 13;
InlineBitpacking inline_bitpacking = 14;
OutOfLineBitpacking out_of_line_bitpacking = 15;
Variable variable = 16;
PackedStructFixedWidthMiniBlock packed_struct_fixed_width_mini_block = 17;
Block block = 18;
Rle rle = 19;
GeneralMiniBlock general_mini_block = 20;
ByteStreamSplit byte_stream_split = 21;
}
}
// Wraps a column with a zone map index that can be used
// to apply pushdown filters
message ZoneIndex {
uint32 rows_per_zone = 1;
Buffer zone_map_buffer = 2;
ColumnEncoding inner = 3;
}
// Marks a column as blob data. It will contain a packed struct
// with fields position and size (u64)
message Blob {
ColumnEncoding inner = 1;
}
// Encodings that describe a column of values
message ColumnEncoding {
oneof column_encoding {
// No special encoding, just column values
google.protobuf.Empty values = 1;
ZoneIndex zone_index = 2;
Blob blob = 3;
}
}
lance-artifact/protos/encodings_v2_1.proto
+635
View File
@@ -0,0 +1,635 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright The Lance Authors
syntax = "proto3";
package lance.encodings21;
// This file contains a specification for encodings that can be used
// to store and load Arrow data into a Lance file for the 2.1 format.
//
// # Types
//
// This file assumes the user wants to load data into Arrow arrays and
// explains how to map Arrow arrays into Lance files. Encodings are divided
// into "structural encodings" (which are used to encode the structure of the
// data such as any list or struct layers) and "compressive encodings" (which
// are used to compress the actual data values).
//
// # Standardized Interpretation of Counting Terms
//
// When working with 2.1 encodings we have a number of different "counting terms" and it can be
// difficult to understand what we mean when we are talking about a "number of values". Here is
// a standard interpretation of these terms:
//
// To understand these definitions consider a data type FIXED_SIZE_LIST<LIST<INT32>>.
//
// A "value" is an abstract term when we aren't being specific.
//
// - num_rows: This is the highest level counting term. A single row includes everything in the
// fixed size list. This is what the user asks for when they asks for a range of rows.
// - num_elements: The number of elements is the number of rows multiplied by the dimension of any
// fixed size list wrappers. This is what you get when you flatten the FSL layer and
// is the starting point for structural encoding. Note that an element can be a list
// value or a single primitive value.
// - num_items: The number of items is the number of values in the repetition and definition vectors
// after everything has been flattened.
// - num_visible_items: The number of visible items is the number of items after invisible items
// have been removed. Invisible items are rep/def levels that don't correspond to an
// actual value.
// # Structural Encodings
//
// The following message are used to describe the structural encoding of the
// data. In this document, we refer to these structural encodings as layouts.
// Repetition and definition levels are described in more detail elsewhere. As we peel through
// the structure of an array we will encounter layers of struct and list. Each of these layers
// potentially adds a new level to the repetition and definition levels. This message describes
// the meaning of each layer.
enum RepDefLayer {
// Should never be used, included for debugging purporses and general protobuf best practice
REPDEF_UNSPECIFIED = 0;
// All values are valid (can be primitive or struct)
REPDEF_ALL_VALID_ITEM = 1;
// All list values are valid
REPDEF_ALL_VALID_LIST = 2;
// There are one or more null items (can be primitive or struct)
REPDEF_NULLABLE_ITEM = 3;
// A list layer with null lists but no empty lists
REPDEF_NULLABLE_LIST = 4;
// A list layer with empty lists but no null lists
REPDEF_EMPTYABLE_LIST = 5;
// A list layer with both empty lists and null lists
REPDEF_NULL_AND_EMPTY_LIST = 6;
}
// A layout used for pages where the data is small
//
// In this case we can fit many values into a single disk sector and transposing buffers is
// expensive. As a result, we do not transpose the buffers but compress the data into small
// chunks (called mini blocks) which are roughly the size of a disk sector.
//
// The end result is a small amount of read amplification (since we must read an entire page
// at a time) but we have more flexibility in compression and do less work per value when
// compressing and decompressing in bulk.
message MiniBlockLayout {
// Description of the compression of repetition levels (e.g. how many bits per rep)
//
// Optional, if there is no repetition then this field is not present
CompressiveEncoding rep_compression = 1;
// Description of the compression of definition levels (e.g. how many bits per def)
//
// Optional, if there is no definition then this field is not present
CompressiveEncoding def_compression = 2;
// Description of the compression of values
CompressiveEncoding value_compression = 3;
// Description of the compression of the dictionary data
//
// Optional, if there is no dictionary then this field is not present
CompressiveEncoding dictionary = 4;
// Number of items in the dictionary
uint64 num_dictionary_items = 5;
// The meaning of each repdef layer, used to interpret repdef buffers correctly
repeated RepDefLayer layers = 6;
// The number of buffers in each mini-block, this is determined by the compression and does
// NOT include the repetition or definition buffers (the presence of these buffers can be determined
// by looking at the rep_compression and def_compression fields)
uint64 num_buffers = 7;
// The depth of the repetition index.
//
// If there is repetition then the depth must be at least 1. If there are many layers
// of repetition then deeper repetition indices will support deeper nested random access. For
// example, given 5 layers of repetition then the repetition index depth must be at least
// 3 to support access like `rows[50][17][3]`.
//
// We require `repetition_index_depth + 1` u64 values per mini-block to store the repetition
// index if the `repetition_index_depth` is greater than 0. The +1 is because we need to store
// the number of "leftover items" at the end of the chunk. Otherwise, we wouldn't have any way
// to know if the final item in a chunk is valid or not.
uint32 repetition_index_depth = 8;
// The page already records how many rows are in the page. For mini-block we also need to know how
// many "items" are in the page. A row and an item are the same thing unless the page has lists.
uint64 num_items = 9;
// Since Lance 2.2, miniblocks have larger chunk sizes (>= 64KB)
bool has_large_chunk = 10;
}
// A layout used for pages where the data is large
//
// In this case the cost of transposing the data is relatively small (compared to the cost of writing the data)
// and so we just zip the buffers together
message FullZipLayout {
// The number of bits of repetition info (0 if there is no repetition)
uint32 bits_rep = 1;
// The number of bits of definition info (0 if there is no definition)
uint32 bits_def = 2;
// The number of bits of value info
//
// Note: we use bits here (and not bytes) for consistency with other encodings. However, in practice,
// there is never a reason to use a bits per value that is not a multiple of 8. The complexity is not
// worth the small savings in space since this encoding is typically used with large values already.
oneof details {
// If this is a fixed width block then we need to have a fixed number of bits per value
uint32 bits_per_value = 3;
// If this is a variable width block then we need to have a fixed number of bits per offset
uint32 bits_per_offset = 4;
}
// The number of items in the page
uint32 num_items = 5;
// The number of visible items in the page
uint32 num_visible_items = 6;
// Description of the compression of values
CompressiveEncoding value_compression = 7;
// The meaning of each repdef layer, used to interpret repdef buffers correctly
repeated RepDefLayer layers = 8;
}
// A layout used for sparse flat or nested pages where Arrow structure is represented directly
// in layer-local slot domains instead of as dense repetition / definition events.
//
// Structural layers are ordered from outer-most to inner-most. Values remain mini-block
// compressed and are split into independently readable chunks.
message SparseLayout {
// Description of the compression of values.
CompressiveEncoding value_compression = 1;
// Number of value buffers in each mini-block chunk. This does not include structural buffers.
uint64 num_buffers = 2;
// Number of entries in the equivalent dense repetition / definition stream. This equals
// num_visible_items plus one structural placeholder for every list slot without children.
// Null leaf slots count as visible items because they still occupy positions in Arrow's
// leaf value buffer. For example, a nullable primitive with 100 slots, 30 of them null,
// has num_items = num_visible_items = 100.
uint64 num_items = 3;
// Number of leaf value slots encoded in the value chunks, including null leaf slots.
uint64 num_visible_items = 4;
// If true, chunk-local value buffer sizes use u32. Otherwise they use u16.
bool has_large_chunk = 5;
// Structural layers ordered from outer-most to inner-most. This may be empty for a flat,
// non-nullable leaf page whose scheduling domain equals num_visible_items.
repeated SparseStructuralLayer structural_layers = 6;
}
// A domain is a layer-local integer coordinate space [0, num_slots). A slot is one
// element in that space. The outer-most domain is the page's top-level rows; each
// layer's child domain is the next layer's parent domain, and the terminal child
// domain contains num_visible_items leaf value slots.
message SparseStructuralLayer {
// Exactly one layer kind is required.
oneof layer {
SparseValidityLayer validity = 1;
SparseListLayer list = 2;
SparseFixedSizeListLayer fixed_size_list = 3;
}
}
message SparseValidityLayer {
// Number of nullable item or struct slots in this layer's parent and child domain.
uint64 num_slots = 1;
// Validity for the slots in this layer.
SparseValiditySet validity = 2;
}
message SparseListLayer {
// Number of list, large-list, or map slots in this layer's parent domain.
uint64 num_slots = 1;
// Number of slots in this layer's child domain.
uint64 num_child_slots = 2;
// Non-empty parent slots. Valid parent slots absent from this set are empty lists.
SparsePositionSet non_empty_positions = 3;
// Positive child counts corresponding one-for-one with non_empty_positions.
SparseCountSet counts = 4;
// Validity for the parent slots in this layer.
SparseValiditySet validity = 5;
}
message SparseFixedSizeListLayer {
// Number of fixed-size-list slots in this layer's parent domain.
uint64 num_slots = 1;
// Number of children per parent slot. The child domain has num_slots * dimension slots.
uint64 dimension = 2;
// Validity for the parent slots in this layer.
SparseValiditySet validity = 3;
}
message SparseValiditySet {
enum Meaning {
SPARSE_VALIDITY_UNSPECIFIED = 0;
// Stored positions are null; all other positions are valid.
SPARSE_VALIDITY_NULL_POSITIONS = 1;
// Stored positions are valid; all other positions are null.
SPARSE_VALIDITY_VALID_POSITIONS = 2;
}
Meaning meaning = 1;
SparsePositionSet positions = 2;
}
message SparsePositionEmpty {}
message SparsePositionAll {}
message SparsePositionRange {
uint64 start = 1;
uint64 length = 2;
}
message SparsePositionSet {
oneof positions {
// Delta-compressed u64 positions. Cardinality is num_positions.
CompressiveEncoding explicit = 1;
// One contiguous, non-empty range.
SparsePositionRange range = 2;
// Every position in the domain.
SparsePositionAll all = 3;
// No positions in the domain.
SparsePositionEmpty empty = 4;
}
// Semantic cardinality of this set.
uint64 num_positions = 5;
}
message SparseCountEmpty {}
message SparseCountConstant {
// Child count shared by every non-empty list slot.
uint64 value = 1;
}
message SparseCountSet {
oneof counts {
// Compressed u64 child counts. Cardinality comes from the containing position set.
CompressiveEncoding explicit = 1;
// One positive child count shared by every non-empty list slot.
SparseCountConstant constant = 2;
// No counts; valid only when there are no non-empty list slots.
SparseCountEmpty empty = 3;
}
}
// A layout used for pages where all (visible) values are the same scalar value.
//
// This generalizes the prior AllNullLayout semantics for file_version >= 2.2.
//
// There may be buffers of repetition and definition information if required in order
// to interpret what kind of nulls are present / which items are visible.
message ConstantLayout {
// The meaning of each repdef layer, used to interpret repdef buffers correctly
repeated RepDefLayer layers = 5;
// Inline fixed-width scalar value bytes.
//
// This MUST only be used for types where a single non-null element is represented by a single
// fixed-width Arrow value buffer (i.e. no offsets buffer, no child data).
//
// Constraints:
// - MUST be absent for an all-null page
// - MUST be <= 32 bytes if present
optional bytes inline_value = 6;
// Optional compression algorithm used for the repetition buffer.
// If absent, repetition levels are stored as raw u16 values.
CompressiveEncoding rep_compression = 7;
// Optional compression algorithm used for the definition buffer.
// If absent, definition levels are stored as raw u16 values.
CompressiveEncoding def_compression = 8;
// Number of values in repetition buffer after decompression.
uint64 num_rep_values = 9;
// Number of values in definition buffer after decompression.
uint64 num_def_values = 10;
}
// A layout where large binary data is encoded externally and only
// the descriptions (position + size) are placed in the page
//
// Repdef information is stored in the descriptions. A description with a size of
// 0 and a position of 0 is an empty value. A description with a size of 0 and a
// non-zero position is a null value and the position is the repdef value.
message BlobLayout {
// The inner layout used to store the descriptions
PageLayout inner_layout = 1;
// The meaning of each repdef layer, used to interpret repdef buffers correctly
//
// The inner layout's repdef layers will always be 1 all valid item layer
repeated RepDefLayer layers = 2;
}
// Describes the structural encoding of a page
message PageLayout {
oneof layout {
// A layout used for pages where the data is small
MiniBlockLayout mini_block_layout = 1;
// A layout used for pages where all (visible) values are the same scalar value or null.
ConstantLayout constant_layout = 2;
// A layout used for pages where the data is large
FullZipLayout full_zip_layout = 3;
// A layout where large binary data is encoded externally
// and only the descriptions are put in the page
BlobLayout blob_layout = 4;
// A sparse structural layout. This variant requires file version 2.3 or later.
SparseLayout sparse_layout = 5;
}
}
// # Compressive Encodings
//
// These encodings describe how an array is compressed. An encoding may split an
// array into multiple buffers. The buffers can then be compressed further (and split
// into yet more buffers). The entire process forms a tree of encodings with the root
// of the tree being the initial array and the leaves being the final compressed buffers.
//
// # Data blocks and buffers
//
// Data blocks are a simplified version of arrays and represent a collection of buffers grouped
// with some kind of interpretation. Data blocks are the input and output of compressive encodings.
// There are different kinds of data blocks:
// - Fixed width data blocks (e.g. u8, u16, ...)
// - Variable width data blocks (e.g. strings, binary)
// - Struct data blocks (note: this is for packed structs, normal structs are encoded in the structural encoding)
//
// In addition, leaf encodings may output "buffers". These are fully compressed buffers of data that
// are stored in the page and no longer compressed.
enum CompressionScheme {
COMPRESSION_ALGORITHM_UNSPECIFIED = 0;
COMPRESSION_ALGORITHM_LZ4 = 1;
COMPRESSION_ALGORITHM_ZSTD = 2;
}
// Compression applied to a single buffer of data
//
// A buffer is the leaf of the compression tree. Unlike data blocks, which can
// be further compressed with a variety of techniques, a buffer cannot be understood
// in any particular way.
//
// A general compression scheme may be applied to a buffer. This is something like
// zstd, lz4, etc. The entire buffer is compressed as a single unit. If this happens
// then any parent encoding becomes opaque, even if it would normally be transparent.
//
// This is a leaf, no further compression is applied to the data.
message BufferCompression {
// A general compression scheme to apply to the buffer
CompressionScheme scheme = 1;
// The compression level
//
// Optional, if not present a scheme-specific default value will be used.
//
// Interpretation of this value depends on the compression scheme. Generally, larger
// values indicate more compression at the expense of more CPU time.
optional int32 level = 2;
}
// Fixed width items placed contiguously in a single buffer
//
// This is a leaf encoding, there is no compression applied to the data.
//
// This is a transparent encoding by definition.
//
// The input is a fixed-width data block.
// The output is a single buffer.
message Flat {
// the number of bits per value, must be greater than 0, does
// not need to be a multiple of 8
uint64 bits_per_value = 1;
// The compression applied to the data
optional BufferCompression data = 2;
}
// Variable width items have the values stored in one buffer and the
// offsets are output as a data block that may be further compressed.
//
// This is a partial leaf encoding. Values are not compressed but
// the offsets may be further compressed.
//
// This is a transparent encoding by definition.
//
// The input is a variable-width data block.
// The output is a single fixed-width data block (the offsets) and
// a single buffer (the values)
message Variable {
// Describes how the offsets data block is compressed
CompressiveEncoding offsets = 1;
// The compression applied to the values
optional BufferCompression values = 2;
}
// Compression algorithm where all values have a constant value (encoded in the description)
//
// This is a leaf encoding, there is no compression applied to the data.
//
// The input can be any kind of data block.
// There is no output.
message Constant {
// The value (TODO: define encoding for literals?)
optional bytes value = 1;
}
// A compression scheme in which a single fixed-width block is "packed" into
// a smaller fixed-width block values where each value has fewer bits.
//
// This is typically done by throwing away the most significant bits of each value when
// those bits are all the same.
//
// In this scheme the number of bits per value is fixed across the entire buffer and stored
// in this message.
//
// This is a transparent encoding.
//
// The input is a fixed-width data block.
// The output is a single fixed-width data block.
message OutOfLineBitpacking {
// the number of bits of the uncompressed value. e.g. for a u32, this will be 32
uint64 uncompressed_bits_per_value = 1;
// The compression used to store the bitpacked values data block
CompressiveEncoding values = 3;
}
// Bitpacking variant where the bits per value are stored inline in the chunks themselves
//
// This variation of bitpacking allows for the number of bits per value to change throughout the
// buffer, which makes the compression more robust to outliers.
//
// This is an opaque encoding.
//
// The input is a fixed-width data block.
// The output is a single buffer.
message InlineBitpacking {
// the number of bits of the uncompressed value. e.g. for a u32, this will be 32
uint64 uncompressed_bits_per_value = 1;
// The compression applied to the values
optional BufferCompression values = 2;
}
// A compression scheme for variable-width data
//
// A small dictionary (referred to as a "symbol table") is used to compress the values.
// In this scheme there is a single symbol table for the entire page and it is stored in the
// encoding description itself.
//
// This is a transparent encoding.
//
// The input is a variable-width data block.
// The output is a single variable-width data block.
message Fsst {
// The FSST symbol table
bytes symbol_table = 1;
// The compression used to store the compressed values data block
CompressiveEncoding values = 2;
}
// A compression scheme where common values are stored in a dictionary and the values are
// encoded as indices into the dictionary.
//
// This is an opaque encoding unless the dictionary is considered metadata.
//
// The input is a any kind of data block.
// There are two outputs:
// - A data block of the same kind as the input (the dictionary)
// - A fixed-width data block containing the indices into the dictionary.
message Dictionary {
// The compression used to store the indices data block
CompressiveEncoding indices = 1;
// The compression used to store the dictionary items data block
CompressiveEncoding items = 2;
// The number of items in the dictionary
uint32 num_dictionary_items = 3;
}
// A compression scheme where runs of common values are encoded as a single value and a count
//
// This is an opaque encoding unless the run lengths are considered metadata.
//
// The input is a single data block of any kind.
// There are two outputs:
// - A data block of the same kind as the input (the run values)
// - A fixed-width data block containing the lengths of the runs
message Rle {
// The compression used to store the run values data block
CompressiveEncoding values = 1;
// The compression used to store the run lengths data block
CompressiveEncoding run_lengths = 2;
}
// Converts a fixed-size-list of values into a flattened list of values
//
// This encoding does not actually compress the data, it just flattens out the FSL layers.
//
// This is a transparent encoding.
//
// The input is a single block of fixed-width data (with a wide width and few items)
// The output is a single block of fixed-width data (with a narrow width and many items)
message FixedSizeList {
// The number of items in this layer of FSL
uint64 items_per_value = 1;
// Whether or not there is a validity buffer
bool has_validity = 3;
// The compression used to store the flattened values data block
CompressiveEncoding values = 2;
}
// Packs a struct containing only fixed-width children into a single fixed-width data block
//
// The children are concatenated row by row and stored as a single fixed-width buffer. This is
// the legacy packed struct representation and remains available for backwards compatibility.
message PackedStruct {
// The number of bits contributed by each child field in the packed row
repeated uint64 bits_per_value = 1;
// The compression used to store the packed fixed-width values
CompressiveEncoding values = 2;
}
// Variable-width packed struct encoding (2.2 extension)
//
// Each child value is compressed independently before being transposed into
// a row-major layout. This preserves per-field compression boundaries at the
// cost of disabling mini-block compression. Readers must prefer this field
// when present and fall back to the legacy encoding otherwise.
message VariablePackedStruct {
// Per-field encoding metadata in struct order
repeated FieldEncoding fields = 1;
// Encoding description for a single child field
message FieldEncoding {
// Compression applied to individual field values before transposition
CompressiveEncoding value = 1;
oneof layout {
// Bit width of each compressed value (when fixed width)
uint64 bits_per_value = 2;
// Bit width of the length prefix for variable-width compressed values
uint64 bits_per_length = 3;
}
}
}
// A compression scheme that wraps the underlying data with general compression
//
// Note: The application of wrapped compression will depend on the layout of the data.
// If we apply it to mini-block data then we compress entire mini-blocks. If we apply
// it to full-zip data then we compress each value individually.
//
// Note: Wrapped compression is somewhat unique at the moment as it is applied to the
// output of the inner encoding and not the input like all other compressive encodings.
//
// Note: General compression can usually be applied in two spots. We can apply
// it to individual buffers or we can apply it here, to the entire array.
//
// For example, let's say we are storing mini-blocks of strings and we are using
// FSST and bitpacking the offsets. We have something like this...
//
// WRAPPED(†3) -> FSST -> VARIABLE -(offsets)-> INLINE_BITPACKING -(data)-> FLAT -> BUFFER (†1)
// -(data)-> BUFFER (†2)
//
// General compression can be applied at †1, †2, or †3 (or any combination of these).
//
// If we apply it at †1 then we apply it just to the bitpacked offsets
// If we apply it at †2 then we apply it just to the FSST compressed data
// If we apply it at †3 then we apply it to the entire mini-block (both offsets and data)
//
// The input is a single data block of any kind.
// The output is a single data block of the same kind as the input.
message General {
// The compression to apply to the values
BufferCompression compression = 1;
// The compression used to store the output data block
CompressiveEncoding values = 3;
}
// A compression scheme where fixed-width values are transposed into a series of byte streams
//
// This is commonly used for floating point values where the upper bits (the mantissa) have a
// significantly different meaning than the lower bits. By splitting the values into byte streams
// we group the mantissa bits together and the exponent bits together. The end result is typically
// more compressible.
//
// Note that this encoding is mostly useful when combined with other encodings. It does not do any
// compression on its own.
//
// This is an opaque encoding.
//
// The input is a fixed-width data block
// The output is a single fixed-width data block
message ByteStreamSplit {
// The compression used to store the values
CompressiveEncoding values = 1;
}
// An encoding that compresses a data block into buffers
message CompressiveEncoding {
oneof compression {
Flat flat = 1;
Variable variable = 2;
Constant constant = 3;
OutOfLineBitpacking out_of_line_bitpacking = 4;
InlineBitpacking inline_bitpacking = 5;
Fsst fsst = 6;
Dictionary dictionary = 7;
Rle rle = 8;
ByteStreamSplit byte_stream_split = 9;
General general = 10;
FixedSizeList fixed_size_list = 11;
PackedStruct packed_struct = 12;
VariablePackedStruct variable_packed_struct = 13;
}
}
lance-artifact/protos/file.proto
+207
View File
@@ -0,0 +1,207 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright The Lance Authors
syntax = "proto3";
package lance.file;
// A file descriptor that describes the contents of a Lance file
message FileDescriptor {
// The schema of the file
Schema schema = 1;
// The number of rows in the file
uint64 length = 2;
}
// A schema which describes the data type of each of the columns
message Schema {
// All fields in this file, including the nested fields.
repeated lance.file.Field fields = 1;
// Schema metadata.
map<string, bytes> metadata = 5;
}
// Metadata of one Lance file.
message Metadata {
// 4 was used for StatisticsMetadata in the past, but has been moved to
// prevent a bug in older readers.
reserved 4;
// Position of the manifest in the file. If it is zero, the manifest is stored
// externally.
uint64 manifest_position = 1;
// Logical offsets of each chunk group, i.e., number of the rows in each
// chunk.
repeated int32 batch_offsets = 2;
// The file position that page table is stored.
//
// A page table is a matrix of N x M x 2, where N = num_fields, and M =
// num_batches. Each cell in the table is a pair of <position:int64,
// length:int64> of the page. Both position and length are int64 values. The
// <position, length> of all the pages in the same column are then
// contiguously stored.
//
// Every field that is a part of the file will have a run in the page table.
// This includes struct columns, which will have a run of length 0 since
// they don't store any actual data.
//
// For example, for the column 5 and batch 4, we have:
// ```text
// position = page_table[5][4][0];
// length = page_table[5][4][1];
// ```
uint64 page_table_position = 3;
message StatisticsMetadata {
// The schema of the statistics.
//
// This might be empty, meaning there are no statistics. It also might not
// contain statistics for every field.
repeated Field schema = 1;
// The field ids of the statistics leaf fields.
//
// This plays a similar role to the `fields` field in the DataFile message.
// Each of these field ids corresponds to a field in the stats_schema. There
// is one per column in the stats page table.
repeated int32 fields = 2;
// The file position of the statistics page table
//
// The page table is a matrix of N x 2, where N = length of stats_fields.
// This is the same layout as the main page table, except there is always
// only one batch.
//
// For example, to get the stats column 5, we have:
// ```text
// position = stats_page_table[5][0];
// length = stats_page_table[5][1];
// ```
uint64 page_table_position = 3;
}
StatisticsMetadata statistics = 5;
} // Metadata
// Supported encodings.
enum Encoding {
// Invalid encoding.
NONE = 0;
// Plain encoding.
PLAIN = 1;
// Var-length binary encoding.
VAR_BINARY = 2;
// Dictionary encoding.
DICTIONARY = 3;
// Run-length encoding.
RLE = 4;
}
// Dictionary field metadata
message Dictionary {
/// The file offset for storing the dictionary value.
/// It is only valid if encoding is DICTIONARY.
///
/// The logic type presents the value type of the column, i.e., string value.
int64 offset = 1;
/// The length of dictionary values.
int64 length = 2;
}
// Field metadata for a column.
message Field {
enum Type {
PARENT = 0;
REPEATED = 1;
LEAF = 2;
}
Type type = 1;
// Fully qualified name.
string name = 2;
/// Field Id.
///
/// See the comment in `DataFile.fields` for how field ids are assigned.
int32 id = 3;
/// Parent Field ID. If not set, this is a top-level column.
int32 parent_id = 4;
// Logical types, support parameterized Arrow Type.
//
// PARENT types will always have logical type "struct".
//
// REPEATED types may have logical types:
// * "list"
// * "large_list"
// * "list.struct"
// * "large_list.struct"
// The final two are used if the list values are structs, and therefore the
// field is both implicitly REPEATED and PARENT.
//
// LEAF types may have logical types:
// * "null"
// * "bool"
// * "int8" / "uint8"
// * "int16" / "uint16"
// * "int32" / "uint32"
// * "int64" / "uint64"
// * "halffloat" / "float" / "double"
// * "string" / "large_string"
// * "binary" / "large_binary"
// * "date32:day"
// * "date64:ms"
// * "decimal:128:{precision}:{scale}" / "decimal:256:{precision}:{scale}"
// * "time:{unit}" / "timestamp:{unit}" / "duration:{unit}", where unit is
// "s", "ms", "us", "ns"
// * "dict:{value_type}:{index_type}:false"
string logical_type = 5;
// If this field is nullable.
bool nullable = 6;
// optional field metadata (e.g. extension type name/parameters)
map<string, bytes> metadata = 10;
bool unenforced_primary_key = 12;
// Position of this field in the primary key (1-based).
// 0 means the field is part of the primary key but uses schema field id for ordering.
// When set to a positive value, primary key fields are ordered by this position.
uint32 unenforced_primary_key_position = 13;
// Reserved for future use. Use unenforced_clustering_key_position instead.
bool unenforced_clustering_key = 14;
// Position of this field in the clustering key (1-based).
// 0 means the field is not part of the clustering key.
uint32 unenforced_clustering_key_position = 15;
// DEPRECATED ----------------------------------------------------------------
// Deprecated: Only used in V1 file format. V2 uses variable encodings defined
// per page.
//
// The global encoding to use for this field.
Encoding encoding = 7;
// Deprecated: Only used in V1 file format. V2 dynamically chooses when to
// do dictionary encoding and keeps the dictionary in the data files.
//
// The file offset for storing the dictionary value.
// It is only valid if encoding is DICTIONARY.
//
// The logic type presents the value type of the column, i.e., string value.
Dictionary dictionary = 8;
// Deprecated: optional extension type name, use metadata field
// ARROW:extension:name
string extension_name = 9;
// Field number 11 was previously `string storage_class`.
// Keep it reserved so older manifests remain compatible while new writers
// avoid reusing the slot.
reserved 11;
reserved "storage_class";
}
lance-artifact/protos/file2.proto
+210
View File
@@ -0,0 +1,210 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright The Lance Authors
syntax = "proto3";
package lance.file.v2;
import "google/protobuf/any.proto";
import "google/protobuf/empty.proto";
// # Lance v2.X File Format
//
// The Lance file format is a barebones format for serializing columnar data
// into a file.
//
// * Each Lance file contains between 0 and 4Gi columns
// * Each column contains between 0 and 4Gi pages
// * Each page contains between 0 and 2^64 items
// * Different pages within a column can have different items counts
// * Columns may have up to 2^64 items
// * Different columns within a file can have different item counts
//
// The Lance file format does not have any notion of a type system or schemas.
// From the perspective of the file format all data is arbitrary buffers of
// bytes with an extensible metadata block to describe the data. It is up to
// the user to interpret these bytes meaningfully.
//
// Data buffers are written to the file first. These data buffers can be
// referenced from three different places in the file:
//
// * Page encodings can reference data buffers. This is the most common way
// that actual data is stored.
// * Column encodings can reference data buffers. For example, a column encoding
// may reference data buffer(s) containing statistics or dictionaries.
// * Finally, the global buffer offset table can reference data buffers. This
// is useful for storing data that is shared across multiple columns.
// This is also useful for global file metadata (e.g. a schema that describes
// the file)
//
// ## File Layout
//
// Note: the number of buffers (BN) is independent of the number of columns (CN)
// and pages.
//
// Buffers often need to be aligned. 64-byte alignment is common when
// working with SIMD operations. 4096-byte alignment is common when
// working with direct I/O. In order to ensure these buffers are aligned
// writers may need to insert padding before the buffers.
//
// If direct I/O is required then most (but not all) fields described
// below must be sector aligned. We have marked these fields with an
// asterisk for clarity. Readers should assume there will be optional
// padding inserted before these fields.
//
// All footer fields are unsigned integers written with little endian
// byte order.
//
// ├──────────────────────────────────┤
// | Data Pages |
// | Data Buffer 0* |
// | ... |
// | Data Buffer BN* |
// ├──────────────────────────────────┤
// | Column Metadatas |
// | |A| Column 0 Metadata* |
// | Column 1 Metadata* |
// | ... |
// | Column CN Metadata* |
// ├──────────────────────────────────┤
// | Column Metadata Offset Table |
// | |B| Column 0 Metadata Position* |
// | Column 0 Metadata Size |
// | ... |
// | Column CN Metadata Position |
// | Column CN Metadata Size |
// ├──────────────────────────────────┤
// | Global Buffers Offset Table |
// | |C| Global Buffer 0 Position* |
// | Global Buffer 0 Size |
// | ... |
// | Global Buffer GN Position |
// | Global Buffer GN Size |
// ├──────────────────────────────────┤
// | Footer |
// | A u64: Offset to column meta 0 |
// | B u64: Offset to CMO table |
// | C u64: Offset to GBO table |
// | u32: Number of global bufs |
// | u32: Number of columns |
// | u16: Major version |
// | u16: Minor version |
// | "LANC" |
// ├──────────────────────────────────┤
//
// File Layout-End
//
// ## Data Pages
//
// A lot of flexibility is provided in how data is stored. A page's buffers do
// not strictly need to be contiguous on the disk. However, it is recommended
// that buffers within a page be grouped together for best performance.
//
// Data pages should be large. The only time a page should be written to disk
// is when the writer needs to flush the page to disk because it has accumulated
// too much data. Pages are not read in sequential order and if pages are too
// small then the seek overhead (or request overhead) will be problematic. We
// generally advise that pages be at least 8MB or larger.
//
// ## Encodings
//
// Specific encodings are not part of this minimal format. They are provided
// by extensions. Readers and writers should be designed so that encodings can
// be easily added and removed. Ideally, they should allow for this without
// requiring recompilation through some kind of plugin system.
// The deferred encoding is used to place the encoding itself in a different
// part of the file. This is most commonly used to allow encodings to be shared
// across different columns. For example, when writing a file with thousands of
// columns, where many pages have the exact same encoding, it can be useful
// to cut down on the size of the metadata by using a deferred encoding.
message DeferredEncoding {
// Location of the buffer containing the encoding.
//
// * If sharing encodings across columns then this will be in a global buffer
// * If sharing encodings across pages within a column this could be in a
// column metadata buffer.
// * This could also be a page buffer if the encoding is not shared, needs
// to be written before the file ends, and the encoding is too large to load
// unless we first determine the page needs to be read. This combination
// seems unusual.
uint64 buffer_location = 1;
uint64 buffer_length = 2;
}
// The encoding is placed directly in the metadata section
message DirectEncoding {
// The bytes that make up the encoding embedded directly in the metadata
//
// This is the most common approach.
bytes encoding = 1;
}
// An encoding stores the information needed to decode a column or page
//
// For example, it could describe if the page is using bit packing, and how many bits
// there are in each individual value.
//
// At the column level it can be used to wrap columns with dictionaries or statistics.
message Encoding {
oneof location {
// The encoding is stored elsewhere and not part of this protobuf message
DeferredEncoding indirect = 1;
// The encoding is stored within this protobuf message
DirectEncoding direct = 2;
// There is no encoding information
google.protobuf.Empty none = 3;
}
}
// ## Metadata
// Each column has a metadata block that is placed at the end of the file.
// These may be read individually to allow for column projection.
message ColumnMetadata {
// This describes a page of column data.
message Page {
// The file offsets for each of the page buffers
//
// The number of buffers is variable and depends on the encoding. There
// may be zero buffers (e.g. constant encoded data) in which case this
// could be empty.
repeated uint64 buffer_offsets = 1;
// The size (in bytes) of each of the page buffers
//
// This field will have the same length as `buffer_offsets` and
// may be empty.
repeated uint64 buffer_sizes = 2;
// Logical length (e.g. # rows) of the page
uint64 length = 3;
// The encoding used to encode the page
Encoding encoding = 4;
// The priority of the page
//
// For tabular data this will be the top-level row number of the first row
// in the page (and top-level rows should not split across pages).
uint64 priority = 5;
}
// Encoding information about the column itself. This typically describes
// how to interpret the column metadata buffers. For example, it could
// describe how statistics or dictionaries are stored in the column metadata.
Encoding encoding = 1;
// The pages in the column
repeated Page pages = 2;
// The file offsets of each of the column metadata buffers
//
// There may be zero buffers.
repeated uint64 buffer_offsets = 3;
// The size (in bytes) of each of the column metadata buffers
//
// This field will have the same length as `buffer_offsets` and
// may be empty.
repeated uint64 buffer_sizes = 4;
} // Metadata-End
// ## Where is the rest?
//
// This file format is extremely minimal. It is a building block for
// creating more useful readers and writers and not terribly useful by itself.
// Other protobuf files will describe how this can be extended.
lance-artifact/protos/filtered_read.proto
+99
View File
@@ -0,0 +1,99 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright The Lance Authors
syntax = "proto3";
package lance.datafusion;
import "table_identifier.proto";
message U64Range {
uint64 start = 1;
uint64 end = 2;
}
message ProjectionProto {
repeated int32 field_ids = 1;
bool with_row_id = 2;
bool with_row_addr = 3;
bool with_row_last_updated_at_version = 4;
bool with_row_created_at_version = 5;
BlobHandlingProto blob_handling = 6;
}
message BlobHandlingProto {
oneof mode {
// All blobs read as binary
bool all_binary = 1;
// Blobs as descriptions, other binary as binary (default)
bool blobs_descriptions = 2;
// All binary columns as descriptions
bool all_descriptions = 3;
// Specific blobs read as binary, rest as descriptions (non-blob binary stays binary)
FieldIdSet some_blobs_binary = 4;
// Specific columns as binary, all other binary as descriptions
FieldIdSet some_binary = 5;
}
}
message FieldIdSet {
repeated uint32 field_ids = 1;
}
message FilteredReadThreadingModeProto {
oneof mode {
uint64 one_partition_multiple_threads = 1;
uint64 multiple_partitions = 2;
}
}
// Serializable form of FilteredReadOptions.
message FilteredReadOptionsProto {
optional U64Range scan_range_before_filter = 1;
optional U64Range scan_range_after_filter = 2;
bool with_deleted_rows = 3;
optional uint32 batch_size = 4;
optional uint64 fragment_readahead = 5;
repeated uint64 fragment_ids = 6;
ProjectionProto projection = 7;
optional bytes refine_filter_substrait = 8;
optional bytes full_filter_substrait = 9;
FilteredReadThreadingModeProto threading_mode = 10;
optional uint64 io_buffer_size_bytes = 11;
// Arrow IPC schema for decoding Substrait filters (may be wider than projection).
optional bytes filter_schema_ipc = 12;
}
// Serializable form of FilteredReadPlan (planned/distributed mode).
// RowAddrTreeMap serialized via its built-in serialize_into/deserialize_from.
// Per-fragment filters are Substrait-encoded and deduplicated.
message FilteredReadPlanProto {
bytes row_addr_tree_map = 1;
optional U64Range scan_range_after_filter = 2;
// Arrow IPC schema for decoding Substrait filters (matches the schema used at encode time).
optional bytes filter_schema_ipc = 3;
// Per-fragment filter mapping. Key is fragment id, value is a list index into
// filter_expressions. Multiple fragments can share the same list index when
// they have the same filter, avoiding duplicate Substrait encoding.
map<uint32, uint32> fragment_filter_ids = 4;
// Deduplicated Substrait-encoded filter expressions. Each entry is referenced
// by one or more values in fragment_filter_ids.
repeated bytes filter_expressions = 5;
}
// Top-level wrapper for FilteredReadExec serialization.
message FilteredReadExecProto {
TableIdentifier table = 1;
FilteredReadOptionsProto options = 2;
// FilteredRead has two modes
// Plan-then-execute (distributed): The planner creates a FilteredReadPlan and sends it to a remote executor.
// Plan-and-execute (local): The executor creates the plan itself at execution time.
optional FilteredReadPlanProto plan = 3;
// Note: FilteredReadExec.index_input (child ExecutionPlan) is NOT serialized here.
// DataFusion's PhysicalExtensionCodec handles child plans automatically: it walks
// the plan tree via children() / with_new_children(), serializes each node, and
// passes deserialized children back as the `inputs` parameter in try_decode.
// This means any ExecutionPlan in the tree (including index_input) must also
// implement try_encode/try_decode in the PhysicalExtensionCodec.
// TODO: implement serialize/deserialize for lance-specific index input ExecutionPlans.
}
lance-artifact/protos/index.proto
+251
View File
@@ -0,0 +1,251 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright The Lance Authors
syntax = "proto3";
package lance.index.pb;
import "google/protobuf/any.proto";
// The type of an index.
enum IndexType {
// Vector index
VECTOR = 0;
}
message Index {
// The unique index name in the dataset.
string name = 1;
// Columns to be used to build the index.
repeated string columns = 2;
// The version of the dataset this index was built from.
uint64 dataset_version = 3;
// The [`IndexType`] of the index.
IndexType index_type = 4;
/// Index implementation details.
oneof implementation {
VectorIndex vector_index = 5;
}
}
message Tensor {
enum DataType {
BFLOAT16 = 0;
FLOAT16 = 1;
FLOAT32 = 2;
FLOAT64 = 3;
UINT8 = 4;
UINT16 = 5;
UINT32 = 6;
UINT64 = 7;
}
DataType data_type = 1;
// Data shape, [dim1, dim2, ...]
repeated uint32 shape = 2;
// Data buffer
bytes data = 3;
}
// Inverted Index File Metadata.
message IVF {
// Centroids of partitions. `dimension * num_partitions` of float32s.
//
// Deprecated, use centroids_tensor instead.
repeated float centroids = 1; // [deprecated = true];
// File offset of each partition.
repeated uint64 offsets = 2;
// Number of records in the partition.
repeated uint32 lengths = 3;
// Tensor of centroids. `num_partitions * dimension` of float32s.
Tensor centroids_tensor = 4;
// KMeans loss.
optional double loss = 5;
}
// Product Quantization.
message PQ {
// The number of bits to present a centroid.
uint32 num_bits = 1;
// Number of sub vectors.
uint32 num_sub_vectors = 2;
// Vector dimension
uint32 dimension = 3;
// Codebook. `dimension * 2 ^ num_bits` of float32s.
repeated float codebook = 4;
// Tensor of codebook. `2 ^ num_bits * dimension` of floats.
Tensor codebook_tensor = 5;
}
// Transform type
enum TransformType {
OPQ = 0;
}
// A transform matrix to apply to a vector or vectors.
message Transform {
// The file offset the matrix is stored
uint64 position = 1;
// Data shape of the matrix, [rows, cols].
repeated uint32 shape = 2;
// Transform type.
TransformType type = 3;
}
// Flat Index
message Flat {}
// DiskAnn Index
message DiskAnn {
// Graph spec version
uint32 spec = 1;
// Graph file
string filename = 2;
// r parameter
uint32 r = 3;
// alpha parameter
float alpha = 4;
// L parameter
uint32 L = 5;
/// Entry points to the graph
repeated uint64 entries = 6;
}
// One stage in the vector index pipeline.
message VectorIndexStage {
oneof stage {
// Flat index
Flat flat = 1;
// `IVF` - Inverted File
IVF ivf = 2;
// Product Quantization
PQ pq = 3;
// Transformer
Transform transform = 4;
// DiskANN
DiskAnn diskann = 5;
}
}
// Metric Type for Vector Index
enum VectorMetricType {
// L2 (Euclidean) Distance
L2 = 0;
// Cosine Distance
Cosine = 1;
// Dot Product
Dot = 2;
// Hamming Distance
Hamming = 3;
}
// Vector Index Metadata
message VectorIndex {
// Index specification version.
uint32 spec_version = 1;
// Vector dimension;
uint32 dimension = 2;
// Composed vector index stages.
//
// For example, `IVF_PQ` index type can be expressed as:
//
// ```text
// let stages = vec![Ivf{}, PQ{num_bits: 8, num_sub_vectors: 16}]
// ```
repeated VectorIndexStage stages = 3;
// Vector distance metrics type
VectorMetricType metric_type = 4;
}
// Details for vector indexes, stored in the manifest's index_details field.
message VectorIndexDetails {
VectorMetricType metric_type = 1;
// The target number of vectors per partition.
// 0 means unset.
uint64 target_partition_size = 2;
// Optional HNSW index configuration. If set, the index has an HNSW layer.
optional HnswParameters hnsw_index_config = 3;
message ProductQuantization {
uint32 num_bits = 1;
uint32 num_sub_vectors = 2;
}
message ScalarQuantization {
uint32 num_bits = 1;
}
message RabitQuantization {
enum RotationType {
FAST = 0;
MATRIX = 1;
}
uint32 num_bits = 1;
RotationType rotation_type = 2;
}
// No quantization; vectors are stored as-is.
message FlatCompression {}
oneof compression {
ProductQuantization pq = 4;
ScalarQuantization sq = 5;
RabitQuantization rq = 6;
FlatCompression flat = 8;
}
// Runtime hints: optional build preferences that don't affect index structure.
// Keys use reverse-DNS namespacing (e.g., "lance.ivf.max_iters", "lancedb.accelerator").
// Unrecognized keys must be silently ignored by all runtimes.
map<string, string> runtime_hints = 9;
}
// Hierarchical Navigable Small World (HNSW) parameters, used as an optional configuration for IVF indexes.
message HnswParameters {
// The maximum number of outgoing edges per node in the HNSW graph. Higher values
// means more connections, better recall, but more memory and slower builds.
// Referred to as "M" in the HNSW literature.
uint32 max_connections = 1;
// "construction exploration factor": The size of the dynamic list used during
// index construction.
uint32 construction_ef = 2;
// The maximum number of levels in the HNSW graph.
uint32 max_level = 3;
}
message JsonIndexDetails {
string path = 1;
google.protobuf.Any target_details = 2;
}
message BloomFilterIndexDetails {}
message RTreeIndexDetails {}
message FMIndexDetails {}
lance-artifact/protos/index_old.proto
+104
View File
@@ -0,0 +1,104 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright The Lance Authors
syntax = "proto3";
package lance.table;
// NOTE: Do *NOT* add new index details here. Add them to the index.proto file instead.
// This file is in the lance.table package namespace while the index.proto file is in the
// lance.index package namespace.
//
// These are only here for forward compatibility. Older versions of Lance expect btree indexes
// to have lance.table in the package namespace.
//
// If you need to modify these messages (e.g. to add new fields to btree or bitmap) then
// it is ok to modify them here.
// Currently many of these are empty messages because all needed details are either hard-coded (e.g.
// filenames) or stored in the index itself. However, we may want to add more details in the
// future, in particular we can add details that may be useful for planning queries (e.g. don't
// force us to load the index until we know we can make use of it)
message BTreeIndexDetails {}
message BitmapIndexDetails {}
message LabelListIndexDetails {}
message NGramIndexDetails {}
message ZoneMapIndexDetails {
// Number of rows per zone. Optional for backwards compatibility: absent on
// datasets written before this field was added. When absent, no seed writer
// is created for the index.
optional uint64 rows_per_zone = 1;
// Whether seed-based incremental updates are enabled for this index.
// On-disk semantics: absent means seeds are disabled (old datasets written
// before this field was added). Present false means explicitly disabled.
// Present true means seeds are enabled: the index will embed per-fragment
// seed buffers in data files and harvest them during incremental updates
// to skip full column scans.
// Creation-time default: index creation code sets this to true for
// variable-length types (strings, binary) and fixed-width types wider than
// 8 bytes, and to false for narrow fixed-width types (e.g. Int64, Float64).
optional bool use_seeds = 2;
// Whether this index tracks exact null row addresses in a separate bitmap.
// Absent or false means legacy format: null positions are not tracked and
// IS NULL searches fall back to approximate zone-level statistics. Present
// true means IS NULL is exact and IS NOT NULL can be answered without a
// full scan.
optional bool has_null_bitmap = 3;
}
message InvertedIndexDetails {
enum DocumentGranularity {
ROW = 0;
LIST_ELEMENT = 1;
}
message CodeTokenizerConfig {
// Split one lexical identifier into subwords, e.g. getUserName ->
// get/user/name.
bool split_identifiers = 1;
// Split identifier subwords across letter/number boundaries, e.g.
// HTML2JSON -> html/2/json. An absent value uses the code tokenizer default;
// a present value records the explicit index-time choice.
optional bool split_on_numerics = 2;
// Keep the complete lexical identifier in addition to subwords, e.g.
// user_name plus user/name. An absent value uses the code tokenizer default;
// a present value records the explicit index-time choice.
optional bool preserve_original = 3;
// Index operator tokens such as "::", "->", and "!=". Operators are not
// indexed by default because they are often high-frequency noise.
bool index_operators = 4;
}
// Lexical tokenizer used after document-level text extraction. This is an
// implementation component such as "simple", "icu", "ngram", or "code".
// Input-time analyzer profiles are expanded into this field and the concrete
// options below before these details are persisted.
// Marking this field as optional as old versions of the index store blank details and we
// need to make sure we have a proper optional field to detect this.
optional string base_tokenizer = 1;
string language = 2;
bool with_position = 3;
optional uint32 max_token_length = 4;
bool lower_case = 5;
bool stem = 6;
bool remove_stop_words = 7;
bool ascii_folding = 8;
uint32 min_ngram_length = 9;
uint32 max_ngram_length = 10;
bool prefix_only = 11;
// Number of documents per compressed posting block. An absent value means
// the index predates this field and must use the legacy block size of 128.
// A present value records the block size used by the index; 256 is valid
// with format versions 3 and 4.
optional uint32 block_size = 12;
// Options for base_tokenizer = "code". Presence records the code tokenizer
// configuration used to build the index; absence means there is no
// code-specific configuration to apply.
CodeTokenizerConfig code_config = 13;
// The logical FTS document boundary. The protobuf default preserves the
// legacy row-document behavior when this field is absent.
DocumentGranularity document_granularity = 14;
// The posting-list payload format. This is separate from index_version,
// which identifies the overall inverted-index layout.
optional uint32 posting_format_version = 15;
}
lance-artifact/protos/license_header.txt
+2
View File
@@ -0,0 +1,2 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright The Lance Authors
lance-artifact/protos/rowids.proto
+113
View File
@@ -0,0 +1,113 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright The Lance Authors
syntax = "proto3";
package lance.table;
// TODO: what would it take to store this in a LanceV2 file?
// Or would flatbuffers be better for this?
/// A sequence of row IDs. This is split up into one or more segments,
/// each of which can be encoded in different ways. The encodings are optimized
/// for values that are sorted, which will often be the case with row ids.
/// They also have optimized forms depending on how sparse the values are.
message RowIdSequence {
repeated U64Segment segments = 1;
}
/// Different ways to encode a sequence of u64 values.
message U64Segment {
/// A range of u64 values.
message Range {
/// The start of the range, inclusive.
uint64 start = 1;
/// The end of the range, exclusive.
uint64 end = 2;
}
/// A range of u64 values with holes.
message RangeWithHoles {
/// The start of the range, inclusive.
uint64 start = 1;
/// The end of the range, exclusive.
uint64 end = 2;
/// The holes in the range, as a sorted array of values;
/// Binary search can be used to check whether a value is a hole and should
/// be skipped. This can also be used to count the number of holes before a
/// given value, if you need to find the logical offset of a value in the
/// segment.
EncodedU64Array holes = 3;
}
/// A range of u64 values with a bitmap.
message RangeWithBitmap {
/// The start of the range, inclusive.
uint64 start = 1;
/// The end of the range, exclusive.
uint64 end = 2;
/// A bitmap of the values in the range. The bitmap is a sequence of bytes,
/// where each byte represents 8 values. The first byte represents values
/// start to start + 7, the second byte represents values start + 8 to
/// start + 15, and so on. The most significant bit of each byte represents
/// the first value in the range, and the least significant bit represents
/// the last value in the range. If the bit is set, the value is in the
/// range; if it is not set, the value is not in the range.
bytes bitmap = 3;
}
oneof segment {
/// When the values are sorted and contiguous.
Range range = 1;
/// When the values are sorted but have a few gaps.
RangeWithHoles range_with_holes = 2;
/// When the values are sorted but have many gaps.
RangeWithBitmap range_with_bitmap = 3;
/// When the values are sorted but are sparse.
EncodedU64Array sorted_array = 4;
/// A general array of values, which is not sorted.
EncodedU64Array array = 5;
}
} // RowIdSegment
/// A basic bitpacked array of u64 values.
message EncodedU64Array {
message U16Array {
uint64 base = 1;
/// The deltas are stored as 16-bit unsigned integers.
/// (protobuf doesn't support 16-bit integers, so we use bytes instead)
bytes offsets = 2;
}
message U32Array {
uint64 base = 1;
/// The deltas are stored as 32-bit unsigned integers.
/// (we use bytes instead of uint32 to avoid overhead of varint encoding)
bytes offsets = 2;
}
message U64Array {
/// (We use bytes instead of uint64 to avoid overhead of varint encoding)
bytes values = 2;
}
oneof array {
U16Array u16_array = 1;
U32Array u32_array = 2;
U64Array u64_array = 3;
}
}
/// A sequence of dataset versions. Similar to RowIdSequence but tracks
/// version runs. It uses RLE (Run-Length Encoding) to efficiently
// represent consecutive rows with the same version.
message RowDatasetVersionSequence {
repeated RowDatasetVersionRun runs = 1;
}
/// A run of rows with the same version.
message RowDatasetVersionRun {
/// The number of consecutive rows with the same version.
U64Segment span = 1;
uint64 version = 2;
}
lance-artifact/protos/table.proto
+805
View File
@@ -0,0 +1,805 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright The Lance Authors
syntax = "proto3";
package lance.table;
import "google/protobuf/any.proto";
import "google/protobuf/timestamp.proto";
import "file.proto";
/*
Format:
+----------------------------------------+
| Encoded Column 0, Chunk 0 |
...
| Encoded Column M, Chunk N - 1 |
| Encoded Column M, Chunk N |
| Indices ... |
| Chunk Position (M x N x 8) |
| Manifest (Optional) |
| Metadata |
| i64: metadata position |
| MAJOR_VERSION | MINOR_VERSION | "LANC" |
+----------------------------------------+
*/
// UUID type. encoded as 16 bytes.
message UUID {
bytes uuid = 1;
}
// Manifest is a global section shared between all the files.
message Manifest {
// All fields of the dataset, including the nested fields.
repeated lance.file.Field fields = 1;
// Schema metadata.
map<string, bytes> schema_metadata = 5;
// Fragments of the dataset.
repeated DataFragment fragments = 2;
// Snapshot version number.
uint64 version = 3;
// The file position of the version auxiliary data.
// * It is not inheritable between versions.
// * It is not loaded by default during query.
uint64 version_aux_data = 4;
message WriterVersion {
// The name of the library that created this file.
string library = 1;
// The version of the library that created this file. Because we cannot assume
// that the library is semantically versioned, this is a string. However, if it
// is semantically versioned, it should be a valid semver string without any 'v'
// prefix. For example: `2.0.0`, `2.0.0-rc.1`.
//
// For forward compatibility with older readers, when writing new manifests this
// field should contain only the core version (major.minor.patch) without any
// prerelease or build metadata. The prerelease/build info should be stored in
// the separate prerelease and build_metadata fields instead.
string version = 2;
// Optional semver prerelease identifier.
//
// This field stores the prerelease portion of a semantic version separately
// from the core version number. For example, if the full version is "2.0.0-rc.1",
// the version field would contain "2.0.0" and prerelease would contain "rc.1".
//
// This separation ensures forward compatibility: older readers can parse the
// clean version field without errors, while newer readers can reconstruct the
// full semantic version by combining version, prerelease, and build_metadata.
//
// If absent, the version field is used as-is.
optional string prerelease = 3;
// Optional semver build metadata.
//
// This field stores the build metadata portion of a semantic version separately
// from the core version number. For example, if the full version is
// "2.0.0-rc.1+build.123", the version field would contain "2.0.0", prerelease
// would contain "rc.1", and build_metadata would contain "build.123".
//
// If absent, no build metadata is present.
optional string build_metadata = 4;
}
// The version of the writer that created this file.
//
// This information may be used to detect whether the file may have known bugs
// associated with that writer.
WriterVersion writer_version = 13;
// If present, the file position of the index metadata.
optional uint64 index_section = 6;
// Version creation Timestamp, UTC timezone
google.protobuf.Timestamp timestamp = 7;
// Optional version tag
string tag = 8;
// Feature flags for readers.
//
// A bitmap of flags that indicate which features are required to be able to
// read the table. If a reader does not recognize a flag that is set, it
// should not attempt to read the dataset.
//
// Known flags:
// * 1 << 0: deletion files are present
// * 1 << 1: row ids are stable and stored as part of the fragment metadata.
// * 1 << 2: use v2 format (deprecated)
// * 1 << 3: table config is present
// * 1 << 4: dataset uses multiple base paths
// * 1 << 5: transaction file writes are disabled
// * 1 << 6: data overlay files are present (see DataOverlayFile). Readers that do
// not understand overlays must refuse the dataset, since ignoring an overlay
// would silently return stale base values.
uint64 reader_feature_flags = 9;
// Feature flags for writers.
//
// A bitmap of flags that indicate which features must be used when writing to the
// dataset. If a writer does not recognize a flag that is set, it should not attempt to
// write to the dataset.
//
// The flag identities are the same as for reader_feature_flags, but the values of
// reader_feature_flags and writer_feature_flags are not required to be identical.
uint64 writer_feature_flags = 10;
// The highest fragment ID that has been used so far.
//
// This ID is not guaranteed to be present in the current version, but it may
// have been used in previous versions.
//
// For a single fragment, will be zero. For no fragments, will be absent.
optional uint32 max_fragment_id = 11;
// Path to the transaction file, relative to `{root}/_transactions`. The file at that
// location contains a wire-format serialized Transaction message representing the
// transaction that created this version.
//
// This string field "transaction_file" may be empty if no transaction file was written.
//
// The path format is "{read_version}-{uuid}.txn" where {read_version} is the version of
// the table the transaction read from (serialized to decimal with no padding digits),
// and {uuid} is a hyphen-separated UUID.
string transaction_file = 12;
// The file position of the transaction content. None if transaction is empty
// This transaction content begins with the transaction content length as u32
// If the transaction proto message has a length of `len`, the message ends at `len` + 4
optional uint64 transaction_section = 21;
// The next unused row id. If zero, then the table does not have any rows.
//
// This is only used if the "stable_row_ids" feature flag is set.
uint64 next_row_id = 14;
message DataStorageFormat {
// The format of the data files (e.g. "lance")
string file_format = 1;
// The max format version of the data files. The format of the version can vary by
// file_format and is not required to follow semver.
//
// Every file in this version of the dataset has the same file_format version.
string version = 2;
}
// The data storage format
//
// This specifies what format is used to store the data files.
DataStorageFormat data_format = 15;
// Table config.
//
// Keys with the prefix "lance." are reserved for the Lance library. Other
// libraries may wish to similarly prefix their configuration keys
// appropriately.
map<string, string> config = 16;
// Metadata associated with the table.
//
// This is a key-value map that can be used to store arbitrary metadata
// associated with the table.
//
// This is different than configuration, which is used to tell libraries how
// to read, write, or manage the table.
//
// This is different than schema metadata, which is used to describe the
// data itself and is attached to the output schema of scans.
map<string, string> table_metadata = 19;
// Field number 17 (`blob_dataset_version`) was used for a secondary blob dataset.
reserved 17;
reserved "blob_dataset_version";
// The base paths of data files.
//
// This is used to determine the base path of a data file. In common cases data file paths are under current dataset base path.
// But for shallow cloning, importing file and other multi-tier storage cases, the actual data files could be outside of the current dataset.
// This field is used with the `base_id` in `lance.file.File` and `lance.file.DeletionFile`.
//
// For example, if we have a dataset with base path `s3://bucket/dataset`, we have a DataFile with base_id 0, we get the actual data file path by:
// base_paths[id = 0] + /data/ + file.path
// the key(a.k.a index) starts from 0, increased by 1 for each new base path.
repeated BasePath base_paths = 18;
// The branch of the dataset. None means main branch.
optional string branch = 20;
} // Manifest
// external dataset base path
message BasePath {
uint32 id = 1;
// This is an alias name of the base path, it is optional.
// When we use shallow clone and the target version is a tag, the tag name will be set here.
optional string name = 2;
// Flag indicating whether this path is a dataset root path or file directory:
// - true: Path is a dataset root (actual files under subdirectories like `data`, '_deletions')
// - false: Path is a direct file directory (scenario like importing files)
bool is_dataset_root = 3;
// Note: This absolute path will be directly used by Path:parse(),
string path = 4;
}
// Auxiliary Data attached to a version.
// Only load on-demand.
message VersionAuxData {
// key-value metadata.
map<string, bytes> metadata = 3;
}
// Metadata describing an index.
message IndexMetadata {
// Unique ID of an index. It is unique across all the dataset versions.
UUID uuid = 1;
// The columns to build the index. These refer to file.Field.id.
repeated int32 fields = 2;
// Index name. Must be unique within one dataset version.
string name = 3;
// The version of the dataset this index was built from.
uint64 dataset_version = 4;
// A bitmap of the included fragment ids.
//
// This may by used to determine how much of the dataset is covered by the
// index. This information can be retrieved from the dataset by looking at
// the dataset at `dataset_version`. However, since the old version may be
// deleted while the index is still in use, this information is also stored
// in the index.
//
// The bitmap is stored as a 32-bit Roaring bitmap.
bytes fragment_bitmap = 5;
// Details, specific to the index type, which are needed to load / interpret the index
//
// Indices should avoid putting large amounts of information in this field, as it will
// bloat the manifest.
//
// Indexes are plugins, and so the format of the details message is flexible and not fully
// defined by the table format. However, there are some conventions that should be followed:
//
// - When Lance APIs refer to indexes they will use the type URL of the index details as the
// identifier for the index type. If a user provides a simple string identifier like
// "btree" then it will be converted to "/lance.table.BTreeIndexDetails"
// - Type URLs comparisons are case-insensitive. Thereform an index must have a unique type
// URL ignoring case.
google.protobuf.Any index_details = 6;
// The minimum lance version that this index is compatible with.
optional int32 index_version = 7;
// Timestamp when the index was created (UTC timestamp in milliseconds since epoch)
//
// This field is optional for backward compatibility. For existing indices created before
// this field was added, this will be None/null.
optional uint64 created_at = 8;
// The base path index of the data file. Used when the file is imported or referred from another dataset.
// Lance use it as key of the base_paths field in Manifest to determine the actual base path of the data file.
optional uint32 base_id = 9;
// List of files and their sizes for this index segment.
// This enables skipping HEAD calls when opening indices and allows reporting
// of index sizes without extra IO.
// If this is empty, the index files sizes are unknown.
repeated IndexFile files = 10;
}
// Metadata about a single file within an index segment.
message IndexFile {
// Path relative to the index directory (e.g., "index.idx", "auxiliary.idx")
string path = 1;
// Size of the file in bytes
uint64 size_bytes = 2;
}
// Index Section, containing a list of index metadata for one dataset version.
message IndexSection {
repeated IndexMetadata indices = 1;
}
// A DataFragment is a set of files which represent the different columns of the same
// rows. If column exists in the schema of a dataset, but the file for that column does
// not exist within a DataFragment of that dataset, that column consists entirely of
// nulls.
message DataFragment {
// The ID of a DataFragment is unique within a dataset.
uint64 id = 1;
repeated DataFile files = 2;
// Optional overlay files for this fragment, which supply new values for a
// subset of cells without rewriting the base data files. This MUST be empty
// if the data overlay files feature flag (64) is not set in the manifest.
//
// Order is significant: a later entry is newer than an earlier one. When two
// overlays cover the same (offset, field) and share a `committed_version`, the
// later entry wins. See DataOverlayFile for the full resolution rules.
repeated DataOverlayFile overlays = 11;
// File that indicates which rows, if any, should be considered deleted.
DeletionFile deletion_file = 3;
// TODO: What's the simplest way we can allow an inline tombstone bitmap?
// A serialized RowIdSequence message (see rowids.proto).
//
// These are the row ids for the fragment, in order of the rows as they appear.
// That is, if a fragment has 3 rows, and the row ids are [1, 42, 3], then the
// first row is row 1, the second row is row 42, and the third row is row 3.
oneof row_id_sequence {
// If small (< 200KB), the row ids are stored inline.
bytes inline_row_ids = 5;
// Otherwise, stored as part of a file.
ExternalFile external_row_ids = 6;
} // row_id_sequence
oneof last_updated_at_version_sequence {
// If small (< 200KB), the row latest updated versions are stored inline.
bytes inline_last_updated_at_versions = 7;
// Otherwise, stored as part of a file.
ExternalFile external_last_updated_at_versions = 8;
} // last_updated_at_version_sequence
oneof created_at_version_sequence {
// If small (< 200KB), the row created at versions are stored inline.
bytes inline_created_at_versions = 9;
// Otherwise, stored as part of a file.
ExternalFile external_created_at_versions = 10;
} // created_at_version_sequence
// Number of original rows in the fragment, this includes rows that are now marked with
// deletion tombstones. To compute the current number of rows, subtract
// `deletion_file.num_deleted_rows` from this value.
uint64 physical_rows = 4;
}
message DataFile {
// Path to the root relative to the dataset's URI.
string path = 1;
// The ids of the fields/columns in this file.
//
// When a DataFile object is created in memory, every value in fields is assigned -1 by
// default. An object with a value in fields of -1 must not be stored to disk. -2 is
// used for "tombstoned", meaning a field that is no longer in use. This is often
// because the original field id was reassigned to a different data file.
//
// In Lance v1 IDs are assigned based on position in the file, offset by the max
// existing field id in the table (if any already). So when a fragment is first created
// with one file of N columns, the field ids will be 1, 2, ..., N. If a second fragment
// is created with M columns, the field ids will be N+1, N+2, ..., N+M.
//
// In Lance v1 there is one field for each field in the input schema, this includes
// nested fields (both struct and list). Fixed size list fields have only a single
// field id (these are not considered nested fields in Lance v1).
//
// This allows column indices to be calculated from field IDs and the input schema.
//
// In Lance v2 the field IDs generally follow the same pattern but there is no
// way to calculate the column index from the field ID. This is because a given
// field could be encoded in many different ways, some of which occupy a different
// number of columns. For example, a struct field could be encoded into N + 1 columns
// or it could be encoded into a single packed column. To determine column indices
// the column_indices property should be used instead.
//
// In Lance v1 these ids must be sorted but might not always be contiguous.
repeated int32 fields = 2;
// The top-level column indices for each field in the file.
//
// If the data file is version 1 then this property will be empty
//
// Otherwise there must be one entry for each field in `fields`.
//
// Some fields may not correspond to a top-level column in the file. In these cases
// the index will -1.
//
// For example, consider the schema:
//
// - dimension: packed-struct (0):
// - x: u32 (1)
// - y: u32 (2)
// - path: `list<u32>` (3)
// - embedding: `fsl<768>` (4)
// - fp64
// - borders: `fsl<4>` (5)
// - simple-struct (6)
// - margin: fp64 (7)
// - padding: fp64 (8)
//
// One possible column indices array could be:
// [0, -1, -1, 1, 3, 4, 5, 6, 7]
//
// This reflects quite a few phenomenon:
// - The packed struct is encoded into a single column and there is no top-level column
// for the x or y fields
// - The variable sized list is encoded into two columns
// - The embedding is encoded into a single column (common for FSL of primitive) and there
// is not "FSL column"
// - The borders field actually does have an "FSL column"
//
// The column indices table may not have duplicates (other than -1)
repeated int32 column_indices = 3;
// The major file version used to create the file
uint32 file_major_version = 4;
// The minor file version used to create the file
//
// If both `file_major_version` and `file_minor_version` are set to 0,
// then this is a version 0.1 or version 0.2 file.
uint32 file_minor_version = 5;
// The known size of the file on disk in bytes.
//
// This is used to quickly find the footer of the file.
//
// When this is zero, it should be interpreted as "unknown".
uint64 file_size_bytes = 6;
// The base path index of the data file. Used when the file is imported or referred from another dataset.
// Lance use it as key of the base_paths field in Manifest to determine the actual base path of the data file.
optional uint32 base_id = 7;
} // DataFile
// An overlay file supplies new values for a subset of (row offset, field) cells
// within a fragment, without rewriting the fragment's base data files. It is
// used for efficient updates when only a small fraction of rows and/or columns
// change.
//
// On read, a cell is resolved by consulting the fragment's overlays from newest
// to oldest: the first overlay that covers that (offset, field) wins; if none
// cover it, the value falls through to the base data file. Because deletions
// take precedence over overlays, an overlay value for an offset that is also
// marked deleted is dead and is ignored.
//
// The overlay's data file does NOT store a row-offset key column. Within a value
// column, the position of a covered offset's value is the rank (0-based count of
// set bits below it) of that offset within the field's coverage bitmap. Because
// fields may cover different offset sets, the value columns of a single overlay
// data file may have different lengths (which the Lance file format permits).
message DataOverlayFile {
// The data file storing the overlay's new cell values, one value column per
// field in `data_file.fields`. No row-offset key column is stored.
DataFile data_file = 1;
// Which (offset, field) cells this overlay provides values for.
oneof coverage {
// A single 32-bit Roaring bitmap of physical row offsets that applies to
// every field in `data_file.fields` (a "dense" / rectangular overlay).
// Every covered offset has a value for every field. This is the common case
// for a plain UPDATE, where one SET list is applied to one set of rows.
bytes shared_offset_bitmap = 2;
// Per-field coverage for a "sparse" overlay, used when different fields cover
// different offset sets (e.g. a MERGE with multiple WHEN MATCHED branches).
FieldCoverage field_coverage = 4;
}
// The dataset version at which this overlay became effective: the version of
// the commit that introduced it, NOT the version it was read from. It is
// stamped at commit time and re-stamped if the commit is retried, in the same
// way as the created-at / last-updated-at version sequences.
//
// This drives two orderings:
// * Versus index builds: an index whose `dataset_version` >= this value
// already incorporates this overlay. Otherwise the overlay's covered cells
// are excluded from index results for the affected fields and re-evaluated
// against their current values (see the Data Overlay Files specification).
// * Versus other overlays: when two overlays cover the same (offset, field),
// the one with the higher `committed_version` wins. Overlays that share a
// `committed_version` are ordered by their position in
// `DataFragment.overlays`, where a later entry is newer and wins.
uint64 committed_version = 3;
}
// Per-field coverage for a sparse overlay.
message FieldCoverage {
// One entry per field in the overlay's `data_file.fields`, in the same order.
// Each is a 32-bit Roaring bitmap of the physical row offsets covered for that
// field. An offset present in a field's bitmap but mapped to a NULL value
// means the cell is overridden to NULL (distinct from an offset that is absent,
// which falls through to the base data file).
repeated bytes offset_bitmaps = 1;
}
// Deletion File
//
// The path of the deletion file is constructed as:
// {root}/_deletions/{fragment_id}-{read_version}-{id}.{extension}
// where {extension} depends on DeletionFileType.
message DeletionFile {
// Type of deletion file, intended as a way to increase efficiency of the storage of deleted row
// offsets. If there are sparsely deleted rows, then ARROW_ARRAY is the most efficient. If there
// are densely deleted rows, then BITMAP is the most efficient.
enum DeletionFileType {
// A single Int32Array of deleted row offsets, stored as an Arrow IPC file with one batch and
// one column. Has a .arrow extension.
ARROW_ARRAY = 0;
// A Roaring Bitmap of deleted row offsets. Has a .bin extension.
BITMAP = 1;
}
// Type of deletion file.
DeletionFileType file_type = 1;
// The version of the dataset this deletion file was built from.
uint64 read_version = 2;
// An opaque id used to differentiate this file from others written by concurrent
// writers.
uint64 id = 3;
// The number of rows that are marked as deleted.
uint64 num_deleted_rows = 4;
// The base path index of the deletion file. Used when the file is imported or referred from another
// dataset. Lance uses it as key of the base_paths field in Manifest to determine the actual base
// path of the deletion file.
optional uint32 base_id = 7;
} // DeletionFile
message ExternalFile {
// Path to the file, relative to the root of the table.
string path = 1;
// The byte offset in the file where the data starts.
uint64 offset = 2;
// The size of the data in the file, in bytes.
uint64 size = 3;
}
// VectorIndexDetails and HnswParameters (formerly HnswIndexDetails) moved to index.proto
message FragmentReuseIndexDetails {
oneof content {
// if < 200KB, store the content inline, otherwise store the InlineContent bytes in external file
InlineContent inline = 1;
ExternalFile external = 2;
}
message InlineContent {
repeated Version versions = 1;
}
message FragmentDigest {
uint64 id = 1;
uint64 physical_rows = 2;
uint64 num_deleted_rows = 3;
}
// A summarized version of the RewriteGroup information in a Rewrite transaction
message Group {
// A roaring treemap of the changed row addresses.
// When combined with the old fragment IDs and new fragment IDs,
// it can recover the full mapping of old row addresses to either new row addresses or deleted.
// this mapping can then be used to remap indexes or satisfy index queries for the new unindexed fragments.
bytes changed_row_addrs = 1;
repeated FragmentDigest old_fragments = 2;
repeated FragmentDigest new_fragments = 3;
}
message Version {
// The dataset_version at the time the index adds this version entry
uint64 dataset_version = 1;
repeated Group groups = 3;
}
}
// ============================================================================
// MemWAL Index Types
// ============================================================================
// Lifecycle status of a WAL shard. Drives drop-table two-phase commit:
// a SEALED shard refuses new writer claims (reversible) until the drop
// commits (the shard dir is deleted) or rolls back (status -> ACTIVE).
enum ShardStatus {
// Normal: the shard accepts writer claims.
ACTIVE = 0;
// A drop is in flight: claims are refused. Reversible to ACTIVE.
SEALED = 1;
}
// Shard manifest containing epoch-based fencing and WAL state.
// Each shard has exactly one active writer at any time.
message ShardManifest {
// Shard identifier (UUID v4).
UUID shard_id = 11;
// Manifest version number.
// Matches the version encoded in the filename.
uint64 version = 1;
// Shard spec ID this shard was created with.
// Set at shard creation and immutable thereafter.
// A value of 0 indicates a manually-created shard not governed by any spec.
uint32 shard_spec_id = 10;
// Computed shard field values as raw Arrow scalar bytes, keyed by shard
// field id. The byte encoding follows Arrow's little-endian convention:
// int32 is 4 LE bytes, utf8 is raw UTF-8 bytes, etc. The receiver looks
// up the result_type from the ShardingSpec to interpret each value.
repeated ShardFieldEntry shard_field_entries = 14;
// Writer fencing token - monotonically increasing.
// A writer must increment this when claiming the shard.
uint64 writer_epoch = 2;
// The most recent WAL entry position that has been flushed to a MemTable.
// During recovery, replay starts from replay_after_wal_entry_position + 1.
// WAL positions are 1-based, so the default value 0 unambiguously means
// "no flush has ever stamped this shard" and recovery replays from 1.
uint64 replay_after_wal_entry_position = 3;
// The most recent WAL entry position observed at the time the manifest was
// updated. WAL positions are 1-based; default 0 means no entry has been
// written yet. This is a hint, not authoritative - recovery must list
// files to find actual state.
uint64 wal_entry_position_last_seen = 4;
// Generation to assign to the next SSTable (incremented after each MemTable flush).
uint64 current_generation = 6;
// Field 7 removed: compaction progress lives in
// MemWalIndexDetails.compacted_sstables.
// List of SSTables created by flushing MemTables and their directory paths.
repeated SsTable sstables = 8;
// Lifecycle status. Default ACTIVE; SEALED marks an in-flight drop
// (drop-table 2PC). A SEALED manifest refuses claims at claim_epoch.
ShardStatus status = 15;
}
// A shard field value stored as raw Arrow scalar bytes.
message ShardFieldEntry {
// Shard field id (matches ShardingField.field_id in the ShardingSpec).
string field_id = 1;
// Raw Arrow scalar value bytes in little-endian encoding.
// The data type is determined by the result_type of the matching ShardingField.
bytes value = 2;
}
// An SSTable: the immutable result of flushing a MemTable, stored as a Lance dataset.
message SsTable {
// Generation number identifying this SSTable.
uint64 generation = 1;
// Directory name relative to the shard directory.
string path = 2;
}
// A pointer to the latest SSTable compacted for a shard.
message CompactedSsTable {
// Shard identifier (UUID v4).
UUID shard_id = 1;
// Generation of the latest SSTable compacted into the base table for this shard.
uint64 generation = 2;
}
// Tracks which compacted SSTable generation a base table index has been rebuilt to cover.
// Used to determine whether to read from SSTable indexes or base table.
message IndexCatchupProgress {
// Name of the base table index (must match an entry in maintained_indexes).
string index_name = 1;
// Per-shard progress: the generation up to which this index covers.
// If a shard is not present, the index is assumed to be fully caught up
// (i.e., caught_up_generation >= compacted_generation for that shard).
repeated CompactedSsTable caught_up_generations = 2;
}
// Index details for MemWAL Index, stored in IndexMetadata.index_details.
// This is the centralized structure for all MemWAL metadata:
// - Configuration (sharding specs, indexes to maintain)
// - SSTable compaction progress
// - Shard state snapshots
//
// Writers read this index to get configuration before writing.
// Readers may use shard snapshots in this index as a point-in-time
// optimization. Readers that need the latest shard set should list shard
// directories in storage and read each shard's latest manifest.
// A background process updates the index periodically to keep shard snapshots current.
//
// Shard snapshots are stored as a Lance file with one row per shard.
// The schema records shard discovery fields. Full mutable shard state remains
// authoritative in the shard manifest files.
// shard_id: utf8
// shard_spec_id: uint32
// shard_field_{field_id}: typed per the matching ShardingField.result_type
message MemWalIndexDetails {
// Snapshot timestamp (Unix timestamp in milliseconds).
int64 snapshot_ts_millis = 1;
// Number of shards in the snapshot.
// Used to determine storage format without reading the snapshot data.
uint32 num_shards = 2;
// Inline shard snapshots for small shard counts.
// When num_shards <= threshold (implementation-defined, e.g., 100),
// snapshots are stored inline as serialized bytes.
// Format: Lance file bytes with the shard snapshot schema.
optional bytes inline_snapshots = 3;
// Sharding specs defining how to derive shard identifiers.
// This configuration determines how rows are partitioned into shards.
repeated ShardingSpec sharding_specs = 7;
// Indexes from the base table to maintain in MemTables.
// These are index names referencing indexes defined on the base table.
// The primary key btree index is always maintained implicitly and
// should not be listed here.
//
// For vector indexes, MemTables inherit quantization parameters (PQ codebook,
// SQ params) from the base table index to ensure distance comparability.
repeated string maintained_indexes = 8;
// Latest SSTable compacted into the base table for each shard.
// This is updated atomically with merge-insert data commits, enabling
// conflict resolution when multiple compactors operate concurrently.
//
// Note: This is separate from shard snapshots because:
// 1. compacted_sstables is updated by compactors (atomic with data commit)
// 2. shard snapshots are updated by background index builder
repeated CompactedSsTable compacted_sstables = 9;
// Per-index catchup progress tracking.
// When data is compacted into the base table, base table indexes are rebuilt
// asynchronously. This field tracks which generation each index covers.
//
// For indexed queries, if an index's caught_up_generation < compacted_generation,
// readers should use SSTable indexes for the gap instead of
// scanning unindexed data in the base table.
//
// If an index is not present in this list, it is assumed to be fully caught up.
repeated IndexCatchupProgress index_catchup = 10;
// Default ShardWriter configuration values for this MemWAL index.
//
// A free-form string map persisted so that every writer — across
// processes and restarts — starts from the same default writer
// configuration. These are defaults only: an individual writer may
// still override any value at runtime in its own ShardWriterConfig
// (which is not persisted).
map<string, string> writer_config_defaults = 11;
}
// Sharding spec definition.
message ShardingSpec {
// Unique identifier for this spec within the index.
// IDs are never reused.
uint32 spec_id = 1;
// Sharding field definitions that determine how to compute shard identifiers.
repeated ShardingField fields = 2;
}
// Sharding field definition.
message ShardingField {
// Unique string identifier for this shard field.
string field_id = 1;
// Field IDs referencing source columns in the schema.
repeated int32 source_ids = 2;
// Well-known shard transform name (e.g., "identity", "year", "bucket").
// Mutually exclusive with expression.
optional string transform = 3;
// DataFusion SQL expression for custom logic.
// Mutually exclusive with transform.
optional string expression = 4;
// Output type of the shard value (Arrow type name).
string result_type = 5;
// Transform parameters (e.g., num_buckets for bucket transform).
map<string, string> parameters = 6;
}
lance-artifact/protos/table_identifier.proto
+19
View File
@@ -0,0 +1,19 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright The Lance Authors
syntax = "proto3";
package lance.datafusion;
// Identifies a Lance dataset for remote reconstruction.
//
// Two modes:
// 1. uri + serialized_manifest (fast): remote executor skips manifest read.
// 2. uri + version + etag (lightweight): remote executor loads manifest from storage.
message TableIdentifier {
string uri = 1;
uint64 version = 2;
optional string manifest_etag = 3;
optional bytes serialized_manifest = 4;
map<string, string> storage_options = 5;
}
lance-artifact/protos/transaction.proto
+377
View File
@@ -0,0 +1,377 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright The Lance Authors
syntax = "proto3";
import "file.proto";
import "table.proto";
import "google/protobuf/any.proto";
package lance.table;
// A transaction represents the changes to a dataset.
//
// This has two purposes:
// 1. When retrying a commit, the transaction can be used to re-build an updated
// manifest.
// 2. When there's a conflict, this can be used to determine whether the other
// transaction is compatible with this one.
message Transaction {
// The version of the dataset this transaction was built from.
//
// For example, for a delete transaction this means the version of the dataset
// that was read from while evaluating the deletion predicate.
uint64 read_version = 1;
// The UUID that unique identifies a transaction.
string uuid = 2;
// Optional version tag.
string tag = 3;
// Optional properties for the transaction
// __lance_commit_message is a reserved key
map<string, string> transaction_properties = 4;
// Add new rows to the dataset.
message Append {
// The new fragments to append.
//
// Fragment IDs are not yet assigned.
repeated DataFragment fragments = 1;
}
// Mark rows as deleted.
message Delete {
// The fragments to update
//
// The fragment IDs will match existing fragments in the dataset.
repeated DataFragment updated_fragments = 1;
// The fragments to delete entirely.
repeated uint64 deleted_fragment_ids = 2;
// The predicate that was evaluated
//
// This may be used to determine whether the delete would have affected
// files written by a concurrent transaction.
string predicate = 3;
}
// Create or overwrite the entire dataset.
message Overwrite {
// The new fragments
//
// Fragment IDs are not yet assigned.
repeated DataFragment fragments = 1;
// The new schema
repeated lance.file.Field schema = 2;
// Schema metadata.
map<string, bytes> schema_metadata = 3;
// Key-value pairs to merge with existing config.
map<string, string> config_upsert_values = 4;
// The base paths to be added for the initial dataset creation
repeated BasePath initial_bases = 5;
}
// Add or replace a new secondary index.
//
// This is also used to remove an index (we are replacing it with nothing)
//
// - new_indices: the modified indices, empty if dropping indices only
// - removed_indices: the indices that are being replaced
message CreateIndex {
repeated IndexMetadata new_indices = 1;
repeated IndexMetadata removed_indices = 2;
}
// An operation that rewrites but does not change the data in the table. These
// kinds of operations just rearrange data.
message Rewrite {
// The old fragments that are being replaced
//
// DEPRECATED: use groups instead.
//
// These should all have existing fragment IDs.
repeated DataFragment old_fragments = 1;
// The new fragments
//
// DEPRECATED: use groups instead.
//
// These fragments IDs are not yet assigned.
repeated DataFragment new_fragments = 2;
// During a rewrite an index may be rewritten. We only serialize the UUID
// since a rewrite should not change the other index parameters.
message RewrittenIndex {
// The id of the index that will be replaced
UUID old_id = 1;
// the id of the new index
UUID new_id = 2;
// the new index details
google.protobuf.Any new_index_details = 3;
// the version of the new index
uint32 new_index_version = 4;
// Files in the new index with their sizes.
// Empty if file sizes are not available (e.g. older writers).
repeated IndexFile new_index_files = 5;
}
// A group of rewrite files that are all part of the same rewrite.
message RewriteGroup {
// The old fragment that is being replaced
//
// This should have an existing fragment ID.
repeated DataFragment old_fragments = 1;
// The new fragment
//
// The ID should have been reserved by an earlier
// reserve operation
repeated DataFragment new_fragments = 2;
}
// Groups of files that have been rewritten
repeated RewriteGroup groups = 3;
// Indices that have been rewritten
repeated RewrittenIndex rewritten_indices = 4;
}
// An operation that merges in a new column, altering the schema.
message Merge {
// The updated fragments
//
// These should all have existing fragment IDs.
repeated DataFragment fragments = 1;
// The new schema
repeated lance.file.Field schema = 2;
// Schema metadata.
map<string, bytes> schema_metadata = 3;
}
// An operation that projects a subset of columns, altering the schema.
message Project {
// The new schema
repeated lance.file.Field schema = 1;
}
// An operation that restores a dataset to a previous version.
message Restore {
// The version to restore to
uint64 version = 1;
}
// An operation that reserves fragment ids for future use in
// a rewrite operation.
message ReserveFragments {
uint32 num_fragments = 1;
}
// An operation that clones a dataset.
message Clone {
// - true: Performs a metadata-only clone (copies manifest without data files).
// The cloned dataset references original data through `base_paths`,
// suitable for experimental scenarios or rapid metadata migration.
// - false: Performs a full deep clone using the underlying object storage's native
// copy API (e.g., S3 CopyObject, GCS rewrite). This leverages server-side
// bulk copy operations to bypass download/upload bottlenecks, achieving
// near-linear speedup for large datasets (typically 3-10x faster than
// manual file transfers). The operation maintains atomicity and data
// integrity guarantees provided by the storage backend.
bool is_shallow = 1;
// the reference name in the source dataset
// in most cases it should be the branch or tag name in the source dataset
optional string ref_name = 2;
// the version of the source dataset for cloning
uint64 ref_version = 3;
// the absolute base path of the source dataset for cloning
string ref_path = 4;
// if the target dataset is a branch, this is the branch name of the target dataset
optional string branch_name = 5;
}
// Exact set of key hashes for conflict detection.
// Used when the number of inserted rows is small.
message ExactKeySetFilter {
// 64-bit hashes of the inserted row keys.
repeated uint64 key_hashes = 1;
}
// Bloom filter for key existence tests.
// Used when the number of rows is large.
message BloomFilter {
// Bitset backing the bloom filter (SBBF format).
bytes bitmap = 1;
// Number of bits in the bitmap.
uint32 num_bits = 2;
// Number of items the filter was sized for.
// Used for intersection validation (filters with different sizes cannot be compared).
// Default: 8192
uint64 number_of_items = 3;
// False positive probability the filter was sized for.
// Used for intersection validation (filters with different parameters cannot be compared).
// Default: 0.00057
double probability = 4;
}
// A filter for checking key existence in set of rows inserted by a merge insert operation.
// Only created when the merge insert's ON columns match the schema's unenforced primary key.
// The presence of this filter indicates strict primary key conflict detection should be used.
// Can use either an exact set (for small row counts) or a Bloom filter (for large row counts).
message KeyExistenceFilter {
// Field IDs of columns participating in the key (must match unenforced primary key).
repeated int32 field_ids = 1;
// The underlying data structure storing the key hashes.
oneof data {
// Exact set of key hashes (used for small number of rows).
ExactKeySetFilter exact = 2;
// Bloom filter (used for large number of rows).
BloomFilter bloom = 3;
}
}
// Serialized as sorted distinct local physical row offsets within the fragment (0-based).
message UInt32List {
repeated uint32 values = 1;
}
// An operation that updates rows but does not add or remove rows.
message Update {
// The fragments that have been removed. These are fragments where all rows
// have been updated and moved to a new fragment.
repeated uint64 removed_fragment_ids = 1;
// The fragments that have been updated.
repeated DataFragment updated_fragments = 2;
// The new fragments where updated rows have been moved to.
repeated DataFragment new_fragments = 3;
// The ids of the fields that have been modified.
repeated uint32 fields_modified = 4;
/// SSTables to mark as compacted after this transaction.
repeated CompactedSsTable compacted_sstables = 5;
/// The fields that used to judge whether to preserve the new frag's id into
/// the frag bitmap of the specified indices.
repeated uint32 fields_for_preserving_frag_bitmap = 6;
// The mode of update
UpdateMode update_mode = 7;
// Filter for checking existence of keys in newly inserted rows, used for conflict detection.
// Only tracks keys from INSERT operations during merge insert, not updates.
optional KeyExistenceFilter inserted_rows = 8;
// Per-fragment physical row offsets that matched an update_columns hash join (RewriteColumns).
map<uint64, UInt32List> updated_fragment_offsets = 9;
}
// The mode of update operation
enum UpdateMode {
/// rows are deleted in current fragments and rewritten in new fragments.
/// This is most optimal when the majority of columns are being rewritten
/// or only a few rows are being updated.
REWRITE_ROWS = 0;
/// within each fragment, columns are fully rewritten and inserted as new data files.
/// Old versions of columns are tombstoned. This is most optimal when most rows are affected
/// but a small subset of columns are affected.
REWRITE_COLUMNS = 1;
}
// An entry for a map update. If value is not set, the key will be removed from the map.
message UpdateMapEntry {
// The key of the map entry to update.
string key = 1;
// The value to set for the key.
optional string value = 2;
}
message UpdateMap {
repeated UpdateMapEntry update_entries = 1;
// If true, the map will be replaced entirely with the new entries.
// If false, the new entries will be merged with the existing map.
bool replace = 2;
}
// An operation that updates the table config, table metadata, schema metadata,
// or field metadata.
message UpdateConfig {
UpdateMap config_updates = 6;
UpdateMap table_metadata_updates = 7;
UpdateMap schema_metadata_updates = 8;
map<int32, UpdateMap> field_metadata_updates = 9;
// Deprecated -------------------------------
map<string, string> upsert_values = 1;
repeated string delete_keys = 2;
map<string, string> schema_metadata = 3;
map<uint32, FieldMetadataUpdate> field_metadata = 4;
message FieldMetadataUpdate {
map<string, string> metadata = 5;
}
}
message DataReplacementGroup {
uint64 fragment_id = 1;
DataFile new_file = 2;
}
// An operation that replaces the data in a region of the table with new data.
message DataReplacement {
repeated DataReplacementGroup replacements = 1;
}
// Overlay files to append to a single fragment, in order (the last entry is
// newest). The overlays are appended to the fragment's existing `overlays`
// list; they do not replace it, so overlays written by concurrent commits are
// preserved.
message DataOverlayGroup {
uint64 fragment_id = 1;
// Each DataOverlayFile.committed_version is left 0 by the writer and stamped
// to the new dataset version at commit time (re-stamped on retry), in the
// same way as the created-at / last-updated-at version sequences. The fields
// touched are read from each overlay's `data_file.fields`.
repeated DataOverlayFile overlays = 2;
}
// Attach overlay files to fragments, supplying new values for a subset of
// (row offset, field) cells without rewriting the fragments' base data files.
// See the DataOverlayFile message in table.proto for resolution, coverage, and
// versioning rules, and the Data Overlay Files and Transactions specifications
// for the (intentionally permissive) conflict semantics.
message DataOverlay {
repeated DataOverlayGroup groups = 1;
}
// Update SSTable compaction progress in the MemWAL index.
// This operation is used during merge-insert to atomically record which
// SSTables have been compacted into the base table.
message UpdateMemWalState {
// SSTables being marked as compacted.
repeated CompactedSsTable compacted_sstables = 1;
}
// An operation that updates base paths in the dataset.
message UpdateBases {
// The new base paths to add to the manifest.
repeated BasePath new_bases = 1;
}
// The operation of this transaction.
oneof operation {
Append append = 100;
Delete delete = 101;
Overwrite overwrite = 102;
CreateIndex create_index = 103;
Rewrite rewrite = 104;
Merge merge = 105;
Restore restore = 106;
ReserveFragments reserve_fragments = 107;
Update update = 108;
Project project = 109;
UpdateConfig update_config = 110;
DataReplacement data_replacement = 111;
UpdateMemWalState update_mem_wal_state = 112;
Clone clone = 113;
UpdateBases update_bases = 114;
DataOverlay data_overlay = 115;
}
// Fields 200/202 (`blob_append` / `blob_overwrite`) previously represented blob dataset ops.
reserved 200, 202;
reserved "blob_append", "blob_overwrite";
}
lance-artifact/rust/.gitignore
+1
View File
@@ -0,0 +1 @@
.env
lance-artifact/rust/AGENTS.md
+90
View File
@@ -0,0 +1,90 @@
# Rust Guidelines
Also see [root AGENTS.md](../AGENTS.md) for cross-language standards.
## Code Style
- Use `Vec::with_capacity()` when size is known or estimable — prefer over-estimating capacity to multiple reallocations.
- Wrap large or expensive-to-clone struct fields (maps, protobuf metadata, schemas) in `Arc<T>` to avoid deep copies.
- Use `Box::pin(...)` or `.boxed()` but never both — `.boxed()` already returns `Pin<Box<...>>`.
- Remove dead code instead of adding `#[allow(dead_code)]`. Delete unused constants instead of reducing visibility.
- Use `column_by_name()` for `RecordBatch` column access in production code; use `batch["column_name"]` in tests.
- Use `PrimitiveArray::<T>::from(vec)` (zero-copy) instead of `from_iter_values(vec)` for Vec-to-PrimitiveArray conversion.
- Implement `Default` trait on config/options structs instead of standalone `default_*()` helpers.
- Place `#[cfg(test)] mod tests` as a single block at the bottom of each file — no production code after it.
- Place `use` imports at the top of the file, not inline within function bodies.
- Extract substantial new logic (bin packing, scheduling) into dedicated submodules instead of inlining into large files.
- Delete obsolete internal (`pub(crate)` / private) methods in the same PR that introduces their replacements. For public API methods, follow the deprecation path in root AGENTS.md instead.
- Choose log levels by audience: `debug!` for routine/high-frequency ops, `info!` for infrequent operator-visible state changes, `warn!` for unexpected conditions.
## Concurrency
- The closure passed to `spawn_cpu()` must only consume CPU and return — it must **never** wait on anything: **no channels** (blocking send/recv), **no I/O**, **no locks**, and no `block_on`/`.blocking_*`. The CPU pool can collapse to a single worker in resource-constrained environments (`<= 3` CPUs), so a parked closure can deadlock the whole pool with a silent 0% hang. Keep the waiting in surrounding async code and hand only the pure-CPU work to `spawn_cpu()`. Only dispatch substantial work (rule of thumb: ~100µs+ of CPU); below that the pool overhead outweighs the benefit and the work is better left inline. See the doc comment on `spawn_cpu` for the rationale.
## API Design
- Use `with_`-prefixed builder methods for optional config (e.g., `MyStruct::new(required).with_option(v)`) — don't create separate constructor variants.
- For public APIs, prefer `Into<T>` or `AsRef<T>` trait bounds for flexible inputs.
- Prefer `pub(crate)` over `pub` for crate-internal items. Use `pub use` re-exports for the actual public API surface.
- Use enums instead of magic numbers for format versions, variant types, and discriminators — leverage exhaustive `match`.
- Use strongly-typed structs instead of `HashMap<String, String>` in APIs — convert to strings only at serialization boundaries.
- Keep `RowAddr` (physical fragment+offset) and `RowId` (stable logical identifier) as distinct types — never raw `u64` for both.
- Use `RowAddress` from `lance-core/src/utils/address.rs` instead of raw bitwise operations on row addresses.
- Use `RowAddrTreeMap`/`RoaringBitmap` instead of `Vec<Range<u64>>` for physical row selections.
- Use logical row counts (`num_rows()`) instead of `physical_rows` for user-facing metrics — subtract deletions.
- Keep traits minimal — only core abstraction methods. Move helpers to standalone functions and config to struct fields.
- Get column/field types from schema metadata — never materialize data rows just to inspect types.
- Use stable, versioned serialization formats for persistent storage (e.g., index files) — avoid unstable cross-version formats.
- Use Arrow's type-safe access (`ArrayAccessor` trait bounds, `as_*_array` helpers) instead of `arrow::compute::cast` + `downcast_ref`. Prefer `_opt` variants (e.g., `as_string_opt`) unless the data type has already been verified.
- In `lance-io/`, use single-syscall writes for local filesystem I/O — don't reuse cloud multipart upload machinery.
## Error Handling
- Never use `.unwrap()`, `.expect()`, `panic!()`, or `assert!()` in library code for fallible operations — use `?` with `Result` and proper error types. Reserve `.unwrap()` for tests only.
- Avoid bare `.unwrap()`; use `if let`, `match`, `let ... else`, `?`, or combinators. Never `.is_none()` followed by `.unwrap()`. If unavoidable, use `.expect("reason")`.
- Return `LanceError::NotSupported` instead of `todo!()` or `unimplemented!()` for unsupported code paths. Test with `Result::Err` assertions, not `#[should_panic]`.
- Match `Error` variant to root cause: `Error::invalid_input` for caller data issues, `Error::corrupt_file` for format/integrity issues, `Error::not_found` for missing resources, `Error::io` for I/O failures.
- Include full context in error messages — variable names, values, sizes, types, indices. Not generic messages like `"Invalid chunk size"`.
- Use `checked_add`/`checked_mul` instead of `wrapping_add`/`wrapping_mul` for counters and IDs — return an error on overflow.
- Prefer `debug_assert!` over `assert!` for non-safety invariants; reserve `assert!` for conditions preventing data corruption. Always include descriptive messages.
- Don't silently guard against impossible conditions — use `debug_assert!`, return an explicit error, or remove the check.
- Log warnings on best-effort/cleanup failures instead of silently swallowing or propagating errors.
- Log warnings for silent no-ops (skipped operations); omit warnings before errors since the error message is sufficient.
- Avoid `unwrap_or(default)` on map lookups for required config params — use `.ok_or_else(|| Error::...)` and verify key names match between serialization and deserialization.
- Advance all parallel iterators before any `continue` branches — early exits that skip `.next()` calls cause misalignment.
- Bind `iter.next()` with `let Some(x) = iter.next() else { ... }` — never call `.next()` twice to check-then-use.
## Naming
- Reserve `_`-prefixed names for truly unused bindings — if a variable is read, drop the underscore.
- Prefix boolean variables with `is_` or `has_` instead of ambiguous `with_` or bare adjectives.
- Name booleans so `false` (zero/`Default::default()`) is the desired default — use `disable_*` instead of `enable_*` when the feature should be on by default.
- Name functions to match their actual scope — e.g., `handle_partition_system_columns` not `handle_system_columns` if only a subset is handled.
## Testing
- Use `record_batch!()` from `arrow_array` to construct `RecordBatch` in tests instead of manual Schema/Arc/try_new boilerplate.
- Use `gen_batch()` builder API (`.col()`, `.into_reader_rows()`) for test data setup instead of manual Arrow construction.
- Use `.try_into_batch()` instead of `.try_into_stream().try_collect()` for scanner results in tests.
- Use plain `"memory://"` URIs in tests — no atomic counters or unique suffixes needed.
- Assert on both error variant (`assert!(matches!(error, ErrorType::Variant { .. }))`) and message content — don't just check `is_err()`.
## Documentation
- Add doc comments to public API elements that convey semantic meaning, valid values, and effects — don't restate type signatures.
- Document enum variant doc comments with behavioral semantics, not just labels. For numeric parameters, state whether it's an id, count, index, etc.
- Add doc comments to magic constants, thresholds, and non-obvious transformation functions — explain what the value represents and why it was chosen.
- Comment fallback/guard code paths with when they trigger and why they exist.
- Ensure doc comments match actual semantics — distinguish mutates-in-place (`&mut self`) from returns-new-value.
- Use explicit forward-looking language (`TODO`, `FIXME`) in comments to distinguish current behavior from planned changes.
- Document the semantic meaning of both present and absent states for `Option<T>` fields.
- Use precise domain terminology — avoid ambiguous abbreviations (e.g., "FIXED" vs "fixed-width") or incorrect terms (e.g., "fields" when meaning "fragments").
## lance-encoding
Performance-critical encoding/decoding paths have additional requirements:
- Hoist loop-invariant conditionals out of hot loops — branch once outside, then use separate loop bodies or monomorphized variants.
- Pre-allocate single contiguous buffers. Default to `buf.resize(len, 0)` for safe initialization; reserve `Vec::with_capacity` + `unsafe { set_len() }` for measured hot paths only, with a `// SAFETY:` comment explaining why the buffer will be fully initialized before read (e.g., immediately followed by `read_exact`).
- Use `spawn_cpu()` only at the async-to-CPU boundary (e.g., FSST, decompression, batch materialization) — never nest redundant `spawn_cpu()` calls.
- Use `expect_next()` and similar utility methods instead of inlining `None`-checks with error returns.
lance-artifact/rust/CLAUDE.md
Symlink
+1
View File
@@ -0,0 +1 @@
AGENTS.md
lance-artifact/rust/CONTRIBUTING.md
+41
View File
@@ -0,0 +1,41 @@
# Contributing to Rust
To format and lint Rust code:
```bash
cargo fmt --all
cargo clippy --all-features --tests --benches
```
## Core Format
The core format is implemented in Rust under the `rust` directory. Once you've setup Rust you can build the core format with:
```bash
cargo build
```
This builds the debug build. For the optimized release build:
```bash
cargo build -r
```
To run the Rust unit tests:
```bash
cargo test
```
If you're working on a performance related feature, benchmarks can be run via:
```bash
cargo bench
```
If you want detailed logging and full backtraces, set the following environment variables.
More details can be found [here](../docs/src/guide/performance.md#logging).
```bash
LANCE_LOG=info RUST_BACKTRACE=FULL <cargo-commands>
```
lance-artifact/rust/README.md
+2
View File
@@ -0,0 +1,2 @@
# Lance Rust Workspace
Where core rust code lance lives
lance-artifact/rust/arrow-scalar/Cargo.toml
+31
View File
@@ -0,0 +1,31 @@
[package]
name = "lance-arrow-scalar"
version = "58.0.0"
edition.workspace = true
authors.workspace = true
license.workspace = true
repository.workspace = true
description = "Arrow scalar type with Ord, Hash, and Eq support"
keywords.workspace = true
categories.workspace = true
rust-version.workspace = true
readme = "README.md"
[dependencies]
# Note: this is a core crate and we should aim to keep this dependency list
# as minimal as possible.
arrow-array = { workspace = true }
arrow-buffer = { workspace = true }
arrow-cast = { workspace = true }
arrow-data = { workspace = true }
arrow-row = { workspace = true }
arrow-schema = { workspace = true }
half = { workspace = true }
[dev-dependencies]
arrow-ord = { workspace = true }
proptest = { workspace = true }
rstest = { workspace = true }
[lints]
workspace = true
lance-artifact/rust/arrow-scalar/README.md
+57
View File
@@ -0,0 +1,57 @@
# lance-arrow-scalar
A scalar type backed by Apache Arrow arrays with `Ord`, `Hash`, and `Eq` support.
## Overview
`ArrowScalar` wraps a single-element Arrow array and provides comparison and hashing operations by leveraging Apache Arrow's `OwnedRow` representation. This ensures:
- **Correct total ordering** for all Arrow types
- **Proper NaN handling** for floating-point values
- **Consistent null ordering**
- **O(1) comparisons** via cached row bytes
## Features
- `Eq`, `Ord`, and `Hash` traits for Arrow scalar values
- Support for all Arrow data types
- Serde serialization/deserialization support
- Zero-copy conversion from Arrow arrays
## Usage
Add to your `Cargo.toml`:
```toml
[dependencies]
lance-arrow-scalar = "57.0.0"
```
Then use in your code:
```rust
use lance_arrow_scalar::ArrowScalar;
// Create from primitive types
let a = ArrowScalar::from(42i32);
let b = ArrowScalar::from(100i32);
assert!(a < b);
// Create from strings
let s1 = ArrowScalar::from("hello");
let s2 = ArrowScalar::from("world");
assert!(s1 < s2);
// Use in collections
use std::collections::HashMap;
let mut map = HashMap::new();
map.insert(ArrowScalar::from("key"), ArrowScalar::from(123));
```
## Cross-Type Comparison
Comparing scalars of different data types produces an arbitrary but consistent ordering based on the underlying row bytes. This allows scalars to be used as keys in sorted collections regardless of type, though the ordering across types is not semantically meaningful.
## Implementation Details
Comparisons and hashing are delegated to [`arrow_row::OwnedRow`], which provides efficient byte-level operations. The row representation is cached at construction time, making all comparison and hashing operations O(1).
lance-artifact/rust/arrow-scalar/src/convert.rs
+105
View File
@@ -0,0 +1,105 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright The Lance Authors
use std::sync::Arc;
use arrow_array::*;
use half::f16;
use crate::ArrowScalar;
macro_rules! impl_from_primitive {
($native_ty:ty, $array_ty:ty) => {
impl From<$native_ty> for ArrowScalar {
fn from(value: $native_ty) -> Self {
let array: ArrayRef = Arc::new(<$array_ty>::from(vec![value]));
Self::try_from_array(array).expect("single-element primitive array is always valid")
}
}
};
}
impl_from_primitive!(i8, Int8Array);
impl_from_primitive!(i16, Int16Array);
impl_from_primitive!(i32, Int32Array);
impl_from_primitive!(i64, Int64Array);
impl_from_primitive!(u8, UInt8Array);
impl_from_primitive!(u16, UInt16Array);
impl_from_primitive!(u32, UInt32Array);
impl_from_primitive!(u64, UInt64Array);
impl_from_primitive!(f32, Float32Array);
impl_from_primitive!(f64, Float64Array);
impl From<bool> for ArrowScalar {
fn from(value: bool) -> Self {
let array: ArrayRef = Arc::new(BooleanArray::from(vec![value]));
Self::try_from_array(array).expect("single-element boolean array is always valid")
}
}
impl From<f16> for ArrowScalar {
fn from(value: f16) -> Self {
let array: ArrayRef = Arc::new(Float16Array::from(vec![value]));
Self::try_from_array(array).expect("single-element f16 array is always valid")
}
}
impl From<&str> for ArrowScalar {
fn from(value: &str) -> Self {
let array: ArrayRef = Arc::new(StringArray::from(vec![value]));
Self::try_from_array(array).expect("single-element string array is always valid")
}
}
impl From<String> for ArrowScalar {
fn from(value: String) -> Self {
Self::from(value.as_str())
}
}
impl From<&[u8]> for ArrowScalar {
fn from(value: &[u8]) -> Self {
let array: ArrayRef = Arc::new(BinaryArray::from_vec(vec![value]));
Self::try_from_array(array).expect("single-element binary array is always valid")
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn test_from_primitives() {
let s = ArrowScalar::from(42i32);
assert!(!s.is_null());
assert_eq!(format!("{s}"), "42");
let s = ArrowScalar::from(1.5f64);
assert!(!s.is_null());
let s = ArrowScalar::from(true);
assert_eq!(format!("{s}"), "true");
}
#[test]
fn test_from_string_types() {
let s = ArrowScalar::from("hello");
assert_eq!(format!("{s}"), "hello");
let s = ArrowScalar::from(String::from("world"));
assert_eq!(format!("{s}"), "world");
}
#[test]
fn test_from_binary() {
let bytes: &[u8] = &[0xDE, 0xAD];
let s = ArrowScalar::from(bytes);
assert!(!s.is_null());
}
#[test]
fn test_from_f16() {
let s = ArrowScalar::from(f16::from_f32(1.5));
assert!(!s.is_null());
}
}
lance-artifact/rust/arrow-scalar/src/lib.rs
+621
View File
@@ -0,0 +1,621 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright The Lance Authors
//! A scalar type backed by a single-element Arrow array with [`Ord`], [`Hash`],
//! and [`Eq`] support.
//!
//! Comparisons and hashing are delegated to [`arrow_row::OwnedRow`], which
//! provides a correct total ordering for all Arrow types (including proper NaN
//! handling for floats and null ordering).
mod convert;
pub mod serde;
use std::cmp::Ordering;
use std::fmt;
use std::hash::{Hash, Hasher};
use std::sync::Arc;
use arrow_array::cast::AsArray;
use arrow_array::types::{Float16Type, Float32Type, Float64Type};
use arrow_array::{ArrayRef, make_array, new_null_array};
use arrow_cast::display::ArrayFormatter;
use arrow_data::transform::MutableArrayData;
use arrow_row::{OwnedRow, RowConverter, SortField};
use arrow_schema::{ArrowError, DataType};
type Result<T> = std::result::Result<T, ArrowError>;
/// A scalar value backed by a length-1 Arrow array.
///
/// `ArrowScalar` provides [`Eq`], [`Ord`], and [`Hash`] by caching an
/// [`OwnedRow`] at construction time. This means comparisons and hashing are
/// O(1) row-byte operations rather than per-type dispatch.
///
/// # Cross-type comparison
///
/// Comparing scalars of different data types produces an arbitrary but
/// consistent ordering based on the underlying row bytes. This is intentional
/// — it allows scalars to be used as keys in sorted collections regardless of
/// type, but the ordering across types is not semantically meaningful.
///
/// # Examples
///
/// ```
/// use lance_arrow_scalar::ArrowScalar;
///
/// let a = ArrowScalar::from(1i32);
/// let b = ArrowScalar::from(2i32);
/// assert!(a < b);
///
/// let c = ArrowScalar::from("hello");
/// assert_eq!(c, ArrowScalar::from("hello"));
/// ```
pub struct ArrowScalar {
array: ArrayRef,
row: OwnedRow,
}
impl ArrowScalar {
/// Create a scalar by extracting the element at `offset` from `array`.
pub fn try_new(array: &ArrayRef, offset: usize) -> Result<Self> {
if offset >= array.len() {
return Err(ArrowError::InvalidArgumentError(
"Scalar index out of bounds".to_string(),
));
}
let data = array.to_data();
let mut mutable = MutableArrayData::new(vec![&data], true, 1);
mutable.extend(0, offset, offset + 1);
let single = make_array(mutable.freeze());
Self::try_from_array(single)
}
/// Create a scalar from a length-1 array.
pub fn try_from_array(array: ArrayRef) -> Result<Self> {
if array.len() != 1 {
return Err(ArrowError::InvalidArgumentError(format!(
"ArrowScalar requires a length-1 array, got length {}",
array.len()
)));
}
let row = Self::compute_row(&array)?;
Ok(Self { array, row })
}
/// Create a null scalar of the given data type.
pub fn new_null(data_type: &DataType) -> Result<Self> {
Self::try_from_array(new_null_array(data_type, 1))
}
fn compute_row(array: &ArrayRef) -> Result<OwnedRow> {
let sort_field = SortField::new(array.data_type().clone());
let converter = RowConverter::new(vec![sort_field])?;
let rows = converter.convert_columns(&[Arc::clone(array)])?;
Ok(rows.row(0).owned())
}
/// Returns a reference to the underlying length-1 array.
pub fn as_array(&self) -> &ArrayRef {
&self.array
}
/// Returns the data type of this scalar.
pub fn data_type(&self) -> &DataType {
self.array.data_type()
}
/// Returns `true` if this scalar is null.
pub fn is_null(&self) -> bool {
self.array.null_count() == 1
}
/// Returns `true` if this scalar is a non-null floating-point NaN.
///
/// ```
/// use lance_arrow_scalar::ArrowScalar;
///
/// assert!(ArrowScalar::from(f32::NAN).is_nan());
/// assert!(!ArrowScalar::from(1.0f32).is_nan());
/// assert!(!ArrowScalar::from(1i32).is_nan());
/// ```
pub fn is_nan(&self) -> bool {
if self.is_null() {
return false;
}
match self.data_type() {
DataType::Float16 => self.array.as_primitive::<Float16Type>().value(0).is_nan(),
DataType::Float32 => self.array.as_primitive::<Float32Type>().value(0).is_nan(),
DataType::Float64 => self.array.as_primitive::<Float64Type>().value(0).is_nan(),
_ => false,
}
}
}
impl PartialEq for ArrowScalar {
fn eq(&self, other: &Self) -> bool {
self.row == other.row
}
}
impl Eq for ArrowScalar {}
impl PartialOrd for ArrowScalar {
fn partial_cmp(&self, other: &Self) -> Option<Ordering> {
Some(self.cmp(other))
}
}
impl Ord for ArrowScalar {
fn cmp(&self, other: &Self) -> Ordering {
self.row.cmp(&other.row)
}
}
impl Hash for ArrowScalar {
fn hash<H: Hasher>(&self, state: &mut H) {
self.row.hash(state);
}
}
impl fmt::Display for ArrowScalar {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
if self.is_null() {
return write!(f, "null");
}
let formatter =
ArrayFormatter::try_new(&self.array, &Default::default()).map_err(|_| fmt::Error)?;
write!(f, "{}", formatter.value(0))
}
}
impl fmt::Debug for ArrowScalar {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
write!(f, "ArrowScalar({}: {})", self.data_type(), self)
}
}
impl Clone for ArrowScalar {
fn clone(&self) -> Self {
Self {
array: Arc::clone(&self.array),
row: self.row.clone(),
}
}
}
#[cfg(test)]
mod tests {
use std::collections::{BTreeSet, HashSet};
use std::sync::Arc;
use arrow_array::*;
use rstest::rstest;
use super::*;
#[test]
fn test_try_new_extracts_element() {
let array: ArrayRef = Arc::new(Int32Array::from(vec![10, 20, 30]));
let s = ArrowScalar::try_new(&array, 1).unwrap();
assert_eq!(format!("{s}"), "20");
}
#[test]
fn test_try_new_out_of_bounds() {
let array: ArrayRef = Arc::new(Int32Array::from(vec![1]));
assert!(ArrowScalar::try_new(&array, 5).is_err());
}
#[test]
fn test_try_from_array_wrong_length() {
let array: ArrayRef = Arc::new(Int32Array::from(vec![1, 2]));
assert!(ArrowScalar::try_from_array(array).is_err());
}
#[test]
fn test_equality() {
let a = ArrowScalar::from(42i32);
let b = ArrowScalar::from(42i32);
let c = ArrowScalar::from(99i32);
assert_eq!(a, b);
assert_ne!(a, c);
}
#[test]
fn test_ordering() {
let a = ArrowScalar::from(1i32);
let b = ArrowScalar::from(2i32);
let c = ArrowScalar::from(3i32);
assert!(a < b);
assert!(b < c);
assert_eq!(a.cmp(&a), Ordering::Equal);
}
#[test]
fn test_hash_consistent_with_eq() {
use std::hash::DefaultHasher;
let a = ArrowScalar::from(42i32);
let b = ArrowScalar::from(42i32);
let hash_a = {
let mut h = DefaultHasher::new();
a.hash(&mut h);
h.finish()
};
let hash_b = {
let mut h = DefaultHasher::new();
b.hash(&mut h);
h.finish()
};
assert_eq!(hash_a, hash_b);
}
#[test]
fn test_in_hashset() {
let mut set = HashSet::new();
set.insert(ArrowScalar::from(1i32));
set.insert(ArrowScalar::from(2i32));
set.insert(ArrowScalar::from(1i32));
assert_eq!(set.len(), 2);
}
#[test]
fn test_in_btreeset() {
let mut set = BTreeSet::new();
set.insert(ArrowScalar::from(3i32));
set.insert(ArrowScalar::from(1i32));
set.insert(ArrowScalar::from(2i32));
let values: Vec<_> = set.iter().map(|s| format!("{s}")).collect();
assert_eq!(values, vec!["1", "2", "3"]);
}
#[test]
fn test_null_scalar() {
let array: ArrayRef = Arc::new(Int32Array::from(vec![None]));
let s = ArrowScalar::try_from_array(array).unwrap();
assert!(s.is_null());
assert_eq!(format!("{s}"), "null");
}
#[test]
fn test_null_sorts_first() {
let null_scalar = {
let array: ArrayRef = Arc::new(Int32Array::from(vec![None]));
ArrowScalar::try_from_array(array).unwrap()
};
let value_scalar = ArrowScalar::from(0i32);
assert!(null_scalar < value_scalar);
}
#[rstest]
#[case::float_nan(
ArrowScalar::from(f64::NAN),
ArrowScalar::from(f64::INFINITY),
Ordering::Greater
)]
#[case::float_normal(ArrowScalar::from(1.0f64), ArrowScalar::from(2.0f64), Ordering::Less)]
fn test_float_ordering(
#[case] a: ArrowScalar,
#[case] b: ArrowScalar,
#[case] expected: Ordering,
) {
assert_eq!(a.cmp(&b), expected);
}
#[rstest]
#[case::float16_nan(ArrowScalar::from(half::f16::NAN), true)]
#[case::float32_nan(ArrowScalar::from(f32::NAN), true)]
#[case::float64_nan(ArrowScalar::from(f64::NAN), true)]
#[case::float64_finite(ArrowScalar::from(1.0f64), false)]
#[case::int32(ArrowScalar::from(1i32), false)]
fn test_is_nan(#[case] scalar: ArrowScalar, #[case] expected: bool) {
assert_eq!(scalar.is_nan(), expected);
}
#[test]
fn test_null_is_not_nan() {
let array: ArrayRef = Arc::new(Float64Array::from(vec![None]));
let scalar = ArrowScalar::try_from_array(array).unwrap();
assert!(!scalar.is_nan());
}
#[test]
fn test_display_string() {
let s = ArrowScalar::from("hello world");
assert_eq!(format!("{s}"), "hello world");
}
#[test]
fn test_debug() {
let s = ArrowScalar::from(42i32);
let debug = format!("{s:?}");
assert!(debug.contains("ArrowScalar"));
assert!(debug.contains("42"));
}
#[test]
fn test_clone() {
let a = ArrowScalar::from(42i32);
let b = a.clone();
assert_eq!(a, b);
}
#[test]
fn test_data_type() {
let s = ArrowScalar::from(42i32);
assert_eq!(s.data_type(), &DataType::Int32);
}
#[test]
fn test_boolean_roundtrip() {
let t = ArrowScalar::from(true);
let f = ArrowScalar::from(false);
assert_eq!(t.data_type(), &DataType::Boolean);
assert!(!t.is_null());
assert_eq!(format!("{t}"), "true");
assert_eq!(format!("{f}"), "false");
// Extract from multi-element array
let array: ArrayRef = Arc::new(BooleanArray::from(vec![true, false, true]));
let s = ArrowScalar::try_new(&array, 1).unwrap();
assert_eq!(format!("{s}"), "false");
assert_eq!(s.data_type(), &DataType::Boolean);
}
#[test]
fn test_boolean_equality_and_ordering() {
let t1 = ArrowScalar::from(true);
let t2 = ArrowScalar::from(true);
let f1 = ArrowScalar::from(false);
assert_eq!(t1, t2);
assert_ne!(t1, f1);
// false < true in arrow row encoding
assert!(f1 < t1);
}
#[test]
fn test_boolean_null() {
let array: ArrayRef = Arc::new(BooleanArray::from(vec![None]));
let scalar = ArrowScalar::try_from_array(array).unwrap();
assert!(scalar.is_null());
assert_eq!(scalar.data_type(), &DataType::Boolean);
assert_eq!(format!("{scalar}"), "null");
// null sorts before false
let f = ArrowScalar::from(false);
assert!(scalar < f);
}
#[test]
fn test_string_view_roundtrip() {
let array: ArrayRef = Arc::new(StringViewArray::from(vec![
"hello world, this is a long string view",
]));
let scalar = ArrowScalar::try_from_array(array).unwrap();
assert_eq!(scalar.data_type(), &DataType::Utf8View);
assert!(!scalar.is_null());
assert_eq!(
format!("{scalar}"),
"hello world, this is a long string view"
);
// Extract from multi-element array
let array: ArrayRef = Arc::new(StringViewArray::from(vec!["alpha", "beta", "gamma"]));
let s = ArrowScalar::try_new(&array, 1).unwrap();
assert_eq!(format!("{s}"), "beta");
assert_eq!(s.data_type(), &DataType::Utf8View);
}
#[test]
fn test_binary_view_roundtrip() {
let values: Vec<&[u8]> = vec![b"\xDE\xAD\xBE\xEF"];
let array: ArrayRef = Arc::new(BinaryViewArray::from(values));
let scalar = ArrowScalar::try_from_array(array).unwrap();
assert_eq!(scalar.data_type(), &DataType::BinaryView);
assert!(!scalar.is_null());
// Extract from multi-element array
let values: Vec<&[u8]> = vec![b"aaa", b"bbb", b"ccc"];
let array: ArrayRef = Arc::new(BinaryViewArray::from(values));
let s = ArrowScalar::try_new(&array, 2).unwrap();
assert_eq!(s.data_type(), &DataType::BinaryView);
}
#[test]
fn test_string_view_equality_and_ordering() {
let mk = |s: &str| {
let array: ArrayRef = Arc::new(StringViewArray::from(vec![s]));
ArrowScalar::try_from_array(array).unwrap()
};
let a = mk("apple");
let b = mk("apple");
let c = mk("banana");
assert_eq!(a, b);
assert_ne!(a, c);
assert!(a < c);
}
#[test]
fn test_binary_view_equality_and_ordering() {
let mk = |b: &[u8]| {
let values: Vec<&[u8]> = vec![b];
let array: ArrayRef = Arc::new(BinaryViewArray::from(values));
ArrowScalar::try_from_array(array).unwrap()
};
let a = mk(b"\x01\x02");
let b = mk(b"\x01\x02");
let c = mk(b"\x01\x03");
assert_eq!(a, b);
assert_ne!(a, c);
assert!(a < c);
}
#[test]
fn test_string_view_in_collections() {
let mk = |s: &str| {
let array: ArrayRef = Arc::new(StringViewArray::from(vec![s]));
ArrowScalar::try_from_array(array).unwrap()
};
let mut hset = HashSet::new();
hset.insert(mk("foo"));
hset.insert(mk("bar"));
hset.insert(mk("foo"));
assert_eq!(hset.len(), 2);
let mut bset = BTreeSet::new();
bset.insert(mk("cherry"));
bset.insert(mk("apple"));
bset.insert(mk("banana"));
let sorted: Vec<_> = bset.iter().map(|s| format!("{s}")).collect();
assert_eq!(sorted, vec!["apple", "banana", "cherry"]);
}
#[test]
fn test_string_view_null() {
let array: ArrayRef = Arc::new(StringViewArray::from(vec![Option::<&str>::None]));
let scalar = ArrowScalar::try_from_array(array).unwrap();
assert!(scalar.is_null());
assert_eq!(scalar.data_type(), &DataType::Utf8View);
assert_eq!(format!("{scalar}"), "null");
}
#[test]
fn test_binary_view_null() {
let array: ArrayRef = Arc::new(BinaryViewArray::from(vec![Option::<&[u8]>::None]));
let scalar = ArrowScalar::try_from_array(array).unwrap();
assert!(scalar.is_null());
assert_eq!(scalar.data_type(), &DataType::BinaryView);
}
#[test]
fn test_cross_type_comparison_is_consistent() {
let int_scalar = ArrowScalar::from(42i32);
let str_scalar = ArrowScalar::from("hello");
// The ordering is arbitrary but must be consistent
let ord1 = int_scalar.cmp(&str_scalar);
let ord2 = int_scalar.cmp(&str_scalar);
assert_eq!(ord1, ord2);
// And the reverse should be opposite
assert_eq!(str_scalar.cmp(&int_scalar), ord1.reverse());
}
}
#[cfg(test)]
mod prop_tests {
use std::sync::Arc;
use arrow_array::*;
use arrow_ord::sort::sort;
use arrow_schema::SortOptions;
use proptest::prelude::*;
use super::ArrowScalar;
/// Generate an arbitrary Arrow array of a randomly chosen type, including
/// nulls. Covers primitives, booleans, string/binary types and their view
/// variants.
fn arbitrary_array() -> BoxedStrategy<ArrayRef> {
let len = 0..=100usize;
prop_oneof![
// --- integer types ---
proptest::collection::vec(proptest::option::of(any::<i8>()), len.clone())
.prop_map(|v| Arc::new(Int8Array::from(v)) as ArrayRef),
proptest::collection::vec(proptest::option::of(any::<i16>()), len.clone())
.prop_map(|v| Arc::new(Int16Array::from(v)) as ArrayRef),
proptest::collection::vec(proptest::option::of(any::<i32>()), len.clone())
.prop_map(|v| Arc::new(Int32Array::from(v)) as ArrayRef),
proptest::collection::vec(proptest::option::of(any::<i64>()), len.clone())
.prop_map(|v| Arc::new(Int64Array::from(v)) as ArrayRef),
proptest::collection::vec(proptest::option::of(any::<u8>()), len.clone())
.prop_map(|v| Arc::new(UInt8Array::from(v)) as ArrayRef),
proptest::collection::vec(proptest::option::of(any::<u16>()), len.clone())
.prop_map(|v| Arc::new(UInt16Array::from(v)) as ArrayRef),
proptest::collection::vec(proptest::option::of(any::<u32>()), len.clone())
.prop_map(|v| Arc::new(UInt32Array::from(v)) as ArrayRef),
proptest::collection::vec(proptest::option::of(any::<u64>()), len.clone())
.prop_map(|v| Arc::new(UInt64Array::from(v)) as ArrayRef),
// --- float types ---
proptest::collection::vec(proptest::option::of(any::<f32>()), len.clone())
.prop_map(|v| Arc::new(Float32Array::from(v)) as ArrayRef),
proptest::collection::vec(proptest::option::of(any::<f64>()), len.clone())
.prop_map(|v| Arc::new(Float64Array::from(v)) as ArrayRef),
// --- boolean ---
proptest::collection::vec(proptest::option::of(any::<bool>()), len.clone())
.prop_map(|v| Arc::new(BooleanArray::from(v)) as ArrayRef),
// --- string types ---
proptest::collection::vec(proptest::option::of(any::<String>()), len.clone()).prop_map(
|v| {
let refs: Vec<Option<&str>> = v.iter().map(|o| o.as_deref()).collect();
Arc::new(StringArray::from(refs)) as ArrayRef
}
),
proptest::collection::vec(proptest::option::of(any::<String>()), len.clone()).prop_map(
|v| {
let refs: Vec<Option<&str>> = v.iter().map(|o| o.as_deref()).collect();
Arc::new(LargeStringArray::from(refs)) as ArrayRef
}
),
proptest::collection::vec(proptest::option::of(any::<String>()), len.clone()).prop_map(
|v| {
let refs: Vec<Option<&str>> = v.iter().map(|o| o.as_deref()).collect();
Arc::new(StringViewArray::from(refs)) as ArrayRef
}
),
// --- binary types ---
proptest::collection::vec(
proptest::option::of(proptest::collection::vec(any::<u8>(), 0..50)),
len.clone(),
)
.prop_map(|v| {
let refs: Vec<Option<&[u8]>> = v.iter().map(|o| o.as_deref()).collect();
Arc::new(BinaryArray::from(refs)) as ArrayRef
}),
proptest::collection::vec(
proptest::option::of(proptest::collection::vec(any::<u8>(), 0..50)),
len.clone(),
)
.prop_map(|v| {
let refs: Vec<Option<&[u8]>> = v.iter().map(|o| o.as_deref()).collect();
Arc::new(LargeBinaryArray::from(refs)) as ArrayRef
}),
proptest::collection::vec(
proptest::option::of(proptest::collection::vec(any::<u8>(), 0..50)),
len,
)
.prop_map(|v| {
let refs: Vec<Option<&[u8]>> = v.iter().map(|o| o.as_deref()).collect();
Arc::new(BinaryViewArray::from(refs)) as ArrayRef
}),
]
.boxed()
}
proptest::proptest! {
#[test]
fn sorted_array_produces_sorted_scalars(array in arbitrary_array()) {
let sorted = sort(
&array,
Some(SortOptions { descending: false, nulls_first: true }),
)
.unwrap();
let scalars: Vec<ArrowScalar> = (0..sorted.len())
.map(|i| ArrowScalar::try_new(&sorted, i).unwrap())
.collect();
for i in 1..scalars.len() {
prop_assert!(
scalars[i - 1] <= scalars[i],
"scalar[{}] ({:?}) should be <= scalar[{}] ({:?})",
i - 1, scalars[i - 1], i, scalars[i],
);
}
}
}
}
lance-artifact/rust/arrow-scalar/src/serde.rs
+558
View File
@@ -0,0 +1,558 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright The Lance Authors
//! Binary serialization for [`ArrowScalar`].
//!
//! Default format (with type prefix):
//! ```text
//! | varint: format_string_len | raw: format_string_bytes |
//! | varint: null_flag (0 = non-null, 1 = null) |
//! | varint: num_buffers | (only if non-null)
//! | varint: buffer_0_len | ... | varint: buffer_{n-1}_len | (only if non-null)
//! | raw: buffer_0 bytes | ... | raw: buffer_{n-1} bytes | (only if non-null)
//! ```
//!
//! The format string uses the
//! [Arrow C Data Interface](https://arrow.apache.org/docs/format/CDataInterface.html#data-type-description-format-strings)
//! encoding. Use [`EncodeOptions`] / [`DecodeOptions`] to omit the type prefix
//! when the caller already knows the data type.
use std::borrow::Cow;
use std::sync::Arc;
use arrow_array::make_array;
use arrow_buffer::Buffer;
use arrow_data::ArrayDataBuilder;
use arrow_schema::{ArrowError, DataType, IntervalUnit, TimeUnit};
use crate::ArrowScalar;
type Result<T> = std::result::Result<T, ArrowError>;
/// Options for [`ArrowScalar::encode_with_options`].
pub struct EncodeOptions {
/// When `true` (the default), the Arrow C Data Interface format string
/// for the scalar's data type is prepended as a varint-length-prefixed
/// UTF-8 string. Set to `false` to omit the type prefix (the caller
/// must then supply the `DataType` at decode time).
pub include_data_type: bool,
}
impl Default for EncodeOptions {
fn default() -> Self {
Self {
include_data_type: true,
}
}
}
/// Options for [`ArrowScalar::decode_with_options`].
#[derive(Default)]
pub struct DecodeOptions<'a> {
/// When `Some`, the data type is taken from this value and the encoded
/// bytes are assumed to contain no type prefix. When `None` (the
/// default), the data type is read from the encoded format-string prefix.
pub data_type: Option<&'a DataType>,
}
/// Encode a `u64` as a variable-length integer (LEB128).
///
/// Values below 128 use a single byte; the maximum encoding is 10 bytes.
pub fn encode_varint(out: &mut Vec<u8>, mut value: u64) {
loop {
let byte = (value & 0x7F) as u8;
value >>= 7;
if value == 0 {
out.push(byte);
return;
}
out.push(byte | 0x80);
}
}
/// Decode a variable-length integer (LEB128) from `buf` at the given `offset`.
///
/// On success, `offset` is advanced past the consumed bytes.
pub fn decode_varint(buf: &[u8], offset: &mut usize) -> Result<u64> {
let mut result: u64 = 0;
let mut shift = 0u32;
loop {
if *offset >= buf.len() {
return Err(ArrowError::InvalidArgumentError(
"Invalid varint: unexpected EOF".to_string(),
));
}
let byte = buf[*offset];
*offset += 1;
result |= u64::from(byte & 0x7F) << shift;
if byte & 0x80 == 0 {
return Ok(result);
}
shift += 7;
if shift >= 64 {
return Err(ArrowError::InvalidArgumentError(
"Invalid varint: too many bytes".to_string(),
));
}
}
}
/// Convert a [`DataType`] to its Arrow C Data Interface format string.
///
/// Only non-nested types are supported (nested types are already rejected by
/// [`ArrowScalar::encode`]).
fn data_type_to_format_string(dtype: &DataType) -> Result<Cow<'static, str>> {
match dtype {
DataType::Null => Ok("n".into()),
DataType::Boolean => Ok("b".into()),
DataType::Int8 => Ok("c".into()),
DataType::UInt8 => Ok("C".into()),
DataType::Int16 => Ok("s".into()),
DataType::UInt16 => Ok("S".into()),
DataType::Int32 => Ok("i".into()),
DataType::UInt32 => Ok("I".into()),
DataType::Int64 => Ok("l".into()),
DataType::UInt64 => Ok("L".into()),
DataType::Float16 => Ok("e".into()),
DataType::Float32 => Ok("f".into()),
DataType::Float64 => Ok("g".into()),
DataType::Binary => Ok("z".into()),
DataType::LargeBinary => Ok("Z".into()),
DataType::Utf8 => Ok("u".into()),
DataType::LargeUtf8 => Ok("U".into()),
DataType::BinaryView => Ok("vz".into()),
DataType::Utf8View => Ok("vu".into()),
DataType::FixedSizeBinary(n) => Ok(Cow::Owned(format!("w:{n}"))),
DataType::Decimal32(p, s) => Ok(Cow::Owned(format!("d:{p},{s},32"))),
DataType::Decimal64(p, s) => Ok(Cow::Owned(format!("d:{p},{s},64"))),
DataType::Decimal128(p, s) => Ok(Cow::Owned(format!("d:{p},{s}"))),
DataType::Decimal256(p, s) => Ok(Cow::Owned(format!("d:{p},{s},256"))),
DataType::Date32 => Ok("tdD".into()),
DataType::Date64 => Ok("tdm".into()),
DataType::Time32(TimeUnit::Second) => Ok("tts".into()),
DataType::Time32(TimeUnit::Millisecond) => Ok("ttm".into()),
DataType::Time64(TimeUnit::Microsecond) => Ok("ttu".into()),
DataType::Time64(TimeUnit::Nanosecond) => Ok("ttn".into()),
DataType::Timestamp(TimeUnit::Second, None) => Ok("tss:".into()),
DataType::Timestamp(TimeUnit::Millisecond, None) => Ok("tsm:".into()),
DataType::Timestamp(TimeUnit::Microsecond, None) => Ok("tsu:".into()),
DataType::Timestamp(TimeUnit::Nanosecond, None) => Ok("tsn:".into()),
DataType::Timestamp(TimeUnit::Second, Some(tz)) => Ok(Cow::Owned(format!("tss:{tz}"))),
DataType::Timestamp(TimeUnit::Millisecond, Some(tz)) => Ok(Cow::Owned(format!("tsm:{tz}"))),
DataType::Timestamp(TimeUnit::Microsecond, Some(tz)) => Ok(Cow::Owned(format!("tsu:{tz}"))),
DataType::Timestamp(TimeUnit::Nanosecond, Some(tz)) => Ok(Cow::Owned(format!("tsn:{tz}"))),
DataType::Duration(TimeUnit::Second) => Ok("tDs".into()),
DataType::Duration(TimeUnit::Millisecond) => Ok("tDm".into()),
DataType::Duration(TimeUnit::Microsecond) => Ok("tDu".into()),
DataType::Duration(TimeUnit::Nanosecond) => Ok("tDn".into()),
DataType::Interval(IntervalUnit::YearMonth) => Ok("tiM".into()),
DataType::Interval(IntervalUnit::DayTime) => Ok("tiD".into()),
DataType::Interval(IntervalUnit::MonthDayNano) => Ok("tin".into()),
other => Err(ArrowError::InvalidArgumentError(format!(
"Cannot encode data type as format string: {other:?}"
))),
}
}
/// Parse an Arrow C Data Interface format string back to a [`DataType`].
///
/// Only non-nested types are supported.
fn format_string_to_data_type(fmt: &str) -> Result<DataType> {
match fmt {
"n" => Ok(DataType::Null),
"b" => Ok(DataType::Boolean),
"c" => Ok(DataType::Int8),
"C" => Ok(DataType::UInt8),
"s" => Ok(DataType::Int16),
"S" => Ok(DataType::UInt16),
"i" => Ok(DataType::Int32),
"I" => Ok(DataType::UInt32),
"l" => Ok(DataType::Int64),
"L" => Ok(DataType::UInt64),
"e" => Ok(DataType::Float16),
"f" => Ok(DataType::Float32),
"g" => Ok(DataType::Float64),
"z" => Ok(DataType::Binary),
"Z" => Ok(DataType::LargeBinary),
"u" => Ok(DataType::Utf8),
"U" => Ok(DataType::LargeUtf8),
"vz" => Ok(DataType::BinaryView),
"vu" => Ok(DataType::Utf8View),
"tdD" => Ok(DataType::Date32),
"tdm" => Ok(DataType::Date64),
"tts" => Ok(DataType::Time32(TimeUnit::Second)),
"ttm" => Ok(DataType::Time32(TimeUnit::Millisecond)),
"ttu" => Ok(DataType::Time64(TimeUnit::Microsecond)),
"ttn" => Ok(DataType::Time64(TimeUnit::Nanosecond)),
"tDs" => Ok(DataType::Duration(TimeUnit::Second)),
"tDm" => Ok(DataType::Duration(TimeUnit::Millisecond)),
"tDu" => Ok(DataType::Duration(TimeUnit::Microsecond)),
"tDn" => Ok(DataType::Duration(TimeUnit::Nanosecond)),
"tiM" => Ok(DataType::Interval(IntervalUnit::YearMonth)),
"tiD" => Ok(DataType::Interval(IntervalUnit::DayTime)),
"tin" => Ok(DataType::Interval(IntervalUnit::MonthDayNano)),
other => {
let parts: Vec<&str> = other.splitn(2, ':').collect();
match parts.as_slice() {
["w", num_bytes] => {
let n = num_bytes.parse::<i32>().map_err(|_| {
ArrowError::InvalidArgumentError(
"FixedSizeBinary requires an integer byte count".to_string(),
)
})?;
Ok(DataType::FixedSizeBinary(n))
}
["d", extra] => {
let dec_parts: Vec<&str> = extra.splitn(3, ',').collect();
match dec_parts.as_slice() {
[precision, scale] => {
let p = precision.parse::<u8>().map_err(|_| {
ArrowError::InvalidArgumentError(
"Decimal requires an integer precision".to_string(),
)
})?;
let s = scale.parse::<i8>().map_err(|_| {
ArrowError::InvalidArgumentError(
"Decimal requires an integer scale".to_string(),
)
})?;
Ok(DataType::Decimal128(p, s))
}
[precision, scale, bits] => {
let p = precision.parse::<u8>().map_err(|_| {
ArrowError::InvalidArgumentError(
"Decimal requires an integer precision".to_string(),
)
})?;
let s = scale.parse::<i8>().map_err(|_| {
ArrowError::InvalidArgumentError(
"Decimal requires an integer scale".to_string(),
)
})?;
match *bits {
"32" => Ok(DataType::Decimal32(p, s)),
"64" => Ok(DataType::Decimal64(p, s)),
"128" => Ok(DataType::Decimal128(p, s)),
"256" => Ok(DataType::Decimal256(p, s)),
_ => Err(ArrowError::InvalidArgumentError(format!(
"Unsupported decimal bit width: {bits}"
))),
}
}
_ => Err(ArrowError::InvalidArgumentError(format!(
"Invalid decimal format string: d:{extra}"
))),
}
}
["tss", ""] => Ok(DataType::Timestamp(TimeUnit::Second, None)),
["tsm", ""] => Ok(DataType::Timestamp(TimeUnit::Millisecond, None)),
["tsu", ""] => Ok(DataType::Timestamp(TimeUnit::Microsecond, None)),
["tsn", ""] => Ok(DataType::Timestamp(TimeUnit::Nanosecond, None)),
["tss", tz] => Ok(DataType::Timestamp(TimeUnit::Second, Some(Arc::from(*tz)))),
["tsm", tz] => Ok(DataType::Timestamp(
TimeUnit::Millisecond,
Some(Arc::from(*tz)),
)),
["tsu", tz] => Ok(DataType::Timestamp(
TimeUnit::Microsecond,
Some(Arc::from(*tz)),
)),
["tsn", tz] => Ok(DataType::Timestamp(
TimeUnit::Nanosecond,
Some(Arc::from(*tz)),
)),
_ => Err(ArrowError::InvalidArgumentError(format!(
"Unsupported format string: {other:?}"
))),
}
}
}
}
impl ArrowScalar {
/// Serialize this scalar to a self-describing binary representation.
///
/// The data type is encoded as a format-string prefix so that
/// [`decode`](Self::decode) can reconstruct the scalar without external
/// type information. Use [`encode_with_options`](Self::encode_with_options)
/// to omit the prefix when the caller already knows the type.
///
/// Only non-nested scalars are supported. Null scalars are encoded as a
/// null flag with no buffer data.
pub fn encode(&self) -> Result<Vec<u8>> {
self.encode_with_options(&EncodeOptions::default())
}
/// Serialize this scalar with the given [`EncodeOptions`].
pub fn encode_with_options(&self, options: &EncodeOptions) -> Result<Vec<u8>> {
let array = self.as_array();
let data = array.to_data();
if !data.child_data().is_empty() {
return Err(ArrowError::InvalidArgumentError(
"Cannot encode nested scalar".to_string(),
));
}
let mut out = Vec::with_capacity(64);
if options.include_data_type {
let fmt = data_type_to_format_string(array.data_type())?;
encode_varint(&mut out, fmt.len() as u64);
out.extend_from_slice(fmt.as_bytes());
}
if self.is_null() {
encode_varint(&mut out, 1); // null_flag = 1
} else {
encode_varint(&mut out, 0); // null_flag = 0
let buffers = data.buffers();
encode_varint(&mut out, buffers.len() as u64);
for b in buffers {
encode_varint(&mut out, b.len() as u64);
}
for b in buffers {
out.extend_from_slice(b.as_slice());
}
}
Ok(out)
}
/// Deserialize a scalar from the self-describing binary representation
/// produced by [`encode`](Self::encode).
///
/// The data type is read from the format-string prefix in the encoded
/// bytes. Use [`decode_with_options`](Self::decode_with_options) to supply
/// the type externally when the prefix was omitted at encode time.
pub fn decode(buf: &[u8]) -> Result<Self> {
Self::decode_with_options(buf, &DecodeOptions::default())
}
/// Deserialize a scalar with the given [`DecodeOptions`].
pub fn decode_with_options(buf: &[u8], options: &DecodeOptions) -> Result<Self> {
let mut offset = 0;
let data_type = match options.data_type {
Some(dt) => dt.clone(),
None => {
let fmt_len = decode_varint(buf, &mut offset)? as usize;
if offset + fmt_len > buf.len() {
return Err(ArrowError::InvalidArgumentError(
"Invalid scalar buffer: unexpected EOF reading format string".to_string(),
));
}
let fmt_str = std::str::from_utf8(&buf[offset..offset + fmt_len]).map_err(|e| {
ArrowError::InvalidArgumentError(format!(
"Invalid format string: not valid UTF-8: {e}"
))
})?;
offset += fmt_len;
format_string_to_data_type(fmt_str)?
}
};
let null_flag = decode_varint(buf, &mut offset)?;
if null_flag == 1 {
if offset != buf.len() {
return Err(ArrowError::InvalidArgumentError(
"Invalid scalar buffer: trailing bytes after null flag".to_string(),
));
}
return Self::new_null(&data_type);
}
let num_buffers = decode_varint(buf, &mut offset)? as usize;
let mut buffer_lens = Vec::with_capacity(num_buffers);
for _ in 0..num_buffers {
buffer_lens.push(decode_varint(buf, &mut offset)? as usize);
}
let mut buffers = Vec::with_capacity(num_buffers);
for len in &buffer_lens {
if offset + len > buf.len() {
return Err(ArrowError::InvalidArgumentError(
"Invalid scalar buffer: unexpected EOF".to_string(),
));
}
buffers.push(Buffer::from_vec(buf[offset..offset + len].to_vec()));
offset += len;
}
if offset != buf.len() {
return Err(ArrowError::InvalidArgumentError(
"Invalid scalar buffer: trailing bytes".to_string(),
));
}
let mut builder = ArrayDataBuilder::new(data_type).len(1).null_count(0);
for b in buffers {
builder = builder.add_buffer(b);
}
let array = make_array(builder.build()?);
Self::try_from_array(array)
}
}
#[cfg(test)]
mod tests {
use std::sync::Arc;
use arrow_array::{
ArrayRef, BinaryViewArray, Int32Array, StringArray, StringViewArray,
TimestampMicrosecondArray,
};
use arrow_schema::DataType;
use rstest::rstest;
use super::*;
use crate::ArrowScalar;
#[test]
fn test_varint_roundtrip() {
for value in [0u64, 1, 127, 128, 16383, 16384, u64::MAX] {
let mut buf = Vec::new();
encode_varint(&mut buf, value);
let mut offset = 0;
let decoded = decode_varint(&buf, &mut offset).unwrap();
assert_eq!(decoded, value);
assert_eq!(offset, buf.len());
}
}
#[test]
fn test_varint_small_is_one_byte() {
let mut buf = Vec::new();
encode_varint(&mut buf, 42);
assert_eq!(buf.len(), 1);
assert_eq!(buf[0], 42);
}
#[rstest]
#[case::int32(Arc::new(Int32Array::from(vec![42])) as ArrayRef)]
#[case::string(Arc::new(StringArray::from(vec!["hello"])) as ArrayRef)]
#[case::string_view(Arc::new(StringViewArray::from(vec!["hello world, long string view"])) as ArrayRef)]
#[case::binary_view(Arc::new(BinaryViewArray::from(vec![b"\xDE\xAD\xBE\xEF".as_ref()])) as ArrayRef)]
fn test_encode_decode_roundtrip(#[case] array: ArrayRef) {
let scalar = ArrowScalar::try_from_array(array).unwrap();
let encoded = scalar.encode().unwrap();
let decoded = ArrowScalar::decode(&encoded).unwrap();
assert_eq!(scalar, decoded);
assert_eq!(scalar.data_type(), decoded.data_type());
}
#[rstest]
#[case::int32(Arc::new(Int32Array::from(vec![42])) as ArrayRef, DataType::Int32)]
#[case::string(Arc::new(StringArray::from(vec!["hello"])) as ArrayRef, DataType::Utf8)]
#[case::string_view(Arc::new(StringViewArray::from(vec!["hello view"])) as ArrayRef, DataType::Utf8View)]
#[case::binary_view(Arc::new(BinaryViewArray::from(vec![b"\xCA\xFE".as_ref()])) as ArrayRef, DataType::BinaryView)]
fn test_encode_decode_without_type_prefix(#[case] array: ArrayRef, #[case] dt: DataType) {
let scalar = ArrowScalar::try_from_array(array).unwrap();
let opts = EncodeOptions {
include_data_type: false,
};
let encoded = scalar.encode_with_options(&opts).unwrap();
let decode_opts = DecodeOptions {
data_type: Some(&dt),
};
let decoded = ArrowScalar::decode_with_options(&encoded, &decode_opts).unwrap();
assert_eq!(scalar, decoded);
}
#[test]
fn test_null_encode_decode_roundtrip() {
let array: ArrayRef = Arc::new(Int32Array::from(vec![None]));
let scalar = ArrowScalar::try_from_array(array).unwrap();
assert!(scalar.is_null());
let encoded = scalar.encode().unwrap();
let decoded = ArrowScalar::decode(&encoded).unwrap();
assert!(decoded.is_null());
assert_eq!(decoded.data_type(), &DataType::Int32);
assert_eq!(scalar, decoded);
}
#[test]
fn test_null_encode_decode_without_type_prefix() {
let array: ArrayRef = Arc::new(StringArray::from(vec![Option::<&str>::None]));
let scalar = ArrowScalar::try_from_array(array).unwrap();
let opts = EncodeOptions {
include_data_type: false,
};
let encoded = scalar.encode_with_options(&opts).unwrap();
let decode_opts = DecodeOptions {
data_type: Some(&DataType::Utf8),
};
let decoded = ArrowScalar::decode_with_options(&encoded, &decode_opts).unwrap();
assert!(decoded.is_null());
assert_eq!(decoded.data_type(), &DataType::Utf8);
}
#[test]
fn test_decode_trailing_bytes() {
let scalar = ArrowScalar::from(42i32);
let mut encoded = scalar.encode().unwrap();
encoded.push(0xFF);
assert!(ArrowScalar::decode(&encoded).is_err());
}
#[test]
fn test_encoded_bytes_contain_format_prefix() {
let scalar = ArrowScalar::from(42i32);
let encoded = scalar.encode().unwrap();
// First byte is varint length of format string "i" (length 1)
assert_eq!(encoded[0], 1);
// Second byte is the format string itself
assert_eq!(encoded[1], b'i');
}
#[rstest]
#[case::null(DataType::Null, "n")]
#[case::boolean(DataType::Boolean, "b")]
#[case::int8(DataType::Int8, "c")]
#[case::uint8(DataType::UInt8, "C")]
#[case::int16(DataType::Int16, "s")]
#[case::uint16(DataType::UInt16, "S")]
#[case::int32(DataType::Int32, "i")]
#[case::uint32(DataType::UInt32, "I")]
#[case::int64(DataType::Int64, "l")]
#[case::uint64(DataType::UInt64, "L")]
#[case::float16(DataType::Float16, "e")]
#[case::float32(DataType::Float32, "f")]
#[case::float64(DataType::Float64, "g")]
#[case::binary(DataType::Binary, "z")]
#[case::large_binary(DataType::LargeBinary, "Z")]
#[case::utf8(DataType::Utf8, "u")]
#[case::large_utf8(DataType::LargeUtf8, "U")]
#[case::binary_view(DataType::BinaryView, "vz")]
#[case::utf8_view(DataType::Utf8View, "vu")]
#[case::date32(DataType::Date32, "tdD")]
#[case::date64(DataType::Date64, "tdm")]
#[case::fixed_size_binary(DataType::FixedSizeBinary(16), "w:16")]
#[case::decimal128(DataType::Decimal128(10, 2), "d:10,2")]
#[case::decimal256(DataType::Decimal256(38, 10), "d:38,10,256")]
#[case::timestamp_us_utc(
DataType::Timestamp(TimeUnit::Microsecond, Some(Arc::from("UTC"))),
"tsu:UTC"
)]
#[case::timestamp_ns_none(DataType::Timestamp(TimeUnit::Nanosecond, None), "tsn:")]
#[case::duration_s(DataType::Duration(TimeUnit::Second), "tDs")]
#[case::interval_ym(DataType::Interval(IntervalUnit::YearMonth), "tiM")]
fn test_format_string_roundtrip(#[case] dt: DataType, #[case] expected_fmt: &str) {
let fmt = data_type_to_format_string(&dt).unwrap();
assert_eq!(fmt.as_ref(), expected_fmt);
let roundtripped = format_string_to_data_type(&fmt).unwrap();
assert_eq!(roundtripped, dt);
}
#[test]
fn test_timestamp_with_tz_roundtrip() {
let array: ArrayRef = Arc::new(
TimestampMicrosecondArray::from(vec![1_000_000]).with_timezone("America/New_York"),
);
let scalar = ArrowScalar::try_from_array(array).unwrap();
let encoded = scalar.encode().unwrap();
let decoded = ArrowScalar::decode(&encoded).unwrap();
assert_eq!(scalar, decoded);
assert_eq!(scalar.data_type(), decoded.data_type());
}
}
lance-artifact/rust/arrow-stats/Cargo.toml
+25
View File
@@ -0,0 +1,25 @@
[package]
name = "lance-arrow-stats"
version = "58.0.0"
edition.workspace = true
authors.workspace = true
license.workspace = true
repository.workspace = true
description = "Statistics accumulator for Arrow arrays (min, max, null_count, nan_count)"
keywords.workspace = true
categories.workspace = true
rust-version.workspace = true
readme = "README.md"
[dependencies]
arrow-array = { workspace = true }
arrow-schema = { workspace = true }
lance-arrow-scalar = { workspace = true }
[dev-dependencies]
arrow-select = { workspace = true }
proptest = { workspace = true }
rstest = { workspace = true }
[lints]
workspace = true
lance-artifact/rust/arrow-stats/README.md
+62
View File
@@ -0,0 +1,62 @@
# lance-arrow-stats
Statistics accumulator for [Apache Arrow](https://arrow.apache.org/) arrays.
Computes min, max, null count, NaN count, and buffer memory usage over one or
more batches of Arrow data. Designed for use in Lance's columnar storage layer
where page-level statistics drive predicate pushdown and query planning.
## Usage
```rust
use arrow_array::{Int32Array, ArrayRef};
use lance_arrow_stats::StatisticsAccumulator;
use arrow_schema::DataType;
use std::sync::Arc;
let mut acc = StatisticsAccumulator::new(&DataType::Int32);
let batch: ArrayRef = Arc::new(Int32Array::from(vec![Some(3), None, Some(1), Some(4)]));
acc.update(&batch).unwrap();
let stats = acc.finish();
assert_eq!(stats.null_count, 1);
```
## Tracked Statistics
| Statistic | Description |
| --------------- | -------------------------------------------------------- |
| `min` | Minimum non-null, non-NaN value (`ArrowScalar`) |
| `max` | Maximum non-null, non-NaN value (`ArrowScalar`) |
| `null_count` | Total number of null values |
| `nan_count` | Total NaN values (float and float-list types only) |
| `item_nulls` | Null items inside list entries (list types only) |
| `buffer_memory` | Total Arrow buffer memory in bytes |
## Supported Types
- **Numeric** &mdash; Int8–Int64, UInt8–UInt64, Float16/32/64
- **Temporal** &mdash; Date32/64, Time32/64, Timestamp, Duration
- **Boolean**
- **String** &mdash; Utf8, LargeUtf8
- **Binary** &mdash; Binary, LargeBinary
- **List** &mdash; List, LargeList, FixedSizeList (computes stats over items)
Dictionary, run-end encoded, and view types are accepted but min/max will be
`None`.
## Merging
Accumulators of the same data type can be merged, which is useful for combining
statistics computed in parallel across different pages or files:
```rust
use lance_arrow_stats::StatisticsAccumulator;
use arrow_schema::DataType;
let mut a = StatisticsAccumulator::new(&DataType::Float32);
let mut b = StatisticsAccumulator::new(&DataType::Float32);
// ... update each with different batches ...
a.merge(&b).unwrap();
```
lance-artifact/rust/arrow-stats/proptest-regressions/lib.txt
+8
View File
@@ -0,0 +1,8 @@
# Seeds for failure cases proptest has generated in the past. It is
# automatically read and these particular cases re-run before any
# novel cases are generated.
#
# It is recommended to check this file in to source control so that
# everyone who runs the test benefits from these saved cases.
cc 81b0445f36fa8f491c1fb3162f51b61c8be140d5b2a1e792c42b4bdb7f1b6a62 # shrinks to values = [0.0, -0.0]
cc 8651fce939497f33c6dafd842937d95965af97833bfbbd10df30d5ea00dbd07d # shrinks to values = [Some(0.0), Some(-0.0)]
lance-artifact/rust/arrow-stats/src/lib.rs
+1294
View File
File diff suppressed because it is too large Load Diff
lance-artifact/rust/arrow-stats/src/nan.rs
+32
View File
@@ -0,0 +1,32 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright The Lance Authors
use arrow_array::cast::AsArray;
use arrow_array::types::{Float16Type, Float32Type, Float64Type};
use arrow_array::{Array, ArrayRef};
macro_rules! count_nans_typed {
($array:expr, $arrow_type:ty) => {{
let typed = $array.as_primitive::<$arrow_type>();
let mut count = 0u64;
for i in 0..typed.len() {
if !typed.is_null(i) && typed.value(i).is_nan() {
count += 1;
}
}
count
}};
}
/// Count the number of non-null NaN values in an array.
///
/// Returns 0 for non-float types.
pub fn count_nans(array: &ArrayRef) -> u64 {
use arrow_schema::DataType::*;
match array.data_type() {
Float16 => count_nans_typed!(array, Float16Type),
Float32 => count_nans_typed!(array, Float32Type),
Float64 => count_nans_typed!(array, Float64Type),
_ => 0,
}
}
lance-artifact/rust/compression/bitpacking/Cargo.toml
+24
View File
@@ -0,0 +1,24 @@
[package]
name = "lance-bitpacking"
version.workspace = true
edition.workspace = true
authors.workspace = true
license.workspace = true
readme.workspace = true
repository.workspace = true
description = "Vendored copy of https://github.com/spiraldb/fastlanes for use in Lance"
keywords.workspace = true
categories.workspace = true
rust-version.workspace = true
[dependencies]
arrayref = "0.3"
crunchy = "0.2"
paste = "1"
seq-macro = "0.3"
[dev-dependencies]
bitpacking = { workspace = true, features = ["bitpacker4x"] }
[lints]
workspace = true
lance-artifact/rust/compression/bitpacking/src/bitpacker_internal/bitpacker4x.rs
+820
View File
@@ -0,0 +1,820 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright The Lance Authors
use super::BitPacker;
use crate::bitpacker_internal::{Available, UnsafeBitPacker};
const BLOCK_LEN: usize = 32 * 4;
#[cfg(target_arch = "x86_64")]
mod sse3 {
use super::BLOCK_LEN;
use crate::bitpacker_internal::Available;
use std::arch::x86_64::__m128i as DataType;
use std::arch::x86_64::_mm_and_si128 as op_and;
use std::arch::x86_64::_mm_lddqu_si128 as load_unaligned;
use std::arch::x86_64::_mm_or_si128 as op_or;
use std::arch::x86_64::_mm_set1_epi32 as set1;
use std::arch::x86_64::_mm_slli_epi32 as left_shift_32;
use std::arch::x86_64::_mm_srli_epi32 as right_shift_32;
use std::arch::x86_64::_mm_storeu_si128 as store_unaligned;
use std::arch::x86_64::{
_mm_add_epi32, _mm_cvtsi128_si32, _mm_shuffle_epi32, _mm_slli_si128, _mm_srli_si128,
_mm_sub_epi32,
};
#[allow(non_snake_case)]
#[inline]
unsafe fn or_collapse_to_u32(accumulator: DataType) -> u32 {
let a__b__c__d_ = accumulator;
let ______a__b_ = _mm_srli_si128(a__b__c__d_, 8);
let a__b__ca_db = op_or(a__b__c__d_, ______a__b_);
let ___a__b__ca = _mm_srli_si128(a__b__ca_db, 4);
let _______cadb = op_or(a__b__ca_db, ___a__b__ca);
_mm_cvtsi128_si32(_______cadb) as u32
}
#[target_feature(enable = "sse3")]
unsafe fn compute_delta(curr: DataType, prev: DataType) -> DataType {
_mm_sub_epi32(
curr,
op_or(_mm_slli_si128(curr, 4), _mm_srli_si128(prev, 12)),
)
}
#[target_feature(enable = "sse3")]
#[allow(non_snake_case)]
#[inline]
unsafe fn integrate_delta(prev: DataType, delta: DataType) -> DataType {
let offset = _mm_shuffle_epi32(prev, 0xff);
let a__b__c__d_ = delta;
let ______a__b_ = _mm_slli_si128(delta, 8);
let a__b__ca_db = _mm_add_epi32(______a__b_, a__b__c__d_);
let ___a__b__ca = _mm_slli_si128(a__b__ca_db, 4);
let a_ab_abc_abcd: DataType = _mm_add_epi32(___a__b__ca, a__b__ca_db);
_mm_add_epi32(offset, a_ab_abc_abcd)
}
#[target_feature(enable = "sse3")]
#[inline]
unsafe fn add(left: DataType, right: DataType) -> DataType {
_mm_add_epi32(left, right)
}
unsafe fn sub(left: DataType, right: DataType) -> DataType {
_mm_sub_epi32(left, right)
}
declare_bitpacker!(target_feature(enable = "sse3"));
impl Available for UnsafeBitPackerImpl {
fn available() -> bool {
is_x86_feature_detected!("sse3")
}
}
}
#[cfg(all(target_arch = "aarch64", target_endian = "little"))]
mod neon {
use super::BLOCK_LEN;
use crate::bitpacker_internal::Available;
use std::arch::aarch64::{
uint32x4_t, vaddq_u32, vandq_u32, vdupq_n_u32, vextq_u32, vgetq_lane_u32, vld1q_u32,
vorrq_u32, vshlq_n_u32, vshrq_n_u32, vst1q_u32, vsubq_u32,
};
pub(crate) type DataType = uint32x4_t;
#[inline]
/// Creates a vector with all elements set to `el`.
unsafe fn set1(el: i32) -> DataType {
vdupq_n_u32(el as u32)
}
#[inline]
unsafe fn right_shift_32<const N: i32>(el: DataType) -> DataType {
const {
assert!(N >= 0);
assert!(N <= 32);
}
// We unroll here because vshrq_n_u32 only accepts constants from 1 to 32.
match N {
0 => el,
1 => vshrq_n_u32::<1>(el),
2 => vshrq_n_u32::<2>(el),
3 => vshrq_n_u32::<3>(el),
4 => vshrq_n_u32::<4>(el),
5 => vshrq_n_u32::<5>(el),
6 => vshrq_n_u32::<6>(el),
7 => vshrq_n_u32::<7>(el),
8 => vshrq_n_u32::<8>(el),
9 => vshrq_n_u32::<9>(el),
10 => vshrq_n_u32::<10>(el),
11 => vshrq_n_u32::<11>(el),
12 => vshrq_n_u32::<12>(el),
13 => vshrq_n_u32::<13>(el),
14 => vshrq_n_u32::<14>(el),
15 => vshrq_n_u32::<15>(el),
16 => vshrq_n_u32::<16>(el),
17 => vshrq_n_u32::<17>(el),
18 => vshrq_n_u32::<18>(el),
19 => vshrq_n_u32::<19>(el),
20 => vshrq_n_u32::<20>(el),
21 => vshrq_n_u32::<21>(el),
22 => vshrq_n_u32::<22>(el),
23 => vshrq_n_u32::<23>(el),
24 => vshrq_n_u32::<24>(el),
25 => vshrq_n_u32::<25>(el),
26 => vshrq_n_u32::<26>(el),
27 => vshrq_n_u32::<27>(el),
28 => vshrq_n_u32::<28>(el),
29 => vshrq_n_u32::<29>(el),
30 => vshrq_n_u32::<30>(el),
31 => vshrq_n_u32::<31>(el),
32 => vdupq_n_u32(0),
_ => core::hint::unreachable_unchecked(),
}
}
#[inline]
unsafe fn left_shift_32<const N: i32>(el: DataType) -> DataType {
const {
assert!(N >= 0);
assert!(N <= 32);
}
// We unroll here because vshlq_n_u32 only accepts constants from 0 to 31.
match N {
0 => el,
1 => vshlq_n_u32::<1>(el),
2 => vshlq_n_u32::<2>(el),
3 => vshlq_n_u32::<3>(el),
4 => vshlq_n_u32::<4>(el),
5 => vshlq_n_u32::<5>(el),
6 => vshlq_n_u32::<6>(el),
7 => vshlq_n_u32::<7>(el),
8 => vshlq_n_u32::<8>(el),
9 => vshlq_n_u32::<9>(el),
10 => vshlq_n_u32::<10>(el),
11 => vshlq_n_u32::<11>(el),
12 => vshlq_n_u32::<12>(el),
13 => vshlq_n_u32::<13>(el),
14 => vshlq_n_u32::<14>(el),
15 => vshlq_n_u32::<15>(el),
16 => vshlq_n_u32::<16>(el),
17 => vshlq_n_u32::<17>(el),
18 => vshlq_n_u32::<18>(el),
19 => vshlq_n_u32::<19>(el),
20 => vshlq_n_u32::<20>(el),
21 => vshlq_n_u32::<21>(el),
22 => vshlq_n_u32::<22>(el),
23 => vshlq_n_u32::<23>(el),
24 => vshlq_n_u32::<24>(el),
25 => vshlq_n_u32::<25>(el),
26 => vshlq_n_u32::<26>(el),
27 => vshlq_n_u32::<27>(el),
28 => vshlq_n_u32::<28>(el),
29 => vshlq_n_u32::<29>(el),
30 => vshlq_n_u32::<30>(el),
31 => vshlq_n_u32::<31>(el),
32 => vdupq_n_u32(0),
_ => core::hint::unreachable_unchecked(),
}
}
use vorrq_u32 as op_or;
#[inline]
unsafe fn op_and(left: DataType, right: DataType) -> DataType {
vandq_u32(left, right)
}
#[inline]
unsafe fn load_unaligned(addr: *const DataType) -> DataType {
vld1q_u32(addr.cast::<u32>())
}
#[inline]
unsafe fn store_unaligned(addr: *mut DataType, data: DataType) {
vst1q_u32(addr.cast::<u32>(), data);
}
#[inline]
/// Collapses the vector by performing a bitwise OR across all lanes
unsafe fn or_collapse_to_u32(acc: DataType) -> u32 {
vgetq_lane_u32(acc, 0)
| vgetq_lane_u32(acc, 1)
| vgetq_lane_u32(acc, 2)
| vgetq_lane_u32(acc, 3)
}
unsafe fn compute_delta(curr: DataType, prev: DataType) -> DataType {
// Build a vector with [prev[3], curr[0], curr[1], curr[2]]
let prev_shifted = vextq_u32(prev, curr, 3);
vsubq_u32(curr, prev_shifted)
}
#[allow(non_snake_case)]
#[inline]
unsafe fn integrate_delta(prev: DataType, delta: DataType) -> DataType {
let base = vdupq_n_u32(vgetq_lane_u32(prev, 3));
let zero = vdupq_n_u32(0);
let a__b__c__d_ = delta;
let ______a__b_ = vextq_u32(zero, a__b__c__d_, 2);
let a__b__ca_db = vaddq_u32(______a__b_, a__b__c__d_);
let ___a__b__ca = vextq_u32(zero, a__b__ca_db, 3);
let a_ab_abc_abcd = vaddq_u32(___a__b__ca, a__b__ca_db);
vaddq_u32(base, a_ab_abc_abcd)
}
#[inline]
unsafe fn add(left: DataType, right: DataType) -> DataType {
vaddq_u32(left, right)
}
#[inline]
unsafe fn sub(left: DataType, right: DataType) -> DataType {
vsubq_u32(left, right)
}
declare_bitpacker!(target_feature(enable = "neon"));
impl Available for UnsafeBitPackerImpl {
fn available() -> bool {
std::arch::is_aarch64_feature_detected!("neon")
}
}
}
mod scalar {
use super::BLOCK_LEN;
use crate::bitpacker_internal::Available;
use std::ptr;
pub(crate) type DataType = [u32; 4];
pub(crate) fn set1(el: i32) -> DataType {
[el as u32; 4]
}
pub(crate) fn right_shift_32<const N: i32>(el: DataType) -> DataType {
[el[0] >> N, el[1] >> N, el[2] >> N, el[3] >> N]
}
pub(crate) fn left_shift_32<const N: i32>(el: DataType) -> DataType {
[el[0] << N, el[1] << N, el[2] << N, el[3] << N]
}
pub(crate) fn op_or(left: DataType, right: DataType) -> DataType {
[
left[0] | right[0],
left[1] | right[1],
left[2] | right[2],
left[3] | right[3],
]
}
pub(crate) fn op_and(left: DataType, right: DataType) -> DataType {
[
left[0] & right[0],
left[1] & right[1],
left[2] & right[2],
left[3] & right[3],
]
}
pub(crate) unsafe fn load_unaligned(addr: *const DataType) -> DataType {
ptr::read_unaligned(addr)
}
pub(crate) unsafe fn store_unaligned(addr: *mut DataType, data: DataType) {
ptr::write_unaligned(addr, data);
}
pub(crate) fn or_collapse_to_u32(accumulator: DataType) -> u32 {
(accumulator[0] | accumulator[1]) | (accumulator[2] | accumulator[3])
}
fn compute_delta(curr: DataType, prev: DataType) -> DataType {
[
curr[0].wrapping_sub(prev[3]),
curr[1].wrapping_sub(curr[0]),
curr[2].wrapping_sub(curr[1]),
curr[3].wrapping_sub(curr[2]),
]
}
fn integrate_delta(offset: DataType, delta: DataType) -> DataType {
let el0 = offset[3].wrapping_add(delta[0]);
let el1 = el0.wrapping_add(delta[1]);
let el2 = el1.wrapping_add(delta[2]);
let el3 = el2.wrapping_add(delta[3]);
[el0, el1, el2, el3]
}
pub(crate) fn add(left: DataType, right: DataType) -> DataType {
[
left[0].wrapping_add(right[0]),
left[1].wrapping_add(right[1]),
left[2].wrapping_add(right[2]),
left[3].wrapping_add(right[3]),
]
}
pub(crate) fn sub(left: DataType, right: DataType) -> DataType {
[
left[0].wrapping_sub(right[0]),
left[1].wrapping_sub(right[1]),
left[2].wrapping_sub(right[2]),
left[3].wrapping_sub(right[3]),
]
}
// The `allow(unused)` is here to put an attribute that has no effect.
//
// For other bitpacker, we enable specific CPU instruction set, but for the
// scalar bitpacker none is required.
declare_bitpacker!(allow(unused));
impl Available for UnsafeBitPackerImpl {
fn available() -> bool {
true
}
}
}
#[derive(Clone, Copy)]
enum InstructionSet {
#[cfg(target_arch = "x86_64")]
SSE3,
#[cfg(all(target_arch = "aarch64", target_endian = "little"))]
NEON,
Scalar,
}
/// `BitPacker4x` packs integers in groups of 4. This gives an opportunity
/// to leverage `SSE3` instructions to encode and decode the stream.
///
/// One block must contain `128 integers`.
#[derive(Clone, Copy)]
pub struct BitPacker4x(InstructionSet);
impl BitPacker4x {
#[cfg(target_arch = "x86_64")]
pub(crate) fn new_sse() -> Option<Self> {
sse3::UnsafeBitPackerImpl::available().then_some(BitPacker4x(InstructionSet::SSE3))
}
#[cfg(not(target_arch = "x86_64"))]
pub(crate) fn new_sse() -> Option<Self> {
None
}
#[cfg(all(target_arch = "aarch64", target_endian = "little"))]
pub(crate) fn new_neon() -> Option<Self> {
neon::UnsafeBitPackerImpl::available().then_some(BitPacker4x(InstructionSet::NEON))
}
#[cfg(not(all(target_arch = "aarch64", target_endian = "little")))]
pub(crate) fn new_neon() -> Option<Self> {
None
}
pub(crate) fn new_scalar() -> Self {
BitPacker4x(InstructionSet::Scalar)
}
}
impl BitPacker for BitPacker4x {
const BLOCK_LEN: usize = BLOCK_LEN;
fn new() -> Self {
Self::new_sse()
.or_else(Self::new_neon)
.unwrap_or_else(Self::new_scalar)
}
fn compress(&self, decompressed: &[u32], compressed: &mut [u8], num_bits: u8) -> usize {
unsafe {
match self.0 {
#[cfg(target_arch = "x86_64")]
InstructionSet::SSE3 => {
sse3::UnsafeBitPackerImpl::compress(decompressed, compressed, num_bits)
}
#[cfg(all(target_arch = "aarch64", target_endian = "little"))]
InstructionSet::NEON => {
neon::UnsafeBitPackerImpl::compress(decompressed, compressed, num_bits)
}
InstructionSet::Scalar => {
scalar::UnsafeBitPackerImpl::compress(decompressed, compressed, num_bits)
}
}
}
}
fn compress_sorted(
&self,
initial: u32,
decompressed: &[u32],
compressed: &mut [u8],
num_bits: u8,
) -> usize {
unsafe {
match self.0 {
#[cfg(target_arch = "x86_64")]
InstructionSet::SSE3 => sse3::UnsafeBitPackerImpl::compress_sorted(
initial,
decompressed,
compressed,
num_bits,
),
#[cfg(all(target_arch = "aarch64", target_endian = "little"))]
InstructionSet::NEON => neon::UnsafeBitPackerImpl::compress_sorted(
initial,
decompressed,
compressed,
num_bits,
),
InstructionSet::Scalar => scalar::UnsafeBitPackerImpl::compress_sorted(
initial,
decompressed,
compressed,
num_bits,
),
}
}
}
fn compress_strictly_sorted(
&self,
initial: Option<u32>,
decompressed: &[u32],
compressed: &mut [u8],
num_bits: u8,
) -> usize {
unsafe {
match self.0 {
#[cfg(target_arch = "x86_64")]
InstructionSet::SSE3 => sse3::UnsafeBitPackerImpl::compress_strictly_sorted(
initial,
decompressed,
compressed,
num_bits,
),
#[cfg(all(target_arch = "aarch64", target_endian = "little"))]
InstructionSet::NEON => neon::UnsafeBitPackerImpl::compress_strictly_sorted(
initial,
decompressed,
compressed,
num_bits,
),
InstructionSet::Scalar => scalar::UnsafeBitPackerImpl::compress_strictly_sorted(
initial,
decompressed,
compressed,
num_bits,
),
}
}
}
fn decompress(&self, compressed: &[u8], decompressed: &mut [u32], num_bits: u8) -> usize {
unsafe {
match self.0 {
#[cfg(target_arch = "x86_64")]
InstructionSet::SSE3 => {
sse3::UnsafeBitPackerImpl::decompress(compressed, decompressed, num_bits)
}
#[cfg(all(target_arch = "aarch64", target_endian = "little"))]
InstructionSet::NEON => {
neon::UnsafeBitPackerImpl::decompress(compressed, decompressed, num_bits)
}
InstructionSet::Scalar => {
scalar::UnsafeBitPackerImpl::decompress(compressed, decompressed, num_bits)
}
}
}
}
fn decompress_strictly_sorted(
&self,
initial: Option<u32>,
compressed: &[u8],
decompressed: &mut [u32],
num_bits: u8,
) -> usize {
unsafe {
match self.0 {
#[cfg(target_arch = "x86_64")]
InstructionSet::SSE3 => sse3::UnsafeBitPackerImpl::decompress_strictly_sorted(
initial,
compressed,
decompressed,
num_bits,
),
#[cfg(all(target_arch = "aarch64", target_endian = "little"))]
InstructionSet::NEON => neon::UnsafeBitPackerImpl::decompress_strictly_sorted(
initial,
compressed,
decompressed,
num_bits,
),
InstructionSet::Scalar => scalar::UnsafeBitPackerImpl::decompress_strictly_sorted(
initial,
compressed,
decompressed,
num_bits,
),
}
}
}
fn decompress_sorted(
&self,
initial: u32,
compressed: &[u8],
decompressed: &mut [u32],
num_bits: u8,
) -> usize {
unsafe {
match self.0 {
#[cfg(target_arch = "x86_64")]
InstructionSet::SSE3 => sse3::UnsafeBitPackerImpl::decompress_sorted(
initial,
compressed,
decompressed,
num_bits,
),
#[cfg(all(target_arch = "aarch64", target_endian = "little"))]
InstructionSet::NEON => neon::UnsafeBitPackerImpl::decompress_sorted(
initial,
compressed,
decompressed,
num_bits,
),
InstructionSet::Scalar => scalar::UnsafeBitPackerImpl::decompress_sorted(
initial,
compressed,
decompressed,
num_bits,
),
}
}
}
fn num_bits(&self, decompressed: &[u32]) -> u8 {
unsafe {
match self.0 {
#[cfg(target_arch = "x86_64")]
InstructionSet::SSE3 => sse3::UnsafeBitPackerImpl::num_bits(decompressed),
#[cfg(all(target_arch = "aarch64", target_endian = "little"))]
InstructionSet::NEON => neon::UnsafeBitPackerImpl::num_bits(decompressed),
InstructionSet::Scalar => scalar::UnsafeBitPackerImpl::num_bits(decompressed),
}
}
}
fn num_bits_sorted(&self, initial: u32, decompressed: &[u32]) -> u8 {
unsafe {
match self.0 {
#[cfg(target_arch = "x86_64")]
InstructionSet::SSE3 => {
sse3::UnsafeBitPackerImpl::num_bits_sorted(initial, decompressed)
}
#[cfg(all(target_arch = "aarch64", target_endian = "little"))]
InstructionSet::NEON => {
neon::UnsafeBitPackerImpl::num_bits_sorted(initial, decompressed)
}
InstructionSet::Scalar => {
scalar::UnsafeBitPackerImpl::num_bits_sorted(initial, decompressed)
}
}
}
}
fn num_bits_strictly_sorted(&self, initial: Option<u32>, decompressed: &[u32]) -> u8 {
unsafe {
match self.0 {
#[cfg(target_arch = "x86_64")]
InstructionSet::SSE3 => {
sse3::UnsafeBitPackerImpl::num_bits_strictly_sorted(initial, decompressed)
}
#[cfg(all(target_arch = "aarch64", target_endian = "little"))]
InstructionSet::NEON => {
neon::UnsafeBitPackerImpl::num_bits_strictly_sorted(initial, decompressed)
}
InstructionSet::Scalar => {
scalar::UnsafeBitPackerImpl::num_bits_strictly_sorted(initial, decompressed)
}
}
}
}
}
#[cfg(any(
target_arch = "x86_64",
all(target_arch = "aarch64", target_endian = "little")
))]
#[cfg(any())]
mod tests {
use super::BLOCK_LEN;
use super::scalar;
use crate::bitpacker_internal::Available;
use crate::tests::test_util_compatible;
use crate::{BitPacker, BitPacker4x};
#[cfg(target_arch = "x86_64")]
#[test]
fn test_compatible_sse3() {
use super::sse3;
if sse3::UnsafeBitPackerImpl::available() {
test_util_compatible::<scalar::UnsafeBitPackerImpl, sse3::UnsafeBitPackerImpl>(
BLOCK_LEN,
);
}
}
#[cfg(all(target_arch = "aarch64", target_endian = "little"))]
#[test]
fn test_compatible_neon() {
use super::neon;
if neon::UnsafeBitPackerImpl::available() {
test_util_compatible::<scalar::UnsafeBitPackerImpl, neon::UnsafeBitPackerImpl>(
BLOCK_LEN,
);
}
}
#[test]
fn test_delta_bit_width_32() {
let values = vec![i32::max_value() as u32 + 1; BitPacker4x::BLOCK_LEN];
let bit_packer = BitPacker4x::new();
let bit_width = bit_packer.num_bits_sorted(0, &values);
assert_eq!(bit_width, 32);
let mut block = vec![0u8; BitPacker4x::compressed_block_size(bit_width)];
bit_packer.compress_sorted(0, &values, &mut block, bit_width);
let mut decoded_values = vec![0x10101010; BitPacker4x::BLOCK_LEN];
bit_packer.decompress_sorted(0, &block, &mut decoded_values, bit_width);
assert_eq!(values, decoded_values);
}
#[test]
fn test_bit_width_32() {
let mut values = vec![i32::max_value() as u32 + 1; BitPacker4x::BLOCK_LEN];
values[0] = 0;
let bit_packer = BitPacker4x::new();
let bit_width = bit_packer.num_bits(&values);
assert_eq!(bit_width, 32);
let mut block = vec![0u8; BitPacker4x::compressed_block_size(bit_width)];
bit_packer.compress(&values, &mut block, bit_width);
let mut decoded_values = vec![0x10101010; BitPacker4x::BLOCK_LEN];
bit_packer.decompress(&block, &mut decoded_values, bit_width);
assert_eq!(values, decoded_values);
}
}
#[cfg(test)]
mod tests {
use super::{BLOCK_LEN, BitPacker4x};
use crate::bitpacker_internal::BitPacker;
use bitpacking::{BitPacker as ExternalBitPacker, BitPacker4x as ExternalBitPacker4x};
fn mask_for_width(width: u8) -> u32 {
match width {
0 => 0,
32 => u32::MAX,
_ => (1u32 << width) - 1,
}
}
fn raw_values(width: u8) -> Vec<u32> {
let mask = mask_for_width(width);
(0..BLOCK_LEN)
.map(|idx| ((idx * 17 + 3) as u32) & mask)
.collect()
}
fn sorted_values(width: u8) -> (u32, Vec<u32>) {
if width == 0 {
return (11, vec![11; BLOCK_LEN]);
}
if width == 32 {
return (0, vec![u32::MAX; BLOCK_LEN]);
}
let mask = mask_for_width(width).min(127);
let initial = 11u32;
let mut current = initial;
let values = (0..BLOCK_LEN)
.map(|idx| {
current += (idx as u32 * 7 + 1) & mask;
current
})
.collect();
(initial, values)
}
fn strictly_sorted_values(width: u8) -> (Option<u32>, Vec<u32>) {
let mask = mask_for_width(width).min(127);
let mut current = 0u32;
let values = (0..BLOCK_LEN)
.map(|idx| {
if idx == 0 {
current = 0;
} else {
current += 1 + ((idx as u32 * 5) & mask);
}
current
})
.collect();
(None, values)
}
#[test]
fn scalar_backend_matches_external_bitpacker4x() {
let scalar = BitPacker4x::new_scalar();
let external = ExternalBitPacker4x::new();
for width in 0..=32 {
let values = raw_values(width);
assert_eq!(scalar.num_bits(&values), external.num_bits(&values));
let mut actual = vec![0u8; BitPacker4x::compressed_block_size(width)];
let actual_len = scalar.compress(&values, &mut actual, width);
let mut expected = vec![0u8; ExternalBitPacker4x::compressed_block_size(width)];
let expected_len = external.compress(&values, &mut expected, width);
assert_eq!(actual_len, expected_len);
assert_eq!(actual, expected, "raw width {width}");
let mut decoded = vec![0u32; BLOCK_LEN];
assert_eq!(scalar.decompress(&actual, &mut decoded, width), actual_len);
assert_eq!(decoded, values);
let (initial, values) = sorted_values(width);
assert_eq!(
scalar.num_bits_sorted(initial, &values),
external.num_bits_sorted(initial, &values)
);
let mut actual = vec![0u8; BitPacker4x::compressed_block_size(width)];
let actual_len = scalar.compress_sorted(initial, &values, &mut actual, width);
let mut expected = vec![0u8; ExternalBitPacker4x::compressed_block_size(width)];
let expected_len = external.compress_sorted(initial, &values, &mut expected, width);
assert_eq!(actual_len, expected_len);
assert_eq!(actual, expected, "sorted width {width}");
let mut decoded = vec![0u32; BLOCK_LEN];
assert_eq!(
scalar.decompress_sorted(initial, &actual, &mut decoded, width),
actual_len
);
assert_eq!(decoded, values);
}
}
#[test]
fn scalar_backend_matches_external_strictly_sorted_bitpacker4x() {
let scalar = BitPacker4x::new_scalar();
let external = ExternalBitPacker4x::new();
for width in 0..=16 {
let (initial, values) = strictly_sorted_values(width);
let num_bits = external.num_bits_strictly_sorted(initial, &values);
assert_eq!(scalar.num_bits_strictly_sorted(initial, &values), num_bits);
let mut actual = vec![0u8; BitPacker4x::compressed_block_size(num_bits)];
let actual_len =
scalar.compress_strictly_sorted(initial, &values, &mut actual, num_bits);
let mut expected = vec![0u8; ExternalBitPacker4x::compressed_block_size(num_bits)];
let expected_len =
external.compress_strictly_sorted(initial, &values, &mut expected, num_bits);
assert_eq!(actual_len, expected_len);
assert_eq!(actual, expected, "strict width {width}");
let mut decoded = vec![0u32; BLOCK_LEN];
assert_eq!(
scalar.decompress_strictly_sorted(initial, &actual, &mut decoded, num_bits),
actual_len
);
assert_eq!(decoded, values);
}
}
}
lance-artifact/rust/compression/bitpacking/src/bitpacker_internal/bitpacker8x.rs
+872
View File
@@ -0,0 +1,872 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright The Lance Authors
use super::BitPacker;
use crate::bitpacker_internal::{Available, UnsafeBitPacker};
const BLOCK_LEN: usize = 32 * 8;
#[cfg(target_arch = "x86_64")]
mod avx2 {
use super::BLOCK_LEN;
use crate::bitpacker_internal::Available;
use std::arch::x86_64::__m256i as DataType;
use std::arch::x86_64::_mm256_and_si256 as op_and;
use std::arch::x86_64::_mm256_lddqu_si256 as load_unaligned;
use std::arch::x86_64::_mm256_or_si256 as op_or;
use std::arch::x86_64::_mm256_set1_epi32 as set1;
use std::arch::x86_64::_mm256_slli_epi32 as left_shift_32;
use std::arch::x86_64::_mm256_srli_epi32 as right_shift_32;
use std::arch::x86_64::_mm256_storeu_si256 as store_unaligned;
use std::arch::x86_64::{
_mm256_add_epi32, _mm256_extract_epi32, _mm256_permute2f128_si256, _mm256_shuffle_epi32,
_mm256_slli_si256, _mm256_srli_si256, _mm256_sub_epi32,
};
#[allow(non_snake_case)]
unsafe fn or_collapse_to_u32(accumulator: DataType) -> u32 {
let a__b__c__d__e__f__g__h_ = accumulator;
let ______a__b________e__f = _mm256_srli_si256(a__b__c__d__e__f__g__h_, 8);
let a__b__ca_db_e__f__ge_hf = op_or(a__b__c__d__e__f__g__h_, ______a__b________e__f);
let ___a__b__ca____e__f__ge = _mm256_srli_si256(a__b__ca_db_e__f__ge_hf, 4);
let _________cadb______gehf = op_or(a__b__ca_db_e__f__ge_hf, ___a__b__ca____e__f__ge);
let cadb = _mm256_extract_epi32(_________cadb______gehf, 0);
let gehf = _mm256_extract_epi32(_________cadb______gehf, 4);
(cadb | gehf) as u32
}
unsafe fn compute_delta(curr: DataType, prev: DataType) -> DataType {
let left_shift = _mm256_slli_si256(curr, 4);
let curr_shift = _mm256_srli_si256(curr, 12);
let curr_right_only = _mm256_permute2f128_si256(curr_shift, curr_shift, 8);
let prev_shift = _mm256_srli_si256(prev, 12);
let sub_left = _mm256_permute2f128_si256(prev_shift, prev_shift, 3 | (8 << 4));
let diff = op_or(left_shift, op_or(curr_right_only, sub_left));
_mm256_sub_epi32(curr, diff)
}
#[allow(non_snake_case)]
unsafe fn integrate_delta(prev: DataType, delta: DataType) -> DataType {
let offset_repeat = _mm256_shuffle_epi32(prev, 0xff);
let offset = _mm256_permute2f128_si256(offset_repeat, offset_repeat, 3 | (8 << 4));
let a__b__c__d__e__f__g__h__ = delta;
let ______a__b________e__f__ = _mm256_slli_si256(delta, 8);
let a__b__ca_db_e__f__ge_fh_ =
_mm256_add_epi32(a__b__c__d__e__f__g__h__, ______a__b________e__f__);
let ___a__b__ca____e__f__ge_ = _mm256_slli_si256(a__b__ca_db_e__f__ge_fh_, 4);
let halved_prefix_sum =
_mm256_add_epi32(___a__b__ca____e__f__ge_, a__b__ca_db_e__f__ge_fh_);
let offsetted_halved_prefix_sum = _mm256_add_epi32(halved_prefix_sum, offset);
let select_last_low = _mm256_shuffle_epi32(offsetted_halved_prefix_sum, 0xff);
let high_offset = _mm256_permute2f128_si256(select_last_low, select_last_low, 8);
_mm256_add_epi32(high_offset, offsetted_halved_prefix_sum)
}
unsafe fn add(left: DataType, right: DataType) -> DataType {
_mm256_add_epi32(left, right)
}
unsafe fn sub(left: DataType, right: DataType) -> DataType {
_mm256_sub_epi32(left, right)
}
declare_bitpacker!(target_feature(enable = "avx2"));
impl Available for UnsafeBitPackerImpl {
fn available() -> bool {
is_x86_feature_detected!("avx2")
}
}
}
#[cfg(all(target_arch = "aarch64", target_endian = "little"))]
mod neon {
use super::BLOCK_LEN;
use crate::bitpacker_internal::Available;
use std::arch::aarch64::{
uint32x4_t, vaddq_u32, vandq_u32, vdupq_n_u32, vextq_u32, vgetq_lane_u32, vld1q_u32,
vorrq_u32, vshlq_n_u32, vshrq_n_u32, vst1q_u32, vsubq_u32,
};
pub(crate) type DataType = [uint32x4_t; 2];
#[inline]
unsafe fn set1(el: i32) -> DataType {
let lanes = vdupq_n_u32(el as u32);
[lanes, lanes]
}
#[inline]
unsafe fn right_shift_32<const N: i32>(el: DataType) -> DataType {
const {
assert!(N >= 0);
assert!(N <= 32);
}
match N {
0 => el,
1 => [vshrq_n_u32::<1>(el[0]), vshrq_n_u32::<1>(el[1])],
2 => [vshrq_n_u32::<2>(el[0]), vshrq_n_u32::<2>(el[1])],
3 => [vshrq_n_u32::<3>(el[0]), vshrq_n_u32::<3>(el[1])],
4 => [vshrq_n_u32::<4>(el[0]), vshrq_n_u32::<4>(el[1])],
5 => [vshrq_n_u32::<5>(el[0]), vshrq_n_u32::<5>(el[1])],
6 => [vshrq_n_u32::<6>(el[0]), vshrq_n_u32::<6>(el[1])],
7 => [vshrq_n_u32::<7>(el[0]), vshrq_n_u32::<7>(el[1])],
8 => [vshrq_n_u32::<8>(el[0]), vshrq_n_u32::<8>(el[1])],
9 => [vshrq_n_u32::<9>(el[0]), vshrq_n_u32::<9>(el[1])],
10 => [vshrq_n_u32::<10>(el[0]), vshrq_n_u32::<10>(el[1])],
11 => [vshrq_n_u32::<11>(el[0]), vshrq_n_u32::<11>(el[1])],
12 => [vshrq_n_u32::<12>(el[0]), vshrq_n_u32::<12>(el[1])],
13 => [vshrq_n_u32::<13>(el[0]), vshrq_n_u32::<13>(el[1])],
14 => [vshrq_n_u32::<14>(el[0]), vshrq_n_u32::<14>(el[1])],
15 => [vshrq_n_u32::<15>(el[0]), vshrq_n_u32::<15>(el[1])],
16 => [vshrq_n_u32::<16>(el[0]), vshrq_n_u32::<16>(el[1])],
17 => [vshrq_n_u32::<17>(el[0]), vshrq_n_u32::<17>(el[1])],
18 => [vshrq_n_u32::<18>(el[0]), vshrq_n_u32::<18>(el[1])],
19 => [vshrq_n_u32::<19>(el[0]), vshrq_n_u32::<19>(el[1])],
20 => [vshrq_n_u32::<20>(el[0]), vshrq_n_u32::<20>(el[1])],
21 => [vshrq_n_u32::<21>(el[0]), vshrq_n_u32::<21>(el[1])],
22 => [vshrq_n_u32::<22>(el[0]), vshrq_n_u32::<22>(el[1])],
23 => [vshrq_n_u32::<23>(el[0]), vshrq_n_u32::<23>(el[1])],
24 => [vshrq_n_u32::<24>(el[0]), vshrq_n_u32::<24>(el[1])],
25 => [vshrq_n_u32::<25>(el[0]), vshrq_n_u32::<25>(el[1])],
26 => [vshrq_n_u32::<26>(el[0]), vshrq_n_u32::<26>(el[1])],
27 => [vshrq_n_u32::<27>(el[0]), vshrq_n_u32::<27>(el[1])],
28 => [vshrq_n_u32::<28>(el[0]), vshrq_n_u32::<28>(el[1])],
29 => [vshrq_n_u32::<29>(el[0]), vshrq_n_u32::<29>(el[1])],
30 => [vshrq_n_u32::<30>(el[0]), vshrq_n_u32::<30>(el[1])],
31 => [vshrq_n_u32::<31>(el[0]), vshrq_n_u32::<31>(el[1])],
32 => set1(0),
_ => core::hint::unreachable_unchecked(),
}
}
#[inline]
unsafe fn left_shift_32<const N: i32>(el: DataType) -> DataType {
const {
assert!(N >= 0);
assert!(N <= 32);
}
match N {
0 => el,
1 => [vshlq_n_u32::<1>(el[0]), vshlq_n_u32::<1>(el[1])],
2 => [vshlq_n_u32::<2>(el[0]), vshlq_n_u32::<2>(el[1])],
3 => [vshlq_n_u32::<3>(el[0]), vshlq_n_u32::<3>(el[1])],
4 => [vshlq_n_u32::<4>(el[0]), vshlq_n_u32::<4>(el[1])],
5 => [vshlq_n_u32::<5>(el[0]), vshlq_n_u32::<5>(el[1])],
6 => [vshlq_n_u32::<6>(el[0]), vshlq_n_u32::<6>(el[1])],
7 => [vshlq_n_u32::<7>(el[0]), vshlq_n_u32::<7>(el[1])],
8 => [vshlq_n_u32::<8>(el[0]), vshlq_n_u32::<8>(el[1])],
9 => [vshlq_n_u32::<9>(el[0]), vshlq_n_u32::<9>(el[1])],
10 => [vshlq_n_u32::<10>(el[0]), vshlq_n_u32::<10>(el[1])],
11 => [vshlq_n_u32::<11>(el[0]), vshlq_n_u32::<11>(el[1])],
12 => [vshlq_n_u32::<12>(el[0]), vshlq_n_u32::<12>(el[1])],
13 => [vshlq_n_u32::<13>(el[0]), vshlq_n_u32::<13>(el[1])],
14 => [vshlq_n_u32::<14>(el[0]), vshlq_n_u32::<14>(el[1])],
15 => [vshlq_n_u32::<15>(el[0]), vshlq_n_u32::<15>(el[1])],
16 => [vshlq_n_u32::<16>(el[0]), vshlq_n_u32::<16>(el[1])],
17 => [vshlq_n_u32::<17>(el[0]), vshlq_n_u32::<17>(el[1])],
18 => [vshlq_n_u32::<18>(el[0]), vshlq_n_u32::<18>(el[1])],
19 => [vshlq_n_u32::<19>(el[0]), vshlq_n_u32::<19>(el[1])],
20 => [vshlq_n_u32::<20>(el[0]), vshlq_n_u32::<20>(el[1])],
21 => [vshlq_n_u32::<21>(el[0]), vshlq_n_u32::<21>(el[1])],
22 => [vshlq_n_u32::<22>(el[0]), vshlq_n_u32::<22>(el[1])],
23 => [vshlq_n_u32::<23>(el[0]), vshlq_n_u32::<23>(el[1])],
24 => [vshlq_n_u32::<24>(el[0]), vshlq_n_u32::<24>(el[1])],
25 => [vshlq_n_u32::<25>(el[0]), vshlq_n_u32::<25>(el[1])],
26 => [vshlq_n_u32::<26>(el[0]), vshlq_n_u32::<26>(el[1])],
27 => [vshlq_n_u32::<27>(el[0]), vshlq_n_u32::<27>(el[1])],
28 => [vshlq_n_u32::<28>(el[0]), vshlq_n_u32::<28>(el[1])],
29 => [vshlq_n_u32::<29>(el[0]), vshlq_n_u32::<29>(el[1])],
30 => [vshlq_n_u32::<30>(el[0]), vshlq_n_u32::<30>(el[1])],
31 => [vshlq_n_u32::<31>(el[0]), vshlq_n_u32::<31>(el[1])],
32 => set1(0),
_ => core::hint::unreachable_unchecked(),
}
}
#[inline]
unsafe fn op_or(left: DataType, right: DataType) -> DataType {
[vorrq_u32(left[0], right[0]), vorrq_u32(left[1], right[1])]
}
#[inline]
unsafe fn op_and(left: DataType, right: DataType) -> DataType {
[vandq_u32(left[0], right[0]), vandq_u32(left[1], right[1])]
}
#[inline]
unsafe fn load_unaligned(addr: *const DataType) -> DataType {
let ptr = addr.cast::<u32>();
[vld1q_u32(ptr), vld1q_u32(ptr.add(4))]
}
#[inline]
unsafe fn store_unaligned(addr: *mut DataType, data: DataType) {
let ptr = addr.cast::<u32>();
vst1q_u32(ptr, data[0]);
vst1q_u32(ptr.add(4), data[1]);
}
#[inline]
unsafe fn or_collapse_to_u32(accumulator: DataType) -> u32 {
vgetq_lane_u32(accumulator[0], 0)
| vgetq_lane_u32(accumulator[0], 1)
| vgetq_lane_u32(accumulator[0], 2)
| vgetq_lane_u32(accumulator[0], 3)
| vgetq_lane_u32(accumulator[1], 0)
| vgetq_lane_u32(accumulator[1], 1)
| vgetq_lane_u32(accumulator[1], 2)
| vgetq_lane_u32(accumulator[1], 3)
}
#[inline]
unsafe fn compute_delta(curr: DataType, prev: DataType) -> DataType {
[
vsubq_u32(curr[0], vextq_u32(prev[1], curr[0], 3)),
vsubq_u32(curr[1], vextq_u32(curr[0], curr[1], 3)),
]
}
#[allow(non_snake_case)]
#[inline]
unsafe fn integrate_half(base: u32, delta: uint32x4_t) -> uint32x4_t {
let base = vdupq_n_u32(base);
let zero = vdupq_n_u32(0);
let a__b__c__d_ = delta;
let ______a__b_ = vextq_u32(zero, a__b__c__d_, 2);
let a__b__ca_db = vaddq_u32(______a__b_, a__b__c__d_);
let ___a__b__ca = vextq_u32(zero, a__b__ca_db, 3);
let a_ab_abc_abcd = vaddq_u32(___a__b__ca, a__b__ca_db);
vaddq_u32(base, a_ab_abc_abcd)
}
#[inline]
unsafe fn integrate_delta(prev: DataType, delta: DataType) -> DataType {
let low = integrate_half(vgetq_lane_u32(prev[1], 3), delta[0]);
let high = integrate_half(vgetq_lane_u32(low, 3), delta[1]);
[low, high]
}
#[inline]
unsafe fn add(left: DataType, right: DataType) -> DataType {
[vaddq_u32(left[0], right[0]), vaddq_u32(left[1], right[1])]
}
#[inline]
unsafe fn sub(left: DataType, right: DataType) -> DataType {
[vsubq_u32(left[0], right[0]), vsubq_u32(left[1], right[1])]
}
declare_bitpacker!(target_feature(enable = "neon"));
impl Available for UnsafeBitPackerImpl {
fn available() -> bool {
std::arch::is_aarch64_feature_detected!("neon")
}
}
}
mod scalar {
use super::BLOCK_LEN;
use crate::bitpacker_internal::Available;
use std::ptr;
pub(crate) type DataType = [u32; 8];
pub(crate) fn set1(el: i32) -> DataType {
[el as u32; 8]
}
pub(crate) fn right_shift_32<const N: i32>(el: DataType) -> DataType {
[
el[0] >> N,
el[1] >> N,
el[2] >> N,
el[3] >> N,
el[4] >> N,
el[5] >> N,
el[6] >> N,
el[7] >> N,
]
}
pub(crate) fn left_shift_32<const N: i32>(el: DataType) -> DataType {
[
el[0] << N,
el[1] << N,
el[2] << N,
el[3] << N,
el[4] << N,
el[5] << N,
el[6] << N,
el[7] << N,
]
}
pub(crate) fn op_or(left: DataType, right: DataType) -> DataType {
[
left[0] | right[0],
left[1] | right[1],
left[2] | right[2],
left[3] | right[3],
left[4] | right[4],
left[5] | right[5],
left[6] | right[6],
left[7] | right[7],
]
}
pub(crate) fn op_and(left: DataType, right: DataType) -> DataType {
[
left[0] & right[0],
left[1] & right[1],
left[2] & right[2],
left[3] & right[3],
left[4] & right[4],
left[5] & right[5],
left[6] & right[6],
left[7] & right[7],
]
}
pub(crate) unsafe fn load_unaligned(addr: *const DataType) -> DataType {
ptr::read_unaligned(addr)
}
pub(crate) unsafe fn store_unaligned(addr: *mut DataType, data: DataType) {
ptr::write_unaligned(addr, data);
}
pub(crate) fn or_collapse_to_u32(accumulator: DataType) -> u32 {
((accumulator[0] | accumulator[1]) | (accumulator[2] | accumulator[3]))
| ((accumulator[4] | accumulator[5]) | (accumulator[6] | accumulator[7]))
}
fn compute_delta(curr: DataType, prev: DataType) -> DataType {
[
curr[0].wrapping_sub(prev[7]),
curr[1].wrapping_sub(curr[0]),
curr[2].wrapping_sub(curr[1]),
curr[3].wrapping_sub(curr[2]),
curr[4].wrapping_sub(curr[3]),
curr[5].wrapping_sub(curr[4]),
curr[6].wrapping_sub(curr[5]),
curr[7].wrapping_sub(curr[6]),
]
}
fn integrate_delta(offset: DataType, delta: DataType) -> DataType {
let el0 = offset[7].wrapping_add(delta[0]);
let el1 = el0.wrapping_add(delta[1]);
let el2 = el1.wrapping_add(delta[2]);
let el3 = el2.wrapping_add(delta[3]);
let el4 = el3.wrapping_add(delta[4]);
let el5 = el4.wrapping_add(delta[5]);
let el6 = el5.wrapping_add(delta[6]);
let el7 = el6.wrapping_add(delta[7]);
[el0, el1, el2, el3, el4, el5, el6, el7]
}
pub(crate) fn add(left: DataType, right: DataType) -> DataType {
[
left[0].wrapping_add(right[0]),
left[1].wrapping_add(right[1]),
left[2].wrapping_add(right[2]),
left[3].wrapping_add(right[3]),
left[4].wrapping_add(right[4]),
left[5].wrapping_add(right[5]),
left[6].wrapping_add(right[6]),
left[7].wrapping_add(right[7]),
]
}
pub(crate) fn sub(left: DataType, right: DataType) -> DataType {
[
left[0].wrapping_sub(right[0]),
left[1].wrapping_sub(right[1]),
left[2].wrapping_sub(right[2]),
left[3].wrapping_sub(right[3]),
left[4].wrapping_sub(right[4]),
left[5].wrapping_sub(right[5]),
left[6].wrapping_sub(right[6]),
left[7].wrapping_sub(right[7]),
]
}
// The `allow(unused)` is here to put an attribute that has no effect.
//
// For other bitpackers, we enable a specific CPU instruction set, but for
// the scalar bitpacker none is required.
declare_bitpacker!(allow(unused));
impl Available for UnsafeBitPackerImpl {
fn available() -> bool {
true
}
}
}
#[derive(Clone, Copy)]
enum InstructionSet {
#[cfg(target_arch = "x86_64")]
AVX2,
#[cfg(all(target_arch = "aarch64", target_endian = "little"))]
NEON,
Scalar,
}
/// 8-wide bitpacker implementation.
///
/// One block contains 256 integers.
#[derive(Clone, Copy)]
pub struct BitPacker8x(InstructionSet);
impl BitPacker8x {
#[cfg(target_arch = "x86_64")]
pub(crate) fn new_avx2() -> Option<Self> {
avx2::UnsafeBitPackerImpl::available().then_some(BitPacker8x(InstructionSet::AVX2))
}
#[cfg(not(target_arch = "x86_64"))]
pub(crate) fn new_avx2() -> Option<Self> {
None
}
#[cfg(all(target_arch = "aarch64", target_endian = "little"))]
pub(crate) fn new_neon() -> Option<Self> {
neon::UnsafeBitPackerImpl::available().then_some(BitPacker8x(InstructionSet::NEON))
}
#[cfg(not(all(target_arch = "aarch64", target_endian = "little")))]
pub(crate) fn new_neon() -> Option<Self> {
None
}
pub(crate) fn new_scalar() -> Self {
BitPacker8x(InstructionSet::Scalar)
}
}
impl BitPacker for BitPacker8x {
const BLOCK_LEN: usize = BLOCK_LEN;
fn new() -> Self {
Self::new_avx2()
.or_else(Self::new_neon)
.unwrap_or_else(Self::new_scalar)
}
fn compress(&self, decompressed: &[u32], compressed: &mut [u8], num_bits: u8) -> usize {
unsafe {
match self.0 {
#[cfg(target_arch = "x86_64")]
InstructionSet::AVX2 => {
avx2::UnsafeBitPackerImpl::compress(decompressed, compressed, num_bits)
}
#[cfg(all(target_arch = "aarch64", target_endian = "little"))]
InstructionSet::NEON => {
neon::UnsafeBitPackerImpl::compress(decompressed, compressed, num_bits)
}
InstructionSet::Scalar => {
scalar::UnsafeBitPackerImpl::compress(decompressed, compressed, num_bits)
}
}
}
}
fn compress_sorted(
&self,
initial: u32,
decompressed: &[u32],
compressed: &mut [u8],
num_bits: u8,
) -> usize {
unsafe {
match self.0 {
#[cfg(target_arch = "x86_64")]
InstructionSet::AVX2 => avx2::UnsafeBitPackerImpl::compress_sorted(
initial,
decompressed,
compressed,
num_bits,
),
#[cfg(all(target_arch = "aarch64", target_endian = "little"))]
InstructionSet::NEON => neon::UnsafeBitPackerImpl::compress_sorted(
initial,
decompressed,
compressed,
num_bits,
),
InstructionSet::Scalar => scalar::UnsafeBitPackerImpl::compress_sorted(
initial,
decompressed,
compressed,
num_bits,
),
}
}
}
fn compress_strictly_sorted(
&self,
initial: Option<u32>,
decompressed: &[u32],
compressed: &mut [u8],
num_bits: u8,
) -> usize {
unsafe {
match self.0 {
#[cfg(target_arch = "x86_64")]
InstructionSet::AVX2 => avx2::UnsafeBitPackerImpl::compress_strictly_sorted(
initial,
decompressed,
compressed,
num_bits,
),
#[cfg(all(target_arch = "aarch64", target_endian = "little"))]
InstructionSet::NEON => neon::UnsafeBitPackerImpl::compress_strictly_sorted(
initial,
decompressed,
compressed,
num_bits,
),
InstructionSet::Scalar => scalar::UnsafeBitPackerImpl::compress_strictly_sorted(
initial,
decompressed,
compressed,
num_bits,
),
}
}
}
fn decompress(&self, compressed: &[u8], decompressed: &mut [u32], num_bits: u8) -> usize {
unsafe {
match self.0 {
#[cfg(target_arch = "x86_64")]
InstructionSet::AVX2 => {
avx2::UnsafeBitPackerImpl::decompress(compressed, decompressed, num_bits)
}
#[cfg(all(target_arch = "aarch64", target_endian = "little"))]
InstructionSet::NEON => {
neon::UnsafeBitPackerImpl::decompress(compressed, decompressed, num_bits)
}
InstructionSet::Scalar => {
scalar::UnsafeBitPackerImpl::decompress(compressed, decompressed, num_bits)
}
}
}
}
fn decompress_sorted(
&self,
initial: u32,
compressed: &[u8],
decompressed: &mut [u32],
num_bits: u8,
) -> usize {
unsafe {
match self.0 {
#[cfg(target_arch = "x86_64")]
InstructionSet::AVX2 => avx2::UnsafeBitPackerImpl::decompress_sorted(
initial,
compressed,
decompressed,
num_bits,
),
#[cfg(all(target_arch = "aarch64", target_endian = "little"))]
InstructionSet::NEON => neon::UnsafeBitPackerImpl::decompress_sorted(
initial,
compressed,
decompressed,
num_bits,
),
InstructionSet::Scalar => scalar::UnsafeBitPackerImpl::decompress_sorted(
initial,
compressed,
decompressed,
num_bits,
),
}
}
}
fn decompress_strictly_sorted(
&self,
initial: Option<u32>,
compressed: &[u8],
decompressed: &mut [u32],
num_bits: u8,
) -> usize {
unsafe {
match self.0 {
#[cfg(target_arch = "x86_64")]
InstructionSet::AVX2 => avx2::UnsafeBitPackerImpl::decompress_strictly_sorted(
initial,
compressed,
decompressed,
num_bits,
),
#[cfg(all(target_arch = "aarch64", target_endian = "little"))]
InstructionSet::NEON => neon::UnsafeBitPackerImpl::decompress_strictly_sorted(
initial,
compressed,
decompressed,
num_bits,
),
InstructionSet::Scalar => scalar::UnsafeBitPackerImpl::decompress_strictly_sorted(
initial,
compressed,
decompressed,
num_bits,
),
}
}
}
fn num_bits(&self, decompressed: &[u32]) -> u8 {
unsafe {
match self.0 {
#[cfg(target_arch = "x86_64")]
InstructionSet::AVX2 => avx2::UnsafeBitPackerImpl::num_bits(decompressed),
#[cfg(all(target_arch = "aarch64", target_endian = "little"))]
InstructionSet::NEON => neon::UnsafeBitPackerImpl::num_bits(decompressed),
InstructionSet::Scalar => scalar::UnsafeBitPackerImpl::num_bits(decompressed),
}
}
}
fn num_bits_sorted(&self, initial: u32, decompressed: &[u32]) -> u8 {
unsafe {
match self.0 {
#[cfg(target_arch = "x86_64")]
InstructionSet::AVX2 => {
avx2::UnsafeBitPackerImpl::num_bits_sorted(initial, decompressed)
}
#[cfg(all(target_arch = "aarch64", target_endian = "little"))]
InstructionSet::NEON => {
neon::UnsafeBitPackerImpl::num_bits_sorted(initial, decompressed)
}
InstructionSet::Scalar => {
scalar::UnsafeBitPackerImpl::num_bits_sorted(initial, decompressed)
}
}
}
}
fn num_bits_strictly_sorted(&self, initial: Option<u32>, decompressed: &[u32]) -> u8 {
unsafe {
match self.0 {
#[cfg(target_arch = "x86_64")]
InstructionSet::AVX2 => {
avx2::UnsafeBitPackerImpl::num_bits_strictly_sorted(initial, decompressed)
}
#[cfg(all(target_arch = "aarch64", target_endian = "little"))]
InstructionSet::NEON => {
neon::UnsafeBitPackerImpl::num_bits_strictly_sorted(initial, decompressed)
}
InstructionSet::Scalar => {
scalar::UnsafeBitPackerImpl::num_bits_strictly_sorted(initial, decompressed)
}
}
}
}
}
#[cfg(test)]
mod tests {
use super::BitPacker8x;
use crate::bitpacker_internal::BitPacker;
use bitpacking::{BitPacker as ExternalBitPacker, BitPacker8x as ExternalBitPacker8x};
fn mask_for_width(width: u8) -> u32 {
match width {
0 => 0,
32 => u32::MAX,
_ => (1u32 << width) - 1,
}
}
fn raw_values(width: u8, seed: u64) -> Vec<u32> {
let mask = mask_for_width(width);
let mut state = seed;
(0..BitPacker8x::BLOCK_LEN)
.map(|idx| {
state ^= state << 13;
state ^= state >> 7;
state ^= state << 17;
match seed % 4 {
0 => 0,
1 => mask,
2 => idx as u32 & mask,
_ => state as u32 & mask,
}
})
.collect()
}
fn sorted_values(width: u8, seed: u64) -> (u32, Vec<u32>) {
if width == 0 {
return (17, vec![17; BitPacker8x::BLOCK_LEN]);
}
if width == 32 {
return (0, vec![u32::MAX; BitPacker8x::BLOCK_LEN]);
}
let mask = mask_for_width(width).min(127);
let mut state = seed;
let mut current = 17u32;
let values = (0..BitPacker8x::BLOCK_LEN)
.map(|_| {
state ^= state << 13;
state ^= state >> 7;
state ^= state << 17;
current += state as u32 & mask;
current
})
.collect();
(17, values)
}
fn strictly_sorted_values(width: u8, seed: u64) -> (Option<u32>, Vec<u32>) {
let mask = mask_for_width(width).min(127);
let mut state = seed;
let mut current = 0u32;
let values = (0..BitPacker8x::BLOCK_LEN)
.map(|idx| {
if idx == 0 {
current = 0;
} else {
state ^= state << 13;
state ^= state >> 7;
state ^= state << 17;
current += 1 + (state as u32 & mask);
}
current
})
.collect();
(None, values)
}
fn assert_raw_compatible(ours: BitPacker8x, external: ExternalBitPacker8x) {
for width in 0..=32 {
for seed in [0, 1, 2, 123456789] {
let values = raw_values(width, seed);
assert_eq!(ours.num_bits(&values), external.num_bits(&values));
let mut actual = vec![0u8; BitPacker8x::compressed_block_size(width)];
let actual_len = ours.compress(&values, &mut actual, width);
let mut expected = vec![0u8; ExternalBitPacker8x::compressed_block_size(width)];
let expected_len = external.compress(&values, &mut expected, width);
assert_eq!(actual_len, expected_len);
assert_eq!(actual, expected, "raw width {width} seed {seed}");
let mut decoded = vec![0u32; BitPacker8x::BLOCK_LEN];
assert_eq!(ours.decompress(&actual, &mut decoded, width), actual_len);
assert_eq!(decoded, values);
}
}
}
fn assert_sorted_compatible(ours: BitPacker8x, external: ExternalBitPacker8x) {
for width in 0..=32 {
for seed in [0, 1, 2, 123456789] {
let (initial, values) = sorted_values(width, seed);
assert_eq!(
ours.num_bits_sorted(initial, &values),
external.num_bits_sorted(initial, &values)
);
let mut actual = vec![0u8; BitPacker8x::compressed_block_size(width)];
let actual_len = ours.compress_sorted(initial, &values, &mut actual, width);
let mut expected = vec![0u8; ExternalBitPacker8x::compressed_block_size(width)];
let expected_len = external.compress_sorted(initial, &values, &mut expected, width);
assert_eq!(actual_len, expected_len);
assert_eq!(actual, expected, "sorted width {width} seed {seed}");
let mut decoded = vec![0u32; BitPacker8x::BLOCK_LEN];
assert_eq!(
ours.decompress_sorted(initial, &actual, &mut decoded, width),
actual_len
);
assert_eq!(decoded, values);
}
}
}
fn assert_strictly_sorted_compatible(ours: BitPacker8x, external: ExternalBitPacker8x) {
for width in 0..=16 {
for seed in [0, 1, 2, 123456789] {
let (initial, values) = strictly_sorted_values(width, seed);
let num_bits = external.num_bits_strictly_sorted(initial, &values);
assert_eq!(ours.num_bits_strictly_sorted(initial, &values), num_bits);
let mut actual = vec![0u8; BitPacker8x::compressed_block_size(num_bits)];
let actual_len =
ours.compress_strictly_sorted(initial, &values, &mut actual, num_bits);
let mut expected = vec![0u8; ExternalBitPacker8x::compressed_block_size(num_bits)];
let expected_len =
external.compress_strictly_sorted(initial, &values, &mut expected, num_bits);
assert_eq!(actual_len, expected_len);
assert_eq!(actual, expected, "strict width {width} seed {seed}");
let mut decoded = vec![0u32; BitPacker8x::BLOCK_LEN];
assert_eq!(
ours.decompress_strictly_sorted(initial, &actual, &mut decoded, num_bits),
actual_len
);
assert_eq!(decoded, values);
}
}
}
#[test]
fn bitpacker8x_raw_compatible_with_external_bitpacking() {
assert_raw_compatible(BitPacker8x::new(), ExternalBitPacker8x::new());
}
#[test]
fn bitpacker8x_sorted_compatible_with_external_bitpacking() {
assert_sorted_compatible(BitPacker8x::new(), ExternalBitPacker8x::new());
}
#[test]
fn scalar_backend_matches_external_bitpacker8x() {
let scalar = BitPacker8x::new_scalar();
let external = ExternalBitPacker8x::new();
assert_raw_compatible(scalar, external);
assert_sorted_compatible(scalar, external);
}
#[test]
fn scalar_backend_matches_external_strictly_sorted_bitpacker8x() {
let scalar = BitPacker8x::new_scalar();
let external = ExternalBitPacker8x::new();
assert_strictly_sorted_compatible(scalar, external);
}
#[cfg(all(target_arch = "aarch64", target_endian = "little"))]
#[test]
fn neon_backend_matches_external_bitpacker8x() {
if let Some(neon) = BitPacker8x::new_neon() {
let external = ExternalBitPacker8x::new();
assert_raw_compatible(neon, external);
assert_sorted_compatible(neon, external);
assert_strictly_sorted_compatible(neon, external);
}
}
}
lance-artifact/rust/compression/bitpacking/src/bitpacker_internal/macros.rs
+669
View File
@@ -0,0 +1,669 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright The Lance Authors
macro_rules! pack_unpack_with_bits {
($name:ident, $n:expr, $cpufeature:meta) => {
mod $name {
use crunchy::unroll;
use super::BLOCK_LEN;
use super::{Sink, Transformer};
use super::{DataType,
set1,
right_shift_32,
left_shift_32,
op_or,
op_and,
load_unaligned,
store_unaligned};
const NUM_BITS: usize = $n;
const NUM_BYTES_PER_BLOCK: usize = NUM_BITS * BLOCK_LEN / 8;
#[$cpufeature]
pub(crate) unsafe fn pack<TDeltaComputer: Transformer>(input_arr: &[u32], output_arr: &mut [u8], mut delta_computer: TDeltaComputer) -> usize {
assert_eq!(input_arr.len(), BLOCK_LEN, "Input block too small {}, (expected {})", input_arr.len(), BLOCK_LEN);
assert!(output_arr.len() >= NUM_BYTES_PER_BLOCK, "Output array too small (numbits {}). {} <= {}", NUM_BITS, output_arr.len(), NUM_BYTES_PER_BLOCK);
let input_ptr = input_arr.as_ptr().cast::<DataType>();
let mut output_ptr = output_arr.as_mut_ptr().cast::<DataType>();
let mut out_register: DataType = delta_computer.transform(load_unaligned(input_ptr));
unroll! {
for iter in 0..30 {
const i: usize = 1 + iter;
const bits_filled: usize = i * NUM_BITS;
const inner_cursor: usize = bits_filled % 32;
const remaining: usize = 32 - inner_cursor;
let offset_ptr = input_ptr.add(i);
let in_register: DataType = delta_computer.transform(load_unaligned(offset_ptr));
out_register =
if inner_cursor > 0 {
op_or(out_register, left_shift_32::<{inner_cursor as i32}>(in_register))
} else {
in_register
};
if remaining <= NUM_BITS {
store_unaligned(output_ptr, out_register);
output_ptr = output_ptr.add(1);
if 0 < remaining && remaining < NUM_BITS {
out_register = right_shift_32::<{remaining as i32}>(in_register);
}
}
}
}
let in_register: DataType = delta_computer.transform(load_unaligned(input_ptr.add(31)));
out_register = if 32 - NUM_BITS > 0 {
op_or(out_register, left_shift_32::<{32 - NUM_BITS as i32}>(in_register))
} else {
op_or(out_register, in_register)
};
store_unaligned(output_ptr, out_register);
NUM_BYTES_PER_BLOCK
}
#[$cpufeature]
pub(crate) unsafe fn unpack<Output: Sink>(compressed: &[u8], mut output: Output) -> usize {
assert!(compressed.len() >= NUM_BYTES_PER_BLOCK, "Compressed array seems too small. ({} < {}) ", compressed.len(), NUM_BYTES_PER_BLOCK);
let mut input_ptr = compressed.as_ptr().cast::<DataType>();
let mask_scalar: u32 = ((1u64 << NUM_BITS) - 1u64) as u32;
let mask = set1(mask_scalar as i32);
let mut in_register: DataType = load_unaligned(input_ptr);
let out_register = op_and(in_register, mask);
output.process(out_register);
unroll! {
for iter in 0..31 {
const i: usize = iter + 1;
const inner_cursor: usize = (i * NUM_BITS) % 32;
const inner_capacity: usize = 32 - inner_cursor;
let shifted_in_register = if inner_cursor != 0 {
right_shift_32::<{inner_cursor as i32}>(in_register)
} else {
in_register
};
let mut out_register: DataType = op_and(shifted_in_register, mask);
// We consumed our current quadruplets entirely.
// We therefore read another one.
if inner_capacity <= NUM_BITS && i != 31 {
input_ptr = input_ptr.add(1);
in_register = load_unaligned(input_ptr);
// This quadruplets is actually cutting one of
// our `DataType`. We need to read the next one.
if inner_capacity < NUM_BITS {
let shifted = if inner_capacity != 0 {
left_shift_32::<{inner_capacity as i32}>(in_register)
} else {
in_register
};
let masked = op_and(shifted, mask);
out_register = op_or(out_register, masked);
}
}
output.process(out_register);
}
}
NUM_BYTES_PER_BLOCK
}
}
}
}
macro_rules! pack_unpack_with_bits_32 {
($cpufeature:meta) => {
mod pack_unpack_with_bits_32 {
use super::BLOCK_LEN;
use super::{DataType, load_unaligned, store_unaligned};
use super::{Sink, Transformer};
use crunchy::unroll;
const NUM_BITS: usize = 32;
const NUM_BYTES_PER_BLOCK: usize = NUM_BITS * BLOCK_LEN / 8;
#[$cpufeature]
pub(crate) unsafe fn pack<TDeltaComputer: Transformer>(
input_arr: &[u32],
output_arr: &mut [u8],
mut delta_computer: TDeltaComputer,
) -> usize {
assert_eq!(
input_arr.len(),
BLOCK_LEN,
"Input block too small {}, (expected {})",
input_arr.len(),
BLOCK_LEN
);
assert!(
output_arr.len() >= NUM_BYTES_PER_BLOCK,
"Output array too small (numbits {}). {} <= {}",
NUM_BITS,
output_arr.len(),
NUM_BYTES_PER_BLOCK
);
let input_ptr: *const DataType = input_arr.as_ptr().cast::<DataType>();
let output_ptr = output_arr.as_mut_ptr().cast::<DataType>();
unroll! {
for i in 0..32 {
let input_offset_ptr = input_ptr.add(i);
let output_offset_ptr = output_ptr.add(i);
let input_register = load_unaligned(input_offset_ptr);
let output_register = delta_computer.transform(input_register);
store_unaligned(output_offset_ptr, output_register);
}
}
NUM_BYTES_PER_BLOCK
}
#[$cpufeature]
pub(crate) unsafe fn unpack<Output: Sink>(
compressed: &[u8],
mut output: Output,
) -> usize {
assert!(
compressed.len() >= NUM_BYTES_PER_BLOCK,
"Compressed array seems too small. ({} < {}) ",
compressed.len(),
NUM_BYTES_PER_BLOCK
);
let input_ptr = compressed.as_ptr().cast::<DataType>();
for i in 0..32 {
let input_offset_ptr = input_ptr.add(i);
let in_register: DataType = load_unaligned(input_offset_ptr);
output.process(in_register);
}
NUM_BYTES_PER_BLOCK
}
}
};
}
macro_rules! declare_bitpacker {
($cpufeature:meta) => {
use super::super::UnsafeBitPacker;
use super::super::most_significant_bit;
use crunchy::unroll;
pack_unpack_with_bits!(pack_unpack_with_bits_1, 1, $cpufeature);
pack_unpack_with_bits!(pack_unpack_with_bits_2, 2, $cpufeature);
pack_unpack_with_bits!(pack_unpack_with_bits_3, 3, $cpufeature);
pack_unpack_with_bits!(pack_unpack_with_bits_4, 4, $cpufeature);
pack_unpack_with_bits!(pack_unpack_with_bits_5, 5, $cpufeature);
pack_unpack_with_bits!(pack_unpack_with_bits_6, 6, $cpufeature);
pack_unpack_with_bits!(pack_unpack_with_bits_7, 7, $cpufeature);
pack_unpack_with_bits!(pack_unpack_with_bits_8, 8, $cpufeature);
pack_unpack_with_bits!(pack_unpack_with_bits_9, 9, $cpufeature);
pack_unpack_with_bits!(pack_unpack_with_bits_10, 10, $cpufeature);
pack_unpack_with_bits!(pack_unpack_with_bits_11, 11, $cpufeature);
pack_unpack_with_bits!(pack_unpack_with_bits_12, 12, $cpufeature);
pack_unpack_with_bits!(pack_unpack_with_bits_13, 13, $cpufeature);
pack_unpack_with_bits!(pack_unpack_with_bits_14, 14, $cpufeature);
pack_unpack_with_bits!(pack_unpack_with_bits_15, 15, $cpufeature);
pack_unpack_with_bits!(pack_unpack_with_bits_16, 16, $cpufeature);
pack_unpack_with_bits!(pack_unpack_with_bits_17, 17, $cpufeature);
pack_unpack_with_bits!(pack_unpack_with_bits_18, 18, $cpufeature);
pack_unpack_with_bits!(pack_unpack_with_bits_19, 19, $cpufeature);
pack_unpack_with_bits!(pack_unpack_with_bits_20, 20, $cpufeature);
pack_unpack_with_bits!(pack_unpack_with_bits_21, 21, $cpufeature);
pack_unpack_with_bits!(pack_unpack_with_bits_22, 22, $cpufeature);
pack_unpack_with_bits!(pack_unpack_with_bits_23, 23, $cpufeature);
pack_unpack_with_bits!(pack_unpack_with_bits_24, 24, $cpufeature);
pack_unpack_with_bits!(pack_unpack_with_bits_25, 25, $cpufeature);
pack_unpack_with_bits!(pack_unpack_with_bits_26, 26, $cpufeature);
pack_unpack_with_bits!(pack_unpack_with_bits_27, 27, $cpufeature);
pack_unpack_with_bits!(pack_unpack_with_bits_28, 28, $cpufeature);
pack_unpack_with_bits!(pack_unpack_with_bits_29, 29, $cpufeature);
pack_unpack_with_bits!(pack_unpack_with_bits_30, 30, $cpufeature);
pack_unpack_with_bits!(pack_unpack_with_bits_31, 31, $cpufeature);
pack_unpack_with_bits_32!($cpufeature);
unsafe fn compress_generic<DeltaComputer: Transformer>(
decompressed: &[u32],
compressed: &mut [u8],
num_bits: u8,
delta_computer: DeltaComputer,
) -> usize {
match num_bits {
0 => 0,
1 => pack_unpack_with_bits_1::pack(decompressed, compressed, delta_computer),
2 => pack_unpack_with_bits_2::pack(decompressed, compressed, delta_computer),
3 => pack_unpack_with_bits_3::pack(decompressed, compressed, delta_computer),
4 => pack_unpack_with_bits_4::pack(decompressed, compressed, delta_computer),
5 => pack_unpack_with_bits_5::pack(decompressed, compressed, delta_computer),
6 => pack_unpack_with_bits_6::pack(decompressed, compressed, delta_computer),
7 => pack_unpack_with_bits_7::pack(decompressed, compressed, delta_computer),
8 => pack_unpack_with_bits_8::pack(decompressed, compressed, delta_computer),
9 => pack_unpack_with_bits_9::pack(decompressed, compressed, delta_computer),
10 => pack_unpack_with_bits_10::pack(decompressed, compressed, delta_computer),
11 => pack_unpack_with_bits_11::pack(decompressed, compressed, delta_computer),
12 => pack_unpack_with_bits_12::pack(decompressed, compressed, delta_computer),
13 => pack_unpack_with_bits_13::pack(decompressed, compressed, delta_computer),
14 => pack_unpack_with_bits_14::pack(decompressed, compressed, delta_computer),
15 => pack_unpack_with_bits_15::pack(decompressed, compressed, delta_computer),
16 => pack_unpack_with_bits_16::pack(decompressed, compressed, delta_computer),
17 => pack_unpack_with_bits_17::pack(decompressed, compressed, delta_computer),
18 => pack_unpack_with_bits_18::pack(decompressed, compressed, delta_computer),
19 => pack_unpack_with_bits_19::pack(decompressed, compressed, delta_computer),
20 => pack_unpack_with_bits_20::pack(decompressed, compressed, delta_computer),
21 => pack_unpack_with_bits_21::pack(decompressed, compressed, delta_computer),
22 => pack_unpack_with_bits_22::pack(decompressed, compressed, delta_computer),
23 => pack_unpack_with_bits_23::pack(decompressed, compressed, delta_computer),
24 => pack_unpack_with_bits_24::pack(decompressed, compressed, delta_computer),
25 => pack_unpack_with_bits_25::pack(decompressed, compressed, delta_computer),
26 => pack_unpack_with_bits_26::pack(decompressed, compressed, delta_computer),
27 => pack_unpack_with_bits_27::pack(decompressed, compressed, delta_computer),
28 => pack_unpack_with_bits_28::pack(decompressed, compressed, delta_computer),
29 => pack_unpack_with_bits_29::pack(decompressed, compressed, delta_computer),
30 => pack_unpack_with_bits_30::pack(decompressed, compressed, delta_computer),
31 => pack_unpack_with_bits_31::pack(decompressed, compressed, delta_computer),
32 => pack_unpack_with_bits_32::pack(decompressed, compressed, delta_computer),
_ => {
panic!("Num bits must be <= 32. Was {}.", num_bits);
}
}
}
pub trait Transformer {
unsafe fn transform(&mut self, data: DataType) -> DataType;
}
struct NoDelta;
impl Transformer for NoDelta {
#[inline]
unsafe fn transform(&mut self, current: DataType) -> DataType {
current
}
}
struct DeltaComputer {
pub previous: DataType,
}
impl Transformer for DeltaComputer {
#[inline]
unsafe fn transform(&mut self, current: DataType) -> DataType {
let result = compute_delta(current, self.previous);
self.previous = current;
result
}
}
struct StrictDeltaComputer {
pub previous: DataType,
}
impl Transformer for StrictDeltaComputer {
#[inline]
unsafe fn transform(&mut self, current: DataType) -> DataType {
let result = compute_delta(current, self.previous);
self.previous = current;
sub(result, set1(1))
}
}
pub trait Sink {
unsafe fn process(&mut self, data_type: DataType);
}
struct Store {
output_ptr: *mut DataType,
}
impl Store {
fn new(output_ptr: *mut DataType) -> Store {
Store { output_ptr }
}
}
struct DeltaIntegrate {
current: DataType,
output_ptr: *mut DataType,
}
impl DeltaIntegrate {
unsafe fn new(initial: u32, output_ptr: *mut DataType) -> DeltaIntegrate {
DeltaIntegrate {
current: set1(initial as i32),
output_ptr,
}
}
}
impl Sink for DeltaIntegrate {
#[inline]
unsafe fn process(&mut self, delta: DataType) {
self.current = integrate_delta(self.current, delta);
store_unaligned(self.output_ptr, self.current);
self.output_ptr = self.output_ptr.add(1);
}
}
struct StrictDeltaIntegrate {
current: DataType,
output_ptr: *mut DataType,
}
impl StrictDeltaIntegrate {
unsafe fn new(initial: u32, output_ptr: *mut DataType) -> StrictDeltaIntegrate {
StrictDeltaIntegrate {
current: set1(initial as i32),
output_ptr,
}
}
}
impl Sink for StrictDeltaIntegrate {
#[inline]
unsafe fn process(&mut self, delta: DataType) {
self.current = integrate_delta(self.current, add(delta, set1(1)));
store_unaligned(self.output_ptr, self.current);
self.output_ptr = self.output_ptr.add(1);
}
}
impl Sink for Store {
#[inline]
unsafe fn process(&mut self, out_register: DataType) {
store_unaligned(self.output_ptr, out_register);
self.output_ptr = self.output_ptr.add(1);
}
}
#[inline]
unsafe fn decompress_to<Output: Sink>(
compressed: &[u8],
mut sink: Output,
num_bits: u8,
) -> usize {
match num_bits {
0 => {
let zero = set1(0i32);
for _ in 0..32 {
sink.process(zero);
}
0
}
1 => pack_unpack_with_bits_1::unpack(compressed, sink),
2 => pack_unpack_with_bits_2::unpack(compressed, sink),
3 => pack_unpack_with_bits_3::unpack(compressed, sink),
4 => pack_unpack_with_bits_4::unpack(compressed, sink),
5 => pack_unpack_with_bits_5::unpack(compressed, sink),
6 => pack_unpack_with_bits_6::unpack(compressed, sink),
7 => pack_unpack_with_bits_7::unpack(compressed, sink),
8 => pack_unpack_with_bits_8::unpack(compressed, sink),
9 => pack_unpack_with_bits_9::unpack(compressed, sink),
10 => pack_unpack_with_bits_10::unpack(compressed, sink),
11 => pack_unpack_with_bits_11::unpack(compressed, sink),
12 => pack_unpack_with_bits_12::unpack(compressed, sink),
13 => pack_unpack_with_bits_13::unpack(compressed, sink),
14 => pack_unpack_with_bits_14::unpack(compressed, sink),
15 => pack_unpack_with_bits_15::unpack(compressed, sink),
16 => pack_unpack_with_bits_16::unpack(compressed, sink),
17 => pack_unpack_with_bits_17::unpack(compressed, sink),
18 => pack_unpack_with_bits_18::unpack(compressed, sink),
19 => pack_unpack_with_bits_19::unpack(compressed, sink),
20 => pack_unpack_with_bits_20::unpack(compressed, sink),
21 => pack_unpack_with_bits_21::unpack(compressed, sink),
22 => pack_unpack_with_bits_22::unpack(compressed, sink),
23 => pack_unpack_with_bits_23::unpack(compressed, sink),
24 => pack_unpack_with_bits_24::unpack(compressed, sink),
25 => pack_unpack_with_bits_25::unpack(compressed, sink),
26 => pack_unpack_with_bits_26::unpack(compressed, sink),
27 => pack_unpack_with_bits_27::unpack(compressed, sink),
28 => pack_unpack_with_bits_28::unpack(compressed, sink),
29 => pack_unpack_with_bits_29::unpack(compressed, sink),
30 => pack_unpack_with_bits_30::unpack(compressed, sink),
31 => pack_unpack_with_bits_31::unpack(compressed, sink),
32 => pack_unpack_with_bits_32::unpack(compressed, sink),
_ => {
panic!("Num bits must be <= 32. Was {}.", num_bits);
}
}
}
pub struct UnsafeBitPackerImpl;
impl UnsafeBitPacker for UnsafeBitPackerImpl {
const BLOCK_LEN: usize = BLOCK_LEN;
#[$cpufeature]
unsafe fn compress(decompressed: &[u32], compressed: &mut [u8], num_bits: u8) -> usize {
compress_generic(decompressed, compressed, num_bits, NoDelta)
}
#[$cpufeature]
unsafe fn compress_sorted(
initial: u32,
decompressed: &[u32],
compressed: &mut [u8],
num_bits: u8,
) -> usize {
let delta_computer = DeltaComputer {
previous: set1(initial as i32),
};
compress_generic(decompressed, compressed, num_bits, delta_computer)
}
#[$cpufeature]
unsafe fn compress_strictly_sorted(
initial: Option<u32>,
decompressed: &[u32],
compressed: &mut [u8],
num_bits: u8,
) -> usize {
// to allow encoding [0, 1, 2, ..], we need to permit an initial value "lower" than
// zero. To get a clean api, that value is None, but in practice, as we work on
// wrapping integers, u32::MAX/-1 does the job just fine.
let initial = initial.unwrap_or(u32::MAX);
let delta_computer = StrictDeltaComputer {
previous: set1(initial as i32),
};
compress_generic(decompressed, compressed, num_bits, delta_computer)
}
#[$cpufeature]
unsafe fn decompress(
compressed: &[u8],
decompressed: &mut [u32],
num_bits: u8,
) -> usize {
assert!(
decompressed.len() >= BLOCK_LEN,
"The output array is not large enough : ({} >= {})",
decompressed.len(),
BLOCK_LEN
);
let output_ptr = decompressed.as_mut_ptr().cast::<DataType>();
let output = Store::new(output_ptr);
decompress_to(compressed, output, num_bits)
}
#[$cpufeature]
unsafe fn decompress_sorted(
initial: u32,
compressed: &[u8],
decompressed: &mut [u32],
num_bits: u8,
) -> usize {
assert!(
decompressed.len() >= BLOCK_LEN,
"The output array is not large enough : ({} >= {})",
decompressed.len(),
BLOCK_LEN
);
let output_ptr = decompressed.as_mut_ptr().cast::<DataType>();
let output = DeltaIntegrate::new(initial, output_ptr);
decompress_to(compressed, output, num_bits)
}
#[$cpufeature]
unsafe fn decompress_strictly_sorted(
initial: Option<u32>,
compressed: &[u8],
decompressed: &mut [u32],
num_bits: u8,
) -> usize {
assert!(
decompressed.len() >= BLOCK_LEN,
"The output array is not large enough : ({} >= {})",
decompressed.len(),
BLOCK_LEN
);
let initial = initial.unwrap_or(u32::MAX);
let output_ptr = decompressed.as_mut_ptr().cast::<DataType>();
let output = StrictDeltaIntegrate::new(initial, output_ptr);
decompress_to(compressed, output, num_bits)
}
#[$cpufeature]
unsafe fn num_bits(decompressed: &[u32]) -> u8 {
assert_eq!(
decompressed.len(),
BLOCK_LEN,
"`decompressed`'s len is not `BLOCK_LEN={}`",
BLOCK_LEN
);
let data: *const DataType = decompressed.as_ptr().cast::<DataType>();
let mut accumulator = load_unaligned(data);
unroll! {
for iter in 0..31 {
let i = iter + 1;
let newvec = load_unaligned(data.add(i));
accumulator = op_or(accumulator, newvec);
}
}
most_significant_bit(or_collapse_to_u32(accumulator))
}
#[$cpufeature]
unsafe fn num_bits_sorted(initial: u32, decompressed: &[u32]) -> u8 {
assert_eq!(
decompressed.len(),
BLOCK_LEN,
"`decompressed`'s len is not `BLOCK_LEN={}`",
BLOCK_LEN
);
let initial_vec = set1(initial as i32);
let data: *const DataType = decompressed.as_ptr().cast::<DataType>();
let first = load_unaligned(data);
let mut accumulator = compute_delta(load_unaligned(data), initial_vec);
let mut previous = first;
unroll! {
for iter in 0..30 {
let i = iter + 1;
let current = load_unaligned(data.add(i));
let delta = compute_delta(current, previous);
accumulator = op_or(accumulator, delta);
previous = current;
}
}
let current = load_unaligned(data.add(31));
let delta = compute_delta(current, previous);
accumulator = op_or(accumulator, delta);
most_significant_bit(or_collapse_to_u32(accumulator))
}
#[$cpufeature]
unsafe fn num_bits_strictly_sorted(initial: Option<u32>, decompressed: &[u32]) -> u8 {
assert_eq!(
decompressed.len(),
BLOCK_LEN,
"`decompressed`'s len is not `BLOCK_LEN={}`",
BLOCK_LEN
);
let initial = initial.unwrap_or(u32::MAX);
let initial_vec = set1(initial as i32);
let one = set1(1);
let data: *const DataType = decompressed.as_ptr().cast::<DataType>();
let first = load_unaligned(data);
let mut accumulator = sub(compute_delta(load_unaligned(data), initial_vec), one);
let mut previous = first;
unroll! {
for iter in 0..30 {
let i = iter + 1;
let current = load_unaligned(data.add(i));
let delta = sub(compute_delta(current, previous), one);
accumulator = op_or(accumulator, delta);
previous = current;
}
}
let current = load_unaligned(data.add(31));
let delta = sub(compute_delta(current, previous), one);
accumulator = op_or(accumulator, delta);
most_significant_bit(or_collapse_to_u32(accumulator))
}
}
#[cfg(any())]
mod tests {
use super::super::UnsafeBitPacker;
use super::UnsafeBitPackerImpl;
use crate::Available;
use crate::tests::{DeltaKind, test_suite_compress_decompress};
#[test]
fn test_num_bits() {
if UnsafeBitPackerImpl::available() {
for num_bits in 0..32 {
for pos in 0..32 {
let mut vals = [0u32; UnsafeBitPackerImpl::BLOCK_LEN];
if num_bits > 0 {
vals[pos] = 1 << (num_bits - 1);
}
assert_eq!(
unsafe { UnsafeBitPackerImpl::num_bits(&vals[..]) },
num_bits
);
}
}
}
}
#[test]
fn test_bitpacker() {
if UnsafeBitPackerImpl::available() {
test_suite_compress_decompress::<UnsafeBitPackerImpl>(DeltaKind::NoDelta);
}
}
#[test]
fn test_bitpacker_delta() {
if UnsafeBitPackerImpl::available() {
test_suite_compress_decompress::<UnsafeBitPackerImpl>(DeltaKind::Delta);
}
}
#[test]
fn test_bitpacker_strict_delta() {
if UnsafeBitPackerImpl::available() {
test_suite_compress_decompress::<UnsafeBitPackerImpl>(DeltaKind::StrictDelta);
}
}
}
};
}
lance-artifact/rust/compression/bitpacking/src/bitpacker_internal/mod.rs
+147
View File
@@ -0,0 +1,147 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright The Lance Authors
// Lance-owned u32 SIMD bitpacking kernels.
//
// This is adapted from the MIT-licensed `bitpacking` crate so Lance can keep the
// hot FTS posting-list bitpacking implementation inside lance-bitpacking while
// preserving byte compatibility with the existing 4x format.
#![allow(dead_code)]
#![allow(unsafe_op_in_unsafe_fn)]
#![allow(clippy::redundant_pub_crate)]
#![allow(clippy::upper_case_acronyms)]
#![allow(clippy::use_self)]
#[macro_use]
mod macros;
mod bitpacker4x;
mod bitpacker8x;
pub use bitpacker4x::BitPacker4x;
pub use bitpacker8x::BitPacker8x;
pub(crate) trait Available {
fn available() -> bool;
}
pub(crate) trait UnsafeBitPacker {
const BLOCK_LEN: usize;
unsafe fn compress(decompressed: &[u32], compressed: &mut [u8], num_bits: u8) -> usize;
unsafe fn compress_sorted(
initial: u32,
decompressed: &[u32],
compressed: &mut [u8],
num_bits: u8,
) -> usize;
unsafe fn compress_strictly_sorted(
initial: Option<u32>,
decompressed: &[u32],
compressed: &mut [u8],
num_bits: u8,
) -> usize;
unsafe fn decompress(compressed: &[u8], decompressed: &mut [u32], num_bits: u8) -> usize;
unsafe fn decompress_sorted(
initial: u32,
compressed: &[u8],
decompressed: &mut [u32],
num_bits: u8,
) -> usize;
unsafe fn decompress_strictly_sorted(
initial: Option<u32>,
compressed: &[u8],
decompressed: &mut [u32],
num_bits: u8,
) -> usize;
unsafe fn num_bits(decompressed: &[u32]) -> u8;
unsafe fn num_bits_sorted(initial: u32, decompressed: &[u32]) -> u8;
unsafe fn num_bits_strictly_sorted(initial: Option<u32>, decompressed: &[u32]) -> u8;
}
/// Block bitpacker for fixed-size `u32` blocks.
///
/// Implementations own runtime SIMD dispatch and use caller-provided buffers.
/// Packed bytes are stable for a given implementation and bit width.
pub trait BitPacker: Sized + Clone + Copy {
/// Number of `u32` values in one physical block.
const BLOCK_LEN: usize;
/// Select the best supported implementation for the current CPU.
///
/// Lance uses SIMD backends when available and falls back to a scalar
/// backend otherwise, matching the existing allocation-free call shape used
/// by the upstream `bitpacking` crate.
fn new() -> Self;
/// Compress one full block of raw values into `compressed`.
fn compress(&self, decompressed: &[u32], compressed: &mut [u8], num_bits: u8) -> usize;
/// Delta-compress one full non-decreasing block into `compressed`.
fn compress_sorted(
&self,
initial: u32,
decompressed: &[u32],
compressed: &mut [u8],
num_bits: u8,
) -> usize;
/// Delta-compress one full strictly increasing block into `compressed`.
fn compress_strictly_sorted(
&self,
initial: Option<u32>,
decompressed: &[u32],
compressed: &mut [u8],
num_bits: u8,
) -> usize;
/// Decompress one raw block into `decompressed`.
fn decompress(&self, compressed: &[u8], decompressed: &mut [u32], num_bits: u8) -> usize;
/// Decompress one delta-compressed non-decreasing block.
fn decompress_sorted(
&self,
initial: u32,
compressed: &[u8],
decompressed: &mut [u32],
num_bits: u8,
) -> usize;
/// Decompress one delta-compressed strictly increasing block.
fn decompress_strictly_sorted(
&self,
initial: Option<u32>,
compressed: &[u8],
decompressed: &mut [u32],
num_bits: u8,
) -> usize;
/// Return the minimum bit width needed to represent a full raw block.
fn num_bits(&self, decompressed: &[u32]) -> u8;
/// Return the minimum bit width needed to represent deltas in a full block.
fn num_bits_sorted(&self, initial: u32, decompressed: &[u32]) -> u8;
/// Return the minimum bit width needed to represent strict deltas in a full block.
fn num_bits_strictly_sorted(&self, initial: Option<u32>, decompressed: &[u32]) -> u8;
/// Return the byte size of one compressed block at `num_bits`.
#[must_use]
fn compressed_block_size(num_bits: u8) -> usize {
Self::BLOCK_LEN * num_bits as usize / 8
}
}
#[inline]
fn most_significant_bit(value: u32) -> u8 {
(u32::BITS - value.leading_zeros()) as u8
}
lance-artifact/rust/compression/bitpacking/src/lib.rs
+2278
View File
File diff suppressed because it is too large Load Diff
lance-artifact/rust/compression/fsst/Cargo.toml
+27
View File
@@ -0,0 +1,27 @@
[package]
name = "fsst"
version.workspace = true
edition.workspace = true
authors.workspace = true
license.workspace = true
readme.workspace = true
repository.workspace = true
description = "FSST string compression for Lance"
keywords.workspace = true
categories.workspace = true
rust-version.workspace = true
[dependencies]
arrow-array.workspace = true
rand.workspace = true
[dev-dependencies]
test-log.workspace = true
tokio.workspace = true
[[example]]
name = "benchmark"
path = "examples/benchmark.rs"
[lints]
workspace = true
lance-artifact/rust/compression/fsst/examples/benchmark.rs
+157
View File
@@ -0,0 +1,157 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright The Lance Authors
use std::fs::File;
use std::io::{BufRead, BufReader};
use arrow_array::StringArray;
use fsst::fsst::{FSST_SYMBOL_TABLE_SIZE, compress, decompress};
use rand::Rng;
const TEST_NUM: usize = 20;
const BUFFER_SIZE: usize = 8 * 1024 * 1024;
fn read_random_8_m_chunk(file_path: &str) -> Result<StringArray, std::io::Error> {
let file = File::open(file_path)?;
let reader = BufReader::new(file);
let lines: Vec<String> = reader.lines().collect::<std::result::Result<_, _>>()?;
let num_lines = lines.len();
let mut rng = rand::rng();
let mut curr_line = rng.random_range(0..num_lines);
let chunk_size = BUFFER_SIZE;
let mut size = 0;
let mut result_lines = vec![];
while size + lines[curr_line].len() < chunk_size {
result_lines.push(lines[curr_line].clone());
size += lines[curr_line].len();
curr_line += 1;
curr_line %= num_lines;
}
Ok(StringArray::from(result_lines))
}
fn benchmark(file_path: &str) {
// Step 1: load data in memory
let mut inputs: Vec<StringArray> = vec![];
let mut symbol_tables: Vec<[u8; FSST_SYMBOL_TABLE_SIZE]> = vec![];
for _ in 0..TEST_NUM {
let this_input = read_random_8_m_chunk(file_path).unwrap();
inputs.push(this_input);
symbol_tables.push([0u8; FSST_SYMBOL_TABLE_SIZE]);
}
// Step 2: allocate memory for compression and decompression outputs
let mut compression_out_bufs = vec![];
let mut compression_out_offsets_bufs = vec![];
for _ in 0..TEST_NUM {
let this_com_out_buf = vec![0u8; BUFFER_SIZE];
let this_com_out_offsets_buf = vec![0i32; BUFFER_SIZE];
compression_out_bufs.push(this_com_out_buf);
compression_out_offsets_bufs.push(this_com_out_offsets_buf);
}
let mut decompression_out_bufs = vec![];
let mut decompression_out_offsets_bufs = vec![];
for _ in 0..TEST_NUM {
// `decompress` requires the output buffer to be at least 8x the compressed input (a 1-byte
// code can expand to an 8-byte symbol). The compressed buffer is at most `BUFFER_SIZE`, so
// `BUFFER_SIZE * 8` is a safe upper bound.
let this_decom_out_buf = vec![0u8; BUFFER_SIZE * 8];
let this_decom_out_offsets_buf = vec![0i32; BUFFER_SIZE * 3];
decompression_out_bufs.push(this_decom_out_buf);
decompression_out_offsets_bufs.push(this_decom_out_offsets_buf);
}
let original_total_size: usize = inputs.iter().map(|input| input.values().len()).sum();
// Step 3: compress data
let start = std::time::Instant::now();
for i in 0..TEST_NUM {
compress(
symbol_tables[i].as_mut(),
inputs[i].values(),
inputs[i].value_offsets(),
&mut compression_out_bufs[i],
&mut compression_out_offsets_bufs[i],
)
.unwrap();
}
let compression_finish_time = std::time::Instant::now();
for i in 0..TEST_NUM {
decompress(
&symbol_tables[i],
&compression_out_bufs[i],
&compression_out_offsets_bufs[i],
&mut decompression_out_bufs[i],
&mut decompression_out_offsets_bufs[i],
)
.unwrap();
}
let decompression_finish_time = std::time::Instant::now();
let compression_total_size: usize = compression_out_bufs.iter().map(|buf| buf.len()).sum();
let compression_ratio = original_total_size as f64 / compression_total_size as f64;
let compress_time = compression_finish_time - start;
let decompress_time = decompression_finish_time - compression_finish_time;
let compress_seconds =
compress_time.as_secs() as f64 + compress_time.subsec_nanos() as f64 * 1e-9;
let decompress_seconds =
decompress_time.as_secs() as f64 + decompress_time.subsec_nanos() as f64 * 1e-9;
let com_speed = (original_total_size as f64 / compress_seconds) / 1024f64 / 1024f64;
let d_speed = (original_total_size as f64 / decompress_seconds) / 1024f64 / 1024f64;
for i in 0..TEST_NUM {
assert_eq!(
inputs[i].value_offsets().len(),
decompression_out_offsets_bufs[i].len()
);
}
// Print tsv headers
#[allow(clippy::print_stdout)]
{
println!("for file: {}", file_path);
println!("Compression ratio\tCompression speed\tDecompression speed");
println!(
"{:.3}\t\t\t\t{:.2}MB/s\t\t\t{:.2}MB/s",
compression_ratio, com_speed, d_speed
);
}
for i in 0..TEST_NUM {
assert_eq!(inputs[i].value_data(), decompression_out_bufs[i]);
assert_eq!(inputs[i].value_offsets(), decompression_out_offsets_bufs[i]);
}
}
// to run this test, download MS Marco dataset from https://msmarco.z22.web.core.windows.net/msmarcoranking/fulldocs.tsv.gz
// and use a script like this to get each column
/*
import csv
import sys
def write_second_column(input_path, output_path):
csv.field_size_limit(sys.maxsize)
with open(input_path, 'r') as input_file, open(output_path, 'w') as output_file:
tsv_reader = csv.reader(input_file, delimiter='\t')
tsv_writer = csv.writer(output_file, delimiter='\t')
for row in tsv_reader:
tsv_writer.writerow([row[2]])
#write_second_column('/Users/x/fulldocs.tsv', '/Users/x/first_column_fulldocs.tsv')
#write_second_column('/Users/x/fulldocs.tsv', '/Users/x/second_column_fulldocs.tsv')
write_second_column('/Users/x/fulldocs.tsv', '/Users/x/third_column_fulldocs.tsv')
*/
fn main() {
let file_paths = [
"/home/x/first_column_fulldocs.tsv",
"/home/x/second_column_fulldocs.tsv",
"/home/x/third_column_fulldocs_chunk_0.tsv",
];
for file_path in file_paths {
benchmark(file_path);
}
}
lance-artifact/rust/compression/fsst/src/fsst.rs
+1744
View File
File diff suppressed because it is too large Load Diff
lance-artifact/rust/compression/fsst/src/lib.rs
+4
View File
@@ -0,0 +1,4 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright The Lance Authors
pub mod fsst;
lance-artifact/rust/examples/Cargo.toml
+54
View File
@@ -0,0 +1,54 @@
[package]
name = "lance-examples"
description = "Lance examples in Rust"
version.workspace = true
edition.workspace = true
authors.workspace = true
license.workspace = true
repository.workspace = true
readme.workspace = true
keywords.workspace = true
categories.workspace = true
rust-version.workspace = true
[[example]]
name = "full_text_search"
path = "src/full_text_search.rs"
[[example]]
name = "hnsw"
path = "src/hnsw.rs"
[[example]]
name = "ivf_hnsw"
path = "src/ivf_hnsw.rs"
[[example]]
name = "llm_dataset_creation"
path = "src/llm_dataset_creation.rs"
[[example]]
name = "write_read_ds"
path = "src/write_read_ds.rs"
[dependencies]
arrow = { workspace = true }
arrow-schema = { workspace = true }
arrow-select = { workspace = true }
clap = { workspace = true, features = ["derive"] }
itertools = { workspace = true }
futures = { workspace = true }
lance = { workspace = true, features = ["aws", "azure", "gcp", "oss", "huggingface", "tencent", "goosefs"] }
lance-index = { workspace = true }
lance-core = { workspace = true }
lance-linalg = { workspace = true }
lance-datagen = { workspace = true }
object_store = {workspace = true}
tempfile = { workspace = true }
tokio = { workspace = true }
all_asserts = "2.3.1"
env_logger = "0.11.7"
hf-hub = "0.4.2"
parquet = { version = "58.0.0", default-features = false, features = ["arrow", "async"] }
tokenizers = "0.15.2"
rand.workspace = true
lance-artifact/rust/examples/src/full_text_search.rs
+129
View File
@@ -0,0 +1,129 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright The Lance Authors
//! Benchmark of HNSW graph.
//!
//!
#![allow(clippy::print_stdout)]
use std::collections::HashSet;
use std::sync::Arc;
use all_asserts::assert_gt;
use arrow::array::AsArray;
use arrow::array::{Array, LargeStringArray, RecordBatch, RecordBatchIterator, UInt64Array};
use arrow::datatypes::UInt64Type;
use arrow_schema::{DataType, Field, Schema};
use itertools::Itertools;
use lance::Dataset;
use lance::index::DatasetIndexExt;
use lance_datagen::{RowCount, array};
use lance_index::scalar::inverted::flat_full_text_search;
use lance_index::scalar::{FullTextSearchQuery, InvertedIndexParams};
use object_store::path::Path;
#[tokio::main]
async fn main() {
env_logger::init();
const TOTAL: usize = 10_000;
const DOC_ID: &str = "__example_doc_id";
let tempdir = tempfile::tempdir().unwrap();
let dataset_dir = Path::from_filesystem_path(tempdir.path()).unwrap();
let create_index = true;
if create_index {
let row_id_col = Arc::new(UInt64Array::from(
(0..TOTAL).map(|i| i as u64).collect_vec(),
));
// Generate random words using lance-datagen
let mut words_gen = array::random_sentence(1, 100, true);
let doc_col = words_gen
.generate_default(RowCount::from(TOTAL as u64))
.unwrap();
let batch = RecordBatch::try_new(
Arc::new(Schema::new(vec![
Field::new("doc", DataType::LargeUtf8, false),
Field::new(DOC_ID, DataType::UInt64, false),
])),
vec![doc_col.clone(), row_id_col.clone()],
)
.unwrap();
let batches = RecordBatchIterator::new([Ok(batch.clone())], batch.schema());
let mut dataset = Dataset::write(batches, dataset_dir.as_ref(), None)
.await
.unwrap();
let params = InvertedIndexParams::default();
let start = std::time::Instant::now();
dataset
.create_index(
&["doc"],
lance_index::IndexType::Inverted,
None,
&params,
true,
)
.await
.unwrap();
println!("create_index: {:?}", start.elapsed());
}
let dataset = Dataset::open(dataset_dir.as_ref()).await.unwrap();
// Use a sample word for query - fetch first doc and pick a word from it
let sample_batch = dataset
.scan()
.project(&["doc"])
.unwrap()
.limit(Some(1), None)
.unwrap()
.try_into_batch()
.await
.unwrap();
let sample_doc = sample_batch["doc"]
.as_any()
.downcast_ref::<LargeStringArray>()
.unwrap()
.value(0);
let query_string = sample_doc.split_whitespace().next().unwrap();
let query = FullTextSearchQuery::new(query_string.to_owned()).limit(Some(10));
println!("query: {:?}", query);
let batch = dataset
.scan()
.full_text_search(query.clone())
.unwrap()
.try_into_batch()
.await
.unwrap();
let index_results = batch[DOC_ID]
.as_primitive::<UInt64Type>()
.iter()
.map(|v| v.unwrap())
.collect::<HashSet<_>>();
let start = std::time::Instant::now();
dataset
.scan()
.full_text_search(query.clone())
.unwrap()
.try_into_batch()
.await
.unwrap();
println!("full_text_search: {:?}", start.elapsed());
let batch = dataset
.scan()
.project(&["doc"])
.unwrap()
.with_row_id()
.try_into_batch()
.await
.unwrap();
let flat_results = flat_full_text_search(&[&batch], "doc", query_string, None)
.unwrap()
.into_iter()
.collect::<HashSet<_>>();
assert_gt!(index_results.len(), 0);
assert_eq!(index_results, flat_results);
}
lance-artifact/rust/examples/src/hnsw.rs
+151
View File
@@ -0,0 +1,151 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright The Lance Authors
//! HNSW is a graph based algorithm for approximate neighbor search in high-dimensional spaces.
//! In this example, we will demonstrate how to build HNSW vector indexing against a Lance dataset.
//! run with `cargo run -v --package lance-examples --example hnsw``
// linked to `docs/examples/Rust/hnsw.rst`
#![allow(clippy::print_stdout)]
use std::collections::HashSet;
use std::sync::Arc;
use arrow::array::{Array, FixedSizeListArray, types::Float32Type};
use arrow::array::{AsArray, FixedSizeListBuilder, Float32Builder};
use arrow::datatypes::{DataType, Field, Schema};
use arrow::record_batch::RecordBatch;
use arrow::record_batch::RecordBatchIterator;
use arrow_select::concat::concat;
use futures::stream::StreamExt;
use lance::Dataset;
use lance_index::vector::v3::subindex::IvfSubIndex;
use lance_index::vector::{
flat::storage::FlatFloatStorage,
hnsw::{
HNSW,
builder::{HnswBuildParams, HnswQueryParams},
},
};
use lance_linalg::distance::DistanceType;
fn ground_truth(fsl: &FixedSizeListArray, query: &[f32], k: usize) -> HashSet<u32> {
let mut dists = vec![];
for i in 0..fsl.len() {
let dist = lance_linalg::distance::l2_distance(
query,
fsl.value(i).as_primitive::<Float32Type>().values(),
);
dists.push((dist, i as u32));
}
dists.sort_by(|a, b| a.0.partial_cmp(&b.0).unwrap());
dists.truncate(k);
dists.into_iter().map(|(_, i)| i).collect()
}
pub async fn create_test_vector_dataset(output: &str, num_rows: usize, dim: i32) {
let schema = Arc::new(Schema::new(vec![Field::new(
"vector",
DataType::FixedSizeList(Arc::new(Field::new("item", DataType::Float32, true)), dim),
false,
)]));
let mut batches = Vec::new();
// Create a few batches
for _ in 0..2 {
let v_builder = Float32Builder::new();
let mut list_builder = FixedSizeListBuilder::new(v_builder, dim);
for _ in 0..num_rows {
for _ in 0..dim {
list_builder.values().append_value(rand::random::<f32>());
}
list_builder.append(true);
}
let array = Arc::new(list_builder.finish());
let batch = RecordBatch::try_new(schema.clone(), vec![array]).unwrap();
batches.push(batch);
}
let batch_reader = RecordBatchIterator::new(batches.into_iter().map(Ok), schema.clone());
println!("Writing dataset to {}", output);
Dataset::write(batch_reader, output, None).await.unwrap();
}
#[tokio::main]
async fn main() {
let uri: Option<String> = None; // None means generate test data
let column = "vector";
let ef = 100;
let max_edges = 30;
let max_level = 7;
// 1. Generate a synthetic test data of specified dimensions
let dataset = match uri.as_deref() {
None => {
println!("No uri is provided, generating test dataset...");
let output = "test_vectors.lance";
create_test_vector_dataset(output, 1000, 64).await;
Dataset::open(output).await.expect("Failed to open dataset")
}
Some(uri) => Dataset::open(uri).await.expect("Failed to open dataset"),
};
println!("Dataset schema: {:#?}", dataset.schema());
let batches = dataset
.scan()
.project(&[column])
.unwrap()
.try_into_stream()
.await
.unwrap()
.then(|batch| async move { batch.unwrap().column_by_name(column).unwrap().clone() })
.collect::<Vec<_>>()
.await;
let arrs = batches.iter().map(|b| b.as_ref()).collect::<Vec<_>>();
let fsl = concat(&arrs).unwrap().as_fixed_size_list().clone();
println!("Loaded {:?} batches", fsl.len());
let vector_store = Arc::new(FlatFloatStorage::new(fsl.clone(), DistanceType::L2));
let q = fsl.value(0);
let k = 10;
let gt = ground_truth(&fsl, q.as_primitive::<Float32Type>().values(), k);
for ef_construction in [15, 30, 50] {
let now = std::time::Instant::now();
// 2. Build a hierarchical graph structure for efficient vector search using Lance API
let hnsw = HNSW::index_vectors(
vector_store.as_ref(),
HnswBuildParams::default()
.max_level(max_level)
.num_edges(max_edges)
.ef_construction(ef_construction),
)
.unwrap();
let construct_time = now.elapsed().as_secs_f32();
let now = std::time::Instant::now();
// 3. Perform vector search with different parameters and compute the ground truth using L2 distance search
let params = HnswQueryParams {
ef,
lower_bound: None,
upper_bound: None,
dist_q_c: 0.0,
use_acorn: false,
};
let results: HashSet<u32> = hnsw
.search_basic(q.clone(), k, &params, None, vector_store.as_ref())
.unwrap()
.iter()
.map(|node| node.id)
.collect();
let search_time = now.elapsed().as_micros();
println!(
"level={}, ef_construct={}, ef={} recall={}: construct={:.3}s search={:.3} us",
max_level,
ef_construction,
ef,
results.intersection(&gt).count() as f32 / k as f32,
construct_time,
search_time
);
}
}
lance-artifact/rust/examples/src/ivf_hnsw.rs
+155
View File
@@ -0,0 +1,155 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright The Lance Authors
//! Run recall benchmarks for HNSW.
//!
//! run with `cargo run --release --example hnsw`
#![allow(clippy::print_stdout)]
use arrow::array::AsArray;
use arrow::array::types::Float32Type;
use clap::Parser;
use futures::TryStreamExt;
use lance::Dataset;
use lance::dataset::ProjectionRequest;
use lance::index::DatasetIndexExt;
use lance::index::vector::VectorIndexParams;
use lance_index::IndexType;
use lance_index::vector::hnsw::builder::HnswBuildParams;
use lance_index::vector::ivf::IvfBuildParams;
use lance_index::vector::sq::builder::SQBuildParams;
use lance_linalg::distance::MetricType;
#[derive(Parser, Debug)]
#[command(version, about, long_about = None)]
struct Args {
/// Dataset URI
uri: String,
/// Vector column name
#[arg(short, long, value_name = "NAME", default_value = "vector")]
column: Option<String>,
#[arg(long, default_value = "100")]
ef: usize,
/// Max number of edges of each node.
#[arg(long, default_value = "30")]
max_edges: usize,
#[arg(long, default_value = "7")]
max_level: u16,
#[arg(long, default_value = "1")]
nprobe: usize,
#[arg(short, default_value = "10")]
k: usize,
#[arg(long, default_value = "false")]
create_index: bool,
#[arg(long, default_value = "cosine")]
metric_type: String,
}
#[cfg(test)]
fn ground_truth(mat: &MatrixView<Float32Type>, query: &[f32], k: usize) -> HashSet<u32> {
let mut dists = vec![];
for i in 0..mat.num_rows() {
let dist = lance_linalg::distance::l2_distance(query, mat.row(i).unwrap());
dists.push((dist, i as u32));
}
dists.sort_by(|a, b| a.0.partial_cmp(&b.0).unwrap());
dists.truncate(k);
dists.into_iter().map(|(_, i)| i).collect()
}
#[tokio::main]
async fn main() {
env_logger::init();
let args = Args::parse();
let mut dataset = Dataset::open(&args.uri)
.await
.expect("Failed to open dataset");
println!("Dataset schema: {:#?}", dataset.schema());
let column = args.column.as_deref().unwrap_or("vector");
let metric_type = MetricType::try_from(args.metric_type.as_str()).unwrap();
let mut ivf_params = IvfBuildParams::new(128);
ivf_params.sample_rate = 20480;
let hnsw_params = HnswBuildParams::default()
.ef_construction(100)
.num_edges(15);
let pq_params = SQBuildParams::default();
let params =
VectorIndexParams::with_ivf_hnsw_sq_params(metric_type, ivf_params, hnsw_params, pq_params);
println!("{:?}", params);
if args.create_index {
let now = std::time::Instant::now();
dataset
.create_index(&[column], IndexType::Vector, None, &params, true)
.await
.unwrap();
println!("build={:.3}s", now.elapsed().as_secs_f32());
}
println!("Loaded {} records", dataset.count_rows(None).await.unwrap());
let take_projection = ProjectionRequest::from_columns([column], dataset.schema());
let q = dataset
.take(&[0], take_projection)
.await
.unwrap()
.column(0)
.as_fixed_size_list()
.values()
.as_primitive::<Float32Type>()
.clone();
let columns: &[&str] = &[];
let mut scan = dataset.scan();
let plan = scan
.project(columns)
.unwrap()
.with_row_id()
.nearest(column, &q, args.k)
.unwrap()
.minimum_nprobes(args.nprobe);
println!("{:?}", plan.explain_plan(true).await.unwrap());
let now = std::time::Instant::now();
plan.try_into_stream()
.await
.unwrap()
.try_collect::<Vec<_>>()
.await
.unwrap();
println!(
"level={}, nprobe={}, k={}, search={:?}",
args.max_level,
args.nprobe,
args.k,
now.elapsed(),
);
let now = std::time::Instant::now();
for _ in 0..10 {
plan.try_into_stream()
.await
.unwrap()
.try_collect::<Vec<_>>()
.await
.unwrap();
}
println!(
"warm up: level={}, nprobe={}, k={}, search={:?}",
args.max_level,
args.nprobe,
args.k,
now.elapsed().div_f32(10.0),
);
}
lance-artifact/rust/examples/src/llm_dataset_creation.rs
+256
View File
@@ -0,0 +1,256 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright The Lance Authors
//! This example demonstrates how to:
//!
//! 1. Download and process a text dataset in parts from huggingface
//! 2. Tokenize the text data with a custom RecordBatchReader
//! 3. Save it as a Lance dataset using Lance API
//!
//! Run with `cargo run -v --package lance-examples --example llm_dataset_creation`
//!
//!
// linked to `docs/examples/Rust/llm_dataset_creation.rst`
use arrow::array::{Array, Int64Builder, ListBuilder, UInt32Array};
use arrow::datatypes::{DataType, Field, Schema};
use arrow::record_batch::RecordBatch;
use arrow::record_batch::RecordBatchReader;
use futures::StreamExt;
use hf_hub::{Repo, RepoType, api::sync::Api};
use lance::dataset::WriteParams;
use parquet::arrow::arrow_reader::ParquetRecordBatchReaderBuilder;
use rand::SeedableRng;
use rand::seq::SliceRandom;
use std::error::Error;
use std::fs::File;
use std::io::Write;
use std::sync::Arc;
use tempfile::NamedTempFile;
use tokenizers::Tokenizer;
// Implement a custom stream batch reader
struct WikiTextBatchReader {
schema: Arc<Schema>,
parquet_readers: Vec<Option<ParquetRecordBatchReaderBuilder<File>>>,
current_reader_idx: usize,
current_reader: Option<Box<dyn RecordBatchReader + Send>>,
tokenizer: Tokenizer,
num_samples: u64,
cur_samples_cnt: u64,
}
impl WikiTextBatchReader {
fn new(
parquet_readers: Vec<ParquetRecordBatchReaderBuilder<File>>,
tokenizer: Tokenizer,
num_samples: Option<u64>,
) -> Result<Self, Box<dyn Error + Send + Sync>> {
let schema = Arc::new(Schema::new(vec![Field::new(
"input_ids",
DataType::List(Arc::new(Field::new("item", DataType::Int64, true))),
false,
)]));
Ok(Self {
schema,
parquet_readers: parquet_readers.into_iter().map(Some).collect(),
current_reader_idx: 0,
current_reader: None,
tokenizer,
num_samples: num_samples.unwrap_or(100_000),
cur_samples_cnt: 0,
})
}
fn process_batch(
&mut self,
input_batch: &RecordBatch,
) -> Result<RecordBatch, arrow::error::ArrowError> {
let num_rows = input_batch.num_rows();
let mut token_builder = ListBuilder::new(Int64Builder::with_capacity(num_rows * 1024)); // Pre-allocate space
let mut should_break = false;
let column = input_batch.column_by_name("text").unwrap();
let string_array = column
.as_any()
.downcast_ref::<arrow::array::StringArray>()
.unwrap();
for i in 0..num_rows {
if self.cur_samples_cnt >= self.num_samples {
should_break = true;
break;
}
if !Array::is_null(string_array, i) {
let text = string_array.value(i);
// Split paragraph into lines
for line in text.split('\n') {
if let Ok(encoding) = self.tokenizer.encode(line, true) {
let tb_values = token_builder.values();
for &id in encoding.get_ids() {
tb_values.append_value(id as i64);
}
token_builder.append(true);
self.cur_samples_cnt += 1;
if self.cur_samples_cnt.is_multiple_of(5000) {
println!("Processed {} rows", self.cur_samples_cnt);
}
if self.cur_samples_cnt >= self.num_samples {
should_break = true;
break;
}
}
}
}
}
// Create array and shuffle it
let input_ids_array = token_builder.finish();
// Create shuffled array by randomly sampling indices
let mut rng = rand::rngs::StdRng::seed_from_u64(1337);
let len = input_ids_array.len();
let mut indices: Vec<u32> = (0..len as u32).collect();
indices.shuffle(&mut rng);
// Take values in shuffled order
let indices_array = UInt32Array::from(indices);
let shuffled = arrow::compute::take(&input_ids_array, &indices_array, None)?;
let batch = RecordBatch::try_new(self.schema.clone(), vec![Arc::new(shuffled)]);
if should_break {
println!("Stop at {} rows", self.cur_samples_cnt);
self.parquet_readers.clear();
self.current_reader = None;
}
batch
}
}
impl RecordBatchReader for WikiTextBatchReader {
fn schema(&self) -> Arc<Schema> {
self.schema.clone()
}
}
impl Iterator for WikiTextBatchReader {
type Item = Result<RecordBatch, arrow::error::ArrowError>;
fn next(&mut self) -> Option<Self::Item> {
loop {
// If we have a current reader, try to get next batch
if let Some(reader) = &mut self.current_reader
&& let Some(batch_result) = reader.next()
{
return Some(batch_result.and_then(|batch| self.process_batch(&batch)));
}
// If no current reader or current reader is exhausted, try to get next reader
if self.current_reader_idx < self.parquet_readers.len()
&& let Some(builder) = self.parquet_readers[self.current_reader_idx].take()
{
match builder.build() {
Ok(reader) => {
self.current_reader = Some(Box::new(reader));
self.current_reader_idx += 1;
continue;
}
Err(e) => {
return Some(Err(arrow::error::ArrowError::ExternalError(Box::new(e))));
}
}
}
// No more readers available
return None;
}
}
}
fn main() -> Result<(), Box<dyn Error + Send + Sync>> {
let rt = tokio::runtime::Runtime::new()?;
rt.block_on(async {
// Load tokenizer
let tokenizer = load_tokenizer("gpt2")?;
// Set up Hugging Face API
// Download from https://huggingface.co/datasets/Salesforce/wikitext/tree/main/wikitext-103-raw-v1
let api = Api::new()?;
let repo = api.repo(Repo::with_revision(
"Salesforce/wikitext".into(),
RepoType::Dataset,
"main".into(),
));
// Define the parquet files we want to download
let train_files = vec![
"wikitext-103-raw-v1/train-00000-of-00002.parquet",
"wikitext-103-raw-v1/train-00001-of-00002.parquet",
];
let mut parquet_readers = Vec::new();
for file in &train_files {
println!("Downloading file: {}", file);
let file_path = repo.get(file)?;
let data = std::fs::read(file_path)?;
// Create a temporary file in the system temp directory and write the downloaded data to it
let mut temp_file = NamedTempFile::new()?;
temp_file.write_all(&data)?;
// Create the parquet reader builder with a larger batch size
let builder = ParquetRecordBatchReaderBuilder::try_new(temp_file.into_file())?
.with_batch_size(8192); // Increase batch size for better performance
parquet_readers.push(builder);
}
if parquet_readers.is_empty() {
println!("No parquet files found to process.");
return Ok(());
}
// Create batch reader
let num_samples: u64 = 500_000;
let batch_reader = WikiTextBatchReader::new(parquet_readers, tokenizer, Some(num_samples))?;
// Save as Lance dataset
println!("Writing to Lance dataset...");
let lance_dataset_path = "rust_wikitext_lance_dataset.lance";
let write_params = WriteParams::default();
lance::Dataset::write(batch_reader, lance_dataset_path, Some(write_params)).await?;
// Verify the dataset
let ds = lance::Dataset::open(lance_dataset_path).await?;
let scanner = ds.scan();
let mut stream = scanner.try_into_stream().await?;
let mut total_rows = 0;
while let Some(batch_result) = stream.next().await {
let batch = batch_result?;
total_rows += batch.num_rows();
}
println!(
"Lance dataset created successfully with {} rows",
total_rows
);
println!("Dataset location: {}", lance_dataset_path);
Ok(())
})
}
fn load_tokenizer(model_name: &str) -> Result<Tokenizer, Box<dyn Error + Send + Sync>> {
let api = Api::new()?;
let repo = api.repo(Repo::with_revision(
model_name.into(),
RepoType::Model,
"main".into(),
));
let tokenizer_path = repo.get("tokenizer.json")?;
let tokenizer = Tokenizer::from_file(tokenizer_path)?;
Ok(tokenizer)
}
lance-artifact/rust/examples/src/write_read_ds.rs
+84
View File
@@ -0,0 +1,84 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright The Lance Authors
#![allow(clippy::print_stdout)]
use arrow::array::UInt32Array;
use arrow::datatypes::{DataType, Field, Schema};
use arrow::record_batch::{RecordBatch, RecordBatchIterator};
use futures::StreamExt;
use lance::Dataset;
use lance::dataset::{WriteMode, WriteParams};
use lance::io::ObjectStore;
use lance_core::utils::tempfile::TempStrDir;
use std::sync::Arc;
// Writes sample dataset to the given path
async fn write_dataset(data_path: &str) -> Result<(), Box<dyn std::error::Error>> {
// Define new schema
let schema = Arc::new(Schema::new(vec![
Field::new("key", DataType::UInt32, false),
Field::new("value", DataType::UInt32, false),
]));
// Create new record batches
let batch = RecordBatch::try_new(
schema.clone(),
vec![
Arc::new(UInt32Array::from(vec![1, 2, 3, 4, 5, 6])),
Arc::new(UInt32Array::from(vec![6, 7, 8, 9, 10, 11])),
],
)?;
let batches = RecordBatchIterator::new([Ok(batch)], schema.clone());
// Define write parameters (e.g. overwrite dataset)
let write_params = WriteParams {
mode: WriteMode::Overwrite,
..Default::default()
};
Dataset::write(batches, data_path, Some(write_params)).await?;
Ok(())
} // End write dataset
// Reads dataset from the given path and prints batch size, schema for all record batches. Also extracts and prints a slice from the first batch
async fn read_dataset(data_path: &str) -> Result<(), Box<dyn std::error::Error>> {
let dataset = Dataset::open(data_path).await?;
let scanner = dataset.scan();
let mut batch_stream = scanner.try_into_stream().await?.map(|b| b.unwrap());
while let Some(batch) = batch_stream.next().await {
println!("Batch size: {}, {}", batch.num_rows(), batch.num_columns()); // print size of batch
println!("Schema: {:?}", batch.schema()); // print schema of recordbatch
println!("Batch: {:?}", batch); // print the entire recordbatch (schema and data)
}
Ok(())
} // End read dataset
async fn clean_resources(data_path: &str) -> Result<(), Box<dyn std::error::Error>> {
let (store, base) = ObjectStore::from_uri(data_path).await?;
store.remove_dir_all(base).await?;
println!("Cleaned up resources at: {}", data_path);
Ok(())
}
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
let tempdir = TempStrDir::default();
let data_path = tempdir.as_str();
let result = async {
write_dataset(data_path).await?;
read_dataset(data_path).await?;
Ok(())
}
.await;
if let Err(e) = clean_resources(data_path).await {
eprintln!("Failed to clean resources: {:?}", e);
}
result
}
lance-artifact/rust/img.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 305 KiB

lance-artifact/rust/lance-arrow/Cargo.toml
+36
View File
@@ -0,0 +1,36 @@
[package]
name = "lance-arrow"
version.workspace = true
edition.workspace = true
authors.workspace = true
license.workspace = true
repository.workspace = true
readme = "README.md"
description = "Arrow Extension for Lance"
keywords.workspace = true
categories.workspace = true
[lib]
crate-type = ["cdylib", "rlib"]
[dependencies]
arrow-array = { workspace = true }
arrow-buffer = { workspace = true }
arrow-data = { workspace = true }
arrow-ipc = { workspace = true }
arrow-ord = { workspace = true }
arrow-schema = { workspace = true }
arrow-select = { workspace = true }
bytemuck = { workspace = true }
bytes = { workspace = true }
futures = { workspace = true }
half = { workspace = true }
jsonb ={ workspace = true }
num-traits = { workspace = true }
rand.workspace = true
[target.'cfg(target_arch = "wasm32")'.dependencies]
getrandom = { version = "0.2", features = ["js"] }
[lints]
workspace = true
lance-artifact/rust/lance-arrow/README.md
+8
View File
@@ -0,0 +1,8 @@
# lance-arrow
`lance-arrow` is a internal sub-crate, containing [Apache-Arrow](https://github.com/apache/arrow-rs)
extensions used by [Lance](https://github.com/lancedb/lance).
**Important Note**: This crate is **not intended for external usage**.
lance-artifact/rust/lance-arrow/src/bfloat16.rs
+404
View File
@@ -0,0 +1,404 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright The Lance Authors
//! bfloat16 support for Apache Arrow.
use std::fmt::Formatter;
use std::slice;
use arrow_array::{Array, FixedSizeBinaryArray, builder::BooleanBufferBuilder};
use arrow_buffer::{Buffer, MutableBuffer};
use arrow_data::ArrayData;
use arrow_schema::{ArrowError, DataType, Field as ArrowField};
use half::bf16;
use crate::{ARROW_EXT_NAME_KEY, FloatArray};
/// The name of the bfloat16 extension in Arrow metadata
pub const BFLOAT16_EXT_NAME: &str = "lance.bfloat16";
/// Check whether the given field is a bfloat16 field
///
/// A field is a bfloat16 field if it has a data type of `FixedSizeBinary(2)` and the metadata
/// contains the bfloat16 extension name.
pub fn is_bfloat16_field(field: &ArrowField) -> bool {
field.data_type() == &DataType::FixedSizeBinary(2)
&& field
.metadata()
.get(ARROW_EXT_NAME_KEY)
.map(|name| name == BFLOAT16_EXT_NAME)
.unwrap_or_default()
}
/// The bfloat16 data type
///
/// This implements the [`ArrowFloatType`](crate::floats::ArrowFloatType) trait for bfloat16 values.
#[derive(Debug)]
pub struct BFloat16Type {}
/// An array of bfloat16 values
///
/// Note that bfloat16 is not the same thing as fp16 which is supported natively by arrow-rs.
#[derive(Clone)]
pub struct BFloat16Array {
inner: FixedSizeBinaryArray,
}
impl std::fmt::Debug for BFloat16Array {
fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
write!(f, "BFloat16Array\n[\n")?;
from_arrow::print_long_array(&self.inner, f, |array, i, f| {
if array.is_null(i) {
write!(f, "null")
} else {
let binary_values = array.value(i);
let value =
bf16::from_bits(u16::from_le_bytes([binary_values[0], binary_values[1]]));
write!(f, "{:?}", value)
}
})?;
write!(f, "]")
}
}
impl BFloat16Array {
pub fn from_iter_values(iter: impl IntoIterator<Item = bf16>) -> Self {
let values: Vec<bf16> = iter.into_iter().collect();
values.into()
}
pub fn len(&self) -> usize {
self.inner.len()
}
pub fn is_empty(&self) -> bool {
self.inner.is_empty()
}
pub fn is_null(&self, i: usize) -> bool {
self.inner.is_null(i)
}
pub fn null_count(&self) -> usize {
self.inner.null_count()
}
pub fn iter(&self) -> BFloat16Iter<'_> {
BFloat16Iter {
array: self,
index: 0,
}
}
pub fn value(&self, i: usize) -> bf16 {
assert!(
i < self.len(),
"Trying to access an element at index {} from a BFloat16Array of length {}",
i,
self.len()
);
// Safety:
// `i < self.len()
unsafe { self.value_unchecked(i) }
}
/// # Safety
/// Caller must ensure that `i < self.len()`
pub unsafe fn value_unchecked(&self, i: usize) -> bf16 {
let binary_value = self.inner.value_unchecked(i);
bf16::from_bits(u16::from_le_bytes([binary_value[0], binary_value[1]]))
}
pub fn into_inner(self) -> FixedSizeBinaryArray {
self.inner
}
}
impl FromIterator<Option<bf16>> for BFloat16Array {
fn from_iter<I: IntoIterator<Item = Option<bf16>>>(iter: I) -> Self {
let mut buffer = MutableBuffer::new(10);
// No null buffer builder :(
let mut nulls = BooleanBufferBuilder::new(10);
let mut len = 0;
for maybe_value in iter {
if let Some(value) = maybe_value {
let bytes = value.to_le_bytes();
buffer.extend(bytes);
} else {
buffer.extend([0u8, 0u8]);
}
nulls.append(maybe_value.is_some());
len += 1;
}
let null_buffer = nulls.finish();
let num_valid = null_buffer.count_set_bits();
let null_buffer = if num_valid == len {
None
} else {
Some(null_buffer.into_inner())
};
let array_data = ArrayData::builder(DataType::FixedSizeBinary(2))
.len(len)
.add_buffer(buffer.into())
.null_bit_buffer(null_buffer);
// SAFETY: the value buffer contains exactly `2 * len` bytes (two bytes
// pushed per iteration of the loop above, including the zero-fill for
// null slots), which matches the `FixedSizeBinary(2)` storage layout.
// The null bit buffer, when present, has `len` bits appended above, so
// its length covers the array's logical range.
let array_data = unsafe { array_data.build_unchecked() };
Self {
inner: FixedSizeBinaryArray::from(array_data),
}
}
}
impl FromIterator<bf16> for BFloat16Array {
fn from_iter<I: IntoIterator<Item = bf16>>(iter: I) -> Self {
Self::from_iter_values(iter)
}
}
impl From<Vec<bf16>> for BFloat16Array {
fn from(data: Vec<bf16>) -> Self {
let len = data.len();
// Zero-copy: `bf16` is `#[repr(transparent)]` over `u16` and derives
// `bytemuck::Pod`, so `cast_vec` reinterprets the allocation in place —
// no per-element copy or heap alloc. The crate-root `compile_error!`
// pins `target_endian = "little"`, so the resulting bytes match the
// `FixedSizeBinary(2)` on-disk order Lance writes elsewhere.
let raw: Vec<u16> = bytemuck::cast_vec(data);
let array_data = ArrayData::builder(DataType::FixedSizeBinary(2))
.len(len)
.add_buffer(Buffer::from_vec(raw));
// SAFETY: the value buffer contains exactly `2 * len` bytes — one
// `u16` per element after the layout-compatible cast — matching the
// `FixedSizeBinary(2)` storage layout. No null buffer is attached, so
// every element is logically valid.
let array_data = unsafe { array_data.build_unchecked() };
Self {
inner: FixedSizeBinaryArray::from(array_data),
}
}
}
impl TryFrom<FixedSizeBinaryArray> for BFloat16Array {
type Error = ArrowError;
fn try_from(value: FixedSizeBinaryArray) -> Result<Self, Self::Error> {
if value.value_length() == 2 {
Ok(Self { inner: value })
} else {
Err(ArrowError::InvalidArgumentError(
"FixedSizeBinaryArray must have a value length of 2".to_string(),
))
}
}
}
impl PartialEq<Self> for BFloat16Array {
fn eq(&self, other: &Self) -> bool {
self.inner.eq(&other.inner)
}
}
pub struct BFloat16Iter<'a> {
array: &'a BFloat16Array,
index: usize,
}
impl<'a> Iterator for BFloat16Iter<'a> {
type Item = Option<bf16>;
fn next(&mut self) -> Option<Self::Item> {
if self.index >= self.array.len() {
return None;
}
let i = self.index;
self.index += 1;
if self.array.is_null(i) {
Some(None)
} else {
Some(Some(self.array.value(i)))
}
}
}
/// Methods that are lifted from arrow-rs temporarily until they are made public.
mod from_arrow {
use arrow_array::Array;
/// Helper function for printing potentially long arrays.
pub(super) fn print_long_array<A, F>(
array: &A,
f: &mut std::fmt::Formatter,
print_item: F,
) -> std::fmt::Result
where
A: Array,
F: Fn(&A, usize, &mut std::fmt::Formatter) -> std::fmt::Result,
{
let head = std::cmp::min(10, array.len());
for i in 0..head {
if array.is_null(i) {
writeln!(f, " null,")?;
} else {
write!(f, " ")?;
print_item(array, i, f)?;
writeln!(f, ",")?;
}
}
if array.len() > 10 {
if array.len() > 20 {
writeln!(f, " ...{} elements...,", array.len() - 20)?;
}
let tail = std::cmp::max(head, array.len() - 10);
for i in tail..array.len() {
if array.is_null(i) {
writeln!(f, " null,")?;
} else {
write!(f, " ")?;
print_item(array, i, f)?;
writeln!(f, ",")?;
}
}
}
Ok(())
}
}
impl FloatArray<BFloat16Type> for FixedSizeBinaryArray {
type FloatType = BFloat16Type;
/// Returns the underlying `bf16` values as a borrowed slice.
///
/// # Preconditions
///
/// - `value_length()` must be 2 (the `FixedSizeBinary(2)` storage shape
/// used by [`BFloat16Array`]). Asserted at entry.
/// - The value buffer must be at least 2-byte aligned. Lance's in-tree
/// constructors always satisfy this: value buffers are built either via
/// `MutableBuffer` (aligned to arrow-buffer's `ALIGNMENT` constant, ≥32
/// bytes) or via `Buffer::from_vec::<u16>` (aligned to `align_of::<u16>()`
/// == 2); both meet `bf16`'s 2-byte requirement. Externally-built
/// `FixedSizeBinaryArray`s arriving via FFI, IPC, or
/// `Buffer::from_custom_allocation` are not required by arrow-rs to be
/// aligned beyond a single byte; passing one to this method violates the
/// precondition. A `debug_assert` below catches such inputs in debug and
/// test builds.
///
/// # Endianness
///
/// `lance-arrow` is gated on `target_endian = "little"` at the crate root,
/// so this method always returns values in the same byte order Lance writes
/// (see [`BFloat16Array::value`] and the [`FromIterator`] impls).
fn as_slice(&self) -> &[bf16] {
assert_eq!(
self.value_length(),
2,
"BFloat16 arrays must use FixedSizeBinary(2) storage"
);
debug_assert_eq!(
(self.value_data().as_ptr() as usize) % std::mem::align_of::<bf16>(),
0,
"BFloat16 value buffer must be at least 2-byte aligned"
);
// SAFETY:
// - The assert above pins `value_size == 2`, so `value_data().len() / 2`
// equals the array's logical element count.
// `FixedSizeBinaryArray::From<ArrayData>` constructs its value buffer
// as `buffers[0].slice_with_length(offset * 2, len * 2)` (arrow-array
// `fixed_size_binary_array.rs`), so `value_data()` already returns
// the offset-adjusted slice. Do not replace `value_data()` with an
// accessor that returns the un-sliced backing buffer.
// - `bf16` is `#[repr(transparent)]` over `u16` (size 2, alignment 2);
// every `u16` bit pattern is a valid `bf16`, so any byte content
// yields a defined value — never UB.
// - Alignment is the caller's responsibility per the precondition
// documented above. The `debug_assert_eq!` immediately preceding this
// block catches violations in debug and test builds only — release
// builds rely on callers honoring the precondition. arrow-rs
// declares `FixedSizeBinary(n)`'s
// `BufferSpec::FixedWidth { alignment: align_of::<u8>() == 1 }`
// (arrow-data `data.rs`), so arrow-rs alone does not guarantee
// 2-byte alignment. Lance's in-tree construction paths build value
// buffers via `MutableBuffer` (arrow-buffer `ALIGNMENT` constant,
// ≥32 bytes) or `Buffer::from_vec::<u16>` (2-byte aligned), both of
// which satisfy `bf16`'s 2-byte requirement.
// - The returned slice borrows from `self`; the underlying ref-counted,
// immutable Arrow buffer cannot be mutated or freed for the slice's
// lifetime.
unsafe {
slice::from_raw_parts(
self.value_data().as_ptr() as *const bf16,
self.value_data().len() / 2,
)
}
}
fn from_values(values: Vec<bf16>) -> Self {
BFloat16Array::from(values).into_inner()
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn test_basics() {
let values: Vec<f32> = vec![1.0, 2.0, 3.0];
let values: Vec<bf16> = values.iter().map(|v| bf16::from_f32(*v)).collect();
let array = BFloat16Array::from_iter_values(values.clone());
let array2 = BFloat16Array::from(values.clone());
assert_eq!(array, array2);
assert_eq!(array.len(), 3);
// Pin the raw little-endian bytes emitted by `From<Vec<bf16>>` (rewritten to
// reinterpret the Vec via `bytemuck::cast_vec`), so a layout/byte-order
// regression is caught directly rather than only through Debug formatting.
// bf16 is the high 16 bits of the f32: 1.0->0x3F80, 2.0->0x4000, 3.0->0x4040.
let inner = array2.clone().into_inner();
let raw_bytes: Vec<u8> = (0..inner.len())
.flat_map(|i| inner.value(i).to_vec())
.collect();
assert_eq!(raw_bytes, vec![0x80, 0x3F, 0x00, 0x40, 0x40, 0x40]);
let expected_fmt = "BFloat16Array\n[\n 1.0,\n 2.0,\n 3.0,\n]";
assert_eq!(expected_fmt, format!("{:?}", array));
for (expected, value) in values.iter().zip(array.iter()) {
assert_eq!(Some(*expected), value);
}
for (expected, value) in values.as_slice().iter().zip(array2.iter()) {
assert_eq!(Some(*expected), value);
}
let arrow_array = array.into_inner();
assert_eq!(arrow_array.as_slice(), values.as_slice());
}
#[test]
fn test_nulls() {
let values: Vec<Option<bf16>> =
vec![Some(bf16::from_f32(1.0)), None, Some(bf16::from_f32(3.0))];
let array = BFloat16Array::from_iter(values.clone());
assert_eq!(array.len(), 3);
assert_eq!(array.null_count(), 1);
let expected_fmt = "BFloat16Array\n[\n 1.0,\n null,\n 3.0,\n]";
assert_eq!(expected_fmt, format!("{:?}", array));
for (expected, value) in values.iter().zip(array.iter()) {
assert_eq!(*expected, value);
}
}
}
lance-artifact/rust/lance-arrow/src/deepcopy.rs
+238
View File
@@ -0,0 +1,238 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright The Lance Authors
use std::sync::Arc;
use arrow_array::{Array, RecordBatch, make_array};
use arrow_buffer::{BooleanBuffer, Buffer, NullBuffer};
use arrow_data::{ArrayData, ArrayDataBuilder, transform::MutableArrayData};
pub fn deep_copy_buffer(buffer: &Buffer) -> Buffer {
Buffer::from(buffer.as_slice())
}
pub fn deep_copy_nulls(nulls: Option<&NullBuffer>) -> Option<NullBuffer> {
let nulls = nulls?;
let bit_buffer = deep_copy_buffer(nulls.inner().inner());
// SAFETY: `null_count` is taken from the source `NullBuffer`, which already
// upheld `NullBuffer::new_unchecked`'s invariant — the unset-bit count over
// the logical bit slice `[bit_offset, bit_offset + bit_len)`. `NullBuffer::slice`
// adjusts only `BooleanBuffer::bit_offset` / `bit_len` and never byte-advances
// the inner `Buffer`, so `deep_copy_buffer` (which copies the source `Buffer`'s
// `as_slice()` view from byte 0) reproduces the exact bit pattern at the same
// bit offsets; the unset-bit count is therefore preserved. `BooleanBuffer::new`
// panics (does not UB) if `bit_offset + bit_len > 8 * buffer.len()`, and the
// copy has the same length, so that check still passes.
Some(unsafe {
NullBuffer::new_unchecked(
BooleanBuffer::new(bit_buffer, nulls.offset(), nulls.len()),
nulls.null_count(),
)
})
}
pub fn deep_copy_array_data(data: &ArrayData) -> ArrayData {
let data_type = data.data_type().clone();
let len = data.len();
let nulls = deep_copy_nulls(data.nulls());
let offset = data.offset();
let buffers = data
.buffers()
.iter()
.map(deep_copy_buffer)
.collect::<Vec<_>>();
let child_data = data
.child_data()
.iter()
.map(deep_copy_array_data)
.collect::<Vec<_>>();
// SAFETY: `build_unchecked` inherits `ArrayData::new_unchecked`'s contract —
// `(data_type, len, offset, nulls, buffers, child_data)` must form a valid
// Arrow array. This call reproduces `data` structurally: `data_type`, `len`,
// and `offset` are forwarded unchanged; each buffer is replaced by a byte-
// identical copy of its offset-applied `as_slice()` view (the output buffer
// is `MutableBuffer`-allocated, at least as aligned as the source); `nulls`
// is deep-copied with the same bit offset/length and unset-bit count (see
// `deep_copy_nulls`); `child_data` is recursively cloned with the same
// guarantee. Every value-level invariant the source upheld — UTF-8 validity,
// monotonic offsets, in-bounds dictionary indices, run-end monotonicity,
// struct child-length matching — therefore transfers to the copy. If the
// source `ArrayData` was itself constructed via `new_unchecked` with an
// invalid payload, this function faithfully reproduces that invalidity.
unsafe {
ArrayDataBuilder::new(data_type)
.len(len)
.nulls(nulls)
.offset(offset)
.buffers(buffers)
.child_data(child_data)
.build_unchecked()
}
}
pub fn deep_copy_array(array: &dyn Array) -> Arc<dyn Array> {
let data = array.to_data();
let data = deep_copy_array_data(&data);
make_array(data)
}
pub fn deep_copy_batch(batch: &RecordBatch) -> crate::Result<RecordBatch> {
let arrays = batch
.columns()
.iter()
.map(|array| deep_copy_array(array))
.collect::<Vec<_>>();
RecordBatch::try_new(batch.schema(), arrays)
}
/// Deep copy array data, extracting only the sliced portion using MutableArrayData
/// This is the most efficient and correct way to copy just the sliced data
pub fn deep_copy_array_data_sliced(data: &ArrayData) -> ArrayData {
// Use MutableArrayData to efficiently copy just the slice
let mut mutable = MutableArrayData::new(vec![data], false, data.len());
// Copy from offset to offset+len (the visible slice)
mutable.extend(0, data.offset(), data.offset() + data.len());
// Freeze into immutable ArrayData
mutable.freeze()
}
/// Deep copy an array, extracting only the sliced portion using MutableArrayData
pub fn deep_copy_array_sliced(array: &dyn Array) -> Arc<dyn Array> {
let data = array.to_data();
let data = deep_copy_array_data_sliced(&data);
make_array(data)
}
/// Deep copy a RecordBatch, extracting only the sliced portion using MutableArrayData
pub fn deep_copy_batch_sliced(batch: &RecordBatch) -> crate::Result<RecordBatch> {
let arrays = batch
.columns()
.iter()
.map(|array| deep_copy_array_sliced(array))
.collect::<Vec<_>>();
RecordBatch::try_new(batch.schema(), arrays)
}
#[cfg(test)]
mod tests {
use std::sync::Arc;
use arrow_array::{Array, Int32Array, RecordBatch, StringArray};
use arrow_schema::{DataType, Field, Schema};
#[test]
fn test_deep_copy_sliced_array_with_nulls() {
let array = Arc::new(Int32Array::from(vec![
Some(1),
None,
Some(3),
None,
Some(5),
]));
let sliced_array = array.slice(1, 3);
let copied_array = super::deep_copy_array(&sliced_array);
assert_eq!(sliced_array.len(), copied_array.len());
assert_eq!(sliced_array.nulls(), copied_array.nulls());
}
#[test]
fn test_deep_copy_array_data_sliced() {
let array = Int32Array::from((0..1000).collect::<Vec<i32>>());
let sliced = array.slice(100, 10);
let sliced_data = sliced.to_data();
let copied_data = super::deep_copy_array_data_sliced(&sliced_data);
assert_eq!(copied_data.len(), 10);
assert_eq!(copied_data.offset(), 0);
// Verify data correctness
let copied_array = Int32Array::from(copied_data);
for i in 0..10 {
assert_eq!(copied_array.value(i), 100 + i as i32);
}
}
#[test]
fn test_deep_copy_array_sliced() {
let array = Arc::new(Int32Array::from(vec![1, 2, 3, 4, 5]));
let sliced = array.slice(1, 3);
let copied = super::deep_copy_array_sliced(&sliced);
assert_eq!(copied.len(), 3);
let copied_int = copied.as_any().downcast_ref::<Int32Array>().unwrap();
assert_eq!(copied_int.value(0), 2);
assert_eq!(copied_int.value(1), 3);
assert_eq!(copied_int.value(2), 4);
}
#[test]
fn test_deep_copy_batch_sliced() {
let schema = Arc::new(Schema::new(vec![
Field::new("id", DataType::Int32, false),
Field::new("name", DataType::Utf8, false),
]));
let id_array = Arc::new(Int32Array::from((0..100).collect::<Vec<i32>>()));
let name_array = Arc::new(StringArray::from(
(0..100)
.map(|i| format!("name_{}", i))
.collect::<Vec<String>>(),
));
let batch = RecordBatch::try_new(
schema,
vec![id_array as Arc<dyn Array>, name_array as Arc<dyn Array>],
)
.unwrap();
let sliced = batch.slice(10, 5);
let copied = super::deep_copy_batch_sliced(&sliced).unwrap();
assert_eq!(copied.num_rows(), 5);
assert_eq!(copied.num_columns(), 2);
// Verify data correctness
let id_col = copied
.column(0)
.as_any()
.downcast_ref::<Int32Array>()
.unwrap();
let name_col = copied
.column(1)
.as_any()
.downcast_ref::<StringArray>()
.unwrap();
for i in 0..5 {
assert_eq!(id_col.value(i), 10 + i as i32);
assert_eq!(name_col.value(i), format!("name_{}", 10 + i));
}
}
#[test]
fn test_deep_copy_array_sliced_with_nulls() {
let array = Arc::new(Int32Array::from(vec![
Some(1),
None,
Some(3),
None,
Some(5),
]));
let sliced = array.slice(1, 3); // [None, Some(3), None]
let copied = super::deep_copy_array_sliced(&sliced);
assert_eq!(copied.len(), 3);
assert_eq!(copied.null_count(), 2); // Two nulls in the slice
let copied_int = copied.as_any().downcast_ref::<Int32Array>().unwrap();
assert!(!copied_int.is_valid(0)); // None
assert!(copied_int.is_valid(1)); // Some(3)
assert!(!copied_int.is_valid(2)); // None
assert_eq!(copied_int.value(1), 3);
}
}
lance-artifact/rust/lance-arrow/src/floats.rs
+291
View File
@@ -0,0 +1,291 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright The Lance Authors
//! Floats Array
use std::fmt::{Debug, Display};
use std::iter::Sum;
use std::sync::Arc;
use std::{
fmt::Formatter,
ops::{AddAssign, DivAssign},
};
use arrow_array::{
Array, FixedSizeBinaryArray, Float16Array, Float32Array, Float64Array,
types::{Float16Type, Float32Type, Float64Type},
};
use arrow_schema::{DataType, Field};
use half::{bf16, f16};
use num_traits::{AsPrimitive, Bounded, Float, FromPrimitive};
use super::bfloat16::{BFloat16Array, BFloat16Type};
use crate::Result;
use crate::bfloat16::is_bfloat16_field;
/// Float data type.
///
/// This helps differentiate between the different float types,
/// because bf16 is not officially supported [DataType] in arrow-rs.
#[derive(Debug)]
pub enum FloatType {
BFloat16,
Float16,
Float32,
Float64,
}
impl std::fmt::Display for FloatType {
fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
match self {
Self::BFloat16 => write!(f, "bfloat16"),
Self::Float16 => write!(f, "float16"),
Self::Float32 => write!(f, "float32"),
Self::Float64 => write!(f, "float64"),
}
}
}
/// Try to convert a [DataType] to a [FloatType]. To support bfloat16, always
/// prefer using the `TryFrom<&Field>` implementation.
impl TryFrom<&DataType> for FloatType {
type Error = crate::ArrowError;
fn try_from(value: &DataType) -> Result<Self> {
match *value {
DataType::Float16 => Ok(Self::Float16),
DataType::Float32 => Ok(Self::Float32),
DataType::Float64 => Ok(Self::Float64),
_ => Err(crate::ArrowError::InvalidArgumentError(format!(
"{:?} is not a floating type",
value
))),
}
}
}
impl TryFrom<&Field> for FloatType {
type Error = crate::ArrowError;
fn try_from(field: &Field) -> Result<Self> {
match field.data_type() {
DataType::FixedSizeBinary(2) if is_bfloat16_field(field) => Ok(Self::BFloat16),
_ => Self::try_from(field.data_type()),
}
}
}
/// Trait for float types used in Lance indexes
///
/// This mimics the utilities provided by [`arrow_array::ArrowPrimitiveType`]
/// but applies to all float types (including bfloat16)
pub trait ArrowFloatType: Debug {
type Native: FromPrimitive
+ FloatToArrayType<ArrowType = Self>
+ AsPrimitive<f32>
+ Debug
+ Display;
const FLOAT_TYPE: FloatType;
const MIN: Self::Native;
const MAX: Self::Native;
/// Arrow Float Array Type.
type ArrayType: FloatArray<Self>;
/// Returns empty array of this type.
fn empty_array() -> Self::ArrayType {
<Self::ArrayType as FloatArray<Self>>::from_values(Vec::new())
}
}
/// Trait to be implemented by native types that have a corresponding [`ArrowFloatType`]
/// implementation.
///
/// This helps define what operations are supported by native floats and also helps convert
/// from a native type back to the corresponding Arrow float type.
pub trait FloatToArrayType:
Float
+ Bounded
+ Sum
+ AddAssign<Self>
+ AsPrimitive<f64>
+ AsPrimitive<f32>
+ DivAssign
+ Send
+ Sync
+ Copy
{
/// The corresponding [`ArrowFloatType`] implementation for this native type
type ArrowType: ArrowFloatType<Native = Self>;
}
impl FloatToArrayType for bf16 {
type ArrowType = BFloat16Type;
}
impl FloatToArrayType for f16 {
type ArrowType = Float16Type;
}
impl FloatToArrayType for f32 {
type ArrowType = Float32Type;
}
impl FloatToArrayType for f64 {
type ArrowType = Float64Type;
}
impl ArrowFloatType for BFloat16Type {
type Native = bf16;
const FLOAT_TYPE: FloatType = FloatType::BFloat16;
const MIN: Self::Native = bf16::MIN;
const MAX: Self::Native = bf16::MAX;
type ArrayType = FixedSizeBinaryArray;
}
impl ArrowFloatType for Float16Type {
type Native = f16;
const FLOAT_TYPE: FloatType = FloatType::Float16;
const MIN: Self::Native = f16::MIN;
const MAX: Self::Native = f16::MAX;
type ArrayType = Float16Array;
}
impl ArrowFloatType for Float32Type {
type Native = f32;
const FLOAT_TYPE: FloatType = FloatType::Float32;
const MIN: Self::Native = f32::MIN;
const MAX: Self::Native = f32::MAX;
type ArrayType = Float32Array;
}
impl ArrowFloatType for Float64Type {
type Native = f64;
const FLOAT_TYPE: FloatType = FloatType::Float64;
const MIN: Self::Native = f64::MIN;
const MAX: Self::Native = f64::MAX;
type ArrayType = Float64Array;
}
/// [FloatArray] is a trait that is implemented by all float type arrays
///
/// This is similar to [`arrow_array::PrimitiveArray`] but applies to all float types (including bfloat16)
/// and is implemented as a trait and not a struct
pub trait FloatArray<T: ArrowFloatType + ?Sized>: Array + Clone + 'static {
type FloatType: ArrowFloatType;
/// Returns a reference to the underlying data as a slice.
///
/// # Panics
///
/// Implementations may panic if the array's storage shape does not match
/// the expected element layout. In particular, the `bf16` impl panics if
/// `value_length() != 2` (the `FixedSizeBinary(2)` shape required by
/// `BFloat16Array`).
///
/// # Preconditions
///
/// Implementations may impose additional invariants on the underlying
/// buffer. The `bf16` impl requires the value buffer to be at least
/// 2-byte aligned — satisfied automatically by every in-tree Lance
/// constructor, but external callers passing externally-built arrays
/// (FFI, IPC, `Buffer::from_custom_allocation`) must ensure alignment.
/// See the impl's docstring for details.
fn as_slice(&self) -> &[T::Native];
/// Construct an array from a vector of values.
fn from_values(values: Vec<T::Native>) -> Self;
/// Construct an array from an iterator of values.
fn from_iter_values(values: impl IntoIterator<Item = T::Native>) -> Self
where
Self: Sized,
{
Self::from_values(values.into_iter().collect())
}
}
impl FloatArray<Float16Type> for Float16Array {
type FloatType = Float16Type;
fn as_slice(&self) -> &[<Float16Type as ArrowFloatType>::Native] {
self.values()
}
fn from_values(values: Vec<<Float16Type as ArrowFloatType>::Native>) -> Self {
Self::from(values)
}
}
impl FloatArray<Float32Type> for Float32Array {
type FloatType = Float32Type;
fn as_slice(&self) -> &[<Float32Type as ArrowFloatType>::Native] {
self.values()
}
fn from_values(values: Vec<<Float32Type as ArrowFloatType>::Native>) -> Self {
Self::from(values)
}
}
impl FloatArray<Float64Type> for Float64Array {
type FloatType = Float64Type;
fn as_slice(&self) -> &[<Float64Type as ArrowFloatType>::Native] {
self.values()
}
fn from_values(values: Vec<<Float64Type as ArrowFloatType>::Native>) -> Self {
Self::from(values)
}
}
/// Convert a float32 array to another float array
///
/// This is used during queries as query vectors are always provided as float32 arrays
/// and need to be converted to the appropriate float type for the index.
pub fn coerce_float_vector(input: &Float32Array, float_type: FloatType) -> Result<Arc<dyn Array>> {
match float_type {
FloatType::BFloat16 => Ok(Arc::new(
BFloat16Array::from_iter_values(input.values().iter().map(|v| bf16::from_f32(*v)))
.into_inner(),
)),
FloatType::Float16 => Ok(Arc::new(Float16Array::from_iter_values(
input.values().iter().map(|v| f16::from_f32(*v)),
))),
FloatType::Float32 => Ok(Arc::new(input.clone())),
FloatType::Float64 => Ok(Arc::new(Float64Array::from_iter_values(
input.values().iter().map(|v| *v as f64),
))),
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn test_coerce_float_vector_bfloat16() {
let input = Float32Array::from(vec![1.0f32, 2.0, 3.0]);
let array = coerce_float_vector(&input, FloatType::BFloat16).unwrap();
assert_eq!(array.data_type(), &DataType::FixedSizeBinary(2));
let fixed = array
.as_any()
.downcast_ref::<FixedSizeBinaryArray>()
.unwrap();
let expected: Vec<bf16> = input.values().iter().map(|v| bf16::from_f32(*v)).collect();
assert_eq!(fixed.as_slice(), expected.as_slice());
}
}
lance-artifact/rust/lance-arrow/src/ipc.rs
+620
View File
@@ -0,0 +1,620 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright The Lance Authors
//! Zero-copy Arrow IPC stream read/write utilities.
//!
//! Provides helpers for serializing and deserializing [`RecordBatch`]es as
//! self-delimiting Arrow IPC streams using synchronous [`Read`]/[`Write`] I/O.
//!
//! These are designed for embedding IPC streams inside larger binary formats
//! (e.g. a cache entry that contains multiple IPC sections). Each stream is
//! self-delimiting (schema + batches + EOS marker) and can be read back
//! independently.
//!
//! # Zero-copy reads
//!
//! [`read_ipc_stream`] and [`read_ipc_stream_single`] take `&Bytes` and use
//! [`Bytes::slice`] to produce each message buffer. Because `Bytes::slice`
//! increments a reference count rather than copying, the resulting
//! [`Buffer`]s — and the array data decoded from them by [`FileDecoder`] —
//! are all backed by the same allocation as the input.
use std::io::{Read, Write};
use std::sync::Arc;
use arrow_array::RecordBatch;
use arrow_buffer::Buffer;
use arrow_ipc::convert::fb_to_schema;
use arrow_ipc::reader::FileDecoder;
use arrow_ipc::root_as_message;
use arrow_ipc::writer::StreamWriter;
use arrow_schema::ArrowError;
use bytes::Bytes;
// ---------------------------------------------------------------------------
// Length-prefixed byte utilities
// ---------------------------------------------------------------------------
/// Write `data` prefixed by its length as a little-endian `u64`.
///
/// Paired with [`read_len_prefixed_bytes`].
pub fn write_len_prefixed_bytes(writer: &mut dyn Write, data: &[u8]) -> Result<(), ArrowError> {
writer
.write_all(&(data.len() as u64).to_le_bytes())
.map_err(|e| ArrowError::IoError(e.to_string(), e))?;
writer
.write_all(data)
.map_err(|e| ArrowError::IoError(e.to_string(), e))
}
/// Read a byte slice written by [`write_len_prefixed_bytes`].
///
/// Reads an 8-byte little-endian length then exactly that many bytes.
pub fn read_len_prefixed_bytes(reader: &mut dyn Read) -> Result<Vec<u8>, ArrowError> {
let mut len_buf = [0u8; 8];
reader
.read_exact(&mut len_buf)
.map_err(|e| ArrowError::IoError(e.to_string(), e))?;
let len = u64::from_le_bytes(len_buf) as usize;
let mut buf = vec![0u8; len];
reader
.read_exact(&mut buf)
.map_err(|e| ArrowError::IoError(e.to_string(), e))?;
Ok(buf)
}
// ---------------------------------------------------------------------------
// IPC stream utilities
// ---------------------------------------------------------------------------
// 4-byte continuation marker used by modern Arrow IPC streams.
const IPC_CONTINUATION: [u8; 4] = [0xff; 4];
/// Write `batch` as a single-batch Arrow IPC stream to `writer`.
pub fn write_ipc_stream(batch: &RecordBatch, writer: &mut dyn Write) -> Result<(), ArrowError> {
let mut sw = StreamWriter::try_new(&mut *writer, batch.schema_ref())?;
sw.write(batch)?;
sw.finish()
}
/// Write all batches from `iter` as a single Arrow IPC stream to `writer`.
///
/// `iter` must yield at least one batch; the schema is inferred from the first
/// batch. Returns `ArrowError::InvalidArgumentError` if the iterator is empty.
/// If you need to write an empty stream (schema only, no rows), construct a
/// `StreamWriter` directly.
pub fn write_ipc_stream_batches<I>(iter: I, writer: &mut dyn Write) -> Result<(), ArrowError>
where
I: IntoIterator<Item = RecordBatch>,
{
let mut iter = iter.into_iter();
let first = iter
.next()
.ok_or_else(|| ArrowError::InvalidArgumentError("no batches to serialize".into()))?;
let mut sw = StreamWriter::try_new(&mut *writer, first.schema_ref())?;
sw.write(&first)?;
for batch in iter {
sw.write(&batch)?;
}
sw.finish()
}
/// Read one complete Arrow IPC stream message from `data` as a zero-copy [`Buffer`].
///
/// Parses the first message starting at byte 0 of `data`. Returns `None` on
/// EOS (size field == 0) or empty input. The returned [`Buffer`] is backed by
/// `data`'s allocation — no bytes are copied.
///
/// The caller should advance its position by `buf.len()` after each call.
fn read_one_ipc_message(data: &Bytes) -> Result<Option<Buffer>, ArrowError> {
let bytes = data.as_ref();
if bytes.is_empty() {
return Ok(None);
}
if bytes.len() < 4 {
return Err(ArrowError::IoError(
"IPC: truncated header".into(),
std::io::Error::new(std::io::ErrorKind::UnexpectedEof, "truncated IPC header"),
));
}
let has_continuation = bytes[..4] == IPC_CONTINUATION;
let (size_bytes, prefix_len): ([u8; 4], usize) = if has_continuation {
if bytes.len() < 8 {
return Err(ArrowError::IoError(
"IPC: truncated header after continuation".into(),
std::io::Error::new(
std::io::ErrorKind::UnexpectedEof,
"truncated after continuation",
),
));
}
(bytes[4..8].try_into().unwrap(), 8)
} else {
(bytes[..4].try_into().unwrap(), 4)
};
let meta_size = u32::from_le_bytes(size_bytes) as usize;
if meta_size == 0 {
return Ok(None); // EOS
}
let meta_end = prefix_len + meta_size;
if bytes.len() < meta_end {
return Err(ArrowError::IoError(
"IPC: truncated metadata".into(),
std::io::Error::new(std::io::ErrorKind::UnexpectedEof, "truncated IPC metadata"),
));
}
let msg = root_as_message(&bytes[prefix_len..meta_end])
.map_err(|e| ArrowError::ParseError(format!("IPC message parse error: {e}")))?;
let body_len = msg.bodyLength() as usize;
let total = meta_end + body_len;
if bytes.len() < total {
return Err(ArrowError::IoError(
"IPC: truncated body".into(),
std::io::Error::new(std::io::ErrorKind::UnexpectedEof, "truncated IPC body"),
));
}
// Zero-copy: Bytes::slice shares the backing allocation; Buffer::from
// wraps it without copying.
Ok(Some(Buffer::from(data.slice(0..total))))
}
/// Read a length-prefixed byte slice at `offset` in `data`, advancing `offset`.
///
/// Reads an 8-byte little-endian length, then slices exactly that many bytes
/// from `data`. The returned [`Bytes`] is zero-copy (shares `data`'s allocation).
pub fn read_len_prefixed_bytes_at(data: &Bytes, offset: &mut usize) -> Result<Bytes, ArrowError> {
let bytes = data.as_ref();
let len_end = offset
.checked_add(8)
.filter(|&e| e <= bytes.len())
.ok_or_else(|| {
ArrowError::IoError(
"length-prefixed bytes: truncated length field".into(),
std::io::Error::new(std::io::ErrorKind::UnexpectedEof, "truncated length"),
)
})?;
let len = u64::from_le_bytes(bytes[*offset..len_end].try_into().unwrap()) as usize;
*offset = len_end;
let data_end = offset
.checked_add(len)
.filter(|&e| e <= bytes.len())
.ok_or_else(|| {
ArrowError::IoError(
"length-prefixed bytes: truncated data".into(),
std::io::Error::new(std::io::ErrorKind::UnexpectedEof, "truncated data"),
)
})?;
let result = data.slice(*offset..data_end);
*offset = data_end;
Ok(result)
}
/// Read all [`RecordBatch`]es from one Arrow IPC stream starting at `offset`,
/// advancing `offset` past the stream (including the EOS marker).
///
/// Zero-copy: array buffers borrow from `data`'s allocation.
pub fn read_ipc_stream_at(
data: &Bytes,
offset: &mut usize,
) -> Result<Vec<RecordBatch>, ArrowError> {
let batches = read_ipc_stream(&data.slice(*offset..))?;
// Recompute how many bytes were consumed by re-parsing message sizes.
// We can't get this from read_ipc_stream directly, so we re-walk the
// message headers (metadata only, no body re-read) to sum up lengths.
let slice = &data.as_ref()[*offset..];
let mut consumed = 0usize;
loop {
let rem = &slice[consumed..];
if rem.is_empty() {
break;
}
let has_cont = rem.len() >= 4 && rem[..4] == IPC_CONTINUATION;
let (size_bytes, prefix_len): ([u8; 4], usize) = if has_cont {
if rem.len() < 8 {
break;
}
(rem[4..8].try_into().unwrap(), 8)
} else {
if rem.len() < 4 {
break;
}
(rem[..4].try_into().unwrap(), 4)
};
let meta_size = u32::from_le_bytes(size_bytes) as usize;
if meta_size == 0 {
// EOS — consume it and stop.
consumed += prefix_len;
break;
}
let meta_end = prefix_len + meta_size;
if rem.len() < meta_end {
break;
}
let msg = root_as_message(&rem[prefix_len..meta_end])
.map_err(|e| ArrowError::ParseError(format!("IPC message parse error: {e}")))?;
let body_len = msg.bodyLength() as usize;
consumed += meta_end + body_len;
}
*offset += consumed;
Ok(batches)
}
/// Read exactly one [`RecordBatch`] from one Arrow IPC stream starting at `offset`,
/// advancing `offset` past the stream (including the EOS marker).
///
/// Zero-copy: array buffers borrow from `data`'s allocation.
pub fn read_ipc_stream_single_at(
data: &Bytes,
offset: &mut usize,
) -> Result<RecordBatch, ArrowError> {
let mut batches = read_ipc_stream_at(data, offset)?;
match batches.len() {
1 => Ok(batches.remove(0)),
n => Err(ArrowError::ParseError(format!(
"expected exactly 1 IPC record batch, got {n}"
))),
}
}
/// Extract the prefix length and metadata size from a raw IPC message buffer.
///
/// Modern IPC streams have an 8-byte prefix `[continuation: 4][size: 4]`.
/// Legacy streams have a 4-byte prefix `[size: 4]`. Returns `(prefix_len, meta_size)`.
fn parse_ipc_message_prefix(buf: &Buffer) -> Result<(usize, usize), ArrowError> {
let has_continuation = buf.len() >= 4 && buf[..4] == IPC_CONTINUATION;
if has_continuation {
if buf.len() < 8 {
return Err(ArrowError::ParseError(
"IPC message buffer too short".into(),
));
}
let meta_size = u32::from_le_bytes(buf[4..8].try_into().unwrap()) as usize;
Ok((8, meta_size))
} else {
if buf.len() < 4 {
return Err(ArrowError::ParseError(
"IPC message buffer too short".into(),
));
}
let meta_size = u32::from_le_bytes(buf[..4].try_into().unwrap()) as usize;
Ok((4, meta_size))
}
}
/// Read all [`RecordBatch`]es from one Arrow IPC stream.
///
/// Zero-copy: each batch's array data buffers are borrowed from the input
/// message buffer(s) and not copied during decoding.
///
/// Uses [`FileDecoder`] directly (rather than `StreamDecoder`) to avoid a
/// known edge case where `StreamDecoder` does not produce a batch for messages
/// with a zero-length body when the message exactly fills the decode buffer.
pub fn read_ipc_stream(data: &Bytes) -> Result<Vec<RecordBatch>, ArrowError> {
let mut offset = 0usize;
let schema_buf = read_one_ipc_message(&data.slice(offset..))?.ok_or_else(|| {
ArrowError::ParseError("IPC stream: expected schema message, got EOS".into())
})?;
offset += schema_buf.len();
let (prefix_len, meta_size) = parse_ipc_message_prefix(&schema_buf)?;
let schema_msg = root_as_message(&schema_buf[prefix_len..prefix_len + meta_size])
.map_err(|e| ArrowError::ParseError(format!("IPC schema parse error: {e}")))?;
let schema = Arc::new(fb_to_schema(schema_msg.header_as_schema().ok_or_else(
|| ArrowError::ParseError("IPC stream: first message is not a schema".into()),
)?));
let mut decoder = FileDecoder::new(schema, schema_msg.version());
let mut batches = Vec::new();
loop {
let Some(buf) = read_one_ipc_message(&data.slice(offset..))? else {
break;
};
offset += buf.len();
let (prefix_len, meta_size) = parse_ipc_message_prefix(&buf)?;
let msg = root_as_message(&buf[prefix_len..prefix_len + meta_size])
.map_err(|e| ArrowError::ParseError(format!("IPC message parse error: {e}")))?;
let body_len = msg.bodyLength() as usize;
// Block offset = 0 since the buffer starts at the message boundary.
// metaDataLength = prefix_len + meta_size (prefix + flatbuf + padding).
let block = arrow_ipc::Block::new(0, (prefix_len + meta_size) as i32, body_len as i64);
match msg.header_type() {
arrow_ipc::MessageHeader::RecordBatch => {
if let Some(batch) = decoder.read_record_batch(&block, &buf)? {
batches.push(batch);
}
}
arrow_ipc::MessageHeader::DictionaryBatch => {
decoder.read_dictionary(&block, &buf)?;
}
_ => break,
}
}
Ok(batches)
}
/// Read exactly one [`RecordBatch`] from one Arrow IPC stream.
pub fn read_ipc_stream_single(data: &Bytes) -> Result<RecordBatch, ArrowError> {
let mut batches = read_ipc_stream(data)?;
match batches.len() {
1 => Ok(batches.remove(0)),
n => Err(ArrowError::ParseError(format!(
"expected exactly 1 IPC record batch, got {n}"
))),
}
}
// ---------------------------------------------------------------------------
// Aligned IPC sections
// ---------------------------------------------------------------------------
/// Byte alignment that each IPC section's stream start is padded to.
///
/// When several IPC streams are concatenated into one larger blob (e.g. a
/// cache entry), a section that starts at an arbitrary offset would leave its
/// array data misaligned. [`FileDecoder`] with `require_alignment = false`
/// then silently copies each buffer into a freshly aligned allocation on
/// every read, defeating zero-copy. Padding each section start to a 64-byte
/// boundary keeps the decoded buffers borrowed directly from the input.
pub const IPC_SECTION_ALIGNMENT: usize = 64;
/// Number of zero-padding bytes needed to advance `pos` to the next
/// [`IPC_SECTION_ALIGNMENT`] boundary.
fn section_padding(pos: usize) -> usize {
(IPC_SECTION_ALIGNMENT - (pos % IPC_SECTION_ALIGNMENT)) % IPC_SECTION_ALIGNMENT
}
/// A [`Write`] adapter that counts the bytes written through it.
struct CountingWriter<'a> {
inner: &'a mut dyn Write,
count: usize,
}
impl Write for CountingWriter<'_> {
fn write(&mut self, buf: &[u8]) -> std::io::Result<usize> {
let n = self.inner.write(buf)?;
self.count += n;
Ok(n)
}
fn flush(&mut self) -> std::io::Result<()> {
self.inner.flush()
}
}
/// Write zero padding so the next byte lands on an [`IPC_SECTION_ALIGNMENT`]
/// boundary, advancing `pos` past it.
fn write_section_padding(writer: &mut dyn Write, pos: &mut usize) -> Result<(), ArrowError> {
let pad = section_padding(*pos);
if pad > 0 {
const ZEROS: [u8; IPC_SECTION_ALIGNMENT] = [0u8; IPC_SECTION_ALIGNMENT];
writer
.write_all(&ZEROS[..pad])
.map_err(|e| ArrowError::IoError(e.to_string(), e))?;
*pos += pad;
}
Ok(())
}
/// Write `batch` as a 64-byte-aligned single-batch Arrow IPC section.
///
/// `pos` is the absolute byte offset of `writer` within the enclosing blob.
/// Zero padding is written first so the IPC stream begins on an
/// [`IPC_SECTION_ALIGNMENT`] boundary, then the stream itself. `pos` is
/// advanced past both the padding and the stream so the caller can write
/// further aligned sections.
///
/// Paired with [`read_ipc_section_at`]. For the decoded buffers to be borrowed
/// zero-copy, the blob must ultimately be read back from a buffer whose base
/// address is at least 64-byte aligned.
pub fn write_ipc_section(
writer: &mut dyn Write,
pos: &mut usize,
batch: &RecordBatch,
) -> Result<(), ArrowError> {
write_section_padding(writer, pos)?;
let mut counting = CountingWriter {
inner: writer,
count: 0,
};
write_ipc_stream(batch, &mut counting)?;
*pos += counting.count;
Ok(())
}
/// Read a single [`RecordBatch`] from an aligned IPC section at `offset`.
///
/// Skips the alignment padding written by [`write_ipc_section`], then reads
/// the stream, advancing `offset` past the section (padding + stream + EOS).
///
/// Zero-copy: array buffers borrow from `data`'s allocation when `data`'s base
/// address is at least 64-byte aligned (see [`write_ipc_section`]).
pub fn read_ipc_section_at(data: &Bytes, offset: &mut usize) -> Result<RecordBatch, ArrowError> {
*offset += section_padding(*offset);
read_ipc_stream_single_at(data, offset)
}
/// Write `batches` as a single 64-byte-aligned multi-batch Arrow IPC section.
///
/// Like [`write_ipc_section`] but emits every batch from `iter` into one IPC
/// stream (schema + N batches + EOS). `iter` must yield at least one batch.
/// Paired with [`read_ipc_section_batches_at`].
pub fn write_ipc_section_batches<I>(
writer: &mut dyn Write,
pos: &mut usize,
iter: I,
) -> Result<(), ArrowError>
where
I: IntoIterator<Item = RecordBatch>,
{
write_section_padding(writer, pos)?;
let mut counting = CountingWriter {
inner: writer,
count: 0,
};
write_ipc_stream_batches(iter, &mut counting)?;
*pos += counting.count;
Ok(())
}
/// Read all [`RecordBatch`]es from an aligned multi-batch IPC section at
/// `offset`, advancing `offset` past the section (padding + stream + EOS).
///
/// Zero-copy: array buffers borrow from `data`'s allocation when `data`'s base
/// address is at least 64-byte aligned (see [`write_ipc_section_batches`]).
pub fn read_ipc_section_batches_at(
data: &Bytes,
offset: &mut usize,
) -> Result<Vec<RecordBatch>, ArrowError> {
*offset += section_padding(*offset);
read_ipc_stream_at(data, offset)
}
#[cfg(test)]
mod tests {
use arrow_array::{ArrayRef, record_batch};
use super::*;
#[test]
fn test_ipc_roundtrip() {
let batch1 = record_batch!(
("int", Int32, [1, 2, 3]),
("str", Utf8, ["foo", "bar", "baz"])
)
.unwrap();
let batch2 = record_batch!(("int", Int32, [4, 5]), ("str", Utf8, ["qux", "quux"])).unwrap();
let batches = vec![batch1.clone(), batch2.clone()];
let mut buf = Vec::new();
write_ipc_stream_batches(batches, &mut buf).unwrap();
let data = Bytes::from(buf);
let batches = read_ipc_stream(&data).unwrap();
assert_eq!(batches.len(), 2);
assert_eq!(batches[0], batch1);
assert_eq!(batches[1], batch2);
let data_base = data.as_ptr() as usize;
let data_end = data_base + data.len();
let assert_col_zero_copy = |array: &ArrayRef| {
for buffer in array.to_data().buffers() {
let ptr = buffer.as_ptr() as usize;
assert!(
ptr >= data_base && ptr < data_end,
"buffer at {ptr:#x} is not backed by the input Bytes allocation \
[{data_base:#x}..{data_end:#x})"
);
}
};
for batch in &batches {
assert_eq!(batch.schema(), batch1.schema());
assert_col_zero_copy(batch.column(0));
assert_col_zero_copy(batch.column(1));
}
}
/// Allocate a [`Bytes`] whose base address is 64-byte aligned, modelling a
/// backend that reads cache entries into an aligned buffer. A plain
/// `Bytes::from(vec)` only guarantees the allocator's alignment for `u8`.
fn aligned_bytes(payload: &[u8]) -> Bytes {
let mut v = vec![0u8; payload.len() + IPC_SECTION_ALIGNMENT];
let pad = section_padding(v.as_ptr() as usize);
v[pad..pad + payload.len()].copy_from_slice(payload);
Bytes::from(v).slice(pad..pad + payload.len())
}
#[test]
fn test_aligned_ipc_sections_are_zero_copy() {
// A LargeBinary column exercises the i64-offset buffer whose 8-byte
// alignment requirement triggers a realigning memcpy when misaligned.
let blocks = arrow_array::LargeBinaryArray::from_vec(vec![&b"hello"[..], b"world"]);
let section_a = RecordBatch::try_from_iter([("a", Arc::new(blocks) as ArrayRef)]).unwrap();
let section_b = record_batch!(("b", Int64, [10i64, 20, 30, 40, 50])).unwrap();
let mut buf = Vec::new();
// Arbitrary, deliberately non-64-aligned preamble so the first section
// must be padded rather than landing at offset 0 by luck.
buf.extend_from_slice(&[0xABu8; 7]);
let mut pos = buf.len();
// The first section's stream begins after padding the 7-byte preamble
// up to the next 64-byte boundary.
assert_eq!(7 + section_padding(7), IPC_SECTION_ALIGNMENT);
write_ipc_section(&mut buf, &mut pos, &section_a).unwrap();
write_ipc_section(&mut buf, &mut pos, &section_b).unwrap();
let data = aligned_bytes(&buf);
assert_eq!(
section_padding(data.as_ptr() as usize),
0,
"base not aligned"
);
let mut offset = 7;
let read_a = read_ipc_section_at(&data, &mut offset).unwrap();
let read_b = read_ipc_section_at(&data, &mut offset).unwrap();
assert_eq!(read_a, section_a);
assert_eq!(read_b, section_b);
let data_base = data.as_ptr() as usize;
let data_end = data_base + data.len();
for batch in [&read_a, &read_b] {
for buffer in batch.column(0).to_data().buffers() {
let ptr = buffer.as_ptr() as usize;
assert!(
ptr >= data_base && ptr < data_end,
"section buffer at {ptr:#x} was realigned out of the input \
[{data_base:#x}..{data_end:#x}) — misaligned section",
);
}
}
}
#[test]
fn test_aligned_multi_batch_section_roundtrip_zero_copy() {
// A multi-batch section (e.g. IVF SQ storage chunks) must round-trip
// every batch and decode the first batch's buffers zero-copy.
let b1 = record_batch!(("v", Int64, [1i64, 2, 3])).unwrap();
let b2 = record_batch!(("v", Int64, [4i64, 5])).unwrap();
let b3 = record_batch!(("v", Int64, [6i64])).unwrap();
let mut buf = vec![0xCDu8; 5];
let mut pos = buf.len();
write_ipc_section_batches(&mut buf, &mut pos, [b1.clone(), b2.clone(), b3.clone()])
.unwrap();
let data = aligned_bytes(&buf);
let mut offset = 5;
let read = read_ipc_section_batches_at(&data, &mut offset).unwrap();
assert_eq!(read, vec![b1, b2, b3]);
assert_eq!(offset, buf.len(), "offset should land at section end");
let data_base = data.as_ptr() as usize;
let data_end = data_base + data.len();
for buffer in read[0].column(0).to_data().buffers() {
let ptr = buffer.as_ptr() as usize;
assert!(
ptr >= data_base && ptr < data_end,
"first batch buffer at {ptr:#x} was realigned out of the input",
);
}
}
}
lance-artifact/rust/lance-arrow/src/json.rs
+1445
View File
File diff suppressed because it is too large Load Diff
lance-artifact/rust/lance-arrow/src/lib.rs
+2764
View File
File diff suppressed because it is too large Load Diff
lance-artifact/rust/lance-arrow/src/list.rs
+176
View File
@@ -0,0 +1,176 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright The Lance Authors
use std::sync::Arc;
use arrow_array::{Array, BooleanArray, GenericListArray, OffsetSizeTrait};
use arrow_buffer::{BooleanBufferBuilder, OffsetBuffer, ScalarBuffer};
use arrow_schema::Field;
pub trait ListArrayExt {
/// Filters out masked null items from the list array
///
/// It is legal for a list array to have a null entry with a non-zero length. The
/// values inside the entry are "garbage" and should be ignored. This function
/// filters the values array to remove the garbage values.
///
/// The output list will always have zero-length nulls.
fn filter_garbage_nulls(&self) -> Self;
/// Returns a copy of the list's values array that has been sliced to size
///
/// It is legal for a list array's offsets to not start with zero. It's also legal
/// for a list array's offsets to not extend to the entire values array. This function
/// behaves similarly to `values()` except it slices the array so that it starts at
/// the first list offset and ends at the last list offset.
fn trimmed_values(&self) -> Arc<dyn Array>;
/// The offset type of the underlying list array.
type Offset: OffsetSizeTrait;
/// Returns offsets shifted so the first offset is zero, matching
/// [`Self::trimmed_values`].
///
/// Sliced list arrays (e.g. a filtered batch) keep offsets that reference the
/// original values buffer, so combining them with trimmed values produces
/// offsets that exceed the values length. Use this together with
/// `trimmed_values` when constructing a new list array.
fn trimmed_offsets(&self) -> OffsetBuffer<Self::Offset>;
}
impl<OffsetSize: OffsetSizeTrait> ListArrayExt for GenericListArray<OffsetSize> {
fn filter_garbage_nulls(&self) -> Self {
if self.is_empty() {
return self.clone();
}
let Some(validity) = self.nulls().cloned() else {
return self.clone();
};
let mut should_keep = BooleanBufferBuilder::new(self.values().len());
// Handle case where offsets do not start at 0
let preamble_len = self.offsets().first().unwrap().to_usize().unwrap();
should_keep.append_n(preamble_len, false);
let mut new_offsets: Vec<OffsetSize> = Vec::with_capacity(self.len() + 1);
new_offsets.push(OffsetSize::zero());
let mut cur_len = OffsetSize::zero();
for (offset, is_valid) in self.offsets().windows(2).zip(validity.iter()) {
let len = offset[1] - offset[0];
if is_valid {
cur_len += len;
should_keep.append_n(len.to_usize().unwrap(), true);
new_offsets.push(cur_len);
} else {
should_keep.append_n(len.to_usize().unwrap(), false);
new_offsets.push(cur_len);
}
}
// Offsets may not reference entire values buffer
let trailer = self.values().len() - should_keep.len();
should_keep.append_n(trailer, false);
let should_keep = should_keep.finish();
let should_keep = BooleanArray::new(should_keep, None);
let new_values = arrow_select::filter::filter(self.values(), &should_keep).unwrap();
let new_offsets = ScalarBuffer::from(new_offsets);
let new_offsets = OffsetBuffer::new(new_offsets);
Self::new(
Arc::new(Field::new(
"item",
self.value_type(),
self.values().is_nullable(),
)),
new_offsets,
new_values,
Some(validity),
)
}
fn trimmed_values(&self) -> Arc<dyn Array> {
let first_value = self
.offsets()
.first()
.map(|v| v.to_usize().unwrap())
.unwrap_or(0);
let last_value = self
.offsets()
.last()
.map(|v| v.to_usize().unwrap())
.unwrap_or(0);
self.values().slice(first_value, last_value - first_value)
}
type Offset = OffsetSize;
fn trimmed_offsets(&self) -> OffsetBuffer<OffsetSize> {
let offsets = self.offsets();
let Some(&first) = offsets.first() else {
return offsets.clone();
};
if first == OffsetSize::zero() {
return offsets.clone();
}
let shifted: Vec<OffsetSize> = offsets.iter().map(|&o| o - first).collect();
OffsetBuffer::new(ScalarBuffer::from(shifted))
}
}
#[cfg(test)]
mod tests {
use std::sync::Arc;
use arrow_array::{ListArray, UInt64Array};
use arrow_buffer::{BooleanBuffer, NullBuffer, OffsetBuffer, ScalarBuffer};
use arrow_schema::{DataType, Field};
use super::ListArrayExt;
#[test]
fn test_filter_garbage_nulls() {
let items = UInt64Array::from(vec![0, 1, 2, 3, 4, 5, 6, 7, 8, 9]);
let offsets = ScalarBuffer::<i32>::from(vec![2, 5, 8, 9]);
let offsets = OffsetBuffer::new(offsets);
let list_validity = NullBuffer::new(BooleanBuffer::from(vec![true, false, true]));
let list_arr = ListArray::new(
Arc::new(Field::new("item", DataType::UInt64, true)),
offsets,
Arc::new(items),
Some(list_validity.clone()),
);
let filtered = list_arr.filter_garbage_nulls();
let expected_items = UInt64Array::from(vec![2, 3, 4, 8]);
let offsets = ScalarBuffer::<i32>::from(vec![0, 3, 3, 4]);
let expected = ListArray::new(
Arc::new(Field::new("item", DataType::UInt64, false)),
OffsetBuffer::new(offsets),
Arc::new(expected_items),
Some(list_validity),
);
assert_eq!(filtered, expected);
}
#[test]
fn test_trim_values() {
let items = UInt64Array::from(vec![0, 1, 2, 3, 4, 5, 6, 7, 8, 9]);
let offsets = ScalarBuffer::<i32>::from(vec![2, 5, 6, 8, 9]);
let offsets = OffsetBuffer::new(offsets);
let list_arr = ListArray::new(
Arc::new(Field::new("item", DataType::UInt64, true)),
offsets,
Arc::new(items),
None,
);
let list_arr = list_arr.slice(1, 2);
let trimmed = list_arr.trimmed_values();
let expected_items = UInt64Array::from(vec![0, 1, 2, 3, 4, 5, 6, 7, 8, 9]);
let expected_items = expected_items.slice(5, 3);
assert_eq!(trimmed.as_ref(), &expected_items);
}
}
lance-artifact/rust/lance-arrow/src/memory.rs
+91
View File
@@ -0,0 +1,91 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright The Lance Authors
use std::collections::HashSet;
use arrow_array::{Array, RecordBatch};
use arrow_data::ArrayData;
/// Counts memory used by buffers of Arrow arrays and RecordBatches.
///
/// This is meant to capture how much memory is being used by the Arrow data
/// structures as they are. It does not represent the memory used if the data
/// were to be serialized and then deserialized. In particular:
///
/// * This does not double count memory used by buffers shared by multiple
/// arrays or batches. Round-tripped data may use more memory because of this.
/// * This counts the **total** size of the buffers, even if the array is a slice.
/// Round-tripped data may use less memory because of this.
#[derive(Default)]
pub struct MemoryAccumulator {
seen: HashSet<usize>,
total: usize,
}
impl MemoryAccumulator {
pub fn record_array(&mut self, array: &dyn Array) {
let data = array.to_data();
self.record_array_data(&data);
}
fn record_array_data(&mut self, data: &ArrayData) {
for buffer in data.buffers() {
let ptr = buffer.as_ptr();
if self.seen.insert(ptr as usize) {
self.total += buffer.capacity();
}
}
if let Some(nulls) = data.nulls() {
let null_buf = nulls.inner().inner();
let ptr = null_buf.as_ptr();
if self.seen.insert(ptr as usize) {
self.total += null_buf.capacity();
}
}
for child in data.child_data() {
self.record_array_data(child);
}
}
pub fn record_batch(&mut self, batch: &RecordBatch) {
for array in batch.columns() {
self.record_array(array);
}
}
pub fn total(&self) -> usize {
self.total
}
}
#[cfg(test)]
mod tests {
use std::sync::Arc;
use arrow_array::Int32Array;
use arrow_schema::{DataType, Field, Schema};
use super::*;
#[test]
fn test_memory_accumulator() {
let batch = RecordBatch::try_new(
Arc::new(Schema::new(vec![Field::new("a", DataType::Int32, false)])),
vec![Arc::new(Int32Array::from(vec![1, 2, 3]))],
)
.unwrap();
let slice = batch.slice(1, 2);
let mut acc = MemoryAccumulator::default();
// Should record whole buffer, not just slice
acc.record_batch(&slice);
assert_eq!(acc.total(), 3 * std::mem::size_of::<i32>());
// Should not double count
acc.record_batch(&slice);
assert_eq!(acc.total(), 3 * std::mem::size_of::<i32>());
}
}
lance-artifact/rust/lance-arrow/src/scalar.rs
+282
View File
@@ -0,0 +1,282 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright The Lance Authors
use arrow_array::{ArrayRef, make_array};
use arrow_buffer::Buffer;
use arrow_data::{ArrayDataBuilder, transform::MutableArrayData};
use arrow_schema::{ArrowError, DataType};
use crate::DataTypeExt;
type Result<T> = std::result::Result<T, ArrowError>;
pub const INLINE_VALUE_MAX_BYTES: usize = 32;
pub fn extract_scalar_value(array: &ArrayRef, idx: usize) -> Result<ArrayRef> {
if idx >= array.len() {
return Err(ArrowError::InvalidArgumentError(
"Scalar index out of bounds".to_string(),
));
}
let data = array.to_data();
let mut mutable = MutableArrayData::new(vec![&data], /*use_nulls=*/ true, 1);
mutable.extend(0, idx, idx + 1);
Ok(make_array(mutable.freeze()))
}
fn read_u32(buf: &[u8], offset: &mut usize) -> Result<u32> {
if *offset + 4 > buf.len() {
return Err(ArrowError::InvalidArgumentError(
"Invalid scalar value buffer: unexpected EOF".to_string(),
));
}
let bytes = [
buf[*offset],
buf[*offset + 1],
buf[*offset + 2],
buf[*offset + 3],
];
*offset += 4;
Ok(u32::from_le_bytes(bytes))
}
fn read_bytes<'a>(buf: &'a [u8], offset: &mut usize, len: usize) -> Result<&'a [u8]> {
if *offset + len > buf.len() {
return Err(ArrowError::InvalidArgumentError(
"Invalid scalar value buffer: unexpected EOF".to_string(),
));
}
let slice = &buf[*offset..*offset + len];
*offset += len;
Ok(slice)
}
fn write_u32(out: &mut Vec<u8>, v: u32) {
out.extend_from_slice(&v.to_le_bytes());
}
fn write_bytes(out: &mut Vec<u8>, bytes: &[u8]) {
out.extend_from_slice(bytes);
}
pub fn encode_scalar_value_buffer(scalar: &ArrayRef) -> Result<Vec<u8>> {
if scalar.len() != 1 || scalar.null_count() != 0 {
return Err(ArrowError::InvalidArgumentError(
"Scalar value buffer must be a single non-null value".to_string(),
));
}
let data = scalar.to_data();
if data.offset() != 0 {
return Err(ArrowError::InvalidArgumentError(
"Scalar value buffer must have offset=0".to_string(),
));
}
if !data.child_data().is_empty() {
return Err(ArrowError::InvalidArgumentError(
"Scalar value buffer does not support nested types".to_string(),
));
}
// Minimal format (RFC): store the Arrow value buffers for a length-1 array.
// Null bitmap and child data are intentionally not supported here.
//
// | u32 num_buffers |
// | u32 buffer_0_len | ... | u32 buffer_{n-1}_len |
// | buffer_0 bytes | ... | buffer_{n-1} bytes |
let mut out = Vec::with_capacity(128);
let buffers = data.buffers();
write_u32(&mut out, buffers.len() as u32);
for b in buffers {
write_u32(&mut out, b.len() as u32);
}
for b in buffers {
write_bytes(&mut out, b.as_slice());
}
Ok(out)
}
pub fn decode_scalar_from_value_buffer(
data_type: &DataType,
value_buffer: &[u8],
) -> Result<ArrayRef> {
if matches!(
data_type,
DataType::Struct(_) | DataType::FixedSizeList(_, _)
) {
return Err(ArrowError::InvalidArgumentError(format!(
"Scalar value buffer does not support nested data type {:?}",
data_type
)));
}
let mut offset = 0;
let num_buffers = read_u32(value_buffer, &mut offset)? as usize;
let buffer_lens = (0..num_buffers)
.map(|_| read_u32(value_buffer, &mut offset).map(|l| l as usize))
.collect::<Result<Vec<_>>>()?;
let mut buffers = Vec::with_capacity(num_buffers);
for len in buffer_lens {
let bytes = read_bytes(value_buffer, &mut offset, len)?;
buffers.push(Buffer::from_vec(bytes.to_vec()));
}
if offset != value_buffer.len() {
return Err(ArrowError::InvalidArgumentError(
"Invalid scalar value buffer: trailing bytes".to_string(),
));
}
let mut builder = ArrayDataBuilder::new(data_type.clone())
.len(1)
.null_count(0);
for b in buffers {
builder = builder.add_buffer(b);
}
Ok(make_array(builder.build()?))
}
pub fn decode_scalar_from_inline_value(
data_type: &DataType,
inline_value: &[u8],
) -> Result<ArrayRef> {
// I expect our input to be safe here, but I added some debug_assert_eq statements just in case.
// If they are triggered, we may need to change them to return actual errors.
//
// Boolean values are bit-packed in Arrow and therefore are not "fixed-stride" in bytes.
// As a result, `byte_width_opt()` returns `None` for `DataType::Boolean`, even though a
// length-1 scalar can be represented inline using a single byte (matching `try_inline_value`).
if matches!(data_type, DataType::Boolean) {
debug_assert_eq!(
inline_value.len(),
1,
"Invalid boolean inline scalar length (expected 1 byte, got {})",
inline_value.len()
);
} else if let Some(byte_width) = data_type.byte_width_opt() {
debug_assert_eq!(
inline_value.len(),
byte_width,
"Inline constant length mismatch for {:?}: expected {} bytes but got {}",
data_type,
byte_width,
inline_value.len()
);
}
let data = ArrayDataBuilder::new(data_type.clone())
.len(1)
.null_count(0)
.add_buffer(Buffer::from_vec(inline_value.to_vec()))
.build()?;
Ok(make_array(data))
}
pub fn try_inline_value(scalar: &ArrayRef) -> Option<Vec<u8>> {
if scalar.null_count() != 0 || scalar.len() != 1 {
return None;
}
let data = scalar.to_data();
if !data.child_data().is_empty() {
return None;
}
if data.buffers().len() != 1 {
return None;
}
let bytes = data.buffers()[0].as_slice();
if bytes.len() > INLINE_VALUE_MAX_BYTES {
return None;
}
Some(bytes.to_vec())
}
#[cfg(test)]
mod tests {
use std::sync::Arc;
use arrow_array::{BooleanArray, FixedSizeBinaryArray, Int32Array, StringArray, cast::AsArray};
use super::*;
#[test]
fn test_extract_scalar_value() {
let array: ArrayRef = Arc::new(Int32Array::from(vec![Some(1), None, Some(3)]));
let scalar = extract_scalar_value(&array, 2).unwrap();
assert_eq!(scalar.len(), 1);
assert_eq!(
scalar
.as_primitive::<arrow_array::types::Int32Type>()
.value(0),
3
);
}
#[test]
fn test_scalar_value_buffer_utf8_round_trip() {
let scalar: ArrayRef = Arc::new(StringArray::from(vec!["hello"]));
let buf = encode_scalar_value_buffer(&scalar).unwrap();
let decoded = decode_scalar_from_value_buffer(&DataType::Utf8, &buf).unwrap();
assert_eq!(decoded.len(), 1);
assert_eq!(decoded.null_count(), 0);
assert_eq!(decoded.as_string::<i32>().value(0), "hello");
}
#[test]
fn test_scalar_value_buffer_fixed_size_binary_round_trip() {
let val = vec![0xABu8; 33];
let scalar: ArrayRef = Arc::new(
FixedSizeBinaryArray::try_from_sparse_iter_with_size(
std::iter::once(Some(val.as_slice())),
33,
)
.unwrap(),
);
let buf = encode_scalar_value_buffer(&scalar).unwrap();
let decoded =
decode_scalar_from_value_buffer(&DataType::FixedSizeBinary(33), &buf).unwrap();
assert_eq!(decoded.len(), 1);
assert_eq!(decoded.as_fixed_size_binary().value(0), val.as_slice());
}
#[test]
fn test_inline_value_boolean_round_trip() {
let scalar: ArrayRef = Arc::new(BooleanArray::from_iter([Some(true)]));
let inline = try_inline_value(&scalar).unwrap();
let decoded = decode_scalar_from_inline_value(&DataType::Boolean, &inline).unwrap();
assert_eq!(decoded.len(), 1);
assert_eq!(decoded.null_count(), 0);
assert!(decoded.as_boolean().value(0));
}
#[test]
fn test_scalar_value_buffer_rejects_nested_type() {
let field = Arc::new(arrow_schema::Field::new("item", DataType::Int32, false));
let list: ArrayRef = Arc::new(arrow_array::FixedSizeListArray::new(
field,
2,
Arc::new(Int32Array::from(vec![1, 2])),
None,
));
let scalar = list.slice(0, 1);
assert!(encode_scalar_value_buffer(&scalar).is_err());
}
#[test]
fn test_decode_scalar_from_value_buffer_rejects_nested_type() {
let buf = Vec::<u8>::new();
let res =
decode_scalar_from_value_buffer(&DataType::Struct(arrow_schema::Fields::empty()), &buf);
assert!(res.is_err());
}
#[test]
fn test_decode_scalar_from_value_buffer_trailing_bytes() {
// num_buffers = 0, plus an extra byte
let mut bytes = Vec::new();
bytes.extend_from_slice(&0u32.to_le_bytes());
bytes.push(1);
let res = decode_scalar_from_value_buffer(&DataType::Int32, &bytes);
assert!(res.is_err());
}
}
lance-artifact/rust/lance-arrow/src/schema.rs
+207
View File
@@ -0,0 +1,207 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright The Lance Authors
//! Extension to arrow schema
use arrow_schema::{ArrowError, DataType, Field, FieldRef, Schema};
use crate::{ARROW_EXT_NAME_KEY, BLOB_META_KEY, BLOB_V2_EXT_NAME};
pub enum Indentation {
OneLine,
MultiLine(u8),
}
impl Indentation {
fn value(&self) -> String {
match self {
Self::OneLine => "".to_string(),
Self::MultiLine(spaces) => " ".repeat(*spaces as usize),
}
}
fn deepen(&self) -> Self {
match self {
Self::OneLine => Self::OneLine,
Self::MultiLine(spaces) => Self::MultiLine(spaces + 2),
}
}
}
/// Extends the functionality of [arrow_schema::Field].
pub trait FieldExt {
/// Create a compact string representation of the field
///
/// This is intended for display purposes and not for serialization
fn to_compact_string(&self, indent: Indentation) -> String;
/// Check if the field is marked as a packed struct
fn is_packed_struct(&self) -> bool;
/// Check if the field is marked as a blob
fn is_blob(&self) -> bool;
/// Check if the field is marked as a blob
fn is_blob_v2(&self) -> bool;
}
impl FieldExt for Field {
fn to_compact_string(&self, indent: Indentation) -> String {
let mut result = format!("{}: ", self.name().clone());
match self.data_type() {
DataType::Struct(fields) => {
result += "{";
result += &indent.value();
for (field_idx, field) in fields.iter().enumerate() {
result += field.to_compact_string(indent.deepen()).as_str();
if field_idx < fields.len() - 1 {
result += ",";
}
result += indent.value().as_str();
}
result += "}";
}
DataType::List(field)
| DataType::LargeList(field)
| DataType::ListView(field)
| DataType::LargeListView(field) => {
result += "[";
result += field.to_compact_string(indent.deepen()).as_str();
result += "]";
}
DataType::FixedSizeList(child, dimension) => {
result += &format!(
"[{}; {}]",
child.to_compact_string(indent.deepen()),
dimension
);
}
DataType::Dictionary(key_type, value_type) => {
result += &value_type.to_string();
result += "@";
result += &key_type.to_string();
}
_ => {
result += &self.data_type().to_string();
}
}
if self.is_nullable() {
result += "?";
}
result
}
// Check if field has metadata `packed` set to true, this check is case insensitive.
fn is_packed_struct(&self) -> bool {
let field_metadata = self.metadata();
const PACKED_KEYS: [&str; 2] = ["packed", "lance-encoding:packed"];
PACKED_KEYS.iter().any(|key| {
field_metadata
.get(*key)
.map(|value| value.eq_ignore_ascii_case("true"))
.unwrap_or(false)
})
}
fn is_blob(&self) -> bool {
let field_metadata = self.metadata();
field_metadata.get(BLOB_META_KEY).is_some()
|| field_metadata
.get(ARROW_EXT_NAME_KEY)
.map(|value| value == BLOB_V2_EXT_NAME)
.unwrap_or(false)
}
fn is_blob_v2(&self) -> bool {
let field_metadata = self.metadata();
field_metadata
.get(ARROW_EXT_NAME_KEY)
.map(|value| value == BLOB_V2_EXT_NAME)
.unwrap_or(false)
}
}
/// Extends the functionality of [arrow_schema::Schema].
pub trait SchemaExt {
/// Create a new [`Schema`] with one extra field.
fn try_with_column(&self, field: Field) -> std::result::Result<Schema, ArrowError>;
fn try_with_column_at(
&self,
index: usize,
field: Field,
) -> std::result::Result<Schema, ArrowError>;
fn field_names(&self) -> Vec<&String>;
fn without_column(&self, column_name: &str) -> Schema;
/// Create a compact string representation of the schema
///
/// This is intended for display purposes and not for serialization
fn to_compact_string(&self, indent: Indentation) -> String;
}
impl SchemaExt for Schema {
fn try_with_column(&self, field: Field) -> std::result::Result<Schema, ArrowError> {
if self.column_with_name(field.name()).is_some() {
return Err(ArrowError::SchemaError(format!(
"Can not append column {} on schema: {:?}",
field.name(),
self
)));
};
let mut fields: Vec<FieldRef> = self.fields().iter().cloned().collect();
fields.push(FieldRef::new(field));
Ok(Self::new_with_metadata(fields, self.metadata.clone()))
}
fn try_with_column_at(
&self,
index: usize,
field: Field,
) -> std::result::Result<Schema, ArrowError> {
if self.column_with_name(field.name()).is_some() {
return Err(ArrowError::SchemaError(format!(
"Failed to modify schema: Inserting column {} would create a duplicate column in schema: {:?}",
field.name(),
self
)));
};
let mut fields: Vec<FieldRef> = self.fields().iter().cloned().collect();
fields.insert(index, FieldRef::new(field));
Ok(Self::new_with_metadata(fields, self.metadata.clone()))
}
/// Project the schema to remove the given column.
///
/// This only works on top-level fields right now. If a field does not exist,
/// the schema will be returned as is.
fn without_column(&self, column_name: &str) -> Schema {
let fields: Vec<FieldRef> = self
.fields()
.iter()
.filter(|f| f.name() != column_name)
.cloned()
.collect();
Self::new_with_metadata(fields, self.metadata.clone())
}
fn field_names(&self) -> Vec<&String> {
self.fields().iter().map(|f| f.name()).collect()
}
fn to_compact_string(&self, indent: Indentation) -> String {
let mut result = "{".to_string();
result += &indent.value();
for (field_idx, field) in self.fields.iter().enumerate() {
result += field.to_compact_string(indent.deepen()).as_str();
if field_idx < self.fields.len() - 1 {
result += ",";
}
result += indent.value().as_str();
}
result += "}";
result
}
}
lance-artifact/rust/lance-arrow/src/stream.rs
+504
View File
@@ -0,0 +1,504 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright The Lance Authors
//! Utilities for working with streams of [`RecordBatch`].
use arrow_array::RecordBatch;
use arrow_schema::{ArrowError, SchemaRef};
use futures::stream::{self, Stream, StreamExt};
use std::pin::Pin;
use crate::deepcopy::deep_copy_batch_sliced;
/// Rechunks a stream of [`RecordBatch`] so that each output batch has
/// approximately `target_bytes` of array data.
///
/// Small input batches are accumulated (by concatenation) until at least
/// `min_bytes` of data has been collected. If the resulting batch exceeds
/// `max_bytes`, it is sliced into roughly equal pieces of ~`max_bytes`
/// (assuming uniform row sizes).
pub fn rechunk_stream_by_size<S, E>(
input: S,
input_schema: SchemaRef,
min_bytes: usize,
max_bytes: usize,
) -> impl Stream<Item = Result<RecordBatch, E>>
where
S: Stream<Item = Result<RecordBatch, E>>,
E: From<ArrowError>,
{
rechunk_stream_by_size_inner(input, input_schema, min_bytes, max_bytes, false)
}
/// Like [`rechunk_stream_by_size`] but deep-copies slices so that
/// `get_array_memory_size` reflects the true size of each output batch.
///
/// After a normal `RecordBatch::slice`, the backing buffers are shared with
/// the original batch, so `get_array_memory_size` still reports the full
/// parent size. This variant deep-copies every slice produced during the
/// splitting phase, which allows the stream to detect and re-split slices
/// that still exceed `max_bytes` (e.g. because a single row is much larger
/// than average).
///
/// The deep copy is a last resort and potentially expensive for large
/// batches. However, it is only performed when a batch actually needs to be
/// sliced — batches that are already within the target range pass through at
/// zero cost. Use this only when the hard cap on `max_bytes` is a
/// correctness requirement, not merely a performance hint.
pub fn rechunk_stream_by_size_deep_copy<S, E>(
input: S,
input_schema: SchemaRef,
min_bytes: usize,
max_bytes: usize,
) -> impl Stream<Item = Result<RecordBatch, E>>
where
S: Stream<Item = Result<RecordBatch, E>>,
E: From<ArrowError>,
{
rechunk_stream_by_size_inner(input, input_schema, min_bytes, max_bytes, true)
}
fn rechunk_stream_by_size_inner<S, E>(
input: S,
input_schema: SchemaRef,
min_bytes: usize,
max_bytes: usize,
deep_copy: bool,
) -> impl Stream<Item = Result<RecordBatch, E>>
where
S: Stream<Item = Result<RecordBatch, E>>,
E: From<ArrowError>,
{
stream::try_unfold(
RechunkState {
input: Box::pin(input),
accumulated: Vec::new(),
acc_bytes: 0,
done: false,
input_schema,
min_bytes,
max_bytes,
deep_copy,
},
|mut state| async move {
if state.done && state.accumulated.is_empty() {
return Ok(None);
}
// Pull batches until we reach the byte target or exhaust input.
// Always pull at least one batch so that min_bytes=0 works.
while !state.done && (state.accumulated.is_empty() || state.acc_bytes < state.min_bytes)
{
match state.input.next().await {
Some(Ok(batch)) => {
state.acc_bytes += batch.get_array_memory_size();
state.accumulated.push(batch);
}
Some(Err(e)) => return Err(e),
None => {
state.done = true;
}
}
}
if state.accumulated.is_empty() {
return Ok(None);
}
// Fast path: if the first accumulated batch already meets the
// byte threshold, deliver it directly instead of concatenating
// everything together (which would just get sliced back apart).
if state.accumulated.len() > 1
&& state.accumulated[0].get_array_memory_size() >= state.min_bytes
{
let b = state.accumulated.remove(0);
state.acc_bytes -= b.get_array_memory_size();
return Ok(Some((b, state)));
}
let batch = if state.accumulated.len() == 1 {
state.accumulated.pop().unwrap()
} else {
let b =
arrow_select::concat::concat_batches(&state.input_schema, &state.accumulated)
.map_err(E::from)?;
state.accumulated.clear();
b
};
state.acc_bytes = 0;
// Slice the batch into ~max_bytes pieces assuming uniform row sizes.
let mut slices =
slice_batch(batch, state.max_bytes, state.deep_copy).map_err(E::from)?;
if slices.len() == 1 {
Ok(Some((slices.pop().unwrap(), state)))
} else {
let first = slices.remove(0);
// Stash leftover slices for subsequent iterations.
for a in &slices {
state.acc_bytes += a.get_array_memory_size();
}
state.accumulated = slices;
Ok(Some((first, state)))
}
},
)
}
/// Slice a batch into pieces of at most `max_bytes`.
///
/// When `deep_copy` is false, slices share buffers with the original batch
/// and `get_array_memory_size` will still report the parent buffer size.
/// This is fine when the caller only needs approximate sizing.
///
/// When `deep_copy` is true, each slice is deep-copied so that
/// `get_array_memory_size` reflects the true size. If a deep-copied slice
/// still exceeds `max_bytes` (due to non-uniform row sizes), it is
/// recursively split until every piece is within budget or contains only a
/// single row.
fn slice_batch(
batch: RecordBatch,
max_bytes: usize,
deep_copy: bool,
) -> Result<Vec<RecordBatch>, ArrowError> {
let batch_bytes = batch.get_array_memory_size();
let num_rows = batch.num_rows();
if batch_bytes <= max_bytes || num_rows <= 1 {
return Ok(vec![batch]);
}
let rows_per_chunk = (max_bytes as u64 * num_rows as u64 / batch_bytes as u64).max(1) as usize;
let mut result = Vec::new();
let mut offset = 0;
while offset < num_rows {
let len = rows_per_chunk.min(num_rows - offset);
let slice = batch.slice(offset, len);
if deep_copy {
let copied = deep_copy_batch_sliced(&slice)?;
// Recurse: the deep-copied slice has accurate sizes, so if it
// still exceeds max_bytes we can split further.
result.extend(slice_batch(copied, max_bytes, true)?);
} else {
result.push(slice);
}
offset += len;
}
Ok(result)
}
/// Internal state for [`rechunk_stream`].
///
/// Kept as a named struct so the `try_unfold` closure stays readable.
struct RechunkState<S> {
input: Pin<Box<S>>,
accumulated: Vec<RecordBatch>,
acc_bytes: usize,
done: bool,
input_schema: SchemaRef,
min_bytes: usize,
max_bytes: usize,
deep_copy: bool,
}
#[cfg(test)]
mod tests {
use super::*;
use std::sync::Arc;
use arrow_array::Int32Array;
use arrow_schema::{DataType, Field, Schema};
use futures::executor::block_on;
fn make_batch(num_rows: usize) -> RecordBatch {
let schema = test_schema();
let values: Vec<i32> = (0..num_rows as i32).collect();
RecordBatch::try_new(schema, vec![Arc::new(Int32Array::from(values))]).unwrap()
}
fn test_schema() -> SchemaRef {
Arc::new(Schema::new(vec![Field::new("a", DataType::Int32, false)]))
}
fn collect_rechunked(
batches: Vec<RecordBatch>,
min_bytes: usize,
max_bytes: usize,
) -> Vec<RecordBatch> {
let input = stream::iter(batches.into_iter().map(Ok::<_, ArrowError>));
let rechunked = rechunk_stream_by_size(input, test_schema(), min_bytes, max_bytes);
block_on(rechunked.collect::<Vec<_>>())
.into_iter()
.map(|r| r.unwrap())
.collect()
}
fn total_rows(batches: &[RecordBatch]) -> usize {
batches.iter().map(|b| b.num_rows()).sum()
}
#[test]
fn test_empty_stream() {
let result = collect_rechunked(vec![], 100, 200);
assert!(result.is_empty());
}
#[test]
fn test_single_batch_passthrough() {
let batch = make_batch(100);
let bytes = batch.get_array_memory_size();
// Batch is between min and max — should pass through as-is.
let result = collect_rechunked(vec![batch], bytes / 2, bytes * 2);
assert_eq!(result.len(), 1);
assert_eq!(result[0].num_rows(), 100);
}
#[test]
fn test_small_batches_concatenated() {
let one_batch_bytes = make_batch(10).get_array_memory_size();
let batches: Vec<_> = (0..8).map(|_| make_batch(10)).collect();
// min = 5 batches worth, max = 10 batches worth.
let result = collect_rechunked(batches, one_batch_bytes * 5, one_batch_bytes * 10);
assert_eq!(total_rows(&result), 80);
// Should have been concatenated into fewer batches than the 8 inputs.
assert!(
result.len() < 8,
"expected fewer output batches, got {}",
result.len()
);
}
#[test]
fn test_large_batch_sliced() {
let batch = make_batch(1000);
let bytes = batch.get_array_memory_size();
let result = collect_rechunked(vec![batch], bytes / 8, bytes / 4);
assert_eq!(total_rows(&result), 1000);
assert!(
result.len() >= 4,
"expected at least 4 slices, got {}",
result.len()
);
}
#[test]
fn test_sliced_leftovers_are_not_recombined() {
// Key test for the fast-path optimisation. When a large batch is
// sliced, leftover slices should be delivered one-at-a-time without
// being concatenated back together. We verify this by checking that
// every output buffer pointer falls inside the original batch's
// allocation (i.e. they are all zero-copy slices, not fresh copies).
let batch = make_batch(1000);
let bytes = batch.get_array_memory_size();
let orig_data = batch.column(0).to_data();
let orig_buf = &orig_data.buffers()[0];
let orig_start = orig_buf.as_ptr() as usize;
let orig_end = orig_start + orig_buf.len();
let result = collect_rechunked(vec![batch], bytes / 8, bytes / 4);
assert_eq!(total_rows(&result), 1000);
assert!(result.len() >= 4);
for (i, b) in result.iter().enumerate() {
let ptr = b.column(0).to_data().buffers()[0].as_ptr() as usize;
assert!(
ptr >= orig_start && ptr < orig_end,
"slice {i} buffer at {ptr:#x} is outside the original allocation \
[{orig_start:#x}, {orig_end:#x}) — it was re-concatenated"
);
}
}
#[test]
fn test_flush_remainder_on_stream_end() {
// Data below min_bytes should still be flushed when the stream ends.
let batch = make_batch(10);
let bytes = batch.get_array_memory_size();
let result = collect_rechunked(vec![batch], bytes * 100, bytes * 200);
assert_eq!(result.len(), 1);
assert_eq!(result[0].num_rows(), 10);
}
#[test]
fn test_large_then_small_batches() {
// After a large batch is fully drained, subsequent small batches
// should be accumulated normally.
let large = make_batch(1000);
let small_bytes = make_batch(10).get_array_memory_size();
let batches = vec![
large,
make_batch(10),
make_batch(10),
make_batch(10),
make_batch(10),
make_batch(10),
];
let result = collect_rechunked(batches, small_bytes * 3, small_bytes * 100);
assert_eq!(total_rows(&result), 1050);
// The large batch should appear (possibly sliced) followed by
// concatenated small batches, so we should have fewer output batches
// than the 6 inputs.
assert!(result.len() < 6);
}
#[test]
fn test_row_preservation_across_slicing() {
// Verify that every input row appears exactly once in the output
// and in the correct order after slicing.
let batch = make_batch(237); // odd count to exercise remainder slice
let bytes = batch.get_array_memory_size();
let result = collect_rechunked(vec![batch], bytes / 8, bytes / 5);
assert_eq!(total_rows(&result), 237);
let values: Vec<i32> = result
.iter()
.flat_map(|b| {
b.column(0)
.as_any()
.downcast_ref::<Int32Array>()
.unwrap()
.values()
.iter()
.copied()
})
.collect();
let expected: Vec<i32> = (0..237).collect();
assert_eq!(values, expected);
}
#[test]
fn test_min_bytes_zero_still_yields_all_rows() {
// When min_bytes=0, the stream should still yield every batch.
// This is the "chop only, don't coalesce" use case.
let batches: Vec<_> = (0..5).map(|_| make_batch(100)).collect();
let batch_bytes = batches[0].get_array_memory_size();
let result = collect_rechunked(batches, 0, batch_bytes * 2);
assert_eq!(total_rows(&result), 500);
}
#[test]
fn test_min_bytes_zero_slices_oversized() {
// min_bytes=0 with a small max_bytes should still slice large batches.
let batch = make_batch(1000);
let bytes = batch.get_array_memory_size();
let result = collect_rechunked(vec![batch], 0, bytes / 4);
assert_eq!(total_rows(&result), 1000);
assert!(
result.len() >= 4,
"expected at least 4 slices, got {}",
result.len()
);
}
/// Build a batch with one variable-length string column.
/// Every row is `small_size` bytes except the row at index `big_row_idx`
/// which is `big_size` bytes.
fn make_variable_batch(
num_rows: usize,
small_size: usize,
big_row_idx: usize,
big_size: usize,
) -> RecordBatch {
let schema = Arc::new(Schema::new(vec![Field::new("s", DataType::Utf8, false)]));
let values: Vec<String> = (0..num_rows)
.map(|i| {
if i == big_row_idx {
"X".repeat(big_size)
} else {
"x".repeat(small_size)
}
})
.collect();
let array = arrow_array::StringArray::from(values);
RecordBatch::try_new(schema, vec![Arc::new(array)]).unwrap()
}
fn variable_schema() -> SchemaRef {
Arc::new(Schema::new(vec![Field::new("s", DataType::Utf8, false)]))
}
fn collect_rechunked_variable(
batches: Vec<RecordBatch>,
min_bytes: usize,
max_bytes: usize,
) -> Vec<RecordBatch> {
let input = stream::iter(batches.into_iter().map(Ok::<_, ArrowError>));
let rechunked =
rechunk_stream_by_size_deep_copy(input, variable_schema(), min_bytes, max_bytes);
block_on(rechunked.collect::<Vec<_>>())
.into_iter()
.map(|r| r.unwrap())
.collect()
}
#[test]
fn test_oversized_row_at_end() {
// 100 rows: 99 small (64 bytes each) + 1 large (100KiB) at the end.
let batch = make_variable_batch(100, 64, 99, 100 * 1024);
let max_bytes = 64 * 1024;
let result = collect_rechunked_variable(vec![batch], 0, max_bytes);
assert_eq!(total_rows(&result), 100);
for (i, b) in result.iter().enumerate() {
let size = b.get_array_memory_size();
assert!(
size <= max_bytes || b.num_rows() == 1,
"batch {i} has {size} bytes (max {max_bytes}) and {} rows",
b.num_rows()
);
}
}
#[test]
fn test_oversized_row_at_start() {
// 100 rows: 1 large (100KiB) at the start + 99 small (64 bytes each).
let batch = make_variable_batch(100, 64, 0, 100 * 1024);
let max_bytes = 64 * 1024;
let result = collect_rechunked_variable(vec![batch], 0, max_bytes);
assert_eq!(total_rows(&result), 100);
for (i, b) in result.iter().enumerate() {
let size = b.get_array_memory_size();
assert!(
size <= max_bytes || b.num_rows() == 1,
"batch {i} has {size} bytes (max {max_bytes}) and {} rows",
b.num_rows()
);
}
}
#[test]
fn test_oversized_row_in_middle() {
// 100 rows: 1 large (100KiB) in the middle + 99 small (64 bytes each).
let batch = make_variable_batch(100, 64, 50, 100 * 1024);
let max_bytes = 64 * 1024;
let result = collect_rechunked_variable(vec![batch], 0, max_bytes);
assert_eq!(total_rows(&result), 100);
for (i, b) in result.iter().enumerate() {
let size = b.get_array_memory_size();
assert!(
size <= max_bytes || b.num_rows() == 1,
"batch {i} has {size} bytes (max {max_bytes}) and {} rows",
b.num_rows()
);
}
}
#[test]
fn test_error_propagation() {
let input = stream::iter(vec![
Ok(make_batch(10)),
Err(ArrowError::ComputeError("boom".into())),
Ok(make_batch(10)),
]);
let rechunked = rechunk_stream_by_size(input, test_schema(), 1, usize::MAX);
let results: Vec<Result<RecordBatch, ArrowError>> = block_on(rechunked.collect());
assert!(results.iter().any(|r| r.is_err()));
}
}
lance-artifact/rust/lance-arrow/src/struct.rs
+191
View File
@@ -0,0 +1,191 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright The Lance Authors
//! Extension to arrow struct arrays
use arrow_array::{Array, StructArray, cast::AsArray, make_array};
use arrow_buffer::NullBuffer;
use arrow_data::{ArrayData, ArrayDataBuilder};
use arrow_schema::ArrowError;
pub trait StructArrayExt {
/// Removes the offset / length of the struct array by pushing it into the children
///
/// In arrow-rs when slice is called it recursively slices the children.
/// In arrow-cpp when slice is called it just sets the offset/length of
/// the struct array and leaves the children as-is
///
/// Both are legal approaches (╥﹏╥)
///
/// This method helps reduce complexity by folding into the arrow-rs approach
fn normalize_slicing(&self) -> Result<Self, ArrowError>
where
Self: Sized;
/// Structs are allowed to mask valid items. For example, a struct array might be:
///
/// [ {"items": [1, 2, 3]}, NULL, {"items": NULL}]
///
/// However, the underlying items array might be: [[1, 2, 3], [4, 5], NULL]
///
/// The [4, 5] list is masked out because the struct array is null.
///
/// The struct validity would be [true, false, true] and the list validity would be [true, true, false]
///
/// This method pushes nulls down into all children. In the above example the list validity would become
/// [true, false, false].
///
/// This method is not recursive. If a child is a struct array it will not push that child's nulls down.
///
/// This method does not remove garbage lists. It only updates the validity so a future call to
/// [crate::list::ListArrayExt::filter_garbage_nulls] will remove the garbage lists (without
/// this pushdown it would not)
fn pushdown_nulls(&self) -> Result<Self, ArrowError>
where
Self: Sized;
}
fn normalized_struct_array_data(data: ArrayData) -> Result<ArrayData, ArrowError> {
let parent_offset = data.offset();
let parent_len = data.len();
let modified_children = data
.child_data()
.iter()
.map(|d| {
let d = normalized_struct_array_data(d.clone())?;
let offset = d.offset();
let len = d.len();
if len < parent_len + parent_offset {
return Err(ArrowError::InvalidArgumentError(format!(
"Child array {} has length {} which is less than the parent length {} plus the parent offset {}",
d.data_type(),
len,
parent_len,
parent_offset
)));
}
let new_offset = offset + parent_offset;
d.into_builder().offset(new_offset)
.len(parent_len)
.build()
})
.collect::<Result<Vec<_>, _>>()?;
ArrayDataBuilder::new(data.data_type().clone())
.len(parent_len)
.offset(0)
.buffers(data.buffers().to_vec())
.child_data(modified_children)
.build()
}
impl StructArrayExt for StructArray {
fn normalize_slicing(&self) -> Result<Self, ArrowError>
where
Self: Sized,
{
if self.offset() == 0 && self.columns().iter().all(|c| c.len() == self.len()) {
return Ok(self.clone());
}
let data = normalized_struct_array_data(self.to_data())?;
Ok(Self::from(data))
}
fn pushdown_nulls(&self) -> Result<Self, ArrowError>
where
Self: Sized,
{
let Some(validity) = self.nulls() else {
return Ok(self.clone());
};
let data = self.to_data();
let children = data
.child_data()
.iter()
.map(|c| {
if let Some(child_validity) = c.nulls() {
let new_validity = child_validity.inner() & validity.inner();
c.clone()
.into_builder()
.nulls(Some(NullBuffer::from(new_validity)))
.build()
} else {
Ok(c.clone()
.into_builder()
.nulls(Some(validity.clone()))
.build()?)
}
})
.collect::<Result<Vec<_>, _>>()?;
let arr = make_array(data.into_builder().child_data(children).build()?);
Ok(arr.as_struct().clone())
}
}
#[cfg(test)]
mod tests {
use arrow_array::{Array, Int32Array, StructArray, cast::AsArray, make_array};
use arrow_schema::{DataType, Field, Fields};
use std::sync::Arc;
use crate::r#struct::StructArrayExt;
#[test]
fn test_normalize_slicing_no_offset() {
let x = Int32Array::from(vec![1, 2, 3]);
let y = Int32Array::from(vec![4, 5, 6]);
let struct_array = StructArray::new(
Fields::from(vec![
Field::new("x", DataType::Int32, true),
Field::new("y", DataType::Int32, true),
]),
vec![Arc::new(x), Arc::new(y)],
None,
);
let normalized = struct_array.normalize_slicing().unwrap();
assert_eq!(normalized, struct_array);
}
#[test]
fn test_arrow_rs_slicing() {
let x = Int32Array::from(vec![1, 2, 3, 4]);
let y = Int32Array::from(vec![5, 6, 7, 8]);
let struct_array = StructArray::new(
Fields::from(vec![
Field::new("x", DataType::Int32, true),
Field::new("y", DataType::Int32, true),
]),
vec![Arc::new(x), Arc::new(y)],
None,
);
// Slicing with arrow-rs propagates the slicing to the children so there should
// be no change needed to the struct array
let sliced = struct_array.slice(1, 2);
let normalized = sliced.normalize_slicing().unwrap();
assert_eq!(normalized, sliced);
}
#[test]
fn test_arrow_cpp_slicing() {
let x = Int32Array::from(vec![1, 2, 3, 4]);
let y = Int32Array::from(vec![5, 6, 7, 8]);
let struct_array = StructArray::new(
Fields::from(vec![
Field::new("x", DataType::Int32, true),
Field::new("y", DataType::Int32, true),
]),
vec![Arc::new(x), Arc::new(y)],
None,
);
let data = struct_array.to_data();
let sliced = data.into_builder().offset(1).len(2).build().unwrap();
let sliced = make_array(sliced);
let normalized = sliced.as_struct().clone().normalize_slicing().unwrap();
assert_eq!(normalized, struct_array.slice(1, 2));
}
}
lance-artifact/rust/lance-core/Cargo.toml
+72
View File
@@ -0,0 +1,72 @@
[package]
name = "lance-core"
version.workspace = true
edition.workspace = true
authors.workspace = true
license.workspace = true
repository.workspace = true
readme.workspace = true
description = "Lance Columnar Format -- Core Library"
keywords.workspace = true
categories.workspace = true
rust-version.workspace = true
[dependencies]
arrow-array.workspace = true
arrow-buffer.workspace = true
arrow-data.workspace = true
arrow-schema.workspace = true
async-trait.workspace = true
lance-arrow.workspace = true
blake3.workspace = true
byteorder.workspace = true
bytes.workspace = true
datafusion-common = { workspace = true, optional = true }
datafusion-sql = { workspace = true, optional = true }
lance-derive.workspace = true
futures.workspace = true
itertools.workspace = true
libc.workspace = true
libm.workspace = true
moka.workspace = true
quick_cache = "0.6"
num_cpus = "1.0"
object_store = { workspace = true }
pin-project.workspace = true
prost.workspace = true
rand.workspace = true
roaring.workspace = true
serde_json.workspace = true
snafu.workspace = true
tempfile.workspace = true
tokio.workspace = true
tokio-stream.workspace = true
tokio-util.workspace = true
tracing.workspace = true
twox-hash.workspace = true
url.workspace = true
log.workspace = true
# This is used to detect CPU features at runtime.
# See src/utils/cpu.rs
[target.'cfg(all(any(target_arch = "aarch64", target_arch = "loongarch64"), target_os = "linux"))'.dependencies]
libc = { version = "0.2" }
[dev-dependencies]
criterion.workspace = true
proptest.workspace = true
rstest.workspace = true
[features]
# Capture Rust backtraces in error types. When disabled (the default),
# the backtrace field is zero-sized with no overhead. At runtime, capture
# is still gated by RUST_BACKTRACE=1.
backtrace = []
datafusion = ["dep:datafusion-common", "dep:datafusion-sql"]
[[bench]]
name = "cache_keys"
harness = false
[lints]
workspace = true
lance-artifact/rust/lance-core/benches/cache_keys.rs
+365
View File
@@ -0,0 +1,365 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright The Lance Authors
use std::any::Any;
use std::borrow::Cow;
use std::hash::{BuildHasher, RandomState};
use std::hint::black_box;
use std::sync::atomic::{AtomicU64, Ordering};
use std::sync::{Arc, Weak};
use async_trait::async_trait;
use criterion::{BenchmarkId, Criterion, criterion_group, criterion_main};
use futures::FutureExt;
use lance_core::cache::{
CacheKey, CacheKeySchema, CacheNamespace, KeyBuilder, LanceCache, WeakLanceCache,
};
struct PageKey {
column_index: u32,
page_index: u64,
}
impl CacheKey for PageKey {
type ValueType = Vec<u8>;
fn key(&self) -> Cow<'_, str> {
format!("{}-{}", self.column_index, self.page_index).into()
}
fn type_name() -> &'static str {
"bench.Page"
}
fn schema() -> CacheKeySchema {
CacheKeySchema::new("bench.page-key", 1)
}
fn write_key(&self, builder: &mut KeyBuilder) {
builder.write_u32(self.column_index);
builder.write_u64(self.page_index);
}
}
#[derive(Clone, Eq, Hash, PartialEq)]
struct LegacyPhysicalKey {
namespace: Arc<str>,
logical_key: Arc<str>,
type_name: &'static str,
}
type LegacyEntryValue = Arc<dyn Any + Send + Sync>;
#[derive(Clone)]
struct LegacyEntry {
value: LegacyEntryValue,
size_bytes: usize,
}
#[async_trait]
trait LegacyBackend: Send + Sync {
async fn get(&self, key: &LegacyPhysicalKey) -> Option<LegacyEntryValue>;
async fn insert(&self, key: &LegacyPhysicalKey, value: LegacyEntryValue, size_bytes: usize);
}
struct LegacyMokaBackend {
cache: moka::future::Cache<LegacyPhysicalKey, LegacyEntry>,
}
impl LegacyMokaBackend {
fn with_capacity(capacity: usize) -> Self {
let cache = moka::future::Cache::builder()
.max_capacity(capacity as u64)
.weigher(|key: &LegacyPhysicalKey, entry: &LegacyEntry| {
std::mem::size_of::<LegacyPhysicalKey>()
.saturating_add(key.logical_key.len())
.saturating_add(entry.size_bytes)
.try_into()
.unwrap_or(u32::MAX)
})
.support_invalidation_closures()
.build();
Self { cache }
}
}
#[async_trait]
impl LegacyBackend for LegacyMokaBackend {
async fn get(&self, key: &LegacyPhysicalKey) -> Option<LegacyEntryValue> {
self.cache.get(key).await.map(|entry| entry.value)
}
async fn insert(&self, key: &LegacyPhysicalKey, value: LegacyEntryValue, size_bytes: usize) {
self.cache
.insert(key.clone(), LegacyEntry { value, size_bytes })
.await;
}
}
#[derive(Clone)]
struct LegacyCache {
backend: Arc<dyn LegacyBackend>,
namespace: Arc<str>,
hits: Arc<AtomicU64>,
misses: Arc<AtomicU64>,
}
impl LegacyCache {
fn with_capacity(capacity: usize) -> Self {
Self {
backend: Arc::new(LegacyMokaBackend::with_capacity(capacity)),
namespace: Arc::from(""),
hits: Arc::new(AtomicU64::new(0)),
misses: Arc::new(AtomicU64::new(0)),
}
}
fn with_key_prefix(&self, segment: &str) -> Self {
Self {
backend: self.backend.clone(),
namespace: Arc::from(format!("{}{segment}/", self.namespace)),
hits: self.hits.clone(),
misses: self.misses.clone(),
}
}
fn physical_key(&self, key: &PageKey) -> LegacyPhysicalKey {
let logical_key = key.key();
LegacyPhysicalKey {
namespace: self.namespace.clone(),
logical_key: Arc::from(logical_key.as_ref()),
type_name: PageKey::type_name(),
}
}
async fn insert(&self, key: &PageKey, value: Arc<Vec<u8>>) {
let size_bytes = std::mem::size_of::<Vec<u8>>()
+ value.capacity()
+ std::mem::size_of::<AtomicU64>() * 2;
self.backend
.insert(&self.physical_key(key), value, size_bytes)
.boxed()
.await;
}
async fn get(&self, key: &PageKey) -> Option<Arc<Vec<u8>>> {
async {
let Some(value) = self.backend.get(&self.physical_key(key)).await else {
self.misses.fetch_add(1, Ordering::Relaxed);
return None;
};
match value.downcast::<Vec<u8>>() {
Ok(value) => {
self.hits.fetch_add(1, Ordering::Relaxed);
Some(value)
}
Err(_) => {
self.misses.fetch_add(1, Ordering::Relaxed);
None
}
}
}
.boxed()
.await
}
}
struct LegacyWeakCache {
backend: Weak<dyn LegacyBackend>,
namespace: Arc<str>,
hits: Arc<AtomicU64>,
misses: Arc<AtomicU64>,
}
impl LegacyWeakCache {
fn from(cache: &LegacyCache) -> Self {
Self {
backend: Arc::downgrade(&cache.backend),
namespace: cache.namespace.clone(),
hits: cache.hits.clone(),
misses: cache.misses.clone(),
}
}
async fn get(&self, key: &PageKey) -> Option<Arc<Vec<u8>>> {
let backend = self.backend.upgrade()?;
let logical_key = key.key();
let physical_key = LegacyPhysicalKey {
namespace: self.namespace.clone(),
logical_key: Arc::from(logical_key.as_ref()),
type_name: PageKey::type_name(),
};
let Some(value) = backend.get(&physical_key).await else {
self.misses.fetch_add(1, Ordering::Relaxed);
return None;
};
match value.downcast::<Vec<u8>>() {
Ok(value) => {
self.hits.fetch_add(1, Ordering::Relaxed);
Some(value)
}
Err(_) => {
self.misses.fetch_add(1, Ordering::Relaxed);
None
}
}
}
}
fn benchmark_key_preparation(c: &mut Criterion) {
let key = PageKey {
column_index: 17,
page_index: 42,
};
let outer_hashes = RandomState::new();
let prefixes: [(&str, Arc<str>); 2] = [
("short", Arc::from("dataset")),
("long", Arc::from("p".repeat(1024))),
];
let mut group = c.benchmark_group("cache_key_preparation");
for (case, prefix) in prefixes {
let namespace = CacheNamespace::root().child(&prefix);
group.bench_with_input(BenchmarkId::new("legacy", case), &prefix, |b, prefix| {
b.iter(|| {
let logical_key = key.key();
let physical_key = LegacyPhysicalKey {
namespace: Arc::clone(prefix),
logical_key: Arc::from(logical_key.as_ref()),
type_name: PageKey::type_name(),
};
black_box(outer_hashes.hash_one(physical_key))
})
});
group.bench_function(BenchmarkId::new("blake3_typed", case), |b| {
b.iter(|| {
let mut builder =
KeyBuilder::new(namespace, PageKey::stable_type_id(), PageKey::schema());
key.write_key(&mut builder);
black_box(outer_hashes.hash_one(builder.finish()))
})
});
}
group.finish();
}
fn benchmark_namespace_derivation(c: &mut Criterion) {
let root = CacheNamespace::root();
let long_segment = "p".repeat(160);
let mut group = c.benchmark_group("cache_namespace_derivation");
group.bench_function("root", |b| {
b.iter(|| black_box(CacheNamespace::root()));
});
group.bench_with_input(
BenchmarkId::new("child", "short"),
&"dataset",
|b, segment| {
b.iter(|| black_box(root.child(black_box(segment))));
},
);
group.bench_with_input(
BenchmarkId::new("child", "long"),
&long_segment,
|b, segment| {
b.iter(|| black_box(root.child(black_box(segment))));
},
);
group.finish();
}
fn benchmark_cache_operations(c: &mut Criterion) {
const CAPACITY: usize = 64 * 1024;
const ROTATING_KEYS: u64 = 512;
let runtime = tokio::runtime::Runtime::new().unwrap();
let prefix = "p".repeat(1024);
let legacy = LegacyCache::with_capacity(CAPACITY).with_key_prefix(&prefix);
let legacy_weak = LegacyWeakCache::from(&legacy);
let fixed = LanceCache::with_capacity(CAPACITY).with_key_prefix(&prefix);
let fixed_weak = WeakLanceCache::from(&fixed);
let hit_key = PageKey {
column_index: 17,
page_index: 42,
};
runtime.block_on(async {
legacy.insert(&hit_key, Arc::new(vec![1_u8; 32])).await;
fixed
.insert_with_key(&hit_key, Arc::new(vec![1_u8; 32]))
.await;
});
let mut group = c.benchmark_group("cache_operations");
group.bench_function(BenchmarkId::new("strong_warmed_hit", "legacy"), |b| {
b.to_async(&runtime)
.iter(|| legacy.get(black_box(&hit_key)));
});
group.bench_function(BenchmarkId::new("strong_warmed_hit", "fixed"), |b| {
b.to_async(&runtime)
.iter(|| fixed.get_with_key(black_box(&hit_key)));
});
group.bench_function(BenchmarkId::new("weak_warmed_hit", "legacy"), |b| {
b.to_async(&runtime)
.iter(|| legacy_weak.get(black_box(&hit_key)));
});
group.bench_function(BenchmarkId::new("weak_warmed_hit", "fixed"), |b| {
b.to_async(&runtime)
.iter(|| fixed_weak.get_with_key(black_box(&hit_key)));
});
let values: Vec<_> = (0..16).map(|value| Arc::new(vec![value; 32])).collect();
let next_legacy_insert = AtomicU64::new(0);
group.bench_function(BenchmarkId::new("bounded_rotating_insert", "legacy"), |b| {
b.to_async(&runtime).iter(|| {
let sequence = next_legacy_insert.fetch_add(1, Ordering::Relaxed);
let page_index = sequence % ROTATING_KEYS;
let value = Arc::clone(&values[sequence as usize % values.len()]);
let legacy = &legacy;
async move {
legacy
.insert(
&PageKey {
column_index: 17,
page_index,
},
value,
)
.await;
}
});
});
let next_fixed_insert = AtomicU64::new(0);
group.bench_function(BenchmarkId::new("bounded_rotating_insert", "fixed"), |b| {
b.to_async(&runtime).iter(|| {
let sequence = next_fixed_insert.fetch_add(1, Ordering::Relaxed);
let page_index = sequence % ROTATING_KEYS;
let value = Arc::clone(&values[sequence as usize % values.len()]);
let fixed = &fixed;
async move {
fixed
.insert_with_key(
&PageKey {
column_index: 17,
page_index,
},
value,
)
.await;
}
});
});
group.finish();
}
criterion_group!(
benches,
benchmark_key_preparation,
benchmark_namespace_derivation,
benchmark_cache_operations
);
criterion_main!(benches);
lance-artifact/rust/lance-core/proptest-regressions/io/writer/statistics.txt
+12
View File
@@ -0,0 +1,12 @@
# Seeds for failure cases proptest has generated in the past. It is
# automatically read and these particular cases re-run before any
# novel cases are generated.
#
# It is recommended to check this file in to source control so that
# everyone who runs the test benefits from these saved cases.
cc d036403fe9f78dbff2c0719e2319e043d9fa1e95aeecd63f8e69593a22c10ea4 # shrinks to values = [""]
cc e7d31563fa5d35fe809e639d776be444b6042700b05fe695a0f6adc14fb171f7 # shrinks to values = []
cc 6c525cb87c8a699c192a10bb4064837f4e91ca609cac82e3615da4776227b613 # shrinks to values = [[0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]]
cc 6a1991927899b890de6623bf046ebd7e6fd512c73c854a21be5a947bf15f98dd # shrinks to values = [[0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]]
cc 1436aa3ba65a78849c52480e744e8ed37a6eb64e793319f36f28e0ffd30c0f34 # shrinks to values = ["𐀀 𐀀aA \u{80}aA\u{b}A \u{b}\00 0𐀀0 A𐀀\0ࠀaࠀAA0¡ 𐀀𐀀¡ 𐀀"]
cc f1974dc3e72ef3d23ce7fd5a983f188a3f26bf9247f43dc25e7e71f46e0bedd9 # shrinks to values = ["\u{7f}", " \u{80}𐀀𐀀\0\0 \u{b}¡𐀀𐀀ࠀ\0 a\u{b} ¡𐀀𐀀0Aa𐀀a00 𐀀a𐀀A"]
lance-artifact/rust/lance-core/proptest-regressions/utils/mask.txt
+9
View File
File diff suppressed because one or more lines are too long
lance-artifact/rust/lance-core/src/cache/backend.rs
Vendored
+137
View File
@@ -0,0 +1,137 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright The Lance Authors
//! Backend interface for cache implementors.
//!
//! This module defines the trait that custom cache backends must implement,
//! along with the entry type they operate on. Most callers should
//! use [`LanceCache`](super::LanceCache) instead of interacting with
//! backends directly.
//!
//! # Migrating custom backends
//!
//! Cache keys are opaque 16-byte values. Store
//! [`InternalCacheKey::as_bytes`] directly instead of decomposing a logical
//! prefix, key string, and Rust type name. The physical namespace must also
//! include [`CACHE_KEY_FORMAT`](super::CACHE_KEY_FORMAT), so a future key
//! protocol produces cold misses instead of aliases. Persistent or tiered
//! backends can route serializable values with [`CacheCodec::type_id`].
//!
//! Prefix invalidation and key inventory are intentionally not part of this
//! interface: one-way digests cannot support either operation without
//! retaining the logical strings that fixed-size keys are designed to remove.
//! Existing callers should migrate removed symbols as follows:
//! - replace `with_backend_and_prefix(backend, prefix)` with
//! [`LanceCache::with_backend`](super::LanceCache::with_backend) followed by
//! [`LanceCache::with_key_prefix`](super::LanceCache::with_key_prefix);
//! - replace `invalidate_prefix` with [`LanceCache::clear`](super::LanceCache::clear)
//! when clearing the shared backend is acceptable, or rotate a versioned
//! namespace to leave older entries to age out;
//! - remove uses of `prefix`, `keys`, and session key-inventory methods; opaque
//! keys have no readable or enumerable equivalent.
use std::any::Any;
use std::pin::Pin;
use std::sync::Arc;
use async_trait::async_trait;
use futures::Future;
use crate::Result;
use crate::deepsize::Context;
use super::{CacheCodec, InternalCacheKey};
/// A type-erased cache entry.
pub type CacheEntry = Arc<dyn Any + Send + Sync>;
/// Low-level pluggable cache backend.
///
/// Implementations store entries keyed by [`InternalCacheKey`] and return
/// type-erased [`CacheEntry`] values.
/// [`LanceCache`](super::LanceCache) handles key construction and type safety;
/// backend authors only need to implement storage and eviction.
#[async_trait]
pub trait CacheBackend: Send + Sync + std::fmt::Debug {
/// Look up an entry by its key.
///
/// `codec` is provided so that persistent backends can deserialize the
/// entry from storage. In-memory backends can ignore it. When `codec`
/// is `None`, the entry type does not support serialization yet and
/// must be stored in-memory.
///
/// The goal is for all cache entry types to eventually have codecs,
/// at which point the `Option` will be removed.
async fn get(&self, key: &InternalCacheKey, codec: Option<CacheCodec>) -> Option<CacheEntry>;
/// Store an entry. `size_bytes` is used for eviction accounting.
///
/// See [`get`](Self::get) for codec semantics.
async fn insert(
&self,
key: &InternalCacheKey,
entry: CacheEntry,
size_bytes: usize,
codec: Option<CacheCodec>,
);
/// Get an existing entry or compute it from `loader`.
///
/// Implementations should deduplicate concurrent loads for the same key
/// so the loader runs at most once.
///
/// Returns `(entry, was_cached)` where `was_cached` is `true` if the entry
/// was already present in the cache (the loader was not invoked).
///
/// See [`get`](Self::get) for codec semantics.
async fn get_or_insert<'a>(
&self,
key: &InternalCacheKey,
loader: Pin<Box<dyn Future<Output = Result<(CacheEntry, usize)>> + Send + 'a>>,
codec: Option<CacheCodec>,
) -> Result<(CacheEntry, bool)>;
/// Remove all entries.
async fn clear(&self);
/// Number of entries currently stored (may flush pending operations).
async fn num_entries(&self) -> usize;
/// Total weighted size in bytes of all stored entries (may flush pending operations).
async fn size_bytes(&self) -> usize;
/// Approximate number of entries, callable from synchronous contexts.
/// Backends that cannot provide this cheaply should return 0.
fn approx_num_entries(&self) -> usize {
0
}
/// Approximate weighted size in bytes, callable from synchronous contexts.
/// Used as a `DeepSizeOf` fallback when exact entry traversal is unavailable.
/// Backends that cannot provide this cheaply should return 0.
///
/// Assumes entries do not share underlying buffers; if they do, the
/// returned total may overcount.
fn approx_size_bytes(&self) -> usize {
0
}
/// Computes the size of the entries currently held in memory.
///
/// `size_of_entry` threads a shared [`Context`] through each value so
/// allocations shared by multiple entries are counted once. It returns
/// `None` when the value's concrete type was not registered by
/// [`LanceCache`](super::LanceCache); implementations should use the
/// entry's declared eviction size as a fallback in that case.
///
/// Backends that can enumerate their in-memory entries should include the
/// physical key footprint in the returned total. The default returns
/// `None`, causing `LanceCache` to use [`approx_size_bytes`](Self::approx_size_bytes).
fn deep_size_of_entries(
&self,
_context: &mut Context,
_size_of_entry: &dyn Fn(&CacheEntry, &mut Context) -> Option<usize>,
) -> Option<usize> {
None
}
}
lance-artifact/rust/lance-core/src/cache/backend_uri.rs
Vendored
+265
View File
@@ -0,0 +1,265 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright The Lance Authors
//! URI-based configuration for cache backends.
//!
//! [`build_from_uri`] parses a compact string form such as
//! `moka://?capacity=1073741824` into a [`BackendConfig`] and hands it to
//! the registry. This gives Python/Java bindings and configuration files a
//! single-string representation of a backend without having to expose a
//! typed builder for every backend.
//!
//! Grammar (intentionally a subset of RFC 3986 — Lance only needs a
//! predictable, unambiguous form):
//!
//! ```text
//! uri ::= scheme ":" hier ( "?" query )?
//! scheme ::= ALPHA ( ALPHA | DIGIT | "+" | "-" | "." )*
//! hier ::= "//" authority path? -- e.g. moka://?..., other:///path?...
//! | path -- e.g. moka:capacity=... (rare)
//! authority ::= *( any char except "/" | "?" )
//! path ::= *( any char except "?" )
//! query ::= pair ( "&" pair )*
//! pair ::= key "=" value -- both percent-decoded
//! ```
//!
//! Mapping to [`BackendConfig`]:
//!
//! * `scheme` becomes `kind`.
//! * The joined `authority + path` (with any leading `//` stripped) is stored
//! under the option key `path` when non-empty. Empty-authority absolute
//! paths such as `backend:///tmp/cache` keep their leading `/`; host-style
//! paths such as `backend://localhost:6379/0` are stored as
//! `localhost:6379/0`. If the query already contains a `path` key, the
//! URI-supplied path wins and the parser errors on the conflict.
//! * Each `key=value` pair from the query becomes an entry in `options`.
//! Duplicate keys are rejected.
use std::sync::Arc;
use super::backend::CacheBackend;
use super::registry::{BackendConfig, build_from_config, normalize_backend_kind};
use crate::{Error, Result};
/// Parse `uri` into a [`BackendConfig`] and build the backend registered
/// under its `scheme`.
///
/// Returns an error if:
/// * the URI cannot be parsed,
/// * no backend is registered for that scheme, or
/// * the constructor itself fails.
pub fn build_from_uri(uri: &str) -> Result<Arc<dyn CacheBackend>> {
let config = parse_backend_uri(uri)?;
build_from_config(&config)
}
/// Parse `uri` into a [`BackendConfig`] without touching the registry.
///
/// See the module docs for the accepted grammar.
pub fn parse_backend_uri(uri: &str) -> Result<BackendConfig> {
let (scheme, rest) = split_scheme(uri)?;
let (path, query) = split_path_query(rest);
let mut config = BackendConfig::new(&scheme)?;
let normalized_path = normalize_path(path);
if !normalized_path.is_empty() {
config.options.insert("path".to_string(), normalized_path);
}
if let Some(query) = query {
for raw_pair in query.split('&') {
if raw_pair.is_empty() {
continue;
}
let (raw_key, raw_value) = raw_pair.split_once('=').ok_or_else(|| {
Error::invalid_input(format!(
"cache backend uri {:?}: query pair {:?} is missing '='",
uri, raw_pair
))
})?;
let key = percent_decode(raw_key).map_err(|err| {
Error::invalid_input(format!(
"cache backend uri {:?}: cannot decode query key {:?}: {}",
uri, raw_key, err
))
})?;
let value = percent_decode(raw_value).map_err(|err| {
Error::invalid_input(format!(
"cache backend uri {:?}: cannot decode query value {:?}: {}",
uri, raw_value, err
))
})?;
if config.options.contains_key(&key) {
return Err(Error::invalid_input(format!(
"cache backend uri {:?}: option {:?} is set more than once",
uri, key
)));
}
config.options.insert(key, value);
}
}
Ok(config)
}
fn split_scheme(uri: &str) -> Result<(String, &str)> {
let colon = uri.find(':').ok_or_else(|| {
Error::invalid_input(format!("cache backend uri {:?} is missing ':'", uri))
})?;
let scheme = &uri[..colon];
let scheme = normalize_backend_kind(scheme)
.map_err(|err| Error::invalid_input(format!("cache backend uri {:?}: {}", uri, err)))?;
Ok((scheme, &uri[colon + 1..]))
}
fn split_path_query(rest: &str) -> (&str, Option<&str>) {
match rest.split_once('?') {
Some((path, query)) => (path, Some(query)),
None => (rest, None),
}
}
/// Strip leading `//authority/` boilerplate and return the useful path
/// component. Empty authorities (e.g. `moka://`) yield an empty path, while
/// empty-authority absolute paths (e.g. `disk:///tmp/cache`) retain their
/// leading slash.
fn normalize_path(raw: &str) -> String {
let Some(without_marker) = raw.strip_prefix("//") else {
return raw.to_string();
};
if without_marker.is_empty() {
return String::new();
}
without_marker.to_string()
}
fn percent_decode(input: &str) -> std::result::Result<String, String> {
let bytes = input.as_bytes();
let mut out = Vec::with_capacity(bytes.len());
let mut i = 0;
while i < bytes.len() {
match bytes[i] {
b'%' => {
if i + 2 >= bytes.len() {
return Err(format!("truncated percent-escape at offset {}", i));
}
let hi = decode_hex_digit(bytes[i + 1])?;
let lo = decode_hex_digit(bytes[i + 2])?;
out.push((hi << 4) | lo);
i += 3;
}
b => {
out.push(b);
i += 1;
}
}
}
String::from_utf8(out).map_err(|err| err.to_string())
}
fn decode_hex_digit(b: u8) -> std::result::Result<u8, String> {
match b {
b'0'..=b'9' => Ok(b - b'0'),
b'a'..=b'f' => Ok(10 + b - b'a'),
b'A'..=b'F' => Ok(10 + b - b'A'),
_ => Err(format!(
"invalid hex digit {:?} in percent-escape",
b as char
)),
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn test_parse_authority_only() {
let cfg = parse_backend_uri("moka://?capacity=1073741824").unwrap();
assert_eq!(cfg.kind, "moka");
assert_eq!(
cfg.options.get("capacity").map(String::as_str),
Some("1073741824")
);
assert!(!cfg.options.contains_key("path"));
}
#[test]
fn test_parse_path_and_query() {
let cfg = parse_backend_uri("example:///var/lance/cache?capacity=10G").unwrap();
assert_eq!(cfg.kind, "example");
assert_eq!(
cfg.options.get("path").map(String::as_str),
Some("/var/lance/cache")
);
assert_eq!(cfg.options.get("capacity").map(String::as_str), Some("10G"));
}
#[test]
fn test_parse_host_style() {
// Redis-style URI with host:port + path segment. All of it lives
// under the "path" option; the backend is responsible for
// interpreting it.
let cfg = parse_backend_uri("redis://localhost:6379/0?prefix=lance").unwrap();
assert_eq!(cfg.kind, "redis");
assert_eq!(
cfg.options.get("path").map(String::as_str),
Some("localhost:6379/0"),
);
assert_eq!(cfg.options.get("prefix").map(String::as_str), Some("lance"));
}
#[test]
fn test_scheme_is_lowercased() {
// Different upper/lower cases must resolve to the same registry
// key, otherwise `Moka://` and `moka://` would look up different
// backends.
let cfg = parse_backend_uri("MOKA://?capacity=1").unwrap();
assert_eq!(cfg.kind, "moka");
}
#[test]
fn test_percent_decoding() {
let cfg = parse_backend_uri("kv://?prefix=a%2Fb&name=hello%20world&token=a+b%2Bc").unwrap();
assert_eq!(cfg.options.get("prefix").map(String::as_str), Some("a/b"));
assert_eq!(
cfg.options.get("name").map(String::as_str),
Some("hello world")
);
assert_eq!(cfg.options.get("token").map(String::as_str), Some("a+b+c"));
}
#[test]
fn test_empty_query_pair_is_skipped() {
// A trailing "&" should not cause a spurious "" pair to appear.
let cfg = parse_backend_uri("moka://?capacity=1&").unwrap();
assert_eq!(cfg.options.len(), 1);
}
#[test]
fn test_missing_scheme_errors() {
let err = parse_backend_uri("no-scheme-here").unwrap_err();
assert!(err.to_string().contains("missing ':'"));
}
#[test]
fn test_invalid_scheme_errors() {
// Digit-leading schemes are invalid per RFC 3986 and would clash
// with URI-like values elsewhere in the config.
let err = parse_backend_uri("1moka://").unwrap_err();
assert!(err.to_string().contains("must start with an ASCII letter"));
}
#[test]
fn test_duplicate_option_errors() {
let err = parse_backend_uri("moka://?capacity=1&capacity=2").unwrap_err();
assert!(err.to_string().contains("more than once"));
}
#[test]
fn test_query_pair_without_equals_errors() {
let err = parse_backend_uri("moka://?capacity").unwrap_err();
assert!(err.to_string().contains("missing '='"));
}
}
lance-artifact/rust/lance-core/src/cache/codec.rs
Vendored
+553
View File
@@ -0,0 +1,553 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright The Lance Authors
//! Serialization codecs for cache entries.
//!
//! Implement [`CacheCodecImpl`] on concrete types, then use
//! [`CacheCodec::from_impl`] to produce a type-erased codec for the cache.
//!
//! # Wire format
//!
//! Every serialized entry begins with a small hand-framed **envelope** so the
//! reader can validate it before trusting the body:
//!
//! ```text
//! [magic: 4B = b"LCE1"]
//! [envelope_version: u8]
//! [type_id_len: u16 LE][type_id: utf8] # stable, author-assigned
//! [type_version: u32 LE] # per-type body schema version
//! <body, written by the type's CacheCodecImpl::serialize>
//! ```
//!
//! The envelope is deliberately *not* protobuf: it is the most
//! stability-critical part, must parse robustly against arbitrary bytes
//! (including data written by older, pre-stabilization builds), and never
//! changes shape. Bodies use protobuf headers, where field-number evolution
//! pays off.
//!
//! # Decode outcome
//!
//! Deserialization never propagates a parse failure as a hard error into the
//! cache path. Anything the reader cannot confidently interpret — absent or
//! wrong magic, an unknown `envelope_version`, a `type_id` mismatch, an
//! unsupported `type_version`, or a body decode error — becomes
//! [`CacheDecode::Miss`]. A backend turns `Miss` into a normal cache miss and
//! recomputes the value. This is what lets data written by an older format
//! self-heal: it simply fails the magic check and is regenerated.
use std::io::Write;
use std::sync::Arc;
use bytes::Bytes;
use crate::{Error, Result};
use super::{CacheEntryReader, CacheEntryWriter};
// ---------------------------------------------------------------------------
// Envelope
// ---------------------------------------------------------------------------
/// Magic bytes that prefix every stabilized cache entry.
///
/// An ASCII tag (`0x4C 0x43 0x45 0x31`) chosen so it cannot collide with any
/// pre-stabilization blob: those began with either a small little-endian
/// length (tens of bytes) or a small tag byte, never these values.
///
/// Exported so backends can cheaply identify Lance cache entries (e.g. when
/// scanning a persistent store at startup) without hardcoding the bytes —
/// prefer [`has_cache_envelope`] over comparing against this directly.
pub const MAGIC: [u8; 4] = *b"LCE1";
/// Returns `true` if `data` begins with the cache-entry [`MAGIC`].
///
/// A cheap prefix check for backends that need to recognize Lance cache
/// entries without fully [`deserialize`](CacheCodec::deserialize)-ing them. A
/// `true` result only means the framing looks like ours; the entry can still
/// decode to a [`Miss`](CacheDecode::Miss) (e.g. wrong `type_id`).
pub fn has_cache_envelope(data: &[u8]) -> bool {
data.get(..MAGIC.len()) == Some(&MAGIC[..])
}
/// Version of the envelope framing itself. Bumped only if the outer frame
/// (magic/version/type_id/type_version layout) ever changes — expected never.
const ENVELOPE_VERSION: u8 = 1;
/// Parsed envelope borrowed from the input bytes.
struct ParsedEnvelope<'a> {
type_id: &'a str,
type_version: u32,
/// Offset of the first body byte within the input.
body_offset: usize,
}
/// Parse and validate the envelope at the start of `data`.
///
/// Returns `None` for anything that is not a well-formed envelope this build
/// understands (wrong/absent magic, unknown `envelope_version`, truncation,
/// non-utf8 `type_id`). Callers translate `None` into [`CacheDecode::Miss`].
fn parse_envelope(data: &Bytes) -> Option<ParsedEnvelope<'_>> {
let bytes = data.as_ref();
let mut off = 0usize;
let magic = bytes.get(off..off + 4)?;
if magic != MAGIC {
return None;
}
off += 4;
if *bytes.get(off)? != ENVELOPE_VERSION {
return None;
}
off += 1;
let type_id_len = u16::from_le_bytes(bytes.get(off..off + 2)?.try_into().ok()?) as usize;
off += 2;
let type_id = std::str::from_utf8(bytes.get(off..off + type_id_len)?).ok()?;
off += type_id_len;
let type_version = u32::from_le_bytes(bytes.get(off..off + 4)?.try_into().ok()?);
off += 4;
Some(ParsedEnvelope {
type_id,
type_version,
body_offset: off,
})
}
/// Write the envelope for `type_id`/`type_version`, returning the number of
/// bytes written (the body's starting offset).
fn write_envelope(writer: &mut dyn Write, type_id: &str, type_version: u32) -> Result<usize> {
let type_id_len = u16::try_from(type_id.len()).map_err(|_| {
Error::io(format!(
"cache codec type_id too long ({} bytes, max {})",
type_id.len(),
u16::MAX
))
})?;
writer.write_all(&MAGIC)?;
writer.write_all(&[ENVELOPE_VERSION])?;
writer.write_all(&type_id_len.to_le_bytes())?;
writer.write_all(type_id.as_bytes())?;
writer.write_all(&type_version.to_le_bytes())?;
Ok(4 + 1 + 2 + type_id.len() + 4)
}
// ---------------------------------------------------------------------------
// CacheDecode — first-class cache-miss outcome
// ---------------------------------------------------------------------------
/// Why a cache entry could not be decoded into the expected type.
///
/// Carried by [`CacheDecode::Miss`] so backends can emit targeted metrics
/// (e.g. distinguish "evicting due to a stale format" from "type collision")
/// without re-parsing. Every reason maps to the same behavior — recompute via
/// the loader — so callers that don't care can ignore it.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum CacheMissReason {
/// Absent or wrong magic, unknown `envelope_version`, truncated framing, or
/// a non-utf8 `type_id`. Typically an entry written by a pre-stabilization
/// or otherwise foreign build.
InvalidEnvelope,
/// Well-formed envelope, but its `type_id` names a different entry type than
/// the codec reading it.
TypeMismatch,
/// Written by a newer build whose `type_version` this build does not
/// understand and must not attempt to interpret.
VersionTooNew,
/// Envelope validated, but the body failed to decode (truncation, a
/// malformed protobuf header, an IPC error, etc.).
BodyError,
}
/// Outcome of deserializing a cache entry.
///
/// `Miss` means the bytes could not be confidently decoded into `T`; the
/// [`CacheMissReason`] says why. A backend treats any `Miss` exactly like a key
/// that was never present: recompute via the loader.
#[derive(Debug)]
pub enum CacheDecode<T> {
Hit(T),
Miss(CacheMissReason),
}
impl<T> CacheDecode<T> {
pub fn hit(self) -> Option<T> {
match self {
Self::Hit(v) => Some(v),
Self::Miss(_) => None,
}
}
}
// ---------------------------------------------------------------------------
// CacheCodecImpl — trait for serializable cache entry types
// ---------------------------------------------------------------------------
/// Serialization trait for cache entries.
///
/// **Experimental**: the serialized format is not yet covered by a stability
/// guarantee and may change between releases. When it does stabilize, the
/// rules are: `TYPE_ID`, protobuf field numbers, and enum values are
/// append-only forever; format changes that protobuf cannot express
/// transparently bump [`CURRENT_VERSION`](Self::CURRENT_VERSION).
///
/// Implement this on concrete types that need to survive serialization through
/// a persistent cache backend, then wire it into a
/// [`CacheKey`](super::CacheKey) via [`CacheCodec::from_impl`].
///
/// The envelope (magic/version/type_id/type_version) is written and validated
/// by the [`CacheCodec`] wrapper. [`serialize`](Self::serialize) writes only
/// the body — a header followed by sections in a fixed, version-keyed order —
/// and [`deserialize`](Self::deserialize) reads them back in that same order.
/// The read sequence mirroring the write sequence for each `type_version` is
/// the invariant the implementor owns.
pub trait CacheCodecImpl: Send + Sync {
/// Stable identity for this entry type. **Must not change once shipped.**
/// This is a deliberate author-assigned string, not `std::any::type_name`
/// (which is not stable across compiler versions).
const TYPE_ID: &'static str;
/// Body schema version this build writes. Bump when the body layout
/// changes in a way protobuf field additions cannot express transparently
/// (adding/removing/reordering sections, a raw-blob encoding change, etc.).
const CURRENT_VERSION: u32;
/// Write the body: a header, then sections in a fixed order.
fn serialize(&self, writer: &mut CacheEntryWriter<'_>) -> Result<()>;
/// Reconstruct from the body. Branch on
/// [`reader.version()`](CacheEntryReader::version) for backward compat;
/// sections are read in write order.
fn deserialize(reader: &mut CacheEntryReader<'_>) -> Result<Self>
where
Self: Sized;
}
// ---------------------------------------------------------------------------
// CacheCodec — type-erased codec passed to backends
// ---------------------------------------------------------------------------
pub(crate) type ArcAny = Arc<dyn std::any::Any + Send + Sync>;
/// Type-erased codec for serializing and deserializing cache entries.
///
/// `CacheCodec` carries the entry's stable `type_id`/`version` plus two plain
/// function pointers — it is `Copy` and has no heap allocation. Construct one
/// via [`CacheCodec::from_impl`] for types that implement [`CacheCodecImpl`],
/// or [`CacheCodec::new`] for custom cases (e.g. when the orphan rule prevents
/// a direct impl).
#[derive(Copy, Clone)]
pub struct CacheCodec {
type_id: &'static str,
version: u32,
serialize_body: fn(&ArcAny, &mut CacheEntryWriter<'_>) -> Result<()>,
deserialize_body: fn(&mut CacheEntryReader<'_>) -> Result<ArcAny>,
}
impl std::fmt::Debug for CacheCodec {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.debug_struct("CacheCodec")
.field("type_id", &self.type_id)
.field("version", &self.version)
.finish_non_exhaustive()
}
}
fn serialize_via_impl<T: CacheCodecImpl + 'static>(
any: &ArcAny,
writer: &mut CacheEntryWriter<'_>,
) -> Result<()> {
let val = any
.downcast_ref::<T>()
.expect("CacheCodec::serialize called with wrong type (this is a bug in the cache layer)");
val.serialize(writer)
}
fn deserialize_via_impl<T: CacheCodecImpl + 'static>(
reader: &mut CacheEntryReader<'_>,
) -> Result<ArcAny> {
let val = T::deserialize(reader)?;
Ok(Arc::new(val) as ArcAny)
}
impl CacheCodec {
/// Create a `CacheCodec` from explicit body function pointers.
///
/// Prefer [`from_impl`](Self::from_impl) when the value type implements
/// [`CacheCodecImpl`]. Use this for types where a direct impl isn't
/// possible (e.g. the orphan rule prevents it). `type_id` and `version`
/// play the same role as the corresponding [`CacheCodecImpl`] constants.
pub fn new(
type_id: &'static str,
version: u32,
serialize_body: fn(&ArcAny, &mut CacheEntryWriter<'_>) -> Result<()>,
deserialize_body: fn(&mut CacheEntryReader<'_>) -> Result<ArcAny>,
) -> Self {
Self {
type_id,
version,
serialize_body,
deserialize_body,
}
}
/// Create a `CacheCodec` from a [`CacheCodecImpl`] implementation.
pub fn from_impl<T: CacheCodecImpl + 'static>() -> Self {
Self {
type_id: T::TYPE_ID,
version: T::CURRENT_VERSION,
serialize_body: serialize_via_impl::<T>,
deserialize_body: deserialize_via_impl::<T>,
}
}
/// Return the stable entry type identity.
///
/// Persistent and tiered backends can use this metadata to route encoded
/// values without retaining a readable logical cache key.
pub const fn type_id(&self) -> &'static str {
self.type_id
}
/// Serialize `value` into `writer`: envelope first, then the body.
pub fn serialize(&self, value: &ArcAny, writer: &mut dyn Write) -> Result<()> {
let body_offset = write_envelope(writer, self.type_id, self.version)?;
let mut entry_writer = CacheEntryWriter::with_pos(writer, body_offset);
(self.serialize_body)(value, &mut entry_writer)
}
/// Deserialize an entry from `data`.
///
/// Never fails: any non-fatal failure to interpret the bytes becomes a
/// [`CacheDecode::Miss`] with the reason why (see [`CacheMissReason`]).
/// Reading from an in-memory [`Bytes`] cannot do I/O, so there is no fault
/// channel — a miss is the only non-`Hit` outcome.
pub fn deserialize(&self, data: &Bytes) -> CacheDecode<ArcAny> {
let Some(envelope) = parse_envelope(data) else {
log::debug!("cache entry rejected: missing or invalid envelope");
return CacheDecode::Miss(CacheMissReason::InvalidEnvelope);
};
if envelope.type_id != self.type_id {
log::debug!(
"cache entry type_id mismatch: got {:?}, expected {:?}",
envelope.type_id,
self.type_id
);
return CacheDecode::Miss(CacheMissReason::TypeMismatch);
}
// A version newer than this build writes was produced by a newer build
// whose body layout we cannot assume to understand. Older/equal versions
// are the impl's responsibility to handle (branching on reader.version()).
if envelope.type_version > self.version {
log::debug!(
"cache entry {:?} has unsupported type_version {} (this build writes {})",
self.type_id,
envelope.type_version,
self.version
);
return CacheDecode::Miss(CacheMissReason::VersionTooNew);
}
let mut reader = CacheEntryReader::new(data, envelope.body_offset, envelope.type_version);
match (self.deserialize_body)(&mut reader) {
Ok(value) => CacheDecode::Hit(value),
Err(e) => {
log::debug!(
"cache entry {:?} v{} failed to decode: {e}",
self.type_id,
envelope.type_version
);
CacheDecode::Miss(CacheMissReason::BodyError)
}
}
}
}
#[cfg(test)]
mod tests {
use super::*;
/// A trivial codec used to exercise the envelope and miss semantics
/// without pulling in arrow-backed payloads.
#[derive(Debug, PartialEq)]
struct Widget {
n: u32,
}
impl CacheCodecImpl for Widget {
const TYPE_ID: &'static str = "test.Widget";
const CURRENT_VERSION: u32 = 1;
fn serialize(&self, writer: &mut CacheEntryWriter<'_>) -> Result<()> {
writer.write_raw(&self.n.to_le_bytes())
}
fn deserialize(reader: &mut CacheEntryReader<'_>) -> Result<Self> {
let bytes = reader.read_raw()?;
let n = u32::from_le_bytes(
bytes
.as_ref()
.try_into()
.map_err(|_| Error::io("bad widget".to_string()))?,
);
Ok(Self { n })
}
}
fn serialize_widget(widget: &Widget) -> Bytes {
let codec = CacheCodec::from_impl::<Widget>();
let any: ArcAny = Arc::new(Widget { n: widget.n });
let mut buf = Vec::new();
codec.serialize(&any, &mut buf).unwrap();
Bytes::from(buf)
}
/// The miss reason, or `None` if the decode was a hit.
fn miss_reason(data: &Bytes) -> Option<CacheMissReason> {
match deserialize_widget(data) {
CacheDecode::Hit(_) => None,
CacheDecode::Miss(reason) => Some(reason),
}
}
fn deserialize_widget(data: &Bytes) -> CacheDecode<Widget> {
let codec = CacheCodec::from_impl::<Widget>();
match codec.deserialize(data) {
CacheDecode::Hit(any) => {
CacheDecode::Hit(Arc::try_unwrap(any.downcast::<Widget>().unwrap()).unwrap())
}
CacheDecode::Miss(reason) => CacheDecode::Miss(reason),
}
}
#[test]
fn envelope_roundtrip_hits() {
let bytes = serialize_widget(&Widget { n: 0xDEADBEEF });
// Sanity: the entry starts with the magic.
assert_eq!(&bytes[..4], b"LCE1");
let decoded = deserialize_widget(&bytes).hit().unwrap();
assert_eq!(decoded, Widget { n: 0xDEADBEEF });
}
#[test]
fn has_cache_envelope_detects_magic() {
let bytes = serialize_widget(&Widget { n: 1 });
assert!(has_cache_envelope(&bytes));
assert!(has_cache_envelope(&MAGIC)); // exactly the magic, nothing after
assert!(!has_cache_envelope(b"LCE")); // too short
assert!(!has_cache_envelope(b"JUNK and more"));
assert!(!has_cache_envelope(&[]));
}
#[test]
fn wrong_magic_is_miss() {
let mut bytes = serialize_widget(&Widget { n: 7 }).to_vec();
bytes[0] = b'X';
assert_eq!(
miss_reason(&Bytes::from(bytes)),
Some(CacheMissReason::InvalidEnvelope)
);
}
#[test]
fn pre_stabilization_blob_is_miss() {
// An old unstable blob led with a small u64 LE length prefix (a JSON
// header of tens of bytes) — no magic. It must self-heal to a miss.
let mut blob = Vec::new();
blob.extend_from_slice(&(42u64).to_le_bytes());
blob.extend_from_slice(&[0u8; 42]);
assert_eq!(
miss_reason(&Bytes::from(blob)),
Some(CacheMissReason::InvalidEnvelope)
);
// A different unstable shape led with a small u8 tag (0/1/2).
assert_eq!(
miss_reason(&Bytes::from(vec![0u8, 1, 2, 3])),
Some(CacheMissReason::InvalidEnvelope)
);
}
#[test]
fn unknown_envelope_version_is_miss() {
let mut bytes = serialize_widget(&Widget { n: 7 }).to_vec();
bytes[4] = 0xFF; // envelope_version byte
assert_eq!(
miss_reason(&Bytes::from(bytes)),
Some(CacheMissReason::InvalidEnvelope)
);
}
#[test]
fn type_id_mismatch_is_miss() {
// Hand-build an envelope with a foreign type_id but valid framing.
let mut buf = Vec::new();
write_envelope(&mut buf, "some.OtherType", 1).unwrap();
buf.extend_from_slice(&(4u64).to_le_bytes());
buf.extend_from_slice(&99u32.to_le_bytes());
assert_eq!(
miss_reason(&Bytes::from(buf)),
Some(CacheMissReason::TypeMismatch)
);
}
#[test]
fn unsupported_future_type_version_is_miss() {
// An entry written by a newer build (higher type_version) must miss
// rather than be misread by this build.
let mut buf = Vec::new();
write_envelope(&mut buf, Widget::TYPE_ID, Widget::CURRENT_VERSION + 1).unwrap();
lance_arrow::ipc::write_len_prefixed_bytes(&mut buf, &9u32.to_le_bytes()).unwrap();
assert_eq!(
miss_reason(&Bytes::from(buf)),
Some(CacheMissReason::VersionTooNew)
);
}
#[test]
fn truncated_envelope_is_miss() {
let bytes = serialize_widget(&Widget { n: 7 });
for cut in [0, 1, 4, 5, 7, 9] {
assert_eq!(
miss_reason(&bytes.slice(..cut.min(bytes.len()))),
Some(CacheMissReason::InvalidEnvelope),
"truncating to {cut} bytes should miss as InvalidEnvelope"
);
}
}
#[test]
fn body_decode_error_is_miss() {
// Valid envelope, but the body is too short for the widget.
let mut buf = Vec::new();
write_envelope(&mut buf, Widget::TYPE_ID, Widget::CURRENT_VERSION).unwrap();
buf.extend_from_slice(&(1u64).to_le_bytes());
buf.push(0u8);
assert_eq!(
miss_reason(&Bytes::from(buf)),
Some(CacheMissReason::BodyError)
);
}
#[test]
fn reader_exposes_envelope_version() {
// type_version travels through the envelope to reader.version().
let mut buf = Vec::new();
write_envelope(&mut buf, Widget::TYPE_ID, 7).unwrap();
let body_off = buf.len();
// A widget body so the codec can decode it.
lance_arrow::ipc::write_len_prefixed_bytes(&mut buf, &5u32.to_le_bytes()).unwrap();
let data = Bytes::from(buf);
let mut r = CacheEntryReader::new(&data, body_off, 7);
assert_eq!(r.version(), 7);
assert_eq!(r.read_raw().unwrap().as_ref(), 5u32.to_le_bytes());
}
}
lance-artifact/rust/lance-core/src/cache/entry_io.rs
Vendored
+202
View File
@@ -0,0 +1,202 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright The Lance Authors
//! Streaming readers/writers for cache entry bodies.
//!
//! [`CacheCodecImpl`](super::CacheCodecImpl) bodies are written and read
//! through these wrappers. They keep serialization streaming (no buffering of
//! the whole entry) and reads zero-copy (sections borrow from the input
//! [`Bytes`]), while tracking the byte position needed to keep Arrow IPC
//! sections 64-byte aligned (see [`lance_arrow::ipc`]).
//!
//! Body layout primitives:
//!
//! ```text
//! HEADER : [header_len: u32 LE][header proto bytes]
//! ARROW_IPC : [pad to 64B][self-delimiting IPC stream]
//! RAW_BLOB : [len: u64 LE][bytes]
//! ```
use std::io::Write;
use arrow_array::RecordBatch;
use bytes::Bytes;
use prost::Message;
use crate::{Error, Result};
/// Writes a cache entry body: a header followed by sections, streaming
/// directly to the underlying writer.
///
/// The envelope is written by the [`CacheCodec`](super::CacheCodec) wrapper
/// before this writer is handed to
/// [`CacheCodecImpl::serialize`](super::CacheCodecImpl::serialize).
pub struct CacheEntryWriter<'a> {
writer: &'a mut dyn Write,
/// Absolute byte offset within the entry, used to align IPC sections.
pos: usize,
}
impl<'a> CacheEntryWriter<'a> {
/// Create a writer positioned at the start of an entry (offset 0).
///
/// Use this for nested serialization into a standalone buffer. The
/// envelope-aware entry point is [`CacheCodec::serialize`](super::CacheCodec::serialize).
pub fn new(writer: &'a mut dyn Write) -> Self {
Self { writer, pos: 0 }
}
/// Create a writer whose section alignment accounts for `pos` bytes
/// already written ahead of the body (i.e. the envelope).
pub(crate) fn with_pos(writer: &'a mut dyn Write, pos: usize) -> Self {
Self { writer, pos }
}
/// Write a single discriminant byte (e.g. a variant tag).
pub fn write_u8(&mut self, value: u8) -> Result<()> {
self.writer.write_all(&[value])?;
self.pos += 1;
Ok(())
}
/// Write a protobuf header as `[len: u32 LE][bytes]`.
pub fn write_header<P: Message>(&mut self, header: &P) -> Result<()> {
let bytes = header.encode_to_vec();
let len = u32::try_from(bytes.len())
.map_err(|_| Error::io(format!("cache header too large: {} bytes", bytes.len())))?;
self.writer.write_all(&len.to_le_bytes())?;
self.writer.write_all(&bytes)?;
self.pos += 4 + bytes.len();
Ok(())
}
/// Write `batch` as a 64-byte-aligned Arrow IPC section.
pub fn write_ipc(&mut self, batch: &RecordBatch) -> Result<()> {
lance_arrow::ipc::write_ipc_section(self.writer, &mut self.pos, batch)
.map_err(|e| Error::io(e.to_string()))
}
/// Write `batches` as a single 64-byte-aligned multi-batch Arrow IPC
/// section. The iterator must yield at least one batch.
pub fn write_ipc_batches<I>(&mut self, batches: I) -> Result<()>
where
I: IntoIterator<Item = RecordBatch>,
{
lance_arrow::ipc::write_ipc_section_batches(self.writer, &mut self.pos, batches)
.map_err(|e| Error::io(e.to_string()))
}
/// Write a raw blob as `[len: u64 LE][bytes]`.
///
/// Only for byte payloads that already have their own stable, portable
/// encoding (e.g. a roaring bitmap, a varint-packed stream).
pub fn write_raw(&mut self, bytes: &[u8]) -> Result<()> {
lance_arrow::ipc::write_len_prefixed_bytes(self.writer, bytes)
.map_err(|e| Error::io(e.to_string()))?;
self.pos += 8 + bytes.len();
Ok(())
}
/// The underlying writer, for a payload that carries its own framing.
///
/// Use this only when the codec writes a self-delimiting or whole-body
/// payload — e.g. streaming a roaring bitmap as the entire body, where the
/// length prefix of [`write_raw`](Self::write_raw) would be redundant and
/// buffering to measure that length would force an extra copy. For
/// structured bodies prefer [`write_header`](Self::write_header) /
/// [`write_ipc`](Self::write_ipc) / [`write_raw`](Self::write_raw), which
/// give you versioning and 64-byte IPC alignment.
///
/// Bytes written through this do **not** advance the section-alignment
/// position, so it must not be interleaved with [`write_ipc`](Self::write_ipc).
pub fn raw_writer(&mut self) -> &mut dyn Write {
self.writer
}
}
/// Reads a cache entry body, tracking an offset into the input and exposing
/// the entry's `type_version` so implementors can branch for backward compat.
///
/// All reads are zero-copy: returned [`Bytes`] and the buffers behind decoded
/// [`RecordBatch`]es borrow from the input allocation.
pub struct CacheEntryReader<'a> {
data: &'a Bytes,
offset: usize,
version: u32,
}
impl<'a> CacheEntryReader<'a> {
/// Create a reader over `data`, starting at body byte `offset`, for an
/// entry written at `version`.
pub fn new(data: &'a Bytes, offset: usize, version: u32) -> Self {
Self {
data,
offset,
version,
}
}
/// The `type_version` from the envelope. Branch on this for backward compat.
pub fn version(&self) -> u32 {
self.version
}
/// Read a single discriminant byte written by [`CacheEntryWriter::write_u8`].
pub fn read_u8(&mut self) -> Result<u8> {
let bytes = self.data.as_ref();
let v = *bytes
.get(self.offset)
.ok_or_else(|| Error::io("cache entry: truncated, missing tag byte".to_string()))?;
self.offset += 1;
Ok(v)
}
/// Read a protobuf header written by [`CacheEntryWriter::write_header`].
pub fn read_header<P: Message + Default>(&mut self) -> Result<P> {
let bytes = self.data.as_ref();
let len_end = self
.offset
.checked_add(4)
.filter(|&e| e <= bytes.len())
.ok_or_else(|| Error::io("cache header: truncated length prefix".to_string()))?;
let len = u32::from_le_bytes(bytes[self.offset..len_end].try_into().unwrap()) as usize;
let data_end = len_end
.checked_add(len)
.filter(|&e| e <= bytes.len())
.ok_or_else(|| Error::io("cache header: truncated body".to_string()))?;
let msg = P::decode(&bytes[len_end..data_end])
.map_err(|e| Error::io(format!("cache header decode failed: {e}")))?;
self.offset = data_end;
Ok(msg)
}
/// Read one [`RecordBatch`] from a 64-byte-aligned IPC section.
pub fn read_ipc(&mut self) -> Result<RecordBatch> {
lance_arrow::ipc::read_ipc_section_at(self.data, &mut self.offset)
.map_err(|e| Error::io(e.to_string()))
}
/// Read all [`RecordBatch`]es from a 64-byte-aligned multi-batch IPC
/// section written by [`CacheEntryWriter::write_ipc_batches`].
pub fn read_ipc_batches(&mut self) -> Result<Vec<RecordBatch>> {
lance_arrow::ipc::read_ipc_section_batches_at(self.data, &mut self.offset)
.map_err(|e| Error::io(e.to_string()))
}
/// Read a raw blob written by [`CacheEntryWriter::write_raw`], zero-copy.
pub fn read_raw(&mut self) -> Result<Bytes> {
lance_arrow::ipc::read_len_prefixed_bytes_at(self.data, &mut self.offset)
.map_err(|e| Error::io(e.to_string()))
}
/// The not-yet-consumed body bytes as a zero-copy slice.
///
/// For a payload that carries its own framing and is parsed with the
/// codec's own cursor — the read counterpart of
/// [`CacheEntryWriter::raw_writer`]. For structured bodies prefer
/// [`read_header`](Self::read_header) / [`read_ipc`](Self::read_ipc) /
/// [`read_raw`](Self::read_raw).
pub fn body(&self) -> Bytes {
self.data.slice(self.offset..)
}
}
lance-artifact/rust/lance-core/src/cache/key.rs
Vendored
+476
View File
@@ -0,0 +1,476 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright The Lance Authors
//! Canonical fixed-size cache key construction.
//!
//! Cache keys are BLAKE3 digests truncated to 128 bits. Logical key fields are
//! encoded with explicit type tags, fixed-width little-endian integers, and
//! length framing for variable-width values. This makes the pre-hash encoding
//! unambiguous and stable across processes, platforms, and builds.
//!
//! The digest is a cache identity, not an authentication or access-control
//! primitive: namespace derivation keys are deterministic and not secret.
//! Truncating to 128 bits gives generic birthday resistance of approximately
//! 64 bits. This protocol does not introduce a FIPS mode; BLAKE3 is the
//! repository's selected cache-key algorithm.
use std::fmt;
/// Storage namespace identifier for canonical cache keys.
///
/// Persistent backends should include this identifier in their physical
/// namespace so future algorithm or framing changes produce cold misses.
pub const CACHE_KEY_FORMAT: &str = "blake3-128-v1";
const KEY_FORMAT_VERSION: u32 = 1;
const NAMESPACE_CONTEXT: &str = "lance-format/lance 2026-07-17 cache namespace v1";
const NAMESPACE_DOMAIN: &[u8] = b"lance-cache-namespace\0";
const ENTRY_DOMAIN: &[u8] = b"lance-cache-entry\0";
/// One-byte type discriminants in the stable key encoding.
#[derive(Clone, Copy)]
#[repr(u8)]
enum FieldTag {
U8 = 1,
U16 = 2,
U32 = 3,
U64 = 4,
I32 = 5,
I64 = 6,
Bool = 7,
Str = 8,
Bytes = 9,
FixedBytes = 10,
None = 11,
Some = 12,
Variant = 13,
Sequence = 14,
}
impl FieldTag {
const fn as_u8(self) -> u8 {
self as u8
}
}
/// Versioned schema identity for fields emitted by a cache key.
///
/// Change the version whenever the encoded fields or their meaning changes.
/// The identifier must be stable and globally unique to the logical layout.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct CacheKeySchema {
id: &'static str,
version: u32,
}
impl CacheKeySchema {
/// Compatibility schema used by the default string-key bridge.
pub const LEGACY_TEXT: Self = Self::new("lance.cache.legacy-text", 1);
/// Create a stable schema identifier and encoding version.
pub const fn new(id: &'static str, version: u32) -> Self {
Self { id, version }
}
/// Return the author-assigned schema identifier.
pub const fn id(self) -> &'static str {
self.id
}
/// Return the schema encoding version.
pub const fn version(self) -> u32 {
self.version
}
}
/// Opaque 128-bit key passed to cache backends.
///
/// The byte representation is canonical. It can be persisted directly and is
/// independent of the host's native integer endianness.
#[derive(Clone, Copy, Eq, Hash, Ord, PartialEq, PartialOrd)]
pub struct InternalCacheKey([u8; 16]);
impl InternalCacheKey {
/// Reconstruct a key from its canonical bytes.
pub const fn from_bytes(bytes: [u8; 16]) -> Self {
Self(bytes)
}
/// Borrow the canonical byte representation.
pub const fn as_bytes(&self) -> &[u8; 16] {
&self.0
}
/// Consume the key and return its canonical bytes.
pub const fn into_bytes(self) -> [u8; 16] {
self.0
}
}
impl fmt::Debug for InternalCacheKey {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
f.write_str("InternalCacheKey(")?;
for byte in self.0 {
write!(f, "{byte:02x}")?;
}
f.write_str(")")
}
}
/// Pre-derived namespace key shared by entries in one logical cache scope.
#[derive(Clone, Copy, Debug)]
pub struct CacheNamespace([u8; 32]);
impl CacheNamespace {
/// Construct the stable root namespace.
pub fn root() -> Self {
Self(blake3::derive_key(NAMESPACE_CONTEXT, b""))
}
/// Derive a child namespace from one framed hierarchy segment.
pub fn child(self, segment: &str) -> Self {
let mut hasher = blake3::Hasher::new_keyed(&self.0);
write_framed(&mut hasher, NAMESPACE_DOMAIN);
hasher.update(&KEY_FORMAT_VERSION.to_le_bytes());
write_framed(&mut hasher, segment.as_bytes());
Self(hasher.finalize().into())
}
}
/// Streams typed logical fields into a canonical cache key.
///
/// Integer methods use little-endian fixed-width encoding. Variable-width
/// strings and bytes are type-tagged and length-prefixed. There is deliberately
/// no `usize` method because cache identities must not depend on target width.
///
/// # Examples
///
/// ```
/// use lance_core::cache::{CacheKeySchema, CacheNamespace, KeyBuilder};
///
/// let namespace = CacheNamespace::root().child("dataset");
/// let mut builder = KeyBuilder::new(
/// namespace,
/// "example.Page",
/// CacheKeySchema::new("example.page-key", 1),
/// );
/// builder.write_u32(7);
/// builder.write_str("values");
/// let key = builder.finish();
/// assert_eq!(key.as_bytes().len(), 16);
/// ```
pub struct KeyBuilder {
hasher: blake3::Hasher,
}
impl KeyBuilder {
/// Start a key in a namespace with a stable value type and key schema.
pub fn new(
namespace: CacheNamespace,
stable_type_id: &'static str,
schema: CacheKeySchema,
) -> Self {
let mut hasher = blake3::Hasher::new_keyed(&namespace.0);
write_framed(&mut hasher, ENTRY_DOMAIN);
hasher.update(&KEY_FORMAT_VERSION.to_le_bytes());
write_framed(&mut hasher, stable_type_id.as_bytes());
write_framed(&mut hasher, schema.id().as_bytes());
hasher.update(&schema.version().to_le_bytes());
Self { hasher }
}
/// Append a tagged, fixed-width `u8`.
#[inline]
pub fn write_u8(&mut self, value: u8) {
self.hasher.update(&[FieldTag::U8.as_u8(), value]);
}
/// Append a tagged, little-endian `u16`.
#[inline]
pub fn write_u16(&mut self, value: u16) {
let mut encoded = [0; 3];
encoded[0] = FieldTag::U16.as_u8();
encoded[1..].copy_from_slice(&value.to_le_bytes());
self.hasher.update(&encoded);
}
/// Append a tagged, little-endian `u32`.
#[inline]
pub fn write_u32(&mut self, value: u32) {
let mut encoded = [0; 5];
encoded[0] = FieldTag::U32.as_u8();
encoded[1..].copy_from_slice(&value.to_le_bytes());
self.hasher.update(&encoded);
}
/// Append a tagged, little-endian `u64`.
#[inline]
pub fn write_u64(&mut self, value: u64) {
let mut encoded = [0; 9];
encoded[0] = FieldTag::U64.as_u8();
encoded[1..].copy_from_slice(&value.to_le_bytes());
self.hasher.update(&encoded);
}
/// Append a tagged, little-endian `i32`.
#[inline]
pub fn write_i32(&mut self, value: i32) {
let mut encoded = [0; 5];
encoded[0] = FieldTag::I32.as_u8();
encoded[1..].copy_from_slice(&value.to_le_bytes());
self.hasher.update(&encoded);
}
/// Append a tagged, little-endian `i64`.
#[inline]
pub fn write_i64(&mut self, value: i64) {
let mut encoded = [0; 9];
encoded[0] = FieldTag::I64.as_u8();
encoded[1..].copy_from_slice(&value.to_le_bytes());
self.hasher.update(&encoded);
}
/// Append a tagged boolean.
#[inline]
pub fn write_bool(&mut self, value: bool) {
self.hasher
.update(&[FieldTag::Bool.as_u8(), u8::from(value)]);
}
/// Append a tagged, length-prefixed UTF-8 string.
#[inline]
pub fn write_str(&mut self, value: &str) {
self.write_variable(FieldTag::Str, value.as_bytes());
}
/// Append tagged, length-prefixed bytes.
#[inline]
pub fn write_bytes(&mut self, value: &[u8]) {
self.write_variable(FieldTag::Bytes, value);
}
/// Append a tagged fixed-size byte array, including its length.
#[inline]
pub fn write_fixed_bytes<const N: usize>(&mut self, value: &[u8; N]) {
self.write_variable(FieldTag::FixedBytes, value);
}
/// Append the canonical marker for an absent optional value.
#[inline]
pub fn write_none(&mut self) {
self.hasher.update(&[FieldTag::None.as_u8()]);
}
/// Append the canonical marker for a present optional value.
#[inline]
pub fn write_some(&mut self) {
self.hasher.update(&[FieldTag::Some.as_u8()]);
}
/// Append a tagged enum variant ordinal.
#[inline]
pub fn write_variant(&mut self, variant: u32) {
let mut encoded = [0; 5];
encoded[0] = FieldTag::Variant.as_u8();
encoded[1..].copy_from_slice(&variant.to_le_bytes());
self.hasher.update(&encoded);
}
/// Append the length of a following sequence.
#[inline]
pub fn write_sequence_len(&mut self, len: u64) {
let mut encoded = [0; 9];
encoded[0] = FieldTag::Sequence.as_u8();
encoded[1..].copy_from_slice(&len.to_le_bytes());
self.hasher.update(&encoded);
}
/// Finalize and return the canonical 128-bit key.
#[inline]
pub fn finish(self) -> InternalCacheKey {
let hash = self.hasher.finalize();
let mut bytes = [0; 16];
bytes.copy_from_slice(&hash.as_bytes()[..16]);
InternalCacheKey(bytes)
}
#[inline]
fn write_variable(&mut self, tag: FieldTag, value: &[u8]) {
self.hasher.update(&[tag.as_u8()]);
self.hasher.update(&encoded_len(value));
self.hasher.update(value);
}
}
#[inline]
fn write_framed(hasher: &mut blake3::Hasher, value: &[u8]) {
hasher.update(&encoded_len(value));
hasher.update(value);
}
#[inline]
fn encoded_len(value: &[u8]) -> [u8; 8] {
(value.len() as u64).to_le_bytes()
}
#[cfg(test)]
mod tests {
use super::*;
const SCHEMA: CacheKeySchema = CacheKeySchema::new("test.key", 1);
fn builder() -> KeyBuilder {
KeyBuilder::new(
CacheNamespace::root().child("s3://bucket/dataset"),
"test.Value",
SCHEMA,
)
}
fn key_with(write: impl FnOnce(&mut KeyBuilder)) -> InternalCacheKey {
let mut key = builder();
write(&mut key);
key.finish()
}
#[test]
fn key_and_namespace_have_fixed_sizes() {
assert_eq!(std::mem::size_of::<InternalCacheKey>(), 16);
assert_eq!(std::mem::size_of::<CacheNamespace>(), 32);
assert_eq!(std::mem::size_of::<FieldTag>(), 1);
}
#[test]
fn blake3_matches_official_empty_keyed_hash_vector() {
let key = *b"whats the Elvish word for friend";
assert_eq!(
blake3::keyed_hash(&key, b"").as_bytes(),
&[
0x92, 0xb2, 0xb7, 0x56, 0x04, 0xed, 0x3c, 0x76, 0x1f, 0x9d, 0x6f, 0x62, 0x39, 0x2c,
0x8a, 0x92, 0x27, 0xad, 0x0e, 0xa3, 0xf0, 0x95, 0x73, 0xe7, 0x83, 0xf1, 0x49, 0x8a,
0x4e, 0xd6, 0x0d, 0x26,
]
);
}
#[test]
fn typed_fields_and_boundaries_are_unambiguous() {
let cases = [
key_with(|key| {
key.write_str("ab");
key.write_str("c");
}),
key_with(|key| {
key.write_str("a");
key.write_str("bc");
}),
key_with(|key| key.write_str("")),
key_with(|key| key.write_bytes(b"")),
key_with(|key| key.write_fixed_bytes(b"")),
key_with(|key| key.write_u8(1)),
key_with(|key| key.write_u16(1)),
key_with(|key| key.write_u32(1)),
key_with(|key| key.write_u64(1)),
key_with(|key| key.write_i32(1)),
key_with(|key| key.write_i64(1)),
key_with(|key| key.write_bool(false)),
key_with(|key| key.write_bool(true)),
key_with(KeyBuilder::write_none),
key_with(KeyBuilder::write_some),
key_with(|key| key.write_variant(0)),
key_with(|key| key.write_variant(1)),
];
assert_eq!(std::collections::BTreeSet::from(cases).len(), cases.len());
assert_ne!(
key_with(|key| {
key.write_sequence_len(2);
key.write_u32(1);
key.write_u32(2);
}),
key_with(|key| {
key.write_u32(1);
key.write_u32(2);
})
);
}
#[test]
fn namespace_type_schema_and_version_are_domain_separated() {
let root = CacheNamespace::root();
let namespace = root.child("dataset").child("index");
let nested = KeyBuilder::new(namespace, "test.Value", SCHEMA).finish();
let combined = KeyBuilder::new(root.child("dataset/index"), "test.Value", SCHEMA).finish();
assert_ne!(nested, combined);
assert_ne!(
nested,
KeyBuilder::new(namespace, "test.OtherValue", SCHEMA).finish()
);
assert_ne!(
nested,
KeyBuilder::new(
namespace,
"test.Value",
CacheKeySchema::new("test.other-key", 1),
)
.finish()
);
assert_ne!(
nested,
KeyBuilder::new(namespace, "test.Value", CacheKeySchema::new("test.key", 2),).finish()
);
let tenant_a_memory =
KeyBuilder::new(root.child("tenant-a").child("memory"), "test.Value", SCHEMA).finish();
assert_ne!(
tenant_a_memory,
KeyBuilder::new(root.child("tenant-b").child("memory"), "test.Value", SCHEMA,).finish()
);
assert_ne!(
tenant_a_memory,
KeyBuilder::new(
root.child("tenant-a").child("persistent"),
"test.Value",
SCHEMA,
)
.finish()
);
}
#[test]
fn integers_use_fixed_width_little_endian_encoding() {
let namespace = CacheNamespace::root().child("endianness");
let mut key = KeyBuilder::new(namespace, "test.Value", SCHEMA);
key.write_u32(0x0102_0304);
let actual = key.finish();
let mut reference = blake3::Hasher::new_keyed(&namespace.0);
write_framed(&mut reference, ENTRY_DOMAIN);
reference.update(&KEY_FORMAT_VERSION.to_le_bytes());
write_framed(&mut reference, b"test.Value");
write_framed(&mut reference, SCHEMA.id().as_bytes());
reference.update(&SCHEMA.version().to_le_bytes());
reference.update(&[FieldTag::U32.as_u8(), 0x04, 0x03, 0x02, 0x01]);
let mut expected = [0; 16];
expected.copy_from_slice(&reference.finalize().as_bytes()[..16]);
assert_eq!(actual, InternalCacheKey::from_bytes(expected));
}
#[test]
fn key_has_stable_golden_vector() {
let mut key = builder();
key.write_u32(7);
key.write_str("page");
key.write_some();
key.write_fixed_bytes(&[0xAB; 16]);
assert_eq!(
key.finish().into_bytes(),
[
0xc4, 0x38, 0xff, 0x22, 0x30, 0x55, 0x30, 0xfc, 0x74, 0x16, 0x38, 0xe9, 0x7d, 0x45,
0xa5, 0x68,
]
);
}
}
lance-artifact/rust/lance-core/src/cache/mod.rs
Vendored
+1435
View File
File diff suppressed because it is too large Load Diff
lance-artifact/rust/lance-core/src/cache/moka.rs
Vendored
+349
View File
@@ -0,0 +1,349 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright The Lance Authors
use std::pin::Pin;
use std::sync::Arc;
use std::sync::atomic::{AtomicBool, Ordering};
use async_trait::async_trait;
use futures::Future;
use crate::Result;
use crate::deepsize::Context;
use crate::error::CloneableError;
use super::backend::{CacheBackend, CacheEntry};
use super::{CacheCodec, InternalCacheKey};
/// Internal record stored in the moka cache.
#[derive(Clone, Debug)]
struct MokaCacheEntry {
entry: CacheEntry,
size_bytes: usize,
}
/// Per-entry key cost for eviction.
pub(super) fn key_footprint(_key: &InternalCacheKey) -> usize {
std::mem::size_of::<InternalCacheKey>()
}
fn physical_size(key: &InternalCacheKey, size_bytes: usize) -> usize {
key_footprint(key).saturating_add(size_bytes)
}
/// Number of physical bytes represented by one Moka weight unit.
///
/// Moka limits each entry's weight to `u32`, so capacities above 4 GiB need
/// coarser units to account for a single large entry without undercharging it.
fn weight_unit(capacity: usize) -> usize {
capacity.div_ceil(u32::MAX as usize).max(1)
}
fn entry_weight(key: &InternalCacheKey, size_bytes: usize, weight_unit: usize) -> u32 {
physical_size(key, size_bytes)
.div_ceil(weight_unit)
.try_into()
.unwrap_or(u32::MAX)
}
/// Default [`CacheBackend`] backed by a [moka](https://crates.io/crates/moka) cache.
///
/// Provides weighted-capacity eviction and concurrent-load deduplication
/// via moka's built-in `optionally_get_with`.
pub struct MokaCacheBackend {
cache: moka::future::Cache<InternalCacheKey, MokaCacheEntry>,
capacity: usize,
weight_unit: usize,
}
impl std::fmt::Debug for MokaCacheBackend {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.debug_struct("MokaCacheBackend")
.field("entry_count", &self.cache.entry_count())
.finish()
}
}
impl MokaCacheBackend {
pub fn with_capacity(capacity: usize) -> Self {
let weight_unit = weight_unit(capacity);
let capacity_weight = capacity.div_ceil(weight_unit) as u64;
let cache = moka::future::Cache::builder()
.max_capacity(capacity_weight)
.weigher(move |key: &InternalCacheKey, entry: &MokaCacheEntry| {
entry_weight(key, entry.size_bytes, weight_unit)
})
.build();
Self {
cache,
capacity,
weight_unit,
}
}
pub fn no_cache() -> Self {
Self {
cache: moka::future::Cache::new(0),
capacity: 0,
weight_unit: 1,
}
}
/// Configured weighted capacity in bytes.
pub fn capacity(&self) -> usize {
self.capacity
}
fn weighted_size_bytes(&self) -> usize {
self.cache
.weighted_size()
.saturating_mul(self.weight_unit as u64)
.try_into()
.unwrap_or(usize::MAX)
}
}
#[async_trait]
impl CacheBackend for MokaCacheBackend {
async fn get(&self, key: &InternalCacheKey, _codec: Option<CacheCodec>) -> Option<CacheEntry> {
self.cache.get(key).await.map(|r| r.entry)
}
async fn insert(
&self,
key: &InternalCacheKey,
entry: CacheEntry,
size_bytes: usize,
_codec: Option<CacheCodec>,
) {
self.cache
.insert(*key, MokaCacheEntry { entry, size_bytes })
.await;
}
async fn get_or_insert<'a>(
&self,
key: &InternalCacheKey,
loader: Pin<Box<dyn Future<Output = Result<(CacheEntry, usize)>> + Send + 'a>>,
_codec: Option<CacheCodec>,
) -> Result<(CacheEntry, bool)> {
// Track whether the loader actually ran (= cache miss).
let was_miss = Arc::new(AtomicBool::new(false));
let was_miss_clone = was_miss.clone();
let init = async move {
was_miss_clone.store(true, Ordering::Relaxed);
loader
.await
.map(|(entry, size_bytes)| MokaCacheEntry { entry, size_bytes })
.map_err(CloneableError)
};
let owned_key = *key;
match self.cache.try_get_with(owned_key, init).await {
Ok(record) => {
let was_cached = !was_miss.load(Ordering::Relaxed);
Ok((record.entry, was_cached))
}
Err(error) => Err(Arc::unwrap_or_clone(error).0),
}
}
async fn clear(&self) {
self.cache.invalidate_all();
self.cache.run_pending_tasks().await;
}
async fn num_entries(&self) -> usize {
self.cache.run_pending_tasks().await;
self.cache.entry_count() as usize
}
async fn size_bytes(&self) -> usize {
self.cache.run_pending_tasks().await;
self.weighted_size_bytes()
}
fn approx_num_entries(&self) -> usize {
self.cache.entry_count() as usize
}
fn approx_size_bytes(&self) -> usize {
// `weighted_size()` can be stale without `run_pending_tasks()`, which
// is async and can't be called from this synchronous context.
self.weighted_size_bytes()
}
fn deep_size_of_entries(
&self,
context: &mut Context,
size_of_entry: &dyn Fn(&CacheEntry, &mut Context) -> Option<usize>,
) -> Option<usize> {
Some(
self.cache
.iter()
.map(|(key, record)| {
key_footprint(key.as_ref())
+ size_of_entry(&record.entry, context).unwrap_or(record.size_bytes)
})
.sum(),
)
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn entry_weights_are_exact_at_byte_granularity() {
let key = InternalCacheKey::from_bytes([0; 16]);
assert_eq!(weight_unit(4096), 1);
assert_eq!(entry_weight(&key, 7, 1), 23);
}
#[tokio::test]
async fn size_methods_use_constant_time_weighted_accounting() {
let backend = MokaCacheBackend::with_capacity(4096);
let key = InternalCacheKey::from_bytes([0; 16]);
let entry: CacheEntry = Arc::new(());
let value_size = 7;
let expected = physical_size(&key, value_size);
backend.insert(&key, entry, value_size, None).await;
assert_eq!(backend.size_bytes().await, expected);
assert_eq!(backend.approx_size_bytes(), expected);
}
#[cfg(target_pointer_width = "64")]
#[test]
fn entry_weights_scale_for_capacities_above_four_gibibytes() {
let key = InternalCacheKey::from_bytes([0; 16]);
let capacity = 6 * 1024 * 1024 * 1024;
let weight_unit = weight_unit(capacity);
assert_eq!(weight_unit, 2);
let size_bytes = u32::MAX as usize + 1024;
let expected = physical_size(&key, size_bytes).div_ceil(weight_unit);
let weight = entry_weight(&key, size_bytes, weight_unit);
assert_eq!(weight as usize, expected);
assert_ne!(weight, u32::MAX);
}
}
/// Registry identifier for the built-in Moka backend.
pub const MOKA_BACKEND_KIND: &str = "moka";
/// [`BackendBuildFn`](super::registry::BackendBuildFn) for [`MokaCacheBackend`].
///
/// Recognized options:
/// * `capacity` — total weighted capacity in bytes (`usize`).
/// This must be present and non-empty.
///
/// Unknown options are rejected so typos surface immediately instead of
/// silently falling through to the default capacity.
pub(super) fn build_moka_backend(
config: &super::registry::BackendConfig,
) -> Result<MokaCacheBackend> {
let mut capacity: Option<usize> = None;
for (key, value) in &config.options {
match key.as_str() {
"capacity" => {
if value.is_empty() {
return Err(crate::Error::invalid_input(
"moka cache backend: capacity must not be empty",
));
} else {
capacity = Some(value.parse::<usize>().map_err(|err| {
crate::Error::invalid_input(format!(
"moka cache backend: cannot parse capacity {:?}: {}",
value, err
))
})?);
}
}
other => {
return Err(crate::Error::invalid_input(format!(
"moka cache backend: unknown option {:?}",
other
)));
}
}
}
let capacity = capacity.ok_or_else(|| {
crate::Error::invalid_input(
"moka cache backend: capacity is required; use moka://?capacity=<bytes>",
)
})?;
Ok(MokaCacheBackend::with_capacity(capacity))
}
pub(super) fn build_moka(config: &super::registry::BackendConfig) -> Result<Arc<dyn CacheBackend>> {
Ok(Arc::new(build_moka_backend(config)?))
}
#[cfg(test)]
mod moka_registry_tests {
use super::super::backend_uri::{build_from_uri, parse_backend_uri};
use super::super::registry::{BackendConfig, build_from_config, registry_test_lock};
use super::*;
#[test]
fn test_moka_builds_from_config() {
let _lock = registry_test_lock();
let cfg = BackendConfig::new("moka")
.unwrap()
.with_option("capacity", "1048576");
let backend = build_moka_backend(&cfg).unwrap();
assert_eq!(backend.capacity(), 1048576);
let _backend = build_from_config(&cfg).unwrap();
}
#[test]
fn test_moka_builds_from_uri() {
let _lock = registry_test_lock();
let cfg = parse_backend_uri("moka://?capacity=1048576").unwrap();
let backend = build_moka_backend(&cfg).unwrap();
assert_eq!(backend.capacity(), 1048576);
let _backend = build_from_uri("moka://?capacity=1048576").unwrap();
}
#[test]
fn test_moka_rejects_unknown_option() {
let _lock = registry_test_lock();
let cfg = BackendConfig::new("moka")
.unwrap()
.with_option("mystery", "1");
let err = build_from_config(&cfg).unwrap_err();
assert!(err.to_string().contains("unknown option"));
}
#[test]
fn test_moka_rejects_bad_capacity() {
let _lock = registry_test_lock();
let cfg = BackendConfig::new("moka")
.unwrap()
.with_option("capacity", "not-a-number");
let err = build_from_config(&cfg).unwrap_err();
assert!(err.to_string().contains("cannot parse capacity"));
}
#[test]
fn test_moka_rejects_missing_capacity() {
let _lock = registry_test_lock();
let cfg = BackendConfig::new("moka").unwrap();
let err = build_from_config(&cfg).unwrap_err();
assert!(err.to_string().contains("capacity is required"));
}
#[test]
fn test_moka_rejects_empty_capacity() {
let _lock = registry_test_lock();
let cfg = BackendConfig::new("moka")
.unwrap()
.with_option("capacity", "");
let err = build_from_config(&cfg).unwrap_err();
assert!(err.to_string().contains("capacity must not be empty"));
}
}
lance-artifact/rust/lance-core/src/cache/quick.rs
Vendored
+298
View File
@@ -0,0 +1,298 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright The Lance Authors
//! [`CacheBackend`] backed by [quick_cache](https://crates.io/crates/quick_cache),
//! whose hit path is one atomic bit — no read-op channel or inline
//! housekeeping. Used for the session index and metadata caches; the index
//! cache sees thousands of cache reads per query.
use std::pin::Pin;
use async_trait::async_trait;
use futures::Future;
use super::backend::{CacheBackend, CacheEntry};
use super::moka::key_footprint;
use super::{CacheCodec, InternalCacheKey};
use crate::Result;
use crate::deepsize::Context;
#[derive(Clone)]
struct QuickEntry {
entry: CacheEntry,
size_bytes: usize,
}
#[derive(Clone)]
struct EntryWeighter;
impl quick_cache::Weighter<InternalCacheKey, QuickEntry> for EntryWeighter {
fn weight(&self, key: &InternalCacheKey, value: &QuickEntry) -> u64 {
// Same accounting as the moka backend.
key_footprint(key).saturating_add(value.size_bytes).max(1) as u64
}
}
pub struct QuickCacheBackend {
cache: quick_cache::sync::Cache<InternalCacheKey, QuickEntry, EntryWeighter>,
}
impl std::fmt::Debug for QuickCacheBackend {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.debug_struct("QuickCacheBackend")
.field("entry_count", &self.cache.len())
.finish()
}
}
/// Minimum weight budget (4 GiB) per shard: shards don't borrow capacity, and
/// an entry heavier than ~its shard's budget is silently refused admission.
const MIN_SHARD_SHARE: usize = 4 << 30;
/// Recommended shard count: `min(cpus / 2, capacity / 4 GiB)`, power of two
/// in `[1, 1024]`. The cpu term bounds lock contention; the capacity term
/// keeps each shard's budget >= 4 GiB so large entries stay admissible.
/// Rounded down because quick_cache rounds requests up.
pub fn recommended_cache_shards(capacity: usize) -> usize {
let by_cpu = std::thread::available_parallelism()
.map(|n| n.get())
.unwrap_or(2)
/ 2;
let shards = (capacity / MIN_SHARD_SHARE).min(by_cpu).max(1);
let shards = if shards.is_power_of_two() {
shards
} else {
shards.next_power_of_two() / 2
};
shards.clamp(1, 1024)
}
/// Assumed average entry size for pre-allocation sizing.
const ESTIMATED_AVG_ENTRY_BYTES: usize = 64 << 10;
impl QuickCacheBackend {
/// Create a backend holding up to `capacity` bytes of weighted entries
/// (weight = key footprint + declared size), sharded per
/// [`recommended_cache_shards`].
pub fn with_capacity(capacity: usize) -> Self {
let shards = recommended_cache_shards(capacity);
// Floor protects the shard count from quick_cache's items-per-shard
// heuristic; ceiling bounds pre-allocation.
let estimated_items = (capacity / ESTIMATED_AVG_ENTRY_BYTES).clamp(shards * 32, 1_000_000);
let options = quick_cache::OptionsBuilder::new()
.estimated_items_capacity(estimated_items)
.weight_capacity(capacity as u64)
.shards(shards)
.build()
// Only errors when weight/item capacity is missing; both are set.
.expect("quick_cache options");
let cache = quick_cache::sync::Cache::with_options(
options,
EntryWeighter,
Default::default(),
Default::default(),
);
Self { cache }
}
}
#[async_trait]
impl CacheBackend for QuickCacheBackend {
async fn get(&self, key: &InternalCacheKey, _codec: Option<CacheCodec>) -> Option<CacheEntry> {
self.cache.get(key).map(|v| v.entry)
}
async fn insert(
&self,
key: &InternalCacheKey,
entry: CacheEntry,
size_bytes: usize,
_codec: Option<CacheCodec>,
) {
self.cache.insert(*key, QuickEntry { entry, size_bytes });
}
async fn get_or_insert<'a>(
&self,
key: &InternalCacheKey,
loader: Pin<Box<dyn Future<Output = Result<(CacheEntry, usize)>> + Send + 'a>>,
_codec: Option<CacheCodec>,
) -> Result<(CacheEntry, bool)> {
match self.cache.get_value_or_guard_async(key).await {
Ok(value) => Ok((value.entry, true)),
Err(guard) => {
let (entry, size_bytes) = loader.await?;
let _ = guard.insert(QuickEntry {
entry: entry.clone(),
size_bytes,
});
Ok((entry, false))
}
}
}
async fn clear(&self) {
self.cache.clear();
}
async fn num_entries(&self) -> usize {
self.cache.len()
}
async fn size_bytes(&self) -> usize {
self.cache.weight() as usize
}
fn approx_num_entries(&self) -> usize {
self.cache.len()
}
fn approx_size_bytes(&self) -> usize {
self.cache.weight() as usize
}
fn deep_size_of_entries(
&self,
context: &mut Context,
size_of_entry: &dyn Fn(&CacheEntry, &mut Context) -> Option<usize>,
) -> Option<usize> {
Some(
self.cache
.iter()
.map(|(key, record)| {
key_footprint(&key)
+ size_of_entry(&record.entry, context).unwrap_or(record.size_bytes)
})
.sum(),
)
}
}
#[cfg(test)]
mod tests {
use std::marker::PhantomData;
use std::sync::Arc;
use std::sync::atomic::{AtomicUsize, Ordering};
use super::*;
use crate::cache::{CacheKey, LanceCache};
struct TestKey<T: 'static> {
key: String,
_phantom: PhantomData<T>,
}
impl<T: 'static> TestKey<T> {
fn new(key: &str) -> Self {
Self {
key: key.to_string(),
_phantom: PhantomData,
}
}
}
impl<T: 'static> CacheKey for TestKey<T> {
type ValueType = T;
fn key(&self) -> std::borrow::Cow<'_, str> {
std::borrow::Cow::Borrowed(&self.key)
}
fn type_name() -> &'static str {
std::any::type_name::<T>()
}
}
#[test]
fn entry_weight_includes_fixed_key() {
let key = InternalCacheKey::from_bytes([0; 16]);
let entry = QuickEntry {
entry: Arc::new(()),
size_bytes: 7,
};
assert_eq!(
quick_cache::Weighter::weight(&EntryWeighter, &key, &entry),
23
);
}
#[tokio::test]
async fn test_quick_backend_roundtrip_singleflight_and_eviction() {
// Capacity must be large relative to one entry: quick_cache shards
// its weight budget, and an entry heavier than its shard's share is
// not admitted at all.
const CAPACITY: usize = 1 << 20;
let item = Arc::new(vec![1u8, 2, 3]);
let cache = LanceCache::with_backend(Arc::new(QuickCacheBackend::with_capacity(CAPACITY)));
// insert + get roundtrip and weighted accounting
cache
.insert_with_key(&TestKey::<Vec<u8>>::new("a"), item.clone())
.await;
assert_eq!(
cache
.get_with_key(&TestKey::<Vec<u8>>::new("a"))
.await
.as_deref(),
Some(&vec![1u8, 2, 3])
);
assert_eq!(cache.approx_size(), 1);
assert!(cache.size_bytes().await > 0);
// get_or_insert runs the loader only on a miss
let loads = Arc::new(AtomicUsize::new(0));
for _ in 0..2 {
let loads = loads.clone();
let value = cache
.get_or_insert_with_key(TestKey::<Vec<u8>>::new("b"), || async move {
loads.fetch_add(1, Ordering::SeqCst);
Ok(vec![7u8])
})
.await
.unwrap();
assert_eq!(value.as_ref(), &vec![7u8]);
}
assert_eq!(loads.load(Ordering::SeqCst), 1);
// capacity is enforced: overfill with 4x capacity of 16KiB entries
// and confirm eviction kept the weighted size within budget
for i in 0..256 {
cache
.insert_with_key(
&TestKey::<Vec<u8>>::new(&format!("fill-{i}")),
Arc::new(vec![0u8; 16 << 10]),
)
.await;
}
assert!(cache.size_bytes().await <= CAPACITY);
assert!(cache.size().await < 258);
cache.clear().await;
assert_eq!(cache.size().await, 0);
}
#[tokio::test]
async fn test_quick_backend_tiny_capacity() {
// A tiny cache must not over-provision item metadata and must still
// admit and evict correctly within its weight budget.
const CAPACITY: usize = 64 << 10;
let cache = LanceCache::with_backend(Arc::new(QuickCacheBackend::with_capacity(CAPACITY)));
for i in 0..64 {
cache
.insert_with_key(
&TestKey::<Vec<u8>>::new(&format!("k-{i}")),
Arc::new(vec![0u8; 4 << 10]),
)
.await;
}
assert!(cache.size_bytes().await <= CAPACITY);
assert!(cache.size().await >= 1);
let hit = cache
.get_with_key(&TestKey::<Vec<u8>>::new("k-63"))
.await
.is_some()
|| cache
.get_with_key(&TestKey::<Vec<u8>>::new("k-62"))
.await
.is_some();
assert!(hit, "recently inserted entries should be resident");
}
}
lance-artifact/rust/lance-core/src/cache/registry.rs
Vendored
+364
View File
@@ -0,0 +1,364 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright The Lance Authors
//! Pluggable cache-backend registry.
//!
//! A [`BackendConfig`] identifies which backend to build (`kind`) and carries
//! backend-specific string options. Backends are constructed through a
//! [`BackendBuildFn`] registered under a unique `kind`. Third-party crates
//! integrate by calling [`register_backend`] once at application startup;
//! [`build_from_config`] then locates the constructor and hands it the
//! config.
//!
//! The registry uses `HashMap<String, String>` for options so it can be
//! represented naturally across FFI (Python `dict[str, str]`, Java
//! `Map<String, String>`, etc.).
use std::collections::HashMap;
use std::sync::{Arc, Mutex, MutexGuard, OnceLock};
use super::backend::CacheBackend;
use super::moka::{MOKA_BACKEND_KIND, build_moka};
use crate::{Error, Result};
/// Backend-independent configuration passed to a [`BackendBuildFn`].
///
/// `kind` selects which registered backend to construct; `options` carries
/// backend-specific key/value settings (e.g. `capacity`, `path`).
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct BackendConfig {
/// Registered backend identifier, e.g. `"moka"`.
pub kind: String,
/// Backend-specific string options.
pub options: HashMap<String, String>,
}
impl BackendConfig {
/// Build a config with no options.
pub fn new(kind: impl AsRef<str>) -> Result<Self> {
Ok(Self {
kind: normalize_backend_kind(kind.as_ref())?,
options: HashMap::new(),
})
}
/// Insert a single option and return `self`, enabling chaining.
pub fn with_option(mut self, key: impl Into<String>, value: impl Into<String>) -> Self {
self.options.insert(key.into(), value.into());
self
}
}
/// Normalize and validate a cache backend kind.
///
/// Backend kinds share the same syntax as URI schemes. They are matched
/// case-insensitively and stored as lowercase ASCII so registry lookups,
/// config dictionaries, and URI parsing all address the same key.
pub fn normalize_backend_kind(kind: &str) -> Result<String> {
let mut chars = kind.chars();
match chars.next() {
Some(c) if c.is_ascii_alphabetic() => {}
_ => {
return Err(Error::invalid_input(format!(
"cache backend kind {:?}: must start with an ASCII letter",
kind
)));
}
}
for c in chars {
let ok = c.is_ascii_alphanumeric() || matches!(c, '+' | '-' | '.');
if !ok {
return Err(Error::invalid_input(format!(
"cache backend kind {:?}: invalid character {:?}",
kind, c
)));
}
}
Ok(kind.to_ascii_lowercase())
}
/// Constructor signature for a cache backend.
///
/// Constructors are synchronous. Backends that need async initialization
/// should surface a `try_new_blocking` shim (or equivalent) and call it here.
pub type BackendBuildFn = fn(&BackendConfig) -> Result<Arc<dyn CacheBackend>>;
fn registry() -> &'static Mutex<HashMap<String, BackendBuildFn>> {
static REGISTRY: OnceLock<Mutex<HashMap<String, BackendBuildFn>>> = OnceLock::new();
REGISTRY.get_or_init(|| Mutex::new(HashMap::new()))
}
fn registry_lock() -> Result<MutexGuard<'static, HashMap<String, BackendBuildFn>>> {
registry()
.lock()
.map_err(|_| Error::internal("cache backend registry mutex is poisoned"))
}
#[cfg(test)]
fn registry_lock_for_test() -> MutexGuard<'static, HashMap<String, BackendBuildFn>> {
registry()
.lock()
.unwrap_or_else(|poisoned| poisoned.into_inner())
}
/// Register a constructor for a cache backend under `kind`.
///
/// Returns `Err` if a non-built-in `kind` is already registered. Built-in
/// backends may be replaced so callers can mask a built-in implementation
/// (for example, a patched `"moka"` backend) without changing URI/config
/// strings elsewhere.
///
/// Typical usage from a backend crate:
///
/// ```ignore
/// pub fn register() -> lance_core::Result<()> {
/// lance_core::cache::register_backend("my_backend", build_my_backend)
/// }
/// ```
pub fn register_backend(kind: &str, build: BackendBuildFn) -> Result<()> {
let kind = normalize_backend_kind(kind)?;
insert_backend(&kind, build, builtin_backend(&kind).is_some())
}
fn insert_backend(kind: &str, build: BackendBuildFn, allow_replace: bool) -> Result<()> {
let mut map = registry_lock()?;
if map.contains_key(kind) && !allow_replace {
return Err(Error::invalid_input(format!(
"cache backend {:?} is already registered",
kind
)));
}
map.insert(kind.to_string(), build);
Ok(())
}
fn builtin_backend(kind: &str) -> Option<BackendBuildFn> {
match kind {
MOKA_BACKEND_KIND => Some(build_moka),
_ => None,
}
}
/// Look up the constructor for `config.kind` and build a backend.
///
/// Returns `Err` if no backend has been registered under that identifier.
pub fn build_from_config(config: &BackendConfig) -> Result<Arc<dyn CacheBackend>> {
ensure_builtin_backends()?;
let kind = normalize_backend_kind(&config.kind)?;
let config = BackendConfig {
kind: kind.clone(),
options: config.options.clone(),
};
let build = {
let map = registry_lock()?;
map.get(&kind).copied()
};
match build {
Some(build) => build(&config),
None => Err(Error::invalid_input(format!(
"unknown cache backend kind: {:?}",
kind
))),
}
}
/// Idempotently register the backends that ship with `lance-core`.
///
/// Called by [`build_from_config`] (and, transitively, by
/// [`build_from_uri`](super::backend_uri::build_from_uri)) so a bare Lance
/// installation can build a Moka backend without the caller having to
/// register it. Third-party backends still have to opt in with their own
/// `register()` call.
///
/// The check is against the current registry contents rather than a
/// process-once flag so that `#[cfg(test)]` helpers which snapshot and
/// restore the registry still see the built-in backend after they take
/// ownership.
fn ensure_builtin_backends() -> Result<()> {
let mut map = registry_lock()?;
if !map.contains_key(MOKA_BACKEND_KIND)
&& let Some(build) = builtin_backend(MOKA_BACKEND_KIND)
{
map.insert(MOKA_BACKEND_KIND.to_string(), build);
}
Ok(())
}
/// Test-only helper: replace the registry with an empty map so tests can
/// exercise duplicate-registration logic without polluting the global one.
#[cfg(test)]
pub(super) fn take_registry_for_test() -> HashMap<String, BackendBuildFn> {
let mut map = registry_lock_for_test();
std::mem::take(&mut *map)
}
/// Test-only helper: restore a previously captured registry state.
#[cfg(test)]
pub(super) fn restore_registry_for_test(saved: HashMap<String, BackendBuildFn>) {
let mut map = registry_lock_for_test();
*map = saved;
}
#[cfg(test)]
pub(super) fn registry_test_lock() -> std::sync::MutexGuard<'static, ()> {
static M: OnceLock<std::sync::Mutex<()>> = OnceLock::new();
M.get_or_init(|| std::sync::Mutex::new(()))
.lock()
.unwrap_or_else(|poisoned| poisoned.into_inner())
}
#[cfg(test)]
mod tests {
use super::*;
use async_trait::async_trait;
use std::pin::Pin;
use crate::cache::InternalCacheKey;
use crate::cache::backend::CacheEntry;
use crate::cache::codec::CacheCodec;
use futures::Future;
// A trivial no-op backend so tests do not depend on Moka or any other
// real backend. Every method returns "empty" / does nothing.
#[derive(Debug, Default)]
struct NullBackend;
#[async_trait]
impl CacheBackend for NullBackend {
async fn get(
&self,
_key: &InternalCacheKey,
_codec: Option<CacheCodec>,
) -> Option<CacheEntry> {
None
}
async fn insert(
&self,
_key: &InternalCacheKey,
_entry: CacheEntry,
_size_bytes: usize,
_codec: Option<CacheCodec>,
) {
}
async fn get_or_insert<'a>(
&self,
_key: &InternalCacheKey,
loader: Pin<Box<dyn Future<Output = crate::Result<(CacheEntry, usize)>> + Send + 'a>>,
_codec: Option<CacheCodec>,
) -> crate::Result<(CacheEntry, bool)> {
let (entry, _size) = loader.await?;
Ok((entry, false))
}
async fn clear(&self) {}
async fn num_entries(&self) -> usize {
0
}
async fn size_bytes(&self) -> usize {
0
}
}
fn build_null(_cfg: &BackendConfig) -> Result<Arc<dyn CacheBackend>> {
Ok(Arc::new(NullBackend))
}
struct RegistryGuard {
// Hold the serialization lock for the full test.
_lock: std::sync::MutexGuard<'static, ()>,
saved: HashMap<String, BackendBuildFn>,
}
impl RegistryGuard {
fn new() -> Self {
Self {
_lock: registry_test_lock(),
saved: take_registry_for_test(),
}
}
}
impl Drop for RegistryGuard {
fn drop(&mut self) {
restore_registry_for_test(std::mem::take(&mut self.saved));
}
}
#[test]
fn test_register_and_build() {
let _guard = RegistryGuard::new();
register_backend("null", build_null).unwrap();
let backend = build_from_config(&BackendConfig::new("null").unwrap()).unwrap();
// Backend is opaque; we just check that the constructor ran and
// gave us an Arc<dyn CacheBackend>.
assert_eq!(Arc::strong_count(&backend), 1);
}
#[test]
fn test_duplicate_registration_errors() {
let _guard = RegistryGuard::new();
register_backend("dup", build_null).unwrap();
let err = register_backend("dup", build_null).unwrap_err();
assert!(err.to_string().contains("already registered"));
}
#[test]
fn test_builtin_kind_can_be_overridden() {
let _guard = RegistryGuard::new();
register_backend("moka", build_null).unwrap();
let backend = build_from_config(&BackendConfig::new("moka").unwrap()).unwrap();
assert_eq!(Arc::strong_count(&backend), 1);
}
#[test]
fn test_unknown_kind_errors() {
let _guard = RegistryGuard::new();
let err = build_from_config(&BackendConfig::new("missing").unwrap()).unwrap_err();
assert!(err.to_string().contains("unknown cache backend kind"));
}
#[test]
fn test_backend_kind_is_normalized() {
let _guard = RegistryGuard::new();
register_backend("Echo.Backend", build_null).unwrap();
let backend = build_from_config(&BackendConfig::new("echo.backend").unwrap()).unwrap();
assert_eq!(Arc::strong_count(&backend), 1);
}
#[test]
fn test_config_lookup_normalizes_direct_config() {
let _guard = RegistryGuard::new();
fn build_echo(cfg: &BackendConfig) -> Result<Arc<dyn CacheBackend>> {
assert_eq!(cfg.kind, "echo.backend");
Ok(Arc::new(NullBackend))
}
register_backend("echo.backend", build_echo).unwrap();
let cfg = BackendConfig {
kind: "ECHO.Backend".to_string(),
options: HashMap::new(),
};
build_from_config(&cfg).unwrap();
}
#[test]
fn test_invalid_backend_kind_errors() {
let err = register_backend("not a scheme", build_null).unwrap_err();
assert!(err.to_string().contains("invalid character"));
let err = BackendConfig::new("1moka").unwrap_err();
assert!(err.to_string().contains("must start with an ASCII letter"));
}
#[test]
fn test_options_are_passed_through() {
let _guard = RegistryGuard::new();
fn build_echo(cfg: &BackendConfig) -> Result<Arc<dyn CacheBackend>> {
assert_eq!(cfg.options.get("capacity").map(String::as_str), Some("42"));
Ok(Arc::new(NullBackend))
}
register_backend("echo", build_echo).unwrap();
let cfg = BackendConfig::new("echo")
.unwrap()
.with_option("capacity", "42");
build_from_config(&cfg).unwrap();
}
}
lance-artifact/rust/lance-core/src/container.rs
+4
View File
@@ -0,0 +1,4 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright The Lance Authors
pub mod list;
lance-artifact/rust/lance-core/src/container/list.rs
+306
View File
@@ -0,0 +1,306 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright The Lance Authors
use std::collections::LinkedList;
use crate::deepsize::DeepSizeOf;
/// A linked list that grows exponentially. It is used to store a large number of
/// elements in a memory-efficient way. The list grows by doubling the capacity of
/// the last element when it's full, the capacity can be limited by the `limit`
/// parameter. The default value is 0, which means no limit.
#[derive(Debug, Clone, Default)]
pub struct ExpLinkedList<T> {
inner: LinkedList<Vec<T>>,
len: usize,
// The maximum capacity of single node in the list.
// If the limit is 0, there is no limit.
// We use u16 to save memory because ExpLinkedList should not
// be used if the limit is that large.
limit: u16,
}
impl<T> ExpLinkedList<T> {
/// Creates a new empty `ExpLinkedList`.
pub fn new() -> Self {
Self {
inner: LinkedList::new(),
len: 0,
limit: 0,
}
}
pub fn with_capacity(capacity: usize) -> Self {
let mut inner = LinkedList::new();
inner.push_back(Vec::with_capacity(capacity));
Self {
inner,
len: 0,
limit: 0,
}
}
/// Creates a new `ExpLinkedList` with a specified capacity limit.
/// The limit is the maximum capacity of a single node in the list.
/// If the limit is 0, there is no limit.
pub fn with_capacity_limit(mut self, limit: u16) -> Self {
self.limit = limit;
self
}
/// Pushes a new element into the list. If the last element in the list
/// reaches its capacity, a new node is created with double capacity.
pub fn push(&mut self, v: T) {
match self.inner.back() {
Some(last) => {
if last.len() == last.capacity() {
let new_cap = if self.limit > 0 && last.capacity() * 2 >= self.limit as usize {
self.limit as usize
} else {
last.capacity() * 2
};
self.inner.push_back(Vec::with_capacity(new_cap));
}
}
None => {
self.inner.push_back(Vec::with_capacity(1));
}
}
self.do_push(v);
}
fn do_push(&mut self, v: T) {
self.inner.back_mut().unwrap().push(v);
self.len += 1;
}
/// Removes the last element from the list.
pub fn pop(&mut self) -> Option<T> {
match self.inner.back_mut() {
Some(last) => {
if last.is_empty() {
self.inner.pop_back();
self.pop()
} else {
self.len -= 1;
last.pop()
}
}
None => None,
}
}
/// Clears the list, removing all elements.
/// This will free the memory used by the list.
pub fn clear(&mut self) {
self.inner.clear();
self.len = 0;
}
/// Returns the number of elements in the list.
pub fn len(&self) -> usize {
self.len
}
/// Returns whether the list is empty.
pub fn is_empty(&self) -> bool {
self.inner.is_empty()
}
/// Returns the size of list, including the size of the elements and the
/// size of the list itself, and the unused space.
/// The element size is calculated using `std::mem::size_of::<T>()`,
/// so it is not accurate for all types.
/// For example, for `String`, it will return the size of the pointer,
/// not the size of the string itself. For that you need to use `DeepSizeOf`.
pub fn size(&self) -> usize {
let unused_space = match self.inner.back() {
Some(last) => last.capacity() - last.len(),
None => 0,
};
(self.len() + unused_space) * std::mem::size_of::<T>()
+ std::mem::size_of::<Self>()
+ self.inner.len() * std::mem::size_of::<Vec<T>>()
}
/// Returns an iterator over the elements in the list.
pub fn iter(&self) -> ExpLinkedListIter<'_, T> {
ExpLinkedListIter::new(self)
}
pub fn block_iter(&self) -> impl Iterator<Item = &[T]> {
self.inner.iter().map(|v| v.as_slice())
}
}
impl<T: DeepSizeOf> DeepSizeOf for ExpLinkedList<T> {
fn deep_size_of_children(&self, context: &mut crate::deepsize::Context) -> usize {
self.inner
.iter()
.map(|v| v.deep_size_of_children(context))
.sum()
}
}
impl<T> FromIterator<T> for ExpLinkedList<T> {
fn from_iter<I: IntoIterator<Item = T>>(iter: I) -> Self {
let iter = iter.into_iter();
let size_hint = iter.size_hint().0;
let cap = if size_hint > 0 { size_hint } else { 1 };
let mut list = Self::with_capacity(cap);
for item in iter {
list.push(item);
}
list
}
}
impl<T> PartialEq for ExpLinkedList<T>
where
T: PartialEq,
{
fn eq(&self, other: &Self) -> bool {
self.iter().zip(other.iter()).all(|(a, b)| a == b)
}
}
impl<T> Eq for ExpLinkedList<T> where T: Eq {}
pub struct ExpLinkedListIter<'a, T> {
inner: std::collections::linked_list::Iter<'a, Vec<T>>,
inner_iter: Option<std::slice::Iter<'a, T>>,
len: usize,
}
impl<'a, T> ExpLinkedListIter<'a, T> {
pub fn new(inner: &'a ExpLinkedList<T>) -> Self {
Self {
inner: inner.inner.iter(),
inner_iter: None,
len: inner.len(),
}
}
}
impl<'a, T> Iterator for ExpLinkedListIter<'a, T> {
type Item = &'a T;
fn next(&mut self) -> Option<Self::Item> {
if let Some(inner_iter) = &mut self.inner_iter
&& let Some(v) = inner_iter.next()
{
return Some(v);
}
if let Some(inner) = self.inner.next() {
self.inner_iter = Some(inner.iter());
return self.next();
}
None
}
fn size_hint(&self) -> (usize, Option<usize>) {
(self.len, Some(self.len))
}
}
pub struct ExpLinkedListIntoIter<T> {
inner: std::collections::linked_list::IntoIter<Vec<T>>,
inner_iter: Option<std::vec::IntoIter<T>>,
len: usize,
}
impl<T> ExpLinkedListIntoIter<T> {
pub fn new(list: ExpLinkedList<T>) -> Self {
let len = list.len();
Self {
inner: list.inner.into_iter(),
inner_iter: None,
len,
}
}
}
impl<T> Iterator for ExpLinkedListIntoIter<T> {
type Item = T;
fn next(&mut self) -> Option<Self::Item> {
if let Some(inner_iter) = &mut self.inner_iter
&& let Some(v) = inner_iter.next()
{
return Some(v);
}
if let Some(inner) = self.inner.next() {
self.inner_iter = Some(inner.into_iter());
return self.next();
}
None
}
fn size_hint(&self) -> (usize, Option<usize>) {
(self.len, Some(self.len))
}
}
impl<T> IntoIterator for ExpLinkedList<T> {
type Item = T;
type IntoIter = ExpLinkedListIntoIter<T>;
fn into_iter(self) -> Self::IntoIter {
ExpLinkedListIntoIter::new(self)
}
}
#[cfg(test)]
mod tests {
use super::*;
fn test_exp_linked_list(list: &mut ExpLinkedList<usize>) {
assert_eq!(list.len(), 100);
assert!(!list.is_empty());
// removes the last 50 elements
for i in 0..50 {
assert_eq!(list.pop(), Some(99 - i));
}
assert_eq!(list.len(), 50);
assert!(!list.is_empty());
// iterate over the list
for (i, v) in list.iter().enumerate() {
assert_eq!(*v, i);
}
// clear the list
list.clear();
assert_eq!(list.len(), 0);
assert!(list.is_empty());
assert_eq!(list.pop(), None);
}
#[test]
fn test_exp_linked_list_basic() {
let mut list = ExpLinkedList::new();
for i in 0..100 {
list.push(i);
assert_eq!(list.len(), i + 1);
}
test_exp_linked_list(&mut list);
}
#[test]
fn test_exp_linked_list_from() {
let mut list = (0..100).collect();
test_exp_linked_list(&mut list);
}
#[test]
fn test_exp_linked_list_with_capacity_limit() {
let mut list = ExpLinkedList::new().with_capacity_limit(10);
for i in 0..100 {
list.push(i);
assert_eq!(list.len(), i + 1);
}
assert_eq!(list.inner.back().unwrap().capacity(), 10);
test_exp_linked_list(&mut list);
}
}
lance-artifact/rust/lance-core/src/datatypes.rs
+687
View File
@@ -0,0 +1,687 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright The Lance Authors
//! Lance data types, [Schema] and [Field]
use std::collections::HashMap;
use std::fmt::{self, Debug, Formatter};
use std::sync::{Arc, LazyLock};
use crate::deepsize::DeepSizeOf;
use arrow_array::ArrayRef;
use arrow_schema::{DataType, Field as ArrowField, Fields, TimeUnit};
use lance_arrow::bfloat16::{BFLOAT16_EXT_NAME, is_bfloat16_field};
use lance_arrow::{ARROW_EXT_META_KEY, ARROW_EXT_NAME_KEY};
mod field;
mod schema;
use crate::{Error, Result};
pub use field::{
BlobVersion, Encoding, Field, LANCE_UNENFORCED_CLUSTERING_KEY_POSITION,
LANCE_UNENFORCED_PRIMARY_KEY, LANCE_UNENFORCED_PRIMARY_KEY_POSITION, NullabilityComparison,
OnTypeMismatch, SchemaCompareOptions,
};
pub use schema::{
BlobHandling, FieldRef, OnMissing, Projectable, Projection, Schema,
escape_field_path_for_project, format_field_path, format_field_path_minimal, parse_field_path,
validate_fixed_size_list_dimensions,
};
pub static BLOB_DESC_FIELDS: LazyLock<Fields> = LazyLock::new(|| {
Fields::from(vec![
ArrowField::new("position", DataType::UInt64, true),
ArrowField::new("size", DataType::UInt64, true),
])
});
pub static BLOB_DESC_TYPE: LazyLock<DataType> =
LazyLock::new(|| DataType::Struct(BLOB_DESC_FIELDS.clone()));
pub static BLOB_DESC_FIELD: LazyLock<ArrowField> = LazyLock::new(|| {
ArrowField::new("description", BLOB_DESC_TYPE.clone(), true).with_metadata(HashMap::from([(
lance_arrow::BLOB_META_KEY.to_string(),
"true".to_string(),
)]))
});
pub static BLOB_DESC_LANCE_FIELD: LazyLock<Field> =
LazyLock::new(|| Field::try_from(&*BLOB_DESC_FIELD).unwrap());
/// The minimal logical blob v2 fields accepted from writers.
///
/// Logical values may also use [`BLOB_V2_LOGICAL_FIELDS`] when an external
/// object range is present.
pub static BLOB_V2_LOGICAL_MINIMAL_FIELDS: LazyLock<Fields> = LazyLock::new(|| {
Fields::from(vec![
ArrowField::new("data", DataType::LargeBinary, true),
ArrowField::new("uri", DataType::Utf8, true),
])
});
/// The complete logical blob v2 fields used for writer input and rewrite output.
///
/// `position` and `size` are an optional range within the external object named
/// by `uri`. They do not describe Lance-managed data, packed, or dedicated
/// storage.
pub static BLOB_V2_LOGICAL_FIELDS: LazyLock<Fields> = LazyLock::new(|| {
let mut fields = BLOB_V2_LOGICAL_MINIMAL_FIELDS
.iter()
.cloned()
.collect::<Vec<_>>();
fields.extend([
Arc::new(ArrowField::new("position", DataType::UInt64, true)),
Arc::new(ArrowField::new("size", DataType::UInt64, true)),
]);
Fields::from(fields)
});
/// The complete logical blob v2 struct type.
pub static BLOB_V2_LOGICAL_TYPE: LazyLock<DataType> =
LazyLock::new(|| DataType::Struct(BLOB_V2_LOGICAL_FIELDS.clone()));
/// Writer-prepared blob v2 fields consumed by the structural encoder.
///
/// The populated fields depend on [`BlobKind`]:
///
/// - [`BlobKind::Inline`] carries `data`; the encoder derives the stored
/// `position` and `size` from the out-of-line buffer it creates.
/// - [`BlobKind::Packed`] carries `blob_id`, `position`, and `blob_size`.
/// - [`BlobKind::Dedicated`] carries `blob_id` and `blob_size`; its stored
/// `position` is zero.
/// - [`BlobKind::External`] carries `uri`, optional `blob_id`, `position`, and
/// `blob_size`. A zero `blob_size` is resolved to the complete external object
/// length when read.
///
/// `blob_size` is distinct from the logical `size`, which is only an optional
/// external-object range before preparation. For external blobs, `uri` is
/// normalized into the stable stored `blob_uri` field.
pub static BLOB_V2_PREPARED_FIELDS: LazyLock<Fields> = LazyLock::new(|| {
Fields::from(vec![
ArrowField::new("kind", DataType::UInt8, true),
ArrowField::new("data", DataType::LargeBinary, true),
ArrowField::new("uri", DataType::Utf8, true),
ArrowField::new("blob_id", DataType::UInt32, true),
ArrowField::new("blob_size", DataType::UInt64, true),
ArrowField::new("position", DataType::UInt64, true),
])
});
/// The writer-prepared blob v2 struct type.
pub static BLOB_V2_PREPARED_TYPE: LazyLock<DataType> =
LazyLock::new(|| DataType::Struct(BLOB_V2_PREPARED_FIELDS.clone()));
/// Stored blob v2 descriptor fields.
///
/// These field names are part of the stable file format. Their meaning depends
/// on `kind`:
///
/// - [`BlobKind::Inline`]: `position` and `size` locate an out-of-line buffer in
/// the Lance data file.
/// - [`BlobKind::Packed`]: `blob_id` identifies a shared packed blob file, and
/// `position` and `size` locate a range within it.
/// - [`BlobKind::Dedicated`]: `blob_id` identifies a dedicated raw blob file,
/// `position` is zero, and `size` is the complete file length.
/// - [`BlobKind::External`]: `blob_uri` and `blob_id` identify the object, while
/// `position` and `size` select a range. A zero `size` is resolved to the
/// object's complete length when read.
pub static BLOB_V2_DESC_FIELDS: LazyLock<Fields> = LazyLock::new(|| {
Fields::from(vec![
ArrowField::new("kind", DataType::UInt8, false),
ArrowField::new("position", DataType::UInt64, false),
ArrowField::new("size", DataType::UInt64, false),
ArrowField::new("blob_id", DataType::UInt32, false),
ArrowField::new("blob_uri", DataType::Utf8, false),
])
});
pub static BLOB_V2_DESC_TYPE: LazyLock<DataType> =
LazyLock::new(|| DataType::Struct(BLOB_V2_DESC_FIELDS.clone()));
pub static BLOB_V2_DESC_FIELD: LazyLock<ArrowField> = LazyLock::new(|| {
ArrowField::new("description", BLOB_V2_DESC_TYPE.clone(), false).with_metadata(HashMap::from([
(lance_arrow::BLOB_META_KEY.to_string(), "true".to_string()),
("lance-encoding:packed".to_string(), "true".to_string()),
]))
});
pub static BLOB_V2_DESC_LANCE_FIELD: LazyLock<Field> =
LazyLock::new(|| Field::try_from(&*BLOB_V2_DESC_FIELD).unwrap());
/// The in-memory representation of a blob v2 struct.
#[non_exhaustive]
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum BlobV2Layout {
/// Writer input or rewrite output.
///
/// Both the minimal `data, uri` fields and the complete
/// `data, uri, position, size` fields have this layout.
Logical,
/// Kind-aware writer intermediate consumed by the structural encoder.
Prepared,
/// Stable descriptor stored in Lance files and returned by descriptor scans.
Descriptor,
}
impl BlobV2Layout {
/// Classify blob v2 child fields by name, type, order, and layout-specific
/// nullability requirements.
///
/// Child metadata is not part of the representation. The complete logical
/// layout also accepts non-nullable `position` and `size` fields, matching
/// the existing writer-input contract. Descriptor child nullability is
/// ignored because it changed across released schemas; row nullness has
/// been represented by either parent struct validity or a nullable `kind`
/// child.
pub fn classify(fields: &Fields) -> Option<Self> {
if logical_blob_v2_fields_match(fields) {
Some(Self::Logical)
} else if blob_v2_fields_match(fields, &BLOB_V2_PREPARED_FIELDS, true) {
Some(Self::Prepared)
} else if blob_v2_fields_match(fields, &BLOB_V2_DESC_FIELDS, false) {
Some(Self::Descriptor)
} else {
None
}
}
}
impl fmt::Display for BlobV2Layout {
fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
match self {
Self::Logical => write!(f, "logical"),
Self::Prepared => write!(f, "prepared"),
Self::Descriptor => write!(f, "descriptor"),
}
}
}
fn blob_v2_field_matches(
actual: &ArrowField,
expected: &ArrowField,
compare_nullability: bool,
) -> bool {
actual.name() == expected.name()
&& actual.data_type() == expected.data_type()
&& (!compare_nullability || actual.is_nullable() == expected.is_nullable())
}
fn blob_v2_fields_match(actual: &Fields, expected: &Fields, compare_nullability: bool) -> bool {
actual.len() == expected.len()
&& actual
.iter()
.zip(expected.iter())
.all(|(actual, expected)| {
blob_v2_field_matches(actual.as_ref(), expected.as_ref(), compare_nullability)
})
}
fn logical_blob_v2_fields_match(fields: &Fields) -> bool {
if blob_v2_fields_match(fields, &BLOB_V2_LOGICAL_MINIMAL_FIELDS, true) {
return true;
}
fields.len() == BLOB_V2_LOGICAL_FIELDS.len()
&& fields
.iter()
.zip(BLOB_V2_LOGICAL_FIELDS.iter())
.enumerate()
.all(|(index, (actual, expected))| {
blob_v2_field_matches(actual.as_ref(), expected.as_ref(), index < 2)
})
}
/// Deprecated name for [`BLOB_V2_LOGICAL_FIELDS`].
#[deprecated(note = "use BLOB_V2_LOGICAL_FIELDS")]
pub use self::BLOB_V2_LOGICAL_FIELDS as BLOB_V2_USER_FIELDS;
/// Deprecated name for [`BLOB_V2_LOGICAL_TYPE`].
#[deprecated(note = "use BLOB_V2_LOGICAL_TYPE")]
pub use self::BLOB_V2_LOGICAL_TYPE as BLOB_V2_USER_TYPE;
pub const BLOB_LOGICAL_TYPE: &str = "blob";
/// LogicalType is a string presentation of arrow type.
/// to be serialized into protobuf.
#[derive(Debug, Clone, PartialEq, DeepSizeOf)]
pub struct LogicalType(String);
impl fmt::Display for LogicalType {
fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
write!(f, "{}", self.0)
}
}
impl LogicalType {
fn is_list(&self) -> bool {
self.0 == "list" || self.0 == "list.struct"
}
fn is_large_list(&self) -> bool {
self.0 == "large_list" || self.0 == "large_list.struct"
}
fn is_fixed_size_list_struct(&self) -> bool {
self.0.starts_with("fixed_size_list:struct:")
}
pub fn is_struct(&self) -> bool {
self.0 == "struct"
}
fn is_blob(&self) -> bool {
self.0 == BLOB_LOGICAL_TYPE
}
fn is_map(&self) -> bool {
self.0 == "map"
}
}
impl From<&str> for LogicalType {
fn from(s: &str) -> Self {
Self(s.to_string())
}
}
fn timeunit_to_str(unit: &TimeUnit) -> &'static str {
match unit {
TimeUnit::Second => "s",
TimeUnit::Millisecond => "ms",
TimeUnit::Microsecond => "us",
TimeUnit::Nanosecond => "ns",
}
}
fn is_supported_fixed_size_list_child(data_type: &DataType, nested: bool) -> bool {
match data_type {
DataType::Struct(_) => !nested,
DataType::List(_) | DataType::LargeList(_) | DataType::Map(_, _) => false,
DataType::FixedSizeList(field, _) => {
is_supported_fixed_size_list_child(field.data_type(), true)
}
_ => true,
}
}
fn parse_timeunit(unit: &str) -> Result<TimeUnit> {
match unit {
"s" => Ok(TimeUnit::Second),
"ms" => Ok(TimeUnit::Millisecond),
"us" => Ok(TimeUnit::Microsecond),
"ns" => Ok(TimeUnit::Nanosecond),
_ => Err(Error::arrow(format!("Unsupported TimeUnit: {unit}"))),
}
}
impl TryFrom<&DataType> for LogicalType {
type Error = Error;
fn try_from(dt: &DataType) -> Result<Self> {
let type_str = match dt {
DataType::Null => "null".to_string(),
DataType::Boolean => "bool".to_string(),
DataType::Int8 => "int8".to_string(),
DataType::UInt8 => "uint8".to_string(),
DataType::Int16 => "int16".to_string(),
DataType::UInt16 => "uint16".to_string(),
DataType::Int32 => "int32".to_string(),
DataType::UInt32 => "uint32".to_string(),
DataType::Int64 => "int64".to_string(),
DataType::UInt64 => "uint64".to_string(),
DataType::Float16 => "halffloat".to_string(),
DataType::Float32 => "float".to_string(),
DataType::Float64 => "double".to_string(),
DataType::Decimal128(precision, scale) => format!("decimal:128:{precision}:{scale}"),
DataType::Decimal256(precision, scale) => format!("decimal:256:{precision}:{scale}"),
DataType::Utf8 | DataType::Utf8View => "string".to_string(),
DataType::Binary | DataType::BinaryView => "binary".to_string(),
DataType::LargeUtf8 => "large_string".to_string(),
DataType::LargeBinary => "large_binary".to_string(),
DataType::Date32 => "date32:day".to_string(),
DataType::Date64 => "date64:ms".to_string(),
DataType::Time32(tu) => format!("time32:{}", timeunit_to_str(tu)),
DataType::Time64(tu) => format!("time64:{}", timeunit_to_str(tu)),
DataType::Timestamp(tu, tz) => format!(
"timestamp:{}:{}",
timeunit_to_str(tu),
tz.as_ref()
.map(|v| v.to_string())
.unwrap_or("-".to_string())
),
DataType::Duration(tu) => format!("duration:{}", timeunit_to_str(tu)),
DataType::Struct(_) => "struct".to_string(),
DataType::Dictionary(key_type, value_type) => {
format!(
"dict:{}:{}:{}",
Self::try_from(value_type.as_ref())?.0,
Self::try_from(key_type.as_ref())?.0,
// Arrow C++ Dictionary has "ordered:bool" field, but it does not exist in `arrow-rs`.
false
)
}
DataType::List(elem) => match elem.data_type() {
DataType::Struct(_) => "list.struct".to_string(),
_ => "list".to_string(),
},
DataType::LargeList(elem) => match elem.data_type() {
DataType::Struct(_) => "large_list.struct".to_string(),
_ => "large_list".to_string(),
},
DataType::FixedSizeList(field, len) => {
if is_bfloat16_field(field) {
// Don't want to directly use `bfloat16`, in case a built-in type is added
// that isn't identical to our extension type.
format!("fixed_size_list:lance.bfloat16:{}", *len)
} else if !is_supported_fixed_size_list_child(field.data_type(), false) {
return Err(Error::schema(format!("Unsupported data type: {:?}", dt)));
} else {
format!(
"fixed_size_list:{}:{}",
Self::try_from(field.data_type())?.0,
*len
)
}
}
DataType::FixedSizeBinary(len) => format!("fixed_size_binary:{}", *len),
DataType::Map(_, keys_sorted) => {
// TODO: We only support keys_sorted=false for now,
// because converting a rust arrow map field to the python arrow field will
// lose the keys_sorted property.
if *keys_sorted {
return Err(Error::schema(format!(
"Unsupported map data type with keys_sorted=true: {:?}",
dt
)));
}
"map".to_string()
}
_ => {
return Err(Error::schema(format!("Unsupported data type: {:?}", dt)));
}
};
Ok(Self(type_str))
}
}
impl TryFrom<&LogicalType> for DataType {
type Error = Error;
fn try_from(lt: &LogicalType) -> Result<Self> {
use DataType::*;
if let Some(t) = match lt.0.as_str() {
"null" => Some(Null),
"bool" => Some(Boolean),
"int8" => Some(Int8),
"uint8" => Some(UInt8),
"int16" => Some(Int16),
"uint16" => Some(UInt16),
"int32" => Some(Int32),
"uint32" => Some(UInt32),
"int64" => Some(Int64),
"uint64" => Some(UInt64),
"halffloat" => Some(Float16),
"float" => Some(Float32),
"double" => Some(Float64),
"string" => Some(Utf8),
"binary" => Some(Binary),
"large_string" => Some(LargeUtf8),
"large_binary" => Some(LargeBinary),
BLOB_LOGICAL_TYPE => Some(LargeBinary),
"json" => Some(LargeBinary),
"date32:day" => Some(Date32),
"date64:ms" => Some(Date64),
"time32:s" => Some(Time32(TimeUnit::Second)),
"time32:ms" => Some(Time32(TimeUnit::Millisecond)),
"time64:us" => Some(Time64(TimeUnit::Microsecond)),
"time64:ns" => Some(Time64(TimeUnit::Nanosecond)),
"duration:s" => Some(Duration(TimeUnit::Second)),
"duration:ms" => Some(Duration(TimeUnit::Millisecond)),
"duration:us" => Some(Duration(TimeUnit::Microsecond)),
"duration:ns" => Some(Duration(TimeUnit::Nanosecond)),
_ => None,
} {
Ok(t)
} else {
let splits = lt.0.split(':').collect::<Vec<_>>();
match splits[0] {
"fixed_size_list" => {
if splits.len() < 3 {
return Err(Error::schema(format!("Unsupported logical type: {}", lt)));
}
let size: i32 = splits
.last()
.unwrap()
.parse::<i32>()
.map_err(|e: _| Error::schema(e.to_string()))?;
let inner_type = splits[1..splits.len() - 1].join(":");
match inner_type.as_str() {
BFLOAT16_EXT_NAME => {
let field = ArrowField::new("item", Self::FixedSizeBinary(2), true)
.with_metadata(
[
(ARROW_EXT_NAME_KEY.into(), BFLOAT16_EXT_NAME.into()),
(ARROW_EXT_META_KEY.into(), "".into()),
]
.into(),
);
Ok(FixedSizeList(Arc::new(field), size))
}
data_type => {
let elem_type = (&LogicalType(data_type.to_string())).try_into()?;
Ok(FixedSizeList(
Arc::new(ArrowField::new("item", elem_type, true)),
size,
))
}
}
}
"fixed_size_binary" => {
if splits.len() != 2 {
Err(Error::schema(format!("Unsupported logical type: {}", lt)))
} else {
let size: i32 = splits[1]
.parse::<i32>()
.map_err(|e: _| Error::schema(e.to_string()))?;
Ok(FixedSizeBinary(size))
}
}
"dict" => {
if splits.len() != 4 {
Err(Error::schema(format!(
"Unsupported dictionary type: {}",
lt
)))
} else {
let value_type: Self = (&LogicalType::from(splits[1])).try_into()?;
let index_type: Self = (&LogicalType::from(splits[2])).try_into()?;
Ok(Dictionary(Box::new(index_type), Box::new(value_type)))
}
}
"decimal" => {
if splits.len() != 4 {
Err(Error::schema(format!("Unsupported decimal type: {}", lt)))
} else {
let bits: i16 = splits[1]
.parse::<i16>()
.map_err(|err| Error::schema(err.to_string()))?;
let precision: u8 = splits[2]
.parse::<u8>()
.map_err(|err| Error::schema(err.to_string()))?;
let scale: i8 = splits[3]
.parse::<i8>()
.map_err(|err| Error::schema(err.to_string()))?;
if bits == 128 {
Ok(Decimal128(precision, scale))
} else if bits == 256 {
Ok(Decimal256(precision, scale))
} else {
Err(Error::schema(format!(
"Only Decimal128 and Decimal256 is supported. Found {bits}"
)))
}
}
}
"timestamp" => {
if splits.len() != 3 {
Err(Error::schema(format!("Unsupported timestamp type: {}", lt)))
} else {
let timeunit = parse_timeunit(splits[1])?;
let tz: Option<Arc<str>> = if splits[2] == "-" {
None
} else {
Some(splits[2].into())
};
Ok(Timestamp(timeunit, tz))
}
}
_ => Err(Error::schema(format!("Unsupported logical type: {}", lt))),
}
}
}
}
#[derive(Debug, Clone, Default)]
pub struct Dictionary {
pub offset: usize,
pub length: usize,
pub values: Option<ArrayRef>,
}
impl DeepSizeOf for Dictionary {
fn deep_size_of_children(&self, context: &mut crate::deepsize::Context) -> usize {
self.values
.as_ref()
.map(|v| (v.as_ref() as &dyn arrow_array::Array).deep_size_of_children(context))
.unwrap_or(0)
}
}
impl PartialEq for Dictionary {
fn eq(&self, other: &Self) -> bool {
match (&self.values, &other.values) {
(Some(a), Some(b)) => a == b,
_ => false,
}
}
}
/// Physical storage mode for blob v2 descriptors (one byte, stored in the packed struct column).
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[repr(u8)]
pub enum BlobKind {
/// Stored in the main data file’s out-of-line buffer; `position`/`size` point into that file.
Inline = 0,
/// Stored in a shared packed blob file; `position`/`size` locate the slice, `blob_id` selects the file.
Packed = 1,
/// Stored in a dedicated raw blob file; `blob_id` identifies the file, `size` is the full file length.
Dedicated = 2,
/// Not stored by Lance data files.
///
/// For external blobs:
/// - `blob_id == 0` means `blob_uri` is an absolute external URI.
/// - `blob_id > 0` means `blob_uri` is a path relative to `manifest.base_paths[blob_id]`.
///
/// External blobs can have a position and a size. If the position is not set,
/// it defaults to 0, which points to the beginning of the blob.
External = 3,
}
impl TryFrom<u8> for BlobKind {
type Error = Error;
fn try_from(value: u8) -> Result<Self> {
match value {
0 => Ok(Self::Inline),
1 => Ok(Self::Packed),
2 => Ok(Self::Dedicated),
3 => Ok(Self::External),
other => Err(Error::invalid_input_source(
format!("Unknown blob kind {other:?}").into(),
)),
}
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn test_classify_blob_v2_layouts() {
assert_eq!(
BlobV2Layout::classify(&BLOB_V2_LOGICAL_MINIMAL_FIELDS),
Some(BlobV2Layout::Logical)
);
assert_eq!(
BlobV2Layout::classify(&BLOB_V2_LOGICAL_FIELDS),
Some(BlobV2Layout::Logical)
);
assert_eq!(
BlobV2Layout::classify(&BLOB_V2_PREPARED_FIELDS),
Some(BlobV2Layout::Prepared)
);
assert_eq!(
BlobV2Layout::classify(&BLOB_V2_DESC_FIELDS),
Some(BlobV2Layout::Descriptor)
);
}
#[test]
fn test_classify_blob_v2_layout_uses_structural_contract() {
let logical_with_required_range = Fields::from(vec![
ArrowField::new("data", DataType::LargeBinary, true),
ArrowField::new("uri", DataType::Utf8, true),
ArrowField::new("position", DataType::UInt64, false),
ArrowField::new("size", DataType::UInt64, false),
]);
assert_eq!(
BlobV2Layout::classify(&logical_with_required_range),
Some(BlobV2Layout::Logical)
);
let prepared_with_child_metadata =
Fields::from(
BLOB_V2_PREPARED_FIELDS
.iter()
.map(|field| {
Arc::new(field.as_ref().clone().with_metadata(HashMap::from([(
"source".to_string(),
"test".to_string(),
)])))
})
.collect::<Vec<_>>(),
);
assert_eq!(
BlobV2Layout::classify(&prepared_with_child_metadata),
Some(BlobV2Layout::Prepared)
);
let nullable_descriptor = Fields::from(
BLOB_V2_DESC_FIELDS
.iter()
.map(|field| Arc::new(field.as_ref().clone().with_nullable(true)))
.collect::<Vec<_>>(),
);
assert_eq!(
BlobV2Layout::classify(&nullable_descriptor),
Some(BlobV2Layout::Descriptor)
);
let malformed_descriptor = Fields::from(vec![
ArrowField::new("kind", DataType::UInt8, false),
ArrowField::new("position", DataType::UInt64, false),
ArrowField::new("size", DataType::UInt32, false),
ArrowField::new("blob_id", DataType::UInt32, false),
ArrowField::new("blob_uri", DataType::Utf8, false),
]);
assert_eq!(BlobV2Layout::classify(&malformed_descriptor), None);
}
}
lance-artifact/rust/lance-core/src/datatypes/field.rs
+2044
View File
File diff suppressed because it is too large Load Diff
lance-artifact/rust/lance-core/src/datatypes/schema.rs
+3163
View File
File diff suppressed because it is too large Load Diff
lance-artifact/rust/lance-core/src/deepsize.rs
+467
View File
@@ -0,0 +1,467 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright The Lance Authors
pub use lance_derive::DeepSizeOf;
use std::collections::{BTreeMap, BTreeSet, HashMap, HashSet};
use std::mem::{size_of, size_of_val};
use std::sync::atomic::{AtomicU64, AtomicUsize};
use std::sync::{Arc, Mutex, RwLock};
use arrow_array::{Array, RecordBatch};
use arrow_buffer::ArrowNativeType;
use arrow_data::ArrayData;
pub struct Context {
seen: HashSet<usize>,
}
impl Default for Context {
fn default() -> Self {
Self::new()
}
}
impl Context {
pub fn new() -> Self {
Self {
seen: HashSet::new(),
}
}
/// Returns true if this pointer was NOT previously seen (i.e., it's new).
pub fn mark_seen(&mut self, ptr: usize) -> bool {
self.seen.insert(ptr)
}
}
pub trait DeepSizeOf {
fn deep_size_of(&self) -> usize {
size_of_val(self) + self.deep_size_of_children(&mut Context::new())
}
fn deep_size_of_children(&self, context: &mut Context) -> usize;
}
// Primitives — no heap children
macro_rules! impl_deep_size_primitive {
($($t:ty),*) => {
$(
impl DeepSizeOf for $t {
fn deep_size_of_children(&self, _context: &mut Context) -> usize {
0
}
}
)*
};
}
impl_deep_size_primitive!(
u8,
u16,
u32,
u64,
u128,
usize,
i8,
i16,
i32,
i64,
i128,
isize,
f32,
f64,
bool,
()
);
impl DeepSizeOf for str {
fn deep_size_of_children(&self, _context: &mut Context) -> usize {
0
}
}
impl DeepSizeOf for String {
fn deep_size_of_children(&self, _context: &mut Context) -> usize {
self.capacity()
}
}
impl DeepSizeOf for bytes::Bytes {
fn deep_size_of_children(&self, context: &mut Context) -> usize {
if context.mark_seen(self.as_ptr() as usize) {
self.len()
} else {
0
}
}
}
impl DeepSizeOf for AtomicU64 {
fn deep_size_of_children(&self, _context: &mut Context) -> usize {
0
}
}
impl DeepSizeOf for AtomicUsize {
fn deep_size_of_children(&self, _context: &mut Context) -> usize {
0
}
}
impl<T: DeepSizeOf, const N: usize> DeepSizeOf for [T; N] {
fn deep_size_of_children(&self, context: &mut Context) -> usize {
self.iter()
.map(|item| item.deep_size_of_children(context))
.sum()
}
}
impl<T: DeepSizeOf> DeepSizeOf for [T] {
fn deep_size_of_children(&self, context: &mut Context) -> usize {
// The slice's own element bytes are accounted for by the owner (e.g. the
// `size_of_val` in the `Arc`/`Box` impls); here we only sum the heap
// children of each element.
self.iter()
.map(|item| item.deep_size_of_children(context))
.sum()
}
}
impl<T: DeepSizeOf> DeepSizeOf for RwLock<T> {
fn deep_size_of_children(&self, context: &mut Context) -> usize {
self.read()
.map(|val| val.deep_size_of_children(context))
.unwrap_or(0)
}
}
impl<T: DeepSizeOf> DeepSizeOf for Mutex<T> {
fn deep_size_of_children(&self, context: &mut Context) -> usize {
self.lock()
.map(|val| val.deep_size_of_children(context))
.unwrap_or(0)
}
}
// Tuples
macro_rules! impl_deep_size_tuple {
($($name:ident),+) => {
impl<$($name: DeepSizeOf),+> DeepSizeOf for ($($name,)+) {
#[allow(non_snake_case)]
fn deep_size_of_children(&self, context: &mut Context) -> usize {
let ($($name,)+) = self;
0 $(+ $name.deep_size_of_children(context))+
}
}
};
}
impl_deep_size_tuple!(A, B);
impl_deep_size_tuple!(A, B, C);
impl_deep_size_tuple!(A, B, C, D);
impl_deep_size_tuple!(A, B, C, D, E);
impl_deep_size_tuple!(A, B, C, D, E, F);
impl<T: DeepSizeOf> DeepSizeOf for Vec<T> {
fn deep_size_of_children(&self, context: &mut Context) -> usize {
self.capacity() * size_of::<T>()
+ self
.iter()
.map(|item| item.deep_size_of_children(context))
.sum::<usize>()
}
}
impl<T: DeepSizeOf + ?Sized> DeepSizeOf for Box<T> {
fn deep_size_of_children(&self, context: &mut Context) -> usize {
size_of_val(&**self) + (**self).deep_size_of_children(context)
}
}
impl<T: DeepSizeOf + ?Sized> DeepSizeOf for Arc<T> {
fn deep_size_of_children(&self, context: &mut Context) -> usize {
if context.mark_seen(Self::as_ptr(self) as *const () as usize) {
size_of_val(&**self) + (**self).deep_size_of_children(context)
} else {
0
}
}
}
impl<T: DeepSizeOf> DeepSizeOf for Option<T> {
fn deep_size_of_children(&self, context: &mut Context) -> usize {
match self {
Some(val) => val.deep_size_of_children(context),
None => 0,
}
}
}
impl<K: DeepSizeOf, V: DeepSizeOf> DeepSizeOf for HashMap<K, V> {
fn deep_size_of_children(&self, context: &mut Context) -> usize {
// Each bucket holds a key-value pair plus hash metadata (~1 byte control per bucket).
// Robin hood / Swiss table capacity is always a power of 2.
let capacity_bytes = self.capacity() * (size_of::<K>() + size_of::<V>() + 1);
let children: usize = self
.iter()
.map(|(k, v)| k.deep_size_of_children(context) + v.deep_size_of_children(context))
.sum();
capacity_bytes + children
}
}
impl<K: DeepSizeOf> DeepSizeOf for HashSet<K> {
fn deep_size_of_children(&self, context: &mut Context) -> usize {
let capacity_bytes = self.capacity() * (size_of::<K>() + 1);
let children: usize = self.iter().map(|k| k.deep_size_of_children(context)).sum();
capacity_bytes + children
}
}
impl<K: DeepSizeOf, V: DeepSizeOf> DeepSizeOf for BTreeMap<K, V> {
fn deep_size_of_children(&self, context: &mut Context) -> usize {
// BTreeMap nodes have ~11 entries each. Rough estimate: per-entry overhead ~3 pointers.
let per_entry = size_of::<K>() + size_of::<V>() + 3 * size_of::<usize>();
let overhead = self.len() * per_entry;
let children: usize = self
.iter()
.map(|(k, v)| k.deep_size_of_children(context) + v.deep_size_of_children(context))
.sum();
overhead + children
}
}
impl<K: DeepSizeOf> DeepSizeOf for BTreeSet<K> {
fn deep_size_of_children(&self, context: &mut Context) -> usize {
let per_entry = size_of::<K>() + 3 * size_of::<usize>();
let overhead = self.len() * per_entry;
let children: usize = self.iter().map(|k| k.deep_size_of_children(context)).sum();
overhead + children
}
}
// Arrow types
fn record_array_data(context: &mut Context, data: &ArrayData) -> usize {
let mut total = 0;
for buffer in data.buffers() {
if context.mark_seen(buffer.as_ptr() as usize) {
total += buffer.capacity();
}
}
if let Some(nulls) = data.nulls() {
let null_buf = nulls.inner().inner();
if context.mark_seen(null_buf.as_ptr() as usize) {
total += null_buf.capacity();
}
}
for child in data.child_data() {
total += record_array_data(context, child);
}
total
}
impl DeepSizeOf for dyn Array {
fn deep_size_of_children(&self, context: &mut Context) -> usize {
// `to_data()` only clones Arc refs (no data copy) and allocates a small
// ArrayData metadata struct. This lets us walk buffer pointers for dedup.
// Cost is O(number_of_buffers), not O(data_size).
let data = self.to_data();
record_array_data(context, &data)
}
}
impl DeepSizeOf for RecordBatch {
fn deep_size_of_children(&self, context: &mut Context) -> usize {
self.columns()
.iter()
.map(|col| col.deep_size_of_children(context))
.sum()
}
}
impl<T> DeepSizeOf for arrow_buffer::ScalarBuffer<T>
where
T: ArrowNativeType,
{
fn deep_size_of_children(&self, context: &mut Context) -> usize {
// Track the underlying buffer pointer to avoid double-counting shared allocations.
// Use capacity() rather than len() * size_of::<T>() because sliced buffers retain
// their full original allocation.
let buf = self.inner();
if context.mark_seen(buf.as_ptr() as usize) {
buf.capacity()
} else {
0
}
}
}
#[cfg(test)]
mod tests {
use super::*;
use arrow_array::{Int32Array, StringArray, StructArray};
use arrow_schema::{DataType, Field, Fields, Schema};
#[test]
fn test_basic_record_batch() {
let batch = RecordBatch::try_new(
Arc::new(Schema::new(vec![Field::new("a", DataType::Int32, false)])),
vec![Arc::new(Int32Array::from(vec![1, 2, 3]))],
)
.unwrap();
let size = batch.deep_size_of();
// Should at least include the buffer for 3 i32s
assert!(size >= 3 * size_of::<i32>());
}
#[test]
fn test_same_batch_dedup() {
let batch = RecordBatch::try_new(
Arc::new(Schema::new(vec![Field::new("a", DataType::Int32, false)])),
vec![Arc::new(Int32Array::from(vec![1, 2, 3, 4, 5]))],
)
.unwrap();
let mut ctx = Context::new();
let size_a = batch.deep_size_of_children(&mut ctx);
let size_b = batch.deep_size_of_children(&mut ctx);
// First measurement should report buffer sizes
assert!(size_a > 0);
// Second measurement of the same batch should add nothing (buffers already seen)
assert_eq!(size_b, 0);
}
#[test]
fn test_arc_dedup() {
let batch = Arc::new(
RecordBatch::try_new(
Arc::new(Schema::new(vec![Field::new("a", DataType::Int32, false)])),
vec![Arc::new(Int32Array::from(vec![1, 2, 3]))],
)
.unwrap(),
);
let clone = Arc::clone(&batch);
let mut ctx = Context::new();
let size_a = batch.deep_size_of_children(&mut ctx);
let size_b = clone.deep_size_of_children(&mut ctx);
assert!(size_a > 0);
assert_eq!(size_b, 0);
}
#[test]
fn test_multi_column_shared_array() {
// Two columns pointing to the same Arc<dyn Array>
let array: Arc<dyn Array> = Arc::new(Int32Array::from(vec![10, 20, 30]));
let schema = Arc::new(Schema::new(vec![
Field::new("a", DataType::Int32, false),
Field::new("b", DataType::Int32, false),
]));
// Single-column batch for reference
let one_col = RecordBatch::try_new(
Arc::new(Schema::new(vec![Field::new("a", DataType::Int32, false)])),
vec![array.clone()],
)
.unwrap();
// Two-column batch with the same Arc shared
let two_col = RecordBatch::try_new(schema, vec![array.clone(), array]).unwrap();
let mut ctx1 = Context::new();
let size_one = one_col.deep_size_of_children(&mut ctx1);
let mut ctx2 = Context::new();
let size_two = two_col.deep_size_of_children(&mut ctx2);
// Both should report the same size since the second column's Arc is
// already seen and contributes nothing
assert_eq!(size_one, size_two);
}
#[test]
fn test_nested_struct_array() {
let int_array = Int32Array::from(vec![1, 2, 3]);
let str_array = StringArray::from(vec!["a", "b", "c"]);
let struct_array = StructArray::from(vec![
(
Arc::new(Field::new("x", DataType::Int32, false)),
Arc::new(int_array) as Arc<dyn Array>,
),
(
Arc::new(Field::new("y", DataType::Utf8, false)),
Arc::new(str_array) as Arc<dyn Array>,
),
]);
let batch = RecordBatch::try_new(
Arc::new(Schema::new(vec![Field::new(
"s",
DataType::Struct(Fields::from(vec![
Field::new("x", DataType::Int32, false),
Field::new("y", DataType::Utf8, false),
])),
false,
)])),
vec![Arc::new(struct_array)],
)
.unwrap();
let size = batch.deep_size_of();
// Should include buffers for both child arrays
assert!(size > 3 * size_of::<i32>());
}
#[test]
fn test_std_types() {
assert_eq!(42u32.deep_size_of(), size_of::<u32>());
let s = String::from("hello");
assert!(s.deep_size_of() >= size_of::<String>() + 5);
let v = vec![1u32, 2, 3];
assert!(v.deep_size_of() >= size_of::<Vec<u32>>() + 3 * size_of::<u32>());
let a = Arc::new(42u32);
let b = Arc::clone(&a);
let mut ctx = Context::new();
let size_a = a.deep_size_of_children(&mut ctx);
let size_b = b.deep_size_of_children(&mut ctx);
assert_eq!(size_a, size_of::<u32>());
assert_eq!(size_b, 0);
}
#[test]
fn test_derive_macro() {
use lance_derive::DeepSizeOf;
#[derive(DeepSizeOf)]
struct Outer {
count: u64,
label: String,
inner: Inner,
}
#[derive(DeepSizeOf)]
struct Inner {
values: Vec<u32>,
}
let val = Outer {
count: 7,
label: String::from("hello"),
inner: Inner {
values: vec![1, 2, 3],
},
};
let size = val.deep_size_of();
// Must be at least the stack size + heap allocations for label + values
assert!(size >= std::mem::size_of::<Outer>() + 5 + 3 * std::mem::size_of::<u32>());
}
}
lance-artifact/rust/lance-core/src/error.rs
+1506
View File
File diff suppressed because it is too large Load Diff
lance-artifact/rust/lance-core/src/levenshtein.rs
+133
View File
@@ -0,0 +1,133 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright The Lance Authors
/// Calculate the Levenshtein distance between two strings.
///
/// The Levenshtein distance is a measure of the number of single-character edits
/// (insertions, deletions, or substitutions) required to change one word into the other.
///
/// # Examples
///
/// ```
/// use lance_core::levenshtein::levenshtein_distance;
///
/// assert_eq!(levenshtein_distance("kitten", "sitting"), 3);
/// assert_eq!(levenshtein_distance("hello", "hello"), 0);
/// ```
pub fn levenshtein_distance(s1: &str, s2: &str) -> usize {
let s1_chars: Vec<char> = s1.chars().collect();
let s2_chars: Vec<char> = s2.chars().collect();
let m = s1_chars.len();
let n = s2_chars.len();
if m == 0 {
return n;
}
if n == 0 {
return m;
}
// Use two rows instead of full matrix for space efficiency
let mut prev_row: Vec<usize> = (0..=n).collect();
let mut curr_row: Vec<usize> = vec![0; n + 1];
for (i, s1_char) in s1_chars.iter().enumerate() {
curr_row[0] = i + 1;
for (j, s2_char) in s2_chars.iter().enumerate() {
let cost = if s1_char == s2_char { 0 } else { 1 };
curr_row[j + 1] = (prev_row[j + 1] + 1)
.min(curr_row[j] + 1)
.min(prev_row[j] + cost);
}
std::mem::swap(&mut prev_row, &mut curr_row);
}
prev_row[n]
}
/// Find the best suggestion from a list of options based on Levenshtein distance.
///
/// Returns `Some(suggestion)` if there's an option where the Levenshtein distance
/// is at most 1/3 of the length of the input string (integer division).
/// Otherwise returns `None`.
///
/// # Examples
///
/// ```
/// use lance_core::levenshtein::find_best_suggestion;
///
/// let options = vec!["vector", "id", "name"];
/// assert_eq!(find_best_suggestion("vacter", &options), Some("vector"));
/// assert_eq!(find_best_suggestion("hello", &options), None);
/// ```
pub fn find_best_suggestion<'a, 'b>(
input: &'a str,
options: &'b [impl AsRef<str>],
) -> Option<&'b str> {
let input_len = input.chars().count();
if input_len == 0 {
return None;
}
let threshold = input_len / 3;
let mut best_option: Option<(&'b str, usize)> = None;
for option in options {
let distance = levenshtein_distance(input, option.as_ref());
if distance <= threshold {
match &best_option {
None => best_option = Some((option.as_ref(), distance)),
Some((_, best_distance)) => {
if distance < *best_distance {
best_option = Some((option.as_ref(), distance));
}
}
}
}
}
best_option.map(|(option, _)| option)
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn test_levenshtein_distance() {
assert_eq!(levenshtein_distance("", ""), 0);
assert_eq!(levenshtein_distance("a", ""), 1);
assert_eq!(levenshtein_distance("", "a"), 1);
assert_eq!(levenshtein_distance("abc", "abc"), 0);
assert_eq!(levenshtein_distance("abc", ""), 3);
assert_eq!(levenshtein_distance("", "abc"), 3);
assert_eq!(levenshtein_distance("kitten", "sitting"), 3);
assert_eq!(levenshtein_distance("saturday", "sunday"), 3);
assert_eq!(levenshtein_distance("vector", "vectr"), 1);
assert_eq!(levenshtein_distance("vector", "vextor"), 1);
assert_eq!(levenshtein_distance("vector", "vvector"), 1);
assert_eq!(levenshtein_distance("abc", "xyz"), 3);
}
#[test]
fn test_find_best_suggestion() {
let options = vec!["vector", "id", "name", "column", "table"];
assert_eq!(find_best_suggestion("vacter", &options), Some("vector"));
assert_eq!(find_best_suggestion("vectr", &options), Some("vector"));
assert_eq!(find_best_suggestion("tble", &options), Some("table"));
// Should return None if no good match
assert_eq!(find_best_suggestion("hello", &options), None);
assert_eq!(find_best_suggestion("xyz", &options), None);
// Should return None if input is too short
assert_eq!(find_best_suggestion("v", &options), None);
assert_eq!(find_best_suggestion("", &options), None);
// Picks closest when multiple are close
assert_eq!(
find_best_suggestion("vecor", &["vector", "vendor"]),
Some("vector")
);
}
}
lance-artifact/rust/lance-core/src/lib.rs
+68
View File
@@ -0,0 +1,68 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright The Lance Authors
#![cfg_attr(coverage, feature(coverage_attribute))]
// Allow the derive macro to reference `lance_core::deepsize` from within this crate.
extern crate self as lance_core;
use arrow_schema::{DataType, Field as ArrowField};
use std::sync::LazyLock;
pub mod cache;
pub mod container;
pub mod datatypes;
pub mod deepsize;
pub mod error;
pub mod levenshtein;
pub mod traits;
pub mod utils;
pub use error::{ArrowResult, Error, FenceReason, Result, box_error};
/// Wildcard to indicate all non-system columns
pub const WILDCARD: &str = "*";
/// Column name for the meta row ID.
pub const ROW_ID: &str = "_rowid";
/// Column name for the meta row address.
pub const ROW_ADDR: &str = "_rowaddr";
/// Column name for the meta row offset.
pub const ROW_OFFSET: &str = "_rowoffset";
/// Column name for the row's last updated at dataset version.
pub const ROW_LAST_UPDATED_AT_VERSION: &str = "_row_last_updated_at_version";
/// Column name for the row's created at dataset version.
pub const ROW_CREATED_AT_VERSION: &str = "_row_created_at_version";
/// Row ID field. This is nullable because its validity bitmap is sometimes used
/// as a selection vector.
pub static ROW_ID_FIELD: LazyLock<ArrowField> =
LazyLock::new(|| ArrowField::new(ROW_ID, DataType::UInt64, true));
/// Row address field. This is nullable because its validity bitmap is sometimes used
/// as a selection vector.
pub static ROW_ADDR_FIELD: LazyLock<ArrowField> =
LazyLock::new(|| ArrowField::new(ROW_ADDR, DataType::UInt64, true));
/// Row offset field. This is nullable merely for compatibility with the other
/// fields.
pub static ROW_OFFSET_FIELD: LazyLock<ArrowField> =
LazyLock::new(|| ArrowField::new(ROW_OFFSET, DataType::UInt64, true));
/// Row last updated at version field.
pub static ROW_LAST_UPDATED_AT_VERSION_FIELD: LazyLock<ArrowField> =
LazyLock::new(|| ArrowField::new(ROW_LAST_UPDATED_AT_VERSION, DataType::UInt64, true));
/// Row created at version field.
pub static ROW_CREATED_AT_VERSION_FIELD: LazyLock<ArrowField> =
LazyLock::new(|| ArrowField::new(ROW_CREATED_AT_VERSION, DataType::UInt64, true));
/// Check if a column name is a system column.
///
/// System columns are virtual columns that are computed at read time and don't
/// exist in the physical data files. They include:
/// - `_rowid`: The row ID
/// - `_rowaddr`: The row address
/// - `_rowoffset`: The row offset
/// - `_row_last_updated_at_version`: The version when the row was last updated
/// - `_row_created_at_version`: The version when the row was created
pub fn is_system_column(column_name: &str) -> bool {
matches!(
column_name,
ROW_ID | ROW_ADDR | ROW_OFFSET | ROW_LAST_UPDATED_AT_VERSION | ROW_CREATED_AT_VERSION
)
}
lance-artifact/rust/lance-core/src/traits.rs
+27
View File
@@ -0,0 +1,27 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright The Lance Authors
//! Dataset Traits
use std::fmt::Debug;
use arrow_array::RecordBatch;
use crate::{Result, datatypes::Schema};
/// `TakeRow` trait.
///
/// It offers a lightweight trait to use `take_rows()` over a dataset, without
/// depending on the `lance` trait.
///
/// <section class="warning">
/// Internal API
/// </section>
#[async_trait::async_trait]
pub trait DatasetTakeRows: Debug + Send + Sync {
/// The schema of the dataset.
fn schema(&self) -> &Schema;
/// Take rows by the internal ROW ids.
async fn take_rows(&self, row_ids: &[u64], projection: &Schema) -> Result<RecordBatch>;
}
lance-artifact/rust/lance-core/src/utils.rs
+22
View File
@@ -0,0 +1,22 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright The Lance Authors
pub mod address;
pub mod aimd;
pub mod assume;
pub mod backoff;
pub mod bit;
pub mod blob;
pub mod bloomfilter;
pub mod cpu;
pub mod deletion;
pub mod futures;
pub mod hash;
pub mod io_stats;
pub mod parse;
pub mod path;
pub mod row_addr_remap;
pub mod tempfile;
pub mod testing;
pub mod tokio;
pub mod tracing;
lance-artifact/rust/lance-core/src/utils/address.rs
+116
View File
@@ -0,0 +1,116 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright The Lance Authors
use std::ops::Range;
/// A row address encodes a fragment ID (upper 32 bits) and row offset (lower 32 bits).
///
/// ```
/// use lance_core::utils::address::RowAddress;
///
/// let addr = RowAddress::new_from_parts(5, 100);
/// assert_eq!(addr.fragment_id(), 5);
/// assert_eq!(addr.row_offset(), 100);
///
/// // Convert to/from u64
/// let raw: u64 = addr.into();
/// let addr2: RowAddress = raw.into();
/// assert_eq!(addr, addr2);
///
/// // Display format
/// assert_eq!(format!("{}", addr), "(5, 100)");
/// ```
#[derive(Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub struct RowAddress(u64);
impl RowAddress {
pub const FRAGMENT_SIZE: u64 = 1 << 32;
/// A fragment id that will never be used.
pub const TOMBSTONE_FRAG: u32 = 0xffffffff;
/// A row id that will never be used.
pub const TOMBSTONE_ROW: u64 = 0xffffffffffffffff;
pub fn new_from_u64(row_addr: u64) -> Self {
Self(row_addr)
}
pub fn new_from_parts(fragment_id: u32, row_offset: u32) -> Self {
Self(((fragment_id as u64) << 32) | row_offset as u64)
}
/// Returns the address for the first row of a fragment.
pub fn first_row(fragment_id: u32) -> Self {
Self::new_from_parts(fragment_id, 0)
}
/// Returns the range of u64 addresses for a given fragment.
///
/// ```
/// use lance_core::utils::address::RowAddress;
///
/// let range = RowAddress::address_range(2);
/// assert_eq!(range.start, 2 * RowAddress::FRAGMENT_SIZE);
/// assert_eq!(range.end, 3 * RowAddress::FRAGMENT_SIZE);
/// ```
pub fn address_range(fragment_id: u32) -> Range<u64> {
u64::from(Self::first_row(fragment_id))..u64::from(Self::first_row(fragment_id + 1))
}
pub fn fragment_id(&self) -> u32 {
(self.0 >> 32) as u32
}
pub fn row_offset(&self) -> u32 {
self.0 as u32
}
}
impl From<RowAddress> for u64 {
fn from(row_addr: RowAddress) -> Self {
row_addr.0
}
}
impl From<u64> for RowAddress {
fn from(row_addr: u64) -> Self {
Self(row_addr)
}
}
impl std::fmt::Debug for RowAddress {
fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
write!(f, "{}", self) // use Display
}
}
impl std::fmt::Display for RowAddress {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
write!(f, "({}, {})", self.fragment_id(), self.row_offset())
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn test_row_address() {
// new_from_u64 (not in doctest)
let addr = RowAddress::new_from_u64(0x0000_0001_0000_0002);
assert_eq!(addr.fragment_id(), 1);
assert_eq!(addr.row_offset(), 2);
// address_range uses first_row internally (coverage)
let range = RowAddress::address_range(3);
assert_eq!(range.start, 3 * RowAddress::FRAGMENT_SIZE);
// From impls with different values than doctest
let addr2 = RowAddress::new_from_parts(7, 8);
let raw: u64 = addr2.into();
let addr3: RowAddress = raw.into();
assert_eq!(addr2, addr3);
// Debug format (doctest only tests Display)
assert_eq!(format!("{:?}", addr), "(1, 2)");
}
}
lance-artifact/rust/lance-core/src/utils/aimd.rs
+623
View File
@@ -0,0 +1,623 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright The Lance Authors
//! AIMD (Additive Increase / Multiplicative Decrease) rate controller.
//!
//! This module provides a reusable AIMD algorithm for dynamically adjusting
//! request rates. On success windows, the rate increases additively. On
//! windows with throttle signals, the rate decreases multiplicatively.
//!
//! The algorithm operates in discrete time windows. At the end of each window,
//! the throttle ratio (throttled / total) is compared against a threshold:
//! - Above threshold: `rate = max(rate * decrease_factor, min_rate)`
//! - At or below threshold: `rate = min(rate + additive_increment, max_rate)`
use std::sync::Mutex;
use std::time::Duration;
use crate::Result;
/// Configuration for the AIMD rate controller.
///
/// Use builder methods to customize. Defaults are tuned for cloud object stores
/// and will start at about 40% of the max rate and require 10 seconds to reach
/// the max rate.
///
/// - initial_rate: 2000 req/s
/// - min_rate: 1 req/s
/// - max_rate: 5000 req/s (0.0 disables ceiling)
/// - decrease_factor: 0.5 (halve on throttle)
/// - additive_increment: 300 req/s per success window
/// - window_duration: 1 second
/// - throttle_threshold: 0.0 (any throttle triggers decrease)
#[derive(Debug, Clone)]
pub struct AimdConfig {
pub initial_rate: f64,
pub min_rate: f64,
pub max_rate: f64,
pub decrease_factor: f64,
pub additive_increment: f64,
pub window_duration: Duration,
pub throttle_threshold: f64,
}
impl Default for AimdConfig {
fn default() -> Self {
Self {
initial_rate: 2000.0,
min_rate: 1.0,
max_rate: 5000.0,
decrease_factor: 0.5,
additive_increment: 300.0,
window_duration: Duration::from_secs(1),
throttle_threshold: 0.0,
}
}
}
impl AimdConfig {
pub fn with_initial_rate(self, initial_rate: f64) -> Self {
Self {
initial_rate,
..self
}
}
pub fn with_min_rate(self, min_rate: f64) -> Self {
Self { min_rate, ..self }
}
pub fn with_max_rate(self, max_rate: f64) -> Self {
Self { max_rate, ..self }
}
pub fn with_decrease_factor(self, decrease_factor: f64) -> Self {
Self {
decrease_factor,
..self
}
}
pub fn with_additive_increment(self, additive_increment: f64) -> Self {
Self {
additive_increment,
..self
}
}
pub fn with_window_duration(self, window_duration: Duration) -> Self {
Self {
window_duration,
..self
}
}
pub fn with_throttle_threshold(self, throttle_threshold: f64) -> Self {
Self {
throttle_threshold,
..self
}
}
/// Validate that the configuration values are sensible.
pub fn validate(&self) -> Result<()> {
if self.initial_rate <= 0.0 {
return Err(crate::Error::invalid_input(format!(
"initial_rate must be positive, got {}",
self.initial_rate
)));
}
if self.min_rate <= 0.0 {
return Err(crate::Error::invalid_input(format!(
"min_rate must be positive, got {}",
self.min_rate
)));
}
if self.max_rate < 0.0 {
return Err(crate::Error::invalid_input(format!(
"max_rate must be non-negative (0.0 = no ceiling), got {}",
self.max_rate
)));
}
if self.max_rate > 0.0 && self.min_rate > self.max_rate {
return Err(crate::Error::invalid_input(format!(
"min_rate ({}) must not exceed max_rate ({})",
self.min_rate, self.max_rate
)));
}
if self.decrease_factor <= 0.0 || self.decrease_factor >= 1.0 {
return Err(crate::Error::invalid_input(format!(
"decrease_factor must be in (0, 1), got {}",
self.decrease_factor
)));
}
if self.additive_increment <= 0.0 {
return Err(crate::Error::invalid_input(format!(
"additive_increment must be positive, got {}",
self.additive_increment
)));
}
if self.window_duration.is_zero() {
return Err(crate::Error::invalid_input(
"window_duration must be non-zero",
));
}
if !(0.0..=1.0).contains(&self.throttle_threshold) {
return Err(crate::Error::invalid_input(format!(
"throttle_threshold must be in [0.0, 1.0], got {}",
self.throttle_threshold
)));
}
if self.max_rate > 0.0 && self.initial_rate > self.max_rate {
return Err(crate::Error::invalid_input(format!(
"initial_rate ({}) must not exceed max_rate ({})",
self.initial_rate, self.max_rate
)));
}
if self.initial_rate < self.min_rate {
return Err(crate::Error::invalid_input(format!(
"initial_rate ({}) must not be below min_rate ({})",
self.initial_rate, self.min_rate
)));
}
Ok(())
}
}
/// Outcome of a single request, used to feed the AIMD controller.
///
/// Non-throttle errors (e.g. 404, network timeout) should be mapped to
/// `Success` since they don't indicate capacity problems.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum RequestOutcome {
Success,
Throttled,
}
struct AimdState {
rate: f64,
window_start: std::time::Instant,
success_count: u64,
throttle_count: u64,
}
/// AIMD rate controller.
///
/// Thread-safe: uses an internal `Mutex` to protect state. The lock is held
/// only briefly during `record_outcome` and `current_rate`.
pub struct AimdController {
config: AimdConfig,
state: Mutex<AimdState>,
}
impl std::fmt::Debug for AimdController {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.debug_struct("AimdController")
.field("config", &self.config)
.field("rate", &self.current_rate())
.finish()
}
}
impl AimdController {
/// Create a new AIMD controller with the given configuration.
pub fn new(config: AimdConfig) -> Result<Self> {
config.validate()?;
let rate = config.initial_rate;
Ok(Self {
config,
state: Mutex::new(AimdState {
rate,
window_start: std::time::Instant::now(),
success_count: 0,
throttle_count: 0,
}),
})
}
/// Record a request outcome and return the current rate.
///
/// If the current time window has expired, the rate is adjusted before
/// recording the new outcome in a fresh window.
pub fn record_outcome(&self, outcome: RequestOutcome) -> f64 {
let mut state = self.state.lock().unwrap();
self.record_outcome_inner(&mut state, outcome, std::time::Instant::now())
}
fn record_outcome_inner(
&self,
state: &mut AimdState,
outcome: RequestOutcome,
now: std::time::Instant,
) -> f64 {
// Check if the window has expired
let elapsed = now.duration_since(state.window_start);
if elapsed >= self.config.window_duration {
let total = state.success_count + state.throttle_count;
if total > 0 {
let throttle_ratio = state.throttle_count as f64 / total as f64;
if throttle_ratio > self.config.throttle_threshold {
// Multiplicative decrease
state.rate =
(state.rate * self.config.decrease_factor).max(self.config.min_rate);
} else {
// Additive increase
state.rate += self.config.additive_increment;
if self.config.max_rate > 0.0 {
state.rate = state.rate.min(self.config.max_rate);
}
}
}
// Reset window
state.window_start = now;
state.success_count = 0;
state.throttle_count = 0;
}
// Record this outcome
match outcome {
RequestOutcome::Success => state.success_count += 1,
RequestOutcome::Throttled => state.throttle_count += 1,
}
state.rate
}
/// Get the current rate without recording an outcome.
pub fn current_rate(&self) -> f64 {
self.state.lock().unwrap().rate
}
}
#[cfg(test)]
mod tests {
use super::*;
use rstest::rstest;
#[rstest]
#[case::zero_initial_rate(
AimdConfig::default().with_initial_rate(0.0),
"initial_rate must be positive"
)]
#[case::negative_min_rate(
AimdConfig::default().with_min_rate(-1.0),
"min_rate must be positive"
)]
#[case::negative_max_rate(
AimdConfig::default().with_max_rate(-1.0),
"max_rate must be non-negative"
)]
#[case::min_exceeds_max(
AimdConfig::default().with_min_rate(100.0).with_max_rate(10.0),
"min_rate (100) must not exceed max_rate (10)"
)]
#[case::decrease_factor_zero(
AimdConfig::default().with_decrease_factor(0.0),
"decrease_factor must be in (0, 1)"
)]
#[case::decrease_factor_one(
AimdConfig::default().with_decrease_factor(1.0),
"decrease_factor must be in (0, 1)"
)]
#[case::decrease_factor_over_one(
AimdConfig::default().with_decrease_factor(1.5),
"decrease_factor must be in (0, 1)"
)]
#[case::zero_additive_increment(
AimdConfig::default().with_additive_increment(0.0),
"additive_increment must be positive"
)]
#[case::zero_window_duration(
AimdConfig::default().with_window_duration(Duration::ZERO),
"window_duration must be non-zero"
)]
#[case::threshold_over_one(
AimdConfig::default().with_throttle_threshold(1.1),
"throttle_threshold must be in [0.0, 1.0]"
)]
#[case::threshold_negative(
AimdConfig::default().with_throttle_threshold(-0.1),
"throttle_threshold must be in [0.0, 1.0]"
)]
#[case::initial_exceeds_max(
AimdConfig::default().with_initial_rate(6000.0),
"initial_rate (6000) must not exceed max_rate (5000)"
)]
#[case::initial_below_min(
AimdConfig::default().with_initial_rate(0.5).with_min_rate(1.0),
"initial_rate (0.5) must not be below min_rate (1)"
)]
fn test_config_validation_rejects_invalid(
#[case] config: AimdConfig,
#[case] expected_msg: &str,
) {
let err = config.validate().unwrap_err();
let msg = err.to_string();
assert!(
msg.contains(expected_msg),
"Expected error containing '{}', got: {}",
expected_msg,
msg
);
}
#[test]
fn test_default_config_is_valid() {
AimdConfig::default().validate().unwrap();
}
#[test]
fn test_no_ceiling_config_is_valid() {
AimdConfig::default().with_max_rate(0.0).validate().unwrap();
}
#[test]
fn test_additive_increase_on_success_window() {
let config = AimdConfig::default()
.with_initial_rate(100.0)
.with_additive_increment(10.0)
.with_window_duration(Duration::from_millis(100));
let controller = AimdController::new(config).unwrap();
// Record some successes in the first window
let start = std::time::Instant::now();
{
let mut state = controller.state.lock().unwrap();
controller.record_outcome_inner(&mut state, RequestOutcome::Success, start);
}
// Advance past the window boundary and record another success
let after_window = start + Duration::from_millis(150);
{
let mut state = controller.state.lock().unwrap();
controller.record_outcome_inner(&mut state, RequestOutcome::Success, after_window);
}
// Rate should have increased by additive_increment
assert_eq!(controller.current_rate(), 110.0);
}
#[test]
fn test_multiplicative_decrease_on_throttle_window() {
let config = AimdConfig::default()
.with_initial_rate(100.0)
.with_decrease_factor(0.5)
.with_window_duration(Duration::from_millis(100));
let controller = AimdController::new(config).unwrap();
let start = std::time::Instant::now();
{
let mut state = controller.state.lock().unwrap();
controller.record_outcome_inner(&mut state, RequestOutcome::Throttled, start);
}
// Advance past window
let after_window = start + Duration::from_millis(150);
{
let mut state = controller.state.lock().unwrap();
controller.record_outcome_inner(&mut state, RequestOutcome::Success, after_window);
}
assert_eq!(controller.current_rate(), 50.0);
}
#[test]
fn test_floor_enforcement() {
let config = AimdConfig::default()
.with_initial_rate(2.0)
.with_min_rate(1.0)
.with_decrease_factor(0.5)
.with_window_duration(Duration::from_millis(100));
let controller = AimdController::new(config).unwrap();
let start = std::time::Instant::now();
{
let mut state = controller.state.lock().unwrap();
controller.record_outcome_inner(&mut state, RequestOutcome::Throttled, start);
}
// After decrease: 2.0 * 0.5 = 1.0 (at floor)
let t1 = start + Duration::from_millis(150);
{
let mut state = controller.state.lock().unwrap();
controller.record_outcome_inner(&mut state, RequestOutcome::Throttled, t1);
}
assert_eq!(controller.current_rate(), 1.0);
// Another decrease should stay at floor
let t2 = t1 + Duration::from_millis(150);
{
let mut state = controller.state.lock().unwrap();
controller.record_outcome_inner(&mut state, RequestOutcome::Success, t2);
}
assert_eq!(controller.current_rate(), 1.0);
}
#[test]
fn test_ceiling_enforcement() {
let config = AimdConfig::default()
.with_initial_rate(4990.0)
.with_max_rate(5000.0)
.with_additive_increment(20.0)
.with_window_duration(Duration::from_millis(100));
let controller = AimdController::new(config).unwrap();
let start = std::time::Instant::now();
{
let mut state = controller.state.lock().unwrap();
controller.record_outcome_inner(&mut state, RequestOutcome::Success, start);
}
let t1 = start + Duration::from_millis(150);
{
let mut state = controller.state.lock().unwrap();
controller.record_outcome_inner(&mut state, RequestOutcome::Success, t1);
}
// 4990 + 20 = 5010, clamped to 5000
assert_eq!(controller.current_rate(), 5000.0);
}
#[test]
fn test_no_ceiling_allows_unbounded_growth() {
let config = AimdConfig::default()
.with_initial_rate(100.0)
.with_max_rate(0.0)
.with_additive_increment(50.0)
.with_window_duration(Duration::from_millis(100));
let controller = AimdController::new(config).unwrap();
let start = std::time::Instant::now();
let mut t = start;
for _ in 0..5 {
{
let mut state = controller.state.lock().unwrap();
controller.record_outcome_inner(&mut state, RequestOutcome::Success, t);
}
t += Duration::from_millis(150);
}
// Trigger final window evaluation
{
let mut state = controller.state.lock().unwrap();
controller.record_outcome_inner(&mut state, RequestOutcome::Success, t);
}
// 100 + 50*5 = 350
assert_eq!(controller.current_rate(), 350.0);
}
#[test]
fn test_empty_window_no_adjustment() {
let config = AimdConfig::default()
.with_initial_rate(100.0)
.with_window_duration(Duration::from_millis(100));
let controller = AimdController::new(config).unwrap();
// Don't record anything in the first window, just advance time
let start = std::time::Instant::now();
let after = start + Duration::from_millis(150);
{
let mut state = controller.state.lock().unwrap();
// First outcome in a new window after empty window
controller.record_outcome_inner(&mut state, RequestOutcome::Success, after);
}
// No adjustment because the expired window had 0 total
assert_eq!(controller.current_rate(), 100.0);
}
#[test]
fn test_throttle_threshold_filtering() {
// With threshold 0.5, less than 50% throttles should still increase
let config = AimdConfig::default()
.with_initial_rate(100.0)
.with_throttle_threshold(0.5)
.with_additive_increment(10.0)
.with_window_duration(Duration::from_millis(100));
let controller = AimdController::new(config).unwrap();
let start = std::time::Instant::now();
{
let mut state = controller.state.lock().unwrap();
// 1 throttle out of 3 = 33% < 50% threshold
controller.record_outcome_inner(&mut state, RequestOutcome::Success, start);
controller.record_outcome_inner(&mut state, RequestOutcome::Success, start);
controller.record_outcome_inner(&mut state, RequestOutcome::Throttled, start);
}
// Advance past window
let t1 = start + Duration::from_millis(150);
{
let mut state = controller.state.lock().unwrap();
controller.record_outcome_inner(&mut state, RequestOutcome::Success, t1);
}
// Should have increased because 33% <= 50%
assert_eq!(controller.current_rate(), 110.0);
}
#[test]
fn test_throttle_threshold_triggers_decrease() {
// With threshold 0.5, >= 50% throttles should decrease
let config = AimdConfig::default()
.with_initial_rate(100.0)
.with_throttle_threshold(0.5)
.with_decrease_factor(0.5)
.with_window_duration(Duration::from_millis(100));
let controller = AimdController::new(config).unwrap();
let start = std::time::Instant::now();
{
let mut state = controller.state.lock().unwrap();
// 2 throttle out of 3 = 67% > 50% threshold
controller.record_outcome_inner(&mut state, RequestOutcome::Success, start);
controller.record_outcome_inner(&mut state, RequestOutcome::Throttled, start);
controller.record_outcome_inner(&mut state, RequestOutcome::Throttled, start);
}
let t1 = start + Duration::from_millis(150);
{
let mut state = controller.state.lock().unwrap();
controller.record_outcome_inner(&mut state, RequestOutcome::Success, t1);
}
assert_eq!(controller.current_rate(), 50.0);
}
#[test]
fn test_recovery_after_decrease() {
let config = AimdConfig::default()
.with_initial_rate(100.0)
.with_decrease_factor(0.5)
.with_additive_increment(10.0)
.with_window_duration(Duration::from_millis(100));
let controller = AimdController::new(config).unwrap();
let start = std::time::Instant::now();
// Window 1: throttle → decrease to 50
{
let mut state = controller.state.lock().unwrap();
controller.record_outcome_inner(&mut state, RequestOutcome::Throttled, start);
}
let t1 = start + Duration::from_millis(150);
// Window 2: success → increase to 60
{
let mut state = controller.state.lock().unwrap();
controller.record_outcome_inner(&mut state, RequestOutcome::Success, t1);
}
let t2 = t1 + Duration::from_millis(150);
// Window 3: success → increase to 70
{
let mut state = controller.state.lock().unwrap();
controller.record_outcome_inner(&mut state, RequestOutcome::Success, t2);
}
let t3 = t2 + Duration::from_millis(150);
// Trigger final evaluation
{
let mut state = controller.state.lock().unwrap();
controller.record_outcome_inner(&mut state, RequestOutcome::Success, t3);
}
assert_eq!(controller.current_rate(), 70.0);
}
#[test]
fn test_within_window_no_adjustment() {
let config = AimdConfig::default()
.with_initial_rate(100.0)
.with_window_duration(Duration::from_secs(10));
let controller = AimdController::new(config).unwrap();
// Record many outcomes but all within the same window
for _ in 0..100 {
controller.record_outcome(RequestOutcome::Throttled);
}
// Rate should still be initial since window hasn't expired
assert_eq!(controller.current_rate(), 100.0);
}
}
lance-artifact/rust/lance-core/src/utils/assume.rs
+41
View File
@@ -0,0 +1,41 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright The Lance Authors
/// A macro that combines debug_assert and std::hint::assert_unchecked for optimized assertions
///
/// In debug builds, this will perform a normal assertion check.
/// In release builds, this will use hint::assert_unchecked which tells the compiler to assume
/// the condition is true without actually checking it.
///
/// # Safety
///
/// This macro is unsafe in release builds since it uses hint::assert_unchecked.
/// The caller must ensure the condition will always be true.
#[macro_export]
macro_rules! assume {
($cond:expr) => {
debug_assert!($cond);
// SAFETY: The debug_assert ensures this is true in debug builds.
// In release builds, caller must ensure the condition holds.
unsafe { std::hint::assert_unchecked($cond); }
};
($cond:expr, $($arg:tt)+) => {
debug_assert!($cond, $($arg)+);
// SAFETY: The debug_assert ensures this is true in debug builds.
// In release builds, caller must ensure the condition holds.
unsafe { std::hint::assert_unchecked($cond); }
};
}
/// Helper macro for equality assumptions.
#[macro_export]
macro_rules! assume_eq {
($left:expr, $right:expr) => {
debug_assert_eq!($left, $right);
unsafe { std::hint::assert_unchecked($left == $right); }
};
($left:expr, $right:expr, $($arg:tt)+) => {
debug_assert_eq!($left, $right, $($arg)+);
unsafe { std::hint::assert_unchecked($left == $right); }
};
}
lance-artifact/rust/lance-core/src/utils/backoff.rs
+291
View File
@@ -0,0 +1,291 @@
use rand::{Rng, SeedableRng};
use std::time::Duration;
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright The Lance Authors
/// Computes backoff as
///
/// ```text
/// backoff = base^attempt * unit + jitter
/// ```
///
/// The defaults are base=2, unit=50ms, jitter=50ms, min=0ms, max=5s. This gives
/// a backoff of 50ms, 100ms, 200ms, 400ms, 800ms, 1.6s, 3.2s, 5s, (not including jitter).
///
/// You can have non-exponential backoff by setting base=1.
pub struct Backoff {
base: u32,
unit: u32,
jitter: i32,
min: u32,
max: u32,
attempt: u32,
}
impl Default for Backoff {
fn default() -> Self {
Self {
base: 2,
unit: 50,
jitter: 50,
min: 0,
max: 5000,
attempt: 0,
}
}
}
impl Backoff {
pub fn with_base(self, base: u32) -> Self {
Self { base, ..self }
}
pub fn with_unit(self, unit: u32) -> Self {
Self { unit, ..self }
}
pub fn with_jitter(self, jitter: i32) -> Self {
Self { jitter, ..self }
}
pub fn with_min(self, min: u32) -> Self {
Self { min, ..self }
}
pub fn with_max(self, max: u32) -> Self {
Self { max, ..self }
}
pub fn next_backoff(&mut self) -> Duration {
let backoff = self
.base
.saturating_pow(self.attempt)
.saturating_mul(self.unit);
let jitter = rand::rng().random_range(-self.jitter..=self.jitter);
let backoff = (backoff.saturating_add_signed(jitter)).clamp(self.min, self.max);
self.attempt += 1;
Duration::from_millis(backoff as u64)
}
pub fn attempt(&self) -> u32 {
self.attempt
}
pub fn reset(&mut self) {
self.attempt = 0;
}
}
/// Upper bound on the number of retry slots.
///
/// Slots double each attempt to spread contending writers apart, but a hundred
/// or so already exceeds any realistic number of concurrent committers, so
/// further doubling only inflates the wait without reducing collisions. Capping
/// the count also bounds a single backoff to `(MAX_SLOTS - 1) * unit` instead of
/// letting it grow without limit as `attempt` climbs.
const MAX_SLOTS: u32 = 128;
/// SlotBackoff is a backoff strategy that randomly chooses a time slot to retry.
///
/// This is useful when you have multiple tasks that can't overlap, and each
/// task takes roughly the same amount of time.
///
/// The `unit` represents the time it takes to complete one attempt. Future attempts
/// are divided into time slots, and a random slot is chosen for the retry. The number
/// of slots increases exponentially with each attempt. Initially, there are 4 slots,
/// then 8, then 16, and so on, up to a fixed cap.
///
/// Example:
/// Suppose you have 10 tasks that can't overlap, each taking 1 second. The tasks
/// don't know about each other and can't coordinate. Each task randomly picks a
/// time slot to retry. Here's how it might look:
///
/// First round (4 slots):
/// ```text
/// task id | 1, 2, 3 | 4, 5, 6 | 7, 8, 9 | 10 |
/// status | x, x, ✓ | x, x, ✓ | x, x, ✓ | ✓ |
/// timeline | 0s | 1s | 2s | 3s |
/// ```
/// Each slot can have one success. Here, tasks 3, 6, 9, and 10 succeed.
/// In the next round, the number of slots doubles (8):
///
/// Second round (8 slots):
/// ```text
/// task id | 1 | 2 | | 4, 5 | 7 | 8 | | |
/// status | ✓ | ✓ | | x, ✓ | ✓ | ✓ | | |
/// timeline | 0s | 1s | 2s | 3s | 4s | 5s | 6s | 7s |
/// ```
/// Most tasks are done now, except for task 4. It will succeed in the next round.
pub struct SlotBackoff {
base: u32,
unit: u32,
starting_i: u32,
attempt: u32,
rng: rand::rngs::SmallRng,
}
impl Default for SlotBackoff {
fn default() -> Self {
Self {
base: 2,
unit: 50,
starting_i: 2, // start with 4 slots
attempt: 0,
rng: rand::rngs::SmallRng::from_os_rng(),
}
}
}
impl SlotBackoff {
pub fn with_unit(self, unit: u32) -> Self {
Self { unit, ..self }
}
pub fn attempt(&self) -> u32 {
self.attempt
}
pub fn next_backoff(&mut self) -> Duration {
let num_slots = self
.base
.saturating_pow(self.attempt.saturating_add(self.starting_i))
.min(MAX_SLOTS);
let slot_i = self.rng.random_range(0..num_slots);
self.attempt = self.attempt.saturating_add(1);
// Widen before multiplying: `unit` is the first-attempt latency, which
// can be large enough that a `u32` slot * unit product would overflow.
Duration::from_millis(slot_i as u64 * self.unit as u64)
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn test_backoff() {
let mut backoff = Backoff::default().with_jitter(0);
assert_eq!(backoff.next_backoff().as_millis(), 50);
assert_eq!(backoff.attempt(), 1);
assert_eq!(backoff.next_backoff().as_millis(), 100);
assert_eq!(backoff.attempt(), 2);
assert_eq!(backoff.next_backoff().as_millis(), 200);
assert_eq!(backoff.attempt(), 3);
assert_eq!(backoff.next_backoff().as_millis(), 400);
assert_eq!(backoff.attempt(), 4);
}
#[test]
fn test_backoff_with_base() {
let mut backoff = Backoff::default().with_base(3).with_jitter(0);
assert_eq!(backoff.next_backoff().as_millis(), 50); // 3^0 * 50
assert_eq!(backoff.next_backoff().as_millis(), 150); // 3^1 * 50
assert_eq!(backoff.next_backoff().as_millis(), 450); // 3^2 * 50
}
#[test]
fn test_backoff_with_unit() {
let mut backoff = Backoff::default().with_unit(100).with_jitter(0);
assert_eq!(backoff.next_backoff().as_millis(), 100); // 2^0 * 100
assert_eq!(backoff.next_backoff().as_millis(), 200); // 2^1 * 100
}
#[test]
fn test_backoff_with_min() {
let mut backoff = Backoff::default().with_min(100).with_jitter(0);
assert_eq!(backoff.next_backoff().as_millis(), 100); // clamped to min
}
#[test]
fn test_backoff_with_max() {
let mut backoff = Backoff::default().with_max(75).with_jitter(0);
assert_eq!(backoff.next_backoff().as_millis(), 50);
assert_eq!(backoff.next_backoff().as_millis(), 75); // clamped to max
}
#[test]
fn test_backoff_reset() {
let mut backoff = Backoff::default().with_jitter(0);
assert_eq!(backoff.next_backoff().as_millis(), 50);
assert_eq!(backoff.attempt(), 1);
backoff.reset();
assert_eq!(backoff.attempt(), 0);
assert_eq!(backoff.next_backoff().as_millis(), 50);
}
#[test]
fn test_slot_backoff() {
#[cfg_attr(coverage, coverage(off))]
fn assert_in(value: u128, expected: &[u128]) {
assert!(
expected.contains(&value),
"value {} not in {:?}",
value,
expected
);
}
for _ in 0..10 {
let mut backoff = SlotBackoff::default().with_unit(100);
assert_in(backoff.next_backoff().as_millis(), &[0, 100, 200, 300]);
assert_eq!(backoff.attempt(), 1);
assert_in(
backoff.next_backoff().as_millis(),
&[0, 100, 200, 300, 400, 500, 600, 700],
);
assert_eq!(backoff.attempt(), 2);
assert_in(
backoff.next_backoff().as_millis(),
&(0..16).map(|i| i * 100).collect::<Vec<_>>(),
);
assert_eq!(backoff.attempt(), 3);
}
}
#[test]
fn test_slot_backoff_high_attempt_is_bounded() {
// Without the slot cap the wait grows unbounded with `attempt`. The cap
// holds every backoff to `(MAX_SLOTS - 1) * unit`.
let unit = 100_000; // 100s first attempt
let mut backoff = SlotBackoff::default().with_unit(unit);
let max_backoff = Duration::from_millis((MAX_SLOTS - 1) as u64 * unit as u64);
for _ in 0..40 {
assert!(backoff.next_backoff() <= max_backoff);
}
assert_eq!(backoff.attempt(), 40);
}
#[test]
fn test_slot_backoff_large_unit_does_not_overflow() {
// With unit = u32::MAX, any slot >= 2 makes the old u32 `slot_i * unit`
// product overflow: a debug panic, or in release a wrap to a value that
// is no longer a multiple of unit. The u64 widening keeps every backoff
// an exact multiple of unit. Seed the RNG so the drawn slots — and thus
// this check — are deterministic rather than dependent on random draws.
let unit = u32::MAX;
let mut backoff = SlotBackoff::default().with_unit(unit);
backoff.rng = rand::rngs::SmallRng::seed_from_u64(0);
let mut saw_high_slot = false;
for _ in 0..64 {
let backoff_ms = backoff.next_backoff().as_millis();
// `slot_i * unit` is always a multiple of unit; a wrapped u32
// product is not.
assert_eq!(backoff_ms % unit as u128, 0, "{backoff_ms} wrapped");
saw_high_slot |= backoff_ms >= 2 * unit as u128;
}
assert!(saw_high_slot, "expected a slot >= 2 in 64 seeded draws");
}
#[test]
fn test_slot_backoff_attempt_saturates() {
// At u32::MAX the counter must stay put rather than panic (debug) or
// wrap to 0 (release), which would restart the low-slot distribution.
let mut backoff = SlotBackoff {
attempt: u32::MAX,
..Default::default()
};
let _ = backoff.next_backoff();
assert_eq!(backoff.attempt(), u32::MAX);
}
}
lance-artifact/rust/lance-core/src/utils/bit.rs
+153
View File
@@ -0,0 +1,153 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright The Lance Authors
/// Returns true if the given number is a power of two.
///
/// ```
/// use lance_core::utils::bit::is_pwr_two;
///
/// assert!(is_pwr_two(1));
/// assert!(is_pwr_two(2));
/// assert!(is_pwr_two(1024));
/// assert!(!is_pwr_two(3));
/// assert!(!is_pwr_two(1000));
/// ```
pub fn is_pwr_two(n: u64) -> bool {
n & (n - 1) == 0
}
/// Returns the number of padding bytes needed to align `n` to `ALIGN`.
///
/// ```
/// use lance_core::utils::bit::pad_bytes;
///
/// assert_eq!(pad_bytes::<8>(0), 0);
/// assert_eq!(pad_bytes::<8>(1), 7);
/// assert_eq!(pad_bytes::<8>(8), 0);
/// assert_eq!(pad_bytes::<8>(9), 7);
/// ```
pub fn pad_bytes<const ALIGN: usize>(n: usize) -> usize {
debug_assert!(is_pwr_two(ALIGN as u64));
(ALIGN - (n & (ALIGN - 1))) & (ALIGN - 1)
}
/// Returns the number of padding bytes needed to align `n` to `align`.
///
/// ```
/// use lance_core::utils::bit::pad_bytes_to;
///
/// assert_eq!(pad_bytes_to(0, 8), 0);
/// assert_eq!(pad_bytes_to(1, 8), 7);
/// assert_eq!(pad_bytes_to(8, 8), 0);
/// assert_eq!(pad_bytes_to(9, 8), 7);
/// ```
pub fn pad_bytes_to(n: usize, align: usize) -> usize {
debug_assert!(is_pwr_two(align as u64));
(align - (n & (align - 1))) & (align - 1)
}
/// Returns the number of padding bytes needed to align `n` to `ALIGN` (u64 version).
///
/// ```
/// use lance_core::utils::bit::pad_bytes_u64;
///
/// assert_eq!(pad_bytes_u64::<8>(0), 0);
/// assert_eq!(pad_bytes_u64::<8>(1), 7);
/// assert_eq!(pad_bytes_u64::<8>(8), 0);
/// assert_eq!(pad_bytes_u64::<8>(9), 7);
/// ```
pub fn pad_bytes_u64<const ALIGN: u64>(n: u64) -> u64 {
debug_assert!(is_pwr_two(ALIGN));
(ALIGN - (n & (ALIGN - 1))) & (ALIGN - 1)
}
// This is a lookup table for the log2 of the first 256 numbers
const LOG_TABLE_256: [u8; 256] = [
0, 1, 2, 2, 3, 3, 3, 3, 4, 4, 4, 4, 4, 4, 4, 4, 5, 5, 5, 5, 5, 5, 5, 5, 5, 5, 5, 5, 5, 5, 5, 5,
6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6,
7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7,
7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7, 7,
8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8,
8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8,
8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8,
8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8, 8,
];
/// Returns the number of bits needed to represent the given number.
///
/// Inspired by <https://graphics.stanford.edu/~seander/bithacks.html>
///
/// ```
/// use lance_core::utils::bit::log_2_ceil;
///
/// assert_eq!(log_2_ceil(1), 1);
/// assert_eq!(log_2_ceil(2), 2);
/// assert_eq!(log_2_ceil(255), 8);
/// assert_eq!(log_2_ceil(256), 9);
/// ```
pub fn log_2_ceil(val: u32) -> u32 {
assert!(val > 0);
let upper_half = val >> 16;
if upper_half == 0 {
let third_quarter = val >> 8;
if third_quarter == 0 {
// Use lowest 8 bits (upper 24 are 0)
LOG_TABLE_256[val as usize] as u32
} else {
// Use bits 16..24 (0..16 are 0)
LOG_TABLE_256[third_quarter as usize] as u32 + 8
}
} else {
let first_quarter = upper_half >> 8;
if first_quarter == 0 {
// Use bits 8..16 (0..8 are 0)
16 + LOG_TABLE_256[upper_half as usize] as u32
} else {
// Use most significant bits (it's a big number!)
24 + LOG_TABLE_256[first_quarter as usize] as u32
}
}
}
#[cfg(test)]
mod tests {
use crate::utils::bit::{is_pwr_two, log_2_ceil, pad_bytes, pad_bytes_to, pad_bytes_u64};
#[test]
fn test_bit_utils() {
// Test values not in doctests
assert!(is_pwr_two(4));
assert!(is_pwr_two(1024));
assert!(!is_pwr_two(5));
// Test different alignment (64) not shown in doctests
assert_eq!(pad_bytes::<64>(100), 28);
assert_eq!(pad_bytes_to(100, 64), 28);
assert_eq!(pad_bytes_u64::<64>(100), 28);
}
#[test]
fn test_log_2_ceil() {
#[cfg_attr(coverage, coverage(off))]
fn classic_approach(mut val: u32) -> u32 {
let mut counter = 0;
while val > 0 {
val >>= 1;
counter += 1;
}
counter
}
for i in 1..(16 * 1024) {
assert_eq!(log_2_ceil(i), classic_approach(i));
}
assert_eq!(log_2_ceil(50 * 1024), classic_approach(50 * 1024));
assert_eq!(
log_2_ceil(1024 * 1024 * 1024),
classic_approach(1024 * 1024 * 1024)
);
// Cover the branch where upper_half != 0 but first_quarter == 0
// (value between 2^16 and 2^24)
assert_eq!(log_2_ceil(100_000), classic_approach(100_000));
}
}
lance-artifact/rust/lance-core/src/utils/blob.rs
+46
View File
@@ -0,0 +1,46 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright The Lance Authors
use object_store::path::Path;
/// Format a blob sidecar path for a data file.
///
/// Layout: `<base>/<data_file_key>/<obfuscated_blob_id>.blob`
/// - `base` is typically the dataset's data directory.
/// - `data_file_key` is the stem of the data file (without extension).
/// - `blob_id` is transformed via `reverse_bits()` before binary formatting.
pub fn blob_path(base: &Path, data_file_key: &str, blob_id: u32) -> Path {
let file_name = format!("{:032b}.blob", blob_id.reverse_bits());
base.clone().join(data_file_key).join(file_name.as_str())
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn test_blob_path_formatting() {
let base = Path::from("base");
let path = blob_path(&base, "deadbeef", 2);
assert_eq!(
path.to_string(),
"base/deadbeef/01000000000000000000000000000000.blob"
);
}
#[test]
fn test_blob_path_scattered_prefixes_for_sequential_ids() {
let base = Path::from("base");
let p1 = blob_path(&base, "deadbeef", 1);
let p2 = blob_path(&base, "deadbeef", 2);
assert_ne!(p1.to_string(), p2.to_string());
assert_eq!(
p1.to_string(),
"base/deadbeef/10000000000000000000000000000000.blob"
);
assert_eq!(
p2.to_string(),
"base/deadbeef/01000000000000000000000000000000.blob"
);
}
}
lance-artifact/rust/lance-core/src/utils/bloomfilter.rs
+10
View File
@@ -0,0 +1,10 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright The Lance Authors
//! Generic bloom filter primitives.
//!
//! These are storage-agnostic data structures with no Lance semantics, used by
//! higher-level crates (e.g. the bloom filter scalar index in `lance-index`).
pub mod as_bytes;
pub mod sbbf;
lance-artifact/rust/lance-core/src/utils/bloomfilter/as_bytes.rs
+164
View File
@@ -0,0 +1,164 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright The Lance Authors
//! Local implementation of AsBytes trait
//!
//! This trait provides conversion from primitive types to byte slices,
//! similar to parquet::data_type::AsBytes but without the external dependency.
/// Trait to convert primitive types to byte slices
/// Reference: <https://arrow.apache.org/rust/src/parquet/data_type.rs.html>
pub trait AsBytes {
/// Convert the value to a byte slice
fn as_bytes(&self) -> impl AsRef<[u8]>;
}
impl AsBytes for i32 {
fn as_bytes(&self) -> impl AsRef<[u8]> {
self.to_le_bytes()
}
}
impl AsBytes for i64 {
fn as_bytes(&self) -> impl AsRef<[u8]> {
self.to_le_bytes()
}
}
impl AsBytes for f32 {
fn as_bytes(&self) -> impl AsRef<[u8]> {
self.to_le_bytes()
}
}
impl AsBytes for f64 {
fn as_bytes(&self) -> impl AsRef<[u8]> {
self.to_le_bytes()
}
}
impl AsBytes for u8 {
fn as_bytes(&self) -> impl AsRef<[Self]> {
[*self]
}
}
impl AsBytes for u16 {
fn as_bytes(&self) -> impl AsRef<[u8]> {
self.to_le_bytes()
}
}
impl AsBytes for u32 {
fn as_bytes(&self) -> impl AsRef<[u8]> {
self.to_le_bytes()
}
}
impl AsBytes for u64 {
fn as_bytes(&self) -> impl AsRef<[u8]> {
self.to_le_bytes()
}
}
impl AsBytes for i8 {
fn as_bytes(&self) -> impl AsRef<[u8]> {
[*self as u8]
}
}
impl AsBytes for i16 {
fn as_bytes(&self) -> impl AsRef<[u8]> {
self.to_le_bytes()
}
}
impl AsBytes for str {
fn as_bytes(&self) -> impl AsRef<[u8]> {
Self::as_bytes(self)
}
}
impl AsBytes for [u8] {
fn as_bytes(&self) -> impl AsRef<[u8]> {
self
}
}
impl AsBytes for bool {
fn as_bytes(&self) -> impl AsRef<[u8]> {
if *self { [1u8] } else { [0u8] }
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn test_i32_as_bytes() {
let val = 0x12345678i32;
let bytes = val.as_bytes();
assert_eq!(bytes.as_ref().len(), 4);
// Check that we get the expected bytes in little-endian format
assert_eq!(bytes.as_ref(), &[0x78, 0x56, 0x34, 0x12]);
}
#[test]
fn test_i64_as_bytes() {
let val = 0x123456789ABCDEF0i64;
let bytes = val.as_bytes();
assert_eq!(bytes.as_ref().len(), 8);
// Check that we get the expected bytes in little-endian format
assert_eq!(
bytes.as_ref(),
&[0xF0, 0xDE, 0xBC, 0x9A, 0x78, 0x56, 0x34, 0x12]
);
}
#[test]
fn test_f32_as_bytes() {
let val = 1.0f32;
let bytes = val.as_bytes();
assert_eq!(bytes.as_ref().len(), 4);
// f32 representation of 1.0 is [0x00, 0x00, 0x80, 0x3F] in little-endian
assert_eq!(bytes.as_ref(), &[0x00, 0x00, 0x80, 0x3F]);
}
#[test]
fn test_f64_as_bytes() {
let val = 1.0f64;
let bytes = val.as_bytes();
assert_eq!(bytes.as_ref().len(), 8);
// f64 representation of 1.0 is [0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0xF0, 0x3F] in little-endian
assert_eq!(
bytes.as_ref(),
&[0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0xF0, 0x3F]
);
}
#[test]
fn test_str_as_bytes() {
let val = "hello";
let bytes = AsBytes::as_bytes(val);
assert_eq!(bytes.as_ref(), b"hello");
}
#[test]
fn test_slice_as_bytes() {
let val: &[u8] = &[1, 2, 3, 4, 5];
let bytes = val.as_bytes();
assert_eq!(bytes.as_ref(), &[1, 2, 3, 4, 5]);
}
#[test]
fn test_bool_as_bytes() {
let val_true = true;
let bytes_true = val_true.as_bytes();
assert_eq!(bytes_true.as_ref(), &[1u8]);
let val_false = false;
let bytes_false = val_false.as_bytes();
assert_eq!(bytes_false.as_ref(), &[0u8]);
}
}
lance-artifact/rust/lance-core/src/utils/bloomfilter/sbbf.rs
+620
View File
@@ -0,0 +1,620 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright The Lance Authors
// Licensed to the Apache Software Foundation (ASF) under one
// or more contributor license agreements. See the NOTICE file
// distributed with this work for additional information
// regarding copyright ownership. The ASF licenses this file
// to you under the Apache License, Version 2.0 (the
// "License"); you may not use this file except in compliance
// with the License. You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing,
// software distributed under the License is distributed on an
// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
// KIND, either express or implied. See the License for the
// specific language governing permissions and limitations
// under the License.
//! Split Block Bloom Filter (SBBF) implementation for Lance
//!
//! Based on the Apache Arrow Parquet SBBF implementation but with public APIs
//! for use in Lance indexing. This implementation follows the Parquet spec
//! <https://github.com/apache/arrow-rs/blob/main/parquet/src/bloom_filter/mod.rs>
//! for SBBF as described in <https://github.com/apache/parquet-format/blob/master/BloomFilter.md>
//! FIXME: Make the upstream SBBF implementation public so that this file could be
//! removed from Lance.
//! <https://github.com/apache/arrow-rs/issues/8277>
use super::as_bytes::AsBytes;
use libm::lgamma;
use std::error::Error;
use std::fmt;
use std::io::Write;
use twox_hash::XxHash64;
#[derive(Debug)]
pub enum SbbfError {
InvalidFpp { fpp: f64 },
WriteError { source: std::io::Error },
InvalidData { message: String },
}
impl fmt::Display for SbbfError {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
match self {
Self::InvalidFpp { fpp } => {
write!(
f,
"False positive probability must be between 0.0 and 1.0, got {}",
fpp
)
}
Self::WriteError { source } => {
write!(f, "Failed to write bloom filter: {}", source)
}
Self::InvalidData { message } => {
write!(f, "Invalid bloom filter data: {}", message)
}
}
}
}
impl Error for SbbfError {
fn source(&self) -> Option<&(dyn Error + 'static)> {
match self {
Self::WriteError { source } => Some(source),
_ => None,
}
}
}
pub type Result<T> = std::result::Result<T, SbbfError>;
/// Salt as defined in the Parquet spec
const SALT: [u32; 8] = [
0x47b6137b_u32,
0x44974d91_u32,
0x8824ad5b_u32,
0xa2b7289d_u32,
0x705495c7_u32,
0x2df1424b_u32,
0x9efc4947_u32,
0x5c6bfb31_u32,
];
/// Each block is 256 bits, broken up into eight contiguous "words", each consisting of 32 bits.
/// Each word is thought of as an array of bits; each bit is either "set" or "not set".
#[derive(Debug, Copy, Clone)]
struct Block([u32; 8]);
impl Block {
const ZERO: Self = Self([0; 8]);
/// Takes as its argument a single unsigned 32-bit integer and returns a block in which each
/// word has exactly one bit set.
fn mask(x: u32) -> Self {
let mut result = [0_u32; 8];
for i in 0..8 {
// wrapping instead of checking for overflow
let y = x.wrapping_mul(SALT[i]);
let y = y >> 27;
result[i] = 1 << y;
}
Self(result)
}
#[inline]
#[cfg(target_endian = "little")]
fn to_le_bytes(self) -> [u8; 32] {
self.to_ne_bytes()
}
#[inline]
#[cfg(not(target_endian = "little"))]
fn to_le_bytes(self) -> [u8; 32] {
self.swap_bytes().to_ne_bytes()
}
#[inline]
fn to_ne_bytes(self) -> [u8; 32] {
// SAFETY: [u32; 8] and [u8; 32] have the same size and neither has invalid bit patterns.
unsafe { std::mem::transmute(self.0) }
}
#[inline]
#[cfg(not(target_endian = "little"))]
fn swap_bytes(mut self) -> Self {
self.0.iter_mut().for_each(|x| *x = x.swap_bytes());
self
}
/// Setting every bit in the block that was also set in the result from mask
fn insert(&mut self, hash: u32) {
let mask = Self::mask(hash);
for i in 0..8 {
self[i] |= mask[i];
}
}
/// Returns true when every bit that is set in the result of mask is also set in the block.
fn check(&self, hash: u32) -> bool {
let mask = Self::mask(hash);
for i in 0..8 {
if self[i] & mask[i] == 0 {
return false;
}
}
true
}
}
impl std::ops::Index<usize> for Block {
type Output = u32;
#[inline]
fn index(&self, index: usize) -> &Self::Output {
self.0.index(index)
}
}
impl std::ops::IndexMut<usize> for Block {
#[inline]
fn index_mut(&mut self, index: usize) -> &mut Self::Output {
self.0.index_mut(index)
}
}
// This implements the false positive probability in Putze et al.'s "Cache-, hash-and
// space-efficient bloom filters", equation 3.
#[inline]
fn false_positive_probability(ndv: u64, log_space_bytes: u8) -> f64 {
const WORD_BITS: f64 = 32.0;
const BUCKET_WORDS: f64 = 8.0;
let bytes = (1u64 << log_space_bytes) as f64;
let ndv = ndv as f64;
if ndv == 0.0 {
return 0.0;
}
// This short-cuts a slowly-converging sum for very dense filters
if ndv / (bytes * u8::BITS as f64) > 2.0 {
return 1.0;
}
let mut result: f64 = 0.0;
// lam is the usual parameter to the Poisson's PMF. Following the notation in the paper,
// lam is B/c, where B is the number of bits in a bucket and c is the number of bits per
// distinct value
let lam = BUCKET_WORDS * WORD_BITS / ((bytes * u8::BITS as f64) / ndv);
// Some of the calculations are done in log-space to increase numerical stability
let loglam = lam.ln();
// 750 iterations are sufficient to cause the sum to converge in all of the tests. In
// other words, setting the iterations higher than 750 will give the same result as
// leaving it at 750.
const ITERS: i32 = 750;
// We start with the highest value of i, since the values we're adding to result are
// mostly smaller at high i, and this increases accuracy to sum from the smallest
// values up.
for i in (0..ITERS).rev() {
// The PMF of the Poisson distribution is lam^i * exp(-lam) / i!. In logspace, using
// lgamma for the log of the factorial function:
let logp = i as f64 * loglam - lam - lgamma((i + 1).into());
// The f_inner part of the equation in the paper is the probability of a single
// collision in the bucket. Since there are kBucketWords non-overlapping lanes in each
// bucket, the log of this probability is:
let logfinner = BUCKET_WORDS * (1.0 - (1.0 - 1.0 / WORD_BITS).powi(i)).ln();
// Here we are forced out of log-space calculations
result += (logp + logfinner).exp();
}
result.min(1.0)
}
/// Minimum and maximum filter sizes
const BITSET_LOG2_MIN_BYTES: u8 = 5; // 32B (1 Block)
const BITSET_LOG2_MAX_BYTES: u8 = 27; // 128MiB
#[inline]
fn min_log2_bytes(ndv: u64, fpp: f64) -> u8 {
let mut low = 0;
let mut high = 64;
while high > low + 1 {
let mid = (high + low) / 2;
let candidate = false_positive_probability(ndv, mid);
if candidate <= fpp {
high = mid;
} else {
low = mid;
}
}
high
}
/// A Split Block Bloom Filter (SBBF) implementation
///
/// This is a high-performance bloom filter optimized for SIMD operations,
/// compatible with the Parquet specification.
#[derive(Debug, Clone)]
pub struct Sbbf {
blocks: Vec<Block>,
}
impl Sbbf {
/// Create a new SBBF from raw bitset data
pub fn new(bitset: &[u8]) -> Result<Self> {
if !bitset.len().is_multiple_of(32) {
return Err(SbbfError::InvalidData {
message: format!(
"Bitset length must be a multiple of 32, got {}",
bitset.len()
),
});
}
let data = bitset
.chunks_exact(4 * 8)
.map(|chunk| {
let mut block = Block::ZERO;
for (i, word) in chunk.chunks_exact(4).enumerate() {
block[i] = u32::from_le_bytes(word.try_into().unwrap());
}
block
})
.collect::<Vec<Block>>();
Ok(Self { blocks: data })
}
/// Create a new empty SBBF with the given number of bytes
/// The actual size will be adjusted to the next power of two within bounds
pub fn with_log2_num_bytes(log2_num_bytes: u8) -> Self {
let num_bytes =
1_usize << log2_num_bytes.clamp(BITSET_LOG2_MIN_BYTES, BITSET_LOG2_MAX_BYTES);
let bitset = vec![0_u8; num_bytes];
// unwrap is safe because we know the size is valid
Self::new(&bitset).unwrap()
}
/// Create a new SBBF with given number of distinct values and false positive probability
pub fn with_ndv_fpp(ndv: u64, fpp: f64) -> Result<Self> {
if !(0.0..1.0).contains(&fpp) {
return Err(SbbfError::InvalidFpp { fpp });
}
let log2_num_bytes = min_log2_bytes(ndv, fpp);
Ok(Self::with_log2_num_bytes(log2_num_bytes))
}
/// Get the hash-to-block-index for a given hash
#[inline]
fn hash_to_block_index(&self, hash: u64) -> usize {
(((hash >> 32).saturating_mul(self.blocks.len() as u64)) >> 32) as usize
}
/// Insert an AsBytes value into the filter
pub fn insert<T: AsBytes + ?Sized>(&mut self, value: &T) {
self.insert_hash(hash_as_bytes(value));
}
/// Insert a hash into the filter
pub fn insert_hash(&mut self, hash: u64) {
let block_index = self.hash_to_block_index(hash);
self.blocks[block_index].insert(hash as u32)
}
/// Check if an AsBytes value is probably present or definitely absent in the filter
pub fn check<T: AsBytes + ?Sized>(&self, value: &T) -> bool {
self.check_hash(hash_as_bytes(value))
}
/// Check if a hash is in the filter. May return
/// true for values that were never inserted ("false positive")
/// but will always return false if a hash has not been inserted.
pub fn check_hash(&self, hash: u64) -> bool {
let block_index = self.hash_to_block_index(hash);
self.blocks[block_index].check(hash as u32)
}
/// Write the bitset in serialized form to the writer
pub fn write_bitset<W: Write>(&self, mut writer: W) -> Result<()> {
for block in &self.blocks {
writer
.write_all(block.to_le_bytes().as_slice())
.map_err(|source| SbbfError::WriteError { source })?;
}
Ok(())
}
/// Get the raw bitset as bytes
pub fn to_bytes(&self) -> Vec<u8> {
let mut result = Vec::with_capacity(self.blocks.len() * 32);
for block in &self.blocks {
result.extend_from_slice(&block.to_le_bytes());
}
result
}
/// Get the number of blocks in this filter
pub fn num_blocks(&self) -> usize {
self.blocks.len()
}
/// Get the size in bytes of this filter
pub fn size_bytes(&self) -> usize {
self.blocks.len() * 32
}
/// Return the total in memory size of this bloom filter in bytes
pub fn estimated_memory_size(&self) -> usize {
self.blocks.capacity() * std::mem::size_of::<Block>()
}
/// Check if this filter might intersect with another filter.
/// Returns true if there's at least one bit position where both filters have a 1.
/// This is a fast check that may return false positives but never false negatives.
///
/// Returns an error if the filters have different sizes, as bloom filters with
/// different configurations cannot be reliably compared.
pub fn might_intersect(&self, other: &Self) -> Result<bool> {
if self.blocks.len() != other.blocks.len() {
return Err(SbbfError::InvalidData {
message: format!(
"Cannot compare bloom filters with different sizes: {} blocks vs {} blocks. \
Both filters must use the same configuration.",
self.blocks.len(),
other.blocks.len()
),
});
}
for i in 0..self.blocks.len() {
for j in 0..8 {
if (self.blocks[i][j] & other.blocks[i][j]) != 0 {
return Ok(true);
}
}
}
Ok(false)
}
/// Check if this filter might intersect with a raw bitmap.
/// The bitmap should be in the same format as produced by to_bytes().
///
/// Returns an error if the bitmaps have different sizes, as bloom filters with
/// different configurations cannot be reliably compared.
pub fn might_intersect_bytes(&self, other_bytes: &[u8]) -> Result<bool> {
Self::bytes_might_intersect(&self.to_bytes(), other_bytes)
}
/// Check if two raw bloom filter bitmaps might intersect.
/// Returns true if there's at least one bit position where both filters have a 1.
///
/// This is a fast probabilistic check: if it returns false, the filters definitely
/// have no common elements. If it returns true, they might have common elements
/// (with possible false positives).
///
/// Returns an error if the bitmaps have different sizes, as bloom filters with
/// different configurations cannot be reliably compared.
pub fn bytes_might_intersect(a: &[u8], b: &[u8]) -> Result<bool> {
if a.len() != b.len() {
return Err(SbbfError::InvalidData {
message: format!(
"Cannot compare bloom filters with different sizes: {} bytes vs {} bytes. \
Both filters must use the same configuration.",
a.len(),
b.len()
),
});
}
for i in 0..a.len() {
if (a[i] & b[i]) != 0 {
return Ok(true);
}
}
Ok(false)
}
}
// Per spec we use xxHash with seed=0
const SEED: u64 = 0;
#[inline]
fn hash_as_bytes<A: AsBytes + ?Sized>(value: &A) -> u64 {
XxHash64::oneshot(SEED, value.as_bytes().as_ref())
}
/// Builder for creating SBBF instances with a fluent API
pub struct SbbfBuilder {
ndv: Option<u64>,
fpp: Option<f64>,
log2_num_bytes: Option<u8>,
}
impl SbbfBuilder {
/// Create a new SBBF builder
pub fn new() -> Self {
Self {
ndv: None,
fpp: None,
log2_num_bytes: None,
}
}
/// Set the expected number of distinct values
pub fn expected_items(mut self, ndv: u64) -> Self {
self.ndv = Some(ndv);
self
}
/// Set the desired false positive probability
pub fn false_positive_probability(mut self, fpp: f64) -> Self {
self.fpp = Some(fpp);
self
}
/// Set the number of bytes directly
pub fn log2_num_bytes(mut self, log2_num_bytes: u8) -> Self {
self.log2_num_bytes = Some(log2_num_bytes);
self
}
/// Build the SBBF
pub fn build(self) -> Result<Sbbf> {
if let Some(log2_num_bytes) = self.log2_num_bytes {
Ok(Sbbf::with_log2_num_bytes(log2_num_bytes))
} else if let (Some(ndv), Some(fpp)) = (self.ndv, self.fpp) {
Sbbf::with_ndv_fpp(ndv, fpp)
} else {
Err(SbbfError::InvalidData {
message: "Must specify either log2_num_bytes or both ndv and fpp".to_string(),
})
}
}
}
impl Default for SbbfBuilder {
fn default() -> Self {
Self::new()
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn test_hash_bytes() {
assert_eq!(hash_as_bytes(""), 17241709254077376921);
}
#[test]
fn test_mask_set_quick_check() {
for i in 0..1_000 {
let result = Block::mask(i);
assert!(result.0.iter().all(|&x| x.is_power_of_two()));
}
}
#[test]
fn test_block_insert_and_check() {
for i in 0..1_000 {
let mut block = Block::ZERO;
block.insert(i);
assert!(block.check(i));
}
}
#[test]
fn test_sbbf_insert_and_check() {
let mut sbbf = Sbbf::with_log2_num_bytes(10);
for i in 0..1_000 {
sbbf.insert(&i);
assert!(sbbf.check(&i));
}
}
#[test]
fn test_sbbf_builder() {
let sbbf = SbbfBuilder::new()
.expected_items(1000)
.false_positive_probability(0.01)
.build()
.unwrap();
assert!(sbbf.num_blocks() > 0);
}
#[test]
fn test_sbbf_string_types() {
let mut sbbf = SbbfBuilder::new()
.expected_items(100)
.false_positive_probability(0.01)
.build()
.unwrap();
// Test different string types
let string_val = "hello";
let str_val = "world";
let bytes_val = b"bytes";
sbbf.insert(string_val);
sbbf.insert(str_val);
sbbf.insert(&bytes_val[..]);
assert!(sbbf.check(string_val));
assert!(sbbf.check(str_val));
assert!(sbbf.check(&bytes_val[..]));
assert!(!sbbf.check("not_inserted"));
}
#[test]
fn test_sbbf_numeric_types() {
let mut sbbf = SbbfBuilder::new()
.expected_items(100)
.false_positive_probability(0.01)
.build()
.unwrap();
// Test different numeric types
let i32_val = 42i32;
let i64_val = 12345i64;
let f64_val = std::f64::consts::PI;
let bool_val = true;
sbbf.insert(&i32_val);
sbbf.insert(&i64_val);
sbbf.insert(&f64_val);
sbbf.insert(&bool_val);
assert!(sbbf.check(&i32_val));
assert!(sbbf.check(&i64_val));
assert!(sbbf.check(&f64_val));
assert!(sbbf.check(&bool_val));
assert!(!sbbf.check(&999i32));
}
#[test]
fn test_num_of_bits_from_ndv_fpp() {
for (fpp, ndv, log2_num_bytes) in &[
(0.1, 10, 3),
(0.01, 10, 4),
(0.001, 10, 5),
(0.1, 100, 7),
(0.01, 100, 8),
(0.001, 100, 8),
(0.1, 1000, 10),
(0.01, 1000, 11),
(0.001, 1000, 12),
] {
assert_eq!(*log2_num_bytes, min_log2_bytes(*ndv, *fpp));
}
}
#[test]
fn test_serialization() {
let mut sbbf = SbbfBuilder::new()
.expected_items(100)
.false_positive_probability(0.01)
.build()
.unwrap();
// Insert some values
for i in 0..50 {
sbbf.insert(&i);
}
// Serialize to bytes
let bytes = sbbf.to_bytes();
assert!(!bytes.is_empty());
assert_eq!(bytes.len(), sbbf.size_bytes());
// Deserialize from bytes
let sbbf2 = Sbbf::new(&bytes).unwrap();
assert_eq!(sbbf.num_blocks(), sbbf2.num_blocks());
// Check that deserialized filter works
for i in 0..50 {
assert!(sbbf2.check(&i));
}
assert!(!sbbf2.check(&999));
}
}

Some files were not shown because too many files have changed in this diff Show More