Skip to content
Building a global app or API with a geo-distributed DB to serve requests closer to end users !
Profile icon

Getting Started With Global Apps & APIs

This tutorial should take about 15 minutes to complete.

Let’s create the backend for a simple Address Book app in the next few minutes. Our address book app will be run globally distributed with local read-write latencies on Macrometa’s global cloud platform.

enter image description here

Note: You need an account with Macrometa’s Cloud platform to build the backend for the app. If needed, you can get a free developer account at

Here's the repo for this tutorial that shows you some of these steps in Python
Replit - Chetan's Python code for the address book

Building the geo-distributed backend engine for our app involves 3 steps:

  1. Creating a geo-fabric to distribute our database and streams across worldwide locations we want to run our backend at

  2. Creating a collection (like a table in SQL) and creating queries for CReate, Update and Delete (CRUD)

  3. Exposing and consuming the CRUD queries as RESTful API endpoints

Step-1: Creating a geo fabric - a database that spans two or more global regions

Use your tenant credentials to login at

Once you login, you should see a dashboard with a map showing all the global locations provisioned for you to use.

enter image description here
The pin icons on the map represent all the locations to which the data will be automatically replicated, synchronized and stored in a deterministic manner. Applications can read and write locally from all these locations without waiting on synchronization for updates from other locations. By default, all data will be stored in all locations on your map. However, you can create specific geo-fabrics if you want to use a subset of the locations provided.

Step-2: Create an Address Book Collection

Collections in Macrometa’s are like tables in an RDBMS database. A collection contains zero or more documents. Macrometa is schema-less. You can read more about various data models supported by the database here.
enter image description here
Let’s start by clicking the COLLECTIONS menu entry, then the Add Collection tile. Give it a name, e.g. addresses, leave the other settings unchanged (we want it to be a document collection) and Save it.

A new tile labeled "addresses" should appear. You can click to open (it will be empty since we have not stored any data in it yet).
enter image description here
Note: The collection "addresses" will automatically be created in all locations where you see pin in the map.

Step-3: Generate CRUD REST API (RESTQL)

To store addresses in our address book app, we will use the following document format (or schema) for each contact:

"firstname": "John",
"lastname": "Doe",
"email": "[email protected]",
"zipcode": 56703

Click the QUERIES menu entry to open C8QL query editor. Then create the query shown in the screenshot below.
enter image description here

Let's execute the query to make sure it works correctly. Do this by clicking on the "Execute" button in blue.

Automatic REST API creation for queries
Let’s save the query with name addAddress. This query then automatically will be available as a REST end point for execution globally by its name addAddress. In short, within a second you have a globally distributed backend service for this functionality in your app. Simple right?

enter image description here

Let’s write queries for the other server-side capabilities we need in our AddressBook app. Save them with relevant names as follows:

Name: addAddress

INSERT { firstname: @firstname, lastname: @lastname, email: @email, zipcode: @zipcode } INTO addresses

Name: getAddresses

FOR address IN addresses RETURN address

Name: updateEmail

UPDATE { _key: @key } WITH { email: @email } IN addresses

Name: removeAddress

REMOVE { _key: @key} IN addresses

You can read more about how to write C8QL queries here.


Click the SUPPORT menu entry and open the API Browser. Scroll down and to see RESTQL api.

enter image description here

You can execute RESTQL API from anywhere in the world. The Macrometa fast data platform will take care of intelligently routing the request to the location closest to your app, and return results from that location.

To see Macrometa in action, let’s execute our getAddresses API using the curl command. Click on SUPPORT, scroll down to RESTQL, and select the POST option to "Execute restql by name". After adding your tenant name, fabric name, and query name (in this case, getAddresses), select Execute and you'll see the Curl syntax is built for you.

enter image description here

In the screenshot above, Macrometa’s platform routed the request and executed in Los Angeles, US datacenter as that is closest to my current location (Macrometa is based in Palo Alto).

You are viewing a single comment. View All
Profile icon

no need to apologize. I just thought it would be a good idea since you posted the tutorial on