Quick Start | 🍓 Strawberry GraphQL

In this Quick-Start, we will:
For a more advanced example of a similar setup including a set of mutations and more queries, please check the example app .
(Not using poetry? pip install strawberry-graphql-django works fine too.)
We’ll build an example database of fruit and their colours.
You’ll notice that for Fruit.category , we use TextChoicesField instead of TextField(choices=...) . This allows strawberry-django to automatically use an enum in the graphQL schema, instead of a string which would be the default behaviour for TextField.
See the choices-field integration for more information.
You’ll need to make migrations then migrate:
Now use the django shell, the admin, the loaddata command or whatever tool you like to load some fruits and colors. I’ve loaded a red strawberry (predictable, right?!) ready for later.
Before creating queries, you have to define a type for each model. A type is a fundamental unit of the schema which describes the shape of the data that can be queried from the GraphQL server. Types can represent scalar values (like String, Int, Boolean, Float, and ID), enums, or complex objects that consist of many fields.
A key feature of strawberry-graphql-django is that it provides helpers to create types from django models, by automatically inferring types (and even documentation!!) from the model fields.
See the fields guide for more information.
Next we want to assemble the schema from its building block types.
You’ll notice a familiar statement, fruits: list[Fruit] . We already used this statement in the previous step in types.py . Seeing it twice can be a point of confusion when you’re first getting to grips with GraphQL and Strawberry.
The purpose here is similar but subtly different. Previously, the syntax defined that it was possible to make a query that traverses within the graph, from a Color to a list of Fruits. Here, the usage defines a root query (a bit like an entrypoint into the graph).
We add the DjangoOptimizerExtension here. Don’t worry about why for now, but you’re almost certain to want it.
See the optimizer guide for more information.
Now we’re showing off. This isn’t enabled by default, since existing django applications will likely have model docstrings and help text that aren’t user-oriented. But if you’re starting clean (or overhauling existing docstrings and help text), setting up the following is super useful for your API users.
If you don’t set these true, you can always provide user-oriented descriptions. See the types guide and fields guide for more details.
This generates following schema:
Start your server with:
Then visit localhost:8000/graphql in your browser. You should see the graphql explorer being served by django. Using the interactive query tool, you can query for the fruits you added earlier:
Now that you have a basic API running, let’s explore some common real-world scenarios.
Allow clients to filter fruits by category or color:
Allow clients to create and update fruits:
Limit the number of results for better performance:
Query with pagination:
Protect your API with authentication:
Add fields that are computed rather than stored:
Query computed fields:
The DjangoOptimizerExtension automatically prevents N+1 query problems:
See the Performance Guide for more optimization strategies.
Handle validation and database errors gracefully:
Error response format:
See the Error Handling Guide for comprehensive error management.
Here’s a complete example bringing everything together:
Now that you have a working GraphQL API with common features, explore these guides to learn more:
Was this page helpful?
Thank you for your feedback! 🙏 It's been posted on our Discord server. Feel free to join and follow up on the conversation!
Something went wrong. Please try again.