Gram: A Data Graph Format

Gram is a textual format for data. We have CSV for tables, JSON for documents, and gram for data graphs.

Use gram when [a,b,c] becomes (a)–>(b)<–(c).

Why Another Data Format?

Anything worth talking about is worth inventing a language for.

 — probably not L. Wittgenstein

Graphs are a powerful and increasingly popular way to think about and work with data. Graph technology includes databases, analytics libraries, visualization software, and a host of other tools.

How do we use these things together? We need a common format to connect tools when performing the usual operations:

• import/export data file
• send/receive network transmissions
• copy & paste across applications

We all expect these actions to just work. It’s frustrating when any of them are not possible. Tools with limited interoperability feel locked-in and isolated. That’s not the graph way.

Gram can make it possible for data graphs to be used in normal everyday work.

Data Graphs as Information Architecture

While there are existing graph formats, gram is designed to complement the Property Graph Model defined by ISO GQL (Graph Query Language).

Gram is interested in information architectures. Data graphs are the means, not the goal. Rather than talking about graphs, gram speaks in graph to talk about other things.

Some motivating examples include:

• Association class: How do we describe the relationship between two things? Not just that they are connected, but how they are connected.
• Decorator pattern: Can multiple applications share data while reserving space for their own use?
• U.S. Route 66: How can we represent path membership and also information about the path itself?
• Bill of materials with finished goods: How do we describe both the plan to build stuff and the stuff that has been built?

Gram attempts to address these scenarios while being friendly to read and write by adopting a path-based representation. Paths all the way down, or all the way up with path composition.

Gram is intuitively simple, inspired by Cypher path expressions.

Gram Format

Information starts with a familiar looking data record of nested properties:

({
 name:”Andreas Kollegger”, 
 address: {
   city:”Malmö”, country:”Sweden”
 }
})

The extra set of parenthesis wrapping the record provides space for an identifier and a set of labels:

(a:Person:Author { 
    name:”Andreas Kollegger”, 
    address: { city:”Malmö”, country:”Sweden” }
})

Data records can be composed into information structures using relationships:

(a)-[:Wrote]->(b:Blog {title:”Gram: a data graph format”})

We can complete this scene with another related record:

(b:Blog)<-[:Read]-(c:Person)

Putting it all together we could write:

(a:Person)-[:Wrote]->(b:Blog)<-[:Read]-(c:Person)
(a:Author { 
    name:”Andreas Kollegger”, 
    address: { city:”Malmö”, country:”Sweden” }
})
(b {title:”Gram: a data graph format”})
(c {when:date`2021-01-21`})

Nice. The first path is readable as a sentence that “a Person Wrote a Blog that was Read by another Person.” Notice in this rewrite we accumulated information — each of the a’s, b’s and c’s are the same records by id.

Like writing prose, you don’t have to say everything at once. Paths appear in an ordered stream that merges forward into a final result. In fact, because any path or sequence of paths forms a valid result, you can time-travel or page through, or slide a window along a graph.

Use Gram for Data Graphs

Gram is:

• friendly to read and write
• composable, sliceable, pageable and streamable
• vendor-neutral
• a work-in-progress 🙂

There is a reference implementation called gram-js (with data format model and parser) which you can see in action along with d3.js in a collection of ObservableHQ notebooks.

Next up is integration with other Javascript libraries and frameworks and conversion to/from other formats.

• Gram of Graphs
• gram-data/gram-js

Check it out and let me know what you think!

Gram: A Data Graph Format was originally published in Neo4j Developer Blog on Medium, where people are continuing the conversation by highlighting and responding to this story.