Cedrick Lunven

GraphQL has become more and more popular among developers to implement APIs (specially frontend developers) as it brings both simplicity and discoverability on the client side. But, what about server side? If you have already worked with Apache Cassandra™ you know that designing the proper data model is key. You also know that you need to know your queries very well in order to ensure performance. Is it possible to create an API on top of Apache Cassandra with GraphQL allowing only valid queries? Let's have a look.

<h2>GraphQL positioning</h2>

<img alt="GraphQL Logo" data-entity-type="file" data-entity-uuid="6ea521ba-2402-4efc-bc55-7bb95240f41d" src="https://www.datastax.com/sites/default/files/inline-images/graphql-logo_1.png" />

<h2>Yet another API specification</h2>

<a href="https://graphql.org/">GraphQL</a> is a query langage created in 2012 by Facebook. They used it multiple years in production before giving it to the open source community in July 2015. Some web giants adopted it right away like Pinterest but the big shift happened in September 2016 when <a href="https://githubengineering.com/the-github-graphql-api/">Github announced</a> they were embracing the technology. Most developers are now accustomed to developing REST API using <a href="https://www.openapis.org/">OpenAPI</a> standard (swagger-ish). What makes GraphQL so appealing? The main advantages are the following

<ol>
	<li>GraphQL is strongly typed : You can validate queries before firing them against the server. It allows the development of tools like <code>GraphiQL</code> to help you interact with your API</li>
	<li>GraphQL is less verbose : Clients will ask exactly for the data they need. Requests are forged on client side where they specified which data they need. Servers will send back the expected Payload not only filtering unwantering attributes but also a hierachical chunk of objects. Not only can you limit the number of data for each entity but you can also limit the number of requests by providing everything as a tree in a single call. Those features are really keen on mobile development or any use where the bandwith or data transfer are important.</li>
	<li>Your API is discoverable. That means that the client can ask the API to describe itself, to communicate about the entities and the functions available. You don't need some contract, the client can discover it at runtime.</li>
</ol>

But, GraphQL, like others technologies, is not a silver bullet and some pain points remain :

<ol>
	<li>There is a single endpoint to access all the operations. This could be both an advantage for the simplicity but this is mostly a drawback because this does not allow versioning.</li>
	<li>Even if strongly typed (which could allows all kinds of code generation engines) the tooling is limited. Technology is young. The schema is quite complex to comprehend, we wiil see that later in this article</li>
	<li>As each query may be unique and hierarchical there is no caching mechanism in place on the server side.</li>
	<li>There were no asynchronous operations previously, but this is becoming possible with last specification version</li>
</ol>

In the Advocates team we have been working with multiple formats and technologies to expose services like REST, gRPC, oData or GraphQL for our reference application <a href="http://killrvideo.github.io/">KillrVideo</a>. While GraphQL looks promising, it is not a silver bullet and should only be used with proper use cases. Our team had a talk on the subject you can view the <a href="https://www.slideshare.net/CdrickLunven/create-api-for-your-databases">slides</a> and <a href="https://www.youtube.com/watch?v=o7YwnnPVuJU">video</a>. Here is our take on this topic:

<ul>
	<li>GraphQL seems relevant when the network and bandwith matter (mobile) as there will be less calls and data on the wire,</li>
	<li>GraphQL seems relevant when you need a typed schema (less flexibility) and some kind of contract between you and your consumer or maybe you don't know your consumer (public API)</li>
	<li>GraphQL seems relevant when you have a highly connected or hierarchical data. Relations and traversal can be retrieved as a single query</li>
	<li>GraphQL seems relevant when you need to aggregate multiple data sources (mashup).</li>
	<li>For CRUD operations, plain old REST is still the way to go</li>
	<li>For streaming, asynchronous and action/command oriented API, gRPC is our best choice</li>
</ul>

Enough with the chit chat, let's get our hands dirty.

<h2>Sample Application</h2>

<img alt="Cassandra" data-entity-type="file" data-entity-uuid="2c2f6e62-a924-4261-9dd4-69f13e1acb3f" src="https://www.datastax.com/sites/default/files/inline-images/graphql-logocassandra_1.png" />

<h2>KillrVideo Application and Data Access Object (DAO)</h2>

Without surprise we will leverage our reference application <code>Killrvideo</code>. We will focus on read and wite operations for our Comments section that can be found here. Here is a simplified of the version we will leverage:

<code>public interface CommentDseDao {</code>

<code>/** Provide videoid and paging information to retrieve a set of comments. */ ResultListPage<comment> findCommentsByVideoId(QueryCommentByVideo query); </comment></code>

<code><comment>/** Provide userid and paging information to retrieve a set of comments. */ ResultListPage<comment> resultComments = findCommentsByUserId(QueryCommentByUser query); </comment></comment></code>

<code><comment><comment>/** Insert new comment on all expected tables from a web bean. */ void insertComment(Comment myComment); </comment></comment></code>

<code><comment><comment>// [..] 
} </comment></comment></code>

<h2>GraphQL Schema</h2>

The first thing to do is to create the GraphQL schema defining all enties and available operations. There are two types of services QUERY and MUTATIONS. Mutations seem familiar right? It's indeed the exact same notion we find with Apache Cassandra. The key takeaway here is to notice by default everything is forbidden and only allowed operations declared in the schema will be available. THIS, is a perfect match for Cassandra usage where we don't allow users to execute forbidden queries like <code>select * from myHugeTable</code> and make our database blow up by allowing for a full table scan.

<code># Killrvideo GraphQL API 
schema { 
&nbsp; &nbsp;query: Query 
&nbsp; &nbsp;mutation: Mutation } </code>

<code># Searches and read-only operations on KillrVideo Keyspace #-------------------------------------------------------------</code>

<code>type Query {</code>

<code>&nbsp; &nbsp; # Search in table comment_by_video, eventually with Pagination. 
&nbsp; &nbsp; getVideoComments(videoid: String!, commentid: String, pageSize: Int , pageState: String): ResultPageCommentGQL! # Search in table comment_by_user, eventually with Pagination. 
&nbsp; &nbsp;getUserComments(userid: String!, commentid: String, pageSize: Int , pageState: String): ResultPageCommentGQL! 
}</code>

<code># Operation that will updated data in DB 
#------------------------------------------------------------- type Mutation { 
&nbsp; &nbsp;# Add a comment for dedicated video and known user. 
&nbsp; &nbsp;commentOnVideo(commentid: String!, videoid: String!, userid: String!, text: String!): CommentGQL! 
} </code>

For now we will have to declare the entities used as input and outputs. There are a number of types available in the schema (Scalar, Object, Interface, Union, InputObject, Enum) and you can details <a href="https://www.graphql-java.com/documentation/v11/schema/">here</a>.

<code># Represent a video comment in GraphQL format type CommentGQL { 
&nbsp; &nbsp;#Unique identifier for a user (tech id) commentid: ID! 
&nbsp; &nbsp;# Unique identifier for a user (required) userid: String! 
&nbsp; &nbsp;# Unique identifier for a video (required) videoid: String! 
&nbsp; &nbsp;# Text of the comment comment: String 
&nbsp; &nbsp;# Insertion Date 
&nbsp; &nbsp;dateOfComment: String } type ResultPageCommentGQL { 
&nbsp; &nbsp;listOfResults: [CommentGQL]! 
&nbsp; &nbsp;nextPage: String 
} </code>

<h2>Spring Boot and GraphQL</h2>

With this GraphQL schema we are all set to start implementing. The same schema can be used with many different languages. In our sample we will use <code>Java</code> and <code>graphql-java</code>framework. Instead of mapping everything manually we will leverage on relevant spring-boot-starter and define expected beans. First thing to do is to declare the following dependencies in your <code>pom.xml</code> file.

<code>&lt;!-- GraphQL --&gt; 
&lt;dependency&gt; 
&nbsp;&lt;groupId&gt;com.graphql-java&lt;/groupId&gt; 
&nbsp;&lt;artifactId&gt;graphql-java&lt;/artifactId&gt; 
&lt;/dependency&gt; 
&lt;dependency&gt; 
&nbsp;&lt;groupId&gt;com.graphql-java&lt;/groupId&gt; 
&nbsp;&lt;artifactId&gt;graphql-java-tools&lt;/artifactId&gt; 
&lt;/dependency&gt; 
&lt;!-- SpringBoot --&gt; 
&lt;dependency&gt; 
&nbsp;&lt;groupId&gt;com.graphql-java&lt;/groupId&gt; 
&nbsp;&lt;artifactId&gt;graphql-spring-boot-starter&lt;/artifactId&gt; 
&lt;/dependency&gt; 
&lt;dependency&gt; 
&nbsp;&lt;groupId&gt;com.graphql-java&lt;/groupId&gt; 
&nbsp;&lt;artifactId&gt;graphiql-spring-boot-starter&lt;/artifactId&gt; &nbsp;&lt;!-- += We will speak about it in a minute --&gt; 
&lt;/dependency&gt;</code>

Define the associated POJO :

<code>public class CommentGQL implements Serializable { 
&nbsp; &nbsp;private static final long serialVersionUID = -4032110812123661790L; 
&nbsp; &nbsp;protected String userid; 
&nbsp; &nbsp;protected String videoid; 
&nbsp; &nbsp;protected String comment; 
&nbsp; &nbsp;protected String commentid; 
&nbsp; &nbsp;private Date dateOfComment; 
&nbsp; &nbsp;// getters, setters 
} 
public class ResultPageCommentGQL { 
&nbsp; &nbsp;private List &lt; CommentGQL &gt; listOfResults = new ArrayList&lt;&gt;(); 
&nbsp; &nbsp;private String nextPage; 
// getters, setters 
} </code>

Define the expected 2 beans <code>com.coxautodev.graphql.tools.GraphQLMutationResolver</code> and <code> com.coxautodev.graphql.tools.GraphQLQueryResolver</code>. We use the method names declared in the schema file. From there this is simply mapping parameters and invoking the DAO. Some parts of code are simplifier, full source code can be found <a href="https://github.com/clun/voxxeddays-api/tree/master/killrvideo-api-graphql/src/main/java/com/killrvideo/graphql/api">here</a>.

<code>@Component 
public class KillrvideoMutation implements GraphQLMutationResolver {</code>

<code>&nbsp; &nbsp;@Autowired 
&nbsp; &nbsp;private CommentDseDao commentDseDao;</code>

<code>&nbsp; &nbsp;public CommentGQL commentOnVideo(String commentid, String videoid, String userid, String text) { 
&nbsp; &nbsp;// Ommited parameters validation 
&nbsp; &nbsp;Comment newComment = new Comment(); // Populating bean 
&nbsp; &nbsp;commentDseDao.insertComment(newComment); 
&nbsp; &nbsp;return new CommentGQL(newComment); 
&nbsp; } 
} </code>

<code>@Component 
public class KillrvideoQuery implements GraphQLQueryResolver {</code>

<code>&nbsp; &nbsp;@Autowired 
&nbsp; &nbsp;private CommentDseDao commentDseDao;</code>

<code>&nbsp; &nbsp;public ResultPageCommentGQL getVideoComments (String videoid, String commentid, int pageSize, String pageState) { 
&nbsp; &nbsp;QueryCommentByVideo qcbv = new QueryCommentByVideo(); 
&nbsp; &nbsp;// Mapping ommited 
&nbsp; &nbsp;ResultListPage<comment> resultComments = commentDseDao.findCommentsByVideoId(qcbv); </comment> 
&nbsp; &nbsp;<comment>ResultPageCommentGQL result = new 
&nbsp; &nbsp;ResultPageCommentGQL();</comment></code> 
<code><comment>&nbsp;resultComments.getPagingState().ifPresent(result::setNextPage); </comment> 
<comment>&nbsp; &nbsp;</comment><comment>result.setListOfResults( </comment> 
<comment>&nbsp; &nbsp; &nbsp;&nbsp;</comment><comment>resultComments.getResults().stream() </comment> 
<comment>&nbsp; &nbsp; &nbsp;&nbsp;</comment><comment>&nbsp; &nbsp; &nbsp;&nbsp;</comment><comment></comment><comment>.map(CommentGQL::new) </comment> 
<comment>&nbsp; &nbsp; &nbsp;&nbsp;</comment><comment>&nbsp; &nbsp; &nbsp;&nbsp;</comment><comment></comment><comment>.collect(Collectors.to 
List())); 
&nbsp; &nbsp; &nbsp;&nbsp;return result; </comment></code>

<code><comment>} </comment></code>

<code><comment>&nbsp; &nbsp;public ResultPageCommentGQL getUserComments (String userid, String commentid, int pageSize, String pageState) { 
&nbsp; &nbsp;QueryCommentByUser qcbu = new QueryCommentByUser(); 
&nbsp; &nbsp;// Mapping ommited ResultListPage<comment> resultComments = commentDseDao.findCommentsByUserId(qcbu); ResultPageCommentGQL result = new ResultPageCommentGQL(); resultComments.getPagingState().ifPresent(result::setNextPage); result.setListOfResults( </comment></comment> 
&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;<comment><comment>resultComments.getResults().stream() </comment></comment> 
&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp;&nbsp;<comment><comment>.map(CommentGQL::new) </comment></comment> 
&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; <comment><comment>.collect(Collectors.toList())); </comment></comment> 
&nbsp; &nbsp;&nbsp; &nbsp;<comment><comment>return result; </comment></comment></code>

<code><comment><comment></comment></comment>&nbsp; &nbsp;<comment><comment>} 
} </comment></comment></code>

We have now everything we need to make it work. If you look at the github repository you will find some boiler plate code like a <code>main</code> and configuration loading here and there. To start the application, execute the standard <code>mvn spring-boot:run.</code> Your api is now started and is available at <a href="http://localhost:8083/gql">http://localhost:8083/gql</a> . The API can be invoked from clients but there is still no user interface to test.

<h2>GraphiQL</h2>

<a href="https://github.com/graphql/graphiql">GraphiQL</a> is a graphical interactive in-browser GraphQL IDE. It allows you to discover existing GraphQL endpoints and fire sample requests. To enable this interface in our sample we added the dependency <code>graphiql-spring-boot-starter</code> in our <code>pom.xml</code>. You can now access the api at <a href="http://localhost:8083/gql/graphiql">http://localhost:8083/gql/graphiql</a>. On the right hand side of the screen you can see the different functions we define, the entities but also the comment we added in the schema file.

<img alt="Documentation Explorer" data-entity-type="file" data-entity-uuid="d9fb6e32-b04f-422c-9d94-15bb6e28f48a" src="https://www.datastax.com/sites/default/files/inline-images/Screen%20Shot%202018-11-28%20at%2014.35.35.png" />

<h2>Testing our Application</h2>

Testing is now straight forward, build your queries and execute using the <code>run</code> button at the top of the page. You will notice that there is some autocompletion in the panel on the right if you use the shortcut <code>CTRL+SPACE</code>.

<img alt="GraphiQL" data-entity-type="file" data-entity-uuid="c5d39b37-3f5a-4964-b64d-feb6700aa06c" src="https://www.datastax.com/sites/default/files/inline-images/Screen%20Shot%202018-11-28%20at%2016.13.56.png" />
<plet's a="" an="" both="" comment="" create="" existing="" find="" need="" on="" to="" video.="" we="">userid and <code>videoid</code>. To do so we use DataStax Studio and query the table <code>comments_by_video</code>. You can see in the picture that we can use the existing video id <code>172219b0-1662-4f11-9232-f2ba5ecec16b</code> and the existing userid : <code>c98a0721-c8ce-408e-9065-45be9511771c</code>

<img alt="Create a Comment" data-entity-type="file" data-entity-uuid="c6fcbe45-fc1d-4ac3-83b1-0360e9e4c238" src="https://www.datastax.com/sites/default/files/inline-images/Screen%20Shot%202018-11-28%20at%2014.30.48.png" />

Let's create a mutation to insert a comment using the schema. <code>commentid</code> is expected to be a valid <code>TimeUUid</code>. To generate one you can either execute the following test in your favourite IDE <code>System.out.println(UUIDs.timeBased());</code>or use cqlsh or DataStax Studio with the following command : <code>SELECT now() FROM killrvideo.comments_by_video LIMIT 1</code>

<img alt="Create Insert Comment Mutation" data-entity-type="file" data-entity-uuid="ca16fedd-cf1f-4292-bd5a-982ddf1f3e78" src="https://www.datastax.com/sites/default/files/inline-images/Screen%20Shot%202018-11-28%20at%2016.22.29.png" />

Ok, now query the list of comments for our user <code>c98a0721-c8ce-408e-9065-45be9511771c</code> and observe the expected 3 comments. We only needs 2 attributes which are the date of the comment and the text so let's filter :

<img alt="Query and Filter" data-entity-type="file" data-entity-uuid="3e73d7fc-62f5-4f8c-8277-5a9d4395c974" src="https://www.datastax.com/sites/default/files/inline-images/Screen%20Shot%202018-11-28%20at%2016.27.18-1.png" />

<h2>Takeaways</h2>

We have seen that GraphQL can be easily used with a Cassandra backend.You can't implement CRUD operations, but you can allow queries you want to enforce good performance on your Cassandra clusters.

Happy coding!
</plet's>

Getting started with GraphQL and Apache Cassandra™

Cedrick Lunven Team Leader AI, Cloud Integrations and Developer Tools, DataStax

Discover more

Share

More Technology

Getting Started with DataStax Astra DB and Amazon Bedrock

Why You Can't Miss Cassandra Summit

Mitigate the OpenAI Debacle with Open Source and Cloud

Supercharge AI Assistants with Superagent and DataStax

NoSQL and Vector DB
for Generative AI,
Instantly, At Scale