# Constraints and shared uniqueness

[Wiki](../README.md) / [Indexes and constraints](README.md)

**On this page**

- [Uniqueness constraints](#uniqueness-constraints)
- [Existence constraints](#existence-constraints)
- [Node-key constraints](#node-key-constraints)
- [Element-uniqueness constraints](#element-uniqueness-constraints)
- [Group- (multi-label) uniqueness constraints](#group--multi-label-uniqueness-constraints)
- [Property type constraints](#property-type-constraints)

The failing inserts in this article are intentional examples. Execute them
individually against disposable data: an Explorer script stops at its first error.

## Uniqueness constraints

A uniqueness constraint guarantees no two nodes with a given label share a value
for a property. It is **index-backed**: declaring one ensures a backing index
exists, and enforcement is then a cheap posting-list check.

```cypher
CREATE CONSTRAINT user_id FOR (u:User) REQUIRE u.id IS UNIQUE;
SHOW CONSTRAINTS;
DROP   CONSTRAINT user_id;                                 // by name (names.md)
DROP   CONSTRAINT FOR (u:User) REQUIRE u.id IS UNIQUE;     // or by definition
```

Behaviour:

- **Enforced on writes** — a `CREATE` or `SET` that would put a second node on the
  same `(label, property)` value fails with a constraint error.
- **Validated at creation** — `CREATE CONSTRAINT` fails if existing data already
  contains a duplicate for that pair.
- **Backing index is protected** — you cannot `DROP INDEX` on a pair that backs a
  live constraint; drop the constraint first. (Dropping the constraint leaves the
  backing index in place; remove it explicitly with `DROP INDEX` if unwanted.)

```cypher
CREATE CONSTRAINT FOR (u:User) REQUIRE u.id IS UNIQUE;
CREATE (:User {id: 1});
CREATE (:User {id: 1});      // error: uniqueness violation on :User(id) = 1
```

## Existence constraints

`REQUIRE n.prop IS NOT NULL` guarantees every node with the label carries the
property. It is validated at the **statement/transaction boundary** (so the order
in which a statement sets properties doesn't matter) and at declaration against
existing data.

```cypher
CREATE CONSTRAINT FOR (p:Person) REQUIRE p.name IS NOT NULL;
DROP   CONSTRAINT FOR (p:Person) REQUIRE p.name IS NOT NULL;
CREATE (:Person {age: 5});   // error: missing required property `name`
```

## Node-key constraints

`REQUIRE (n.a, n.b) IS NODE KEY` is the composite generalisation: every labelled
node must carry **all** the key properties, and the property **tuple** must be
unique within the label.

```cypher
CREATE CONSTRAINT FOR (p:Person) REQUIRE (p.first, p.last) IS NODE KEY;
CREATE (:Person {first: 'Ada', last: 'Lovelace'});
CREATE (:Person {first: 'Ada', last: 'Byron'});      // ok (different tuple)
CREATE (:Person {first: 'Ada', last: 'Lovelace'});   // error: duplicate node key
CREATE (:Person {first: 'Ada'});                     // error: missing key property
```

## Element-uniqueness constraints

`REQUIRE EACH n.prop IS UNIQUE` is uniqueness **per element**: no *other* node
with the label may hold any of this node's elements, in any position — but a
node repeating its own element across slots is allowed (a staged id where
draft == live is the steady state, not a violation).

```cypher
CREATE CONSTRAINT FOR (u:User) REQUIRE EACH u.id IS UNIQUE;
CREATE (:User {id: ['xxx', null, 'xxx']});   // ok (own repeat)
CREATE (:User {id: [null, 'xxx', null]});    // error: element uniqueness violation
CREATE (:User {id: 'xxx'});                  // error (a scalar is one element)
```

It is backed by an element index ([Element indexes and staged values](element.md#element-multi-entry-indexes)): declaring the constraint
auto-creates the index if absent, existing data is validated at declaration,
and the backing index cannot be dropped while the constraint lives.
`SHOW CONSTRAINTS` reports it as `ELEMENT_UNIQUE`.

## Group- (multi-label) uniqueness constraints

A plain `IS UNIQUE` constraint is scoped to **one** label: a `:User` and a
`:Product` may each hold `id = 'x'` independently. A *label alternation*
`(n:A|B|C)` opts a set of labels into a **shared** uniqueness namespace — the
value must be unique across the **union** of nodes carrying any of those labels
(a Galactus DB extension).

```cypher
CREATE CONSTRAINT FOR (n:Person|Company|Address) REQUIRE n.id IS UNIQUE;
CREATE (:Person  {id: 'x'});
CREATE (:Company {id: 'x'});   // error: group uniqueness violation
CREATE (:Vehicle {id: 'x'});   // ok: Vehicle was not opted in
```

Semantics:

- **Opt-in by label.** Only the named labels participate; a label outside the
  group shares no namespace with it. A node with **no** property, or with the
  property but none of the group's labels, is unconstrained.
- **Own repeats are fine.** One node carrying two of the group's labels
  (`:Person:Company {id: 'x'}`) posts the same value twice but is a single
  node, not a collision.
- **Gaining a label is checked.** `SET n:Company` subjects `n`'s existing
  properties to the group there and then.
- **Removal is automatic.** Deleting the node, removing the property, or
  removing the group label frees the value immediately — enforcement fans
  across each label's index, so there is no separate structure to keep in sync.
- **Modifiable in place — CREATE adds, DROP removes.** The group is keyed by
  the property, so the label set is edited without a rebuild. The verbs are
  asymmetric on purpose: **CREATE never destroys**, so re-running any old CREATE
  is safe.

  ```cypher
  // add: union more labels in (revalidated; rejected if existing data collides)
  CREATE CONSTRAINT FOR (n:Person|Company|Vehicle) REQUIRE n.id IS UNIQUE;

  // remove: name the labels to opt out (relaxing, so never fails)
  DROP CONSTRAINT FOR (n:Vehicle)        REQUIRE n.id IS UNIQUE;  // {Person, Company}
  DROP CONSTRAINT FOR (n:Company|Vehicle) REQUIRE n.id IS UNIQUE; // removes both
  ```

  Re-declaring with a *smaller* set does **not** shrink the group (CREATE only
  ever unions — use DROP to remove). The group vanishes once its last label is
  removed. A removed label's backing index is left in place, and becomes
  eligible for `DROP INDEX` again. A single-label `DROP … IS UNIQUE` prefers a
  plain uniqueness constraint on that pair, and only removes the label from a
  group when no plain unique exists.

Each participating label gets a backing `(label, id)` hash index for free
(auto-created, backfilled, and drop-protected while the constraint lives), so
`MATCH (p:Person {id: 'x'})` still seeks. Existing data is validated across the
union at declaration. `SHOW CONSTRAINTS` reports it as `GROUP_UNIQUE` with the
labels joined by `|`.

The alternation is valid **only** with a plain `IS UNIQUE`; `IS NOT NULL`,
`IS NODE KEY`, and `REQUIRE EACH … IS UNIQUE` remain single-label.

`SHOW CONSTRAINTS` reports each constraint's `type` (`UNIQUE`,
`NODE_PROPERTY_EXISTENCE`, `NODE_KEY`, `ELEMENT_UNIQUE`, `GROUP_UNIQUE`).

## Property type constraints

A property type constraint fixes the type of value a property may hold, on a
node label or a relationship type. The property may still be absent.

```cypher
CREATE CONSTRAINT FOR (p:Person) REQUIRE p.age IS :: INTEGER;
CREATE CONSTRAINT FOR ()-[r:RATED]-() REQUIRE r.stars IS :: INTEGER;
CREATE CONSTRAINT FOR (d:Doc) REQUIRE d.tags IS :: LIST<STRING NOT NULL>;

CREATE (:Person {age: 'forty'});
// Error: property `age` on :Person must be INTEGER (property type constraint), but the value is STRING

DROP CONSTRAINT FOR (p:Person) REQUIRE p.age IS :: INTEGER;
```

Types: `BOOLEAN`, `STRING`, `INTEGER`, `FLOAT`, `DATE`, `LOCAL TIME`,
`ZONED TIME`, `LOCAL DATETIME`, `ZONED DATETIME`, `DURATION`, `POINT`,
`DECIMAL` (from version 1.7.2) and `LIST<type NOT NULL>` of any of them.
`IS TYPED` is accepted for `IS ::`, as are the synonyms `INT`, `BOOL`,
`VARCHAR`, `NUMERIC`, `TIME WITH TIME ZONE` and so on. Types are exact: an
integer is not a float, and neither is a decimal.

The check runs when the property is written and when a node gains the label.
Creating the constraint fails if existing data violates it. A property has at
most one type constraint; drop it to change the type. `SHOW CONSTRAINTS` lists
it with type `NODE_PROPERTY_TYPE(INTEGER)` or `RELATIONSHIP_PROPERTY_TYPE(…)`.
A relationship type accepts only this kind of constraint.

A database that declares a property type constraint is written in a newer
storage format that version 1.0.1 refuses to open. A `DECIMAL` type constraint
needs version 1.7.2 or later.

## Related articles

[EXPLAIN and PROFILE](../cypher/planning.md) · [Resident and hybrid storage](../operations/storage.md) · [Schema and maintenance procedures](../cypher/procedures.md)
