Skip to content

logicblocks.event.query

class Clause

Bases: ABC

Base class for the parts of a query: filters, sorts and paging.

class FilterClause(operator: Operator, field: Path, value: Any)

Bases: Clause

Restrict results to those whose field satisfies a comparison.

Attributes:

  • operator (Operator) — The comparison to perform.
  • field (Path) — The path to the value to compare against.
  • value (Any) — The value to compare the field with.
operator: Operator
field: Path
value: Any
class Function(alias: str)

Bases: ABC

Base class for values computed per record during a query.

A function’s result is exposed under its alias, so that it can be used as a SortField.

Attributes:

  • alias (str) — The name under which the computed value is exposed.
alias: str
class KeySetPagingClause(
    last_id: str | None = None,
    direction: PagingDirection = PagingDirection.FORWARDS,
    item_count: int = 10,
)

Bases: PagingClause

Page through results relative to a known record.

Key-set paging identifies a page by the ID of a record at its boundary rather than by position. Records are ordered by any sort clause in the query; the Postgres implementation additionally orders by ID to break ties and, when there is no sort clause, orders by ID alone.

With no last_id, the first item_count records are returned. With a last_id and forwards direction, up to item_count records immediately after that record are returned. With a last_id and backwards direction, up to item_count records immediately before that record are returned, still in sort order. The record with last_id is itself excluded.

Typically, pass the ID of the last record of the current page to move forwards, or the ID of the first record to move backwards.

Attributes:

  • last_id (str | None) — The ID of the record to page relative to, or None for the first page.
  • direction (PagingDirection) — Whether to page after or before the record with last_id.
  • item_count (int) — The maximum number of records in the page.
last_id: str | None = None
direction: PagingDirection = PagingDirection.FORWARDS
item_count: int = 10
def is_forwards()

Return whether this requests the page after last_id.

def is_backwards()

Return whether this requests the page before last_id.

def is_first_page()

Return whether this requests the first page.

class Lookup(*, filters: Sequence[Clause] | None = None)

Bases: Query

Find the records matching some filters, typically to locate one.

Attributes:

  • filters (Sequence[Clause]) — The clauses that records must satisfy, all of which must match. Defaults to no filters.
filters: Sequence[Clause]
class OffsetPagingClause(*, page_number: int = 1, item_count: int = 10)

Bases: PagingClause

Page through results by page number.

Page n skips the first (n - 1) * item_count records, in sort order, and returns up to item_count records. Unlike key-set paging, pages shift if records are added or removed between requests.

Attributes:

  • page_number (int) — The 1-based number of the page to return. Defaults to 1.
  • item_count (int) — The maximum number of records in a page. Defaults to 10.
page_number: int
item_count: int
property offset

The number of records preceding the requested page.

class Operator

Bases: StrEnum

Comparison operators available to a FilterClause.

In each case the left operand is the value at the clause’s field and the right operand is the clause’s value.

Attributes:

  • EQUAL — The field equals the value. A value of None matches a null field.
  • NOT_EQUAL — The field does not equal the value. A value of None matches a non-null field.
  • GREATER_THAN — The field is greater than the value.
  • GREATER_THAN_OR_EQUAL — The field is greater than or equal to the value.
  • LESS_THAN — The field is less than the value.
  • LESS_THAN_OR_EQUAL — The field is less than or equal to the value.
  • IN — The field is one of the values in the given sequence.
  • CONTAINS — The field is a list containing the value.
  • REGEX_MATCHES — The field is a string matching the regular expression given as the value. In memory the expression must match from the start of the value; on Postgres it can match anywhere.
  • NOT_REGEX_MATCHES — The field is a string not matching the regular expression given as the value.
EQUAL = 'equal'
NOT_EQUAL = 'not_equal'
GREATER_THAN = 'greater_than'
GREATER_THAN_OR_EQUAL = 'greater_than_or_equal'
LESS_THAN = 'less_than'
LESS_THAN_OR_EQUAL = 'less_than_or_equal'
IN = 'in'
CONTAINS = 'contains'
REGEX_MATCHES = 'regex_matches'
NOT_REGEX_MATCHES = 'not_regex_matches'
class PagingClause

Bases: Clause

Base class for clauses that limit results to a single page.

class PagingDirection

Bases: StrEnum

Direction to page in, relative to a known record, in key-set paging.

Attributes:

  • FORWARDS — Page through the records after the known record.
  • BACKWARDS — Page through the records before the known record.
FORWARDS = 'forwards'
BACKWARDS = 'backwards'
class Path(top_level: str, *sub_levels: str | int)

A path to a value within a record.

The top level names an attribute of the record (or a column in Postgres) and each sub-level indexes further into its nested value, for example Path("state", "address", "postcode").

Parameters:

  • top_level (str) — The name of the top-level attribute.
  • *sub_levels (str | int) — The keys into the nested value.
top_level: str
sub_levels: Sequence[str | int]
def is_nested()

Return whether the path has any sub-levels.

class Query

Bases: ABC

Base class for queries over stored records.

class Search(
    *,
    filters: Sequence[Clause] | None = None,
    sort: Clause | None = None,
    paging: Clause | None = None,
)

Bases: Query

Find the records matching some filters, sorted and paged.

Filters are applied first, all of which must match, then the sort and finally the paging.

Attributes:

  • filters (Sequence[Clause]) — The clauses that records must satisfy. Defaults to no filters.
  • sort (Clause | None) — The clause by which to order results, if any.
  • paging (Clause | None) — The clause by which to limit results to a page, if any.
filters: Sequence[Clause]
sort: Clause | None
paging: Clause | None
class Similarity(alias: str, *, left: Path, right: str)

Bases: Function

Score the textual similarity between a field and a string.

Scores are based on trigrams and range from 0 (no similarity) to 1 (identical). The Postgres implementation uses the similarity function from the pg_trgm extension, which must be installed; the in-memory implementation approximates it.

Attributes:

  • alias (str) — The name under which the score is exposed.
  • left (Path) — The path to the text to compare.
  • right (str) — The text to compare against.
left: Path
right: str
class SortClause(fields: Sequence[SortField])

Bases: Clause

Order results by one or more fields.

Attributes:

  • fields (Sequence[SortField]) — The fields to sort by, in priority order: later fields only break ties between earlier ones.
fields: Sequence[SortField]
class SortField(field: Path | Function, order: SortOrder)

Bases: Clause

A single field, or function result, to sort by.

Attributes:

  • field (Path | Function) — The path to sort by, or a function whose result is sorted by under its alias.
  • order (SortOrder) — The direction to sort in.
field: Path | Function
order: SortOrder
class SortOrder

Bases: StrEnum

Direction in which a SortField orders results.

Attributes:

  • ASC — Ascending order.
  • DESC — Descending order.
ASC = 'asc'
DESC = 'desc'