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
Metadata
Release files for frogql 0.5.4
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 | Actions |
|---|---|---|---|---|
| frogql-0.5.4.tar.gz | 553.6 kB | Without provenance | Details for frogql-0.5.4.tar.gz |
Built distributions (wheels)
| File | Actions Reset | |||
|---|---|---|---|---|
| frogql-0.5.4-cp38-abi3-win_amd64.whl | CPython 3.8 | abi3 | Windows x86-64 | Details for frogql-0.5.4-cp38-abi3-win_amd64.whl |
| frogql-0.5.4-cp38-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl | CPython 3.8 | abi3 | Linux glibc 2.17+ x86-64 | Details for frogql-0.5.4-cp38-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl |
| frogql-0.5.4-cp38-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl | CPython 3.8 | abi3 | Linux glibc 2.17+ ARM64 | Details for frogql-0.5.4-cp38-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl |
| frogql-0.5.4-cp38-abi3-macosx_11_0_arm64.whl | CPython 3.8 | abi3 | macOS 11.0+ ARM64 | Details for frogql-0.5.4-cp38-abi3-macosx_11_0_arm64.whl |
| frogql-0.5.4-cp38-abi3-macosx_10_12_x86_64.whl | CPython 3.8 | abi3 | macOS 10.12+ x86-64 | Details for frogql-0.5.4-cp38-abi3-macosx_10_12_x86_64.whl |
Total release size: 7.7 MB
Release files / frogql-0.5.4.tar.gz
| Download URL | frogql-0.5.4.tar.gz |
|---|---|
| Size | 553.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
e03fd3aea1a66daa70bbf4c60aa36e5b71a58ca4d26c17716635fe1434715311
|
|
BLAKE2b-256 checksum How to use checksums |
56a8aae9eb8d3183f002e365f4b49ed4c9998fcdd2fe98626d19185749719d71
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
maturin/1.15.0
|
Release files / frogql-0.5.4-cp38-abi3-win_amd64.whl
| Download URL | frogql-0.5.4-cp38-abi3-win_amd64.whl |
|---|---|
| Size | 1.4 MB |
| Tags | CPython 3.8 Windows x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
e5f6c625210a2b540cae7f19ac54af75051aab2fcfae741b4e4d8b370829a27d
|
|
BLAKE2b-256 checksum How to use checksums |
e02b6864c63c69ffbdb917afa80b1838b9001d4ab16830b00307ba4dd94837fa
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
maturin/1.15.0
|
Release files / frogql-0.5.4-cp38-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
| Download URL | frogql-0.5.4-cp38-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl |
|---|---|
| Size | 1.5 MB |
| Tags | CPython 3.8 Linux glibc 2.17+ x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
c158efc3d074557224a861d0012c7b71583d2865b39e2bfb2e40a6024733a648
|
|
BLAKE2b-256 checksum How to use checksums |
3b97e43707b8556c7ce4caaa83291f6c36735bbc0f896badc3b86d6baaed0531
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
maturin/1.15.0
|
Release files / frogql-0.5.4-cp38-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
| Download URL | frogql-0.5.4-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 |
591e7c480bdcab8270759f825941940a027305ad8b411c796ec61a8ca1ec5531
|
|
BLAKE2b-256 checksum How to use checksums |
31e26faf5da5b39511bf94769a07e270ab3d9ad37f7d4e2f3cd6fbb86e5bb346
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
maturin/1.15.0
|
Release files / frogql-0.5.4-cp38-abi3-macosx_11_0_arm64.whl
| Download URL | frogql-0.5.4-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 |
f0ba5b47138525b964396dc118ca99bea5eadcf028452c13956c6a62068ad797
|
|
BLAKE2b-256 checksum How to use checksums |
1586f1594ead123cb4489face405b5675a61b09a44141ad32c5a9e0b2ac7b173
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
maturin/1.15.0
|
Release files / frogql-0.5.4-cp38-abi3-macosx_10_12_x86_64.whl
| Download URL | frogql-0.5.4-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 |
5be80a01373934535e9c7ba2e4a9bf449fa3d1aaa2886235de96c99d526c7e84
|
|
BLAKE2b-256 checksum How to use checksums |
5eee14bf2fe0213236d0a138a8ed81ef2e1396005689b1a5b78b35c9b499bcb7
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
maturin/1.15.0
|
Security for frogql 0.5.4
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.
To learn more about protecting yourself from malicious actors, visit our package security documentation.