diff --git a/cassandra/policies.py b/cassandra/policies.py index 25565a2c..466a4cdc 100644 --- a/cassandra/policies.py +++ b/cassandra/policies.py @@ -485,6 +485,10 @@ class HostFilterPolicy(LoadBalancingPolicy): load_balancing_policy=blacklist_filter_policy, ) + See the note in the :meth:`.make_query_plan` documentation for a caveat on + how wrapping ordering polices (e.g. :class:`.RoundRobinPolicy`) may break + desirable properties of the wrapped policy. + Please note that whitelist and blacklist policies are not recommended for general, day-to-day use. You probably want something like :class:`.DCAwareRoundRobinPolicy`, which prefers a local DC but has @@ -546,10 +550,15 @@ class HostFilterPolicy(LoadBalancingPolicy): def make_query_plan(self, working_keyspace=None, query=None): """ Defers to the child policy's - :meth:`.LoadBalancingPolicy.make_query_plan`. Since host changes (up, - down, addition, and removal) have not been propagated to the child - policy, the child policy will only ever return policies for which - :meth:`.predicate(host)` was truthy when that change occurred. + :meth:`.LoadBalancingPolicy.make_query_plan` and filters the results. + + Note that this filtering may break desirable properties of the wrapped + policy in some cases. For instance, imagine if you configure this + policy to filter out ``host2``, and to wrap a round-robin policy that + rotates through three hosts in the order ``host1, host2, host3``, + ``host2, host3, host1``, ``host3, host1, host2``, repeating. This + policy will yield ``host1, host3``, ``host3, host1``, ``host3, host1``, + disproportionately favoring ``host3``. """ child_qp = self._child_policy.make_query_plan( working_keyspace=working_keyspace, query=query diff --git a/docs/api/cassandra/policies.rst b/docs/api/cassandra/policies.rst index 0cb16ed1..b662755c 100644 --- a/docs/api/cassandra/policies.rst +++ b/docs/api/cassandra/policies.rst @@ -26,7 +26,7 @@ Load Balancing .. autoclass:: HostFilterPolicy - # we document these methods manually so we can specify a param to predicate + .. we document these methods manually so we can specify a param to predicate .. automethod:: predicate(host) .. automethod:: distance