---
last_review: "2026-05-06"
last_reviewer: "s.kaviani"
documented_code: [ ]
---

```{tags} user, tutorial
```

% Issue: https://gitlab.indiscale.com/caosdb/src/linkahead-docs/-/issues/72

# First Steps with PyLinkAhead

In this tutorial, you will connect to a LinkAhead server using the Python client, run queries, work
with the returned data, and extract property values for analysis. The web interface is convenient
for interactive browsing, while PyLinkAhead is designed for scripting, automation, and data analysis
workflows.

| Concept                 | PyLinkAhead                 |
|-------------------------|-----------------------------|
| Connect to a server     | `db.configure_connection()` |
| Run a query             | `db.execute_query()`        |
| Access a record         | `Container[0]`, `Record`    |
| Read a property         | `.get_property()`           |
| Read a property's value | `.value`                    |
| Record id               | `.id`                       |
| Single-result queries   | `unique=True`               |
| Download a file         | `.download()`               |

## Prerequisites

Before starting, make sure that:

- PyLinkAhead is installed: see the [setup guide](/how_to/dev_guides/pylib/README_SETUP_pylib.md).
- A connection is configured for your instance:
  see [How to Configure PyLinkAhead](/how_to/dev_guides/pylib/configure_pylinkahead.md). For this
  tutorial you can skip this and use the public demo instead.
- You have access to a LinkAhead instance: you can use
  the [public demo](https://demo.indiscale.com).
- You are familiar with basic LinkAhead concepts such as Records, RecordTypes, and Properties: see
  the [LinkAhead Web Interface Tutorial](/tutorial/webinterface/first_steps.md).
- You know the basics of the LinkAhead query language: see
  the [LinkAhead Query Tutorial](/tutorial/webinterface/query_find.md).

% TODO: The specific values in the examples below (number of results, property ids, record ids)
% TODO: depend on the current state of the demo instance and should be verified if the demo data
% TODO: changes.

The examples below use the public demo instance hosted by [IndiScale](https://indiscale.com).

## Setup

### Connecting to a LinkAhead Server

In regular use, PyLinkAhead reads connection settings from `~/.pylinkahead.ini` automatically when
you import the library, no extra code needed. This tutorial uses `configure_connection()` instead to
keep the examples self-contained and work with the public demo out of the box.

Open a Python interactive session (`python3` in your terminal) or create a new `.py` script file.
All code examples on this page are Python, not shell commands.

First, import the Python client:

```python
import linkahead as db
```

Then configure the connection to the demo instance:

```{literalinclude} /.assets/tests/tutorials/pylib/test_first_steps.py
:start-after: "# ---- LINK-1 ----"
:end-before: "# ---- LINK-2 ----"
:language: python
:dedent:
```

:::{note}
`password_method="plain"` is suitable only for the public demo instance and should not be used for
production systems.
:::

## Querying Data

### Running Your First Query

Queries in PyLinkAhead use the same query language as the web interface. The demo instance contains
a small music dataset with guitar records and musical analyses.

```{literalinclude} /.assets/tests/tutorials/pylib/test_first_steps.py
:start-after: "# ---- LINK-3 ----"
:end-before: "# ---- LINK-4-1 ----"
:language: python
:dedent:
```

The result is returned as a `Container` object:

```{literalinclude} /.assets/tests/tutorials/pylib/test_first_steps.py
:start-after: "EXPECTED_OUTPUT_1 "
:end-before: "# END_EXPECTED_OUTPUT_1"
:caption: Output:
:class: text-output
:language: text
:dedent:
```

A `Container` behaves similarly to a Python list and contains the matching LinkAhead entities. You
can check how many results were returned:

```{literalinclude} /.assets/tests/tutorials/pylib/test_first_steps.py
:start-after: "# ---- LINK-4-2 ----"
:end-before: "# ---- LINK-5 ----"
:language: python
:dedent:
```

```{literalinclude} /.assets/tests/tutorials/pylib/test_first_steps.py
:start-after: "EXPECTED_OUTPUT_2 "
:end-before: "# END_EXPECTED_OUTPUT_2"
:caption: Output:
:class: text-output
:language: text
:dedent:
```

### Working with Records

You can access individual records using normal list indexing and print them to see their full
representation including parent and properties:

```{literalinclude} /.assets/tests/tutorials/pylib/test_first_steps.py
:start-after: "# ---- LINK-6 ----"
:end-before: "# ---- LINK-7 ----"
:language: python
:dedent:
```

```{code-block} text
:caption: Output:
:class: text-output

<Record id="115" name="My first guitar">
  <Version id="cf205bfafd852c1aba3a6eee8b502feeff89e320" head="true">
    <Predecessor id="595403aae4bb593712b0aa653f70f6a8be0e0a42"/>
  </Version>
  <Parent id="110" name="Guitar" flag="inheritance:NONE,"/>
  <Property id="100" name="price" datatype="DOUBLE" unit="€" ...>48.0</Property>
  <Property id="106" name="electric" datatype="BOOLEAN" ...>False</Property>
  <Property id="131" name="Photograph" datatype="Photograph" ...>132</Property>
</Record>
```

The `...` in the output above is an abbreviation; the actual output includes additional attributes
on each property.

A `Record` contains metadata and properties that can be accessed programmatically.

### Accessing Properties

Properties can be accessed by name:

```{literalinclude} /.assets/tests/tutorials/pylib/test_first_steps.py
:start-after: "# ---- LINK-12 ----"
:end-before: "# ---- LINK-13 ----"
:language: python
:dedent:
```

```{code-block} text
:caption: Output:
:class: text-output

<Property id="100" name="price" datatype="DOUBLE" unit="€">48.0</Property>
```

To access only the value:

```{literalinclude} /.assets/tests/tutorials/pylib/test_first_steps.py
:start-after: "# ---- LINK-13 ----"
:end-before: "# ---- LINK-14 ----"
:language: python
:dedent:
```

```{code-block} text
:caption: Output:
:class: text-output

48.0
```

Properties can also be accessed by their numeric id:

```{literalinclude} /.assets/tests/tutorials/pylib/test_first_steps.py
:start-after: "# ---- LINK-14 ----"
:end-before: "# ---- LINK-15 ----"
:language: python
:dedent:
```

```{code-block} text
:caption: Output:
:class: text-output

<Property id="100" name="price" datatype="DOUBLE" unit="€">48.0</Property>
```

Using ids can be useful when names are not guaranteed to be unique across a data model.

### Querying for a Single Record

Pass `unique=True` when you know a query returns exactly one record. It is useful as a safety check:
instead of silently returning the first item from a list, it raises an error if zero or more than
one result is found, so unexpected data does not go unnoticed. The call also returns a `Record`
directly instead of a `Container`, so you do not need to index into a list. The demo contains one
`MusicalAnalysis` record with `quality_factor=0.08`:

```{literalinclude} /.assets/tests/tutorials/pylib/test_first_steps.py
:start-after: "# ---- LINK-16 ----"
:end-before: "# ---- LINK-17 ----"
:language: python
:dedent:
```

You can then access the record type and id directly:

```{literalinclude} /.assets/tests/tutorials/pylib/test_first_steps.py
:start-after: "# ---- LINK-17 ----"
:end-before: "# ---- LINK-18 ----"
:language: python
:dedent:
```

```{code-block} text
:caption: Output:
:class: text-output

<class 'linkahead.common.models.Record'>
123
```

Record ids are useful for constructing follow-up queries:

```{literalinclude} /.assets/tests/tutorials/pylib/test_first_steps.py
:start-after: "# ---- LINK-19 ----"
:end-before: "# ---- LINK-20 ----"
:language: python
:dedent:
```

```{code-block} text
:caption: Output:
:class: text-output

<Record id="115" ...
```

## Analyzing Data

### Extracting Values from Multiple Records

The demo contains `MusicalAnalysis` records with a `quality_factor` property. Query them:

```{literalinclude} /.assets/tests/tutorials/pylib/test_first_steps.py
:start-after: "# ---- LINK-23 ----"
:end-before: "# ---- LINK-24 ----"
:language: python
:dedent:
```

Iterate over the container to collect all values:

```{literalinclude} /.assets/tests/tutorials/pylib/test_first_steps.py
:start-after: "# ---- LINK-25 ----"
:end-before: "# ---- LINK-26 ----"
:language: python
:dedent:
```

```{code-block} text
:caption: Output:
:class: text-output

[0.08]
```

You can use these values with standard Python libraries, for example to create a histogram:

```python
import matplotlib.pyplot as plt

plt.hist(qfs)
plt.xlabel("quality factor")
plt.ylabel("count")
plt.show()
```

:::{note}
This example is illustrative and not backed by an automated test.
:::

## Working with Files

### Downloading Files

File records can be downloaded directly from Python. The demo instance contains a photo of the first
guitar we queried earlier:

```{literalinclude} /.assets/tests/tutorials/pylib/test_first_steps.py
:start-after: "# ---- LINK-21 ----"
:end-before: "# ---- LINK-22 ----"
:language: python
:dedent:
```

The downloaded file is stored locally, and the path is returned as `target_path`.

For large datasets, it can be more efficient to access files through a mounted filesystem instead of
downloading them through the API.

## Summary

This tutorial covered:

- Connecting to a LinkAhead server.
- Running queries from Python.
- Working with `Container` and `Record` objects.
- Accessing record properties by name and id.
- Extracting property values from multiple records.
- Using ids in follow-up queries.
- Downloading files.

Continue with [Creating a Data Model](Data-Insertion.md) to create Properties, RecordTypes, and
inheritance hierarchies in LinkAhead.