Result specifications are used by the Data API to describe the desired results of a
They can be used to filter, sort and paginate the contents of collections, and to limit the fields returned for each item.
Python calls to
get call can pass a
ResultSpec instance directly.
Requests to the HTTP REST API are converted into instances automatically.
Implementers of Data API endpoints can ignore result specifications entirely, except where efficiency suffers.
Any filters, sort keys, and so on still present after the endpoint returns its result are applied generically.
ResultSpec instances are mutable, so endpoints that do apply some of the specification can remove parts of the specification.
Result specifications are applied in the following order:
- Field Selection (fields)
- Pagination (limit/offset)
Only fields & properties are applied to non-collection results. Endpoints processing a result specification should take care to replicate this behavior.
A result specification has the following attributes, which should be treated as read-only:
A list of field names that should be included, or
Nonefor no sorting. if the field names all begin with
-, then those fields will be omitted and all others included.
A list of field names to sort on. if any field name begins with
-, then the ordering on that field will be in reverse.
The maximum number of collection items to return.
The 0-based index of the first collection item to return.
- A list of
Propertyinstances to be applied. The result is a logical AND of all properties.
All of the attributes can be supplied as constructor keyword arguments.
Endpoint implementations may call these methods to indicate that they have processed part of the result spec. A subsequent call to
applywill then not waste time re-applying that part.
If a property exists, return its values list and remove it from the result spec.
If a filter exists for the given field and operator, return its values list and remove it from the result spec.
If a filter exists for the field, remove it and return the expected value (True or False); otherwise return None. This method correctly handles odd cases like
If one string filter exists for the field, remove it and return the expected value (as string); otherwise return None.
If one integer filter exists for the field, remove it and return the expected value (as integer); otherwise return None. raises ValueError if the field is not convertible to integer.
Remove the order attribute.
Remove a single field from the
fieldsattribute, returning True if it was present. Endpoints can use this in conditionals to avoid fetching particularly expensive fields from the DB API.
The following method is used internally to apply any remaining parts of a result spec that are not handled by the endpoint.
Apply the result specification to the data, returning a transformed copy of the data. If the data is a collection, then the result will be a
Filter(field, op, values)¶
- field (string) -- the field to filter on
- op (string) -- the comparison operator (e.g., "eq" or "gt")
- values (list) -- the values on the right side of the operator
A filter represents a limitation of the items from a collection that should be returned.
Many operators, such as "gt", only accept one value. Others, such as "eq" or "ne", can accept multiple values. In either case, the values must be passed as a list.
Parameters: values (list) -- the values on the right side of the operator (
A property represents an item of a foreign table.
In either case, the values must be passed as a list.