Documents and Semantic Search

The Documents and Search tabs provide powerful tools for exploring and finding information within your knowledge base. Documents shows what's been indexed, while Search lets you find relevant content using AI-powered semantic understanding.

Documents Tab

The Documents tab displays all indexed document chunks across your entire knowledge base. Think of it as the "raw content" view - every piece of text that's been processed and is available for AI agents to reference.

What Are Documents?

When you add a knowledge source (website, PDF, etc.), the system breaks the content into smaller, manageable chunks called "documents". This chunking allows AI agents to quickly find and retrieve relevant information.

Example:

Source: Product User Guide (50 pages)
  (chunked into)
Documents:
  - Introduction (page 1-2)
  - Getting Started (page 3-5)
  - Installation (page 6-10)
  - Configuration (page 11-15)
  ... and so on

Document Table

The Documents tab shows a paginated table with:

Column	Description
Content Preview	First 200 characters of the document chunk
Source	The original knowledge source
Chunk ID	Unique identifier for this document chunk
Actions	View full content or delete

Filtering Documents

Filter by Source:

Use the source dropdown to show documents from a specific source:

1. Click the "Source" filter dropdown
2. Select a source
3. Table updates to show only documents from that source
4. Clear filter to show all documents again

Filter by Search:

Use the search box to find documents containing specific text:

1. Type keywords in the search box
2. Documents are filtered in real-time
3. Searches content preview text

Viewing Document Details

Click the View action to open a detailed view showing:

• Full Content: Complete text of the document chunk
• Metadata: Source, chunk ID, timestamps
• Context: Previous and next chunks (if applicable)
• Vector Information: Embedding details (for advanced users)

Deleting Documents

You can delete individual document chunks:

1. Click the Delete action (trash icon)
2. Confirm deletion
3. Document is removed from the index

Note: Deleting a document chunk doesn't delete the source. To remove all documents from a source, delete the source itself from the Knowledge page.

Pagination

Navigate through large document sets:

• Page Size: Choose 10, 25, 50, or 100 documents per page
• Page Navigation: Use arrows or page numbers to browse
• Total Count: See total indexed documents at the bottom

---

Search Tab

The Search tab provides AI-powered semantic search across your entire knowledge base. Unlike keyword search, semantic search understands meaning and context.

What is Semantic Search?

Semantic search uses AI to understand what you're looking for, not just match keywords.

Example:

Search Query	Keyword Search Finds	Semantic Search Finds
"How do I reset my password?"	Documents with exact words "reset password"	Documents about password recovery, account access, login issues, password change procedures
"What are the pricing options?"	Only docs with "pricing options"	Pricing pages, subscription plans, cost information, billing details

Search Modes

Choose how search interprets your query:

1. Semantic Search (Default)

Best for: Natural language questions, finding concepts

Uses AI embeddings to understand meaning and context. Returns results based on semantic similarity, not keyword matching.

When to use:

• Asking questions ("How do I...?")
• Finding related concepts
• Exploring topics without knowing exact terms

Example:

Query: "troubleshooting connection issues"
Finds: Network problems, connectivity errors,
       Wi-Fi setup, VPN configuration, etc.

2. Keyword Search

Best for: Finding exact terms, product names, error codes

Traditional search that looks for exact word matches.

When to use:

• Looking for specific product names
• Finding error codes (e.g., "ERROR_404")
• Searching for technical terms

Example:

Query: "API_KEY_INVALID"
Finds: Documents containing the exact error code

3. Hybrid Search

Best for: Combining both approaches for comprehensive results

Runs both semantic and keyword search, then combines results.

When to use:

• Want comprehensive coverage
• Unsure which mode works better
• Looking for specific terms within a topic

Example:

Query: "OAuth authentication flow"
Finds: Documents about OAuth (semantic) AND
       documents with exact term "OAuth" (keyword)

Using the Search Interface

1. Enter Your Query: Type your question or search terms
2. Choose Search Mode: Select Semantic, Keyword, or Hybrid
3. Filter by Source (optional): Narrow search to specific sources
4. Click Search: Results appear below with relevance scores

Search Results

Each result shows:

Field	Description
Content Preview	Snippet of matching content with highlights
Relevance Score	0-100 score showing how relevant the result is
Source	Original knowledge source
View Full	Action to see complete document

Relevance Scoring

Results are ranked by relevance:

Score	Meaning	Indicator
90-100	Highly relevant	Green
70-89	Very relevant	Yellow
50-69	Somewhat relevant	Orange
0-49	Low relevance	Red

Tip: Focus on results with scores above 70 for best matches.

Filtering Search Results

By Source:

Limit search to specific sources:

1. Click "Filter by Source"
2. Select one or more sources
3. Search only returns results from selected sources

Empty Search Results

If no results are found:

Check:

• Are your sources indexed and ready?
• Try different search modes (semantic vs keyword)
• Broaden your query terms
• Remove source filters to search all content

Tips:

Too specific: "configuration parameter for max_connections in PostgreSQL 14.5"
Better: "PostgreSQL connection limits"

Too vague: "how to"
Better: "how to configure database settings"

---

Use Cases

For Support Teams

Scenario: Customer asks "My payment didn't go through"

1. Go to Search tab
2. Use Semantic Search mode
3. Query: "payment processing failed"
4. Filter by your support knowledge source
5. Get relevant troubleshooting docs

For Product Teams

Scenario: Need to find all API documentation

1. Go to Documents tab
2. Filter by your API documentation source
3. Browse all indexed API chunks
4. Use search within table to find specific endpoints

For Content Teams

Scenario: Update pricing information across all documents

1. Search tab, Keyword mode
2. Query: "pricing" or "$99"
3. Review all results
4. Update source documents
5. Reload sources to re-index

---

Best Practices

Writing Effective Queries

For Semantic Search:

Good: "How do I configure SAML SSO?"
Good: "troubleshooting email delivery"
Good: "best practices for security"

Avoid: Single keywords like "setup" or "error"
Avoid: Very long sentences with multiple questions

For Keyword Search:

Good: "ERROR_CODE_500"
Good: "PostgreSQL"
Good: "API endpoint /v1/users"

Avoid: Natural language questions
Avoid: Vague terms like "thing" or "stuff"

Search Mode Selection

Query Type	Recommended Mode	Example
Natural question	Semantic	"How do I reset my password?"
Product/Feature name	Keyword	"ChatGPT API"
Error code	Keyword	"ERR_CONNECTION_REFUSED"
Concept exploration	Semantic	"authentication best practices"
Mixed technical + concept	Hybrid	"OAuth implementation guide"

Managing Documents

Regular Cleanup:

1. Review Documents tab quarterly
2. Delete outdated chunks (old versions)
3. Reload sources with updated content
4. Remove duplicate documents

Monitor Index Health:

1. Check stats dashboard (top of Knowledge page)
2. Ensure "Index Health" is "Active"
3. Investigate any sources showing "Error" status
4. Re-index problematic sources

---

Troubleshooting

Search Returns No Results

Problem: Search finds nothing, but content exists

Solutions:

1. Check search mode - try switching to Hybrid
2. Verify sources are indexed (green "Active" status)
3. Simplify query - remove filters and try broader terms
4. Allow time for indexing (new sources take 5-10 minutes)

Relevance Scores Seem Off

Problem: Irrelevant results have high scores

Solution:

1. Semantic search learns over time - scores improve with use
2. Try Keyword or Hybrid mode for more precise matching
3. Use source filters to narrow scope
4. Refine query to be more specific

Can't Delete a Document

Problem: Delete button not working

Solution:

1. Check if you have edit permissions
2. Try deleting the entire source instead
3. Refresh page and try again
4. Contact support if issue persists

---

What's Next

• Assign Sources to Agents: Let AI agents use your knowledge
• Chat with Your Knowledge: Ask questions to AI agents powered by your content
• Refine Your Sources: Add more content to improve AI responses