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.
Super class
zarr::zarr_store -> zarr_localstore
Active bindings
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 '.'.
Methods
Method 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.
Usage
zarr_localstore$new(root, read_only = FALSE)Arguments
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.
Method exists()
Check if a key exists in the store. The key can point to a group, an array, or a chunk.
Method 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" or ".zgroup" (version 2) in the root of this store.
Method 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.
Method 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.
Method 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.
Method 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.
Method 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.
Method get()
Retrieve the value associated with a given key.
Arguments
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.
Method get_metadata()
Retrieve the metadata document of the node at the location
indicated by the prefix argument. The metadata will always be
presented to the caller in the Zarr v.3 format.
Method set_metadata()
Set the metadata document of the node at the location
indicated by the prefix argument. The formatting of the metadata
should always use the Zarr v.3 format, it will be converted internally
if the store is Zarr v.2.
Arguments
prefixThe prefix of the node whose metadata document to set.
metadataThe metadata to persist, either a
listor an instance of array_builder.
Method create_group()
Create a new group in the store under the specified path.
Method create_array()
Create a new array in the store under the specified path to
the parent argument.
Arguments
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
listwith 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 "/".