Converting Zarr V2 to V3

Changing the Internal Representation

When an array or group is initialised, it internally holds metadata in the Zarr version it was created with.

To change the internal representation to Zarr V3, call to_v3() on an Array or Group, then call store_metadata() to update the stored metadata. V2 metadata must be explicitly erased if needed (see below).

Convert a Group to V3

let group: Group = group.to_v3();
group.store_metadata()?;
// group.async_store_metadata().await?;
group.erase_metadata_opt(MetadataEraseVersion::V2)?;
// group.async_erase_metadata_opt(MetadataEraseVersion::V2).await?;

Convert an Array to V3

let array: Array = array.to_v3()?;
array.store_metadata()?;
// array.async_store_metadata().await?;
array.erase_metadata_opt(MetadataEraseVersion::V2)?;
// array.async_erase_metadata_opt(MetadataEraseVersion::V2).await?;

Note that Array::to_v3() is fallible because some V2 metadata is not V3 compatible.

Writing Versioned Metadata Explicitly

Rather than changing the internal representation, an alternative is to just write metadata with a specified version.

For groups, the store_metadata_opt accepts a GroupMetadataOptions argument. GroupMetadataOptions currently has only one option that impacts the Zarr version of the metadata. By default, GroupMetadataOptions keeps the current Zarr version.

To write Zarr V3 metadata:

group.store_metadata_opt(&
    GroupMetadataOptions::default()
    .with_metadata_convert_version(MetadataConvertVersion::V3)
)?;
// group.async_store_metadata_opt(...).await?;

Note that the original metadata is not automatically deleted. If you want to delete it:

group.erase_metadata()?;
// group.async_erase_metadata().await?;

ArrayMetadataOptions has similar options for changing the Zarr version of the metadata. It also has various other configuration options, see its documentation.