Playground Project¶

The repository ships a small, fully runnable Django project at examples/playground/ that exercises every major django-graphex feature end-to-end: queries with all three paginators, filtering (including a custom @filter_field), N+1-safe nested lists, the full query-optimization surface, a typed GenericForeignKey union, directives, CRUD mutations with permissions, descriptor-API hand-written mutations, base64 file uploads, query depth/cost limits, and native subscriptions over WebSocket and SSE.

Quick start¶

You need uv and Python 3.12+.

git clone https://github.com/eamigo86/django-graphex.git
cd django-graphex/examples/playground

make install     # uv sync — installs the local library (editable) + daphne
make migrate     # generate + apply migrations (SQLite)
make seed        # load demo data (see below)
make run         # daphne ASGI server (HTTP + WebSocket) on 127.0.0.1:8000

Open GraphiQL at http://127.0.0.1:8000/graphql/. The seed creates the superuser demo / demo12345.

All the Makefile targets:

What the seed creates¶

python manage.py seed (idempotent — it clears the demo tables first) loads:

• 15 authors x 12 posts each (180 posts), statuses cycling DRAFT / PUBLISHED / ARCHIVED, each post in one of the categories Tech / Life / News and tagged with one of django / graphql / python
• 3 comments per post (540 comments)
• 12 private notes owned by the demo user
• 2 accounts + 2 invoices + 4 attachments — the attachments alternate between Account and Invoice targets so the typed GenericForeignKey union query returns both member types
• The superuser demo / demo12345 (also linked to the first author)

The counts are deliberate: 12 posts per author is more than the page size of 10, so nested posts lists span real multiple pages and the DB-side window-pagination path (ROW_NUMBER() OVER (PARTITION BY ...)) is genuinely exercised — try results(offset: 10) on a nested list. Scale the dataset without editing code:

uv run python manage.py seed --authors 25 --posts 15   # explicit counts
uv run python manage.py seed --scale 2                 # doubles authors + posts

Endpoints¶

Authenticating (private fields)¶

Auth is Django session-based. Private fields (me, myNotes, the note mutations, noteSubscription) require a logged-in user:

1. Open http://127.0.0.1:8000/admin/ and log in as demo / demo12345.
2. Return to GraphiQL — it shares the session cookie.

Log out of /admin to test the anonymous (public) behaviour again.

Schema tour¶

Everything lives in blog/schema.py (with settings in config/settings.py). What each part demonstrates:

Starter queries¶

Paste these into GraphiQL at /graphql/ right after make seed — they all work anonymously.

{
  posts(filter: { status: { exact: PUBLISHED } }) {
    totalCount
    results(limit: 5, ordering: "-id") {
      id
      title
      status
      author { name }
      tags { totalCount results { name } }
      comments {
        totalCount
        results(first: 2) { authorName text }
        pageInfo { hasNextPage endCursor }
      }
    }
  }
  authors {
    totalCount
    results(page: 1) { name }
  }
  comments {
    totalCount
    results(first: 3) { text }
    pageInfo { hasNextPage endCursor }
  }
}

{
  posts(filter: { search: "author 3" }) {
    totalCount
    results(limit: 5) { id title }
  }
  authors {
    results(page: 1) {
      name
      postCount
      posts(filter: { title: { icontains: "Post 1" } }) {
        totalCount
        results(limit: 3, ordering: "-id") {
          title
          status
          category { name }
        }
      }
    }
  }
}

{
  attachments {
    totalCount
    results {
      caption
      target {
        __typename
        ... on AccountType { label balance }
        ... on InvoiceType { number amount }
      }
    }
  }
}

{
  posts {
    results(limit: 3) {
      title @uppercase
      slug: title @slugify
      teaser: body @truncate(length: 40)
    }
  }
}

Try subscriptions live¶

The playground serves the v2 native subscription engine behind both standards-based transports: graphql-transport-ws on /ws/graphql/ and SSE (graphql-sse / text/event-stream) on /graphql/stream. The easiest way to watch them work is the built-in browser client:

1. Open http://127.0.0.1:8000/graphql/client/. WS mode is pre-selected and already points at /ws/graphql/; press Connect.

2. Enter a subscription and press the run (▶) button:

   subscription {
     postSubscription(action: ALL_ACTIONS) {
       id
       title
       status
     }
   }
   

3. Trigger a change from GraphiQL in another tab (any existing author id works — grab one with { authors { results(page: 1) { id name } } }):

   mutation {
     postCreate(newPost: { title: "Live update", author: 1 }) {
       ok
       post { id title }
     }
   }
   

   The client streams the next event with the new post instantly. Both playground subscriptions set payload_mode = "full", so the whole serialized instance is deliverable — not just the id.

To try the SSE transport instead, switch the client's toggle to SSE and set the SSE endpoint to http://127.0.0.1:8000/graphql/stream (the playground mounts the SSE view on that route) before connecting.

More things to try:

• Per-subscriber filters — subscribe with commentSubscription(action: ALL_ACTIONS, filters: { post: 1 }) { id text } and only that post's comments are delivered.
• Private subscription — log in at /admin/ first, then subscribe to noteSubscription(action: ALL_ACTIONS) { id title } from the same browser session. It is gated by AuthenticatedFieldsMiddleware, and subscription_scope server-forces "only my notes" — another user's note changes never reach you.

Run the test suite¶

The playground ships genuine end-to-end tests that drive the same consumer, SSE view and schema the server runs — a WS round-trip (subscribe → ORM Post.objects.create() → next frame received) and the equivalent SSE round-trip, plus schema/permission and client smoke tests:

make test

Where to go next¶

• Sample Application — the illustrative tutorial companion
• Query Recipes and Mutation Recipes
• Subscriptions — the full transport and engine guide
• Query Optimization — what the optimizer does on every playground query