Query from Any Node User Guide

Overview

HeliosDB’s query routing feature allows you to connect to any node in the cluster and execute queries transparently, with automatic routing to the appropriate data node.

Benefits

Connect to any node (no single point of failure)
Automatic query routing based on data location
Load balancing across nodes
Transparent to applications

Prerequisites

HeliosDB v3.2+ multi-node cluster
Metadata service configured
Network connectivity between nodes

Configuration

/etc/heliosdb/heliosdb.conf:

query_routing:
  enabled: true
  routing_strategy: data_locality  # Or: round_robin, least_loaded
  max_hops: 2
  timeout_ms: 5000

SQL Examples

Query Any Node

-- Connect to node-1
psql -h node-1 -U heliosdb -d mydb

-- Query data on node-2 (automatic routing)
SELECT * FROM users WHERE id = 12345;

Check Query Routing

-- See which node processed query
SELECT
    query,
    source_node,
    target_node,
    routing_time_ms
FROM heliosdb.query_routing_log
WHERE timestamp > now() - interval '1 hour';

Use Cases

Multi-Region Setup

nodes:
  - name: us-east-1
    region: us-east
    priority: 1
  - name: us-west-1
    region: us-west
    priority: 2

routing:
  prefer_local_region: true

Load Balancing

# Application uses connection pool to random nodes
nodes = ['node-1:5432', 'node-2:5432', 'node-3:5432']
conn = psycopg2.connect(host=random.choice(nodes), ...)

Troubleshooting

Routing Errors

-- Check routing failures
SELECT
    error_message,
    COUNT(*) as count
FROM heliosdb.routing_errors
WHERE timestamp > now() - interval '1 hour'
GROUP BY error_message;

Best Practices

Use connection pooling with multiple nodes
Monitor routing latency
Prefer data locality for performance
Configure appropriate timeouts

For more: /docs/architecture/query-routing.md