dynamo-graph

Low-level graph database operations implemented in DynamoDB. Logic involving complex traversals, lazy lists, intersections, and unions, are deferred to the consuming client.

Ensure that you have your AWS CLI properly configured, so that the aws-sdk dependency can do its magic.

Documentation (TODO)

All code is written in a literate style. For more detailed explanations, refer to the source code.

Example

import { G, V, E } from 'dynamo-graph'
 
// create a graph instance
 
const g = G.define('my-graph')
 
// create vertex definitions
 
const USER = V.define('User')
const NOTE = V.define('Note')
 
// create edge definitions
 
const AUTHORED = E.define('Authored', E.ONE_TO_MANY)
 
const overview = async () => {
 
  // if this is our first time using the graph
  // G.generate will instantiate all the DynamoDB tables, indices, and system objects
  await G.generate(g)
 
  // V.create
 
  const me = await V.create(g, USER, { name: "James", job: "Intern" })
    // => { id: '3Rx', label: 'User', updatedAt: 14699502051042, attrs: { name: "James", job: "Intern" } }
  const boss = await V.create(g, USER, { name: "Tyler", job: "CTO" })
    // => { id: '3Ry', label: 'User', updatedAt: 14699502056492, attrs: { name: "Tyler", job: "CTO" }}
  const note = await V.create(g, NOTE, { message: "some note" })
    // => { id: '3Rz', label: 'Note', updatedAt: 14699502285314, attrs: { message: "some note" }}
 
  // V.all
 
  await V.all(g, USER)
    // => TODO: document
 
  // V.update
 
  await V.update(g, USER, me.id, { name: "James", job: "Engineer" })
    // => { id: '3Rx', label: 'User', updatedAt: 14699502496014, attrs: { name: "James", job: "Engineer" } }
 
  // V.putByKey
 
  await V.putByKey(g, NOTE, 'important', { message: 'Publish dynamo-graph!' })
    // => { id: 'd7', label: 'Note', updatedAt: 1469950262268, key: 'important', attrs: { message: 'Publish dynamo-graph!' } }
 
  // n.b. the id remains the same, the key uniquely identifies the vertex
  const important = await V.putByKey(g, NOTE, 'important', { message: 'Published' })
    // => { id: 'd7', label: 'Note', updatedAt: 1469950309677, key: 'important', attrs: { message: 'Published' } }
 
  // E.set
 
  const e1 = await E.set(g, important.id, AUTHORED, E.IN, E.GENERATE, me.id)
    // => { from: 'd7', label: 'Authored', direction: '<', weight: 1042, to: '3Rx', updatedAt: 1469950464801 }
 
  const e2 = await E.set(g, me.id, AUTHORED, E.OUT, +Date.now(), note.id)
    // => { from: '3Rx', label: 'Authored', direction: '>', weight: 1469950468427, to: '3Rz', updatedat: 1469950468427 }
 
  // E.get
 
  await E.get(g, note.id, AUTHORED, E.IN, +Date.now(), me.id)
    // => { from: '3Rz', label: 'Authored', direction: '<', weight: 1469950468427, to: '3Rx', updatedat: 1469950468427 }
 
  // E.range
 
  await E.range(g, me.id, AUTHORED, E.OUT)
    // => { items: [ e2, e1 ], hasMore: false, lastCursor: 1042 }
  await E.range(g, me.id, AUTHORED, E.OUT, { first: 1, after: 99999 })
    // => { items: [ e1 ], hasMore: false, lastCursor: 1042 }
  await E.range(g, me.id, AUTHORED, E.OUT, { last: 1, before: -1 })
    // => { items: [ e1 ], hasMore: true, lastCursor: 1042 }
 
  // Edge multiplicities are respected:
  
  await E.set(g, boss.id, AUTHORED, E.OUT, E.GENERATE, important.id)
    // => { from: '3Ry', label: 'Authored', direction: '>', weight: 1043, to: 'd7', updatedAt: 1469981321205 }
  await E.get(g, me.id, AUTHORED, E.OUT, important.id)
    // => null
  await E.get(g, important.id, AUTHORED, E.IN, me.id)
    // => null
 
  // E.remove
  await E.remove(g, boss.id, AUTHORED, E.OUT, important.id)
    // => { from: '3Ry', label: 'Authored', direction: '>', weight: 1043, to: 'd7', updatedAt: 1469981321205 }
 
}

G

A graph is an abstraction over the database, containing meta information as well as exposure to the raw operations

type Graph =
  { name: string
  , env: "production" | "beta" | "development"
  , region: "us-east-1" | "us-west-1" | ... | "local"
  , id: () => Promise<Id>
  , weight: () => Promise<Weight>
  , putCounter: (key: string, value: number) => Promise<number>
  , incrCounter: (key: string, value: number) => Promise<number></number>
  }

G.define(name[, { env, region }]): Graph

G.generate(g): Promise<Graph>

V

A vertex is a tuple (id, label, attrs, key?, updatedAt) such that the id uniquely determines the vertex, the label uniquely determines the type of the attributes, and the label-key pair uniquely determines a vertex

type Vertex<a> =
  { id        : string
  , label     : Label
  , attrs     : a
  , key?      : string
  , updatedAt : number
  }

V.define(label)

V.create(g, def, attrs)

V.update(g, def, id, attrs)

V.putByKey(g, def, key, attrs)

V.get(g, id)

V.getMany(g, ids)

V.getByKey(g, def, key)

V.all(g, def, cursor)

V.count(g, def, cursor)

V.remove(g, id)

E

An edge is a tuple (from, label, direction, weight, to, attrs, updatedAt) such that (from, label, direction, to) and (from, label, direction, weight) both uniquely identify the edge.

type Edge<a> =
  { from       : string
  , label      : Label
  , direction  : ">" | "<"
  , weight     : number
  , to         : string
  , attrs      : a
  , updatedAt  : number
  }

Directions

Edge operations require a direction: E.OUT, or E.IN

Multiplicities

Defining an Edge requires the use of one of the following multiplicities:

• E.MANY_TO_MANY: no restrictions, describes a simple graph
• E.ONE_TO_MANY: a vertex may have many OUT edges, but only one IN edge, typically surjective
• E.MANY_TO_ONE: a vertex may have many IN edges, but many OUT edge, i.e. an injective mapping
• E.ONE_TO_ONE: a vertex may have only one IN or OUT edge, i.e. a bipartition

E.define(label, multiplicity)

E.get(g, from, def, direction, to)

E.range(g, from, def, direction, cursor)

E.count(g, from, def, direction, cursor)

E.set(g, from, def, direction, weight, to, attrs)

E.remove(g, from, def, to)