Query filter strings for model resources

Limiting Clauses for Query Operations

I am starting to work on expanding the model-system’s queryOperation() method to accept a limiting clause that subsets results based on their property values. Here is a proposed grammar for the query string (which coincides to some degree with the attribute resource’s [type='xxx'] grammar):

type-specifier "[" ("string"|"floating-point"|"integer") [ "{" property-name [ "=" property-value ] "}" ]


  • type-specifier is any currently-accepted model-entity type specifier string.
  • property-name is either a single-quoted name or a slash-quoted regular expression (i.e., a regular expression surrounded by forward slashes such as /(foo|bar)/).
  • property-value is
    • a single, single-quoted string value to match (when searching for string properties),
    • a single, slash-quoted regular expression to match (when searching for string properties by regular expression),
    • a single, unquoted integer or floating point value to match (when searching for properties of those types), or
    • a tuple (indicated with parentheses) of values as specified above to match, which implies the property must be vector-valued.

Note that single quotes are used because these filter strings will appear in XML and/or JSON serializations that use double-quotes to mark the start and end of the query string. The examples below include the double-quotes around the query as a reminder.

For regular expressions, the c++11 standard library is used to search for matches; the syntax must be accepted by the std::regex constructor and std::regex_search() must return true when passed property names or values in order for the corresponding entity to be included in filtered results.


Query string Results
model|3 Any model explicitly marked as 3-dimensional. (This example has no limiting clause is here to be clear that existing query strings will continue to be accepted.)
vertex[string] Vertices with any string properties at all (but not vertices without string properties).
any[integer{'counter'}] Any entity with an integer property named ‘counter’ (regardless of the value).
face[string{'pedigree'='zz'}] Faces with a string-property named pedigree whose value is “zz”
any[floating-point{/.*/=(0,0,0)}] An entity of any type with any floating-point property whose value is a 3-entry vector of zeros.
group[string{'alphabet'=('abc', 'def')}] Any group with a string property named “alphabet” whose value is a vector of 2 strings: one valued “abc” and the next valued “def”.

Invalid un-examples:

Query string Why This is Invalid
edge,face[integer{'pedigree'=23}] Multiple queries are not supported yet. Also, it is unclear whether the limiting clause applies to both types or just faces. For now, use multiple filters to handle combination queries with different limiting clauses. Note that if this example had used edge|face instead of edge,face, it would have been valid; the filter would have apply to edges or faces.
any[{'pedigree'}] You must currently specify the property type.
any[integer{'lattice'=(0,*,*)'}] There is no way to search for properties with partially-matched array-valued entries.
any[integer{'counter'=(*,*,*)'}] There is no way to search for properties whose value is a given length yet.

Comments and Questions

  • Searching by the array length of the property value is not included, but is possible. If it is important, let me know.
  • Ignoring the type of the property (string, floating-point, integer) is not currently allowed because it is inefficient (the properties are stored in separate maps for each type, so the search cost would be tripled). If it’s important, let me know.
  • Regular expressions (for strings and/or property names) are now included.
  • Inexact matches of floating-point values is not provided yet; they would be useful but the grammar will get more complicated to parse. We might use <xx,yy> to indicate acceptable ranges for any component of an array entry. It might also be nice to search for array entries with a magnitude near a certain value (i.e., vectors of a given Euclidean length).

As an update, I’ve edited the description above to reflect that the branch can now perform regular-expression matches.

Also, PEGTL is really cool. The CMB superbuild now builds v2.7.1 (the most recent release that only requires C++11 and not C++17).

This branch has been merged.