Tags: explanation, developer

Features of interest

Note

This new documentation page has not yet been fully reviewed and may be incomplete.

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.

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.