Skip to content

Queries

Use query objects or predicates to select elements.

#Query objects and predicates

There is no selector-string grammar. Pass a structured query object or a predicate function to cy.elements(), cy.nodes(), cy.edges(), cy.filter() or eles.filter(). A query is validated and unknown keys throw; a predicate is called for each element and can contain arbitrary application logic.

const selectedHighScores = cy.nodes({
selected: true,
data: { score: { gte: 0.8 } },
});
const readyForLayout = cy.nodes(node =>
node.data('status') === 'ready' && !node.locked(),
);

#State, structure and data tests

Every supplied query term must hold. The group term can constrain a query to 'nodes' or 'edges'; the node- and edge-specific collection methods also restrict the search directly. State fields include selected, selectable, locked, grabbed, grabbable, active, hovered and emphasized.

Query term Meaning when true
group: 'nodes' or group: 'edges' Restrict the result to a group.
selected, selectable Selected now, or allowed to become selected.
locked, grabbed, grabbable Locked in place, being dragged, or allowed to be dragged.
active, hovered, emphasized Active pointer state, hover state, or emphasis membership.
parent, childless A node with children, or a node without children.
child, orphan A node with a parent, or a node without a parent.
collapsed A collapsed compound node.

Use false to request the opposite state, for example { selected: false }. Structural node flags include parent, childless, child, orphan and collapsed. These share state names with style conditionals so that the elements an application can style can also be queried.

Data values use a bare value for strict equality, or a condition object with exactly one operator: eq, ne, lt, lte, gt, gte or in. Missing data fails all comparisons, including ne. Numeric operators require a number. in requires a non-empty array. For a typed core, TypeScript restricts data keys to the element data shape.

Data condition Matches
{ kind: 'protein' } or { kind: { eq: 'protein' } } An existing value strictly equal to 'protein'.
{ kind: { ne: 'protein' } } An existing value other than 'protein'.
{ score: { gt: 2 } }, { score: { gte: 2 } } A numeric value greater than 2, or greater than or equal to 2.
{ score: { lt: 2 } }, { score: { lte: 2 } } A numeric value less than 2, or less than or equal to 2.
{ kind: { in: ['protein', 'gene'] } } An existing value equal to one of the listed values.

All data fields and state terms are combined with and. For or, a missing-field check or a calculation, use a predicate:

const interesting = cy.nodes(node =>
node.selected() || (node.data('score') ?? 0) > 0.8,
);
// Filter only the neighbours of a particular node.
const neighbours = cy.getElementById('a').neighborhood().nodes();
const highScores = neighbours.filter({ data: { score: { gte: 0.8 } } });

A query result is a snapshot of membership. Query again after data or state changes to obtain a new result; a previously returned collection does not automatically add newly matching elements.

const heavyEdges = cy.edges({
data: { weight: { gt: 2 }, kind: { in: ['activation', 'binding'] } },
});
const notSelectedParents = cy.nodes({
parent: true,
selected: false,
});
Moved sections

Migration guide

All guides · Alphabetical API index · Read continuously