Programmatically set custom order (reorder) in orderable collection via Local/REST API

[thisanimus]

In Payload, I see that custom ordering within a collection is accomplished via fractional indexing. This order is typically changed via drag and drop, but I find I need to set the initial custom order programmatically once.

Questions:

1. Is there a way to set the fractional index based on a legacy field (number) I previously used to manage ordering?
2. On collection item creation or update via REST or Local API, is there a way to define the order?
3. Once the custom order is set, is there a way to get the position of an item within the array?

[zubricks]

Hey @thisanimus

Here are some answers to your questions:

1. You could fetch your docs sorted by your legacy field, then call the /api/reorder endpoint sequentially to place each one after the previous
2. Not directly. New documents are automatically appended to the end on create. To place a document at a specific position, you'd have to create it first, then immediately call /api/reorder to move it.
3. Since _order is a fractional index string, you'd need to fetch all documents sorted by _order and find the index client-side

[andershermansen]

Follow up to answer 2. You can!

You can set _order or _order (for joins) directly when you insert or update a document. You just have to calculate the fractional index yourself. So on your client side you can do this and create/update by rest api or Local API. I have not done it for _order fields, but done it for join fields with _order field and that works great!

It's also documented here https://payloadcms.com/docs/configuration/collections#fractional-indexing how to use the helpers to generate the value to use.

For item 1, as an alternative you could also look into an migration which will fetch the data in the order you have now and update the _order accordingly by using the same fractional-indexing helpers to generate new keys and update the document.