feat(server): asset search endpoint (#4931)

* feat(server): GET /assets endpoint

* chore: open api

* chore: use dumb name

* feat: search by make, model, lens, city, state, country

* chore: open api

* chore: pagination validation and tests

* chore: pr feedback

server/src/domain/asset/asset.service.ts

@@ -30,6 +30,8 @@ import {
   AssetIdsDto,
   AssetJobName,
   AssetJobsDto,
+  AssetOrder,
+  AssetSearchDto,
   AssetStatsDto,
   DownloadArchiveInfo,
   DownloadInfoDto,
@@ -91,6 +93,34 @@ export class AssetService {
     this.configCore = SystemConfigCore.create(configRepository);
   }
 
+  search(authUser: AuthUserDto, dto: AssetSearchDto) {
+    let checksum: Buffer | undefined = undefined;
+
+    if (dto.checksum) {
+      const encoding = dto.checksum.length === 28 ? 'base64' : 'hex';
+      checksum = Buffer.from(dto.checksum, encoding);
+    }
+
+    const enumToOrder = { [AssetOrder.ASC]: 'ASC', [AssetOrder.DESC]: 'DESC' } as const;
+    const order = dto.order ? enumToOrder[dto.order] : undefined;
+
+    return this.assetRepository
+      .search({
+        ...dto,
+        order,
+        checksum,
+        ownerId: authUser.id,
+      })
+      .then((assets) =>
+        assets.map((asset) =>
+          mapAsset(asset, {
+            stripMetadata: false,
+            withStack: true,
+          }),
+        ),
+      );
+  }
+
   canUploadFile({ authUser, fieldName, file }: UploadRequest): true {
     this.access.requireUploadAccess(authUser);
 

server/src/domain/asset/dto/asset.dto.ts

@@ -1,8 +1,161 @@
+import { AssetType } from '@app/infra/entities';
+import { ApiProperty } from '@nestjs/swagger';
 import { Type } from 'class-transformer';
-import { IsBoolean, IsInt, IsPositive, IsString } from 'class-validator';
-import { Optional, ValidateUUID } from '../../domain.util';
+import { IsBoolean, IsEnum, IsInt, IsPositive, IsString, Min } from 'class-validator';
+import { Optional, QueryBoolean, QueryDate, ValidateUUID } from '../../domain.util';
 import { BulkIdsDto } from '../response-dto';
 
+export enum AssetOrder {
+  ASC = 'asc',
+  DESC = 'desc',
+}
+
+export class AssetSearchDto {
+  @ValidateUUID({ optional: true })
+  id?: string;
+
+  @ValidateUUID({ optional: true })
+  libraryId?: string;
+
+  @IsString()
+  @Optional()
+  deviceAssetId?: string;
+
+  @IsString()
+  @Optional()
+  deviceId?: string;
+
+  @IsEnum(AssetType)
+  @Optional()
+  @ApiProperty({ enumName: 'AssetTypeEnum', enum: AssetType })
+  type?: AssetType;
+
+  @IsString()
+  @Optional()
+  checksum?: string;
+
+  @QueryBoolean({ optional: true })
+  isArchived?: boolean;
+
+  @QueryBoolean({ optional: true })
+  isEncoded?: boolean;
+
+  @QueryBoolean({ optional: true })
+  isExternal?: boolean;
+
+  @QueryBoolean({ optional: true })
+  isFavorite?: boolean;
+
+  @QueryBoolean({ optional: true })
+  isMotion?: boolean;
+
+  @QueryBoolean({ optional: true })
+  isOffline?: boolean;
+
+  @QueryBoolean({ optional: true })
+  isReadOnly?: boolean;
+
+  @QueryBoolean({ optional: true })
+  isVisible?: boolean;
+
+  @QueryBoolean({ optional: true })
+  withDeleted?: boolean;
+
+  @QueryBoolean({ optional: true })
+  withStacked?: boolean;
+
+  @QueryBoolean({ optional: true })
+  withExif?: boolean;
+
+  @QueryBoolean({ optional: true })
+  withPeople?: boolean;
+
+  @QueryDate({ optional: true })
+  createdBefore?: Date;
+
+  @QueryDate({ optional: true })
+  createdAfter?: Date;
+
+  @QueryDate({ optional: true })
+  updatedBefore?: Date;
+
+  @QueryDate({ optional: true })
+  updatedAfter?: Date;
+
+  @QueryDate({ optional: true })
+  trashedBefore?: Date;
+
+  @QueryDate({ optional: true })
+  trashedAfter?: Date;
+
+  @QueryDate({ optional: true })
+  takenBefore?: Date;
+
+  @QueryDate({ optional: true })
+  takenAfter?: Date;
+
+  @IsString()
+  @Optional()
+  originalFileName?: string;
+
+  @IsString()
+  @Optional()
+  originalPath?: string;
+
+  @IsString()
+  @Optional()
+  resizePath?: string;
+
+  @IsString()
+  @Optional()
+  webpPath?: string;
+
+  @IsString()
+  @Optional()
+  encodedVideoPath?: string;
+
+  @IsString()
+  @Optional()
+  city?: string;
+
+  @IsString()
+  @Optional()
+  state?: string;
+
+  @IsString()
+  @Optional()
+  country?: string;
+
+  @IsString()
+  @Optional()
+  make?: string;
+
+  @IsString()
+  @Optional()
+  model?: string;
+
+  @IsString()
+  @Optional()
+  lensModel?: string;
+
+  @IsEnum(AssetOrder)
+  @Optional()
+  @ApiProperty({ enumName: 'AssetOrder', enum: AssetOrder })
+  order?: AssetOrder;
+
+  @IsInt()
+  @Min(1)
+  @Type(() => Number)
+  @Optional()
+  page?: number;
+
+  @IsInt()
+  @Min(1)
+  @Type(() => Number)
+  @Optional()
+  size?: number;
+}
+
 export class AssetBulkUpdateDto extends BulkIdsDto {
   @Optional()
   @IsBoolean()

server/src/domain/domain.util.ts

@@ -1,6 +1,17 @@
 import { applyDecorators } from '@nestjs/common';
 import { ApiProperty } from '@nestjs/swagger';
-import { IsArray, IsNotEmpty, IsOptional, IsString, IsUUID, ValidateIf, ValidationOptions } from 'class-validator';
+import { Transform, Type } from 'class-transformer';
+import {
+  IsArray,
+  IsBoolean,
+  IsDate,
+  IsNotEmpty,
+  IsOptional,
+  IsString,
+  IsUUID,
+  ValidateIf,
+  ValidationOptions,
+} from 'class-validator';
 import { CronJob } from 'cron';
 import { basename, extname } from 'node:path';
 import sanitize from 'sanitize-filename';
@@ -33,6 +44,22 @@ interface IValue {
   value?: string;
 }
 
+export const QueryBoolean = ({ optional }: { optional?: boolean }) => {
+  const decorators = [IsBoolean(), Transform(toBoolean)];
+  if (optional) {
+    decorators.push(Optional());
+  }
+  return applyDecorators(...decorators);
+};
+
+export const QueryDate = ({ optional }: { optional?: boolean }) => {
+  const decorators = [IsDate(), Type(() => Date)];
+  if (optional) {
+    decorators.push(Optional());
+  }
+  return applyDecorators(...decorators);
+};
+
 export const toBoolean = ({ value }: IValue) => {
   if (value == 'true') {
     return true;

server/src/domain/repositories/asset.repository.ts

@@ -11,11 +11,58 @@ export interface AssetStatsOptions {
 }
 
 export interface AssetSearchOptions {
-  isVisible?: boolean;
-  trashedBefore?: Date;
+  id?: string;
+  libraryId?: string;
+  deviceAssetId?: string;
+  deviceId?: string;
+  ownerId?: string;
   type?: AssetType;
-  order?: 'ASC' | 'DESC';
+  checksum?: Buffer;
+
+  isArchived?: boolean;
+  isEncoded?: boolean;
+  isExternal?: boolean;
+  isFavorite?: boolean;
+  isMotion?: boolean;
+  isOffline?: boolean;
+  isReadOnly?: boolean;
+  isVisible?: boolean;
+
   withDeleted?: boolean;
+  withStacked?: boolean;
+  withExif?: boolean;
+  withPeople?: boolean;
+
+  createdBefore?: Date;
+  createdAfter?: Date;
+  updatedBefore?: Date;
+  updatedAfter?: Date;
+  trashedBefore?: Date;
+  trashedAfter?: Date;
+  takenBefore?: Date;
+  takenAfter?: Date;
+
+  originalFileName?: string;
+  originalPath?: string;
+  resizePath?: string;
+  webpPath?: string;
+  encodedVideoPath?: string;
+
+  city?: string;
+  state?: string;
+  country?: string;
+  make?: string;
+  model?: string;
+  lensModel?: string;
+
+  /** defaults to 'DESC' */
+  order?: 'ASC' | 'DESC';
+
+  /** defaults to 1 */
+  page?: number;
+
+  /** defaults to 250 */
+  size?: number;
 }
 
 export interface LivePhotoSearchOptions {
@@ -127,4 +174,5 @@ export interface IAssetRepository {
   getTimeBucket(timeBucket: string, options: TimeBucketOptions): Promise<AssetEntity[]>;
   upsertExif(exif: Partial<ExifEntity>): Promise<void>;
   upsertJobStatus(jobStatus: Partial<AssetJobStatusEntity>): Promise<void>;
+  search(options: AssetSearchOptions): Promise<AssetEntity[]>;
 }

server/src/immich/app.module.ts

@@ -16,6 +16,7 @@ import {
   AlbumController,
   AppController,
   AssetController,
+  AssetsController,
   AuditController,
   AuthController,
   JobController,
@@ -41,6 +42,7 @@ import { ErrorInterceptor, FileUploadInterceptor } from './interceptors';
   ],
   controllers: [
     ActivityController,
+    AssetsController,
     AssetController,
     AssetControllerV1,
     AppController,

server/src/immich/controllers/asset.controller.ts

@@ -4,6 +4,7 @@ import {
   AssetIdsDto,
   AssetJobsDto,
   AssetResponseDto,
+  AssetSearchDto,
   AssetService,
   AssetStatsDto,
   AssetStatsResponseDto,
@@ -42,6 +43,19 @@ import { UseValidation, asStreamableFile } from '../app.utils';
 import { Route } from '../interceptors';
 import { UUIDParamDto } from './dto/uuid-param.dto';
 
+@ApiTags('Asset')
+@Controller('assets')
+@Authenticated()
+@UseValidation()
+export class AssetsController {
+  constructor(private service: AssetService) {}
+
+  @Get()
+  searchAssets(@AuthUser() authUser: AuthUserDto, @Query() dto: AssetSearchDto): Promise<AssetResponseDto[]> {
+    return this.service.search(authUser, dto);
+  }
+}
+
 @ApiTags('Asset')
 @Controller(Route.ASSET)
 @Authenticated()

server/src/infra/repositories/asset.repository.ts

@@ -18,12 +18,15 @@ import {
 } from '@app/domain';
 import { Injectable } from '@nestjs/common';
 import { InjectRepository } from '@nestjs/typeorm';
+import _ from 'lodash';
 import { DateTime } from 'luxon';
 import { And, FindOptionsRelations, FindOptionsWhere, In, IsNull, LessThan, Not, Repository } from 'typeorm';
 import { AssetEntity, AssetJobStatusEntity, AssetType, ExifEntity } from '../entities';
 import OptionalBetween from '../utils/optional-between.util';
 import { paginate } from '../utils/pagination.util';
 
+const DEFAULT_SEARCH_SIZE = 250;
+
 const truncateMap: Record<TimeBucketSize, string> = {
   [TimeBucketSize.DAY]: 'day',
   [TimeBucketSize.MONTH]: 'month',
@@ -50,6 +53,134 @@ export class AssetRepository implements IAssetRepository {
     await this.jobStatusRepository.upsert(jobStatus, { conflictPaths: ['assetId'] });
   }
 
+  search(options: AssetSearchOptions): Promise<AssetEntity[]> {
+    const {
+      id,
+      libraryId,
+      deviceAssetId,
+      type,
+      checksum,
+      ownerId,
+
+      isVisible,
+      isFavorite,
+      isExternal,
+      isReadOnly,
+      isOffline,
+      isArchived,
+      isMotion,
+      isEncoded,
+
+      createdBefore,
+      createdAfter,
+      updatedBefore,
+      updatedAfter,
+      trashedBefore,
+      trashedAfter,
+      takenBefore,
+      takenAfter,
+
+      originalFileName,
+      originalPath,
+      resizePath,
+      webpPath,
+      encodedVideoPath,
+
+      city,
+      state,
+      country,
+      make,
+      model,
+      lensModel,
+
+      withDeleted: _withDeleted,
+      withExif: _withExif,
+      withStacked,
+      withPeople,
+
+      order,
+    } = options;
+
+    const withDeleted = _withDeleted ?? (trashedAfter !== undefined || trashedBefore !== undefined);
+
+    const page = Math.max(options.page || 1, 1);
+    const size = Math.min(options.size || DEFAULT_SEARCH_SIZE, DEFAULT_SEARCH_SIZE);
+
+    const exifWhere = _.omitBy(
+      {
+        city,
+        state,
+        country,
+        make,
+        model,
+        lensModel,
+      },
+      _.isUndefined,
+    );
+
+    const withExif = Object.keys(exifWhere).length > 0 || _withExif;
+
+    const where = _.omitBy(
+      {
+        ownerId,
+        id,
+        libraryId,
+        deviceAssetId,
+        type,
+        checksum,
+        isVisible,
+        isFavorite,
+        isExternal,
+        isReadOnly,
+        isOffline,
+        isArchived,
+        livePhotoVideoId: isMotion && Not(IsNull()),
+        originalFileName,
+        originalPath,
+        resizePath,
+        webpPath,
+        encodedVideoPath: encodedVideoPath ?? (isEncoded && Not(IsNull())),
+        createdAt: OptionalBetween(createdAfter, createdBefore),
+        updatedAt: OptionalBetween(updatedAfter, updatedBefore),
+        deletedAt: OptionalBetween(trashedAfter, trashedBefore),
+        fileCreatedAt: OptionalBetween(takenAfter, takenBefore),
+        exifInfo: Object.keys(exifWhere).length > 0 ? exifWhere : undefined,
+      },
+      _.isUndefined,
+    );
+
+    const builder = this.repository.createQueryBuilder('asset');
+
+    if (withExif) {
+      if (_withExif) {
+        builder.leftJoinAndSelect('asset.exifInfo', 'exifInfo');
+      } else {
+        builder.leftJoin('asset.exifInfo', 'exifInfo');
+      }
+    }
+
+    if (withPeople) {
+      builder.leftJoinAndSelect('asset.faces', 'faces');
+      builder.leftJoinAndSelect('faces.person', 'person');
+    }
+
+    if (withStacked) {
+      builder.leftJoinAndSelect('asset.stack', 'stack');
+    }
+
+    if (withDeleted) {
+      builder.withDeleted();
+    }
+
+    builder
+      .where(where)
+      .skip(size * (page - 1))
+      .take(size)
+      .orderBy('asset.fileCreatedAt', order ?? 'DESC');
+
+    return builder.getMany();
+  }
+
   create(asset: AssetCreate): Promise<AssetEntity> {
     return this.repository.save(asset);
   }