From d39b1c56f8298b26c563b88eb9aeb6509551e90f Mon Sep 17 00:00:00 2001 From: Ryan Schultz Date: Sat, 11 Jul 2026 16:44:22 -0500 Subject: [PATCH] Docs: clarify immediate vs. any-depth spatial selectors The location and parent filters both match at any depth in the spatial hierarchy, which surprises users who want only the elements immediately under a given container. Document that the parent query key resolves the direct parent only (e.g. query:"parent.Name"="My Site"), add a matching filter example, and note the immediacy on the parent value key. Co-Authored-By: Claude Opus 4.8 (cherry picked from commit 0b7e25a3ef2bfc66a4f2715a07c3f67fa020888e) --- .../docs/ifcopenshell-python/selector_syntax.rst | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-) diff --git a/src/ifcopenshell-python/docs/ifcopenshell-python/selector_syntax.rst b/src/ifcopenshell-python/docs/ifcopenshell-python/selector_syntax.rst index 5ae16c5ec0..f8098c83af 100644 --- a/src/ifcopenshell-python/docs/ifcopenshell-python/selector_syntax.rst +++ b/src/ifcopenshell-python/docs/ifcopenshell-python/selector_syntax.rst @@ -72,6 +72,8 @@ Filtering is typically used to select any IFC element or type. "``IfcPump, location=""Level 3""``", "Locations bubble up the hierarchy. So if a pump is in a space and that space is on Level 3, then you can say ""all pumps on level 3"" which will include that pump in the space." + "``IfcElement, query:""parent.Name""=""My Site""``", "Only elements *immediately* under ""My Site"" in the spatial hierarchy. Unlike the ``location`` and ``parent`` filters, which both match at any depth, the ``parent`` query key resolves the direct parent only, so nested storeys (and their contents) are excluded." + The filter elements syntax works by specifying one or more groups of filters separated by a ``+`` character. Each filter group will return a set of filtered elements, and these are unioned together. @@ -111,6 +113,15 @@ will search through all IfcTypeProducts and IfcProducts in the IFC project. "Parent", "Filter", "``parent{{=}}{{value}}``", "``parent=Foo`` specifies the criteria that elements must be a direct or indirect child in the spatial hierarchy to an element with a ``Name`` attribute with a value of ``Foo``." "Query", "Filter", "``query:{{keys}}{{=}}{{value}}``", "``query:types.count=0`` specifies the criteria that elements must have zero type occurrences. The query keys corresponds to the syntax used in the `Getting element values`_ section" +.. note:: + + The ``location`` and ``parent`` filters both match at **any depth** in the + spatial hierarchy. To match only elements *immediately* contained in (or + aggregated under) a spatial element, use the ``parent`` query key, which + resolves the direct parent only. For example, + ``query:"parent.Name"="My Site"`` selects elements directly under ``My + Site`` but excludes anything nested inside its sub-storeys or spaces. + When you specify a filter with a ``{{=}}`` check, you can choose from one of the following comparison checks: @@ -191,7 +202,7 @@ Valid keys are: "``storey``", "Gets the first IfcBuildingStorey spatial element that an element is contained in." "``building``", "Gets the first IfcBuilding spatial element that an element is contained in." "``site``", "Gets the first IfcSite spatial element that an element is contained in." - "``parent``", "Gets the parent element in the spatial hierarchy." + "``parent``", "Gets the **immediate** parent element in the spatial hierarchy (the direct spatial container, or the direct aggregate/nest/fill/void parent). Combine with ``.Name`` in a query filter to match only immediate children, e.g. ``query:""parent.Name""=""My Site""``." "``classification``", "Gets the element's classification reference(s)" "``group``", "Gets the element's group(s)" "``system``", "Gets the element's system(s). This is a subset of group(s)."