Package org.neo4j.graphdb

Interface Transaction

All Superinterfaces:
AutoCloseable
public interface Transaction extends AutoCloseable
A programmatically handled transaction.

All database operations that access the graph, indexes, or the schema must be performed in a transaction.

If you attempt to access the graph outside of a transaction, those operations will throw NotInTransactionException.

Here's the idiomatic use of programmatic transactions in Neo4j: 

 
 try ( Transaction tx = graphDb.beginTx() )
 {
     // operations on the graph
     // ...

     tx.commit();
 }

Let's walk through this example line by line. First we retrieve a Transaction object by invoking the GraphDatabaseService.beginTx() factory method. This creates a new transaction which has internal state to keep track of whether the current transaction is successful. Then we wrap all operations that modify the graph in a try-finally block with the transaction as resource. At the end of the block, we invoke the tx.commit() method to commit that the transaction.

If an exception is raised in the try-block, commit() will never be invoked and the transaction will be roll backed. This is very important: unless commit() is invoked, the transaction will fail upon close(). A transaction can be explicitly rolled back by invoking the rollback() method.

Read operations inside of a transaction will also read uncommitted data from the same transaction.

All ResourceIterables that were returned from operations executed inside a transaction will be automatically closed when the transaction is committed or rolled back. Note however, that the ResourceIterator should be closed as soon as possible if you don't intend to exhaust the iterator.

Note that transactions should be used by a single thread only. It is generally not safe to use a transaction from multiple threads. Doing so will lead to undefined behavior.

  • Method Details

    • createNode

      Node createNode()
      Creates a new node.
      Returns:
      the created node.

    • createNode

      Node createNode(Label... labels)
      Creates a new node and adds the provided labels to it.
      Parameters:
      labels - labels to add to the created node.
      Returns:
      the created node.

    • getNodeById

      @Deprecated(since="5.0", forRemoval=true) Node getNodeById(long id)
      Deprecated, for removal: This API element is subject to removal in a future version.
      in favor of getNodeByElementId(String).
      Looks up a node by id. Please note: Neo4j reuses its internal ids when nodes and relationships are deleted, which means it's bad practice to refer to them this way. Instead, use application generated ids.
      Parameters:
      id - the id of the node
      Returns:
      the node with id id if found
      Throws:
      NotFoundException - if not found

    • getNodeByElementId

      Node getNodeByElementId(String elementId)
      Looks up a node by element id. Please note: Neo4j reuses its internal ids when nodes and relationships are deleted, which means it's bad practice to refer to them this way. Instead, use application generated ids.
      Parameters:
      elementId - the id of the node
      Returns:
      the node with id id if found
      Throws:
      NotFoundException - if not found

    • getRelationshipById

      @Deprecated(since="5.0", forRemoval=true) Relationship getRelationshipById(long id)
      Deprecated, for removal: This API element is subject to removal in a future version.
      in favor of getRelationshipByElementId(String).
      Looks up a relationship by id. Please note: Neo4j reuses its internal ids when nodes and relationships are deleted, which means it's bad practice to refer to them this way. Instead, use application generated ids.
      Parameters:
      id - the id of the relationship
      Returns:
      the relationship with id id if found
      Throws:
      NotFoundException - if not found

    • getRelationshipByElementId

      Relationship getRelationshipByElementId(String elementId)
      Looks up a relationship by element id. Please note: Neo4j reuses its internal ids when nodes and relationships are deleted, which means it's bad practice to refer to them this way. Instead, use application generated ids.
      Parameters:
      elementId - the id of the relationship
      Returns:
      the relationship with id id if found
      Throws:
      NotFoundException - if not found

    • bidirectionalTraversalDescription

      BidirectionalTraversalDescription bidirectionalTraversalDescription()
      Factory method for bidirectional traversal descriptions.
      Returns:
      a new BidirectionalTraversalDescription

    • traversalDescription

      TraversalDescription traversalDescription()
      Factory method for unidirectional traversal descriptions.
      Returns:
      a new TraversalDescription

    • execute

      Result execute(String query) throws QueryExecutionException
      Executes a query and returns an iterable that contains the result set. This method is the same as execute(String, java.util.Map) with an empty parameters-map.
      Parameters:
      query - The query to execute
      Returns:
      A Result that contains the result set.
      Throws:
      QueryExecutionException - If the Query contains errors

    • execute

      Result execute(String query, Map<String,Object> parameters) throws QueryExecutionException
      Executes a query and returns an iterable that contains the result set.
      Parameters:
      query - The query to execute
      parameters - Parameters for the query
      Returns:
      A Result that contains the result set
      Throws:
      QueryExecutionException - If the Query contains errors

    • getAllLabelsInUse

      Iterable<Label> getAllLabelsInUse()
      Returns all labels currently in the underlying store. Labels are added to the store the first time they are used. This method guarantees that it will return all labels currently in use. Please take care that the returned ResourceIterable is closed correctly and as soon as possible inside your transaction to avoid potential blocking of write operations.
      Returns:
      all labels in the underlying store.

    • getAllRelationshipTypesInUse

      Iterable<RelationshipType> getAllRelationshipTypesInUse()
      Returns all relationship types currently in the underlying store. Relationship types are added to the underlying store the first time they are used in a successfully committed node.createRelationshipTo(...). This method guarantees that it will return all relationship types currently in use.
      Returns:
      all relationship types in the underlying store

    • getAllLabels

      Iterable<Label> getAllLabels()
      Returns all labels currently in the underlying store. Labels are added to the store the first time they are used. This method guarantees that it will return all labels currently in use. However, it may also return more than that (e.g. it can return "historic" labels that are no longer used). Please take care that the returned ResourceIterable is closed correctly and as soon as possible inside your transaction to avoid potential blocking of write operations.
      Returns:
      all labels in the underlying store.

    • getAllRelationshipTypes

      Iterable<RelationshipType> getAllRelationshipTypes()
      Returns all relationship types currently in the underlying store. Relationship types are added to the underlying store the first time they are used in a successfully committed node.createRelationshipTo(...). Note that this method is guaranteed to return all known relationship types, but it does not guarantee that it won't return more than that (e.g. it can return "historic" relationship types that no longer have any relationships in the node space).
      Returns:
      all relationship types in the underlying store

    • getAllPropertyKeys

      Iterable<String> getAllPropertyKeys()
      Returns all property keys currently in the underlying store. This method guarantees that it will return all property keys currently in use. However, it may also return more than that (e.g. it can return "historic" labels that are no longer used). Please take care that the returned ResourceIterable is closed correctly and as soon as possible inside your transaction to avoid potential blocking of write operations.
      Returns:
      all property keys in the underlying store.

    • findNodes

      ResourceIterator<Node> findNodes(Label label, String key, String template, StringSearchMode searchMode)
      Returns all nodes having a given label, and a property value of type String or Character matching the given value template and search mode.

      If an online index is found, it will be used to look up the requested nodes. If no indexes exist for the label/property combination, the database will scan all labeled nodes looking for matching property values.

      The search mode and value template are used to select nodes of interest. The search mode can be one of

      • EXACT: The value has to match the template exactly. This is the same behavior as findNode(Label, String, Object).
      • PREFIX: The value must have a prefix matching the template.
      • SUFFIX: The value must have a suffix matching the template.
      • CONTAINS: The value must contain the template. Only exact matches are supported.
      Note that in Neo4j the Character 'A' will be treated the same way as the String 'A'.

      Please ensure that the returned ResourceIterator is closed correctly and as soon as possible inside your transaction to avoid potential blocking of write operations.

      Parameters:
      label - consider nodes with this label
      key - required property key
      template - required property value template
      searchMode - search mode to use for finding matches
      Returns:
      an iterator containing all matching nodes. See ResourceIterator for responsibilities.

    • findNodes

      ResourceIterator<Node> findNodes(Label label, Map<String,Object> propertyValues)
      Returns all nodes having the label, and the wanted property values. If an online index is found, it will be used to look up the requested nodes.

      If no indexes exist for the label with all provided properties, the database will scan all labeled nodes looking for matching nodes.

      Note that equality for values do not follow the rules of Java. This means that the number 42 is equals to all other 42 numbers, regardless of whether they are encoded as Integer, Long, Float, Short, Byte or Double.

      Same rules follow Character and String - the Character 'A' is equal to the String 'A'.

      Finally - arrays also follow these rules. An int[] {1,2,3} is equal to a double[] {1.0, 2.0, 3.0}

      Please ensure that the returned ResourceIterator is closed correctly and as soon as possible inside your transaction to avoid potential blocking of write operations.

      Parameters:
      label - consider nodes with this label
      propertyValues - required property key-value combinations
      Returns:
      an iterator containing all matching nodes. See ResourceIterator for responsibilities.

    • findNodes

      ResourceIterator<Node> findNodes(Label label, String key1, Object value1, String key2, Object value2, String key3, Object value3)
      Returns all nodes having the label, and the wanted property values. If an online index is found, it will be used to look up the requested nodes.

      If no indexes exist for the label with all provided properties, the database will scan all labeled nodes looking for matching nodes.

      Note that equality for values do not follow the rules of Java. This means that the number 42 is equals to all other 42 numbers, regardless of whether they are encoded as Integer, Long, Float, Short, Byte or Double.

      Same rules follow Character and String - the Character 'A' is equal to the String 'A'.

      Finally - arrays also follow these rules. An int[] {1,2,3} is equal to a double[] {1.0, 2.0, 3.0}

      Please ensure that the returned ResourceIterator is closed correctly and as soon as possible inside your transaction to avoid potential blocking of write operations.

      Parameters:
      label - consider nodes with this label
      key1 - required property key1
      value1 - required property value of key1
      key2 - required property key2
      value2 - required property value of key2
      key3 - required property key3
      value3 - required property value of key3
      Returns:
      an iterator containing all matching nodes. See ResourceIterator for responsibilities.

    • findNodes

      ResourceIterator<Node> findNodes(Label label, String key1, Object value1, String key2, Object value2)
      Returns all nodes having the label, and the wanted property values. If an online index is found, it will be used to look up the requested nodes.

      If no indexes exist for the label with all provided properties, the database will scan all labeled nodes looking for matching nodes.

      Note that equality for values do not follow the rules of Java. This means that the number 42 is equals to all other 42 numbers, regardless of whether they are encoded as Integer, Long, Float, Short, Byte or Double.

      Same rules follow Character and String - the Character 'A' is equal to the String 'A'.

      Finally - arrays also follow these rules. An int[] {1,2,3} is equal to a double[] {1.0, 2.0, 3.0}

      Please ensure that the returned ResourceIterator is closed correctly and as soon as possible inside your transaction to avoid potential blocking of write operations.

      Parameters:
      label - consider nodes with this label
      key1 - required property key1
      value1 - required property value of key1
      key2 - required property key2
      value2 - required property value of key2
      Returns:
      an iterator containing all matching nodes. See ResourceIterator for responsibilities.

    • findNode

      Node findNode(Label label, String key, Object value)
      Equivalent to findNodes(Label, String, Object), however it must find no more than one node or it will throw an exception.
      Parameters:
      label - consider nodes with this label
      key - required property key
      value - required property value
      Returns:
      the matching node or null if none could be found
      Throws:
      MultipleFoundException - if more than one matching node is found

    • findNodes

      ResourceIterator<Node> findNodes(Label label, String key, Object value)
      Returns all nodes having the label, and the wanted property value. If an online index is found, it will be used to look up the requested nodes.

      If no indexes exist for the label/property combination, the database will scan all labeled nodes looking for the property value.

      Note that equality for values do not follow the rules of Java. This means that the number 42 is equals to all other 42 numbers, regardless of whether they are encoded as Integer, Long, Float, Short, Byte or Double.

      Same rules follow Character and String - the Character 'A' is equal to the String 'A'.

      Finally - arrays also follow these rules. An int[] {1,2,3} is equal to a double[] {1.0, 2.0, 3.0}

      Please ensure that the returned ResourceIterator is closed correctly and as soon as possible inside your transaction to avoid potential blocking of write operations.

      Parameters:
      label - consider nodes with this label
      key - required property key
      value - required property value
      Returns:
      an iterator containing all matching nodes. See ResourceIterator for responsibilities.

    • findNodes

      ResourceIterator<Node> findNodes(Label label)
      Returns all nodes with a specific label. Please take care that the returned ResourceIterator is closed correctly and as soon as possible inside your transaction to avoid potential blocking of write operations.
      Parameters:
      label - the Label to return nodes for.
      Returns:
      an iterator containing all nodes matching the label. See ResourceIterator for responsibilities.

    • findRelationships

      ResourceIterator<Relationship> findRelationships(RelationshipType relationshipType, String key, String template, StringSearchMode searchMode)
      Returns all relationships having the type, and a property value of type String or Character matching the given value template and search mode.

      If an online index is found, it will be used to look up the requested relationships. If no indexes exist for the type/property combination, the database will scan all relationships of a specific type looking for matching property values.

      The search mode and value template are used to select relationships of interest. The search mode can be one of

      • EXACT: The value has to match the template exactly. This is the same behavior as findRelationships(RelationshipType, String, Object).
      • PREFIX: The value must have a prefix matching the template.
      • SUFFIX: The value must have a suffix matching the template.
      • CONTAINS: The value must contain the template. Only exact matches are supported.
      Note that in Neo4j the Character 'A' will be treated the same way as the String 'A'.

      Please ensure that the returned ResourceIterator is closed correctly and as soon as possible inside your transaction to avoid potential blocking of write operations.

      Parameters:
      relationshipType - consider relationships with this type
      key - required property key
      template - required property value template
      searchMode - search mode to use for finding matches
      Returns:
      an iterator containing all matching relationships. See ResourceIterator for responsibilities.

    • findRelationships

      ResourceIterator<Relationship> findRelationships(RelationshipType relationshipType, Map<String,Object> propertyValues)
      Returns all relationships having the type, and the wanted property values. If an online index is found, it will be used to look up the requested relationships.

      If no indexes exist for the type with all provided properties, the database will scan all relationships of a specific type looking for matching values.

      Note that equality for values do not follow the rules of Java. This means that the number 42 is equals to all other 42 numbers, regardless of whether they are encoded as Integer, Long, Float, Short, Byte or Double.

      Same rules follow Character and String - the Character 'A' is equal to the String 'A'.

      Finally - arrays also follow these rules. An int[] {1,2,3} is equal to a double[] {1.0, 2.0, 3.0}

      Please ensure that the returned ResourceIterator is closed correctly and as soon as possible inside your transaction to avoid potential blocking of write operations.

      Parameters:
      relationshipType - consider relationships with this type
      propertyValues - required property key-value combinations
      Returns:
      an iterator containing all matching relationships. See ResourceIterator for responsibilities.

    • findRelationships

      ResourceIterator<Relationship> findRelationships(RelationshipType relationshipType, String key1, Object value1, String key2, Object value2, String key3, Object value3)
      Returns all relationships having the type, and the wanted property values. If an online index is found, it will be used to look up the requested relationships.

      If no indexes exist for the type with all provided properties, the database will scan all relationships of a specific type looking for matching values.

      Note that equality for values do not follow the rules of Java. This means that the number 42 is equals to all other 42 numbers, regardless of whether they are encoded as Integer, Long, Float, Short, Byte or Double.

      Same rules follow Character and String - the Character 'A' is equal to the String 'A'.

      Finally - arrays also follow these rules. An int[] {1,2,3} is equal to a double[] {1.0, 2.0, 3.0}

      Please ensure that the returned ResourceIterator is closed correctly and as soon as possible inside your transaction to avoid potential blocking of write operations.

      Parameters:
      relationshipType - consider relationships with this type
      key1 - required property key1
      value1 - required property value of key1
      key2 - required property key2
      value2 - required property value of key2
      key3 - required property key3
      value3 - required property value of key3
      Returns:
      an iterator containing all matching relationships. See ResourceIterator for responsibilities.

    • findRelationships

      ResourceIterator<Relationship> findRelationships(RelationshipType relationshipType, String key1, Object value1, String key2, Object value2)
      Returns all relationships having the type, and the wanted property values. If an online index is found, it will be used to look up the requested relationships.

      If no indexes exist for the type with all provided properties, the database will scan all relationships of a specific type looking for matching values.

      Note that equality for values do not follow the rules of Java. This means that the number 42 is equals to all other 42 numbers, regardless of whether they are encoded as Integer, Long, Float, Short, Byte or Double.

      Same rules follow Character and String - the Character 'A' is equal to the String 'A'.

      Finally - arrays also follow these rules. An int[] {1,2,3} is equal to a double[] {1.0, 2.0, 3.0}

      Please ensure that the returned ResourceIterator is closed correctly and as soon as possible inside your transaction to avoid potential blocking of write operations.

      Parameters:
      relationshipType - consider relationships with this type
      key1 - required property key1
      value1 - required property value of key1
      key2 - required property key2
      value2 - required property value of key2
      Returns:
      an iterator containing all matching relationships. See ResourceIterator for responsibilities.

    • findRelationship

      Relationship findRelationship(RelationshipType relationshipType, String key, Object value)
      Equivalent to findRelationships(RelationshipType, String, Object), however it must find no more than one relationship or it will throw an exception.
      Parameters:
      relationshipType - consider relationships with this type
      key - required property key
      value - required property value
      Returns:
      the matching relationship or null if none could be found
      Throws:
      MultipleFoundException - if more than one matching relationship is found

    • findRelationships

      ResourceIterator<Relationship> findRelationships(RelationshipType relationshipType, String key, Object value)
      Returns all relationships having the type, and the wanted property value. If an online index is found, it will be used to look up the requested relationships.

      If no indexes exist for the type/property combination, the database will scan all relationships of a specific type looking for the property value.

      Note that equality for values do not follow the rules of Java. This means that the number 42 is equals to all other 42 numbers, regardless of whether they are encoded as Integer, Long, Float, Short, Byte or Double.

      Same rules follow Character and String - the Character 'A' is equal to the String 'A'.

      Finally - arrays also follow these rules. An int[] {1,2,3} is equal to a double[] {1.0, 2.0, 3.0}

      Please ensure that the returned ResourceIterator is closed correctly and as soon as possible inside your transaction to avoid potential blocking of write operations.

      Parameters:
      relationshipType - consider relationships with this type
      key - required property key
      value - required property value
      Returns:
      an iterator containing all matching relationships. See ResourceIterator for responsibilities.

    • findRelationships

      ResourceIterator<Relationship> findRelationships(RelationshipType relationshipType)
      Returns all relationships of a specific type. Please take care that the returned ResourceIterator is closed correctly and as soon as possible inside your transaction to avoid potential blocking of write operations.
      Parameters:
      relationshipType - the RelationshipType to return relationships for.
      Returns:
      an iterator containing all relationships with matching type. See ResourceIterator for responsibilities.
      Throws:
      IllegalStateException - if relationship index feature not enabled

    • terminate

      void terminate()
      Marks this transaction as terminated, which means that it will be, much like in the case of failure, unconditionally rolled back when close() is called. Once this method has been invoked, it doesn't matter if commit() ()} is invoked afterwards -- the transaction will still be rolled back. Additionally, terminating a transaction causes all subsequent operations carried out within that transaction to throw a TransactionTerminatedException. Note that, unlike the other transaction operations, this method can be called from different thread. When this method is called, it signals to terminate the transaction and returns immediately. Calling this method on an already closed transaction has no effect.

    • getAllNodes

      ResourceIterable<Node> getAllNodes()
      Returns all nodes in the graph.
      Returns:
      all nodes in the graph.

    • getAllRelationships

      ResourceIterable<Relationship> getAllRelationships()
      Returns all relationships in the graph.
      Returns:
      all relationships in the graph.

    • acquireWriteLock

      Lock acquireWriteLock(Entity entity)
      Acquires a write lock for entity for this transaction. The lock (returned from this method) can be released manually, but if not it's released automatically when the transaction finishes.
      Parameters:
      entity - the entity to acquire a lock for. If another transaction currently holds a write lock to that entity this call will wait until it's released.
      Returns:
      a Lock which optionally can be used to release this lock earlier than when the transaction finishes. If not released (with Lock.release() it's going to be released when the transaction finishes.

    • acquireReadLock

      Lock acquireReadLock(Entity entity)
      Acquires a read lock for entity for this transaction. The lock (returned from this method) can be released manually, but if not it's released automatically when the transaction finishes.
      Parameters:
      entity - the entity to acquire a lock for. If another transaction currently hold a write lock to that entity this call will wait until it's released.
      Returns:
      a Lock which optionally can be used to release this lock earlier than when the transaction finishes. If not released (with Lock.release() it's going to be released with the transaction finishes.

    • schema

      Schema schema()
      Returns the schema manager where all things related to schema, for example constraints and indexing on labels.
      Returns:
      the schema manager for this database.

    • commit

      void commit()
      Commit and close current transaction.

      When commit() is completed, all resources are released and no more changes are possible in this transaction.

    • rollback

      void rollback()
      Roll back and close current transaction. When rollback() is completed, all resources are released and no more changes are possible in this transaction

    • close

      void close()
      Close transaction. If commit() or rollback() have been called this does nothing. If none of them are called, the transaction will be rolled back.

      All ResourceIterables that where returned from operations executed inside this transaction will be automatically closed by this method in they were not closed before.

      This method comes from AutoCloseable so that a Transaction can participate in try-with-resource statements.