diff --git a/api.rst b/api.rst index 9284d3eed..7dba6729e 100644 --- a/api.rst +++ b/api.rst @@ -411,10 +411,48 @@ To do this, specify the ``Prefer: count=planned`` header. HTTP/1.1 206 Partial Content Content-Range: 0-24/3572000 -Note that the accuracy of this count depends how up-to-date are the PostgreSQL statistics tables. +Note that the accuracy of this count depends on how up-to-date are the PostgreSQL statistics tables. For example in this case, to increase the accuracy of the count you can do ``ANALYZE bigtable``. See `ANALYZE `_ for more details. +.. _estimated_count: + +Estimated Count +~~~~~~~~~~~~~~~ + +When you are interested in the count, the relative error is important. If you have an estimated count of 1000000 and the exact count is +1001000, the error is small enough to be ignored. But with an estimated count of 7, an exact count of 28 would be a huge misprediction. + +In general, when having smaller row-counts, the estimated count should be as close to the exact count as possible. + +To help with these cases, PostgREST can get the exact count up until a threshold and get the estimated count when +that threshold is surpassed. To use this behavior, you can specify the ``Prefer: count=estimated`` header. The **threshold** is +defined by :ref:`max-rows`. + +Here's an example. Suppose we set ``max-rows=1000`` and *smalltable* has 321 rows, then we'll get the exact count: + +.. code-block:: http + + HEAD /smalltable?limit=25 HTTP/1.1 + Prefer: count=estimated + +.. code-block:: http + + HTTP/1.1 206 Partial Content + Content-Range: 0-24/321 + +If we make a similar request on *bigtable*, which has 3573458 rows, we would get the estimated count: + +.. code-block:: http + + HEAD /bigtable?limit=25 HTTP/1.1 + Prefer: count=estimated + +.. code-block:: http + + HTTP/1.1 206 Partial Content + Content-Range: 0-24/3572000 + .. _res_format: Response Format diff --git a/releases/upcoming.rst b/releases/upcoming.rst index 8096b97ea..886c4449b 100644 --- a/releases/upcoming.rst +++ b/releases/upcoming.rst @@ -13,7 +13,7 @@ Added * Support for HTTP HEAD requests. |br| -- `@steve-chavez `_ -* Support for :ref:`planned_count`. +* Support for :ref:`planned_count` and :ref:`estimated_count`. |br| -- `@steve-chavez `_ Changed