Understanding Indexes

An index in Ducky is simply a collection of related documents. Think of it like a folder or database where you group similar content together for organized searching.

What is an Index?

An index is a named collection that contains your documents. Each document belongs to exactly one index, and when you search, you specify which index to search within.

from duckyai import DuckyAI

ducky = DuckyAI(api_key="your-api-key")

# Add documents to different indexes
ducky.documents.index(
    index_name="product-catalog",  # This is the index name
    doc_id="laptop-123",
    content="High-performance laptop with 16GB RAM..."
)

ducky.documents.index(
    index_name="help-docs",  # Different index
    doc_id="setup-guide",
    content="How to set up your new laptop..."
)

import { Ducky } from "duckyai-ts";

const ducky = new Ducky({
  apiKey: process.env.DUCKY_API_KEY ?? "",
});

// Add documents to different indexes
await ducky.documents.index({
  indexName: "product-catalog",  // This is the index name
  docId: "laptop-123",
  content: "High-performance laptop with 16GB RAM..."
});

await ducky.documents.index({
  indexName: "help-docs",  // Different index
  docId: "setup-guide",
  content: "How to set up your new laptop..."
});

Index vs Other Search Systems

If you're familiar with Elasticsearch, Ducky indexes are much simpler. Unlike Elasticsearch indexes which require complex configuration and mapping, Ducky indexes are just collections - you create them by adding documents, and Ducky handles all the search optimization automatically.

Ducky Index = Collection of Documents

No schema definition, no mapping configuration, no index settings to manage.

Why Use Indexes?

Indexes help you organize content and control search scope:

Content Organization:

# Separate business content
ducky.documents.index(index_name="products", ...)
ducky.documents.index(index_name="documentation", ...)
ducky.documents.index(index_name="blog-posts", ...)

Targeted Searching:

# Search only in product catalog
product_results = ducky.documents.retrieve(
    index_name="products",
    query="wireless headphones"
)

# Search only in documentation
doc_results = ducky.documents.retrieve(
    index_name="documentation", 
    query="API authentication"
)

// Search only in product catalog
const productResults = await ducky.documents.retrieve({
  indexName: "products",
  query: "wireless headphones"
});

// Search only in documentation
const docResults = await ducky.documents.retrieve({
  indexName: "documentation", 
  query: "API authentication"
});

Working with Indexes

Creating Indexes

Indexes are created automatically when you add your first document:

# This creates the "knowledge-base" index if it doesn't exist
ducky.documents.index(
    index_name="knowledge-base",
    doc_id="first-doc",
    content="Your content here..."
)

// This creates the "knowledge-base" index if it doesn't exist
await ducky.documents.index({
  indexName: "knowledge-base",
  docId: "first-doc",
  content: "Your content here..."
});

Managing Indexes

# List all your indexes
indexes = ducky.indexes.list()

# Get index details
index_info = ducky.indexes.get(index_name="products")

# Delete an index (removes all documents)
ducky.indexes.delete(index_name="old-index")

// List all your indexes
const indexes = await ducky.indexes.list();

// Get index details
const indexInfo = await ducky.indexes.get({
  indexName: "products"
});

// Delete an index (removes all documents)
await ducky.indexes.delete({
  indexName: "old-index"
});

When to Use Multiple Indexes

Content Types:

products - Product catalog
documentation - Help articles and guides
policies - Legal documents and policies

Access Patterns:

public-content - Customer-facing information
internal-docs - Employee resources

Teams or Projects:

team-engineering - Technical documentation
team-marketing - Marketing materials

Best Practices

Naming Conventions

# Good - descriptive and consistent
"product-catalog"
"user-documentation" 
"company-policies"

# Avoid - generic or unclear
"index1"
"data"
"stuff"

Index Organization

By Content Type:

indexes = [
    "products",           # Product information
    "documentation",      # User guides
    "blog-posts",        # Marketing content
    "support-articles"   # Customer support
]

By Access Level:

indexes = [
    "public-knowledge",   # Public information
    "internal-docs",     # Employee-only content
    "customer-data"      # Customer-specific content
]

Keep Related Content Together

Put documents that should be searched together in the same index. If users typically search across multiple types of content simultaneously, consider combining them into one index rather than splitting them.

🦆
Get in touch or see our roadmap if you need help