Neo4j Adds One-Line Graph Embeddings API to Aura Graph Analytics

A single call instead of a configuration hill

Graph embeddings compress a node and the structure around it into a vector, so that nodes with similar surroundings end up with similar vectors. Neo4j says embeddings have been the fastest-growing use case for Neo4j Graph Data Science (GDS), its graph analytics and machine learning library, over the last few years.

The company argues that creating them used to be a job for data scientists, who had to decide which model fits a graph, which configuration fits a use case and what each parameter does. Neo4j contrasts this with text embeddings, where one call returns vectors in a few lines of code, and says graphs deserve the same treatment.

The new API is available in preview in the GDS Python client, version 2.2 or later. The call gives every node in a graph loaded into an Aura Graph Analytics session an embedding. Under the hood it runs FastRP, which Neo4j describes as a fast and highly scalable algorithm, with defaults the company chose and which, it says, work well in most cases.

Defaults, dials and what happens to the data

Users who want control can set the embedding size and other FastRP settings, name the property that stores the embeddings, embed only some node labels or relationship types, and fix a random_seed for reproducible results.

The embeddings are added to the in-memory graph as a new node property, called embedding unless another name is chosen. Nothing is written to the database. From there, users can stream the vectors into pandas, pass them to another algorithm in the same session, such as kNN to find similar nodes or k-means to cluster them, or write them back to the database if the session is attached to one.

The call fails if the graph already has a property with the same name, so existing embeddings are not overwritten by accident. Neo4j suggests giving each set of embeddings its own property name while experimenting. In production or scheduled pipelines, users can drop the property first with fail_if_missing=False, which makes the step safe if the property does not exist yet.

Training embeddings on your own properties and classes

The default embedding captures only where each node sits in the overall shape of the graph. Properties stored on the nodes play no part. For cases where those properties or already classified nodes matter, Neo4j offers gds.embedding.train, which trains a GraphSAGE model that learns from node properties and from known classes.

Users point the call at the property holding the known classes (target_label and target_property), the properties to learn from (feature_properties) and a model name. According to Neo4j, a small classifier trained on the known classes teaches the encoder which patterns matter. The encoder and the classifier can both be tuned, along with the number of epochs and the batch size.

The saved encoder is then passed to create through the graph_encoder argument, which returns the workflow to a single call. Neo4j warns that the model has already seen its training examples, so results should be judged on nodes it did not train on. The trained model is a regular Aura Graph Analytics model and can be stored with gds.model.store in the project's model catalog for use in a later session.

Availability and what comes next

Aura Graph Analytics is available on the AuraDB Free tier, so the API can be tried without paying. Data does not have to live in Neo4j: nodes and relationships from a data warehouse, Databricks or a CSV file can be loaded into pandas DataFrames, and gds.graph.construct turns them into a graph in a standalone session. The documentation includes a quickstart that runs on Cora, a small citation graph shipped with the GDS Python client.

Both endpoints are in preview, so they may change. The API is available only in Aura Graph Analytics with GDS Python client 2.2 or later. Neo4j says it plans to add more capabilities for generating embeddings and putting them to work, and to bring the API to its Cypher API as well. It asks users for feedback via the Neo4j Community Forum.

Neo4j points to uses such as flagging accounts that resemble known fraudsters, recommending products based on similar customers, segmenting customers and feeding vectors into standard models to predict churn. It also says that for AI agents built on knowledge graphs, combining text embeddings with graph embeddings can find related entities that text alone would miss.