GraphQL Quick Start Guide

GraphQL Quick Start Guide

Get up and running with HeliosDB’s GraphQL API in minutes. This guide covers essential operations from basic queries to real-time subscriptions.

Prerequisites

• HeliosDB server running (default GraphQL endpoint: https://localhost:443/graphql)
• API key or authentication token
• A GraphQL client library (Apollo, gql, or curl)

Connection Details

Parameter	Default Value
Endpoint	https://localhost:443/graphql
WebSocket	wss://localhost:443/graphql/ws
Playground	https://localhost:443/graphql
Protocol	HTTP/HTTPS
Auth Header	Authorization: Bearer YOUR_API_KEY

---

5-Minute Getting Started

Step 1: Test Your Connection

Using curl to verify the GraphQL endpoint is accessible:

curl -X POST https://localhost:443/graphql \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ __typename }"}'

Step 2: Explore the Schema

Open the GraphQL Playground at https://localhost:443/graphql to explore auto-generated schemas from your database tables.

Step 3: Write Your First Query

query GetUsers {
  users(limit: 10) {
    id
    name
    email
    created_at
  }
}

---

Setting Up GraphQL Clients

JavaScript (Apollo Client)

import { ApolloClient, InMemoryCache, gql } from '@apollo/client';

const client = new ApolloClient({
  uri: 'https://localhost:443/graphql',
  cache: new InMemoryCache(),
  headers: {
    Authorization: 'Bearer YOUR_API_KEY'
  }
});

// Execute a query
const { data } = await client.query({
  query: gql`
    query GetUsers {
      users(limit: 10) {
        id
        name
        email
      }
    }
  `
});
console.log(data.users);

Python (gql)

from gql import gql, Client
from gql.transport.requests import RequestsHTTPTransport

transport = RequestsHTTPTransport(
    url="https://localhost:443/graphql",
    headers={"Authorization": "Bearer YOUR_API_KEY"}
)
client = Client(transport=transport)

query = gql("""
    query GetUsers {
        users(limit: 10) {
            id
            name
            email
        }
    }
""")
result = client.execute(query)
print(result["users"])

---

Writing Queries

Query with Variables

query GetUser($id: Int!) {
  users_by_pk(id: $id) {
    id
    name
    email
    orders {
      id
      total
    }
  }
}

Variables:

{ "id": 123 }

Query with Filtering

query ActiveUsers {
  users(
    where: {
      status: { _eq: "active" },
      created_at: { _gt: "2024-01-01" }
    },
    order_by: { created_at: desc },
    limit: 20
  ) {
    id
    name
    email
  }
}

Aggregation Query

query UsersWithOrderStats {
  users(limit: 10) {
    id
    name
    orders_aggregate {
      aggregate {
        count
        sum { total }
      }
    }
  }
}

---

Mutations for Data Modification

Insert Single Record

mutation CreateUser($input: users_insert_input!) {
  insert_users_one(object: $input) {
    id
    name
    email
    created_at
  }
}

Variables:

{
  "input": {
    "name": "Alice",
    "email": "alice@example.com",
    "status": "active"
  }
}

Update Records

mutation UpdateUserStatus($id: Int!, $status: String!) {
  update_users_by_pk(
    pk_columns: { id: $id },
    _set: { status: $status }
  ) {
    id
    status
    updated_at
  }
}

Delete Records

mutation DeleteUser($id: Int!) {
  delete_users_by_pk(id: $id) {
    id
    name
  }
}

---

Subscriptions for Real-Time Updates

Basic Subscription

subscription WatchNewOrders {
  orders(
    where: { status: { _eq: "pending" } },
    order_by: { created_at: desc },
    limit: 10
  ) {
    id
    total
    status
    created_at
    user { name }
  }
}

Apollo Client with Subscriptions

import { split, HttpLink } from '@apollo/client';
import { WebSocketLink } from '@apollo/client/link/ws';
import { getMainDefinition } from '@apollo/client/utilities';

const httpLink = new HttpLink({
  uri: 'https://localhost:443/graphql',
  headers: { Authorization: 'Bearer YOUR_API_KEY' }
});

const wsLink = new WebSocketLink({
  uri: 'wss://localhost:443/graphql/ws',
  options: {
    reconnect: true,
    connectionParams: { authToken: 'YOUR_API_KEY' }
  }
});

const splitLink = split(
  ({ query }) => {
    const definition = getMainDefinition(query);
    return definition.kind === 'OperationDefinition' &&
           definition.operation === 'subscription';
  },
  wsLink,
  httpLink
);

// Subscribe to changes
client.subscribe({
  query: gql`subscription { orders(limit: 10) { id status } }`
}).subscribe({
  next: (result) => console.log(result.data),
  error: (err) => console.error(err)
});

---

Key Features

Feature	Description
Auto-generated Schema	GraphQL schema generated from database tables
Real-time Subscriptions	WebSocket-based live data updates
Query Batching	DataLoader integration for N+1 prevention
Schema Federation	Support for distributed architectures
Query Complexity	Built-in complexity analysis

---

Next Steps

• GraphQL Configuration - Server configuration options
• GraphQL Compatibility - Feature compatibility matrix
• GraphQL Examples - Advanced code examples
• HTTP/REST API - REST alternative

---

Last Updated: January 2026