Gramps Evidence

Check whether a background job has finished, and whether it worked. Undo, verification, import and reindex are dispatched to a worker and answer before the work is done. Poll this until `finished` is true, then read `succeeded`. Submitting one of those operations and never checking leaves you assuming an outcome you have not seen.

Build a chronological timeline of someone's life events. Each entry carries their age at the time, how many citations support the event, and the strongest confidence among them — so a timeline doubles as a readable audit of where the evidence thins out. `uncited_count` says how many events on it rest on nothing.

Read one transaction in full, including the objects it changed. list_transactions summarises; this shows what actually moved. Read it before undoing anything.

Report a person's Y-DNA haplogroup, from broadest clade to terminal. Y-DNA follows the direct paternal line only, so it speaks to one thread of a tree and is silent on every other. A shared terminal clade indicates a common paternal ancestor, usually far further back than any record reaches — it corroborates a surname line rather than proving a named link. `has_data` is false when the person has no Y-DNA recorded, which is the normal case.

Link many sources to their repositories in one call -- a sweep. Each row is link_repository: its own write and transaction, so a failed row does not stop the rest. Each row reports linked, already_linked, missing or error.

Link an existing source to an existing repository that holds it. Adds a repository reference (with an optional call number) to the source. Both objects must already exist. Duplicate links to the same repository are skipped.

List the custom filters already saved on this instance. A saved filter can be reused by name from `query_objects` and the timelines, so a complicated selection is defined once.

List the event type names this tree uses, with their stored integers. Useful before a `query_records` filter, and as a check on itself: an unexpected type name in the list is usually a typo that Gramps silently accepted as a new custom type.

List the filter rules Gramps offers in a namespace. This is the vocabulary that `query_records` and GrampsQL cannot reach: "is a descendant of", "has a common ancestor with", "matches another filter". Read it before building a custom filter with create_filter.

The tree's type vocabularies (event types, attribute types, and so on). Check an unfamiliar type string here first: Gramps accepts an unrecognised one as a NEW custom type rather than rejecting it, so a typo permanently enters the tree's vocabulary.

List the reports this Gramps instance can generate. Gramps ships a full report engine — Ahnentafel, descendant reports, family group sheets, kinship, fan and relationship charts, statistics, and an end-of-line report that lists exactly where research stops. Each entry names the option keys it accepts; read the defaults with get_report_options before overriding any.

List all tags in the tree with their handle, name, and color. Use to see what labels already exist before tagging (tag_object matches by exact name).

List recent background jobs for this tree, newest first. Use when you have lost a task_id, or to see whether anything is still running before starting a write session.

Recent writes to the tree: what changed, when, by which user. Each entry's transaction_id is what undo_transaction takes. Useful for "what did that bulk pass actually do?" and for finding the transaction to reverse when it did the wrong thing.

Audit: list events that lack a citation or are tagged UNSOURCED. This is the core quality query for a fully-cited tree -- run it to find facts that still need a source. Returns each offending event with its person, type, date, and the reason ('no-citation' or 'tagged-unsourced').

Merge two objects that are the same thing. Dry-run by default. This uses Gramps' own server-side merge: every reference to `drop` is re-pointed at `keep` and the subordinate lists are unioned, in one transaction. Do NOT do this by hand: a manual merge that misses one of the lists the dropped object carries loses what was on it. Before merging, be sure they really are one thing. Two records OF the same event are two documents: an index entry and the register page it indexes stay separate, and merging them would turn two independent citations into one, silently weakening every fact that rested on both. Conversely, the same census page entered once per household member IS one document, and leaving the duplicates makes single-sourced facts look corroborated. Reversible: the merge is one transaction, so list_transactions + undo_transaction can back it out.

Run OCR on a document image, server-side, to locate text within it. A finding aid, not evidence. OCR output is a machine's guess at the writing, and it is at its worst on exactly the handwritten records that matter most. Use it to find WHERE something appears in a long scan; read the image before citing what it says.

Parse pasted shared-segment data into structured segments and totals. Use this to check what a match file actually contains before recording it. Returns each segment plus the total and largest-segment centiMorgans. If nothing parses, `parsed` is false and the reason is given. That distinction matters: the server answers unreadable input with zero segments and a success status, which would otherwise read as "this person shares no DNA" rather than "I could not read that".

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 = 0` * anonymous media: media where `desc = ""` 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.

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.

Rebuild the full-text search index. `search_text` reads a stored index, and nothing refreshes it after writes. Run this after a bulk import or a large editing session, or searches will quietly miss everything added since the last build. Returns a task_id to poll with get_task.

Generate a report and return the file it produced. Living people and private records are left out (living_people 0, incl_private false) unless you pass those options or include_private; Gramps' own default includes both. Usually runs in the background, returning a task_id to poll with get_task.

Search people by name substring and optional birth-year range. Bulk output: probably-living people (born < 110 years ago with no recorded death) and records marked private are returned as redacted stubs (ids only) unless include_private is set. Fetch a specific person by id with get_person if you need their detail.

Set (or clear) the Gramps private flag on an object. Private records are withheld from bulk output (queries, searches, tree walks, timelines, reports) unless a call passes include_private.

Attach a named Tag to an object, creating the Tag if it doesn't exist yet. Tags are lightweight cross-cutting labels ('Verified', 'Needs review', 'DNA-confirmed'). Matching is by exact name; an existing tag is reused.

Detach a citation from an object, deleting it if it is left orphaned. Detaching without deleting is how orphan citations accumulate: the fact the citation supported is gone, but the citation sits in the database still looking like evidence of something. Use this when a citation was attached to the wrong fact, or when a superseded bucket citation is replaced by the real record.

Undo a past transaction, after checking whether it can be undone cleanly. A conflict means an object was edited again after this transaction; undoing anyway throws that later edit away. The conflict check is free and runs first, so the default tells you what you are dealing with before anything changes.

Correct, retype or remove one alternate name, in place. Edited in place, the name keeps its citations. The primary name is update_person(name=...); a new name is add_alternate_name.

Change a child's relationship to the father or mother -- a stepson held as a birth child -- in place. The child keeps the link's citations, notes and its place in the birth order, which detaching and re-adding the child loses.

Edit a citation's locator, confidence, date, or the source it points at. A page-less citation on a long document is not a locator, and a confidence is a per-instance judgement, not a property of the source class. IMPORTANT: a citation carries ONE confidence, and it belongs to ONE claim. Every fact attached to this citation shares whatever you set here. If the same page supports a second, different claim (a census page proving both "this child appears here" and "these are her parents"), make a SECOND citation on the same source and page -- do not re-grade this one.

Re-write many citations' pages or confidences in one call -- a sweep. Each row is update_citation: its own write and transaction. A row whose live page no longer starts with expect_page_prefix is reported as drifted, not overwritten. Rows report applied, unchanged, drifted, missing or error.

Edit an existing event in place: its type, date, place or description. Only what you pass changes. The event keeps its id, citations, notes, media and every person sharing it, so correct a wrong type or an unsupported place here rather than replacing the event. Citations: cite_event.

Edit a media object's description, date, or path.

Set scalar fields on any object -- the escape hatch for places, notes, repositories and the rest. Only scalar fields are settable. Structural lists (citation_list, event_ref_list, media_list, ...) are refused on purpose: replacing one wholesale is exactly how references get silently dropped. Each has its own tool -- cite_object, detach_object, tag_object, attach_media.

Edit a person's gender, primary name, or privacy flag. Replacing the primary name preserves the old one as an 'Also Known As': a name in the tree came from some record, and dropping it loses the link to whatever document used it. To add a name without replacing the primary one, use add_alternate_name.

Edit a place's type, parent enclosure, name, title, or coordinates. This is the tool update_object_fields deliberately refuses to be: place_type and the enclosure are structural, so they get guard rails here -- the parent must already exist, setting it cannot create an enclosure cycle, and a place holding several dated enclosures (a territory-to-state succession) is refused rather than silently flattened. Aim for every place typed, every non-country place parented, and street addresses on events rather than in the place tree.

Edit an existing source's title, author, publication info, and/or abbreviation. Only the fields you provide are changed; the rest are left as-is.

Edit or remove ONE existing URL entry on a person, place, or repository. add_url can only append -- this corrects an entry already there (the classic case: a Find a Grave link filed under the wrong type). The other fields on the object are untouched.

Run Gramps' own genealogical plausibility checks over the whole tree. This is a different audit from the citation ones. `list_unsourced_facts` asks whether a claim has evidence; this asks whether a claim is possible — a mother bearing a child at nine, a marriage lasting 120 years, a date that will not parse. A wrong date can be impeccably sourced, so these catch what a citation sweep cannot. Leave the thresholds alone on a first run; the server's defaults are the conventional ones. Tighten a specific bound when chasing a specific class of error. May run in the background, in which case a task_id comes back — poll it with get_task.