lightly-studio 0.3.1__py3-none-any.whl → 0.3.2__py3-none-any.whl

lightly_studio/examples/example_metadata.py

@@ -16,14 +16,11 @@ from uuid import UUID
 from environs import Env
 from sqlmodel import Session
 
-from lightly_studio import DatasetLoader
-from lightly_studio.api.db import db_manager
+import lightly_studio as ls
+from lightly_studio import db_manager
+from lightly_studio.core.sample import Sample
 from lightly_studio.metadata.gps_coordinate import GPSCoordinate
-from lightly_studio.models.dataset import DatasetTable
-from lightly_studio.resolvers import (
-    metadata_resolver,
-    sample_resolver,
-)
+from lightly_studio.resolvers import metadata_resolver
 from lightly_studio.resolvers.metadata_resolver.metadata_filter import Metadata
 from lightly_studio.resolvers.samples_filter import SampleFilter
 
@@ -34,25 +31,24 @@ dataset_path = env.path("DATASET_PATH", "/path/to/your/yolo/dataset/data.yaml")
 LIGHTLY_STUDIO_DATASET_SPLIT = env.str("LIGHTLY_STUDIO_DATASET_SPLIT", "test")
 
 
-def load_existing_dataset() -> tuple[DatasetTable, list[UUID], DatasetLoader]:
+def load_existing_dataset() -> tuple[ls.Dataset, list[Sample]]:
     """Load an existing dataset using DatasetLoader.
 
     Returns:
-        Tuple of (dataset, sample_ids, loader).
+        Tuple of (dataset, samples).
     """
     print(" Loading existing dataset...")
 
-    loader = DatasetLoader()
-    dataset = loader.from_yolo(
-        str(dataset_path),
+    dataset = ls.Dataset.create()
+    dataset.add_samples_from_yolo(
+        data_yaml=str(dataset_path),
         input_split=LIGHTLY_STUDIO_DATASET_SPLIT,
     )
-    # Get all sample IDs from the dataset
-    samples = dataset.get_samples()
-    sample_ids = [s.sample_id for s in samples]
+    # Get all samples from the dataset
+    samples = dataset.query().to_list()
 
-    print(f"✅ Loaded dataset with {len(sample_ids)} samples")
-    return dataset, sample_ids, loader
+    print(f"✅ Loaded dataset with {len(samples)} samples")
+    return dataset, samples
 
 
 def add_bulk_metadata(session: Session, sample_ids: list[UUID]) -> None:
@@ -93,56 +89,38 @@ def add_bulk_metadata(session: Session, sample_ids: list[UUID]) -> None:
     print(f"✅ Added metadata to {len(sample_ids)} samples in {elapsed_time:.2f}s")
 
 
-def add_individual_metadata(session: Session, sample_ids: list[UUID]) -> None:
+def add_individual_metadata(samples: list[Sample]) -> None:
     """Add metadata to individual samples."""
     print("\n Adding individual metadata to specific samples...")
 
     # Add metadata to first 5 samples individually
-    for i, sample_id in enumerate(sample_ids[:5]):
+    for i, sample in enumerate(samples[:5]):
+        print(f" Adding metadata to sample {sample.file_name} {sample.sample_id}...")
         # Add some specific metadata
-        metadata_resolver.set_value_for_sample(
-            session=session,
-            sample_id=sample_id,
-            key="special_metadata",
-            value=f"sample_{i + 1}_special",
+        sample.metadata["special_metadata"] = f"sample_{i + 1}_special"
+        sample.metadata["priority"] = random.randint(1, 10)
+        sample.metadata["list"] = [1, 2, 3]
+        sample.metadata["custom_gps"] = GPSCoordinate(
+            lat=40.7128 + i * 0.1,  # Slightly different coordinates
+            lon=-74.0060 + i * 0.1,
         )
 
-        metadata_resolver.set_value_for_sample(
-            session=session,
-            sample_id=sample_id,
-            key="priority",
-            value=random.randint(1, 10),
-        )
-
-        metadata_resolver.set_value_for_sample(
-            session=session,
-            sample_id=sample_id,
-            key="list",
-            value=[1, 2, 3],
-        )
-
-        metadata_resolver.set_value_for_sample(
-            session=session,
-            sample_id=sample_id,
-            key="custom_gps",
-            value=GPSCoordinate(
-                lat=40.7128 + i * 0.1,  # Slightly different coordinates
-                lon=-74.0060 + i * 0.1,
-            ),
-        )
+    print(f"✅ Added individual metadata to {min(5, len(samples))} samples")
 
-    print(f"✅ Added individual metadata to {min(5, len(sample_ids))} samples")
 
-
-def demonstrate_bulk_metadata_filters(dataset: DatasetTable) -> None:
+def demonstrate_bulk_metadata_filters(dataset: ls.Dataset) -> None:
     """Demonstrate filtering with bulk-added metadata."""
+    # TODO(Michal, 09/2025): Update with native metadata filtering instead of accessing
+    # `dataset._inner` when implemented.
+    dataset_table = dataset._inner  # noqa: SLF001
+
     print("\n Bulk Metadata Filters:")
     print("=" * 50)
 
     # Filter by temperature
     print("\n1. Filter by temperature > 25:")
     filter_temp = SampleFilter(metadata_filters=[Metadata("temperature") > 25])  # noqa PLR2004
-    samples = dataset.get_samples(filters=filter_temp)
+    samples = dataset_table.get_samples(filters=filter_temp)
     print(f"   Found {len(samples)} samples with temperature > 25")
     for sample in samples[:3]:  # Show first 3
         print(f" {sample.file_name}: {sample['temperature']}")
@@ -150,7 +128,7 @@ def demonstrate_bulk_metadata_filters(dataset: DatasetTable) -> None:
     # Filter by location
     print("\n2. Filter by location == 'city':")
     filter_location = SampleFilter(metadata_filters=[Metadata("location") == "city"])
-    samples = dataset.get_samples(filters=filter_location)
+    samples = dataset_table.get_samples(filters=filter_location)
     print(f"   Found {len(samples)} samples from cities")
     for sample in samples[:3]:  # Show first 3
         print(f" {sample.file_name}: {sample['location']}")
@@ -158,7 +136,7 @@ def demonstrate_bulk_metadata_filters(dataset: DatasetTable) -> None:
     # Filter by GPS coordinates
     print("\n3. Filter by latitude > 0° (Northern hemisphere):")
     filter_lat = SampleFilter(metadata_filters=[Metadata("gps_coordinates.lat") > 0])
-    samples = dataset.get_samples(filters=filter_lat)
+    samples = dataset_table.get_samples(filters=filter_lat)
     print(f"   Found {len(samples)} samples in Northern hemisphere")
     for sample in samples[:3]:  # Show first 3
         gps = sample["gps_coordinates"]
@@ -169,14 +147,18 @@ def demonstrate_bulk_metadata_filters(dataset: DatasetTable) -> None:
     filter_confidence = SampleFilter(
         metadata_filters=[Metadata("confidence") > 0.9]  # noqa PLR2004
     )
-    samples = dataset.get_samples(filters=filter_confidence)
+    samples = dataset_table.get_samples(filters=filter_confidence)
     print(f"   Found {len(samples)} samples with confidence > 0.9")
     for sample in samples[:3]:  # Show first 3
         print(f"   📸 {sample.file_name}: confidence={sample['confidence']:.3f}")
 
 
-def demonstrate_individual_metadata_filters(dataset: DatasetTable) -> None:
+def demonstrate_individual_metadata_filters(dataset: ls.Dataset) -> None:
     """Demonstrate filtering with individually-added metadata."""
+    # TODO(Michal, 09/2025): Update with native metadata filtering instead of accessing
+    # `dataset._inner` when implemented.
+    dataset_table = dataset._inner  # noqa: SLF001
+
     print("\n Individual Metadata Filters:")
     print("=" * 50)
 
@@ -185,7 +167,7 @@ def demonstrate_individual_metadata_filters(dataset: DatasetTable) -> None:
     filter_special = SampleFilter(
         metadata_filters=[Metadata("special_metadata") == "sample_1_special"]
     )
-    samples = dataset.get_samples(filters=filter_special)
+    samples = dataset_table.get_samples(filters=filter_special)
     print(f"   Found {len(samples)} samples with special metadata")
     for sample in samples:
         print(f" {sample.file_name}: {sample['special_metadata']}")
@@ -193,7 +175,7 @@ def demonstrate_individual_metadata_filters(dataset: DatasetTable) -> None:
     # Filter by priority
     print("\n2. Filter by high priority (> 7):")
     filter_priority = SampleFilter(metadata_filters=[Metadata("priority") > 7])  # noqa PLR2004
-    samples = dataset.get_samples(filters=filter_priority)
+    samples = dataset_table.get_samples(filters=filter_priority)
     print(f"   Found {len(samples)} samples with priority > 7")
     for sample in samples:
         print(f" {sample.file_name}: priority={sample['priority']}")
@@ -203,15 +185,19 @@ def demonstrate_individual_metadata_filters(dataset: DatasetTable) -> None:
     filter_custom_gps = SampleFilter(
         metadata_filters=[Metadata("custom_gps.lat") > 40.8]  # noqa PLR2004
     )
-    samples = dataset.get_samples(filters=filter_custom_gps)
+    samples = dataset_table.get_samples(filters=filter_custom_gps)
     print(f"   Found {len(samples)} samples with custom GPS lat > 40.8")
     for sample in samples:
         gps = sample["custom_gps"]
         print(f" {sample.file_name}: lat={gps.lat:.4f}, lon={gps.lon:.4f}")
 
 
-def demonstrate_combined_filters(dataset: DatasetTable) -> None:
+def demonstrate_combined_filters(dataset: ls.Dataset) -> None:
     """Demonstrate combining multiple filters."""
+    # TODO(Michal, 09/2025): Update with native metadata filtering instead of accessing
+    # `dataset._inner` when implemented.
+    dataset_table = dataset._inner  # noqa: SLF001
+
     print("\n Combined Filters:")
     print("=" * 50)
 
@@ -224,7 +210,7 @@ def demonstrate_combined_filters(dataset: DatasetTable) -> None:
             Metadata("temperature") > 25,  # noqa PLR2004
         ]
     )
-    samples = dataset.get_samples(filters=filter_combined)
+    samples = dataset_table.get_samples(filters=filter_combined)
     print(f"   Found {len(samples)} samples matching all criteria")
     for sample in samples[:3]:
         print(
@@ -241,64 +227,64 @@ def demonstrate_combined_filters(dataset: DatasetTable) -> None:
             Metadata("location") == "city",
         ]
     )
-    samples = dataset.get_samples(filters=filter_gps_combined)
+    samples = dataset_table.get_samples(filters=filter_gps_combined)
     print(f"   Found {len(samples)} samples in northern hemisphere cities with high confidence")
     for sample in samples[:3]:
         gps = sample["gps_coordinates"]
         print(f" {sample.file_name}: lat={gps.lat:.4f}, conf={sample['confidence']:.2f}")
 
 
-def demonstrate_dictionary_like_access(session: Session, sample_ids: list[UUID]) -> None:
+def demonstrate_dictionary_like_access(samples: list[Sample]) -> None:
     """Demonstrate adding metadata using dictionary-like access."""
     print("\n Dictionary-like Metadata Access:")
     print("=" * 50)
 
     # Get the first few samples to demonstrate
-    samples = sample_resolver.get_many_by_id(session, sample_ids[:2])
+    samples = samples[:2]
 
-    print("\n1. Adding metadata using sample['key'] = value syntax:")
+    print("\n1. Adding metadata using sample.metadata['key'] = value syntax:")
 
     # Add different types of metadata to different samples
-    samples[0]["temperature"] = 25
-    samples[0]["location"] = "city"
-    samples[0]["is_processed"] = True
-    samples[0]["confidence"] = 0.95
+    samples[0].metadata["temperature"] = 25
+    samples[0].metadata["location"] = "city"
+    samples[0].metadata["is_processed"] = True
+    samples[0].metadata["confidence"] = 0.95
     print(
-        f" {samples[0].file_name}: temp={samples[0]['temperature']}°C, "
-        f"location={samples[0]['location']},"
-        f" processed={samples[0]['is_processed']}"
+        f" {samples[0].file_name}: temp={samples[0].metadata['temperature']}°C, "
+        f"location={samples[0].metadata['location']},"
+        f" processed={samples[0].metadata['is_processed']}"
     )
 
-    samples[1]["temperature"] = 15
-    samples[1]["location"] = "mountain"
-    samples[1]["gps_coordinates"] = GPSCoordinate(lat=40.7128, lon=-74.0060)
-    samples[1]["tags"] = ["outdoor", "nature", "landscape"]
+    samples[1].metadata["temperature"] = 15
+    samples[1].metadata["location"] = "mountain"
+    samples[1].metadata["gps_coordinates"] = GPSCoordinate(lat=40.7128, lon=-74.0060)
+    samples[1].metadata["tags"] = ["outdoor", "nature", "landscape"]
     print(
-        f" {samples[1].file_name}: temp={samples[1]['temperature']}°C, "
-        f"location={samples[1]['location']}, tags={samples[1]['tags']}"
+        f" {samples[1].file_name}: temp={samples[1].metadata['temperature']}°C, "
+        f"location={samples[1].metadata['location']}, tags={samples[1].metadata['tags']}"
     )
 
     # Demonstrate reading metadata
-    print("\n2. Reading metadata using sample['key'] syntax:")
+    print("\n2. Reading metadata using sample.metadata['key'] syntax:")
     for sample in samples:
         print(f" {sample.file_name}:")
-        print(f"      Temperature: {sample['temperature']}°C")
-        print(f"      Location: {sample['location']}")
-        gps = sample["gps_coordinates"]
+        print(f"      Temperature: {sample.metadata['temperature']}°C")
+        print(f"      Location: {sample.metadata['location']}")
+        gps = sample.metadata["gps_coordinates"]
         print(f"      GPS: lat={gps.lat:.4f}, lon={gps.lon:.4f}")
-        print(f"      Tags: {sample['tags']}")
+        print(f"      Tags: {sample.metadata['tags']}")
 
     # Demonstrate None return for missing keys
-    print("  Note: sample['key'] returns None for missing keys")
-    missing_value = samples[0]["nonexistent_key"]
+    print("  Note: sample.metadata['key'] returns None for missing keys")
+    missing_value = samples[0].metadata["nonexistent_key"]
     if missing_value is None:
-        print(f" sample['nonexistent_key']: {missing_value}")
+        print(f" sample.metadata['nonexistent_key']: {missing_value}")
 
     print(f"✅ Added metadata to {len(samples)} samples using dictionary-like access")
 
     # Demonstrate schema presentation
     try:
-        samples[0]["temperature"] = "string_value"  # Invalid type for demonstration
+        samples[0].metadata["temperature"] = "string_value"  # Invalid type for demonstration
         print(f" ❌ This should not print: {missing_value}")
     except ValueError:
         print(" ✅ Correctly raised ValueError for invalid type")
@@ -308,22 +294,21 @@ def main() -> None:
     """Main function to demonstrate  metadata functionality."""
     try:
         # Load existing dataset
-        dataset, sample_ids, loader = load_existing_dataset()
+        dataset, samples = load_existing_dataset()
 
-        with db_manager.session() as session:
-            # Add bulk metadata
-            add_bulk_metadata(session, sample_ids)
+        # Add bulk metadata
+        add_bulk_metadata(db_manager.persistent_session(), [s.sample_id for s in samples])
 
-            # Add individual metadata
-            add_individual_metadata(session, sample_ids)
+        # Add individual metadata
+        add_individual_metadata(samples)
 
-            # Demonstrate different types of filtering
-            demonstrate_bulk_metadata_filters(dataset)
-            demonstrate_individual_metadata_filters(dataset)
-            demonstrate_combined_filters(dataset)
-            demonstrate_dictionary_like_access(session, sample_ids)
+        # Demonstrate different types of filtering
+        demonstrate_bulk_metadata_filters(dataset)
+        demonstrate_individual_metadata_filters(dataset)
+        demonstrate_combined_filters(dataset)
+        demonstrate_dictionary_like_access(samples)
 
-            loader.start_gui()
+        ls.start_gui()
 
     except ValueError as e:
         print(f"❌ Error: {e}")

lightly_studio/examples/example_selection.py

@@ -4,8 +4,7 @@ from pathlib import Path
 
 from environs import Env
 
-from lightly_studio import DatasetLoader
-from lightly_studio.selection.select import Selection
+import lightly_studio as ls
 
 # Read environment variables
 env = Env()
@@ -15,25 +14,14 @@ env.read_env()
 dataset_path = Path(env.path("DATASET_PATH", "/path/to/your/dataset"))
 dataset_path = dataset_path.parent if dataset_path.is_file() else dataset_path
 
-# Create a DatasetLoader from a path
-loader = DatasetLoader()
-dataset = loader.from_directory(
-    dataset_name="clothing_small_test",
-    img_dir=str(dataset_path),
-)
-
-# Create the selection interface
-# TODO(Malte, 08/2025): Replace this with using a DatasetView.
-# See the Select class for more details on the TODO.
-select = Selection(
-    dataset_id=dataset.dataset_id,
-    session=loader.session,
-)
+# Create a Dataset from a path
+dataset = ls.Dataset.create()
+dataset.add_samples_from_path(path=str(dataset_path))
 
-# Select a diverse subset of 10 samples.
-select.diverse(
+# Run selection via the dataset query
+dataset.query().selection().diverse(
     n_samples_to_select=10,
     selection_result_tag_name="diverse_selection",
 )
 
-loader.start_gui()
+ls.start_gui()

lightly_studio/examples/example_split_work.py

@@ -4,25 +4,21 @@ import math
 
 from environs import Env
 
-from lightly_studio import DatasetLoader
-from lightly_studio.models.tag import TagCreate
-from lightly_studio.resolvers import (
-    tag_resolver,
-)
+import lightly_studio as ls
 
 # Read environment variables
 env = Env()
 env.read_env()
 
-# Create a DatasetLoader instance
-loader = DatasetLoader()
+# Create a Dataset instance
+dataset = ls.Dataset.create()
 
 # Define the path to the dataset (folder containing data.yaml)
 dataset_path = env.path("DATASET_PATH", "/path/to/your/yolo/dataset/data.yaml")
 
 # Load YOLO dataset using data.yaml path
-dataset = loader.from_yolo(
-    str(dataset_path),
+dataset.add_samples_from_yolo(
+    data_yaml=str(dataset_path),
     input_split=env.str("LIGHTLY_STUDIO_DATASET_SPLIT", "test"),
 )
 
@@ -32,36 +28,16 @@ dataset = loader.from_yolo(
 # to work on.
 reviewers = env.str("DATASET_REVIEWERS", "Alice, Bob, Charlie, David")
 
-# Get all samples from the db
-samples = dataset.get_samples()
-
 # Create a tag for each reviewer to work on
-tags = []
-for reviewer in reviewers.split(","):
-    tags.append(
-        tag_resolver.create(
-            session=loader.session,
-            tag=TagCreate(
-                dataset_id=dataset.dataset_id,
-                name=f"""{reviewer.strip()} tasks""",
-                kind="sample",
-            ),
-        )
-    )
+tags = [reviewer.strip() for reviewer in reviewers.split(",")]
+
+# Get all samples from the db
+samples = dataset.query().to_list()
 
 # Chunk the samples into portions equally divided among the reviewers.
 chunk_size = math.ceil(len(samples) / len(tags))
-for i, tag in enumerate(tags):
-    # allocate all samples for this tag
-    sample_ids = [sample.sample_id for sample in samples[i * chunk_size : (i + 1) * chunk_size]]
-
-    # Add sample_ids to the tag
-    tag_resolver.add_sample_ids_to_tag_id(
-        session=loader.session,
-        tag_id=tag.tag_id,
-        sample_ids=sample_ids,
-    )
-
+for i, sample in enumerate(samples):
+    sample.add_tag(tags[i // chunk_size])
 
 # Launch the server to load data
-loader.start_gui()
+ls.start_gui()

lightly_studio/examples/{example_v2.py → example_yolo.py}

@@ -1,4 +1,4 @@
-"""Example of how to load samples from path with the dataset class."""
+"""Example of how to add samples in yolo format to a dataset."""
 
 from pathlib import Path
 
@@ -12,10 +12,9 @@ env.read_env()
 
 # Define the path to the dataset directory
 dataset_path = Path(env.path("DATASET_PATH", "/path/to/your/dataset"))
-dataset_path = dataset_path.parent if dataset_path.is_file() else dataset_path
 
 # Create a DatasetLoader from a path
-dataset = ls.Dataset("clothing_small_test")
-dataset.add_samples_from_path(path=dataset_path)
+dataset = ls.Dataset.create()
+dataset.add_samples_from_yolo(data_yaml=dataset_path, input_split="train")
 
 ls.start_gui()

lightly_studio/models/annotation/annotation_base.py

@@ -4,7 +4,7 @@ from datetime import datetime, timezone
 from typing import TYPE_CHECKING, List, Optional
 from uuid import UUID, uuid4
 
-from pydantic import BaseModel
+from pydantic import BaseModel, ConfigDict
 from pydantic import Field as PydanticField
 from sqlalchemy.orm import Mapped
 from sqlmodel import Field, Relationship, SQLModel
@@ -107,10 +107,10 @@ class AnnotationCreate(SQLModel):
     sample_id: UUID
 
     """ Optional properties for object detection. """
-    x: Optional[float] = None
-    y: Optional[float] = None
-    width: Optional[float] = None
-    height: Optional[float] = None
+    x: Optional[int] = None
+    y: Optional[int] = None
+    width: Optional[int] = None
+    height: Optional[int] = None
 
     """ Optional properties for instance and semantic segmentation. """
     segmentation_mask: Optional[List[int]] = None
@@ -157,13 +157,12 @@ class AnnotationWithSampleView(AnnotationView):
 class AnnotationViewsWithCount(BaseModel):
     """Response model for counted annotations."""
 
+    model_config = ConfigDict(populate_by_name=True)
+
     annotations: List[AnnotationWithSampleView] = PydanticField(..., alias="data")
     total_count: int
     next_cursor: Optional[int] = PydanticField(..., alias="nextCursor")
 
-    class Config:  # noqa: D106
-        populate_by_name = True
-
 
 class AnnotationDetailsView(AnnotationView):
     """Representing detailed view of an annotation."""

lightly_studio/models/annotation/instance_segmentation.py

@@ -34,10 +34,10 @@ class InstanceSegmentationAnnotationTable(SQLModel, table=True):
         back_populates="instance_segmentation_details"
     )
 
-    x: float
-    y: float
-    width: float
-    height: float
+    x: int
+    y: int
+    width: int
+    height: int
     # TODO(Kondrat 06/2025): We need to fix logic in the loader,
     # because it shouldn't be optional.
     # lightly_studio/dataset/loader.py#L148
@@ -49,8 +49,8 @@ class InstanceSegmentationAnnotationTable(SQLModel, table=True):
 class InstanceSegmentationAnnotationView(SQLModel):
     """API response model for instance segmentation annotations."""
 
-    x: float
-    y: float
-    width: float
-    height: float
+    x: int
+    y: int
+    width: int
+    height: int
     segmentation_mask: Optional[List[int]] = None

lightly_studio/models/annotation/object_detection.py

@@ -32,10 +32,10 @@ class ObjectDetectionAnnotationTable(SQLModel, table=True):
         back_populates="object_detection_details"
     )
 
-    x: float
-    y: float
-    width: float
-    height: float
+    x: int
+    y: int
+    width: int
+    height: int
 
 
 class ObjectDetectionAnnotationView(SQLModel):

lightly_studio/models/dataset.py

@@ -10,6 +10,7 @@ from uuid import UUID, uuid4
 from sqlalchemy.orm import Session as SQLAlchemySession
 from sqlmodel import Field, Session, SQLModel
 
+from lightly_studio.api.routes.api.validators import Paginated
 from lightly_studio.models.sample import SampleTable
 from lightly_studio.resolvers import sample_resolver
 from lightly_studio.resolvers.samples_filter import SampleFilter
@@ -73,11 +74,14 @@ class DatasetTable(DatasetBase, table=True):
         if session is None:
             raise RuntimeError("No database session found for this instance")
 
+        pagination = None
+        if limit is not None:
+            pagination = Paginated(offset=offset, limit=limit)
+
         return sample_resolver.get_all_by_dataset_id(
             session=session,
             dataset_id=self.dataset_id,
-            offset=offset,
-            limit=limit,
+            pagination=pagination,
             filters=filters,
             text_embedding=text_embedding,
             sample_ids=sample_ids,

lightly_studio/models/sample.py

@@ -4,6 +4,8 @@ from datetime import datetime, timezone
 from typing import TYPE_CHECKING, Any, List, Literal, Optional
 from uuid import UUID, uuid4
 
+from pydantic import BaseModel, ConfigDict
+from pydantic import Field as PydanticField
 from sqlalchemy.orm import Mapped, Session
 from sqlmodel import Field, Relationship, SQLModel
 
@@ -44,7 +46,7 @@ class SampleBase(SQLModel):
     dataset_id: UUID = Field(default=None, foreign_key="datasets.dataset_id")
 
     """The dataset image path."""
-    file_path_abs: str
+    file_path_abs: str = Field(default=None, unique=True)
 
 
 class SampleCreate(SampleBase):
@@ -97,6 +99,7 @@ class SampleTable(SampleBase, table=True):
     embeddings: Mapped[List["SampleEmbeddingTable"]] = Relationship(back_populates="sample")
     metadata_dict: "SampleMetadataTable" = Relationship(back_populates="sample")
 
+    # TODO(Michal, 9/2025): Remove this function in favour of Sample.metadata.
     def __getitem__(self, key: str) -> Any:
         """Provides dict-like access to sample metadata.
 
@@ -111,6 +114,7 @@ class SampleTable(SampleBase, table=True):
             return None
         return self.metadata_dict.get_value(key)
 
+    # TODO(Michal, 9/2025): Remove this function in favour of Sample.metadata.
     def __setitem__(self, key: str, value: Any) -> None:
         """Sets a metadata key-value pair for this sample.
 
@@ -173,8 +177,11 @@ class SampleView(SQLModel):
     height: int
 
 
-class SampleViewsWithCount(SQLModel):
+class SampleViewsWithCount(BaseModel):
     """Response model for counted samples."""
 
-    data: List[SampleView]
+    model_config = ConfigDict(populate_by_name=True)
+
+    samples: List[SampleView] = PydanticField(..., alias="data")
     total_count: int
+    next_cursor: Optional[int] = PydanticField(None, alias="nextCursor")

lightly_studio/resolvers/dataset_resolver.py

@@ -67,6 +67,16 @@ def get_by_id(session: Session, dataset_id: UUID) -> DatasetTable | None:
     ).one_or_none()
 
 
+def get_by_name(session: Session, name: str) -> DatasetTable | None:
+    """Retrieve a single dataset by name."""
+    datasets = session.exec(select(DatasetTable).where(DatasetTable.name == name)).all()
+    if len(datasets) == 0:
+        return None
+    if len(datasets) > 1:
+        raise ValueError(f"Cannot retrieve a dataset, found multiple with name '{name}'.")
+    return datasets[0]
+
+
 def update(session: Session, dataset_id: UUID, dataset_data: DatasetCreate) -> DatasetTable:
     """Update an existing dataset."""
     dataset = get_by_id(session=session, dataset_id=dataset_id)