python wrapper for lance-rs
Project description
Python bindings for Lance Data Format
:warning: Under heavy development
Lance is a new columnar data format for data science and machine learning
Why you should use Lance
- Is order of magnitude faster than parquet for point queries and nested data structures common to DS/ML
- Comes with a fast vector index that delivers sub-millisecond nearest neighbors search performance
- Is automatically versioned and supports lineage and time-travel for full reproducibility
- Integrated with duckdb/pandas/polars already. Easily convert from/to parquet in 2 lines of code
Quick start
Installation
pip install pylance
Make sure you have a recent version of pandas (1.5+), pyarrow (10.0+), and DuckDB (0.7.0+)
Converting to Lance
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
dataset = lance.dataset("/tmp/test.lance")
assert isinstance(dataset, pa.dataset.Dataset)
Pandas
df = dataset.to_table().to_pandas()
DuckDB
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
wget ftp://ftp.irisa.fr/local/texmex/corpus/sift.tar.gz
tar -xzf sift.tar.gz
Convert it to Lance
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
sift1m.create_index("vector",
index_type="IVF_PQ",
num_partitions=256, # IVF
num_sub_vectors=16) # PQ
Search the dataset
# 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]
*More distance metrics, HNSW, and distributed support is on the roadmap
Python package details
Install from PyPI: pip install pylance # >=0.3.0 is the new rust-based implementation
Install from source: maturin develop (under the /python directory)
Import via: import lance
The python integration is done via pyo3 + custom python code:
- We make wrapper classes in Rust for Dataset/Scanner/RecordBatchReader that's exposed to python.
- These are then used by LanceDataset / LanceScanner implementations that extend pyarrow Dataset/Scanner for duckdb compat.
- Data is delivered via the Arrow C Data Interface
Motivation
Why do we need a new format for data science and machine learning?
1. Reproducibility is a must-have
Versioning and experimentation support should be built into the dataset instead of requiring multiple tools.
It should also be efficient and not require expensive copying everytime you want to create a new version.
We call this "Zero copy versioning" in Lance. It makes versioning data easy without increasing storage costs.
2. Cloud storage is now the default
Remote object storage is the default now for data science and machine learning and the performance characteristics of cloud are fundamentally different.
Lance format is optimized to be cloud native. Common operations like filter-then-take can be order of magnitude faster
using Lance than Parquet, especially for ML data.
3. Vectors must be a first class citizen, not a separate thing
The majority of reasonable scale workflows should not require the added complexity and cost of a specialized database just to compute vector similarity. Lance integrates optimized vector indices into a columnar format so no additional infrastructure is required to get low latency top-K similarity search.
4. Open standards is a requirement
The DS/ML ecosystem is incredibly rich and data must be easily accessible across different languages, tools, and environments. Lance makes Apache Arrow integration its primary interface, which means conversions to/from is 2 lines of code, your code does not need to change after conversion, and nothing is locked-up to force you to pay for vendor compute. We need open-source not fauxpen-source.
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distributions
Built Distributions
Hashes for pylance-0.6.4-cp38-abi3-win_amd64.whl
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | 78ba2de4de19d688048313ce87142d261e3a03056ee3cb873698a2792cc3c4a1 |
|
| MD5 | 40f3a1d7bbc6a02428bbb89d0c23783a |
|
| BLAKE2b-256 | ed7fe450b3bc03c18c1fd8fd5f15663230da601d497028b366a77bea56bca618 |
Hashes for pylance-0.6.4-cp38-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | 035e061e587ba28521c1c963a2448e12f2020a1c0c6f7309cfe52672fca87c27 |
|
| MD5 | b1b271db29d8d1eeeb1a806e17d88c59 |
|
| BLAKE2b-256 | 65576c8e8c0e263c4c5d632238369504cf900e967a0f9e6c07a248a296b1fb39 |
Hashes for pylance-0.6.4-cp38-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | 5d6909ac01f150d813067c908cf4000e941bc670d92b47718bde1e00af30c1f4 |
|
| MD5 | d51e017d15c3b3408b3501ff7c60dd25 |
|
| BLAKE2b-256 | 814fb39bb829f7f3c1ca1b1168ee514b0880c93b4f0c73a5db4f6488893a77ef |
Hashes for pylance-0.6.4-cp38-abi3-macosx_11_0_arm64.whl
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | b7df23abc0a37991958ddb15f742fa3d8d65f579f451f8db3241136f3f6a5638 |
|
| MD5 | d27ac1386cf2e3d2a015ab77a6e79623 |
|
| BLAKE2b-256 | f90937e9da7cfb22acbde255cafc60f39454273f8ec5ce16bc1872e7e7d4e17a |
Hashes for pylance-0.6.4-cp38-abi3-macosx_10_15_x86_64.whl
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | b57895de4237966e6f9a1f3309a522f796d5768e9b55b138dcebd1301aeaf2b1 |
|
| MD5 | 21c7c137f27db486fe34eb89736b3d49 |
|
| BLAKE2b-256 | 82419e0264cd42cc58d09f07c703b0352a76ad62dc1d58dad7fe3d1d3ecab1c2 |
