Skip to main content

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=100) 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.

Metadata

Release files for frogql 0.2.5

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for frogql 0.2.5
File Size Uploaded Provenance Actions
frogql-0.2.5.tar.gz 332.7 kB Without provenance Details for frogql-0.2.5.tar.gz

Built distributions (wheels)

Table of built distributions (wheels) for frogql 0.2.5
File Actions
frogql-0.2.5-cp38-abi3-win_amd64.whl CPython 3.8 abi3 Windows x86-64 Details for frogql-0.2.5-cp38-abi3-win_amd64.whl
frogql-0.2.5-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.2.5-cp38-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
frogql-0.2.5-cp38-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl CPython 3.8 abi3 Linux glibc 2.17+ ARM64 Details for frogql-0.2.5-cp38-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
frogql-0.2.5-cp38-abi3-macosx_11_0_arm64.whl CPython 3.8 abi3 macOS 11.0+ ARM64 Details for frogql-0.2.5-cp38-abi3-macosx_11_0_arm64.whl
frogql-0.2.5-cp38-abi3-macosx_10_12_x86_64.whl CPython 3.8 abi3 macOS 10.12+ x86-64 Details for frogql-0.2.5-cp38-abi3-macosx_10_12_x86_64.whl

Total release size: 6.3 MB

Release files / frogql-0.2.5.tar.gz

Download URL frogql-0.2.5.tar.gz
Size 332.7 kB
Tags Source
SHA-256 checksum
How to use checksums
9ca39ef090d258bc607f5ceaa3ab11a5a9c8865cbfec2f0b0c2d6eb596002f2f
BLAKE2b-256 checksum
How to use checksums
83c40668a9f68a5f8155e9ebc431288e4f5056af2c296b1beb17e339bc6298c9
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via maturin/1.14.0

Release files / frogql-0.2.5-cp38-abi3-win_amd64.whl

Download URL frogql-0.2.5-cp38-abi3-win_amd64.whl
Size 1.1 MB
Tags CPython 3.8 Windows x86-64 abi3
SHA-256 checksum
How to use checksums
b3ef8453da3aeb803e54d139bd92688f59a0f4315d7a627b6a74f0d28d9c65df
BLAKE2b-256 checksum
How to use checksums
9d3d8b0e93b8efc559d6d698107a1cc6b6c82c27bafb7dc5aa4076b58bb00d5e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via maturin/1.14.0

Release files / frogql-0.2.5-cp38-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl

Download URL frogql-0.2.5-cp38-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Size 1.3 MB
Tags CPython 3.8 Linux glibc 2.17+ x86-64 abi3
SHA-256 checksum
How to use checksums
f2a99fc83ddf50718c09c5f5893baec32536b5c328f8c2def818132d0280a905
BLAKE2b-256 checksum
How to use checksums
509d266df099102d9aa127031d20e0c673bbf505db011ccf57f3f369107d4248
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via maturin/1.14.0

Release files / frogql-0.2.5-cp38-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl

Download URL frogql-0.2.5-cp38-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Size 1.2 MB
Tags CPython 3.8 Linux glibc 2.17+ ARM64 abi3
SHA-256 checksum
How to use checksums
fb266bb147de59eac49353d74f9047e461203f5bb118cf4882a0db0c69ea9d23
BLAKE2b-256 checksum
How to use checksums
f62a6f8dff1f78cfe7ace7b94c7ec40c5962b31fdd5c4966e3d9391bcbbe4a2f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via maturin/1.14.0

Release files / frogql-0.2.5-cp38-abi3-macosx_11_0_arm64.whl

Download URL frogql-0.2.5-cp38-abi3-macosx_11_0_arm64.whl
Size 1.1 MB
Tags CPython 3.8 abi3 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
ec7b36ad1f8a48f2e69f9f1ca1039df42ec101e18686bb4c1aa3fdc4899abbfc
BLAKE2b-256 checksum
How to use checksums
374cdc9feb4fd5752f1b09e8b20a6dabd6f12d7ed7e606b2f434b85fd050f174
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via maturin/1.14.0

Release files / frogql-0.2.5-cp38-abi3-macosx_10_12_x86_64.whl

Download URL frogql-0.2.5-cp38-abi3-macosx_10_12_x86_64.whl
Size 1.2 MB
Tags CPython 3.8 abi3 macOS 10.12+ x86-64
SHA-256 checksum
How to use checksums
05a4402430e6d91a31b5237e47206d958578ebb616bd7130679634762f9308e7
BLAKE2b-256 checksum
How to use checksums
1e6674d5bfbee1fdd435e78d1b7995922e6e22c688635bcf12484a36bcff6e20
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via maturin/1.14.0

Security for frogql 0.2.5

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.

Release history Release notifications | RSS feed

This release

0.2.5 This release

6 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page