openstack
/
keystone
Code Issues Proposed changes

Merge "Update filtering-responsibilities and truncation"

This commit is contained in:
Zuul 2020-06-09 11:20:20 +00:00 committed by Gerrit Code Review
parent 73dc3cebd3 db57d74fe4
commit c27c9d258d
2 changed files with 20 additions and 20 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

27
doc/source/contributor/filtering-responsibilities.rst
View File

@ -14,23 +14,22 @@
License for the specific language governing permissions and limitations
under the License.
==========================================================
Filtering responsibilities between controllers and drivers
==========================================================
============================================================
Filtering responsibilities between API resources and drivers
============================================================
Keystone supports the specification of filtering on list queries as part of the
v3 identity API. By default these queries are satisfied in the controller
class when a controller calls the ``wrap_collection`` method at the end of a
``list_{entity}`` method. However, to enable optimum performance, any driver
can implement some or all of the specified filters (for example, by adding
filtering to the generated SQL statements to generate the list).
v3 identity API. By default these queries are satisfied in the API resource when
it calls the ``wrap_collection`` method at the end of a ``get`` method. However,
to enable optimum performance, any driver can implement some or all of the specified
filters (for example, by adding filtering to the generated SQL statements to generate
the list).
The communication of the filter details between the controller level and its
drivers is handled by the passing of a reference to a Hints object,
which is a list of dicts describing the filters. A driver that satisfies a
filter must delete the filter from the Hints object so that when it is returned
to the controller level, it knows to only execute any unsatisfied
filters.
The communication of the filter details between the API resource and its drivers is
handled by the passing of a reference to a Hints object, which is a list of dicts
describing the filters. A driver that satisfies a filter must delete the filter from
the Hints object so that when it is returned to the API, it knows to only execute any
unsatisfied filters.
The contract for a driver for ``list_{entity}`` methods is therefore:

13
doc/source/contributor/list-truncation.rst
View File

@ -19,13 +19,14 @@ Entity list truncation by drivers
=================================
Keystone supports the ability for a deployment to restrict the number of
entries returned from ``list_{entity}`` methods, typically to prevent poorly
entries returned from list operations, typically to prevent poorly
formed searches (e.g. without sufficient filters) from becoming a performance
issue.
These limits are set in the configuration file, either for a specific driver or
across all drivers. These limits are read at the Manager level and passed into
individual drivers as part of the Hints list object. A driver should try and
honor any such limit if possible, but if it is unable to do so then it may
ignore it (and the truncation of the returned list of entities will happen at
the controller level).
across all drivers. A global ``list_limit`` set in ``[DEFAULT]`` section of
keystone is considered in case no limit is set for specific driver. These
limits are read at the Manager level and passed into individual drivers as part
of the Hints list object. A driver should try and honor any such limit if possible,
but if it is unable to do so then it may ignore it (and the truncation of the
returned list of entities will happen at the API level by ``wrap_collection`` method).