Using GraphQL with NoSQL database ArangoDB

GraphQL is a query language created by Facebook for modern web and mobile applications as an alternative to REST APIs. Following the original announcement alongside Relay, Facebook has published an official specification and reference implementation in JavaScript. Recently projects outside Facebook like Meteor have also begun to embrace GraphQL.

Users have been asking us how they can try out GraphQL with ArangoDB. While working on the 2.8 release of our NoSQL database we experimented with GraphQL and published an ArangoDB-compatible wrapper for GraphQL.js. With the general availability of ArangoDB 2.8 you can now use GraphQL in ArangoDB using Foxx services (JavaScript in the database).

A GraphQL primer

GraphQL is a query language that bears some superficial similarities with JSON. Generally GraphQL APIs consist of three parts:

The GraphQL schema is implemented on the server using a library like graphql-sync and defines the types supported by the API, the names of fields that can be queried and the types of queries that can be made. Additionally it defines how the fields are resolved to values using a backend (which can be anything from a simple function call, a remote web service or accessing a database collection).

The client sends queries to the GraphQL API using the GraphQL query language. For web applications and JavaScript mobile apps you can use either GraphQL.js or graphql-sync to make it easier to generate these queries by escaping parameters.

The server exposes the GraphQL API (e.g. using an HTTP endpoint) and passes the schema and query to the GraphQL implementation, which validates and executes the query, later returning the output as JSON.

GraphQL vs REST

Whereas in REST APIs each endpoint represents a single resource or collection of resources, GraphQL is agnostic of the underlying protocols. When used via HTTP it only needs a single endpoint that handles all queries.

The API developer still needs to decide what information should be exposed to the client or what access controls should apply to the data but instead of implementing them at each API endpoint, GraphQL allows centralising them in the GraphQL schema. Instead of querying multiple endpoints, the client can pick and choose from the schema when defining the query and filter the response to only contain the fields it actually needs.

For example, the following GraphQL query:

could return a response like this:

whereas in a traditional REST API accessing the names of the friends would likely require additional API calls and filtering the responses to certain fields would either require proprietary extensions or additional endpoints.

GraphQL Demo Service

If you are running ArangoDB 2.8 you can install the Foxx service demo-graphql from the Store. The service provides a single HTTP POST endpoint /graphql that accepts well-formed GraphQL queries against the Star Wars data set used by GraphQL.js. (more…)

Posted in API, Foxx | Tagged , , | 11 Comments

ArangoDB 2.8: API Changes

There are a few API changes coming in the next 2.8 release. Please have a look if you contribute to a language driver or client-side query builder for ArangoDB.

AQL keywords added

The following AQL keywords were added in ArangoDB 2.8:

  • ANY
  • ALL
  • NONE

Usage of these keywords for collection names, variable names or attribute names in AQL queries will not be possible without quoting. For example, the following AQL query will still work as it uses a quoted collection name and a quoted attribute name:

This may be relevant for client-side query builders.

Deadlock handling / New error code 29

Client applications should be prepared to handle error 29 (deadlock detected) that ArangoDB may now throw when it detects a deadlock across multiple transactions. When a client application receives error 29, it should retry the operation that failed.

The error can only occur for AQL queries or user transactions that involve more than a single collection. (more…)

Posted in API, Drivers, Releases | Leave a comment

Using Bind Parameters in the AQL Editor

The AQL editor in the web interface is useful for running ad hoc AQL queries and trying things out. It provides a feature to explain the query and inspect its execution plan. This can be used to check if the query uses indexes, and which.

So far the AQL editor only supported using query string literals, but it lacked support for bind parameters. Queries issued by application code however often will use bind parameters for security reasons. Often enough this prevented copying & pasting queries from the application code into the AQL editor and vice versa without making manual adjustments.

This has been fixed in the upcoming ArangoDB version 2.8 (currently in development). Bind parameters can now be used in the AQL editor as well. Bind parameters can be entered as JSON values, the same format that is used for bind parameters in the HTTP REST API and in (JavaScript) application code.

The queries can also be saved in the AQL editor along with their bind parameter values for later reuse.

Screenshot from the feature in 2.8:


Posted in API, General | Leave a comment

Running V8 isolates in a multi-threaded ArangoDB database

ArangoDB allows running user-defined JavaScript code in the database. This can be used for more complex, stored procedures-like database operations. Additionally, ArangoDB’s Foxx framework can be used to make any database functionality available via an HTTP REST API. It’s easy to build data-centric microservices with it, using the scripting functionality for tasks like access control, data validation, sanitation etc.

We often get asked how the scripting functionality is implemented under the hood. Additionally, several people have asked how ArangoDB’s JavaScript functionality relates to node.js.

This post tries to explain that in detail.


Posted in API, Architecture, C++, Documentation, nodejs | Leave a comment

ArangoDB 2.6 – API changes, additions and changed behavior

ArangoDB 2.6 comes with new and changed APIs as well as changed behavior regarding document keys and several graph functions.

If you use Travis-CI for your tests you can download the Travis-CI ArangoDB build here: Travis-CI/ArangoDB-2.6.0-alpha2.tar.gz

The changes so far:

APIs added

  • added batch document removal and lookup APIs:

    These APIs can be used to perform multi-document lookup and removal operations efficiently. The arguments to these APIs are the name of the collection plus the array of document keys to fetch or remove.

    The endpoints for these APIs are as follows:

    Example call to fetch documents:

    The documents will be returned in an attribute documents of the HTTP response. documents is an array containing all documents found. Only those documents that were actually found will be returned. Documents that were searched but do not exist will not be returned and do not trigger any errors. (more…)

Posted in API, Documentation, Releases | Leave a comment

LoopBack Connector for ArangoDB

ArangoDB can be used as a backend data source for APIs that you compose with the popular open-source LoopBack Node.js framework.


In a recent blog article on StrongLoop, Nicholas Duffy explains how to use his new loopback-connector-arango connector to access ArangoDB:

Getting Started with the Node.js LoopBack Connector for ArangoDB

The tutorial uses the loopback-connector-arango which is available as npm and a demo application which is available from Github. (more…)

Posted in API, Community, nodejs | Leave a comment

Bulk Document Lookups

ArangoDB 2.6 comes with a specialized API for bulk document lookups. The new API allows fetching multiple documents from the server using a single request, making bulk document retrieval more efficient than when using one request per document to fetch.

Provided the documents keys are known, all the client application needs to do is to call the collection’s lookupByKeys method:

Additionally, the server-side REST API method for bulk document lookups can be invoked directly via HTTP as follows:

Jan compared the functionality with single document requests in his latest blog post.

Posted in API | 3 Comments

Fulltext Index Enhancements

This post is about improvements for the fulltext index in ArangoDB 2.6. The improvements address the problem that non-string attributes were ignored when fulltext-indexing.

Effectively this prevented string values inside arrays or objects from being indexed. Though this behavior was documented, it was limited the usefulness of the fulltext index much. Several users requested the fulltext index to be able to index arrays and object attributes, too.

Finally this has been accomplished, so the fulltext index in 2.6 supports indexing arrays and objects!

Read on in Jan’s blog post about Fulltext Index Enhancements.

Posted in API, Architecture | Leave a comment

Exporting Data for Offline Processing (in PHP)

A few weeks ago I wrote about ArangoDB’s specialized export API.

The export API is useful when the goal is to extract all documents from a given collection and to process them outside of ArangoDB.

The export API can provide quick and memory-efficient snapshots of the data in the underlying collection, making it suitable for extract all documents of the collection. It will be able to provide data much faster than with an AQL query that will extract all documents.

In this post I’ll show how to use the export API to extract data and process it with PHP.

Please read the full blog post Exporting Data for Offline Processing.

Posted in API | Leave a comment

Creating Multi-Game Highscore Lists

I just came across a question about how to create highscore lists or leaderboards in ArangoDB, and how they would work when compared to Redis sorted sets.

This blog post tries to give an answer on the topic and also detailed instructions and queries for setting up highscore lists with ArangoDB. The additional section “Extensions” explains slightly more advanced highscore list use cases like multi-game highscore lists, joining data and maintaining a “last updated” date.

Posted in API, Documentation, Query Language | 3 Comments