TypeQL Query Examples

Common TypeQL query patterns for the FFO ontology — listing clusters, finding non-FIPS nodes, traversing relationships, querying Ceph, and more.

TypeQL Query Examples

This page provides working TypeQL queries for common operations against the FFO ontology. Each example shows the query, explains what it does, and notes any output considerations.

All queries assume the database name is ffo and use TypeDB 3.x syntax.

Listing Entities

List All Clusters

match $c isa cluster;
fetch { $c.* };

Returns all clusters with all their attributes (name, environment, classification, fips_enabled, etc.). Each result is a document containing every attribute the cluster has.

List Clusters With Limit and Offset

match $c isa cluster;
limit 10; offset 0;
fetch { $c.* };

Paginated results. Remember: limit and offset must come between match and fetch.

List All Deployments

match $d isa deployment;
fetch { $d.* };

Returns all deployments with attributes like name, namespace, replicas, and status.

List All Findings

match $f isa finding;
fetch { $f.* };

Returns all security findings. Results include severity, status, description, and any other attributes.

Filtering

Find Production Clusters

match $c isa cluster, has environment "prod";
fetch { $c.* };

Filters clusters to only those with environment set to “prod”. The has clause chains directly after isa with a comma.

Find Non-FIPS Clusters

match $c isa cluster, has fips_enabled false;
fetch { $c.* };

Returns clusters where FIPS is not enabled. Useful for compliance audits.

Find IL4 Production Clusters

match $c isa cluster,
    has environment "prod",
    has classification "IL4";
fetch { $c.* };

Multiple filters chain with commas. This finds clusters that are both production AND IL4 classified.

Find Critical Findings

match $f isa finding, has severity "critical";
fetch { $f.* };

Returns only findings with critical severity. Combine with other filters:

match $f isa finding,
    has severity "critical",
    has status "open";
fetch { $f.* };

Find High and Critical Findings (Two Queries)

TypeQL does not have an OR operator for attribute values in a single match clause. Run two queries or use a broader match:

match $f isa finding, has severity "critical";
fetch { $f.* };

match $f isa finding, has severity "high";
fetch { $f.* };

Relationships

Get Nodes for a Cluster

match
    $c isa cluster, has name "geo-prod-01";
    ($c, $n) isa cluster_node;
    $n isa node;
fetch { $n.* };

Traverses the cluster_node relation from a named cluster to its nodes. Returns node attributes.

Get Deployments for a Cluster

match
    $c isa cluster, has name "geo-prod-01";
    ($c, $d) isa cluster_deployment;
    $d isa deployment;
fetch { $d.* };

Same pattern: match the cluster, follow the relation, fetch the target entity.

Get Findings for a Cluster

match
    $c isa cluster, has name "geo-prod-01";
    ($c, $f) isa cluster_finding;
    $f isa finding;
fetch { $f.* };

Returns all findings associated with a specific cluster.

Get Services for a Deployment

match
    $d isa deployment, has name "compass-api";
    ($d, $s) isa deployment_service;
    $s isa service;
fetch { $s.* };

Get Image Vulnerabilities

match
    $i isa image, has name "compass-api";
    ($i, $v) isa image_vulnerability;
fetch { $v.* };

Returns vulnerabilities associated with a container image.

Get Controls for a Finding

match
    $f isa finding, has name "CVE-2024-1234";
    ($f, $ctrl) isa finding_control;
    $ctrl isa control;
fetch { $ctrl.* };

Maps a security finding to the compliance controls it violates.

Get Controls in a Framework

match
    $fw isa framework, has name "NIST-800-53";
    ($fw, $ctrl) isa framework_control;
    $ctrl isa control;
fetch { $ctrl.* };

Lists all controls defined in a compliance framework.

Multi-Hop Traversals

Cluster to Controls (via Findings)

match
    $c isa cluster, has name "geo-prod-01";
    ($c, $f) isa cluster_finding;
    $f isa finding;
    ($f, $ctrl) isa finding_control;
    $ctrl isa control;
fetch { "finding": $f.*, "control": $ctrl.* };

Two-hop traversal: cluster -> finding -> control. Returns both the finding and its mapped control.

Principal Roles via Group Membership

match
    $p isa principal, has name "jsmith";
    ($g, $p) isa group_principal;
    $g isa group;
    ($g, $r) isa group_role;
    $r isa iam_role;
fetch { "group": $g.*, "role": $r.* };

Traverses: principal -> group -> role. Shows which roles a user inherits through group membership.

Ceph Queries

Important: Ceph entities use entity_name as their primary identifier, not name. This is a deliberate schema convention. Using name on Ceph entities will return empty results.

List Ceph Clusters

match $cc isa ceph_cluster;
fetch { $cc.* };

Returns Ceph cluster attributes including entity_name, health_status, and fsid.

Get Ceph Health

match $cc isa ceph_cluster;
fetch { "cluster": $cc.entity_name, "health": $cc.health_status };

Named fetch to get just the cluster name and health status.

List Ceph Pools

match $p isa ceph_pool;
fetch { $p.* };

Returns all Ceph pools. Key attributes include entity_name, size, pg_count, and type.

List OSDs

match $o isa osd;
fetch { $o.* };

Returns all Ceph OSDs with entity_name, status, host, and device_class.

List Ceph Monitors

match $m isa ceph_mon;
fetch { $m.* };

Returns all Ceph monitors with entity_name, status, and host.

Filter OSDs by Host

match $o isa osd, has host "ceph-node-01";
fetch { $o.* };

Returns OSDs on a specific host.

Counting

Count Clusters

match $c isa cluster;
reduce $count = count;

Returns a single row with the count. Note: reduce queries return concept_rows, not concept_documents.

Count Critical Findings

match $f isa finding, has severity "critical";
reduce $count = count;

Count Nodes in a Cluster

match
    $c isa cluster, has name "geo-prod-01";
    ($c, $n) isa cluster_node;
reduce $count = count;

Named Fetch (Projections)

Instead of fetching all attributes with $x.*, you can select specific attributes:

Cluster Name and Environment Only

match $c isa cluster;
fetch { "name": $c.name, "env": $c.environment };

Returns documents with only the specified fields.

Finding Summary

match $f isa finding, has status "open";
fetch {
    "name": $f.name,
    "severity": $f.severity,
    "status": $f.status
};

Schema Introspection

These queries run in SCHEMA transactions, not READ transactions.

List All Entity Types

match entity $x;

Returns all entity types defined in the FFO schema.

List All Relation Types

match relation $x;

Returns all relation types defined in the FFO schema.

Query Patterns Summary

Pattern	Template
List all of type	`match $x isa TYPE; fetch { $x.* };`
Filter by attribute	`match $x isa TYPE, has ATTR VALUE; fetch { $x.* };`
Follow relation	`match $a isa TYPE_A, has name "X"; ($a, $b) isa REL; fetch { $b.* };`
Multi-hop	Chain relation patterns in the match clause
Count	`match ...; reduce $count = count;`
Paginate	`match ...; limit N; offset M; fetch { ... };`
Named fetch	`fetch { "label": $x.attr };`
Schema types	`match entity $x;` or `match relation $x;` (SCHEMA tx)

Common Mistakes

Using name for Ceph entities. Ceph types use entity_name. A query like match $c isa ceph_cluster, has name "X" will return nothing.
Putting limit after fetch. limit and offset go between match and fetch.
Repeating the variable in has clauses. Write $e isa cluster, has name "X", has env "prod" not $e isa cluster, $e has name "X".
Forgetting .resolve() in Python. tx.query(...) returns a Promise. Call .resolve() to get results.
Using 2.x fetch syntax. Write fetch { $x.* } not fetch $x: *.
Running schema queries in READ transactions. match entity $x; requires TransactionType.SCHEMA.