Metadata-Version: 2.3
Name: hypersync-lancedb-pipe
Version: 0.1.0
Summary: A serverless embedded streaming OLAP data pipeline
Author-email: Evan K <ekcopersonal@gmail.com>
Requires-Python: >=3.8
Requires-Dist: boto3>=1.34.94
Requires-Dist: duckdb>=0.10.2
Requires-Dist: hvplot>=0.9.2
Requires-Dist: hypersync==0.6.1
Requires-Dist: ipykernel>=6.29.4
Requires-Dist: lancedb>=0.6.11
Requires-Dist: polars>=0.20.23
Requires-Dist: pyarrow==15.0.0
Description-Content-Type: text/markdown

# hypersync-lancedb-pipe

A serverless embedded streaming OLAP data pipeline that leverages historical blockchain data from [Hypersync](https://github.com/enviodev/hypersync-client-python) and mutable columnar storage format [lance](https://lancedb.github.io/lance/).

Since Lance is designed to be mutable, it is possible to create an embedded streaming pipeline using the same data source. The main advantage of this streaming approach is that it doesn't require any parquet glob file management. This reduces the complexity of streaming to the same as batch processing. The other main benefit is that LanceDB has tight integration with both
[polars](https://lancedb.github.io/lancedb/python/polars_arrow/#from-polars-dataframe) and [duckdb](https://lancedb.github.io/lancedb/python/duckdb/). LanceDB accepts polars dataframes as
data inputs, which allows for a more flexible ETL pipeline, allowing polars to be used as a preprocessing tool. 

Since LanceDB leverages the [Apache Arrow Standard](https://arrow.apache.org/overview/), there is a lot of flexibility to query from ths database - such as querying larger than memory
datasets with polars lazyframes and a dataframe API, or using an embedded OLAP engine like duckdb for faster speed and SQL API.

### Getting Started
1. This repository uses rye to manage dependencies and the virtual environment. To install, refer to this link for instructions [here](https://rye-up.com/guide/installation/). 
2. Once rye is installed, run `rye sync` to install dependencies and setup the virtual environment, which has a default name of `.venv`. 
3. Activate the virtual environment with the command `source .venv/bin/activate`.

### Running the Pipeline
There are some script examples in the `scripts` folder. These examples demonstrate the versatility of the lancedb writer.

* Run `historical_sync.py` file to backfill data from a historical block number. Assumes there is no existing table.
* Run `head_sync.py` to sync the database to the head of the chain. Assumes existing table exists.
* Run `backfill_sync.py` to perform a backfill sync from the earliest block number. Assumes existing table exists.