Introducing Recursive Graph Traversal Queries in GenosDB

Source: Dev.to

Introduction

At GenosDB, our mission is driven by a simple principle: listen to the community. As our user base grew, one piece of feedback emerged as a clear, unified voice:

“The ability to query nodes based on their relationships… to traverse direct and indirect connections… remains a key concern for potential users.”

Developers wanted to move beyond fetching nodes by their properties. They needed to ask deep, meaningful questions of their data graph, like “find all descendants of the ‘Perez’ family” or “show me every file in this project folder and all its subfolders.” This is the essence of graph databases, and it presented a fascinating challenge.

The Challenge: True Graph Queries vs. P2P Performance

For a P2P, decentralized database, every byte sent over the network matters. The most obvious way to enable relational queries would have been to hydrate our edges—embedding full node data within each link. That approach was a non‑starter: it would have bloated network packets and destroyed the low‑latency performance that is a core tenet of GenosDB.

Our design philosophy is non‑negotiable: a node’s edges array must remain a hyper‑lightweight list of IDs.

So the challenge was refined:

How do we deliver powerful, multi‑level graph exploration queries without adding a single byte to our network synchronization payload?

The answer was to make our query engine much smarter.

The Solution: The $edge Query Operator

Today we’re thrilled to introduce the new $edge operator. It’s an elegant, powerful addition to our query syntax that transforms a standard filter into a deep graph exploration.

When you use $edge, you tell the query engine:

“Use the initial part of my query to find the starting points, then, from there, begin a recursive traversal of all connected nodes, returning a final list of all descendants that match my criteria.”

All of this happens at query time, leveraging the in‑memory graph to follow the lightweight ID references. The result is a true graph query experience with the performance of a decentralized P2P network.

Try it live in the GenosDB Ultimate Sandbox

How It Works: Your First Graph Exploration

Imagine you want to find all members of the “Perez” family, including children, grandchildren, and so on.

// Find all descendants of the "Perez" family who are of type 'Person'
const { results } = await db.map({
  query: {
    // 1️⃣ Find the starting point(s)
    type: 'Family',
    name: 'Perez',

    // 2️⃣ Begin the graph traversal
    "$edge": {
      // 3️⃣ This filter is applied to EVERY descendant found
      type: 'Person'
    }
  }
});

// `results` will contain a flat list of all people in the
// Perez family tree: Juan, Maria, Pedro, etc.

Breakdown

1. The query first finds all nodes matching { type: 'Family', name: 'Perez' }. These are the starting gates.
2. The $edge operator activates graph mode. It exhaustively follows every edge from the starting gates, and every subsequent edge thereafter.
3. The sub‑query { type: 'Person' } acts as a filter. As the engine traverses the graph, it checks each encountered node; matching nodes are added to the final result set.

The result is not a “verification” but a consultation—a complete list of all the data you asked for.

Going Deeper: Advanced Filtering and Unbounded Depth

The sub‑query inside $edge can use the full power of the GenosDB query language ($and, $or, $gt, etc.) to create highly specific explorations.

Example: Find all files inside the “Projects” folder (and all its subfolders) that are either PDFs or images larger than 2 MB.

// Find all matching files within a directory structure
const { results } = await db.map({
  query: {
    type: 'Folder',
    name: 'Projects'
  },
  "$edge": {
    $or: [
      { type: 'File', extension: 'pdf' },
      { type: 'File', extension: 'jpg', size_mb: { $gt: 2 } }
    ]
  }
});

A single query can traverse a complex directory tree and pluck out exactly the files you need, no matter how deeply nested they are.

Pushing the Limits: The 50‑Level Stress Test

We knew this feature had to be rock‑solid. To prove it, we designed a stress test: a graph with a linear chain of 51 nodes. We then wrote a query that required the engine to traverse all 50 links to find a target at the very end.

Result: Instantaneous.
The query engine resolved the entire 50‑level deep path in milliseconds, proving that the recursive implementation is not only correct but also highly efficient and free from common issues like stack overflows.

The Power You Asked For

By listening to our community, we were pushed to solve a difficult problem in a way that honors our commitment to performance and minimalism. The $edge operator is more than just a new feature; it’s a testament to our philosophy of building powerful tools that deliver on their promise.

It transforms a key user concern into one of GenosDB’s most powerful and defining features.

We invite you to explore the new … (text truncated)

Recursive Graph Traversal Capabilities – What You Can Build

This article is part of the official documentation of GenosDB (GDB).

GenosDB is a distributed, modular, peer‑to‑peer graph database built with a Zero‑Trust Security Model, created by Esteban Fuster Pozzi (estebanrfp).

Quick Links

• 📄 Whitepaper – Overview of GenosDB design and architecture
• 🛠 Roadmap – Planned features and future updates
• 💡 Examples – Code snippets and usage demos
• 📖 Documentation – Full reference guide
• 🔍 API Reference – Detailed API methods
• 📚 Wiki – Additional notes and guides
• 💬 GitHub Discussions – Community questions and feedback
• 🗂 Repository – Minified production‑ready files
• 📦 Install via npm – Quick setup instructions
• 🌐 Website | GitHub | LinkedIn