[FEA] Standardize Datasets API for public end-user use
@HowardHuang1 is already working on this.
Since Jan 30, 2026.
- Dominant language
- Cuda
- Stars
- 854
- Forks
- 236
- Avg merge
- 3d 3h
- Merged PRs (30d)
- 62
Description
Currently, the Datasets classes are embedded inside internal implementations and not meant for direct public consumption by users. However, because of this, significant drawbacks have been created to the overall UX and memory management inside some of the indexes. For example, when an mdspan containing CAGRA training vectors has not been previously padded/strided to a proper offset, CAGRA will take it upon itself to copy the vectors into a "padded dataset" instance on behalf of the user. This forfeits user control, makes the UI confusing, creates memory spikes that have proven to be very confusing for the users, and blurs the memory ownership model (now the CAGRA index has become "sometimes owning", which is always very challening maintain and explain to users).
Instead, we've decided we should invest more heavily in the Datasets infrastructure for being able to populate the necessary fields and pre-conditions, thus in the process also self-documenting these pre-conditions for the user. For example, CAGRA should accept a "PaddedDataset" instead of just an mdspan. This additional pre-condition now means that a user will need to construct an instance of "PaddedDataset" and they will be able to better manage an immediately note (as documented in the underlying factory functions) the potential for a copy. But more than anything else, they will now have full ownership and control over the memory that gets passed into the CAGRA index, so it'll always be a view from CAGRA's perspective.
This will help address #1571
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Assessment
This issue has not been assessed yet.