Scalar Types#

Fields with scalar types are leaf nodes in the graph, as opposed to objects that provide more fields. GraphQL defines five default scalar types, and Magql provides a few more useful types. It’s also possible to define your own types.

Scalar types manage converting input data from JSON to Python, and output data from Python to JSON. Executing a GraphQL operation validates the data against the types before calling the resolvers.

GraphQL Built-In Scalars#

The following types are defined by the GraphQL spec. Magql provides wrappers around the types from GraphQL-Core, so that they can be referenced in Magql. It also patches the converters to work with string data from HTML forms.

  • String

  • Int accepts values as strings.

  • Float accepts values as strings.

  • Boolean accepts the strings 1, true, on, 0 false, and off.

  • ID converts ints and floats to strings.

Magql Built-In Scalars#

Magql provides the following additional types:

Custom Scalars#

If you have a data type that is not natively representable in JSON, you can write a custom scalar that can convert Python data to and from JSON data.

For example, there is no JSON equivalent to a Python Decimal. Instead, we can represent it as a JSON string.

import decimal
import magql

Decimal = magql.Scalar(
    description="An arbitrary-precision decimal number given as a string.",
schema = magql.Schema(types=[Decimal])

@schema.query.field("add", Decimal, args={"a": "Decimal", "b": "Decimal"})
def resolve_add(parent, info, **kwargs):
    a = kwargs.pop("a")
    b = kwargs.pop("b")
    return a + b
>>> schema.execute("""query { add("1.1", "2.2") }""").data
{'add': '3.3'}

Remember, this only defines the scalar on the server. It’s important to fill in description and specified_by for custom scalars. This information will be present in the schema document and introspection, and serves as documentation for others to know how to implement the type.