The minimalistic document archiving platform.
feat(search): add document date filtering (#945)
Corentin Thomasset31e27d5e1e00
diff --git a/.changeset/silver-places-go.md b/.changeset/silver-places-go.mdnew file mode 100644index 00000000..d76345e7--- /dev/null+++ b/.changeset/silver-places-go.md@@ -0,0 +1,5 @@+---+"@papra/app": patch+---++Added the `date` search filter, allowing to filter by document dates, like `date:>2026`, and `has:date`.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 6d02cc3e..3e0f84e5 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@@ -33,7 +33,9 @@ Use filters to search specific document properties. Current supported filters:- `content:` - Search in document content- `tag:` - Search by tag name or ID- `created:` - Filter by document creation date+- `date:` - Filter by document date (the date associated with the document)- `has:tags` - Check if documents have any tags, it can be negated with `-has:tags` or `NOT has:tags` to find untagged documents+- `has:date` - Check if documents have a date set, it can be negated with `-has:date` or `NOT has:date` to find documents without a date### Filter Examples@@ -69,6 +71,8 @@ The `has:` filter checks whether documents have certain properties:- `has:tags` - Documents with at least one tag- `-has:tags` or `NOT has:tags` - Documents without any tags+- `has:date` - Documents with a date set+- `-has:date` or `NOT has:date` - Documents without a date#### Existence Filter Examples@@ -84,11 +88,17 @@ has:tags invoice# Find tagged documents that are not archivedhas:tags NOT tag:archived++# Find documents without a date set+-has:date++# Find documents that have a date and a specific tag+has:date tag:invoice```### Date Filter-The `created:` filter supports date comparisons with the following operators:+The `created:` and `date:` filters support date comparisons with the following operators:- `=` - Exact date match- `>` - After the date@@ -127,6 +137,13 @@ created:<=2024-06-30# Finds invoices created only in 2024tag:invoice created:>2024 created:<2025++# Finds documents with a document date after January 1st, 2024+date:>2024++# Finds documents with a document date on or before now+date:<=now+```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.tsindex 6627496f..c535cd18 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@@ -4,10 +4,10 @@ import { and, eq } from 'drizzle-orm';import { documentsTable } from '../../documents.table';import { buildQueryFromExpression } from './query-builder/query-builder';-export function makeSearchWhereClause({ query, organizationId, db }: { query: string; organizationId: string; db: Database }) {+export function makeSearchWhereClause({ query, organizationId, db, now = new Date() }: { query: string; organizationId: string; db: Database; now?: Date }) {const { expression, issues: parsedIssues } = parseSearchQuery({ query });- const { sqlQuery, issues } = buildQueryFromExpression({ expression, organizationId, db });+ const { sqlQuery, issues } = buildQueryFromExpression({ expression, organizationId, db, now });return {searchWhereClause: and(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.tsindex 992c84a6..828b5654 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@@ -22,8 +22,8 @@ export function createDocumentSearchRepository({ db }: { db: Database }) {}, { db });}-async function searchOrganizationDocuments({ organizationId, searchQuery, pageIndex, pageSize, db }: { organizationId: string; searchQuery: string; pageIndex: number; pageSize: number; db: Database }) {- const { searchWhereClause } = makeSearchWhereClause({ organizationId, query: searchQuery, db });+async function searchOrganizationDocuments({ organizationId, searchQuery, pageIndex, pageSize, db, now = new Date() }: { organizationId: string; searchQuery: string; pageIndex: number; pageSize: number; db: Database; now?: Date }) {+ const { searchWhereClause } = makeSearchWhereClause({ organizationId, query: searchQuery, db, now });const paginatedIdsSubquery = db.selectDistinct({ id: documentsTable.id, createdAt: documentsTable.createdAt })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 53bb27bb..7c89295f 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@@ -6,6 +6,8 @@ import {handleAndExpression,handleContentFilter,handleCreatedFilter,+ handleDocumentDateFilter,+ handleDocumentHasDateFilter,handleEmptyExpression,handleHasTagsFilter,handleNameFilter,@@ -126,6 +128,7 @@ describe('query-builder', async () => {test('supports equality operator for date filtering', () => {const { sqlQuery, issues } = handleCreatedFilter({expression: { type: 'filter', field: 'created', value: '2024-01-15', operator: '=' },+ now: new Date('2025-06-15'),});expect(issues).to.eql([]);@@ -139,6 +142,8 @@ describe('query-builder', async () => {test('supports greater than operator for date filtering', () => {const { sqlQuery, issues } = handleCreatedFilter({expression: { type: 'filter', field: 'created', value: '2024-01-15', operator: '>' },+ now: new Date('2025-06-15'),+});expect(issues).to.eql([]);@@ -152,6 +157,7 @@ describe('query-builder', async () => {test('supports greater than or equal operator for date filtering', () => {const { sqlQuery, issues } = handleCreatedFilter({expression: { type: 'filter', field: 'created', value: '2024-01-15', operator: '>=' },+ now: new Date('2025-06-15'),});expect(issues).to.eql([]);@@ -165,6 +171,7 @@ describe('query-builder', async () => {test('supports less than operator for date filtering', () => {const { sqlQuery, issues } = handleCreatedFilter({expression: { type: 'filter', field: 'created', value: '2024-01-15', operator: '<' },+ now: new Date('2025-06-15'),});expect(issues).to.eql([]);@@ -178,6 +185,7 @@ describe('query-builder', async () => {test('supports less than or equal operator for date filtering', () => {const { sqlQuery, issues } = handleCreatedFilter({expression: { type: 'filter', field: 'created', value: '2024-01-15', operator: '<=' },+ now: new Date('2025-06-15'),});expect(issues).to.eql([]);@@ -191,6 +199,7 @@ describe('query-builder', async () => {test('returns an error for invalid date format', () => {const { sqlQuery, issues } = handleCreatedFilter({expression: { type: 'filter', field: 'created', value: 'not-a-date', operator: '=' },+ now: new Date('2025-06-15'),});expect(issues).to.eql([{@@ -223,6 +232,7 @@ describe('query-builder', async () => {for (const [dateFormat, timestamp] of Object.entries(dateFormats)) {const { sqlQuery, issues } = handleCreatedFilter({expression: { type: 'filter', field: 'created', value: dateFormat, operator: '=' },+ now: new Date('2025-06-15'),});expect(issues).to.eql([]);@@ -234,6 +244,140 @@ describe('query-builder', async () => {});});+ describe('handleDocumentDateFilter', () => {+ const now = new Date('2025-06-15T00:00:00Z');++ test('supports equality operator for date filtering', () => {+ const { sqlQuery, issues } = handleDocumentDateFilter({+ expression: { type: 'filter', field: 'date', value: '2024-01-15', operator: '=' },+ now,+ });++ expect(issues).to.eql([]);++ expect(getSqlString(sqlQuery)).to.eql({+ sql: `"documents"."document_date" = ?`,+ params: [1705276800000],+ });+ });++ test('supports greater than operator for date filtering', () => {+ const { sqlQuery, issues } = handleDocumentDateFilter({+ expression: { type: 'filter', field: 'date', value: '2024-01-15', operator: '>' },+ now,+ });++ expect(issues).to.eql([]);++ expect(getSqlString(sqlQuery)).to.eql({+ sql: `"documents"."document_date" > ?`,+ params: [1705276800000],+ });+ });++ test('supports greater than or equal operator for date filtering', () => {+ const { sqlQuery, issues } = handleDocumentDateFilter({+ expression: { type: 'filter', field: 'date', value: '2024-01-15', operator: '>=' },+ now,+ });++ expect(issues).to.eql([]);++ expect(getSqlString(sqlQuery)).to.eql({+ sql: `"documents"."document_date" >= ?`,+ params: [1705276800000],+ });+ });++ test('supports less than operator for date filtering', () => {+ const { sqlQuery, issues } = handleDocumentDateFilter({+ expression: { type: 'filter', field: 'date', value: '2024-01-15', operator: '<' },+ now,+ });++ expect(issues).to.eql([]);++ expect(getSqlString(sqlQuery)).to.eql({+ sql: `"documents"."document_date" < ?`,+ params: [1705276800000],+ });+ });++ test('supports less than or equal operator for date filtering', () => {+ const { sqlQuery, issues } = handleDocumentDateFilter({+ expression: { type: 'filter', field: 'date', value: '2024-01-15', operator: '<=' },+ now,+ });++ expect(issues).to.eql([]);++ expect(getSqlString(sqlQuery)).to.eql({+ sql: `"documents"."document_date" <= ?`,+ params: [1705276800000],+ });+ });++ test('returns an error for invalid date format', () => {+ const { sqlQuery, issues } = handleDocumentDateFilter({+ expression: { type: 'filter', field: 'date', value: 'not-a-date', operator: '=' },+ now,+ });++ expect(issues).to.eql([{+ message: 'Invalid date format for date filter: "not-a-date". Expected a valid date string.',+ code: 'INVALID_DATE_FORMAT',+ }]);++ expect(getSqlString(sqlQuery)).to.eql({ sql: `0`, params: [] });+ });++ test('supports "now" value to use the current date', () => {+ const { sqlQuery, issues } = handleDocumentDateFilter({+ expression: { type: 'filter', field: 'date', value: 'now', operator: '<=' },+ now,+ });++ expect(issues).to.eql([]);++ expect(getSqlString(sqlQuery)).to.eql({+ sql: `"documents"."document_date" <= ?`,+ params: [now.getTime()],+ });+ });+ });++ describe('handleDocumentHasDateFilter', () => {+ test('builds query to find documents with a date', () => {+ const { sqlQuery, issues } = handleDocumentHasDateFilter({+ expression: { type: 'filter', field: 'has', value: 'date', operator: '=' },+ organizationId: 'org_1',+ db,+ });++ expect(issues).to.eql([]);++ expect(getSqlString(sqlQuery)).to.eql({+ sql: `"documents"."document_date" is not null`,+ params: [],+ });+ });++ test('just the equality operator is supported ("=") for has filters, other operators return an issue and a no-op SQL query that evaluates to false', () => {+ const { sqlQuery, issues } = handleDocumentHasDateFilter({+ expression: { type: 'filter', field: 'has', value: 'date', operator: '>' },+ organizationId: 'org_1',+ db,+ });++ expect(issues).to.eql([{+ message: 'Unsupported operator ">" for has filter',+ code: 'UNSUPPORTED_FILTER_OPERATOR',+ }]);++ expect(getSqlString(sqlQuery)).to.eql({ sql: `0`, params: [] });+ });+ });+describe('handleEmptyExpression', () => {test('when the expression is empty, it returns a no-op SQL query that always evaluates to true', () => {const { sqlQuery, issues } = handleEmptyExpression();@@ -291,6 +435,7 @@ describe('query-builder', async () => {},organizationId: 'org_1',db,+ now: new Date('2025-06-15'),});expect(issues).to.eql([]);@@ -315,6 +460,7 @@ describe('query-builder', async () => {},organizationId: 'org_1',db,+ now: new Date('2025-06-15'),});expect(issues).to.eql([@@ -347,6 +493,7 @@ describe('query-builder', async () => {},organizationId: 'org_1',db,+ now: new Date('2025-06-15'),});expect(issues).to.eql([]);@@ -371,6 +518,7 @@ describe('query-builder', async () => {},organizationId: 'org_1',db,+ now: new Date('2025-06-15'),});expect(issues).to.eql([@@ -400,6 +548,7 @@ describe('query-builder', async () => {},organizationId: 'org_1',db,+ now: new Date('2025-06-15'),});expect(issues).to.eql([]);@@ -418,6 +567,7 @@ describe('query-builder', async () => {},organizationId: 'org_1',db,+ now: new Date('2025-06-15'),});expect(issues).to.eql([]);@@ -436,6 +586,7 @@ describe('query-builder', async () => {},organizationId: 'org_1',db,+ now: new Date('2025-06-15'),});expect(issues).to.eql([{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 2b806e5f..a56c48dd 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@@ -1,7 +1,7 @@import type { AndExpression, Expression, FilterExpression, NotExpression, OrExpression, TextExpression } from '@papra/search-parser';import 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 { and, eq, inArray, isNotNull, not, or, sql } from 'drizzle-orm';import { isValidDate } from '../../../../shared/date';import { tagIdRegex } from '../../../../tags/tags.constants';import { normalizeTagName } from '../../../../tags/tags.repository.models';@@ -91,8 +91,8 @@ export function handleTextExpression({ expression, organizationId, db }: { expre};}-export function handleAndExpression({ expression, organizationId, db }: { expression: AndExpression; organizationId: string; db: Database }): QueryResult {- const subQueries = expression.operands.map(expression => buildQueryFromExpression({ expression, organizationId, db }));+export function handleAndExpression({ expression, organizationId, db, now }: { expression: AndExpression; organizationId: string; db: Database; now: Date }): QueryResult {+ const subQueries = expression.operands.map(expression => buildQueryFromExpression({ expression, organizationId, db, now }));return {sqlQuery: and(...subQueries.map(sq => sq.sqlQuery)),@@ -100,8 +100,8 @@ export function handleAndExpression({ expression, organizationId, db }: { expres};}-export function handleOrExpression({ expression, organizationId, db }: { expression: OrExpression; organizationId: string; db: Database }): QueryResult {- const subQueries = expression.operands.map(expression => buildQueryFromExpression({ expression, organizationId, db }));+export function handleOrExpression({ expression, organizationId, db, now }: { expression: OrExpression; organizationId: string; db: Database; now: Date }): QueryResult {+ const subQueries = expression.operands.map(expression => buildQueryFromExpression({ expression, organizationId, db, now }));return {sqlQuery: or(...subQueries.map(sq => sq.sqlQuery)),@@ -109,8 +109,8 @@ export function handleOrExpression({ expression, organizationId, db }: { express};}-export function handleNotExpression({ expression, organizationId, db }: { expression: NotExpression; organizationId: string; db: Database }): QueryResult {- const subQuery = buildQueryFromExpression({ expression: expression.operand, organizationId, db });+export function handleNotExpression({ expression, organizationId, db, now }: { expression: NotExpression; organizationId: string; db: Database; now: Date }): QueryResult {+ const subQuery = buildQueryFromExpression({ expression: expression.operand, organizationId, db, now });if (!subQuery.sqlQuery) {// Should not happen, but just for type safety@@ -174,10 +174,47 @@ export function handleHasTagsFilter({ expression, organizationId, db }: { expres};}-export function handleCreatedFilter({ expression }: { expression: FilterExpression }): QueryResult {+function getDateValue({ value, now }: { value: string; now: Date }): Date {+ if (value === 'now') {+ return now;+ }++ return new Date(value);+}++export function handleDocumentDateFilter({ expression, now }: { expression: FilterExpression; now: Date }): QueryResult {+ const { value, operator, field } = expression;++ const dateValue = getDateValue({ value, now });+ const sqlOperator = getSqlOperator({ operator });++ if (!isValidDate(dateValue)) {+ return createInvalidDateFormatQueryResult({ field, value });+ }++ return {+ sqlQuery: sqlOperator(documentsTable.documentDate, dateValue),+ issues: [],+ };+}++export function handleDocumentHasDateFilter({ expression }: { expression: FilterExpression; organizationId: string; db: Database }): QueryResult {+ const { operator, field } = expression;++ if (operator !== '=') {+ return createUnsupportedOperatorQueryResult({ operator, field });+ }++ return {+ sqlQuery: isNotNull(documentsTable.documentDate),+ issues: [],+ };+}++export function handleCreatedFilter({ expression, now }: { expression: FilterExpression; now: Date }): QueryResult {const { value, operator } = expression;- const dateValue = new Date(value);+ const dateValue = getDateValue({ value, now });if (!isValidDate(dateValue)) {return createInvalidDateFormatQueryResult({ field: 'created', value });@@ -205,23 +242,25 @@ export function handleInvalidHasValue({ expression }: { expression: FilterExpres});}-export function buildQueryFromExpression({ expression, organizationId, db }: { expression: Expression; organizationId: string; db: Database }): QueryResult {+export function buildQueryFromExpression({ expression, organizationId, db, now }: { expression: Expression; organizationId: string; db: Database; now: Date }): QueryResult {// I usually prefer a LUT, but for type narrowing, switch is more convenient and avoids castingswitch (expression.type) {case 'empty': return handleEmptyExpression();case 'text': return handleTextExpression({ expression, organizationId, db });- case 'and': return handleAndExpression({ expression, organizationId, db });- case 'or': return handleOrExpression({ expression, organizationId, db });- case 'not': return handleNotExpression({ expression, organizationId, db });+ case 'and': return handleAndExpression({ expression, organizationId, db, now });+ case 'or': return handleOrExpression({ expression, organizationId, db, now });+ case 'not': return handleNotExpression({ expression, organizationId, db, now });case 'filter':switch (expression.field) {case '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 });+ case 'created': return handleCreatedFilter({ expression, now });+ case 'date': return handleDocumentDateFilter({ expression, now });case 'has':switch (expression.value) {case 'tags': return handleHasTagsFilter({ expression, organizationId, db });+ case 'date': return handleDocumentHasDateFilter({ expression, organizationId, db });default: return handleInvalidHasValue({ expression });}default: return handleUnsupportedExpression();