Server-side operations with GraphQL

Learn how to perform server-side operations using GraphQL with a complete reference implementation that uses the MySQL database.

This guide we will develop an Olympic Medals application that demonstrates how to integrate a GraphQL endpoint with ag-Grid's Server-side Row Model. Specifically it will show how data can be lazy-loaded as required, even when performing group, filter, sort operations when working with large datasets.

The following screenshot shows what the finished application looks like:

The reference implementation covered in this guide is for demonstration purposes only. If you use this in production it comes with no warranty or support.

The source code can be found here: https://github.com/ag-grid/ag-grid-server-side-graphql-example.

Overview

In recent years GraphQL has become a popular alternative to REST when fetching data for clients. Familiarity with GraphQL is assumed however the following; Introduction to GraphQL should provide all the necessary background information to follow this guide.

One of the main benefits of GraphQL is the ability to expose a single endpoint and schema which maps to numerous data sources. However in our Olympic Medals application we will keep things simple by using just a single MySQL datasource.

In our application, the GraphQL endpoint will be hosted using a web server comprised of Node.js running Express.js. An overview of technologies used in this guide is illustrated in the diagram below:

We will now proceed and to install and run the application before going through the implementation details.

Download and Install

Clone the example project using: git clone https://github.com/ag-grid/ag-grid-server-side-graphql-example.git Navigate into the project directory: cd ag-grid-server-side-graphql-example Install project dependencies and build project using: yarn install

Database Setup

Download and install the database as per the MySql Download documentation.

Create a database with the name 'sample_data'. Then run the following script to create the table olympic_winners and populate it with data via the mysql command line:

mysql -u root -p -D sample_data < ./data/olympic_winners.sql

That's it. We are now ready to run and explore the application.

Running the application

To run the application execute the following from the command line:

yarn start

Then point your browser to http://localhost:4000/

Defining the GraphQL schema

To keep things simple, our schema will just contain a single entity OlympicWinner.

// server/schema.js type OlympicWinner { athlete: String country: String age: Int sport: String year: Int gold: Int silver: Int bronze: Int }

A single rows query is also defined along with it's supporting input types and enums:

// server/schema.js type Query { rows( startRow: Int, endRow: Int, sorting: [SortModel], rowGroups: [RowGroup], groupKeys: [String] ): [OlympicWinner]! } input SortModel { colId: String sort: String } input RowGroup { colId: String aggFunc: String }

The input types defined in the schema directly map to the IServerSideGetRowsRequest. We will discuss these mappings in detail in the following sections.

The corresponding rows resolver function is implemented as follows:

// server/schema.js import {fetchRows} from "./olympicService"; const resolvers = { Query: { rows: (obj, args) => new Promise((resolve, reject) => { const resultCallback = (err, results) => err ? reject(err) : resolve(results); fetchRows(args, resultCallback); }).then(rows => rows) }, };

The OlympicService simply takes the query arguments and uses dynamic SQL techniques to construct the corresponding SQL queries. The implementation details will be omitted from this guide but can be examined in the project repository.

The GraphQL schema created using the makeExecutableSchema helper function from the graphql-tools package, by combining the schema typeDefs along with the corresponding resolvers package as follows:

// server/schema.js const schema = makeExecutableSchema({ typeDefs, resolvers, }); export default schema;

GraphQL Endpoint

Hosting our GraphQL endpoint is done with the help of the express-graphql npm package. It is supplied with the schema we defined above.

// server/server.js import express from 'express'; import graphqlHTTP from 'express-graphql'; import schema from './schema'; const app = express(); app.use('/graphql', graphqlHTTP({ schema: schema, graphiql: true })); app.listen(4000, () => { console.log('Started on localhost:4000'); });

Notice that we have supplied the option: graphiql: true to enable the GraphiQL, client which is a useful tool for testing queries during development, and is available at: http://localhost:4000/graphql.

Server-side Datasource

In order to fetch data for the Server-side Row Model we must implement the IServerSideDatasource, which contains a single method getRows(params) which accepts request params from the grid.

To retrieve data from our GraphQL endpoint we will use the Apollo client. The response is then passed back to the grid via the params.successCallback(rows, lastRow) as shown below:

// client/serverSideDatasource.js class ServerSideDatasource { constructor(gridOptions) { this.gridOptions = gridOptions; this.client = new ApolloClient({uri: "http://localhost:4000/graphql/"}); } getRows(params) { const columns = this.gridOptions.columnDefs; // query GraphQL endpoint this.client.query(query(params.request, columns)) .then(response => { const rows = response.data.rows; // determine last row to size scrollbar and last block size correctly let lastRow = -1; if (rows.length <= this.gridOptions.cacheBlockSize) { lastRow = params.request.startRow + rows.length; } // pass results to grid params.successCallback(rows, lastRow); }) .catch(err => { console.error(err); params.failCallback() }); } }

The IServerSideGetRowsRequest supplied in the params is simply mapped to our GraphQL queries input params as shown below:

// client/serverSideDatasource.js const query = (request, columns) => { return { query: gql` query GetRows($start: Int, $end: Int, $sortModel: [SortModel], $groups: [RowGroup], $groupKeys: [String]) { rows( startRow: $start, endRow: $end, sorting: $sortModel, rowGroups: $groups, groupKeys: $groupKeys ) { ${getFields(columns)} } } `, variables: { start: request.startRow, end: request.endRow, sortModel: mapSortModel(request), groups: mapGroups(request), groupKeys: mapGroupKeys(request) }, } }; const getFields = (columnDefs) => { return columnDefs.map(colDef => colDef.field).join(); }; const mapGroups = (request) => { return request.rowGroupCols.map(grp => { return { colId: grp.field } }); }; const mapGroupKeys = (request) => { return request.groupKeys.map(key => key.toString()); }; const mapSortModel = (request) => { return request.sortModel.map(srt => { return { colId: srt.colId, sort: srt.sort } }); };

Note that we are using the Apollo graphql-tag package to help create the GraphQL AST.

The ServerSideDatasource is then registered with the grid via the grid api as follows:

// client/index.js const datasource = new ServerSideDatasource(gridOptions); gridOptions.api.setServerSideDatasource(datasource);

Conclusion

In this guide we presented a reference implementation for integrating the Server-side Row Model with GraphQL server hosted in node and connected to a MySQL database. This included all necessary configuration and install instructions.

A high level overview was given to illustrate the problem this approach solves before providing details of how to achieve the following server-side operations:

Infinite Scrolling
Sorting
Grouping