query_records
Query Gramps collections server-side with columns, filters, sorting and relationship paths. Filter events by type and audit records with counts and cursor paging.
Instructions
Query any collection server-side, with columns, filters and sorting.
More capable than query_objects and the tool to reach for on an audit.
It reads indexed columns, reaches arbitrary paths inside the stored object,
and follows relationships — so "families where the mother died before the
father" or "events whose place is in Ohio" are single queries.
It is the only way to filter events by type. GrampsQL cannot: the word
is shadowed, so type = "Birth" silently matches nothing. Pass event_type
here instead.
Returns rows plus a total count and a next_after cursor. Private records,
living people and families with a living parent come back as redacted stubs.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| after | No | Cursor from a previous response's next_after, for paging past the first page. | |
| limit | No | Maximum rows (1-500). | |
| where | No | Conditions combined with AND. Each is {"column": <name or json_path>, "op": <op>, "value": ...}. Operators: eq, ne, lt, lte, gt, gte, like, regex, contains, in. Use "value_column" instead of "value" to compare two columns. | |
| select | No | Columns to return. A plain column name, or {"json_path": [...], "as": "label"} to reach into the stored object. A path may cross a relationship: person->birth/death, family->father/mother, event->place. Omit for the default columns. | |
| order_by | No | Sort keys, each {"column": ..., "direction": "asc" or "desc"}. json_path is not usable here. | |
| event_type | No | Events only. Filter by type name such as 'Birth' or 'Census'. Translated to the integer the tree stores, which is the only way event type is filterable at all. | |
| where_expr | No | An expression instead of `where`, e.g. "surname == 'Smith'". | |
| object_type | Yes | Collection to query: person, family, event, place, source, citation, repository, media, note, or tag. | |
| include_private | No | Show living people and private records in full. Only when the user asks for them; they are withheld by default. |