Neo4j-KGBuilder: Visual Knowledge Graphs with Neo4j, Spring Boot and Vue

What Neo4j-KGBuilder Is Built to Solve

Neo4j-KGBuilder addresses the gap between storing data in a graph database and building a graph through code or a query console. It combines a Spring Boot backend, a Vue 2.7 interface, Neo4j graph storage and D3.js visualization so a user can create entities and relationships on a canvas. The intended audience includes knowledge-graph learners, instructors and developers assembling a small demonstration or prototype without first designing a complete frontend.

The project separates graph data from application metadata. Neo4j holds the graph itself, while the SQL database stores the domain list, category tree, node details, image indexes and feedback records. This design makes the graph available through the intended Neo4j model while leaving supporting records in relational storage. All graph access is described as passing through `Neo4jUtil` in `kgBuilder-base`, which executes Cypher.

Neo4j-KGBuilder covers more than manual node creation. Its documented scope includes CSV and spreadsheet imports, CSV and PNG exports, external MySQL data sources, ER modeling, bulk node creation and a natural-language retrieval interface. That breadth makes it a candidate for prototyping several graph-oriented workflows, although the README does not describe multi-user authorization, tenant isolation, production backup procedures or deployment automation.

Canvas Editing and Graph Data Flow

The primary interface presents the current graph on a draggable canvas. A user can switch to a crosshair cursor and create a node at a chosen position. Selecting a node opens a circular menu for editing, lazy expansion, appending children, connecting a relationship or deleting the node. A double click changes the node name. Node color and size are configurable, and coordinate changes are saved so a refresh does not discard the manual layout.

A connection is created by entering connection mode, selecting another node and supplying a relationship name. The graph model permits several differently named relationships between the same pair of nodes, rather than forcing a single relationship type per pair. Nodes can also carry rich text and image attachments, with details presented on hover. These features keep common graph construction work in the browser while persistence is handled through the backend.

The application distinguishes graph records from SQL metadata, but that split creates an operational consequence. Restarting with the default H2 configuration clears the metadata database, even if Neo4j still contains graph records. A durable deployment therefore needs the documented MySQL profile and correct initialization settings. The README also states that file uploads must be readable by the Neo4j process, particularly for Docker or remote deployment. This is a specific deployment constraint, not a general claim about the interface.

CSV, Spreadsheet and Database Import Paths

Neo4j-KGBuilder accepts triple-oriented files with the column order `node-relationship-node`. The documented example is:

刘德华,出演,无间道
刘德华,演唱,忘情水

The importer supports `.xlsx`, `.xls` and `.csv`. Spreadsheet processing is attributed to Apache POI in the backend technology list. Input files must use UTF-8 without a BOM; otherwise Chinese text can be corrupted. The upload location comes from `neo4j.file.location`, and that directory must be visible to the Neo4j service process.

External database ingestion follows a different path. A user registers an external MySQL connection, browses its tables and columns, selects columns and marks identifiers, then connects components in a flow designer and labels relationship types. According to the README, rows are extracted with pagination and combined into entity nodes, attribute nodes and relationships. This is more involved than uploading a triple file, but it is appropriate when source records already describe graph semantics.

The CSV route is predictable for a small prototype because its expected column order is documented. The MySQL workflow offers richer integration but requires more modeling decisions before execution. The README does not state transaction semantics, duplicate handling, rollback behavior or how partially imported files are reconciled, so those points require verification before using either importer with production data.

Installing Neo4j-KGBuilder on the Documented Default Branch

The build requires JDK 17 or later, Maven 3.6 or later, Node.js 14 or later and Neo4j 5.x. Neo4j 3.x and 4.x are explicitly unsupported because the implementation uses Neo4j 5's `elementId` behavior. MySQL is optional, since the default profile uses an in-memory H2 database.

Clone and build the multi-module project as follows. The build skips tests, so it should not be treated as evidence that the test suite passed.

git clone https://github.com/MiracleTanC/Neo4j-KGBuilder.git
cd Neo4j-KGBuilder
mvn clean install -DskipTests

Configure the Neo4j connection before starting `kgBuilder-pro/src/main/java/com/warmer/Application.java`. The README gives these environment variables:

export NEO4J_URL=bolt://localhost:7687
export NEO4J_USERNAME=neo4j
export NEO4J_PASSWORD=你的密码

The backend listens on port `8081`. Start it from the IDE or run the packaged jar. The `dev` profile uses H2 and an `always` SQL initialization policy, which means schema recreation occurs during startup. For durable SQL metadata, execute `sql/kg_builder.sql` against the target MySQL database and activate the `mysql` profile.

source sql/kg_builder.sql;
export SPRING_PROFILES_ACTIVE=mysql
export DB_USERNAME=root
export DB_PASSWORD=你的密码

The `mysql` profile fixes `SQL_INIT_MODE` to `never`. The README warns against combining MySQL with the H2-oriented `always` policy because doing so can clear and recreate SQL data. That warning should be checked in the active configuration before startup.

Running the Vue Client and Creating a First Graph

Install and start the frontend from `kgBuilder-ui`. Development mode defaults to port `80` and proxies `/kg-api/*` to the backend. The backend and frontend therefore need to be online together.

cd kgBuilder-ui
npm install
npm run serve

Open `http://localhost:80`, select or create a graph on the left, and create a node on the canvas. After selecting the node, choose the connection action, select a second node and enter a relationship name. The project documentation says node coordinates are persisted automatically.

For a production frontend build, the documented output is `dist/`:

cd kgBuilder-ui
npm run build

Port `80` may already be in use. The README identifies `kgBuilder-ui/vue.config.js` as the file containing the development server port configuration, or alternatively suggests running with administrator privileges. It does not document authentication, deployment behind a reverse proxy, HTTPS configuration or browser support policy, so a first deployment should be limited to a controlled environment.

ER Modeling and the Limits of Question Answering

The ER tool uses X6 and JsPlumb to define entities, attributes and relationships in a structural view. A configured ER flow can then generate the corresponding graph structure. This is useful when the intended graph comes from a relational model, although the README does not publish the generated node property schema in enough detail to assess every mapping decision.

The question-answering feature has a narrower purpose. The README states that HanLP segments a natural-language question, keywords are matched against graph nodes and matching results are returned. It labels the implementation demonstration-grade and presents it as an example that could precede an LLM integration. Accordingly, it should not be described as a general reasoning engine or treated as evidence of semantic answer quality.

A project needing exact graph traversal, deterministic filtering or database-backed retrieval may find the CSV, API and Neo4j query paths more predictable. The question-answering interface is better viewed as a proof of concept. The documentation does not specify indexing, ranking, synonym handling, ambiguity resolution, prompt behavior or evaluation data.

Maintenance, Upgrades and License Boundaries

The repository is not archived, and the last push was on 2026-08-27. No GitHub releases are listed, so there is no documented release channel or published version number to use for upgrades. The default branch is `dev`, which is relevant when cloning: the quick-start command uses the repository URL without a branch argument, so the checked-out branch should be confirmed before building.

The README identifies Apache License 2.0 through its license badge and `LICENSE` link. Repository metadata lists the license as unknown, so the actual `LICENSE` file should be reviewed when distribution or integration requirements matter. This article does not provide legal advice or infer obligations beyond the stated license identification.

Compatibility is the clearest upgrade constraint. The project requires Neo4j 5.x and is not compatible with Neo4j 3.x or 4.x according to the README. Java 17, Spring Boot 3.5.8, Vue 2.7 and D3.js v5 form the documented stack. Because no releases are published, upgrades currently depend on repository changes rather than a documented migration sequence. The relevant first check is therefore the configuration and database state before rebuilding, especially the active SQL profile and `SQL_INIT_MODE`.

Editorial conclusion

Neo4j-KGBuilder is appropriate for developers who need a visual prototype or a teaching environment, especially when their data fits nodes, attributes and relationships. It is a poor fit for production deployments that require durable metadata by default, sophisticated natural-language answers, or compatibility with Neo4j 3.x and 4.x. Before adoption, verify Neo4j 5 availability, persistent MySQL configuration, file visibility and the exact behavior of your planned import workflow.

Frequently asked questions

Official sources

1. Issues
2. MiracleTanC/Neo4j-KGBuilder on GitHub
3. README