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

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

Built distributions (wheels)

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

Total release size: 22.4 MB

Release files / frogql-0.2.1.tar.gz

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

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

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

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

Download URL frogql-0.2.1-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
47b50e00a039a5dea89b7e40a3ce9672e2eca970e5f1ad49ecdc54c04682009e
BLAKE2b-256 checksum
How to use checksums
271e817dc751461d47694c4f0272fa310f6bd205c6cdc4332601958930308124
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via maturin/1.13.3

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

Download URL frogql-0.2.1-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
25e95149a3381a9ef3d6979532b73d7d4e9b7824595f502cc5833c8cea48a0cd
BLAKE2b-256 checksum
How to use checksums
5fdadb65f8f2784d1151e8ce54f5931190742692ec4e190656ea4a15186f8a28
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via maturin/1.13.3

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

Download URL frogql-0.2.1-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
cb18f04da627caf64e806066649880405223568905fb790e18fe436183766d62
BLAKE2b-256 checksum
How to use checksums
f5df66934b7d58820a405c94e522c2cb3df4b2ce495a1a9c153ee4c4ee0dcb67
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via maturin/1.13.3

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

Download URL frogql-0.2.1-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
792ccdda3bd24b1c7ce31ce3fa3209114ad2e1ab4bde984d609d285d6f8d0c5d
BLAKE2b-256 checksum
How to use checksums
8a99c6b3f9503cce165af6419393d98e0f98f3f8539410b1bf99696832267d03
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via maturin/1.13.3

Security for frogql 0.2.1

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