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 $hyparEnumQuery or $hyparAutocompleteQuery.

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].Height This query gets all of the Wall elements in the model, and gets their Height property. The term discriminator refers 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 & (for “AND”).

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 context only support the “filter” component of a query —

For example, this query gets the Area of any Wall OR Floor elements in the model:

[*discriminator=Elements.Wall | discriminator=Elements.Floor].Area

And this query gets all SpaceBoundary elements with a Name of “Open Office”:

[*discriminator=Elements.SpaceBoundary & Name=Open Office]

🚧 Caution! 🚧

Queries are sensitive to case and spacing, based on the JsonProperty of the object you are querying. For example, in order to query the Product Name shown in the code below, your query would be:[*discriminator=Elements.Product].Product Name

Because we are querying the serialized JSON of this object, we need “Product Name” with a space between the words as defined in the JsonProperty attribute.

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 :helperMethodName(more, arguments)

Note, we always query against a specific model, and the model that is in use can vary depending on the context.

Filtering

These queries can be used inside the filter portion of your query — between the [] brackets.

hasName - filter for items that have a name. For example, [*discriminator=Elements.ViewScope&:hasName] retrieves all ViewScope elements that have a Name property that isn’t null or empty.

filterOnNestedPropertyValue - filters the list of objects based on a (potentially nested) property value. For example, [*discriminator=Elements.ElementInstance&:filterOnNestedPropertyValue(BaseDefinition.Id,167a1c8f-3e43-47f6-a50e-9bb8d75b888e)] will return:

all ElementInstances
whose BaseDefinition's Id
is equal to 167a1c8f-3e43-47f6-a50e-9bb8d75b888e
— 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 Transform property. Useful for broad geometric filtering. For example, [*discriminator=Elements.Mass&:transformOrigin(x, >, 5)] will retrieve all Mass elements with an x position that’s greater than 5.

Value retrieval

These queries can be used to perform additional processing on the values retrieved by the query, and typically go outside the [] brackets.

joinToString - join a list of strings together with commas , For example, [*discriminator=Elements.Envelope].Name:joinToString will 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, [*discriminator=Elements.Wall].LevelId:getElement.Elevation will:

Get all the walls
Look at each wall’s LevelId property
Find the Level element with that Id
Retrieve the Elevation of the level

getElementFromDependency - This functions the same as getElement, but is able to search for elements in dependent models as well.

toString - convert an object to a string using standard JavaScript toString() behavior