Datastore¶
- class lsst.daf.butler.Datastore(config: DatastoreConfig, bridgeManager: DatastoreRegistryBridgeManager)¶
Bases:
object
Datastore interface.
- Parameters:
Attributes Summary
Name of the key containing a list of subconfigurations that also need to be merged with defaults and will likely use different Python datastore classes (but all using DatastoreConfig).
Path to configuration defaults.
Indicate whether this Datastore is ephemeral or not.
Names associated with this datastore returned as a list.
Return the root URIs for each named datastore.
Methods Summary
clone
(bridgeManager)Make an independent copy of this Datastore with a different
DatastoreRegistryBridgeManager
instance.emptyTrash
([ignore_errors])Remove all datasets from the trash.
exists
(datasetRef)Check if the dataset exists in the datastore.
export
(refs, *[, directory, transfer])Export datasets for transfer to another data repository.
export_records
(refs)Export datastore records and locations to an in-memory data structure.
forget
(refs)Indicate to the Datastore that it should remove all records of the given datasets, without actually deleting them.
fromConfig
(config, bridgeManager[, butlerRoot])Create datastore from type specified in config file.
get
(datasetRef[, parameters, storageClass])Load an
InMemoryDataset
from the store.Return all the lookup keys relevant to this datastore.
getManyURIs
(refs[, predict, allow_missing])Return URIs associated with many datasets.
getURI
(datasetRef[, predict])URI to the Dataset.
getURIs
(datasetRef[, predict])Return URIs associated with dataset.
Make definitions of the opaque tables used by this Datastore.
import_records
(data)Import datastore location and record data from an in-memory data structure.
ingest
(*datasets[, transfer, ...])Ingest one or more files into the datastore.
knows
(ref)Check if the dataset is known to the datastore.
knows_these
(refs)Check which of the given datasets are known to this datastore.
mexists
(refs[, artifact_existence])Check the existence of multiple datasets at once.
needs_expanded_data_ids
(transfer[, entity])Test whether this datastore needs expanded data IDs to ingest.
Retrieve serializable data that can be used to execute a
get()
.put
(inMemoryDataset, datasetRef)Write a
InMemoryDataset
with a givenDatasetRef
to the store.put_new
(in_memory_dataset, ref)Write a
InMemoryDataset
with a givenDatasetRef
to the store.remove
(datasetRef)Indicate to the Datastore that a Dataset can be removed.
retrieveArtifacts
(refs, destination[, ...])Retrieve the artifacts associated with the supplied refs.
setConfigRoot
(root, config, full[, overwrite])Set filesystem-dependent config options for this datastore.
set_retrieve_dataset_type_method
(method)Specify a method that can be used by datastore to retrieve registry-defined dataset type.
Context manager supporting
Datastore
transactions.transfer
(inputDatastore, datasetRef)Transfer a dataset from another datastore to this datastore.
transfer_from
(source_datastore, refs[, ...])Transfer dataset artifacts from another datastore to this one.
trash
(ref[, ignore_errors])Indicate to the Datastore that a Dataset can be moved to the trash.
validateConfiguration
(entities[, logFailures])Validate some of the configuration for this datastore.
validateKey
(lookupKey, entity)Validate a specific look up key with supplied entity.
Attributes Documentation
- containerKey: ClassVar[str | None] = None¶
Name of the key containing a list of subconfigurations that also need to be merged with defaults and will likely use different Python datastore classes (but all using DatastoreConfig). Assumed to be a list of configurations that can be represented in a DatastoreConfig and containing a “cls” definition. None indicates that no containers are expected in this Datastore.
- defaultConfigFile: ClassVar[str | None] = None¶
Path to configuration defaults. Accessed within the
config
resource or relative to a search path. Can be None if no defaults specified.
- isEphemeral: bool = False¶
Indicate whether this Datastore is ephemeral or not. An ephemeral datastore is one where the contents of the datastore will not exist across process restarts. This value can change per-instance.
- names¶
Names associated with this datastore returned as a list.
Can be different to
name
for a chaining datastore.
- roots¶
Return the root URIs for each named datastore.
Mapping from datastore name to root URI. The URI can be
None
if a datastore has no concept of a root URI. (dict
[str
,ResourcePath
|None
])
Methods Documentation
- abstract clone(bridgeManager: DatastoreRegistryBridgeManager) Datastore ¶
Make an independent copy of this Datastore with a different
DatastoreRegistryBridgeManager
instance.
- abstract emptyTrash(ignore_errors: bool = True) None ¶
Remove all datasets from the trash.
- Parameters:
- ignore_errors
bool
, optional Determine whether errors should be ignored.
- ignore_errors
Notes
Some Datastores may implement this method as a silent no-op to disable Dataset deletion through standard interfaces.
- abstract exists(datasetRef: DatasetRef) bool ¶
Check if the dataset exists in the datastore.
- Parameters:
- datasetRef
DatasetRef
Reference to the required dataset.
- datasetRef
- Returns:
- export(refs: Iterable[DatasetRef], *, directory: ResourcePathExpression | None = None, transfer: str | None = 'auto') Iterable[FileDataset] ¶
Export datasets for transfer to another data repository.
- Parameters:
- refsiterable of
DatasetRef
Dataset references to be exported.
- directory
str
, optional Path to a directory that should contain files corresponding to output datasets. Ignored if
transfer
is explicitlyNone
.- transfer
str
, optional Mode that should be used to move datasets out of the repository. Valid options are the same as those of the
transfer
argument toingest
, and datastores may similarly signal that a transfer mode is not supported by raisingNotImplementedError
. If “auto” is given and nodirectory
is specified,None
will be implied.
- refsiterable of
- Returns:
- datasetiterable of
DatasetTransfer
Structs containing information about the exported datasets, in the same order as
refs
.
- datasetiterable of
- Raises:
- NotImplementedError
Raised if the given transfer mode is not supported.
- abstract export_records(refs: Iterable[DatasetIdRef]) Mapping[str, DatastoreRecordData] ¶
Export datastore records and locations to an in-memory data structure.
- abstract forget(refs: Iterable[DatasetRef]) None ¶
Indicate to the Datastore that it should remove all records of the given datasets, without actually deleting them.
- Parameters:
- refs
Iterable
[DatasetRef
] References to the datasets being forgotten.
- refs
Notes
Asking a datastore to forget a
DatasetRef
it does not hold should be a silent no-op, not an error.
- static fromConfig(config: Config, bridgeManager: DatastoreRegistryBridgeManager, butlerRoot: ResourcePathExpression | None = None) Datastore ¶
Create datastore from type specified in config file.
- abstract get(datasetRef: DatasetRef, parameters: Mapping[str, Any] | None = None, storageClass: StorageClass | str | None = None) Any ¶
Load an
InMemoryDataset
from the store.- Parameters:
- datasetRef
DatasetRef
Reference to the required Dataset.
- parameters
dict
StorageClass
-specific parameters that specify a slice of the Dataset to be loaded.- storageClass
StorageClass
orstr
, optional The storage class to be used to override the Python type returned by this method. By default the returned type matches the dataset type definition for this dataset. Specifying a read
StorageClass
can force a different type to be returned. This type must be compatible with the original type.
- datasetRef
- Returns:
- inMemoryDataset
object
Requested Dataset or slice thereof as an InMemoryDataset.
- inMemoryDataset
- abstract getLookupKeys() set[LookupKey] ¶
Return all the lookup keys relevant to this datastore.
- Returns:
- keys
set
ofLookupKey
The keys stored internally for looking up information based on
DatasetType
name orStorageClass
.
- keys
- getManyURIs(refs: Iterable[DatasetRef], predict: bool = False, allow_missing: bool = False) dict[DatasetRef, DatasetRefURIs] ¶
Return URIs associated with many datasets.
- Parameters:
- Returns:
- URIs
dict
of [DatasetRef
,DatasetRefUris
] A dict of primary and component URIs, indexed by the passed-in refs.
- URIs
- Raises:
- FileNotFoundError
A URI has been requested for a dataset that does not exist and guessing is not allowed.
Notes
In file-based datastores, getManyURIs does not check that the file is really there, it’s assuming it is if datastore is aware of the file then it actually exists.
- abstract getURI(datasetRef: DatasetRef, predict: bool = False) ResourcePath ¶
URI to the Dataset.
- Parameters:
- datasetRef
DatasetRef
Reference to the required Dataset.
- predict
bool
If
True
attempt to predict the URI for a dataset if it does not exist in datastore.
- datasetRef
- Returns:
- uri
str
URI string pointing to the Dataset within the datastore. If the Dataset does not exist in the datastore, the URI may be a guess. If the datastore does not have entities that relate well to the concept of a URI the returned URI string will be descriptive. The returned URI is not guaranteed to be obtainable.
- uri
- Raises:
- FileNotFoundError
A URI has been requested for a dataset that does not exist and guessing is not allowed.
- abstract getURIs(datasetRef: DatasetRef, predict: bool = False) DatasetRefURIs ¶
Return URIs associated with dataset.
- Parameters:
- datasetRef
DatasetRef
Reference to the required dataset.
- predict
bool
, optional If the datastore does not know about the dataset, controls whether it should return a predicted URI or not.
- datasetRef
- Returns:
- uris
DatasetRefURIs
The URI to the primary artifact associated with this dataset (if the dataset was disassembled within the datastore this may be
None
), and the URIs to any components associated with the dataset artifact. (can be empty if there are no components).
- uris
- abstract get_opaque_table_definitions() Mapping[str, DatastoreOpaqueTable] ¶
Make definitions of the opaque tables used by this Datastore.
- Returns:
- tables
Mapping
[str
,ddl.TableSpec
] Mapping of opaque table names to their definitions. This can be an empty mapping if Datastore does not use opaque tables to keep datastore records.
- tables
- abstract import_records(data: Mapping[str, DatastoreRecordData]) None ¶
Import datastore location and record data from an in-memory data structure.
- Parameters:
Notes
Implementations should generally not check that any external resources (e.g. files) referred to by these records actually exist, for performance reasons; we expect higher-level code to guarantee that they do.
Implementations are responsible for calling
DatastoreRegistryBridge.insert
on all datasets indata.locations
where the key is innames
, as well as loading any opaque table data.Implementations may assume that datasets are either fully present or not at all (single-component exports are not permitted).
- ingest(*datasets: FileDataset, transfer: str | None = None, record_validation_info: bool = True) None ¶
Ingest one or more files into the datastore.
- Parameters:
- *datasets
FileDataset
Each positional argument is a struct containing information about a file to be ingested, including its path (either absolute or relative to the datastore root, if applicable), a complete
DatasetRef
(withdataset_id not None
), and optionally a formatter class or its fully-qualified string name. If a formatter is not provided, the one the datastore would use forput
on that dataset is assumed.- transfer
str
, optional How (and whether) the dataset should be added to the datastore. If
None
(default), the file must already be in a location appropriate for the datastore (e.g. within its root directory), and will not be modified. Other choices include “move”, “copy”, “link”, “symlink”, “relsymlink”, and “hardlink”. “link” is a special transfer mode that will first try to make a hardlink and if that fails a symlink will be used instead. “relsymlink” creates a relative symlink rather than use an absolute path. Most datastores do not support all transfer modes. “auto” is a special option that will let the data store choose the most natural option for itself.- record_validation_info
bool
, optional If
True
, the default, the datastore can record validation information associated with the file. IfFalse
the datastore will not attempt to track any information such as checksums or file sizes. This can be useful if such information is tracked in an external system or if the file is to be compressed in place. It is up to the datastore whether this parameter is relevant.
- *datasets
- Raises:
- NotImplementedError
Raised if the datastore does not support the given transfer mode (including the case where ingest is not supported at all).
- DatasetTypeNotSupportedError
Raised if one or more files to be ingested have a dataset type that is not supported by the datastore.
- FileNotFoundError
Raised if one of the given files does not exist.
- FileExistsError
Raised if transfer is not
None
but the (internal) location the file would be moved to is already occupied.
Notes
Subclasses should implement
_prepIngest
and_finishIngest
instead of implementingingest
directly. Datastores that hold and delegate to child datastores may want to call those methods as well.Subclasses are encouraged to document their supported transfer modes in their class documentation.
- abstract knows(ref: DatasetRef) bool ¶
Check if the dataset is known to the datastore.
Does not check for existence of any artifact.
- Parameters:
- ref
DatasetRef
Reference to the required dataset.
- ref
- Returns:
- knows_these(refs: Iterable[DatasetRef]) dict[DatasetRef, bool] ¶
Check which of the given datasets are known to this datastore.
This is like
mexist()
but does not check that the file exists.- Parameters:
- refsiterable
DatasetRef
The datasets to check.
- refsiterable
- Returns:
- exists
dict`[`DatasetRef
,bool
] Mapping of dataset to boolean indicating whether the dataset is known to the datastore.
- exists
- mexists(refs: Iterable[DatasetRef], artifact_existence: dict[ResourcePath, bool] | None = None) dict[DatasetRef, bool] ¶
Check the existence of multiple datasets at once.
- Parameters:
- refsiterable of
DatasetRef
The datasets to be checked.
- artifact_existence
dict
[lsst.resources.ResourcePath
,bool
] Optional mapping of datastore artifact to existence. Updated by this method with details of all artifacts tested. Can be
None
if the caller is not interested.
- refsiterable of
- Returns:
- existence
dict
of [DatasetRef
,bool
] Mapping from dataset to boolean indicating existence.
- existence
- needs_expanded_data_ids(transfer: str | None, entity: DatasetRef | DatasetType | StorageClass | None = None) bool ¶
Test whether this datastore needs expanded data IDs to ingest.
- Parameters:
- transfer
str
orNone
Transfer mode for ingest.
- entity
DatasetRef
orDatasetType
orStorageClass
orNone
, optional Object representing what will be ingested. If not provided (or not specific enough),
True
may be returned even if expanded data IDs aren’t necessary.
- transfer
- Returns:
- prepare_get_for_external_client(ref: DatasetRef) object | None ¶
Retrieve serializable data that can be used to execute a
get()
.- Parameters:
- ref
DatasetRef
Reference to the required dataset.
- ref
- Returns:
- abstract put(inMemoryDataset: Any, datasetRef: DatasetRef) None ¶
Write a
InMemoryDataset
with a givenDatasetRef
to the store.- Parameters:
- inMemoryDataset
object
The Dataset to store.
- datasetRef
DatasetRef
Reference to the associated Dataset.
- inMemoryDataset
- abstract put_new(in_memory_dataset: Any, ref: DatasetRef) Mapping[str, DatasetRef] ¶
Write a
InMemoryDataset
with a givenDatasetRef
to the store.- Parameters:
- in_memory_dataset
object
The Dataset to store.
- ref
DatasetRef
Reference to the associated Dataset.
- in_memory_dataset
- Returns:
- datastore_refs
Mapping
[str
,DatasetRef
] Mapping of a datastore name to dataset reference stored in that datastore, reference will include datastore records. Only non-ephemeral datastores will appear in this mapping.
- datastore_refs
- abstract remove(datasetRef: DatasetRef) None ¶
Indicate to the Datastore that a Dataset can be removed.
- Parameters:
- datasetRef
DatasetRef
Reference to the required Dataset.
- datasetRef
- Raises:
- FileNotFoundError
When Dataset does not exist.
Notes
Some Datastores may implement this method as a silent no-op to disable Dataset deletion through standard interfaces.
- abstract retrieveArtifacts(refs: Iterable[DatasetRef], destination: ResourcePath, transfer: str = 'auto', preserve_path: bool = True, overwrite: bool = False) list[ResourcePath] ¶
Retrieve the artifacts associated with the supplied refs.
- Parameters:
- refsiterable of
DatasetRef
The datasets for which artifacts are to be retrieved. A single ref can result in multiple artifacts. The refs must be resolved.
- destination
lsst.resources.ResourcePath
Location to write the artifacts.
- transfer
str
, optional Method to use to transfer the artifacts. Must be one of the options supported by
lsst.resources.ResourcePath.transfer_from()
. “move” is not allowed.- preserve_path
bool
, optional If
True
the full path of the artifact within the datastore is preserved. IfFalse
the final file component of the path is used.- overwrite
bool
, optional If
True
allow transfers to overwrite existing files at the destination.
- refsiterable of
- Returns:
- targets
list
oflsst.resources.ResourcePath
URIs of file artifacts in destination location. Order is not preserved.
- targets
Notes
For non-file datastores the artifacts written to the destination may not match the representation inside the datastore. For example a hierarchichal data structure in a NoSQL database may well be stored as a JSON file.
- abstract classmethod setConfigRoot(root: str, config: Config, full: Config, overwrite: bool = True) None ¶
Set filesystem-dependent config options for this datastore.
The options will be appropriate for a new empty repository with the given root.
- Parameters:
- root
str
Filesystem path to the root of the data repository.
- config
Config
A
Config
to update. Only the subset understood by this component will be updated. Will not expand defaults.- full
Config
A complete config with all defaults expanded that can be converted to a
DatastoreConfig
. Read-only and will not be modified by this method. Repository-specific options that should not be obtained from defaults when Butler instances are constructed should be copied fromfull
toconfig
.- overwrite
bool
, optional If
False
, do not modify a value inconfig
if the value already exists. Default is always to overwrite with the providedroot
.
- root
Notes
If a keyword is explicitly defined in the supplied
config
it will not be overridden by this method ifoverwrite
isFalse
. This allows explicit values set in external configs to be retained.
- set_retrieve_dataset_type_method(method: Callable[[str], DatasetType | None] | None) None ¶
Specify a method that can be used by datastore to retrieve registry-defined dataset type.
- Parameters:
- method
Callable
|None
Method that takes a name of the dataset type and returns a corresponding
DatasetType
instance as defined in Registry. If dataset type name is not known to registryNone
is returned.
- method
Notes
This method is only needed for a Datastore supporting a “trusted” mode when it does not have an access to datastore records and needs to guess dataset location based on its stored dataset type.
- transaction() Iterator[DatastoreTransaction] ¶
Context manager supporting
Datastore
transactions.Transactions can be nested, and are to be used in combination with
Registry.transaction
.
- abstract transfer(inputDatastore: Datastore, datasetRef: DatasetRef) None ¶
Transfer a dataset from another datastore to this datastore.
- Parameters:
- inputDatastore
Datastore
The external
Datastore
from which to retrieve the Dataset.- datasetRef
DatasetRef
Reference to the required Dataset.
- inputDatastore
- transfer_from(source_datastore: Datastore, refs: Collection[DatasetRef], transfer: str = 'auto', artifact_existence: dict[ResourcePath, bool] | None = None, dry_run: bool = False) tuple[set[DatasetRef], set[DatasetRef]] ¶
Transfer dataset artifacts from another datastore to this one.
- Parameters:
- source_datastore
Datastore
The datastore from which to transfer artifacts. That datastore must be compatible with this datastore receiving the artifacts.
- refs
Collection
ofDatasetRef
The datasets to transfer from the source datastore.
- transfer
str
, optional How (and whether) the dataset should be added to the datastore. Choices include “move”, “copy”, “link”, “symlink”, “relsymlink”, and “hardlink”. “link” is a special transfer mode that will first try to make a hardlink and if that fails a symlink will be used instead. “relsymlink” creates a relative symlink rather than use an absolute path. Most datastores do not support all transfer modes. “auto” (the default) is a special option that will let the data store choose the most natural option for itself. If the source location and transfer location are identical the transfer mode will be ignored.
- artifact_existence
dict
[lsst.resources.ResourcePath
,bool
] Optional mapping of datastore artifact to existence. Updated by this method with details of all artifacts tested. Can be
None
if the caller is not interested.- dry_run
bool
, optional Process the supplied source refs without updating the target datastore.
- source_datastore
- Returns:
- accepted
set
[DatasetRef
] The datasets that were transferred.
- rejected
set
[DatasetRef
] The datasets that were rejected due to a constraints violation.
- accepted
- Raises:
- TypeError
Raised if the two datastores are not compatible.
- abstract trash(ref: DatasetRef | Iterable[DatasetRef], ignore_errors: bool = True) None ¶
Indicate to the Datastore that a Dataset can be moved to the trash.
- Parameters:
- ref
DatasetRef
or iterable thereof Reference(s) to the required Dataset.
- ignore_errors
bool
, optional Determine whether errors should be ignored. When multiple refs are being trashed there will be no per-ref check.
- ref
- Raises:
- FileNotFoundError
When Dataset does not exist and errors are not ignored. Only checked if a single ref is supplied (and not in a list).
Notes
Some Datastores may implement this method as a silent no-op to disable Dataset deletion through standard interfaces.
- abstract validateConfiguration(entities: Iterable[DatasetRef | DatasetType | StorageClass], logFailures: bool = False) None ¶
Validate some of the configuration for this datastore.
- Parameters:
- entitiesiterable of
DatasetRef
,DatasetType
, orStorageClass
Entities to test against this configuration. Can be differing types.
- logFailures
bool
, optional If
True
, output a log message for every validation error detected.
- entitiesiterable of
- Raises:
- DatastoreValidationError
Raised if there is a validation problem with a configuration.
Notes
Which parts of the configuration are validated is at the discretion of each Datastore implementation.
- abstract validateKey(lookupKey: LookupKey, entity: DatasetRef | DatasetType | StorageClass) None ¶
Validate a specific look up key with supplied entity.
- Parameters:
- lookupKey
LookupKey
Key to use to retrieve information from the datastore configuration.
- entity
DatasetRef
,DatasetType
, orStorageClass
Entity to compare with configuration retrieved using the specified lookup key.
- lookupKey
- Raises:
- DatastoreValidationError
Raised if there is a problem with the combination of entity and lookup key.
Notes
Bypasses the normal selection priorities by allowing a key that would normally not be selected to be validated.