# Data model and values

[Wiki](../README.md) / [Cypher query language](README.md)

**On this page**

- [The property graph](#the-property-graph)
  - [Identity and id reuse](#identity-and-id-reuse)
- [The value type system](#the-value-type-system)
  - [Storage rules](#storage-rules)
  - [Equality and ordering (storage vs query)](#equality-and-ordering-storage-vs-query)
- [Nodes, relationships and patterns](#nodes-relationships-and-patterns)
- [Multiple databases](#multiple-databases)
- [Entity values and identity](#entity-values-and-identity)

## The property graph

GDB uses a **labelled property graph** model:

- **Nodes** — entities. A node has:
  - zero or more **labels** (e.g. `:Person:Employee`) — a node may carry many;
  - a set of **properties** (key → value).
- **Relationships** — directed, **typed** edges between two nodes. A relationship
  has:
  - exactly **one** type (e.g. `:KNOWS`);
  - a **start** node and an **end** node (it is always directed);
  - its own set of **properties**.

Labels, relationship types and property keys are **interned**: each distinct
string is stored once and referenced by a small integer id, so a million
`:Person` nodes share one `"Person"` token. This is invisible at the query level
but is why label scans and type filters are cheap.

### Identity and id reuse

Every node and relationship has an internal integer id (surfaced by the `id()`
function). Ids are dense and assigned on creation. **A deleted id may be reused**
by a later creation. Do not treat an id as a stable external
key; use a property with a uniqueness constraint for that (see
[Indexes and constraints](../indexes/README.md)).

## The value type system

GDB has a **closed** set of value types. Every property value, every expression
result and every returned column is one of these:

| Type | Cypher literal examples | Notes |
|---|---|---|
| `Null` | `null` | Absence of a value. Drives three-valued logic (see [topic guide](expressions.md)). |
| `Boolean` | `true`, `false` | |
| `Integer` | `42`, `-7`, `0` | 64-bit signed. |
| `Float` | `3.14`, `2.5`, `1.0` | 64-bit IEEE-754. |
| `Decimal` | `decimal('12.30')` | Exact, up to 38 digits. From version 1.7.2; see [decimal numbers](../types/decimal.md). |
| `String` | `'Ada'`, `"Bob"` | UTF-8. Single or double quotes. |
| `Bytes` | *(no literal)* | Byte blobs; produced/consumed via the API and Bolt, not a Cypher literal. |
| `List` | `[1, 2, 3]`, `['a', true, 3]` | Heterogeneous, ordered. |
| `Map` | `{name: 'Ada', age: 36}` | String keys → values. |
| `Point` | `point({x: 1, y: 2})` | Spatial. See [Spatial and temporal values](../types/README.md). |
| `Geometry` | `spatial.fromWKT('POINT(1 2)')` | WKB-backed planar shapes; [formats and operations](../types/spatial-shapes.md). |
| `Geography` | `spatial.fromWKT('POINT(-0.12 51.5)', {domain:'geography'})` | Longitude/latitude shapes with spherical great-circle edges. |
| `Date` | `date('2026-09-15')` | Calendar date; no zone. |
| `LocalTime` | `localtime('12:30:00')` | Time of day; no zone. |
| `Time` | `time('12:30:00+01:00')` | Time with an offset. |
| `LocalDateTime` | `localdatetime('2026-09-15T12:30:00')` | Date/time without a zone. |
| `Duration` | `duration('P1D')` | Months, days, seconds and nanoseconds. |
| `DateTime` | `datetime('2024-06-27T15:30:00+05:00')` | Timezone-aware instant. See [Spatial and temporal values](../types/README.md). |

### Storage rules

- **`NaN` cannot be stored.** A property value of `NaN` is rejected
  (`NaN` is not equality-comparable, so it could not be indexed soundly).
- **Strings are de-duplicated** in memory by an optional, on-by-default value
  interner: N nodes with `name = 'Bob'` share one allocation. This is transparent
  and reclaimed when the last holder is deleted.

### Equality and ordering (storage vs query)

- At the **query** level, equality follows Cypher's three-valued logic:
  `1 = 1.0` is `true`; comparisons involving `null` yield `null`; `NaN = NaN` is
  `false`. See [Operators and expressions](expressions.md).
- **Ordering** across types is defined for `ORDER BY` (e.g. numbers order
  numerically; nulls sort last ascending and first descending). Incomparable cross-type comparisons (`<`, `>`)
  yield `null`.

## Nodes, relationships and patterns

Patterns are how you describe shapes of the graph to match or create.

```text
()                       // an anonymous node
(p)                      // a node bound to variable p
(p:Person)               // a node with label Person
(p:Person:Employee)      // multiple labels
(p:Person {name: 'Ada'}) // label + inline property predicate / spec

(a)-[:KNOWS]->(b)        // a directed KNOWS relationship from a to b
(a)<-[:KNOWS]-(b)        // the reverse direction
(a)-[r:KNOWS]->(b)       // bind the relationship to r
(a)-[r:KNOWS {since: 2015}]->(b)   // typed + property
(a)-[]->(b)              // any relationship type
(a)--(b)                 // any direction, any type
(a)-[:KNOWS*1..3]->(b)   // variable-length: 1 to 3 KNOWS hops
```

A **path** binds an entire matched chain:

```cypher
MATCH p = (a:Person)-[:KNOWS]->(b)
RETURN length(p), nodes(p), relationships(p)
```

Pattern semantics worth knowing:

- **Node matching is homomorphic** but **relationship matching is isomorphic**
  within a single `MATCH`: the same relationship is never used twice in one
  pattern, but a node may recur.
- Inline `{...}` in a `MATCH` pattern is an **equality predicate** on those
  properties; in a `CREATE`/`MERGE` it **sets** them.

## Multiple databases

One database server can host several named databases, subject to licence limits:

- The home database selected by `GDB_INITIAL_DATABASE`, `galactus` by default.
- `system` — reserved (routing/administration); cannot be dropped.
- Any database you create by name.

Each durable database is fully isolated on disk under `data_dir/<name>/` with its
own segmented commit/property log. Select a database in Explorer or in the native
driver's connection configuration. An omitted or empty driver database setting
uses the server's home database; it does not create a new database.

## Entity values and identity

The engine represents query nodes and relationships as maps with reserved
metadata, and paths as alternating entity lists; Bolt encodes them as graph
structures. `elementId()` is the string form of the numeric ID in this implementation.
Neither ID form is an application key. Prefer a property protected by a
[constraint](../indexes/constraints.md#uniqueness-constraints).
See [temporal values](../types/temporal.md) for all constructors and arithmetic.

## Related articles

[Indexes and constraints](../indexes/README.md) · [Procedure directory](../reference/procedures.md) · [Transactions and concurrency](../operations/transactions.md)
