This class implements a Zarr store for the local file system. With this class Zarr stores on devices accessible through the local file system can be read and written to. This includes locally attached drives, removable media, NFS mounts, etc.
The chunking pattern is to locate all the chunks of an array in a single directory. That means that chunks have names like "c0.0.0" in the array directory.
This class performs no sanity checks on any of the arguments passed to the methods, for performance reasons. Since this class should be accessed through group and array objects, it is up to that code to ensure that arguments are valid, in particular keys and prefixes.
zarr::zarr_store -> zarr_localstore
friendlyClassName(read-only) Name of the class for printing.
root(read-only) The root directory of the file system store.
uri(read-only) The URI of the store location.
separator(read-only) The default chunk separator of the local file store, usually a dot '.'.
new()Create an instance of this class.
If the root location does not exist, it will be created. The location
on the file system must be writable by the process creating the store.
The store is not yet functional in the sense that it is just an empty
directory. Write a root group with .$create_group('/', '') or an
array with .$create_array('/', '', metadata) for a single-array store
before any other operations on the store.
If the root location does exist on the file system it must be a valid Zarr store, as determined by the presence of a "zarr.json" file. It is an error to try to open a Zarr store on an existing location where this metadata file is not present.
zarr_localstore$new(root, read_only = FALSE)rootThe path to the local store to be created or opened. The path may use UTF-8 code points. Following the Zarr specification, it is recommended that the root path has an extension of ".zarr" to easily identify the location as a Zarr store. When creating a file store, the root directory cannot already exist.
read_onlyFlag to indicate if the store is opened read-only.
Default FALSE.
An instance of this class.
exists()Check if a key exists in the store. The key can point to a group, an array, or a chunk.
zarr_localstore$exists(key)keyCharacter string. The key that the store will be searched for.
TRUE if argument key is found, FALSE otherwise.
clear()Clear the store. Remove all keys and values from the store. Invoking this method deletes affected files on the file system and this action can not be undone. The only file that will remain is "zarr.json" in the root of this store.
zarr_localstore$clear()TRUE if the operation proceeded, FALSE otherwise.
erase()Remove a key from the store. The key must point to an array chunk or an empty group. The location of the key and all of its values are removed.
zarr_localstore$erase(key)keyCharacter string. The key to remove from the store.
TRUE if the operation proceeded, FALSE otherwise.
erase_prefix()Remove all keys in the store that begin with a given prefix. The last location in the prefix is preserved while all keys below are removed from the store. Any metadata extensions added to the group pointed to by the prefix will be deleted as well - only a basic group-identifying metadata file will remain.
zarr_localstore$erase_prefix(prefix)prefixCharacter string. The prefix to groups or arrays to remove from the store, including in child groups.
TRUE if the operation proceeded, FALSE otherwise.
list_dir()Retrieve all keys and prefixes with a given prefix and which do not contain the character "/" after the given prefix. In other words, this retrieves all the nodes in the store below the node indicated by the prefix.
zarr_localstore$list_dir(prefix)prefixCharacter string. The prefix whose nodes to list.
A character array with all keys found in the store immediately
below the prefix, both for groups and arrays.
list_prefix()Retrieve all keys and prefixes with a given prefix.
zarr_localstore$list_prefix(prefix)prefixCharacter string. The prefix whose nodes to list.
A character vector with all paths found in the store below the
prefix location, both for groups and arrays.
set()Store a (key, value) pair. The key points to a specific
file (shard or chunk of an array) in a store, rather than a group or an
array. The key must be relative to the root of the store (so not start
with a "/") and may be composite. It must include the name of the file.
An example would be "group/subgroup/array/c0.0.0". The group hierarchy
and the array must have been created before. If the value exists, it
will be overwritten.
zarr_localstore$set(key, value)keyThe key whose value to set.
valueThe value to set, a complete chunk of data, a raw vector.
Self, invisibly, or an error.
set_if_not_exists()Store a (key, value) pair. The key points to a specific
file (shard or chunk of an array) in a store, rather than a group or an
array. The key must be relative to the root of the store (so not start
with a "/") and may be composite. It must include the name of the file.
An example would be "group/subgroup/array/c0.0.0". The group hierarchy
and the array must have been created before. If the key exists,
nothing will be written.
zarr_localstore$set_if_not_exists(key, value)keyThe key whose value to set.
valueThe value to set, a complete chunk of data.
Self, invisibly, or an error.
get()Retrieve the value associated with a given key.
zarr_localstore$get(key, prototype = NULL, byte_range = NULL)keyCharacter string. The key for which to get data.
prototypeIgnored. The only buffer type that is supported maps directly to an R raw vector.
byte_rangeIf NULL, all data associated with the key is
retrieved. If a single positive integer, all bytes starting from a
given byte offset to the end of the object are returned. If a single
negative integer, the final bytes are returned. If an integer vector of
length 2, request a specific range of bytes where the end is exclusive.
If the range ends after the end of the object, the entire remainder of
the object will be returned. If the given range is zero-length or
starts after the end of the object, an error will be returned.
An raw vector of data, or NULL if no data was found.
get_metadata()Retrieve the metadata document of the node at the location
indicated by the prefix argument.
zarr_localstore$get_metadata(prefix)prefixThe prefix of the node whose metadata document to retrieve.
A list with the metadata, or NULL if the prefix is not pointing
to a Zarr group or array.
set_metadata()Set the metadata document of the node at the location
indicated by the prefix argument.
zarr_localstore$set_metadata(prefix, metadata)prefixThe prefix of the node whose metadata document to set.
metadataThe metadata to persist, either a list or an instance
of array_builder.
Self, invisible
is_group()Test if path is pointing to a Zarr group.
zarr_localstore$is_group(path)pathThe path to test.
TRUE if the path points to a Zarr group, FALSE otherwise.
create_group()Create a new group in the store under the specified path.
zarr_localstore$create_group(path, name)pathThe path to the parent group of the new group. Ignored when creating a root group.
nameThe name of the new group. This may be an empty string ""
to create a root group. It is an error to supply an empty string if a
root group or array already exists.
A list with the metadata of the group, or an error if the group could not be created.
create_array()Create a new array in the store under the specified path to
the parent argument.
zarr_localstore$create_array(parent, name, metadata)parentThe path to the parent group of the new array. Ignored when creating a root array.
nameThe name of the new array. This may be an empty string ""
to create a root array. It is an error to supply an empty string if a
root group or array already exists.
metadataA list with the metadata for the array. The list has to
be valid for array construction. Use the array_builder class to
create and or test for validity. An element "chunk_key_encoding" will
be added to the metadata if not already present or with a value other
than a dot "." or a slash "/".
A list with the metadata of the array, or an error if the array could not be created.
https://zarr-specs.readthedocs.io/en/latest/v3/stores/filesystem/index.html