lamindb 1.9.1__py3-none-any.whl → 1.10.0__py3-none-any.whl

lamindb/migrations/0116_remove_artifact_unique_artifact_storage_key_hash_and_more.py

@@ -0,0 +1,51 @@
+# Generated by Django 5.2 on 2025-07-26 15:55
+
+from django.db import migrations, models
+
+import lamindb.base.fields
+
+
+class Migration(migrations.Migration):
+    dependencies = [
+        ("lamindb", "0115_alter_space_uid"),
+    ]
+
+    operations = [
+        migrations.RemoveConstraint(
+            model_name="artifact",
+            name="unique_artifact_storage_key_hash",
+        ),
+        migrations.AlterField(
+            model_name="record",
+            name="description",
+            field=lamindb.base.fields.CharField(
+                blank=True, db_index=True, default=None, max_length=255, null=True
+            ),
+        ),
+        migrations.AlterField(
+            model_name="reference",
+            name="text",
+            field=lamindb.base.fields.TextField(
+                blank=True, db_index=True, default=None, null=True
+            ),
+        ),
+        migrations.AlterField(
+            model_name="reference",
+            name="url",
+            field=lamindb.base.fields.URLField(blank=True, db_index=True, null=True),
+        ),
+        migrations.AlterField(
+            model_name="run",
+            name="name",
+            field=lamindb.base.fields.CharField(
+                blank=True, db_index=True, default=None, max_length=150, null=True
+            ),
+        ),
+        migrations.AddConstraint(
+            model_name="artifact",
+            constraint=models.UniqueConstraint(
+                fields=("storage", "key", "hash"),
+                name="unique_artifact_storage_key_hash",
+            ),
+        ),
+    ]

lamindb/migrations/0117_fix_artifact_storage_hash_unique_constraints.py

@@ -0,0 +1,32 @@
+# Generated by Django 5.2 on 2025-07-26 18:50
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+    dependencies = [
+        ("lamindb", "0116_remove_artifact_unique_artifact_storage_key_hash_and_more"),
+    ]
+
+    operations = [
+        migrations.RemoveConstraint(
+            model_name="artifact",
+            name="unique_artifact_storage_key_hash",
+        ),
+        migrations.AddConstraint(
+            model_name="artifact",
+            constraint=models.UniqueConstraint(
+                condition=models.Q(("key__isnull", False)),
+                fields=("storage", "key", "hash"),
+                name="unique_artifact_storage_key_hash_not_null",
+            ),
+        ),
+        migrations.AddConstraint(
+            model_name="artifact",
+            constraint=models.UniqueConstraint(
+                condition=models.Q(("key__isnull", True)),
+                fields=("storage", "hash"),
+                name="unique_artifact_storage_hash_null_key",
+            ),
+        ),
+    ]

lamindb/migrations/{0115_squashed.py → 0117_squashed.py}

@@ -1,4 +1,4 @@
-# Generated by Django 5.2 on 2025-07-06 09:12
+# Generated by Django 5.2 on 2025-07-26 18:58
 
 import django.core.validators
 import django.db.models.deletion
@@ -137,6 +137,8 @@ class Migration(migrations.Migration):
         ("lamindb", "0113_lower_case_branch_and_space_names"),
         ("lamindb", "0114_alter_run__status_code"),
         ("lamindb", "0115_alter_space_uid"),
+        ("lamindb", "0116_remove_artifact_unique_artifact_storage_key_hash_and_more"),
+        ("lamindb", "0117_fix_artifact_storage_hash_unique_constraints"),
     ]
 
     dependencies = []  # type: ignore
@@ -1477,7 +1479,11 @@ class Migration(migrations.Migration):
                 (
                     "description",
                     lamindb.base.fields.CharField(
-                        blank=True, default=None, max_length=255, null=True
+                        blank=True,
+                        db_index=True,
+                        default=None,
+                        max_length=255,
+                        null=True,
                     ),
                 ),
                 (
@@ -1825,7 +1831,10 @@ class Migration(migrations.Migration):
                         null=True,
                     ),
                 ),
-                ("url", lamindb.base.fields.URLField(blank=True, null=True)),
+                (
+                    "url",
+                    lamindb.base.fields.URLField(blank=True, db_index=True, null=True),
+                ),
                 (
                     "pubmed_id",
                     lamindb.base.fields.BigIntegerField(
@@ -1860,7 +1869,9 @@ class Migration(migrations.Migration):
                 ),
                 (
                     "text",
-                    lamindb.base.fields.TextField(blank=True, default=None, null=True),
+                    lamindb.base.fields.TextField(
+                        blank=True, db_index=True, default=None, null=True
+                    ),
                 ),
                 (
                     "date",
@@ -1989,7 +2000,11 @@ class Migration(migrations.Migration):
                 (
                     "name",
                     lamindb.base.fields.CharField(
-                        blank=True, default=None, max_length=150, null=True
+                        blank=True,
+                        db_index=True,
+                        default=None,
+                        max_length=150,
+                        null=True,
                     ),
                 ),
                 (
@@ -4472,7 +4487,15 @@ class Migration(migrations.Migration):
             constraint=models.UniqueConstraint(
                 condition=models.Q(("key__isnull", False)),
                 fields=("storage", "key", "hash"),
-                name="unique_artifact_storage_key_hash",
+                name="unique_artifact_storage_key_hash_not_null",
+            ),
+        ),
+        migrations.AddConstraint(
+            model_name="artifact",
+            constraint=models.UniqueConstraint(
+                condition=models.Q(("key__isnull", True)),
+                fields=("storage", "hash"),
+                name="unique_artifact_storage_hash_null_key",
             ),
         ),
     ]

lamindb/models/_describe.py

@@ -179,7 +179,7 @@ def describe_artifact_general(
     two_column_items.append(Text.assemble(("branch: ", "dim"), branch_name))
     # actually not name field here, but handle
     created_by_handle = (
-        foreign_key_data["branch"]["name"]
+        foreign_key_data["created_by"]["name"]
         if foreign_key_data
         else self.created_by.handle
     )
@@ -234,3 +234,109 @@ def describe_artifact_general(
         )
     )
     return tree
+
+
+def describe_collection_general(
+    self: Collection,
+    tree: Tree | None = None,
+    foreign_key_data: dict[str, dict[str, int | str]] | None = None,
+) -> Tree:
+    if tree is None:
+        tree = describe_header(self)
+
+    # add general information (order is the same as in API docs)
+    general = tree.add(Text("General", style="bold bright_cyan"))
+
+    if self.key:
+        general.add(Text.assemble(("key: ", "dim"), (f"{self.key}", "cyan3")))
+    if self.description:
+        general.add(
+            Text.assemble(
+                ("description: ", "dim"),
+                f"{self.description}",
+            )
+        )
+
+    # Two column items (short content)
+    two_column_items = []
+
+    two_column_items.append(Text.assemble(("uid: ", "dim"), f"{self.uid}"))
+
+    transform_name = (
+        foreign_key_data["transform"]["name"]
+        if foreign_key_data and "transform" in foreign_key_data
+        else self.transform.name
+        if self.transform
+        else None
+    )
+    if transform_name:
+        two_column_items.append(
+            Text.assemble(
+                ("transform: ", "dim"),
+                (f"{transform_name}", "cyan3"),
+            )
+        )
+
+    space_name = (
+        foreign_key_data["space"]["name"]
+        if foreign_key_data and "space" in foreign_key_data
+        else self.space.name
+        if self.space
+        else None
+    )
+    if space_name:
+        two_column_items.append(Text.assemble(("space: ", "dim"), space_name))
+
+    branch_name = (
+        foreign_key_data["branch"]["name"]
+        if foreign_key_data and "branch" in foreign_key_data
+        else self.branch.name
+        if self.branch
+        else None
+    )
+    if branch_name:
+        two_column_items.append(Text.assemble(("branch: ", "dim"), branch_name))
+
+    created_by_handle = (
+        foreign_key_data["created_by"]["name"]
+        if foreign_key_data and "created_by" in foreign_key_data
+        else self.created_by.handle
+        if self.created_by
+        else None
+    )
+    if created_by_handle:
+        two_column_items.append(
+            Text.assemble(
+                ("created_by: ", "dim"),
+                (created_by_handle),
+            )
+        )
+
+    if self.created_at:
+        two_column_items.append(
+            Text.assemble(("created_at: ", "dim"), highlight_time(str(self.created_at)))
+        )
+
+    if self.version:
+        two_column_items.append(Text.assemble(("version: ", "dim"), f"{self.version}"))
+
+    # Add two-column items in pairs
+    for i in range(0, len(two_column_items), 2):
+        if i + 1 < len(two_column_items):
+            # Two items side by side
+            left_item = two_column_items[i]
+            right_item = two_column_items[i + 1]
+
+            # Create padded version by calculating the plain text length
+            left_plain_text = (
+                left_item.plain if hasattr(left_item, "plain") else str(left_item)
+            )
+            padding_needed = max(0, 45 - len(left_plain_text))
+            padding = " " * padding_needed
+
+            general.add(Text.assemble(left_item, padding, right_item))
+        else:
+            # Single item (odd number)
+            general.add(two_column_items[i])
+
+    return tree

lamindb/models/_django.py

@@ -1,6 +1,6 @@
 from __future__ import annotations
 
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Any
 
 from django.contrib.postgres.aggregates import ArrayAgg
 from django.db import connection
@@ -13,8 +13,7 @@ from ._relations import dict_related_model_to_related_name, get_schema_modules
 from .schema import Schema
 
 if TYPE_CHECKING:
-    from .artifact import Artifact
-    from .sqlrecord import SQLRecord
+    from .artifact import Artifact, Collection
 
 
 def patch_many_to_many_descriptor() -> None:
@@ -32,7 +31,8 @@ def patch_many_to_many_descriptor() -> None:
     def patched_get(self, instance, cls=None):
         if instance is not None and instance.pk is None:
             raise ValueError(
-                f"You are trying to access the many-to-many relationships of an unsaved {instance.__class__.__name__} object. Please save it first using '.save()'."
+                f"You are trying to access the many-to-many relationships of an unsaved {instance.__class__.__name__} object. "
+                f"Please save it first using '.save()'."
             )
 
         manager = original_get(self, instance, cls)
@@ -77,12 +77,12 @@ def get_related_model(model, field_name):
 
 
 def get_artifact_with_related(
-    artifact: SQLRecord,
+    artifact: Artifact,
     include_fk: bool = False,
     include_m2m: bool = False,
     include_feature_link: bool = False,
     include_schema: bool = False,
-) -> dict:
+) -> dict[str, Any]:
     """Fetch an artifact with its related data."""
     from ._label_manager import EXCLUDE_LABELS
     from .can_curate import get_name_field
@@ -234,6 +234,63 @@ def get_artifact_with_related(
     }
 
 
+def get_collection_with_related(
+    collection: Collection,
+    include_fk: bool = False,
+) -> dict[str, Any]:
+    """Fetch a collection with its related data."""
+    from .can_curate import get_name_field
+
+    model = collection.__class__
+    schema_modules = get_schema_modules(collection._state.db)
+
+    foreign_key_fields = [
+        f.name
+        for f in model._meta.fields
+        if f.is_relation and f.related_model.__get_module_name__() in schema_modules
+    ]
+
+    # Clear previous queries
+    connection.queries_log.clear()
+
+    annotations = {}
+
+    if include_fk:
+        for fk in foreign_key_fields:
+            name_field = get_name_field(get_related_model(model, fk))
+            if fk == "run":
+                annotations[f"fkfield_{fk}"] = JSONObject(
+                    id=F(f"{fk}__id"),
+                    name=F(f"{fk}__{name_field}"),
+                    transform_key=F(f"{fk}__transform__key"),
+                )
+            else:
+                annotations[f"fkfield_{fk}"] = JSONObject(
+                    id=F(f"{fk}__id"), name=F(f"{fk}__{name_field}")
+                )
+
+    collection_meta = (
+        model.objects.using(collection._state.db)
+        .filter(uid=collection.uid)
+        .annotate(**annotations)
+        .values(*["id", "uid"], *annotations.keys())
+        .first()
+    )
+
+    if not collection_meta:
+        return None
+
+    related_data: dict = {"fk": {}}
+    for k, v in collection_meta.items():
+        if k.startswith("fkfield_") and v is not None:
+            related_data["fk"][k[8:]] = v
+
+    return {
+        **{name: collection_meta[name] for name in ["id", "uid"]},
+        "related_data": related_data,
+    }
+
+
 def get_schema_m2m_relations(artifact: Artifact, slot_schema: dict, limit: int = 20):
     """Fetch all many-to-many relationships for given feature sets."""
     from .can_curate import get_name_field

lamindb/models/_feature_manager.py

@@ -969,7 +969,6 @@ class FeatureManager:
                         }
                     else:
                         result = parse_dtype(feature.dtype)[0]
-                        print(result["field"])
                     validated = result["registry"].validate(  # type: ignore
                         values, field=result["field"], mute=True
                     )

lamindb/models/artifact.py

@@ -67,7 +67,7 @@ from ..errors import IntegrityError, InvalidArgument, ValidationError
 from ..models._is_versioned import (
     create_uid,
 )
-from ._django import get_artifact_with_related
+from ._django import get_artifact_with_related, get_collection_with_related
 from ._feature_manager import (
     FeatureManager,
     filter_base,
@@ -117,7 +117,11 @@ if TYPE_CHECKING:
     from tiledbsoma import Measurement as SOMAMeasurement
 
     from lamindb.base.types import StrField
-    from lamindb.core.storage._backed_access import AnnDataAccessor, BackedAccessor
+    from lamindb.core.storage._backed_access import (
+        AnnDataAccessor,
+        BackedAccessor,
+        SpatialDataAccessor,
+    )
     from lamindb.core.types import ScverseDataStructures
 
     from ..base.types import (
@@ -709,7 +713,11 @@ def save_schema_links(self: Artifact) -> None:
 
 
 def _describe_postgres(self):  # for Artifact & Collection
-    from ._describe import describe_artifact_general, describe_header
+    from ._describe import (
+        describe_artifact_general,
+        describe_collection_general,
+        describe_header,
+    )
     from ._feature_manager import describe_features
 
     model_name = self.__class__.__name__
@@ -737,13 +745,23 @@ def _describe_postgres(self):  # for Artifact & Collection
             related_data=related_data,
             with_labels=True,
         )
+    elif model_name == "Collection":
+        result = get_collection_with_related(self, include_fk=True)
+        tree = describe_collection_general(
+            self, foreign_key_data=related_data.get("fk", {})
+        )
+        return tree
     else:
         tree = describe_header(self)
         return tree
 
 
 def _describe_sqlite(self, print_types: bool = False):  # for artifact & collection
-    from ._describe import describe_artifact_general, describe_header
+    from ._describe import (
+        describe_artifact_general,
+        describe_collection_general,
+        describe_header,
+    )
     from ._feature_manager import describe_features
     from .collection import Collection
 
@@ -786,6 +804,9 @@ def _describe_sqlite(self, print_types: bool = False):  # for artifact & collect
             tree=tree,
             with_labels=True,
         )
+    elif model_name == "Collection":
+        tree = describe_collection_general(self)
+        return tree
     else:
         tree = describe_header(self)
         return tree
@@ -983,7 +1004,7 @@ class Artifact(SQLRecord, IsVersioned, TracksRun, TracksUpdates):
 
     Args:
         data: `UPathStr` A path to a local or remote folder or file.
-        kind: `Literal["dataset", "model"] | None = None` Distinguish models from datasets from other files & folders.
+        kind: `Literal["dataset", "model"] | str | None = None` Distinguish models from datasets from other files & folders.
         key: `str | None = None` A path-like key to reference artifact in default storage, e.g., `"myfolder/myfile.fcs"`. Artifacts with the same key form a version family.
         description: `str | None = None` A description.
         revises: `Artifact | None = None` Previous version of the artifact. Is an alternative way to passing `key` to trigger a new version.
@@ -1095,11 +1116,19 @@ class Artifact(SQLRecord, IsVersioned, TracksRun, TracksUpdates):
             # folders
             # the conditional composite constraint allows duplicating files in different parts of the
             # file hierarchy, but errors if the same file is to be registered with the same key
-            # or if the key is not populated
+            # In SQL, NULL values are treated specially in unique constraints.
+            # Multiple NULL values are not considered equal to each other for uniqueness purposes.
+            # For non-NULL keys
             models.UniqueConstraint(
                 fields=["storage", "key", "hash"],
-                name="unique_artifact_storage_key_hash",
-                condition=Q(key__isnull=False),
+                condition=models.Q(key__isnull=False),
+                name="unique_artifact_storage_key_hash_not_null",
+            ),
+            # For NULL keys (only storage + hash need to be unique)
+            models.UniqueConstraint(
+                fields=["storage", "hash"],
+                condition=models.Q(key__isnull=True),
+                name="unique_artifact_storage_hash_null_key",
             ),
         ]
 
@@ -1209,12 +1238,12 @@ class Artifact(SQLRecord, IsVersioned, TracksRun, TracksUpdates):
 
     This is either a file suffix (`".csv"`, `".h5ad"`, etc.) or the empty string "".
     """
-    kind: ArtifactKind | None = CharField(
+    kind: ArtifactKind | str | None = CharField(
         max_length=20,
         db_index=True,
         null=True,
     )
-    """:class:`~lamindb.base.types.ArtifactKind` (default `None`)."""
+    """:class:`~lamindb.base.types.ArtifactKind` or custom `str` value (default `None`)."""
     otype: str | None = CharField(
         max_length=64, db_index=True, null=True, editable=False
     )
@@ -1327,7 +1356,7 @@ class Artifact(SQLRecord, IsVersioned, TracksRun, TracksUpdates):
         # here; and we might refactor this but we might also keep that internal
         # usage
         data: UPathStr,
-        kind: ArtifactKind | None = None,
+        kind: ArtifactKind | str | None = None,
         key: str | None = None,
         description: str | None = None,
         revises: Artifact | None = None,
@@ -2246,6 +2275,7 @@ class Artifact(SQLRecord, IsVersioned, TracksRun, TracksUpdates):
         **kwargs,
     ) -> (
         AnnDataAccessor
+        | SpatialDataAccessor
         | BackedAccessor
         | SOMACollection
         | SOMAExperiment

lamindb/models/collection.py

@@ -1,12 +1,7 @@
 from __future__ import annotations
 
 import warnings
-from typing import (
-    TYPE_CHECKING,
-    Any,
-    Literal,
-    overload,
-)
+from typing import TYPE_CHECKING, Any, Literal, overload
 
 import anndata as ad
 import pandas as pd
@@ -132,7 +127,7 @@ class Collection(SQLRecord, IsVersioned, TracksRun, TracksUpdates):
     """Versioned collections of artifacts.
 
     Args:
-        artifacts: `list[Artifact]` A list of artifacts.
+        artifacts: `Artifact | list[Artifact]` One or several artifacts.
         key: `str` A file-path like key, analogous to the `key` parameter of `Artifact` and `Transform`.
         description: `str | None = None` A description.
         revises: `Collection | None = None` An old version of the collection.
@@ -232,7 +227,7 @@ class Collection(SQLRecord, IsVersioned, TracksRun, TracksUpdates):
     @overload
     def __init__(
         self,
-        artifacts: list[Artifact],
+        artifacts: Artifact | list[Artifact],
         key: str,
         description: str | None = None,
         meta: Any | None = None,
@@ -259,7 +254,7 @@ class Collection(SQLRecord, IsVersioned, TracksRun, TracksUpdates):
         # now we proceed with the user-facing constructor
         if len(args) > 1:
             raise ValueError("Only one non-keyword arg allowed: artifacts")
-        artifacts: Artifact | Iterable[Artifact] = (
+        artifacts: Artifact | list[Artifact] = (
             kwargs.pop("artifacts") if len(args) == 0 else args[0]
         )
         meta_artifact: Artifact | None = kwargs.pop("meta_artifact", None)

lamindb/models/project.py

@@ -133,7 +133,7 @@ class Reference(SQLRecord, CanCurate, TracksRun, TracksUpdates, ValidateFields):
         null=True,
     )
     """An abbreviation for the reference."""
-    url: str | None = URLField(null=True)
+    url: str | None = URLField(null=True, db_index=True)
     """URL linking to the reference."""
     pubmed_id: int | None = BigIntegerField(null=True, db_index=True)
     """A PudMmed ID."""
@@ -150,7 +150,7 @@ class Reference(SQLRecord, CanCurate, TracksRun, TracksUpdates, ValidateFields):
     """Digital Object Identifier (DOI) for the reference."""
     description: str | None = CharField(null=True, db_index=True)
     """Description of the reference."""
-    text: str | None = TextField(null=True)
+    text: str | None = TextField(null=True, db_index=True)
     """Abstract or full text of the reference to make it searchable."""
     date: DateType | None = DateField(null=True, default=None)
     """Date of creation or publication of the reference."""

lamindb/models/record.py

@@ -93,7 +93,7 @@ class Record(SQLRecord, CanCurate, TracksRun, TracksUpdates):
     """Record-like components of this record."""
     composites: Record
     """Record-like composites of this record."""
-    description: str | None = CharField(null=True)
+    description: str | None = CharField(null=True, db_index=True)
     """A description (optional)."""
     linked_artifacts: Artifact = models.ManyToManyField(
         Artifact, through="RecordArtifact", related_name="linked_in_records"

lamindb/models/run.py

@@ -232,7 +232,7 @@ class Run(SQLRecord):
         editable=False, unique=True, db_index=True, max_length=20, default=base62_16
     )
     """Universal id, valid across DB instances."""
-    name: str | None = CharField(max_length=150, null=True)
+    name: str | None = CharField(max_length=150, null=True, db_index=True)
     """A name."""
     transform: Transform = ForeignKey("Transform", CASCADE, related_name="runs")
     """The transform :class:`~lamindb.Transform` that is being run."""

lamindb/models/sqlrecord.py

@@ -1764,6 +1764,9 @@ def record_repr(
         field_names.insert(0, "uid")
     fields_str = {}
     for k in field_names:
+        if k == "n" and getattr(self, k) < 0:
+            # only needed for Schema
+            continue
         if not k.startswith("_") and hasattr(self, k):
             value = getattr(self, k)
             # Force strip the time component of the version

{lamindb-1.9.1.dist-info → lamindb-1.10.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: lamindb
-Version: 1.9.1
+Version: 1.10.0
 Summary: A data framework for biology.
 Author-email: Lamin Labs <open-source@lamin.ai>
 Requires-Python: >=3.10,<3.14
@@ -10,8 +10,8 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Requires-Dist: lamin_utils==0.15.0
-Requires-Dist: lamin_cli==1.6.0
-Requires-Dist: lamindb_setup[aws]==1.8.3
+Requires-Dist: lamin_cli==1.6.1
+Requires-Dist: lamindb_setup[aws]==1.9.0
 Requires-Dist: pyyaml
 Requires-Dist: pyarrow
 Requires-Dist: pandera>=0.24.0