0
# Data Access
1

2
Functions for opening and accessing existing zarr arrays and groups from various storage backends. These functions provide flexible ways to load existing data structures with support for different storage formats and access patterns.
3

4
## Capabilities
5

6
### Generic Opening Functions
7

8
```python { .api }
9
def open(
10
    store: StoreLike,
11
    mode: str = 'r',
12
    cache_attrs: bool = True,
13
    cache_metadata: bool = True,
14
    path: str = None,
15
    **kwargs
16
) -> Union[Array, Group]
17
```
18

19
Open an array or group from storage, automatically detecting the type.
20

21
**Parameters:**
22
- `store`: Storage location (path, store object, or store-like mapping)
23
- `mode`: Access mode ('r' for read-only, 'r+' for read-write, 'w' for write)
24
- `cache_attrs`: Whether to cache attributes in memory
25
- `cache_metadata`: Whether to cache metadata in memory  
26
- `path`: Path within the store to open
27

28
**Returns:** Array or Group depending on what's stored at the location
29

30
### Array-Specific Opening
31

32
```python { .api }
33
def open_array(
34
    store: StoreLike,
35
    mode: str = 'r',
36
    cache_attrs: bool = True,
37
    cache_metadata: bool = True,
38
    path: str = None,
39
    chunk_store: StoreLike = None,
40
    storage_options: dict = None,
41
    zarr_version: int = None,
42
    **kwargs
43
) -> Array
44
```
45

46
Open an existing zarr array from storage.
47

48
**Parameters:**
49
- `store`: Storage location containing the array
50
- `mode`: Access mode
51
- `chunk_store`: Separate storage for chunk data (optional)
52
- `storage_options`: Additional options for storage backend
53
- `zarr_version`: Zarr format version (2 or 3)
54

55
```python { .api }
56
def open_like(
57
    a: ArrayLike,
58
    path: str,
59
    mode: str = 'r',
60
    **kwargs
61
) -> Array
62
```
63

64
Open an array with the same properties as an existing array template.
65

66
**Parameters:**
67
- `a`: Template array to copy properties from
68
- `path`: Path to the array to open
69
- `mode`: Access mode
70

71
### Group-Specific Opening
72

73
```python { .api }
74
def open_group(
75
    store: StoreLike = None,
76
    mode: str = 'r',
77
    cache_attrs: bool = True,
78
    cache_metadata: bool = True,
79
    synchronizer: Any = None,
80
    path: str = None,
81
    chunk_store: StoreLike = None,
82
    storage_options: dict = None,
83
    zarr_version: int = None,
84
    **kwargs
85
) -> Group
86
```
87

88
Open an existing zarr group from storage.
89

90
**Parameters:**
91
- `store`: Storage location containing the group
92
- `mode`: Access mode
93
- `synchronizer`: Synchronization primitive for concurrent access
94
- `zarr_version`: Zarr format version
95

96
### Consolidated Metadata Access
97

98
```python { .api }
99
def open_consolidated(
100
    store: StoreLike,
101
    mode: str = 'r',
102
    cache_attrs: bool = True,
103
    cache_metadata: bool = True,
104
    use_consolidated: bool = True,
105
    **kwargs
106
) -> Group  
107
```
108

109
Open a group that has consolidated metadata for improved performance.
110

111
**Parameters:**
112
- `store`: Storage location with consolidated metadata
113
- `use_consolidated`: Whether to use consolidated metadata (must be True)
114

115
Consolidated metadata stores all child array/group metadata in the parent group's metadata, reducing the number of storage operations needed to access nested structures.
116

117
## Type Definitions
118

119
```python { .api }
120
StoreLike = Union[str, os.PathLike, Store, MutableMapping]
121
ArrayLike = Union[np.ndarray, Array, list, tuple]
122
```
123

124
## Access Modes
125

126
- `'r'`: Read-only access (default)
127
- `'r+'`: Read-write access to existing arrays/groups  
128
- `'w'`: Write mode (overwrites existing data)
129
- `'w-'`: Write mode, fails if array/group exists
130
- `'a'`: Append mode (read-write, creates if doesn't exist)
131

132
## Usage Examples
133

134
### Basic Data Access
135

136
```python
137
import zarr
138

139
# Open array or group (auto-detect type)
140
data = zarr.open('data.zarr')
141

142
# Open specific array
143
arr = zarr.open_array('temperature_data.zarr')
144

145
# Open specific group  
146
grp = zarr.open_group('experiment_results.zarr')
147

148
# Open with write access
149
writable_arr = zarr.open_array('data.zarr', mode='r+')
150
```
151

152
### Working with Different Storage Backends
153

154
```python
155
from zarr.storage import LocalStore, MemoryStore, ZipStore
156

157
# Open from local filesystem
158
arr = zarr.open_array(LocalStore('path/to/data'))
159

160
# Open from ZIP file
161
arr = zarr.open_array(ZipStore('data.zip'))
162

163
# Open from memory store
164
store = MemoryStore()
165
arr = zarr.open_array(store)
166
```
167

168
### Cloud Storage Access
169

170
```python
171
# Open from S3-compatible storage using fsspec
172
import zarr
173
from zarr.storage import FsspecStore
174

175
# Using fsspec for S3
176
store = FsspecStore('s3://bucket/path/to/data.zarr')
177
arr = zarr.open_array(store)
178

179
# Direct path (requires s3fs installed)
180
arr = zarr.open('s3://bucket/path/to/data.zarr')
181
```
182

183
### Performance Optimization
184

185
```python
186
# Open with consolidated metadata for faster access
187
grp = zarr.open_consolidated('large_dataset.zarr')
188

189
# Disable metadata caching for memory-constrained environments
190
arr = zarr.open_array('data.zarr', cache_metadata=False)
191

192
# Use separate chunk store for performance
193
main_store = zarr.storage.LocalStore('metadata/')
194
chunk_store = zarr.storage.LocalStore('chunks/')
195
arr = zarr.open_array(main_store, chunk_store=chunk_store)
196
```
197

198
### Template-Based Opening
199

200
```python
201
# Open array with same properties as template
202
template = zarr.open_array('template.zarr')
203
new_arr = zarr.open_like(template, 'similar_data.zarr')
204

205
# Properties like dtype, chunks, compression are inherited from template
206
```
207

208
### Error Handling
209

210
```python
211
from zarr.errors import ArrayNotFoundError, GroupNotFoundError
212

213
try:
214
    arr = zarr.open_array('nonexistent.zarr')
215
except ArrayNotFoundError:
216
    print("Array not found")
217

218
try:
219
    grp = zarr.open_group('missing_group.zarr') 
220
except GroupNotFoundError:
221
    print("Group not found")
222
```