<!-- nornir:class: idiot -->
# 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.
```rust
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.