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, written by save() together with the data. DDL is plain GQL:

conn.execute("CREATE GRAPH TYPE movies AS { (: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)")
conn.save()  # without it, none of the above survives closing the connection

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.

Metadata

Release files for frogql 0.6.0

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.6.0
File Size Uploaded Provenance Actions
frogql-0.6.0.tar.gz 1.2 MB Without provenance Details for frogql-0.6.0.tar.gz

Built distributions (wheels)

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

Total release size: 8.5 MB

Release files / frogql-0.6.0.tar.gz

Download URL frogql-0.6.0.tar.gz
Size 1.2 MB
Tags Source
SHA-256 checksum
How to use checksums
af6c5064b0e4c8d7b434721d6e37a42826016c8ab3dcc2a66ae09fe62cd974b1
BLAKE2b-256 checksum
How to use checksums
e81c7fcfc976a1d1fb01d755b58e31a1601e373f86750c08f6cd52414c104a9b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via maturin/1.15.0

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

Download URL frogql-0.6.0-cp38-abi3-win_amd64.whl
Size 1.4 MB
Tags CPython 3.8 Windows x86-64 abi3
SHA-256 checksum
How to use checksums
a687b0cecfe28daa5f0ff1ed1deffc75e5226ad5715315f6e4213deb62caa273
BLAKE2b-256 checksum
How to use checksums
d67ae5019441ae6eced246a58f34855899eff639068fd726735242ad9c33d6ee
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via maturin/1.15.0

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

Download URL frogql-0.6.0-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
06e83f3299142640ebf898cce5b7b16da7b0b17f38d52defa271e21d780c7ef5
BLAKE2b-256 checksum
How to use checksums
78a681953c47ec38ac341c9904b9c73fd7f95b9f5808d5f60782b5b756c41b8f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via maturin/1.15.0

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

Download URL frogql-0.6.0-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
e3a49e1fe15201023b84176de9099009a02b60b356a52589aff28ee30a77570f
BLAKE2b-256 checksum
How to use checksums
3de2f3728573c27811b80d56bcb789bf31d1a485a78bd4b84b51cdbfea2ceee6
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via maturin/1.15.0

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

Download URL frogql-0.6.0-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
45e7b8fdea080340a0087418be11ef962a639b8afe4b1493ae8dab28b3aaf6c2
BLAKE2b-256 checksum
How to use checksums
22cfdf03a0caeccc152810d2bedf79ae962715a875ad5fe0f938b9c4535dc54e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via maturin/1.15.0

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

Download URL frogql-0.6.0-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
581990b05d635ab763c99386cf57b8d1060d99966d730ef83af1b0d7fd50aa0c
BLAKE2b-256 checksum
How to use checksums
8b04a5722e5e64cc118ebb263d80fdec36b888ecdc304f2d51ea66d61e49116a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via maturin/1.15.0

Security for frogql 0.6.0

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