obj_query
Queries schematic or PCB objects and reads their properties, with optional property-value filters and selected fields returned for each matching object.
Instructions
Query schematic OR PCB objects and read their properties.
Iterates objects of the given type, optionally filtering by property values, and returns the requested properties for each matching object.
Args: object_type: Altium object type constant. Schematic: "eNetLabel", "ePort", "ePowerObject", "eSchComponent", "eWire", "eBus", "eBusEntry", "eParameter", "ePin", "eLabel", "eLine", "eRectangle", "eSheetSymbol", "eSheetEntry", "eNoERC", "eJunction" PCB: "eTrackObject", "ePadObject", "eViaObject", "eComponentObject", "eArcObject", "eFillObject", "eTextObject", "eRuleObject", "eDimensionObject", "eConnectionObject" (the ratsnest: one line per unrouted connection, with X1, Y1, X2, Y2, Layer1, Layer2 and Net) properties: Comma-separated property names to return.
SCHEMATIC objects use the dotted spelling:
"Text,Location.X,Location.Y" for net labels
"Designator,Name,ConnectionX,ConnectionY" for pins.
ConnectionX/ConnectionY are the pin's ELECTRICAL end --
the point a wire or net label must sit on to attach.
Location is the BODY-side root and is NOT the connection
point; deriving the end by hand from Orientation and
PinLength is a common source of wrong conclusions about
what is wired.
"Designator.Text,Comment.Text,LibReference" for components
A managed (Workspace) component also reads, but does not
write, "LibIdentifierKind,LibraryIdentifier,DesignItemId,
VaultGUID,ItemGUID,RevisionGUID,SymbolReference,
SymbolVaultGUID,SymbolItemGUID,SymbolRevisionGUID". Read
off a part Altium placed, they are the values the managed
tools need.
PCB PRIMITIVES DO NOT. They are a separate, flat set,
and mixing the two is the single commonest mistake here:
a caller who used Designator.Text infers a dotted rule,
writes Net.Name on a track, and gets an error naming the
right spelling. Net is the one that catches people, and
it is plain "Net":
"Net,Layer,Width" for tracks
"Net,Layer,HoleSize,Size" for vias
"Designator,Comment,Pattern,Rotation,X,Y" for components
"Text,Height,StrokeWidth,IsDesignator" for texts
Full set: ObjectId, X, Y, Layer, Descriptor, Selected,
Net, X1, Y1, X2, Y2, Width, Radius, StartAngle,
EndAngle, XCenter, YCenter, HoleSize, Size, TopShape,
TopXSize, TopYSize, Rotation, Name, Text, Pattern,
Designator, Comment, SourceDesignator, Kind,
RemoveDead, RemoveNarrowNecks, RemoveIslandsByArea,
StandoffHeight, OverallHeight, BodyOpacity3D, InComponent, Component,
InPolygon, IsKeepout, Locked, Layer1, Layer2,
IsRedundant, Mode, Height, StrokeWidth, IsDesignator,
IsComment, UseTTFonts.
On a text, Height and StrokeWidth are writable in mils
(Altium's own names, Size and Width, answer the same).
On a via, Size and HoleSize are writable; a write that
would leave the hole as large as the pad is refused, so
give Size first to grow a via and HoleSize first to
shrink it. Lengths read back in decimal mils.
On a pad, Name and Designator both read and write its
designator; an empty one is refused.
On a 3D body, BodyOpacity3D reads and
writes 0 (clear) to 1 (solid), not a percentage.
IsDesignator and IsComment pick out component labels:
filter "IsDesignator=true" for every designator.
A board type walks EVERY primitive of that type, a
footprint's own tracks and a hatched polygon's tracks
with the routing, on the same copper layers. Filter
"InComponent=false|InPolygon=false" keeps to free copper;
Component is the owning footprint's designator.
An unrecognised PCB property is REFUSED and the reply
lists the valid ones. It used to come back empty, which
is indistinguishable from a property that is genuinely
blank, and that ambiguity has three times been read as
"the bridge cannot see this data".
A track on a mechanical layer really does have no net,
so filter to copper before concluding anything from an
empty Net: filter="Layer=TopLayer".
scope: Document scope:
"active_doc", current sheet only (default)
"project", all SCH sheets in focused project
"doc:C:\path\to\Sheet.SchDoc", specific sheet by path (no focus change)
"project:C:\path\to\Project.PrjPcb", specific project by path
"lib_component:NAME", a named symbol in the active SchLib
"lib_component:NAME@3", part 3 of a MULTI-PART symbol.
A SchLib iterator yields one part at a time, so
without the suffix only part 1 is visible and a pin
on part 3 reports matched:0. Query each part in
turn to cover the whole component. The suffix is
read from the RIGHT, so a LibRef containing '@'
still works.
Ask for the `OwnerPartId` property to see which
part a returned primitive belongs to (0 means
shared across every part).
filter: Pipe-separated property=value conditions (AND logic), e.g.:
"Text=VCC", match net labels with Text equal to VCC
"Designator.Text=R1", match component with designator R1
"" (empty), match all objects of the type
On a PCB type a length (X, Y, X1, Y1, X2, Y2, Width, Size,
HoleSize, ...) matches as a number in mils, to 0.00005
mil, with '.' or ',' as the decimal point:
"X2=3172.6356" and "X2=3172,63560" are the same filter.
limit: Maximum number of objects to return (0 = unlimited)Returns: Dictionary with "objects" array and "count"
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| scope | No | active_doc | |
| filter | No | ||
| properties | Yes | ||
| object_type | Yes |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||