GraphQL

EdgeDB includes built-in support for GraphQL. Once you activate the extension, your instance will expose a /graphql endpoint that can process queries and mutations via HTTP.

All queries on this page assume the following schema. If you aren't familiar with how to model schemas in EdgeDB, check out the Data Modeling showcase.

Copy

abstract type Person {
  required property name;
}

type Hero extending Person {
  secret_identity: str;
  number_of_movies: int64;
  multi friends: Hero; # many-to-many
}

type Villain extending Person {
  nemesis: Hero;
}

Workflow

To activate the GraphQL extension on your instance, add the following line somewhere in your schema file:

Copy

using extension graphql;

Then create and apply a migration to activate the extension.

Copy

edgedb migration create

Did you create extension 'graphql'? [y,n,l,c,b,s,q,?]
>y
Created ./dbschema/migrations/000XX.edgeql, id: m13mnixu...

Copy

edgedb migrate

Applied m13mnixu... (000XX.edgeql)

Your EdgeDB instance is now a fully operational GraphQL server!

Your schema can process GraphQL queries via HTTP at http://localhost:<port>/db/<database-name>/graphql. For full details on the GraphQL-over-HTTP protocol, read the GraphQL docs.
An interactive GraphiQL terminal is available at http://localhost:<port>/db/<database-name>/graphql/explore.

To find your instance's port number, run edgedb server status. The database name is normally "edgedb" (the default database created in all instances) but could be the name of another database you've created in your instance.

Querying

Every object type, abstract type, and expression alias is reflected as a query and three mutations: insert, update, and delete mutations. Filter by any property (including computed properties), deeply fetch any link, and write advanced queries with scalar-specific operators like like/ilike, gt/lt/gte/lte/nte, or exists. To compare these GraphQL queries side-by-side with their EdgeQL equivalents, check out the comparison page.

Simple query

Nested query

Basic filter

Nested filters

Advanced filtering

Ordering

Pagination

Copy

query getHeroes {
  Hero {
    id
    name
    secret_identity
  }
}

{
  "data": {
    "Hero": [
      {
        "id": "8a55cc24...",
        "name": "Iron Man",
        "secret_identity": "Tony Stark"
      },
      {
        "id": "82eefef6...",
        "name": "Spider-Man",
        "secret_identity": "Peter Parker"
      },
      ...
    ]
  }
}

Mutation

Write advanced mutations containing scalar-specific operators like increment and append, create or update several objects in a single query, and safely use GraphQL variables. To compare these GraphQL queries side-by-side with their EdgeQL equivalents, check out the comparison page.

Insert

Update

Delete

Insert multiple

Nested insert

Nested connect

Disconnect

Variables

Copy

mutation {
  insert_Hero(data: {
    name: "The Falcon",
    secret_identity: "Sam Wilson"
  }) {
    id name secret_identity
  }
}

{
  "data": {
    "insert_Hero": [
      {
        "id": "ed1ad7ca...",
        "name": "The Falcon",
        "secret_identity": "Sam Wilson"
      }
    ]
  }
}

Keep exploring

5-min Quickstart

Interactive EdgeQL Tutorial