GROQ - a GraphQL alternative?

Here below is a sample GraphQL query.

{users {idemail}}

The query above specifies that we want to retrieve all the users in our system and return only the id and the email.

Great! 😎

Now, here is also a query. See below:

[users] { id, email }

Or we could also write it this way,

*[] {id,email}

Alright. Awesome. We call the above as or GROQ for short but what exactly is it?

Before We Dive In

I made a quick demo so we could see it in action. The video is 5 minutes only. If you want to skip the video and read through it, .

Or .

So for the last example, we want to get only results id, name, and base stats. The query would be like this below:

*[ id == 4 ] {id,"name": name.english,base,}

And here's the result:

[{"id": 4,"name": "Charmander","base": {"HP": 39,"Attack": 52,"Defense": 43,"Sp. Attack": 60,"Sp. Defense": 50,"Speed": 65}}]Getting Started

In today's modern web, has pretty much changed how we approach fetching data. For so long, we've gone accustomed to thinking in terms of . had become the de-facto standard until the former came. One can't simply ignore the benefits of using it but unfortunately, not everyone has the capacity to begin adopting it and/or start new.

So now, the question is - "Is there a way that we could gain GraphQL's declarative and expressive syntax without doing much work on our good old responses in JSON format?"

Well, the answer to that is, YES!

Absolutely.

GraphQL is a query language for API's and GROQ is also a query language but JSON-based. It carries on the work that has become so fashionable similar to the implementations of GraphQL which allows robust transformations, filters, projections, and many more.

In simpler terms, GROQ just like GraphQL allows us to describe exactly how we want to shape our data through filters, projections, and many more.

What's great with GROQ is that it also takes it a step further...

Let's go back to our example query above, here shown below:

*[] { id, email }

If you're new, you'd probably reject what you're seeing. When I first started using GROQ, I have this feeling that it's not something I shouldn't get myself into and learn. I was wrong, and I realized how it could be useful in other areas of my professional career as a developer.

* denotes everything, within the [] is our filter (though not required here but for the sake of example) and lastly, the { id, email } is our transformation which only returns those fields.

It's not that easy from the very beginning but just like any other thing we try to learn, it gets easier through practice.

Let's Play

Here below are basic to advanced usages of GROQ with its corresponding GraphQL equivalent. The data is based on Pokemon's API.

*["Grass" in type] {"name": name.english,base,}

Play with it here:

And the GraphQL equivalent below:

{pokemons(filter: {type: {in: "Grass"}}) {name: name.englishbase {HPAttack,Defense"Sp. Attack""Sp. Defense"Speed}}}*["Grass" in type] {"name": name.english,base,} | order(base.Speed desc)

Play with it here:

And the GraphQL equivalent below:

{ pokemons(sort: {fields: base__Speed, order: DESC}, filter: {type: {in: "Grass"}}) { name: name.english base { HP Attack, Defense "Sp. Attack" "Sp. Defense" Speed } } } {"GrassPokemonsCount": count(*["Grass" in type])}

Result:

{"GrassPokemonsCount": 97}

Play with it here:

Why GraphQL alternative? (Real Life Usage)

In our experience, using GROQ with our REST APIs has allowed us to take its superpowers like filtering, sorting, and shaping our JSON response data however we want it. It has brought tremendous benefits and it never felt so easy. From an investment standpoint, sure, you'll have to learn GROQ's syntax additionally but the benefits are just tenfolds.

For example in one of our eCommerce projects, we fetch the JSON data and used GROQ to do multi-level filtering based on customers' selection.

It's such a breeze of joy.

Let's say, given all shoes, get all of the color blue and the size is greater than 12.

Pretty contrived example below:

import { parse, evaluate } from 'groq-js'let input = *[type == "shoes" && color == "blue" && size > 12] {id,name,description,price,images,}// Returns an ESTree-inspired syntax treelet tree = parse(input)let dataset = await fetch(PRODUCTS_API_ENDPOINT);// Evaluate a tree against a datasetlet value = await evaluate(tree, {dataset})// Gather everything into one JavaScript objectlet shoeProducts = await value.get()

And that's it! No need for GraphQL. We've supercharged our REST API without doing too much. 😊

To learn more about GROQ, head over to , and refer to anytime. I've also found some challenges you could try .