Add estimated count reference

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 <https://www.postgresql.org/docs/11/sql-analyze.html>`_ 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

releases/upcoming.rst

@@ -13,7 +13,7 @@ Added
 * Support for HTTP HEAD requests.
   |br| -- `@steve-chavez <https://github.com/steve-chavez>`_
 
-* Support for :ref:`planned_count`.
+* Support for :ref:`planned_count` and :ref:`estimated_count`.
   |br| -- `@steve-chavez <https://github.com/steve-chavez>`_
 
 Changed