GenQuery (genq)

A Terminal-based RootsMagic Reporting Engine

GenQuery executes blocks of Nushell code to query and parse RootsMagic's SQLite database (RootsMagic version 10 only) to generate tabular reports from the command line. This utility leverages Nushell's shell environment to create a quick, flexible and easy to use reporting tool.

In the examples below, all queries are filtered to the first 20 records for demonstration purposes only.

Screencast Example Queries:

Queries in screencast are filtered to the first 20 records for demonstration purposes only.

• genq list people | first 20 List all people in your database
• genq list sources | first 20 List sources
• genq list obits | first 20
• census 1910
• census RIN 2
• census year 1910 | where Surname == 'Iiams'
• census year 1910 | where Surname == 'Iiams' | sort-by Given

Example of GenQuery:

Example

Quick Start Guide:

Requirements:

• Modern Windows (Win10 or Win11)
• Modern MacOS (Intel and M processors)
• NuShell (genq install this if not present)
• RootsMagic 10 (RM10, RM8 and RM9 should also work well)

Installation:

Installation is performed via installation scripts via command-line. Guides are available for Windows and MacOS. For Windows, the installation script installs the Chocolatey package management software if not already present and uses it to install Nushell. Similarly for MacOS, the installation script installs the Homebrew package management software (if not already present) and uses it to install Nushell.

Caution

Currently, there is minimal testing on the various platforms. If you are operating within the requirements above and encounter a problem, please open an issue.

Getting Started:

A sample RootsMagic database of the U.S. Presidents is included with installation. After installation, GenQuery starts in a "demo" mode configuration where GenQuery queries this database. When you are comfortable using it, you can edit the "genq-config.nu" file to use your RootsMagic database. A "genq configure" command is under development to simplify updating configurations.

Note

GenQuery comes with a syncdb command. This command pulls a current copy of your production RootsMagic database to an GenQuery query location. GenQuery is designed to never touch your production database.

More About GenQuery:

Here is a full description of genq.

Updating Nushell and GenQuery:

Documentation for updating Nushell and GenQuery going forward is pending.

Known Limitations:

Note

String collation. RootsMagic ships a proprietary SQLite collation called RMNOCASE that folds both case and diacritics — so "Müller" matches "Mueller" and "café" matches "cafe" — for name, place, and source columns. Because GenQuery is multi-platform and Nushell's bundled SQLite layer cannot register custom collations from script, GenQuery uses SQLite's built-in NOCASE (ASCII-only case folding) as a workaround everywhere a comparison or sort against those columns is needed. Practical effects:

• Surnames, places, or sources containing diacritics may sort differently than they do in the RootsMagic UI.
• Distinct-count metrics (e.g., distinct surnames) can be marginally higher than RootsMagic reports, because diacritic variants don't merge.
• String-equality filters do not fold diacritics — where Surname == 'Muller' will not match a row stored as "Müller".

Numeric joins — which power the vast majority of GenQuery queries — are unaffected. RMNOCASE-aware behavior may be revisited if a Nushell SQLite plugin (or upstream extension-loading hook) becomes available.