What are queries?
Queries are an important feature in Hypar, used for a number of different purposes across the platform.
Here are some examples of where you can use queries:
- Overrides use queries to find their
context— the set of elements the override applies to.
- Function Visibility Filters use queries to specify which elements are visible in the scene.
- You can utilize queries to populate a dropdown menu input with
Hypar’s queries utilize json-query, so you’re welcome to refer to their documentation for more details on syntax. This guide is intended to cover what you need to know to use queries in Hypar and provide you with some helpful tips.
How do queries work?
Most queries on Hypar look something like this:
[*discriminator=Elements.Wall].HeightThis query gets all of the
Wallelements in the model, and gets their
Heightproperty. The term
discriminatorrefers to a special element property which is used by various systems on Hypar to know what type an element is — to discriminate between one type and another.
The portion in
specifies the “filter” conditions. The
[* ... ]syntax retrieves all items that satisfy the criteria within. It’s possible to combine multiple criteria with the
|symbol (for “OR”) or
The portion outside of the
is utilized to retrieve properties. You can use
.to “drill” down into nested properties. Some Hypar features, like Visibility Filters and Override
contextonly support the “filter” component of a query —
For example, this query gets the
Floorelements in the model:
[*discriminator=Elements.Wall | discriminator=Elements.Floor].Area
And this query gets all SpaceBoundary elements with a
Nameof “Open Office”:
[*discriminator=Elements.SpaceBoundary & Name=Open Office]
Advanced query tips
In addition to this basic property retrieval, there are some special Hypar methods that let you do even more with your queries. Helper methods are functions that can follow some querying, and then the first argument to the helper method will be the result of query. If your query results in multiple values, then the helper method is run on each item in that array individually.The syntax for using a helper method is
Note, we always query against a specific model, and the model that is in use can vary depending on the context.
These queries can be used inside the filter portion of your query — between the
hasName- filter for items that have a name. For example,
ViewScopeelements that have a
Nameproperty that isn’t null or empty.
filterOnNestedPropertyValue- filters the list of objects based on a (potentially nested) property value. For example,
- is equal to
- — in other words, all the instances of the element with that ID.
transformOrigin- This will filter your query based on the XYZ position of its
Transformproperty. Useful for broad geometric filtering. For example,
[*discriminator=Elements.Mass&:transformOrigin(x, >, 5)]will retrieve all
Masselements with an
xposition that’s greater than 5.
These queries can be used to perform additional processing on the values retrieved by the query, and typically go outside the
joinToString- join a list of strings together with commas
[*discriminator=Elements.Envelope].Name:joinToStringwill return a single string value, joining together the names of all the envelopes in the model.
getElement- takes in an id, and will fetch that element. Useful for navigating to another Element via your query. For example,
- Get all the walls
- Look at each wall’s
- Find the Level element with that Id
- Retrieve the
Elevationof the level
getElementFromDependency- This functions the same as
getElement, but is able to search for elements in dependent models as well.