Skip to content

armgit / papra

Public Imported from GitHub
0

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.md
new file mode 100644
index 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.mdx
index 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 archived
has: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 2024
tag: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.ts
index 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.ts
index 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.ts
index 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.ts
index 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 casting
switch (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();