trilium/docs/User Guide/Advanced Features/Bulk Operations.md

Bulk Operations

Execute actions on multiple notes simultaneously, saving time and ensuring consistency across your note collection.

Prerequisites

• Understanding of Trilium's note hierarchy
• Familiarity with search functionality
• Basic knowledge of attributes (labels and relations)

Overview

Bulk operations allow you to perform batch actions on multiple notes at once. This powerful feature enables efficient management of large note collections, systematic reorganization, and mass updates to note metadata.

Available Bulk Actions

Note Operations

Move Notes

Relocate multiple notes to a new parent location in the hierarchy.

{
  "name": "moveNote",
  "targetParentNoteId": "target_note_id"
}

Behavior:

• Notes with single parent: moved to target location
• Notes with multiple parents: cloned to target location (preserving existing relationships)

Delete Notes

Remove multiple notes from the database.

{
  "name": "deleteNote"
}

Important: This operation is permanent. Deleted notes can only be recovered from backups.

Rename Notes

Update titles of multiple notes using dynamic patterns.

{
  "name": "renameNote",
  "newTitle": "Prefix: ${note.title}"
}

Available variables:

• ${note.title} - Current note title
• ${note.noteId} - Note identifier
• ${note.dateCreated} - Creation date

Delete Revisions

Remove all revision history for selected notes.

{
  "name": "deleteRevisions"
}

Use cases:

• Reduce database size
• Remove sensitive historical data
• Clean up after major content updates

Attribute Operations

Add Label

Attach a new label to multiple notes.

{
  "name": "addLabel",
  "labelName": "status",
  "labelValue": "reviewed"
}

Update Label Value

Modify existing label values across multiple notes.

{
  "name": "updateLabelValue",
  "labelName": "priority",
  "labelValue": "high"
}

Rename Label

Change label names while preserving values.

{
  "name": "renameLabel",
  "oldLabelName": "tag",
  "newLabelName": "category"
}

Delete Label

Remove specific labels from multiple notes.

{
  "name": "deleteLabel",
  "labelName": "deprecated"
}

Relation Operations

Add Relation

Create relationships between notes and a target.

{
  "name": "addRelation",
  "relationName": "references",
  "targetNoteId": "target_note_id"
}

Update Relation Target

Redirect existing relations to a new target note.

{
  "name": "updateRelationTarget",
  "relationName": "template",
  "targetNoteId": "new_template_id"
}

Rename Relation

Change relation names while maintaining connections.

{
  "name": "renameRelation",
  "oldRelationName": "parent",
  "newRelationName": "category"
}

Delete Relation

Remove specific relations from multiple notes.

{
  "name": "deleteRelation",
  "relationName": "obsolete"
}

Custom Script Execution

Execute JavaScript code against each selected note.

{
  "name": "executeScript",
  "script": "note.setLabel('processed', new Date().toISOString());"
}

Available context:

• note - Current note object with full API access

Using Bulk Operations

Via Search Results

1. Execute a search query to find target notes
2. Select "Bulk Actions" from the search results menu
3. Choose desired action and configure parameters
4. Review affected note count
5. Execute the operation

Via Script API

const api = require('trilium');

// Find all notes with specific label
const targetNotes = api.searchForNotes('#needsUpdate');

// Define actions
const actions = [
  {
    name: 'updateLabelValue',
    labelName: 'status',
    labelValue: 'updated'
  },
  {
    name: 'addLabel',
    labelName: 'lastProcessed',
    labelValue: new Date().toISOString()
  }
];

// Execute bulk operation
api.executeBulkActions(targetNotes, actions, false);

Including Descendants

Set includeDescendants to true to apply operations to entire subtrees:

api.executeBulkActions(noteIds, actions, true);

Performance Considerations

Database Impact

• Small operations (< 100 notes): Minimal impact, execute immediately
• Medium operations (100-1000 notes): May cause brief UI lag
• Large operations (> 1000 notes): Consider running during low-activity periods

Optimization Strategies

1. Batch Processing

   • Break large operations into smaller chunks
   • Process in sequential batches to prevent timeouts

2. Index Utilization

   • Ensure search queries use indexed attributes
   • Avoid complex nested searches for bulk operations

3. Memory Management

   • Operations load all target notes into memory
   • Monitor system resources for very large operations

Use Case Examples

Project Archival

Archive completed project notes with metadata:

const projectNotes = api.searchForNotes('#project #status=completed');
const archiveActions = [
  { name: 'moveNote', targetParentNoteId: 'archive_folder_id' },
  { name: 'addLabel', labelName: 'archivedDate', labelValue: new Date().toISOString() },
  { name: 'deleteLabel', labelName: 'active' }
];
api.executeBulkActions(projectNotes, archiveActions, true);

Content Migration

Migrate notes from old structure to new taxonomy:

const oldCategoryNotes = api.searchForNotes('#category=old-system');
const migrationActions = [
  { name: 'renameLabel', oldLabelName: 'category', newLabelName: 'legacy-category' },
  { name: 'addRelation', relationName: 'migrated-to', targetNoteId: 'new_system_root' }
];
api.executeBulkActions(oldCategoryNotes, migrationActions, false);

Bulk Metadata Update

Add timestamps and processing flags:

const unprocessedNotes = api.searchForNotes('!#processed');
const metadataActions = [
  { 
    name: 'executeScript', 
    script: `
      note.setLabel('processed', 'true');
      note.setLabel('processedBy', 'bulk-operation');
      note.setLabel('processedDate', new Date().toISOString());
    `
  }
];
api.executeBulkActions(unprocessedNotes, metadataActions, false);

Troubleshooting

Operation Fails Silently

Symptom: Bulk operation completes but changes aren't visible.

Solutions:

• Verify note IDs exist and are accessible
• Check for protected notes requiring unlocked session
• Review browser console for JavaScript errors
• Ensure sufficient permissions for target operations

Performance Degradation

Symptom: System becomes unresponsive during large operations.

Solutions:

• Reduce batch size to under 500 notes
• Disable real-time sync during operation
• Clear browser cache before large operations
• Consider server-side script execution for massive updates

Inconsistent Results

Symptom: Some notes updated while others unchanged.

Solutions:

• Check for note-specific validation errors
• Verify attribute name consistency (case-sensitive)
• Ensure target notes aren't deleted or archived
• Review operation logs for specific failures

Memory Errors

Symptom: "Out of memory" errors for large operations.

Solutions:

• Increase Node.js heap size: NODE_OPTIONS="--max-old-space-size=4096"
• Process notes in smaller batches
• Use streaming operations for file attachments
• Restart Trilium server before massive operations

Best Practices

1. Always Test First

   • Run operations on small test set
   • Verify expected behavior before full execution

2. Create Backups

   • Backup database before irreversible operations
   • Export affected notes as additional precaution

3. Document Operations

   • Log bulk operations with timestamp and purpose
   • Maintain audit trail for compliance requirements

4. Use Transactions

   • Group related actions in single operation
   • Ensures atomic updates (all or nothing)

5. Monitor Progress

   • Watch server logs during execution
   • Set up alerts for long-running operations

Related Topics

• Search Documentation
• Attribute System
• Script API Reference
• Database Maintenance