gramps-ql 0.4.0
A Python library to filter Gramps objects by a query syntax
License: MIT

# GQL &ndash; the Gramps Query Language

This Python library provides GQL, a query language to a [Gramps](https://github.com/gramps-project/gramps) database. The syntax is inspired by JQL, the Jira Query Language.

## Installation

```
python -m pip install gramps-ql
```

## Usage

You can iterate over objects in a database matching the query:

```python
import gramps_ql as gql

db = ... # A Gramps DbReadBase instance

# iterate over private people
query = 'class=person AND private'

for obj in gql.iter_objects(query, db):
    f(obj) # do something with the Gramps object obj
```

Alternatively, you can match individual objects:

```python
if gql.match(query, obj, db):
    print("Object matches query 🙂")
else:
    print("Object doesn't match query 🙁")
```

## 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](https://gramps-project.org/wiki/index.php/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

```sql
class = note and private and text.string ~ David
```

All private notes that contain the string "David" in their text


```sql
media_list.length >= 10
```

All objects (of any class) with 10 or more media references

```sql
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.)

```sql
class = family and child_ref_list.length > 10
```

Families with more than 10 children.

```sql
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.

```sql
note_list.any.get_note.text.string ~ "David"
```

All objects with at least one note that contains the string "David" in their text.


```sql
class = family and child_ref_list.all.ref.get_person.gender = 0 and child_ref_list.length = 3
```

All families with three daughters.


## Roadmap

GQL could be used in Gramplets or in Gramps Web (API).

The following improvements are currently being contemplated:

- Better support for dates, e.g. comparing a string to a date
- Performance improvements. Currently, the whole database needs to be read even for a simple query like `class=tag`.

Suggestions for improvment as well as contributions are welcome!

## Full list of Gramps Properties

The following properties of Gramps objects exist as of Gramps 5.2.

Here, `[]` indicates array properties, on which index (`[0]` etc.), `any`, `all`, and `length` are supported.

Obviously, many of those properties are only present on some of the primary Gramps object types.

```
abbrev
address_list
address_list[]._class
address_list[].citation_list
address_list[].city
address_list[].country
address_list[].county
address_list[].date
address_list[].date._class
address_list[].date.calendar
address_list[].date.dateval
address_list[].date.modifier
address_list[].date.newyear
address_list[].date.quality
address_list[].date.sortval
address_list[].date.text
address_list[].locality
address_list[].note_list
address_list[].phone
address_list[].postal
address_list[].private
address_list[].state
address_list[].street
alt_loc
alt_loc[]._class
alt_loc[].city
alt_loc[].country
alt_loc[].county
alt_loc[].locality
alt_loc[].parish
alt_loc[].phone
alt_loc[].postal
alt_loc[].state
alt_loc[].street
alt_names
alt_names[]._class
alt_names[].date
alt_names[].date._class
alt_names[].date.calendar
alt_names[].date.dateval
alt_names[].date.modifier
alt_names[].date.newyear
alt_names[].date.quality
alt_names[].date.sortval
alt_names[].date.text
alt_names[].lang
alt_names[].value
alternate_names
alternate_names[]._class
alternate_names[].call
alternate_names[].citation_list
alternate_names[].date
alternate_names[].date._class
alternate_names[].date.calendar
alternate_names[].date.dateval
alternate_names[].date.modifier
alternate_names[].date.newyear
alternate_names[].date.quality
alternate_names[].date.sortval
alternate_names[].date.text
alternate_names[].display_as
alternate_names[].famnick
alternate_names[].first_name
alternate_names[].group_as
alternate_names[].nick
alternate_names[].note_list
alternate_names[].private
alternate_names[].sort_as
alternate_names[].suffix
alternate_names[].surname_list
alternate_names[].surname_list[]._class
alternate_names[].surname_list[].connector
alternate_names[].surname_list[].origintype
alternate_names[].surname_list[].origintype._class
alternate_names[].surname_list[].origintype.string
alternate_names[].surname_list[].prefix
alternate_names[].surname_list[].primary
alternate_names[].surname_list[].surname
alternate_names[].title
alternate_names[].type
alternate_names[].type._class
alternate_names[].type.string
attribute_list
attribute_list[]._class
attribute_list[].citation_list
attribute_list[].note_list
attribute_list[].private
attribute_list[].type
attribute_list[].type._class
attribute_list[].type.string
attribute_list[].value
author
birth_ref_index
change
checksum
child_ref_list
child_ref_list[]._class
child_ref_list[].citation_list
child_ref_list[].frel
child_ref_list[].frel._class
child_ref_list[].frel.string
child_ref_list[].mrel
child_ref_list[].mrel._class
child_ref_list[].mrel.string
child_ref_list[].note_list
child_ref_list[].private
child_ref_list[].ref
citation_list
code
confidence
date
date._class
date.calendar
date.dateval
date.modifier
date.newyear
date.quality
date.sortval
date.text
death_ref_index
desc
description
event_ref_list
event_ref_list[]._class
event_ref_list[].attribute_list
event_ref_list[].attribute_list[]._class
event_ref_list[].attribute_list[].citation_list
event_ref_list[].attribute_list[].note_list
event_ref_list[].attribute_list[].private
event_ref_list[].attribute_list[].type
event_ref_list[].attribute_list[].type._class
event_ref_list[].attribute_list[].type.string
event_ref_list[].attribute_list[].value
event_ref_list[].citation_list
event_ref_list[].note_list
event_ref_list[].private
event_ref_list[].ref
event_ref_list[].role
event_ref_list[].role._class
event_ref_list[].role.string
family_list
father_handle
format
gender
gramps_id
handle
lat
lds_ord_list
lds_ord_list[]._class
lds_ord_list[].citation_list
lds_ord_list[].date
lds_ord_list[].date._class
lds_ord_list[].date.calendar
lds_ord_list[].date.dateval
lds_ord_list[].date.modifier
lds_ord_list[].date.newyear
lds_ord_list[].date.quality
lds_ord_list[].date.sortval
lds_ord_list[].date.text
lds_ord_list[].famc
lds_ord_list[].note_list
lds_ord_list[].place
lds_ord_list[].private
lds_ord_list[].status
lds_ord_list[].temple
lds_ord_list[].type
long
media_list
media_list[]._class
media_list[].attribute_list
media_list[].attribute_list[]._class
media_list[].attribute_list[].citation_list
media_list[].attribute_list[].note_list
media_list[].attribute_list[].private
media_list[].attribute_list[].type
media_list[].attribute_list[].type._class
media_list[].attribute_list[].type.string
media_list[].attribute_list[].value
media_list[].citation_list
media_list[].note_list
media_list[].private
media_list[].rect
media_list[].ref
mime
mother_handle
name
name._class
name.date
name.date._class
name.date.calendar
name.date.dateval
name.date.modifier
name.date.newyear
name.date.quality
name.date.sortval
name.date.text
name.lang
name.value
note_list
page
parent_family_list
path
person_ref_list
person_ref_list[]._class
person_ref_list[].citation_list
person_ref_list[].note_list
person_ref_list[].private
person_ref_list[].ref
person_ref_list[].rel
place
place_type
place_type._class
place_type.string
placeref_list
placeref_list[]._class
placeref_list[].date
placeref_list[].date._class
placeref_list[].date.calendar
placeref_list[].date.dateval
placeref_list[].date.modifier
placeref_list[].date.newyear
placeref_list[].date.quality
placeref_list[].date.sortval
placeref_list[].date.text
placeref_list[].ref
primary_name
primary_name._class
primary_name.call
primary_name.citation_list
primary_name.date
primary_name.date._class
primary_name.date.calendar
primary_name.date.dateval
primary_name.date.modifier
primary_name.date.newyear
primary_name.date.quality
primary_name.date.sortval
primary_name.date.text
primary_name.display_as
primary_name.famnick
primary_name.first_name
primary_name.group_as
primary_name.nick
primary_name.note_list
primary_name.private
primary_name.sort_as
primary_name.suffix
primary_name.surname_list
primary_name.surname_list[]._class
primary_name.surname_list[].connector
primary_name.surname_list[].origintype
primary_name.surname_list[].origintype._class
primary_name.surname_list[].origintype.string
primary_name.surname_list[].prefix
primary_name.surname_list[].primary
primary_name.surname_list[].surname
primary_name.title
primary_name.type
primary_name.type._class
primary_name.type.string
private
pubinfo
reporef_list
reporef_list[]._class
reporef_list[].call_number
reporef_list[].media_type
reporef_list[].media_type._class
reporef_list[].media_type.string
reporef_list[].note_list
reporef_list[].private
reporef_list[].ref
source_handle
tag_list
text
text._class
text.string
text.tags
text.tags[]._class
text.tags[].name
text.tags[].name._class
text.tags[].name.string
text.tags[].ranges
text.tags[].value
title
type
type._class
type.string
urls
urls[]._class
urls[].desc
urls[].path
urls[].private
urls[].type
urls[].type._class
urls[].type.string
```