haskell-neo4j-client-0.3.2.4: A Haskell neo4j client

Copyright(c) 2014 Antoni Silvestre
LicenseMIT
MaintainerAntoni Silvestre <antoni.silvestre@gmail.com>
Stabilityexperimental
Portabilityportable
Safe HaskellNone
LanguageHaskell98

Database.Neo4j

Contents

Description

Library to interact with the Neo4j REST API.

Synopsis

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 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

newAuthConnection :: Hostname -> Port -> Credentials -> IO Connection #

Create a new connection that can be manually closed with runResourceT using provided credentials for basic auth

withAuthConnection :: Hostname -> Port -> Credentials -> Neo4j a -> IO a #

Run a set of Neo4j commands in a single connection using provided credentials for basic auth

newSecureConnection :: Hostname -> Port -> IO Connection #

Create a new https connection that can be manually closed with runResourceT

withSecureConnection :: Hostname -> Port -> Neo4j a -> IO a #

Run a set of Neo4j commands in a single https connection

newSecureAuthConnection :: Hostname -> Port -> Credentials -> IO Connection #

Create a new https connection that can be manually closed with runResourceT using provided credentials for basic auth

withSecureAuthConnection :: Hostname -> Port -> Credentials -> Neo4j a -> IO a #

Run a set of Neo4j commands in a single https connection using provided credentials for basic auth

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

Instances

Monad Neo4j # 

Methods

(>>=) :: Neo4j a -> (a -> Neo4j b) -> Neo4j b #

(>>) :: Neo4j a -> Neo4j b -> Neo4j b #

return :: a -> Neo4j a #

fail :: String -> Neo4j a #

Functor Neo4j # 

Methods

fmap :: (a -> b) -> Neo4j a -> Neo4j b #

(<$) :: a -> Neo4j b -> Neo4j a #

Applicative Neo4j # 

Methods

pure :: a -> Neo4j a #

(<*>) :: Neo4j (a -> b) -> Neo4j a -> Neo4j b #

(*>) :: Neo4j a -> Neo4j b -> Neo4j b #

(<*) :: Neo4j a -> Neo4j b -> Neo4j a #

MonadIO Neo4j # 

Methods

liftIO :: IO a -> Neo4j a #

MonadThrow Neo4j # 

Methods

throwM :: Exception e => e -> Neo4j a #

MonadBase Neo4j Neo4j # 

Methods

liftBase :: Neo4j α -> Neo4j α #

Constructing and managing node/relationship properties

data Val #

Type for a single value of a Neo4j property

Instances

Eq Val # 

Methods

(==) :: Val -> Val -> Bool #

(/=) :: Val -> Val -> Bool #

Show Val # 

Methods

showsPrec :: Int -> Val -> ShowS #

show :: Val -> String #

showList :: [Val] -> ShowS #

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

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

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

newtype NodePath #

Constructors

NodePath 

Fields

Instances

Eq NodePath # 
Ord NodePath # 
Show NodePath # 
Generic NodePath # 

Associated Types

type Rep NodePath :: * -> * #

Methods

from :: NodePath -> Rep NodePath x #

to :: Rep NodePath x -> NodePath #

Hashable NodePath # 

Methods

hashWithSalt :: Int -> NodePath -> Int #

hash :: NodePath -> Int #

FromJSON IdPath #

How to decodify an IdPath from JSON

EntityIdentifier NodePath # 
NodeIdentifier NodePath # 
NodeBatchIdentifier NodePath # 
BatchEntity NodePath # 
type Rep NodePath # 
type Rep NodePath = D1 (MetaData "NodePath" "Database.Neo4j.Types" "haskell-neo4j-client-0.3.2.4-7alwluRyigX1pUlPDPCCwe" True) (C1 (MetaCons "NodePath" PrefixI True) (S1 (MetaSel (Just Symbol "runNodePath") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 Text)))

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 # 
Ord Relationship # 
Show Relationship # 
FromJSON Relationship #

JSON to Relationship

FromJSON FullPath #

How to decodify an IdPath from JSON

EntityIdentifier Relationship # 
RelIdentifier Relationship # 
Entity 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

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

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

newtype RelPath #

Constructors

RelPath 

Fields

Instances

Eq RelPath # 

Methods

(==) :: RelPath -> RelPath -> Bool #

(/=) :: RelPath -> RelPath -> Bool #

Ord RelPath # 
Show RelPath # 
Generic RelPath # 

Associated Types

type Rep RelPath :: * -> * #

Methods

from :: RelPath -> Rep RelPath x #

to :: Rep RelPath x -> RelPath #

Hashable RelPath # 

Methods

hashWithSalt :: Int -> RelPath -> Int #

hash :: RelPath -> Int #

FromJSON IdPath #

How to decodify an IdPath from JSON

EntityIdentifier RelPath # 
RelIdentifier RelPath # 
RelBatchIdentifier RelPath # 
BatchEntity RelPath # 
type Rep RelPath # 
type Rep RelPath = D1 (MetaData "RelPath" "Database.Neo4j.Types" "haskell-neo4j-client-0.3.2.4-7alwluRyigX1pUlPDPCCwe" True) (C1 (MetaCons "RelPath" PrefixI True) (S1 (MetaSel (Just Symbol "runRelPath") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 Text)))

Managing labels and getting nodes by label

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 

Instances

Eq Index # 

Methods

(==) :: Index -> Index -> Bool #

(/=) :: Index -> Index -> Bool #

Show Index # 

Methods

showsPrec :: Int -> Index -> ShowS #

show :: Index -> String #

showList :: [Index] -> ShowS #

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

Database version information