Skip to content
HeliosDB HeliosDB Full

HeliosDB Wave 1 Beta - 10-Minute Quickstart

HeliosDB Wave 1 Beta - 10-Minute Quickstart

Get up and running with all 4 innovations in 10 minutes

Step 1: Install (2 minutes)

Terminal window
# Docker (easiest)
docker run -d --name heliosdb-beta \
  -p 5432:5432 -p 8080:8080 \
  heliosdb/heliosdb:v7.0-beta-wave1


# Verify
curl http://localhost:8080/health

Step 2: Connect (1 minute)

Terminal window
# Install Python client
pip install heliosdb


# Connect
python3
>>> import heliosdb
>>> conn = heliosdb.connect("postgresql://localhost:5432/heliosdb")
>>> cursor = conn.cursor()

Step 3: Try Conversational BI (2 minutes)

# Enable NL2SQL
cursor.execute("SET heliosdb.nl2sql = ON")


# Ask in natural language
cursor.execute("""
    Show me the top 5 customers by total spending
""")


print(cursor.fetchall())
# Output: [(customer_1, 15420.50), (customer_2, 12350.00), ...]


# Multi-turn conversation
cursor.execute("""
    Now filter to only customers from California
""")


print(cursor.fetchall())

** 88%+ accuracy on complex queries**

Step 4: Try Multimodal Vector Search (2 minutes)

# Search images using text
cursor.execute("""
    SELECT product_id, name, similarity
    FROM products
    WHERE vector_search(
        image_embedding,
        text_embedding('red sports car'),
        modality='cross-modal'
    )
    ORDER BY similarity DESC
    LIMIT 5
""")


print(cursor.fetchall())
# Output: [(123, "Ferrari 488", 0.92), (456, "Porsche 911", 0.89), ...]

** <180ms embedding latency**

Step 5: Try Hybrid Execution (2 minutes)

# Automatic local vs cloud routing
cursor.execute("SET heliosdb.hybrid_mode = 'auto'")


# Small query - runs locally
cursor.execute("SELECT * FROM cache WHERE id < 100")
# Latency: ~5ms (local)


# Large query - runs in cloud with filter pushdown
cursor.execute("""
    SELECT region, COUNT(*)
    FROM sales_history
    WHERE date > '2024-01-01'
    GROUP BY region
""")
# Latency: 150ms (cloud, but 60% faster with pushdown)

** 50-70% latency reduction**

Step 6: Try Cost Optimization (1 minute)

# Enable cost tracking
cursor.execute("SET heliosdb.cost_tracking = ON")


# Run query
cursor.execute("SELECT * FROM large_table LIMIT 1000")


# Check cost
cost = cursor.execute("SELECT last_query_cost()").fetchone()[0]
print(f"Query cost: ${cost:.4f}")
# Output: Query cost: $0.0023


# Set budget alert
cursor.execute("SET heliosdb.budget_limit = 50.00")  # $50 daily

** 20-30% cost savings with auto-optimization**

What You Just Did

  • Ran natural language queries with 88%+ accuracy
  • Searched across image/text/audio modalities
  • Experienced hybrid local+cloud execution
  • Tracked query costs in real-time

All in under 10 minutes!

📚 Next Steps

  1. Read full guide: BETA_DEPLOYMENT_GUIDE.md
  2. Run benchmarks: TPC-H Guide
  3. Try stress tests: Stress Test Guide
  4. Join beta Slack: #heliosdb-beta

Pro Tips

For NL2SQL

  • Use schema hints for better accuracy: SET heliosdb.schema_hints = ON
  • Try different LLM providers: OpenAI, Anthropic, Cohere
  • Review execution plans: EXPLAIN <your NL query>
  • Rebuild indexes regularly for best performance
  • Use appropriate similarity metrics (cosine, euclidean, dot)
  • Batch embed operations for 5x speedup

For Hybrid Execution

  • Monitor query routing: SELECT * FROM heliosdb.query_routing_stats
  • Adjust thresholds: SET heliosdb.local_threshold_rows = 10000
  • Track savings: SELECT * FROM heliosdb.hybrid_savings

For Cost Optimization

  • Review recommendations: SELECT * FROM heliosdb.cost_recommendations
  • Enable auto-apply: SET heliosdb.auto_apply_optimizations = ON
  • Set up alerts: Configure in config/beta.toml

❓ Common Questions

Q: What happens if NL2SQL makes an error? A: HeliosDB uses execution-based refinement - it tries again with fixes. After 3 attempts, it returns the best query + confidence score.

Q: Can I use my own embedding models? A: Yes! Configure custom models in config/beta.toml under [multimodal_vector]

Q: How does hybrid routing decide local vs cloud? A: Based on data size, query complexity, and cost. You can view decisions with EXPLAIN HYBRID.

Q: Are costs estimated or actual? A: Actual costs for cloud operations, estimated for local (based on CPU/memory usage).

🐛 Troubleshooting

Can’t connect: Check Docker is running and ports are exposed NL2SQL errors: Verify API key in config: heliosdb-cli config check Slow queries: Enable query optimization: SET heliosdb.auto_optimize = ON High costs: Review query patterns: SELECT * FROM heliosdb.expensive_queries

Support: beta-support@heliosdb.com Version: Wave 1 Beta (v7.0.0-beta.1) Last Updated: November 10, 2025