---
last_review: "2025-01-01"
last_reviewer: "-"
documented_code: [ ]
---

```{tags} explanation, schema
```

# LinkAhead Data Model

:::{note}
This page has been migrated from the old documentation, and has not yet been fully revised.
There might be inconsistencies or errors when using with current LinkAhead versions.
:::
% TODO: Issue: https://gitlab.indiscale.com/caosdb/src/linkahead-docs/-/issues/77

## Introduction

LinkAhead is a data and knowledge management system that stores it's data and represents its
knowledge as `Entities`. The concept of `Entity` can be thought of as the equivalent to tables,
rows, columns and the tuples that are contained in the tables of a traditional RDBMS. Or, think of
`Entity` as the key concepts of object-oriented programming languages: Class, Object, Member
Variables are the Entities of Java.

The basic building blocks of the LinkAhead Data Model are shown in the following picture:

:::{figure} /.assets/images/explanation/general/entities.svg

Entities
:::

It has a base object called **Entity**. Entities are either **Record Types**, **Records**, or *
*Abstract Properties** (and Record like objects for files). What *kind of data* is stored is defined
by the Record Types. Actual data is then stored in CaosDB as Records which are of some Record Type.
Those Records can have Properties that contain information about the Record. The following is a more
detailed explanation (also see this [paper](https://www.mdpi.com/2306-5729/4/2/83)).

:::{note}
Record Types and Abstract Properties are used to define the ontology for a particular domain in
which the RDMS (research data management) is used. Records are used to store the actual data and
therefore represent individuals or particular things, e.g. a particular experiment, a particular
time series, etc.
:::

## Record Types

**Record Types** define classes or types of things, e.g. persons, experiments, timeseries, etc.
Records can be viewed as members of the class defined by its Record Type. These classes can contain
Abstract Properties which define key-value relationships for properties of the things along with the
expected data type and possibly the default unit, a default value, or a range of permitted values.
As files on the backend file system are a major focus of this database management system, there is a
special File entity that encapsulates typical file properties like path, size and checksum.

## Entities

**Entities** can be related via binary, directed, transitive is-a relations which model both
subtyping and instantiation, depending on the relation. These relations construct a directed graph
of the Entities. If A is-a B we call A the child of B and B the parent of A. No adamant restrictions
are imposed on the relate of the is-a relation and thus, Entities can be children of multiple
Entities.

## Properties

Each Entity has a list of Entity Properties, or in short just **Properties**. An Entity Property is
not an Entity of its own, but a triple of an Abstract Property, a value or Null, and an Importance.
The values can be numerals, strings, dates, any other valid value that fits into one of several
builtin data types, or, most notably, references to other Entities. The Importance is either
`obligatory`, `recommended`, `suggested`, or `fix`. A valid child of an Entity implicitly inherits
its parent’s Properties according to their Importance, which means that it is obliged, recommended
or only suggested to have a Property with the same Abstract Property (or any subtype thereof). As
opposed to Properties with other priorities, **Fixed Properties** have no effect on the Entity’s
children.

During the creation or update of Entities, the importances of the parents are checked by the server.
Missing obligatory Properties invalidate the transaction and result in an error, by default. Missing
Properties, when they are recommended, result in a warning, but the transaction is considered valid.
Entities with missing suggested Properties are silently accepted as valid.
See [the detailed specification of RecordTypes](/explanation/server/apis/RecordType.md) for more
information on importances and inheritance.

% TODO: The following two sections ("Creating Data Models with PyLinkAhead" and
% TODO: "Property Inheritance") were newly added during the Data-Insertion.md split.
% TODO: Review and edit them to fit this explanation page properly.

## Creating Data Models with PyLinkAhead

RecordTypes and Properties can be created programmatically using the Python client. When creating a
Property, you must specify a datatype. Available basic datatypes include `db.INTEGER`, `db.DOUBLE`,
and `db.TEXT`. See the [full list of datatypes](./Datatype.md).

```python
# Create a Property of type DOUBLE and insert it
property_a = db.Property(name="a", datatype=db.DOUBLE)
property_a.insert()
```

Multiple Properties and a RecordType can be combined into a data model and inserted together using a
`db.Container`.

### Property Inheritance

When creating a child RecordType, the `inheritance` parameter of `add_parent()` controls which
properties are automatically assigned from the parent upon insertion:

```
inheritance = obligatory | recommended | fix | all | none
```

The server assigns all properties of the parent with the specified importance level (and any higher
importance) to the child RecordType automatically. Note that inherited properties are only visible
after insertion, since they are set by the server, not the client.

See the [importance specification](/explanation/server/apis/RecordType.md#importance) for full
details.