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"
      }
    ]
  }
}