Decorators

FraiseQL uses decorators (Python) and decorator functions (TypeScript) to define GraphQL schema elements. This reference covers all available decorators, the GraphQL SDL they generate, and how to handle errors within decorated functions.

Note

This page documents Python decorators. TypeScript uses @Type(), @Input(), @Query(), @Mutation() from import { Type, Input, Query, Mutation } from 'fraiseql'. Go uses struct tags: fraiseql:"fieldname". See TypeScript SDK and Go SDK.

Prefer TOML?

SpecQL is a TOML-first schema authoring tool that generates these decorators from TOML definitions. It includes 56 semantic scalar types (Email, IBAN, Money, etc.) and is a good fit for teams that want to keep schema definitions in a data format rather than Python code.

Decorator Execution Order

When a request arrives, FraiseQL processes it through a fixed pipeline:

Request
  → Middleware (in registration order)
  → Authentication (JWT/API key verification)
  → Authorization (role + scope checks)
  → Resolver (SQL view or function execution)
  → Response

When multiple decorators protect the same resolver, they execute in this order:

1. @authenticated — JWT validation (fails fast if not logged in)
2. @requires_scope — OAuth scope check
3. @role — Role-based access check
4. Resolver executes
5. @after_mutation or @observer — Post-execution side effects

Note: @before_mutation exceptions abort the mutation and roll back the database transaction.

This means:

• @middleware functions run before any authentication check — they can read or modify the raw request
• Authentication failures short-circuit before reaching authorization or resolvers
• @query/@mutation requires_scope checks run after the token is verified
• @before_mutation hooks run inside the resolver phase, after all auth checks pass
• @after_mutation hooks run after the SQL function completes successfully

@type

Defines a GraphQL object type.

Python

import fraiseql

@fraiseql.type
class User:
    """A user in the system."""
    id: ID
    name: str
    email: str
    created_at: DateTime

TypeScript

import { Type } from 'fraiseql';

@Type()
class User {
    /** A user in the system. */
    id!: ID;
    name!: string;
    email!: string;
    createdAt!: Date;
}

Generated GraphQL SDL:

type User {
  """A user in the system."""
  id: ID!
  name: String!
  email: String!
  createdAt: DateTime!
}

Options

Option	Type	Description
implements	list[str]	Interfaces to implement
relay	bool	Implement the Node interface and enable keyset cursor generation
requires_role	str	Required role to access this type
crud	bool or list[str]	Auto-generate CRUD queries/mutations. True = all ops, or list: ["create", "read", "list", "update", "delete"]
tenant_scoped	bool	Auto-inject tenant_id from JWT on all queries/mutations for this type
sql_source	str	Override the default view name (default: v_{snake_case_name})
key_fields	list[str]	Federation key fields for entity resolution. When export_schema(federation=...) is used, types without explicit key_fields default to ["id"]
extends	bool	Marks this type as extending a type defined in another subgraph (Apollo Federation extend type)

When relay=True, the type implements the Node interface, the global node(id: ID!) query is added to the schema, and fraiseql compile validates that pk_{entity} is present in the corresponding SQL view.

Python

@fraiseql.type(implements=["Node"])
class UserAnalytics:
    id: ID
    page_views: int

TypeScript

@Type({ implements: ['Node'] })
class UserAnalytics {
    id!: ID;
    pageViews!: number;
}

Field Options

Use Annotated (Python) or field decorators (TypeScript) for field-level options:

Python

from typing import Annotated

@fraiseql.type
class User:
    id: ID
    email: str

    # Protected field — hidden or rejected if scope missing
    salary: Annotated[Decimal, fraiseql.field(requires_scope="hr:read", on_deny="mask")]

    # Deprecated field
    username: Annotated[str, fraiseql.field(deprecated="Use email instead")]

    # Field with description
    bio: Annotated[str | None, fraiseql.field(description="User biography")]

TypeScript

import { Type, field } from 'fraiseql';

@Type()
class User {
    id!: ID;
    email!: string;

    @field({ requiresScope: 'hr:read' })
    salary!: number;

    @field({ deprecated: 'Use email instead' })
    username!: string;
}

@query

Defines a GraphQL query.

Python

@fraiseql.query
def user(id: ID) -> User | None:
    """Get a user by ID."""
    return fraiseql.config(sql_source="v_user")

TypeScript

import { Query, ID } from 'fraiseql';

@Query({ sqlSource: 'v_user' })
function user(id: ID): Promise<User | null> {
    return Promise.resolve(null);
}

Generated GraphQL SDL:

type Query {
  user(id: ID!): User
}

Options

Option	Type	Default	Description
sql_source	str	—	View or table to query
relay	bool	False	Enable Relay spec (Connection/Edge/PageInfo, keyset cursors)
auto_params	bool | dict	inferred	True = all four params; False = none; dict for partial overrides (e.g. {"limit": True, "offset": False}). Partial dicts merge with [query_defaults] in fraiseql.toml.
inject	dict[str, str]	—	Server-side JWT claim injection. Keys are SQL param names; values are "jwt:<claim>". See Server-Side Injection.
cache_ttl_seconds	int	—	Cache duration in seconds. Set to 0 to disable caching for this query
additional_views	list[str]	None	Additional SQL views this query reads from. Used for cache invalidation — mutations to these views will also evict this query’s cache entries.
requires_role	str	—	Required role
requires_scope	str	—	Required scope
rest_path	str | None	None	REST endpoint path override (e.g. "/users/{id}"). When absent, REST auto-derives endpoints from query names. Path parameter names must match function argument names.
rest_method	str | None	"GET"	HTTP method override for the REST endpoint. Defaults to "GET" for queries.

Transport notes:

• REST endpoints are auto-derived for all queries/mutations when [rest] is enabled. Use rest_path/rest_method only to override the default path or method.
• gRPC endpoints are auto-generated for all queries/mutations when [grpc] is enabled — no per-operation annotation needed. Filter with include_types/exclude_types in [grpc].
• Path parameters in rest_path must match function argument names — mismatches are caught at compile time.
• Duplicate (method, path) pairs are rejected at compile time.

REST path override example

Note

REST (rest_path, rest_method) transport annotations require the rest-transport Cargo feature and the [rest] TOML section. Available since v2.1. gRPC endpoints are auto-generated and do not use decorator parameters — see gRPC Transport.

Python

# Custom REST path (overrides auto-derived /users/{id})
@fraiseql.query(rest_path="/api/users/{id}", rest_method="GET")
def get_user(id: UUID) -> User:
    return fraiseql.config(sql_source="v_user")

@fraiseql.mutation(
    sql_source="create_user",
    operation="CREATE",
    rest_path="/api/users",
    rest_method="POST",
)
def create_user(email: str, name: str) -> User: ...

TypeScript

@Query({
  sqlSource: 'v_user',
  restPath: '/api/users/{id}',
  restMethod: 'GET',
})
async function getUser(id: string): Promise<User> {}

Auto Params

For list queries (-> list[T]), all four params are enabled automatically. Pass auto_params=False to opt out:

Param	GraphQL argument	SQL
where	where: {Type}WhereInput	WHERE …
orderBy	orderBy: [{Type}OrderByInput!]	ORDER BY …
limit	limit: Int	LIMIT …
offset	offset: Int	OFFSET …

# All four auto-enabled (list return type)
@fraiseql.query
def posts() -> list[Post]:
    return fraiseql.config(sql_source="v_post")

# Opt out entirely
@fraiseql.query(auto_params=False)
def posts() -> list[Post]:
    return fraiseql.config(sql_source="v_post")

Relay mode

When relay=True, the query generates a Relay-spec {Type}Connection instead of [Type!]!, and limit/offset are replaced by first/after/last/before. Requires @fraiseql.type(relay=True) on the return type and pk_{entity} in the SQL view.

@fraiseql.type(relay=True)
class Post:
    id: ID
    title: str

@fraiseql.query
def posts() -> list[Post]:
    return fraiseql.config(sql_source="v_post", relay=True)

See Relay Pagination for full details.

@mutation

Defines a GraphQL mutation.

Python

@fraiseql.mutation(sql_source="fn_create_user", operation="CREATE")
def create_user(email: str, name: str) -> User:
    """Create a new user."""
    pass

TypeScript

import { Mutation } from 'fraiseql';

@Mutation({ sqlSource: 'fn_create_user', operation: 'CREATE' })
function createUser(email: string, name: string): Promise<User> {
    return Promise.resolve({} as User);
}

Generated GraphQL SDL:

type Mutation {
  createUser(email: String!, name: String!): User!
}

Options

Option	Type	Default	Description
sql_source	str	—	SQL function to call
operation	str	—	"CREATE", "UPDATE", "DELETE", "CUSTOM"
inject	dict[str, str]	—	Server-side JWT claim injection. Keys are SQL param names; values are "jwt:<claim>". Injected params are never exposed to clients. See Server-Side Injection.
requires_role	str	—	Required role
requires_scope	str	—	Required scope
invalidates_views	list[str]	—	View names to purge from response cache after the mutation runs (e.g. ["v_post", "v_comment"]).
invalidates_fact_tables	list[str]	—	Fact table names to invalidate after the mutation (e.g. ["tf_sales"]).
cascade	bool	None	Expose GraphQL Cascade data in the mutation response. When True, the cascade field from mutation_response is included in the GraphQL response and fed into the cache invalidation pipeline. When None (default), falls back to the [cascade].enabled TOML setting.
rest_path	str | None	None	REST endpoint path override (e.g. "/users"). When absent, REST auto-derives endpoints from mutation names.
rest_method	str | None	"POST"	HTTP method override for the REST endpoint. Defaults to "POST" for mutations.

Python

@fraiseql.mutation(
    sql_source="fn_delete_user",
    operation="DELETE",
    requires_scope="admin:delete_user"
)
def delete_user(id: ID) -> bool:
    """Delete a user. Requires admin scope."""
    pass

TypeScript

@Mutation({
    sqlSource: 'fn_delete_user',
    operation: 'DELETE',
    requiresScope: 'admin:delete_user',
})
function deleteUser(id: ID): Promise<boolean> {
    return Promise.resolve(true);
}

Error Handling

Raise errors from within @before_mutation hooks or @after_mutation hooks to abort or signal failures:

Python

# Raise errors from PostgreSQL functions using RAISE EXCEPTION —
# not from Python hooks. The Python layer is schema authoring only.
#
# In your PostgreSQL function:
# IF user_is_system THEN
#     RAISE EXCEPTION 'Cannot delete system users'
#         USING ERRCODE = 'P0001', HINT = 'FORBIDDEN';
# END IF;

TypeScript

import { beforeMutation, FraiseQLError } from 'fraiseql';

beforeMutation('deleteUser', async (args, context) => {
    const user = await getUser(args.id);
    if (!user) {
        throw new FraiseQLError('NOT_FOUND', `User ${args.id} does not exist`);
    }
    if (user.isSystemUser) {
        throw new FraiseQLError('FORBIDDEN', 'Cannot delete system users');
    }
});

FraiseQLError produces a structured GraphQL error with an extensions.code field:

{
  "errors": [
    {
      "message": "Cannot delete system users",
      "extensions": { "code": "FORBIDDEN" }
    }
  ]
}

@subscription

Defines a GraphQL subscription.

Python

@fraiseql.subscription(entity_type="User", topic="user_created")
def user_created() -> User:
    """Subscribe to new users."""
    pass

TypeScript

import { Subscription } from 'fraiseql';

@Subscription({ entityType: 'User', topic: 'user_created' })
function userCreated(): AsyncIterator<User> {
    return {} as AsyncIterator<User>;
}

Generated GraphQL SDL:

type Subscription {
  userCreated: User!
}

Options

Option	Type	Description
entity_type	str	Entity to watch
topic	str	NATS topic
operation	str	"INSERT", "UPDATE", "DELETE"

Python

@fraiseql.subscription(
    entity_type="Order",
    operation="UPDATE",
    topic="order_updated"
)
def order_shipped(customer_id: ID | None = None) -> Order:
    """Subscribe to order updates."""
    pass

TypeScript

@Subscription({
    entityType: 'Order',
    operation: 'UPDATE',
    topic: 'order_updated',
})
function orderShipped(customerId?: ID): AsyncIterator<Order> {
    return {} as AsyncIterator<Order>;
}

@input

Defines a GraphQL input type.

@fraiseql.input
class CreateUserInput:
    """Input for creating a user."""
    email: str
    name: str
    bio: str | None = None
    role: str = "user"

Generated GraphQL SDL:

input CreateUserInput {
  """Input for creating a user."""
  email: String!
  name: String!
  bio: String
  role: String!
}

Validation

Input validation is enforced in PostgreSQL functions using RAISE EXCEPTION, not via Python-level decorators. See Validation Rules for the TOML-based validation configuration that FraiseQL applies before SQL execution.

@enum

Defines a GraphQL enum.

from enum import Enum

@fraiseql.enum
class OrderStatus(Enum):
    """Status of an order."""
    PENDING = "pending"
    CONFIRMED = "confirmed"
    SHIPPED = "shipped"
    DELIVERED = "delivered"
    CANCELLED = "cancelled"

Usage:

@fraiseql.type
class Order:
    id: ID
    status: OrderStatus

@interface

Defines a GraphQL interface.

@fraiseql.interface
class Node:
    """An object with an ID."""
    id: ID

@fraiseql.interface
class Timestamped:
    """An object with timestamps."""
    created_at: DateTime
    updated_at: DateTime

Implement interfaces:

@fraiseql.type(implements=["Node", "Timestamped"])
class User:
    id: ID
    name: str
    created_at: DateTime
    updated_at: DateTime

@union

Defines a GraphQL union type.

@fraiseql.type
class User:
    id: ID
    name: str

@fraiseql.type
class Post:
    id: ID
    title: str

@fraiseql.union(members=[User, Post])
class SearchResult:
    """Result from a search query."""
    pass

Usage:

@fraiseql.query
def search(query: str) -> list[SearchResult]:
    return fraiseql.config(sql_source="fn_search")

@scalar

Defines a custom scalar type. The class must inherit from CustomScalar and implement serialize, parse_value, and parse_literal.

from fraiseql import CustomScalar, scalar

@scalar
class TaxId(CustomScalar):
    """Tax ID with validation."""
    name = "TaxId"

    def serialize(self, value: str) -> str:
        return value.upper().replace("-", "")

    def parse_value(self, value: str) -> str:
        cleaned = value.upper().replace("-", "")
        if len(cleaned) != 9:
            raise ValueError("Tax ID must be 9 characters")
        return cleaned

    def parse_literal(self, ast) -> str:
        return self.parse_value(ast.value)

Typed Error Unions

Use @fraiseql.error to annotate error types returned by mutations. Scalar fields (str, int, float, datetime, UUID, etc.) are populated from the metadata JSONB column of the mutation_response row returned by your SQL function. Both camelCase and snake_case metadata keys are resolved automatically.

@fraiseql.error
class InsufficientFundsError:
    code: str
    required_amount: float
    available_amount: float

@fraiseql.mutation(sql_source="fn_transfer_funds")
def transfer_funds(
    from_id: str,
    to_id: str,
    amount: float
) -> Transfer | InsufficientFundsError:
    ...

This generates a GraphQL union return type — clients handle domain errors as typed data rather than error extensions. The SQL function must return a mutation_response row; when status begins with "failed:" or is "error", the metadata JSONB is used to populate the error type’s fields.

fraiseql.field()

Field-level configuration for use with Annotated.

fraiseql.field(
    requires_scope="scope",   # Required OAuth scope
    on_deny="reject",         # "reject" (default) or "mask"
    deprecated="message",     # Deprecation reason
    description="text",       # Field description
)

Parameter	Type	Description
requires_scope	str	OAuth scope required to read this field
on_deny	str	"reject" raises an error; "mask" returns null
deprecated	str	Marks the field deprecated with a reason message
description	str	Field description exposed in introspection

Type Annotations

Optional Fields

@fraiseql.type
class User:
    bio: str | None  # Nullable field

Lists

@fraiseql.type
class User:
    roles: list[str]        # Non-null list, non-null items
    tags: list[str] | None  # Nullable list

Forward References

@fraiseql.type
class User:
    posts: list['Post']     # Forward reference
    manager: 'User | None'  # Self-reference

Quick Reference

Decorator Cheat Sheet

Decorator	Purpose	Key Options
@type	Define object type	implements, relay, requires_role
@input	Define input type	—
@query	Define query	sql_source, auto_params, cache_ttl_seconds, rest_path
@mutation	Define mutation	sql_source, operation, requires_scope, cascade, rest_path
@subscription	Define subscription	entity_type, topic, operation
@enum	Define enum	—
@interface	Define interface	—
@union	Define union	members
@scalar	Define custom scalar	—
@error	Define error type	—

Common Auto Params

@fraiseql.query(auto_params={"limit": True, "offset": True, "where": True, "order_by": True})
def users() -> list[User]:
    return fraiseql.config(sql_source="v_user")

Field Options

# With Annotated
from typing import Annotated

@fraiseql.type
class User:
    id: ID
    email: Annotated[str, fraiseql.field(
        requires_scope="user:read_email",  # Require scope
        on_deny="mask",                    # Return null instead of error
        deprecated="Use contactEmail instead",  # Deprecation
        description="Primary contact email",    # Description
    )]

Verify It Works

1. Define a simple type with decorators:

   import fraiseql
   
   @fraiseql.type
   class Product:
       id: str
       name: str
       price: float

2. Add a query decorator:

   @fraiseql.query
   def product(id: str) -> Product:
       return fraiseql.config(sql_source="v_product")

3. Compile the schema:

   fraiseql compile

   Expected output:

   ✓ Schema validated (1 types, 1 queries)
   ✓ Compiled to schema.compiled.json

4. Introspect the generated schema:

   curl -X POST http://localhost:8080/graphql \
     -H "Content-Type: application/json" \
     -d '{"query": "{ __type(name: \"Product\") { fields { name } } }"}' | jq

   Expected response:

   {
     "data": {
       "__type": {
         "fields": [
           {"name": "id"},
           {"name": "name"},
           {"name": "price"}
         ]
       }
     }
   }

5. Test the query:

   curl -X POST http://localhost:8080/graphql \
     -H "Content-Type: application/json" \
     -d '{"query": "{ product(id: \"123\") { id name price } }"}'

6. Test with authorization:

   @fraiseql.mutation(
       sql_source="fn_create_product",
       requires_scope="admin:products"
   )
   def create_product(name: str, price: float) -> Product:
       pass

   Test without scope (should fail):

   curl -X POST http://localhost:8080/graphql \
     -H "Authorization: Bearer $USER_TOKEN" \
     -d '{"query": "mutation { createProduct(name: \"Widget\", price: 9.99) { id } }"}'

   Expected error:

   {
     "errors": [{
       "message": "Forbidden: missing scope admin:products"
     }]
   }

Troubleshooting

Decorator Not Found

@fraiseql.type
class User:
    pass
# Error: module 'fraiseql' has no attribute 'type'

Solution: Use correct import:

import fraiseql

@fraiseql.type  # Correct
class User:
    pass

Type Not Generated

$ fraiseql compile
Warning: Type 'User' has no fields

Check:

1. All fields have type annotations
2. No syntax errors in class definition
3. Class is properly indented under decorator

Forward Reference Error

@fraiseql.type
class User:
    posts: list[Post]  # Error: Post not defined

Solution: Use string literal for forward reference:

@fraiseql.type
class User:
    posts: list['Post']  # Forward reference as string

Mutation Not Working

@fraiseql.mutation(sql_source="fn_create_user")
def create_user(name: str) -> User:
    pass

Check:

1. SQL function exists: SELECT * FROM pg_proc WHERE proname = 'fn_create_user'
2. Function returns correct type
3. Input parameters match function signature

Next Steps

Type System

Type System — Type definitions

Scalars

Scalars — Built-in scalars

GraphQL API

GraphQL API — Generated API