logicblocks.event.query
logicblocks.event.query
Section titled “logicblocks.event.query”Clause
Section titled “Clause”class Clause
Bases: ABC
Base class for the parts of a query: filters, sorts and paging.
FilterClause
Section titled “FilterClause”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
Section titled “operator”operator: Operator
field: Path
value: Any
Function
Section titled “Function”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
KeySetPagingClause
Section titled “KeySetPagingClause”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, orNonefor the first page.direction(PagingDirection) — Whether to page after or before the record withlast_id.item_count(int) — The maximum number of records in the page.
last_id
Section titled “last_id”last_id: str | None = None
direction
Section titled “direction”direction: PagingDirection = PagingDirection.FORWARDS
item_count
Section titled “item_count”item_count: int = 10
is_forwards
Section titled “is_forwards”def is_forwards()
Return whether this requests the page after last_id.
is_backwards
Section titled “is_backwards”def is_backwards()
Return whether this requests the page before last_id.
is_first_page
Section titled “is_first_page”def is_first_page()
Return whether this requests the first page.
Lookup
Section titled “Lookup”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
Section titled “filters”filters: Sequence[Clause]
OffsetPagingClause
Section titled “OffsetPagingClause”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
Section titled “page_number”page_number: int
item_count
Section titled “item_count”item_count: int
offset
Section titled “offset”property offset
The number of records preceding the requested page.
Operator
Section titled “Operator”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 ofNonematches a null field.NOT_EQUAL— The field does not equal the value. A value ofNonematches 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
Section titled “NOT_EQUAL”NOT_EQUAL = 'not_equal'
GREATER_THAN
Section titled “GREATER_THAN”GREATER_THAN = 'greater_than'
GREATER_THAN_OR_EQUAL
Section titled “GREATER_THAN_OR_EQUAL”GREATER_THAN_OR_EQUAL = 'greater_than_or_equal'
LESS_THAN
Section titled “LESS_THAN”LESS_THAN = 'less_than'
LESS_THAN_OR_EQUAL
Section titled “LESS_THAN_OR_EQUAL”LESS_THAN_OR_EQUAL = 'less_than_or_equal'
IN = 'in'
CONTAINS
Section titled “CONTAINS”CONTAINS = 'contains'
REGEX_MATCHES
Section titled “REGEX_MATCHES”REGEX_MATCHES = 'regex_matches'
NOT_REGEX_MATCHES
Section titled “NOT_REGEX_MATCHES”NOT_REGEX_MATCHES = 'not_regex_matches'
PagingClause
Section titled “PagingClause”class PagingClause
Bases: Clause
Base class for clauses that limit results to a single page.
PagingDirection
Section titled “PagingDirection”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
Section titled “FORWARDS”FORWARDS = 'forwards'
BACKWARDS
Section titled “BACKWARDS”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
Section titled “top_level”top_level: str
sub_levels
Section titled “sub_levels”sub_levels: Sequence[str | int]
is_nested
Section titled “is_nested”def is_nested()
Return whether the path has any sub-levels.
class Query
Bases: ABC
Base class for queries over stored records.
Search
Section titled “Search”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
Section titled “filters”filters: Sequence[Clause]
sort: Clause | None
paging
Section titled “paging”paging: Clause | None
Similarity
Section titled “Similarity”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
SortClause
Section titled “SortClause”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
Section titled “fields”fields: Sequence[SortField]
SortField
Section titled “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
SortOrder
Section titled “SortOrder”class SortOrder
Bases: StrEnum
Direction in which a SortField orders results.
Attributes:
ASC— Ascending order.DESC— Descending order.
ASC = 'asc'
DESC = 'desc'