Beginnen met Graphs - Data in Neo4j laden met Kettle

Data in Neo4j laden

Update 2020-05-20: updates ivm installatie en algemene update voor de wijzigingen sinds de eerste versie van deze post uit begin 2018.  

Of je een ervaren Neo4j ontwikkelaar of analyst bent, of net begonnen bent met het verkennen van Neo4j, één van de eerste hindernissen die je moet overwinnen is de tijd en moeite die het kost om je data in je Neo4j graphs te laden. Natuurlijk kan je CSV genereren en importeren, maar dat wordt al snel onoverzichtelijk en tijdrovend. We dachten dat dit beter kan.  

Kettle en Neo4j

Als grote fans van Kettle (of Pentaho Data Integration) en Neo4j besloten we deze beide werelden samen te brengen en ontwikkelden een Kettle plugin om data naar Neo4j te laden. Dat was in 2017, intussen is er veel gebeurd. Matt Casters, die Kettle startte, werkt intussen voor Neo4j en heeft de ontwikkeling van deze plugin overgenomen. Hij heeft aan aantal steps toegevoegd en heeft de plugin in het algemeen uitgebreid tot een tool die klaar is voor gebruik in productie. Laat ons dat in iets meer detail bekijken.  

We gaan er van uit dat je vertrouwd bent met de installatie en het opstarten van zowel Neo4j als Kettle. Indien dat niet het geval is kan je hier terugvinden hoe je kan starten met Kettle, hier vind je hoe je met Neo4j van start kan gaan. Neem ook even een kijkje op ons overzicht rond graphs. 

Om de Neo4j plugin aan je Kettle installatie toe te voegen kan je de laatste release downloaden (momenteel 5.0.4) uit onze GitHub repository en uitpakken in je data-integration/plugins folder. Vergeet niet eerste eventuele oudere versies te verwijderen en Spoon te (her)starten.  Als alternatief voor deze manuele installatie kan je de Kettle Remix downloaden van remix.kettle.be.  Kettle Remix is een door Matt samengestelde distributie die een groot aantal bug fixes en functionaliteit bevat die je niet in de standaard Kettle distributie vindt. De Neo4j plugin hoort bij deze extra functionaliteit.       

2020-05-20: in de oorspronkelijke post en de toen beschikbare plugin-versie was 'Neo4j Output' de enige beschikbare step. Matt heeft sindsdien de plugin uitgebreid met een heel aantal extra steps en job entries die we daarom aan deze post toegevoegd hebben.  

Na het opstarten van Spoon is een nieuwe categorie 'Neo4j' beschikbaar in je transformation editor:  

De beschikbare transformation steps zijn: 

• Get Neo4j Logging Info: bevraagt de Neo4j execution graph naar start- en eindtijden van jobs en transformations
• Neo4j Output: schrijft nodes en relationships naar een Neo4j graph 
• Neo4j Cypher:  voert Cypher queries uit om data naar Neo4j te schrijven of uit Neo4j te lezen. Aan deze step kan je parameters en input velden doorgeven om je queries flexibeler te maken. 
• Neo4j Generate CSVs: genereer CSV files voor nodes en relationship die je later met neo4j-import kan opladen
• Neo4j Graph Output: bouw een Neo4j subgraph model op basis van velden in je Kettle-stream, en laad deze in 1 stap naar Neo4j. 
• Neo4j Import: voert een import commando uit op basis van de aangeleverde CSV bestanden 
• Neo4j Split Graph: splitst de nodes en relationships uit een Kettle graph data type.  

De beschikbare job entries zijn:

• Check Neo4j Connections: controleer of de opgegeven Neo4j verbindingen geldig zijn en correct gebruikt kunnen worden 
• Neo4j Cypher Script: voer een Cypher script uit. Zoals steeds is er een verschil tussen een job entry en een transformation step: Deze job entry voert een script uit en geeft een return code terug. In tegenstelling tot de vergelijkbare transformation step is de job entry bedoeld voor het uitvoeren van scripts, niet voor data-uitwisseling met Neo4j. 

Een voorbeeld-graph, schol! 

Graphs zijn, net als Belgisch bier overal. We hebben daarom niet lang moeten zoeken naar een voorbeeld om met deze plugin uit te werken: we hebben de Beer Graph van Neo4j-held Rik Van Bruggen gerecupereerd om aan te tonen hoe eenvoudig het maken van nodes en relationships kan zijn. De code voor deze voorbeelden is hier beschikbaar. 

Neo4j Connection

Geef de details voor je Neo4j server op via Neo4j -> Edit Connection (Remix) of vanuit de 'connection' velden bovenaan in 1 van de Neo4j Output steps in de nodes transformations (zie hieronder). Om deze verbindingen te parametriseren kan je  key/value velden toevoegen aan je kettle.properties, bijvoorbeeld: 

NEO4J_HOST=localhost
NEO4J_USER=neo4j
NEO4J_PASS=knowbi
NEO4J_PORT=7687            # de BOLT protocol poort (standaard 7687), niet de browser poort (standaard 7474)

De job in het voorbeeld (jb_beer_graph.kjb) job bevat twee transformations:

Om de nodes aan te maken biedt de Neo4j Output step de volgende opties: 

• connection: maak of selecteer een Neo4j verbinding zoals hierboven beschreven
• batch size: het aantal rijen dat per keer naar Neo4j geschreven wordt, vergelijkbaar met de commit size in een relational database
• create indexes: maakt indexes aan voor de node primary keys. Standaard geactiveerd, meestal is er geen reden om dit te wijzigen. 
• use CREATE instead of MERGE: het standaard gedrag van de step (MERGE) werkt properties bij op reeds bestaande nodes. Hoewel CREATE doorgaans sneller is maakt deze opties sowieso nieuwe nodes aan. Aangezien CREATE niet probeert bestaande nodes bij te werken kan dit resulteren in het dupliceren van nodes. 
• only create relationships: gebruik de 'From Node' en 'To Node' enkel als lookups voor het maken van relationships. Met deze optie maak je geen nodes aan,  enkel relationships. 
• From and To Node tabs: specifieer labels en properties voor de nodes vanuit input velden of als tekst waarden. 
• Relationship: specifieer een relationship type en optionele properties vanuit input velden of als tekst waarden. 

In het onderstaande voorbeeld gebruiken we het BeerType veld om een label aan te maken en het 'name' veld voor het type beer als de 'name' property. Het 'Primary?' veld is ingesteld op 'Y' om aan te geven dat dit een primary propery is dat gebruikt zal worden om deze node op te zoeken bij het aanmaken van relaties. 

De transformation om de relationships aan te maken is vergelijkbaar. In plaats van vier streams zoals voor de nodes, splitsen we hier het aangeleverde CSV in drie streams voor de relaties: beer - alcholpct, beer - brewery, beer - type, brand - beer.

Voor het aanmaken van relaties hebben we de drie tabs in de De Neo4j Output nodig. 

Eerst geven we in de 'From Node' tab het label veld (brandLabel field) en primary property (BeerBrand) op

Het opzoeken van de end node is vergelijkbaar: 

Tenslote bepalen we de relatie die deze beiden nodes verbindt in de Relationship tab: 

In deze tab bepalen we het type relatie van uit een veld ('Relationship field') of met een tekst waarde ('Relationship value'). 

De bier graph wordt aangemaakt in twee verschillende transformations (eerst nodes, daarna relaties) om te vermijden dat nodes gedupliceerd worden. In het algemeen biedt het gescheiden aanmaken van nodes en relaties betere performantie.

Na het uitvoeren van de job kan je je graph verkennen in de Neo4J browser (e.g. http://localhost:7474). 

Deze query toont je de node voor het heerlijke Orval. Indien je niet vertrouwd bent met de Cypher query taal kan je op de Orval node dubbel klikken. Je krijgt dan de verbonden nodes voor brewery, beer type en alcohol percentage te zien.  

Meer informatie over de Neo4j plugin kan je vinden op de github wiki. 

Update 2020-05-20: er is veel gebeurd sinds we de oorspronkelijk versie van de Kettle Neo4j plugin en deze post geschreven hebben. Eerst en vooral is Neo4j stevig gegroeid in de voorbije 2.5 jaar, net als de functionaliteit in de Kettle Neo4j plugin. 
Aangezien we niet diezelfde groei zagen in Kettle (aka Pentaho Data Integration) zijn we gestart met Project Hop. Alle functionaliteit in de Kettle Neo4j plugins is reeds beschikbaar in Project Hop. Wat Project Hop is en hoe en waarom know.bi stevig betrokken is kan je in deze post lezen.