Home

Awesome

The Object Graph Mapping Library for Kotlin and Gremlin

Build Status Latest Release Kotlin Version License

Gremlin is the graph traversal language for the Apache TinkerPop graph framework and is supported by most graph database implementations.

Basic Usage:

Define a Vertex

@Element("Person")
data class Person(

        @ID
        val id: Long? = null,
           
        @Property("name")
        val name: String)

Define a Relationship

   val friends = ManyToManySymmetricEdgeSpec<Person>("friends")
   val subordinates = SingleToManyEdgeSpec<Person, Person>("boss_to_subordinates")
   val boss = subordinates.inverse
   

Save a Vertex

    val mighael = graphMapper.saveV(Person(name = "Michael Scott"))
    val dwight = graphMapper.saveV(Person(name = "Dwight Schrute"))
    

Save an Edge

    graphMapper.saveE(friends from michael to dwight)
    graphMapper.saveE(boss from michael to dwight)
    

Traverse an Edge

    graphMapper.traverse(friends from michael) // returns List<Person> [ dwight ]
    graphMapper.traverse(friends from dwight) // returns List<Person> [ michael ]
    graphMapper.traverse(subordinates from michael) // returns List<Person> [ dwight ]
    graphMapper.traverse(boss from dwight) // returns non-optional Person micheal

The graphMapper is an implementation of the GraphMapper interface which requires two properties:

  1. A GraphTraversalSource spawned from a tinkerpop graph
  2. A GraphDescription which is easily instantiated using CachedGraphDescription(vertices = setOf(Person::class))

Sample Starwars App

An interactive example can be run using the starwars example project. From the repo root directory, run:

./gradlew run

Then load GraphiQL at http://localhost:5000/graphiql.html to explore the data mapped with this library.

A small typescript + apollo + react web client that uses this starwars API can also be sampled:

cd example/frontend && yarn start 

Then load http://localhost:3000 (server must also be running)

Installation:

Library Extensions

Mix and match the following extensions to this library

Features:

Why use a graph database and ogm?

Limitations:

Design Principles:

Native property types are stored directly in the graph as property values:

If your Gremlin implementation does not support one of these native types, make sure to register a property mapper for they type with your GraphDescription or declare a @Mapper for that property.

Built-in property mappers:

To use other property types, register your custom property mapper with GraphDescription by returning a PropertyMapper from the getScalarPropertyMapper function a @Mapper for that property.

How the mapping works:

Given:

    class Name(val first: String, val last: String)
    class Person(val name: Name)

...is serialized in the graph using vertex properties:

    "name.first" -> "Lionel"
    "name.last" -> "Messi"

Given:

    class Name(val first: String, val last: String)
    class Person(val names: Set<Name>)
    

...is serialized in the graph using vertex properties:

    "names.0.first" -> "Cassius"
    "names.0.last" -> "Clay"
    "names.1.first" -> "Muhammad"
    "names.1.last" -> "Ali"

To preserve the difference between a null and empty collection or map, we use a special UUID token. For example if the names Set was empty:

    "names" -> "474A56F1-6309-41B5-A632-AD53F57DBDAE"                

...or in the case of an empty map, the special UUID is: 9B94DCB9-D405-47C1-B56D-72F83C4E81D3.

Legal:

Licensed under the Apache Software License 2.0. This code is in no way affiliated with, authorized, maintained, sponsored or endorsed by the Apache Software Foundation.