Admin - Graphql

Documentation
1

The admin API and how to run Dgraph with GraphQL.

Running

The simplest way to start with Dgraph GraphQL is to run the all-in-one Docker image.

docker run -it -p 8080:8080 dgraph/standalone:master

That brings up GraphQL at localhost:8080/graphql and localhost:8080/admin, but is intended for quickstart and doesn’t persist data.

Advanced Options

Once you’ve tried out Dgraph GraphQL, you’ll need to move past the dgraph/standalone and run and deploy Dgraph instances.

Dgraph is a distributed graph database. It can scale to huge data and shard that data across a cluster of Dgraph instances. GraphQL is built into Dgraph in its Alpha nodes. To learn how to manage and deploy a Dgraph cluster to build an App check Dgraph’s Dgraph docs, and, in particular, the deployment guide.

GraphQL schema introspection is enabled by default, but can be disabled with the --graphql_introspection=false when starting the Dgraph alpha nodes.

Dgraph’s schema

Dgraph’s GraphQL runs in Dgraph and presents a GraphQL schema where the queries and mutations are executed in the Dgraph cluster. So the GraphQL schema is backed by Dgraph’s schema.

Warning: this means if you have a Dgraph instance and change its GraphQL schema, the schema of the underlying Dgraph will also be changed!

/admin

When you start Dgraph with GraphQL, two GraphQL endpoints are served.

At /graphql you’ll find the GraphQL API for the types you’ve added. That’s what your app would access and is the GraphQL entry point to Dgraph. If you need to know more about this, see the quick start, example and schema docs.

At /admin you’ll find an admin API for administering your GraphQL instance. The admin API is a GraphQL API that serves POST and GET as well as compressed data, much like the /graphql endpoint.

Here are the important types, queries, and mutations from the admin schema.

type GQLSchema {
	id: ID!
	schema: String! 
	generatedSchema: String!
}
type UpdateGQLSchemaPayload {
	gqlSchema: GQLSchema
}
input UpdateGQLSchemaInput {
	set: GQLSchemaPatch!
}
input GQLSchemaPatch {
	schema: String!
}
type Query {
	getGQLSchema: GQLSchema
	health: Health
}
type Mutation {
	updateGQLSchema(input: UpdateGQLSchemaInput!) : UpdateGQLSchemaPayload
}

You’ll notice that the /admin schema is very much the same as the schemas generated by Dgraph GraphQL.

  • The health query lets you know if everything is connected and if there’s a schema currently being served at /graphql.
  • The getGQLSchema query gets the current GraphQL schema served at /graphql, or returns null if there’s no such schema.
  • The updateGQLSchema mutation allows you to change the schema currently served at /graphql.

First Start

On first starting with a blank database:

  • There’s no schema served at /graphql.
  • Querying the /admin endpoint for getGQLSchema returns "getGQLSchema": null.
  • Querying the /admin endpoint for health lets you know that no schema has been added.

Adding Schema

Given a blank database, running the /admin mutation:

mutation {
  updateGQLSchema(
    input: { set: { schema: "type Person { name: String }"}})
  {
    gqlSchema {
      schema
      generatedSchema
    }
  }
}

would cause the following.

  • The /graphql endpoint would refresh and now serves the GraphQL schema generated from type type Person { name: String }: that’s Dgraph type Person and predicate Person.name: string .; see here for how to customize the generated schema.
  • The schema of the underlying Dgraph instance would be altered to allow for the new Person type and name predicate.
  • The /admin endpoint for health would return that a schema is being served.
  • The mutation returns "schema": "type Person { name: String }" and the generated GraphQL schema for generatedSchema (this is the schema served at /graphql).
  • Querying the /admin endpoint for getGQLSchema would return the new schema.

Migrating Schema

Given an instance serving the schema from the previous section, running an updateGQLSchema mutation with the following input

type Person {
    name: String @search(by: [regexp])
    dob: DateTime
}

changes the GraphQL definition of Person and results in the following.

  • The /graphql endpoint would refresh and now serves the GraphQL schema generated from the new type.
  • The schema of the underlying Dgraph instance would be altered to allow for dob (predicate Person.dob: datetime . is added, and Person.name becomes Person.name: string @index(regexp).) and indexes are rebuilt to allow the regexp search.
  • The health is unchanged.
  • Querying the /admin endpoint for getGQLSchema now returns the updated schema.

Removing from Schema

Adding a schema through GraphQL doesn’t remove existing data (it would remove indexes). For example, starting from the schema in the previous section and running updateGQLSchema with the initial type Person { name: String } would have the following effects.

  • The /graphql endpoint would refresh to serve the schema built from this type.
  • Thus field dob would no longer be accessible and there’d be no search available on name.
  • The search index on name in Dgraph would be removed.
  • The predicate dob in Dgraph is left untouched - the predicate remains and no data is deleted.
This is a companion discussion topic for the original entry at https://dgraph.io/docs/graphql/admin/