froGQL
Embedded GQL graph database with single-file storage. Rust core, Python bindings via PyO3.
froGQL implements ISO GQL path pattern matching: MATCH, comma-joins, unions, repetitions ({n,m}), OPTIONAL MATCH, EXISTS / NOT EXISTS, WHERE, RETURN, LIMIT. The runtime uses Leapfrog Triejoin (CompactLTJ) as its primary join strategy — worst-case-optimal for multi-way joins, with measured 14×–4000× speedups over pairwise hash-join on social-graph workloads.
Install
pip install frogql
Wheels ship for CPython 3.8+ on Linux (x86_64, aarch64), macOS (x86_64, arm64), and Windows (x86_64).
Quick start
import frogql
# Open or create a .gdb database
conn = frogql.open("movies.gdb")
# Run a query — returns a list of {alias: value} dicts.
# Use `AS name` in RETURN to pick the dict key; otherwise the
# projection falls back to col0, col1, ...
rows = conn.execute(
"MATCH (p:Person)-[:ACTED_IN]->(m:Movie) "
"WHERE m.released = 1999 "
"RETURN p.name AS actor, m.title AS title",
limit=10,
)
for row in rows:
print(row["actor"], "->", row["title"])
# Inspect the graph
print(conn.node_count, conn.edge_count)
print(conn.schema())
Bare patterns (no RETURN)
A query without RETURN projects each row as a dict of the matched
variables plus a special _paths key holding the full match:
rows = conn.execute("(p:Person)-[:ACTED_IN]->(m:Movie)", limit=1)
row = rows[0]
row["p"] # {"kind": "node", "id": ..., "labels": [...], "props": {...}}
row["m"] # the movie node
row["_paths"] # [[node_p, edge, node_m]] — list of paths, each a
# list of node/edge dicts in match order
_paths is a list because comma-joined patterns produce one path per
joined sub-pattern. For a single pattern, _paths[0] is the full path.
Data import
# From JSON
frogql.import_json("graph.gdb", "graph.json")
# From a CSV directory with spanner_import_config.json
frogql.import_csv("graph.gdb", "path/to/csv_dir/")
Graph types and indexes
The catalog persists inside the .gdb file. DDL is plain GQL:
conn.execute("CREATE GRAPH TYPE movies { (:Movie {title STRING, released INT}) }")
conn.execute("USE GRAPH TYPE movies")
conn.execute("VALIDATE GRAPH TYPE movies")
conn.execute("CREATE BTREE INDEX ON :Movie(released)")
A DEFAULT graph type is auto-inferred at import time. Auto-built secondary indexes (hash + btree) cover unique (label, prop) pairs and are picked up by the optimizer for constant-folding and range filters.
API surface
| Call | Returns |
|---|---|
frogql.open(path) |
Connection |
frogql.import_json(db_path, json_path) |
None |
frogql.import_csv(db_path, csv_dir) |
None |
Connection.execute(query, limit=0) |
list[dict] (with RETURN: keys = aliases or colN; without RETURN: keys = pattern variables plus _paths) |
Connection.schema() |
dict |
Connection.graph_types() |
list[dict] |
Connection.node_count / Connection.edge_count |
int |
Connection is not thread-safe across Python threads (PyO3 unsendable).
License
MIT. See LICENSE in the source repository.
Links
Release files for frogql 0.5.11
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | |
|---|---|---|---|---|
| frogql-0.5.11.tar.gz | 1.2 MB | Without provenance | Details |
Built distributions (wheels)
| File | Reset | |||
|---|---|---|---|---|
| frogql-0.5.11-cp38-abi3-win_amd64.whl | CPython 3.8 | abi3 | Windows x86-64 | Details |
| frogql-0.5.11-cp38-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl | CPython 3.8 | abi3 | Linux glibc 2.17+ x86-64 | Details |
| frogql-0.5.11-cp38-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl | CPython 3.8 | abi3 | Linux glibc 2.17+ ARM64 | Details |
| frogql-0.5.11-cp38-abi3-macosx_11_0_arm64.whl | CPython 3.8 | abi3 | macOS 11.0+ ARM64 | Details |
| frogql-0.5.11-cp38-abi3-macosx_10_12_x86_64.whl | CPython 3.8 | abi3 | macOS 10.12+ x86-64 | Details |
Total release size: 8.4 MB
Release files / frogql-0.5.11.tar.gz
| Download URL | frogql-0.5.11.tar.gz |
|---|---|
| Size | 1.2 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
27245c4fecd51fa18e7dffffa352c079ada5e9d79ef8f853127a55e42e18ea22
|
|
BLAKE2b-256 checksum How to use checksums |
725f68622cd158adb4a19e3100f7b9d5fb702349cf355edcd95abed84cd25812
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
maturin/1.15.0
|
Release files / frogql-0.5.11-cp38-abi3-win_amd64.whl
| Download URL | frogql-0.5.11-cp38-abi3-win_amd64.whl |
|---|---|
| Size | 1.4 MB |
| Tags | CPython 3.8 Windows x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
915473df4694bae73c381df458aca651ec982d3aeeb01a5efa507211c5ac659b
|
|
BLAKE2b-256 checksum How to use checksums |
dc45fb63111cd2a76ab0ce2e69fe1d5636c988e281b7bf840e568665dd2a799c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
maturin/1.15.0
|
Release files / frogql-0.5.11-cp38-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
| Download URL | frogql-0.5.11-cp38-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl |
|---|---|
| Size | 1.6 MB |
| Tags | CPython 3.8 Linux glibc 2.17+ x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
6f147385fb50841899a740cb402a5a8ce4cedce87c2b41e67eb0079caf55185d
|
|
BLAKE2b-256 checksum How to use checksums |
01c742c29f1592c96c879aac3819d4153f11dcf61ac3fd226a14550a5a55293a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
maturin/1.15.0
|
Release files / frogql-0.5.11-cp38-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
| Download URL | frogql-0.5.11-cp38-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl |
|---|---|
| Size | 1.5 MB |
| Tags | CPython 3.8 Linux glibc 2.17+ ARM64 abi3 |
|
SHA-256 checksum How to use checksums |
1bc45217a3845a7939908918d1c99c4ca10433e5e9f8fc2f9d5cd90c1858abe3
|
|
BLAKE2b-256 checksum How to use checksums |
6fe43a1368e6c51d379b20ff75158d46f4077e74d49dbc0be06f5caca811b412
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
maturin/1.15.0
|
Release files / frogql-0.5.11-cp38-abi3-macosx_11_0_arm64.whl
| Download URL | frogql-0.5.11-cp38-abi3-macosx_11_0_arm64.whl |
|---|---|
| Size | 1.4 MB |
| Tags | CPython 3.8 abi3 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
3146a9eccb0d251b8849c322766ecead1273a5d3777e1d9480a551ebd7f55923
|
|
BLAKE2b-256 checksum How to use checksums |
92275297ec66fc601bfd748c487715a59f8cdac5dc8bbab381bd9cad5e316e9a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
maturin/1.15.0
|
Release files / frogql-0.5.11-cp38-abi3-macosx_10_12_x86_64.whl
| Download URL | frogql-0.5.11-cp38-abi3-macosx_10_12_x86_64.whl |
|---|---|
| Size | 1.4 MB |
| Tags | CPython 3.8 abi3 macOS 10.12+ x86-64 |
|
SHA-256 checksum How to use checksums |
4117cdf6dee505f3dc0e8ca5b9745ef4f804a6cac0e890448e003669d7b825be
|
|
BLAKE2b-256 checksum How to use checksums |
3e23de41958522449555d48060a13426be6e94f6b2d7137789ba4ef3e7ef86d6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
maturin/1.15.0
|
Security for frogql 0.5.11
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
