Skip to main content

gramps-object-query-language

A small, closed query AST and SQL compiler for fast object queries against Gramps genealogy data.

This is not a general query language, not GraphQL, and not a raw-SQL passthrough. It compiles a structured Query (select/where/order_by/ limit/after) -- or an "almost Python" expression string -- into parameterized SQL against Gramps' flattened secondary columns, with every column checked against a fixed per-type whitelist before the compiler ever touches it.

Paths into the JSON blob are checked, not trusted: every Gramps class publishes a complete recursive get_schema(), so primary_name.surname_list[0].surname is whitelisted the same way a flat column name is, and a typo is a compile-time error naming the fields that exist rather than an all-NULL column.

It is standalone and privacy-agnostic: it carries no knowledge of proxies, permissions, or any particular web API. An evaluator/proxied_query path is also included for evaluating the same query AST directly against real (possibly proxied) Gramps objects, for callers that can't run raw SQL against an unproxied database.

Install

pip install gramps-object-query-language

Documentation

  • README-query-language.md -- a plain-language, goal-first guide to where_expr for non-programmers ("Find all the families where the mom died before the dad" -> the query for it).
  • docs/where_expr.md -- the technical reference for the "almost Python" where_expr filter language (Person "gender == Person.MALE", Family "mother.death.date.sortval < father.death.date.sortval", ...), with every example tested against real SQLite.

Modules

  • gramps_object_query_language.query -- the query AST and SQL compiler.
  • gramps_object_query_language.query_lang -- an "almost Python" expression parser (parse_expr) that translates into the same where shape, plus compile_expr, which translates it the rest of the way into query.py's executable AST for callers that want to run it directly, and parse_select, which parses select entries ("birth.place.title as birthplace", "count(events) as n_events") written in that same path grammar. See docs/where_expr.md.
  • gramps_object_query_language.evaluator -- evaluates the AST directly against real Gramps objects (no SQL), for use with a proxied database.
  • gramps_object_query_language.proxied_query -- runs a where expression through Gramps' own Filter/Rule machinery against a possibly-proxied database.

Benchmarks

benchmarks/sort_cost.py measures what each kind of sort column costs (indexed flat column vs. JSON path vs. relationship hop), with SQLite's own query plans. Its output is quoted in docs/where_expr.md -- run it rather than trusting the numbers there.

python benchmarks/sort_cost.py --people 20000

Development

pip install -e ".[test]"
pytest

License

GNU Affero General Public License v3 or later (AGPL-3.0-or-later). See LICENSE.

Metadata

Release files for gramps-object-query-language 0.5.8

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

Source distribution (sdist)

Source distribution for gramps-object-query-language 0.5.8
File Size Uploaded Provenance Actions
gramps_object_query_language-0.5.8.tar.gz 97.4 kB Without provenance Details for gramps_object_query_language-0.5.8.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for gramps-object-query-language 0.5.8
File Interpreter ABI Platform Actions
gramps_object_query_language-0.5.8-py3-none-any.whl Python 3 none any Details for gramps_object_query_language-0.5.8-py3-none-any.whl

Total release size: 197.9 kB

Release files / gramps_object_query_language-0.5.8.tar.gz

Download URL gramps_object_query_language-0.5.8.tar.gz
Size 97.4 kB
Tags Source
SHA-256 checksum
How to use checksums
658e6950ae56b43228bbcf47fde3d0c5584810857fe9b5fac1ac51689c27a321
BLAKE2b-256 checksum
How to use checksums
350dc9cc8fe1c86183f93f93caab8df30f9461abccb214376888d7c8ed67f32a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.2

Release files / gramps_object_query_language-0.5.8-py3-none-any.whl

Download URL gramps_object_query_language-0.5.8-py3-none-any.whl
Size 100.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
c4a734fd430059283b23b92a525503438082fdf6bbebf160d73bdce248ccfc37
BLAKE2b-256 checksum
How to use checksums
57b64bbd8c49172456246a4e1d0e570a054ac4b40f47109535368be6793770e4
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.2

Security for gramps-object-query-language 0.5.8

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.

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