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.

Links

Metadata

Release files for frogql 0.2.2

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.2
File Size Uploaded Provenance Actions
frogql-0.2.2.tar.gz 17.1 MB Without provenance Details for frogql-0.2.2.tar.gz

Built distributions (wheels)

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

Total release size: 22.4 MB

Release files / frogql-0.2.2.tar.gz

Download URL frogql-0.2.2.tar.gz
Size 17.1 MB
Tags Source
SHA-256 checksum
How to use checksums
6124f599b4928fed9a4d40f55e679f0b0a3b4d8c0d2c82b93e3dc4ebcdfd10d1
BLAKE2b-256 checksum
How to use checksums
50a68d6b87272099defef8807d0a581bf068636a1bb988100b1ba8283c1a11c4
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via maturin/1.13.3

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

Download URL frogql-0.2.2-cp38-abi3-win_amd64.whl
Size 985.8 kB
Tags CPython 3.8 Windows x86-64 abi3
SHA-256 checksum
How to use checksums
8ed67a4f1144cddf01a584fb74dc4ca0d59b3be629911a1f14c398db6030da26
BLAKE2b-256 checksum
How to use checksums
d1afde08f2224d7f8d425916f8e903f1dff0db8c908acb415c35cfccac09639a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via maturin/1.13.3

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

Download URL frogql-0.2.2-cp38-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Size 1.2 MB
Tags CPython 3.8 Linux glibc 2.17+ x86-64 abi3
SHA-256 checksum
How to use checksums
195992253a9ff5cc97b6e146d54d15aa04ded30f029506188e67556f0b6ad155
BLAKE2b-256 checksum
How to use checksums
68f586311b349dcdd99e1827dba998d1bed537625f4e90b1ad9f28ad3f0fd22c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via maturin/1.13.3

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

Download URL frogql-0.2.2-cp38-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Size 1.1 MB
Tags CPython 3.8 Linux glibc 2.17+ ARM64 abi3
SHA-256 checksum
How to use checksums
05190f48a9eee397fbfbe84d44c676dfaa2f52710cbe9799e71678eb139b3fef
BLAKE2b-256 checksum
How to use checksums
ea7f0fd5d8b4d83d6ddf14f17b43ae58170cf101e827c7598edd4f094a24dd40
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via maturin/1.13.3

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

Download URL frogql-0.2.2-cp38-abi3-macosx_11_0_arm64.whl
Size 1.0 MB
Tags CPython 3.8 abi3 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
b13d9d131dd6ceef1e41e7daa0dc8096a1d240610244e1c4ec2640ecc85c72ce
BLAKE2b-256 checksum
How to use checksums
cffc8a0f16a2909fed2c26c44383887a73f2a9886dcac8514a591c86eeb0852e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via maturin/1.13.3

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

Download URL frogql-0.2.2-cp38-abi3-macosx_10_12_x86_64.whl
Size 1.1 MB
Tags CPython 3.8 abi3 macOS 10.12+ x86-64
SHA-256 checksum
How to use checksums
d9dee02a09fe478f5ebb88d69b90ef185662f402cf96216414e9b0ccdf59bb0f
BLAKE2b-256 checksum
How to use checksums
c251b400510a0d6cf2a0497bd52c543a519d8634ab7b1834cb538aa78825781d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via maturin/1.13.3

Security for frogql 0.2.2

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