Skip to content

🔷 Generate from GraphQL

Generate Pydantic models from GraphQL schema definitions.

🚀 Quick Start

datamodel-codegen \
    --input schema.graphql \
    --input-file-type graphql \
    --output-model-type pydantic_v2.BaseModel \
    --output model.py

Why --output-model-type?

Starting from version 0.53.0, explicitly specifying --output-model-type is recommended. See Omitting --output-model-type is deprecated for details.

📦 Installation

GraphQL support requires the graphql extra: 

pip install 'datamodel-code-generator[graphql]'

📝 Simple Example

Let's consider a simple GraphQL schema (more details in GraphQL Schemas and Types).

schema.graphql 

type Book {
  id: ID!
  title: String
  author: Author
}

type Author {
  id: ID!
  name: String
  books: [Book]
}

input BooksInput {
    ids: [ID!]!
}

input AuthorBooksInput {
    id: ID!
}

type Query {
  getBooks(input: BooksInput): [Book]
  getAuthorBooks(input: AuthorBooksInput): [Book]
}

✨ Generated model.py 

# generated by datamodel-codegen:
#   filename:  schema.graphql
#   timestamp: 2023-11-20T17:04:42+00:00

from __future__ import annotations

from typing import TypeAlias

from pydantic import BaseModel, Field
from typing_extensions import Literal

# The `Boolean` scalar type represents `true` or `false`.
Boolean: TypeAlias = bool


# The `ID` scalar type represents a unique identifier, often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as `"4"`) or integer (such as `4`) input value will be accepted as an ID.
ID: TypeAlias = str


# The `String` scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.
String: TypeAlias = str


class Author(BaseModel):
    books: list[Book | None] | None = Field(default_factory=list)
    id: ID
    name: String | None = None
    typename__: Literal['Author'] | None = Field('Author', alias='__typename')


class Book(BaseModel):
    author: Author | None = None
    id: ID
    title: String | None = None
    typename__: Literal['Book'] | None = Field('Book', alias='__typename')


class AuthorBooksInput(BaseModel):
    id: ID
    typename__: Literal['AuthorBooksInput'] | None = Field(
        'AuthorBooksInput', alias='__typename'
    )


class BooksInput(BaseModel):
    ids: list[ID]
    typename__: Literal['BooksInput'] | None = Field(
        'BooksInput', alias='__typename'
    )

📤 Response Deserialization

For the following response of getAuthorBooks GraphQL query:

response.json 

{
  "getAuthorBooks": [
    {
      "author": {
        "id": "51341cdscwef14r13",
        "name": "J. K. Rowling"
      },
      "id": "1321dfvrt211wdw",
      "title": "Harry Potter and the Prisoner of Azkaban"
    },
    {
      "author": {
        "id": "51341cdscwef14r13",
        "name": "J. K. Rowling"
      },
      "id": "dvsmu12e19xmqacqw9",
      "title": "Fantastic Beasts: The Crimes of Grindelwald"
    }
  ]
}

main.py 

from model import Book

response = {...}

books = [
    Book.parse_obj(book_raw) for book_raw in response["getAuthorBooks"]
]
print(books)
# [Book(author=Author(books=[], id='51341cdscwef14r13', name='J. K. Rowling', typename__='Author'), id='1321dfvrt211wdw', title='Harry Potter and the Prisoner of Azkaban', typename__='Book'), Book(author=Author(books=[], id='51341cdscwef14r13', name='J. K. Rowling', typename__='Author'), id='dvsmu12e19xmqacqw9', title='Fantastic Beasts: The Crimes of Grindelwald', typename__='Book')]

🎨 Custom Scalar Types

datamodel-codegen \
    --input schema.graphql \
    --input-file-type graphql \
    --output-model-type pydantic_v2.BaseModel \
    --extra-template-data data.json \
    --output model.py

schema.graphql 

scalar Long

type A {
  id: ID!
  duration: Long!
}

data.json 

{
  "Long": {
    "py_type": "int"
  }
}

✨ Generated model.py 

# generated by datamodel-codegen:
#   filename:  custom-scalar-types.graphql
#   timestamp: 2019-07-26T00:00:00+00:00

from __future__ import annotations

from typing import Optional, TypeAlias

from pydantic import BaseModel, Field
from typing_extensions import Literal

# The `Boolean` scalar type represents `true` or `false`.
Boolean: TypeAlias = bool


# The `ID` scalar type represents a unique identifier, often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as `"4"`) or integer (such as `4`) input value will be accepted as an ID.
ID: TypeAlias = str


Long: TypeAlias = int


# The `String` scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.
String: TypeAlias = str


class A(BaseModel):
    duration: Long
    id: ID
    typename__: Optional[Literal['A']] = Field('A', alias='__typename')

🚫 Excluding __typename Field

When using generated models for GraphQL mutations, the __typename field may cause issues as GraphQL servers typically don't expect this field in input data.

Use the --graphql-no-typename option to exclude this field:

datamodel-codegen \
    --input schema.graphql \
    --input-file-type graphql \
    --output-model-type pydantic_v2.BaseModel \
    --graphql-no-typename \
    --output model.py

Before (default): 

class Book(BaseModel):
    id: ID
    title: String | None = None
    typename__: Literal['Book'] | None = Field('Book', alias='__typename')

After (with --graphql-no-typename): 

class Book(BaseModel):
    id: ID
    title: String | None = None

Union Type Discrimination

If your schema uses GraphQL union types and you rely on __typename for type discrimination during deserialization, excluding this field may break that functionality. Consider using this option only for input types or schemas without unions.

📖 See Also