Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/estebanrfp/gdb/llms.txt

Use this file to discover all available pages before exploring further.

​
🌍 Geo-spatial Module for GenosDB

Geolocation Query Visualization This document explains the purpose of the Geo-spatial module in GenosDB, which provides the $near and $bbox operators. These operators are designed to simplify and accelerate queries involving geographic data, such as finding nodes near a specific location or within a defined area.

​
Purpose of Geo-spatial Operators

Geo-spatial operators allow you to filter nodes based on their geographic coordinates (latitude and longitude). This functionality is essential for applications that involve maps, location-based services, or any form of spatial data analysis.

​
Key Use Cases

  1. Find Nearby Nodes: Identify all data points within a certain radius of a given location (e.g., “find all cafes within 2 km”).
  2. Filter by Area: Retrieve nodes that fall within a rectangular bounding box (e.g., “show all landmarks within Manhattan”).
  3. Real-Time Location Queries: Dynamically query nodes based on a user’s changing location, with live updates.

​
Enabling the Module

The Geo-spatial module is not imported separately but is activated when you initialize your GenosDB instance. To use the $near and $bbox operators, enable the geo option. 
import { gdb } from "genosdb";

// Enable the Geo-spatial module during database initialization
const db = await gdb("my-geo-database", { geo: true });

console.log("Geo-spatial operators are now active.");

​
Flexible Coordinate Handling

The operators are designed to be flexible. They can automatically find coordinate data within a node’s value whether it is stored in a flat structure or nested inside another object (like location).
  • Flat Structure: await db.put({ name: "Point A", latitude: 40.7, longitude: -74.0 });
  • Nested Structure: await db.put({ name: "Point B", location: { latitude: 40.8, longitude: -73.9 } });
Both formats will be correctly processed by $near and $bbox queries.

​
Operator Details

​
1. $near

The $near operator finds nodes whose geographic coordinates are within a specified radius (in kilometers) of a central point.

​
Syntax

The field name used in the query (e.g., location below) is a placeholder; the operator searches the entire node value for coordinate fields. 
// Find nodes within a 50km radius
const { results } = await db.map({
  query: {
    location: {
      $near: { latitude: 40.7128, longitude: -74.006, radius: 50 }
    }
  }
});

console.log("Nearby nodes:", results);

​
Example: Find Landmarks Near a User

First, let’s add some geo-tagged landmarks in New York City. 
await db.put({ name: "Times Square", type: "Landmark", location: { latitude: 40.7580, longitude: -73.9855 } });
await db.put({ name: "Central Park", type: "Park", location: { latitude: 40.7850, longitude: -73.9682 } });
await db.put({ name: "Statue of Liberty", type: "Landmark", location: { latitude: 40.6892, longitude: -74.0445 } });
Now, find all landmarks within a 5 km radius of Times Square. 
const userLocation = { latitude: 40.7580, longitude: -73.9855 };

const { results } = await db.map({
  query: {
    location: {
      $near: { ...userLocation, radius: 5 } // Radius in kilometers
    }
  }
});

// This will return Times Square and Central Park, but not the Statue of Liberty.
console.log("Nearby places:", results);

​
2. $bbox

The $bbox operator finds nodes whose geographic coordinates fall within a rectangular “bounding box” defined by minimum and maximum latitude and longitude values.

​
Syntax

// Find nodes within a specific rectangular area
const { results } = await db.map({
  query: {
    location: {
      $bbox: {
        minLat: 40.70, maxLat: 40.88,
        minLng: -74.02, maxLng: -73.93
      }
    }
  }
});

console.log("Nodes within the area:", results);

​
Example: Filter Nodes within Manhattan

Using the same data as before, let’s find all nodes within the approximate boundaries of Manhattan. 
const manhattanBounds = {
  minLat: 40.70, maxLat: 40.88,
  minLng: -74.02, maxLng: -73.93
};

const { results } = await db.map({
  query: {
    location: {
      $bbox: manhattanBounds
    }
  }
});

// This will return Times Square and Central Park.
console.log("Nodes in Manhattan:", results);

​
Advanced Usage

​
Combining with Standard Filters

You can combine geo-spatial operators with other standard query filters to create highly specific searches.

​
Example: Find Parks in a Specific Area

Find nodes that are within the Manhattan bounding box AND have a type of “Park”. 
const manhattanBounds = {
  minLat: 40.70, maxLat: 40.88,
  minLng: -74.02, maxLng: -73.93
};

const { results } = await db.map({
  query: {
    location: { $bbox: manhattanBounds }, // Geo-spatial filter
    type: "Park"                         // Standard value filter
  }
});

// This will only return the "Central Park" node.
console.log("Parks in Manhattan:", results);

​
Real-Time Updates with Callbacks

Leverage GenosDB’s real-time capabilities to monitor geo-queries live. The callback will be triggered for initial results and any subsequent changes (nodes entering or leaving the query area).

​
Example: Monitor Nearby Nodes in Real-Time

const userLocation = { latitude: 40.7580, longitude: -73.9855 };

const { unsubscribe } = await db.map(({ id, value, action }) => {
  // Destructure the event object to get node details and the event type
  if (action === "initial" || action === "added") {
    console.log(`[NODE NEARBY] ${value.name} (${id}) has appeared.`);
  }
  if (action === "removed") {
    // This fires when a node no longer matches the query
    console.log(`[NODE NO LONGER NEARBY] A node with ID ${id} is now out of range.`);
  }
}, {
  query: {
    location: {
      $near: { ...userLocation, radius: 5 } // 5 km radius
    }
  }
});

// To stop listening for updates later:
// unsubscribe();

​
Live Example

To see the geo-spatial operators in action, visit the interactive example: Geolocation with GenosDB

​
Conclusion

The Geo-spatial module provides powerful and easy-to-use tools for querying spatial data in GenosDB. It enables you to:
  • Find nodes near a specific point with $near.
  • Filter nodes within a defined rectangular area with $bbox.
  • Combine geo-queries with other filters for precise results.
  • Build dynamic, location-aware applications with real-time updates.
These operators are ideal for mapping services, logistics platforms, social networks, and location-based games.

Build docs developers (and LLMs) love

Get started for freeTalk to us