Simplify Paginate .after/.before Cursors

I am running into a lot of complexity in passing cursors back to fauna for complicated, multi-field indexes.

According to: Paginate :: Fauna Documentation

Cursor
A cursor is an object used as a marker to indicate a position within a set. The cursor has a structure identical to the associated index’s values field; the same fields with the same types, in the same order.

However, the next line:

Cursor matching is prefix-based. That means that if your index contains two or more fields, you only need to specify the first field to achieve a match. You may have to specify additional fields if there are multiple index entries that would match the first field.

I was thrown off because my client was only giving me 2022-06-25T02:34:34.311362Z which I then had to spend quite to a while to realize it needed to be typed correctly with Time("2022-06-25T02:34:34.311362Z")

As I have read and understood the documents, it is not clear there is any good reason to be able to specify individual fields of a cursor in .after and .before and if there is a good reason, then it should be documented. As it is documented now, it is unnecessary complexity.

Whether there is good reason for the above, or not I believe the primary way someone should specify the next page aka .after/.before for a cursor should be with a cursorId so that one string can be sent and the next page of the cursor comes back guaranteed without having to worry about if you included all necessary index fields, or if they are typed correctly.

Thank you

Pagination cursors need all of the relevant information to dead-reckon to the correct position in the Index, or any Set which can involve multiple Indexes. Even if we encode the cursor as a string, all of the information needs to be serialized.

For passing back and forth between your client and server, you can transform the JSON back into FQL using the function parseJSON, which is exported from the javascript driver.

That said, the JSON representation of cursors, particularly if they contain References or other special Fauna types, can be unwieldy. Encoding the cursor as a string is something we did with the GraphQL API.

The pagination cursors are not meant to be treated as transparent structures; that is, if you need to specify a range of values yourself, use the Range function. Don’t manipulate cursors directly. Since cursor items don’t need to be (shouldn’t be) handled directly, encoding a cursor in an easier-to-handle way makes sense.

1 Like