Filter using the Gramps Query Language¶
The object list views (people, families, events, ...) have an optional advanced filter mode based on the Gramps Query Language (GQL).
To use it, type a query in GQL syntax and press enter (or hit the "apply" button). The view will be filtered by the query. If the query is invalid, the input field's frame turns red.
The GQL syntax is described below, copied from the GQL documentation.
Syntax¶
A GQL query is a string composed of statements of the form property operator value, optionally combined with the keywords and and or as well as parentheses.
Properties¶
class¶
Filters for the Gramps object class and can be one of person, family, event, place, citation, source, repository, media, or note.
Object properties¶
GQL supports querying nested properties of Gramps objects, e.g. primary_name.date.calendar. See below for a full list of properties – see also Gramps Data Model.
List elements by index¶
Individual elements in list-like properties can be accessed by positional index in square brackets. This can be combined with nested properties, e.g. primary_name.surname_list[0].surname.
length¶
This is a special property that returns the length of an array-like Gramps property, e.g. media_list.length > 0 to get objects with media references.
all, any¶
Two more special properties for array-like Gramps properties. all requires a condition to apply to all items of the list, any requires it to apply to at least one item. Both properties can be combined with other properties before and after. Examples: media_list.any.citation_list.length > 0 to return objects with media references that have citations; media_list.all.citation_list.length = 0 to return objects where all media objects do not have citations.
Array index¶
A numerical array index can be used to access specific elements of a list, e.g. child_ref_list[0] for the first child.
get_person, etc.¶
While all the preceding properties refer to a single Gramps object, it is also possible to filter on different objects referred to by the initial object. For instance, an event has a place handle in its place property. Using the get_place pseudo-property, GQL switches to the properties of that object. For instance, it is possible to search for class = event and place.get_place.name.value ~ York. This can also be combined with any or all, e.g. class = person and event_ref_list.any.ref.get_event.description ~ farmer.
Operators¶
=, !=¶
Equality or inequality. Examples: class = person, class != family
>, >=, <, <=¶
Comparison. Works for strings as well as numbers. Examples: confidence <= 1, change > 1712477760, gramps_id > "I2015"
~, !~¶
Contains or does not contain. Works for lists as well as strings. Examples: gramps_id !~ F00, author ~ David, family_list ~ "3a16680f7d226e3ac3eefc8b57a"
No operator/value¶
If no operator and value is given, the value is interpreted as a boolean (true or false). This works for
all types of properties and Python rules for casting to true/false are applied. For instance, the query private returns private objects; confidence returns objects where confidence is greater than 0; media_list returns objects with at least one media reference.
Values¶
Values can be numbers or strings. If numbers should be interpreted as strings or special characters like = are involved, enclose the value in strings. Examples: gramps_id = F0001, but gramps_id = "0001".
Commented examples¶
class = note and private and text.string ~ David
All private notes that contain the string "David" in their text
media_list.length >= 10
All objects (of any class) with 10 or more media references
class != person and media_list.any.rect
All objects that are not a person but have a media reference that is part of an image. Here, media_list.any.rect means that for each of the items in the media list, it is checked whether the rect (rectangle) property has a truthy value, meaning it is a non-empty list. (media_list.any.rect.length > 0 would have the same effect.)
class = family and child_ref_list.length > 10
Families with more than 10 children.
class = event and date.modifier = 0 and date.dateval[2] > 2020
Events where the date is a normal date (not a range etc.) and the year is after 2020.
note_list.any.get_note.text.string ~ "David"
All objects with at least one note that contains the string "David" in their text.
class = family and child_ref_list.all.ref.get_person.gender = 0 and child_ref_list.length = 3
All families with three daughters.
Full list of Gramps Properties¶
For a full list of Gramps properties, see the GQL documentation.