Finding accurately with advanced search

Finding accurately with advanced search

When you are searching for nodes/metadata, you can use advanced search syntax and have better precision on what you really want.

Operator Definition Examples
name: Search nodes by name. Example: node:roof
Meaning: Nodes whose name contains “roof”.
attribute: Search nodes by metadata name or value. Example: attribute:material
Meaning: Nodes whose attributes contain “material” (as a key or a value).

Example: attribute:material=wood
Meaning: Nodes which have an attribute “metadata” whose value contains “wood”.

layer: Search nodes included in a layer. Example: layer:Ground
Meaning: Nodes that are included in a layer named “Ground”.
has:surface Search nodes that have a surface. Example: has:surface
Meaning: Nodes that have a surface (generally, nodes that have a geometry in the 3D scene).
has:attribute Search nodes that have metadata. Example: has:attribute
Meaning: Nodes that contain metadata.

You can use globbing (*) and quoting ("") to fine-tune your query:

  • * characters match any character sequence: basement_*_ext would find all nodes whose name contains “basement_” then anything then “_ext” (like “basement_room_a_ext” for instance).
  • "" characters match exactly the character sequence: "groundfloor_entrance" would match all nodes whose name is exactly “groundfloor_entrance” (unlike “groundfloor_entrance_door” for instance).

All operators can be combined with an implicit “and”. For instance, you could find all the walls with a wood material in a building with a query like: name:wall has:surface has:attribute attribute:material="wood*".

Functions and projections

Projection is an operator, to map (transform) a node into a value in the context of the search query. It is mainly used as an argument to functions.
It supports two syntaxes:
– Unary: | PROJECTABLE which projects the current node evaluated using PROJECTABLE. PROJECTABLE can be an attribute qualifier (attribute:NAME, or the shorter version @NAME).
– Binary: NODES | PROJECTABLE which projects each node of NODES using PROJECTABLE. NODES can result from a descendant/ancestor query: /* | @width or a select function: select(*) | @width

Several functions are handled by the server. They are applied to each node. If they return a boolean value, it is used to know wether the node is kept in the search result or not. If the function returns a value other than a boolean value, it can be used as an argument for function calls or comparison operators (>, <, >=, <=, =).

Function Definition Examples
count(NODES) Returns the number size of NODES, which is a list of nodes. Example: count(/*)
Meaning: Nodes that have childrens.
min(VALUES) Returns the minimum of VALUES, which is a list of comparable values. Example: min(select(*) | @size) = | @size
Meaning: Nodes whose attribute size is the minimum of all nodes.
max(VALUES) Returns the maximum of VALUES, which is a list of comparable values. Example: max(select(*) | @size) = | @size
Meaning: Nodes whose attribute size is the maximum of all nodes.
select(QUERY) Returns the nodes matching QUERY, which can be any valid search query. Example: select(*)
Meaning: All nodes in the scene.
in-range(VALUE, MIN, MAX, RANGE_INDEX, NUM_RANGES) Returns wether value is in the range numbered RANGE_INDEX, given that the range [MIN, MAX] is divided into NUM_RANGES ranges of the same size. RANGE_INDEX is expected to be in the range [0, NUM_RANGES[ Example: in-range(| @size, 1, 10, 0, 1)
Meaning: All nodes whose size is in the range [1, 10].