Molecule vs Gremlin

Let’s compare the queries/traversals in the Gremlin Getting Started Tutorial with equivalent Molecule queries.

For the examples we’ll use the same “Modern” graph as the tutorial:

Insert data

Gremlin is untyped, so data is inserted directly in a generic way where “types” are created on-the-go:

Graph graph =; (1)
Vertex marko = graph.addVertex(T.label, "person",, 1, "name", "marko", "age", 29); (2)
Vertex vadas = graph.addVertex(T.label, "person",, 2, "name", "vadas", "age", 27);
Vertex lop = graph.addVertex(T.label, "software",, 3, "name", "lop", "lang", "java");
Vertex josh = graph.addVertex(T.label, "person",, 4, "name", "josh", "age", 32);
Vertex ripple = graph.addVertex(T.label, "software",, 5, "name", "ripple", "lang", "java");
Vertex peter = graph.addVertex(T.label, "person",, 6, "name", "peter", "age", 35);
marko.addEdge("knows", vadas,, 7, "weight", 0.5f); (3)
marko.addEdge("knows", josh,, 8, "weight", 1.0f);
marko.addEdge("created", lop,, 9, "weight", 0.4f);
josh.addEdge("created", ripple,, 10, "weight", 1.0f);
josh.addEdge("created", lop,, 11, "weight", 0.4f);
peter.addEdge("created", lop,, 12, "weight", 0.2f);

In Molecule we first define a schema. Since we won’t use the weight properties yet, we’ll start off defining a schema without those:

object ModernGraph1DataModel {

  trait Person {
    val name = oneString
    val age  = oneInt

    // Normal (uni-directional) reference
    val software = many[Software]

    // Bidirectional self-reference
    val friends = manyBi[Person]

  trait Software {
    val name = oneString
    val lang = oneString

When we compile our project with sbt compile, the sbt-molecule plugin will generate the necessary boilerplate code so that we can enter typed data to populate the graph:

// Create database and save implicit connection
implicit val conn = recreateDbFrom(ModernGraph1Schema)

// Software
val List(lop, ripple) = insert Seq(
  ("lop", "java"),
  ("ripple", "java")
) eids

// People and software created
val List(marko, vadas, josh, peter) = insert Seq(
  ("marko", 29, Set(lop)),
  ("vadas", 27, Set[Long]()),
  ("josh", 32, Set(lop, ripple)),
  ("peter", 35, Set(lop))
) eids

// Friendships
Person(marko).friends(vadas, josh).update

We’ll use the variables with entity ids above for the coming examples.

The first 5 minutes

Now we are ready to make queries.

Generic vs domain language

Since Gremlin traverses generic edges and vertices it is also communicating intentions in a generic way like the following “query”:

Get the value of the name property on vertex with the unique identifier of “1”.

gremlin> g.V(1).values('name')

Since Molecule uses the domain terms as custom building blocks directly, we can formulate our intentions with the language of our domain directly:

What is the Person name of entity marko?

Person(marko).name.get.head === "marko"

Edges / Entities

Get the edges with the label “knows” for the vertex with the unique identifier of “1”:

gremlin> g.V(1).outE('knows')

Marko’s friends

Person(marko).friends.get.head === Set(vadas, josh)


Get the names of the people that the vertex with the unique identifier of “1” “knows”.

gremlin> g.V(1).out('knows').values('name')

In Molecule we can jump from one namespace like Person to Friends since there’s a relationship defined between the two. That way we can get Marko’s referenced Friends entities:

Person(marko) === Set("vadas", "josh")

Note though, that a namespace is not like a SQL table but rather just a meaningful prefix for a group of attributes.


Get the names of the people vertex “1” knows who are over the age of 30.

gremlin> g.V(1).out('knows').has('age', gt(30)).values('name') //(7)

Names of Marko’s friends over the age of 30.

Person(marko)>(30).get === Set("josh")

The next 15 minutes

Find Marko in the graph

gremlin> g.V().has('name','marko')

Prepending the generic attribute e before an attribute finds the entity that it belongs to:

Person.e.name_("marko").get.head === marko

We also append an underscore _ to the name attribute so that it becomes name_. In Molecule this makes the attribute “tacit”, or “silent”, meaning that we don’t need to return its value “marko” since we’re already applying it as a value that we expect the attribute to have.

Traversing / relationships

Gremlin has reached the “software that Marko created”, he has access to the properties of the “software” vertex and you can therefore ask Gremlin to extract the value of the “name” property

gremlin> g.V().has('name','marko').out('created').values('name')

What software did Marko create? - here we use a relationship again to get to the referenced Software entities and their names

Person.name_("marko") === Seq("lop")

OR logic

Find the “age” values of both “vadas” and “marko”

gremlin> g.V().has('name',within('vadas','marko')).values('age')

To get both names we us Molecule’s OR-logic by applying multiple values to an attribute. name should be either “marko” OR “vadas” and we can use various syntaxes:

Person.name_("marko", "vadas").age.get === Seq(27, 29)       // Vararg
Person.name_("marko" or "vadas").age.get === Seq(27, 29)     // `or`
Person.name_(Seq("marko", "vadas")).age.get === Seq(27, 29)  // Seq


Average age of “vadas” and “marko”

gremlin> g.V().has('name',within('vadas','marko')).values('age').mean()

Molecule implements Datomics aggregate functions by applying the keyword avg to a number attribute like age

Person.name_("marko", "vadas").age(avg).get.head === 28.0

Where / 2-step queries

“Who are the people that marko develops software with?"

gremlin> g.V().has('name','marko').out('created').in('created').values('name')

It’s idiomatic with Datomic to split such query and use the output of one query as input for the next one:

// First find ids of software projects that marko has participated in
val markoSoftware = Person.name_("marko").software.get.head

// Then find names of persons that have participated in those projects === Seq("peter", "josh", "marko")

Excluding marko from the result
gremlin> g.V().has('name','marko').as('exclude').out('created').in('created').where(neq('exclude')).values('name')
==>peter"marko").software_(markoSoftware).get === Seq("peter", "josh")


“Group all the vertices in the graph by their vertex label”

gremlin> g.V().group().by(label).by('name')

Since Molecule is typed we would probably ask for specific name attribute values: === Seq("peter", "vadas", "josh", "marko") === Seq("ripple", "lop")

Edge property queries

The Gremlin tutorial doesn’t actually use any of the weight properties so we made the Knows test suite to see how we can work with edge property molecules.

Let’s ask a few more complex questions - a reminder of the graph could be useful here

Who knows young people?

// Since we save bidirectional references we get friendships in both directions:<(30).get === List(
  ("vadas", "marko", 29), // vadas knows marko who is 29
  ("josh", "marko", 29), // josh knows marko who is 29
  ("marko", "vadas", 27) // marko knows vadas who is 27

How many young friends does the older people have?>=(30).friends(count).age_.<(30).get === List(
  ("josh", 32, 1) // josh (32) knows 1 young person (Marko, 29)

Marko’s friends and their friends"marko") === List(
  ("marko", "vadas", "peter"),
  ("marko", "josh", "marko"),
  ("marko", "vadas", "marko")

// Same, nested"marko").Knows.*(*(
        .map(t1 => (t1._1, => (t2._1, t2._2.sorted)).sortBy(_._1))) ===
              ("josh", List("marko")),
              ("vadas", List("marko", "peter")),

Marko’s friends and their friends (excluding marko)"marko")"marko").get === List(
  ("marko", "vadas", "peter")

Marko’s friends' friends

Person.name_("marko")"marko").get === List(

Marko’s friends' friends that are not already marko’s friends (or marko)

val ownCircle = Person(marko) :+ "marko"
Person(marko) === List(

Using the edge properties

Well-known friends

Person(marko).Knows.weight_.>(0.8) === List("josh")

Well-known friends heavily involved in projects

Person(marko).Knows.weight_.>(0.8)>(0.8) ===
  List(("josh", "ripple"))

Friends of friends' side projects

Person(marko)"marko").Created.weight.<(0.5) ===
  List(("peter", 0.2, "lop"))

// .. or elaborated:
Person(marko) // marko entity
  .Knows.Person // friends of marko"marko") // friends of friends of marko that are not marko
  .Created.weight.<(0.5) // Created (software) with a low weight property // name of software created
  .get === List((
  "peter", // peter is a friend of vadas who is a friend of marko
  0.2,     // peter participated with a weight of 0.2 in creating
  "lop"    // the software "lop"