nomenclature_query

Building a custom nomenclature or summary table

Nomenclature (BOM) and sheet-summary tables aren't fixed layouts — each one is backed by a query you build interactively, over the same views The project database documents. The same builder also drives Projet → Exporter au format CSV, for a report you want as a file rather than a table on a sheet.

Source: sources/dataBase/ui/elementquerywidget.{cpp,h} (nomenclature), sources/dataBase/ui/summaryquerywidget.{cpp,h} (sheet summary) — wired into a table's properties via projectdbmodelpropertieswidget.cpp, and into the CSV export dialog via ui/bomexportdialog.{cpp,h}.

---

1. Two builders, two views

Widget	Queries	Table it configures
ElementQueryWidget	element_nomenclature_view	nomenclature / BOM
SummaryQueryWidget	project_summary_view	sheet summary

Both work the same way: pick columns, order them, optionally filter and group, and the widget assembles the SELECT for you.

---

2. Picking and ordering columns

A two-list layout: available columns on one side, chosen columns on the other. Double-click (or the Add button) moves a column across; Up/Down buttons reorder the chosen list, which is also the column order the finished table renders in.

---

3. Filtering

Select a chosen column and set a filter on it. Seven modes:

Filter	SQL it builds
No filter	(column ignored for filtering)
Not empty	column != ''
Empty	column IS NULL OR column = ''
Contains	column LIKE '%value%'
Does not contain	column NOT LIKE '%value%'
Is equal	column = 'value'
Is not equal	column != 'value'

The first two need no value and disable the text box; the rest take one.

Which kinds of element are listed

The Type d'éléments (kind of elements) box of the nomenclature builder has one tick per kind:

Tick	Lists
Tous (all)	every kind below
Simples	plain symbols
Borniers	terminals
Organes de protection	protective devices
Contacteurs et relais	contactors and relays
Vignettes	thumbnails
Boutons et commutateurs	push buttons and switches
Automates (MAE/SPS)	PLCs
Contacts esclaves	contact blocks: the slave elements linked to a coil or other master (see Linking elements)

Contacts esclaves is unticked by default in a nomenclature table placed on a sheet, so tables keep the rows they had. In the CSV export (§7) it is ticked by default, so each contact block, which usually has its own order code, gets a row of its own — the same rows as --export-bom on the command line. Untick it to leave contact blocks out of the export.

---

4. Grouping, counting, and dropping to raw SQL

• Group by a column, to roll up rows — e.g. one row per manufacturer reference instead of one per element.
• Count — a running total alongside the grouping.
• Edit SQL query — a checkbox that hands you the generated SELECT directly for hand-editing. This is the escape hatch for anything the column/filter builder can't express; once you've edited it by hand, the widget is just showing you raw SQL, not trying to keep the two in sync. Once you're editing raw SQL, nothing restricts the FROM clause to the view the builder normally targets — you can query any table the project database exposes. What is restricted, and checked whether you got here by hand-editing or by typing a query from scratch, is covered next.

---

5. Saving a configuration for reuse

Give the current column/filter/group setup a name and save it; load it back later rather than rebuilding a report from scratch every time. Handy for a BOM layout you use across many projects.

---

6. Read-only enforcement

Whatever you type into "Edit SQL query" has to be a single SELECT or WITH ... SELECT statement. This is checked at two levels:

• As you type, the field's border turns red and a message appears underneath explaining why — before you've tried to run or save anything.
• Whenever the query actually runs — Preview, CSV export, or inserting the table onto a sheet — as a second, independent check. A query that reached this widget some other way (loaded from a saved report, or from a table already placed on a sheet) is checked here too, not just the live typing feedback.

The quick check rejects a query that isn't a single statement (a trailing ; is fine, a second one after it is not) or doesn't start with SELECT/WITH. On its own that could be fooled — WITH x AS (SELECT 1) DELETE FROM element starts with WITH — so when a query runs, SQLite itself runs it in read-only mode (PRAGMA query_only) and refuses anything that would write, before any row is touched. This also covers a query stored inside a project file, which runs when the project opens.

---

7. Live preview, and the CSV export's own options

Projet → Exporter au format CSV opens this same column/filter/SQL builder inside a dedicated export dialog, with a Preview button below it: run the current query and see the actual result in a table before deciding to save it as a CSV file. This is the export path specifically — inserting a table onto a sheet (Projet → Ajouter une nomenclature / Ajouter un sommaire) uses the same builder widget but doesn't have a separate preview step, since the table itself is the live result once placed.

Above the builder, the export dialog has two ticks of its own:

Option	Default	Does
Formater en tant que liste de materiel (format as a bill of materials)	unticked	groups the rows by designation and adds a count column, so each part appears once with its quantity
Laisser de côté les jonctions (leave out the junctions)	unticked	drops the rows of junctions: terminal-type elements with no label, no designation, no manufacturer and no manufacturer reference — the splice, corner and cross symbols some people draw where wires branch. A terminal block with a label or a part number stays

With junctions drawn as symbols, they can be most of a parts list: on one reporter's cabinet, 109 of 151 rows were empty junction rows (issue #1178). Leaving out junctions and contact blocks (§3) are also options of the command-line export (--no-junctions, --no-slaves, see CLI reference).

---

8. Sharing a report between users or installs

Saved reports (§5 above) live in nomenclature.json, in this install's own config directory — there's no built-in way for someone else to see a report you've saved, until now:

• Exporter... writes every saved report to a .json file you choose.
• Importer... reads one of those files back in, merging its reports into your own nomenclature.json. A name that already exists locally isn't overwritten silently — you're asked, per report, whether to replace it.

Both buttons sit next to the existing save/load controls in §5.

---

9. What this is not

• Not a general SQL client, once you leave "Edit SQL query" mode: the column/filter builder only ever targets the one view it's bound to (element_nomenclature_view or project_summary_view). "Edit SQL query" itself can target any table — see §4 — but every query, built or hand-written, still has to be read-only (§6).
• Not live outside the app. Like the rest of the project database, this queries the in-memory cache — see The project database for what that means and doesn't mean.
• Not the same as --export-bom. The CLI export reads the same view but with its own fixed column set — see Automating QElectroTech. This widget is for a table rendered on a sheet, and its column choices don't affect the CLI export or vice versa.

---

See also: The project database · Automating QElectroTech