Split BaseItemRepository and IItemRepository

Emby.Server.Implementations/ApplicationHost.cs

@@ -507,7 +507,13 @@ namespace Emby.Server.Implementations
 
             serviceCollection.AddSingleton<IUserDataManager, UserDataManager>();
 
-            serviceCollection.AddSingleton<IItemRepository, BaseItemRepository>();
+            serviceCollection.AddSingleton<BaseItemRepository>();
+            serviceCollection.AddSingleton<IItemRepository>(sp => sp.GetRequiredService<BaseItemRepository>());
+            serviceCollection.AddSingleton<IItemQueryHelpers>(sp => sp.GetRequiredService<BaseItemRepository>());
+            serviceCollection.AddSingleton<IItemPersistenceService, ItemPersistenceService>();
+            serviceCollection.AddSingleton<INextUpService, NextUpService>();
+            serviceCollection.AddSingleton<IItemCountService, ItemCountService>();
+            serviceCollection.AddSingleton<ILinkedChildrenService, LinkedChildrenService>();
             serviceCollection.AddSingleton<IPeopleRepository, PeopleRepository>();
             serviceCollection.AddSingleton<IChapterRepository, ChapterRepository>();
             serviceCollection.AddSingleton<IMediaAttachmentRepository, MediaAttachmentRepository>();
@@ -641,6 +647,7 @@ namespace Emby.Server.Implementations
             BaseItem.ConfigurationManager = ConfigurationManager;
             BaseItem.FileSystem = Resolve<IFileSystem>();
             BaseItem.ItemRepository = Resolve<IItemRepository>();
+            BaseItem.ItemCountService = Resolve<IItemCountService>();
             BaseItem.LibraryManager = Resolve<ILibraryManager>();
             BaseItem.LocalizationManager = Resolve<ILocalizationManager>();
             BaseItem.Logger = Resolve<ILogger<BaseItem>>();

Emby.Server.Implementations/Library/LibraryManager.cs

@@ -77,6 +77,10 @@ namespace Emby.Server.Implementations.Library
         private readonly IMediaEncoder _mediaEncoder;
         private readonly IFileSystem _fileSystem;
         private readonly IItemRepository _itemRepository;
+        private readonly IItemPersistenceService _persistenceService;
+        private readonly INextUpService _nextUpService;
+        private readonly IItemCountService _countService;
+        private readonly ILinkedChildrenService _linkedChildrenService;
         private readonly IImageProcessor _imageProcessor;
         private readonly NamingOptions _namingOptions;
         private readonly IPeopleRepository _peopleRepository;
@@ -115,6 +119,10 @@ namespace Emby.Server.Implementations.Library
         /// <param name="userViewManagerFactory">The user view manager.</param>
         /// <param name="mediaEncoder">The media encoder.</param>
         /// <param name="itemRepository">The item repository.</param>
+        /// <param name="persistenceService">The item persistence service.</param>
+        /// <param name="nextUpService">The next up service.</param>
+        /// <param name="countService">The item count service.</param>
+        /// <param name="linkedChildrenService">The linked children service.</param>
         /// <param name="imageProcessor">The image processor.</param>
         /// <param name="namingOptions">The naming options.</param>
         /// <param name="directoryService">The directory service.</param>
@@ -133,6 +141,10 @@ namespace Emby.Server.Implementations.Library
             Lazy<IUserViewManager> userViewManagerFactory,
             IMediaEncoder mediaEncoder,
             IItemRepository itemRepository,
+            IItemPersistenceService persistenceService,
+            INextUpService nextUpService,
+            IItemCountService countService,
+            ILinkedChildrenService linkedChildrenService,
             IImageProcessor imageProcessor,
             NamingOptions namingOptions,
             IDirectoryService directoryService,
@@ -151,6 +163,10 @@ namespace Emby.Server.Implementations.Library
             _userViewManagerFactory = userViewManagerFactory;
             _mediaEncoder = mediaEncoder;
             _itemRepository = itemRepository;
+            _persistenceService = persistenceService;
+            _nextUpService = nextUpService;
+            _countService = countService;
+            _linkedChildrenService = linkedChildrenService;
             _imageProcessor = imageProcessor;
 
             _cache = new FastConcurrentLru<Guid, BaseItem>(_configurationManager.Configuration.CacheSize);
@@ -363,7 +379,7 @@ namespace Emby.Server.Implementations.Library
                 }
             }
 
-            _itemRepository.DeleteItem([.. pathMaps.Select(f => f.Item.Id)]);
+            _persistenceService.DeleteItem([.. pathMaps.Select(f => f.Item.Id)]);
         }
 
         public void DeleteItem(BaseItem item, DeleteOptions options, BaseItem parent, bool notifyParentItem)
@@ -513,7 +529,7 @@ namespace Emby.Server.Implementations.Library
 
             item.SetParent(null);
 
-            _itemRepository.DeleteItem([item.Id, .. children.Select(f => f.Id)]);
+            _persistenceService.DeleteItem([item.Id, .. children.Select(f => f.Id)]);
             _cache.TryRemove(item.Id, out _);
             foreach (var child in children)
             {
@@ -1158,7 +1174,7 @@ namespace Emby.Server.Implementations.Library
 
         public IReadOnlyDictionary<string, MusicArtist[]> GetArtists(IReadOnlyList<string> names)
         {
-            return _itemRepository.FindArtists(names);
+            return _linkedChildrenService.FindArtists(names);
         }
 
         public MusicArtist GetArtist(string name, DtoOptions options)
@@ -1303,7 +1319,7 @@ namespace Emby.Server.Implementations.Library
 
             if (toDelete.Count > 0)
             {
-                _itemRepository.DeleteItem(toDelete.ToArray());
+                _persistenceService.DeleteItem(toDelete.ToArray());
             }
         }
 
@@ -1379,7 +1395,7 @@ namespace Emby.Server.Implementations.Library
                 progress.Report(percent * 100);
             }
 
-            _itemRepository.UpdateInheritedValues();
+            _persistenceService.UpdateInheritedValues();
 
             progress.Report(100);
         }
@@ -1562,7 +1578,7 @@ namespace Emby.Server.Implementations.Library
                 AddUserToQuery(query, query.User);
             }
 
-            return _itemRepository.GetCount(query);
+            return _countService.GetCount(query);
         }
 
         public ItemCounts GetItemCounts(InternalItemsQuery query)
@@ -1581,7 +1597,7 @@ namespace Emby.Server.Implementations.Library
                 AddUserToQuery(query, query.User);
             }
 
-            return _itemRepository.GetItemCounts(query);
+            return _countService.GetItemCounts(query);
         }
 
         /// <inheritdoc/>
@@ -1593,18 +1609,18 @@ namespace Emby.Server.Implementations.Library
                 AddUserToQuery(query, user);
             }
 
-            return _itemRepository.GetItemCountsForNameItem(kind, id, relatedItemKinds, query);
+            return _countService.GetItemCountsForNameItem(kind, id, relatedItemKinds, query);
         }
 
         public Dictionary<Guid, int> GetChildCountBatch(IReadOnlyList<Guid> parentIds, Guid? userId)
         {
-            return _itemRepository.GetChildCountBatch(parentIds, userId);
+            return _countService.GetChildCountBatch(parentIds, userId);
         }
 
         /// <inheritdoc/>
         public Dictionary<Guid, (int Played, int Total)> GetPlayedAndTotalCountBatch(IReadOnlyList<Guid> folderIds, User user)
         {
-            return _itemRepository.GetPlayedAndTotalCountBatch(folderIds, user);
+            return _countService.GetPlayedAndTotalCountBatch(folderIds, user);
         }
 
         public IReadOnlyList<BaseItem> GetItemList(InternalItemsQuery query, List<BaseItem> parents)
@@ -1649,7 +1665,7 @@ namespace Emby.Server.Implementations.Library
                 }
             }
 
-            return _itemRepository.GetNextUpSeriesKeys(query, dateCutoff);
+            return _nextUpService.GetNextUpSeriesKeys(query, dateCutoff);
         }
 
         /// <inheritdoc />
@@ -1659,7 +1675,7 @@ namespace Emby.Server.Implementations.Library
             bool includeSpecials,
             bool includeWatchedForRewatching)
         {
-            return _itemRepository.GetNextUpEpisodesBatch(query, seriesKeys, includeSpecials, includeWatchedForRewatching);
+            return _nextUpService.GetNextUpEpisodesBatch(query, seriesKeys, includeSpecials, includeWatchedForRewatching);
         }
 
         public QueryResult<BaseItem> QueryItems(InternalItemsQuery query)
@@ -2051,7 +2067,7 @@ namespace Emby.Server.Implementations.Library
         {
             ArgumentNullException.ThrowIfNull(video);
 
-            var linkedIds = _itemRepository.GetLinkedChildrenIds(video.Id, (int)MediaBrowser.Controller.Entities.LinkedChildType.LocalAlternateVersion);
+            var linkedIds = _linkedChildrenService.GetLinkedChildrenIds(video.Id, (int)MediaBrowser.Controller.Entities.LinkedChildType.LocalAlternateVersion);
             if (linkedIds.Count > 0)
             {
                 return linkedIds;
@@ -2065,7 +2081,7 @@ namespace Emby.Server.Implementations.Library
         {
             ArgumentNullException.ThrowIfNull(video);
 
-            var linkedIds = _itemRepository.GetLinkedChildrenIds(video.Id, (int)MediaBrowser.Controller.Entities.LinkedChildType.LinkedAlternateVersion);
+            var linkedIds = _linkedChildrenService.GetLinkedChildrenIds(video.Id, (int)MediaBrowser.Controller.Entities.LinkedChildType.LinkedAlternateVersion);
             if (linkedIds.Count > 0)
             {
                 return linkedIds
@@ -2081,7 +2097,7 @@ namespace Emby.Server.Implementations.Library
         /// <inheritdoc />
         public void UpsertLinkedChild(Guid parentId, Guid childId, MediaBrowser.Controller.Entities.LinkedChildType childType)
         {
-            _itemRepository.UpsertLinkedChild(parentId, childId, childType);
+            _linkedChildrenService.UpsertLinkedChild(parentId, childId, childType);
         }
 
         /// <inheritdoc />
@@ -2223,7 +2239,7 @@ namespace Emby.Server.Implementations.Library
                 }
             }
 
-            _itemRepository.SaveItems(allItems, cancellationToken);
+            _persistenceService.SaveItems(allItems, cancellationToken);
 
             foreach (var item in allItems)
             {
@@ -2374,7 +2390,7 @@ namespace Emby.Server.Implementations.Library
 
             item.ValidateImages();
 
-            await _itemRepository.SaveImagesAsync(item).ConfigureAwait(false);
+            await _persistenceService.SaveImagesAsync(item).ConfigureAwait(false);
 
             RegisterItem(item);
         }
@@ -2426,7 +2442,7 @@ namespace Emby.Server.Implementations.Library
                 }
             }
 
-            _itemRepository.SaveItems(allItems, cancellationToken);
+            _persistenceService.SaveItems(allItems, cancellationToken);
 
             foreach (var item in allItems)
             {
@@ -2478,7 +2494,7 @@ namespace Emby.Server.Implementations.Library
         /// <inheritdoc />
         public async Task ReattachUserDataAsync(BaseItem item, CancellationToken cancellationToken)
         {
-            await _itemRepository.ReattachUserDataAsync(item, cancellationToken).ConfigureAwait(false);
+            await _persistenceService.ReattachUserDataAsync(item, cancellationToken).ConfigureAwait(false);
         }
 
         public async Task RunMetadataSavers(BaseItem item, ItemUpdateType updateReason)
@@ -3669,7 +3685,7 @@ namespace Emby.Server.Implementations.Library
         /// <inheritdoc />
         public async Task RerouteLinkedChildReferencesAsync(Guid fromChildId, Guid toChildId)
         {
-            var affectedParentIds = _itemRepository.RerouteLinkedChildren(fromChildId, toChildId);
+            var affectedParentIds = _linkedChildrenService.RerouteLinkedChildren(fromChildId, toChildId);
 
             // Update in-memory LinkedChildren and re-save metadata (NFO) for affected parents
             foreach (var parentId in affectedParentIds)

Emby.Server.Implementations/ScheduledTasks/Tasks/AudioNormalizationTask.cs

@@ -26,7 +26,7 @@ namespace Emby.Server.Implementations.ScheduledTasks.Tasks;
 /// </summary>
 public partial class AudioNormalizationTask : IScheduledTask
 {
-    private readonly IItemRepository _itemRepository;
+    private readonly IItemPersistenceService _persistenceService;
     private readonly ILibraryManager _libraryManager;
     private readonly IMediaEncoder _mediaEncoder;
     private readonly IApplicationPaths _applicationPaths;
@@ -38,21 +38,21 @@ public partial class AudioNormalizationTask : IScheduledTask
     /// <summary>
     /// Initializes a new instance of the <see cref="AudioNormalizationTask"/> class.
     /// </summary>
-    /// <param name="itemRepository">Instance of the <see cref="IItemRepository"/> interface.</param>
+    /// <param name="persistenceService">Instance of the <see cref="IItemPersistenceService"/> interface.</param>
     /// <param name="libraryManager">Instance of the <see cref="ILibraryManager"/> interface.</param>
     /// <param name="mediaEncoder">Instance of the <see cref="IMediaEncoder"/> interface.</param>
     /// <param name="applicationPaths">Instance of the <see cref="IApplicationPaths"/> interface.</param>
     /// <param name="localizationManager">Instance of the <see cref="ILocalizationManager"/> interface.</param>
     /// <param name="logger">Instance of the <see cref="ILogger{AudioNormalizationTask}"/> interface.</param>
     public AudioNormalizationTask(
-        IItemRepository itemRepository,
+        IItemPersistenceService persistenceService,
         ILibraryManager libraryManager,
         IMediaEncoder mediaEncoder,
         IApplicationPaths applicationPaths,
         ILocalizationManager localizationManager,
         ILogger<AudioNormalizationTask> logger)
     {
-        _itemRepository = itemRepository;
+        _persistenceService = persistenceService;
         _libraryManager = libraryManager;
         _mediaEncoder = mediaEncoder;
         _applicationPaths = applicationPaths;
@@ -138,7 +138,7 @@ public partial class AudioNormalizationTask : IScheduledTask
                 {
                     if (toSaveDbItems.Count > 1)
                     {
-                        _itemRepository.SaveItems(toSaveDbItems, cancellationToken);
+                        _persistenceService.SaveItems(toSaveDbItems, cancellationToken);
                         toSaveDbItems.Clear();
                     }
 
@@ -158,7 +158,7 @@ public partial class AudioNormalizationTask : IScheduledTask
 
             if (toSaveDbItems.Count > 1)
             {
-                _itemRepository.SaveItems(toSaveDbItems, cancellationToken);
+                _persistenceService.SaveItems(toSaveDbItems, cancellationToken);
                 toSaveDbItems.Clear();
             }
 
@@ -183,7 +183,7 @@ public partial class AudioNormalizationTask : IScheduledTask
                 {
                     if (toSaveDbItems.Count > 1)
                     {
-                        _itemRepository.SaveItems(toSaveDbItems, cancellationToken);
+                        _persistenceService.SaveItems(toSaveDbItems, cancellationToken);
                         toSaveDbItems.Clear();
                     }
 
@@ -200,7 +200,7 @@ public partial class AudioNormalizationTask : IScheduledTask
 
             if (toSaveDbItems.Count > 1)
             {
-                _itemRepository.SaveItems(toSaveDbItems, cancellationToken);
+                _persistenceService.SaveItems(toSaveDbItems, cancellationToken);
             }
 
             // Update progress

Jellyfin.Server.Implementations/Item/BaseItemMapper.cs

@@ -0,0 +1,494 @@
+#pragma warning disable RS0030 // Do not use banned APIs
+
+using System;
+using System.Collections.Concurrent;
+using System.Linq;
+using System.Reflection;
+using System.Text;
+using System.Text.Json;
+using Jellyfin.Database.Implementations.Entities;
+using Jellyfin.Extensions;
+using Jellyfin.Extensions.Json;
+using MediaBrowser.Common;
+using MediaBrowser.Controller;
+using MediaBrowser.Controller.Entities;
+using MediaBrowser.Controller.Entities.Audio;
+using MediaBrowser.Controller.Entities.TV;
+using MediaBrowser.Controller.LiveTv;
+using MediaBrowser.Model.Entities;
+using MediaBrowser.Model.LiveTv;
+using Microsoft.Extensions.Logging;
+using BaseItemDto = MediaBrowser.Controller.Entities.BaseItem;
+using BaseItemEntity = Jellyfin.Database.Implementations.Entities.BaseItemEntity;
+
+namespace Jellyfin.Server.Implementations.Item;
+
+/// <summary>
+/// Handles mapping between BaseItemEntity (database) and BaseItemDto (domain) objects.
+/// </summary>
+internal static class BaseItemMapper
+{
+    /// <summary>
+    /// This holds all the types in the running assemblies
+    /// so that we can de-serialize properly when we don't have strong types.
+    /// </summary>
+    private static readonly ConcurrentDictionary<string, Type?> _typeMap = new ConcurrentDictionary<string, Type?>();
+
+    /// <summary>
+    /// Maps a Entity to the DTO.
+    /// </summary>
+    /// <param name="entity">The entity.</param>
+    /// <param name="dto">The dto base instance.</param>
+    /// <param name="appHost">The Application server Host.</param>
+    /// <returns>The dto to map.</returns>
+    public static BaseItemDto Map(BaseItemEntity entity, BaseItemDto dto, IServerApplicationHost? appHost)
+    {
+        dto.Id = entity.Id;
+        dto.ParentId = entity.ParentId.GetValueOrDefault();
+        dto.Path = appHost?.ExpandVirtualPath(entity.Path) ?? entity.Path;
+        dto.EndDate = entity.EndDate;
+        dto.CommunityRating = entity.CommunityRating;
+        dto.CustomRating = entity.CustomRating;
+        dto.IndexNumber = entity.IndexNumber;
+        dto.IsLocked = entity.IsLocked;
+        dto.Name = entity.Name;
+        dto.OfficialRating = entity.OfficialRating;
+        dto.Overview = entity.Overview;
+        dto.ParentIndexNumber = entity.ParentIndexNumber;
+        dto.PremiereDate = entity.PremiereDate;
+        dto.ProductionYear = entity.ProductionYear;
+        dto.SortName = entity.SortName;
+        dto.ForcedSortName = entity.ForcedSortName;
+        dto.RunTimeTicks = entity.RunTimeTicks;
+        dto.PreferredMetadataLanguage = entity.PreferredMetadataLanguage;
+        dto.PreferredMetadataCountryCode = entity.PreferredMetadataCountryCode;
+        dto.IsInMixedFolder = entity.IsInMixedFolder;
+        dto.InheritedParentalRatingValue = entity.InheritedParentalRatingValue;
+        dto.InheritedParentalRatingSubValue = entity.InheritedParentalRatingSubValue;
+        dto.CriticRating = entity.CriticRating;
+        dto.PresentationUniqueKey = entity.PresentationUniqueKey;
+        dto.OriginalTitle = entity.OriginalTitle;
+        dto.Album = entity.Album;
+        dto.LUFS = entity.LUFS;
+        dto.NormalizationGain = entity.NormalizationGain;
+        dto.IsVirtualItem = entity.IsVirtualItem;
+        dto.ExternalSeriesId = entity.ExternalSeriesId;
+        dto.Tagline = entity.Tagline;
+        dto.TotalBitrate = entity.TotalBitrate;
+        dto.ExternalId = entity.ExternalId;
+        dto.Size = entity.Size;
+        dto.Genres = string.IsNullOrWhiteSpace(entity.Genres) ? [] : entity.Genres.Split('|');
+        dto.DateCreated = entity.DateCreated ?? DateTime.SpecifyKind(DateTime.MinValue, DateTimeKind.Utc);
+        dto.DateModified = entity.DateModified ?? DateTime.SpecifyKind(DateTime.MinValue, DateTimeKind.Utc);
+        dto.ChannelId = entity.ChannelId ?? Guid.Empty;
+        dto.DateLastRefreshed = entity.DateLastRefreshed ?? DateTime.SpecifyKind(DateTime.MinValue, DateTimeKind.Utc);
+        dto.DateLastSaved = entity.DateLastSaved ?? DateTime.SpecifyKind(DateTime.MinValue, DateTimeKind.Utc);
+        dto.OwnerId = entity.OwnerId ?? Guid.Empty;
+        dto.Width = entity.Width.GetValueOrDefault();
+        dto.Height = entity.Height.GetValueOrDefault();
+        dto.UserData = entity.UserData;
+
+        if (entity.Provider is not null)
+        {
+            dto.ProviderIds = entity.Provider.ToDictionary(e => e.ProviderId, e => e.ProviderValue);
+        }
+
+        if (entity.ExtraType is not null)
+        {
+            dto.ExtraType = (ExtraType)entity.ExtraType;
+        }
+
+        if (entity.LockedFields is not null)
+        {
+            dto.LockedFields = entity.LockedFields?.Select(e => (MetadataField)e.Id).ToArray() ?? [];
+        }
+
+        if (entity.Audio is not null)
+        {
+            dto.Audio = (ProgramAudio)entity.Audio;
+        }
+
+        dto.ProductionLocations = entity.ProductionLocations?.Split('|', StringSplitOptions.RemoveEmptyEntries) ?? [];
+        dto.Studios = entity.Studios?.Split('|') ?? [];
+        dto.Tags = string.IsNullOrWhiteSpace(entity.Tags) ? [] : entity.Tags.Split('|');
+
+        if (dto is IHasProgramAttributes hasProgramAttributes)
+        {
+            hasProgramAttributes.IsMovie = entity.IsMovie;
+            hasProgramAttributes.IsSeries = entity.IsSeries;
+            hasProgramAttributes.EpisodeTitle = entity.EpisodeTitle;
+            hasProgramAttributes.IsRepeat = entity.IsRepeat;
+        }
+
+        if (dto is LiveTvChannel liveTvChannel)
+        {
+            liveTvChannel.ServiceName = entity.ExternalServiceId;
+        }
+
+        if (dto is Trailer trailer)
+        {
+            trailer.TrailerTypes = entity.TrailerTypes?.Select(e => (TrailerType)e.Id).ToArray() ?? [];
+        }
+
+        if (dto is Video video)
+        {
+            video.PrimaryVersionId = entity.PrimaryVersionId;
+        }
+
+        if (dto is IHasSeries hasSeriesName)
+        {
+            hasSeriesName.SeriesName = entity.SeriesName;
+            hasSeriesName.SeriesId = entity.SeriesId.GetValueOrDefault();
+            hasSeriesName.SeriesPresentationUniqueKey = entity.SeriesPresentationUniqueKey;
+        }
+
+        if (dto is Episode episode)
+        {
+            episode.SeasonName = entity.SeasonName;
+            episode.SeasonId = entity.SeasonId.GetValueOrDefault();
+        }
+
+        if (dto is IHasArtist hasArtists)
+        {
+            hasArtists.Artists = entity.Artists?.Split('|', StringSplitOptions.RemoveEmptyEntries) ?? [];
+        }
+
+        if (dto is IHasAlbumArtist hasAlbumArtists)
+        {
+            hasAlbumArtists.AlbumArtists = entity.AlbumArtists?.Split('|', StringSplitOptions.RemoveEmptyEntries) ?? [];
+        }
+
+        if (dto is LiveTvProgram program)
+        {
+            program.ShowId = entity.ShowId;
+        }
+
+        if (entity.Images is not null)
+        {
+            dto.ImageInfos = entity.Images.Select(e => MapImageFromEntity(e, appHost)).ToArray();
+        }
+
+        // dto.Type = entity.Type;
+        // dto.Data = entity.Data;
+        // dto.MediaType = Enum.TryParse<MediaType>(entity.MediaType);
+        if (dto is IHasStartDate hasStartDate)
+        {
+            hasStartDate.StartDate = entity.StartDate.GetValueOrDefault();
+        }
+
+        // Fields that are present in the DB but are never actually used
+        // dto.UnratedType = entity.UnratedType;
+        // dto.TopParentId = entity.TopParentId;
+        // dto.CleanName = entity.CleanName;
+        // dto.UserDataKey = entity.UserDataKey;
+
+        if (dto is Folder folder)
+        {
+            folder.DateLastMediaAdded = entity.DateLastMediaAdded ?? DateTime.SpecifyKind(DateTime.MinValue, DateTimeKind.Utc);
+            if (entity.LinkedChildEntities is not null && entity.LinkedChildEntities.Count > 0)
+            {
+                folder.LinkedChildren = entity.LinkedChildEntities
+                    .OrderBy(e => e.SortOrder)
+                    .Select(e => new LinkedChild
+                    {
+                        ItemId = e.ChildId,
+                        Type = (MediaBrowser.Controller.Entities.LinkedChildType)e.ChildType
+                    })
+                    .ToArray();
+            }
+        }
+
+        return dto;
+    }
+
+    /// <summary>
+    /// Maps a DTO to a database entity.
+    /// </summary>
+    /// <param name="dto">The DTO.</param>
+    /// <param name="appHost">The application host for path resolution.</param>
+    /// <returns>The database entity.</returns>
+    public static BaseItemEntity Map(BaseItemDto dto, IServerApplicationHost appHost)
+    {
+        var dtoType = dto.GetType();
+        var entity = new BaseItemEntity()
+        {
+            Type = dtoType.ToString(),
+            Id = dto.Id
+        };
+
+        if (TypeRequiresDeserialization(dtoType))
+        {
+            entity.Data = JsonSerializer.Serialize(dto, dtoType, JsonDefaults.Options);
+        }
+
+        entity.ParentId = !dto.ParentId.IsEmpty() ? dto.ParentId : null;
+        entity.Path = GetPathToSave(dto.Path, appHost);
+        entity.EndDate = dto.EndDate;
+        entity.CommunityRating = dto.CommunityRating;
+        entity.CustomRating = dto.CustomRating;
+        entity.IndexNumber = dto.IndexNumber;
+        entity.IsLocked = dto.IsLocked;
+        entity.Name = dto.Name;
+        entity.CleanName = dto.Name.GetCleanValue();
+        entity.OfficialRating = dto.OfficialRating;
+        entity.Overview = dto.Overview;
+        entity.ParentIndexNumber = dto.ParentIndexNumber;
+        entity.PremiereDate = dto.PremiereDate;
+        entity.ProductionYear = dto.ProductionYear;
+        entity.SortName = dto.SortName;
+        entity.ForcedSortName = dto.ForcedSortName;
+        entity.RunTimeTicks = dto.RunTimeTicks;
+        entity.PreferredMetadataLanguage = dto.PreferredMetadataLanguage;
+        entity.PreferredMetadataCountryCode = dto.PreferredMetadataCountryCode;
+        entity.IsInMixedFolder = dto.IsInMixedFolder;
+        entity.InheritedParentalRatingValue = dto.InheritedParentalRatingValue;
+        entity.InheritedParentalRatingSubValue = dto.InheritedParentalRatingSubValue;
+        entity.CriticRating = dto.CriticRating;
+        entity.PresentationUniqueKey = dto.PresentationUniqueKey;
+        entity.OriginalTitle = dto.OriginalTitle;
+        entity.Album = dto.Album;
+        entity.LUFS = dto.LUFS;
+        entity.NormalizationGain = dto.NormalizationGain;
+        entity.IsVirtualItem = dto.IsVirtualItem;
+        entity.ExternalSeriesId = dto.ExternalSeriesId;
+        entity.Tagline = dto.Tagline;
+        entity.TotalBitrate = dto.TotalBitrate;
+        entity.ExternalId = dto.ExternalId;
+        entity.Size = dto.Size;
+        entity.Genres = string.Join('|', dto.Genres);
+        entity.DateCreated = dto.DateCreated == DateTime.MinValue ? null : dto.DateCreated;
+        entity.DateModified = dto.DateModified == DateTime.MinValue ? null : dto.DateModified;
+        entity.ChannelId = dto.ChannelId;
+        entity.DateLastRefreshed = dto.DateLastRefreshed == DateTime.MinValue ? null : dto.DateLastRefreshed;
+        entity.DateLastSaved = dto.DateLastSaved == DateTime.MinValue ? null : dto.DateLastSaved;
+        entity.OwnerId = dto.OwnerId == Guid.Empty ? null : dto.OwnerId;
+        entity.Width = dto.Width;
+        entity.Height = dto.Height;
+        entity.Provider = dto.ProviderIds.Select(e => new BaseItemProvider()
+        {
+            Item = entity,
+            ProviderId = e.Key,
+            ProviderValue = e.Value
+        }).ToList();
+
+        if (dto.Audio.HasValue)
+        {
+            entity.Audio = (ProgramAudioEntity)dto.Audio;
+        }
+
+        if (dto.ExtraType.HasValue)
+        {
+            entity.ExtraType = (BaseItemExtraType)dto.ExtraType;
+        }
+
+        entity.ProductionLocations = dto.ProductionLocations is not null ? string.Join('|', dto.ProductionLocations.Where(p => !string.IsNullOrWhiteSpace(p))) : null;
+        entity.Studios = dto.Studios is not null ? string.Join('|', dto.Studios) : null;
+        entity.Tags = dto.Tags is not null ? string.Join('|', dto.Tags) : null;
+        entity.LockedFields = dto.LockedFields is not null ? dto.LockedFields
+            .Select(e => new BaseItemMetadataField()
+            {
+                Id = (int)e,
+                Item = entity,
+                ItemId = entity.Id
+            })
+            .ToArray() : null;
+
+        if (dto is IHasProgramAttributes hasProgramAttributes)
+        {
+            entity.IsMovie = hasProgramAttributes.IsMovie;
+            entity.IsSeries = hasProgramAttributes.IsSeries;
+            entity.EpisodeTitle = hasProgramAttributes.EpisodeTitle;
+            entity.IsRepeat = hasProgramAttributes.IsRepeat;
+        }
+
+        if (dto is LiveTvChannel liveTvChannel)
+        {
+            entity.ExternalServiceId = liveTvChannel.ServiceName;
+        }
+
+        if (dto is Video video)
+        {
+            entity.PrimaryVersionId = video.PrimaryVersionId;
+        }
+
+        if (dto is IHasSeries hasSeriesName)
+        {
+            entity.SeriesName = hasSeriesName.SeriesName;
+            entity.SeriesId = hasSeriesName.SeriesId;
+            entity.SeriesPresentationUniqueKey = hasSeriesName.SeriesPresentationUniqueKey;
+        }
+
+        if (dto is Episode episode)
+        {
+            entity.SeasonName = episode.SeasonName;
+            entity.SeasonId = episode.SeasonId;
+        }
+
+        if (dto is IHasArtist hasArtists)
+        {
+            entity.Artists = hasArtists.Artists is not null ? string.Join('|', hasArtists.Artists) : null;
+        }
+
+        if (dto is IHasAlbumArtist hasAlbumArtists)
+        {
+            entity.AlbumArtists = hasAlbumArtists.AlbumArtists is not null ? string.Join('|', hasAlbumArtists.AlbumArtists) : null;
+        }
+
+        if (dto is LiveTvProgram program)
+        {
+            entity.ShowId = program.ShowId;
+        }
+
+        if (dto.ImageInfos is not null)
+        {
+            entity.Images = dto.ImageInfos.Select(f => MapImageToEntity(dto.Id, f)).ToArray();
+        }
+
+        if (dto is Trailer trailer)
+        {
+            entity.TrailerTypes = trailer.TrailerTypes?.Select(e => new BaseItemTrailerType()
+            {
+                Id = (int)e,
+                Item = entity,
+                ItemId = entity.Id
+            }).ToArray() ?? [];
+        }
+
+        // dto.Type = entity.Type;
+        // dto.Data = entity.Data;
+        entity.MediaType = dto.MediaType.ToString();
+        if (dto is IHasStartDate hasStartDate)
+        {
+            entity.StartDate = hasStartDate.StartDate;
+        }
+
+        entity.UnratedType = dto.GetBlockUnratedType().ToString();
+
+        // Fields that are present in the DB but are never actually used
+        // dto.UserDataKey = entity.UserDataKey;
+
+        if (dto is Folder folder)
+        {
+            entity.DateLastMediaAdded = folder.DateLastMediaAdded == DateTime.MinValue ? null : folder.DateLastMediaAdded;
+            entity.IsFolder = folder.IsFolder;
+        }
+
+        return entity;
+    }
+
+    /// <summary>
+    /// Maps a database image entity to a domain image info.
+    /// </summary>
+    /// <param name="e">The database image entity.</param>
+    /// <param name="appHost">The application host.</param>
+    /// <returns>The mapped image info.</returns>
+    public static ItemImageInfo MapImageFromEntity(BaseItemImageInfo e, IServerApplicationHost? appHost)
+    {
+        return new ItemImageInfo()
+        {
+            Path = appHost?.ExpandVirtualPath(e.Path) ?? e.Path,
+            BlurHash = e.Blurhash is null ? null : Encoding.UTF8.GetString(e.Blurhash),
+            DateModified = e.DateModified ?? DateTime.SpecifyKind(DateTime.MinValue, DateTimeKind.Utc),
+            Height = e.Height,
+            Width = e.Width,
+            Type = (ImageType)e.ImageType
+        };
+    }
+
+    /// <summary>
+    /// Maps a domain image info to a database image entity.
+    /// </summary>
+    /// <param name="baseItemId">The parent item ID.</param>
+    /// <param name="e">The image info to map.</param>
+    /// <returns>The mapped database entity.</returns>
+    public static BaseItemImageInfo MapImageToEntity(Guid baseItemId, ItemImageInfo e)
+    {
+        return new BaseItemImageInfo()
+        {
+            ItemId = baseItemId,
+            Id = Guid.NewGuid(),
+            Path = e.Path,
+            Blurhash = e.BlurHash is null ? null : Encoding.UTF8.GetBytes(e.BlurHash),
+            DateModified = e.DateModified,
+            Height = e.Height,
+            Width = e.Width,
+            ImageType = (ImageInfoImageType)e.Type,
+            Item = null!
+        };
+    }
+
+    /// <summary>
+    /// Gets the type from a type name string.
+    /// </summary>
+    /// <param name="typeName">The type name.</param>
+    /// <returns>The resolved type, or null.</returns>
+    public static Type? GetType(string typeName)
+    {
+        ArgumentException.ThrowIfNullOrEmpty(typeName);
+
+        return _typeMap.GetOrAdd(typeName, k => AppDomain.CurrentDomain.GetAssemblies()
+            .Select(a => a.GetType(k))
+            .FirstOrDefault(t => t is not null));
+    }
+
+    /// <summary>
+    /// Checks whether a type requires JSON deserialization.
+    /// </summary>
+    /// <param name="type">The type to check.</param>
+    /// <returns>True if the type requires deserialization.</returns>
+    public static bool TypeRequiresDeserialization(Type type)
+    {
+        return type.GetCustomAttribute<RequiresSourceSerialisationAttribute>() == null;
+    }
+
+    /// <summary>
+    /// Deserializes a BaseItemEntity and sets all properties.
+    /// </summary>
+    /// <param name="baseItemEntity">The DB entity.</param>
+    /// <param name="logger">Logger.</param>
+    /// <param name="appHost">The application server Host.</param>
+    /// <param name="skipDeserialization">If only mapping should be processed.</param>
+    /// <returns>A mapped BaseItem, or null if the item type is unknown.</returns>
+    public static BaseItemDto? DeserializeBaseItem(BaseItemEntity baseItemEntity, ILogger logger, IServerApplicationHost? appHost, bool skipDeserialization = false)
+    {
+        var type = GetType(baseItemEntity.Type);
+        if (type is null)
+        {
+            logger.LogWarning(
+                "Skipping item {ItemId} with unknown type '{ItemType}'. This may indicate a removed plugin or database corruption.",
+                baseItemEntity.Id,
+                baseItemEntity.Type);
+            return null;
+        }
+
+        BaseItemDto? dto = null;
+        if (TypeRequiresDeserialization(type) && baseItemEntity.Data is not null && !skipDeserialization)
+        {
+            try
+            {
+                dto = JsonSerializer.Deserialize(baseItemEntity.Data, type, JsonDefaults.Options) as BaseItemDto;
+            }
+            catch (JsonException ex)
+            {
+                logger.LogError(ex, "Error deserializing item with JSON: {Data}", baseItemEntity.Data);
+            }
+        }
+
+        if (dto is null)
+        {
+            dto = Activator.CreateInstance(type) as BaseItemDto ?? throw new InvalidOperationException("Cannot deserialize unknown type.");
+        }
+
+        return Map(baseItemEntity, dto, appHost);
+    }
+
+    private static string? GetPathToSave(string path, IServerApplicationHost appHost)
+    {
+        if (path is null)
+        {
+            return null;
+        }
+
+        return appHost.ReverseVirtualPath(path);
+    }
+}

Jellyfin.Server.Implementations/Item/BaseItemRepository.ByName.cs

@@ -0,0 +1,293 @@
+#pragma warning disable RS0030 // Do not use banned APIs
+
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using Jellyfin.Data.Enums;
+using Jellyfin.Database.Implementations.Entities;
+using Jellyfin.Extensions;
+using MediaBrowser.Controller.Entities;
+using MediaBrowser.Model.Dto;
+using MediaBrowser.Model.Querying;
+using Microsoft.EntityFrameworkCore;
+using BaseItemDto = MediaBrowser.Controller.Entities.BaseItem;
+
+namespace Jellyfin.Server.Implementations.Item;
+
+public sealed partial class BaseItemRepository
+{
+    /// <inheritdoc />
+    public QueryResult<(BaseItemDto Item, ItemCounts? ItemCounts)> GetAllArtists(InternalItemsQuery filter)
+    {
+        return GetItemValues(filter, _getAllArtistsValueTypes, _itemTypeLookup.BaseItemKindNames[BaseItemKind.MusicArtist]);
+    }
+
+    /// <inheritdoc />
+    public QueryResult<(BaseItemDto Item, ItemCounts? ItemCounts)> GetArtists(InternalItemsQuery filter)
+    {
+        return GetItemValues(filter, _getArtistValueTypes, _itemTypeLookup.BaseItemKindNames[BaseItemKind.MusicArtist]);
+    }
+
+    /// <inheritdoc />
+    public QueryResult<(BaseItemDto Item, ItemCounts? ItemCounts)> GetAlbumArtists(InternalItemsQuery filter)
+    {
+        return GetItemValues(filter, _getAlbumArtistValueTypes, _itemTypeLookup.BaseItemKindNames[BaseItemKind.MusicArtist]);
+    }
+
+    /// <inheritdoc />
+    public QueryResult<(BaseItemDto Item, ItemCounts? ItemCounts)> GetStudios(InternalItemsQuery filter)
+    {
+        return GetItemValues(filter, _getStudiosValueTypes, _itemTypeLookup.BaseItemKindNames[BaseItemKind.Studio]);
+    }
+
+    /// <inheritdoc />
+    public QueryResult<(BaseItemDto Item, ItemCounts? ItemCounts)> GetGenres(InternalItemsQuery filter)
+    {
+        return GetItemValues(filter, _getGenreValueTypes, _itemTypeLookup.BaseItemKindNames[BaseItemKind.Genre]);
+    }
+
+    /// <inheritdoc />
+    public QueryResult<(BaseItemDto Item, ItemCounts? ItemCounts)> GetMusicGenres(InternalItemsQuery filter)
+    {
+        return GetItemValues(filter, _getGenreValueTypes, _itemTypeLookup.BaseItemKindNames[BaseItemKind.MusicGenre]);
+    }
+
+    /// <inheritdoc />
+    public IReadOnlyList<string> GetStudioNames()
+    {
+        return GetItemValueNames(_getStudiosValueTypes, [], []);
+    }
+
+    /// <inheritdoc />
+    public IReadOnlyList<string> GetAllArtistNames()
+    {
+        return GetItemValueNames(_getAllArtistsValueTypes, [], []);
+    }
+
+    /// <inheritdoc />
+    public IReadOnlyList<string> GetMusicGenreNames()
+    {
+        return GetItemValueNames(
+            _getGenreValueTypes,
+            _itemTypeLookup.MusicGenreTypes,
+            []);
+    }
+
+    /// <inheritdoc />
+    public IReadOnlyList<string> GetGenreNames()
+    {
+        return GetItemValueNames(
+            _getGenreValueTypes,
+            [],
+            _itemTypeLookup.MusicGenreTypes);
+    }
+
+    private string[] GetItemValueNames(IReadOnlyList<ItemValueType> itemValueTypes, IReadOnlyList<string> withItemTypes, IReadOnlyList<string> excludeItemTypes)
+    {
+        using var context = _dbProvider.CreateDbContext();
+
+        var query = context.ItemValuesMap
+            .AsNoTracking()
+            .Where(e => itemValueTypes.Any(w => w == e.ItemValue.Type));
+        if (withItemTypes.Count > 0)
+        {
+            query = query.Where(e => withItemTypes.Contains(e.Item.Type));
+        }
+
+        if (excludeItemTypes.Count > 0)
+        {
+            query = query.Where(e => !excludeItemTypes.Contains(e.Item.Type));
+        }
+
+        // query = query.DistinctBy(e => e.CleanValue);
+        return query.Select(e => e.ItemValue)
+            .GroupBy(e => e.CleanValue)
+            .Select(e => e.OrderBy(v => v.Value).First().Value)
+            .ToArray();
+    }
+
+    private QueryResult<(BaseItemDto Item, ItemCounts? ItemCounts)> GetItemValues(InternalItemsQuery filter, IReadOnlyList<ItemValueType> itemValueTypes, string returnType)
+    {
+        ArgumentNullException.ThrowIfNull(filter);
+
+        if (!filter.Limit.HasValue)
+        {
+            filter.EnableTotalRecordCount = false;
+        }
+
+        using var context = _dbProvider.CreateDbContext();
+
+        var innerQueryFilter = TranslateQuery(context.BaseItems.Where(e => e.Id != EF.Constant(PlaceholderId)), context, new InternalItemsQuery(filter.User)
+        {
+            ExcludeItemTypes = filter.ExcludeItemTypes,
+            IncludeItemTypes = filter.IncludeItemTypes,
+            MediaTypes = filter.MediaTypes,
+            AncestorIds = filter.AncestorIds,
+            ItemIds = filter.ItemIds,
+            TopParentIds = filter.TopParentIds,
+            ParentId = filter.ParentId,
+            IsAiring = filter.IsAiring,
+            IsMovie = filter.IsMovie,
+            IsSports = filter.IsSports,
+            IsKids = filter.IsKids,
+            IsNews = filter.IsNews,
+            IsSeries = filter.IsSeries
+        });
+        var itemValuesQuery = context.ItemValuesMap
+            .Where(ivm => itemValueTypes.Contains(ivm.ItemValue.Type))
+            .Join(
+                innerQueryFilter,
+                ivm => ivm.ItemId,
+                g => g.Id,
+                (ivm, g) => ivm.ItemValue.CleanValue);
+
+        var innerQuery = PrepareItemQuery(context, filter)
+            .Where(e => e.Type == returnType)
+            .Where(e => itemValuesQuery.Contains(e.CleanName));
+
+        var outerQueryFilter = new InternalItemsQuery(filter.User)
+        {
+            IsPlayed = filter.IsPlayed,
+            IsFavorite = filter.IsFavorite,
+            IsFavoriteOrLiked = filter.IsFavoriteOrLiked,
+            IsLiked = filter.IsLiked,
+            IsLocked = filter.IsLocked,
+            NameLessThan = filter.NameLessThan,
+            NameStartsWith = filter.NameStartsWith,
+            NameStartsWithOrGreater = filter.NameStartsWithOrGreater,
+            Tags = filter.Tags,
+            OfficialRatings = filter.OfficialRatings,
+            StudioIds = filter.StudioIds,
+            GenreIds = filter.GenreIds,
+            Genres = filter.Genres,
+            Years = filter.Years,
+            NameContains = filter.NameContains,
+            SearchTerm = filter.SearchTerm,
+            ExcludeItemIds = filter.ExcludeItemIds
+        };
+
+        var masterQuery = TranslateQuery(innerQuery, context, outerQueryFilter)
+            .GroupBy(e => e.PresentationUniqueKey)
+            .Select(e => e.OrderBy(x => x.Id).FirstOrDefault())
+            .Select(e => e!.Id);
+
+        var query = context.BaseItems
+            .Include(e => e.TrailerTypes)
+            .Include(e => e.Provider)
+            .Include(e => e.LockedFields)
+            .Include(e => e.Images)
+            .Include(e => e.LinkedChildEntities)
+            .AsSingleQuery()
+            .Where(e => masterQuery.Contains(e.Id));
+
+        query = ApplyOrder(query, filter, context);
+
+        var result = new QueryResult<(BaseItemDto, ItemCounts?)>();
+        if (filter.EnableTotalRecordCount)
+        {
+            result.TotalRecordCount = query.Count();
+        }
+
+        if (filter.Limit.HasValue || filter.StartIndex.HasValue)
+        {
+            var offset = filter.StartIndex ?? 0;
+
+            if (offset > 0)
+            {
+                query = query.Skip(offset);
+            }
+
+            if (filter.Limit.HasValue)
+            {
+                query = query.Take(filter.Limit.Value);
+            }
+        }
+
+        if (filter.IncludeItemTypes.Length > 0)
+        {
+            var typeSubQuery = new InternalItemsQuery(filter.User)
+            {
+                ExcludeItemTypes = filter.ExcludeItemTypes,
+                IncludeItemTypes = filter.IncludeItemTypes,
+                MediaTypes = filter.MediaTypes,
+                AncestorIds = filter.AncestorIds,
+                ExcludeItemIds = filter.ExcludeItemIds,
+                ItemIds = filter.ItemIds,
+                TopParentIds = filter.TopParentIds,
+                ParentId = filter.ParentId,
+                IsPlayed = filter.IsPlayed
+            };
+
+            var itemCountQuery = TranslateQuery(context.BaseItems.AsNoTracking().Where(e => e.Id != EF.Constant(PlaceholderId)), context, typeSubQuery)
+                .Where(e => e.ItemValues!.Any(f => itemValueTypes!.Contains(f.ItemValue.Type)));
+
+            var seriesTypeName = _itemTypeLookup.BaseItemKindNames[BaseItemKind.Series];
+            var movieTypeName = _itemTypeLookup.BaseItemKindNames[BaseItemKind.Movie];
+            var episodeTypeName = _itemTypeLookup.BaseItemKindNames[BaseItemKind.Episode];
+            var musicAlbumTypeName = _itemTypeLookup.BaseItemKindNames[BaseItemKind.MusicAlbum];
+            var musicArtistTypeName = _itemTypeLookup.BaseItemKindNames[BaseItemKind.MusicArtist];
+            var audioTypeName = _itemTypeLookup.BaseItemKindNames[BaseItemKind.Audio];
+            var trailerTypeName = _itemTypeLookup.BaseItemKindNames[BaseItemKind.Trailer];
+
+            // Get the IDs from itemCountQuery to use in the join
+            var itemIds = itemCountQuery.Select(e => e.Id);
+
+            // Rewrite query to avoid SelectMany on navigation properties (which requires SQL APPLY, not supported on SQLite)
+            // Instead, start from ItemValueMaps and join with BaseItems
+            var countsByCleanName = context.ItemValuesMap
+                .Where(ivm => itemValueTypes.Contains(ivm.ItemValue.Type))
+                .Where(ivm => itemIds.Contains(ivm.ItemId))
+                .Join(
+                    context.BaseItems,
+                    ivm => ivm.ItemId,
+                    e => e.Id,
+                    (ivm, e) => new { CleanName = ivm.ItemValue.CleanValue, e.Type })
+                .GroupBy(x => new { x.CleanName, x.Type })
+                .Select(g => new { g.Key.CleanName, g.Key.Type, Count = g.Count() })
+                .GroupBy(x => x.CleanName)
+                .ToDictionary(
+                    g => g.Key,
+                    g => new ItemCounts
+                    {
+                        SeriesCount = g.Where(x => x.Type == seriesTypeName).Sum(x => x.Count),
+                        EpisodeCount = g.Where(x => x.Type == episodeTypeName).Sum(x => x.Count),
+                        MovieCount = g.Where(x => x.Type == movieTypeName).Sum(x => x.Count),
+                        AlbumCount = g.Where(x => x.Type == musicAlbumTypeName).Sum(x => x.Count),
+                        ArtistCount = g.Where(x => x.Type == musicArtistTypeName).Sum(x => x.Count),
+                        SongCount = g.Where(x => x.Type == audioTypeName).Sum(x => x.Count),
+                        TrailerCount = g.Where(x => x.Type == trailerTypeName).Sum(x => x.Count),
+                    });
+
+            result.StartIndex = filter.StartIndex ?? 0;
+            result.Items =
+            [
+                .. query
+                    .AsEnumerable()
+                    .Where(e => e is not null)
+                    .Select(e =>
+                    {
+                        var item = DeserializeBaseItem(e, filter.SkipDeserialization);
+                        countsByCleanName.TryGetValue(e.CleanName ?? string.Empty, out var itemCount);
+                        return (item, itemCount);
+                    })
+                    .Where(x => x.item is not null)
+                    .Select(x => (x.item!, x.itemCount))
+            ];
+        }
+        else
+        {
+            result.StartIndex = filter.StartIndex ?? 0;
+            result.Items =
+            [
+                .. query
+                    .AsEnumerable()
+                    .Where(e => e != null)
+                    .Select(e => DeserializeBaseItem(e, filter.SkipDeserialization))
+                    .Where(item => item != null)
+                    .Select(item => (item!, (ItemCounts?)null))
+            ];
+        }
+
+        return result;
+    }
+}

Jellyfin.Server.Implementations/Item/BaseItemRepository.QueryBuilding.cs

@@ -0,0 +1,541 @@
+#pragma warning disable RS0030 // Do not use banned APIs
+#pragma warning disable CA1304 // Specify CultureInfo
+#pragma warning disable CA1311 // Specify a culture or use an invariant version
+#pragma warning disable CA1862 // Use the 'StringComparison' method overloads to perform case-insensitive string comparisons
+
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using System.Linq.Expressions;
+using Jellyfin.Data.Enums;
+using Jellyfin.Database.Implementations;
+using Jellyfin.Database.Implementations.Entities;
+using Jellyfin.Database.Implementations.Enums;
+using Jellyfin.Extensions;
+using MediaBrowser.Controller.Entities;
+using MediaBrowser.Model.Entities;
+using MediaBrowser.Model.Querying;
+using Microsoft.EntityFrameworkCore;
+using BaseItemEntity = Jellyfin.Database.Implementations.Entities.BaseItemEntity;
+
+namespace Jellyfin.Server.Implementations.Item;
+
+public sealed partial class BaseItemRepository
+{
+    /// <inheritdoc />
+    public IQueryable<BaseItemEntity> PrepareItemQuery(JellyfinDbContext context, InternalItemsQuery filter)
+    {
+        IQueryable<BaseItemEntity> dbQuery = context.BaseItems.AsNoTracking();
+        dbQuery = dbQuery.AsSingleQuery();
+
+        return dbQuery;
+    }
+
+    private IQueryable<BaseItemEntity> ApplyQueryFilter(IQueryable<BaseItemEntity> dbQuery, JellyfinDbContext context, InternalItemsQuery filter)
+    {
+        dbQuery = TranslateQuery(dbQuery, context, filter);
+        dbQuery = ApplyGroupingFilter(context, dbQuery, filter);
+        dbQuery = ApplyQueryPaging(dbQuery, filter);
+        dbQuery = ApplyNavigations(dbQuery, filter);
+        return dbQuery;
+    }
+
+    private IQueryable<BaseItemEntity> ApplyQueryPaging(IQueryable<BaseItemEntity> dbQuery, InternalItemsQuery filter)
+    {
+        if (filter.Limit.HasValue || filter.StartIndex.HasValue)
+        {
+            var offset = filter.StartIndex ?? 0;
+
+            if (offset > 0)
+            {
+                dbQuery = dbQuery.Skip(offset);
+            }
+
+            if (filter.Limit.HasValue)
+            {
+                dbQuery = dbQuery.Take(filter.Limit.Value);
+            }
+        }
+
+        return dbQuery;
+    }
+
+    private IQueryable<BaseItemEntity> ApplyGroupingFilter(JellyfinDbContext context, IQueryable<BaseItemEntity> dbQuery, InternalItemsQuery filter)
+    {
+        // This whole block is needed to filter duplicate entries on request
+        // for the time being it cannot be used because it would destroy the ordering
+        // this results in "duplicate" responses for queries that try to lookup individual series or multiple versions but
+        // for that case the invoker has to run a DistinctBy(e => e.PresentationUniqueKey) on their own
+
+        var enableGroupByPresentationUniqueKey = EnableGroupByPresentationUniqueKey(filter);
+        if (enableGroupByPresentationUniqueKey && filter.GroupBySeriesPresentationUniqueKey)
+        {
+            var tempQuery = dbQuery.GroupBy(e => new { e.PresentationUniqueKey, e.SeriesPresentationUniqueKey }).Select(e => e.OrderBy(x => x.Id).FirstOrDefault()).Select(e => e!.Id);
+            dbQuery = context.BaseItems.Where(e => tempQuery.Contains(e.Id));
+        }
+        else if (enableGroupByPresentationUniqueKey)
+        {
+            var tempQuery = dbQuery.GroupBy(e => e.PresentationUniqueKey).Select(e => e.OrderBy(x => x.Id).FirstOrDefault()).Select(e => e!.Id);
+            dbQuery = context.BaseItems.Where(e => tempQuery.Contains(e.Id));
+        }
+        else if (filter.GroupBySeriesPresentationUniqueKey)
+        {
+            var tempQuery = dbQuery.GroupBy(e => e.SeriesPresentationUniqueKey).Select(e => e.OrderBy(x => x.Id).FirstOrDefault()).Select(e => e!.Id);
+            dbQuery = context.BaseItems.Where(e => tempQuery.Contains(e.Id));
+        }
+        else
+        {
+            dbQuery = dbQuery.Distinct();
+        }
+
+        if (filter.CollapseBoxSetItems == true)
+        {
+            dbQuery = ApplyBoxSetCollapsing(context, dbQuery, filter.CollapseBoxSetItemTypes);
+
+            // Apply name-range filters after collapse so BoxSets are filtered by their own name,
+            // not by their children's names.
+            dbQuery = ApplyNameFilters(dbQuery, filter);
+        }
+
+        dbQuery = ApplyOrder(dbQuery, filter, context);
+
+        return dbQuery;
+    }
+
+    private IQueryable<BaseItemEntity> ApplyBoxSetCollapsing(
+        JellyfinDbContext context,
+        IQueryable<BaseItemEntity> dbQuery,
+        BaseItemKind[] collapsibleTypes)
+    {
+        var boxSetTypeName = _itemTypeLookup.BaseItemKindNames[BaseItemKind.BoxSet];
+
+        var currentIds = dbQuery.Select(e => e.Id);
+
+        if (collapsibleTypes.Length == 0)
+        {
+            // Collapse all item types into box sets
+            return ApplyBoxSetCollapsingAll(context, currentIds, boxSetTypeName);
+        }
+
+        // Only collapse specific item types, keep others untouched
+        var collapsibleTypeNames = collapsibleTypes.Select(t => _itemTypeLookup.BaseItemKindNames[t]).ToList();
+
+        // Items whose type is NOT collapsible (always kept in results)
+        var nonCollapsibleIds = currentIds
+            .Where(id => !context.BaseItems.Any(bi => bi.Id == id && collapsibleTypeNames.Contains(bi.Type)));
+
+        // Collapsible items that are NOT in any box set (kept in results)
+        var collapsibleNotInBoxSet = currentIds
+            .Where(id =>
+                context.BaseItems.Any(bi => bi.Id == id && collapsibleTypeNames.Contains(bi.Type))
+                && !context.BaseItems.Any(bs => bs.Id == id && bs.Type == boxSetTypeName)
+                && !context.LinkedChildren.Any(lc =>
+                    lc.ChildId == id
+                    && lc.ChildType == Jellyfin.Database.Implementations.Entities.LinkedChildType.Manual
+                    && context.BaseItems.Any(bs => bs.Id == lc.ParentId && bs.Type == boxSetTypeName)));
+
+        // Box set IDs containing at least one accessible collapsible child item
+        var boxSetIds = context.LinkedChildren
+            .Where(lc =>
+                lc.ChildType == Jellyfin.Database.Implementations.Entities.LinkedChildType.Manual
+                && currentIds.Contains(lc.ChildId)
+                && context.BaseItems.Any(bi => bi.Id == lc.ChildId && collapsibleTypeNames.Contains(bi.Type))
+                && context.BaseItems.Any(bs => bs.Id == lc.ParentId && bs.Type == boxSetTypeName))
+            .Select(lc => lc.ParentId)
+            .Distinct();
+
+        var collapsedIds = nonCollapsibleIds.Union(collapsibleNotInBoxSet).Union(boxSetIds);
+        return context.BaseItems.Where(e => collapsedIds.Contains(e.Id));
+    }
+
+    private static IQueryable<BaseItemEntity> ApplyBoxSetCollapsingAll(
+        JellyfinDbContext context,
+        IQueryable<Guid> currentIds,
+        string boxSetTypeName)
+    {
+        // Items that are NOT box sets and NOT in any box set
+        var notInBoxSet = currentIds
+            .Where(id =>
+                !context.BaseItems.Any(bs => bs.Id == id && bs.Type == boxSetTypeName)
+                && !context.LinkedChildren.Any(lc =>
+                    lc.ChildId == id
+                    && lc.ChildType == Jellyfin.Database.Implementations.Entities.LinkedChildType.Manual
+                    && context.BaseItems.Any(bs => bs.Id == lc.ParentId && bs.Type == boxSetTypeName)));
+
+        // Box set IDs containing at least one accessible child item
+        var boxSetIds = context.LinkedChildren
+            .Where(lc =>
+                lc.ChildType == Jellyfin.Database.Implementations.Entities.LinkedChildType.Manual
+                && currentIds.Contains(lc.ChildId)
+                && context.BaseItems.Any(bs => bs.Id == lc.ParentId && bs.Type == boxSetTypeName))
+            .Select(lc => lc.ParentId)
+            .Distinct();
+
+        var collapsedIds = notInBoxSet.Union(boxSetIds);
+        return context.BaseItems.Where(e => collapsedIds.Contains(e.Id));
+    }
+
+    private static IQueryable<BaseItemEntity> ApplyNameFilters(IQueryable<BaseItemEntity> dbQuery, InternalItemsQuery filter)
+    {
+        if (!string.IsNullOrWhiteSpace(filter.NameStartsWith))
+        {
+            var nameStartsWithLower = filter.NameStartsWith.ToLowerInvariant();
+            dbQuery = dbQuery.Where(e => e.SortName!.ToLower().StartsWith(nameStartsWithLower));
+        }
+
+        if (!string.IsNullOrWhiteSpace(filter.NameStartsWithOrGreater))
+        {
+            var startsOrGreaterLower = filter.NameStartsWithOrGreater.ToLowerInvariant();
+            dbQuery = dbQuery.Where(e => e.SortName!.ToLower().CompareTo(startsOrGreaterLower) >= 0);
+        }
+
+        if (!string.IsNullOrWhiteSpace(filter.NameLessThan))
+        {
+            var lessThanLower = filter.NameLessThan.ToLowerInvariant();
+            dbQuery = dbQuery.Where(e => e.SortName!.ToLower().CompareTo(lessThanLower) < 0);
+        }
+
+        return dbQuery;
+    }
+
+    /// <inheritdoc />
+    public IQueryable<BaseItemEntity> ApplyNavigations(IQueryable<BaseItemEntity> dbQuery, InternalItemsQuery filter)
+    {
+        if (filter.TrailerTypes.Length > 0 || filter.IncludeItemTypes.Contains(BaseItemKind.Trailer))
+        {
+            dbQuery = dbQuery.Include(e => e.TrailerTypes);
+        }
+
+        if (filter.DtoOptions.ContainsField(ItemFields.ProviderIds))
+        {
+            dbQuery = dbQuery.Include(e => e.Provider);
+        }
+
+        if (filter.DtoOptions.ContainsField(ItemFields.Settings))
+        {
+            dbQuery = dbQuery.Include(e => e.LockedFields);
+        }
+
+        if (filter.DtoOptions.EnableUserData)
+        {
+            dbQuery = dbQuery.Include(e => e.UserData);
+        }
+
+        if (filter.DtoOptions.EnableImages)
+        {
+            dbQuery = dbQuery.Include(e => e.Images);
+        }
+
+        // Include LinkedChildEntities for container types and videos that use them
+        // (BoxSet, Playlist, CollectionFolder for manual linking; Video, Movie for alternate versions).
+        // When IncludeItemTypes is empty (any type may be returned), always include them to ensure
+        // LinkedChildren are loaded before items are saved back, preventing accidental deletion.
+        var linkedChildTypes = new[]
+        {
+            BaseItemKind.BoxSet,
+            BaseItemKind.Playlist,
+            BaseItemKind.CollectionFolder,
+            BaseItemKind.Video,
+            BaseItemKind.Movie
+        };
+        if (filter.IncludeItemTypes.Length == 0 || filter.IncludeItemTypes.Any(linkedChildTypes.Contains))
+        {
+            dbQuery = dbQuery.Include(e => e.LinkedChildEntities);
+        }
+
+        if (filter.IncludeExtras)
+        {
+            dbQuery = dbQuery.Include(e => e.Extras);
+        }
+
+        return dbQuery;
+    }
+
+    /// <inheritdoc />
+    public IQueryable<BaseItemEntity> ApplyOrder(IQueryable<BaseItemEntity> query, InternalItemsQuery filter, JellyfinDbContext context)
+    {
+        var orderBy = filter.OrderBy.Where(e => e.OrderBy != ItemSortBy.Default).ToArray();
+        var hasSearch = !string.IsNullOrEmpty(filter.SearchTerm);
+
+        // SeriesDatePlayed requires special handling to avoid correlated subqueries.
+        // Instead of running a MAX() subquery per-row in ORDER BY, we pre-aggregate
+        // max played dates per series in one query and left-join it.
+        if (!hasSearch && orderBy.Any(o => o.OrderBy == ItemSortBy.SeriesDatePlayed))
+        {
+            return ApplySeriesDatePlayedOrder(query, filter, context, orderBy);
+        }
+
+        IOrderedQueryable<BaseItemEntity>? orderedQuery = null;
+
+        if (hasSearch)
+        {
+            var relevanceExpression = OrderMapper.MapSearchRelevanceOrder(filter.SearchTerm!);
+            orderedQuery = query.OrderBy(relevanceExpression);
+        }
+
+        if (orderBy.Length > 0)
+        {
+            var firstOrdering = orderBy[0];
+            var expression = OrderMapper.MapOrderByField(firstOrdering.OrderBy, filter, context);
+
+            if (orderedQuery is null)
+            {
+                orderedQuery = firstOrdering.SortOrder == SortOrder.Ascending
+                    ? query.OrderBy(expression)
+                    : query.OrderByDescending(expression);
+            }
+            else
+            {
+                orderedQuery = firstOrdering.SortOrder == SortOrder.Ascending
+                    ? orderedQuery.ThenBy(expression)
+                    : orderedQuery.ThenByDescending(expression);
+            }
+
+            if (firstOrdering.OrderBy is ItemSortBy.Default or ItemSortBy.SortName)
+            {
+                orderedQuery = firstOrdering.SortOrder == SortOrder.Ascending
+                    ? orderedQuery.ThenBy(e => e.Name)
+                    : orderedQuery.ThenByDescending(e => e.Name);
+            }
+
+            foreach (var item in orderBy.Skip(1))
+            {
+                expression = OrderMapper.MapOrderByField(item.OrderBy, filter, context);
+                orderedQuery = item.SortOrder == SortOrder.Ascending
+                    ? orderedQuery.ThenBy(expression)
+                    : orderedQuery.ThenByDescending(expression);
+            }
+        }
+
+        if (orderedQuery is null)
+        {
+            return query.OrderBy(e => e.SortName);
+        }
+
+        // Add SortName as final tiebreaker
+        if (!hasSearch && (orderBy.Length == 0 || orderBy.All(o => o.OrderBy is not ItemSortBy.SortName and not ItemSortBy.Name)))
+        {
+            orderedQuery = orderedQuery.ThenBy(e => e.SortName);
+        }
+
+        return orderedQuery;
+    }
+
+    private IQueryable<BaseItemEntity> ApplySeriesDatePlayedOrder(
+        IQueryable<BaseItemEntity> query,
+        InternalItemsQuery filter,
+        JellyfinDbContext context,
+        (ItemSortBy OrderBy, SortOrder SortOrder)[] orderBy)
+    {
+        // Pre-aggregate max played date per series key in ONE query.
+        // This generates a single: SELECT SeriesPresentationUniqueKey, MAX(LastPlayedDate) ... GROUP BY
+        // instead of a correlated subquery per outer row.
+        IQueryable<UserData> userDataQuery = filter.User is not null
+            ? context.UserData.Where(ud => ud.UserId == filter.User.Id && ud.Played)
+            : context.UserData.Where(ud => ud.Played);
+
+        var seriesMaxDates = userDataQuery
+            .Join(
+                context.BaseItems,
+                ud => ud.ItemId,
+                bi => bi.Id,
+                (ud, bi) => new { bi.SeriesPresentationUniqueKey, ud.LastPlayedDate })
+            .Where(x => x.SeriesPresentationUniqueKey != null)
+            .GroupBy(x => x.SeriesPresentationUniqueKey)
+            .Select(g => new { SeriesKey = g.Key!, MaxDate = g.Max(x => x.LastPlayedDate) });
+
+        var joined = query.LeftJoin(
+            seriesMaxDates,
+            e => e.PresentationUniqueKey,
+            s => s.SeriesKey,
+            (e, s) => new { Item = e, MaxDate = s != null ? s.MaxDate : (DateTime?)null });
+
+        var seriesSort = orderBy.First(o => o.OrderBy == ItemSortBy.SeriesDatePlayed);
+
+        return seriesSort.SortOrder == SortOrder.Ascending
+            ? joined.OrderBy(x => x.MaxDate).ThenBy(x => x.Item.SortName).Select(x => x.Item)
+            : joined.OrderByDescending(x => x.MaxDate).ThenBy(x => x.Item.SortName).Select(x => x.Item);
+    }
+
+    /// <summary>
+    /// Builds a query for descendants of an ancestor with user access filtering applied.
+    /// Uses recursive CTE to traverse both hierarchical (AncestorIds) and linked (LinkedChildren) relationships.
+    /// </summary>
+    /// <inheritdoc />
+    public IQueryable<BaseItemEntity> BuildAccessFilteredDescendantsQuery(
+        JellyfinDbContext context,
+        InternalItemsQuery filter,
+        Guid ancestorId)
+    {
+        // Use recursive CTE to get all descendants (hierarchical and linked)
+        var allDescendantIds = DescendantQueryHelper.GetAllDescendantIds(context, ancestorId);
+
+        var baseQuery = context.BaseItems
+            .Where(b => allDescendantIds.Contains(b.Id) && !b.IsFolder && !b.IsVirtualItem);
+
+        return ApplyAccessFiltering(context, baseQuery, filter);
+    }
+
+    /// <summary>
+    /// Applies user access filtering to a query.
+    /// Includes TopParentIds, parental rating, and tag filtering.
+    /// </summary>
+    /// <inheritdoc />
+    public IQueryable<BaseItemEntity> ApplyAccessFiltering(
+        JellyfinDbContext context,
+        IQueryable<BaseItemEntity> baseQuery,
+        InternalItemsQuery filter)
+    {
+        // Apply TopParentIds filtering (library folder access)
+        if (filter.TopParentIds.Length > 0)
+        {
+            var topParentIds = filter.TopParentIds;
+            baseQuery = baseQuery.Where(e => topParentIds.Contains(e.TopParentId!.Value));
+        }
+
+        // Apply parental rating filtering
+        if (filter.MaxParentalRating is not null)
+        {
+            baseQuery = baseQuery.Where(BuildMaxParentalRatingFilter(context, filter.MaxParentalRating));
+        }
+
+        // Apply block unrated items filtering
+        if (filter.BlockUnratedItems.Length > 0)
+        {
+            var unratedItemTypes = filter.BlockUnratedItems.Select(f => f.ToString()).ToArray();
+            baseQuery = baseQuery.Where(e =>
+                e.InheritedParentalRatingValue != null || !unratedItemTypes.Contains(e.UnratedType));
+        }
+
+        // Apply excluded tags filtering (blocked tags)
+        if (filter.ExcludeInheritedTags.Length > 0)
+        {
+            var excludedTags = filter.ExcludeInheritedTags.Select(e => e.GetCleanValue()).ToArray();
+            baseQuery = baseQuery.Where(e =>
+                !context.ItemValuesMap.Any(f =>
+                    f.ItemValue.Type == ItemValueType.Tags
+                    && excludedTags.Contains(f.ItemValue.CleanValue)
+                    && (f.ItemId == e.Id
+                        || (e.SeriesId.HasValue && f.ItemId == e.SeriesId.Value)
+                        || e.Parents!.Any(p => f.ItemId == p.ParentItemId)
+                        || (e.TopParentId.HasValue && f.ItemId == e.TopParentId.Value))));
+        }
+
+        // Apply included tags filtering (allowed tags - item must have at least one)
+        if (filter.IncludeInheritedTags.Length > 0)
+        {
+            var includeTags = filter.IncludeInheritedTags.Select(e => e.GetCleanValue()).ToArray();
+            baseQuery = baseQuery.Where(e =>
+                context.ItemValuesMap.Any(f =>
+                    f.ItemValue.Type == ItemValueType.Tags
+                    && includeTags.Contains(f.ItemValue.CleanValue)
+                    && (f.ItemId == e.Id
+                        || (e.SeriesId.HasValue && f.ItemId == e.SeriesId.Value)
+                        || e.Parents!.Any(p => f.ItemId == p.ParentItemId)
+                        || (e.TopParentId.HasValue && f.ItemId == e.TopParentId.Value))));
+        }
+
+        return baseQuery;
+    }
+
+    /// <summary>
+    /// Builds a filter expression for max parental rating that handles both rated items
+    /// and unrated BoxSets/Playlists (which check linked children's ratings).
+    /// </summary>
+    private static Expression<Func<BaseItemEntity, bool>> BuildMaxParentalRatingFilter(
+        JellyfinDbContext context,
+        ParentalRatingScore maxRating)
+    {
+        var maxScore = maxRating.Score;
+        var maxSubScore = maxRating.SubScore ?? 0;
+        var linkedChildren = context.LinkedChildren;
+
+        return e =>
+            // Item has a rating: check against limit
+            (e.InheritedParentalRatingValue != null
+                && (e.InheritedParentalRatingValue < maxScore
+                    || (e.InheritedParentalRatingValue == maxScore && (e.InheritedParentalRatingSubValue ?? 0) <= maxSubScore)))
+            // Item has no rating
+            || (e.InheritedParentalRatingValue == null
+                && (
+                    // No linked children (not a BoxSet/Playlist): pass as unrated
+                    !linkedChildren.Any(lc => lc.ParentId == e.Id)
+                    // Has linked children: at least one child must be within limits
+                    || linkedChildren.Any(lc => lc.ParentId == e.Id
+                        && (lc.Child!.InheritedParentalRatingValue == null
+                            || lc.Child.InheritedParentalRatingValue < maxScore
+                            || (lc.Child.InheritedParentalRatingValue == maxScore
+                                && (lc.Child.InheritedParentalRatingSubValue ?? 0) <= maxSubScore)))));
+    }
+
+    private Dictionary<Guid, (int Played, int Total)> GetPlayedAndTotalCountBatch(IReadOnlyList<Guid> folderIds, User user)
+    {
+        ArgumentNullException.ThrowIfNull(folderIds);
+        ArgumentNullException.ThrowIfNull(user);
+
+        if (folderIds.Count == 0)
+        {
+            return new Dictionary<Guid, (int Played, int Total)>();
+        }
+
+        using var dbContext = _dbProvider.CreateDbContext();
+        var folderIdsArray = folderIds.ToArray();
+        var filter = new InternalItemsQuery(user);
+        var userId = user.Id;
+
+        var leafItems = dbContext.BaseItems
+            .Where(b => !b.IsFolder && !b.IsVirtualItem);
+        leafItems = ApplyAccessFiltering(dbContext, leafItems, filter);
+
+        var playedLeafItems = leafItems
+            .Select(b => new { b.Id, Played = b.UserData!.Any(ud => ud.UserId == userId && ud.Played) });
+
+        var ancestorLeaves = dbContext.AncestorIds
+            .WhereOneOrMany(folderIdsArray, a => a.ParentItemId)
+            .Join(
+                playedLeafItems,
+                a => a.ItemId,
+                b => b.Id,
+                (a, b) => new { FolderId = a.ParentItemId, b.Id, b.Played });
+
+        var linkedLeaves = dbContext.LinkedChildren
+            .WhereOneOrMany(folderIdsArray, lc => lc.ParentId)
+            .Join(
+                playedLeafItems,
+                lc => lc.ChildId,
+                b => b.Id,
+                (lc, b) => new { FolderId = lc.ParentId, b.Id, b.Played });
+
+        var linkedFolderLeaves = dbContext.LinkedChildren
+            .WhereOneOrMany(folderIdsArray, lc => lc.ParentId)
+            .Join(
+                dbContext.BaseItems.Where(b => b.IsFolder),
+                lc => lc.ChildId,
+                b => b.Id,
+                (lc, b) => new { lc.ParentId, FolderChildId = b.Id })
+            .Join(
+                dbContext.AncestorIds,
+                x => x.FolderChildId,
+                a => a.ParentItemId,
+                (x, a) => new { x.ParentId, DescendantId = a.ItemId })
+            .Join(
+                playedLeafItems,
+                x => x.DescendantId,
+                b => b.Id,
+                (x, b) => new { FolderId = x.ParentId, b.Id, b.Played });
+
+        var results = ancestorLeaves
+            .Union(linkedLeaves)
+            .Union(linkedFolderLeaves)
+            .GroupBy(x => x.FolderId)
+            .Select(g => new
+            {
+                FolderId = g.Key,
+                Total = g.Select(x => x.Id).Distinct().Count(),
+                Played = g.Where(x => x.Played).Select(x => x.Id).Distinct().Count()
+            })
+            .ToDictionary(x => x.FolderId, x => (x.Played, x.Total));
+
+        return results;
+    }
+}

Jellyfin.Server.Implementations/Item/BaseItemRepository.Querying.cs

@@ -0,0 +1,553 @@
+#pragma warning disable RS0030 // Do not use banned APIs
+
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using System.Linq.Expressions;
+using System.Threading.Tasks;
+using Jellyfin.Data.Enums;
+using Jellyfin.Database.Implementations;
+using Jellyfin.Database.Implementations.Entities;
+using Jellyfin.Extensions;
+using MediaBrowser.Controller.Entities;
+using MediaBrowser.Model.Querying;
+using Microsoft.EntityFrameworkCore;
+using BaseItemDto = MediaBrowser.Controller.Entities.BaseItem;
+
+namespace Jellyfin.Server.Implementations.Item;
+
+public sealed partial class BaseItemRepository
+{
+    /// <inheritdoc />
+    public IReadOnlyList<Guid> GetItemIdsList(InternalItemsQuery filter)
+    {
+        ArgumentNullException.ThrowIfNull(filter);
+        PrepareFilterQuery(filter);
+
+        using var context = _dbProvider.CreateDbContext();
+        return ApplyQueryFilter(context.BaseItems.AsNoTracking().Where(e => e.Id != EF.Constant(PlaceholderId)), context, filter).Select(e => e.Id).ToArray();
+    }
+
+    /// <inheritdoc />
+    public QueryResult<BaseItemDto> GetItems(InternalItemsQuery filter)
+    {
+        ArgumentNullException.ThrowIfNull(filter);
+        if (!filter.EnableTotalRecordCount || (!filter.Limit.HasValue && (filter.StartIndex ?? 0) == 0))
+        {
+            var returnList = GetItemList(filter);
+            return new QueryResult<BaseItemDto>(
+                filter.StartIndex,
+                returnList.Count,
+                returnList);
+        }
+
+        PrepareFilterQuery(filter);
+        var result = new QueryResult<BaseItemDto>();
+
+        using var context = _dbProvider.CreateDbContext();
+
+        IQueryable<BaseItemEntity> dbQuery = PrepareItemQuery(context, filter);
+
+        dbQuery = TranslateQuery(dbQuery, context, filter);
+        dbQuery = ApplyGroupingFilter(context, dbQuery, filter);
+
+        if (filter.EnableTotalRecordCount)
+        {
+            result.TotalRecordCount = dbQuery.Count();
+        }
+
+        dbQuery = ApplyQueryPaging(dbQuery, filter);
+        dbQuery = ApplyNavigations(dbQuery, filter);
+
+        result.Items = dbQuery.AsEnumerable().Where(e => e != null).Select(w => DeserializeBaseItem(w, filter.SkipDeserialization)).Where(dto => dto != null).ToArray()!;
+        result.StartIndex = filter.StartIndex ?? 0;
+        return result;
+    }
+
+    /// <inheritdoc />
+    public IReadOnlyList<BaseItemDto> GetItemList(InternalItemsQuery filter)
+    {
+        ArgumentNullException.ThrowIfNull(filter);
+        PrepareFilterQuery(filter);
+
+        using var context = _dbProvider.CreateDbContext();
+        IQueryable<BaseItemEntity> dbQuery = PrepareItemQuery(context, filter);
+
+        dbQuery = TranslateQuery(dbQuery, context, filter);
+
+        dbQuery = ApplyGroupingFilter(context, dbQuery, filter);
+        dbQuery = ApplyQueryPaging(dbQuery, filter);
+
+        var hasRandomSort = filter.OrderBy.Any(e => e.OrderBy == ItemSortBy.Random);
+        if (hasRandomSort)
+        {
+            var orderedIds = dbQuery.Select(e => e.Id).ToList();
+            if (orderedIds.Count == 0)
+            {
+                return Array.Empty<BaseItemDto>();
+            }
+
+            var itemsById = ApplyNavigations(context.BaseItems.Where(e => orderedIds.Contains(e.Id)), filter)
+                .AsEnumerable()
+                .Select(w => DeserializeBaseItem(w, filter.SkipDeserialization))
+                .Where(dto => dto != null)
+                .ToDictionary(i => i!.Id);
+
+            return orderedIds.Where(itemsById.ContainsKey).Select(id => itemsById[id]).ToArray()!;
+        }
+
+        dbQuery = ApplyNavigations(dbQuery, filter);
+
+        return dbQuery.AsEnumerable().Where(e => e != null).Select(w => DeserializeBaseItem(w, filter.SkipDeserialization)).Where(dto => dto != null).ToArray()!;
+    }
+
+    /// <inheritdoc/>
+    public IReadOnlyList<BaseItemDto> GetLatestItemList(InternalItemsQuery filter, CollectionType collectionType)
+    {
+        ArgumentNullException.ThrowIfNull(filter);
+        PrepareFilterQuery(filter);
+
+        // Early exit if collection type is not supported
+        if (collectionType is not CollectionType.movies and not CollectionType.tvshows and not CollectionType.music)
+        {
+            return [];
+        }
+
+        var limit = filter.Limit;
+        using var context = _dbProvider.CreateDbContext();
+
+        var baseQuery = PrepareItemQuery(context, filter);
+        baseQuery = TranslateQuery(baseQuery, context, filter);
+
+        if (collectionType == CollectionType.tvshows)
+        {
+            return GetLatestTvShowItems(context, baseQuery, filter, limit);
+        }
+
+        // Find the top N group keys ordered by most recent DateCreated.
+        // Movies group by PresentationUniqueKey (alternate versions like 4K/1080p share a key).
+        // Music groups by Album.
+        Expression<Func<BaseItemEntity, bool>> groupKeyFilter;
+        Expression<Func<BaseItemEntity, string?>> groupKeySelector;
+
+        if (collectionType is CollectionType.movies)
+        {
+            groupKeyFilter = e => e.PresentationUniqueKey != null;
+            groupKeySelector = e => e.PresentationUniqueKey;
+        }
+        else
+        {
+            groupKeyFilter = e => e.Album != null;
+            groupKeySelector = e => e.Album;
+        }
+
+        var topGroupKeys = baseQuery
+            .Where(groupKeyFilter)
+            .GroupBy(groupKeySelector)
+            .Select(g => new { GroupKey = g.Key!, MaxDate = g.Max(e => e.DateCreated) })
+            .OrderByDescending(g => g.MaxDate);
+
+        if (filter.Limit.HasValue)
+        {
+            topGroupKeys = topGroupKeys.Take(filter.Limit.Value).OrderByDescending(g => g.MaxDate);
+        }
+
+        // Get only the first (most recent) item ID per group using a lightweight projection,
+        // then fetch full entities only for those items. This avoids loading all versions/tracks
+        // with expensive navigation properties just to discard duplicates.
+        var topGroupKeyList = topGroupKeys.Select(g => g.GroupKey).ToList();
+        // ThenByDescending(Id) is a tiebreaker for deterministic ordering when multiple items
+        // share the same DateCreated timestamp — without it, SQL returns arbitrary order across queries.
+        var allItemsLite = collectionType switch
+        {
+            CollectionType.movies => baseQuery
+                .Where(e => e.PresentationUniqueKey != null && topGroupKeyList.Contains(e.PresentationUniqueKey))
+                .OrderByDescending(e => e.DateCreated)
+                .ThenByDescending(e => e.Id)
+                .Select(e => new { e.Id, GroupKey = e.PresentationUniqueKey })
+                .AsEnumerable(),
+            _ => baseQuery
+                .Where(e => e.Album != null && topGroupKeyList.Contains(e.Album))
+                .OrderByDescending(e => e.DateCreated)
+                .ThenByDescending(e => e.Id)
+                .Select(e => new { e.Id, GroupKey = e.Album })
+                .AsEnumerable()
+        };
+
+        // Client-side DistinctBy: EF Core/SQLite cannot reliably translate
+        // GroupBy(...).Select(g => g.First()) to SQL. The projection is lightweight
+        // (only Id + GroupKey for ~50 items), so client-side dedup is negligible.
+        var firstIds = allItemsLite
+            .DistinctBy(e => e.GroupKey)
+            .Select(e => e.Id)
+            .AsEnumerable();
+
+        var itemsQuery = context.BaseItems.AsNoTracking().Where(e => firstIds.Contains(e.Id));
+        itemsQuery = ApplyNavigations(itemsQuery, filter);
+
+        return itemsQuery
+            .OrderByDescending(e => e.DateCreated)
+            .ThenByDescending(e => e.Id)
+            .AsEnumerable()
+            .Select(w => DeserializeBaseItem(w, filter.SkipDeserialization))
+            .Where(dto => dto != null)
+            .ToArray()!;
+    }
+
+    /// <summary>
+    /// Gets the latest TV show items with smart Season/Series container selection.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// This method implements intelligent container selection for TV shows in the "Latest" section.
+    /// Instead of always showing individual episodes, it analyzes recent additions and may return
+    /// a Season or Series container when multiple related episodes were recently added.
+    /// </para>
+    /// <para>
+    /// The selection logic is:
+    /// <list type="bullet">
+    ///     <item>If recent episodes span multiple seasons → return the Series</item>
+    ///     <item>If multiple recent episodes are from one season AND the series has multiple seasons → return the Season</item>
+    ///     <item>If multiple recent episodes are from one season AND the series has only one season → return the Series</item>
+    ///     <item>Otherwise → return the most recent Episode</item>
+    /// </list>
+    /// </para>
+    /// </remarks>
+    /// <param name="context">The database context.</param>
+    /// <param name="baseQuery">The base query with filters already applied.</param>
+    /// <param name="filter">The query filter options.</param>
+    /// <param name="limit">Maximum number of items to return.</param>
+    /// <returns>A list of BaseItemDto representing the latest TV content.</returns>
+    private IReadOnlyList<BaseItemDto> GetLatestTvShowItems(JellyfinDbContext context, IQueryable<BaseItemEntity> baseQuery, InternalItemsQuery filter, int? limit)
+    {
+        // Episodes added within this window are considered "recently added together"
+        const double RecentAdditionWindowHours = 24.0;
+
+        // Step 1: Find the top N series with recently added content, ordered by most recent addition
+        var topSeriesWithDates = baseQuery
+            .Where(e => e.SeriesName != null)
+            .GroupBy(e => e.SeriesName)
+            .Select(g => new { SeriesName = g.Key!, MaxDate = g.Max(e => e.DateCreated) })
+            .OrderByDescending(g => g.MaxDate);
+
+        if (limit.HasValue)
+        {
+            topSeriesWithDates = topSeriesWithDates.Take(limit.Value).OrderByDescending(g => g.MaxDate);
+        }
+
+        var topSeriesNames = topSeriesWithDates.Select(g => g.SeriesName).AsEnumerable();
+
+        // Compute a global date cutoff: the oldest series' max date minus the window.
+        // Episodes before this cutoff cannot be in any series' "recent additions" window,
+        // so we can safely exclude them to avoid loading ancient episodes.
+        var globalCutoff = topSeriesWithDates.Any()
+            ? topSeriesWithDates.Min(g => g.MaxDate)?.AddHours(-RecentAdditionWindowHours)
+            : null;
+
+        // Fetch only the columns needed for analysis (lightweight projection).
+        var episodeQuery = baseQuery.Where(e => e.SeriesName != null && topSeriesNames.Contains(e.SeriesName));
+        if (globalCutoff is not null)
+        {
+            episodeQuery = episodeQuery.Where(e => e.DateCreated >= globalCutoff);
+        }
+
+        var allEpisodes = episodeQuery
+            .OrderByDescending(e => e.DateCreated)
+            .ThenByDescending(e => e.Id)
+            .Select(e => new { e.Id, e.SeriesName, e.DateCreated, e.SeasonId, e.SeriesId })
+            .AsEnumerable();
+
+        // Collect all season/series IDs we'll need to look up for count information
+        var allSeasonIds = new HashSet<Guid>();
+        var allSeriesIds = new HashSet<Guid>();
+
+        // Analysis data for each series: recent episode count, season IDs, and the most recent episode ID
+        var analysisData = new List<(
+            int RecentEpisodeCount,
+            List<Guid> SeasonIds,
+            Guid? FirstRecentSeriesId,
+            DateTime MaxDate,
+            Guid MostRecentEpisodeId)>();
+
+        // Step 3: Analyze each series to identify recent additions within the time window
+        foreach (var group in allEpisodes.GroupBy(e => e.SeriesName))
+        {
+            var episodes = group.ToList();
+            var mostRecentDate = episodes[0].DateCreated ?? DateTime.MinValue;
+            var recentCutoff = mostRecentDate.AddHours(-RecentAdditionWindowHours);
+
+            // Find episodes added within the recent window
+            var recentEpisodeCount = 0;
+            var seasonIdSet = new HashSet<Guid>();
+            Guid? firstRecentSeriesId = null;
+
+            foreach (var ep in episodes)
+            {
+                if (ep.DateCreated >= recentCutoff)
+                {
+                    recentEpisodeCount++;
+                    if (ep.SeasonId.HasValue)
+                    {
+                        seasonIdSet.Add(ep.SeasonId.Value);
+                    }
+
+                    firstRecentSeriesId ??= ep.SeriesId;
+                }
+            }
+
+            var seasonIds = seasonIdSet.ToList();
+            analysisData.Add((recentEpisodeCount, seasonIds, firstRecentSeriesId, mostRecentDate, episodes[0].Id));
+
+            // Track all unique season/series IDs for batch lookups
+            foreach (var sid in seasonIds)
+            {
+                allSeasonIds.Add(sid);
+            }
+
+            if (firstRecentSeriesId.HasValue)
+            {
+                allSeriesIds.Add(firstRecentSeriesId.Value);
+            }
+        }
+
+        // Step 4: Batch fetch counts - episodes per season and seasons per series
+        // These counts help determine whether to show Season or Series as the container
+        var episodeType = _itemTypeLookup.BaseItemKindNames[BaseItemKind.Episode];
+        var seasonType = _itemTypeLookup.BaseItemKindNames[BaseItemKind.Season];
+        var seasonEpisodeCounts = allSeasonIds.Count > 0
+            ? context.BaseItems
+                .AsNoTracking()
+                .Where(e => e.SeasonId.HasValue && allSeasonIds.Contains(e.SeasonId.Value) && e.Type == episodeType)
+                .GroupBy(e => e.SeasonId!.Value)
+                .Select(g => new { SeasonId = g.Key, Count = g.Count() })
+                .ToDictionary(x => x.SeasonId, x => x.Count)
+            : [];
+
+        var seriesSeasonCounts = allSeriesIds.Count > 0
+            ? context.BaseItems
+                .AsNoTracking()
+                .Where(e => e.SeriesId.HasValue && allSeriesIds.Contains(e.SeriesId.Value) && e.Type == seasonType)
+                .GroupBy(e => e.SeriesId!.Value)
+                .Select(g => new { SeriesId = g.Key, Count = g.Count() })
+                .ToDictionary(x => x.SeriesId, x => x.Count)
+            : [];
+
+        // Step 5: Apply the container selection logic for each series.
+        // For each series, decide which entity best represents the recent additions:
+        //   - 1 episode added → show the Episode itself
+        //   - Multiple episodes in 1 season (multi-season series) → show the Season
+        //   - Multiple episodes in 1 season (single-season series) → show the Series
+        //   - Episodes across multiple seasons → show the Series
+        var entitiesToFetch = new HashSet<Guid>();
+        var seriesResults = new List<(Guid? SeasonId, Guid? SeriesId, DateTime MaxDate, Guid MostRecentEpisodeId)>(analysisData.Count);
+
+        foreach (var (recentEpisodeCount, seasonIds, firstRecentSeriesId, maxDate, mostRecentEpisodeId) in analysisData)
+        {
+            Guid? seasonId = null;
+            Guid? seriesId = null;
+
+            if (seasonIds.Count == 1)
+            {
+                // All recent episodes are from a single season
+                var sid = seasonIds[0];
+                var totalEpisodes = seasonEpisodeCounts.GetValueOrDefault(sid, 0);
+                var totalSeasonsInSeries = firstRecentSeriesId.HasValue
+                    ? seriesSeasonCounts.GetValueOrDefault(firstRecentSeriesId.Value, 1)
+                    : 1;
+
+                // Check if multiple episodes were added, or if all episodes in the season were added
+                var hasMultipleOrAllEpisodes = recentEpisodeCount > 1 || recentEpisodeCount == totalEpisodes;
+
+                if (totalSeasonsInSeries > 1 && hasMultipleOrAllEpisodes)
+                {
+                    // Multi-season series with bulk additions: show the Season
+                    seasonId = sid;
+                    entitiesToFetch.Add(sid);
+                }
+                else if (hasMultipleOrAllEpisodes && firstRecentSeriesId.HasValue)
+                {
+                    // Single-season series with bulk additions: show the Series
+                    seriesId = firstRecentSeriesId;
+                    entitiesToFetch.Add(firstRecentSeriesId.Value);
+                }
+
+                // Otherwise: single episode, will fall through to show the Episode
+            }
+            else if (seasonIds.Count > 1 && firstRecentSeriesId.HasValue)
+            {
+                // Recent episodes span multiple seasons: show the Series
+                seriesId = firstRecentSeriesId;
+                entitiesToFetch.Add(seriesId!.Value);
+            }
+
+            if (seasonId is null && seriesId is null)
+            {
+                entitiesToFetch.Add(mostRecentEpisodeId);
+            }
+
+            seriesResults.Add((seasonId, seriesId, maxDate, mostRecentEpisodeId));
+        }
+
+        // Step 6: Fetch the Season/Series entities we decided to return
+        var entities = entitiesToFetch.Count > 0
+            ? ApplyNavigations(
+                    context.BaseItems.AsNoTracking().Where(e => entitiesToFetch.Contains(e.Id)),
+                    filter)
+                .AsSingleQuery()
+                .ToDictionary(e => e.Id)
+            : [];
+
+        // Step 7: Build final results, preferring Season > Series > Episode.
+        // All needed entities are already fetched in step 6 with navigation properties.
+        var results = new List<(BaseItemEntity Entity, DateTime MaxDate)>(seriesResults.Count);
+        foreach (var (seasonId, seriesId, maxDate, mostRecentEpisodeId) in seriesResults)
+        {
+            if (seasonId.HasValue && entities.TryGetValue(seasonId.Value, out var seasonEntity))
+            {
+                results.Add((seasonEntity, maxDate));
+                continue;
+            }
+
+            if (seriesId.HasValue && entities.TryGetValue(seriesId.Value, out var seriesEntity))
+            {
+                results.Add((seriesEntity, maxDate));
+                continue;
+            }
+
+            if (entities.TryGetValue(mostRecentEpisodeId, out var episodeEntity))
+            {
+                results.Add((episodeEntity, maxDate));
+            }
+        }
+
+        var finalResults = results
+            .OrderByDescending(r => r.MaxDate)
+            .ThenByDescending(r => r.Entity.Id);
+
+        if (limit.HasValue)
+        {
+            finalResults = finalResults
+            .Take(limit.Value)
+            .OrderByDescending(r => r.MaxDate)
+            .ThenByDescending(r => r.Entity.Id);
+        }
+
+        return finalResults
+            .Select(r => DeserializeBaseItem(r.Entity, filter.SkipDeserialization))
+            .Where(dto => dto is not null)
+            .ToArray()!;
+    }
+
+    /// <inheritdoc/>
+    public async Task<bool> ItemExistsAsync(Guid id)
+    {
+        var dbContext = await _dbProvider.CreateDbContextAsync().ConfigureAwait(false);
+        await using (dbContext.ConfigureAwait(false))
+        {
+            return await dbContext.BaseItems.AnyAsync(f => f.Id == id).ConfigureAwait(false);
+        }
+    }
+
+    /// <inheritdoc  />
+    public BaseItemDto? RetrieveItem(Guid id)
+    {
+        if (id.IsEmpty())
+        {
+            throw new ArgumentException("Guid can't be empty", nameof(id));
+        }
+
+        using var context = _dbProvider.CreateDbContext();
+        var dbQuery = PrepareItemQuery(context, new()
+        {
+            DtoOptions = new()
+            {
+                EnableImages = true
+            }
+        });
+        dbQuery = dbQuery.Include(e => e.TrailerTypes)
+            .Include(e => e.Provider)
+            .Include(e => e.LockedFields)
+            .Include(e => e.UserData)
+            .Include(e => e.Images)
+            .Include(e => e.LinkedChildEntities)
+            .AsSingleQuery();
+
+        var item = dbQuery.FirstOrDefault(e => e.Id == id);
+        if (item is null)
+        {
+            return null;
+        }
+
+        return DeserializeBaseItem(item);
+    }
+
+    /// <inheritdoc />
+    public bool GetIsPlayed(User user, Guid id, bool recursive)
+    {
+        using var dbContext = _dbProvider.CreateDbContext();
+
+        if (recursive)
+        {
+            var descendantIds = DescendantQueryHelper.GetAllDescendantIds(dbContext, id);
+
+            return dbContext.BaseItems
+                    .Where(e => descendantIds.Contains(e.Id) && !e.IsFolder && !e.IsVirtualItem)
+                    .All(f => f.UserData!.Any(e => e.UserId == user.Id && e.Played));
+        }
+
+        return dbContext.BaseItems.Where(e => e.ParentId == id).All(f => f.UserData!.Any(e => e.UserId == user.Id && e.Played));
+    }
+
+    /// <inheritdoc />
+    public QueryFiltersLegacy GetQueryFiltersLegacy(InternalItemsQuery filter)
+    {
+        ArgumentNullException.ThrowIfNull(filter);
+        PrepareFilterQuery(filter);
+
+        using var context = _dbProvider.CreateDbContext();
+        var baseQuery = PrepareItemQuery(context, filter);
+        baseQuery = TranslateQuery(baseQuery, context, filter);
+
+        var matchingItemIds = baseQuery.Select(e => e.Id);
+
+        var years = baseQuery
+            .Where(e => e.ProductionYear != null && e.ProductionYear > 0)
+            .Select(e => e.ProductionYear!.Value)
+            .Distinct()
+            .OrderBy(y => y)
+            .ToArray();
+
+        var officialRatings = baseQuery
+            .Where(e => e.OfficialRating != null && e.OfficialRating != string.Empty)
+            .Select(e => e.OfficialRating!)
+            .Distinct()
+            .OrderBy(r => r)
+            .ToArray();
+
+        var tags = context.ItemValuesMap
+            .Where(ivm => ivm.ItemValue.Type == ItemValueType.Tags)
+            .Where(ivm => matchingItemIds.Contains(ivm.ItemId))
+            .Select(ivm => ivm.ItemValue)
+            .GroupBy(iv => iv.CleanValue)
+            .Select(g => g.OrderBy(iv => iv.Value).First().Value)
+            .OrderBy(t => t)
+            .ToArray();
+
+        var genres = context.ItemValuesMap
+            .Where(ivm => ivm.ItemValue.Type == ItemValueType.Genre)
+            .Where(ivm => matchingItemIds.Contains(ivm.ItemId))
+            .Select(ivm => ivm.ItemValue)
+            .GroupBy(iv => iv.CleanValue)
+            .Select(g => g.OrderBy(iv => iv.Value).First().Value)
+            .OrderBy(g => g)
+            .ToArray();
+
+        return new QueryFiltersLegacy
+        {
+            Years = years,
+            OfficialRatings = officialRatings,
+            Tags = tags,
+            Genres = genres
+        };
+    }
+}

Jellyfin.Server.Implementations/Item/ItemCountService.cs

@@ -0,0 +1,427 @@
+#pragma warning disable RS0030 // Do not use banned APIs
+
+using System;
+using System.Collections.Generic;
+using System.Globalization;
+using System.Linq;
+using Jellyfin.Data.Enums;
+using Jellyfin.Database.Implementations;
+using Jellyfin.Database.Implementations.Entities;
+using Jellyfin.Extensions;
+using MediaBrowser.Controller.Entities;
+using MediaBrowser.Controller.Persistence;
+using MediaBrowser.Model.Dto;
+using Microsoft.EntityFrameworkCore;
+
+namespace Jellyfin.Server.Implementations.Item;
+
+/// <summary>
+/// Provides item counting and played-status query operations.
+/// </summary>
+public class ItemCountService : IItemCountService
+{
+    private readonly IDbContextFactory<JellyfinDbContext> _dbProvider;
+    private readonly IItemTypeLookup _itemTypeLookup;
+    private readonly IItemQueryHelpers _queryHelpers;
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="ItemCountService"/> class.
+    /// </summary>
+    /// <param name="dbProvider">The database context factory.</param>
+    /// <param name="itemTypeLookup">The item type lookup.</param>
+    /// <param name="queryHelpers">The shared query helpers.</param>
+    public ItemCountService(
+        IDbContextFactory<JellyfinDbContext> dbProvider,
+        IItemTypeLookup itemTypeLookup,
+        IItemQueryHelpers queryHelpers)
+    {
+        _dbProvider = dbProvider;
+        _itemTypeLookup = itemTypeLookup;
+        _queryHelpers = queryHelpers;
+    }
+
+    /// <inheritdoc/>
+    public int GetCount(InternalItemsQuery filter)
+    {
+        ArgumentNullException.ThrowIfNull(filter);
+        _queryHelpers.PrepareFilterQuery(filter);
+
+        using var context = _dbProvider.CreateDbContext();
+        var dbQuery = _queryHelpers.TranslateQuery(context.BaseItems.AsNoTracking(), context, filter);
+
+        return dbQuery.Count();
+    }
+
+    /// <inheritdoc />
+    public ItemCounts GetItemCounts(InternalItemsQuery filter)
+    {
+        ArgumentNullException.ThrowIfNull(filter);
+        _queryHelpers.PrepareFilterQuery(filter);
+
+        using var context = _dbProvider.CreateDbContext();
+        var dbQuery = _queryHelpers.TranslateQuery(context.BaseItems.AsNoTracking(), context, filter);
+
+        var counts = dbQuery
+            .GroupBy(x => x.Type)
+            .Select(x => new { x.Key, Count = x.Count() })
+            .ToArray();
+
+        var lookup = _itemTypeLookup.BaseItemKindNames;
+        var result = new ItemCounts
+        {
+            ItemCount = counts.Sum(c => c.Count)
+        };
+        foreach (var count in counts)
+        {
+            if (string.Equals(count.Key, lookup[BaseItemKind.MusicAlbum], StringComparison.Ordinal))
+            {
+                result.AlbumCount = count.Count;
+            }
+            else if (string.Equals(count.Key, lookup[BaseItemKind.MusicArtist], StringComparison.Ordinal))
+            {
+                result.ArtistCount = count.Count;
+            }
+            else if (string.Equals(count.Key, lookup[BaseItemKind.Episode], StringComparison.Ordinal))
+            {
+                result.EpisodeCount = count.Count;
+            }
+            else if (string.Equals(count.Key, lookup[BaseItemKind.Movie], StringComparison.Ordinal))
+            {
+                result.MovieCount = count.Count;
+            }
+            else if (string.Equals(count.Key, lookup[BaseItemKind.MusicVideo], StringComparison.Ordinal))
+            {
+                result.MusicVideoCount = count.Count;
+            }
+            else if (string.Equals(count.Key, lookup[BaseItemKind.LiveTvProgram], StringComparison.Ordinal))
+            {
+                result.ProgramCount = count.Count;
+            }
+            else if (string.Equals(count.Key, lookup[BaseItemKind.Series], StringComparison.Ordinal))
+            {
+                result.SeriesCount = count.Count;
+            }
+            else if (string.Equals(count.Key, lookup[BaseItemKind.Audio], StringComparison.Ordinal))
+            {
+                result.SongCount = count.Count;
+            }
+            else if (string.Equals(count.Key, lookup[BaseItemKind.Trailer], StringComparison.Ordinal))
+            {
+                result.TrailerCount = count.Count;
+            }
+            else if (string.Equals(count.Key, lookup[BaseItemKind.BoxSet], StringComparison.Ordinal))
+            {
+                result.BoxSetCount = count.Count;
+            }
+            else if (string.Equals(count.Key, lookup[BaseItemKind.Book], StringComparison.Ordinal))
+            {
+                result.BookCount = count.Count;
+            }
+        }
+
+        return result;
+    }
+
+    /// <inheritdoc />
+    public ItemCounts GetItemCountsForNameItem(BaseItemKind kind, Guid id, BaseItemKind[] relatedItemKinds, InternalItemsQuery accessFilter)
+    {
+        using var context = _dbProvider.CreateDbContext();
+
+        var item = context.BaseItems.AsNoTracking()
+            .Where(e => e.Id == id)
+            .Select(e => new { e.Name, e.CleanName })
+            .FirstOrDefault();
+
+        if (item is null)
+        {
+            return new ItemCounts();
+        }
+
+        IQueryable<BaseItemEntity> baseQuery;
+        switch (kind)
+        {
+            case BaseItemKind.Person:
+                baseQuery = context.PeopleBaseItemMap
+                    .AsNoTracking()
+                    .Where(m => m.People.Name == item.Name)
+                    .Select(m => m.Item);
+                break;
+            case BaseItemKind.MusicArtist:
+                baseQuery = context.ItemValuesMap
+                    .AsNoTracking()
+                    .Where(ivm => ivm.ItemValue.CleanValue == item.CleanName
+                        && (ivm.ItemValue.Type == ItemValueType.Artist || ivm.ItemValue.Type == ItemValueType.AlbumArtist))
+                    .Select(ivm => ivm.Item);
+                break;
+            case BaseItemKind.Genre:
+            case BaseItemKind.MusicGenre:
+                baseQuery = context.ItemValuesMap
+                    .AsNoTracking()
+                    .Where(ivm => ivm.ItemValue.CleanValue == item.CleanName
+                        && ivm.ItemValue.Type == ItemValueType.Genre)
+                    .Select(ivm => ivm.Item);
+                break;
+            case BaseItemKind.Studio:
+                baseQuery = context.ItemValuesMap
+                    .AsNoTracking()
+                    .Where(ivm => ivm.ItemValue.CleanValue == item.CleanName
+                        && ivm.ItemValue.Type == ItemValueType.Studios)
+                    .Select(ivm => ivm.Item);
+                break;
+            case BaseItemKind.Year:
+                if (int.TryParse(item.Name, NumberStyles.Integer, CultureInfo.InvariantCulture, out var year))
+                {
+                    baseQuery = context.BaseItems
+                        .AsNoTracking()
+                        .Where(e => e.ProductionYear == year);
+                }
+                else
+                {
+                    return new ItemCounts();
+                }
+
+                break;
+            default:
+                return new ItemCounts();
+        }
+
+        var typeNames = relatedItemKinds.Select(k => _itemTypeLookup.BaseItemKindNames[k]).ToArray();
+        baseQuery = baseQuery.Where(e => typeNames.Contains(e.Type));
+
+        baseQuery = _queryHelpers.ApplyAccessFiltering(context, baseQuery, accessFilter);
+
+        var counts = baseQuery
+            .GroupBy(x => x.Type)
+            .Select(x => new { x.Key, Count = x.Count() })
+            .ToArray();
+
+        var lookup = _itemTypeLookup.BaseItemKindNames;
+        var result = new ItemCounts();
+        var totalCount = 0;
+
+        foreach (var count in counts)
+        {
+            totalCount += count.Count;
+
+            if (string.Equals(count.Key, lookup[BaseItemKind.MusicAlbum], StringComparison.Ordinal))
+            {
+                result.AlbumCount = count.Count;
+            }
+            else if (string.Equals(count.Key, lookup[BaseItemKind.MusicArtist], StringComparison.Ordinal))
+            {
+                result.ArtistCount = count.Count;
+            }
+            else if (string.Equals(count.Key, lookup[BaseItemKind.Episode], StringComparison.Ordinal))
+            {
+                result.EpisodeCount = count.Count;
+            }
+            else if (string.Equals(count.Key, lookup[BaseItemKind.Movie], StringComparison.Ordinal))
+            {
+                result.MovieCount = count.Count;
+            }
+            else if (string.Equals(count.Key, lookup[BaseItemKind.MusicVideo], StringComparison.Ordinal))
+            {
+                result.MusicVideoCount = count.Count;
+            }
+            else if (string.Equals(count.Key, lookup[BaseItemKind.LiveTvProgram], StringComparison.Ordinal))
+            {
+                result.ProgramCount = count.Count;
+            }
+            else if (string.Equals(count.Key, lookup[BaseItemKind.Series], StringComparison.Ordinal))
+            {
+                result.SeriesCount = count.Count;
+            }
+            else if (string.Equals(count.Key, lookup[BaseItemKind.Audio], StringComparison.Ordinal))
+            {
+                result.SongCount = count.Count;
+            }
+            else if (string.Equals(count.Key, lookup[BaseItemKind.Trailer], StringComparison.Ordinal))
+            {
+                result.TrailerCount = count.Count;
+            }
+            else if (string.Equals(count.Key, lookup[BaseItemKind.BoxSet], StringComparison.Ordinal))
+            {
+                result.BoxSetCount = count.Count;
+            }
+            else if (string.Equals(count.Key, lookup[BaseItemKind.Book], StringComparison.Ordinal))
+            {
+                result.BookCount = count.Count;
+            }
+        }
+
+        result.ItemCount = totalCount;
+
+        return result;
+    }
+
+    /// <inheritdoc/>
+    public int GetPlayedCount(InternalItemsQuery filter, Guid ancestorId)
+    {
+        ArgumentNullException.ThrowIfNull(filter.User);
+        using var dbContext = _dbProvider.CreateDbContext();
+
+        var baseQuery = _queryHelpers.BuildAccessFilteredDescendantsQuery(dbContext, filter, ancestorId);
+        return baseQuery.Count(b => b.UserData!.Any(u => u.UserId == filter.User.Id && u.Played));
+    }
+
+    /// <inheritdoc/>
+    public int GetTotalCount(InternalItemsQuery filter, Guid ancestorId)
+    {
+        using var dbContext = _dbProvider.CreateDbContext();
+
+        var baseQuery = _queryHelpers.BuildAccessFilteredDescendantsQuery(dbContext, filter, ancestorId);
+        return baseQuery.Count();
+    }
+
+    /// <inheritdoc/>
+    public (int Played, int Total) GetPlayedAndTotalCount(InternalItemsQuery filter, Guid ancestorId)
+    {
+        ArgumentNullException.ThrowIfNull(filter);
+        ArgumentNullException.ThrowIfNull(filter.User);
+        using var dbContext = _dbProvider.CreateDbContext();
+
+        var baseQuery = _queryHelpers.BuildAccessFilteredDescendantsQuery(dbContext, filter, ancestorId);
+        return GetPlayedAndTotalCountFromQuery(baseQuery, filter.User.Id);
+    }
+
+    /// <inheritdoc/>
+    public (int Played, int Total) GetPlayedAndTotalCountFromLinkedChildren(InternalItemsQuery filter, Guid parentId)
+    {
+        ArgumentNullException.ThrowIfNull(filter);
+        ArgumentNullException.ThrowIfNull(filter.User);
+        using var dbContext = _dbProvider.CreateDbContext();
+
+        var allDescendantIds = DescendantQueryHelper.GetAllDescendantIds(dbContext, parentId);
+        var baseQuery = dbContext.BaseItems
+            .Where(b => allDescendantIds.Contains(b.Id) && !b.IsFolder && !b.IsVirtualItem);
+        baseQuery = _queryHelpers.ApplyAccessFiltering(dbContext, baseQuery, filter);
+
+        return GetPlayedAndTotalCountFromQuery(baseQuery, filter.User.Id);
+    }
+
+    /// <inheritdoc/>
+    public Dictionary<Guid, int> GetChildCountBatch(IReadOnlyList<Guid> parentIds, Guid? userId)
+    {
+        ArgumentNullException.ThrowIfNull(parentIds);
+
+        if (parentIds.Count == 0)
+        {
+            return new Dictionary<Guid, int>();
+        }
+
+        using var dbContext = _dbProvider.CreateDbContext();
+
+        var parentIdsArray = parentIds.ToArray();
+
+        var hierarchicalCounts = dbContext.BaseItems
+            .Where(b => b.ParentId.HasValue && parentIdsArray.Contains(b.ParentId.Value))
+            .GroupBy(b => b.ParentId!.Value)
+            .Select(g => new { ParentId = g.Key, Count = g.Count() })
+            .ToDictionary(x => x.ParentId, x => x.Count);
+
+        var linkedCounts = dbContext.LinkedChildren
+            .Where(lc => parentIdsArray.Contains(lc.ParentId))
+            .GroupBy(lc => lc.ParentId)
+            .Select(g => new { ParentId = g.Key, Count = g.Count() })
+            .ToDictionary(x => x.ParentId, x => x.Count);
+
+        var result = new Dictionary<Guid, int>();
+        foreach (var parentId in parentIds)
+        {
+            var hierarchicalCount = hierarchicalCounts.GetValueOrDefault(parentId, 0);
+            var linkedCount = linkedCounts.GetValueOrDefault(parentId, 0);
+
+            result[parentId] = linkedCount > 0 ? linkedCount : hierarchicalCount;
+        }
+
+        return result;
+    }
+
+    /// <inheritdoc/>
+    public Dictionary<Guid, (int Played, int Total)> GetPlayedAndTotalCountBatch(IReadOnlyList<Guid> folderIds, User user)
+    {
+        ArgumentNullException.ThrowIfNull(folderIds);
+        ArgumentNullException.ThrowIfNull(user);
+
+        if (folderIds.Count == 0)
+        {
+            return new Dictionary<Guid, (int Played, int Total)>();
+        }
+
+        using var dbContext = _dbProvider.CreateDbContext();
+        var folderIdsArray = folderIds.ToArray();
+        var filter = new InternalItemsQuery(user);
+        var userId = user.Id;
+
+        var leafItems = dbContext.BaseItems
+            .Where(b => !b.IsFolder && !b.IsVirtualItem);
+        leafItems = _queryHelpers.ApplyAccessFiltering(dbContext, leafItems, filter);
+
+        var playedLeafItems = leafItems
+            .Select(b => new { b.Id, Played = b.UserData!.Any(ud => ud.UserId == userId && ud.Played) });
+
+        var ancestorLeaves = dbContext.AncestorIds
+            .WhereOneOrMany(folderIdsArray, a => a.ParentItemId)
+            .Join(
+                playedLeafItems,
+                a => a.ItemId,
+                b => b.Id,
+                (a, b) => new { FolderId = a.ParentItemId, b.Id, b.Played });
+
+        var linkedLeaves = dbContext.LinkedChildren
+            .WhereOneOrMany(folderIdsArray, lc => lc.ParentId)
+            .Join(
+                playedLeafItems,
+                lc => lc.ChildId,
+                b => b.Id,
+                (lc, b) => new { FolderId = lc.ParentId, b.Id, b.Played });
+
+        var linkedFolderLeaves = dbContext.LinkedChildren
+            .WhereOneOrMany(folderIdsArray, lc => lc.ParentId)
+            .Join(
+                dbContext.BaseItems.Where(b => b.IsFolder),
+                lc => lc.ChildId,
+                b => b.Id,
+                (lc, b) => new { lc.ParentId, FolderChildId = b.Id })
+            .Join(
+                dbContext.AncestorIds,
+                x => x.FolderChildId,
+                a => a.ParentItemId,
+                (x, a) => new { x.ParentId, DescendantId = a.ItemId })
+            .Join(
+                playedLeafItems,
+                x => x.DescendantId,
+                b => b.Id,
+                (x, b) => new { FolderId = x.ParentId, b.Id, b.Played });
+
+        var results = ancestorLeaves
+            .Union(linkedLeaves)
+            .Union(linkedFolderLeaves)
+            .GroupBy(x => x.FolderId)
+            .Select(g => new
+            {
+                FolderId = g.Key,
+                Total = g.Select(x => x.Id).Distinct().Count(),
+                Played = g.Where(x => x.Played).Select(x => x.Id).Distinct().Count()
+            })
+            .ToDictionary(x => x.FolderId, x => (x.Played, x.Total));
+
+        return results;
+    }
+
+    private static (int Played, int Total) GetPlayedAndTotalCountFromQuery(IQueryable<BaseItemEntity> query, Guid userId)
+    {
+        var result = query
+            .Select(b => b.UserData!.Any(u => u.UserId == userId && u.Played))
+            .GroupBy(_ => 1)
+            .OrderBy(g => g.Key)
+            .Select(g => new
+            {
+                Total = g.Count(),
+                Played = g.Count(isPlayed => isPlayed)
+            })
+            .FirstOrDefault();
+
+        return result is null ? (0, 0) : (result.Played, result.Total);
+    }
+}

Jellyfin.Server.Implementations/Item/ItemPersistenceService.cs

@@ -0,0 +1,637 @@
+#pragma warning disable RS0030 // Do not use banned APIs
+
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using System.Threading;
+using System.Threading.Tasks;
+using Jellyfin.Database.Implementations;
+using Jellyfin.Database.Implementations.Entities;
+using Jellyfin.Extensions;
+using MediaBrowser.Controller;
+using MediaBrowser.Controller.Entities;
+using MediaBrowser.Controller.Entities.Audio;
+using MediaBrowser.Controller.Persistence;
+using MediaBrowser.Controller.Playlists;
+using Microsoft.EntityFrameworkCore;
+using Microsoft.Extensions.Logging;
+using BaseItemDto = MediaBrowser.Controller.Entities.BaseItem;
+using DbLinkedChildType = Jellyfin.Database.Implementations.Entities.LinkedChildType;
+using LinkedChildType = MediaBrowser.Controller.Entities.LinkedChildType;
+
+namespace Jellyfin.Server.Implementations.Item;
+
+/// <summary>
+/// Handles item persistence operations (save, delete, update).
+/// </summary>
+public class ItemPersistenceService : IItemPersistenceService
+{
+    private readonly IDbContextFactory<JellyfinDbContext> _dbProvider;
+    private readonly IServerApplicationHost _appHost;
+    private readonly ILogger<ItemPersistenceService> _logger;
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="ItemPersistenceService"/> class.
+    /// </summary>
+    /// <param name="dbProvider">The database context factory.</param>
+    /// <param name="appHost">The application host.</param>
+    /// <param name="logger">The logger.</param>
+    public ItemPersistenceService(
+        IDbContextFactory<JellyfinDbContext> dbProvider,
+        IServerApplicationHost appHost,
+        ILogger<ItemPersistenceService> logger)
+    {
+        _dbProvider = dbProvider;
+        _appHost = appHost;
+        _logger = logger;
+    }
+
+    /// <inheritdoc />
+    public void DeleteItem(params IReadOnlyList<Guid> ids)
+    {
+        if (ids is null || ids.Count == 0 || ids.Any(f => f.Equals(BaseItemRepository.PlaceholderId)))
+        {
+            throw new ArgumentException("Guid can't be empty or the placeholder id.", nameof(ids));
+        }
+
+        using var context = _dbProvider.CreateDbContext();
+        using var transaction = context.Database.BeginTransaction();
+
+        var date = (DateTime?)DateTime.UtcNow;
+
+        var descendantIds = DescendantQueryHelper.GetOwnedDescendantIdsBatch(context, ids);
+        foreach (var id in ids)
+        {
+            descendantIds.Add(id);
+        }
+
+        var extraIds = context.BaseItems
+            .Where(e => e.OwnerId.HasValue && descendantIds.Contains(e.OwnerId.Value))
+            .Select(e => e.Id)
+            .ToArray();
+
+        foreach (var extraId in extraIds)
+        {
+            descendantIds.Add(extraId);
+        }
+
+        var relatedItems = descendantIds.ToArray();
+
+        context.UserData
+            .Join(
+                context.UserData.WhereOneOrMany(relatedItems, e => e.ItemId),
+                placeholder => new { placeholder.UserId, placeholder.CustomDataKey },
+                userData => new { userData.UserId, userData.CustomDataKey },
+                (placeholder, userData) => placeholder)
+            .Where(e => e.ItemId == BaseItemRepository.PlaceholderId)
+            .ExecuteDelete();
+
+        context.UserData.WhereOneOrMany(relatedItems, e => e.ItemId)
+            .ExecuteUpdate(e => e
+                .SetProperty(f => f.RetentionDate, date)
+                .SetProperty(f => f.ItemId, BaseItemRepository.PlaceholderId));
+
+        context.AncestorIds.WhereOneOrMany(relatedItems, e => e.ItemId).ExecuteDelete();
+        context.AncestorIds.WhereOneOrMany(relatedItems, e => e.ParentItemId).ExecuteDelete();
+        context.AttachmentStreamInfos.WhereOneOrMany(relatedItems, e => e.ItemId).ExecuteDelete();
+        context.BaseItemImageInfos.WhereOneOrMany(relatedItems, e => e.ItemId).ExecuteDelete();
+        context.BaseItemMetadataFields.WhereOneOrMany(relatedItems, e => e.ItemId).ExecuteDelete();
+        context.BaseItemProviders.WhereOneOrMany(relatedItems, e => e.ItemId).ExecuteDelete();
+        context.BaseItemTrailerTypes.WhereOneOrMany(relatedItems, e => e.ItemId).ExecuteDelete();
+        context.Chapters.WhereOneOrMany(relatedItems, e => e.ItemId).ExecuteDelete();
+        context.CustomItemDisplayPreferences.WhereOneOrMany(relatedItems, e => e.ItemId).ExecuteDelete();
+        context.ItemDisplayPreferences.WhereOneOrMany(relatedItems, e => e.ItemId).ExecuteDelete();
+        context.ItemValues.Where(e => e.BaseItemsMap!.Count == 0).ExecuteDelete();
+        context.ItemValuesMap.WhereOneOrMany(relatedItems, e => e.ItemId).ExecuteDelete();
+        context.LinkedChildren.WhereOneOrMany(relatedItems, e => e.ParentId).ExecuteDelete();
+        context.LinkedChildren.WhereOneOrMany(relatedItems, e => e.ChildId).ExecuteDelete();
+        context.BaseItems.WhereOneOrMany(relatedItems, e => e.Id).ExecuteDelete();
+        context.KeyframeData.WhereOneOrMany(relatedItems, e => e.ItemId).ExecuteDelete();
+        context.MediaSegments.WhereOneOrMany(relatedItems, e => e.ItemId).ExecuteDelete();
+        context.MediaStreamInfos.WhereOneOrMany(relatedItems, e => e.ItemId).ExecuteDelete();
+        var query = context.PeopleBaseItemMap.WhereOneOrMany(relatedItems, e => e.ItemId).Select(f => f.PeopleId).Distinct().ToArray();
+        context.PeopleBaseItemMap.WhereOneOrMany(relatedItems, e => e.ItemId).ExecuteDelete();
+        context.Peoples.WhereOneOrMany(query, e => e.Id).Where(e => e.BaseItems!.Count == 0).ExecuteDelete();
+        context.TrickplayInfos.WhereOneOrMany(relatedItems, e => e.ItemId).ExecuteDelete();
+        context.SaveChanges();
+        transaction.Commit();
+    }
+
+    /// <inheritdoc />
+    public void UpdateInheritedValues()
+    {
+        using var context = _dbProvider.CreateDbContext();
+        using var transaction = context.Database.BeginTransaction();
+
+        context.ItemValuesMap.Where(e => e.ItemValue.Type == ItemValueType.InheritedTags).ExecuteDelete();
+        context.SaveChanges();
+
+        transaction.Commit();
+    }
+
+    /// <inheritdoc />
+    public void SaveItems(IReadOnlyList<BaseItemDto> items, CancellationToken cancellationToken)
+    {
+        UpdateOrInsertItems(items, cancellationToken);
+    }
+
+    /// <inheritdoc />
+    public async Task SaveImagesAsync(BaseItem item, CancellationToken cancellationToken = default)
+    {
+        ArgumentNullException.ThrowIfNull(item);
+
+        var images = item.ImageInfos.Select(e => BaseItemMapper.MapImageToEntity(item.Id, e)).ToArray();
+
+        var context = await _dbProvider.CreateDbContextAsync(cancellationToken).ConfigureAwait(false);
+        await using (context.ConfigureAwait(false))
+        {
+            if (!await context.BaseItems
+                .AnyAsync(bi => bi.Id == item.Id, cancellationToken)
+                .ConfigureAwait(false))
+            {
+                _logger.LogWarning("Unable to save ImageInfo for non existing BaseItem");
+                return;
+            }
+
+            await context.BaseItemImageInfos
+                .Where(e => e.ItemId == item.Id)
+                .ExecuteDeleteAsync(cancellationToken)
+                .ConfigureAwait(false);
+
+            await context.BaseItemImageInfos
+                .AddRangeAsync(images, cancellationToken)
+                .ConfigureAwait(false);
+
+            await context.SaveChangesAsync(cancellationToken).ConfigureAwait(false);
+        }
+    }
+
+    /// <inheritdoc />
+    public async Task ReattachUserDataAsync(BaseItemDto item, CancellationToken cancellationToken)
+    {
+        ArgumentNullException.ThrowIfNull(item);
+        cancellationToken.ThrowIfCancellationRequested();
+
+        var dbContext = await _dbProvider.CreateDbContextAsync(cancellationToken).ConfigureAwait(false);
+
+        await using (dbContext.ConfigureAwait(false))
+        {
+            var transaction = await dbContext.Database.BeginTransactionAsync(cancellationToken).ConfigureAwait(false);
+            await using (transaction.ConfigureAwait(false))
+            {
+                var userKeys = item.GetUserDataKeys().ToArray();
+                var retentionDate = (DateTime?)null;
+
+                await dbContext.UserData
+                    .Where(e => e.ItemId == BaseItemRepository.PlaceholderId)
+                    .Where(e => userKeys.Contains(e.CustomDataKey))
+                    .ExecuteUpdateAsync(
+                        e => e
+                            .SetProperty(f => f.ItemId, item.Id)
+                            .SetProperty(f => f.RetentionDate, retentionDate),
+                        cancellationToken).ConfigureAwait(false);
+
+                item.UserData = await dbContext.UserData
+                    .AsNoTracking()
+                    .Where(e => e.ItemId == item.Id)
+                    .ToArrayAsync(cancellationToken)
+                    .ConfigureAwait(false);
+
+                await transaction.CommitAsync(cancellationToken).ConfigureAwait(false);
+            }
+        }
+    }
+
+    private void UpdateOrInsertItems(IReadOnlyList<BaseItemDto> items, CancellationToken cancellationToken)
+    {
+        ArgumentNullException.ThrowIfNull(items);
+        cancellationToken.ThrowIfCancellationRequested();
+
+        var tuples = new List<(BaseItemDto Item, List<Guid>? AncestorIds, BaseItemDto TopParent, IEnumerable<string> UserDataKey, List<string> InheritedTags)>();
+        foreach (var item in items.GroupBy(e => e.Id).Select(e => e.Last()).Where(e => e.Id != BaseItemRepository.PlaceholderId))
+        {
+            var ancestorIds = item.SupportsAncestors ?
+                item.GetAncestorIds().Distinct().ToList() :
+                null;
+
+            var topParent = item.GetTopParent();
+
+            var userdataKey = item.GetUserDataKeys();
+            var inheritedTags = item.GetInheritedTags();
+
+            tuples.Add((item, ancestorIds, topParent, userdataKey, inheritedTags));
+        }
+
+        using var context = _dbProvider.CreateDbContext();
+        using var transaction = context.Database.BeginTransaction();
+
+        var ids = tuples.Select(f => f.Item.Id).ToArray();
+        var existingItems = context.BaseItems.Where(e => ids.Contains(e.Id)).Select(f => f.Id).ToArray();
+
+        foreach (var item in tuples)
+        {
+            var entity = BaseItemMapper.Map(item.Item, _appHost);
+            entity.TopParentId = item.TopParent?.Id;
+
+            if (!existingItems.Any(e => e == entity.Id))
+            {
+                context.BaseItems.Add(entity);
+            }
+            else
+            {
+                context.BaseItemProviders.Where(e => e.ItemId == entity.Id).ExecuteDelete();
+                context.BaseItemImageInfos.Where(e => e.ItemId == entity.Id).ExecuteDelete();
+                context.BaseItemMetadataFields.Where(e => e.ItemId == entity.Id).ExecuteDelete();
+
+                if (entity.Images is { Count: > 0 })
+                {
+                    context.BaseItemImageInfos.AddRange(entity.Images);
+                }
+
+                if (entity.LockedFields is { Count: > 0 })
+                {
+                    context.BaseItemMetadataFields.AddRange(entity.LockedFields);
+                }
+
+                context.BaseItems.Attach(entity).State = EntityState.Modified;
+            }
+        }
+
+        var itemValueMaps = tuples
+            .Select(e => (e.Item, Values: GetItemValuesToSave(e.Item, e.InheritedTags)))
+            .ToArray();
+        var allListedItemValues = itemValueMaps
+            .SelectMany(f => f.Values)
+            .Distinct()
+            .ToArray();
+        var existingValues = context.ItemValues
+            .Select(e => new
+            {
+                item = e,
+                Key = e.Type + "+" + e.Value
+            })
+            .Where(f => allListedItemValues.Select(e => $"{(int)e.MagicNumber}+{e.Value}").Contains(f.Key))
+            .Select(e => e.item)
+            .ToArray();
+        var missingItemValues = allListedItemValues.Except(existingValues.Select(f => (MagicNumber: f.Type, f.Value))).Select(f => new ItemValue()
+        {
+            CleanValue = f.Value.GetCleanValue(),
+            ItemValueId = Guid.NewGuid(),
+            Type = f.MagicNumber,
+            Value = f.Value
+        }).ToArray();
+        context.ItemValues.AddRange(missingItemValues);
+
+        var itemValuesStore = existingValues.Concat(missingItemValues).ToArray();
+        var valueMap = itemValueMaps
+            .Select(f => (f.Item, Values: f.Values.Select(e => itemValuesStore.First(g => g.Value == e.Value && g.Type == e.MagicNumber)).DistinctBy(e => e.ItemValueId).ToArray()))
+            .ToArray();
+
+        var mappedValues = context.ItemValuesMap.Where(e => ids.Contains(e.ItemId)).ToList();
+
+        foreach (var item in valueMap)
+        {
+            var itemMappedValues = mappedValues.Where(e => e.ItemId == item.Item.Id).ToList();
+            foreach (var itemValue in item.Values)
+            {
+                var existingItem = itemMappedValues.FirstOrDefault(f => f.ItemValueId == itemValue.ItemValueId);
+                if (existingItem is null)
+                {
+                    context.ItemValuesMap.Add(new ItemValueMap()
+                    {
+                        Item = null!,
+                        ItemId = item.Item.Id,
+                        ItemValue = null!,
+                        ItemValueId = itemValue.ItemValueId
+                    });
+                }
+                else
+                {
+                    itemMappedValues.Remove(existingItem);
+                }
+            }
+
+            context.ItemValuesMap.RemoveRange(itemMappedValues);
+        }
+
+        var itemsWithAncestors = tuples
+            .Where(t => t.Item.SupportsAncestors && t.AncestorIds != null)
+            .Select(t => t.Item.Id)
+            .ToList();
+
+        var allExistingAncestorIds = itemsWithAncestors.Count > 0
+            ? context.AncestorIds
+                .Where(e => itemsWithAncestors.Contains(e.ItemId))
+                .ToList()
+                .GroupBy(e => e.ItemId)
+                .ToDictionary(g => g.Key, g => g.ToList())
+            : new Dictionary<Guid, List<AncestorId>>();
+
+        var allRequestedAncestorIds = tuples
+            .Where(t => t.Item.SupportsAncestors && t.AncestorIds != null)
+            .SelectMany(t => t.AncestorIds!)
+            .Distinct()
+            .ToList();
+
+        var validAncestorIdsSet = allRequestedAncestorIds.Count > 0
+            ? context.BaseItems
+                .Where(e => allRequestedAncestorIds.Contains(e.Id))
+                .Select(f => f.Id)
+                .ToHashSet()
+            : new HashSet<Guid>();
+
+        foreach (var item in tuples)
+        {
+            if (item.Item.SupportsAncestors && item.AncestorIds != null)
+            {
+                var existingAncestorIds = allExistingAncestorIds.GetValueOrDefault(item.Item.Id) ?? new List<AncestorId>();
+                var validAncestorIds = item.AncestorIds.Where(id => validAncestorIdsSet.Contains(id)).ToArray();
+                foreach (var ancestorId in validAncestorIds)
+                {
+                    var existingAncestorId = existingAncestorIds.FirstOrDefault(e => e.ParentItemId == ancestorId);
+                    if (existingAncestorId is null)
+                    {
+                        context.AncestorIds.Add(new AncestorId()
+                        {
+                            ParentItemId = ancestorId,
+                            ItemId = item.Item.Id,
+                            Item = null!,
+                            ParentItem = null!
+                        });
+                    }
+                    else
+                    {
+                        existingAncestorIds.Remove(existingAncestorId);
+                    }
+                }
+
+                context.AncestorIds.RemoveRange(existingAncestorIds);
+            }
+        }
+
+        context.SaveChanges();
+
+        var folderIds = tuples
+            .Where(t => t.Item is Folder)
+            .Select(t => t.Item.Id)
+            .ToList();
+
+        var videoIds = tuples
+            .Where(t => t.Item is Video)
+            .Select(t => t.Item.Id)
+            .ToList();
+
+        var allLinkedChildrenByParent = new Dictionary<Guid, List<LinkedChildEntity>>();
+        if (folderIds.Count > 0 || videoIds.Count > 0)
+        {
+            var allParentIds = folderIds.Concat(videoIds).Distinct().ToList();
+            var allLinkedChildren = context.LinkedChildren
+                .Where(e => allParentIds.Contains(e.ParentId))
+                .ToList();
+
+            allLinkedChildrenByParent = allLinkedChildren
+                .GroupBy(e => e.ParentId)
+                .ToDictionary(g => g.Key, g => g.ToList());
+        }
+
+        foreach (var item in tuples)
+        {
+            if (item.Item is Folder folder)
+            {
+                var existingLinkedChildren = allLinkedChildrenByParent.GetValueOrDefault(item.Item.Id)?.ToList() ?? new List<LinkedChildEntity>();
+                if (folder.LinkedChildren.Length > 0)
+                {
+#pragma warning disable CS0618 // Type or member is obsolete - legacy path resolution for old data
+                    var pathsToResolve = folder.LinkedChildren
+                        .Where(lc => (!lc.ItemId.HasValue || lc.ItemId.Value.IsEmpty()) && !string.IsNullOrEmpty(lc.Path))
+                        .Select(lc => lc.Path)
+                        .Distinct()
+                        .ToList();
+
+                    var pathToIdMap = pathsToResolve.Count > 0
+                        ? context.BaseItems
+                            .Where(e => e.Path != null && pathsToResolve.Contains(e.Path))
+                            .Select(e => new { e.Path, e.Id })
+                            .GroupBy(e => e.Path!)
+                            .ToDictionary(g => g.Key, g => g.First().Id)
+                        : [];
+
+                    var resolvedChildren = new List<(LinkedChild Child, Guid ChildId)>();
+                    foreach (var linkedChild in folder.LinkedChildren)
+                    {
+                        var childItemId = linkedChild.ItemId;
+                        if (!childItemId.HasValue || childItemId.Value.IsEmpty())
+                        {
+                            if (!string.IsNullOrEmpty(linkedChild.Path) && pathToIdMap.TryGetValue(linkedChild.Path, out var resolvedId))
+                            {
+                                childItemId = resolvedId;
+                            }
+                        }
+#pragma warning restore CS0618
+
+                        if (childItemId.HasValue && !childItemId.Value.IsEmpty())
+                        {
+                            resolvedChildren.Add((linkedChild, childItemId.Value));
+                        }
+                    }
+
+                    resolvedChildren = resolvedChildren
+                        .GroupBy(c => c.ChildId)
+                        .Select(g => g.Last())
+                        .ToList();
+
+                    var childIdsToCheck = resolvedChildren.Select(c => c.ChildId).ToList();
+                    var existingChildIds = childIdsToCheck.Count > 0
+                        ? context.BaseItems
+                            .Where(e => childIdsToCheck.Contains(e.Id))
+                            .Select(e => e.Id)
+                            .ToHashSet()
+                        : [];
+
+                    var isPlaylist = folder is Playlist;
+                    var sortOrder = 0;
+                    foreach (var (linkedChild, childId) in resolvedChildren)
+                    {
+                        if (!existingChildIds.Contains(childId))
+                        {
+                            _logger.LogWarning(
+                                "Skipping LinkedChild for parent {ParentName} ({ParentId}): child item {ChildId} does not exist in database",
+                                item.Item.Name,
+                                item.Item.Id,
+                                childId);
+                            continue;
+                        }
+
+                        var existingLink = existingLinkedChildren.FirstOrDefault(e => e.ChildId == childId);
+                        if (existingLink is null)
+                        {
+                            context.LinkedChildren.Add(new LinkedChildEntity()
+                            {
+                                ParentId = item.Item.Id,
+                                ChildId = childId,
+                                ChildType = (DbLinkedChildType)linkedChild.Type,
+                                SortOrder = isPlaylist ? sortOrder : null
+                            });
+                        }
+                        else
+                        {
+                            existingLink.SortOrder = isPlaylist ? sortOrder : null;
+                            existingLink.ChildType = (DbLinkedChildType)linkedChild.Type;
+                            existingLinkedChildren.Remove(existingLink);
+                        }
+
+                        sortOrder++;
+                    }
+                }
+
+                if (existingLinkedChildren.Count > 0)
+                {
+                    context.LinkedChildren.RemoveRange(existingLinkedChildren);
+                }
+            }
+
+            if (item.Item is Video video)
+            {
+                var existingLinkedChildren = (allLinkedChildrenByParent.GetValueOrDefault(video.Id) ?? new List<LinkedChildEntity>())
+                    .Where(e => (int)e.ChildType == 2 || (int)e.ChildType == 3)
+                    .ToList();
+
+                var newLinkedChildren = new List<(Guid ChildId, LinkedChildType Type)>();
+
+                if (video.LocalAlternateVersions.Length > 0)
+                {
+                    var pathsToResolve = video.LocalAlternateVersions.Where(p => !string.IsNullOrEmpty(p)).ToList();
+                    if (pathsToResolve.Count > 0)
+                    {
+                        var pathToIdMap = context.BaseItems
+                            .Where(e => e.Path != null && pathsToResolve.Contains(e.Path))
+                            .Select(e => new { e.Path, e.Id })
+                            .GroupBy(e => e.Path!)
+                            .ToDictionary(g => g.Key, g => g.First().Id);
+
+                        foreach (var path in pathsToResolve)
+                        {
+                            if (pathToIdMap.TryGetValue(path, out var childId))
+                            {
+                                newLinkedChildren.Add((childId, LinkedChildType.LocalAlternateVersion));
+                            }
+                        }
+                    }
+                }
+
+                if (video.LinkedAlternateVersions.Length > 0)
+                {
+                    foreach (var linkedChild in video.LinkedAlternateVersions)
+                    {
+                        if (linkedChild.ItemId.HasValue && !linkedChild.ItemId.Value.IsEmpty())
+                        {
+                            newLinkedChildren.Add((linkedChild.ItemId.Value, LinkedChildType.LinkedAlternateVersion));
+                        }
+                    }
+                }
+
+                newLinkedChildren = newLinkedChildren
+                    .GroupBy(c => c.ChildId)
+                    .Select(g => g.Last())
+                    .ToList();
+
+                var childIdsToCheck = newLinkedChildren.Select(c => c.ChildId).ToList();
+                var existingChildIds = childIdsToCheck.Count > 0
+                    ? context.BaseItems
+                        .Where(e => childIdsToCheck.Contains(e.Id))
+                        .Select(e => e.Id)
+                        .ToHashSet()
+                    : [];
+
+                int sortOrder = 0;
+                foreach (var (childId, childType) in newLinkedChildren)
+                {
+                    if (!existingChildIds.Contains(childId))
+                    {
+                        _logger.LogWarning(
+                            "Skipping alternate version for video {VideoName} ({VideoId}): child item {ChildId} does not exist in database",
+                            video.Name,
+                            video.Id,
+                            childId);
+                        continue;
+                    }
+
+                    var existingLink = existingLinkedChildren.FirstOrDefault(e => e.ChildId == childId);
+                    if (existingLink is null)
+                    {
+                        context.LinkedChildren.Add(new LinkedChildEntity
+                        {
+                            ParentId = video.Id,
+                            ChildId = childId,
+                            ChildType = (DbLinkedChildType)childType,
+                            SortOrder = sortOrder
+                        });
+                    }
+                    else
+                    {
+                        existingLink.ChildType = (DbLinkedChildType)childType;
+                        existingLink.SortOrder = sortOrder;
+                        existingLinkedChildren.Remove(existingLink);
+                    }
+
+                    sortOrder++;
+                }
+
+                if (existingLinkedChildren.Count > 0)
+                {
+                    var orphanedLocalVersionIds = existingLinkedChildren
+                        .Where(e => e.ChildType == DbLinkedChildType.LocalAlternateVersion)
+                        .Select(e => e.ChildId)
+                        .ToList();
+
+                    context.LinkedChildren.RemoveRange(existingLinkedChildren);
+
+                    if (orphanedLocalVersionIds.Count > 0)
+                    {
+                        var orphanedItems = context.BaseItems
+                            .Where(e => orphanedLocalVersionIds.Contains(e.Id) && e.OwnerId == video.Id)
+                            .ToList();
+
+                        if (orphanedItems.Count > 0)
+                        {
+                            _logger.LogInformation(
+                                "Deleting {Count} orphaned LocalAlternateVersion items for video {VideoName} ({VideoId})",
+                                orphanedItems.Count,
+                                video.Name,
+                                video.Id);
+                            context.BaseItems.RemoveRange(orphanedItems);
+                        }
+                    }
+                }
+            }
+        }
+
+        context.SaveChanges();
+        transaction.Commit();
+    }
+
+    private static List<(ItemValueType MagicNumber, string Value)> GetItemValuesToSave(BaseItemDto item, List<string> inheritedTags)
+    {
+        var list = new List<(ItemValueType, string)>();
+
+        if (item is IHasArtist hasArtist)
+        {
+            list.AddRange(hasArtist.Artists.Select(i => ((ItemValueType)0, i)));
+        }
+
+        if (item is IHasAlbumArtist hasAlbumArtist)
+        {
+            list.AddRange(hasAlbumArtist.AlbumArtists.Select(i => (ItemValueType.AlbumArtist, i)));
+        }
+
+        list.AddRange(item.Genres.Select(i => (ItemValueType.Genre, i)));
+        list.AddRange(item.Studios.Select(i => (ItemValueType.Studios, i)));
+        list.AddRange(item.Tags.Select(i => (ItemValueType.Tags, i)));
+
+        list.AddRange(inheritedTags.Select(i => (ItemValueType.InheritedTags, i)));
+
+        list.RemoveAll(i => string.IsNullOrWhiteSpace(i.Item2));
+
+        return list;
+    }
+}

Jellyfin.Server.Implementations/Item/LinkedChildrenService.cs

@@ -0,0 +1,160 @@
+#pragma warning disable RS0030 // Do not use banned APIs
+
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using Jellyfin.Data.Enums;
+using Jellyfin.Database.Implementations;
+using MediaBrowser.Controller.Entities.Audio;
+using MediaBrowser.Controller.Persistence;
+using Microsoft.EntityFrameworkCore;
+using DbLinkedChildType = Jellyfin.Database.Implementations.Entities.LinkedChildType;
+using LinkedChildType = MediaBrowser.Controller.Entities.LinkedChildType;
+
+namespace Jellyfin.Server.Implementations.Item;
+
+/// <summary>
+/// Provides linked children query and manipulation operations.
+/// </summary>
+public class LinkedChildrenService : ILinkedChildrenService
+{
+    private readonly IDbContextFactory<JellyfinDbContext> _dbProvider;
+    private readonly IItemTypeLookup _itemTypeLookup;
+    private readonly IItemQueryHelpers _queryHelpers;
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="LinkedChildrenService"/> class.
+    /// </summary>
+    /// <param name="dbProvider">The database context factory.</param>
+    /// <param name="itemTypeLookup">The item type lookup.</param>
+    /// <param name="queryHelpers">The shared query helpers.</param>
+    public LinkedChildrenService(
+        IDbContextFactory<JellyfinDbContext> dbProvider,
+        IItemTypeLookup itemTypeLookup,
+        IItemQueryHelpers queryHelpers)
+    {
+        _dbProvider = dbProvider;
+        _itemTypeLookup = itemTypeLookup;
+        _queryHelpers = queryHelpers;
+    }
+
+    /// <inheritdoc/>
+    public IReadOnlyList<Guid> GetLinkedChildrenIds(Guid parentId, int? childType = null)
+    {
+        using var dbContext = _dbProvider.CreateDbContext();
+
+        var query = dbContext.LinkedChildren
+            .Where(lc => lc.ParentId.Equals(parentId));
+
+        if (childType.HasValue)
+        {
+            query = query.Where(lc => (int)lc.ChildType == childType.Value);
+        }
+
+        return query
+            .OrderBy(lc => lc.SortOrder)
+            .Select(lc => lc.ChildId)
+            .ToList();
+    }
+
+    /// <inheritdoc/>
+    public IReadOnlyDictionary<string, MusicArtist[]> FindArtists(IReadOnlyList<string> artistNames)
+    {
+        using var dbContext = _dbProvider.CreateDbContext();
+
+        var artists = dbContext.BaseItems.Where(e => e.Type == _itemTypeLookup.BaseItemKindNames[BaseItemKind.MusicArtist]!)
+            .Where(e => artistNames.Contains(e.Name))
+            .ToArray();
+
+        var lookup = artists
+            .GroupBy(e => e.Name!)
+            .ToDictionary(
+                g => g.Key,
+                g => g.Select(f => _queryHelpers.DeserializeBaseItem(f)).Where(dto => dto is not null).Cast<MusicArtist>().ToArray());
+
+        var result = new Dictionary<string, MusicArtist[]>(artistNames.Count);
+        foreach (var name in artistNames)
+        {
+            if (lookup.TryGetValue(name, out var artistArray))
+            {
+                result[name] = artistArray;
+            }
+        }
+
+        return result;
+    }
+
+    /// <inheritdoc/>
+    public IReadOnlyList<Guid> GetManualLinkedParentIds(Guid childId)
+    {
+        using var context = _dbProvider.CreateDbContext();
+        return context.LinkedChildren
+            .Where(lc => lc.ChildId == childId && lc.ChildType == DbLinkedChildType.Manual)
+            .Select(lc => lc.ParentId)
+            .Distinct()
+            .ToList();
+    }
+
+    /// <inheritdoc/>
+    public IReadOnlyList<Guid> RerouteLinkedChildren(Guid fromChildId, Guid toChildId)
+    {
+        using var context = _dbProvider.CreateDbContext();
+
+        var affectedParentIds = context.LinkedChildren
+            .Where(lc => lc.ChildId == fromChildId && lc.ChildType == DbLinkedChildType.Manual)
+            .Select(lc => lc.ParentId)
+            .Distinct()
+            .ToList();
+
+        if (affectedParentIds.Count == 0)
+        {
+            return affectedParentIds;
+        }
+
+        var parentsWithTarget = context.LinkedChildren
+            .Where(lc => lc.ChildId == toChildId && lc.ChildType == DbLinkedChildType.Manual)
+            .Select(lc => lc.ParentId)
+            .ToHashSet();
+
+        context.LinkedChildren
+            .Where(lc => lc.ChildId == fromChildId
+                && lc.ChildType == DbLinkedChildType.Manual
+                && !parentsWithTarget.Contains(lc.ParentId))
+            .ExecuteUpdate(s => s.SetProperty(e => e.ChildId, toChildId));
+
+        context.LinkedChildren
+            .Where(lc => lc.ChildId == fromChildId
+                && lc.ChildType == DbLinkedChildType.Manual
+                && parentsWithTarget.Contains(lc.ParentId))
+            .ExecuteDelete();
+
+        return affectedParentIds;
+    }
+
+    /// <inheritdoc/>
+    public void UpsertLinkedChild(Guid parentId, Guid childId, LinkedChildType childType)
+    {
+        using var context = _dbProvider.CreateDbContext();
+
+        var dbChildType = (DbLinkedChildType)childType;
+        var existingLink = context.LinkedChildren
+            .FirstOrDefault(lc => lc.ParentId == parentId && lc.ChildId == childId);
+
+        if (existingLink is null)
+        {
+            context.LinkedChildren.Add(new Jellyfin.Database.Implementations.Entities.LinkedChildEntity
+            {
+                ParentId = parentId,
+                ChildId = childId,
+                ChildType = dbChildType,
+                SortOrder = null
+            });
+        }
+        else
+        {
+            existingLink.ChildType = dbChildType;
+        }
+
+        context.SaveChanges();
+    }
+}

Jellyfin.Server.Implementations/Item/NextUpService.cs

@@ -0,0 +1,345 @@
+#pragma warning disable RS0030 // Do not use banned APIs
+
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using Jellyfin.Data.Enums;
+using Jellyfin.Database.Implementations;
+using Jellyfin.Database.Implementations.Entities;
+using MediaBrowser.Controller.Entities;
+using MediaBrowser.Controller.Persistence;
+using Microsoft.EntityFrameworkCore;
+using BaseItemDto = MediaBrowser.Controller.Entities.BaseItem;
+
+namespace Jellyfin.Server.Implementations.Item;
+
+/// <summary>
+/// Provides next-up episode query operations.
+/// </summary>
+public class NextUpService : INextUpService
+{
+    private readonly IDbContextFactory<JellyfinDbContext> _dbProvider;
+    private readonly IItemTypeLookup _itemTypeLookup;
+    private readonly IItemQueryHelpers _queryHelpers;
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="NextUpService"/> class.
+    /// </summary>
+    /// <param name="dbProvider">The database context factory.</param>
+    /// <param name="itemTypeLookup">The item type lookup.</param>
+    /// <param name="queryHelpers">The shared query helpers.</param>
+    public NextUpService(
+        IDbContextFactory<JellyfinDbContext> dbProvider,
+        IItemTypeLookup itemTypeLookup,
+        IItemQueryHelpers queryHelpers)
+    {
+        _dbProvider = dbProvider;
+        _itemTypeLookup = itemTypeLookup;
+        _queryHelpers = queryHelpers;
+    }
+
+    /// <inheritdoc />
+    public IReadOnlyList<string> GetNextUpSeriesKeys(InternalItemsQuery filter, DateTime dateCutoff)
+    {
+        ArgumentNullException.ThrowIfNull(filter);
+        ArgumentNullException.ThrowIfNull(filter.User);
+
+        using var context = _dbProvider.CreateDbContext();
+
+        var query = context.BaseItems
+            .AsNoTracking()
+            .Where(i => filter.TopParentIds.Contains(i.TopParentId!.Value))
+            .Where(i => i.Type == _itemTypeLookup.BaseItemKindNames[BaseItemKind.Episode])
+            .Join(
+                context.UserData.AsNoTracking().Where(e => e.ItemId != EF.Constant(BaseItemRepository.PlaceholderId)),
+                i => new { UserId = filter.User.Id, ItemId = i.Id },
+                u => new { u.UserId, u.ItemId },
+                (entity, data) => new { Item = entity, UserData = data })
+            .GroupBy(g => g.Item.SeriesPresentationUniqueKey)
+            .Select(g => new { g.Key, LastPlayedDate = g.Max(u => u.UserData.LastPlayedDate) })
+            .Where(g => g.Key != null && g.LastPlayedDate != null && g.LastPlayedDate >= dateCutoff)
+            .OrderByDescending(g => g.LastPlayedDate)
+            .Select(g => g.Key!);
+
+        if (filter.Limit.HasValue)
+        {
+            query = query.Take(filter.Limit.Value);
+        }
+
+        return query.ToArray();
+    }
+
+    /// <inheritdoc />
+    public IReadOnlyDictionary<string, NextUpEpisodeBatchResult> GetNextUpEpisodesBatch(
+        InternalItemsQuery filter,
+        IReadOnlyList<string> seriesKeys,
+        bool includeSpecials,
+        bool includeWatchedForRewatching)
+    {
+        ArgumentNullException.ThrowIfNull(filter);
+        ArgumentNullException.ThrowIfNull(filter.User);
+
+        if (seriesKeys.Count == 0)
+        {
+            return new Dictionary<string, NextUpEpisodeBatchResult>();
+        }
+
+        _queryHelpers.PrepareFilterQuery(filter);
+        using var context = _dbProvider.CreateDbContext();
+
+        var userId = filter.User.Id;
+        var episodeTypeName = _itemTypeLookup.BaseItemKindNames[BaseItemKind.Episode];
+
+        var lastWatchedBase = context.BaseItems
+            .AsNoTracking()
+            .Where(e => e.Type == episodeTypeName)
+            .Where(e => e.SeriesPresentationUniqueKey != null && seriesKeys.Contains(e.SeriesPresentationUniqueKey))
+            .Where(e => e.ParentIndexNumber != 0)
+            .Where(e => e.UserData!.Any(ud => ud.UserId == userId && ud.Played));
+        lastWatchedBase = _queryHelpers.ApplyAccessFiltering(context, lastWatchedBase, filter);
+        var lastWatchedInfo = lastWatchedBase
+            .GroupBy(e => e.SeriesPresentationUniqueKey)
+            .Select(g => new
+            {
+                SeriesKey = g.Key!,
+                LastWatchedId = g.OrderByDescending(e => e.ParentIndexNumber)
+                                 .ThenByDescending(e => e.IndexNumber)
+                                 .Select(e => e.Id)
+                                 .FirstOrDefault()
+            })
+            .ToDictionary(x => x.SeriesKey, x => x.LastWatchedId);
+
+        Dictionary<string, Guid> lastWatchedByDateInfo = new();
+        if (includeWatchedForRewatching)
+        {
+            var lastWatchedByDateBase = context.BaseItems
+                .AsNoTracking()
+                .Where(e => e.Type == episodeTypeName)
+                .Where(e => e.SeriesPresentationUniqueKey != null && seriesKeys.Contains(e.SeriesPresentationUniqueKey))
+                .Where(e => e.ParentIndexNumber != 0)
+                .Where(e => e.UserData!.Any(ud => ud.UserId == userId && ud.Played));
+            lastWatchedByDateBase = _queryHelpers.ApplyAccessFiltering(context, lastWatchedByDateBase, filter);
+            lastWatchedByDateInfo = lastWatchedByDateBase
+                .SelectMany(e => e.UserData!.Where(ud => ud.UserId == userId && ud.Played)
+                    .Select(ud => new { Episode = e, ud.LastPlayedDate }))
+                .GroupBy(x => x.Episode.SeriesPresentationUniqueKey)
+                .Select(g => new
+                {
+                    SeriesKey = g.Key!,
+                    LastWatchedId = g.OrderByDescending(x => x.LastPlayedDate)
+                                     .Select(x => x.Episode.Id)
+                                     .FirstOrDefault()
+                })
+                .ToDictionary(x => x.SeriesKey, x => x.LastWatchedId);
+        }
+
+        var allLastWatchedIds = lastWatchedInfo.Values
+            .Concat(lastWatchedByDateInfo.Values)
+            .Where(id => id != Guid.Empty)
+            .Distinct()
+            .ToList();
+        var lastWatchedEpisodes = new Dictionary<Guid, BaseItemEntity>();
+        if (allLastWatchedIds.Count > 0)
+        {
+            var lwQuery = context.BaseItems.AsNoTracking().Where(e => allLastWatchedIds.Contains(e.Id));
+            lwQuery = _queryHelpers.ApplyNavigations(lwQuery, filter);
+            lastWatchedEpisodes = lwQuery.ToDictionary(e => e.Id);
+        }
+
+        Dictionary<string, List<BaseItemEntity>> specialsBySeriesKey = new();
+        if (includeSpecials)
+        {
+            var specialsQuery = context.BaseItems
+                .AsNoTracking()
+                .Where(e => e.Type == episodeTypeName)
+                .Where(e => e.SeriesPresentationUniqueKey != null && seriesKeys.Contains(e.SeriesPresentationUniqueKey))
+                .Where(e => e.ParentIndexNumber == 0)
+                .Where(e => !e.IsVirtualItem);
+            specialsQuery = _queryHelpers.ApplyAccessFiltering(context, specialsQuery, filter);
+            specialsQuery = _queryHelpers.ApplyNavigations(specialsQuery, filter).AsSingleQuery();
+
+            foreach (var special in specialsQuery)
+            {
+                var key = special.SeriesPresentationUniqueKey!;
+                if (!specialsBySeriesKey.TryGetValue(key, out var list))
+                {
+                    list = new List<BaseItemEntity>();
+                    specialsBySeriesKey[key] = list;
+                }
+
+                list.Add(special);
+            }
+        }
+
+        var positionLookup = new Dictionary<string, (int Season, int Episode)>();
+        foreach (var kvp in lastWatchedInfo)
+        {
+            if (kvp.Value != Guid.Empty
+                && lastWatchedEpisodes.TryGetValue(kvp.Value, out var lw)
+                && lw.ParentIndexNumber.HasValue
+                && lw.IndexNumber.HasValue)
+            {
+                positionLookup[kvp.Key] = (lw.ParentIndexNumber.Value, lw.IndexNumber.Value);
+            }
+        }
+
+        var allUnplayedBase = context.BaseItems
+            .AsNoTracking()
+            .Where(e => e.Type == episodeTypeName)
+            .Where(e => e.SeriesPresentationUniqueKey != null && seriesKeys.Contains(e.SeriesPresentationUniqueKey))
+            .Where(e => e.ParentIndexNumber != 0)
+            .Where(e => !e.IsVirtualItem)
+            .Where(e => !e.UserData!.Any(ud => ud.UserId == userId && ud.Played));
+        allUnplayedBase = _queryHelpers.ApplyAccessFiltering(context, allUnplayedBase, filter);
+        var allUnplayedCandidates = allUnplayedBase
+            .Select(e => new
+            {
+                e.Id,
+                e.SeriesPresentationUniqueKey,
+                e.ParentIndexNumber,
+                EpisodeNumber = e.IndexNumber
+            })
+            .ToList();
+
+        var nextEpisodeIds = new HashSet<Guid>();
+        var seriesNextIdMap = new Dictionary<string, Guid>();
+
+        foreach (var seriesKey in seriesKeys)
+        {
+            var candidates = allUnplayedCandidates
+                .Where(c => c.SeriesPresentationUniqueKey == seriesKey);
+
+            if (positionLookup.TryGetValue(seriesKey, out var pos))
+            {
+                candidates = candidates.Where(c =>
+                    c.ParentIndexNumber > pos.Season
+                    || (c.ParentIndexNumber == pos.Season && c.EpisodeNumber > pos.Episode));
+            }
+
+            var nextCandidate = candidates
+                .OrderBy(c => c.ParentIndexNumber)
+                .ThenBy(c => c.EpisodeNumber)
+                .FirstOrDefault();
+
+            if (nextCandidate is not null && nextCandidate.Id != Guid.Empty)
+            {
+                nextEpisodeIds.Add(nextCandidate.Id);
+                seriesNextIdMap[seriesKey] = nextCandidate.Id;
+            }
+        }
+
+        var seriesNextPlayedIdMap = new Dictionary<string, Guid>();
+        if (includeWatchedForRewatching)
+        {
+            var allPlayedBase = context.BaseItems
+                .AsNoTracking()
+                .Where(e => e.Type == episodeTypeName)
+                .Where(e => e.SeriesPresentationUniqueKey != null && seriesKeys.Contains(e.SeriesPresentationUniqueKey))
+                .Where(e => e.ParentIndexNumber != 0)
+                .Where(e => !e.IsVirtualItem)
+                .Where(e => e.UserData!.Any(ud => ud.UserId == userId && ud.Played));
+            allPlayedBase = _queryHelpers.ApplyAccessFiltering(context, allPlayedBase, filter);
+            var allPlayedCandidates = allPlayedBase
+                .Select(e => new
+                {
+                    e.Id,
+                    e.SeriesPresentationUniqueKey,
+                    e.ParentIndexNumber,
+                    EpisodeNumber = e.IndexNumber
+                })
+                .ToList();
+
+            foreach (var seriesKey in seriesKeys)
+            {
+                if (!lastWatchedByDateInfo.TryGetValue(seriesKey, out var lastByDateId))
+                {
+                    continue;
+                }
+
+                var lastByDateEntity = lastWatchedEpisodes.GetValueOrDefault(lastByDateId);
+                if (lastByDateEntity is null)
+                {
+                    continue;
+                }
+
+                var playedCandidates = allPlayedCandidates
+                    .Where(c => c.SeriesPresentationUniqueKey == seriesKey);
+
+                if (lastByDateEntity.ParentIndexNumber.HasValue && lastByDateEntity.IndexNumber.HasValue)
+                {
+                    var lastSeason = lastByDateEntity.ParentIndexNumber.Value;
+                    var lastEp = lastByDateEntity.IndexNumber.Value;
+                    playedCandidates = playedCandidates.Where(c =>
+                        c.ParentIndexNumber > lastSeason
+                        || (c.ParentIndexNumber == lastSeason && c.EpisodeNumber > lastEp));
+                }
+
+                var nextPlayedCandidate = playedCandidates
+                    .OrderBy(c => c.ParentIndexNumber)
+                    .ThenBy(c => c.EpisodeNumber)
+                    .FirstOrDefault();
+
+                if (nextPlayedCandidate is not null && nextPlayedCandidate.Id != Guid.Empty)
+                {
+                    nextEpisodeIds.Add(nextPlayedCandidate.Id);
+                    seriesNextPlayedIdMap[seriesKey] = nextPlayedCandidate.Id;
+                }
+            }
+        }
+
+        var nextEpisodes = new Dictionary<Guid, BaseItemEntity>();
+        if (nextEpisodeIds.Count > 0)
+        {
+            var nextQuery = context.BaseItems.AsNoTracking().Where(e => nextEpisodeIds.Contains(e.Id));
+            nextQuery = _queryHelpers.ApplyNavigations(nextQuery, filter).AsSingleQuery();
+            nextEpisodes = nextQuery.ToDictionary(e => e.Id);
+        }
+
+        var result = new Dictionary<string, NextUpEpisodeBatchResult>();
+        foreach (var seriesKey in seriesKeys)
+        {
+            var batchResult = new NextUpEpisodeBatchResult();
+
+            if (lastWatchedInfo.TryGetValue(seriesKey, out var lwId) && lwId != Guid.Empty)
+            {
+                if (lastWatchedEpisodes.TryGetValue(lwId, out var entity))
+                {
+                    batchResult.LastWatched = _queryHelpers.DeserializeBaseItem(entity, filter.SkipDeserialization);
+                }
+            }
+
+            if (seriesNextIdMap.TryGetValue(seriesKey, out var nextId) && nextEpisodes.TryGetValue(nextId, out var nextEntity))
+            {
+                batchResult.NextUp = _queryHelpers.DeserializeBaseItem(nextEntity, filter.SkipDeserialization);
+            }
+
+            if (includeSpecials && specialsBySeriesKey.TryGetValue(seriesKey, out var specials))
+            {
+                batchResult.Specials = specials.Select(s => _queryHelpers.DeserializeBaseItem(s, filter.SkipDeserialization)!).ToList();
+            }
+            else
+            {
+                batchResult.Specials = Array.Empty<BaseItemDto>();
+            }
+
+            if (includeWatchedForRewatching)
+            {
+                if (lastWatchedByDateInfo.TryGetValue(seriesKey, out var lastByDateId) &&
+                    lastWatchedEpisodes.TryGetValue(lastByDateId, out var lastByDateEntity))
+                {
+                    batchResult.LastWatchedForRewatching = _queryHelpers.DeserializeBaseItem(lastByDateEntity, filter.SkipDeserialization);
+                }
+
+                if (seriesNextPlayedIdMap.TryGetValue(seriesKey, out var nextPlayedId) &&
+                    nextEpisodes.TryGetValue(nextPlayedId, out var nextPlayedEntity))
+                {
+                    batchResult.NextPlayedForRewatching = _queryHelpers.DeserializeBaseItem(nextPlayedEntity, filter.SkipDeserialization);
+                }
+            }
+
+            result[seriesKey] = batchResult;
+        }
+
+        return result;
+    }
+}

Jellyfin.Server/Migrations/Routines/CleanupOrphanedExtras.cs

@@ -36,6 +36,7 @@ public class CleanupOrphanedExtras : IAsyncMigrationRoutine
     /// <param name="dbContextFactory">The database context factory.</param>
     /// <param name="libraryManager">The library manager.</param>
     /// <param name="itemRepository">The item repository.</param>
+    /// <param name="itemCountService">The item count service.</param>
     /// <param name="channelManager">The channel manager.</param>
     /// <param name="recordingsManager">The recordings manager.</param>
     /// <param name="mediaSourceManager">The media source manager.</param>
@@ -46,6 +47,7 @@ public class CleanupOrphanedExtras : IAsyncMigrationRoutine
         IDbContextFactory<JellyfinDbContext> dbContextFactory,
         ILibraryManager libraryManager,
         IItemRepository itemRepository,
+        IItemCountService itemCountService,
         IChannelManager channelManager,
         IRecordingsManager recordingsManager,
         IMediaSourceManager mediaSourceManager,
@@ -57,6 +59,7 @@ public class CleanupOrphanedExtras : IAsyncMigrationRoutine
         _libraryManager = libraryManager;
         BaseItem.LibraryManager ??= libraryManager;
         BaseItem.ItemRepository ??= itemRepository;
+        BaseItem.ItemCountService ??= itemCountService;
         BaseItem.ChannelManager ??= channelManager;
         BaseItem.MediaSourceManager ??= mediaSourceManager;
         BaseItem.MediaSegmentManager ??= mediaSegmentManager;

Jellyfin.Server/Migrations/Routines/FixAudioData.cs

@@ -1,10 +1,6 @@
-using System;
-using System.Globalization;
-using System.IO;
 using System.Linq;
 using System.Threading;
 using Jellyfin.Data.Enums;
-using MediaBrowser.Controller;
 using MediaBrowser.Controller.Entities;
 using MediaBrowser.Controller.Entities.Audio;
 using MediaBrowser.Controller.Persistence;
@@ -23,16 +19,19 @@ namespace Jellyfin.Server.Migrations.Routines
 #pragma warning restore CS0618 // Type or member is obsolete
     {
         private readonly ILogger<FixAudioData> _logger;
-        private readonly IServerApplicationPaths _applicationPaths;
         private readonly IItemRepository _itemRepository;
+        private readonly IItemCountService _countService;
+        private readonly IItemPersistenceService _persistenceService;
 
         public FixAudioData(
-            IServerApplicationPaths applicationPaths,
             ILoggerFactory loggerFactory,
-            IItemRepository itemRepository)
+            IItemRepository itemRepository,
+            IItemCountService countService,
+            IItemPersistenceService persistenceService)
         {
-            _applicationPaths = applicationPaths;
             _itemRepository = itemRepository;
+            _countService = countService;
+            _persistenceService = persistenceService;
             _logger = loggerFactory.CreateLogger<FixAudioData>();
         }
 
@@ -41,7 +40,7 @@ namespace Jellyfin.Server.Migrations.Routines
         {
             _logger.LogInformation("Backfilling audio lyrics data to database.");
             var startIndex = 0;
-            var records = _itemRepository.GetCount(new InternalItemsQuery
+            var records = _countService.GetCount(new InternalItemsQuery
             {
                 IncludeItemTypes = [BaseItemKind.Audio],
             });
@@ -68,7 +67,7 @@ namespace Jellyfin.Server.Migrations.Routines
                     }
                 }
 
-                _itemRepository.SaveItems(results, CancellationToken.None);
+                _persistenceService.SaveItems(results, CancellationToken.None);
                 startIndex += results.Count;
                 _logger.LogInformation("Backfilled data for {UpdatedRecords} of {TotalRecords} audio records", startIndex, records);
             }

Jellyfin.Server/Migrations/Routines/FixIncorrectOwnerIdRelationships.cs

@@ -24,7 +24,7 @@ public class FixIncorrectOwnerIdRelationships : IAsyncMigrationRoutine
     private readonly IStartupLogger<FixIncorrectOwnerIdRelationships> _logger;
     private readonly IDbContextFactory<JellyfinDbContext> _dbContextFactory;
     private readonly ILibraryManager _libraryManager;
-    private readonly IItemRepository _itemRepository;
+    private readonly IItemPersistenceService _persistenceService;
 
     /// <summary>
     /// Initializes a new instance of the <see cref="FixIncorrectOwnerIdRelationships"/> class.
@@ -32,17 +32,17 @@ public class FixIncorrectOwnerIdRelationships : IAsyncMigrationRoutine
     /// <param name="logger">The startup logger.</param>
     /// <param name="dbContextFactory">The database context factory.</param>
     /// <param name="libraryManager">The library manager.</param>
-    /// <param name="itemRepository">The item repository.</param>
+    /// <param name="persistenceService">The item persistence service.</param>
     public FixIncorrectOwnerIdRelationships(
         IStartupLogger<FixIncorrectOwnerIdRelationships> logger,
         IDbContextFactory<JellyfinDbContext> dbContextFactory,
         ILibraryManager libraryManager,
-        IItemRepository itemRepository)
+        IItemPersistenceService persistenceService)
     {
         _logger = logger;
         _dbContextFactory = dbContextFactory;
         _libraryManager = libraryManager;
-        _itemRepository = itemRepository;
+        _persistenceService = persistenceService;
     }
 
     /// <inheritdoc/>
@@ -157,7 +157,7 @@ public class FixIncorrectOwnerIdRelationships : IAsyncMigrationRoutine
                     {
                         try
                         {
-                            _itemRepository.DeleteItem([itemId]);
+                            _persistenceService.DeleteItem([itemId]);
                             deletedCount++;
                             _logger.LogInformation("Successfully deleted duplicate item {ItemId} at path {Path} via direct database deletion", itemId, path);
                         }

MediaBrowser.Controller/Entities/BaseItem.cs

@@ -489,6 +489,8 @@ namespace MediaBrowser.Controller.Entities
 
         public static IItemRepository ItemRepository { get; set; }
 
+        public static IItemCountService ItemCountService { get; set; }
+
         public static IChapterManager ChapterManager { get; set; }
 
         public static IFileSystem FileSystem { get; set; }

MediaBrowser.Controller/Entities/Folder.cs

@@ -1883,11 +1883,11 @@ namespace MediaBrowser.Controller.Entities
 
                     if (LinkedChildren.Length > 0)
                     {
-                        (playedCount, totalCount) = ItemRepository.GetPlayedAndTotalCountFromLinkedChildren(query, Id);
+                        (playedCount, totalCount) = ItemCountService.GetPlayedAndTotalCountFromLinkedChildren(query, Id);
                     }
                     else
                     {
-                        (playedCount, totalCount) = ItemRepository.GetPlayedAndTotalCount(query, Id);
+                        (playedCount, totalCount) = ItemCountService.GetPlayedAndTotalCount(query, Id);
                     }
                 }
 

MediaBrowser.Controller/Persistence/IItemCountService.cs

@@ -0,0 +1,86 @@
+using System;
+using System.Collections.Generic;
+using Jellyfin.Data.Enums;
+using Jellyfin.Database.Implementations.Entities;
+using MediaBrowser.Controller.Entities;
+using MediaBrowser.Model.Dto;
+
+namespace MediaBrowser.Controller.Persistence;
+
+/// <summary>
+/// Provides item counting and played-status query operations.
+/// </summary>
+public interface IItemCountService
+{
+    /// <summary>
+    /// Gets the count of items matching the filter.
+    /// </summary>
+    /// <param name="filter">The query filter.</param>
+    /// <returns>The item count.</returns>
+    int GetCount(InternalItemsQuery filter);
+
+    /// <summary>
+    /// Gets item counts grouped by type.
+    /// </summary>
+    /// <param name="filter">The query filter.</param>
+    /// <returns>The item counts by type.</returns>
+    ItemCounts GetItemCounts(InternalItemsQuery filter);
+
+    /// <summary>
+    /// Gets item counts for a "by-name" item using an optimized query.
+    /// </summary>
+    /// <param name="kind">The kind of the name item.</param>
+    /// <param name="id">The ID of the name item.</param>
+    /// <param name="relatedItemKinds">The item kinds to count.</param>
+    /// <param name="accessFilter">A pre-configured query with user access filtering settings.</param>
+    /// <returns>The item counts grouped by type.</returns>
+    ItemCounts GetItemCountsForNameItem(BaseItemKind kind, Guid id, BaseItemKind[] relatedItemKinds, InternalItemsQuery accessFilter);
+
+    /// <summary>
+    /// Gets the count of played items that are descendants of the specified ancestor.
+    /// </summary>
+    /// <param name="filter">The query filter containing user access settings.</param>
+    /// <param name="ancestorId">The ancestor item id.</param>
+    /// <returns>The count of played descendant items.</returns>
+    int GetPlayedCount(InternalItemsQuery filter, Guid ancestorId);
+
+    /// <summary>
+    /// Gets the total count of items that are descendants of the specified ancestor.
+    /// </summary>
+    /// <param name="filter">The query filter containing user access settings.</param>
+    /// <param name="ancestorId">The ancestor item id.</param>
+    /// <returns>The total count of descendant items.</returns>
+    int GetTotalCount(InternalItemsQuery filter, Guid ancestorId);
+
+    /// <summary>
+    /// Gets both the played count and total count of descendant items.
+    /// </summary>
+    /// <param name="filter">The query filter containing user access settings.</param>
+    /// <param name="ancestorId">The ancestor item id.</param>
+    /// <returns>A tuple containing (Played count, Total count).</returns>
+    (int Played, int Total) GetPlayedAndTotalCount(InternalItemsQuery filter, Guid ancestorId);
+
+    /// <summary>
+    /// Gets both the played count and total count from linked children.
+    /// </summary>
+    /// <param name="filter">The query filter containing user access settings.</param>
+    /// <param name="parentId">The parent item id.</param>
+    /// <returns>A tuple containing (Played count, Total count).</returns>
+    (int Played, int Total) GetPlayedAndTotalCountFromLinkedChildren(InternalItemsQuery filter, Guid parentId);
+
+    /// <summary>
+    /// Batch-fetches played and total counts for multiple folder items.
+    /// </summary>
+    /// <param name="folderIds">The list of folder item IDs to get counts for.</param>
+    /// <param name="user">The user for access filtering and played status.</param>
+    /// <returns>Dictionary mapping folder ID to (Played count, Total count).</returns>
+    Dictionary<Guid, (int Played, int Total)> GetPlayedAndTotalCountBatch(IReadOnlyList<Guid> folderIds, User user);
+
+    /// <summary>
+    /// Batch-fetches child counts for multiple parent folders.
+    /// </summary>
+    /// <param name="parentIds">The list of parent folder IDs.</param>
+    /// <param name="userId">The user ID for access filtering.</param>
+    /// <returns>Dictionary mapping parent ID to child count.</returns>
+    Dictionary<Guid, int> GetChildCountBatch(IReadOnlyList<Guid> parentIds, Guid? userId);
+}

MediaBrowser.Controller/Persistence/IItemPersistenceService.cs

@@ -0,0 +1,47 @@
+using System;
+using System.Collections.Generic;
+using System.Threading;
+using System.Threading.Tasks;
+using MediaBrowser.Controller.Entities;
+
+namespace MediaBrowser.Controller.Persistence;
+
+/// <summary>
+/// Provides item persistence operations (save, delete, update).
+/// </summary>
+public interface IItemPersistenceService
+{
+    /// <summary>
+    /// Deletes items by their IDs.
+    /// </summary>
+    /// <param name="ids">The IDs to delete.</param>
+    void DeleteItem(params IReadOnlyList<Guid> ids);
+
+    /// <summary>
+    /// Saves items to the database.
+    /// </summary>
+    /// <param name="items">The items to save.</param>
+    /// <param name="cancellationToken">The cancellation token.</param>
+    void SaveItems(IReadOnlyList<BaseItem> items, CancellationToken cancellationToken);
+
+    /// <summary>
+    /// Saves image info for an item.
+    /// </summary>
+    /// <param name="item">The item.</param>
+    /// <param name="cancellationToken">The cancellation token.</param>
+    /// <returns>A task representing the asynchronous operation.</returns>
+    Task SaveImagesAsync(BaseItem item, CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Reattaches user data entries to the correct item.
+    /// </summary>
+    /// <param name="item">The item.</param>
+    /// <param name="cancellationToken">The cancellation token.</param>
+    /// <returns>A task representing the asynchronous operation.</returns>
+    Task ReattachUserDataAsync(BaseItem item, CancellationToken cancellationToken);
+
+    /// <summary>
+    /// Updates inherited values.
+    /// </summary>
+    void UpdateInheritedValues();
+}

MediaBrowser.Controller/Persistence/IItemQueryHelpers.cs

@@ -0,0 +1,94 @@
+using System;
+using System.Linq;
+using Jellyfin.Database.Implementations;
+using Jellyfin.Database.Implementations.Entities;
+using MediaBrowser.Controller.Entities;
+
+namespace MediaBrowser.Controller.Persistence;
+
+/// <summary>
+/// Provides shared query-building methods used by extracted item services.
+/// Implemented by <c>BaseItemRepository</c>.
+/// </summary>
+public interface IItemQueryHelpers
+{
+    /// <summary>
+    /// Translates an <see cref="InternalItemsQuery"/> into EF Core filter expressions.
+    /// </summary>
+    /// <param name="baseQuery">The base queryable to filter.</param>
+    /// <param name="context">The database context.</param>
+    /// <param name="filter">The query filter.</param>
+    /// <returns>The filtered queryable.</returns>
+    IQueryable<BaseItemEntity> TranslateQuery(
+        IQueryable<BaseItemEntity> baseQuery,
+        JellyfinDbContext context,
+        InternalItemsQuery filter);
+
+    /// <summary>
+    /// Prepares a base query for items from the context.
+    /// </summary>
+    /// <param name="context">The database context.</param>
+    /// <param name="filter">The query filter.</param>
+    /// <returns>The prepared queryable.</returns>
+    IQueryable<BaseItemEntity> PrepareItemQuery(JellyfinDbContext context, InternalItemsQuery filter);
+
+    /// <summary>
+    /// Applies user access filtering (library access, parental controls, tags) to a query.
+    /// </summary>
+    /// <param name="context">The database context.</param>
+    /// <param name="baseQuery">The base queryable to filter.</param>
+    /// <param name="filter">The query filter containing access settings.</param>
+    /// <returns>The access-filtered queryable.</returns>
+    IQueryable<BaseItemEntity> ApplyAccessFiltering(
+        JellyfinDbContext context,
+        IQueryable<BaseItemEntity> baseQuery,
+        InternalItemsQuery filter);
+
+    /// <summary>
+    /// Applies navigation property includes to a query based on filter options.
+    /// </summary>
+    /// <param name="dbQuery">The queryable to apply navigations to.</param>
+    /// <param name="filter">The query filter.</param>
+    /// <returns>The queryable with navigation includes.</returns>
+    IQueryable<BaseItemEntity> ApplyNavigations(
+        IQueryable<BaseItemEntity> dbQuery,
+        InternalItemsQuery filter);
+
+    /// <summary>
+    /// Applies ordering to a query based on filter options.
+    /// </summary>
+    /// <param name="query">The queryable to order.</param>
+    /// <param name="filter">The query filter.</param>
+    /// <param name="context">The database context.</param>
+    /// <returns>The ordered queryable.</returns>
+    IQueryable<BaseItemEntity> ApplyOrder(
+        IQueryable<BaseItemEntity> query,
+        InternalItemsQuery filter,
+        JellyfinDbContext context);
+
+    /// <summary>
+    /// Builds a query for descendants of an ancestor with user access filtering applied.
+    /// </summary>
+    /// <param name="context">The database context.</param>
+    /// <param name="filter">The query filter.</param>
+    /// <param name="ancestorId">The ancestor item ID.</param>
+    /// <returns>The filtered descendant queryable.</returns>
+    IQueryable<BaseItemEntity> BuildAccessFilteredDescendantsQuery(
+        JellyfinDbContext context,
+        InternalItemsQuery filter,
+        Guid ancestorId);
+
+    /// <summary>
+    /// Deserializes a <see cref="BaseItemEntity"/> into a <see cref="BaseItem"/>.
+    /// </summary>
+    /// <param name="entity">The database entity.</param>
+    /// <param name="skipDeserialization">Whether to skip JSON deserialization.</param>
+    /// <returns>The deserialized item, or null.</returns>
+    BaseItem? DeserializeBaseItem(BaseItemEntity entity, bool skipDeserialization = false);
+
+    /// <summary>
+    /// Prepares a filter query by adjusting limits and virtual item settings.
+    /// </summary>
+    /// <param name="query">The query to prepare.</param>
+    void PrepareFilterQuery(InternalItemsQuery query);
+}

MediaBrowser.Controller/Persistence/IItemRepository.cs

@@ -1,18 +1,13 @@
 #nullable disable
 
-#pragma warning disable CS1591
-
 using System;
 using System.Collections.Generic;
-using System.Threading;
 using System.Threading.Tasks;
 using Jellyfin.Data.Enums;
 using Jellyfin.Database.Implementations.Entities;
 using MediaBrowser.Controller.Entities;
-using MediaBrowser.Controller.Entities.Audio;
 using MediaBrowser.Model.Dto;
 using MediaBrowser.Model.Querying;
-using LinkedChildType = MediaBrowser.Controller.Entities.LinkedChildType;
 
 namespace MediaBrowser.Controller.Persistence;
 
@@ -21,29 +16,6 @@ namespace MediaBrowser.Controller.Persistence;
 /// </summary>
 public interface IItemRepository
 {
-    /// <summary>
-    /// Deletes the item.
-    /// </summary>
-    /// <param name="ids">The identifier to delete.</param>
-    void DeleteItem(params IReadOnlyList<Guid> ids);
-
-    /// <summary>
-    /// Saves the items.
-    /// </summary>
-    /// <param name="items">The items.</param>
-    /// <param name="cancellationToken">The cancellation token.</param>
-    void SaveItems(IReadOnlyList<BaseItem> items, CancellationToken cancellationToken);
-
-    Task SaveImagesAsync(BaseItem item, CancellationToken cancellationToken = default);
-
-    /// <summary>
-    /// Reattaches the user data to the item.
-    /// </summary>
-    /// <param name="item">The item.</param>
-    /// <param name="cancellationToken">The cancellation token.</param>
-    /// <returns>A task that represents the asynchronous reattachment operation.</returns>
-    Task ReattachUserDataAsync(BaseItem item, CancellationToken cancellationToken);
-
     /// <summary>
     /// Retrieves the item.
     /// </summary>
@@ -80,69 +52,6 @@ public interface IItemRepository
     /// <returns>List&lt;BaseItem&gt;.</returns>
     IReadOnlyList<BaseItem> GetLatestItemList(InternalItemsQuery filter, CollectionType collectionType);
 
-    /// <summary>
-    /// Gets the list of series presentation keys for next up.
-    /// </summary>
-    /// <param name="filter">The query.</param>
-    /// <param name="dateCutoff">The minimum date for a series to have been most recently watched.</param>
-    /// <returns>The list of keys.</returns>
-    IReadOnlyList<string> GetNextUpSeriesKeys(InternalItemsQuery filter, DateTime dateCutoff);
-
-    /// <summary>
-    /// Gets next up episodes for multiple series in a single batched query.
-    /// Returns the last watched episode, next unwatched episode, specials, and next played episode for each series.
-    /// </summary>
-    /// <param name="filter">The query filter.</param>
-    /// <param name="seriesKeys">The series presentation unique keys to query.</param>
-    /// <param name="includeSpecials">Whether to include specials (ParentIndexNumber = 0) in the results.</param>
-    /// <param name="includeWatchedForRewatching">Whether to include watched episodes for rewatching mode.</param>
-    /// <returns>A dictionary mapping series key to batch result containing episodes needed for NextUp calculation.</returns>
-    IReadOnlyDictionary<string, NextUpEpisodeBatchResult> GetNextUpEpisodesBatch(
-        InternalItemsQuery filter,
-        IReadOnlyList<string> seriesKeys,
-        bool includeSpecials,
-        bool includeWatchedForRewatching);
-
-    /// <summary>
-    /// Updates the inherited values.
-    /// </summary>
-    void UpdateInheritedValues();
-
-    int GetCount(InternalItemsQuery filter);
-
-    ItemCounts GetItemCounts(InternalItemsQuery filter);
-
-    /// <summary>
-    /// Gets item counts for a "by-name" item (Person, MusicArtist, Genre, MusicGenre, Studio, Year)
-    /// using an optimized query that starts from the mapping table instead of scanning all BaseItems.
-    /// </summary>
-    /// <param name="kind">The kind of the name item.</param>
-    /// <param name="id">The ID of the name item.</param>
-    /// <param name="relatedItemKinds">The item kinds to count.</param>
-    /// <param name="accessFilter">A pre-configured query with user access filtering settings.</param>
-    /// <returns>The item counts grouped by type.</returns>
-    ItemCounts GetItemCountsForNameItem(BaseItemKind kind, Guid id, BaseItemKind[] relatedItemKinds, InternalItemsQuery accessFilter);
-
-    QueryResult<(BaseItem Item, ItemCounts ItemCounts)> GetGenres(InternalItemsQuery filter);
-
-    QueryResult<(BaseItem Item, ItemCounts ItemCounts)> GetMusicGenres(InternalItemsQuery filter);
-
-    QueryResult<(BaseItem Item, ItemCounts ItemCounts)> GetStudios(InternalItemsQuery filter);
-
-    QueryResult<(BaseItem Item, ItemCounts ItemCounts)> GetArtists(InternalItemsQuery filter);
-
-    QueryResult<(BaseItem Item, ItemCounts ItemCounts)> GetAlbumArtists(InternalItemsQuery filter);
-
-    QueryResult<(BaseItem Item, ItemCounts ItemCounts)> GetAllArtists(InternalItemsQuery filter);
-
-    IReadOnlyList<string> GetMusicGenreNames();
-
-    IReadOnlyList<string> GetStudioNames();
-
-    IReadOnlyList<string> GetGenreNames();
-
-    IReadOnlyList<string> GetAllArtistNames();
-
     /// <summary>
     /// Checks if an item has been persisted to the database.
     /// </summary>
@@ -151,118 +60,84 @@ public interface IItemRepository
     Task<bool> ItemExistsAsync(Guid id);
 
     /// <summary>
-    /// Gets a value indicating wherever all children of the requested Id has been played.
+    /// Gets genres with item counts.
     /// </summary>
-    /// <param name="user">The userdata to check against.</param>
-    /// <param name="id">The Top id to check.</param>
-    /// <param name="recursive">Whever the check should be done recursive. Warning expensive operation.</param>
-    /// <returns>A value indicating whever all children has been played.</returns>
-    bool GetIsPlayed(User user, Guid id, bool recursive);
+    /// <param name="filter">The query filter.</param>
+    /// <returns>The genres and their item counts.</returns>
+    QueryResult<(BaseItem Item, ItemCounts ItemCounts)> GetGenres(InternalItemsQuery filter);
 
     /// <summary>
-    /// Gets the count of played items that are descendants of the specified ancestor.
-    /// Uses the AncestorIds table for efficient recursive lookup.
-    /// Applies user access filtering (library access, parental controls, tags).
+    /// Gets music genres with item counts.
     /// </summary>
-    /// <param name="filter">The query filter containing user access settings.</param>
-    /// <param name="ancestorId">The ancestor item id.</param>
-    /// <returns>The count of played descendant items.</returns>
-    int GetPlayedCount(InternalItemsQuery filter, Guid ancestorId);
+    /// <param name="filter">The query filter.</param>
+    /// <returns>The music genres and their item counts.</returns>
+    QueryResult<(BaseItem Item, ItemCounts ItemCounts)> GetMusicGenres(InternalItemsQuery filter);
 
     /// <summary>
-    /// Gets the total count of items that are descendants of the specified ancestor.
-    /// Uses the AncestorIds table for efficient recursive lookup.
-    /// Applies user access filtering (library access, parental controls, tags).
+    /// Gets studios with item counts.
     /// </summary>
-    /// <param name="filter">The query filter containing user access settings.</param>
-    /// <param name="ancestorId">The ancestor item id.</param>
-    /// <returns>The total count of descendant items.</returns>
-    int GetTotalCount(InternalItemsQuery filter, Guid ancestorId);
+    /// <param name="filter">The query filter.</param>
+    /// <returns>The studios and their item counts.</returns>
+    QueryResult<(BaseItem Item, ItemCounts ItemCounts)> GetStudios(InternalItemsQuery filter);
 
     /// <summary>
-    /// Gets both the played count and total count of items that are descendants of the specified ancestor.
-    /// Uses the AncestorIds table for efficient recursive lookup.
-    /// Applies user access filtering (library access, parental controls, tags).
+    /// Gets artists with item counts.
     /// </summary>
-    /// <param name="filter">The query filter containing user access settings.</param>
-    /// <param name="ancestorId">The ancestor item id.</param>
-    /// <returns>A tuple containing (Played count, Total count).</returns>
-    (int Played, int Total) GetPlayedAndTotalCount(InternalItemsQuery filter, Guid ancestorId);
+    /// <param name="filter">The query filter.</param>
+    /// <returns>The artists and their item counts.</returns>
+    QueryResult<(BaseItem Item, ItemCounts ItemCounts)> GetArtists(InternalItemsQuery filter);
 
     /// <summary>
-    /// Gets both the played count and total count of items that are linked children of the specified parent.
-    /// Uses the LinkedChildren table for BoxSets, Playlists, etc.
-    /// Applies user access filtering (library access, parental controls, tags).
+    /// Gets album artists with item counts.
     /// </summary>
-    /// <param name="filter">The query filter containing user access settings.</param>
-    /// <param name="parentId">The parent item id (BoxSet, Playlist, etc.).</param>
-    /// <returns>A tuple containing (Played count, Total count).</returns>
-    (int Played, int Total) GetPlayedAndTotalCountFromLinkedChildren(InternalItemsQuery filter, Guid parentId);
+    /// <param name="filter">The query filter.</param>
+    /// <returns>The album artists and their item counts.</returns>
+    QueryResult<(BaseItem Item, ItemCounts ItemCounts)> GetAlbumArtists(InternalItemsQuery filter);
 
     /// <summary>
-    /// Batch-fetches played and total counts for multiple folder items using the AncestorIds table.
-    /// This avoids N+1 queries when building DTOs for lists of folder items (Series, Seasons, etc.).
-    /// Applies user access filtering (parental controls, tags).
+    /// Gets all artists with item counts.
     /// </summary>
-    /// <param name="folderIds">The list of folder item IDs to get counts for.</param>
-    /// <param name="user">The user for access filtering and played status.</param>
-    /// <returns>Dictionary mapping folder ID to (Played count, Total count).</returns>
-    Dictionary<Guid, (int Played, int Total)> GetPlayedAndTotalCountBatch(IReadOnlyList<Guid> folderIds, User user);
+    /// <param name="filter">The query filter.</param>
+    /// <returns>All artists and their item counts.</returns>
+    QueryResult<(BaseItem Item, ItemCounts ItemCounts)> GetAllArtists(InternalItemsQuery filter);
 
     /// <summary>
-    /// Gets the IDs of linked children for the specified parent.
+    /// Gets all music genre names.
     /// </summary>
-    /// <param name="parentId">The parent item ID.</param>
-    /// <param name="childType">Optional child type filter (e.g., LocalAlternateVersion, LinkedAlternateVersion).</param>
-    /// <returns>List of child item IDs.</returns>
-    IReadOnlyList<Guid> GetLinkedChildrenIds(Guid parentId, int? childType = null);
+    /// <returns>The list of music genre names.</returns>
+    IReadOnlyList<string> GetMusicGenreNames();
 
     /// <summary>
-    /// Gets all artist matches from the db.
+    /// Gets all studio names.
     /// </summary>
-    /// <param name="artistNames">The names of the artists.</param>
-    /// <returns>A map of the artist name and the potential matches.</returns>
-    IReadOnlyDictionary<string, MusicArtist[]> FindArtists(IReadOnlyList<string> artistNames);
+    /// <returns>The list of studio names.</returns>
+    IReadOnlyList<string> GetStudioNames();
 
     /// <summary>
-    /// Batch-fetches child counts for multiple parent folders.
-    /// Returns the count of immediate children (non-recursive) for each parent.
+    /// Gets all genre names.
     /// </summary>
-    /// <param name="parentIds">The list of parent folder IDs.</param>
-    /// <param name="userId">The user ID for access filtering.</param>
-    /// <returns>Dictionary mapping parent ID to child count.</returns>
-    Dictionary<Guid, int> GetChildCountBatch(IReadOnlyList<Guid> parentIds, Guid? userId);
+    /// <returns>The list of genre names.</returns>
+    IReadOnlyList<string> GetGenreNames();
 
     /// <summary>
-    /// Gets parent IDs (Playlists/BoxSets) that reference the specified child with LinkedChildType.Manual.
+    /// Gets all artist names.
     /// </summary>
-    /// <param name="childId">The child item ID.</param>
-    /// <returns>List of parent IDs that reference the child.</returns>
-    IReadOnlyList<Guid> GetManualLinkedParentIds(Guid childId);
+    /// <returns>The list of artist names.</returns>
+    IReadOnlyList<string> GetAllArtistNames();
 
     /// <summary>
-    /// Gets legacy query filters (Years, Genres, Tags, OfficialRatings) aggregated directly from the database.
+    /// Gets legacy query filters aggregated from the database.
     /// </summary>
     /// <param name="filter">The query filter.</param>
     /// <returns>Aggregated filter values.</returns>
     QueryFiltersLegacy GetQueryFiltersLegacy(InternalItemsQuery filter);
 
     /// <summary>
-    /// Updates LinkedChildren references from one child to another, preserving SortOrder.
-    /// Handles duplicates: if parent already references toChildId, removes the old reference instead.
-    /// Used when video versions change to maintain collection integrity.
+    /// Gets whether all children of the requested item have been played.
     /// </summary>
-    /// <param name="fromChildId">The child ID to re-route from.</param>
-    /// <param name="toChildId">The child ID to re-route to.</param>
-    /// <returns>List of parent item IDs whose LinkedChildren were modified.</returns>
-    IReadOnlyList<Guid> RerouteLinkedChildren(Guid fromChildId, Guid toChildId);
-
-    /// <summary>
-    /// Creates or updates a LinkedChild entry linking a parent to a child item.
-    /// If the link already exists, updates the child type.
-    /// </summary>
-    /// <param name="parentId">The parent item ID.</param>
-    /// <param name="childId">The child item ID.</param>
-    /// <param name="childType">The type of linked child relationship.</param>
-    void UpsertLinkedChild(Guid parentId, Guid childId, LinkedChildType childType);
+    /// <param name="user">The user to check against.</param>
+    /// <param name="id">The top item id to check.</param>
+    /// <param name="recursive">Whether the check should be done recursively.</param>
+    /// <returns>A value indicating whether all children have been played.</returns>
+    bool GetIsPlayed(User user, Guid id, bool recursive);
 }

MediaBrowser.Controller/Persistence/ILinkedChildrenService.cs

@@ -0,0 +1,50 @@
+using System;
+using System.Collections.Generic;
+using MediaBrowser.Controller.Entities.Audio;
+using LinkedChildType = MediaBrowser.Controller.Entities.LinkedChildType;
+
+namespace MediaBrowser.Controller.Persistence;
+
+/// <summary>
+/// Provides linked children query and manipulation operations.
+/// </summary>
+public interface ILinkedChildrenService
+{
+    /// <summary>
+    /// Gets the IDs of linked children for the specified parent.
+    /// </summary>
+    /// <param name="parentId">The parent item ID.</param>
+    /// <param name="childType">Optional child type filter.</param>
+    /// <returns>List of child item IDs.</returns>
+    IReadOnlyList<Guid> GetLinkedChildrenIds(Guid parentId, int? childType = null);
+
+    /// <summary>
+    /// Gets all artist matches from the database.
+    /// </summary>
+    /// <param name="artistNames">The names of the artists.</param>
+    /// <returns>A map of the artist name and the potential matches.</returns>
+    IReadOnlyDictionary<string, MusicArtist[]> FindArtists(IReadOnlyList<string> artistNames);
+
+    /// <summary>
+    /// Gets parent IDs that reference the specified child with LinkedChildType.Manual.
+    /// </summary>
+    /// <param name="childId">The child item ID.</param>
+    /// <returns>List of parent IDs that reference the child.</returns>
+    IReadOnlyList<Guid> GetManualLinkedParentIds(Guid childId);
+
+    /// <summary>
+    /// Updates LinkedChildren references from one child to another.
+    /// </summary>
+    /// <param name="fromChildId">The child ID to re-route from.</param>
+    /// <param name="toChildId">The child ID to re-route to.</param>
+    /// <returns>List of parent item IDs whose LinkedChildren were modified.</returns>
+    IReadOnlyList<Guid> RerouteLinkedChildren(Guid fromChildId, Guid toChildId);
+
+    /// <summary>
+    /// Creates or updates a LinkedChild entry.
+    /// </summary>
+    /// <param name="parentId">The parent item ID.</param>
+    /// <param name="childId">The child item ID.</param>
+    /// <param name="childType">The type of linked child relationship.</param>
+    void UpsertLinkedChild(Guid parentId, Guid childId, LinkedChildType childType);
+}

MediaBrowser.Controller/Persistence/INextUpService.cs

@@ -0,0 +1,33 @@
+using System;
+using System.Collections.Generic;
+using MediaBrowser.Controller.Entities;
+
+namespace MediaBrowser.Controller.Persistence;
+
+/// <summary>
+/// Provides next-up episode query operations.
+/// </summary>
+public interface INextUpService
+{
+    /// <summary>
+    /// Gets the list of series presentation keys for next up.
+    /// </summary>
+    /// <param name="filter">The query.</param>
+    /// <param name="dateCutoff">The minimum date for a series to have been most recently watched.</param>
+    /// <returns>The list of keys.</returns>
+    IReadOnlyList<string> GetNextUpSeriesKeys(InternalItemsQuery filter, DateTime dateCutoff);
+
+    /// <summary>
+    /// Gets next up episodes for multiple series in a single batched query.
+    /// </summary>
+    /// <param name="filter">The query filter.</param>
+    /// <param name="seriesKeys">The series presentation unique keys to query.</param>
+    /// <param name="includeSpecials">Whether to include specials.</param>
+    /// <param name="includeWatchedForRewatching">Whether to include watched episodes for rewatching mode.</param>
+    /// <returns>A dictionary mapping series key to batch result.</returns>
+    IReadOnlyDictionary<string, NextUpEpisodeBatchResult> GetNextUpEpisodesBatch(
+        InternalItemsQuery filter,
+        IReadOnlyList<string> seriesKeys,
+        bool includeSpecials,
+        bool includeWatchedForRewatching);
+}