---
title: "GraphQL Protocol Support"
---

# GraphQL Protocol Support

:::caution[Planned: not in the current release]
A GraphQL API for HeliosDB Full is planned. The current release opens no GraphQL listener. Reach
the same data over the PostgreSQL listener or `POST /api/v1/query` today. This page
describes the planned interface.
:::

HeliosDB provides a fully-featured GraphQL API with auto-generated schemas, subscriptions, and federation support.

## Overview

| Property | Value |
|----------|-------|
| **Protocol** | GraphQL over HTTP |
| **Port** | 443 (HTTPS), 8080 (HTTP) |
| **State** | Planned |
| **Compatibility** | 80%+ |

## Quick Start

### GraphQL Playground

Access the interactive GraphQL Playground at:
```
https://localhost:443/graphql
```

### Query Example

```graphql
query GetUsers {
  users(where: { status: { _eq: "active" } }, limit: 10) {
    id
    name
    email
    orders {
      id
      total
      created_at
    }
  }
}
```

### cURL

```bash
curl -X POST https://localhost:443/graphql \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query { users(limit: 10) { id name email } }"
  }'
```

### JavaScript (Apollo Client)

```javascript
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'
  }
});

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

### Python (gql)

```python
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)
```

## Key Features

- Auto-generated GraphQL schema from database tables
- Real-time subscriptions via WebSocket
- Query batching and DataLoader integration
- Schema federation for distributed architectures
- Built-in query complexity analysis
- N+1 query prevention

## Documentation

- **[CONFIGURATION.md](https://www.heliosdb.com/docs/full/reference/protocols/graphql/configuration/)** - Server configuration options
- **[COMPATIBILITY.md](https://www.heliosdb.com/docs/full/reference/protocols/graphql/compatibility/)** - Feature compatibility matrix
- **[EXAMPLES.md](https://www.heliosdb.com/docs/full/reference/protocols/graphql/examples/)** - Code examples and patterns

## Related Resources

- [HTTP/REST API](/docs/full/reference/protocols/http-rest/) - REST alternative

---