Space Cloud finally supports GraphQL! Things like cross-database joins are now possible with Space Cloud.

Before we dive into GraphQL, let’s step back a bit to see what Space Cloud is.

What is Space Cloud?

To keep things simple,

Space Cloud is an open-source web server which provides instant realtime APIs on the database of your choice.

It means that you can consume the CRUD functionality of any database via the API it provides.

What’s cool is that the API remains the same irrespective of the database. You can have multiple types of databases, eg. Mongo and MySQL in a single project and access them in the same manner.

Another exciting feature is that all the APIs are realtime. You can optionally subscribe to changes in the database. This is exceptionally helpful while making realtime apps.

Since Space Cloud has a robust security module built into it, you can consume these APIs directly from the frontend. So in most use cases, just making an Angular or React app using the Space Cloud APIs should be the only code you write.

In essence, it’s a Firebase equivalent, but is open-source and works with any database.

Cool, that’s enough of history and features. Let’s talk about what we are planning to cover in this guide.

Starting with GraphQL and Space Cloud

It’s needless to say that GraphQL is yet another format to consume the features offered by Space Cloud. GraphQL is particularly exciting for us. The graph-like nature of GraphQL helps query multiple entities in a single request. This helps reduce network roundtrips and dramatically improves user experience.

Another new feature we are introducing with GraphQL is cross-database joins. This is essentially making relationships with entities present in different databases. See it as joining the users table ( present in MySQL ) to activities of that user ( present in MongoDB ).

I’ll be using MongoDB as my database. Feel free to use any supported database which you might like.

In this guide we’ll be covering the following topics to using GraphQL with Space Cloud:

  • Inserting data
  • Querying data with filters
  • Updating data
  • Performing joins

As you might have noticed, this guide doesn’t cover all the functionality which Space Cloud offers via its GraphQL API. A better resource to understand Space Cloud capabilities would be the official docs.

Start and Configure Space Cloud

The easiest way to run Space Cloud is by using docker-compose.

Step 1: Get the docker-compose file

The spaceuptech/space-cloud/install-manifests repo contains all installation manifests required to deploy Space Cloud anywhere. Get the docker-compose file from there:

wget https://raw.githubusercontent.com/spaceuptech/space-cloud/master/install-manifests/quick-start/docker-compose/mongo/docker-compose.yaml

Step 2: Run Space Cloud & MongoDB

docker-compose up -d

Check if the containers are running:

docker ps

Step 3: Configure Space Cloud

If you exec into docker container of Space Cloud, you can see a config.yaml file and a raft-store folder generated in the home directory.

Space Cloud needs this config file to function. The config file is used to load information like the database to be used, its connection string, security rules, etc.

Space Cloud has it’s own Mission Control (admin UI) to configure all of this quickly.

Note: All changes to the config of space-cloud should be done through the Mission Control only. Changes made manually to the config file get overwritten.


Open Mission Control

Head over to http://localhost:4122/mission-control to open Mission Control.

Note: Replace localhost with the address of your Space Cloud if you are not running it locally.

Creating a project

Click on Create a Project button.

Give a name to your project. MongoDB is selected as your database by default. Keep it as it is for this guide.

Hit Next to create the project.

Configuring the database module

Head over to the Database section.

Copy paste mongodb://mongo:27017 in the connection string input.

Hit the Save button. That’s all that is required to configure Space Cloud for this guide!

Run our queries on Space Cloud

Fortunately, Mission Control has an embedded GraphiQL IDE to which lets us fire queries without having to build a frontend.

Head over to the explorer section.

Inserting data

Let’s say we are building a blog, and we want to create authors and posts. This is nothing but insert operations on the database.

Try running the following query in the GraphiQL editor to create authors:

mutation {
 insert_authors(
   docs: [
    {_id: "1", name: "Dan"},
    {_id: "2", name: "Ryan"}
  ]
 ) @mongo {
   status
 }
}

On successful insert, you should be able to see the status as 200 which means you have successfully inserted the documents in the database.

The docs argument is nothing but the array of objects or records (in case of SQL) that you want to insert in your collection/table.

If you have noticed, we have used a @mongo directive in the above query. For PostgreSQL or MySQL, change it to @postgres or @mysql respectively. And that’s it!

Inserting posts should be a no brainer now. Just run the following quert to insert some posts:

mutation {
 insert_posts(
    docs: [
      {_id: "1", author_id: "1", title: "Introducing React Hooks", uploaded_date: "2019-05-25"},
      {_id: "2", author_id: "1", title: "React vs Vue", uploaded_date: "2019-09-15"},
      {_id: "3", author_id: "2", title: "Context API", uploaded_date: "2019-09-21"},
      {_id: "4", author_id: "2", title: "React + Redux", uploaded_date: "2019-10-01"}
    ]
 ) @mongo {
   status
 }
}

Querying data with filters

Having inserted authors and their posts, let’s try to query posts of a particular author. This is nothing but a filtering operation.

Try running the following query in the GraphiQL editor:

query {
 posts(
   where: {author_id: "1"}
 ) @mongo {
   _id
   title
 }
}

As you can see, we only got the posts that belonged to author_id 1. Check out this guide for a complete list of filtering options.

Updating data

Updates require two information - a where clause to filter the documents to be updated and at least one update operator.

Let’s say you want to update the name of a particular author. This is how you would do it:

mutation {
 update_authors(
   where: {_id: "2"},
   set: {name: "Ryan Florence"}
 ) @mongo {
   status
 }
}

You can also perform operations like incrementing, decrementing, multiplying, etc. Check out this guide for a complete list of update operations.

Performing joins

Now comes the fun part, i.e. Performing join operations directly from the frontend. Joins are used to fetch data for a type along with data for a related type.

Let’s say we want to show a list of authors along with the title of their last post. This is, in essence, a database join operation. This is how you would do it using Space Cloud:

query {
 authors @mongo {
   _id
   name
   posts(
     where: {author_id: "authors._id"}
     limit: 1
     sort: ["-uploaded_date"]
   ) @mongo {
     title
   }
 }
}

The response should look something like this:

{
  "authors": [
    {
      "_id": "1",
      "name": "Dan",
      "posts": [
        {
          "title": "Introducing React Hooks"
        }
      ]
    },
    {
      "_id": "2",
      "name": "Ryan Florence",
      "posts": [
        {
          "title": "Context API"
        }
      ]
    }
  ]
}

Note how we are matching the parent query’s result authors._id with the nested query’s field author_id to perform a join operation. Read more about joins here.

Wrapping up

GraphQL opens up tons of new possibilities for us. We are very excited about it and are going to double down on making our GraphQL support more robust.

The future, however, seems to be amazing. With the ability to do cross-database joins and joining results of microservices, we now stand the chance of truly becoming the kings of the Backend as a Service world.

We are soon going to porting all out functionalities to GraphQL to try and make everything accessible via the same API. We strongly believe that GraphQL has all that is required to standardize the API world finally.