GraphQL with Express<\/h2>\n
If unfamiliar with GraphQL, take a few minutes to get up to speed using the GraphQL documentation. The following pages should be a good start:<\/p>\n
- \n
- Introduction<\/a><\/li>\n
- Queries and Mutations<\/a><\/li>\n
- Schemas and Types<\/a><\/li>\n<\/ul>\n
Prerequisites<\/h3>\n
- \n
- node<\/a>\u00a0v10.x or later<\/li>\n
- npm<\/a>\u00a0v5.x or later<\/li>\n
- git<\/a>\u00a0v2.14.1 or later<\/li>\n<\/ul>\n
Create Project Structure<\/h3>\n
We need to create a directory on your machine for our project, we will call it
rage-with-couchbase<\/code>:<\/p>\nmkdir rage-with-couchbase && cd $_<\/code><\/pre>\nmkdir<\/code> will create a new directory using the stringrage-with-couchbase<\/code> for the folder’s name, bash stores that string in a variable we can use immediately named$_<\/code>.<\/p>\nwe change directories using
$_<\/code> ensuring we don’t misspell the directory on the concatenated command (it’s bash magic).<\/p>\nNow let’s create a
.gitignore<\/code> file in the root of our project.<\/p>\ntouch .gitignore && echo \"\/node_modules\/*\" >> .gitignore<\/code><\/pre>\ntouch<\/code> will generate a.gitignore<\/code> file ignoring allnode_modules<\/code> directories and sub-directories in our project. This is important because as part of our fullstack React and GraphQL demo project, we will be tracking git changes from the rootrage-with-couchbase<\/code> directory, but we will have server and client directories with their ownpackage.json<\/code> andnode_modules<\/code> directory.<\/p>\necho<\/code> will add thenode_modules\/<\/code> text inside the.gitignore<\/code> file, this will serve to ignore all node_modules<\/strong> directories in the root and all subdirectories.<\/p>\nCreating Our Express Server<\/h3>\n
Now we will create the directory to store our Express server and we will use npm to manage its packages.<\/p>\n
mkdir couchbase-gql-server && cd $_ && npm init -y<\/code><\/pre>\nmkdir<\/code> will create a new folder inside the project root specifically for our server using the stringcouchbase-gql-server<\/code> for the name, this is your server project directory.<\/p>\nwe change directories and use the
$_<\/code> (more magic) and then we initialize an npm<\/strong> project usingnpm init -y<\/code> accepting the default values with the-y<\/code> flag.<\/p>\nInstall Express Server Dependencies<\/h3>\n
npm install graphql express express-graphql couchbase && npm install nodemon -D && code .<\/code><\/pre>\nOnce install is finished, we need to open our project with our editor of choice. I prefer VS Code.<\/p>\n
Create Our GraphQL Server<\/h3>\n
touch server.js .gitignore && echo \"\/node_modules\/*\" >> .gitignore<\/code><\/pre>\nRequire
express\/express-graphql\/graphql<\/code> in ourserver.js<\/code> file:<\/p>\nconst express = require('express')\r\nconst { graphqlHTTP } = require('express-graphql')\r\nconst { buildSchema } = require('graphql')\r\n \r\nconst couchbase = require('couchbase')<\/code><\/pre>\nThe first three imports are needed for our GraphQL server and the last import is required for connecting to and querying our Couchbase Server.<\/p>\n
Initialize Express and Connect to Our Bucket<\/h3>\n
Add the following code:<\/p>\n
const app = express()\r\nconst cluster = new couchbase.Cluster('couchbase:\/\/localhost', { \r\n username: 'Administrator', password: 'password' \r\n})\r\nconst bucket = cluster.bucket('travel-sample')\r\nvar collection = bucket.defaultCollection();<\/code><\/pre>\nAbove we are connecting to our Couchbase Server cluster, authenticating with our user that we set up, and opening our
travel-sample<\/code> bucket. Never use default usernames and passwords in production applications.<\/p>\nCreate Our GraphQL Schema<\/h3>\n
Adding the code below will define two endpoints that will enable our GraphQL Server to access and retrieve data from our documents inside of our Couchbase Server bucket.<\/p>\n
const schema = buildSchema(`\r\n type Airline {\r\n id: Int,\r\n callsign: String,\r\n country: String,\r\n iata: String,\r\n icao: String,\r\n name: String,\r\n type: String\r\n }\r\n input AirlineInput {\r\n callsign: String,\r\n country: String,\r\n iata: String,\r\n icao: String,\r\n name: String,\r\n type: String\r\n }\r\n type Query {\r\n airlinesUK: [Airline],\r\n airlineByKey(id: Int!): Airline\r\n airlinesByRegion(region: String!): [Airline]\r\n }\r\n type Mutation {\r\n updateAirline(id: Int!, input: AirlineInput): Airline\r\n }<\/code><\/pre>\nThe
Query<\/code> type specifies which GraphQL queries<\/a> clients can execute against its own data graph.<\/p>\nWe have two endpoints defined by that
Query<\/code>. One named “airlinesUK” and the other “airlineByKey”. In our React app, we will only use the “airlinesUK” endpoint. I made the “airlineByKey” endpoint simply to show an example of retrieving a single Couchbase document by key. This operation does not use the N1QL query language and therefore does not have any additional overhead. Understanding when and where to use each is important from the perspective of building the API, we wouldn’t want to use a N1QL query to return a single document that we can get by key.<\/p>\nIn our GraphQL code, we have an object of type
Airline<\/code>. This object model the document structure found in our Couchbase `travel-sample` bucket where the type is “airline”.<\/p>\nNext, we have an Endpoint named “
airlinesUK<\/code>“. Notice that the return value of this endpoint is an array of Airline:[Airline]<\/code>. This means we will be getting a list of airlines back.<\/p>\nWe also have “
airlineByKey<\/code>” endpoint where we will fetch a singleAirline<\/code>.<\/p>\nIf you remember from our Bucket images above, each document is defined by a key in a format like
airline_1234<\/code> where1234<\/code> is theid<\/code> of the airline.<\/p>\n![\"travel-sample](\"https:\/\/www.couchbase.com\/blog\/wp-content\/uploads\/2020\/01\/travel-sample-document.jpg\")
<\/p>\nWe will keep this
id<\/code> in mind when using the NodeJS SDK to fetch our individualairlineByKey<\/code> using a simplebucket.get()<\/code> method.<\/p>\nCreate Our Resolver Implementation for Each Endpoint<\/h3>\n
Now, that we have defined two queries in our GraphQL-Express API using our
schema<\/code> object, we need implementation in JavaScript for retrieving the data.<\/p>\nOur React application that we will create will only need the N1QL<\/strong> query named
airlinesUK<\/code>.<\/p>\nBut I wanted to show you how to query without N1QL<\/strong> using the NodeJS SDK’s API using just a key or extending it to use a region (US\/UK, etc..), that is the
airlineByKey<\/code> andairlineByRegion<\/code> implementation.<\/p>\nAdd the following code to our
server.js<\/code> file for our N1QL queries:
\n(In your JS code, ensure to escape backticks with backslashes)<\/p>\n\/\/ Define N1QL Queries\r\nconst airlinesUkQuery = `\r\n SELECT airline.* \r\n FROM \\`travel-sample\\` AS airline \r\n WHERE airline.type = 'airline'\r\n AND airline.country = 'United Kingdom'\r\n`\r\nconst airlinesByRegionQuery = `\r\n SELECT airline.* \r\n FROM \\`travel-sample\\` AS airline \r\n WHERE airline.type = 'airline'\r\n AND airline.country = $REGION\r\n`<\/code><\/pre>\nAdd the following code to our
server.js<\/code> file for our GraphQL resolvers:<\/p>\nconst root = {\r\n airlinesUK: async () => {\r\n const result = await cluster.query(airlinesUkQuery)\r\n return result.rows\r\n },\r\n \/*\r\n query getAirlinesUK {\r\n airlinesUK {\r\n id\r\n name\r\n callsign\r\n country\r\n iata\r\n icao\r\n }\r\n }\r\n *\/\r\n airlinesByRegion: async ({region}) => {\r\n const options = { parameters: { REGION: region } }\r\n const result = await cluster.query(airlinesByRegionQuery, options)\r\n return result.rows\r\n },\r\n \/*\r\n query getAirlinesByRegion($region: String!) {\r\n airlinesByRegion(region:$region) {\r\n id\r\n name\r\n callsign\r\n country\r\n iata\r\n icao\r\n }\r\n }\r\n {\r\n \"region\": \"{{country}}\"\r\n }\r\n *\/\r\n airlineByKey: async ({id}) => {\r\n const result = await collection.get(`airline_${id}`)\r\n return result.value\r\n },\r\n \/*\r\n query getAirlineByKey($id: Int!) {\r\n airlineByKey(id:$id) {\r\n id\r\n name\r\n callsign\r\n country\r\n iata\r\n icao\r\n }\r\n }\r\n {\r\n \"id\": {{id}}\r\n }\r\n *\/\r\n updateAirline: async ({id, input}) => {\r\n const result = await collection.get(`airline_${id}`)\r\n\r\n const newDocument = {\r\n ...result.content, \r\n callsign: input.callsign ? input.callsign : result.value.callsign,\r\n country: input.country ? input.country : result.value.country,\r\n iata: input.iata ? input.iata : result.value.iata,\r\n icao: input.icao ? input.icao : result.value.icao,\r\n name: input.name ? input.name : result.value.name,\r\n };\r\n\r\n console.log(newDocument)\r\n\r\n await collection.upsert(`airline_${id}`, newDocument)\r\n return newDocument\r\n }\r\n \/*\r\n mutation updateExistingAirline($id:Int!, $input:AirlineInput) {\r\n updateAirline(id:$id, input:$input){\r\n callsign\r\n country\r\n iata\r\n }\r\n }\r\n {\r\n \"id\": 112,\r\n \"input\": {\r\n \"callsign\": \"FLYSTAR\",\r\n \"country\": \"United Kingdom\"\r\n }\r\n }\r\n *\/\r\n}<\/code><\/pre>\nNote: In the N1QL statement above, you will need to escape the backticks in the FROM line around
`travel-sample`<\/code> with backslashes. Our blog’s code sample does not show those Backslashes, but they are there and they are in the Final Source Code<\/a><\/p>\nJust to drive this home, we are using two different methods to query our Couchbase Server.<\/p>\n
The first method corresponds to the
airlinesUK<\/code> endpoint, this is its resolver. We need to return a promise and inside rely onbucket.query<\/code>to take a predefined N1QL query that I have broken up line by line in the statement variable for readability. Being able to run this type of SQL query is very powerful for a document database. A lot of the SQL we know transfers over and this is a big relief compared to other document databases that have a brand new API and query language you will need to learn.<\/p>\nThe second method corresponds to the
airlinesUK<\/code> endpoint, this is its resolver. We need to return a promise and inside rely onbucket.get<\/code> method and in this case, we are just defining the key of our document. Remember that one of the great things about using a key-value data store is that we can easily pick out a single document with little overhead.<\/p>\nEach of the methods above also tests for query errors and either resolve or reject based on a
result<\/code> orerror<\/code>.<\/p>\nCreating Our GraphQL with Express Server<\/h3>\n
Now that we have everything sorted out for our endpoints and queries, all we need to do is
use<\/code> our Express server and give it a port to run on, let’s do that now.<\/p>\nAdd the following code to the end of our
server.js<\/code> file:<\/p>\n\/* \r\n The graphqlHTTP function accepts a schema, rootValue and graphiql \r\n among other options for configuring our GraphQL Server \r\n*\/\r\nconst serverPort = 4000\r\nconst serverUrl = '\/graphql'\r\napp.use(serverUrl, graphqlHTTP({\r\n schema: schema,\r\n rootValue: root,\r\n graphiql: true\r\n}))\r\n\r\napp.listen(\r\n serverPort, \r\n () => console.log(`GraphQL server running: https:\/\/localhost:${serverPort}${serverUrl}`)\r\n)<\/code><\/pre>\nIf you have ever created an Express or Express-GraphQL server, this code should look familiar.<\/p>\n
First, we set up our port and GraphQL URL.<\/p>\n
Next, we pass in our GraphQL schema and its resolvers and set our
graphiql<\/code> option to true. (This will give us an IDE to test our GraphQL queries available at localhost:4000\/graphql<\/a>.<\/p>\nFinally, we listen on port 4000 and set a message in the console to indicate our server is running.<\/p>\n
Let’s run our server, ensure that your Couchbase:<\/p>\n
node server<\/code><\/pre>\nOnce we have the GraphQL server running we can test the
AirlinesUK<\/code> query by pasting the following code into the GraphQL IDE query pane:<\/p>\nquery getAirlinesUK{\r\n airlinesUK {\r\n id\r\n name\r\n callsign\r\n country\r\n iata\r\n icao\r\n }\r\n}<\/code><\/pre>\nAs the query indicates it will retrieve all of our UK based airlines:<\/p>\n
![\"GraphQL](\"https:\/\/www.couchbase.com\/blog\/wp-content\/uploads\/2020\/01\/travel-sample-graphiql-airlinesUK.jpg\")
<\/p>\nNext, we will use the
airlineByKey<\/code> endpoint, in this example, we will also need to create a query variable and paste it into the respective pane:<\/p>\nquery getAirlineByKey($id: Int!) {\r\n airlineByKey(id:$id){\r\n id\r\n name\r\n callsign\r\n country\r\n iata\r\n icao\r\n }\r\n}<\/code><\/pre>\n{\r\n \"id\": 112\r\n}<\/code><\/pre>\nAnd with that in place and we can query again and retrieve a single airline document by key:<\/p>\n
![\"GraphQL](\"https:\/\/www.couchbase.com\/blog\/wp-content\/uploads\/2020\/01\/travel-sample-graphiql-airlineByKey.jpg\")
<\/p>\nWith a super simple GraphQL API setup, we are ready to create our react application<\/a> that will use these endpoints for a master-detail page using the UK airlines in a list component and when we click a particular Airline, another component will show the full details of the airline on the right side of the page.<\/p>\n
- npm<\/a>\u00a0v5.x or later<\/li>\n
- Queries and Mutations<\/a><\/li>\n