Skip to content

Building and filtering

Build ordered sets and filter with queries or predicates.

#Set operations and filtering

Collections can be unioned, intersected, subtracted or compared. These operations return new collections and deduplicate elements by their identity; they do not mutate the graph. filter() accepts a query object or a predicate function. Query objects operate on state and data columns; predicates run once per element and can express application logic not included in the query form. Unknown query keys throw. See selectors for the supported query vocabulary.

#eles.union(other)

// The union of the two collections, deduped
eles.union<OtherData = Data>(other: Collection<NodeData, EdgeData, OtherData>): Collection<NodeData, EdgeData, Data | OtherData>

The union of the two collections, deduped.

Parameters
NameDescription
other: Collection<NodeData, EdgeData, OtherData>

the collection to add

Returns Collection<NodeData, EdgeData, Data | OtherData>

a new collection holding both sets

Example

const other = cy.getElementById('b');
console.log(cy.getElementById('a').union(other).map(ele => ele.id())); // ["a","b"]

Example graph and handle setup

Also spelled eles.u, eles.or, eles.add, eles.merge.

#eles.difference(other)

// This collection's elements that are not in other
eles.difference(other: Collection): Collection<NodeData, EdgeData, Data>

This collection's elements that are not in other.

Parameters
NameDescription
other: Collection

the collection to subtract

Returns Collection<NodeData, EdgeData, Data>

a new collection

Example

const other = cy.getElementById('b');
console.log(cy.getElementById('a').difference(other).map(ele => ele.id())); // ["a"]

Example graph and handle setup

Also spelled eles.not, eles.subtract, eles.unmerge, eles.relativeComplement.

#eles.intersection(other)

// The elements present in both collections
eles.intersection(other: Collection): Collection<NodeData, EdgeData, Data>

The elements present in both collections.

Parameters
NameDescription
other: Collection

the collection to intersect with

Returns Collection<NodeData, EdgeData, Data>

a new collection

Example

const other = cy.getElementById('b');
console.log(cy.getElementById('a').intersection(other).map(ele => ele.id())); // []

Example graph and handle setup

Also spelled eles.intersect, eles.and.

#eles.symmetricDifference(other)

// The elements in exactly one of the two collections
eles.symmetricDifference<OtherData = Data>(other: Collection<NodeData, EdgeData, OtherData>): Collection<NodeData, EdgeData, Data | OtherData>

The elements in exactly one of the two collections.

Parameters
NameDescription
other: Collection<NodeData, EdgeData, OtherData>

the other collection

Returns Collection<NodeData, EdgeData, Data | OtherData>

a new collection

Example

const other = cy.getElementById('b');
console.log(cy.getElementById('a').symmetricDifference(other).map(ele => ele.id())); // ["a","b"]

Example graph and handle setup

Also spelled eles.symdiff, eles.xor.

#eles.filter(criterion, thisArg?)

// The subset matching the criterion
eles.filter(criterion: FilterLike<NodeData, EdgeData, Data, NodeData | EdgeData>, thisArg?: unknown): Collection<NodeData, EdgeData, Data>

The subset matching the criterion.

A structured query object is answered directly off the flags column — no per-element handles and no closures — while a predicate function is called per element. Pass either of these two forms; selector strings are not accepted.

Parameters
NameDescription
criterion: FilterLike<NodeData, EdgeData, Data, NodeData | EdgeData>

a query object ({ selected: true }, { data: { weight: { gt: 0.5 } } }, …) or an ( ele, i, eles) => boolean predicate

thisArg: unknown?

optional receiver, for the predicate form

Fields of criterion
NameDescription
group: GroupName?

restrict to one group

selected: boolean?

require the element (not) to be selected

selectable: boolean?

whether the element may be selected by the user

locked: boolean?

whether the element is locked in place

grabbed: boolean?

whether the user is dragging the element

grabbable: boolean?

whether the element may be dragged

active: boolean?

whether the element is under an active press

hovered: boolean?

whether the pointer is over the element

emphasized: boolean?

whether the element is in the current emphasis (* cy.emphasize())

parent: boolean?

structural (nodes only): has at least one child

childless: boolean?

structural (nodes only): has no children — exactly { parent: false }

child: boolean?

structural (nodes only): has a parent

orphan: boolean?

structural (nodes only): has no parent — exactly { child: false }

collapsed: boolean?

whether this compound parent is in collapsed miniature state (nodes only)

data: QueryData<Data>?

data-sidecar conditions per key; a bare value means equality. Typed, the keys are the queried elements' fields.

Returns Collection<NodeData, EdgeData, Data>

a new collection of the matching elements

Example

cy.getElementById('a').select();
console.log(cy.nodes().filter({ selected: true }).map(node => node.id())); // ['a']

Example graph and handle setup

Throws

if a query object carries an unknown key — a typo must not silently match everything

#eles.nodes(criterion?)

// The nodes in this collection, optionally filtered
eles.nodes(criterion?: FilterLike<NodeData, EdgeData, NodeData, NodeData | EdgeData>): Collection<NodeData, EdgeData, NodeData>

The nodes in this collection, optionally filtered.

Parameters
NameDescription
criterion: FilterLike<NodeData, EdgeData, NodeData, NodeData | EdgeData>?

a query object or predicate; omit for all nodes

Fields of criterion
NameDescription
group: GroupName?

restrict to one group

selected: boolean?

require the element (not) to be selected

selectable: boolean?

whether the element may be selected by the user

locked: boolean?

whether the element is locked in place

grabbed: boolean?

whether the user is dragging the element

grabbable: boolean?

whether the element may be dragged

active: boolean?

whether the element is under an active press

hovered: boolean?

whether the pointer is over the element

emphasized: boolean?

whether the element is in the current emphasis (* cy.emphasize())

parent: boolean?

structural (nodes only): has at least one child

childless: boolean?

structural (nodes only): has no children — exactly { parent: false }

child: boolean?

structural (nodes only): has a parent

orphan: boolean?

structural (nodes only): has no parent — exactly { child: false }

collapsed: boolean?

whether this compound parent is in collapsed miniature state (nodes only)

data: QueryData<Data>?

data-sidecar conditions per key; a bare value means equality. Typed, the keys are the queried elements' fields.

Returns Collection<NodeData, EdgeData, NodeData>

a new collection of nodes

Example

console.log(eles.nodes().map(ele => ele.id())); // ["a","b","c"]

Example graph and handle setup

#eles.edges(criterion?)

// The edges in this collection, optionally filtered
eles.edges(criterion?: FilterLike<NodeData, EdgeData, EdgeData, NodeData | EdgeData>): Collection<NodeData, EdgeData, EdgeData>

The edges in this collection, optionally filtered.

Parameters
NameDescription
criterion: FilterLike<NodeData, EdgeData, EdgeData, NodeData | EdgeData>?

a query object or predicate; omit for all edges

Fields of criterion
NameDescription
group: GroupName?

restrict to one group

selected: boolean?

require the element (not) to be selected

selectable: boolean?

whether the element may be selected by the user

locked: boolean?

whether the element is locked in place

grabbed: boolean?

whether the user is dragging the element

grabbable: boolean?

whether the element may be dragged

active: boolean?

whether the element is under an active press

hovered: boolean?

whether the pointer is over the element

emphasized: boolean?

whether the element is in the current emphasis (* cy.emphasize())

parent: boolean?

structural (nodes only): has at least one child

childless: boolean?

structural (nodes only): has no children — exactly { parent: false }

child: boolean?

structural (nodes only): has a parent

orphan: boolean?

structural (nodes only): has no parent — exactly { child: false }

collapsed: boolean?

whether this compound parent is in collapsed miniature state (nodes only)

data: QueryData<Data>?

data-sidecar conditions per key; a bare value means equality. Typed, the keys are the queried elements' fields.

Returns Collection<NodeData, EdgeData, EdgeData>

a new collection of edges

Example

console.log(eles.edges().map(ele => ele.id())); // ["ab","bc"]

Example graph and handle setup

#eles.getElementById(id)

// Find a member by id
eles.getElementById(id: string): Collection<NodeData, EdgeData, Data>

Find a member by id. This is a linear scan of the collection; use cy.$id( id) for the O(1) whole-graph index.

Parameters
NameDescription
id: string

the element id

Returns Collection<NodeData, EdgeData, Data>

a collection of one element, or an empty collection

Example

console.log(eles.getElementById('a').id()); // 'a'

Example graph and handle setup

#eles.absoluteComplement()

// All elements of the graph not in this collection
eles.absoluteComplement(): Collection<NodeData, EdgeData>

All elements of the graph not in this collection.

Returns Collection<NodeData, EdgeData>

the complement against the whole graph, not against any enclosing collection — which is what the absolute in the name is distinguishing

Example

console.log(eles.absoluteComplement().map(ele => ele.id())); // []

Example graph and handle setup

Also spelled eles.complement, eles.abscomp.

#eles.diff(other)

// Three-way set difference against another collection
eles.diff<OtherData = Data>(other: Collection<NodeData, EdgeData, OtherData>): { left: Collection<NodeData, EdgeData, Data>; right: Collection<NodeData, EdgeData, OtherData>; both: Collection<NodeData, EdgeData, Data>; }

Three-way set difference against another collection.

Parameters
NameDescription
other: Collection<NodeData, EdgeData, OtherData>

the collection to compare with

Returns { left: Collection<NodeData, EdgeData, Data>; right: Collection<NodeData, EdgeData, OtherData>; both: Collection<NodeData, EdgeData, Data>; }

{ left: only in this, right: only in other, both: in both }

Example

const result = cy.getElementById('a').diff(cy.getElementById('b'));
console.log(result.both.length); // 0

Example graph and handle setup

All guides · Alphabetical API index · Read continuously