Skip to content

armgit / papra

Public Imported from GitHub
0

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.mdx
index 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 spaces
content:"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"
:::note
The `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 Operators
Combine 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.mdx
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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, OrExpr
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 { 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 }: { e
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 });
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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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());
+}