Query¶
The Query class allows you to build and execute queries to retrieve entities from the data source based on specific conditions. A query can return a single entity, a list of entities, or a paginated set.
Every entity also exposes a .query shortcut that returns a pre-configured Query instance for that entity type:
Attributes¶
Below are the attributes available on a Query instance:
-
filters: The list of filter conditions added viawhere(). -
order: The list of properties by which to sort the results. -
projection: The list of properties to include or exclude in the result. -
distinct_on: The list of properties for which the resulting entities should be distinct. -
limit: The maximum number of entities to retrieve. -
offset: The number of initial entities to skip before starting retrieval. -
page_size: The number of entities to retrieve per page. -
page_token: The token representing the desired page of results.
Building a Query¶
Instantiate a Query by passing the entity class you want to query:
All builder methods return self, so they can be chained:
where¶
The where() method adds a filter condition to the query. It accepts either two arguments (property, value) — in which case = is assumed as the operator — or three arguments (property, operator, value):
query = Query(Portfolio)
query.where('name', 'My Portfolio')
# equivalent to:
query.where('name', '=', 'My Portfolio')
Supported operators are =, <, <=, >, >=, and IN.
Filtering by date — when the operator is =, a full-day range is created automatically:
query = Query(Portfolio)
query.where('date', '=', '2023-08-10')
# expands to: date >= 2023-08-10 00:00:00 AND date <= 2023-08-10 23:59:59
Filtering by tags — pass a single string or a list of strings:
Filtering by a list — use the IN operator with a list of values:
from everysk.sdk.entities import File
query = Query(File)
query.where('content_type', 'IN', ['text/csv', 'application/pdf'])
Filtering by link_uid — filter by a single value or multiple values using IN:
query = Query(Portfolio)
query.where('link_uid', 'my-link-uid')
# match any of several link UIDs
query = Query(Portfolio)
query.where('link_uid', 'IN', ['link-a', 'link-b'])
Passing an unsupported operator raises an SDKValueError:
sort_by¶
The sort_by() method adds a property to the sort order. Prefix the property name with - for descending order:
Adding a property that is not sortable or that has already been added raises a ValueError:
query.sort_by('invalid_property')
# ValueError: invalid_property is not sortable
query.sort_by('date')
# ValueError: Duplicated order property: date in ['date']
set_projection¶
The set_projection() method specifies which properties to include or exclude from the result. Pass a string or a list of strings. Prefix a property name with - to exclude it (inverse projection):
# Include only name and date
query = Query(Portfolio)
query.set_projection(['name', 'date'])
# Exclude date
query.set_projection(['-date'])
Mixing inclusion and exclusion in the same call raises a ValueError:
query.set_projection(['name', '-date'])
# ValueError: Projection and Inverse Projection should not be set in the same query
set_distinct_on¶
The set_distinct_on() method specifies the properties for which the resulting entities should be distinct. Pass a string or a list of strings:
set_limit¶
Sets the maximum number of entities the query should return:
The value must be an integer greater than or equal to 0, otherwise an SDKValueError is raised.
set_offset¶
Sets the number of initial entities to skip before retrieval begins:
The value must be an integer greater than or equal to 0, otherwise an SDKValueError is raised.
set_page_size¶
Sets the number of entities to retrieve per page in a paginated query:
The value must be an integer greater than or equal to 0, otherwise an SDKValueError is raised.
set_page_token¶
Sets the page token to resume from a specific page:
set_find_or_fail¶
When set to True, the query raises an error if no entity is found instead of returning None:
load¶
Fetches a single entity matching the query. Returns the entity instance or None if nothing is found. An optional offset can be passed to skip results:
portfolio = Query(Portfolio).where('name', 'My Portfolio').load()
portfolio.name
# 'My Portfolio'
# Skip the first result and return the second match
portfolio = Query(Portfolio).where('name', 'My Portfolio').load(offset=1)
loads¶
Fetches a list of entities matching the query. Returns an empty list if nothing is found. Optional limit and offset parameters control the result set:
portfolios = Query(Portfolio).where('tags', 'equity').loads()
# [<Portfolio ...>, <Portfolio ...>, ...]
# Fetch up to 2 results, skipping the first
portfolios = Query(Portfolio).where('tags', 'equity').loads(limit=2, offset=1)
page¶
Fetches a single page of entities. Returns a QueryPage dictionary with entities and next_page_token keys:
result = Query(Portfolio).page(page_size=10)
len(result['entities'])
# up to 10 — depends on available data
result['next_page_token']
# 'eyJvZmZzZXQiOiAxMH0=' (None if this is the last page)
Pass the token from the previous response to retrieve the next page:
pages¶
A generator that iterates over all pages automatically. Yields one list of entities per page until no more pages are available:
for page in Query(Portfolio).where('tags', 'equity').pages(page_size=10):
for portfolio in page:
print(portfolio.name)
fetch_ids¶
Fetches only the IDs of matching entities instead of full entity objects. Optional limit and offset parameters are supported:
ids = Query(Portfolio).where('tags', 'equity').fetch_ids()
# ['port_abc123', 'port_def456', ...]
ids = Query(Portfolio).fetch_ids(limit=5, offset=10)
fetch_id¶
Fetches the ID of a single matching entity. Returns the ID string or None if nothing is found. An optional offset can be provided:
entity_id = Query(Portfolio).where('name', 'My Portfolio').fetch_id()
# 'port_abc123'
entity_id = Query(Portfolio).where('name', 'My Portfolio').fetch_id(offset=1)