Schema modeling

TypeDB treats relations and attributes as first-class, alongside entities (see Entities, Relations, Attributes for the underlying data model). Choosing between the three is the first modeling decision for every piece of data:

In this example, we apply these principles to build a small employment schema:

The remainder of this guide uses the above schema as a baseline.

TypeQL reads most elegantly when every type (entity, relation, role, and attribute) is named with a noun. The main TypeQL keywords (isa, has, links, relates, owns, plays) are verbs, so the types slot in as nouns around them, and queries read like English sentences.

All types: querying with match …​ isa …​ reads as "X is a Y", and the type’s label fills the Y slot: $person isa person works as a sentence because the label is a noun.

Attributes: querying with match …​ has …​, the object of the sentence comes after the has, so it reads best as a noun. Read aloud, $person has name "Alice" is a well-formed English sentence; a verb name like named would produce the awkward $person has named "Alice".

Relations: querying with match …​ links …​, the object of the sentence again comes after the verb, so a relation also reads best as a noun.

Relations read best as active or verbal nouns: the noun form of the action the relation captures. For example, employment is the noun form of to employ, marriage of to marry, and assignment of to assign. Sometimes the two coincide: grant is the noun form of to grant, and review of to review. Compare the verb-named alternative: employs links (…​) reads as two verbs in a row, while employment links …​ reads naturally.

Functions should be named by what they return and the constraints they contain, e.g. persons_by_name, or principals_with_access. The call site then reads as a description of the result:

Here with declares a query-level function, valid for that query only; the functions section covers persisting functions in the schema with define.

TypeDB supports only single inheritance. Treat sub as a true, independent "is-a" axis, and compose everything else. When a supertype exists only to be specialized, mark it @abstract so that only its subtypes can have instances, as with the abstract id attribute above.

To compose, use relations and roles: a role that a type plays acts as a trait or interface, much like a component architecture in OOP. We might have a plain entity person, but a person can behave as an employee: entity person, plays employment:employee. Attribute ownerships are interfaces the same way: entity person, owns name indicates a person can act as a "name-owner".

Both axes are resolved polymorphically at read time:

Since a type cannot sub two parents, a nice way to give one type several independent capabilities is to create unary relations (relations with a single role) that act as components for the type. Here, a strongly typed HR subsystem can be built against a person’s hr_component, of which at most one can exist:

The HR subsystem can then look up a person’s component and work against it:

TypeDB gives you the power to choose the level of type safety you want. The same domain can be modeled anywhere on a spectrum, from a single generic type with string labels to a fully enumerated schema where even enum values are types.

At the loose end, you can choose to avoid defining specialized types altogether, and create an entity type thing with an attribute label:

Any kind of data fits without schema changes, but you trade off type errors for silent misses and data bugs. A mistyped label is not an error; the query silently returns no results instead of failing:

Alternatively, you can choose to enumerate your types into the schema (like the person and company types above), and the database will type check those for you. The same typo is then an error, caught as soon as the query runs:

At the strict end, consider an attribute with an enumerated set of values, usually modeled with a @values restriction:

Those values can instead be turned into unary relation types, and the system will validate the enums as types:

Note the @card(0..1) on the plays: the default of @card(0..) would allow an account to be active and suspended at the same time, so we tighten it to match the single-valued status attribute it replaces.

With the enum lifted into the type system, each state can later gain its own attributes and roles (e.g. a suspended_status owning a reason), and queries over states are type checked like any other pattern:

How much type safety you need comes down to a trade-off: the size of the schema you are willing to manage, against the rigor with which your reads and writes are validated. More types buy you earlier errors and richer queries; less gets you flexibility.

Use the most specific possible cardinality for every capability in your schema. The defaults are permissive:

The only way to encode a required connection is a cardinality with a lower bound of at least one, e.g. @card(1) or @card(1..). Note that @key implies cardinality 1 as well (and therefore cannot be combined with @card).

For most relations, tighten the default @card(0..1) on each relates role to @card(1), unless the role is genuinely optional (an account holding without an account is rarely meaningful):

A complete account holding commits fine:

A holding missing its account now fails commit-time validation instead of silently persisting incomplete data:

The same applies to owns: @card(1) makes an attribute mandatory, @card(1..) requires at least one, and @key both requires exactly one and enforces uniqueness.

Value restrictions like @values and @range can be declared on the attribute definition itself, where they constrain every use of the attribute; or locally on an individual owns, where they constrain only that owner. Declaring them at the owns level lets a single generic attribute carry different restrictions for different owners:

Both owners share the same rating attribute (enabling polymorphic queries over ratings), but each is validated against its own range, and a violation is rejected as soon as the insert runs:

Subtypes can add their own specializations of inherited capabilities, and both the local and the inherited constraints are validated at commit time. For example, if an identity is required to have at least one email, a subtype service_account can restrict that to exactly one:

A user only carries the inherited @card(1..), so multiple emails are fine:

A service_account is checked against both the inherited @card(1..) and its local @card(1), so two emails and zero emails are both rejected:

Under the hood, @key is a composition of @unique and @card(1): @unique requires that no two instances of the owner type (including its subtypes) own an attribute of that type with the same value. Both @key and @unique go on the ownership, not on the attribute definition.

Role types are inherited as-is: a part_time_employment sub employment inherits the role employment:employee. There is no distinct role part_time_employment:employee; it is the same employment:employee, held by employment and all of its subtypes, so every type that plays it can participate in the sub-relations too.

To restrict who can participate in a sub-relation, rather than letting it accept every player of the inherited role, create a role subtype with as:

This essentially creates a new role type part_time_employment:part_time_employee sub employment:employee, and also blocks the inherited employee role in part_time_employment instances. Note that plays declarations are not inherited across the specialization; players of the new role need their own plays, and it is exactly this that constrains participation. Here both roles happen to be granted to person; in a real model, the specialized role is typically granted to a narrower type: only admins may execute privileged actions, while every user may execute ordinary ones.

Because of the role subtyping, querying the parent role at read time also resolves players of the specialized role:

The inherited employee role, however, can no longer be used in part_time_employment instances; the specialization blocks it:

The cost of a specialized role is that a new name must be created for it.

Functions abstract read queries into named, reusable units. Functions have several uses: modularizing queries, deriving conceptual relations, and performing aggregation and recursion.