Scalar DB GraphQL

This blog post introduces an overview of Scalar DB GraphQL, a GraphQL interface to Scalar DB. (Japanese version is here.)

What is Scalar DB GraphQL?

Scalar DB GraphQL is an interface for accessing Scalar DB with GraphQL. While you need to use Java to interact with Scalar DB through the native CRUD API, which is built with Java language, the GraphQL interface allows you to access Scalar DB with a wide range of programming languages.

Scalar DB GraphQL is available under a commercial license. It is provided as a Docker image and a Helm chart to deploy to a Kubernetes environment.

Features

Scalar DB GraphQL has the following features.

• Generates a GraphQL schema for CRUD operations on Scalar DB tables
• Provides an HTTP server to communicate with clients
• Supports transactions using directives

Scalar DB GraphQL reads table metadata and generates GraphQL schemas to perform CRUD operations on Scalar DB tables at startup. You must create the tables in advance on storage and databases supported by Scalar DB.

GraphQL clients can execute queries and mutations mapped to CRUD operations on each table through the built-in HTTP server. Transactions spanning multiple HTTP requests are also supported.

Architecture

The following figure shows the structure of Scalar DB GraphQL.

The GraphQL Java components are built using the Scalar DB Java API and take the role of processing GraphQL tasks and accessing storage;

• GraphQL schema generation (at startup)
• Interpreting GraphQL inputs and executing Scalar DB API calls
• Returning results in JSON format

The HTTP server is only responsible for mediating the exchange of requests and responses between the clients and the GraphQL components.

Example of GraphQL schema

This section illustrates how a GraphQL schema is generated and how queries are executed, using a concrete example of a Scalar DB table.

We assume that a schema described by the following JSON is loaded in the database. Please refer to this entry for schema definition.

When you start Scalar DB GraphQL with this namespace "sample" specified, it generates the following GraphQL schema.

As you can see, GraphQL fields for CRUD operations (get, scan, put, and delete) are generated in the Query and Mutation types for a single table. (The Subscription type is not supported.) The input types and types are also generated to represent inputs and responses.

Clients can build and execute queries based on the generated GraphQL schema. GraphiQL, a graphical GraphQL IDE, is also available, which allows users to build queries interactively on web browsers.

As a first example, the following GraphQL query executes a get operation on the orders table. The orders_get field and its argument represent a get operation of Scalar DB, followed by the selection set that lists the column names you want to retrieve.

Each CRUD operation of the Scalar DB Transaction API maps to a field defined in the GraphQL Query and Mutation root types. The following table shows the mapping.

Transactions

In Scalar DB GraphQL, all operations are executed in transactions.

You control transactions with a directive named @transaction. A directive is a syntax used to provide additional settings for GraphQL operations. You can add a @transaction directive to both queries and mutations.

When a GraphQL operation is executed and the transaction is ongoing, the transaction ID is returned to the client in the "extensions" key of the response. Specifying the transaction ID in a subsequent operation allows you to continue the transaction across multiple GraphQL operations.

The rest of this section explains transactions with examples. We assume that there is a table named account.

A new transaction is started if a @transaction directive decorates a query without arguments.

The transaction ID in which the operation is executed is returned in the "extensions" field of the response JSON.

Active transactions are kept on the server. If the transaction ID is passed as an argument of the directive of the next operation, the server looks up the active transaction and executes the operation in the specified transaction.

Also, specifying commit: true as an argument to a directive commits the transaction at the end of the operation.

Running an abort field in a mutation operation aborts the specified transaction. An abort field must be used solely in operation.

As a special case, you can omit a @transaction directive. In this case, it is exactly the same as specifying @transaction(commit: true). That is, a transaction is started before the operation is executed and committed after execution. This is used when a transaction can be completed in a single operation.

Examples of GraphQL operations

Here are some examples of GraphQL execution.

The following example starts a transaction, puts two records in the orders table, and commits the transaction. As described above, it is equivalent to giving @transaction(commit: true).

Response:

The following example starts a new transaction and gets a record from the orders table that was inserted in the above example. It does not commit the transaction since commit: true is not specified, and the response includes the ongoing transaction ID in the "extensions" field.

Response:

The next mutation updates the record retrieved in the above example in the same transaction, and commits it.

Response:

Summary

This article introduced Scalar DB GraphQL interface. When Scalar DB GraphQL is invoked, it generates a GraphQL schema for the tables in the specified namespaces of the database.GraphQL operations allow you to perform CRUD operations without Java programming.