Live Queries

TopGun provides a powerful reactive query system that allows you to subscribe to changes in your data. Unlike traditional databases where you have to poll for updates, TopGun pushes updates to your client in real-time.

Basic Usage

To create a live query, use the client.query() method. This returns a QueryHandle that you can subscribe to.

const query = client.query('todos', {
  where: { completed: false },
  sort: { createdAt: 'desc' }
});

const unsubscribe = query.subscribe((results) => {
  console.log('Active todos:', results);
});

// Later, when you're done:
unsubscribe();

Query Filters

The QueryFilter object supports several options:

• where: Simple equality matching
• predicate: Complex conditions using logic operators
• sort: Sort order
• limit: Max number of results (coming soon)

Complex Predicates

For more complex filtering, use the predicate field:

import { Predicates } from '@topgunbuild/client';

const query = client.query('products', {
  predicate: Predicates.and(
    Predicates.greaterThan('price', 100),
    Predicates.equal('category', 'electronics')
  )
});

Available Predicate Methods

Change Tracking

TopGun tracks not just the current state, but what changed. This enables:

• Efficient UI updates (only re-render changed items)
• Add/remove animations (framer-motion, react-spring)
• Notifications (“New item added”)
• Optimistic UI rollback on specific keys

const query = client.query('todos');

// Subscribe to changes
const unsubscribe = query.onChanges((changes) => {
  for (const change of changes) {
    console.log(`${change.type}: ${change.key}`, change.value);
    // change.type: 'add' | 'update' | 'remove'
    // change.previousValue: available for update/remove
  }
});

// Get pending changes without subscribing
const pending = query.getPendingChanges();

// Consume and clear changes
const consumed = query.consumeChanges();

React Integration

If you are using React, we recommend using the useQuery hook which handles subscription management automatically.

Distributed Live Queries (Cluster Mode)

In clustered environments, live queries automatically work across all nodes. When you subscribe to a query, you receive real-time updates for matching documents regardless of which node owns the data.

How It Works

// Live queries work seamlessly in clustered environments
// The client connects to any node - queries see data from ALL nodes

const client = new TopGunClient({
  serverUrl: 'ws://node1:8080'  // Connect to any cluster node
});

// This subscription receives updates from all cluster nodes
const query = client.query('orders', {
  predicate: Predicates.greaterThan('total', 100)
});

// Updates are pushed automatically when:
// - New matching documents are added on ANY node
// - Existing documents are modified to match/unmatch on ANY node
// - Documents are removed from ANY node
query.subscribe((results) => {
  console.log('All matching orders across cluster:', results.length);
});

Architecture

When a client subscribes to a live query in a cluster:

1. Registration Phase: The connected node (coordinator) broadcasts the subscription to all cluster nodes
2. Initial Results: Each node evaluates the query against its local data and sends results
3. Result Merging: The coordinator deduplicates and merges results from all nodes
4. Live Updates: When data changes on any node, that node evaluates affected subscriptions and sends targeted updates to the coordinator
5. Client Delivery: The coordinator forwards updates to the client

Client ──QUERY_SUB──▶ Coordinator ──CLUSTER_SUB_REGISTER──▶ All Nodes
                            │                                    │
                            │◀───────────────────────────────────┘
                            │         Initial results + ACKs
                            │
                            ▼
                     Merge & Send to Client
                            │
              ┌─────────────┼─────────────┐
              │             │             │
         On change:    On change:    On change:
         Node A        Node B        Node C
              │             │             │
              └─────────────┼─────────────┘
                            │
                    CLUSTER_SUB_UPDATE
                            │
                            ▼
                  Forward to Client

Delta Updates

Instead of resending full result sets, nodes send targeted delta updates:

This approach minimizes network traffic and enables efficient UI updates.