raindrop query

The raindrop query commands perform intelligent search and Retrieval Augmented Generation (RAG) operations on Raindrop smart buckets. Search across documents, chat with specific files, query application events, and manage search indexes.

Smart buckets automatically index uploaded content for semantic search. Use query commands to leverage this intelligence for document search, Q&A, and knowledge retrieval.

Command Categories

• Search - Natural language search across buckets
• Chunk Search - RAG-based search with context retrieval
• Document Chat - Interactive Q&A with specific documents
• Event Query - Application event streaming
• Reindex - Rebuild search indexes

Basic Usage

Search for documents:

raindrop query search "machine learning tutorials" --buckets docs

RAG search with chunks:

raindrop query chunk-search "What is LiquidMetal?" --buckets knowledge-base

Chat with a document:

raindrop query document "Summarize this" --bucket docs --object-id report.pdf

Command Reference

raindrop query search

Natural language search across smart buckets.

Syntax:

raindrop query search [query] --buckets <bucket>... [--page <number>] [--request-id <id>] [--output <format>]

Arguments:

• [query] - Search query text (optional for pagination)

Flags:

Flag	Description	Required	Default
-b, --buckets	Bucket names (multiple)	Yes	-
--request-id	Request ID for pagination	No	-
--page	Page number	No	1
-o, --output	Output format	No	text
-m, --manifest	Manifest file path	No	raindrop.manifest

Examples:

# Search single bucket
raindrop query search "API documentation" --buckets docs

# Search multiple buckets
raindrop query search "authentication" --buckets docs tutorials examples

# Search with specific version
raindrop query search "deployment" --buckets docs#v1.0.0

# Get results as JSON
raindrop query search "configuration" --buckets docs --output json

# Paginate results (use request-id from previous response)
raindrop query search --request-id req_abc123 --page 2 --buckets docs

Output (text):

Search Results for: "API documentation"
Buckets: docs

Found 5 results:

1. api-reference.md
   Score: 0.89
   Preview: "Complete API reference for all endpoints..."
   Location: docs/api-reference.md

2. getting-started.md
   Score: 0.76
   Preview: "Getting started with the API. First, authenticate..."
   Location: docs/getting-started.md

3. authentication.md
   Score: 0.72
   Preview: "API authentication uses Bearer tokens..."
   Location: docs/authentication.md

Request ID: req_abc123 (use for pagination)

Output (JSON):

{
  "requestId": "req_abc123",
  "results": [
    {
      "key": "api-reference.md",
      "score": 0.89,
      "preview": "Complete API reference for all endpoints...",
      "location": "docs/api-reference.md",
      "metadata": {
        "size": 15420,
        "lastModified": "2025-10-23T10:30:00.000Z"
      }
    }
  ],
  "hasMore": true,
  "page": 1
}

---

raindrop query chunk-search

RAG search with semantic chunking and context retrieval.

Syntax:

raindrop query chunk-search <query> --buckets <bucket>... [--output <format>]

Arguments:

• <query> - Search query (required)

Flags:

Flag	Description	Required	Default
-b, --buckets	Bucket names (multiple)	Yes	-
-o, --output	Output format	No	text
-m, --manifest	Manifest file path	No	raindrop.manifest

Examples:

# RAG search single bucket
raindrop query chunk-search "What is LiquidMetal?" --buckets knowledge-base

# Search multiple buckets
raindrop query chunk-search "How do I deploy?" --buckets docs tutorials

# JSON output
raindrop query chunk-search "Configuration options" --buckets docs --output json

Output:

Chunk Search Results for: "What is LiquidMetal?"

Found 3 relevant chunks:

Chunk 1 (Score: 0.94)
Source: introduction.md
LiquidMetal is a serverless platform for building intelligent applications.
It provides built-in support for AI, databases, and smart storage.
...

Chunk 2 (Score: 0.87)
Source: overview.md
The platform handles infrastructure provisioning, scaling, and monitoring
automatically, letting you focus on application logic.
...

Chunk 3 (Score: 0.82)
Source: getting-started.md
Getting started with LiquidMetal is simple. First, install the CLI...

RAG vs Regular Search:

Feature	chunk-search (RAG)	search
Context	Returns text chunks with context	Returns document references
Use Case	Question answering, summaries	Document discovery
Processing	Semantic chunking	Full document matching
Output	Text excerpts	Document metadata

---

raindrop query document

Interactive Q&A with a specific document.

Syntax:

raindrop query document <query> --bucket <bucket> --object-id <id> [--output <format>]

Arguments:

• <query> - Question about the document (required)

Flags:

Flag	Description	Required	Default
-b, --bucket	Bucket name	Yes	-
--object-id	Object ID (file path)	Yes	-
-o, --output	Output format	No	text
-m, --manifest	Manifest file path	No	raindrop.manifest

Examples:

# Ask question about document
raindrop query document "What is the main topic?" \
  --bucket docs \
  --object-id report.pdf

# Summarize document
raindrop query document "Summarize this document" \
  --bucket docs \
  --object-id whitepaper.pdf

# Extract specific information
raindrop query document "What are the key findings?" \
  --bucket research \
  --object-id study-2024.pdf

# JSON output
raindrop query document "List all recommendations" \
  --bucket docs \
  --object-id guidelines.pdf \
  --output json

Output:

Question: "What is the main topic?"
Document: report.pdf (bucket: docs)

Answer:
The main topic of this document is the architectural design of the LiquidMetal
platform, focusing on the actor model implementation and resource management
strategies. The document outlines three key components: the runtime engine,
the catalog service, and the deployment pipeline.

Sources:
- Page 1: Introduction (lines 1-15)
- Page 3: Architecture Overview (lines 45-78)
- Page 5: Component Details (lines 120-145)

---

raindrop query events

Stream and query Raindrop application events.

Syntax:

raindrop query events [--application <name>] [--version-id <id>] [--output <format>]

Flags:

Flag	Description	Required	Default
-a, --application	Application name	No	From manifest
-v, --version-id	Version ID	No	From config
-o, --output	Output format	No	table
-m, --manifest	Manifest file path	No	raindrop.manifest

Examples:

# Query events for current app/version
raindrop query events

# Query specific application
raindrop query events --application my-app

# Query specific version
raindrop query events --application my-app --version-id v1.0.0

# JSON output
raindrop query events --output json

Output (table):

┌──────────────────────┬──────────┬─────────────────────────────┬──────────────────────────┐
│ Event ID             │ Type     │ Message                     │ Timestamp                │
├──────────────────────┼──────────┼─────────────────────────────┼──────────────────────────┤
│ evt_abc123           │ deploy   │ Deployment started          │ 2025-10-23T10:30:00.000Z │
│ evt_def456           │ build    │ Building handler bundles    │ 2025-10-23T10:30:15.000Z │
│ evt_ghi789           │ deploy   │ Deployment complete         │ 2025-10-23T10:32:00.000Z │
└──────────────────────┴──────────┴─────────────────────────────┴──────────────────────────┘

---

raindrop query reindex

Rebuild search index for a bucket by reprocessing all objects.

Syntax:

raindrop query reindex --bucket <bucket> [--parallel <number>] [--dry-run]

Flags:

Flag	Description	Required	Default
-b, --bucket	Bucket name	Yes	-
--parallel	Parallel operations	No	10
-d, --dry-run	Show what would be reindexed	No	false
-m, --manifest	Manifest file path	No	raindrop.manifest

Examples:

# Reindex bucket
raindrop query reindex --bucket docs

# Dry run (preview)
raindrop query reindex --bucket docs --dry-run

# Reindex with more parallelism
raindrop query reindex --bucket docs --parallel 20

# Reindex specific version
raindrop query reindex --bucket docs#v1.0.0

Output:

Reindexing bucket: docs

Scanning objects...
Found 42 objects to reindex

Reindexing (10 parallel operations):
[██████████████████████████████] 42/42 (100%)

Reindex complete!
- Objects processed: 42
- Time taken: 15.3s
- Average: 2.7 objects/sec

Dry Run Output:

Dry run: Would reindex bucket "docs"

Objects to be reindexed (42 total):
  - introduction.md (1.2 KB)
  - api-reference.md (15.4 KB)
  - getting-started.md (3.8 KB)
  ...

No changes made (dry run)

When to Reindex:

• After bulk uploads
• When search results seem incorrect
• After changing bucket configuration
• When recovering from errors
• After restoring from backup

Use Cases

Document Search System

Build searchable documentation:

# Upload documentation
for file in docs/*.md; do
  raindrop object put "$(basename "$file")" "$file" --bucket docs
done

# Wait for automatic indexing
sleep 5

# Search documentation
raindrop query search "installation guide" --buckets docs
raindrop query search "API authentication" --buckets docs

Knowledge Base Q&A

Create AI-powered Q&A:

# Search knowledge base
raindrop query chunk-search "How do I configure database connections?" \
  --buckets knowledge-base

# Get detailed answer from specific doc
raindrop query document "What are the database connection parameters?" \
  --bucket knowledge-base \
  --object-id database-guide.pdf

Content Analysis

Analyze uploaded content:

# Find all mentions of a topic
raindrop query search "security best practices" --buckets docs tutorials

# Summarize multiple documents
for doc in report1.pdf report2.pdf report3.pdf; do
  echo "=== $doc ==="
  raindrop query document "Provide a brief summary" \
    --bucket reports \
    --object-id "$doc"
done

Index Management

Maintain search indexes:

# Check what would be reindexed
raindrop query reindex --bucket docs --dry-run

# Reindex after bulk update
raindrop query reindex --bucket docs --parallel 15

# Verify search works
raindrop query search "test query" --buckets docs

Search Tips

Query Formulation:

• Use natural language questions
• Be specific about what you’re looking for
• Include key terms and concepts
• Try different phrasings if results aren’t good

Bucket Selection:

• Search specific buckets for better relevance
• Search multiple related buckets together
• Use versioned buckets for time-specific searches

Result Pagination:

• Save requestId from first search
• Use --request-id and --page for subsequent pages
• Request IDs expire after 24 hours

RAG vs Document Search:

• Use chunk-search for questions requiring synthesis
• Use search for finding specific documents
• Use document for deep dives into single files

Best Practices

Search Performance:

• Index buckets after bulk uploads
• Use specific queries over generic ones
• Search fewer buckets when possible
• Implement caching for common queries

Index Management:

• Reindex after configuration changes
• Use dry-run before production reindexes
• Monitor reindex performance
• Schedule reindexes during low-traffic periods

Query Optimization:

• Start broad, then narrow down
• Use pagination for large result sets
• Cache request IDs for continued browsing
• Implement result deduplication

Content Organization:

• Organize buckets by topic or domain
• Use consistent naming conventions
• Structure documents for better chunking
• Include metadata in filenames

Troubleshooting

No Search Results:

# Check bucket exists and has content
raindrop object list --bucket docs

# Verify indexing completed
# (wait a few seconds after upload)

# Try reindexing
raindrop query reindex --bucket docs

# Retry search
raindrop query search "your query" --buckets docs

Poor Search Quality:

# Try more specific queries
raindrop query search "specific term" --buckets docs

# Use RAG search instead
raindrop query chunk-search "your question" --buckets docs

# Check if bucket needs reindexing
raindrop query reindex --bucket docs --dry-run

Slow Reindexing:

# Increase parallelism
raindrop query reindex --bucket docs --parallel 20

# Check bucket size
raindrop object list --bucket docs | wc -l

# Consider reindexing during off-peak hours

Exit Codes

Code	Description
0	Command completed successfully
1	General error (bucket not found, object not found, query failed, etc.)
2	Invalid arguments