1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
|
# Command-line interface
Zarr-Python provides a command-line interface that enables:
- migration of Zarr v2 metadata to v3
- removal of v2 or v3 metadata
To see available commands run the following in a terminal:
```bash
zarr --help
```
or to get help on individual commands:
```bash
zarr migrate --help
zarr remove-metadata --help
```
## Migrate metadata from v2 to v3
### Migrate to a separate location
To migrate a Zarr array/group's metadata from v2 to v3 run:
```bash
zarr migrate v3 path/to/input.zarr path/to/output.zarr
```
This will write new `zarr.json` files to `output.zarr`, leaving `input.zarr` un-touched.
Note - this will migrate the entire Zarr hierarchy, so if `input.zarr` contains multiple groups/arrays,
new `zarr.json` will be made for all of them.
### Migrate in-place
If you'd prefer to migrate the metadata in-place run:
```bash
zarr migrate v3 path/to/input.zarr
```
This will write new `zarr.json` files to `input.zarr`, leaving the existing v2 metadata un-touched.
To open the array/group using the new metadata use:
```python
import zarr
zarr_with_v3_metadata = zarr.open('path/to/input.zarr', zarr_format=3)
```
Once you are happy with the conversion, you can run the following to remove the old v2 metadata:
```bash
zarr remove-metadata v2 path/to/input.zarr
```
Note there is also a shortcut to migrate and remove v2 metadata in one step:
```bash
zarr migrate v3 path/to/input.zarr --remove-v2-metadata
```
## Remove metadata
Remove v2 metadata using:
```bash
zarr remove-metadata v2 path/to/input.zarr
```
or v3 with:
```bash
zarr remove-metadata v3 path/to/input.zarr
```
By default, this will only allow removal of metadata if a valid alternative exists. For example, you can't
remove v2 metadata unless v3 metadata exists at that location.
To override this behaviour use `--force`:
```bash
zarr remove-metadata v3 path/to/input.zarr --force
```
## Dry run
All commands provide a `--dry-run` option that will log changes that would be made on a real run, without creating
or modifying any files.
```bash
zarr migrate v3 path/to/input.zarr --dry-run
Dry run enabled - no new files will be created or changed. Log of files that would be created on a real run:
Saving metadata to path/to/input.zarr/zarr.json
```
## Verbose
You can also add `--verbose` **before** any command, to see a full log of its actions:
```bash
zarr --verbose migrate v3 path/to/input.zarr
zarr --verbose remove-metadata v2 path/to/input.zarr
```
## Equivalent functions
All features of the command-line interface are also available via functions under
`zarr.metadata`.
|
