Module org.neo4j.driver
Package org.neo4j.driver

Interface Value

All Superinterfaces:
MapAccessor, MapAccessorWithDefaultValue
All Known Subinterfaces:
InternalValue
All Known Implementing Classes:
BooleanValue, BytesValue, DateTimeValue, DateValue, DurationValue, EntityValueAdapter, FloatValue, IntegerValue, ListValue, LocalDateTimeValue, LocalTimeValue, MapValue, NodeValue, NullValue, NumberValueAdapter, ObjectValueAdapter, PathValue, PointValue, RelationshipValue, StringValue, TimeValue, UnsupportedDateTimeValue, ValueAdapter
@Immutable public interface Value extends MapAccessor, MapAccessorWithDefaultValue
A unit of data that adheres to the Neo4j type system.

This interface describes a number of isType methods along with typeValue methods. The first set of these correlate with types from the Neo4j Type System and are used to determine which Neo4j type is represented. The second set of methods perform coercions to Java types (wherever possible). For example, a common String value should be tested for using isString and extracted using stringValue.

Navigating a tree structure

Because Neo4j often handles dynamic structures, this interface is designed to help you handle such structures in Java. Specifically, Value lets you navigate arbitrary tree structures without having to resort to type casting.

Given a tree structure like: 

 
 {
   users : [
     { name : "Anders" },
     { name : "John" }
   ]
 }

You can retrieve the name of the second user, John, like so: 

 
 String username = value.get("users").get(1).get("name").asString();

You can also easily iterate over the users: 

 
 List<String> names = new LinkedList<>();
 for(Value user : value.get("users").values() )
 {
     names.add(user.get("name").asString());
 }
Since:
1.0

  • Method Details

    • size

      int size()
      If the underlying value is a collection type, return the number of values in the collection.

      For TypeSystem.LIST() list} values, this will return the size of the list.

      For map values, this will return the number of entries in the map.

      For node and TypeSystem.RELATIONSHIP() relationship} values, this will return the number of properties.

      For path values, this returns the length (number of relationships) in the path.

      Specified by:
      size in interface MapAccessor
      Returns:
      the number of values in an underlying collection

    • isEmpty

      boolean isEmpty()
      If this value represents a list or map, test if the collection is empty.
      Returns:
      true if size() is 0, otherwise false

    • keys

      Iterable<String> keys()
      If the underlying value supports key-based indexing, return an iterable of the keys in the map, this applies to map, node and TypeSystem.RELATIONSHIP() relationship} values.
      Specified by:
      keys in interface MapAccessor
      Returns:
      the keys in the value

    • get

      Value get(int index)
      Retrieve the value at the given index
      Parameters:
      index - the index of the value
      Returns:
      the value or a NullValue if the index is out of bounds
      Throws:
      ClientException - if record has not been initialized

    • type

      Type type()
      Returns:
      The type of this value as defined in the Neo4j type system

    • hasType

      boolean hasType(Type type)
      Test if this value is a value of the given type
      Parameters:
      type - the given type
      Returns:
      type.isTypeOf(this)

    • isTrue

      boolean isTrue()
      Returns:
      true if the value is a Boolean value and has the value True.

    • isFalse

      boolean isFalse()
      Returns:
      true if the value is a Boolean value and has the value False.

    • isNull

      boolean isNull()
      Returns:
      true if the value is a Null, otherwise false

    • asObject

      Object asObject()
      This returns a java standard library representation of the underlying value, using a java type that is "sensible" given the underlying type. The mapping for common types is as follows:

      Note that the types in TypeSystem refers to the Neo4j type system where TypeSystem.INTEGER() and TypeSystem.FLOAT() are both 64-bit precision. This is why these types return java Long and Double, respectively.

      Returns:
      the value as a Java Object.
      Throws:
      DateTimeException - if zone information supplied by server is not supported by driver runtime. Applicable to datetime values only.

    • computeOrDefault

      <T> T computeOrDefault(Function<Value,T> mapper, T defaultValue)
      Apply the mapping function on the value if the value is not a NullValue, or the default value if the value is a NullValue.
      Type Parameters:
      T - The return type
      Parameters:
      mapper - The mapping function defines how to map a Value to T.
      defaultValue - the value to return if the value is a NullValue
      Returns:
      The value after applying the given mapping function or the default value if the value is NullValue.

    • asBoolean

      boolean asBoolean()
      Returns:
      the value as a Java boolean, if possible.
      Throws:
      Uncoercible - if value types are incompatible.

    • asBoolean

      boolean asBoolean(boolean defaultValue)
      Parameters:
      defaultValue - return this value if the value is a NullValue.
      Returns:
      the value as a Java boolean, if possible.
      Throws:
      Uncoercible - if value types are incompatible.

    • asByteArray

      byte[] asByteArray()
      Returns:
      the value as a Java byte array, if possible.
      Throws:
      Uncoercible - if value types are incompatible.

    • asByteArray

      byte[] asByteArray(byte[] defaultValue)
      Parameters:
      defaultValue - default to this value if the original value is a NullValue
      Returns:
      the value as a Java byte array, if possible.
      Throws:
      Uncoercible - if value types are incompatible.

    • asString

      String asString()
      Returns:
      the value as a Java String, if possible.
      Throws:
      Uncoercible - if value types are incompatible.

    • asString

      String asString(String defaultValue)
      Parameters:
      defaultValue - return this value if the value is null.
      Returns:
      the value as a Java String, if possible
      Throws:
      Uncoercible - if value types are incompatible.

    • asNumber

      Number asNumber()
      Returns:
      the value as a Java Number, if possible.
      Throws:
      Uncoercible - if value types are incompatible.

    • asLong

      long asLong()
      Returns a Java long if no precision is lost in the conversion.
      Returns:
      the value as a Java long.
      Throws:
      LossyCoercion - if it is not possible to convert the value without loosing precision.
      Uncoercible - if value types are incompatible.

    • asLong

      long asLong(long defaultValue)
      Returns a Java long if no precision is lost in the conversion.
      Parameters:
      defaultValue - return this default value if the value is a NullValue.
      Returns:
      the value as a Java long.
      Throws:
      LossyCoercion - if it is not possible to convert the value without loosing precision.
      Uncoercible - if value types are incompatible.

    • asInt

      int asInt()
      Returns a Java int if no precision is lost in the conversion.
      Returns:
      the value as a Java int.
      Throws:
      LossyCoercion - if it is not possible to convert the value without loosing precision.
      Uncoercible - if value types are incompatible.

    • asInt

      int asInt(int defaultValue)
      Returns a Java int if no precision is lost in the conversion.
      Parameters:
      defaultValue - return this default value if the value is a NullValue.
      Returns:
      the value as a Java int.
      Throws:
      LossyCoercion - if it is not possible to convert the value without loosing precision.
      Uncoercible - if value types are incompatible.

    • asDouble

      double asDouble()
      Returns a Java double if no precision is lost in the conversion.
      Returns:
      the value as a Java double.
      Throws:
      LossyCoercion - if it is not possible to convert the value without loosing precision.
      Uncoercible - if value types are incompatible.

    • asDouble

      double asDouble(double defaultValue)
      Returns a Java double if no precision is lost in the conversion.
      Parameters:
      defaultValue - default to this value if the value is a NullValue.
      Returns:
      the value as a Java double.
      Throws:
      LossyCoercion - if it is not possible to convert the value without loosing precision.
      Uncoercible - if value types are incompatible.

    • asFloat

      float asFloat()
      Returns a Java float if no precision is lost in the conversion.
      Returns:
      the value as a Java float.
      Throws:
      LossyCoercion - if it is not possible to convert the value without loosing precision.
      Uncoercible - if value types are incompatible.

    • asFloat

      float asFloat(float defaultValue)
      Returns a Java float if no precision is lost in the conversion.
      Parameters:
      defaultValue - default to this value if the value is a NullValue
      Returns:
      the value as a Java float.
      Throws:
      LossyCoercion - if it is not possible to convert the value without loosing precision.
      Uncoercible - if value types are incompatible.

    • asList

      List<Object> asList()
      If the underlying type can be viewed as a list, returns a java list of values, where each value has been converted using asObject().
      Returns:
      the value as a Java list of values, if possible
      See Also:

    • asList

      List<Object> asList(List<Object> defaultValue)
      If the underlying type can be viewed as a list, returns a java list of values, where each value has been converted using asObject().
      Parameters:
      defaultValue - default to this value if the value is a NullValue
      Returns:
      the value as a Java list of values, if possible
      See Also:

    • asList

      <T> List<T> asList(Function<Value,T> mapFunction)
      Type Parameters:
      T - the type of target list elements
      Parameters:
      mapFunction - a function to map from Value to T. See Values for some predefined functions, such as Values.ofBoolean(), Values.ofList(Function).
      Returns:
      the value as a list of T obtained by mapping from the list elements, if possible
      See Also:

    • asList

      <T> List<T> asList(Function<Value,T> mapFunction, List<T> defaultValue)
      Type Parameters:
      T - the type of target list elements
      Parameters:
      mapFunction - a function to map from Value to T. See Values for some predefined functions, such as Values.ofBoolean(), Values.ofList(Function).
      defaultValue - default to this value if the value is a NullValue
      Returns:
      the value as a list of T obtained by mapping from the list elements, if possible
      See Also:

    • asEntity

      Entity asEntity()
      Returns:
      the value as a Entity, if possible.
      Throws:
      Uncoercible - if value types are incompatible.

    • asNode

      Node asNode()
      Returns:
      the value as a Node, if possible.
      Throws:
      Uncoercible - if value types are incompatible.

    • asRelationship

      Relationship asRelationship()
      Returns:
      the value as a Relationship, if possible.
      Throws:
      Uncoercible - if value types are incompatible.

    • asPath

      Path asPath()
      Returns:
      the value as a Path, if possible.
      Throws:
      Uncoercible - if value types are incompatible.

    • asLocalDate

      LocalDate asLocalDate()
      Returns:
      the value as a LocalDate, if possible.
      Throws:
      Uncoercible - if value types are incompatible.

    • asOffsetTime

      OffsetTime asOffsetTime()
      Returns:
      the value as a OffsetTime, if possible.
      Throws:
      Uncoercible - if value types are incompatible.

    • asLocalTime

      LocalTime asLocalTime()
      Returns:
      the value as a LocalTime, if possible.
      Throws:
      Uncoercible - if value types are incompatible.

    • asLocalDateTime

      LocalDateTime asLocalDateTime()
      Returns:
      the value as a LocalDateTime, if possible.
      Throws:
      Uncoercible - if value types are incompatible.

    • asOffsetDateTime

      OffsetDateTime asOffsetDateTime()
      Returns:
      the value as a OffsetDateTime, if possible.
      Throws:
      Uncoercible - if value types are incompatible.
      DateTimeException - if zone information supplied by server is not supported by driver runtime.

    • asZonedDateTime

      ZonedDateTime asZonedDateTime()
      Returns:
      the value as a ZonedDateTime, if possible.
      Throws:
      Uncoercible - if value types are incompatible.
      DateTimeException - if zone information supplied by server is not supported by driver runtime.

    • asIsoDuration

      IsoDuration asIsoDuration()
      Returns:
      the value as a IsoDuration, if possible.
      Throws:
      Uncoercible - if value types are incompatible.

    • asPoint

      Point asPoint()
      Returns:
      the value as a Point, if possible.
      Throws:
      Uncoercible - if value types are incompatible.

    • asLocalDate

      LocalDate asLocalDate(LocalDate defaultValue)
      Parameters:
      defaultValue - default to this value if the value is a NullValue
      Returns:
      the value as a LocalDate, if possible.
      Throws:
      Uncoercible - if value types are incompatible.

    • asOffsetTime

      OffsetTime asOffsetTime(OffsetTime defaultValue)
      Parameters:
      defaultValue - default to this value if the value is a NullValue
      Returns:
      the value as a OffsetTime, if possible.
      Throws:
      Uncoercible - if value types are incompatible.

    • asLocalTime

      LocalTime asLocalTime(LocalTime defaultValue)
      Parameters:
      defaultValue - default to this value if the value is a NullValue
      Returns:
      the value as a LocalTime, if possible.
      Throws:
      Uncoercible - if value types are incompatible.

    • asLocalDateTime

      LocalDateTime asLocalDateTime(LocalDateTime defaultValue)
      Parameters:
      defaultValue - default to this value if the value is a NullValue
      Returns:
      the value as a LocalDateTime, if possible.
      Throws:
      Uncoercible - if value types are incompatible.

    • asOffsetDateTime

      OffsetDateTime asOffsetDateTime(OffsetDateTime defaultValue)
      Parameters:
      defaultValue - default to this value if the value is a NullValue
      Returns:
      the value as a OffsetDateTime, if possible.
      Throws:
      Uncoercible - if value types are incompatible.

    • asZonedDateTime

      ZonedDateTime asZonedDateTime(ZonedDateTime defaultValue)
      Parameters:
      defaultValue - default to this value if the value is a NullValue
      Returns:
      the value as a ZonedDateTime, if possible.
      Throws:
      Uncoercible - if value types are incompatible.

    • asIsoDuration

      IsoDuration asIsoDuration(IsoDuration defaultValue)
      Parameters:
      defaultValue - default to this value if the value is a NullValue
      Returns:
      the value as a IsoDuration, if possible.
      Throws:
      Uncoercible - if value types are incompatible.

    • asPoint

      Point asPoint(Point defaultValue)
      Parameters:
      defaultValue - default to this value if the value is a NullValue
      Returns:
      the value as a Point, if possible.
      Throws:
      Uncoercible - if value types are incompatible.

    • asMap

      Map<String,Object> asMap(Map<String,Object> defaultValue)
      Return as a map of string keys and values converted using asObject().

      This is equivalent to calling asMap(Function, Map) with Values.ofObject().

      Parameters:
      defaultValue - default to this value if the value is a NullValue
      Returns:
      the value as a Java map

    • asMap

      <T> Map<String,T> asMap(Function<Value,T> mapFunction, Map<String,T> defaultValue)
      Type Parameters:
      T - the type of map values
      Parameters:
      mapFunction - a function to map from Value to T. See Values for some predefined functions, such as Values.ofBoolean(), Values.ofList(Function).
      defaultValue - default to this value if the value is a NullValue
      Returns:
      the value as a map from string keys to values of type T obtained from mapping he original map values, if possible
      See Also:

    • as

      @Preview(name="Object mapping") default <T> T as(Class<T> targetClass)
      Maps this value to the given type providing that is it supported.

      Basic Mapping

      Supported destination types depend on the value Type, please see the table below for more details.

      Supported Mappings
      Value Type Supported Target Types
      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, Period (only when seconds = 0 and nanoseconds = 0 and no overflow happens), 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:

      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();

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

      The mapping is done by matching user-defined property names to target type constructor parameters. Therefore, the constructor parameters must either have 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 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):

      1. Maximum matching properties.
      2. Minimum mismatching properties.
      The constructor search is done in the order defined by the 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.

      The mapping only works for types with directly accessible constructors, not interfaces or abstract types.

      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.
      Type Parameters:
      T - the target type to map to
      Parameters:
      targetClass - the target class to map to
      Returns:
      the mapped value
      Throws:
      Uncoercible - when mapping to the target type is not possible
      LossyCoercion - when mapping cannot be achieved without losing precision
      Since:
      5.28.5
      See Also:

    • equals

      boolean equals(Object other)
      Overrides:
      equals in class Object

    • hashCode

      int hashCode()
      Overrides:
      hashCode in class Object

    • toString

      String toString()
      Overrides:
      toString in class Object