分页和计数#

分页控制为 API resource 回应。结合计数，您可以遍历响应的所有行。

限制和分页#

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

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

在这里，返回从0到14的项。此信息在每个响应中都可用，并可帮助您在客户端上呈现分页控件。这是一个符合RFC7233的解决方案，可以保持响应JSON的整洁。

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

curl "http://localhost:3000/people?limit=15&offset=30"

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

您可以使用标题来指定所需的行范围。这个请求得到了前20个人：

curl "http://localhost: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 "http://localhost: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

为了避免……的缺点 exact count ，PostgREST可以利用PostgreSQL统计数据，并获得相当准确和快速的计数。为此，请指定 Prefer: count=planned 标题。

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

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

请注意，此计数的准确性取决于PostgreSQL统计表的更新程度。例如，在本例中，为了提高计数的准确性，您可以这样做 ANALYZE bigtable 。看见 ANALYZE 了解更多详细信息。

当你对计数感兴趣时，相对误差是很重要的。如果你有一个 planned count 1000000，精确计数为1001000，误差小到可以忽略不计。但由于计划中的人数为7人，准确地数到28人将是一个巨大的错误预测。

通常，当行计数较小时，估计计数应尽可能接近准确计数。

为了帮助处理这些情况，PostgREST可以获得直到阈值的准确计数，并在超过该阈值时获得计划的计数。若要使用此行为，可以指定 Prefer: count=estimated 标题。这个 threshold 由以下因素定义数据库最大行数。

这里有一个例子。假设我们设置了 db-max-rows=1000 和 smalltable 有321行，那么我们将得到确切的计数：

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

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

如果我们提出类似的要求， bigtable ，它有3573458行，我们将得到计划的计数：

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

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