GraphQL API

FraiseQL generates a complete GraphQL API from your schema. This reference covers all generated operations.

Schema Structure

type Query {
    # Entity queries
    user(id: ID!): User
    users(where: UserWhereInput, limit: Int, offset: Int, orderBy: UserOrderByInput): [User!]!

    # Relationship queries
    postsByAuthor(authorId: ID!, limit: Int): [Post!]!
}

type Mutation {
    # CRUD operations
    createUser(input: CreateUserInput!): User!
    updateUser(id: ID!, input: UpdateUserInput!): User!
    deleteUser(id: ID!): Boolean!

    # Custom mutations
    publishPost(id: ID!): Post!
}

type Subscription {
    # Real-time updates
    userCreated: User!
    postUpdated(authorId: ID): Post!
}

Queries

Single Entity Query

query GetUser($id: ID!) {
    user(id: $id) {
        id
        name
        email
        createdAt
    }
}

Variables:

{
    "id": "550e8400-e29b-41d4-a716-446655440000"
}

Response:

{
    "data": {
        "user": {
            "id": "550e8400-e29b-41d4-a716-446655440000",
            "name": "John Doe",
            "email": "john@example.com",
            "createdAt": "2024-01-15T10:30:00Z"
        }
    }
}

List Query

query GetUsers($limit: Int, $offset: Int) {
    users(limit: $limit, offset: $offset) {
        id
        name
        email
    }
}

With Filtering:

query GetActiveUsers {
    users(where: { isActive: { _eq: true } }, limit: 20) {
        id
        name
    }
}

With Ordering:

query GetRecentUsers {
    users(orderBy: { createdAt: DESC }, limit: 10) {
        id
        name
        createdAt
    }
}

Nested Queries

query GetPostWithAuthor($id: ID!) {
    post(id: $id) {
        id
        title
        content
        author {
            id
            name
            email
        }
        comments {
            id
            content
            author {
                name
            }
        }
    }
}

Mutations

Create

mutation CreateUser($input: CreateUserInput!) {
    createUser(input: $input) {
        id
        email
        name
        createdAt
    }
}

Variables:

{
    "input": {
        "email": "new@example.com",
        "name": "New User",
        "bio": "Hello world"
    }
}

Update

mutation UpdateUser($id: ID!, $input: UpdateUserInput!) {
    updateUser(id: $id, input: $input) {
        id
        name
        bio
        updatedAt
    }
}

Variables:

{
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "input": {
        "name": "Updated Name",
        "bio": "New bio"
    }
}

Delete

mutation DeleteUser($id: ID!) {
    deleteUser(id: $id)
}

Response:

{
    "data": {
        "deleteUser": true
    }
}

Custom Mutations

mutation PublishPost($id: ID!) {
    publishPost(id: $id) {
        id
        isPublished
        publishedAt
    }
}

Subscriptions

Entity Created

subscription OnUserCreated {
    userCreated {
        id
        name
        email
    }
}

Entity Updated

subscription OnPostUpdated($authorId: ID) {
    postUpdated(authorId: $authorId) {
        id
        title
        updatedAt
    }
}

Using with WebSocket

const ws = new WebSocket('ws://localhost:8080/subscriptions');

ws.onopen = () => {
    ws.send(JSON.stringify({
        type: 'subscribe',
        id: '1',
        payload: {
            query: `subscription { userCreated { id name } }`
        }
    }));
};

ws.onmessage = (event) => {
    const data = JSON.parse(event.data);
    console.log('New user:', data.payload.data.userCreated);
};

Input Types

Create Input

input CreateUserInput {
    email: String!
    name: String!
    bio: String
    avatarUrl: String
}

Update Input

input UpdateUserInput {
    name: String
    bio: String
    avatarUrl: String
}

All fields optional - only provided fields are updated.

Filter Input

input UserWhereInput {
    id: IDFilter
    email: StringFilter
    name: StringFilter
    isActive: BooleanFilter
    createdAt: DateTimeFilter
    _and: [UserWhereInput!]
    _or: [UserWhereInput!]
    _not: UserWhereInput
}

input StringFilter {
    _eq: String
    _neq: String
    _in: [String!]
    _nin: [String!]
    _like: String
    _ilike: String
    _is_null: Boolean
}

Order By Input

input UserOrderByInput {
    id: OrderDirection
    name: OrderDirection
    email: OrderDirection
    createdAt: OrderDirection
}

enum OrderDirection {
    ASC
    DESC
    ASC_NULLS_FIRST
    ASC_NULLS_LAST
    DESC_NULLS_FIRST
    DESC_NULLS_LAST
}

Scalar Types

Scalar	GraphQL	JSON Format
`ID`	`ID`	UUID string
`String`	`String`	UTF-8 string
`Int`	`Int`	32-bit integer
`Float`	`Float`	Double precision
`Boolean`	`Boolean`	true/false
`DateTime`	`DateTime`	ISO 8601
`Date`	`Date`	YYYY-MM-DD
`Time`	`Time`	HH:MM:SS
`Decimal`	`Decimal`	String (precision)
`JSON`	`JSON`	Any JSON value

Error Responses

Validation Error

{
    "errors": [{
        "message": "Variable '$email' expected type 'String!' but got null",
        "locations": [{"line": 1, "column": 15}],
        "extensions": {
            "code": "GRAPHQL_VALIDATION_FAILED"
        }
    }]
}

Not Found

{
    "data": {
        "user": null
    }
}

Authorization Error

{
    "errors": [{
        "message": "Forbidden: missing scope read:User.email",
        "path": ["user", "email"],
        "extensions": {
            "code": "FORBIDDEN"
        }
    }]
}

Business Logic Error

{
    "errors": [{
        "message": "User with email already exists",
        "path": ["createUser"],
        "extensions": {
            "code": "DUPLICATE_EMAIL"
        }
    }]
}

Introspection

Schema Query

query {
    __schema {
        types {
            name
            kind
        }
    }
}

Type Query

query {
    __type(name: "User") {
        name
        fields {
            name
            type {
                name
                kind
            }
        }
    }
}

Playground

Access the GraphQL playground at:

http://localhost:8080/graphql

Features:

Interactive query editor
Schema explorer
Variable editor
Response viewer
Query history

Batching

Send multiple operations in one request:

[
    {
        "query": "query { user(id: \"1\") { name } }"
    },
    {
        "query": "query { user(id: \"2\") { name } }"
    }
]

Response:

[
    {"data": {"user": {"name": "User 1"}}},
    {"data": {"user": {"name": "User 2"}}}
]

Limit: Batch size limits are enforced at the server level. The [graphql] TOML namespace is not a verified fraiseql.toml section — check the TOML Config Reference for current batch configuration options.

HTTP Details

Endpoint

POST /graphql
Content-Type: application/json

Request Format

{
    "query": "query GetUser($id: ID!) { user(id: $id) { name } }",
    "operationName": "GetUser",
    "variables": {
        "id": "123"
    }
}

GET Requests (APQ)

GET /graphql?extensions={"persistedQuery":{"version":1,"sha256Hash":"..."}}
    &variables={"id":"123"}

Headers

Header	Description
`Authorization`	Bearer token for auth
`X-Request-ID`	Request tracing ID
`Content-Type`	`application/json`

Decorators

Decorators — Define schema elements

Operators

Operators — Filter operators

Scalars

Scalars — Type reference

Pagination

Pagination — Cursor and offset pagination, connection types

Custom Queries

Custom Queries — sql_source mapping, full-text search, sorting