What does the key parameter do under the hood?¶
LaminDB is designed around associating biological metadata to artifacts and collections. This enables querying for them in storage by metadata and removes the requirement for semantic artifact and collection names.
Here, we will discuss trade-offs for using the key parameter, which allows for semantic keys, in various scenarios.
Setup¶
Install the lamindb Python package:
pip install 'lamindb[jupyter]'
We’re simulating an artifact system with several nested folders and artifacts. Such structures are resembled in, for example, the RxRx: cell imaging guide.
import random
import string
from pathlib import Path
def create_complex_biological_hierarchy(root_folder):
root_path = Path(root_folder)
if root_path.exists():
print("Folder structure already exists. Skipping...")
else:
root_path.mkdir()
raw_folder = root_path / "raw"
preprocessed_folder = root_path / "preprocessed"
raw_folder.mkdir()
preprocessed_folder.mkdir()
for i in range(1, 5):
artifact_name = f"raw_data_{i}.txt"
with (raw_folder / artifact_name).open("w") as f:
random_text = "".join(
random.choice(string.ascii_letters) for _ in range(10)
)
f.write(random_text)
for i in range(1, 3):
collection_folder = raw_folder / f"Collection_{i}"
collection_folder.mkdir()
for j in range(1, 5):
artifact_name = f"raw_data_{j}.txt"
with (collection_folder / artifact_name).open("w") as f:
random_text = "".join(
random.choice(string.ascii_letters) for _ in range(10)
)
f.write(random_text)
for i in range(1, 5):
artifact_name = f"result_{i}.txt"
with (preprocessed_folder / artifact_name).open("w") as f:
random_text = "".join(
random.choice(string.ascii_letters) for _ in range(10)
)
f.write(random_text)
root_folder = "complex_biological_project"
create_complex_biological_hierarchy(root_folder)
!lamin init --storage ./key-eval
💡 connected lamindb: testuser1/key-eval
import lamindb as ln
ln.settings.verbosity = "hint"
💡 connected lamindb: testuser1/key-eval
ln.UPath("complex_biological_project").view_tree()
4 sub-directories & 8 files with suffixes '.txt'
/home/runner/work/lamindb/lamindb/docs/faq/complex_biological_project
├── preprocessed/
│ ├── result_4.txt
│ ├── result_1.txt
│ ├── result_3.txt
│ └── result_2.txt
└── raw/
├── Collection_1/
├── raw_data_3.txt
├── raw_data_1.txt
├── raw_data_2.txt
├── Collection_2/
└── raw_data_4.txt
ln.settings.transform.stem_uid = "WIwaNDvlEkwS"
ln.settings.transform.version = "1"
ln.track()
💡 notebook imports: lamindb==0.74.1
💡 saved: Transform(uid='WIwaNDvlEkwS5zKv', version='1', name='What does the key parameter do under the hood?', key='key', type='notebook', created_by_id=1, updated_at='2024-07-06 12:50:01 UTC')
💡 saved: Run(uid='jyZsba2WONPhEnxXN7k8', transform_id=1, created_by_id=1)
💡 tracked pip freeze > /home/runner/.cache/lamindb/run_env_pip_jyZsba2WONPhEnxXN7k8.txt
Run(uid='jyZsba2WONPhEnxXN7k8', started_at='2024-07-06 12:50:01 UTC', is_consecutive=True, transform_id=1, created_by_id=1)
Storing artifacts using Storage, File, and Collection¶
Lamin has three storage classes that manage different types of in-memory and on-disk objects:
Storage: Manages the default storage root that can be either local or in the cloud. For more details we refer to Storage FAQ.Artifact: Manages datasets with an optionalkeythat acts as a relative path within the current default storage root (seeStorage). An example is a single h5 artifact.Collection: Manages a collection of datasets with an optionalkeythat acts as a relative path within the current default storage root (seeStorage). An example is a collection of h5 artifacts.
For more details we refer to Tutorial: Artifacts.
The current storage root is:
ln.settings.storage
StorageSettings(root='/home/runner/work/lamindb/lamindb/docs/faq/key-eval', uid='ABf8Pwtf89MW')
By default, Lamin uses virtual keys that are only reflected in the database but not in storage.
It is possible to turn this behavior off by setting ln.settings.creation._artifact_use_virtual_keys = False.
Generally, we discourage disabling this setting manually. For more details we refer to Storage FAQ.
ln.settings.creation._artifact_use_virtual_keys
True
We will now create File objects with and without semantic keys using key and also save them as Collections.
artifact_no_key_1 = ln.Artifact("complex_biological_project/raw/raw_data_1.txt")
artifact_no_key_2 = ln.Artifact("complex_biological_project/raw/raw_data_2.txt")
💡 path content will be copied to default storage upon `save()` with key `None` ('.lamindb/Yy6SxUpNDlZRTbWzJkll.txt')
💡 path content will be copied to default storage upon `save()` with key `None` ('.lamindb/YXof7jwWOzMiYRVeAlxw.txt')
The logging suggests that the artifacts will be saved to our current default storage with auto generated storage keys.
artifact_no_key_1.save()
artifact_no_key_2.save()
✅ storing artifact 'Yy6SxUpNDlZRTbWzJkll' at '/home/runner/work/lamindb/lamindb/docs/faq/key-eval/.lamindb/Yy6SxUpNDlZRTbWzJkll.txt'
✅ storing artifact 'YXof7jwWOzMiYRVeAlxw' at '/home/runner/work/lamindb/lamindb/docs/faq/key-eval/.lamindb/YXof7jwWOzMiYRVeAlxw.txt'
Artifact(uid='YXof7jwWOzMiYRVeAlxw', suffix='.txt', type='dataset', size=10, hash='HJFjpVT4TShXhWwKcvBEjA', hash_type='md5', visibility=1, key_is_virtual=True, created_by_id=1, storage_id=1, transform_id=1, run_id=1, updated_at='2024-07-06 12:50:02 UTC')
artifact_key_3 = ln.Artifact(
"complex_biological_project/raw/raw_data_3.txt", key="raw/raw_data_3.txt"
)
artifact_key_4 = ln.Artifact(
"complex_biological_project/raw/raw_data_4.txt", key="raw/raw_data_4.txt"
)
artifact_key_3.save()
artifact_key_4.save()
💡 path content will be copied to default storage upon `save()` with key 'raw/raw_data_3.txt'
💡 path content will be copied to default storage upon `save()` with key 'raw/raw_data_4.txt'
✅ storing artifact 'gPNt4SYIVVjNXAIF2GVs' at '/home/runner/work/lamindb/lamindb/docs/faq/key-eval/.lamindb/gPNt4SYIVVjNXAIF2GVs.txt'
✅ storing artifact '2YGKR6iekm0cDB2I2loB' at '/home/runner/work/lamindb/lamindb/docs/faq/key-eval/.lamindb/2YGKR6iekm0cDB2I2loB.txt'
Artifact(uid='2YGKR6iekm0cDB2I2loB', key='raw/raw_data_4.txt', suffix='.txt', type='dataset', size=10, hash='xx57revqfoaM92ty0snjyg', hash_type='md5', visibility=1, key_is_virtual=True, created_by_id=1, storage_id=1, transform_id=1, run_id=1, updated_at='2024-07-06 12:50:02 UTC')
Files with keys are not stored in different locations because of the usage of virtual keys.
However, they are still semantically queryable by key.
ln.Artifact.filter(key__contains="raw").df().head()
| uid | version | description | key | suffix | type | accessor | size | hash | hash_type | n_objects | n_observations | visibility | key_is_virtual | storage_id | transform_id | run_id | created_by_id | updated_at | |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| id | |||||||||||||||||||
| 3 | gPNt4SYIVVjNXAIF2GVs | None | None | raw/raw_data_3.txt | .txt | dataset | None | 10 | 8X1oiSkx_flg-x8qjT39Uw | md5 | None | None | 1 | True | 1 | 1 | 1 | 1 | 2024-07-06 12:50:02.056869+00:00 |
| 4 | 2YGKR6iekm0cDB2I2loB | None | None | raw/raw_data_4.txt | .txt | dataset | None | 10 | xx57revqfoaM92ty0snjyg | md5 | None | None | 1 | True | 1 | 1 | 1 | 1 | 2024-07-06 12:50:02.060900+00:00 |
Collection does not have a key parameter because it does not store any additional data in Storage.
In contrast, it has a name parameter that serves as a semantic identifier of the collection.
ds_1 = ln.Collection([artifact_no_key_1, artifact_no_key_2], name="no key collection")
ds_2 = ln.Collection([artifact_key_3, artifact_key_4], name="sample collection")
ds_1
Collection(uid='FKUMZZsCkRTVUD2XDHqU', name='no key collection', hash='LyBFFYRv55bBXY3xrHQV', visibility=1, created_by_id=1, transform_id=1, run_id=1)
Advantages and disadvantages of semantic keys¶
Semantic keys have several advantages and disadvantages that we will discuss and demonstrate in the remaining notebook:
Advantages:¶
Simple: It can be easier to refer to specific collections in conversations
Familiarity: Most people are familiar with the concept of semantic names
Disadvantages¶
Length: Semantic names can be long with limited aesthetic appeal
Inconsistency: Lack of naming conventions can lead to confusion
Limited metadata: Semantic keys can contain some, but usually not all metadata
Inefficiency: Writing lengthy semantic names is a repetitive process and can be time-consuming
Ambiguity: Overly descriptive artifact names may introduce ambiguity and redundancy
Clashes: Several people may attempt to use the same semantic key. They are not unique
Renaming artifacts¶
Renaming Files that have associated keys can be done on several levels.
In storage¶
A artifact can be locally moved or renamed:
artifact_key_3.path
PosixUPath('/home/runner/work/lamindb/lamindb/docs/faq/key-eval/.lamindb/gPNt4SYIVVjNXAIF2GVs.txt')
loaded_artifact = artifact_key_3.load()
!mkdir complex_biological_project/moved_artifacts
!mv complex_biological_project/raw/raw_data_3.txt complex_biological_project/moved_artifacts
artifact_key_3.path
PosixUPath('/home/runner/work/lamindb/lamindb/docs/faq/key-eval/.lamindb/gPNt4SYIVVjNXAIF2GVs.txt')
After moving the artifact locally, the storage location (the path) has not changed and the artifact can still be loaded.
artifact_3 = artifact_key_3.load()
The same applies to the key which has not changed.
artifact_key_3.key
'raw/raw_data_3.txt'
By key¶
Besides moving the artifact in storage, the key can also be renamed.
artifact_key_4.key
'raw/raw_data_4.txt'
artifact_key_4.key = "bad_samples/sample_data_4.txt"
artifact_key_4.key
'bad_samples/sample_data_4.txt'
Due to the usage of virtual keys, modifying the key does not change the storage location and the artifact stays accessible.
artifact_key_4.path
PosixUPath('/home/runner/work/lamindb/lamindb/docs/faq/key-eval/.lamindb/2YGKR6iekm0cDB2I2loB.txt')
artifact_4 = artifact_key_4.load()
Modifying the path attribute¶
However, modifying the path directly is not allowed:
try:
artifact_key_4.path = f"{ln.settings.storage}/here_now/sample_data_4.txt"
except AttributeError as e:
print(e)
property of 'Artifact' object has no setter
Clashing semantic keys¶
Semantic keys should not clash. Let’s attempt to use the same semantic key twice
print(artifact_key_3.key)
print(artifact_key_4.key)
raw/raw_data_3.txt
bad_samples/sample_data_4.txt
artifact_key_4.key = "raw/raw_data_3.txt"
print(artifact_key_3.key)
print(artifact_key_4.key)
raw/raw_data_3.txt
raw/raw_data_3.txt
When filtering for this semantic key it is now unclear to which artifact we were referring to:
ln.Artifact.filter(key__icontains="sample_data_3").df()
| uid | version | description | key | suffix | type | accessor | size | hash | hash_type | n_objects | n_observations | visibility | key_is_virtual | storage_id | transform_id | run_id | created_by_id | updated_at | |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| id |
When querying by key LaminDB cannot resolve which artifact we actually wanted.
In fact, we only get a single hit which does not paint a complete picture.
print(artifact_key_3.uid)
print(artifact_key_4.uid)
gPNt4SYIVVjNXAIF2GVs
2YGKR6iekm0cDB2I2loB
Both artifacts still exist though with unique uids that can be used to get access to them.
Most importantly though, saving these artifacts to the database will result in an IntegrityError to prevent this issue.
try:
artifact_key_3.save()
artifact_key_4.save()
except Exception as e:
print(
"It is not possible to save artifacts to the same key. This results in an"
" Integrity Error!"
)
We refer to What happens if I save the same artifacts & records twice? for more detailed explanations of behavior when attempting to save artifacts multiple times.
Hierarchies¶
Another common use-case of keys are artifact hierarchies.
It can be useful to resemble the artifact structure in “complex_biological_project” from above also in LaminDB to allow for queries for artifacts that were stored in specific folders.
Common examples of this are folders specifying different processing stages such as raw, preprocessed, or annotated.
Note that this use-case may also be overlapping with Collection which also allows for grouping Files.
However, Collection cannot model hierarchical groupings.
Key¶
import os
for root, _, artifacts in os.walk("complex_biological_project/raw"):
for artifactname in artifacts:
file_path = os.path.join(root, artifactname)
key_path = file_path.removeprefix("complex_biological_project")
ln_artifact = ln.Artifact(file_path, key=key_path)
ln_artifact.save()
💡 returning existing artifact with same hash: Artifact(uid='Yy6SxUpNDlZRTbWzJkll', suffix='.txt', type='dataset', size=10, hash='XAl5Qh_riySzWBOb3ExDJg', hash_type='md5', visibility=1, key_is_virtual=True, created_by_id=1, storage_id=1, transform_id=1, run_id=1, updated_at='2024-07-06 12:50:02 UTC')
❗ key None on existing artifact differs from passed key /raw/raw_data_1.txt
💡 returning existing artifact with same hash: Artifact(uid='YXof7jwWOzMiYRVeAlxw', suffix='.txt', type='dataset', size=10, hash='HJFjpVT4TShXhWwKcvBEjA', hash_type='md5', visibility=1, key_is_virtual=True, created_by_id=1, storage_id=1, transform_id=1, run_id=1, updated_at='2024-07-06 12:50:02 UTC')
❗ key None on existing artifact differs from passed key /raw/raw_data_2.txt
💡 returning existing artifact with same hash: Artifact(uid='2YGKR6iekm0cDB2I2loB', key='raw/raw_data_3.txt', suffix='.txt', type='dataset', size=10, hash='xx57revqfoaM92ty0snjyg', hash_type='md5', visibility=1, key_is_virtual=True, created_by_id=1, storage_id=1, transform_id=1, run_id=1, updated_at='2024-07-06 12:50:02 UTC')
❗ key raw/raw_data_3.txt on existing artifact differs from passed key /raw/raw_data_4.txt
💡 path content will be copied to default storage upon `save()` with key '/raw/Collection_1/raw_data_3.txt'
✅ storing artifact 'Vp9X3C7KWRQ6bKf8GG4y' at '/home/runner/work/lamindb/lamindb/docs/faq/key-eval/.lamindb/Vp9X3C7KWRQ6bKf8GG4y.txt'
💡 path content will be copied to default storage upon `save()` with key '/raw/Collection_1/raw_data_1.txt'
✅ storing artifact 'bXUB28jZ3wCdfBJ6lVT1' at '/home/runner/work/lamindb/lamindb/docs/faq/key-eval/.lamindb/bXUB28jZ3wCdfBJ6lVT1.txt'
💡 path content will be copied to default storage upon `save()` with key '/raw/Collection_1/raw_data_2.txt'
✅ storing artifact 'SVpsqqY3plQcOzULifgw' at '/home/runner/work/lamindb/lamindb/docs/faq/key-eval/.lamindb/SVpsqqY3plQcOzULifgw.txt'
💡 path content will be copied to default storage upon `save()` with key '/raw/Collection_1/raw_data_4.txt'
✅ storing artifact 'HO0BctC2BS3ez2amjnEp' at '/home/runner/work/lamindb/lamindb/docs/faq/key-eval/.lamindb/HO0BctC2BS3ez2amjnEp.txt'
💡 path content will be copied to default storage upon `save()` with key '/raw/Collection_2/raw_data_3.txt'
✅ storing artifact '5z1frkWywntZvIEbXAca' at '/home/runner/work/lamindb/lamindb/docs/faq/key-eval/.lamindb/5z1frkWywntZvIEbXAca.txt'
💡 path content will be copied to default storage upon `save()` with key '/raw/Collection_2/raw_data_1.txt'
✅ storing artifact 'm6z8wHij4RJaeY91uGcV' at '/home/runner/work/lamindb/lamindb/docs/faq/key-eval/.lamindb/m6z8wHij4RJaeY91uGcV.txt'
💡 path content will be copied to default storage upon `save()` with key '/raw/Collection_2/raw_data_2.txt'
✅ storing artifact 'oKKI92T1MuGlvKSKdyaA' at '/home/runner/work/lamindb/lamindb/docs/faq/key-eval/.lamindb/oKKI92T1MuGlvKSKdyaA.txt'
💡 path content will be copied to default storage upon `save()` with key '/raw/Collection_2/raw_data_4.txt'
✅ storing artifact 'jsjI5OSSegQX9FR8EAcJ' at '/home/runner/work/lamindb/lamindb/docs/faq/key-eval/.lamindb/jsjI5OSSegQX9FR8EAcJ.txt'
ln.Artifact.filter(key__startswith="raw").df()
| uid | version | description | key | suffix | type | accessor | size | hash | hash_type | n_objects | n_observations | visibility | key_is_virtual | storage_id | transform_id | run_id | created_by_id | updated_at | |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| id | |||||||||||||||||||
| 3 | gPNt4SYIVVjNXAIF2GVs | None | None | raw/raw_data_3.txt | .txt | dataset | None | 10 | 8X1oiSkx_flg-x8qjT39Uw | md5 | None | None | 1 | True | 1 | 1 | 1 | 1 | 2024-07-06 12:50:02.490162+00:00 |
| 4 | 2YGKR6iekm0cDB2I2loB | None | None | raw/raw_data_3.txt | .txt | dataset | None | 10 | xx57revqfoaM92ty0snjyg | md5 | None | None | 1 | True | 1 | 1 | 1 | 1 | 2024-07-06 12:50:02.529780+00:00 |
Collection¶
Alternatively, it would have been possible to create a Collection with a corresponding name:
all_data_paths = []
for root, _, artifacts in os.walk("complex_biological_project/raw"):
for artifactname in artifacts:
file_path = os.path.join(root, artifactname)
all_data_paths.append(file_path)
all_data_artifacts = []
for path in all_data_paths:
all_data_artifacts.append(ln.Artifact(path))
data_ds = ln.Collection(all_data_artifacts, name="data")
data_ds.save()
💡 returning existing artifact with same hash: Artifact(uid='Yy6SxUpNDlZRTbWzJkll', suffix='.txt', type='dataset', size=10, hash='XAl5Qh_riySzWBOb3ExDJg', hash_type='md5', visibility=1, key_is_virtual=True, created_by_id=1, storage_id=1, transform_id=1, run_id=1, updated_at='2024-07-06 12:50:02 UTC')
💡 returning existing artifact with same hash: Artifact(uid='YXof7jwWOzMiYRVeAlxw', suffix='.txt', type='dataset', size=10, hash='HJFjpVT4TShXhWwKcvBEjA', hash_type='md5', visibility=1, key_is_virtual=True, created_by_id=1, storage_id=1, transform_id=1, run_id=1, updated_at='2024-07-06 12:50:02 UTC')
💡 returning existing artifact with same hash: Artifact(uid='2YGKR6iekm0cDB2I2loB', key='raw/raw_data_3.txt', suffix='.txt', type='dataset', size=10, hash='xx57revqfoaM92ty0snjyg', hash_type='md5', visibility=1, key_is_virtual=True, created_by_id=1, storage_id=1, transform_id=1, run_id=1, updated_at='2024-07-06 12:50:02 UTC')
💡 returning existing artifact with same hash: Artifact(uid='Vp9X3C7KWRQ6bKf8GG4y', key='/raw/Collection_1/raw_data_3.txt', suffix='.txt', type='dataset', size=10, hash='B9II-MP0kKAx4Tn2xtQdOg', hash_type='md5', visibility=1, key_is_virtual=True, created_by_id=1, storage_id=1, transform_id=1, run_id=1, updated_at='2024-07-06 12:50:02 UTC')
💡 returning existing artifact with same hash: Artifact(uid='bXUB28jZ3wCdfBJ6lVT1', key='/raw/Collection_1/raw_data_1.txt', suffix='.txt', type='dataset', size=10, hash='W57ttx7EnZnnnoheTiSgCA', hash_type='md5', visibility=1, key_is_virtual=True, created_by_id=1, storage_id=1, transform_id=1, run_id=1, updated_at='2024-07-06 12:50:02 UTC')
💡 returning existing artifact with same hash: Artifact(uid='SVpsqqY3plQcOzULifgw', key='/raw/Collection_1/raw_data_2.txt', suffix='.txt', type='dataset', size=10, hash='DofkUuR15fScQSuqbg19CQ', hash_type='md5', visibility=1, key_is_virtual=True, created_by_id=1, storage_id=1, transform_id=1, run_id=1, updated_at='2024-07-06 12:50:02 UTC')
💡 returning existing artifact with same hash: Artifact(uid='HO0BctC2BS3ez2amjnEp', key='/raw/Collection_1/raw_data_4.txt', suffix='.txt', type='dataset', size=10, hash='s_e9dYyOYKO_vWe4mA0Xmw', hash_type='md5', visibility=1, key_is_virtual=True, created_by_id=1, storage_id=1, transform_id=1, run_id=1, updated_at='2024-07-06 12:50:02 UTC')
💡 returning existing artifact with same hash: Artifact(uid='5z1frkWywntZvIEbXAca', key='/raw/Collection_2/raw_data_3.txt', suffix='.txt', type='dataset', size=10, hash='-Z8rTVpY8MQDpy3qh7GoGw', hash_type='md5', visibility=1, key_is_virtual=True, created_by_id=1, storage_id=1, transform_id=1, run_id=1, updated_at='2024-07-06 12:50:02 UTC')
💡 returning existing artifact with same hash: Artifact(uid='m6z8wHij4RJaeY91uGcV', key='/raw/Collection_2/raw_data_1.txt', suffix='.txt', type='dataset', size=10, hash='hIXyQ97HeeZ4wGYp2ivBTw', hash_type='md5', visibility=1, key_is_virtual=True, created_by_id=1, storage_id=1, transform_id=1, run_id=1, updated_at='2024-07-06 12:50:02 UTC')
💡 returning existing artifact with same hash: Artifact(uid='oKKI92T1MuGlvKSKdyaA', key='/raw/Collection_2/raw_data_2.txt', suffix='.txt', type='dataset', size=10, hash='ZotSm6FuaJB0jE8yTVsClQ', hash_type='md5', visibility=1, key_is_virtual=True, created_by_id=1, storage_id=1, transform_id=1, run_id=1, updated_at='2024-07-06 12:50:02 UTC')
💡 returning existing artifact with same hash: Artifact(uid='jsjI5OSSegQX9FR8EAcJ', key='/raw/Collection_2/raw_data_4.txt', suffix='.txt', type='dataset', size=10, hash='FQblusptpPTyH1Velq3MAQ', hash_type='md5', visibility=1, key_is_virtual=True, created_by_id=1, storage_id=1, transform_id=1, run_id=1, updated_at='2024-07-06 12:50:02 UTC')
ln.Collection.filter(name__icontains="data").df()
| uid | version | name | description | hash | reference | reference_type | visibility | transform_id | artifact_id | run_id | created_by_id | updated_at | |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| id | |||||||||||||
| 1 | 3iCFkuaAuc04zHVBjHK9 | None | data | None | W5ViXpwAh1snNPP2os1r | None | None | 1 | 1 | None | 1 | 1 | 2024-07-06 12:50:02.690362+00:00 |
This approach will likely lead to clashes. Alternatively, Ulabels can be added to Files to resemble hierarchies.
Ulabels¶
for root, _, artifacts in os.walk("complex_biological_project/raw"):
for artifactname in artifacts:
file_path = os.path.join(root, artifactname)
key_path = file_path.removeprefix("complex_biological_project")
ln_artifact = ln.Artifact(file_path, key=key_path)
ln_artifact.save()
data_label = ln.ULabel(name="data")
data_label.save()
ln_artifact.ulabels.add(data_label)
💡 returning existing artifact with same hash: Artifact(uid='Yy6SxUpNDlZRTbWzJkll', suffix='.txt', type='dataset', size=10, hash='XAl5Qh_riySzWBOb3ExDJg', hash_type='md5', visibility=1, key_is_virtual=True, created_by_id=1, storage_id=1, transform_id=1, run_id=1, updated_at='2024-07-06 12:50:02 UTC')
❗ key None on existing artifact differs from passed key /raw/raw_data_1.txt
💡 returning existing artifact with same hash: Artifact(uid='YXof7jwWOzMiYRVeAlxw', suffix='.txt', type='dataset', size=10, hash='HJFjpVT4TShXhWwKcvBEjA', hash_type='md5', visibility=1, key_is_virtual=True, created_by_id=1, storage_id=1, transform_id=1, run_id=1, updated_at='2024-07-06 12:50:02 UTC')
❗ key None on existing artifact differs from passed key /raw/raw_data_2.txt
💡 returning existing ULabel record with same name: 'data'
💡 returning existing artifact with same hash: Artifact(uid='2YGKR6iekm0cDB2I2loB', key='raw/raw_data_3.txt', suffix='.txt', type='dataset', size=10, hash='xx57revqfoaM92ty0snjyg', hash_type='md5', visibility=1, key_is_virtual=True, created_by_id=1, storage_id=1, transform_id=1, run_id=1, updated_at='2024-07-06 12:50:02 UTC')
❗ key raw/raw_data_3.txt on existing artifact differs from passed key /raw/raw_data_4.txt
💡 returning existing ULabel record with same name: 'data'
💡 returning existing artifact with same hash: Artifact(uid='Vp9X3C7KWRQ6bKf8GG4y', key='/raw/Collection_1/raw_data_3.txt', suffix='.txt', type='dataset', size=10, hash='B9II-MP0kKAx4Tn2xtQdOg', hash_type='md5', visibility=1, key_is_virtual=True, created_by_id=1, storage_id=1, transform_id=1, run_id=1, updated_at='2024-07-06 12:50:02 UTC')
💡 returning existing ULabel record with same name: 'data'
💡 returning existing artifact with same hash: Artifact(uid='bXUB28jZ3wCdfBJ6lVT1', key='/raw/Collection_1/raw_data_1.txt', suffix='.txt', type='dataset', size=10, hash='W57ttx7EnZnnnoheTiSgCA', hash_type='md5', visibility=1, key_is_virtual=True, created_by_id=1, storage_id=1, transform_id=1, run_id=1, updated_at='2024-07-06 12:50:02 UTC')
💡 returning existing ULabel record with same name: 'data'
💡 returning existing artifact with same hash: Artifact(uid='SVpsqqY3plQcOzULifgw', key='/raw/Collection_1/raw_data_2.txt', suffix='.txt', type='dataset', size=10, hash='DofkUuR15fScQSuqbg19CQ', hash_type='md5', visibility=1, key_is_virtual=True, created_by_id=1, storage_id=1, transform_id=1, run_id=1, updated_at='2024-07-06 12:50:02 UTC')
💡 returning existing ULabel record with same name: 'data'
💡 returning existing artifact with same hash: Artifact(uid='HO0BctC2BS3ez2amjnEp', key='/raw/Collection_1/raw_data_4.txt', suffix='.txt', type='dataset', size=10, hash='s_e9dYyOYKO_vWe4mA0Xmw', hash_type='md5', visibility=1, key_is_virtual=True, created_by_id=1, storage_id=1, transform_id=1, run_id=1, updated_at='2024-07-06 12:50:02 UTC')
💡 returning existing ULabel record with same name: 'data'
💡 returning existing artifact with same hash: Artifact(uid='5z1frkWywntZvIEbXAca', key='/raw/Collection_2/raw_data_3.txt', suffix='.txt', type='dataset', size=10, hash='-Z8rTVpY8MQDpy3qh7GoGw', hash_type='md5', visibility=1, key_is_virtual=True, created_by_id=1, storage_id=1, transform_id=1, run_id=1, updated_at='2024-07-06 12:50:02 UTC')
💡 returning existing ULabel record with same name: 'data'
💡 returning existing artifact with same hash: Artifact(uid='m6z8wHij4RJaeY91uGcV', key='/raw/Collection_2/raw_data_1.txt', suffix='.txt', type='dataset', size=10, hash='hIXyQ97HeeZ4wGYp2ivBTw', hash_type='md5', visibility=1, key_is_virtual=True, created_by_id=1, storage_id=1, transform_id=1, run_id=1, updated_at='2024-07-06 12:50:02 UTC')
💡 returning existing ULabel record with same name: 'data'
💡 returning existing artifact with same hash: Artifact(uid='oKKI92T1MuGlvKSKdyaA', key='/raw/Collection_2/raw_data_2.txt', suffix='.txt', type='dataset', size=10, hash='ZotSm6FuaJB0jE8yTVsClQ', hash_type='md5', visibility=1, key_is_virtual=True, created_by_id=1, storage_id=1, transform_id=1, run_id=1, updated_at='2024-07-06 12:50:02 UTC')
💡 returning existing ULabel record with same name: 'data'
💡 returning existing artifact with same hash: Artifact(uid='jsjI5OSSegQX9FR8EAcJ', key='/raw/Collection_2/raw_data_4.txt', suffix='.txt', type='dataset', size=10, hash='FQblusptpPTyH1Velq3MAQ', hash_type='md5', visibility=1, key_is_virtual=True, created_by_id=1, storage_id=1, transform_id=1, run_id=1, updated_at='2024-07-06 12:50:02 UTC')
💡 returning existing ULabel record with same name: 'data'
labels = ln.ULabel.lookup()
ln.Artifact.filter(ulabels__in=[labels.data]).df()
| uid | version | description | key | suffix | type | accessor | size | hash | hash_type | n_objects | n_observations | visibility | key_is_virtual | storage_id | transform_id | run_id | created_by_id | updated_at | |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| id | |||||||||||||||||||
| 1 | Yy6SxUpNDlZRTbWzJkll | None | None | None | .txt | dataset | None | 10 | XAl5Qh_riySzWBOb3ExDJg | md5 | None | None | 1 | True | 1 | 1 | 1 | 1 | 2024-07-06 12:50:02.730372+00:00 |
| 2 | YXof7jwWOzMiYRVeAlxw | None | None | None | .txt | dataset | None | 10 | HJFjpVT4TShXhWwKcvBEjA | md5 | None | None | 1 | True | 1 | 1 | 1 | 1 | 2024-07-06 12:50:02.748422+00:00 |
| 4 | 2YGKR6iekm0cDB2I2loB | None | None | raw/raw_data_3.txt | .txt | dataset | None | 10 | xx57revqfoaM92ty0snjyg | md5 | None | None | 1 | True | 1 | 1 | 1 | 1 | 2024-07-06 12:50:02.769592+00:00 |
| 5 | Vp9X3C7KWRQ6bKf8GG4y | None | None | /raw/Collection_1/raw_data_3.txt | .txt | dataset | None | 10 | B9II-MP0kKAx4Tn2xtQdOg | md5 | None | None | 1 | True | 1 | 1 | 1 | 1 | 2024-07-06 12:50:02.789646+00:00 |
| 6 | bXUB28jZ3wCdfBJ6lVT1 | None | None | /raw/Collection_1/raw_data_1.txt | .txt | dataset | None | 10 | W57ttx7EnZnnnoheTiSgCA | md5 | None | None | 1 | True | 1 | 1 | 1 | 1 | 2024-07-06 12:50:02.809230+00:00 |
| 7 | SVpsqqY3plQcOzULifgw | None | None | /raw/Collection_1/raw_data_2.txt | .txt | dataset | None | 10 | DofkUuR15fScQSuqbg19CQ | md5 | None | None | 1 | True | 1 | 1 | 1 | 1 | 2024-07-06 12:50:02.829513+00:00 |
| 8 | HO0BctC2BS3ez2amjnEp | None | None | /raw/Collection_1/raw_data_4.txt | .txt | dataset | None | 10 | s_e9dYyOYKO_vWe4mA0Xmw | md5 | None | None | 1 | True | 1 | 1 | 1 | 1 | 2024-07-06 12:50:02.850101+00:00 |
| 9 | 5z1frkWywntZvIEbXAca | None | None | /raw/Collection_2/raw_data_3.txt | .txt | dataset | None | 10 | -Z8rTVpY8MQDpy3qh7GoGw | md5 | None | None | 1 | True | 1 | 1 | 1 | 1 | 2024-07-06 12:50:02.870391+00:00 |
| 10 | m6z8wHij4RJaeY91uGcV | None | None | /raw/Collection_2/raw_data_1.txt | .txt | dataset | None | 10 | hIXyQ97HeeZ4wGYp2ivBTw | md5 | None | None | 1 | True | 1 | 1 | 1 | 1 | 2024-07-06 12:50:02.890911+00:00 |
| 11 | oKKI92T1MuGlvKSKdyaA | None | None | /raw/Collection_2/raw_data_2.txt | .txt | dataset | None | 10 | ZotSm6FuaJB0jE8yTVsClQ | md5 | None | None | 1 | True | 1 | 1 | 1 | 1 | 2024-07-06 12:50:02.911502+00:00 |
| 12 | jsjI5OSSegQX9FR8EAcJ | None | None | /raw/Collection_2/raw_data_4.txt | .txt | dataset | None | 10 | FQblusptpPTyH1Velq3MAQ | md5 | None | None | 1 | True | 1 | 1 | 1 | 1 | 2024-07-06 12:50:02.931062+00:00 |
However, Ulabels are too versatile for such an approach and clashes are also to be expected here.
Metadata¶
Due to the chance of clashes for the aforementioned approaches being rather high, we generally recommend not to store hierarchical data with solely semantic keys.
Biological metadata makes Files and Collections unambiguous and easily queryable.
Legacy data and multiple storage roots¶
Distributed Collections¶
LaminDB can ingest legacy data that already had a structure in their storage.
In such cases, it disables _artifact_use_virtual_keys and the artifacts are ingested with their actual storage location.
It might be therefore be possible that Files stored in different storage roots may be associated with a single Collection.
To simulate this, we are disabling _artifact_use_virtual_keys and ingest artifacts stored in a different path (the “legacy data”).
ln.settings.creation._artifact_use_virtual_keys = False
for root, _, artifacts in os.walk("complex_biological_project/preprocessed"):
for artifactname in artifacts:
file_path = os.path.join(root, artifactname)
key_path = file_path.removeprefix("complex_biological_project")
print(file_path)
print()
ln_artifact = ln.Artifact(file_path, key=f"./{key_path}")
ln_artifact.save()
complex_biological_project/preprocessed/result_4.txt
💡 path content will be copied to default storage upon `save()` with key './/preprocessed/result_4.txt'
✅ storing artifact 'VDwnHlJL6Kx91IH32xyd' at '/home/runner/work/lamindb/lamindb/docs/faq/key-eval/preprocessed/result_4.txt'
complex_biological_project/preprocessed/result_1.txt
💡 path content will be copied to default storage upon `save()` with key './/preprocessed/result_1.txt'
✅ storing artifact 'xLD04DyWqamAAX93fumO' at '/home/runner/work/lamindb/lamindb/docs/faq/key-eval/preprocessed/result_1.txt'
complex_biological_project/preprocessed/result_3.txt
💡 path content will be copied to default storage upon `save()` with key './/preprocessed/result_3.txt'
✅ storing artifact 'tGPKybCLKZGuv9MwsO9I' at '/home/runner/work/lamindb/lamindb/docs/faq/key-eval/preprocessed/result_3.txt'
complex_biological_project/preprocessed/result_2.txt
💡 path content will be copied to default storage upon `save()` with key './/preprocessed/result_2.txt'
✅ storing artifact 'hCg26eRMaRncF8aZio8f' at '/home/runner/work/lamindb/lamindb/docs/faq/key-eval/preprocessed/result_2.txt'
ln.Artifact.df()
| uid | version | description | key | suffix | type | accessor | size | hash | hash_type | n_objects | n_observations | visibility | key_is_virtual | storage_id | transform_id | run_id | created_by_id | updated_at | |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| id | |||||||||||||||||||
| 16 | hCg26eRMaRncF8aZio8f | None | None | .//preprocessed/result_2.txt | .txt | dataset | None | 10 | -DkOj7vsh3SuYV-9dENZFA | md5 | None | None | 1 | False | 1 | 1 | 1 | 1 | 2024-07-06 12:50:03.022000+00:00 |
| 15 | tGPKybCLKZGuv9MwsO9I | None | None | .//preprocessed/result_3.txt | .txt | dataset | None | 10 | OS6uaBV8J4z1JZdp64ypUg | md5 | None | None | 1 | False | 1 | 1 | 1 | 1 | 2024-07-06 12:50:03.014381+00:00 |
| 14 | xLD04DyWqamAAX93fumO | None | None | .//preprocessed/result_1.txt | .txt | dataset | None | 10 | feNCn_dQUWgtAEtatHVf3A | md5 | None | None | 1 | False | 1 | 1 | 1 | 1 | 2024-07-06 12:50:03.006366+00:00 |
| 13 | VDwnHlJL6Kx91IH32xyd | None | None | .//preprocessed/result_4.txt | .txt | dataset | None | 10 | XkbpIsLBx4kP985_q6ab4A | md5 | None | None | 1 | False | 1 | 1 | 1 | 1 | 2024-07-06 12:50:02.998180+00:00 |
| 12 | jsjI5OSSegQX9FR8EAcJ | None | None | /raw/Collection_2/raw_data_4.txt | .txt | dataset | None | 10 | FQblusptpPTyH1Velq3MAQ | md5 | None | None | 1 | True | 1 | 1 | 1 | 1 | 2024-07-06 12:50:02.931062+00:00 |
| 11 | oKKI92T1MuGlvKSKdyaA | None | None | /raw/Collection_2/raw_data_2.txt | .txt | dataset | None | 10 | ZotSm6FuaJB0jE8yTVsClQ | md5 | None | None | 1 | True | 1 | 1 | 1 | 1 | 2024-07-06 12:50:02.911502+00:00 |
| 10 | m6z8wHij4RJaeY91uGcV | None | None | /raw/Collection_2/raw_data_1.txt | .txt | dataset | None | 10 | hIXyQ97HeeZ4wGYp2ivBTw | md5 | None | None | 1 | True | 1 | 1 | 1 | 1 | 2024-07-06 12:50:02.890911+00:00 |
| 9 | 5z1frkWywntZvIEbXAca | None | None | /raw/Collection_2/raw_data_3.txt | .txt | dataset | None | 10 | -Z8rTVpY8MQDpy3qh7GoGw | md5 | None | None | 1 | True | 1 | 1 | 1 | 1 | 2024-07-06 12:50:02.870391+00:00 |
| 8 | HO0BctC2BS3ez2amjnEp | None | None | /raw/Collection_1/raw_data_4.txt | .txt | dataset | None | 10 | s_e9dYyOYKO_vWe4mA0Xmw | md5 | None | None | 1 | True | 1 | 1 | 1 | 1 | 2024-07-06 12:50:02.850101+00:00 |
| 7 | SVpsqqY3plQcOzULifgw | None | None | /raw/Collection_1/raw_data_2.txt | .txt | dataset | None | 10 | DofkUuR15fScQSuqbg19CQ | md5 | None | None | 1 | True | 1 | 1 | 1 | 1 | 2024-07-06 12:50:02.829513+00:00 |
| 6 | bXUB28jZ3wCdfBJ6lVT1 | None | None | /raw/Collection_1/raw_data_1.txt | .txt | dataset | None | 10 | W57ttx7EnZnnnoheTiSgCA | md5 | None | None | 1 | True | 1 | 1 | 1 | 1 | 2024-07-06 12:50:02.809230+00:00 |
| 5 | Vp9X3C7KWRQ6bKf8GG4y | None | None | /raw/Collection_1/raw_data_3.txt | .txt | dataset | None | 10 | B9II-MP0kKAx4Tn2xtQdOg | md5 | None | None | 1 | True | 1 | 1 | 1 | 1 | 2024-07-06 12:50:02.789646+00:00 |
| 4 | 2YGKR6iekm0cDB2I2loB | None | None | raw/raw_data_3.txt | .txt | dataset | None | 10 | xx57revqfoaM92ty0snjyg | md5 | None | None | 1 | True | 1 | 1 | 1 | 1 | 2024-07-06 12:50:02.769592+00:00 |
| 2 | YXof7jwWOzMiYRVeAlxw | None | None | None | .txt | dataset | None | 10 | HJFjpVT4TShXhWwKcvBEjA | md5 | None | None | 1 | True | 1 | 1 | 1 | 1 | 2024-07-06 12:50:02.748422+00:00 |
| 1 | Yy6SxUpNDlZRTbWzJkll | None | None | None | .txt | dataset | None | 10 | XAl5Qh_riySzWBOb3ExDJg | md5 | None | None | 1 | True | 1 | 1 | 1 | 1 | 2024-07-06 12:50:02.730372+00:00 |
| 3 | gPNt4SYIVVjNXAIF2GVs | None | None | raw/raw_data_3.txt | .txt | dataset | None | 10 | 8X1oiSkx_flg-x8qjT39Uw | md5 | None | None | 1 | True | 1 | 1 | 1 | 1 | 2024-07-06 12:50:02.490162+00:00 |
artifact_from_raw = ln.Artifact.filter(key__icontains="Collection_2/raw_data_1").first()
artifact_from_preprocessed = ln.Artifact.filter(
key__icontains="preprocessed/result_1"
).first()
print(artifact_from_raw.path)
print(artifact_from_preprocessed.path)
/home/runner/work/lamindb/lamindb/docs/faq/key-eval/.lamindb/m6z8wHij4RJaeY91uGcV.txt
/home/runner/work/lamindb/lamindb/docs/faq/key-eval/preprocessed/result_1.txt
Let’s create our Collection:
ds = ln.Collection(
[artifact_from_raw, artifact_from_preprocessed], name="raw_and_processed_collection_2"
)
ds.save()
ds.artifacts.df()
| uid | version | description | key | suffix | type | accessor | size | hash | hash_type | n_objects | n_observations | visibility | key_is_virtual | storage_id | transform_id | run_id | created_by_id | updated_at | |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| id | |||||||||||||||||||
| 10 | m6z8wHij4RJaeY91uGcV | None | None | /raw/Collection_2/raw_data_1.txt | .txt | dataset | None | 10 | hIXyQ97HeeZ4wGYp2ivBTw | md5 | None | None | 1 | True | 1 | 1 | 1 | 1 | 2024-07-06 12:50:02.890911+00:00 |
| 14 | xLD04DyWqamAAX93fumO | None | None | .//preprocessed/result_1.txt | .txt | dataset | None | 10 | feNCn_dQUWgtAEtatHVf3A | md5 | None | None | 1 | False | 1 | 1 | 1 | 1 | 2024-07-06 12:50:03.006366+00:00 |
Modeling directories¶
ln.settings.creation._artifact_use_virtual_keys = True
dir_path = ln.core.datasets.dir_scrnaseq_cellranger("sample_001")
ln.UPath(dir_path).view_tree()
💡 file has more than one suffix (path.suffixes), using only last suffix: '.bai' - if you want your composite suffix to be recognized add it to lamindb.core.storage.VALID_SUFFIXES.add()
3 sub-directories & 15 files with suffixes '.bai', '.tsv.gz', '.mtx.gz', '.cloupe', '.h5', '.html', '.csv', '.bam'
/home/runner/work/lamindb/lamindb/docs/faq/sample_001
├── possorted_genome_bam.bam
├── filtered_feature_bc_matrix.h5
├── metrics_summary.csv
├── filtered_feature_bc_matrix/
│ ├── barcodes.tsv.gz
│ ├── matrix.mtx.gz
│ └── features.tsv.gz
├── possorted_genome_bam.bam.bai
├── analysis/
│ └── analysis.csv
├── raw_feature_bc_matrix/
│ ├── barcodes.tsv.gz
│ ├── matrix.mtx.gz
│ └── features.tsv.gz
├── web_summary.html
├── raw_feature_bc_matrix.h5
├── cloupe.cloupe
└── molecule_info.h5
There are two ways to create Artifact objects from directories: from_dir() and Artifact.
cellranger_raw_artifact = ln.Artifact.from_dir("sample_001/raw_feature_bc_matrix/")
❗ this creates one artifact per file in the directory - you might simply call ln.Artifact(dir) to get one artifact for the entire directory
❗ folder is outside existing storage location, will copy files from sample_001/raw_feature_bc_matrix/ to /home/runner/work/lamindb/lamindb/docs/faq/key-eval/raw_feature_bc_matrix
✅ created 3 artifacts from directory using storage /home/runner/work/lamindb/lamindb/docs/faq/key-eval and key = raw_feature_bc_matrix/
for artifact in cellranger_raw_artifact:
artifact.save()
✅ storing artifact 'AixXSVxCHTN0NdP5HBtp' at '/home/runner/work/lamindb/lamindb/docs/faq/key-eval/.lamindb/AixXSVxCHTN0NdP5HBtp.tsv.gz'
✅ storing artifact 'IscuxPRVx3MTpzuAS9HJ' at '/home/runner/work/lamindb/lamindb/docs/faq/key-eval/.lamindb/IscuxPRVx3MTpzuAS9HJ.mtx.gz'
✅ storing artifact 'DuRYLXyPRBrz20EoYvIx' at '/home/runner/work/lamindb/lamindb/docs/faq/key-eval/.lamindb/DuRYLXyPRBrz20EoYvIx.tsv.gz'
cellranger_raw_folder = ln.Artifact(
"sample_001/raw_feature_bc_matrix/", description="cellranger raw"
)
cellranger_raw_folder.save()
💡 path content will be copied to default storage upon `save()` with key `None` ('.lamindb/miphU6LPBNdgqebS')
✅ storing artifact 'miphU6LPBNdgqebS0hHh' at '/home/runner/work/lamindb/lamindb/docs/faq/key-eval/.lamindb/miphU6LPBNdgqebS'
Artifact(uid='miphU6LPBNdgqebS0hHh', description='cellranger raw', suffix='', type='dataset', size=18, hash='AKVyRkYsZzRAWt_jFLVb1g', hash_type='md5-d', n_objects=3, visibility=1, key_is_virtual=True, created_by_id=1, storage_id=1, transform_id=1, run_id=1, updated_at='2024-07-06 12:50:03 UTC')
ln.Artifact.filter(key__icontains="raw_feature_bc_matrix").df()
| uid | version | description | key | suffix | type | accessor | size | hash | hash_type | n_objects | n_observations | visibility | key_is_virtual | storage_id | transform_id | run_id | created_by_id | updated_at | |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| id | |||||||||||||||||||
| 17 | AixXSVxCHTN0NdP5HBtp | None | None | raw_feature_bc_matrix/barcodes.tsv.gz | .tsv.gz | dataset | None | 6 | hyjdELWvO7Rifj-H1K9P-w | md5 | None | None | 1 | True | 1 | 1 | 1 | 1 | 2024-07-06 12:50:03.153445+00:00 |
| 18 | IscuxPRVx3MTpzuAS9HJ | None | None | raw_feature_bc_matrix/matrix.mtx.gz | .mtx.gz | dataset | None | 6 | dYd1PgtlEHndix-z0Vey5A | md5 | None | None | 1 | True | 1 | 1 | 1 | 1 | 2024-07-06 12:50:03.157545+00:00 |
| 19 | DuRYLXyPRBrz20EoYvIx | None | None | raw_feature_bc_matrix/features.tsv.gz | .tsv.gz | dataset | None | 6 | 9PNxupejEH1EICD0x-HU5A | md5 | None | None | 1 | True | 1 | 1 | 1 | 1 | 2024-07-06 12:50:03.161209+00:00 |
ln.Artifact.filter(key__icontains="raw_feature_bc_matrix/matrix.mtx.gz").one().path
PosixUPath('/home/runner/work/lamindb/lamindb/docs/faq/key-eval/.lamindb/IscuxPRVx3MTpzuAS9HJ.mtx.gz')
artifact = ln.Artifact.filter(description="cellranger raw").one()
artifact.path.glob("*")
<generator object Path.glob at 0x7f222531c480>