Cross Bucket Search

Cross-Bucket Search Guide

This guide covers the comprehensive cross-bucket search feature in R2 Bucket Manager, allowing you to search for files across all buckets simultaneously with powerful filtering options.

---

Overview

Cross-Bucket Search enables you to find files across your entire R2 infrastructure from a single interface. Instead of navigating to individual buckets, you can search all buckets in parallel, apply advanced filters, and perform file operations directly from the search results.

Key Features

• Multi-Bucket Search - Search across all your R2 buckets simultaneously
• Real-time Search - Debounced search activates automatically as you type (300ms)
• Advanced Filters - Combine multiple filter types (extension, size, date)
• Sortable Results - Click column headers to sort by filename, bucket, size, or date
• Full File Operations - Download, move, copy, or delete files directly from results
• Server-Side Performance - Parallel queries across all buckets for optimal speed
• Result Limiting - Returns up to 100 matching files per search (configurable)

---

Accessing Cross-Bucket Search

On the Main Page

1. Navigate to the R2 Bucket Manager main page (bucket list view)
2. Look for the "🔍 Search Across All Buckets" button at the top of the page
3. Click the button to expand the search interface

Search Interface Layout

The search interface includes:

• Search Input - Text field for entering your search query
• Filter Buttons - Extension, Size, and Date filter controls
• Active Filters Display - Shows all currently applied filters
• Results Table - Displays matching files with sortable columns
• Control Buttons - "Clear All" to reset filters and collapse

---

How to Search

Basic Text Search

1. Type your query in the search input field
2. View results automatically - Search executes with a 300ms debounce after you stop typing
3. Refine your search - Modify your text to narrow results
4. Clear search - Click the ✕ button next to the search input or use "Clear All"

Search Behavior

• Case-insensitive - "Report", "report", and "REPORT" all match the same files
• Filename matching - Searches filename only, not full paths
• Real-time updates - Results update instantly as you type
• Partial matching - "report" matches "monthly-report.pdf", "Q4-Report.xlsx", etc.

Example Searches

Query	Matches
report	monthly-report.pdf, Q4_Report.xlsx, sales_report_2024.csv
backup	backup-2025.tar.gz, system_backup.zip
invoice	invoice_001.pdf, 2025-invoice-template.docx

---

Advanced Filtering

Extension Filter

Filter files by their file type using quick presets or custom selection.

Quick Filter Presets

Click one of these buttons for instant filtering:

• 📷 Images - .jpg, .png, .gif, .webp, .svg, .bmp, .heic, .avif
• 📄 Documents - .pdf, .doc, .docx, .xls, .xlsx, .ppt, .pptx, .txt, .csv
• 🎬 Videos - .mp4, .mov, .webm, .avi, .mkv, .flv, .m4v, .wmv
• 💻 Code - .js, .ts, .py, .java, .go, .rust, .html, .css, .json
• 📦 Archives - .zip, .rar, .tar, .gz, .7z, .bz2, .xz

Custom Extension Selection

1. Click the "Extension" filter button
2. Select individual extensions from the available list
3. Select multiple extensions to combine filters (e.g., .jpg AND .png)
4. See file counts next to each extension
5. Click an extension again to deselect it

Active Extension Filter Display

• Active extensions appear as removable badges below the filter buttons
• Click the ✕ on any badge to remove that extension from the filter
• Badge shows format: .jpg or Images (4) with count

---

Size Filter

Filter files by their storage size using preset ranges or custom values.

Preset Size Ranges

Click one of these buttons for quick filtering:

Range	Size
< 1 MB	0 - 1,048,576 bytes
1 - 10 MB	1 - 10 MB
10 - 50 MB	10 - 50 MB
50 - 100 MB	50 - 100 MB
> 100 MB	100 MB and above

Custom Size Range

1. Click the "Size" filter button
2. Select "Custom Range" option
3. Enter Minimum size (in MB) or leave blank for no minimum
4. Enter Maximum size (in MB) or leave blank for no maximum
5. Click Apply to filter results

Active Size Filter Display

• Active size filter appears as a removable badge below the filter buttons
• Badge shows format: Size: 10-50 MB or Size: Custom
• Click the ✕ on the badge to remove the size filter

Use Cases

• Find small files (< 1 MB) that are quick to download
• Locate large video files (> 100 MB) consuming storage
• Identify medium-sized documents (1-10 MB) for backup
• Search for specific size ranges in your bucket structure

---

Date Filter

Filter files by their upload date using preset ranges or custom dates.

Preset Date Ranges

Click one of these buttons for quick filtering:

Range	Time Period
Today	Last 24 hours
Last 7 Days	Past week
Last 30 Days	Past month
Last 90 Days	Past quarter
This Year	Current calendar year

Custom Date Range

1. Click the "Date" filter button
2. Select "Custom Range" option
3. Click "From Date" to select start date
4. Click "To Date" to select end date
5. Use the calendar picker to navigate and select dates
6. Click Apply to filter results

Active Date Filter Display

• Active date filter appears as a removable badge below the filter buttons
• Badge shows format: Date: Today or Date: 2025-01-01 to 2025-01-31
• Click the ✕ on the badge to remove the date filter

Upload Date Details

• Filters based on when files were uploaded to R2
• Respects timezone of the R2 bucket
• Useful for finding recent uploads or archived content
• Helps identify files from specific project phases

---

Combining Filters

Multi-Filter Search

You can combine multiple filter types simultaneously for precise results:

Example 1: Find recent images

1. Enter text search: product
2. Apply Extensions filter: Images (📷)
3. Apply Date filter: Last 7 Days

• Result: All product images uploaded in the last week

Example 2: Find large documents

1. Enter text search: report
2. Apply Extensions filter: Documents (📄)
3. Apply Size filter: 50 - 100 MB

• Result: All reports between 50-100 MB in size

Example 3: Find code files

1. No text search (leave empty for all files)
2. Apply Extensions filter: Code (💻)
3. Apply Size filter: < 1 MB
4. Apply Date filter: This Year

• Result: All source code files under 1 MB uploaded this year

Filter Priority

Filters work with AND logic:

• A file must match ALL active filters to appear in results
• If no files match all criteria, results will be empty
• Remove filters one by one to broaden your search

Clearing Filters

• Clear individual filter - Click the ✕ on any badge below the filter buttons
• Clear all filters - Click the "Clear All" button at the top right of the search section
• Collapse search - Click "Clear All" to collapse the search interface

---

Search Results

Results Table

Results are displayed in a sortable table with the following columns:

Column	Information
Filename	Name of the file found
Bucket	R2 bucket containing the file (clickable)
Size	File size in human-readable format (B, KB, MB, GB)
Upload Date	Date and time file was uploaded to R2

Sorting Results

Click column headers to sort results:

• First click - Sort ascending (A→Z or 0→9)
• Second click - Sort descending (Z→A or 9→0)
• Third click - Remove sort (return to default order)

Sorting Examples

Action	Result
Click Filename	Files sorted alphabetically
Click Bucket	Files grouped by bucket name
Click Size	Files sorted by size (small→large)
Click Upload Date	Files sorted by date (oldest→newest)

Navigating Results

• Results show up to 100 files per search
• If more than 100 results exist, only first 100 are displayed
• Modify filters to narrow results if needed
• Click bucket badge to navigate to that specific bucket

---

File Operations from Search Results

Available Actions

You can perform the following operations on files found in search results:

Download File

1. Locate the file in the results table
2. Click the "Download" button for that file
3. File downloads directly to your computer
4. Uses signed URLs for secure downloads

Move File

1. Locate the file in the results table
2. Click the "Move" button for that file
3. Select destination bucket and folder in the modal
4. Click Confirm to move
5. File is moved from source bucket to destination
6. Search results refresh automatically

Copy File

1. Locate the file in the results table
2. Click the "Copy" button for that file
3. Select destination bucket and folder in the modal
4. Click Confirm to copy
5. File is copied (original remains in source bucket)
6. Search results refresh automatically

Delete File

1. Locate the file in the results table
2. Click the "Delete" button for that file
3. Confirm the deletion in the modal
4. File is permanently deleted
5. Search results update to remove deleted file

Bucket Navigation

• Click the bucket badge next to any filename
• Navigate directly to that bucket's file browser
• Leave search interface and view full bucket contents

---

Performance & Optimization

Server-Side Search

Cross-bucket search uses parallel server-side queries:

• Searches across all buckets simultaneously
• Returns results in seconds even with many buckets
• No client-side filtering delays
• Optimized for buckets with thousands of files

Search Performance Tips

1. Use specific search terms - "report" is faster than "r"
2. Combine filters - Filters reduce result set before returning to client
3. Sort appropriately - Click headers to organize results as needed
4. Limit searches - Results capped at 100 files for performance

Result Limits

• Max results: 100 files per search (configurable)
• Search timeout: Results return within seconds
• Filter impact: Filters applied server-side before returning results

---

API Reference

Search Endpoint

GET /api/search

Query Parameters

Parameter	Type	Description	Example
query	string	Search term (filename match)	query=report
extensions	string	Comma-separated extensions	extensions=.jpg,.png
minSize	number	Minimum file size in bytes	minSize=1048576
maxSize	number	Maximum file size in bytes	maxSize=104857600
startDate	string	Start date (ISO 8601)	startDate=2025-01-01
endDate	string	End date (ISO 8601)	endDate=2025-12-31
limit	number	Max results to return	limit=50

Example Request

curl "http://localhost:8787/api/search?query=report&extensions=.pdf,.docx&minSize=1048576&maxSize=104857600"

Response Format

{
  "success": true,
  "results": [
    {
      "filename": "monthly-report.pdf",
      "bucket": "documents-bucket",
      "size": 2097152,
      "uploadDate": "2025-01-15T10:30:00Z"
    },
    {
      "filename": "Q4_Report.docx",
      "bucket": "archives-bucket",
      "size": 5242880,
      "uploadDate": "2025-01-20T14:45:00Z"
    }
  ],
  "count": 2,
  "totalMatched": 2
}

Error Response

{
  "success": false,
  "error": "Search query is required",
  "statusCode": 400
}

---

Use Cases

Finding Files Across Projects

Scenario: You manage multiple project buckets and need to find all marketing materials.

Solution:

1. Search for: marketing
2. Filter by: Documents + Images (multi-select extensions)
3. Result: All marketing files across all buckets instantly visible
4. Take action: Download, move to archive bucket, or organize by date

Locating Large Files

Scenario: Your storage is filling up and you need to identify what's consuming space.

Solution:

1. Leave search empty (search for everything)
2. Filter by: Size > 100 MB
3. Sort by: Size (descending)
4. Result: All large files ranked by size
5. Take action: Download for backup or delete old files

Finding Recent Uploads

Scenario: Team uploaded files today and you need to verify they arrived.

Solution:

1. Leave search empty or search for team member name
2. Filter by: Date - Today
3. Result: All files uploaded today
4. Take action: Verify, move to appropriate bucket, or download

Backup & Disaster Recovery

Scenario: Need to backup all documents from before a certain date.

Solution:

1. Leave search empty (all files)
2. Filter by: Documents (📄) extensions
3. Filter by: Date range (before backup date)
4. Download selected files or entire buckets
5. Store in secure backup location

Project Migration

Scenario: Migrating project files to a new bucket structure.

Solution:

1. Search for project-related files across multiple old buckets
2. Apply date filters to find files from specific project phase
3. Use Move operation to reorganize into new bucket structure
4. Use Copy to create redundancy during migration

---

Tips & Best Practices

Search Tips

✅ DO:

• Use descriptive search terms
• Combine multiple filters for precise results
• Sort results to organize findings
• Navigate to buckets for bulk operations

❌ DON'T:

• Search for very common terms (e.g., single letters) as this may return many results
• Use full paths in search (search by filename only)
• Perform too many simultaneous searches (wait for one to complete)

Filter Tips

✅ DO:

• Use preset date ranges for quick filtering
• Combine extension filters for multiple file types
• Use custom size ranges for storage analysis
• Clear filters when changing search strategy

❌ DON'T:

• Leave all filters empty and expect meaningful results
• Use extremely broad date ranges when you need specificity
• Forget to clear old filters before new searches

Performance Tips

✅ DO:

• Use specific search terms for faster results
• Apply filters to reduce result set size
• Use bucket navigation for bulk file operations
• Check results limit if search seems incomplete

❌ DON'T:

• Search for very broad terms on buckets with millions of files
• Attempt to download 100+ files individually (use bulk download instead)
• Leave search interface open when not in use

---

Troubleshooting

No Results Found

Problem: Search returns no results even though you expect files to match.

Solutions:

• Verify search term spelling
• Try a broader search term
• Remove filters one at a time to find which filter is too restrictive
• Check that files actually exist in accessible buckets
• Ensure date range includes file upload dates

Search Slow or Timeout

Problem: Search is taking too long or times out.

Solutions:

• Use more specific search terms
• Apply filters to reduce result set
• Check network connection
• Try a simpler search first
• Contact support if consistently slow

Wrong Bucket Results

Problem: Files from unexpected buckets appear in results.

Solutions:

• Verify your search term matches what you're looking for
• Check if system buckets are hidden (they should be filtered out)
• Review bucket permissions
• Try narrowing with additional filters

Can't Perform File Operations

Problem: Download, Move, Copy, or Delete buttons don't work.

Solutions:

• Verify you have permission for the operation
• Check that destination bucket exists (for move/copy)
• Ensure file hasn't been deleted since search executed
• Try refreshing the search results
• Check browser console for error messages

---

Learning More

• Advanced Filtering - Detailed filtering guide for single buckets
• File Operations - Comprehensive file management guide
• API Reference - Complete API documentation
• Troubleshooting - Additional troubleshooting help