< Summary - Jellyfin

Information
Class: Jellyfin.Server.Implementations.Item.PeopleRepository
Assembly: Jellyfin.Server.Implementations
File(s): /srv/git/jellyfin/Jellyfin.Server.Implementations/Item/PeopleRepository.cs
Line coverage
58%
Covered lines: 155
Uncovered lines: 108
Coverable lines: 263
Total lines: 520
Line coverage: 58.9%
Branch coverage
53%
Covered branches: 61
Total branches: 114
Branch coverage: 53.5%
Method coverage

Feature is only available for sponsors

Upgrade to PRO version

Coverage history

Coverage history 0 25 50 75 100 5/31/2026 - 12:15:44 AM Line coverage: 0.6% (1/149) Branch coverage: 0% (0/70) Total lines: 3166/1/2026 - 12:16:05 AM Line coverage: 0.6% (1/157) Branch coverage: 0% (0/72) Total lines: 3277/27/2026 - 12:16:14 AM Line coverage: 0.6% (1/160) Branch coverage: 0% (0/72) Total lines: 3318/6/2026 - 12:17:15 AM Line coverage: 33.7% (61/181) Branch coverage: 17% (16/94) Total lines: 3848/9/2026 - 12:16:58 AM Line coverage: 28.5% (61/214) Branch coverage: 16% (16/100) Total lines: 43110/29/2026 - 12:17:11 AM Line coverage: 58.9% (155/263) Branch coverage: 53.5% (61/114) Total lines: 520 5/31/2026 - 12:15:44 AM Line coverage: 0.6% (1/149) Branch coverage: 0% (0/70) Total lines: 3166/1/2026 - 12:16:05 AM Line coverage: 0.6% (1/157) Branch coverage: 0% (0/72) Total lines: 3277/27/2026 - 12:16:14 AM Line coverage: 0.6% (1/160) Branch coverage: 0% (0/72) Total lines: 3318/6/2026 - 12:17:15 AM Line coverage: 33.7% (61/181) Branch coverage: 17% (16/94) Total lines: 3848/9/2026 - 12:16:58 AM Line coverage: 28.5% (61/214) Branch coverage: 16% (16/100) Total lines: 43110/29/2026 - 12:17:11 AM Line coverage: 58.9% (155/263) Branch coverage: 53.5% (61/114) Total lines: 520

Coverage delta

Coverage delta 38 -38

Metrics

MethodBranch coverage Crap Score Cyclomatic complexity Line coverage
.ctor(...)100%11100%
GetPeople(...)71.42%151482.14%
GetPeopleNames(...)0%4260%
UpdatePeople(...)85.71%2828100%
DeleteOrphanedCredits()100%11100%
DeleteCreditsWithoutMapping(...)100%66100%
GetPeopleNamesByItems(...)0%4260%
GetPeopleByItems(...)0%4260%
MapCredits(...)50%4475%
Map(...)50%66100%
Map(...)100%11100%
TranslateQuery(...)53.33%2243040%
IsAlphaNumeric(...)0%7280%
IsValidPersonType(...)100%210%

File(s)

/srv/git/jellyfin/Jellyfin.Server.Implementations/Item/PeopleRepository.cs

#LineLine coverage
 1using System;
 2using System.Collections.Generic;
 3using System.Linq;
 4using Jellyfin.Data.Enums;
 5using Jellyfin.Database.Implementations;
 6using Jellyfin.Database.Implementations.Entities;
 7using Jellyfin.Extensions;
 8using MediaBrowser.Controller.Entities;
 9using MediaBrowser.Controller.Persistence;
 10using MediaBrowser.Model.Querying;
 11using Microsoft.EntityFrameworkCore;
 12
 13namespace Jellyfin.Server.Implementations.Item;
 14#pragma warning disable RS0030 // Do not use banned APIs
 15#pragma warning disable CA1304 // Specify CultureInfo
 16#pragma warning disable CA1311 // Specify a culture or use an invariant version
 17#pragma warning disable CA1862 // Use the 'StringComparison' method overloads to perform case-insensitive string compari
 18
 19/// <summary>
 20/// Manager for handling people.
 21/// </summary>
 22/// <param name="dbProvider">Efcore Factory.</param>
 23/// <param name="itemTypeLookup">Items lookup service.</param>
 24/// <param name="queryHelpers">Shared item query helpers.</param>
 25/// <remarks>
 26/// Initializes a new instance of the <see cref="PeopleRepository"/> class.
 27/// </remarks>
 28public class PeopleRepository(IDbContextFactory<JellyfinDbContext> dbProvider, IItemTypeLookup itemTypeLookup, IItemQuer
 29{
 4930    private readonly IDbContextFactory<JellyfinDbContext> _dbProvider = dbProvider;
 31
 32    /// <inheritdoc/>
 33    public QueryResult<PersonInfo> GetPeople(InternalPeopleQuery filter)
 34    {
 835        using var context = _dbProvider.CreateDbContext();
 836        var dbQuery = TranslateQuery(context.Peoples.AsNoTracking(), context, filter);
 837        int? distinctNameCount = null;
 38
 39        // Include PeopleBaseItemMap
 840        if (!filter.ItemId.IsEmpty())
 41        {
 042            dbQuery = dbQuery.Include(p => p.BaseItems!.Where(m => m.ItemId == filter.ItemId))
 043                .OrderBy(e => e.BaseItems!.Where(m => m.ItemId == filter.ItemId).Min(m => m.ListOrder))
 044                .ThenBy(e => e.PersonType)
 045                .ThenBy(e => e.Name);
 46        }
 47        else
 48        {
 49            // The Peoples table has one row per (Name, PersonType), so the same person can
 50            // appear multiple times (e.g. as Actor and GuestStar). Collapse to one row per
 51            // name so /Persons doesn't return the same BaseItem id repeatedly, keeping the
 52            // lowest id per lowercased name so case-only duplicates collapse together.
 853            var candidates = dbQuery;
 854            dbQuery = candidates
 855                .Where(p => !candidates.Any(other => other.Name.ToLower() == p.Name.ToLower() && other.Id < p.Id))
 856                .OrderBy(e => e.Name.ToLower());
 57
 858            if (filter.EnableTotalRecordCount)
 59            {
 860                distinctNameCount = candidates.Select(e => e.Name.ToLower()).Distinct().Count();
 61            }
 62        }
 63
 864        var count = 0;
 865        if (filter.EnableTotalRecordCount)
 66        {
 867            count = distinctNameCount ?? dbQuery.Count();
 68        }
 69
 870        if (filter.StartIndex.HasValue && filter.StartIndex > 0)
 71        {
 072            dbQuery = dbQuery.Skip(filter.StartIndex.Value);
 73        }
 74
 875        if (filter.Limit > 0)
 76        {
 177            dbQuery = dbQuery.Take(filter.Limit);
 78        }
 79
 880        return new QueryResult<PersonInfo>
 881        {
 882            StartIndex = filter.StartIndex ?? 0,
 883            TotalRecordCount = count,
 884            Items = dbQuery.AsEnumerable().SelectMany(MapCredits).ToArray(),
 885        };
 886    }
 87
 88    /// <inheritdoc/>
 89    public IReadOnlyList<string> GetPeopleNames(InternalPeopleQuery filter)
 90    {
 091        using var context = _dbProvider.CreateDbContext();
 92
 093        IQueryable<string> dbQuery = TranslateQuery(context.Peoples.AsNoTracking(), context, filter)
 094            .Select(e => e.Name)
 095            .Distinct()
 096            .OrderBy(e => e);
 97
 098        if (filter.StartIndex.HasValue && filter.StartIndex > 0)
 99        {
 0100            dbQuery = dbQuery.Skip(filter.StartIndex.Value);
 101        }
 102
 0103        if (filter.Limit > 0)
 104        {
 0105            dbQuery = dbQuery.Take(filter.Limit);
 106        }
 107
 0108        return dbQuery.ToArray();
 0109    }
 110
 111    /// <inheritdoc />
 112    public void UpdatePeople(Guid itemId, IReadOnlyList<PersonInfo> people)
 113    {
 130114        foreach (var person in people)
 115        {
 38116            person.Name = person.Name.Trim();
 38117            person.Role = person.Role?.Trim() ?? string.Empty;
 118        }
 119
 120        // Project the values every comparison below needs once, so neither the case folding nor the
 121        // enum formatting is repeated per candidate.
 27122        var credits = people.Select(e => (Person: e, LoweredName: e.Name.ToLowerInvariant(), PersonType: e.Type.ToString
 123
 124        // multiple metadata providers can provide the _same_ credit; dedupe case-insensitively.
 125        // The role is part of the key because one person can hold several credits of the same type
 126        // on an item, e.g. a Writer credited for both the Novel and the Screenplay.
 27127        var distinctCredits = credits.DistinctBy(e => (e.LoweredName, e.PersonType, e.LoweredRole)).ToArray();
 128
 27129        var distinctPersons = distinctCredits.DistinctBy(e => (e.LoweredName, e.PersonType)).ToArray();
 130
 27131        using var context = _dbProvider.CreateDbContext();
 27132        var existingMaps = context.PeopleBaseItemMap
 27133            .AsNoTracking()
 27134            .Include(e => e.People)
 27135            .Where(e => e.ItemId == itemId)
 27136            .ToList();
 137
 138        // Most library scans refresh unchanged local metadata. Avoid opening a write
 139        // transaction when the item's people mappings, order and roles are unchanged.
 27140        var incomingCredits = distinctCredits
 27141            .Select((credit, index) => new
 27142            {
 27143                Key = (credit.LoweredName, credit.PersonType, credit.LoweredRole),
 27144                Role = credit.Person.Role,
 27145                ListOrder = index,
 27146                SortOrder = credit.Person.SortOrder
 27147            })
 27148            .ToDictionary(e => e.Key);
 27149        var mappingsAreUnchanged = existingMaps.Count == incomingCredits.Count
 27150            && existingMaps.All(map =>
 27151                incomingCredits.TryGetValue(
 27152                    (map.People.Name.ToLowerInvariant(), map.People.PersonType ?? string.Empty, map.Role?.ToLowerInvaria
 27153                    out var incoming)
 27154                && map.ListOrder == incoming.ListOrder
 27155                && map.SortOrder == incoming.SortOrder
 27156                && string.Equals(map.Role ?? string.Empty, incoming.Role, StringComparison.OrdinalIgnoreCase));
 157
 27158        if (mappingsAreUnchanged)
 159        {
 3160            return;
 161        }
 162
 24163        using var transaction = context.Database.BeginTransaction();
 164        // The fast-path snapshot was read before acquiring the write transaction. Reload
 165        // tracked mappings inside it so a concurrent refresh cannot leave stale credits.
 24166        existingMaps = context.PeopleBaseItemMap
 24167            .Include(e => e.People)
 24168            .Where(e => e.ItemId == itemId)
 24169            .ToList();
 170
 171        // Query each person type separately so SQLite can use IX_Peoples_NameLower.
 172        // Combining the two fields into `lower(Name) || '-' || PersonType` forces a full
 173        // scan of Peoples for every media item, which is prohibitive during a large import.
 24174        var existingPersons = new List<People>();
 96175        foreach (var personTypeGroup in distinctPersons.GroupBy(e => e.PersonType, StringComparer.Ordinal))
 176        {
 24177            var names = personTypeGroup
 24178                .Select(e => e.LoweredName)
 24179                .ToArray();
 180
 24181            existingPersons.AddRange(context.Peoples
 24182                .Where(e => e.PersonType == personTypeGroup.Key && names.Contains(e.Name.ToLower()))
 24183                .ToArray());
 184        }
 185
 24186        var existingPersonKeys = existingPersons.Select(e => (e.Name.ToLowerInvariant(), e.PersonType ?? string.Empty)).
 187
 24188        var toAdd = distinctPersons
 24189            .Where(e => !existingPersonKeys.Contains((e.LoweredName, e.PersonType)))
 24190            .Select(e => Map(e.Person))
 24191            .ToArray();
 24192        context.Peoples.AddRange(toAdd);
 24193        context.SaveChanges();
 194
 195        // The Peoples table can hold case-only duplicates, so keep the first match per key just as
 196        // the previous First() lookup did.
 24197        var personsEntities = new Dictionary<(string LoweredName, string PersonType), People>();
 112198        foreach (var entity in toAdd.Concat(existingPersons))
 199        {
 32200            personsEntities.TryAdd((entity.Name.ToLowerInvariant(), entity.PersonType ?? string.Empty), entity);
 201        }
 202
 24203        var existingMapsByCredit = new Dictionary<(string LoweredName, string PersonType, string LoweredRole), PeopleBas
 64204        foreach (var map in existingMaps)
 205        {
 8206            existingMapsByCredit.TryAdd((map.People.Name.ToLowerInvariant(), map.People.PersonType ?? string.Empty, map.
 207        }
 208
 24209        var listOrder = 0;
 210
 116211        foreach (var credit in distinctCredits)
 212        {
 34213            var entityPerson = personsEntities[(credit.LoweredName, credit.PersonType)];
 34214            if (existingMapsByCredit.TryGetValue((credit.LoweredName, credit.PersonType, credit.LoweredRole), out var ex
 215            {
 216                // Update the order for existing mappings
 5217                existingMap.ListOrder = listOrder;
 5218                existingMap.SortOrder = credit.Person.SortOrder;
 219                // person mapping already exists so remove from list
 5220                existingMaps.Remove(existingMap);
 221            }
 222            else
 223            {
 29224                context.PeopleBaseItemMap.Add(new PeopleBaseItemMap()
 29225                {
 29226                    Item = null!,
 29227                    ItemId = itemId,
 29228                    People = null!,
 29229                    PeopleId = entityPerson.Id,
 29230                    ListOrder = listOrder,
 29231                    SortOrder = credit.Person.SortOrder,
 29232                    Role = credit.Person.Role
 29233                });
 234            }
 235
 34236            listOrder++;
 237        }
 238
 24239        var droppedCredits = existingMaps.Select(e => e.PeopleId).Distinct().ToArray();
 24240        context.PeopleBaseItemMap.RemoveRange(existingMaps);
 241
 24242        context.SaveChanges();
 243
 244        // Nothing else ever deletes a credit row, so one left without a single mapping outlives the
 245        // credit it stood for: it keeps a person of that name off the dead-person sweep, which only
 246        // sees items no credit names, and keeps the name in every by-name list. That is how a credit
 247        // a provider dropped, or one a broken provider result invented, becomes impossible to clean up.
 24248        DeleteCreditsWithoutMapping(context, droppedCredits);
 249
 24250        context.SaveChanges();
 24251        transaction.Commit();
 51252    }
 253
 254    /// <inheritdoc/>
 255    public int DeleteOrphanedCredits()
 256    {
 2257        using var context = _dbProvider.CreateDbContext();
 258
 2259        return DeleteCreditsWithoutMapping(context, null);
 2260    }
 261
 262    // A null candidate list sweeps every credit, anything else only the ones just unmapped.
 263    private int DeleteCreditsWithoutMapping(JellyfinDbContext context, IReadOnlyList<Guid>? candidates)
 264    {
 26265        if (candidates is not null && candidates.Count == 0)
 266        {
 21267            return 0;
 268        }
 269
 5270        var credits = candidates is null
 5271            ? context.Peoples.AsQueryable()
 5272            : context.Peoples.WhereOneOrMany(candidates, e => e.Id);
 273
 5274        return credits.Where(e => !context.PeopleBaseItemMap.Any(f => f.PeopleId == e.Id)).ExecuteDelete();
 275    }
 276
 277    /// <inheritdoc/>
 278    public IReadOnlyDictionary<Guid, IReadOnlyList<string>> GetPeopleNamesByItems(IReadOnlyList<Guid> itemIds, IReadOnly
 279    {
 0280        using var context = _dbProvider.CreateDbContext();
 0281        var query = context.PeopleBaseItemMap
 0282            .AsNoTracking()
 0283            .WhereOneOrMany(itemIds, m => m.ItemId);
 284
 0285        if (personTypes.Count > 0)
 286        {
 0287            query = query.Where(m => personTypes.Contains(m.People.PersonType));
 288        }
 289
 0290        var rows = query
 0291            .OrderBy(m => m.ListOrder)
 0292            .Select(m => new { m.ItemId, m.People.Name })
 0293            .ToList();
 294
 0295        var result = new Dictionary<Guid, IReadOnlyList<string>>();
 0296        foreach (var group in rows.GroupBy(r => r.ItemId))
 297        {
 0298            var names = group
 0299                .Select(r => r.Name)
 0300                .Where(name => !string.IsNullOrEmpty(name))
 0301                .Distinct()
 0302                .ToArray();
 303
 0304            if (names.Length > 0)
 305            {
 0306                result[group.Key] = names;
 307            }
 308        }
 309
 0310        return result;
 0311    }
 312
 313    /// <inheritdoc/>
 314    public IReadOnlyDictionary<Guid, IReadOnlyList<PersonInfo>> GetPeopleByItems(IReadOnlyList<Guid> itemIds)
 315    {
 0316        using var context = _dbProvider.CreateDbContext();
 0317        var rows = context.PeopleBaseItemMap
 0318            .AsNoTracking()
 0319            .WhereOneOrMany(itemIds, m => m.ItemId)
 0320            .OrderBy(m => m.ListOrder)
 0321            .Select(m => new
 0322            {
 0323                m.ItemId,
 0324                m.Role,
 0325                m.SortOrder,
 0326                m.People.Id,
 0327                m.People.Name,
 0328                m.People.PersonType
 0329            })
 0330            .ToList();
 331
 0332        var result = new Dictionary<Guid, IReadOnlyList<PersonInfo>>();
 0333        foreach (var group in rows.GroupBy(r => r.ItemId))
 334        {
 0335            var people = new List<PersonInfo>();
 0336            foreach (var row in group)
 337            {
 0338                var personInfo = new PersonInfo
 0339                {
 0340                    ItemId = row.ItemId,
 0341                    Id = row.Id,
 0342                    Name = row.Name,
 0343                    Role = row.Role,
 0344                    SortOrder = row.SortOrder
 0345                };
 0346                if (Enum.TryParse<PersonKind>(row.PersonType, out var kind))
 347                {
 0348                    personInfo.Type = kind;
 349                }
 350
 0351                people.Add(personInfo);
 352            }
 353
 0354            result[group.Key] = people;
 355        }
 356
 0357        return result;
 0358    }
 359
 360    private IEnumerable<PersonInfo> MapCredits(People people)
 361    {
 13362        var mappings = people.BaseItems;
 13363        if (mappings is null || mappings.Count == 0)
 364        {
 13365            return [Map(people, null)];
 366        }
 367
 0368        return mappings.OrderBy(m => m.ListOrder).Select(m => Map(people, m));
 369    }
 370
 371    private PersonInfo Map(People people, PeopleBaseItemMap? mapping)
 372    {
 13373        var personInfo = new PersonInfo()
 13374        {
 13375            Id = people.Id,
 13376            Name = people.Name,
 13377            Role = mapping?.Role,
 13378            SortOrder = mapping?.SortOrder
 13379        };
 13380        if (Enum.TryParse<PersonKind>(people.PersonType, out var kind))
 381        {
 13382            personInfo.Type = kind;
 383        }
 384
 13385        return personInfo;
 386    }
 387
 388    private People Map(PersonInfo people)
 389    {
 26390        var personInfo = new People()
 26391        {
 26392            Name = people.Name,
 26393            PersonType = people.Type.ToString(),
 26394            Id = people.Id,
 26395        };
 396
 26397        return personInfo;
 398    }
 399
 400    private IQueryable<People> TranslateQuery(IQueryable<People> query, JellyfinDbContext context, InternalPeopleQuery f
 401    {
 8402        if (filter.User is not null && filter.IsFavorite.HasValue)
 403        {
 0404            var personType = itemTypeLookup.BaseItemKindNames[BaseItemKind.Person];
 0405            var userId = filter.User.Id;
 0406            var isFavorite = filter.IsFavorite.Value;
 0407            var favoriteItemIds = context.UserData
 0408                .Where(u => u.UserId.Equals(userId) && u.IsFavorite == isFavorite)
 0409                .Select(u => u.ItemId);
 410
 0411            var favoriteNames = context.BaseItems
 0412                .Where(b => b.Type == personType && favoriteItemIds.Contains(b.Id))
 0413                .Select(b => b.Name);
 414
 0415            query = query.Where(e => favoriteNames.Contains(e.Name));
 416        }
 417
 8418        if (filter.AccessFilter is not null)
 419        {
 420            // Keep only people credited on at least one item the user can see.
 0421            var accessibleItems = queryHelpers.ApplyAccessFiltering(context, context.BaseItems.AsNoTracking(), filter.Ac
 0422            query = query.Where(e => context.PeopleBaseItemMap
 0423                .Any(m => m.PeopleId == e.Id && accessibleItems.Any(i => i.Id == m.ItemId)));
 424        }
 425
 8426        if (filter.MustHaveItem)
 427        {
 428            // A credit with no by-name item behind it cannot be handed back as one.
 3429            var personType = itemTypeLookup.BaseItemKindNames[BaseItemKind.Person];
 3430            query = query.Where(e => context.BaseItems.Any(b => b.Type == personType && b.Name == e.Name));
 431        }
 432
 8433        if (!filter.ItemId.IsEmpty())
 434        {
 0435            var itemId = filter.ItemId;
 0436            query = query.Where(e => context.PeopleBaseItemMap
 0437                .Where(m => m.ItemId.Equals(itemId))
 0438                .Select(m => m.PeopleId)
 0439                .Contains(e.Id));
 440        }
 441
 8442        if (filter.ParentId != null)
 443        {
 0444            query = query.Where(e => e.BaseItems!.Any(w => context.AncestorIds.Any(i => i.ParentItemId == filter.ParentI
 445        }
 446
 8447        if (!filter.AppearsInItemId.IsEmpty())
 448        {
 0449            var appearsInItemId = filter.AppearsInItemId;
 0450            query = query.Where(e => context.PeopleBaseItemMap
 0451                .Where(m => m.ItemId.Equals(appearsInItemId))
 0452                .Select(m => m.PeopleId)
 0453                .Contains(e.Id));
 454        }
 455
 8456        var queryPersonTypes = filter.PersonTypes.Where(IsValidPersonType).ToList();
 8457        if (queryPersonTypes.Count > 0)
 458        {
 0459            query = query.Where(e => queryPersonTypes.Contains(e.PersonType));
 460        }
 461
 8462        var queryExcludePersonTypes = filter.ExcludePersonTypes.Where(IsValidPersonType).ToList();
 463
 8464        if (queryExcludePersonTypes.Count > 0)
 465        {
 0466            query = query.Where(e => !queryExcludePersonTypes.Contains(e.PersonType));
 467        }
 468
 8469        if (filter.MaxListOrder.HasValue && !filter.ItemId.IsEmpty())
 470        {
 0471            query = query.Where(e => e.BaseItems!.Any(w => w.ItemId == filter.ItemId && w.ListOrder <= filter.MaxListOrd
 472        }
 473
 8474        if (!string.IsNullOrWhiteSpace(filter.NameContains))
 475        {
 0476            var nameContainsUpper = filter.NameContains.ToUpper();
 0477            query = query.Where(e => e.Name.ToUpper().Contains(nameContainsUpper));
 478        }
 479
 8480        if (!string.IsNullOrWhiteSpace(filter.NameStartsWith))
 481        {
 0482            query = query.Where(e => e.Name.StartsWith(filter.NameStartsWith.ToLowerInvariant()));
 483        }
 484
 8485        if (!string.IsNullOrWhiteSpace(filter.NameLessThan))
 486        {
 3487            query = query.Where(e => e.Name.ToLower().CompareTo(filter.NameLessThan.ToLowerInvariant()) < 0);
 488        }
 489
 8490        if (!string.IsNullOrWhiteSpace(filter.NameStartsWithOrGreater))
 491        {
 2492            query = query.Where(e => e.Name.ToLower().CompareTo(filter.NameStartsWithOrGreater.ToLowerInvariant()) >= 0)
 493        }
 494
 8495        return query;
 496    }
 497
 498    private bool IsAlphaNumeric(string str)
 499    {
 0500        if (string.IsNullOrWhiteSpace(str))
 501        {
 0502            return false;
 503        }
 504
 0505        for (int i = 0; i < str.Length; i++)
 506        {
 0507            if (!char.IsLetter(str[i]) && !char.IsNumber(str[i]))
 508            {
 0509                return false;
 510            }
 511        }
 512
 0513        return true;
 514    }
 515
 516    private bool IsValidPersonType(string value)
 517    {
 0518        return IsAlphaNumeric(value);
 519    }
 520}