Skip to content

Estimation interfaces

bondi.estimation.CardinalityEstimate dataclass

Estimated filter cardinality relative to a recorded population.

Sampling implementations report observed matches and actual sample size. Other implementations may leave these diagnostics absent. A zero sample match count is not proof that the full population has no matches.

Source code in src/bondi/estimation.py 
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
@dataclass(frozen=True)
class CardinalityEstimate:
    """Estimated filter cardinality relative to a recorded population.

    Sampling implementations report observed matches and actual sample size.
    Other implementations may leave these diagnostics absent. A zero sample
    match count is not proof that the full population has no matches.
    """

    cardinality: float
    population_size: int
    sample_matches: int | None = None
    sample_size: int | None = None

    @property
    def selectivity(self) -> float:
        """Estimated matching fraction; zero for an empty population."""
        return self.cardinality / self.population_size if self.population_size else 0.0

selectivity property

Estimated matching fraction; zero for an empty population.

bondi.estimation.CardinalityEstimator

Bases: Protocol[QueryT]

Synchronous estimation; concrete implementations define supported queries.

Source code in src/bondi/estimation.py 
29
30
31
32
33
34
class CardinalityEstimator(Protocol[QueryT]):
    """Synchronous estimation; concrete implementations define supported queries."""

    def estimate(self, query: QueryT) -> CardinalityEstimate:
        """Estimate cardinality in the implementation's configured population."""
        ...

estimate(query)

Estimate cardinality in the implementation's configured population.

Source code in src/bondi/estimation.py 
32
33
34
def estimate(self, query: QueryT) -> CardinalityEstimate:
    """Estimate cardinality in the implementation's configured population."""
    ...

bondi.estimation.AsyncCardinalityEstimator

Bases: Protocol[QueryT]

Async estimation for implementations requiring asynchronous I/O.

Source code in src/bondi/estimation.py 
37
38
39
40
41
42
class AsyncCardinalityEstimator(Protocol[QueryT]):
    """Async estimation for implementations requiring asynchronous I/O."""

    async def estimate(self, query: QueryT) -> CardinalityEstimate:
        """Estimate cardinality in the implementation's configured population."""
        ...

estimate(query) async

Estimate cardinality in the implementation's configured population.

Source code in src/bondi/estimation.py 
40
41
42
async def estimate(self, query: QueryT) -> CardinalityEstimate:
    """Estimate cardinality in the implementation's configured population."""
    ...