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 License for the specific language governing permissions and limitations
under the License. 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 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 v3 identity API. By default these queries are satisfied in the API resource when
class when a controller calls the ``wrap_collection`` method at the end of a it calls the ``wrap_collection`` method at the end of a ``get`` method. However,
``list_{entity}`` method. However, to enable optimum performance, any driver to enable optimum performance, any driver can implement some or all of the specified
can implement some or all of the specified filters (for example, by adding filters (for example, by adding filtering to the generated SQL statements to generate
filtering to the generated SQL statements to generate the list). the list).
The communication of the filter details between the controller level and its The communication of the filter details between the API resource and its drivers is
drivers is handled by the passing of a reference to a Hints object, handled by the passing of a reference to a Hints object, which is a list of dicts
which is a list of dicts describing the filters. A driver that satisfies a describing the filters. A driver that satisfies a filter must delete the filter from
filter must delete the filter from the Hints object so that when it is returned the Hints object so that when it is returned to the API, it knows to only execute any
to the controller level, it knows to only execute any unsatisfied unsatisfied filters.
filters.
The contract for a driver for ``list_{entity}`` methods is therefore: 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 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 formed searches (e.g. without sufficient filters) from becoming a performance
issue. issue.
These limits are set in the configuration file, either for a specific driver or 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 across all drivers. A global ``list_limit`` set in ``[DEFAULT]`` section of
individual drivers as part of the Hints list object. A driver should try and keystone is considered in case no limit is set for specific driver. These
honor any such limit if possible, but if it is unable to do so then it may limits are read at the Manager level and passed into individual drivers as part
ignore it (and the truncation of the returned list of entities will happen at of the Hints list object. A driver should try and honor any such limit if possible,
the controller level). 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).