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

```{tags} explanation, developer
```

# Features of interest

:::{note}
This new documentation page has not yet been fully reviewed and may be incomplete.
:::
% TODO: Issue:
% TODO: Exceptions: Maybe use sphinx.ext.inheritance_diagram to generate a tree.

This page briefly explains some additional features and concepts of the python
library which may be useful.

## Exceptions

In case of erroneous transactions, connection problems or other problems, PyLinkAhead may raise
exceptions. Some of these errors are representations of errors encountered in the LinkAhead server,
others stem from problems on the client side.

Exceptions are ordered hierarchically from general exceptions to specific transaction or connection
problems. The base exception class for LinkAhead errors is `LinkAheadException`. For more
information on specific error types, see
the [code documentation](/reference/pylib/api/linkahead.exceptions.rst).

## Querying

Apart from the general `query` function, there are dedicated functions for each query type, named
`find`, `select`, and `count` for their supported keywords. The `find` and `select` functions return
Containers with Entities, while `count` returns the returned integer.

Additionally, to retrieve a Record by a unique identifier, `get_entity_by` can be used. This
function takes exactly one of `eid`, `name`, `path`, or `query` as parameter, and retrieves and
returns the Record identified by this, or raises an error if there are either no or several entities
fitting the request. If identifying an entity by `eid` or `name`, the parameter `role` can be used
to restrict the type of Entity (Record, RecordType, Property or File) to be retrieved.

### Query Pagination

For retrieval of many entities using a `FIND` query, it may be preferable to retrieve the results
in 'batches' rather than retrieve the entire result at once, for example for performance reasons or
to prevent connection timeouts. For this there is the `find_paginated` function, which is given the
requested size of each 'batch' in the `page_length` parameter, and returns a generator which yields
Containers with the requested amount of entities. This generator can then be used in loops or
comprehensions to iterate through each 'batch' of entities. Apart from this, its usage largely
matches `find`.

:::{note}
If your database changes while iterating over a paginated query, for example if a record was
inserted or updated, a `PagingConsistencyError` will be raised, as the query results may have
changed in the meantime.
:::

### Caching

To speed up repetitive queries, the Python client has an optional client-side cache, shared between
all query functions. It can be activated for a call using the `client_cached` parameter. If
`client_cached` is set to true, the result of the query to execute is retrieved from the cache if
present, or from the server if not and then added to the cache. As the cache does not automatically
invalidate data if the server state is changed, not even if this change is initiated by the current
client, this may mean the request returns outdated data differing from the current server state.
This means that it should usually only be used if you can either guarantee that the server state
will not change during the lifetime of the cache, or that any changes will not be relevant.

Administrative functions for the cache are collected as static methods by the `ClientQueryCache`
class. Most importantly, `ClientQueryCache.clear()` can be used to clear the cache.

:::{note}
To avoid working with outdated data, please use the cache with care and make sure to clear it when
needed.
:::