分页和计数

分页控制为 API 资源响应返回的行数。与计数结合使用，您可以遍历响应的所有行。

限制和分页

PostgREST 使用 HTTP 范围头来描述结果的大小。每个响应都包含当前范围，以及如果请求，则包含结果的总数

HTTP/1.1 200 OK
Range-Unit: items
Content-Range: 0-14/*

这里返回了从零到十四的项目。此信息在每个响应中都可用，可以帮助您在客户端渲染分页控件。这是一个符合 RFC7233 的解决方案，它使响应 JSON 更简洁。

一种请求限制和偏移量的方法是使用查询参数。例如

curl "https://#:3000/people?limit=15&offset=30"

此方法也适用于嵌入式资源，我们将在另一节中介绍。即使您使用查询参数来限制查询，服务器也会始终以范围标头进行响应。

您可以使用标头来指定所需的行的范围。此请求获取前二十个人

curl "https://#:3000/people" -i \
  -H "Range-Unit: items" \
  -H "Range: 0-19"

请注意，如果服务器无法满足您的请求，它可能会返回更少的行。

HTTP/1.1 200 OK
Range-Unit: items
Content-Range: 0-17/*

您也可以请求开放式范围，用于没有限制的偏移量，例如 Range: 10-。

为了获取表的总大小（例如，在渲染分页控件中的最后一页链接时），您可以指定一个 Prefer: count=<value> 标头。值可以是 exact、planned 和 estimated。

这也适用于视图和表值函数.

要获取精确计数，请使用 Prefer: count=exact。

curl "https://#:3000/bigtable" -I \
  -H "Range-Unit: items" \
  -H "Range: 0-24" \
  -H "Prefer: count=exact"

请注意，表越大，此查询在数据库中运行的速度越慢。服务器将以选定的范围和总数进行响应。

HTTP/1.1 206 Partial Content
Range-Unit: items
Content-Range: 0-24/3573458

为了避免精确计数的缺点，PostgREST 可以利用 PostgreSQL 统计信息并获得相当准确且快速的计数。为此，请指定 Prefer: count=planned 标头。

curl "https://#:3000/bigtable?limit=25" -I \
  -H "Prefer: count=planned"

HTTP/1.1 206 Partial Content
Content-Range: 0-24/3572000

请注意，此计数的准确性取决于 PostgreSQL 统计表更新的程度。例如，在这种情况下，要提高计数的准确性，您可以执行 ANALYZE bigtable。有关更多详细信息，请参阅 ANALYZE。

当您对计数感兴趣时，相对误差很重要。如果您有一个计划计数为 1000000，而精确计数为 1001000，则误差小到可以忽略不计。但是，如果计划计数为 7，而精确计数为 28，则会是一个巨大的误判。

一般来说，当行数较少时，估计计数应尽可能接近精确计数。

为了帮助处理这些情况，PostgREST 可以获取到阈值之前的精确计数，并在超过阈值时获取计划计数。要使用此行为，您可以指定 Prefer: count=estimated 头部。**阈值** 由 db-max-rows 定义。

以下是一个示例。假设我们设置 db-max-rows=1000 并且 smalltable 有 321 行，那么我们将获得精确计数。

curl "https://#:3000/smalltable?limit=25" -I \
  -H "Prefer: count=estimated"

HTTP/1.1 206 Partial Content
Content-Range: 0-24/321

如果我们在 bigtable 上进行类似的请求，该表有 3573458 行，我们将获得计划计数。

curl "https://#:3000/bigtable?limit=25" -I \
  -H "Prefer: count=estimated"

HTTP/1.1 206 Partial Content
Content-Range: 0-24/3572000