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

```{tags} advanced-user, tutorial
```

# High-Level API

:::{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/85
% TODO: This API is unstable, and would likely only need an explanation doc

In addition to the old standard pylib API, new versions of pylib ship with a high-level API that
facilitates usage of LinkAhead entities within data analysis scripts. This API exposes the
Properties of LinkAhead Records as standard python attributes, making them easier to access.

To illustrate this, see the following code snippet:

```python
import linkahead as db
from linkahead.high_level_api import convert_to_python_object

record = db.Record()
record.add_parent("Experiment")
# Adding and retrieving properties in the standard API
record.add_property(name="alpha", value=5)
record.get_property("alpha").value = 25                 # setting properties (old api)
print(record.get_property("alpha").value)               # getting properties (old api)

high_level_record = convert_to_python_object(record)    # convert record into a high-level entity
# Adding and retrieving properties in the high-level API
high_level_record.beta = 25
print(high_level_record.beta)
```

:::{warning}
The high-level API is experimental and functions may be unstable.
:::

## Quickstart

The high-level API is contained in the `linkahead.high_level_api` module.
There are two functions converting entities between the two representation (old API and new API):

- `convert_to_python_object`: Convert entities from **old** into **new** representation.
- `convert_to_entity`: Convert entities from **new** into **old** representation.

Furthermore, there are a few utility functions which expose useful shorthands:

- `new_high_level_entity`: Retrieve a record type and create a new high-level entity which contains
  properties of a certain importance level preset.
- `create_record`: Create a new high-level entity using the name of a record type and a list of key
  value pairs as properties.
- `load_external_record`: Retrieve a record with a specific name and return it as high-level entity.
- `create_entity_container`: Convert a high-level entity into a standard entity including all sub
  entities.
- `query`: Do a LinkAhead query and return the result as a container of high-level objects.

So as a first example, you could retrieve any record from LinkAhead and use it with its high-level
representation:

```python
from linkahead.high_level_api import query

# Retrieve an entity
entity_list = query("FIND Experiment")
experiment = entity_list[0]

# Use a property:
print(experiment.date)

# Use sub properties:
print(experiment.output[0].path)
```

This example demonstrates how references are retrieved automatically in the high-level API. For
default parameter values, it automatically resolves and retrieves references recursively. This means
that sub properties, like the list of output files "output", are available immediately.

Note that for the old API you were supposed to run the following series of commands to achieve
the same result:

```python
import linkahead as db

# Retrieve an entity
container = db.execute_query("FIND Experiment")
experiment = container[0]

# Use a property:
print(experiment.get_property("date"))

# Use sub-properties:
output_file_id = experiment.get_property("output").value[0].id
output_file = db.File(id=output_file_id).retrieve()
print(output_file.path)
```

Resolving sub-properties makes use of the `resolve_reference` function provided by the high
level entity class (`LinkAheadPythonEntity`), with the following parameters:

- `deep`: Whether to use recursive retrieval
- `references`: Whether to use the supplied db.Container to resolve references. This allows offline
  usage. Set it to None if you want to automatically retrieve entities from the current LinkAhead
  connection.
- `visited`: Needed for recursion, should not be set.

Objects in the high-level representation can be serialized to a simple yaml form using the function
`serialize` with the following parameters:

- `without_metadata`: Set this to True if you don't want to see property metadata like "unit" or "
  importance".
- `visited`: Needed for recursion, set this to None.

This function creates a simple dictionary containing a representation of the entity, which can be
stored to disk and completely deserialized using the function `deserialize`.

Furthermore, the "*str*" function is overloaded, so that you can use print to directly inspect high
level objects using the following statement:

```python
print(str(obj))
```

## Concepts

As described in the section Quickstart the two functions `convert_to_python_object` and
`convert_to_entity` convert entities between the high-level and the standard representation.

The high-level entities are represented using the following classes from the module
`linkahead.high_level_api`:

- `LinkAheadPythonEntity`: Base class of the following entity classes.
- `LinkAheadPythonRecord`
- `LinkAheadPythonRecordType`
- `LinkAheadPythonProperty`
- `LinkAheadPythonFile`: Used for file entities and provides an additional `download` function for
  being able to directly retrieve files from LinkAhead.
% TODO: - `LinkAheadPythonMultiProperty`:

In addition, there are the following helper structures which are realized as Python data classes:

- `LinkAheadPropertyMetaData`: For storing meta data about properties.
- `LinkAheadPythonUnresolved`: The base class of unresolved entities.
- `LinkAheadPythonUnresolvedParent`: Parents of entities are stored as unresolved parents by
  default, storing an id or a name of a parent (or both).
- `LinkAheadPythonUnresolvedReference`: An unresolved reference is a reference property with an id
  which has not (yet) been resolved to an Entity.

The function `resolve_references` can be used to recursively replace
`LinkAheadPythonUnresolvedReferences` into members of type `LinkAheadPythonRecords` or
`LinkAheadPythonFile`.

Each property stored in a LinkAhead record corresponds to:

- a member attribute of `LinkAheadPythonRecord` **and**
- an entry in a dict called "metadata" storing a LinkAheadPropertyMetadata object with the following
  information about properties:
    - `unit`
    - `datatype`
    - `description`
    - `id`
    - `importance`