stoolap-python 0.5.0b2__cp310-cp310-macosx_10_12_x86_64.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
stoolap/__init__.py ADDED
@@ -0,0 +1,195 @@
1
+ # Copyright 2025 Stoolap Contributors
2
+ #
3
+ # Licensed under the Apache License, Version 2.0 (the "License");
4
+ # you may not use this file except in compliance with the License.
5
+ # You may obtain a copy of the License at
6
+ #
7
+ # http://www.apache.org/licenses/LICENSE-2.0
8
+ #
9
+ # Unless required by applicable law or agreed to in writing, software
10
+ # distributed under the License is distributed on an "AS IS" BASIS,
11
+ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12
+ # See the License for the specific language governing permissions and
13
+ # limitations under the License.
14
+
15
+ """Stoolap - High-performance embedded SQL database for Python.
16
+
17
+ Usage:
18
+ from stoolap import Database
19
+
20
+ db = Database.open(":memory:")
21
+ db.exec("CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)")
22
+ db.execute("INSERT INTO users VALUES ($1, $2)", [1, "Alice"])
23
+ rows = db.query("SELECT * FROM users")
24
+ # [{"id": 1, "name": "Alice"}]
25
+
26
+ Async usage:
27
+ from stoolap import AsyncDatabase
28
+
29
+ db = await AsyncDatabase.open(":memory:")
30
+ await db.exec("CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)")
31
+ await db.execute("INSERT INTO users VALUES ($1, $2)", [1, "Alice"])
32
+ rows = await db.query("SELECT * FROM users")
33
+ await db.close()
34
+ """
35
+
36
+ from stoolap._stoolap import (
37
+ Database,
38
+ Transaction,
39
+ PreparedStatement,
40
+ Vector,
41
+ StoolapError,
42
+ )
43
+
44
+ import asyncio
45
+
46
+
47
+ class AsyncDatabase:
48
+ """Async wrapper around Database.
49
+
50
+ All methods release the GIL and run on a thread executor,
51
+ so they won't block the asyncio event loop.
52
+ """
53
+
54
+ __slots__ = ("_db",)
55
+
56
+ def __init__(self, db: Database):
57
+ self._db = db
58
+
59
+ @classmethod
60
+ async def open(cls, path: str = ":memory:") -> "AsyncDatabase":
61
+ db = await asyncio.to_thread(Database.open, path)
62
+ return cls(db)
63
+
64
+ async def execute(self, sql: str, params=None) -> int:
65
+ return await asyncio.to_thread(self._db.execute, sql, params)
66
+
67
+ async def exec(self, sql: str) -> None:
68
+ return await asyncio.to_thread(self._db.exec, sql)
69
+
70
+ async def query(self, sql: str, params=None) -> list:
71
+ return await asyncio.to_thread(self._db.query, sql, params)
72
+
73
+ async def query_one(self, sql: str, params=None):
74
+ return await asyncio.to_thread(self._db.query_one, sql, params)
75
+
76
+ async def query_raw(self, sql: str, params=None) -> dict:
77
+ return await asyncio.to_thread(self._db.query_raw, sql, params)
78
+
79
+ async def execute_batch(self, sql: str, params_list: list) -> int:
80
+ return await asyncio.to_thread(self._db.execute_batch, sql, params_list)
81
+
82
+ def prepare(self, sql: str) -> "AsyncPreparedStatement":
83
+ stmt = self._db.prepare(sql)
84
+ return AsyncPreparedStatement(stmt)
85
+
86
+ async def begin(self) -> "AsyncTransaction":
87
+ tx = await asyncio.to_thread(self._db.begin)
88
+ return AsyncTransaction(tx)
89
+
90
+ async def close(self) -> None:
91
+ await asyncio.to_thread(self._db.close)
92
+
93
+ def __repr__(self) -> str:
94
+ return "AsyncDatabase(open)"
95
+
96
+
97
+ class AsyncTransaction:
98
+ """Async wrapper around Transaction.
99
+
100
+ Can be used as an async context manager:
101
+ async with await db.begin() as tx:
102
+ await tx.execute(...)
103
+ """
104
+
105
+ __slots__ = ("_tx",)
106
+
107
+ def __init__(self, tx: Transaction):
108
+ self._tx = tx
109
+
110
+ async def execute(self, sql: str, params=None) -> int:
111
+ return await asyncio.to_thread(self._tx.execute, sql, params)
112
+
113
+ async def query(self, sql: str, params=None) -> list:
114
+ return await asyncio.to_thread(self._tx.query, sql, params)
115
+
116
+ async def query_one(self, sql: str, params=None):
117
+ return await asyncio.to_thread(self._tx.query_one, sql, params)
118
+
119
+ async def query_raw(self, sql: str, params=None) -> dict:
120
+ return await asyncio.to_thread(self._tx.query_raw, sql, params)
121
+
122
+ async def execute_batch(self, sql: str, params_list: list) -> int:
123
+ return await asyncio.to_thread(self._tx.execute_batch, sql, params_list)
124
+
125
+ async def execute_prepared(self, stmt, params=None) -> int:
126
+ return await asyncio.to_thread(self._tx.execute_prepared, stmt._stmt if isinstance(stmt, AsyncPreparedStatement) else stmt, params)
127
+
128
+ async def query_prepared(self, stmt, params=None) -> list:
129
+ return await asyncio.to_thread(self._tx.query_prepared, stmt._stmt if isinstance(stmt, AsyncPreparedStatement) else stmt, params)
130
+
131
+ async def query_one_prepared(self, stmt, params=None):
132
+ return await asyncio.to_thread(self._tx.query_one_prepared, stmt._stmt if isinstance(stmt, AsyncPreparedStatement) else stmt, params)
133
+
134
+ async def query_raw_prepared(self, stmt, params=None) -> dict:
135
+ return await asyncio.to_thread(self._tx.query_raw_prepared, stmt._stmt if isinstance(stmt, AsyncPreparedStatement) else stmt, params)
136
+
137
+ async def commit(self) -> None:
138
+ await asyncio.to_thread(self._tx.commit)
139
+
140
+ async def rollback(self) -> None:
141
+ await asyncio.to_thread(self._tx.rollback)
142
+
143
+ async def __aenter__(self) -> "AsyncTransaction":
144
+ return self
145
+
146
+ async def __aexit__(self, exc_type, exc_val, exc_tb) -> bool:
147
+ # Same rules as the sync context manager: commit on clean exit,
148
+ # rollback on exception, no-op if the block already ended the tx.
149
+ return await asyncio.to_thread(self._tx.__exit__, exc_type, exc_val, exc_tb)
150
+
151
+ def __repr__(self) -> str:
152
+ return repr(self._tx)
153
+
154
+
155
+ class AsyncPreparedStatement:
156
+ """Async wrapper around PreparedStatement."""
157
+
158
+ __slots__ = ("_stmt",)
159
+
160
+ def __init__(self, stmt: PreparedStatement):
161
+ self._stmt = stmt
162
+
163
+ async def execute(self, params=None) -> int:
164
+ return await asyncio.to_thread(self._stmt.execute, params)
165
+
166
+ async def query(self, params=None) -> list:
167
+ return await asyncio.to_thread(self._stmt.query, params)
168
+
169
+ async def query_one(self, params=None):
170
+ return await asyncio.to_thread(self._stmt.query_one, params)
171
+
172
+ async def query_raw(self, params=None) -> dict:
173
+ return await asyncio.to_thread(self._stmt.query_raw, params)
174
+
175
+ async def execute_batch(self, params_list: list) -> int:
176
+ return await asyncio.to_thread(self._stmt.execute_batch, params_list)
177
+
178
+ @property
179
+ def sql(self) -> str:
180
+ return self._stmt.sql
181
+
182
+ def __repr__(self) -> str:
183
+ return repr(self._stmt)
184
+
185
+
186
+ __all__ = [
187
+ "Database",
188
+ "Transaction",
189
+ "PreparedStatement",
190
+ "Vector",
191
+ "AsyncDatabase",
192
+ "AsyncTransaction",
193
+ "AsyncPreparedStatement",
194
+ "StoolapError",
195
+ ]
stoolap/__init__.pyi ADDED
@@ -0,0 +1,101 @@
1
+ # Copyright 2025 Stoolap Contributors
2
+ #
3
+ # Licensed under the Apache License, Version 2.0 (the "License");
4
+ # you may not use this file except in compliance with the License.
5
+ # You may obtain a copy of the License at
6
+ #
7
+ # http://www.apache.org/licenses/LICENSE-2.0
8
+ #
9
+ # Unless required by applicable law or agreed to in writing, software
10
+ # distributed under the License is distributed on an "AS IS" BASIS,
11
+ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12
+ # See the License for the specific language governing permissions and
13
+ # limitations under the License.
14
+
15
+ from typing import Any, Optional, Union, Dict, List, Sequence
16
+
17
+ Params = Optional[Union[List[Any], tuple, Dict[str, Any]]]
18
+ ParamSet = Union[List[Any], tuple]
19
+
20
+ __all__: list[str]
21
+
22
+ class StoolapError(RuntimeError): ...
23
+
24
+ class Vector:
25
+ def __init__(self, data: Sequence[float]) -> None: ...
26
+ def to_list(self) -> List[float]: ...
27
+ def __len__(self) -> int: ...
28
+
29
+ class Database:
30
+ @staticmethod
31
+ def open(path: str = ":memory:") -> "Database": ...
32
+ def execute(self, sql: str, params: Params = None) -> int: ...
33
+ def exec(self, sql: str) -> None: ...
34
+ def query(self, sql: str, params: Params = None) -> List[Dict[str, Any]]: ...
35
+ def query_one(self, sql: str, params: Params = None) -> Optional[Dict[str, Any]]: ...
36
+ def query_raw(self, sql: str, params: Params = None) -> Dict[str, Any]: ...
37
+ def execute_batch(self, sql: str, params_list: Sequence[ParamSet]) -> int: ...
38
+ def prepare(self, sql: str) -> "PreparedStatement": ...
39
+ def begin(self) -> "Transaction": ...
40
+ def close(self) -> None: ...
41
+
42
+ class Transaction:
43
+ def execute(self, sql: str, params: Params = None) -> int: ...
44
+ def query(self, sql: str, params: Params = None) -> List[Dict[str, Any]]: ...
45
+ def query_one(self, sql: str, params: Params = None) -> Optional[Dict[str, Any]]: ...
46
+ def query_raw(self, sql: str, params: Params = None) -> Dict[str, Any]: ...
47
+ def execute_batch(self, sql: str, params_list: Sequence[ParamSet]) -> int: ...
48
+ def execute_prepared(self, stmt: "PreparedStatement", params: Params = None) -> int: ...
49
+ def query_prepared(self, stmt: "PreparedStatement", params: Params = None) -> List[Dict[str, Any]]: ...
50
+ def query_one_prepared(self, stmt: "PreparedStatement", params: Params = None) -> Optional[Dict[str, Any]]: ...
51
+ def query_raw_prepared(self, stmt: "PreparedStatement", params: Params = None) -> Dict[str, Any]: ...
52
+ def commit(self) -> None: ...
53
+ def rollback(self) -> None: ...
54
+ def __enter__(self) -> "Transaction": ...
55
+ def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> bool: ...
56
+
57
+ class PreparedStatement:
58
+ @property
59
+ def sql(self) -> str: ...
60
+ def execute(self, params: Params = None) -> int: ...
61
+ def query(self, params: Params = None) -> List[Dict[str, Any]]: ...
62
+ def query_one(self, params: Params = None) -> Optional[Dict[str, Any]]: ...
63
+ def query_raw(self, params: Params = None) -> Dict[str, Any]: ...
64
+ def execute_batch(self, params_list: Sequence[ParamSet]) -> int: ...
65
+
66
+ class AsyncDatabase:
67
+ @classmethod
68
+ async def open(cls, path: str = ":memory:") -> "AsyncDatabase": ...
69
+ async def execute(self, sql: str, params: Params = None) -> int: ...
70
+ async def exec(self, sql: str) -> None: ...
71
+ async def query(self, sql: str, params: Params = None) -> List[Dict[str, Any]]: ...
72
+ async def query_one(self, sql: str, params: Params = None) -> Optional[Dict[str, Any]]: ...
73
+ async def query_raw(self, sql: str, params: Params = None) -> Dict[str, Any]: ...
74
+ async def execute_batch(self, sql: str, params_list: Sequence[ParamSet]) -> int: ...
75
+ def prepare(self, sql: str) -> "AsyncPreparedStatement": ...
76
+ async def begin(self) -> "AsyncTransaction": ...
77
+ async def close(self) -> None: ...
78
+
79
+ class AsyncTransaction:
80
+ async def execute(self, sql: str, params: Params = None) -> int: ...
81
+ async def query(self, sql: str, params: Params = None) -> List[Dict[str, Any]]: ...
82
+ async def query_one(self, sql: str, params: Params = None) -> Optional[Dict[str, Any]]: ...
83
+ async def query_raw(self, sql: str, params: Params = None) -> Dict[str, Any]: ...
84
+ async def execute_batch(self, sql: str, params_list: Sequence[ParamSet]) -> int: ...
85
+ async def execute_prepared(self, stmt: Union["AsyncPreparedStatement", PreparedStatement], params: Params = None) -> int: ...
86
+ async def query_prepared(self, stmt: Union["AsyncPreparedStatement", PreparedStatement], params: Params = None) -> List[Dict[str, Any]]: ...
87
+ async def query_one_prepared(self, stmt: Union["AsyncPreparedStatement", PreparedStatement], params: Params = None) -> Optional[Dict[str, Any]]: ...
88
+ async def query_raw_prepared(self, stmt: Union["AsyncPreparedStatement", PreparedStatement], params: Params = None) -> Dict[str, Any]: ...
89
+ async def commit(self) -> None: ...
90
+ async def rollback(self) -> None: ...
91
+ async def __aenter__(self) -> "AsyncTransaction": ...
92
+ async def __aexit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> bool: ...
93
+
94
+ class AsyncPreparedStatement:
95
+ @property
96
+ def sql(self) -> str: ...
97
+ async def execute(self, params: Params = None) -> int: ...
98
+ async def query(self, params: Params = None) -> List[Dict[str, Any]]: ...
99
+ async def query_one(self, params: Params = None) -> Optional[Dict[str, Any]]: ...
100
+ async def query_raw(self, params: Params = None) -> Dict[str, Any]: ...
101
+ async def execute_batch(self, params_list: Sequence[ParamSet]) -> int: ...
Binary file
@@ -0,0 +1,346 @@
1
+ Metadata-Version: 2.4
2
+ Name: stoolap-python
3
+ Version: 0.5.0b2
4
+ Classifier: Development Status :: 4 - Beta
5
+ Classifier: Intended Audience :: Developers
6
+ Classifier: License :: OSI Approved :: Apache Software License
7
+ Classifier: Programming Language :: Python :: 3
8
+ Classifier: Programming Language :: Python :: 3.9
9
+ Classifier: Programming Language :: Python :: 3.10
10
+ Classifier: Programming Language :: Python :: 3.11
11
+ Classifier: Programming Language :: Python :: 3.12
12
+ Classifier: Programming Language :: Python :: 3.13
13
+ Classifier: Programming Language :: Rust
14
+ Classifier: Topic :: Database
15
+ Requires-Dist: pytest ; extra == 'dev'
16
+ Requires-Dist: pytest-asyncio ; extra == 'dev'
17
+ Provides-Extra: dev
18
+ License-File: LICENSE
19
+ Summary: High-performance Python driver for Stoolap embedded SQL database
20
+ Keywords: database,sql,embedded,stoolap
21
+ Home-Page: https://stoolap.io
22
+ Author: Stoolap Contributors
23
+ License: Apache-2.0
24
+ Requires-Python: >=3.9
25
+ Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
26
+ Project-URL: Documentation, https://stoolap.io/docs/drivers/python/
27
+ Project-URL: Homepage, https://stoolap.io
28
+ Project-URL: Repository, https://github.com/stoolap/stoolap-python
29
+
30
+ # stoolap-python
31
+
32
+ High-performance Python driver for [Stoolap](https://stoolap.io) embedded SQL database. Built with [PyO3](https://pyo3.rs) for native Rust performance with both sync and async APIs.
33
+
34
+ Run the benchmark yourself: `python benchmark.py`
35
+
36
+ ## Installation
37
+
38
+ ```bash
39
+ pip install stoolap-python
40
+ ```
41
+
42
+ ## Quick Start
43
+
44
+ ```python
45
+ from stoolap import Database
46
+
47
+ # In-memory database
48
+ db = Database.open(":memory:")
49
+
50
+ # exec() runs one or more DDL/DML statements (no parameters)
51
+ db.exec("""
52
+ CREATE TABLE users (
53
+ id INTEGER PRIMARY KEY,
54
+ name TEXT NOT NULL,
55
+ email TEXT
56
+ );
57
+ CREATE INDEX idx_users_name ON users(name);
58
+ """)
59
+
60
+ # execute() runs a single statement with parameters, returns rows affected
61
+ db.execute(
62
+ "INSERT INTO users (id, name, email) VALUES ($1, $2, $3)",
63
+ [1, "Alice", "alice@example.com"],
64
+ )
65
+
66
+ # Named parameters (:key)
67
+ db.execute(
68
+ "INSERT INTO users (id, name, email) VALUES (:id, :name, :email)",
69
+ {"id": 2, "name": "Bob", "email": "bob@example.com"},
70
+ )
71
+
72
+ # query() returns a list of dicts
73
+ users = db.query("SELECT * FROM users ORDER BY id")
74
+ # [{"id": 1, "name": "Alice", "email": "alice@example.com"}, ...]
75
+
76
+ # query_one() returns a single dict or None
77
+ user = db.query_one("SELECT * FROM users WHERE id = $1", [1])
78
+ # {"id": 1, "name": "Alice", "email": "alice@example.com"}
79
+
80
+ # query_raw() returns columnar format (faster for large results)
81
+ raw = db.query_raw("SELECT id, name FROM users ORDER BY id")
82
+ # {"columns": ["id", "name"], "rows": [[1, "Alice"], [2, "Bob"]]}
83
+
84
+ db.close()
85
+ ```
86
+
87
+ Each `Database.open(":memory:")` is a private database. To share one in-memory database between opens in the same process, give it a name: `Database.open("memory://name")`.
88
+
89
+ `query()` and `query_one()` key each row by column name, so two result columns with the same name (for example `a.id` and `b.id` in a join) collapse into one key. Alias them, or use `query_raw()`, when that matters.
90
+
91
+ ## Prepared Statements
92
+
93
+ Parse SQL once, execute many times with different parameters:
94
+
95
+ ```python
96
+ insert = db.prepare("INSERT INTO users (id, name) VALUES ($1, $2)")
97
+ insert.execute([1, "Alice"])
98
+ insert.execute([2, "Bob"])
99
+
100
+ # Batch execution (auto-wrapped in a transaction)
101
+ insert.execute_batch([
102
+ [3, "Charlie"],
103
+ [4, "Diana"],
104
+ ])
105
+
106
+ # Prepared queries
107
+ lookup = db.prepare("SELECT * FROM users WHERE id = $1")
108
+ user = lookup.query_one([1]) # Single row as dict or None
109
+ rows = lookup.query([1]) # All rows as list of dicts
110
+ raw = lookup.query_raw([1]) # Columnar format
111
+
112
+ # Named parameters also work with prepared statements
113
+ lookup = db.prepare("SELECT * FROM users WHERE id = :id")
114
+ user = lookup.query_one({"id": 1})
115
+ ```
116
+
117
+ ## Transactions
118
+
119
+ ```python
120
+ # Context manager (auto-commit on clean exit, auto-rollback on exception)
121
+ with db.begin() as tx:
122
+ tx.execute("INSERT INTO users (id, name) VALUES ($1, $2)", [1, "Alice"])
123
+ tx.execute("INSERT INTO users (id, name) VALUES ($1, $2)", [2, "Bob"])
124
+
125
+ # Manual control
126
+ tx = db.begin()
127
+ try:
128
+ tx.execute("INSERT INTO users (id, name) VALUES ($1, $2)", [1, "Alice"])
129
+ tx.commit()
130
+ except:
131
+ tx.rollback()
132
+ raise
133
+ ```
134
+
135
+ Transactions support `execute()`, `query()`, `query_one()`, `query_raw()`, and `execute_batch()` with both positional (`$1, $2`) and named (`:key`) parameters. A statement prepared on the database runs inside a transaction with `execute_prepared(stmt, params)`, `query_prepared`, `query_one_prepared` and `query_raw_prepared`. `rollback()` is a no-op once the transaction has ended, so the handler above never hides the original error.
136
+
137
+ ## Batch Execution
138
+
139
+ Execute the same statement with multiple parameter sets, auto-wrapped in a transaction:
140
+
141
+ ```python
142
+ # On Database
143
+ changes = db.execute_batch(
144
+ "INSERT INTO users (id, name) VALUES ($1, $2)",
145
+ [[1, "Alice"], [2, "Bob"], [3, "Charlie"]],
146
+ )
147
+ # changes == 3
148
+
149
+ # On PreparedStatement (reuses cached plan)
150
+ stmt = db.prepare("INSERT INTO users (id, name) VALUES ($1, $2)")
151
+ changes = stmt.execute_batch([[4, "Diana"], [5, "Eve"]])
152
+ ```
153
+
154
+ ## Async API
155
+
156
+ All methods release the GIL and run on a thread executor:
157
+
158
+ ```python
159
+ from stoolap import AsyncDatabase
160
+
161
+ db = await AsyncDatabase.open(":memory:")
162
+
163
+ await db.exec("CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)")
164
+ await db.execute("INSERT INTO users (id, name) VALUES ($1, $2)", [1, "Alice"])
165
+
166
+ rows = await db.query("SELECT * FROM users")
167
+
168
+ # Async transactions
169
+ async with await db.begin() as tx:
170
+ await tx.execute("INSERT INTO users (id, name) VALUES ($1, $2)", [2, "Bob"])
171
+
172
+ # Async prepared statements
173
+ stmt = db.prepare("SELECT * FROM users WHERE id = $1")
174
+ user = await stmt.query_one([1])
175
+
176
+ await db.close()
177
+ ```
178
+
179
+ ## Error Handling
180
+
181
+ All database errors raise `StoolapError`:
182
+
183
+ ```python
184
+ from stoolap import Database, StoolapError
185
+
186
+ db = Database.open(":memory:")
187
+ try:
188
+ db.query("SELECT * FROM nonexistent_table")
189
+ except StoolapError as e:
190
+ print(f"Database error: {e}")
191
+ ```
192
+
193
+ ## Persistence
194
+
195
+ ```python
196
+ # File-based database (data persists across restarts)
197
+ db = Database.open("file:///path/to/mydata")
198
+
199
+ # Relative paths also work
200
+ db = Database.open("./mydata")
201
+ ```
202
+
203
+ ### Configuration Options
204
+
205
+ Pass options as query parameters in the DSN:
206
+
207
+ ```python
208
+ # Max durability
209
+ db = Database.open("file:///path/to/mydata?sync_mode=full")
210
+
211
+ # Max throughput (less durable)
212
+ db = Database.open("file:///path/to/mydata?sync_mode=none&checkpoint_interval=120")
213
+ ```
214
+
215
+ | Parameter | Values | Default | Description |
216
+ |-----------|--------|---------|-------------|
217
+ | `sync_mode` | `none`, `normal`, `full` | `normal` | Durability level (`full` = fsync every write, `normal` = fsync every 1s) |
218
+ | `checkpoint_interval` | seconds | `60` | Seconds between checkpoint cycles (seal + compact + WAL truncate) |
219
+ | `compact_threshold` | count | `4` | Sub-target volumes per table before merging |
220
+ | `target_volume_rows` | count | `1048576` | Target rows per cold volume (controls compaction split boundary) |
221
+ | `checkpoint_on_close` | `on`, `off` | `on` | Seal all hot rows on clean shutdown for fast startup |
222
+ | `keep_snapshots` | count | `3` | Number of backup snapshots to retain |
223
+ | `compression` | `on`, `off` | `on` | Enable both WAL + volume compression (LZ4) |
224
+ | `wal_compression` | `on`, `off` | `on` | WAL compression only |
225
+ | `volume_compression` | `on`, `off` | `on` | Cold volume file compression only |
226
+ | `compression_threshold` | bytes | `64` | Minimum data size before compression |
227
+ | `wal_buffer_size` | bytes | `65536` | WAL write buffer size |
228
+ | `wal_flush_trigger` | bytes | `32768` | WAL size before flush |
229
+ | `wal_max_size` | bytes | `67108864` | WAL size before rotation (64 MB) |
230
+ | `commit_batch_size` | count | `100` | Commits batched before syncing (normal mode) |
231
+ | `sync_interval_ms` | milliseconds | `1000` | Minimum ms between syncs (normal mode) |
232
+
233
+ ## Type Mapping
234
+
235
+ | Python | Stoolap | Notes |
236
+ |--------|---------|-------|
237
+ | `int` | `INTEGER` | 64-bit signed |
238
+ | `float` | `FLOAT` | 64-bit double |
239
+ | `str` | `TEXT` | UTF-8 |
240
+ | `bool` | `BOOLEAN` | |
241
+ | `None` | `NULL` | |
242
+ | `datetime.datetime` | `TIMESTAMP` | Converted to/from UTC |
243
+ | `dict` / `list` | `JSON` | Serialized via `json.dumps` |
244
+ | `Vector` | `VECTOR(N)` | `list[float]` on output |
245
+
246
+ ## Vector Similarity Search
247
+
248
+ Store embeddings and perform k-NN similarity search using HNSW indexes:
249
+
250
+ ```python
251
+ from stoolap import Database, Vector
252
+
253
+ db = Database.open(":memory:")
254
+
255
+ # Create a table with a VECTOR column
256
+ db.exec("""
257
+ CREATE TABLE documents (
258
+ id INTEGER PRIMARY KEY,
259
+ title TEXT,
260
+ embedding VECTOR(3)
261
+ );
262
+ CREATE INDEX idx_emb ON documents(embedding) USING HNSW WITH (metric = 'cosine');
263
+ """)
264
+
265
+ # Insert vectors using the Vector wrapper
266
+ db.execute(
267
+ "INSERT INTO documents VALUES ($1, $2, $3)",
268
+ [1, "Hello world", Vector([0.1, 0.2, 0.3])],
269
+ )
270
+ db.execute(
271
+ "INSERT INTO documents VALUES ($1, $2, $3)",
272
+ [2, "Goodbye world", Vector([0.9, 0.1, 0.0])],
273
+ )
274
+
275
+ # k-NN search: find 5 nearest neighbors
276
+ results = db.query(
277
+ "SELECT id, title, VEC_DISTANCE_COSINE(embedding, '[0.1, 0.2, 0.3]') AS dist "
278
+ "FROM documents ORDER BY dist LIMIT 5"
279
+ )
280
+
281
+ # Read vectors back as list[float]
282
+ row = db.query_one("SELECT embedding FROM documents WHERE id = 1")
283
+ emb = row["embedding"] # [0.1, 0.2, 0.3]
284
+ ```
285
+
286
+ ### Distance Functions
287
+
288
+ | Function | Description |
289
+ |----------|-------------|
290
+ | `VEC_DISTANCE_L2(a, b)` | Euclidean distance |
291
+ | `VEC_DISTANCE_COSINE(a, b)` | Cosine distance (1 - similarity) |
292
+ | `VEC_DISTANCE_IP(a, b)` | Negative inner product |
293
+
294
+ ### Vector Utilities
295
+
296
+ | Function | Description |
297
+ |----------|-------------|
298
+ | `VEC_DIMS(v)` | Number of dimensions |
299
+ | `VEC_NORM(v)` | L2 norm (magnitude) |
300
+ | `VEC_TO_TEXT(v)` | Convert to string `[1.0, 2.0, 3.0]` |
301
+
302
+ ### HNSW Index Options
303
+
304
+ ```sql
305
+ CREATE INDEX idx ON table(column) USING HNSW WITH (metric = 'cosine');
306
+ ```
307
+
308
+ Supported metrics: `l2` (default), `cosine`, `ip` (inner product).
309
+
310
+ ## Features
311
+
312
+ Stoolap is a full-featured embedded SQL database:
313
+
314
+ - **MVCC Transactions** with snapshot isolation
315
+ - **Cost-based query optimizer** with adaptive execution
316
+ - **Parallel query execution** (filter, join, sort, distinct)
317
+ - **JOINs**: INNER, LEFT, RIGHT, FULL OUTER, CROSS, NATURAL
318
+ - **Subqueries**: scalar, EXISTS, IN, NOT IN, ANY/ALL, correlated
319
+ - **Window functions**: ROW_NUMBER, RANK, DENSE_RANK, LAG, LEAD, NTILE
320
+ - **CTEs**: WITH and WITH RECURSIVE
321
+ - **Aggregations**: GROUP BY, HAVING, ROLLUP, CUBE, GROUPING SETS
322
+ - **Vector similarity search** with HNSW indexes (L2, cosine, inner product)
323
+ - **Indexes**: B-tree, Hash, Bitmap (auto-selected), HNSW, multi-column composite
324
+ - **110+ built-in functions**: string, math, date/time, JSON, vector, aggregate
325
+ - **Immutable volume-based storage** with columnar format, zone maps, bloom filters, and LZ4 compression
326
+ - **WAL + checkpoint cycles** for crash recovery (seal + compact + WAL truncate)
327
+ - **Aggregation pushdown** to cold volume statistics (COUNT, SUM, MIN, MAX)
328
+ - **Semantic query caching** with predicate subsumption
329
+
330
+ ## Building from Source
331
+
332
+ Requires [Rust](https://rustup.rs) (stable) and Python >= 3.9.
333
+
334
+ ```bash
335
+ git clone https://github.com/stoolap/stoolap-python.git
336
+ cd stoolap-python
337
+ python -m venv .venv && source .venv/bin/activate
338
+ pip install maturin pytest pytest-asyncio
339
+ maturin develop --release
340
+ pytest
341
+ ```
342
+
343
+ ## License
344
+
345
+ Apache-2.0
346
+
@@ -0,0 +1,8 @@
1
+ stoolap/__init__.py,sha256=YRVYvqXoaPRfXqUpEJjz1lT5VQeecJDVP3p-a4r53mU,6543
2
+ stoolap/__init__.pyi,sha256=M7PNIjaSgifKwvGt0dx8KNpuQavboSEK_3KtCPwdzlc,5540
3
+ stoolap/_stoolap.cpython-310-darwin.so,sha256=VOK55mFvcOV4kW5T_oyQ5OIUM0NN6XKC5WfO572jDGw,11413688
4
+ stoolap_python-0.5.0b2.dist-info/METADATA,sha256=DFJXw79gFgOyz3yjjrvnZ70dngauhYSNjlcpIu2YRfI,11466
5
+ stoolap_python-0.5.0b2.dist-info/WHEEL,sha256=yzu3hVJSUN32RBA7_LxISSeOSTx8roEJknw_abZE1ps,107
6
+ stoolap_python-0.5.0b2.dist-info/licenses/LICENSE,sha256=JwuEHVB8rbYcB5IHg-yAuP_aZzKieP2I5aGqHYML38I,11350
7
+ stoolap_python-0.5.0b2.dist-info/sboms/stoolap-python.cyclonedx.json,sha256=i1YStnxcMq6ZpKRsKBJUZJhcKuY4w1rlqasNaS1yqpQ,97009
8
+ stoolap_python-0.5.0b2.dist-info/RECORD,,
@@ -0,0 +1,4 @@
1
+ Wheel-Version: 1.0
2
+ Generator: maturin (1.15.0)
3
+ Root-Is-Purelib: false
4
+ Tag: cp310-cp310-macosx_10_12_x86_64