Decorators Reference¶
Complete reference for all FraiseQL decorators with signatures, parameters, and examples.
Type Decorators¶
@fraiseql.type / @fraise_type¶
Purpose: Define GraphQL object types
Signature:
import fraiseql
@fraiseql.type(
sql_source: str | None = None,
jsonb_column: str | None = "data",
implements: list[type] | None = None,
resolve_nested: bool = False
)
Parameters:
| Parameter | Type | Default | Description |
|---|---|---|---|
| sql_source | str | None | None | Database table/view name for automatic query generation |
| jsonb_column | str | None | "data" | JSONB column name. Use None for regular column tables |
| implements | list[type] | None | None | List of GraphQL interface types |
| resolve_nested | bool | False | Resolve nested instances via separate queries |
Examples: See Types and Schema
@input / @fraise_input¶
Purpose: Define GraphQL input types
Signature:
import fraiseql
@input
class InputName:
field1: str
field2: int | None = None
Parameters: None (decorator takes no arguments)
Examples: See Types and Schema
@enum / @fraise_enum¶
Purpose: Define GraphQL enum types from Python Enum classes
Signature:
@enum
class EnumName(Enum):
VALUE1 = "value1"
VALUE2 = "value2"
Parameters: None
Examples: See Types and Schema
@interface / @fraise_interface¶
Purpose: Define GraphQL interface types
Signature:
@interface
class InterfaceName:
field1: str
field2: int
Parameters: None
Examples: See Types and Schema
Query Decorators¶
@fraiseql.query¶
Purpose: Mark async functions as GraphQL queries
Signature:
import fraiseql
@fraiseql.query
async def query_name(info, param1: Type1, param2: Type2 = default) -> ReturnType:
pass
Parameters: None (decorator takes no arguments)
First Parameter: Always info (GraphQL resolver info)
Return Type: Any GraphQL type (fraise_type, list, scalar, Connection, etc.)
Examples:
import fraiseql
from fraiseql.types import ID
@fraiseql.query
async def get_user(info, id: ID) -> User:
db = info.context["db"]
return await db.find_one("v_user", where={"id": id})
@fraiseql.query
async def search_users(
info,
name_filter: str | None = None,
limit: int = 10
) -> list[User]:
db = info.context["db"]
filters = {}
if name_filter:
filters["name"] = {"icontains": name_filter}
return await db.find("v_user", where=filters, limit=limit)
See Also: Queries and Mutations
@connection¶
Purpose: Create cursor-based pagination queries
Signature:
import fraiseql
@connection(
node_type: type,
view_name: str | None = None,
default_page_size: int = 20,
max_page_size: int = 100,
include_total_count: bool = True,
cursor_field: str = "id",
jsonb_extraction: bool | None = None,
jsonb_column: str | None = None
)
Parameters:
| Parameter | Type | Default | Required | Description |
|---|---|---|---|---|
| node_type | type | - | Yes | Type of objects in the connection |
| view_name | str | None | None | No | Database view name (inferred from function name if omitted) |
| default_page_size | int | 20 | No | Default number of items per page |
| max_page_size | int | 100 | No | Maximum allowed page size |
| include_total_count | bool | True | No | Include total count in results |
| cursor_field | str | "id" | No | Field to use for cursor ordering |
| jsonb_extraction | bool | None | None | No | No effect: recorded in __fraiseql_connection__ only; rows are read as db.find reads them |
| jsonb_column | str | None | None | No | No effect: recorded only; the JSONB column is the one registered for the view |
Must be used with: @fraiseql.query decorator
Returns: Connection[T]
Examples:
import fraiseql
from fraiseql.types import Connection
from fraiseql.types import ID
@fraiseql.type(sql_source="v_user")
class User:
id: ID
name: str
@connection(node_type=User)
@fraiseql.query
async def users_connection(info, first: int | None = None) -> Connection[User]:
pass # Implementation handled by decorator
@connection(
node_type=Post,
view_name="v_published_posts",
default_page_size=25,
max_page_size=50,
cursor_field="created_at"
)
@fraiseql.query
async def posts_connection(
info,
first: int | None = None,
after: str | None = None
) -> Connection[Post]:
pass
See Also: Queries and Mutations
Mutation Decorators¶
@fraiseql.mutation¶
Purpose: Define GraphQL mutations
Function-based Signature:
import fraiseql
@fraiseql.mutation
async def mutation_name(info, input: InputType) -> ReturnType:
pass
Class-based Signature:
import fraiseql
@fraiseql.mutation(
function: str | None = None,
schema: str | None = None,
context_params: dict[str, str] | None = None,
error_config: MutationErrorConfig | None = None,
name: str | None = None,
result_name: str | None = None,
)
class MutationName:
input: InputType
success: SuccessType
error: ErrorType
Parameters (Class-based):
| Parameter | Type | Default | Description |
|---|---|---|---|
| function | str | None | None | PostgreSQL function name (defaults to snake_case of class name). It only picks the SQL function: several mutations may share one |
| schema | str | None | "public" | PostgreSQL schema containing the function |
| context_params | dict[str, str] | None | None | Maps GraphQL context keys to PostgreSQL function parameters |
| error_config | MutationErrorConfig | None | None | Error configuration for this mutation. If not specified, uses default_error_config from FraiseQLConfig (if set). DEPRECATED - Only used in non-HTTP mode. HTTP mode uses status string taxonomy |
| name | str | None | None | GraphQL field name, used as given. See Field names |
| result_name | str | None | None | GraphQL name of the result union, used as given. See Result union names |
Mutation field names¶
A class mutation's GraphQL field is named after the class: CreateUser becomes
createUser (create_user with camel_case_fields=False). A function
mutation is named after the function. name= sets the field name directly.
function= doesn't change the field name.
Two mutations with the same field name make the schema build raise a
ValueError that names both. Give one of them a different name=.
Names taken from function=
Up to fraiseql 1.28, a class mutation was named after its function=:
RegisterUser with function="register_new_user" was served as
registerNewUser. fraiseql 1.x keeps that name, so upgrading renames
nothing, and the schema build emits one FutureWarning listing every field
still named this way, with its preferred name:
These mutations are named by fraiseql's legacy rule (a field after its function=, a result union after its success type):
field 'registerNewUser' (preferred: 'registerUser')
fraiseql 1.x keeps these names. To choose a name and silence this warning, pass name="..." (field) or result_name="..." (union) to @mutation.
To keep the current name, pass it: @fraiseql.mutation(function="register_new_user", name="registerNewUser").
To switch to the preferred name, pass name="registerUser". Either removes
the mutation from the warning. (fraiseql 2.x on PyPI is the separate
FraiseQL v2 project; it is not a later version of these names.)
Mutations that shared a function= lost a field before 1.29. They get the
class-derived names straight away, with no warning.
For an auto-discovered mutation, the preferred name is the name: in its
@fraiseql:mutation comment; set it to the current name to keep it.
Mutation result union names¶
A mutation whose success and error types differ returns a union of the two.
Each mutation gets its own union, named after its field: createUser returns
CreateUserResult. result_name= sets the union name directly. Several
mutations may share success and error types; each still gets its own union.
When the success and error types are the same class, there is no union and
result_name= is ignored.
Two mutations with the same union name make the schema build raise a
ValueError that names both. Give one of them a different result_name=.
Names taken from the success type
Up to fraiseql 1.28, the union was named after the success type:
UpdatePostTitle with success: PostSuccess returned PostResult, and two
mutations sharing a success type failed the schema build with
multiple types named '...Result'. fraiseql 1.x keeps the union name of a
mutation that works, and the same FutureWarning as for field names lists it:
result union 'PostResult' (preferred: 'UpdatePostTitleResult')
Pass result_name="PostResult" to keep the current name, or
result_name="UpdatePostTitleResult" to switch to the preferred one.
Mutations that shared a success type get the preferred names straight away,
with no warning.
An auto-discovered mutation takes result_name: in its @fraiseql:mutation
comment.
Global Default: If you don't specify error_config on a mutation, FraiseQL will use default_error_config from your FraiseQLConfig (if set). This allows you to set a global error handling strategy and override it per-mutation when needed.
from fraiseql import FraiseQLConfig, DEFAULT_ERROR_CONFIG, STRICT_STATUS_CONFIG
# Set global default
config = FraiseQLConfig(
database_url="postgresql://localhost/mydb",
default_error_config=DEFAULT_ERROR_CONFIG,
)
# Uses global default
@fraiseql.mutation(function="create_user")
class CreateUser:
input: CreateUserInput
success: CreateUserSuccess
error: CreateUserError
# Overrides global default
@fraiseql.mutation(
function="delete_user",
error_config=STRICT_STATUS_CONFIG, # Override
)
class DeleteUser:
input: DeleteUserInput
success: DeleteUserSuccess
error: DeleteUserError
See: FraiseQLConfig.default_error_config for details.
Examples:
import fraiseql
# Function-based: call the PostgreSQL function, then read the row back from the view
@fraiseql.mutation
async def create_user_account(info, input: CreateUserInput) -> User:
db = info.context["db"]
result = await db.execute_function("fn_create_user", input.to_dict())
return await db.find_one(
"v_user", "createUserAccount", info, mandatory_filters={"id": result["id"]}
)
# Class-based
@fraiseql.mutation
class CreateUser:
input: CreateUserInput
success: CreateUserSuccess
error: CreateUserError
# With custom function (name= sets the field to "registerUser"; without it,
# fraiseql 1.x names the field after the function, "registerNewUser", and warns)
@fraiseql.mutation(function="register_new_user", schema="auth", name="registerUser")
class RegisterUser:
input: RegistrationInput
success: RegisterUserSuccess
error: RegisterUserError
# With context parameters - maps context to PostgreSQL function params
@fraiseql.mutation(
function="create_location",
context_params={
"tenant_id": "input_pk_organization",
"user_id": "input_created_by"
}
)
class CreateLocation:
input: CreateLocationInput
success: CreateLocationSuccess
error: CreateLocationError
How context_params Works:
context_params automatically injects GraphQL context values as PostgreSQL function parameters:
import fraiseql
# GraphQL mutation
@fraiseql.mutation(
function="create_location",
context_params={
"tenant_id": "input_pk_organization", # info.context["tenant_id"] → p_pk_organization
"user_id": "input_created_by" # info.context["user_id"] → p_created_by
}
)
class CreateLocation:
input: CreateLocationInput
success: CreateLocationSuccess
error: CreateLocationError
# PostgreSQL function signature
# CREATE FUNCTION create_location(
# p_pk_organization uuid, -- From info.context["tenant_id"]
# p_created_by uuid, -- From info.context["user_id"]
# input jsonb -- From mutation input
# ) RETURNS jsonb
Real-World Example:
import fraiseql
# Context from JWT
async def get_context(request: Request) -> dict:
token = extract_jwt(request)
return {
"tenant_id": token["tenant_id"],
"user_id": token["user_id"]
}
# Mutation with context injection
@fraiseql.mutation(
function="create_order",
context_params={
"tenant_id": "input_tenant_id",
"user_id": "input_created_by"
}
)
class CreateOrder:
input: CreateOrderInput
success: CreateOrderSuccess
error: CreateOrderError
# PostgreSQL function
# CREATE FUNCTION create_order(
# p_tenant_id uuid, -- Automatically from context!
# p_created_by uuid, -- Automatically from context!
# input jsonb
# ) RETURNS jsonb AS $$
# BEGIN
# -- p_tenant_id and p_created_by are available
# -- No need to extract from input JSONB
# INSERT INTO tb_order (tenant_id, data)
# VALUES (p_tenant_id, jsonb_set(input, '{created_by}', to_jsonb(p_created_by)));
# END;
# $$ LANGUAGE plpgsql;
Benefits:
- Security: Tenant/user IDs come from verified JWT, not user input
- Simplicity: No need to pass tenant_id in mutation input
- Consistency: Context injection happens automatically on every mutation
See Also: Queries and Mutations
@success / @error / @result¶
Purpose: Helper decorators for mutation result types
Usage:
from fraiseql.mutations.decorators import success, error
@success
class CreateUserSuccess:
user: User
message: str
@error
class CreateUserError:
code: str
message: str
field: str | None = None
@fraiseql.mutation
async def create_user(info, input: CreateUserInput) -> CreateUserSuccess | CreateUserError:
...
Note: These are type markers, not required for mutations. Use @fraiseql.type instead for most cases.
result() is deprecated
fraiseql.result(success_cls, error_cls) builds a union type from a success
and an error class. It is deprecated since 1.29 and keeps working in
fraiseql 1.x: annotate Success | Error instead, and the mutation's union is named as
described in Result union names.
Field Decorators¶
@field¶
Purpose: Mark methods as GraphQL fields with custom resolvers
Signature:
import fraiseql
@field(
resolver: Callable[..., Any] | None = None,
description: str | None = None,
track_n1: bool = True
)
def method_name(self, info, ...params) -> ReturnType:
pass
Parameters:
| Parameter | Type | Default | Description |
|---|---|---|---|
| method | Callable | - | Method to decorate (when used without parentheses) |
| resolver | Callable | None | None | Optional custom resolver function |
| description | str | None | None | Field description for GraphQL schema |
| track_n1 | bool | True | Track N+1 query patterns for performance monitoring |
Examples:
import fraiseql
@fraiseql.type
class User:
first_name: str
last_name: str
@field(description="Full display name")
def display_name(self) -> str:
return f"{self.first_name} {self.last_name}"
@field(description="User's posts")
async def posts(self, info) -> list[Post]:
db = info.context["db"]
return await db.find("v_post", where={"user_id": self.id})
@field(description="Posts with parameters")
async def recent_posts(
self,
info,
limit: int = 10
) -> list[Post]:
db = info.context["db"]
return await db.find(
"v_post",
where={"user_id": self.id},
order_by=[{"created_at": "DESC"}],
limit=limit
)
See Also: Queries and Mutations
@dataloader_field¶
Purpose: Automatically use DataLoader for field resolution
Signature:
@dataloader_field(
loader_class: type[DataLoader],
key_field: str,
description: str | None = None
)
async def method_name(self, info) -> ReturnType:
pass # Implementation is auto-generated
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
| loader_class | type[DataLoader] | Yes | DataLoader class to use for loading |
| key_field | str | Yes | Field name on parent object containing the key to load |
| description | str | None | No | Field description for GraphQL schema |
Examples:
from fraiseql import dataloader_field
from fraiseql.optimization.dataloader import DataLoader
from fraiseql.types import ID
# Define DataLoader
class UserDataLoader(DataLoader):
async def batch_load(self, keys: list[UUID]) -> list[User | None]:
db = self.context["db"]
users = await db.find("v_user", where={"id": {"in": keys}})
# Return in same order as keys
user_map = {user.id: user for user in users}
return [user_map.get(key) for key in keys]
# Use in type
@fraiseql.type
class Post:
author_id: ID
@dataloader_field(UserDataLoader, key_field="author_id")
async def author(self, info) -> User | None:
"""Load post author using DataLoader."""
pass # Implementation is auto-generated
# GraphQL query automatically batches author loads
# query {
# posts {
# title
# author { name } # Batched into single query
# }
# }
Benefits:
- Eliminates N+1 query problems
- Automatic batching of requests
- Built-in caching within single request
- Type-safe implementation
See Also: Optimization documentation
Subscription Decorators¶
@subscription¶
Purpose: Mark async generator functions as GraphQL subscriptions
Signature:
@subscription
async def subscription_name(info, ...params) -> AsyncGenerator[ReturnType, None]:
async for item in event_stream():
yield item
Parameters: None
Return Type: Must be AsyncGenerator[YieldType, None]
Examples:
from typing import AsyncGenerator
from fraiseql.types import ID
@subscription
async def on_post_created(info) -> AsyncGenerator[Post, None]:
async for post in post_event_stream():
yield post
@subscription
async def on_user_posts(
info,
user_id: ID
) -> AsyncGenerator[Post, None]:
async for post in post_event_stream():
if post.user_id == user_id:
yield post
See Also: Queries and Mutations
Authentication Decorators¶
@requires_auth¶
Purpose: Require authentication for resolver
Signature:
@requires_auth
async def resolver_name(info, ...params) -> ReturnType:
pass
Parameters: None
Examples:
import fraiseql
from fraiseql.auth import requires_auth
@fraiseql.query
@requires_auth
async def get_my_profile(info) -> User:
user = info.context["user"] # Guaranteed to be authenticated
db = info.context["db"]
return await db.find_one(
"v_user", "getMyProfile", info, mandatory_filters={"id": user.user_id}
)
@fraiseql.mutation
@requires_auth
async def update_profile(info, input: UpdateProfileInput) -> User:
user = info.context["user"]
db = info.context["db"]
await db.execute_function(
"fn_update_user", {"id": str(user.user_id), **input.to_dict()}
)
return await db.find_one(
"v_user", "updateProfile", info, mandatory_filters={"id": user.user_id}
)
Raises: GraphQLError with code "UNAUTHENTICATED" if not authenticated
@requires_permission¶
Purpose: Require specific permission for resolver
Signature:
@requires_permission(permission: str)
async def resolver_name(info, ...params) -> ReturnType:
pass
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
| permission | str | Yes | Permission string required (e.g., "users:write") |
Examples:
import fraiseql
from fraiseql.auth import requires_permission
from fraiseql.types import ID
@fraiseql.mutation
@requires_permission("users:write")
async def create_user(info, input: CreateUserInput) -> User:
db = info.context["db"]
result = await db.execute_function("fn_create_user", input.to_dict())
return await db.find_one(
"v_user", "createUser", info, mandatory_filters={"id": result["id"]}
)
@fraiseql.mutation
@requires_permission("users:delete")
async def delete_user(info, id: ID) -> bool:
db = info.context["db"]
# fn_delete_user(input jsonb, OUT deleted boolean)
result = await db.execute_function("fn_delete_user", {"id": str(id)})
return result["deleted"]
Raises:
- GraphQLError with code "UNAUTHENTICATED" if not authenticated
- GraphQLError with code "FORBIDDEN" if missing permission
@requires_role¶
Purpose: Require specific role for resolver
Signature:
@requires_role(role: str)
async def resolver_name(info, ...params) -> ReturnType:
pass
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
| role | str | Yes | Role name required (e.g., "admin") |
Examples:
import fraiseql
from fraiseql.auth import requires_role
@fraiseql.query
@requires_role("admin")
async def get_all_users(info) -> list[User]:
db = info.context["db"]
return await db.find("v_user")
@fraiseql.mutation
@requires_role("admin")
async def admin_action(info, input: AdminActionInput) -> Result:
# Admin-only mutation
pass
Raises:
- GraphQLError with code "UNAUTHENTICATED" if not authenticated
- GraphQLError with code "FORBIDDEN" if missing role
@requires_any_permission¶
Purpose: Require any of the specified permissions
Signature:
@requires_any_permission(*permissions: str)
async def resolver_name(info, ...params) -> ReturnType:
pass
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
| *permissions | str | Yes | Variable number of permission strings |
Examples:
import fraiseql
from fraiseql.auth import requires_any_permission
from fraiseql.types import ID
@fraiseql.mutation
@requires_any_permission("users:write", "admin:all")
async def update_user(info, id: ID, input: UpdateUserInput) -> User:
# Can be performed by users:write OR admin:all
db = info.context["db"]
await db.execute_function("fn_update_user", {"id": str(id), **input.to_dict()})
return await db.find_one("v_user", "updateUser", info, mandatory_filters={"id": id})
Raises:
- GraphQLError with code "UNAUTHENTICATED" if not authenticated
- GraphQLError with code "FORBIDDEN" if missing all permissions
@requires_any_role¶
Purpose: Require any of the specified roles
Signature:
@requires_any_role(*roles: str)
async def resolver_name(info, ...params) -> ReturnType:
pass
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
| *roles | str | Yes | Variable number of role names |
Examples:
import fraiseql
from fraiseql.auth import requires_any_role
from fraiseql.types import ID
@fraiseql.query
@requires_any_role("admin", "moderator")
async def moderate_content(info, id: ID) -> ModerationResult:
# Can be performed by admin OR moderator
pass
Raises:
- GraphQLError with code "UNAUTHENTICATED" if not authenticated
- GraphQLError with code "FORBIDDEN" if missing all roles
Decorator Combinations¶
Stacking decorators:
import fraiseql, connection, type
from fraiseql.auth import requires_auth, requires_permission
from fraiseql.types import Connection
from fraiseql.types import ID
# Multiple decorators - order matters
@connection(node_type=User)
@fraiseql.query
@requires_auth
@requires_permission("users:read")
async def users_connection(info, first: int | None = None) -> Connection[User]:
pass
# Field-level auth
@fraiseql.type
class User:
id: ID
name: str
@field(description="Private settings")
@requires_auth
async def settings(self, info) -> UserSettings:
# Only accessible to authenticated users
pass
Decorator Order Rules:
- Type decorators (@fraiseql.type, @input, @enum, @interface) - First
- Query/Mutation/Subscription decorators - Second
- Connection decorator - Before @fraiseql.query
- Auth decorators - After query/mutation/field decorators
- Field decorators (@field, @dataloader_field) - On methods
See Also¶
- Types and Schema - Type system details
- Queries and Mutations - Query and mutation patterns
- Configuration - Configure decorator behavior