diff --git a/admin.rst b/admin.rst index 363851656..9d4841c8d 100644 --- a/admin.rst +++ b/admin.rst @@ -32,7 +32,7 @@ The first step is to create an Nginx configuration file that proxies requests to .. note:: - For ubuntu, if you already installed nginx through :code:`apt` you can add this to the config file in + For ubuntu, if you already installed nginx through :code:`apt` you can add this to the config file in :code:`/etc/nginx/sites-enabled/default`. .. _block_fulltable: @@ -88,10 +88,6 @@ This is fine in small tables, but count performance degrades in big tables due t -- Pending nginx config: Remove any prefer header which contains the word count -.. note:: - - In future versions we will support :code:`Prefer: count=estimated` to leverage the PostgreSQL statistics tables for a fast (and fairly accurate) result. - .. _hardening_https: HTTPS diff --git a/api.rst b/api.rst index 1880dc9fc..9284d3eed 100644 --- a/api.rst +++ b/api.rst @@ -371,12 +371,16 @@ The other way to request a limit or offset is with query parameters. For example This method is also useful for embedded resources, which we will cover in another section. The server always responds with range headers even if you use query parameters to limit the query. -In order to obtain the total size of the table or view (such as when rendering the last page link in a pagination control), specify your preference in a request header: +.. _exact_count: +Exact Count +~~~~~~~~~~~ + +In order to obtain the total size of the table or view (such as when rendering the last page link in a pagination control), specify ``Prefer: count=exact`` as a request header: .. code-block:: http - GET /bigtable HTTP/1.1 + HEAD /bigtable HTTP/1.1 Range-Unit: items Range: 0-24 Prefer: count=exact @@ -389,6 +393,28 @@ Note that the larger the table the slower this query runs in the database. The s Range-Unit: items Content-Range: 0-24/3573458 +.. _planned_count: + +Planned Count +~~~~~~~~~~~~~ + +To avoid the shortcomings of :ref:`exact count `, PostgREST can leverage PostgreSQL statistics and get a fairly accurate and fast count. +To do this, specify the ``Prefer: count=planned`` header. + +.. code-block:: http + + HEAD /bigtable?limit=25 HTTP/1.1 + Prefer: count=planned + +.. code-block:: http + + 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. +For example in this case, to increase the accuracy of the count you can do ``ANALYZE bigtable``. +See `ANALYZE `_ for more details. + .. _res_format: Response Format diff --git a/releases/upcoming.rst b/releases/upcoming.rst index 836a2c78c..8096b97ea 100644 --- a/releases/upcoming.rst +++ b/releases/upcoming.rst @@ -13,6 +13,9 @@ Added * Support for HTTP HEAD requests. |br| -- `@steve-chavez `_ +* Support for :ref:`planned_count`. + |br| -- `@steve-chavez `_ + Changed -------