Ontology metadata search

In the examples below, suppose you have a field called Ontology Field linked to the Polygon ontology shown below:

arrow indicates A is a subclass of B

Using the being operator

In the GraphQL Search API, there is a special operator (being) for fields of type ONTOLOGY. Please note that ONTOLOGY metadata values are actually class IDs, not labels, so a search query based on ordinary string operators (like eq or regex) won't work. Instead, you can input a class label into the being operator, and Model-Prime will automatically search for instances of that class, and (optionally) its subclasses.

Here is an example of a GraphQL search that will match instances of the class Polygon but not any of its subclasses:

{
  search(
    filter: {
        field: {
            alias: "Ontology Field"
            being: {
                class: "Polygon"
            }
        }
    }
  ) {
    count
    items {
      robolog_id
      fields {
        alias
        value
      }
    }
  }
}

Finding all instances within an ontology

If you want to query for all instances of a particular field, you can simply use the field operator with no search predicate. This works for any field, whether it is an ontology field or not.

{
  search(
    filter: {
        field: {
            alias: "Ontology Field"
        }
    }
  ) {
    count
    items {
      robolog_id
      fields {
        alias
        value
      }
    }
  }
}

Subclass or superclass search

Suppose that you only want to find instances of Quadrilateral, including all of its subclasses. This can be accomplished using subclass_of as shown (the rest of the query remains the same):

being: {
    subclass_of: "Quadrilateral"
}

By default, subclass_of finds the class itself and its direct subclasses, but also transitive subclasses at any depth. In the example ontology, this operator would match instances of the classes Quadrilateral, Parallelogram, Kite, Rectangle, Rhombus, and Square.

If you wish to match only the subclasses up to a particular depth, you can specify this using the depth field.

being: {
    subclass_of: "Quadrilateral"
    depth: 1
}

This operator would match instances of the classes Quadrilateral, Parallelogram, and Kite. Note that depth: 0 would match only Quadrilateral, and depth: -1 specifies unlimited depth, which is the default.

superclass_of is also available:

being: {
    superclass_of: "Parallelogram"
}

This would match instances of the classes Parallelogram, Quadrilateral, and Polygon.

Querying the ontology itself

The above examples use Model-Prime's GraphQL Search to find instances of ontology classes, as field-values in your robolog metadata. If you just want to inspect the ontology graph itself, this can be done using the Ontology Query API. This endpoint performs a breadth-first search of the ontology, with similar parameters to the metadata search described above. See the Swagger documentation for details.

One important difference is that the ontology can be queried at any particular version in its history, by specifying a semantic version number. To query the current draft version, use the keyword draft. The default is the latest published version (or you can use the keyword latest).