linkahead.queries module#

This module collects convenience methods for querying.

class linkahead.queries.ClientQueryCache#

Bases: object

Singleton convenience wrapper for cache administration.

CACHE_SIZE: int = 33333#

DEFAULT_SIZE: Final[int] = 33333#

DUMMY_CACHE: dict[str, Any] = {}#

classmethod clear() → None#: Empty the client-side query cache.

classmethod fill(items: dict[str | int | tuple[str, str] | tuple[str, int], Any], kind: str = 'eid', flags: dict | None = {}, unique: bool = False, raise_exception_on_error: bool = True, page_length: int | None = None) → None#

Add entries to the cache without actually submitting queries. Note that this does not overwrite existing entries with the same keys.

Parameters:

items (dict[Union[str, int, tuple[str, str], tuple[str, int]], Any]) – The new items to insert. Keys can be ids, names, paths, tuples of id and role, tuples of name and role, or queries. Values are the new return values for the specified requests.
kind (str, default "eid") – The kind of item specified - one of eid, name, path or query.
of (All further parameters are forwarded to _cached_query and are a part)
cache. (the retrieval key for the)

classmethod info() → CacheInfo#

Get info about the cache.

Returns:: out – Information on the client-side query cache.
Return type:: _ClientQueryCacheInfo

classmethod initialize(maxsize: int | None = None) → None#: Empty the existing cache and re-initialize it with size maxsize if given, cache_size otherwise. If given, cache_size is overwritten by maxsize.

class linkahead.queries.QueryType(*values)#

Bases: Enum

COUNT = 'COUNT'#

FIND = 'FIND'#

SELECT = 'SELECT'#

classmethod from_query(query: str) → QueryType | None#: Get the type of the given query, or None if it does not start with a valid keyword.

linkahead.queries.count(query: str, *, flags: dict | None = None, raise_exception_on_error: bool = True, client_cached: bool = False, server_cached: bool | None = None) → int#

Execute a COUNT query and return the result as int.

For documentation of the function parameters refer to the query function.

Returns:: result – The number of entities fitting the given restraints.
Return type:: int

See also

find: Function to execute a FIND query.

linkahead.queries.find(query: str, *, flags: dict | None = None, raise_exception_on_error: bool = True, client_cached: bool = False, server_cached: bool | None = None) → Container#

Execute a FIND query and return a Container with the resulting Entities.

Parameters:

query (str) – The query to execute.
flags (dict of str, optional, keyword-only) – Flags to be added to the request.
raise_exception_on_error (bool, default True, keyword-only) – Sets whether an exception is raised for errors in the resulting entities.
client_cached (bool, default False, keyword-only) – Sets whether to use the client-side query caching.
server_cached (bool or None, default True, keyword-only) – Sets whether to use the server-side query caching.

Returns:

result – A Container with the resulting Entities.

Return type:

db.Container[db.Entity]

See also

count: Function to execute a COUNT query.
select: Function to execute a SELECT query.
query: Function to execute an arbitrary query.
paginated_query: Function to execute a paginated query, returns a generator.
get_entity_by: Function to retrieve a single, uniquely identified entity.

linkahead.queries.find_paginated(query: str, *, page_length: int = 10, **kwargs) → Iterator[Container]#

Executes a FIND query while paginating the results, meaning that for each page, another call to the server is made. The returned generator yields containers with up to page_length of the resulting entities.

Parameters:

query (str) – The query to execute. Must be a FIND query.
page_length (int, default 10, keyword-only) – The number of Entities that should be present per yielded db.Container.
**kwargs – Further keyword arguments are passed to the underlying query function. Valid arguments are [‘client_cached’, ‘server_cached’, ‘raise_exception_on_error’, ‘flags’]. For details check the documentation of the ‘find’ function.

Yields:

page (Container) – Returns a container with the next page_length resulting entities.

Raises:

PagingConsistencyError – If page_length is set and the database state changed between paged requests.
ValueError – If given a COUNT or SELECT query or invalid keyword arguments.

See also

find: Function for non-paginated FIND queries.
query: General query function.

Return the result of a unique query that uses one of id, name, path or query to find and return the correct entity. Exactly one of these parameters should be set.

Parameters:

eid (str or int, optional, keyword-only) – If set, retrieves the entity with the given ID.
name (str, optional, keyword-only) – If set, retrieves the entity with the given name. There must not be other entities with this name-role combination.
path (str, optional, keyword-only) – If set, retrieves the file with the given path.
query (str, optional, keyword-only) – If set, executes the given query and returns the resulting Entity. The query must return exactly one Record.
role (db.Role, default Entity, keyword-only) – Can be set to one of [“Entity”, “Record”, “RecordType”, “Property”, “File”], to specify which kind of Entity to retrieve. Does not apply when retrieving by query or path.
client_cached (bool, default False, keyword-only) – Passed to query call, sets whether to us the cache on client side.
**kwargs – Further keyword arguments are passed to the underlying query function. Valid arguments are [‘server_cached’, ‘raise_exception_on_error’, ‘flags’]. For details check the documentation of the ‘query’ function.

Returns:

entity – The retrieved Entity.

Return type:

db.Entity

Raises:

EmptyUniqueQueryError – If the given filters fit no Entities on the server.
QueryNotUniqueError – If the given filters fit several Entities on the server.
ValueError – If none or more than one of the arguments [eid, name, path, query] are set, or if invalid keyword arguments are supplied.

See also

find: Query function for FIND queries which return several entities.

linkahead.queries.query(query: str, *, flags: dict | None = None, raise_exception_on_error: bool = True, client_cached: bool = False, server_cached: bool | None = None) → Any#

Execute any query and return a Container with the resulting Entities, or an int if the given query is a COUNT query. Should only be used if the type of the query to be executed cannot be known.

For documentation of the function parameters refer to the find function.

Returns:: result – A Container with the resulting Entities. If given query is a COUNT query, returns an int instead.
Return type:: db.Container[db.Entity] or int

See also

find: Function to execute a FIND query.
count: Function to execute a COUNT query.
select: Function to execute a SELECT query.

linkahead.queries.query_from(*, eid: str | int | None, name: str | None, path: str | None, role: str = 'ENTITY') → str#

Supply one of eid, name, or path to get the canonical query string for retrieving an entity using this identifier, optionally narrowed using the entity’s role. Convenience wrapper around query_from_eid, query_from_name and query_from_path.

Parameters:

eid (str or int, optional, keyword-only) – Get the canonical query string for retrieving an entity by the given id.
name (str, optional, keyword-only) – Get the canonical query string for retrieving an entity by the given name.
path (str, optional, keyword-only) – Get the canonical query string for retrieving an entity by the given path.
role (db.Role, default Entity, keyword-only) – Can be set to one of [“Entity”, “Record”, “RecordType”, “Property”, “File”], to specify which kind of Entity the query should retrieve.

Returns:

query – The requested query.

Return type:

str

linkahead.queries.query_from_eid(eid: str | int, role: str = 'ENTITY') → str#: Get the canonical query string for retrieving an entity by id.

linkahead.queries.query_from_name(name: str, role: str = 'ENTITY') → str#: Get the canonical query string for retrieving an entity by name.

linkahead.queries.query_from_path(path: str) → str#: Get the canonical query string for retrieving a file by path.

linkahead.queries.select(query: str, *, flags: dict | None = None, raise_exception_on_error: bool = True, client_cached: bool = False, server_cached: bool | None = None) → Container#

Execute a SELECT query and return a Container with the resulting Entities.

For documentation of the function refer to the find function.

See also

find: Function to execute a FIND query.