SmartBuckets

SmartBuckets is Raindrop’s RAG-in-a-box building block. Any time you need RAG in your Raindrop app, you should use SmartBuckets. It provides multi-modal indexing capabilities that automatically process uploaded content for AI-powered search and retrieval.

SmartBuckets extends standard Bucket functionality with semantic search methods. All standard bucket operations work identically while adding search(), chunkSearch(), documentChat(), getPaginatedResults(), and createPageSummary() methods. Files uploaded to SmartBuckets become immediately searchable through natural language queries without requiring manual preprocessing or separate search infrastructure.

The system automatically extracts text from documents and images from PDFs to create searchable indexes. This enables semantic search across stored files, making SmartBuckets ideal for document management systems, knowledge bases, and applications requiring content discovery. Multi-modal indexing means SmartBuckets can process various file types including extracting and indexing images from PDFs for comprehensive search operations.

Creating SmartBuckets

Define SmartBuckets in your application manifest. SmartBucket names must be unique within your application and follow kebab-case conventions.

application "demo-app" {
    smartbucket "demo-sb" {}
}

Accessing SmartBuckets

SmartBuckets are accessed through environment bindings. The SmartBucket name from your manifest becomes an uppercase environment variable with underscores replacing dashes.

// Access SmartBucket via environment binding
const results = await this.env.DEMO_SB.search({
  input: "search query",
  requestId: "req-1"
});

Core Concepts

Main Interfaces

• SmartBucket - Extends Bucket with AI search capabilities
• SearchInput - Input for semantic search operations
• SearchOutput - Search results with pagination
• RagSearchInput - Input for chunk-based RAG search
• DocumentChatInput - Input for document Q&A
• GetPaginatedResultsInput - Input for result pagination
• CreatePageSummaryInput - Input for page summarization

SearchResult

Search operations return results with relevance scores and extracted content. Each result includes text content, source reference, and semantic similarity score.

interface SearchResult {
  chunkSignature?: string;    // Unique chunk identifier
  text?: string;              // Extracted text content
  source?: string;            // Source file reference
  payloadSignature?: string;  // Content payload identifier
  score?: number;             // Relevance score (0-1)
  embed?: Float32Array;       // Vector embedding data
  type?: string;              // Content type classification
}

PaginationInfo

Search methods return pagination details for navigating large result sets. Pagination enables efficient browsing through multiple pages of search results.

interface PaginationInfo {
  total: number;        // Total results available
  page: number;         // Current page number
  pageSize: number;     // Results per page
  totalPages: number;   // Total pages available
  hasMore: boolean;     // More results available
}

search

Performs semantic search across all bucket content using natural language queries.

Input

interface SearchInput {
  input: string;        // Natural language search query
  requestId?: string;   // Optional request tracking ID
  partition?: string;   // Optional data partition filter
}

Output

interface SearchOutput {
  results: SearchResult[];      // Ranked search matches
  pagination: PaginationInfo;   // Pagination details
}

Example

// Search for relevant documents
const results = await this.env.DEMO_SB.search({
  input: "climate change research",
  requestId: "search-001"
});

// Process search results
results.results.forEach(result => {
  console.log(`Found: ${result.source} (score: ${result.score})`);
});

chunkSearch

Returns specific text chunks from documents for RAG applications.

Input

interface RagSearchInput {
  input: string;        // Search query for chunks
  requestId: string;    // Required request ID
  partition?: string;   // Optional partition filter
}

Output

interface RagSearchOutput {
  results: SearchResult[];  // Relevant text chunks
}

Example

// Get relevant chunks for context
const chunks = await this.env.DEMO_SB.chunkSearch({
  input: "renewable energy costs",
  requestId: "chunk-001"
});

// Use chunks as context
const context = chunks.results
  .map(chunk => chunk.text)
  .join('\n');

documentChat

Generates answers to questions about specific document content using AI.

Input

interface DocumentChatInput {
  objectId: string;     // Target document ID
  input: string;        // Question or prompt
  requestId: string;    // Request tracking ID
  partition?: string;   // Optional partition filter
}

Output

interface DocumentChatOutput {
  answer: string;       // Generated response
}

Example

// Ask question about document
const answer = await this.env.DEMO_SB.documentChat({
  objectId: "report.pdf",
  input: "What are the main findings?",
  requestId: "chat-001"
});

// Display generated answer
console.log(answer.answer);

getPaginatedResults

Retrieves additional pages from previous search operations.

Input

interface GetPaginatedResultsInput {
  requestId: string;    // Previous search request ID
  page?: number;        // Target page number
  pageSize?: number;    // Results per page
  partition?: string;   // Optional partition filter
}

Output

interface GetPaginatedResultsOutput {
  results: SearchResult[];      // Page results
  pagination: PaginationInfo;   // Updated pagination
}

Example

// Get next page of results
const nextPage = await this.env.DEMO_SB.getPaginatedResults({
  requestId: "search-001",
  page: 2,
  pageSize: 20
});

// Check pagination status
console.log(`Page ${nextPage.pagination.page} of ${nextPage.pagination.totalPages}`);

createPageSummary

Generates intelligent summaries of search result pages.

Input

interface CreatePageSummaryInput {
  requestId?: string;   // Previous search request ID
  page: number;         // Page to summarize
  pageSize: number;     // Results per page
  partition?: string;   // Optional partition filter
}

Output

interface CreatePageSummaryOutput {
  summary: string;      // Generated summary text
}

Example

// Summarize search results page
const summary = await this.env.DEMO_SB.createPageSummary({
  requestId: "search-001",
  page: 1,
  pageSize: 20
});

// Display generated summary
console.log(summary.summary);