---
title: "GraphQL Compatibility"
---

# GraphQL Compatibility

:::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.
:::

Detailed feature compatibility reference for HeliosDB's GraphQL implementation.

## GraphQL Specification Compliance

| Feature | Result | Notes |
|---------|--------|-------|
| Query Operations | Supported | Full support |
| Mutation Operations | Supported | CRUD mutations |
| Subscription Operations | Supported | Real-time via WebSocket |
| Fragments | Supported | Inline and named |
| Variables | Supported | All types |
| Directives | Supported | Built-in and custom |
| Introspection | Supported | Full schema introspection |

## Schema Features

### Types

| Type | Result | Notes |
|------|--------|-------|
| Scalar | Supported | String, Int, Float, Boolean, ID |
| Object | Supported | Auto-generated from tables |
| Input Object | Supported | For mutations |
| Enum | Supported | From table columns |
| List | Supported | Arrays and connections |
| Non-Null | Supported | Required fields |
| Interface | Supported | For polymorphic types |
| Union | Supported | Multiple return types |

### Custom Scalars

| Scalar | Result | Database Type |
|--------|--------|---------------|
| DateTime | Supported | TIMESTAMP |
| Date | Supported | DATE |
| Time | Supported | TIME |
| JSON | Supported | JSONB |
| UUID | Supported | UUID |
| BigInt | Supported | BIGINT |
| Decimal | Supported | DECIMAL |
| Upload | Supported | For file uploads |

### Directives

| Directive | Result | Description |
|-----------|--------|-------------|
| @skip | Supported | Conditional field skip |
| @include | Supported | Conditional field include |
| @deprecated | Supported | Mark as deprecated |
| @specifiedBy | Supported | Scalar URL specification |
| @auth | Supported | Authentication required |
| @rbac | Supported | Role-based access |
| @cache | Supported | Response caching |
| @rateLimit | Supported | Field-level rate limiting |

## Query Capabilities

### Filtering

| Operator | Example | Description |
|----------|---------|-------------|
| `_eq` | `{status: {_eq: "active"}}` | Equal |
| `_neq` | `{status: {_neq: "deleted"}}` | Not equal |
| `_gt` | `{age: {_gt: 18}}` | Greater than |
| `_gte` | `{age: {_gte: 18}}` | Greater or equal |
| `_lt` | `{price: {_lt: 100}}` | Less than |
| `_lte` | `{price: {_lte: 100}}` | Less or equal |
| `_in` | `{id: {_in: [1, 2, 3]}}` | In list |
| `_nin` | `{id: {_nin: [1, 2]}}` | Not in list |
| `_like` | `{name: {_like: "%john%"}}` | SQL LIKE |
| `_ilike` | `{name: {_ilike: "%JOHN%"}}` | Case-insensitive LIKE |
| `_is_null` | `{deleted_at: {_is_null: true}}` | IS NULL |
| `_contains` | `{tags: {_contains: ["a"]}}` | Array contains |
| `_contained_in` | `{tags: {_contained_in: ["a", "b"]}}` | Array contained in |

### Sorting

```graphql
query {
  users(order_by: [
    { created_at: desc },
    { name: asc }
  ]) {
    id
    name
  }
}
```

### Pagination

| Style | Result | Description |
|-------|--------|-------------|
| Offset | Supported | `limit` and `offset` |
| Cursor | Supported | Relay-style connections |

```graphql
# Offset pagination
query {
  users(limit: 10, offset: 20) {
    id
    name
  }
}

# Cursor pagination
query {
  usersConnection(first: 10, after: "cursor123") {
    edges {
      node { id name }
      cursor
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}
```

### Aggregations

```graphql
query {
  users_aggregate(where: {status: {_eq: "active"}}) {
    aggregate {
      count
      sum { balance }
      avg { age }
      max { created_at }
      min { created_at }
    }
  }
}
```

## Mutations

### Insert

```graphql
mutation {
  insert_users(objects: [
    { name: "Alice", email: "alice@example.com" }
  ]) {
    affected_rows
    returning {
      id
      name
    }
  }
}
```

### Update

```graphql
mutation {
  update_users(
    where: { id: { _eq: 1 } },
    _set: { status: "inactive" }
  ) {
    affected_rows
    returning {
      id
      status
    }
  }
}
```

### Delete

```graphql
mutation {
  delete_users(where: { status: { _eq: "deleted" } }) {
    affected_rows
  }
}
```

### Upsert

```graphql
mutation {
  insert_users(
    objects: [{ id: 1, name: "Alice", email: "alice@example.com" }],
    on_conflict: {
      constraint: users_pkey,
      update_columns: [name, email]
    }
  ) {
    affected_rows
  }
}
```

## Subscriptions

```graphql
subscription {
  users(where: { status: { _eq: "active" } }) {
    id
    name
    status
  }
}
```

## Federation

### Apollo Federation v2 Support

| Directive | Result | Description |
|-----------|--------|-------------|
| @key | Supported | Entity key |
| @external | Supported | External field |
| @requires | Supported | Required fields |
| @provides | Supported | Provided fields |
| @extends | Supported | Type extension |
| @shareable | Supported | Shareable field |
| @inaccessible | Supported | Hide from schema |
| @override | Supported | Override field |
| @tag | Supported | Schema tagging |

## Performance Features

| Feature | Result | Description |
|---------|--------|-------------|
| Query Batching | Supported | Multiple queries in one request |
| DataLoader | Supported | N+1 query prevention |
| Persistent Queries | Supported | APQ for reduced bandwidth |
| Response Caching | Supported | Configurable TTL |
| Query Complexity | Supported | Cost analysis |
| Depth Limiting | Supported | Max query depth |

## Client Compatibility

| Client | Result | Notes |
|--------|--------|-------|
| Apollo Client | Tested | Full support |
| Relay | Tested | Connection spec |
| urql | Tested | Full support |
| graphql-request | Tested | Lightweight client |
| gql (Python) | Tested | Full support |
| graphql-go | Tested | Full support |

---