query_objects
Query Gramps objects with server-side GrampsQL filters to audit citations, sources, media, and other records without pulling whole collections.
Instructions
Query any collection with a server-side filter. The workhorse for audits.
Use this instead of fetching a collection and filtering it yourself: whole-collection pulls are slow on any real tree, and the filter runs in the database. Typical audit questions it answers directly:
uncited high-confidence claims: citations where
confidence >= 3 AND page = ""documents with no image: sources where
media_list.length = 0anonymous media: media where
desc = ""a URL anywhere:
urls.any.path ~ "blm.gov"; a list is searched through its items, never with~on the list itself
To ask "what cites this source?" use get_backlinks -- a source has no citation_list, because citations point at IT, and reading citation_list on a source reports zero for every source in the tree.
Private records and living people come back as redacted stubs.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| gql | No | GrampsQL filter, applied server-side over the RAW object JSON. Single '=' for equality (NOT '=='), '~' for substring, '<list>.length' for sizes, combined with AND/OR. Examples: 'confidence >= 3 AND page = ""' (high-confidence citations with no locator), 'media_list.length = 0' (sources with no image), 'desc = ""' (undescribed media), 'description ~ "1871"'. A LIST is searched through its items with '.any.' (or '.all.'), and a handle followed with 'get_<type>': 'urls.any.path ~ "blm.gov"', 'attribute_list.any.value ~ "x"', 'note_list.any.get_note.text.string ~ "x"'. '~' on the list itself asks whether the value IS an item, so it is refused. TRAPS: a field the object lacks is not an error, it matches nothing -- event 'type' is one (use query_records). Booleans compare as 0/1: 'private = 1', never 'private = true'. A query reads the whole collection, so each OR'd condition adds time. | |
| keys | No | Comma-separated fields to return, e.g. 'gramps_id,title,media_list'. Strongly recommended -- whole objects are large. NEVER build a write payload from a keys= result: writes replace the whole record. | |
| page | No | Page of results, 1-based. | |
| sort | No | Sort key; prefix '-' for descending (e.g. '-change'). | |
| limit | No | Max rows to return. | |
| handles | No | Fetch these specific handles in one request. | |
| gramps_ids | No | Fetch these specific gramps_ids (e.g. ['S0001','S0002']). | |
| object_type | Yes | One of: person, family, event, place, source, citation, repository, media, note, tag. | |
| include_private | No | Show living people and private records in full. Only when the user asks for them; they are withheld by default. |