S3ResourceFilter

S3ResourceFilter is a class representing the DAL queries and Python filters to select the records for a resource.

Overview

S3ResourceFilters are a part of S3Resources:

They contain the queries and filters to extract the data from the database.

At the time an S3Resource gets defined, a S3ResourceFilter is automatically added to it. This default filter (so called "master query") covers:

• available records (i.e. not deleted)
• accessible records (i.e. access permitted)
• selected records by record ID and/or UID
• joined records (e.g. components)

It is possible to extend this filter during the request:

• by a URL query
• by the S3Resource.add_filter() method

S3ResourceFilters can filter for both real fields in the database table as well as virtual (computed) fields.

Design

S3ResourceFilters consist of a hierarchical set of web2py Query and S3ResourceQuery objects, where:

• Query instances represent the DAL queries ("query")
• S3ResourceQuery instances represent virtual field filters ("vfltr")

It is possible to define S3ResourceQueries even for real fields. When extracting rows from the database table, those parts of a S3ResourceQuery which (only) concern real fields get automatically converted into Query instances and added to the DAL query. Furthermore, where S3ResourceQueries need joins, those get automatically added to the real query as well.

The process for the extraction of rows from the database is as follows:

This process supports pagination (slicing), although that would necessarily not only retrieve the requested page from the database, but all records which match the DAL query. Therefore, the virtual filters should always only be the "last mile", while the DAL query reduces the number of candidates to the necessary minimum.

URL queries

Extending filters at the back-end