Database.Neo4j

Library to interact with the Neo4j REST API.

How to use this library

In order to start issuing commands to neo4j you must establish a connection, in order to do that you can use the function withConnection:

withConnection "127.0.0.1" 7474 $ do
   neo <- createNode M.empty
   cypher <- createNode M.empty
   r <- createRelationship "KNOWS" M.empty neo cypher
   ...

Also most calls have a batch analogue version, with batch mode you can issue several commands to Neo4j at once. In order to issue batches you must use the Database.Neo4j.Batch monad, parameters in batch mode can be actual entities already obtained by issuing regular commands or previous batch commands, or even batch futures, that is you can refer to entities created in the same batch, for instance:

withConnection "127.0.0.1" 7474 $ do
   g <- B.runBatch $ do
       neo <- B.createNode M.empty
       cypher <- B.createNode M.empty
       B.createRelationship "KNOWS" M.empty neo cypher
   ...

As you can see this example does the same thing the previous one does but it will be more efficient as it will be translated into only one request to the database.

Batch commands return a Database.Neo4j.Graph object that holds all the information about relationships, nodes and their labels that can be inferred from running a batch command.

Another example with batches would be for instance remove all the nodes in a Database.Neo4j.Graph object

withConnection "127.0.0.1" 7474 $ do
   ...
   B.runBatch $ mapM_ B.deleteNode (G.getNodes gp)

For more information about batch commands and graph objects you can refer to their Database.Neo4j.Batch and Database.Neo4j.Graph modules.

Properties are hashmaps with key Text and values a custom type called PropertyValue. This custom type tries to use Haskell's type system to match property values to what Neo4j expects, we only allow Int64, Double, Bool and Text like values and one-level arrays of these. The only restriction we cannot guarantee with these types is that arrays of values must be of the same type.

In order to create a PropertyValue from a literal or a value of one of the allowed types you can use the newval function or the operator |: to create pairs of key values:

import qualified Data.HashMap.Lazy as M

myval = newval False
someProperties = M.fromList ["mytext" |: ("mytext" :: T.Text),
                            "textarrayprop" |: ["a" :: T.Text, "", "adeu"],
                            "int" |: (-12 :: Int64),
                            "intarray" |: [1 :: Int64, 2],
                            "double" |: (-12.23 :: Double),
                            "doublearray" |: [0.1, -12.23 :: Double],
                            "bool" |: False,
                            "aboolproparray" |: [False, True]
                           ]

When unexpected errors occur a Neo4jException will be raised, sometimes with a specific exception value like for instance Neo4jNoEntityException, or more generic ones like Neo4jHttpException or Neo4jParseException if the server returns something totally unexpected. (I'm sure there's still work to do here preparing the code to return more specific exceptions for known scenarios)

About Cypher support for now we allow sending queries with parameters, the result is a collection of column headers and JSON data values, the Graph object has the function addCypher that tries to find nodes and relationships in a cypher query result and insert them in a Database.Neo4j.Graph object

import qualified Database.Neo4j.Cypher as C

withConnection host port $ do
   ...
   -- Run a cypher query with parameters
   res <- C.cypher "CREATE (n:Person { name : {name} }) RETURN n" M.fromList [("name", C.newparam ("Pep" :: T.Text))]

   -- Get all nodes and relationships that this query returned and insert them in a Graph object
   let graph = G.addCypher (C.fromSuccess res) G.empty

   -- Get the column headers
   let columnHeaders = C.cols $ C.fromSuccess res

   -- Get the rows of JSON values received
   let values = C.vals $ C.fromSuccess res

Connection handling objects

data Connection

Type for a connection

type Hostname = ByteString

type Port = Int

newConnection :: Hostname -> Port -> IO Connection

Create a new connection that can be manually closed with runResourceT

withConnection :: Hostname -> Port -> Neo4j a -> IO a

Run a set of Neo4j commands in a single connection

Main monadic type to handle sequences of commands to Neo4j

newtype Neo4j a

Neo4j monadic type to be able to sequence neo4j commands in a connection

Constructors

Neo4j

Fields

runNeo4j :: Connection -> IO a

Instances

Monad Neo4j

Functor Neo4j

Applicative Neo4j

MonadThrow Neo4j

MonadIO Neo4j

MonadBase Neo4j Neo4j

Constructing and managing node/relationship properties

data Val

Type for a single value of a Neo4j property

Constructors

IntVal Int64

BoolVal Bool

TextVal Text

DoubleVal Double

Instances

Eq Val

Show Val

ToJSON Val

Specifying how to convert property single values to JSON

FromJSON Val

JSON to single property values

data PropertyValue

Wrapping type for a Neo4j single property or array of properties Using these types allows type checking for only correct properties that is int, double, string, boolean and single typed arrays of these, also nulls are not allowed

Constructors

ValueProperty Val

ArrayProperty [Val]

Instances

Eq PropertyValue

Show PropertyValue

ToJSON PropertyValue

Specifying how to convert property values to JSON

FromJSON PropertyValue

JSON to property values

newval :: PropertyValueConstructor a => a -> PropertyValue

(|:) :: PropertyValueConstructor a => Text -> a -> (Text, PropertyValue)

This operator allows easy construction of property value types from literals

type Properties = HashMap Text PropertyValue

We use hashmaps to represent Neo4j properties

emptyProperties :: HashMap Text PropertyValue

Shortcut for emtpy properties

getProperties :: Entity a => a -> Neo4j Properties

Retrieve relationship/node properties from the DB, if the entity is not present it will raise an exception If the entity doesn't exist it will raise a Neo4jNoEntity exception

getProperty :: Entity a => a -> Text -> Neo4j (Maybe PropertyValue)

Get a relationship/node property If the 404 is because the parent entity doesn't exist we'll raise the corresponding Neo4jNoEntity If the 404 is because there is no property just return Nothing

setProperties :: Entity a => a -> Properties -> Neo4j a

Set all relationship/node properties If the entity doesn't exist it will raise a Neo4jNoEntity exception

setProperty :: Entity a => a -> Text -> PropertyValue -> Neo4j a

Set a relationship/node property If the entity doesn't exist it will raise a Neo4jNoEntity exception

deleteProperties :: Entity a => a -> Neo4j a

Delete all relationship/node properties If the entity doesn't exist it will raise a Neo4jNoEntity exception

deleteProperty :: Entity a => a -> Text -> Neo4j a

Delete a relationship/node property If the entity doesn't exist it will raise a Neo4jNoEntity exception

Managing nodes

data Node

Representation of a Neo4j node, has a location URI and a set of properties

Instances

Eq Node

Show Node

FromJSON Node

JSON to Node

EntityIdentifier Node

NodeIdentifier Node

NodeBatchIdentifier Node

BatchEntity Node

NodeBatchIdentifier (BatchFuture Node)

BatchEntity (BatchFuture Node)

getNodeProperties :: Node -> Properties

Get the properties of a node

createNode :: Properties -> Neo4j Node

Create a new node with a set of properties

getNode :: NodeIdentifier a => a -> Neo4j (Maybe Node)

Refresh a node entity with the contents in the DB

deleteNode :: NodeIdentifier a => a -> Neo4j ()

Delete a node, if the node has relationships it will raise a Neo4jNonOrphanNodeDeletion

nodeId :: Node -> ByteString

Get the ID of a node

nodePath :: Node -> NodePath

runNodeIdentifier :: NodeIdentifier a => a -> ByteString

class NodeIdentifier a where

Methods

getNodePath :: a -> NodePath

Instances

NodeIdentifier Integer

NodeIdentifier ByteString

NodeIdentifier NodePath

NodeIdentifier Node

newtype NodePath

Constructors

NodePath

Fields

runNodePath :: Text

Instances

Eq NodePath

Show NodePath

Generic NodePath

Hashable NodePath

EntityIdentifier NodePath

NodeIdentifier NodePath

NodeBatchIdentifier NodePath

BatchEntity NodePath

type Rep NodePath

Managing relationships

data Relationship

Type for a Neo4j relationship, has a location URI, a relationship type, a starting node and a destination node

Instances

Eq Relationship

Show Relationship

FromJSON Relationship

JSON to Relationship

EntityIdentifier Relationship

RelIdentifier Relationship

RelBatchIdentifier Relationship

BatchEntity Relationship

RelBatchIdentifier (BatchFuture Relationship)

BatchEntity (BatchFuture Relationship)

data Direction

Relationship direction

Constructors

Outgoing

Incoming

Any

type RelationshipType = Text

Type for a relationship type description

createRelationship :: RelationshipType -> Properties -> Node -> Node -> Neo4j Relationship

Create a new relationship with a type and a set of properties

getRelationship :: RelIdentifier a => a -> Neo4j (Maybe Relationship)

Refresh a relationship entity with the contents in the DB

deleteRelationship :: RelIdentifier a => a -> Neo4j ()

Delete a relationship

getRelationships :: Node -> Direction -> [RelationshipType] -> Neo4j [Relationship]

Get all relationships for a node, if the node has disappeared it will raise an exception

relId :: Relationship -> ByteString

Get the ID of a relationship

relPath :: Relationship -> RelPath

allRelationshipTypes :: Neo4j [RelationshipType]

Gets all relationship types in the DB

getRelProperties :: Relationship -> Properties

Get the properties of a relationship

getRelType :: Relationship -> RelationshipType

Get the type of a relationship

runRelIdentifier :: RelIdentifier a => a -> ByteString

getRelationshipFrom :: Relationship -> Neo4j Node

Get the "node from" from a relationship from the DB | Raises Neo4jNoEntityException if the node (and thus the relationship) does not exist any more

getRelationshipTo :: Relationship -> Neo4j Node

Get the "node to" from a relationship from the DB | Raises Neo4jNoEntityException if the node (and thus the relationship) does not exist any more

class RelIdentifier a where

Methods

getRelPath :: a -> RelPath

Instances

RelIdentifier Integer

RelIdentifier ByteString

RelIdentifier RelPath

RelIdentifier Relationship

newtype RelPath

Constructors

RelPath

Fields

runRelPath :: Text

Instances

Eq RelPath

Show RelPath

Generic RelPath

Hashable RelPath

EntityIdentifier RelPath

RelIdentifier RelPath

RelBatchIdentifier RelPath

BatchEntity RelPath

type Rep RelPath

Managing labels and getting nodes by label

class EntityIdentifier a where

Methods

getEntityPath :: a -> EntityPath

Instances

EntityIdentifier Text

EntityIdentifier RelPath

EntityIdentifier Relationship

EntityIdentifier NodePath

EntityIdentifier Node

type Label = Text

Type for a label

allLabels :: Neo4j [Label]

Get all labels in the DB

getLabels :: Node -> Neo4j [Label]

Retrieve all labels for a node, if the node doesn't exist already it will raise an exception | Raises Neo4jNoEntityException if the node doesn't exist

getNodesByLabelAndProperty :: Label -> Maybe (Text, PropertyValue) -> Neo4j [Node]

Get all nodes using a label and a property

addLabels :: [Label] -> Node -> Neo4j ()

Add labels to a node | Raises Neo4jNoEntityException if the node doesn't exist

changeLabels :: [Label] -> Node -> Neo4j ()

Change node labels | Raises Neo4jNoEntityException if the node doesn't exist

removeLabel :: Label -> Node -> Neo4j ()

Remove a label for a node | Raises Neo4jNoEntityException if the node doesn't exist

Indexes

data Index

Type for an index

Constructors

Index

Fields

indexLabel :: Label

indexProperties :: [Text]

Instances

Eq Index

Show Index

FromJSON Index

JSON to Index

createIndex :: Label -> Text -> Neo4j Index

Creates an index for a label and a property

getIndexes :: Label -> Neo4j [Index]

Gets all indexes for a label

dropIndex :: Label -> Text -> Neo4j ()

Drop and index

Exceptions

data Neo4jException

Exceptions this library can raise

Constructors

Neo4jHttpException String

Neo4jNonOrphanNodeDeletionException ByteString

Neo4jNoEntityException ByteString

Neo4jUnexpectedResponseException Status

Neo4jNoSuchProperty Text

Neo4jBatchException ByteString

Neo4jParseException String

TransactionEndedExc

Instances

Eq Neo4jException

Show Neo4jException

Exception Neo4jException

Typeable * Neo4jException