For the latest stable version, please use Spring Data Neo4j 7.4.0!spring-doc.cn

Conversions

Convention-based Mapping

The Neo4j Converter has a few conventions for mapping objects when no additional mapping metadata is provided. The conventions are:spring-doc.cn

  • The short Java class name is mapped to the primary label in the following manner: The class com.bigbank.SavingsAccount maps to the savingsAccount primary label.spring-doc.cn

  • The converter uses any Spring Converter registered with it to override the default mapping of object properties to node fields and values.spring-doc.cn

  • The fields of an object are used to convert to and from fields in the graph. Public JavaBean properties are not used.spring-doc.cn

  • If you have a single non-zero-argument constructor whose constructor argument names match top-level property names of node, that constructor is used. Otherwise, the zero-argument constructor is used. If there is more than one non-zero-argument constructor, an exception will be thrown.spring-doc.cn

We support a broad range of conversions out of the box. Find the list of supported cypher types in the official drivers manual: Type mapping.spring-doc.cn

Primitive types of wrapper types are equally supported.spring-doc.cn

Domain type Cypher type Maps directly to native type

java.lang.Booleanspring-doc.cn

Booleanspring-doc.cn

✔spring-doc.cn

boolean[]spring-doc.cn

List of Booleanspring-doc.cn

✔spring-doc.cn

java.lang.Longspring-doc.cn

Integerspring-doc.cn

✔spring-doc.cn

long[]spring-doc.cn

List of Integerspring-doc.cn

✔spring-doc.cn

java.lang.Doublespring-doc.cn

Floatspring-doc.cn

✔spring-doc.cn

double[]spring-doc.cn

List of Floatspring-doc.cn

✔spring-doc.cn

java.lang.Stringspring-doc.cn

Stringspring-doc.cn

✔spring-doc.cn

java.lang.String[]spring-doc.cn

List of Stringspring-doc.cn

✔spring-doc.cn

byte[]spring-doc.cn

ByteArrayspring-doc.cn

✔spring-doc.cn

java.lang.Bytespring-doc.cn

ByteArray with length 1spring-doc.cn

java.lang.Characterspring-doc.cn

String with length 1spring-doc.cn

char[]spring-doc.cn

List of String with length 1spring-doc.cn

java.util.Datespring-doc.cn

String formatted as ISO 8601 Date (yyyy-MM-dd’T’HH:mm:ss.SSSZ). Notice the Z: SDN will store all java.util.Date instances in UTC. If you require the time zone, use a type that supports it (i.e. ZoneDateTime) or store the zone as a separate property.spring-doc.cn

java.lang.Floatspring-doc.cn

Stringspring-doc.cn

float[]spring-doc.cn

List of Stringspring-doc.cn

java.lang.Integerspring-doc.cn

Integerspring-doc.cn

int[]spring-doc.cn

List of Integerspring-doc.cn

java.util.Localespring-doc.cn

String formatted as BCP 47 language tagspring-doc.cn

java.lang.Shortspring-doc.cn

Integerspring-doc.cn

short[]spring-doc.cn

List of Integerspring-doc.cn

java.math.BigDecimalspring-doc.cn

Stringspring-doc.cn

java.math.BigIntegerspring-doc.cn

Stringspring-doc.cn

java.time.LocalDatespring-doc.cn

Datespring-doc.cn

✔spring-doc.cn

java.time.OffsetTimespring-doc.cn

Timespring-doc.cn

✔spring-doc.cn

java.time.LocalTimespring-doc.cn

LocalTimespring-doc.cn

✔spring-doc.cn

java.time.ZonedDateTimespring-doc.cn

DateTimespring-doc.cn

✔spring-doc.cn

java.time.LocalDateTimespring-doc.cn

LocalDateTimespring-doc.cn

✔spring-doc.cn

java.time.OffsetDateTimespring-doc.cn

DateTimespring-doc.cn

java.time.Instantspring-doc.cn

DateTimespring-doc.cn

java.util.TimeZonespring-doc.cn

Stringspring-doc.cn

java.time.ZoneIdspring-doc.cn

Stringspring-doc.cn

java.time.Periodspring-doc.cn

Durationspring-doc.cn

java.time.Durationspring-doc.cn

Durationspring-doc.cn

org.neo4j.driver.types.IsoDurationspring-doc.cn

Durationspring-doc.cn

✔spring-doc.cn

org.neo4j.driver.types.Pointspring-doc.cn

Pointspring-doc.cn

✔spring-doc.cn

org.springframework.data.neo4j.types.GeographicPoint2dspring-doc.cn

Point with CRS 4326spring-doc.cn

org.springframework.data.neo4j.types.GeographicPoint3dspring-doc.cn

Point with CRS 4979spring-doc.cn

org.springframework.data.neo4j.types.CartesianPoint2dspring-doc.cn

Point with CRS 7203spring-doc.cn

org.springframework.data.neo4j.types.CartesianPoint3dspring-doc.cn

Point with CRS 9157spring-doc.cn

org.springframework.data.geo.Pointspring-doc.cn

Point with CRS 4326 and x/y corresponding to lat/longspring-doc.cn

Instances of Enumspring-doc.cn

String (The name value of the enum)spring-doc.cn

Instances of Enum[]spring-doc.cn

List of String (The name value of the enum)spring-doc.cn

java.net.URLspring-doc.cn

Stringspring-doc.cn

java.net.URIspring-doc.cn

Stringspring-doc.cn

java.util.UUIDspring-doc.cn

Stringspring-doc.cn

Custom conversions

For attributes of a given type

If you prefer to work with your own types in the entities or as parameters for @Query annotated methods, you can define and provide a custom converter implementation. First you have to implement a GenericConverter and register the types your converter should handle. For entity property type converters you need to take care of converting your type to and from a Neo4j Java Driver Value. If your converter is supposed to work only with custom query methods in the repositories, it is sufficient to provide the one-way conversion to the Value type.spring-doc.cn

Example of a custom converter implementation
public class MyCustomTypeConverter implements GenericConverter {

	@Override
	public Set<ConvertiblePair> getConvertibleTypes() {
		Set<ConvertiblePair> convertiblePairs = new HashSet<>();
		convertiblePairs.add(new ConvertiblePair(MyCustomType.class, Value.class));
		convertiblePairs.add(new ConvertiblePair(Value.class, MyCustomType.class));
		return convertiblePairs;
	}

	@Override
	public Object convert(Object source, TypeDescriptor sourceType, TypeDescriptor targetType) {
		if (MyCustomType.class.isAssignableFrom(sourceType.getType())) {
			// convert to Neo4j Driver Value
			return convertToNeo4jValue(source);
		} else {
			// convert to MyCustomType
			return convertToMyCustomType(source);
		}
	}

}

To make SDN aware of your converter, it has to be registered in the Neo4jConversions. To do this, you have to create a @Bean with the type org.springframework.data.neo4j.core.convert.Neo4jConversions. Otherwise, the Neo4jConversions will get created in the background with the internal default converters only.spring-doc.cn

Example of a custom converter implementation
@Bean
public Neo4jConversions neo4jConversions() {
	Set<GenericConverter> additionalConverters = Collections.singleton(new MyCustomTypeConverter());
	return new Neo4jConversions(additionalConverters);
}

If you need multiple converters in your application, you can add as many as you need in the Neo4jConversions constructor.spring-doc.cn

For specific attributes only

If you need conversions only for some specific attributes, we provide @ConvertWith. This is an annotation that can be put on attributes of both entities (@Node) and relationship properties (@RelationshipProperties) It defines a Neo4jPersistentPropertyConverter via the converter attribute and an optional Neo4jPersistentPropertyConverterFactory to construct the former. With an implementation of Neo4jPersistentPropertyConverter all specific conversions for a given type can be addressed. In addition, @ConvertWith also provides converterRef for referencing any Spring bean in the application context implementing Neo4jPersistentPropertyConverter. The referenced bean will be preferred over constructing a new converter.spring-doc.cn

We provide @DateLong and @DateString as meta-annotated annotations for backward compatibility with Neo4j-OGM schemes not using native types. Those are meta annotated annotations building on the concept above.spring-doc.cn

Composite properties

With @CompositeProperty, attributes of type Map<String, Object> or Map<? extends Enum, Object> can be stored as composite properties. All entries inside the map will be added as properties to the node or relationship containing the property. Either with a configured prefix or prefixed with the name of the property. While we only offer that feature for maps out of the box, you can Neo4jPersistentPropertyToMapConverter and configure it as the converter to use on @CompositeProperty. A Neo4jPersistentPropertyToMapConverter needs to know how a given type can be decomposed to and composed back from a map.spring-doc.cn