Object Mapping

[injectives]

The 5.28.5 driver release includes a new preview feature that we refer to as Object Mapping or, sometimes, Value Mapping.

Its main objective is to simplify reading Neo4j Cypher values to Java values, including support for reading Neo4j Cypher maps to Java objects automatically via constructor instantiation. It also supports creating Neo4j Cypher maps from java.lang.Record instances.

Note that mapping to and from Java objects is an alternative to accessing the user-defined values in a org.neo4j.driver.types.MapAccessor. If Object Graph Mapping (OGM) is needed, please use a higher level solution built on top of the driver, like Spring Data Neo4j.

org.neo4j.driver.Value

The following new method has been introduced to org.neo4j.driver.Value:

<T> T as(Class<T> targetClass)

It maps the value to the given type providing that is it supported.

Basic Mapping

Supported destination types depend on the value org.neo4j.driver.types.Type, please see the supported mappings below.

• TypeSystem#BOOLEAN -> boolean, Boolean
• TypeSystem#BYTES -> byte[]
• TypeSystem#STRING -> String, char, Character
• TypeSystem#INTEGER -> long, Long, int, Integer, short, Short, double, Double, float, Float
• TypeSystem#FLOAT -> long, Long, int, Integer, double, Double, float, Float
• TypeSystem#PATH -> Path
• TypeSystem#POINT -> Point
• TypeSystem#DATE -> LocalDate
• TypeSystem#TIME -> OffsetTime
• TypeSystem#LOCAL_TIME -> LocalTime
• TypeSystem#LOCAL_DATE_TIME -> LocalDateTime
• TypeSystem#DATE_TIME -> ZonedDateTime, OffsetDateTime
• TypeSystem#DURATION -> IsoDuration, java.time.Period (only when seconds = 0 and nanoseconds = 0 and no overflow happens), java.time.Duration (only when months = 0 and days = 0 and no overflow happens)
• TypeSystem#NULL -> null
• TypeSystem#LIST -> List, T[] as long as list elements may be mapped to the array component type (for example, char[], boolean[], String[], long[], int[], short[], double[], float[])
• TypeSystem#MAP -> Map
• TypeSystem#NODE -> Node
• TypeSystem#RELATIONSHIP -> Relationship

Object Mapping

Mapping of user-defined properties to user-defined types is supported for the following value types:

• TypeSystem#NODE
• TypeSystem#RELATIONSHIP
• TypeSystem#MAP

Example (using the Neo4j Movies Database):

// assuming the following Java record
public record Movie(String title, String tagline, long released) {}
// the nodes may be mapped to Movie instances
var movies = driver.executableQuery("MATCH (movie:Movie) RETURN movie")
        .execute()
        .records()
        .stream()
        .map(record -> record.get("movie").as(Movie.class))
        .toList();
}

The mapping is done by matching user-defined property names to target type constructor parameters. Therefore, the constructor parameters must either have org.neo4j.driver.mapping.Property annotation or have a matching name that is available at runtime (note that the constructor parameter names are typically changed by the compiler unless either the compiler -parameters option is used or they belong to the cannonical constructor of java.lang.Record). The name matching is case-sensitive.

Additionally, the org.neo4j.driver.mapping.Property annotation may be used when mapping a property with a different name to java.lang.Record cannonical constructor parameter.

The constructor selection criteria is the following (top priority first):

• Maximum matching properties.
• Minimum mismatching properties.

The constructor search is done in the order defined by the java.lang.Class#getDeclaredConstructors and is finished either when a full match is found with no mismatches or once all constructors have been visited.

At least 1 property match must be present for mapping to work.

A null value is used for arguments that don't have a matching property. If the argument does not accept null value (this includes primitive types), an alternative constructor that excludes it must be available.

Example with optional property (using the Neo4j Movies Database):

// assuming the following Java record
public record Person(String name, long born) {
    // alternative constructor for values that don't have 'born' property available
    public Person(@Property("name") String name) {
        this(name, -1);
    }
}
// the nodes may be mapped to Person instances
var persons = driver.executableQuery("MATCH (person:Person) RETURN person")
        .execute()
        .records()
        .stream()
        .map(record -> record.get("person").as(Person.class))
        .toList();

Types with generic parameters defined at the class level are not supported. However, constructor arguments with specific types are permitted.

Example (using the Neo4j Movies Database):

// assuming the following Java record
public record Acted(List<String> roles) {}
// the relationships may be mapped to Acted instances
var actedList = driver.executableQuery("MATCH ()-[acted:ACTED_IN]-() RETURN acted")
        .execute()
        .records()
        .stream()
        .map(record -> record.get("acted").as(Acted.class))
        .toList();

On the contrary, the following record would not be mapped because the type information is insufficient:

public record Acted<T>(List<T> roles) {}

Wildcard type value is not supported.

org.neo4j.driver.Record

The following new method has been introduced to org.neo4j.driver.Record:

<T> T as(Class<T> targetClass)

It maps values of this record to properties of the given type providing that is it supported.

Example (using the Neo4j Movies Database):

// assuming the following Java record
public record MovieInfo(String title, String director, List<String> actors) {}
// the record values may be mapped to MovieInfo instances
var movies = driver.executableQuery("MATCH (actor:Person)-[:ACTED_IN]->(movie:Movie)<-[:DIRECTED]-(director:Person) RETURN movie.title as title, director.name AS director, collect(actor.name) Ators")
        .execute()
        .records()
        .stream()
        .map(record -> record.as(MovieInfo.class))
        .toList();
}

It follows the same set of rules and has the same requirements as described in the Object Mapping Value section above.

org.neo4j.driver.Values

The following new method has been added to org.neo4j.driver.Values:

Value value(java.lang.Record record)

It returns a map value based on record components of a given java.lang.Record.

Example (similar to the Neo4j Movies Database):

// assuming the following Java record
public record Movie(String title, String tagline, long released) {}
// a new movie may be created in the following way
var movie = new Movie("title", "tagline", 2025);
var movieValue = Values.value(movie);
driver.executableQuery("CREATE (:Movie $movie)")
         .withParameters(Map.of("movie", movieValue))
         .execute();

Because the driver methods accepting a Map<String, Object> as query parameters automatically map values to value instances, it is possible to avoid mapping movie explicitly:

var movie = new Movie("title", "tagline", 2025);
driver.executableQuery("CREATE (:Movie $movie)")
         .withParameters(Map.of("movie", movie))
         .execute();

Assuming movie titles being unique, it is possible to update the created movie in the following way:

var updatedMovie = new Movie("title", "updated tagline", 2024);
driver.executableQuery("""
                 MATCH (movie:Movie {title: $movie.title})
                 SET movie += $movie
                 """)
         .withParameters(Map.of("movie", updatedMovie))
         .execute();

The Property annotation may be used to override the record component name.

public record Movie(String title, String tagline, @Property("releasedYear") long released) {}

Note that those record components that have null value will be excluded from the map value.

It is also important to understand that sending all properties over network may not always be desirable and will depend on a use-case.

In addition, please note that while this mapping allows nested structures, like map of maps, there may be limitations on how those are supported by the database. Please read the Neo4j Cypher Manual for more up-to-date details. For example, at the time of writing, it is not possible to store maps as properties (see the following page).

This new mapping as also available via the Value value(Object value) method, but with a note that it is still in preview status, not GA status.