CLI pagination

Vault uses pagination to improve performance when retrieving objects

The default page size is specified in the PVAULT_SERVICE_DEFAULT_PAGE_SIZE environment variable. When you request a list of objects, you can use the --page-size flag to set a different page size. However, the page size cannot exceed the value specified in the PVAULT_SERVICE_MAX_PAGE_SIZE environment variable.

The text response provides a standard table containing the object details with additional information depending on whether there are one or more pages of results. When there is one page of results, the response looks like this:

Displaying 2 results.
+-----------------------------+------------+
|            email            |    name    |
+-----------------------------+------------+
| mr.john@somemail.com        | John       |
| john1234@anotheremail.com   | John       |
+-----------------------------+------------+

When there is more than one page of results, the response looks like this:

There are 79 remaining objects.
Use --cursor=AXfKgvXQNTZYiFCtBSTHbjkmYXiaE84oxgGzdeQyKXZbbG0sUX7jAwrUeaBIosUeXqYIKw== to show more.
+-----------------------------+------------+
|            email            |    name    |
+-----------------------------+------------+
| mr.john@somemail.com        | John       |
| john1234@anotheremail.com   | John       |
…
| john9999@anotheremail.com   | John       |
+-----------------------------+------------+

By default, the number of results is limited to 100,000 items even if there are more items that satisfy the query. You can read more about this.

You can then obtain the next page with a command similar to this:

pvault object query \
  query --query-json='{"match": {"name": "John"}}' \
  --props=email \
  --props=name \
  --collection=employees \
  --cursor=AXfKgvXQNTZYiFCtBSTHbjkmYXiaE84oxgGzdeQyKXZbbG0sUX7jAwrUeaBIosUeXqYIKw==

The final page in a sequence of pages returns 0 for remaining_count and no cursor. For example:

There are 0 remaining objects.
+-----------------------------+------------+
|            email            |    name    |
+-----------------------------+------------+
…
| john8745@anotheremail.com   | John       |
+-----------------------------+------------+

If you choose to return JSON, the responses are identical to those provided by the REST API. See REST API pagination for more details.