Ariadne · Python GraphQL Schema-first

Schema-first Server

Ariadne Server gives you ability to describe your GraphQL API using Schema Definition Language and connect your business logic using a minimal amount of Python boilerplate.

Type-safe Client

Ariadne Codegen is a generator that turns your GraphQL schema and operations into a fully typed Python client, including Pydantic models.

Open Design

Easily add new features to the library, and replace or extend existing ones. Integrate with any web framework you like.

GraphQL Server

Define schema using SDL

Enable frontend and backend teams to cooperate effectively. Ariadne taps into the leading approach in the GraphQL community and opens up hundreds of developer tools, examples, and learning resources.

Ariadne provides out of the box utilities for loading schema from GraphQL files or Python strings.

from ariadne import gql, load_schema_from_path

# load schema from file...
schema = load_schema_from_path("schema.graphql")

# ...directory containing graphql files...
schema = load_schema_from_path("schema")

# ...or inside Python files
schema = gql("""
  type Query {
    user: User
  }

  type User {
    id: ID
    username: String!
  }
""")

Add business logic to schema with minimal boilerplate

Use specialized objects that connect business logic to the schema. Replace whatever you like and roll out your own implementations to fit your team's needs.

from ariadne import QueryType

from .models import Category, Promotion

query = QueryType()

@query.field("categories")
async def resolve_categories(*_):
    return await Category.query.where(Category.depth == 0)


@query.field("promotions")
async def resolve_promotions(*_):
    return await Promotion.query.all()

Fully asynchronous

Use asynchronous query execution and ASGI to speed up your API with minimal effort.

If your stack is not yet ready for async, don't worry - synchronous query execution is also available.

from ariadne import QueryType

from .models import Category, Promotion

query = QueryType()

@query.field("categories")
async def resolve_categories(*_):
    return await Category.query.where(Category.depth == 0)


@query.field("promotions")
async def resolve_promotions(*_):
    return await Promotion.query.all()

Serve your API however you want

Ariadne provides WSGI and ASGI apps enabling easy implementation of custom GraphQL services, and full interoperability with popular web frameworks.

Even if your technology has no resources for adding GraphQL to your stack, use the simple guide to create new integrations with Ariadne.

# As standalone ASGI or WSGI app...
from ariadne.asgi import GraphQL

from .schema import schema

app = GraphQL(schema, debug=True)

# ...or add GraphQL API to your favorite web framework
from ariadne.contrib.django.views import GraphQLView
from django.urls import include, path

from .schema import schema

urlpatterns = [
    ...
    path('graphql/', GraphQLView.as_view(schema=schema), name='graphql'),
]

GraphQL Client

Generate Pydantic models from schema

Ariadne Codegen creates strongly typed client methods for each operation you define.

Each function returns data validated against Pydantic models generated from your fragments and schema, ensuring correctness at runtime and full autocomplete in your editor.

Query defines a User type by fragment
fragment User on User {
  id
  firstName
  lastName
}

query GetUser($id: ID!) {
  user(id: $id) {
    ...User
  }
}

# Ariadne Codegen generates a Pydantic model:
from graphql_client.fragments import User

# Result of query is parsed into a model
user = User(id="1", first_name="John", last_name="Snow")

print(user.first_name)  # "John"
print(user.last_name)   # "Snow"

print(user.model_dump()) # {'id': '1', 'first_name': 'John', 'last_name': 'Snow'}

Typed client functions with validation

Ariadne Codegen creates strongly typed client methods for each operation you define.

Each function returns data validated against Pydantic models generated from your fragments and schema, ensuring correctness at runtime and full autocomplete in your editor.

query GetUser($id: ID!) {
  user(id: $id) {
    id
    firstName
    lastName
  }
}

After running ariadne-codegen, the client has a get_user() method
from graphql_client import Client

client = Client(url="https://example.com/graphql")
result = await client.get_user(id="1")
user = result.user  # fully typed Pydantic model

print(user.first_name)  # "John"
print(user.last_name)   # "Snow"

print(user.model_dump()) # {'id': '1', 'first_name': 'John', 'last_name': 'Snow'}

Build custom operations programmatically

With the custom operation builder, Ariadne Codegen generates helpers for queries, fields, and fragments.

This lets you construct complex GraphQL operations in Python with chaining, aliases, and inline fragments, while still getting type-safe responses validated against Pydantic models.

from graphql_client import Client
from graphql_client.custom_fields import (
    ProductFields,
)
from graphql_client.custom_queries import Query


async def get_products():
    # Create a client instance with the specified URL and headers
    client = Client(
        url="https://example.com/graphql",
    )

    # Build the queries programmatically
    product_query = Query.product(id="1").fields(
        ProductFields.id,
        ProductFields.name,
    )

    # Execute both queries with a custom operation name
    response = await client.query(
        product_query,
        operation_name="get_products",
    )