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 and parse_order_by, which parse select entries ("birth.place.title as birthplace", "count(events) as n_events") and order_by entries ("-birth.date.sortval") 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.10

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.10
File Size Uploaded Provenance Actions
gramps_object_query_language-0.5.10.tar.gz 99.0 kB Without provenance Details for gramps_object_query_language-0.5.10.tar.gz

Built distribution (wheel)

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

Total release size: 201.2 kB

Release files / gramps_object_query_language-0.5.10.tar.gz

Download URL gramps_object_query_language-0.5.10.tar.gz
Size 99.0 kB
Tags Source
SHA-256 checksum
How to use checksums
bda22efa8f1e8ee6ea3a2f581e59f8f1e61c5eab0e6d3618620bc63837b74c61
BLAKE2b-256 checksum
How to use checksums
33bac6e99b75597b7e461e13dd5194997db1224d1dbdca2c22e6ebcb54d536d0
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.10-py3-none-any.whl

Download URL gramps_object_query_language-0.5.10-py3-none-any.whl
Size 102.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
136169a6f91356b37b7fa20cb0353bb7c3c4025f17472e6c96acc1ff51efc6a1
BLAKE2b-256 checksum
How to use checksums
b6f31ce74801ae6f952f45996afa3a4a5fbaa6fd313a72b808140e06b667f715
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.10

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