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

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.

Field Projection

Use the fields option to receive only the fields you need. This reduces network traffic when records contain many fields but your UI only displays a subset.

const query = client.query('users', {
  where: { status: 'active' },
  fields: ['name', 'avatar'],
});

query.subscribe((results) => {
  // Each result contains only { name, avatar } — other fields are omitted
  results.forEach(r => console.log(r.value));
});

Field projection is applied server-side, so only the selected fields traverse the network. The key is always included regardless of the fields list.

Result Limit

Use the limit option to cap the number of results returned in the initial response. This is useful for pagination or when you only need a top-N view.

const query = client.query('orders', {
  where: { status: 'pending' },
  sort: { createdAt: 'desc' },
  limit: 20,
});

query.subscribe((results) => {
  // results contains at most 20 entries
  // Live updates (ENTER/UPDATE/LEAVE) still arrive for subsequent mutations
  console.log('Top orders:', results.length);
});

When the total matching records exceed the limit, the response includes hasMore: true so your application can implement load-more or cursor-based pagination.

Merkle Delta Reconnect

When a client reconnects after going offline, TopGun uses Merkle trees to efficiently synchronize only the changes that occurred while the client was disconnected, instead of retransmitting the full result set.

How it works:

1. The server maintains a per-query Merkle tree of record hashes
2. On initial QUERY_RESP, the server includes a merkleRootHash
3. When the client reconnects, it sends a QUERY_SYNC_INIT message with its last known merkleRootHash
4. The server compares trees and sends only the changed records

This is fully automatic — no application code is needed. The client stores the Merkle root hash and sends it on reconnect. If the hashes match, no data is retransmitted.