The minimalistic document archiving platform.
feat(search): add `created` filter for document search (#762)
Corentin Thomassetb657f727ba4c
diff --git a/apps/docs/src/content/docs/03-guides/08-advanced-search.mdx b/apps/docs/src/content/docs/03-guides/08-advanced-search.mdxindex 45644d73..3ab15723 100644--- a/apps/docs/src/content/docs/03-guides/08-advanced-search.mdx+++ b/apps/docs/src/content/docs/03-guides/08-advanced-search.mdx@@ -32,31 +32,74 @@ Use filters to search specific document properties. Current supported filters:- `name:` - Search in document names- `content:` - Search in document content- `tag:` - Search by tag name or ID+- `created:` - Filter by document creation date### Filter Examples```yaml+# Finds documents whose name contains "invoice"name:invoice-```--Finds documents whose name contains "invoice"-```yaml+# Finds documents with "financial report" in their content+# use quotes for phrases with spacescontent:"financial report"-```--Finds documents with "financial report" in their content (use quotes for phrases with spaces)-```yaml+# Finds documents tagged with "urgent"tag:urgent++# Finds documents created after January 1st, 2024+created:>2024```-Finds documents tagged with "urgent":::noteThe `name:` and `content:` filters use **contains** matching, not exact equality. So `name:foo` will match documents named "foo", "foobar", "my-foo-document", etc.:::+### Date Filter++The `created:` filter supports date comparisons with the following operators:++- `=` - Exact date match+- `>` - After the date+- `>=` - On or after the date+- `<` - Before the date+- `<=` - On or before the date++#### Date Format++Dates can be specified in various formats, including:++- Only year: `YYYY` (interpreted as January 1st of that year)+- Month and year: `YYYY-MM` (interpreted as the first day of that month)+- Common formats: `YYYY/MM/DD`, `YYYY.MM.DD`, `Month DD, YYYY`, etc.+- ISO 8601: `YYYY-MM-DD`, `YYYY-MM-DDTHH:MM:SSZ`, etc.++Invalid date formats will be ignored in the search query.++#### Date Filter Examples++```yaml+# Finds documents created exactly on January 15th, 2024 at 00:00:00+created:2024-01-15++# Finds documents created after January 1st, 2024+created:>2024++# Finds documents created on or after January 1st, 2024+created:>=2024-01-01++# Finds documents created before December 31st, 2024+created:<2024-12-31++# Finds documents created on or before June 30th, 2024+created:<=2024-06-30++# Finds invoices created only in 2024+tag:invoice created:>2024 created:<2025+```++## Logical OperatorsCombine filters using logical operators (case-insensitive):diff --git a/apps/docs/src/content/docs/04-resources/03-api-endpoints.mdx b/apps/docs/src/content/docs/04-resources/03-api-endpoints.mdxindex b3c2b77b..e89bf749 100644--- a/apps/docs/src/content/docs/04-resources/03-api-endpoints.mdx+++ b/apps/docs/src/content/docs/04-resources/03-api-endpoints.mdx@@ -210,7 +210,7 @@ Search documents in the organization by name or content.- Required API key permissions: `documents:read`- Query parameters- - `searchQuery`: The search query.+ - `searchQuery`: The search query. Supports advanced search syntax with filters (`name:`, `content:`, `tag:`, `created:`), logical operators (`AND`, `OR`, `NOT`), and grouping. See the [Advanced Search guide](/guides/advanced-search) for details.- `pageIndex`: (optional, default: 0) The page index to start from.- `pageSize`: (optional, default: 100) The number of documents to return.- Response (JSON)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.tsindex 522a0220..5808793a 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@@ -259,11 +259,11 @@ describe('database-fts5 repository', () => {describe('search query can have filters', async () => {const documents = [- { id: 'doc_1', organizationId: 'org_1', name: 'Invoice cloudflare', originalName: 'document-1.pdf', content: 'Cloudflare invoice, hosting 5€', originalStorageKey: '', mimeType: 'application/pdf', originalSha256Hash: 'hash1', isDeleted: false },- { id: 'doc_2', organizationId: 'org_1', name: 'Invoice smartphone', originalName: 'document-1.pdf', content: 'The smartphone invoice', originalStorageKey: '', mimeType: 'application/pdf', originalSha256Hash: 'hash2', isDeleted: false },- { id: 'doc_3', organizationId: 'org_1', name: 'Car invoice', originalName: 'document-1.pdf', content: 'Your brand new car invoice, insurance attached', originalStorageKey: '', mimeType: 'application/pdf', originalSha256Hash: 'hash3', isDeleted: false },- { id: 'doc_4', organizationId: 'org_1', name: 'Car insurance', originalName: 'document-2.pdf', content: 'Your car insurance contract', originalStorageKey: '', mimeType: 'application/pdf', originalSha256Hash: 'hash4', isDeleted: false },- { id: 'doc_5', organizationId: 'org_1', name: 'Meeting notes', originalName: 'document-3.pdf', content: 'Notes from the meeting about the new project', originalStorageKey: '', mimeType: 'application/pdf', originalSha256Hash: 'hash5', isDeleted: false },+ { id: 'doc_1', organizationId: 'org_1', name: 'Invoice cloudflare', originalName: 'document-1.pdf', content: 'Cloudflare invoice, hosting 5€', originalStorageKey: '', mimeType: 'application/pdf', originalSha256Hash: 'hash1', isDeleted: false, createdAt: new Date('2026-01-10') },+ { id: 'doc_2', organizationId: 'org_1', name: 'Invoice smartphone', originalName: 'document-1.pdf', content: 'The smartphone invoice', originalStorageKey: '', mimeType: 'application/pdf', originalSha256Hash: 'hash2', isDeleted: false, createdAt: new Date('2026-01-11') },+ { id: 'doc_3', organizationId: 'org_1', name: 'Car invoice', originalName: 'document-1.pdf', content: 'Your brand new car invoice, insurance attached', originalStorageKey: '', mimeType: 'application/pdf', originalSha256Hash: 'hash3', isDeleted: false, createdAt: new Date('2026-01-12') },+ { id: 'doc_4', organizationId: 'org_1', name: 'Car insurance', originalName: 'document-2.pdf', content: 'Your car insurance contract', originalStorageKey: '', mimeType: 'application/pdf', originalSha256Hash: 'hash4', isDeleted: false, createdAt: new Date('2026-01-13') },+ { id: 'doc_5', organizationId: 'org_1', name: 'Meeting notes', originalName: 'document-3.pdf', content: 'Notes from the meeting about the new project', originalStorageKey: '', mimeType: 'application/pdf', originalSha256Hash: 'hash5', isDeleted: false, createdAt: new Date('2026-01-14') },];const { db } = await createInMemoryDatabase({@@ -317,6 +317,14 @@ describe('database-fts5 repository', () => {searchQuery: 'name:invoice tag:invoice smartphone',expectedDocumentsIds: ['doc_2'],},+ {+ searchQuery: 'created:>=2026-01-12',+ expectedDocumentsIds: ['doc_3', 'doc_4', 'doc_5'],+ },+ {+ searchQuery: 'created:>=2026-01-12 created:<=2026-01-13',+ expectedDocumentsIds: ['doc_3', 'doc_4'],+ },];for (const { searchQuery, expectedDocumentsIds } of searches) {diff --git a/apps/papra-server/src/modules/documents/document-search/database-fts5/query-builder/query-builder.models.ts b/apps/papra-server/src/modules/documents/document-search/database-fts5/query-builder/query-builder.models.tsindex ae9326ee..1c3fbe44 100644--- a/apps/papra-server/src/modules/documents/document-search/database-fts5/query-builder/query-builder.models.ts+++ b/apps/papra-server/src/modules/documents/document-search/database-fts5/query-builder/query-builder.models.ts@@ -1,3 +1,6 @@+import type { Operator } from '@papra/search-parser';+import type { BinaryOperator } from 'drizzle-orm';+import { eq, gt, gte, lt, lte } from 'drizzle-orm';import { documentsFtsTable } from '../database-fts5.tables';function joinColumnNames(columns: string[]): string {@@ -36,3 +39,15 @@ export function createUnsupportedOperatorIssue({ operator, field }: { operator:code: 'UNSUPPORTED_FILTER_OPERATOR',};}++const operatorsMap: Record<Operator, BinaryOperator> = {+ '=': eq,+ '<': lt,+ '<=': lte,+ '>': gt,+ '>=': gte,+};++export function getSqlOperator({ operator }: { operator: Operator }): BinaryOperator {+ return operatorsMap[operator];+}diff --git a/apps/papra-server/src/modules/documents/document-search/database-fts5/query-builder/query-builder.test.ts b/apps/papra-server/src/modules/documents/document-search/database-fts5/query-builder/query-builder.test.tsindex d5adc9c9..3f10a5b3 100644--- a/apps/papra-server/src/modules/documents/document-search/database-fts5/query-builder/query-builder.test.ts+++ b/apps/papra-server/src/modules/documents/document-search/database-fts5/query-builder/query-builder.test.ts@@ -2,7 +2,7 @@ import type { SQL } from 'drizzle-orm';import { SQLiteSyncDialect } from 'drizzle-orm/sqlite-core';import { describe, expect, test } from 'vitest';import { createInMemoryDatabase } from '../../../../app/database/database.test-utils';-import { handleAndExpression, handleContentFilter, handleEmptyExpression, handleNameFilter, handleNotExpression, handleOrExpression, handleTextExpression, handleUnsupportedExpression } from './query-builder';+import { handleAndExpression, handleContentFilter, handleCreatedFilter, handleEmptyExpression, handleNameFilter, handleNotExpression, handleOrExpression, handleTextExpression, handleUnsupportedExpression } from './query-builder';describe('query-builder', async () => {const { db } = await createInMemoryDatabase();@@ -110,6 +110,118 @@ describe('query-builder', async () => {});});+ describe('handleCreatedFilter', () => {+ test('supports equality operator for date filtering', () => {+ const { sqlQuery, issues } = handleCreatedFilter({+ expression: { type: 'filter', field: 'created', value: '2024-01-15', operator: '=' },+ });++ expect(issues).to.eql([]);++ expect(getSqlString(sqlQuery)).to.eql({+ sql: `\"documents\".\"created_at\" = ?`,+ params: [1705276800000],+ });+ });++ test('supports greater than operator for date filtering', () => {+ const { sqlQuery, issues } = handleCreatedFilter({+ expression: { type: 'filter', field: 'created', value: '2024-01-15', operator: '>' },+ });++ expect(issues).to.eql([]);++ expect(getSqlString(sqlQuery)).to.eql({+ sql: `\"documents\".\"created_at\" > ?`,+ params: [1705276800000],+ });+ });++ test('supports greater than or equal operator for date filtering', () => {+ const { sqlQuery, issues } = handleCreatedFilter({+ expression: { type: 'filter', field: 'created', value: '2024-01-15', operator: '>=' },+ });++ expect(issues).to.eql([]);++ expect(getSqlString(sqlQuery)).to.eql({+ sql: `\"documents\".\"created_at\" >= ?`,+ params: [1705276800000],+ });+ });++ test('supports less than operator for date filtering', () => {+ const { sqlQuery, issues } = handleCreatedFilter({+ expression: { type: 'filter', field: 'created', value: '2024-01-15', operator: '<' },+ });++ expect(issues).to.eql([]);++ expect(getSqlString(sqlQuery)).to.eql({+ sql: `\"documents\".\"created_at\" < ?`,+ params: [1705276800000],+ });+ });++ test('supports less than or equal operator for date filtering', () => {+ const { sqlQuery, issues } = handleCreatedFilter({+ expression: { type: 'filter', field: 'created', value: '2024-01-15', operator: '<=' },+ });++ expect(issues).to.eql([]);++ expect(getSqlString(sqlQuery)).to.eql({+ sql: `\"documents\".\"created_at\" <= ?`,+ params: [1705276800000],+ });+ });++ test('returns an error for invalid date format', () => {+ const { sqlQuery, issues } = handleCreatedFilter({+ expression: { type: 'filter', field: 'created', value: 'not-a-date', operator: '=' },+ });++ expect(issues).to.eql([{+ message: 'Invalid date format "not-a-date" for created filter',+ code: 'INVALID_DATE_FORMAT',+ }]);++ expect(getSqlString(sqlQuery)).to.eql({ sql: `0`, params: [] });+ });++ test('accepts various ISO date formats', () => {+ const dateFormats = {+ '2024': 1704067200000,+ '2024-01': 1704067200000,+ '2024-01-15': 1705276800000,+ '2024-01-15T00:00:00Z': 1705276800000,+ '2024-01-15T00:00:00.000Z': 1705276800000,+ '2024-01-15T02:00:00+02:00': 1705276800000,+ '2024/01/15': 1705276800000,+ '2024/01/15 00:00:00': 1705276800000,+ '2024.01.15': 1705276800000,+ '2024,01,15': 1705276800000,+ '2024 01 15': 1705276800000,+ 'January 15, 2024': 1705276800000,+ 'Jan 15 2024': 1705276800000,+ '15 January 2024': 1705276800000,+ '15 Jan 2024': 1705276800000,+ };++ for (const [dateFormat, timestamp] of Object.entries(dateFormats)) {+ const { sqlQuery, issues } = handleCreatedFilter({+ expression: { type: 'filter', field: 'created', value: dateFormat, operator: '=' },+ });++ expect(issues).to.eql([]);+ expect(getSqlString(sqlQuery)).to.eql({+ sql: `\"documents\".\"created_at\" = ?`,+ params: [timestamp],+ });+ }+ });+ });+describe('handleEmptyExpression', () => {test('when the expression is empty, it returns a no-op SQL query that always evaluates to true', () => {const { sqlQuery, issues } = handleEmptyExpression();diff --git a/apps/papra-server/src/modules/documents/document-search/database-fts5/query-builder/query-builder.ts b/apps/papra-server/src/modules/documents/document-search/database-fts5/query-builder/query-builder.tsindex 27adde7c..15528bfb 100644--- a/apps/papra-server/src/modules/documents/document-search/database-fts5/query-builder/query-builder.ts+++ b/apps/papra-server/src/modules/documents/document-search/database-fts5/query-builder/query-builder.ts@@ -2,10 +2,11 @@ import type { AndExpression, Expression, FilterExpression, NotExpression, OrExprimport type { Database } from '../../../../app/database/database.types';import type { QueryResult } from './query-builder.types';import { and, eq, inArray, not, or, sql } from 'drizzle-orm';+import { isValidDate } from '../../../../shared/date';import { documentsTagsTable, tagsTable } from '../../../../tags/tags.table';import { documentsTable } from '../../../documents.table';import { documentsFtsTable } from '../database-fts5.tables';-import { createUnsupportedOperatorIssue, formatFts5QueryValue } from './query-builder.models';+import { createUnsupportedOperatorIssue, formatFts5QueryValue, getSqlOperator } from './query-builder.models';export function handleEmptyExpression(): QueryResult {return {@@ -151,6 +152,31 @@ export function handleTagFilter({ expression, organizationId, db }: { expression};}+export function handleCreatedFilter({ expression }: { expression: FilterExpression }): QueryResult {+ const { value, operator } = expression;++ const dateValue = new Date(value);++ if (!isValidDate(dateValue)) {+ return {+ sqlQuery: sql`0`,+ issues: [+ {+ message: `Invalid date format "${value}" for created filter`,+ code: 'INVALID_DATE_FORMAT',+ },+ ],+ };+ }++ const sqlOperator = getSqlOperator({ operator });++ return {+ sqlQuery: sqlOperator(documentsTable.createdAt, dateValue),+ issues: [],+ };+}+export function handleUnsupportedExpression(): QueryResult {return {sqlQuery: sql`0`,@@ -176,6 +202,7 @@ export function buildQueryFromExpression({ expression, organizationId, db }: { ecase 'tag': return handleTagFilter({ expression, organizationId, db });case 'name': return handleNameFilter({ expression, organizationId, db });case 'content': return handleContentFilter({ expression, organizationId, db });+ case 'created': return handleCreatedFilter({ expression });default: return handleUnsupportedExpression();}default: return handleUnsupportedExpression();diff --git a/apps/papra-server/src/modules/shared/date.test.ts b/apps/papra-server/src/modules/shared/date.test.tsnew file mode 100644index 00000000..dd072f4d--- /dev/null+++ b/apps/papra-server/src/modules/shared/date.test.ts@@ -0,0 +1,15 @@+import { describe, expect, test } from 'vitest';+import { isValidDate } from './date';++describe('date', () => {+ describe('isValidDate', () => {+ test('ensure that a date is valid and there are no parsing issues', () => {+ expect(isValidDate(new Date())).toBe(true);+ expect(isValidDate(new Date('2024-01-15'))).toBe(true);+ expect(isValidDate(new Date('2024-01-15T10:30:00'))).toBe(true);++ expect(isValidDate(new Date('invalid-date-string'))).toBe(false);+ expect(isValidDate(new Date(Number.NaN))).toBe(false);+ });+ });+});diff --git a/apps/papra-server/src/modules/shared/date.ts b/apps/papra-server/src/modules/shared/date.tsnew file mode 100644index 00000000..5a80e8e2--- /dev/null+++ b/apps/papra-server/src/modules/shared/date.ts@@ -0,0 +1,3 @@+export function isValidDate(date: Date): boolean {+ return !Number.isNaN(date.getTime());+}