Querying your design

A check answers “does my design break this rule?” A query answers a question you make up on the spot: “which nets carry more than 12V?”, “which parts have no datasheet?”, “how many parts sit on each net?”. agni query lets you search your whole design as data, and every answer comes back with its source so you can go check it.

The tool turns your design into a set of simple facts. A net has a voltage, a part sits on a net, a datasheet lists a limit, a copper track has a width. A query is a question over those facts.

The facts you can ask about ¶

Each fact is a named relation with a few fields. You query them by name:

The datasheet facts need a parameter set (--params), the board facts need a .kicad_pcb or an IPC-2581 board. Ask for a fact your design doesn’t carry and you simply get no rows. The tool never makes one up.

That table is the short form. Every relation also has a full card covering what it means for hardware, how the projection is built, and the cases where an empty result is not a clean answer. The ones this page leans on are inlined at the bottom of this page; the complete set is the relation catalog.

Writing a query ¶

A query is a list of facts separated by commas, an optional filter, and an optional => that picks which columns to show:

component.mpn(?ref, ?mpn), net.max_voltage(?net, ?v), ?v < 30  =>  ?ref, ?net

• ?ref, ?mpn, ?net, ?v are variables, blanks the tool fills in.
• Reusing a variable joins: ?net in two facts means “the same net in both”.
• ?v < 30 filters. Operators: < <= = != > >=. Text in double quotes: "VIN". Numbers plain.
• => ?ref, ?net picks the answer columns. Omit it to show every variable.

That is the whole language. The examples below build on it.

Start here: the five-rung ladder ¶

These are the starter queries the panel offers as click-to-run chips (and agni query --examples prints the same set). Each adds exactly one idea over the one before. Run one, read the result, then edit it. Every rung names its concept, with a one-line analogy for the SQL-literate.

1. Every part on every net (projection) ¶

component-on-net(?ref, ?net) => ?ref, ?net

A single fact is already a question. This lists each part and the net it sits on. => picks the answer columns, SQL’s SELECT list, with the relations as the tables.

2. Rails above 3V (filter) ¶

net.max_voltage(?net, ?v), ?v > 3 => ?net, ?v

A bare comparison prunes rows, a WHERE clause. Operators: < <= = != > >=. Numbers plain, text in "quotes".

3. Parts sitting on a rail above 3V (join) ¶

component-on-net(?ref, ?net), net.max_voltage(?net, ?v), ?v > 3 => ?ref, ?net, ?v

Reusing ?net in two facts means “the same net in both”, that is a JOIN ... ON. Joins are how you connect what a part is, where it sits, and what its rail carries.

The two relations are separate tables of facts until a variable appears in both. That shared ?net is what pairs a row on the left with a row on the right, and ?v > 3 then decides which of the paired rows survive.

4. Parts on USB nets (predicate) ¶

component-on-net(?ref, ?net), contains(?net, "USB") => ?ref, ?net

contains is a test over an already-bound value, SQL’s LIKE '%USB%'. prefix/suffix are the anchored variants.

5. Reachable through series pass elements (recursion) ¶

reaches(?from, ?net) => ?from, ?net

reaches walks connectivity transitively through series passives (a resistor, an inductor, a ferrite bead, a fuse), a recursive CTE / transitive closure over the connectivity graph. It answers “what does this rail actually feed after the filter”, which no per-net question can see across a series element.

Where these commands run ¶

Every transcript below is generated by running the command shown, so each one works as written, from the working directory its sample lives in. Three samples appear, all checked into a clone of the engine repo:

Point any of them at your own design instead and the same queries run. Nothing here depends on the sample beyond the names it happens to carry.

Going further ¶

Find something by name ¶

entity(name, kind) is the relation that names what exists. Every other relation ranges over a relationship, so a search built on one inherits its blind spots: looking through component-on-net cannot find a part that sits on no net, because such a part has no row there.

$ agni query designs/gateway/gateway.edn 'entity(?name, ?kind), contains(?name, "CAN") => ?name, ?kind'
name       kind  provenance
CAN1_CANH  net   designs/gateway/gateway.edn:CAN1_CANH
CAN1_CANL  net   designs/gateway/gateway.edn:CAN1_CANL
CAN1_RXD   net   designs/gateway/gateway.edn:CAN1_RXD
CAN1_TXD   net   designs/gateway/gateway.edn:CAN1_TXD

4 result(s)

kind is component, net or bus, so you can scope the search:

$ agni query designs/gateway/gateway.edn 'entity(?name, "component"), prefix(?name, "U") => ?name'
name  provenance
U1    designs/gateway/gateway.edn
U2    designs/gateway/gateway.edn
U3    designs/gateway/gateway.edn
U4    designs/gateway/gateway.edn
U5    designs/gateway/gateway.edn

5 result(s)

The string predicates (contains, prefix, suffix, glob, match) decide how the name is matched. A leading wildcard is the case prefix cannot express, which is how you find every net named for the rail it carries whichever block named it:

$ agni query designs/gateway/gateway.edn 'entity(?name, "net"), glob(?name, "*_1V8") => ?name'
name         provenance
PMIC_IO_1V8  designs/gateway/gateway.edn:PMIC_IO_1V8

1 result(s)

The cases only this relation reaches are the ones worth finding during a review. A part connected to nothing:

$ agni query fires.edn 'entity(?ref, "component"), not component-on-net(?ref, ?any) => ?ref'
ref  provenance
X1   fires.edn

1 result(s)

A net with nothing on it, here against a board that has none:

$ agni query fires.edn 'entity(?net, "net"), not component-on-net(?any, ?net) => ?net'
no results

That empty answer is the answer. Asking for something a design does not carry returns no rows rather than an invention, which is the same property the relation cards spend their space on.

Pins are not in entity, because a pin is named by two things rather than one. Enumerate those with pin(?ref, ?pin), which is also what to reach for when you want to find a pin: the viewer’s find-by- name box searches entity, so it will not turn one up.

In the web viewer this has a front door. The query panel has a Find by name mode: type part of a name, and it writes the same query into the box, runs it, and hands you back the query. Each hit is clickable, whatever sort of thing it turns out to be, so a search lands you on the drawing and leaves a sentence you can edit into a better question.

Reading a result cell in the viewer ¶

A cell that names a component, a net or a bus is a link: clicking it highlights that thing on the drawing. The small chips beside it are the sheets it appears on, one per sheet, and clicking one opens that sheet. They are not a grouping of related names, and they have nothing to do with the cell being a net in particular. Any locatable cell gets them.

AVDD_3V3   [ 04_POWER ] [ 07_SENSOR ] [ 11_MCU ] [ +2 ]

That row says the net AVDD_3V3 is drawn on at least five sheets, three of them named. A single-sheet design shows no chips at all, because there is nowhere to navigate. The strip caps at three and counts the rest, since past a handful the interesting fact is how many sheets a thing spans rather than which; clicking the +N expands it.

Whichever entity is on the drawing right now is marked in the table, and so is the chip for the sheet you are looking at. That is what tells you where you are after a click sends the canvas somewhere, and it follows the viewer rather than your last click here: pick something on the drawing instead and the mark moves to that.

Find parts stressed above their datasheet rating ¶

This joins what the part is (component.mpn), what its datasheet says (param), where it sits (component-on-net), and the rail’s voltage (net.max_voltage), then keeps only the ones where the rated maximum is below the rail.

$ agni query regulator.fires.kicad_sch --params ./params/ 'component.mpn(?r,?m), param(?m,"VIN",?vmax), component-on-net(?r,?n), net.max_voltage(?n,?rail), ?vmax < ?rail => ?r, ?m, ?vmax, ?n, ?rail'
r   m       vmax  n     rail  provenance
U1  LM1117  20    +24V  24    datasheet "SNOS412Q - FEBRUARY 2000 - REVISED JANUARY 2023" page 4, "7.1 Absolute Maximum Ratings" (hand, confidence 1) ; regulator.fires.kicad_sch

1 result(s)

U1 (an LM1117) sits on a +24V rail, but its datasheet caps VIN at 20V. The provenance column cites both sides, the schematic and the datasheet page, so you can open each and confirm.

Find undatasheeted parts (negation) ¶

not keeps the rows where a fact is absent. “Parts on a net that have no MPN” (the component.mpn relation is populated from the datasheet join, so pass --params):

$ agni query regulator.fires.kicad_sch --params ./params/ 'component-on-net(?r,?n), not component.mpn(?r,?m) => ?r'
r   provenance
J1  regulator.fires.kicad_sch

1 result(s)

J1 is placed but carries no part number, so a datasheet can never be matched to it.

A not has to be anchored. At least one variable inside it must also appear in a positive relation, so the negation is about the row rather than about the design. Above, ?r is the anchor: not component.mpn(?r,?m) asks whether THIS part has a part number. The ?m is free on purpose and means “for any value”, which is what you want.

Drop the anchor and the question changes without looking like it has:

entity(?n,"net"), not component.class(?tp,"test_point") => ?n

?tp appears nowhere else, so that asks whether the design contains no test point AT ALL, and on a board that has even one it filters away every row. It used to answer “no results”, which reads as a fact about the board. It is now an error naming the unanchored variable.

To negate a pair of relations, name them first. not takes one relation, so the question that spelling was reaching for, nets with no test point ON THEM, needs both component-on-net and component.class to be true of the same part. Define a relation for that and negate it by name:

has_test_point(?n) :- component-on-net(?tp,?n), component.class(?tp,"test_point");
entity(?n,"net"), not has_test_point(?n) => ?n

Clauses are separated by ;, a clause containing :- defines a relation, and the one clause without one is the question. This is the general shape for any “X with no related Y”, which is most of what a coverage question asks: rails with no decoupling, buses with no pull-up, parts with no protection.

A defined relation is fully derived before anything negates it, so the answer does not depend on the order you wrote the clauses in.

Count parts per net (aggregation) ¶

count, min, max, sum and list summarize. Group by the plain columns. The aggregate reduces the rest:

$ agni query regulator.fires.kicad_sch 'component-on-net(?r,?n) => ?n, count(?r)'
n     count(r)  provenance
+24V  2         regulator.fires.kicad_sch
GND   1         regulator.fires.kicad_sch

2 result(s)

Keep only some groups (having) ¶

A comparison in the question filters facts, one at a time, before there is any group. To ask about the group itself you need having, which runs after the reduce. “Nets carrying more than one part”:

$ agni query regulator.fires.kicad_sch 'component-on-net(?r,?n) => ?n, count(?r) having count(?r) > 1'
n     count(r)  provenance
+24V  2         regulator.fires.kicad_sch

1 result(s)

The aggregate does not have to be a column. Drop count(?r) from the projection and keep the having, and the answer is the nets rather than the tally, which is usually what a coverage question wants:

component-on-net(?r,?n) => ?n having count(?r) > 1

Counting values instead of bindings (distinct) ¶

An aggregate reduces one entry per ANSWER, not per distinct value. A question that joins two things produces one answer per combination, so a part appears once for every partner it was paired with, and count counts all of them. distinct reduces the values instead:

$ agni query regulator.fires.kicad_sch 'component-on-net(?r,?n), component-on-net(?other,?n) => ?n, count(?r), count(distinct ?r), list(distinct ?r)'
n     count(r)  count(distinct r)  list(distinct r)  provenance
+24V  4         2                  J1 U1             regulator.fires.kicad_sch
GND   1         1                  U1                regulator.fires.kicad_sch

2 result(s)

+24V carries two parts. Asking twice about what sits on a net pairs each with each, so there are four answers and count(?r) reports 4. count(distinct ?r) reports the 2 you meant, and list(distinct ?r) names them.

distinct works the same way on every aggregate, list included, so a projection carrying both count(?r) and list(?r) always describes the same set. If you are ever unsure which you have, select both spellings and compare, as above.

The other way to get there is a defined relation, which projects the extra column away before the group forms:

on(?r,?n) :- component-on-net(?r,?n), component-on-net(?other,?n);
on(?r,?n) => ?n, count(?r)

The defined relation keeps ?r and drops ?other, so its tuples are already one per part per net and a plain count matches count(distinct ?r). Drop ?r from the head too and you are counting nets, not parts, which is the mistake this idiom is easiest to make.

Search the board (any tier, one language) ¶

Board facts query the same way. “Nets routed thinner than 0.3 mm”:

$ agni query board.kicad_pcb 'board.track_width(?net,?w), ?w < 0.3 => ?net, ?w'
net  w     provenance
SIG  0.25  board net SIG

1 result(s)

And you can join across the schematic, the datasheet, and the board in one question, “a net routed thin that carries a high-current part”:

board.track_width(?net,?w), component-on-net(?ref,?net), component.mpn(?ref,?mpn), param(?mpn,"IOUT",?i), ?w < 0.25 => ?net, ?ref, ?i

A single query can span copper, connectivity, and datasheets at once, and each answer stays traceable back to the layer and the datasheet page.

Follow a rail through passives (reaches) ¶

reaches(from, net) walks connectivity through series passives (resistors, ferrites, fuses). It is how you ask “what does this rail actually feed after the filter”. “Everything reachable from GND”:

$ agni query board.kicad_pcb 'reaches("GND", ?n) => ?n'
n    provenance
GND  reaches from GND
SIG  reaches from GND

2 result(s)

See what the walk crossed (route) ¶

reaches tells you a net is reachable. It does not tell you what stands between the two, so you end up opening the schematic to check an answer the tool already knew. route(from, net, path) is the same walk with that half kept: path binds the nets in crossing order with the part crossed between each pair, so an answer carries the evidence for itself.

$ agni query board.kicad_pcb 'route("GND", ?n, ?path) => ?n, ?path'
n    path                provenance
GND  GND                 route from GND
SIG  GND -> [R1] -> SIG  route from GND

2 result(s)

Read GND -> [R1] -> SIG as: the walk left GND, went through R1, and arrived at SIG. The names outside the brackets are nets and the one inside is the part. The first row is the reflexive one, since a net reaches itself at zero crossings and its route is its own name.

It answers with a route and not every route. The walk is breadth-first, so where two resistors bridge the same two nets you get the shorter one and no mention of the other. And a route never ends on a rail or a plane, because the walk refuses to enter one at all. For the pin-to-pin form, which does end on a rail and reports the test points sitting on each net along the way, use agni trace.

Asking under your own vocabulary ¶

Some relations do not report what is in the file; they report what the engine believes. rail, feedback, and pin.type are resolved from a vocabulary at the moment the design is read.

That vocabulary is the built-in one unless you say otherwise, and it is anchored on the names most boards use. On a board that names rails function-first, what the built-in vocabulary returns can be badly wrong for your project.

Isolating that takes moving two things aside rather than one, which is itself worth knowing. The tutorial project declares its conventions.yaml, so naming the design applies it automatically and the before-state is otherwise unreachable. And a seeded datasheet’s pin functions establish the rail role on their own, so with params/ in place this board classifies all four rails whatever the naming vocabulary says. Move both and the question is about NAMING alone:

$ mv conventions.yaml conventions-off.yaml
$ mv params params-off
$ agni query designs/gateway/gateway.edn 'rail(?n) => ?n'
n    provenance
GND  designs/gateway/gateway.edn:GND

1 result(s)

Pass your own vocabulary and ask again, with the corpus still aside so the pair differs in exactly one thing:

$ mv params params-off
$ agni query designs/gateway/gateway.edn 'rail(?n) => ?n' --conventions conventions.yaml
n               provenance
GND             designs/gateway/gateway.edn:GND
PMIC_CORE_3V3   designs/gateway/gateway.edn:PMIC_CORE_3V3
PMIC_IO_1V8     designs/gateway/gateway.edn:PMIC_IO_1V8
PMIC_MAIN_12V0  designs/gateway/gateway.edn:PMIC_MAIN_12V0

4 result(s)

Nothing about the design changed. This is the loop to author a lexicon in: ask, compare against the rails you know the board has, fix the pattern, ask again. See Naming conventions.

The datasheet route is the other way to the same answer, and it needs no lexicon at all: that is what the corpus was doing before it was moved aside, and Datasheets is where it lives.

Only the config’s lexicon half is used here, since a query runs no rules.

In the viewer ¶

The viewer has a Query panel that runs the same queries against the design you have open. Type a query, press Run (or ⌘/Ctrl+Enter), and the results appear as a table. Each row has a small toggle that expands its provenance, so the citations stay out of your way until you want them.

The panel runs the query on the server, over the open file, so you get the same answers as agni query without leaving the design. The vocabulary control in the top bar applies here too, and a query and a check in the same session then answer under the same vocabulary.

Datasheet (param) facts are not yet wired into the viewer. A query over param returns nothing there, and datasheet joins stay on the CLI for now.

You do not have to memorize the vocabulary. Below the query box the panel lists every relation as a click-to-insert chip, grouped by kind (Netlist, Board, Datasheet, Predicates, and any extension relations your deployment adds). Clicking a chip drops its template at your cursor, so component-on-net inserts component-on-net(?ref_des, ?net) ready to wire into the rest of the query. Hover a chip to see its full signature and a one-line description.

Every answer is checkable ¶

The last column is always provenance, the source of the facts that produced the row: a schematic file, or a datasheet document, page, and table, or a board net. A query never gives you a number you cannot trace back to its source, so a search you run is one you can verify. In the viewer the provenance rides behind each row’s expand toggle instead of a trailing column.

Taking a view out of the tool ¶

A question you keep asking is a view, and --format is how one leaves the tool.

agni query designs/gateway/gateway.edn \
  'component-on-net(?r,?n), component.class(?r,"test_point") => ?n, ?r' \
  --format markdown --title "Test point coverage" > tp-coverage.md

Five formats. text is the aligned terminal table and is the default. csv opens in a spreadsheet. json is for tooling. markdown and html are documents: they carry the title, the design, and the query itself, above the answer.

That last part is the point of the flag rather than a decoration. A table pasted into a ticket is a screenshot, and nobody downstream can re-run it, scope it differently, or disagree with it. A view carries the question that produced it, so it can be checked the way any other claim can.

Two behaviours worth knowing, both deliberate:

• csv carries no preamble. No title, no query, no count, because its first row has to be the header for a spreadsheet or a script to bind to it. The document formats carry the question; csv carries the table.
• An empty result still says something. csv writes the header alone, so a consumer can tell a view that matched nothing from a run that produced no file. markdown and html write a sentence rather than an empty table, because a table with no rows reads as an omission rather than an answer.

The design is named by its mount URI, never by the path on the machine that ran the query, so a view is safe to commit or mail.

agni query designs/gateway/gateway.edn 'rail(?n) => ?n' --format csv > rails.csv

Following a signal across the parts in the way ¶

A query joins facts. It cannot follow a path, because a path is not a fact: it is a sequence, of unknown length, and there is no relation whose columns can hold one. So “which nets carry a resistor” is a query and “what does this pin go through to reach that one” is not.

agni trace is that second question. It walks from one pin to another through the series parts that split a net without breaking the path, and prints what it crossed.

$ agni trace designs/gateway/gateway.edn --from U3.10 --to U1.5
U3.10 (NRST) --> R3 --> U1.5 (PG)

route
  U3.10 (NRST)
  net MCU_NRST
  cross R3 (resistor) pin 1 --> pin 2
  net PMIC_PG
  U1.5 (PG)

routed: 1 crossing, 2 nets, searched to a radius of 6

$ agni trace designs/gateway/gateway.edn --from U1.2 --to U3.2
U1.2 (VOUT) --> U3.2 (VDDIO)

route
  U1.2 (VOUT)
  net PMIC_CORE_3V3
      probe: TP1.1
      also: C1.1 (capacitor), C2.1 (capacitor), U2.1 (ic), U4.1 (ic), U5.1 (ic)
  U3.2 (VDDIO)

routed: 0 crossings, 1 net, searched to a radius of 6

$ agni trace designs/gateway/gateway.edn --from U3.10 --to U1.1
no route: U3.10 (NRST) --> U1.1 (VIN)

  U3.10 (NRST) on net MCU_NRST
  U1.1 (VIN) on net PMIC_MAIN_12V0

no series path from MCU_NRST to PMIC_MAIN_12V0 within 6 crossings.
The walk crosses resistors, inductors, ferrites and fuses.
A capacitor is a DC block and is never crossed.
A rail or plane may END a route and is never passed through.

Three things in that output are the point of the command.

The part in the middle. R3 sits between the MCU’s reset pin and the PMIC’s power-good output, so the two pins are on different nets and no per-net question can see that they are joined. A series element splitting a net is the ordinary case, not an awkward one, which is why “are these connected” is so often answered wrongly by eye.

What else is sitting there. The parts on each net are listed, probe points first, because a reviewer reading a route is usually working out where to put a probe or which capacitor is in the way. Filtering the output down to the series elements would remove the most useful thing on the line.

A no is an answer. The third trace found nothing, and it says which nets the two pins are actually on, how far it searched, and what it will and will not cross. A capacitor is a DC block, so the walk never crosses one; a rail or plane can be where a route ENDS but is never passed through, since a supply joins everything to everything and a route through one would mean nothing.

What the command refuses to do is guess. A pin you name that the design does not have is an error rather than an empty result, because a name spelled wrong in a declaration and two pins that are genuinely unconnected are opposite problems, and reporting the first as the second sends you to look at the board instead of at what you typed.

What a query is not ¶

A query reports, it does not judge. It has no notion of pass/fail, that is what checks are for. If you find yourself running the same query to catch a recurring problem, that is a sign it should become a rule.

Reference: the relations used here ¶

These are the full cards for the relations the examples above use, inlined so you do not have to leave the page. They are the same text the relation catalog serves, and they are generated from the relation definitions themselves, so they cannot drift from what the engine actually projects.

Read the “absence is not a pass” section on any relation you scope a question by. An empty result means the fact is absent from your design, which is a different statement from “nothing matched”, and the cards say which is which.

net.max_voltage(?n, ?v) => ?n, ?v

net.max_voltage(?n, ?v), ?v > 3, component-on-net(?r, ?n) => ?r, ?n, ?v

component.mpn(?r, ?m) => ?r

component.mpn(?r, ?m), param(?m, ?sym, ?max) => ?r

component.class(?r, ?c) => ?c

component.class(?r, "diode"), component-on-net(?r, ?n) => ?n

component-on-net(?r, ?n) => ?r, ?n

component-on-net(?r, ?n), component.class(?r, "diode") => ?r, ?n

reaches(?n, ?rn, 2)           # exactly 2 crossings — SKIPS a part sitting 1 away
reaches(?n, ?rn, ?h), ?h <= 2 # within 2 crossings — what a protection question means

reaches("VBUS_IN", ?net) => ?net

reaches("VBUS_IN", ?net), component-on-net(?r, ?net) => ?r

reaches(?n, ?rn, ?h), ?h <= 2, component-on-net(?t, ?rn), component.class(?t, "tvs") => ?n, ?t

reaches("VBUS_IN", ?net, ?hops) => ?net, ?hops

VBUS -> [R5] -> VBUS_F -> [L1] -> VDD_3V3

route("VBUS", ?net, ?path) => ?net, ?path

route("SPI_CS", ?net, ?path) => ?net, ?path

route(?from, ?net, ?path), component-on-net(?ref, ?net), component.class(?ref, "test_point")
  => ?from, ?net, ?ref, ?path

board.track_width(?n, ?w) => ?n, ?w

board.track_width(?n, ?w), ?w < 0.2 => ?n, ?w