.nornir/graphdb-for-idiots.md

The graph seam, for idiots

Class: idiot. What knut-graphdb is, in short flat sentences.

What it is

One trait for talking to a graph database. It is called GraphDb.

You give it an address. It gives you graphs.

let db = FalkorBackend::new("127.0.0.1:6379");
let names = db.graph_names().await?;      // what graphs are here?
let schema = db.open("social").await?;    // what is in this one?
let scene = db.read("social", 300).await?; // give me the nodes and edges

That is the whole thing.

Why it exists

There used to be two of these. knut had one half. korp had the other half. Neither could do the whole job. korp also opened its own connections to FalkorDB in three other places.

Now there is one. korp opens none.

The rule about containers

A GraphDb is a client. It takes an address and talks to it.

It never starts anything. It does not know what a container is. If you want a FalkorDB running, that is somebody else's job.

The rule about Cypher

Cypher is the query language FalkorDB speaks. Cozo does not speak it.

So Cypher is not on the main trait. It is a separate one you opt into.

This means a backend that cannot do Cypher does not have to write a fake method that panics. It just does not implement the extra trait. Nothing to get wrong.

The rule about empty

Empty and broken are different answers.

No graphs here → Ok(vec![]).
Cannot reach the server → an error.
That graph does not exist → a different error.
Took too long → a different error again.

If a graph seam ever answers "broken" with "empty", somebody stares at a blank screen and thinks the data is gone. That has happened here. It is why the types are separate.

The weird one: `open` asks twice

open("social") first lists every graph, then reads the schema.

That looks wasteful. It is not.

FalkorDB creates a graph the first time you query a name it has never seen. So if open asked the graph directly, the asking would create it, and the answer would always be "yes, it exists". Then a typo leaves a junk empty graph behind forever.

Listing first costs one extra round trip. Keep it.

Colours are not here

The graph viewer paints Person blue and Vessel teal. Those colours live in korp, not here.

Reason: they are named after korp's things. A different program using this trait has different things and would get the wrong colours. So this crate hands back the labels and whoever draws picks the paint.

Two backends

FalkorDB — a real server, over the network, optionally with client certificates.
Cozo — runs inside your own program. No server. No container. Good for tests and for a demo with nothing installed.

Both answer the same questions.