Currently, querying ArangoDB with GraphQL requires building a GraphQL.js schema. This is tedious and the resulting JavaScript schema file can be long and bulky. Here we will demonstrate a short proof of concept that reduces the user related part to only defining the GraphQL IDL file and simple AQL queries.
The Apollo GraphQL project built a library that takes a GraphQL IDL and resolver functions to build a GraphQL.js schema. Resolve functions are called by GraphQL to get the actual data from the database. I modified the library in the way that before the resolvers are added, I read the IDL AST and create resolver functions.
To simplify things and to not depend on special “magic”, let’s introduce the directive @aql. With this directive, it’s possible to write an AQL query that gets the needed data. With the bind parameter @current it is possible to access the current parent object to do JOINs or related operations.
Interested in trying out ArangoDB? Fire up your database in just a few clicks with ArangoDB Oasis: the Cloud Service for ArangoDB. Start your free 14-day trial here.
A GraphQL IDL
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
type BlogEntry { _key: String! authorKey: String! author: Author @aql(exec: "FOR author IN Author FILTER author._key == @current.authorKey RETURN author") } type Author { _key: String! name: String } type Query { blogEntry(_key: String!): BlogEntry } |
This IDL describes a BlogEntry and an Author object. The BlogEntry holds an Author object which is fetched via the AQL query in the directive @aql. The type Query defines a query that fetches one BlogEntry.
Now let’s have a look at a GraphQL query:
|
1 2 3 4 5 6 7 8 9 |
{ blogEntry(_key: "1") { _key authorKey author { name } } } |
This query fetches the BlogEntry with _key “1”. The generated AQL query is:
|
1 |
FOR doc IN BlogEntry FILTER doc._key == '1' RETURN doc |
And with the fetched BlogEntry document the corresponding Author is fetched via the AQL query defined in the directive.
The result will approximately look like this:
|
1 2 3 4 5 6 7 8 9 10 11 |
{ "data" : { "blogEntry" : { "_key" : "1", "authorKey" : "2", "author" : { "name" : "Author Name" } } } } |
As a conclusion of this short demo, we can claim that with the usage of GraphQLs IDL, it is possible to reduce effort on the users’ side to query ArangoDB with GraphQL. For simple GraphQL queries and IDLs it’s possible to automatically generate resolvers to fetch the necessary data.
The effort resulted in an npm package is called graphql-aql-generator.
ArangoDB Foxx example
Now let’s have a look at the same example, but with using ArangoDB javascript framework – Foxx. To do so, we have to follow the simple steps listed below:
- Open the ArangoDB web interface and navigate to
SERVICES. - Then click
Add Service. SelectNew Serviceand fill out all fields with*.
Important is theMountfield. I will use/test. Then Generate. - Click on the service to open its settings. Click
Settingsand then go toSet Developmentto enable the development mode. - Then click
Infoand open the path atPath:.
Now we have to install the npm package:
|
1 |
npm install --save graphql-aql-generator |
We also need the collections Author and BlogEntry. And the following documents:
Authorcollection:
|
1 2 3 4 |
{ "_key":"2" "name": "Author Name" } |
BlogEntrycollection:
|
1 2 3 4 |
{ "_key":"1" "authorKey": "2" } |
Foxx has a built-in graphql router that we can use to serve GraphQL queries. We assemble a new route called /graphql that serves the incoming GraphQL queries. With graphiql: true we enable the GraphiQL explorer so we can test-drive our queries.
|
1 2 3 4 5 6 7 8 9 10 11 12 |
const createGraphQLRouter = require('@arangodb/foxx/graphql'); const generator = require('graphql-aql-generator'); const typeDefs = [`...`] const schema = generator(typeDefs); router.use('/graphql', createGraphQLRouter({ schema: schema, graphiql: true, graphql: require('graphql-sync') })); |
Open 127.0.0.1:8529/test/graphql and the GraphiQL explorer is loaded so we can execute a query to fetch a BlogEntry with an Author.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 |
{ blogEntry(_key: "1") { _key authorKey author { name } } } ``` The result is: ``` { "data": { "blogEntry": { "_key": "1", "authorKey": "2", "author": { "name": "Author Name" } } } } |
For the sake of completeness, here is the full Foxx example that works by copy & paste. Do not forget to
npm install graphql-aql-generator and create the collections and documents.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 |
// main.js code 'use strict'; const createRouter = require('@arangodb/foxx/router'); const router = createRouter(); module.context.use(router); const createGraphQLRouter = require('@arangodb/foxx/graphql'); const generator = require('graphql-aql-generator'); const typeDefs = [` type BlogEntry { _key: String! authorKey: String! author: Author @aql(exec: "FOR author in Author filter author._key == @current.authorKey return author") } type Author { _key: String! name: String } type Query { blogEntry(_key: String!): BlogEntry } `] const schema = generator(typeDefs); router.use('/graphql', createGraphQLRouter({ schema: schema, graphiql: true, graphql: require('graphql-sync') })); |
Would be great to hear your thoughts, feedback, questions, and comments in our Slack Community channel or via a contact us form.
5 Comments
It seems very powerful. Does it create a single query to fetch data?
This is awesome 🙂
Is it possible to support “Subscription” of GraphQL with Foxx?
will this work for Mutation?
Hi! Thanks for the response, if you want to check out this following post it is more up to date and can help answer your question https://www.arangodb.com/docs/stable/foxx-reference-modules-graph-ql.html.