dmitrykoval/vinum — 64 Stars

Topics

#arrow #data-analysis #numpy #olap #python #sql

Language breakdown

C++ 45.3%

Python 42.1%

Jupyter Notebook 12.1%

CMake 0.5%

▸ Files click to expand

README

Vinum

|PyPi| |CI| |GradePython| |Codecov|_

.. |PyPi| image:: https://img.shields.io/pypi/v/vinum.svg .. _PyPi: https://pypi.org/project/vinum/

.. |CI| image:: https://github.com/dmitrykoval/vinum/actions/workflows/ci.yml/badge.svg .. _CI: https://github.com/dmitrykoval/vinum/actions/workflows/ci.yml

.. |Grade_Python| image:: https://img.shields.io/lgtm/grade/python/g/dmitrykoval/vinum.svg?logo=lgtm&logoWidth=18 .. GradePython: https://lgtm.com/projects/g/dmitrykoval/vinum/context:python

.. |Codecov| image:: https://codecov.io/gh/dmitrykoval/vinum/branch/main/graphs/badge.svg?branch=main&service=github .. _Codecov: https://codecov.io/gh/dmitrykoval/vinum?branch=main

Vinum is a SQL query processor for Python, designed for data analysis workflows and in-memory analytics.

When should I use Vinum? ======================== Vinum is running inside of the host Python process and allows to execute any functions available to the interpreter as UDFs. If you are doing data analysis or running ETL in Python, Vinum allows to execute efficient SQL queries with an ability to call native Python UDFs.

Key Features: =============

Vinum is running inside of the host Python process and has a hybrid query

execution model - whenever possible it would prefer native compiled version of operators and only executes Python interpreted code where strictly necessary (ie. for native Python UDFs).

Allows to use functions available within the host Python interpreter

as UDFs, including native Python, NumPy, etc.

Vinum's execution model doesn't require input datasets to fit into memory,

as it operates on a stream of record batches. However, the final result is fully materialized in memory.

Written in the mix of C++ and Python and is built from ground up on top of

Apache Arrow <https://arrow.apache.org/>_, which provides the foundation for moving data and enables minimal overhead for transferring data to and from Numpy and Pandas.

Architecture ============ .. image:: https://github.com/dmitrykoval/vinum/raw/main/doc/source/_static/architecture.png

Vinum uses PostgresSQL parser provided by pglast <https://github.com/lelit/pglast>_ project.

Query planner and executor are implemented in Python, while all the physical operators are either implemented in C++ or use compiled vectorized kernels from Arrow or NumPy. The only exception to this is native python UDFs, which are running within interpreted Python.

Query execution model is based on the vectorized model described in the prolific paper by P. A. Boncz, M. Zukowski, and N. Nes. Monetdb/x100: Hyper-pipelining query execution. In CIDR, 2005. <https://ir.cwi.nl/pub/16497/16497B.pdf>_

Example of a query plan:

.. image:: https://github.com/dmitrykoval/vinum/raw/main/doc/source/_static/query.png

Install =======

`pip install vinum


Examples ========
Query python dict 

Create a Table from a python dict and return result of the query as a Pandas DataFrame.
>>> import vinum as vn     >>> data = {'value': [300.1, 2.8, 880], 'mode': ['air', 'bus', 'air']}     >>> tbl = vn.Table.from_pydict(data)     >>> tbl.sql_pd("SELECT value, np.log(value) FROM t WHERE mode='air'")        value    np.log     0  300.1  5.704116     1  880.0  6.779922
Query pandas dataframe 

>>> import pandas as pd     >>> import vinum as vn     >>> data = {'col1': [1, 2, 3], 'col2': [7, 13, 17]}     >>> pdf = pd.DataFrame(data=data)     >>> tbl = vn.Table.from_pandas(pdf)     >>> tbl.sql_pd('SELECT * FROM t WHERE col2 > 10 ORDER BY col1 DESC')        col1  col2     0     3    17     1     2    13
Run query on a csv stream

For larger datasets or datasets that won't fit into memory - streamcsv() is the recommended way to execute a query. Compressed files are also supported and can be streamed without prior extraction.


>>> import vinum as vn     >>> query = 'select passenger_count pc, count(*) from t group by pc'     >>> vn.streamcsv('taxi.csv.bz2').sql(query).topandas()        pc  count     0   0    165     1   5   3453     ...
Read and query csv 
     >>> import vinum as vn     >>> tbl = vn.read_csv('taxi.csv')     >>> restbl = tbl.sql('SELECT key, fareamount, passenger_count FROM t '     ...                   'WHERE fare_amount > 5 LIMIT 3')     >>> restbl.topandas()                                 key  fareamount  passengercount     0   2010-01-05 16:52:16.0000002         16.9                1     1  2011-08-18 00:35:00.00000049          5.7                2     2   2012-04-21 04:30:42.0000001          7.7                1
Compute Euclidean distance with numpy functions 

Use any numpy functions via the 'np.*' namespace.
>>> import vinum as vn     >>> tbl = vn.Table.from_pydict({'x': [1, 2, 3], 'y': [7, 13, 17]})     >>> tbl.sql_pd('SELECT *, np.sqrt(np.square(x) + np.square(y)) dist '     ...            'FROM t ORDER BY dist DESC')        x   y       dist     0  3  17  17.262677     1  2  13  13.152946     2  1   7   7.071068
Compute Euclidean distance with vectorized UDF 

Register UDF performing vectorized operations on Numpy arrays.
>>> import vinum as vn     >>> vn.register_numpy('distance',     ...                   lambda x, y: np.sqrt(np.square(x) + np.square(y)))     >>> tbl = vn.Table.from_pydict({'x': [1, 2, 3], 'y': [7, 13, 17]})     >>> tbl.sql_pd('SELECT *, distance(x, y) AS dist '     ...            'FROM t ORDER BY dist DESC')        x   y       dist     0  3  17  17.262677     1  2  13  13.152946     2  1   7   7.071068
Compute Euclidean distance with python UDF 

Register Python lambda function as UDF.
>>> import math     >>> import vinum as vn     >>> vn.register_python('distance', lambda x, y: math.sqrt(x2 + y2))     >>> tbl = vn.Table.from_pydict({'x': [1, 2, 3], 'y': [7, 13, 17]})     >>> tbl.sql_pd('SELECT x, y, distance(x, y) AS dist FROM t')        x   y       dist     0  1   7   7.071068     1  2  13  13.152946     2  3  17  17.262677
Group by z-score 

>>> import numpy as np     >>> import vinum as vn     >>> def z_score(x: np.ndarray):     ...     "Compute Standard Score"     ...     mean = np.mean(x)     ...     std = np.std(x)     ...     return (x - mean) / std     ...     >>> vn.registernumpy('score', zscore)     >>> tbl = vn.read_csv('taxi.csv')     >>> tbl.sqlpd('select toint(score(fareamount)) AS bucket, avg(fareamount), count(*) '     ...            'FROM t GROUP BY bucket ORDER BY bucket limit 3')        bucket        avg  count_star     0      -1  -1.839000          10     1       0   8.817733       45158     2       1  25.155522        2376

Documentation =============

Vinum documentation _

Getting started started.html>

What Vinum is not ================= Vinum is not a Database Management System, there are no plans to support insert/update/delete statements and transactions. If you need a DBMS designed for data analytics and OLAP, or don't need Python UDFs, consider using excellent DuckDB _ - it is based on solid scientific foundation and is very fast.