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.9

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.9
File Size Uploaded Provenance Actions
frogql-0.2.9.tar.gz 362.5 kB Without provenance Details for frogql-0.2.9.tar.gz

Built distributions (wheels)

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

Total release size: 6.5 MB

Release files / frogql-0.2.9.tar.gz

Download URL frogql-0.2.9.tar.gz
Size 362.5 kB
Tags Source
SHA-256 checksum
How to use checksums
c746c973f2f976adf37aa5f7dd576c7a57aac4eb00564b0b4cf4c9e178256ea5
BLAKE2b-256 checksum
How to use checksums
e344b07c94245e5daaaa62100095749ee2cf81d1e88c516b277cd75f32ea025e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via maturin/1.14.1

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

Download URL frogql-0.2.9-cp38-abi3-win_amd64.whl
Size 1.2 MB
Tags CPython 3.8 Windows x86-64 abi3
SHA-256 checksum
How to use checksums
4c2f11a928f94a26796ec4792d5ce8f22f832d3618a7dc69574e4ed35ff06faf
BLAKE2b-256 checksum
How to use checksums
954a824ef57d32dc33466f71200669ddad4e87e206d93b54a24a36a52d16bbe4
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via maturin/1.14.1

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

Download URL frogql-0.2.9-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
5b75837cb028aaf21d1435d2ca40112d960db8fcd24fe975e844fb4d21c6b6b2
BLAKE2b-256 checksum
How to use checksums
79b0c41f789a05c6d148c55f25366465532049888b6932547e60d791f8d003aa
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via maturin/1.14.1

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

Download URL frogql-0.2.9-cp38-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Size 1.3 MB
Tags CPython 3.8 Linux glibc 2.17+ ARM64 abi3
SHA-256 checksum
How to use checksums
a53403c287cb5e69bc5e4c66fedeccabbb74b2d27a099a4a5eee914025a8d19d
BLAKE2b-256 checksum
How to use checksums
59538035ea17a036a7eece5b37d0688b9774e3333818fca1148a8b7c212bb477
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via maturin/1.14.1

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

Download URL frogql-0.2.9-cp38-abi3-macosx_11_0_arm64.whl
Size 1.2 MB
Tags CPython 3.8 abi3 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
d40ae2ef27b2ed9a21b9b27bfa1478b7d9a8987a014dba8afda541c1c80e9f8d
BLAKE2b-256 checksum
How to use checksums
9b84616ce4a8b251cb46fe357246fe885f43c5fddd565710e8fdcd85adf4cef0
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via maturin/1.14.1

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

Download URL frogql-0.2.9-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
5221c5e72f3edd6bdff2685639f5804ebdb283b75d90aba08ddcfb5daaebabe9
BLAKE2b-256 checksum
How to use checksums
8ba06408a02eadfeade3cbbd5a2d0bdcfc62aad8c504ccf61407078f5a82c5d9
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via maturin/1.14.1

Security for frogql 0.2.9

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.9 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