Scalars
Scalar types represent concrete values at the leaves of a query. For example in
the following query the name
field will resolve to a scalar type (in this case
it’s a String
type):
There are several built-in scalars, and you can define custom scalars too. (Enums are also leaf values.) The built in scalars are:
-
String
, maps to Python’sstr
-
Int
, a signed 32-bit integer, maps to Python’sint
-
Float
, a signed double-precision floating-point value, maps to Python’sfloat
-
Boolean
, true or false, maps to Python’sbool
-
ID
, a specialisedString
for representing unique object identifiers -
Date
, an ISO-8601 encoded date -
DateTime
, an ISO-8601 encoded datetime -
Time
, an ISO-8601 encoded time -
Decimal
, a Decimal value serialized as a string -
UUID
, a UUID value serialized as a string -
Void
, always null, maps to Python’sNone
-
JSON
, a JSON value as specified in ECMA-404 standard, maps to Python’sdict
-
Base16
,Base32
,Base64
, represents hexadecimal strings encoded withBase16
/Base32
/Base64
. As specified in RFC4648 . Maps to Python’sstr
Fields can return built-in scalars by using the Python equivalent:
Scalar types can also be used as inputs:
Custom scalars
You can create custom scalars for your schema to represent specific types in your data model. This can be helpful to let clients know what kind of data they can expect for a particular field.
To define a custom scalar you need to give it a name and functions that tell Strawberry how to serialize and deserialise the type.
For example here is a custom scalar type to represent a Base64 string:
The Base16
, Base32
and Base64
scalar types are available in
strawberry.scalars
Example JSONScalar
Usage:
The JSON
scalar type is available in strawberry.scalars
Overriding built in scalars
To override the behaviour of the built in scalars you can pass a map of overrides to your schema.
Here is a full example of replacing the built in DateTime
scalar with one that
serializes all datetimes as unix timestamps:
Replacing datetime with the popular pendulum
library
To override with a pendulum instance you’d want to serialize and parse_value like the above example. Let’s throw them in a class this time.
In addition we’ll be using the Union
clause to combine possible input types.
Since pendulum isn’t typed yet, we’ll have to silence mypy’s errors using
# type: ignore
BigInt (64-bit integers)
Python by default allows, integer size to be 2^64. However the graphql spec has capped it to 2^32.
This will inevitably raise errors. Instead of using strings on the client as a workaround, you could use the following scalar:
You can adapt your schema to automatically use this scalar for all integers by
using the scalar_overrides
parameter
Only use this override if you expect most of your integers to be 64-bit. Since most GraphQL schemas follow standardized design patterns and most clients require additional effort to handle all numbers as strings, it makes more sense to reserve BigInt for numbers that actually exceed the 32-bit limit. You can achieve this by annotating `BigInt` instead of `int` in your resolvers handling large python integers.