Skip to content

 zarr.create_hierarchy

zarr.create_hierarchy 

create_hierarchy(
    *,
    store: Store,
    nodes: dict[
        str,
        GroupMetadata | ArrayV2Metadata | ArrayV3Metadata,
    ],
    overwrite: bool = False,
) -> Iterator[tuple[str, Group | AnyArray]]

Create a complete zarr hierarchy from a collection of metadata objects.

This function will parse its input to ensure that the hierarchy is complete. Any implicit groups will be inserted as needed. For example, an input like {'a/b': GroupMetadata} will be parsed to {'': GroupMetadata, 'a': GroupMetadata, 'b': Groupmetadata}

After input parsing, this function then creates all the nodes in the hierarchy concurrently.

Arrays and Groups are yielded in the order they are created. This order is not stable and should not be relied on.

Parameters:

  • store (Store) –

    The storage backend to use.

  • nodes (dict[str, GroupMetadata | ArrayV3Metadata | ArrayV2Metadata]) –

    A dictionary defining the hierarchy. The keys are the paths of the nodes in the hierarchy, relative to the root of the Store. The root of the store can be specified with the empty string ''. The values are instances of GroupMetadata or ArrayMetadata. Note that all values must have the same zarr_format -- it is an error to mix zarr versions in the same hierarchy.

    Leading "/" characters from keys will be removed.

  • overwrite (bool, default: False ) –

    Whether to overwrite existing nodes. Defaults to False, in which case an error is raised instead of overwriting an existing array or group.

    This function will not erase an existing group unless that group is explicitly named in nodes. If nodes defines implicit groups, e.g. {`'a/b/c': GroupMetadata}, and a group already exists at path a, then this function will leave the group at a as-is.

Yields:

  • tuple[str, Group | Array] –

    This function yields (path, node) pairs, in the order the nodes were created.

Examples:

from zarr import create_hierarchy
from zarr.storage import MemoryStore
from zarr.core.group import GroupMetadata

store = MemoryStore()
nodes = {'a': GroupMetadata(attributes={'name': 'leaf'})}
nodes_created = dict(create_hierarchy(store=store, nodes=nodes))
print(nodes)
# {'a': GroupMetadata(attributes={'name': 'leaf'}, zarr_format=3, consolidated_metadata=None, node_type='group')}
Source code in zarr/core/sync_group.py 
 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
def create_hierarchy(
    *,
    store: Store,
    nodes: dict[str, GroupMetadata | ArrayV2Metadata | ArrayV3Metadata],
    overwrite: bool = False,
) -> Iterator[tuple[str, Group | AnyArray]]:
    """
    Create a complete zarr hierarchy from a collection of metadata objects.

    This function will parse its input to ensure that the hierarchy is complete. Any implicit groups
    will be inserted as needed. For example, an input like
    ```{'a/b': GroupMetadata}``` will be parsed to
    ```{'': GroupMetadata, 'a': GroupMetadata, 'b': Groupmetadata}```

    After input parsing, this function then creates all the nodes in the hierarchy concurrently.

    Arrays and Groups are yielded in the order they are created. This order is not stable and
    should not be relied on.

    Parameters
    ----------
    store : Store
        The storage backend to use.
    nodes : dict[str, GroupMetadata | ArrayV3Metadata | ArrayV2Metadata]
        A dictionary defining the hierarchy. The keys are the paths of the nodes in the hierarchy,
        relative to the root of the ``Store``. The root of the store can be specified with the empty
        string ``''``. The values are instances of ``GroupMetadata`` or ``ArrayMetadata``. Note that
        all values must have the same ``zarr_format`` -- it is an error to mix zarr versions in the
        same hierarchy.

        Leading "/" characters from keys will be removed.
    overwrite : bool
        Whether to overwrite existing nodes. Defaults to ``False``, in which case an error is
        raised instead of overwriting an existing array or group.

        This function will not erase an existing group unless that group is explicitly named in
        ``nodes``. If ``nodes`` defines implicit groups, e.g. ``{`'a/b/c': GroupMetadata}``, and a
        group already exists at path ``a``, then this function will leave the group at ``a`` as-is.

    Yields
    ------
    tuple[str, Group | Array]
        This function yields (path, node) pairs, in the order the nodes were created.

    Examples
    --------
    ```python
    from zarr import create_hierarchy
    from zarr.storage import MemoryStore
    from zarr.core.group import GroupMetadata

    store = MemoryStore()
    nodes = {'a': GroupMetadata(attributes={'name': 'leaf'})}
    nodes_created = dict(create_hierarchy(store=store, nodes=nodes))
    print(nodes)
    # {'a': GroupMetadata(attributes={'name': 'leaf'}, zarr_format=3, consolidated_metadata=None, node_type='group')}
    ```
    """
    coro = create_hierarchy_async(store=store, nodes=nodes, overwrite=overwrite)

    for key, value in sync(_collect_aiterator(coro)):
        yield key, _parse_async_node(value)