Edgy (edgy v1.0.0)

Documentation for Edgy.

Edgy is a set of Ecto Schema and functions for treating PostgreSQL as a graph database. You can use it with other Ecto backends but the filter by property queries will not work as they utilize the PostgreSQL jsonb operators.

Installation

Make a migration

mix ecto.gen.migration setup_edgy

Then make the change function look like this:

def change do
    Edgy.Migrations.run_migrations()
end

Configure the default Repo

config :edgy, repo: MyApp.Repo

Usage

{:ok, graph} = Edgy.create_graph("demo")
{:ok, a} = Edgy.add_node(graph, "node", %{name: "a"})
{:ok, b} = Edgy.add_node(graph, "node", %{name: "b"})
{:ok, c} = Edgy.add_node(graph, "node", %{name: "c"})
{:ok, ab} = Edgy.add_edge(graph, "link", %{name: "a -> b", strength: "strong"}, a, b)
{:ok, bc} = Edgy.add_edge(graph, "link", %{name: "b -> c", strength: "weak"}, b, c)

Edgy.edges([a], direction: :from, recursive: true)
Edgy.edges([a], properties: %{strength: "strong"})
Edgy.edges([a], properties: %{strength: "weak"})

Common options:

The query functions all accept the following options

  • repo - pass an explicit repo to the function otherwise the Application.env value for :edgy, :repo will be used
  • type - filter nodes or edges based on their type
  • properties - filter nodes or edges based on their properties

Summary

Functions

Add a bunch of edges. edges should be {type, properties, from_node, to_node}

Add many nodes in a single transaction.

Create a new graph. Names for graphs must be unique because we interact with the graph via its name.

Delete many edges.

Delete a graph by name. Deleting a graph will delete all the associated nodes and edges.

Delete a node. Deleting a node will delete all edges connected to a node.

Delete many nodes. Deleting a node will delete all edges connected to a node.

Fetch the edges connected to the node or nodes

Get graph by name.

Load nodes of a specific type from the graph. Optionally filter on the properties of the nodes.

Fetch the edges of a given type coming into a node or list of nodes. Optionally filter by edge properties.

Load a full graph into memory

Fetch the edges of a given type coming from a node or list of nodes. Optionally filter by edge properties.

Convert the graph into the data structure from the :digraph module.

Update the properties of an edge.

Update the properties of a node.

Functions

add_edge(graph, type, properties, from, to, opts \\ [])

Add an edge connecting two nodes.

add_edges(graph, edges, opts \\ [])

Add a bunch of edges. edges should be {type, properties, from_node, to_node}

add_node(graph, type, properties, opts \\ [])

Add a node to the graph.

add_nodes(graph, nodes, opts \\ [])

Add many nodes in a single transaction.

create_graph(name, opts \\ [])

Create a new graph. Names for graphs must be unique because we interact with the graph via its name.

delete_edge(edge, opts \\ [])

Delete an edge.

delete_edges(edges, opts \\ [])

Delete many edges.

delete_graph(name, opts \\ [])

Delete a graph by name. Deleting a graph will delete all the associated nodes and edges.

delete_node(node, opts \\ [])

Delete a node. Deleting a node will delete all edges connected to a node.

delete_nodes(nodes, opts \\ [])

Delete many nodes. Deleting a node will delete all edges connected to a node.

edges(nodes, opts \\ [])

Fetch the edges connected to the node or nodes

Additonal Options:

  • recursive - continue following the edges until there are no more nodes to explore or the recursion limit is reached
  • limit - the maximum number of recursive queries to make
  • direction - either :to or :from to select either incoming or outgoing edges

get_graph(name, opts \\ [])

Get graph by name.

get_nodes(graph, opts \\ [])

Load nodes of a specific type from the graph. Optionally filter on the properties of the nodes.

incoming_edges(nodes, opts \\ [])

Fetch the edges of a given type coming into a node or list of nodes. Optionally filter by edge properties.

Additonal Options:

  • recursive - continue following the edges until there are no more nodes to explore or the recursion limit is reached
  • limit - the maximum number of recursive queries to make

load_graph(name, opts \\ [])

Load a full graph into memory

outgoing_edges(nodes, opts \\ [])

Fetch the edges of a given type coming from a node or list of nodes. Optionally filter by edge properties.

Additonal Options:

  • recursive - continue following the edges until there are no more nodes to explore or the recursion limit is reached
  • limit - the maximum number of recursive queries to make

rename_graph(graph, name, opts \\ [])

Rename a graph.

to_digraph(graph, opts \\ [])

Convert the graph into the data structure from the :digraph module.

update_edge(edge, properties, opts \\ [])

Update the properties of an edge.

update_node(node, properties, opts \\ [])

Update the properties of a node.