Skip to content

armgit / papra

Public Imported from GitHub
0

The minimalistic document archiving platform.

feat(documents): add configurable sorting to document search (#1088)

Corentin Thomassetbbe03aa53dd1
diff --git a/apps/papra-server/src/modules/documents/document-search/database-fts5/database-fts5.document-search-provider.ts b/apps/papra-server/src/modules/documents/document-search/database-fts5/database-fts5.document-search-provider.ts
index ad8becb7..9549b786 100644
--- a/apps/papra-server/src/modules/documents/document-search/database-fts5/database-fts5.document-search-provider.ts
+++ b/apps/papra-server/src/modules/documents/document-search/database-fts5/database-fts5.document-search-provider.ts
@@ -9,8 +9,8 @@ export function createDatabaseFts5DocumentSearchServices({ db }: { db: Database
return {
name: DATABASE_FTS5_DOCUMENT_SEARCH_PROVIDER_NAME,
- searchDocuments: async ({ searchQuery, organizationId, pageIndex, pageSize }) => {
- const { documents, documentsCount } = await documentsSearchRepository.searchOrganizationDocuments({ organizationId, searchQuery, pageIndex, pageSize });
+ searchDocuments: async ({ searchQuery, organizationId, pageIndex, pageSize, sort }) => {
+ const { documents, documentsCount } = await documentsSearchRepository.searchOrganizationDocuments({ organizationId, searchQuery, pageIndex, pageSize, sort });
return {
documents,
diff --git a/apps/papra-server/src/modules/documents/document-search/database-fts5/database-fts5.repository.models.test.ts b/apps/papra-server/src/modules/documents/document-search/database-fts5/database-fts5.repository.models.test.ts
index c7463b61..57ceb08b 100644
--- a/apps/papra-server/src/modules/documents/document-search/database-fts5/database-fts5.repository.models.test.ts
+++ b/apps/papra-server/src/modules/documents/document-search/database-fts5/database-fts5.repository.models.test.ts
@@ -1,7 +1,8 @@
+import type { SQL } from 'drizzle-orm';
import { describe, expect, test } from 'vitest';
import { stringifySqlQuery } from '../../../app/database/database.models';
import { createInMemoryDatabase } from '../../../app/database/database.test-utils';
-import { makeSearchWhereClause } from './database-fts5.repository.models';
+import { makeSearchOrderByClauses, makeSearchWhereClause } from './database-fts5.repository.models';
describe('database-fts5 repository models', () => {
describe('makeSearchWhereClause', async () => {
@@ -43,4 +44,64 @@ describe('database-fts5 repository models', () => {
});
});
});
+
+ describe('makeSearchOrderByClauses', () => {
+ const toOrderByClause = ({ orderByClauses }: { orderByClauses: SQL[] }) => orderByClauses.map(clause => stringifySqlQuery(clause)).map(({ query }) => query).join(', ');
+
+ test('sort by createdAt', () => {
+ expect(
+ toOrderByClause(makeSearchOrderByClauses({ sort: { field: 'createdAt', order: 'asc' } })),
+ ).to.eql(
+ '"documents"."created_at" asc, "documents"."id" asc',
+ );
+
+ expect(
+ toOrderByClause(makeSearchOrderByClauses({ sort: { field: 'createdAt', order: 'desc' } })),
+ ).to.eql(
+ '"documents"."created_at" desc, "documents"."id" desc',
+ );
+ });
+
+ test('sort by name, the name is sorted case-insensitively', () => {
+ expect(
+ toOrderByClause(makeSearchOrderByClauses({ sort: { field: 'name', order: 'desc' } })),
+ ).to.eql(
+ '"documents"."name" COLLATE NOCASE desc, "documents"."id" desc',
+ );
+
+ expect(
+ toOrderByClause(makeSearchOrderByClauses({ sort: { field: 'name', order: 'asc' } })),
+ ).to.eql(
+ '"documents"."name" COLLATE NOCASE asc, "documents"."id" asc',
+ );
+ });
+
+ test('sort by documentDate asc', () => {
+ expect(
+ toOrderByClause(makeSearchOrderByClauses({ sort: { field: 'documentDate', order: 'asc' } })),
+ ).to.eql(
+ '"documents"."document_date" asc, "documents"."id" asc',
+ );
+
+ expect(
+ toOrderByClause(makeSearchOrderByClauses({ sort: { field: 'documentDate', order: 'desc' } })),
+ ).to.eql(
+ '"documents"."document_date" desc, "documents"."id" desc',
+ );
+ });
+
+ test('sort by updatedAt desc', () => {
+ expect(
+ toOrderByClause(makeSearchOrderByClauses({ sort: { field: 'updatedAt', order: 'desc' } })),
+ ).to.eql(
+ '"documents"."updated_at" desc, "documents"."id" desc',
+ );
+
+ expect(
+ toOrderByClause(makeSearchOrderByClauses({ sort: { field: 'updatedAt', order: 'asc' } })),
+ ).to.eql(
+ '"documents"."updated_at" asc, "documents"."id" asc',
+ );
+ });
+ });
});
diff --git a/apps/papra-server/src/modules/documents/document-search/database-fts5/database-fts5.repository.models.ts b/apps/papra-server/src/modules/documents/document-search/database-fts5/database-fts5.repository.models.ts
index 4b81b14d..e65c9a29 100644
--- a/apps/papra-server/src/modules/documents/document-search/database-fts5/database-fts5.repository.models.ts
+++ b/apps/papra-server/src/modules/documents/document-search/database-fts5/database-fts5.repository.models.ts
@@ -1,7 +1,10 @@
+import type { SQL } from 'drizzle-orm';
+import type { SQLiteColumn } from 'drizzle-orm/sqlite-core';
import type { Database } from '../../../app/database/database.types';
+import type { DocumentSearchSort, DocumentSearchSortField } from '../document-search.constants';
import type { CustomPropertyDefinition } from './query-builder/query-builder.custom-properties';
import { parseSearchQuery } from '@papra/search-parser';
-import { and, eq } from 'drizzle-orm';
+import { and, asc, desc, eq, sql } from 'drizzle-orm';
import { documentsTable } from '../../documents.table';
import { buildQueryFromExpression } from './query-builder/query-builder';
@@ -23,3 +26,22 @@ export function makeSearchWhereClause({ query, organizationId, db, now = new Dat
issues: [...parsedIssues, ...issues],
};
}
+
+const sortableColumnsByField: Record<DocumentSearchSortField, SQLiteColumn | SQL> = {
+ createdAt: documentsTable.createdAt,
+ updatedAt: documentsTable.updatedAt,
+ name: sql`${documentsTable.name} COLLATE NOCASE`, // case-insensitive sorting for name
+ documentDate: documentsTable.documentDate,
+};
+
+export function makeSearchOrderByClauses({ sort }: { sort: DocumentSearchSort }) {
+ const sortColumn = sortableColumnsByField[sort.field];
+ const orderDirection = sort.order === 'desc' ? desc : asc;
+
+ const orderByClauses = [
+ orderDirection(sortColumn),
+ orderDirection(documentsTable.id), // tie-breaker to ensure deterministic order
+ ];
+
+ return { orderByClauses, sortColumn };
+}
diff --git a/apps/papra-server/src/modules/documents/document-search/database-fts5/database-fts5.repository.test.ts b/apps/papra-server/src/modules/documents/document-search/database-fts5/database-fts5.repository.test.ts
index 39b70c65..a371b64f 100644
--- a/apps/papra-server/src/modules/documents/document-search/database-fts5/database-fts5.repository.test.ts
+++ b/apps/papra-server/src/modules/documents/document-search/database-fts5/database-fts5.repository.test.ts
@@ -438,6 +438,141 @@ describe('database-fts5 repository', () => {
expect(searchResults).to.have.length(3);
expect(searchResults.map(doc => doc.id)).to.eql(['doc_3', 'doc_1', 'doc_2']);
});
+
+ describe('sort', () => {
+ test('documents can be sorted by name, case-insensitively', async () => {
+ const documents = [
+ { id: 'doc_1', organizationId: 'org_1', name: 'Banana', originalName: 'document-1.pdf', content: 'lorem ipsum', originalStorageKey: '', mimeType: 'application/pdf', originalSha256Hash: 'hash1', isDeleted: false },
+ { id: 'doc_2', organizationId: 'org_1', name: 'apple', originalName: 'document-2.pdf', content: 'lorem ipsum', originalStorageKey: '', mimeType: 'application/pdf', originalSha256Hash: 'hash2', isDeleted: false },
+ { id: 'doc_3', organizationId: 'org_1', name: 'cherry', originalName: 'document-3.pdf', content: 'lorem ipsum', originalStorageKey: '', mimeType: 'application/pdf', originalSha256Hash: 'hash3', isDeleted: false },
+ ];
+
+ const { db } = await createInMemoryDatabase({
+ organizations: [{ id: 'org_1', name: 'Organization 1' }],
+ documents,
+ });
+
+ const documentsSearchRepository = createDocumentSearchRepository({ db });
+ await documentsSearchRepository.indexDocuments({ documents });
+
+ const { documents: ascResults } = await documentsSearchRepository.searchOrganizationDocuments({
+ organizationId: 'org_1',
+ searchQuery: 'lorem',
+ pageIndex: 0,
+ pageSize: 10,
+ sort: { field: 'name', order: 'asc' },
+ });
+
+ expect(ascResults.map(doc => doc.id)).to.eql(['doc_2', 'doc_1', 'doc_3']);
+
+ const { documents: descResults } = await documentsSearchRepository.searchOrganizationDocuments({
+ organizationId: 'org_1',
+ searchQuery: 'lorem',
+ pageIndex: 0,
+ pageSize: 10,
+ sort: { field: 'name', order: 'desc' },
+ });
+
+ expect(descResults.map(doc => doc.id)).to.eql(['doc_3', 'doc_1', 'doc_2']);
+ });
+
+ test('documents can be sorted by document date, with null dates ordered first ascending and last descending', async () => {
+ const documents = [
+ { id: 'doc_1', organizationId: 'org_1', name: 'Document 1', originalName: 'document-1.pdf', content: 'lorem ipsum', originalStorageKey: '', mimeType: 'application/pdf', originalSha256Hash: 'hash1', isDeleted: false, documentDate: new Date('2026-03-01') },
+ { id: 'doc_2', organizationId: 'org_1', name: 'Document 2', originalName: 'document-2.pdf', content: 'lorem ipsum', originalStorageKey: '', mimeType: 'application/pdf', originalSha256Hash: 'hash2', isDeleted: false, documentDate: new Date('2026-01-01') },
+ { id: 'doc_3', organizationId: 'org_1', name: 'Document 3', originalName: 'document-3.pdf', content: 'lorem ipsum', originalStorageKey: '', mimeType: 'application/pdf', originalSha256Hash: 'hash3', isDeleted: false },
+ ];
+
+ const { db } = await createInMemoryDatabase({
+ organizations: [{ id: 'org_1', name: 'Organization 1' }],
+ documents,
+ });
+
+ const documentsSearchRepository = createDocumentSearchRepository({ db });
+ await documentsSearchRepository.indexDocuments({ documents });
+
+ const { documents: ascResults } = await documentsSearchRepository.searchOrganizationDocuments({
+ organizationId: 'org_1',
+ searchQuery: 'lorem',
+ pageIndex: 0,
+ pageSize: 10,
+ sort: { field: 'documentDate', order: 'asc' },
+ });
+
+ expect(ascResults.map(doc => doc.id)).to.eql(['doc_3', 'doc_2', 'doc_1']);
+
+ const { documents: descResults } = await documentsSearchRepository.searchOrganizationDocuments({
+ organizationId: 'org_1',
+ searchQuery: 'lorem',
+ pageIndex: 0,
+ pageSize: 10,
+ sort: { field: 'documentDate', order: 'desc' },
+ });
+
+ expect(descResults.map(doc => doc.id)).to.eql(['doc_1', 'doc_2', 'doc_3']);
+ });
+
+ test('documents can be sorted by update date', async () => {
+ const documents = [
+ { id: 'doc_1', organizationId: 'org_1', name: 'Document 1', originalName: 'document-1.pdf', content: 'lorem ipsum', originalStorageKey: '', mimeType: 'application/pdf', originalSha256Hash: 'hash1', isDeleted: false, updatedAt: new Date('2026-01-02T10:00:00Z') },
+ { id: 'doc_2', organizationId: 'org_1', name: 'Document 2', originalName: 'document-2.pdf', content: 'lorem ipsum', originalStorageKey: '', mimeType: 'application/pdf', originalSha256Hash: 'hash2', isDeleted: false, updatedAt: new Date('2026-01-03T10:00:00Z') },
+ { id: 'doc_3', organizationId: 'org_1', name: 'Document 3', originalName: 'document-3.pdf', content: 'lorem ipsum', originalStorageKey: '', mimeType: 'application/pdf', originalSha256Hash: 'hash3', isDeleted: false, updatedAt: new Date('2026-01-01T10:00:00Z') },
+ ];
+
+ const { db } = await createInMemoryDatabase({
+ organizations: [{ id: 'org_1', name: 'Organization 1' }],
+ documents,
+ });
+
+ const documentsSearchRepository = createDocumentSearchRepository({ db });
+ await documentsSearchRepository.indexDocuments({ documents });
+
+ const { documents: searchResults } = await documentsSearchRepository.searchOrganizationDocuments({
+ organizationId: 'org_1',
+ searchQuery: 'lorem',
+ pageIndex: 0,
+ pageSize: 10,
+ sort: { field: 'updatedAt', order: 'desc' },
+ });
+
+ expect(searchResults.map(doc => doc.id)).to.eql(['doc_2', 'doc_1', 'doc_3']);
+ });
+
+ test('sort is applied across pages', async () => {
+ const documents = [
+ { id: 'doc_1', organizationId: 'org_1', name: 'delta', originalName: 'document-1.pdf', content: 'lorem ipsum', originalStorageKey: '', mimeType: 'application/pdf', originalSha256Hash: 'hash1', isDeleted: false },
+ { id: 'doc_2', organizationId: 'org_1', name: 'alpha', originalName: 'document-2.pdf', content: 'lorem ipsum', originalStorageKey: '', mimeType: 'application/pdf', originalSha256Hash: 'hash2', isDeleted: false },
+ { id: 'doc_3', organizationId: 'org_1', name: 'charlie', originalName: 'document-3.pdf', content: 'lorem ipsum', originalStorageKey: '', mimeType: 'application/pdf', originalSha256Hash: 'hash3', isDeleted: false },
+ { id: 'doc_4', organizationId: 'org_1', name: 'bravo', originalName: 'document-4.pdf', content: 'lorem ipsum', originalStorageKey: '', mimeType: 'application/pdf', originalSha256Hash: 'hash4', isDeleted: false },
+ ];
+
+ const { db } = await createInMemoryDatabase({
+ organizations: [{ id: 'org_1', name: 'Organization 1' }],
+ documents,
+ });
+
+ const documentsSearchRepository = createDocumentSearchRepository({ db });
+ await documentsSearchRepository.indexDocuments({ documents });
+
+ const { documents: page0 } = await documentsSearchRepository.searchOrganizationDocuments({
+ organizationId: 'org_1',
+ searchQuery: 'lorem',
+ pageIndex: 0,
+ pageSize: 2,
+ sort: { field: 'name', order: 'asc' },
+ });
+ const { documents: page1 } = await documentsSearchRepository.searchOrganizationDocuments({
+ organizationId: 'org_1',
+ searchQuery: 'lorem',
+ pageIndex: 1,
+ pageSize: 2,
+ sort: { field: 'name', order: 'asc' },
+ });
+
+ expect(page0.map(doc => doc.id)).to.eql(['doc_2', 'doc_4']);
+ expect(page1.map(doc => doc.id)).to.eql(['doc_3', 'doc_1']);
+ });
+ });
});
describe('indexDocuments', () => {
diff --git a/apps/papra-server/src/modules/documents/document-search/database-fts5/database-fts5.repository.ts b/apps/papra-server/src/modules/documents/document-search/database-fts5/database-fts5.repository.ts
index 6bae5fa8..649a1e4e 100644
--- a/apps/papra-server/src/modules/documents/document-search/database-fts5/database-fts5.repository.ts
+++ b/apps/papra-server/src/modules/documents/document-search/database-fts5/database-fts5.repository.ts
@@ -1,12 +1,14 @@
import type { Database } from '../../../app/database/database.types';
+import type { DocumentSearchSort } from '../document-search.constants';
import type { DocumentSearchableData, DocumentUpdate } from '../document-search.types';
import { injectArguments } from '@corentinth/chisels';
-import { desc, eq, getTableColumns, inArray, sql } from 'drizzle-orm';
+import { eq, getTableColumns, inArray, sql } from 'drizzle-orm';
import { customPropertyDefinitionsTable } from '../../../custom-properties/custom-properties.table';
import { isNonEmptyArray } from '../../../shared/arrays/arrays.utils';
import { omit, omitUndefined } from '../../../shared/objects';
import { documentsTable } from '../../documents.table';
-import { makeSearchWhereClause } from './database-fts5.repository.models';
+import { DEFAULT_DOCUMENT_SEARCH_SORT } from '../document-search.constants';
+import { makeSearchOrderByClauses, makeSearchWhereClause } from './database-fts5.repository.models';
import { documentsFtsTable } from './database-fts5.tables';
export type DocumentSearchRepository = ReturnType<typeof createDocumentSearchRepository>;
@@ -21,19 +23,21 @@ export function createDocumentSearchRepository({ db }: { db: Database }) {
}, { db });
}
-async function searchOrganizationDocuments({ organizationId, searchQuery, pageIndex, pageSize, db, now = new Date() }: { organizationId: string; searchQuery: string; pageIndex: number; pageSize: number; db: Database; now?: Date }) {
+async function searchOrganizationDocuments({ organizationId, searchQuery, pageIndex, pageSize, sort = DEFAULT_DOCUMENT_SEARCH_SORT, db, now = new Date() }: { organizationId: string; searchQuery: string; pageIndex: number; pageSize: number; sort?: DocumentSearchSort; db: Database; now?: Date }) {
const customPropertyDefinitions = await db
.select()
.from(customPropertyDefinitionsTable)
.where(eq(customPropertyDefinitionsTable.organizationId, organizationId));
const { searchWhereClause } = makeSearchWhereClause({ organizationId, query: searchQuery, db, now, customPropertyDefinitions });
+ const { orderByClauses, sortColumn } = makeSearchOrderByClauses({ sort });
const paginatedIdsSubquery = db
- .selectDistinct({ id: documentsTable.id, createdAt: documentsTable.createdAt })
+ // selecting the sort value keeps it in the result set so the DISTINCT + ORDER BY of the paginated subquery stays unambiguous (the tag filters can otherwise produce duplicate rows per document)
+ .selectDistinct({ id: documentsTable.id, sortValue: sql`${sortColumn}`.as('sort_value') })
.from(documentsTable)
.where(searchWhereClause)
- .orderBy(desc(documentsTable.createdAt))
+ .orderBy(...orderByClauses)
.limit(pageSize)
.offset(pageIndex * pageSize)
.as('paginated_docs');
@@ -50,7 +54,8 @@ async function searchOrganizationDocuments({ organizationId, searchQuery, pageIn
})
.from(paginatedIdsSubquery)
.innerJoin(documentsTable, eq(documentsTable.id, paginatedIdsSubquery.id))
- .orderBy(desc(paginatedIdsSubquery.createdAt)),
+ // re-apply the sort on the joined documents table so the collation of `sortColumn` is honoured here too
+ .orderBy(...orderByClauses),
]);
const documentsCount = totalCountResult[0]?.count ?? 0;
diff --git a/apps/papra-server/src/modules/documents/document-search/document-search.constants.ts b/apps/papra-server/src/modules/documents/document-search/document-search.constants.ts
new file mode 100644
index 00000000..2f0c44a0
--- /dev/null
+++ b/apps/papra-server/src/modules/documents/document-search/document-search.constants.ts
@@ -0,0 +1,12 @@
+export const documentSearchSortFields = ['createdAt', 'updatedAt', 'name', 'documentDate'] as const;
+export type DocumentSearchSortField = (typeof documentSearchSortFields)[number];
+
+export const documentSearchSortOrders = ['asc', 'desc'] as const;
+export type DocumentSearchSortOrder = (typeof documentSearchSortOrders)[number];
+
+export type DocumentSearchSort = {
+ field: DocumentSearchSortField;
+ order: DocumentSearchSortOrder;
+};
+
+export const DEFAULT_DOCUMENT_SEARCH_SORT: DocumentSearchSort = { field: 'createdAt', order: 'desc' };
diff --git a/apps/papra-server/src/modules/documents/document-search/document-search.types.ts b/apps/papra-server/src/modules/documents/document-search/document-search.types.ts
index 4963a14e..62d54a9c 100644
--- a/apps/papra-server/src/modules/documents/document-search/document-search.types.ts
+++ b/apps/papra-server/src/modules/documents/document-search/document-search.types.ts
@@ -1,4 +1,5 @@
import type { Document } from '../documents.types';
+import type { DocumentSearchSort } from './document-search.constants';
export type DocumentSearchableData = {
id: string;
@@ -25,6 +26,7 @@ export type DocumentSearchServices = {
organizationId: string;
pageIndex: number;
pageSize: number;
+ sort?: DocumentSearchSort;
}) => Promise<DocumentSearchResult>;
getDocumentIdsMatchingQuery: (args: {
diff --git a/apps/papra-server/src/modules/documents/document-search/document-search.usecase.ts b/apps/papra-server/src/modules/documents/document-search/document-search.usecase.ts
index 0834a3d0..411db766 100644
--- a/apps/papra-server/src/modules/documents/document-search/document-search.usecase.ts
+++ b/apps/papra-server/src/modules/documents/document-search/document-search.usecase.ts
@@ -1,12 +1,15 @@
import type { Logger } from '../../shared/logger/logger';
+import type { DocumentSearchSort } from './document-search.constants';
import type { DocumentSearchServices } from './document-search.types';
import { createLogger } from '../../shared/logger/logger';
+import { DEFAULT_DOCUMENT_SEARCH_SORT } from './document-search.constants';
export async function searchOrganizationDocuments({
searchQuery,
organizationId,
pageIndex,
pageSize,
+ sort = DEFAULT_DOCUMENT_SEARCH_SORT,
documentSearchServices,
logger = createLogger({ namespace: 'document-search.usecase' }),
}: {
@@ -14,6 +17,7 @@ export async function searchOrganizationDocuments({
organizationId: string;
pageIndex: number;
pageSize: number;
+ sort?: DocumentSearchSort;
documentSearchServices: DocumentSearchServices;
logger?: Logger;
}) {
@@ -23,6 +27,7 @@ export async function searchOrganizationDocuments({
organizationId,
pageIndex,
pageSize,
+ sort,
});
const durationMs = Date.now() - startTime;
@@ -30,6 +35,8 @@ export async function searchOrganizationDocuments({
organizationId,
pageIndex,
pageSize,
+ sortField: sort.field,
+ sortOrder: sort.order,
durationMs,
pageDocumentCount: documents.length,
}, 'Executed document search');