Accelerate Neo4j App Development With Low-Code Keymaker Framework

Using the Keymaker framework to build analytical query pipelines and APIs.

Keymaker is a recommendations framework that enhances the development of Neo4j-based applications by offering innovative next-best-action recommendations.

Its unique architecture, which distinctly separates the logic ‘engine’ from the user interface, ensures unparalleled flexibility in application design and functionality. It is a data model agnostic tool. It seamlessly integrates with Neo4j databases (versions 4.5.x and 5.x supported), allowing for the flexible configuration of analytical query pipelines tailored to specific business needs across diverse industries.

With Keymaker, each engine or query pipeline you develop is automatically equipped with a GraphQL API endpoint. This streamlines the development of user interfaces using frameworks like React, by eliminating the need for manually defining type definitions, queries, and mutations, allowing developers to concentrate on the business logic.

Keymaker High-Level Architecture

Keymaker’s architecture is built around three core components: the Admin Dashboard, the Admin API, and the Engine API. Together, these elements offer a comprehensive interface for seamless framework interaction:

  • Admin Dashboard: It is a user interface for establishing database connections, constructing analytical pipelines referred to as “engines” within Keymaker, and writing Cypher queries.
  • Admin API: This API facilitates user interaction with the framework.
  • Engine API: This API connects with your Neo4j database and exposes an endpoint that executes the engine.

The following diagram demonstrates this architecture.

Keymaker High-Level Architecture

Keymaker Key Features

Keymaker provides score-based recommendations to a user based on the business logic defined within an engine. Keymaker engines can execute recommendation / next-best-action logic using techniques like collaborative, content-based or rules-based filtering. It can also apply algorithms from Neo4j’s Graph Data Science Library ( )
for behavioral or community analysis.

Each engine consists of one or more phases(or steps), each with a specific purpose in the pipeline, and the phases have access to all of the engine inputs as Cypher parameters. Let’s break down the various engine phases available within Keymaker:

  • Discovery Phase: Initiates the search for potential results and assigns initial scores.
  • Boost Phase: Adjusts scores of previously discovered items based on custom criteria.
  • Exclude Phase: Excludes specific results based on defined conditions.
  • Diversity Phase: Ensures a diverse set of recommendations by limiting results based on an attribute.
  • Collection Phase: Prepares and stores complex data patterns for later use in the pipeline.
  • Write Phase: Analyzes and writes back results to the database without returning data.
  • GDS Create Phase: Utilizes GDS to create an in-memory graph for subsequent operations.
  • GDS Write Phase: Employs GDS algorithms to write updates back to Neo4j or adjust the in-memory graph.
  • GDS Drop Phase: Removes an in-memory graph created by GDS.

Here is an example of a content-based recommendation query pipeline for movies:

In this example, the engine is expecting a parameter to be passed which is the $startMovieTitle. Based on this parameter, the following business criteria will be evaluated.

We can now invoke this query pipeline using the recommendations API endpoint.

Here is a sample GraphQL query:

query {
engineID: "movies-content-based-recommendations"
params: { startMovieTitle: "Toy Story" }
first: 20
skip: 0
) {

As you can see, each response has been scored based on the different business criteria that were met against our defined parameter “Toy Story”.

Our recommendation engine has identified “Toy Story 2” as a top pick with an aggregated score of 16, reflecting its strong alignment with our selection criteria. This score is derived from matching genres (+3), featuring common actors such as Tom Hanks and Tim Allen (+2), high title similarity (+5), and recent release year relevance (+6). “The Pebble and the Penguin” follows with a score of 13, recognized for its genre match and release year, despite lacking in actor and title similarity contributions.

With Keymaker’s adaptive backend, our recommendation system seamlessly integrates diverse business criteria to tailor precise content suggestions and also provides explainability for the recommendations.

Note: At the end of the blog, we have video links available to set up keymaker locally on your machine and also run some sample recommendation query pipelines using the movies recommendation dataset.

Keymaker Benefits

  • Scoring & Explainability: Each engine can return a score that helps to stack rank the results, and it can also return an explanation of why the results were produced and which rules or filtering techniques were applied.
  • Dynamic Flexibility: Keymaker enables on-the-fly modifications to business logic, allowing for immediate examination of the results and A/B testing. This agility eliminates the need for service redeployment within the framework, streamlining the development and testing process.
  • Rapid Development: Keymaker simplifies your workflow by managing the GraphQL server, allowing you to focus only on defining the business logic within the engines without the overhead of server management. A GraphQL API end-point is created for each engine automatically, which makes it faster and easier to connect to these engines from a front-end/UI or another system.
  • Enhanced Readability: By organizing business logic into distinct phases, Keymaker significantly reduces query complexity and enhances readability. This structured approach facilitates easier understanding and maintenance of the business logic.
  • Extracting Visualization Paths: Engines can also return an aggregation of paths that map to the results so that the specific results can be visualized using Neo4j’s Bloom product.
  • Optimized Performance: Leveraging the official Neo4j GraphQL library, Keymaker is optimized for high performance. You can achieve greater throughput with Keymaker by using it with a Neo4j cluster and setting up multiple Keymaker instances pointing to the cluster.


Github Repo:
Official Documentation:
Keymaker Help Page:


How to Install Keymaker on Your Local Machine: A Step-by-Step Tutorial

Quick Start: Verify Your Keymaker Setup and Build Your First Query Pipelines

Keymaker Features Overview

Accelerate Neo4j App Development With Low-Code Framework was originally published in Neo4j Developer Blog on Medium, where people are continuing the conversation by highlighting and responding to this story.