Introducing GraphQL Architect

[greta]

Build Low-Code GraphQL APIs Powered By Neo4j

GraphQL Architect is a graph app for Neo4j Desktop that enables developers to build, query, and deploy GraphQL APIs backed by the Neo4j graph database, all from within Neo4j Desktop.

Install GraphQL Architect from the Neo4j Desktop Graph Apps Gallery.

Low Code GraphQL With GraphQL Architect

The goal of GraphQL Architect is to simplify the process of developing, querying, and deploying GraphQL APIs.

Features:

• Query local or remote GraphQL APIs using GraphiQL
• Generate and run a local GraphQL API from an existing Neo4j Database, without writing any code. The schema will be inferred from the database’s data model. Or,
• Drive your Neo4j database’s property graph model by defining its GraphQL schema using the GraphQL Schema Definition Language (SDL)
• Add custom logic by adding Cypher statements to your GraphQL schema using the @cypher GraphQL schema directive
• Edit the GraphQL schema using a schema-aware GraphQL type definition editor with linting and semantic auto-complete suggestions
• Export and deploy your GraphQL API application

With GraphQL Architect you can build, query, and deploy GraphQL APIs backed by Neo4j using just GraphQL SDL — no code is necessary. Custom logic can be added to your API using the Cypher query language.

GraphQL Architect is a low code tool for building, querying and deploying GraphQL APIs powered by Neo4j. You can install it from the Neo4j Desktop Graph Apps Gallery.

Installation

Install GraphQL Architect from within Neo4j Desktop using the Graph App Gallery or from install.graphapp.io

GraphQL Architect is a Graph App for Neo4j Desktop. That means you’ll first need to have Neo4j Desktop installed, which you can download here. Neo4j Desktop allows you to manage multiple Neo4j projects, install Neo4j DBMSs, work with remote databases, install and launch Graph Apps, and much more. Think of Neo4j Desktop as “Mission Control” for working with Neo4j.

Once you have Neo4j Desktop installed, open the Graph Apps Gallery and look for Graph Architect in the list of apps available. Just click on the “Install” button and you’ll be ready to start using GraphQL Architect!

The Neo4j Desktop Graph Apps Gallery offers a host of Graph Apps for Neo4j Desktop that can be installed with just a click.

Getting Started With GraphQL Architect

Once you’ve installed GraphQL Architect and have a Neo4j database running, select the “Open” drop-down for the database you’d like to use and select “GraphQL Architect”.

Opening the GraphQL Architect graph app for the sample Movie database that ships with Neo4j Desktop

This will open the GraphQL Architect application in a new window. You may be prompted to install the APOC standard library for Neo4j if you don’t already have it installed. APOC is a dependency of the neo4j-graphql.js library used for generating database queries from GraphQL.

The main view of the GraphQL Architect Graph App. From here you can generate GraphQL type definitions for a Neo4j database, start and query a local GraphQL API connected to your database, add custom logic by editing the GraphQL type definitions and adding Cypher, or export and deploy your GraphQL API once you’re done developing and testing.

Using With An Existing Database

One of the most powerful features of GraphQL Architect is the ability to infer a GraphQL schema from an existing Neo4j Database. This means you can run a GraphQL API with full Create, Read, Update, Delete (CRUD) operations with just the click of a button!

When starting GraphQL Architect with an existing Neo4j database a GraphQL schema will be generated from the database. This schema includes entry points into the GraphQL API (the Query and Mutation types), mapping each node label to a type in the GraphQL API. The generated API also includes arguments for ordering, pagination, and filtering.

To start a local GraphQL server using this generated schema click the “Start GraphQL Server” button. You can then use the embedded GraphiQL tool to query the GraphQL API.

For example, here we use the generated GraphQL API to query the sample movies Neo4j database for movies released before 2000 starring Emil Eifrem using GraphiQL in GraphQL Architect.

Querying the default movies Neo4j database using GraphQL in GraphQL Architect.

You can learn more about the GraphQL schema generation in the neo4j-graphql.js documentation.

Using With A New Database

Above we showed the generated type definitions in the case of connecting to an existing database. What if we are starting a new project and are starting with an empty database? We can use GraphQL type definitions to define the property graph model we want to create in Neo4j.

Here, we define two types in GraphQL, a Person and Company. Each has an id and name field, and the Person has a relationship field connecting it to a Company.

type Person {
  personId: ID!
  name: String!
  works_at: Company @relation(direction: OUT, name: "WORKS_AT")
}

type Company {
  companyId: ID!
  name: String!
}

When we start the GraphQL server by clicking “Start GraphQL Server”, our generated GraphQL API includes CRUD operations for each type and relationship field defined in our schema, including mutations for creating data.

The generated GraphQL mutations for our Company, Person data model defined using GraphQL SDL.

We can then use these generated mutations to add data to our Neo4j database. For example, here we create a Person node, a Company node, and a relationship connecting them using the GraphiQL tool embedded in GraphQL Architect:


In Neo4j, we’ve now created a graph that looks like this:


You can learn more about designing a property graph model using GraphQL in the GraphQL Schema Design guide.

Schema Editor

In GraphQL Architect, the GraphQL schema editor is where you can update your GraphQL schema and add custom logic using Cypher. Powered by Monaco GraphQL (part of the GraphiQL project) the schema editor gives you schema-aware linting and auto-complete suggestions, as well as all the functionality from the Monaco editor (part of the VSCode Project) such as code formatting and different color schemes such as dark mode.

Schema Aware Autocomplete And Linting

While editing your GraphQL type definitions in GraphQL Architect you’ll have access to smart schema-aware autocomplete suggestions, taking into account the types and shape of your schema. Just use ctrl-space to trigger the autocomplete suggestions, powered by the GraphQL Language Services library and Monaco GraphQL.


As you use the editor, your type definitions are continuously parsed, offering linting and syntax checking, helping to find errors in your schema as you edit.

Adding Custom Logic With Cypher

So far we’ve seen how to use the generated CRUD operations provided by GraphQL Architect, but what if we want to add custom logic to our API? Custom logic can be defined using the @cypher GraphQL schema directive. By annotating fields in our GraphQL type definitions using the @cypher schema directive we can map custom Cypher queries to fields in the GraphQL schema.

Here we add a float scalar field average which computes the average rating across all movies that an actor has acted in:


We can also use @cypher schema directives to define object fields. Here we compute similar movies by looking at common actors, a simple graph recommendation query:


You can learn more about adding custom logic with the @cyher GraphQL schema directive in the neo4j-graphql.js documentation.

Run Local GraphQL Server


Running a local GraphQL server is powered by Apollo Server and the neo4j-graphql.js library. However, the specifics of running a Node.js GraphQL server are abstracted away with GraphQL Architect, allowing you to focus on the design of your API and your application.

Once you’ve designed your GraphQL type definitions, click the “Start GraphQL Server” button in the sidebar menu in GraphQL Architect. This will start a local API that you can query using the built-in GraphiQL window in GraphQL Architect. Or build an application against the endpoint using Apollo Client or other GraphQL client tooling.

Using With Cloud Databases


Of course, sometimes we’ll want to be able to develop and test our GraphQL API with a Neo4j instance hosted in the cloud, either on Neo4j Sandbox, Neo4j Aura, or running somewhere else.

To do this, create a remote database in Neo4j Desktop, by clicking on the “Add Database” button and selecting “Connect To Remote DBMS”. Then you’ll be able to input your connection credentials and connect it to Neo4j Desktop. Once activated in Neo4j Desktop, GraphQL Architect will connect and you’ll be able to use all of the features of GraphQL Architect that you could with a local database.

Deploy And Export Your GraphQL API

GraphQL Architect is great for developing and querying your GraphQL API locally. When you’re ready to export and deploy your API, just click the Deploy button.


Currently, you can export your API application as a new project (including the Node.js code required to run the application) or update a project created with the create-grandstack-app CLI. We’ve just started to scratch the surface of deployment options for GraphQL Architect. If there’s a service you’d like to see added as a deployment target please let us know!

Send Us Your Feedback!

We’d love to know if you have any feedback while using GraphQL Architect. Is there a feature you’d like to see added? Is there a bug you’d like to report? Just click the “Feedback” button and let us know. This kind of user feedback is invaluable for us as it allows us to continually improve.

Click the “Feedback” button to submit feedback and feature requests.

Resources

• Install GraphQL Architect in the Neo4j Desktop Graph Apps Gallery.
• Learn more about using GraphQL and Neo4j in the neo4j-graphql.js documentation and on GRANDstack.io
• Check out the GRANDstack Blog to keep up to date on what going on in the Neo4j GraphQL ecosystem.
• The book Fullstack GraphQL Applications with GRANDstack covers building GraphQL APIs using Neo4j from a full-stack perspective.


---

Introducing GraphQL Architect was originally published in Neo4j Developer Blog on Medium, where people are continuing the conversation by highlighting and responding to this story.