Query Builder

Query builder

Two fluent, chainable query APIs sit over the property graph: GraphQuery (synchronous, over the loaded working set) and PersistedGraphQuery (asynchronous, over the complete backing store without warming the hot cache).

// Loaded working set
graph.query()
  .whereNodeType('document')
  .similarTo([0.90, 0.30, 0.10], 0.5, 5)
  .toArray()

// Complete persisted store, without loading results into the hot cache
const recentPosts = await graph.queryPersisted()
  .whereNodeType('document')
  .orderBy('updatedAt', 'desc')
  .limit(20)
  .toArray()

GraphQuery — graph.query()

Filter methods (chainable):

• where(field, value) / whereAttribute(name, value) — strict equality.
• whereAttributeRange(name, { above?, below? }) — exclusive boundaries.
• whereNodeType(...types) — restrict node types.
• whereEdge(type, target?) — requires an outgoing edge.
• whereEdgeSource(source) — requires an incoming edge from that source.
• join(edgeType, direction?, predicate?) — filter by connected nodes.
• traverse(edgeType, depth, direction?) — breadth-first traversal, includes the seed nodes.
• similarTo(vector, threshold?, topK?) — rank vector-bearing nodes by cosine similarity. See Vector search & embeddings.
• whereActivated(above) — keep only nodes whose current (decay-corrected) activation exceeds above. See Adaptive memory.
• orderBy(field, direction?), orderByActivation(direction?), offset(n), limit(n) — shape results.

Filters run before traversal. Similarity ranking runs after orderBy, so it becomes the final ordering before offset and limit. Limits, offsets, traversal depths, and top-K values must be non-negative integers; timestamps must be finite and non-negative; vectors and numeric range boundaries must contain finite numbers; node IDs/types and edge endpoints/types must not be empty.

Terminal methods

• toArray(), first(), count(), ids() — matched nodes/IDs. count() respects similarity, traversal, offset, and limit.
• pluck(...fields) — project node data into records that also carry id and type.
• aggregate(field, op) — sum, avg, min, max, count.
• groupAggregate(field, op, groupByField) — aggregate by a data field.
• having(groups, predicate) — filter aggregate rows.
• groupByVector(groups, field, op, threshold?) — assign nodes to their nearest centroid (clustering).
• uniqueKeys(field) — distinct values across all currently loaded nodes.
• collect(edgeType, direction?, predicate?) — unique directly connected nodes.

graph.query().whereNodeType('book').aggregate('price', 'avg')

PersistedGraphQuery — graph.queryPersisted()

Chainable filters: where, whereAttribute, whereAttributeRange, whereNodeType, whereEdge, whereEdgeSource, join, traverse, orderBy, similarTo, whereActivated, orderByActivation, offset, limit. Asynchronous terminal methods: toArray(), first(), count(), ids(), collect(). Activation filters/ordering apply post-load (like similarity), so they disable adapter-side pagination.

Adapters may implement queryNodes(query)/countNodes(query) for optimized storage-level execution, plus getEdgesBySources/ getEdgesByTargets for indexed graph operations — when absent, Polypack falls back to the original node/edge methods. countNodes({}) returns the total persisted node count without materialising ids, and type-only queries use a secondary type index. For node-only queries, offset and limit are delegated to the adapter; BinaryStoreAdapter uses an in-memory snapshot for persisted queries. Queries with similarity or graph post-processing retain pagination in the query layer so filtering, traversal, and ranking happen before the page is selected.

Text queries

• queryText(text, threshold?, topK?) — Promise<GraphQuery> already configured for similarity search over the loaded set.
• queryPersistedText(text, threshold?, topK?) — the same over the complete persisted dataset.
• searchNodes(text, type, threshold?, topK?) — shorthand on PolyGraph itself. See Property graph.

See Vector search & embeddings for how text is turned into vectors.

---

Back to Home.