Graph database
A graph database you query with openCypher.
Use it when the interesting part of your data is how things connect, such as which services depend on which, or which machines can reach which networks. You create a GraphDatabase and query it from inside one of your VPCs. Behind it there is no server with a disk. The data is divided into regions, and every file of a region is an object in the database's storage bucket.
What sits behind the endpoint
The key space is cut into ranges called regions. A region server serves a region, query executors run openCypher over the regions, and a placement driver decides who serves what and hands out timestamps. Every one of those is a Compute process.
- Your client is a program on one of your VPCs. The database's endpoints have addresses on that VPC.
- The GraphDatabase is one resource. The platform makes its password and shows it to you once; only a verifier is stored.
- An executor runs the openCypher query and its transaction.
- A region server serves one key range. Its files are objects, so it holds nothing that cannot be read again.
- The placement driver decides which process serves which region, and its timestamps put transactions in order.
- The bucket is the database's own bucket in Storage, sealed with the database's own keys.
Connecting and signing in
The endpoint takes an openCypher statement with parameters over HTTP/JSON, on an address in your VPC. A client signs in with the database's user and its generated password, or with an Etorm token whose roles allow querying or reading that database. If the token only has a read role, a statement that changes data is refused.
The openCypher here has no shortestPath and no spatial types, and times are in UTC. Passwords and tokens are never logged.
Transactions and how fresh a read is
A transaction can touch more than one region. It commits with a two-phase commit and sees a consistent snapshot of the whole database. That is snapshot isolation, and it is not serializable, so keep it in mind if two transactions can each pass a check that the other one would have failed. When two transactions do conflict, one of them gets a transient error and should retry.
Reads come in two kinds. A strong read takes a fresh timestamp and goes to the region's leader. A bounded read may be served by a follower and may be as old as you allow, anywhere from 1 to 3 600 seconds. A dashboard that can live with data a minute old is a good candidate for bounded reads; each region can have 0 to 2 read followers to serve them.
How it grows
A region splits when its size or its request rate passes a threshold, and readers never see the split happen. Splitting stops at the region limit, which is 1 024 by default. You pick a size class for the database, or auto, which starts small and grows.
Because a region's files are objects, moving a region to another process just means opening it there. The old server is fenced off, not trusted to stop on its own.
Why there is no disk
We made the storage bucket the only disk the database has. There is no machine to size and nothing local to lose when a process goes away. In return, a commit is acknowledged only once it is stored as objects, so every commit waits for storage.
The bucket is sealed with keys that belong to this database alone. When you delete the database, the keys are destroyed and every process stops.
Limits
| Property | Value |
|---|---|
| openCypher | No shortestPath and no spatial types. Times are in UTC. |
| Size class | small: up to 2 region servers and 1 executor. medium: 8 and 4. large: 32 and 16. auto starts small and grows. |
| Regions | 1 024 by default; splitting stops at the limit. |
| Read followers | 0 to 2 per region. |
| Bounded reads | 1 to 3 600 seconds old, when you choose bounded consistency. |
| Process memory | 256 MiB at most for each process. |
When a piece fails
| What fails | What happens |
|---|---|
| Storage | Commits fail with a transient error. Nothing is acknowledged that is not durable. |
| A region server | After a timeout its region is assigned to another server. The new server fences the old one, and clients retry. |
| The placement driver | Reads carry on at timestamps already handed out. New timestamps wait for the standby to take over. |
| A transaction's coordinator | Its locks are resolved by the next reader that runs into them. |
| The database, when you delete it | Its keys are destroyed and every process stops. |
If you need tables rather than a graph, look at the PostgreSQL-compatible database, which keeps its data in Storage the same way. The architecture page shows how the storage layer fits together.