@spec batch_create(t(), [{:group | :array, String.t(), keyword()}]) ::
  {:ok, map()} | {:error, term()}

Creates multiple groups and/or arrays in parallel.

Reduces latency for cloud storage by writing metadata concurrently. Returns a map of created items keyed by their names.

Examples

items = [
  {:group, "exp1"},
  {:group, "exp2"},
  {:array, "exp1/results", shape: {100, 100}, chunks: {10, 10}, dtype: :float32}
]

{:ok, created} = Group.batch_create(root, items)
# created = %{
#   "exp1" => %Group{...},
#   "exp2" => %Group{...},
#   "exp1/results" => %Array{...}
# }

@spec create(
  String.t(),
  keyword()
) :: {:ok, t()} | {:error, term()}

Creates a new group.

Options

• :storage - Storage backend (default: :memory)
• :path - Path for filesystem storage

Examples

{:ok, group} = ExZarr.Group.create("/data", storage: :filesystem, path: "/tmp/zarr")

@spec create_array(t(), String.t(), keyword()) ::
  {:ok, ExZarr.Array.t()} | {:error, term()}

Creates a new array within this group.

Examples

{:ok, array} = ExZarr.Group.create_array(group, "measurements",
  shape: {1000},
  chunks: {100},
  dtype: :float64
)

@spec create_group(t(), String.t(), keyword()) :: {:ok, t()} | {:error, term()}

Creates a subgroup within this group.

Examples

{:ok, subgroup} = ExZarr.Group.create_group(group, "experiments")

Access nested groups/arrays using path notation. Creates intermediate groups on write operations.

Examples

# Read access
array = group["temperature"]
nested = group["experiments/exp1/results"]

# Write access (auto-creates intermediate groups)
group = put_in(group["new/path"], array)

# Update access
group = update_in(group["data"], fn arr -> modify(arr) end)

@spec get_array(t(), String.t()) :: {:ok, ExZarr.Array.t()} | {:error, :not_found}

Gets an array from the group by name.

@spec get_attr(t(), String.t()) :: {:ok, term()} | {:error, :not_found}

Gets an attribute from the group.

@spec get_group(t(), String.t()) :: {:ok, t()} | {:error, :not_found}

Gets a subgroup by name.

@spec get_item(t(), String.t()) ::
  {:ok, ExZarr.Array.t() | t()} | {:error, :not_found}

Gets an item (array or group) at the specified path with lazy loading.

Paths can be nested using forward slashes: "exp1/run2/data". Items are loaded from storage on first access and cached.

Examples

{:ok, array} = Group.get_item(root, "temperature")
{:ok, nested} = Group.get_item(root, "experiments/exp1/results")
{:error, :not_found} = Group.get_item(root, "nonexistent")

@spec list_arrays(t()) :: [String.t()]

Lists all arrays in the group.

@spec list_groups(t()) :: [String.t()]

Lists all subgroups.

@spec open(
  String.t(),
  keyword()
) :: {:ok, t()} | {:error, term()}

Opens an existing group from storage.

@spec put_item(t(), String.t(), ExZarr.Array.t() | t()) :: t()

Puts an item (array or group) at the specified path.

Creates intermediate groups as needed. Returns the updated root group.

Examples

group = Group.put_item(root, "new/path/array", array)
group = Group.put_item(root, "experiments/exp1", subgroup)

@spec remove_item(t(), String.t()) :: t()

Removes an item from the group.

Does not delete from storage, only removes from the in-memory structure. The path remains in _loaded to indicate it was checked.

Examples

group = Group.remove_item(root, "temperature")
group = Group.remove_item(root, "experiments/exp1")

@spec require_group(t(), String.t()) :: {:ok, t()} | {:error, term()}

Ensures a group exists at the specified path, creating it if necessary.

Similar to mkdir -p, this creates all intermediate groups along the path. If the path exists and is a group, returns it. If it's an array, returns an error.

Examples

{:ok, group} = Group.require_group(root, "exp1/run2/results")
{:ok, existing} = Group.require_group(root, "experiments")
{:error, :path_is_array} = Group.require_group(root, "temperature")

@spec set_attr(t(), String.t(), term()) :: t()

Sets an attribute on the group.

@spec tree(
  t(),
  keyword()
) :: String.t()

Generates an ASCII tree visualization of the group hierarchy.

Uses box-drawing characters to show the structure. Arrays are marked with [A] and groups with [G]. Optionally shows array shapes.

Options

• :depth - Maximum depth to display (default: unlimited)
• :show_shapes - Include array shapes in output (default: true)

Examples

IO.puts(Group.tree(root))
# Output:
# /
# ├── [A] temperature (1000, 1000)
# ├── [A] pressure (1000, 1000)
# └── [G] experiments
#     └── [G] exp1
#         └── [A] results (500, 500)

IO.puts(Group.tree(root, depth: 2, show_shapes: false))