---
updatedAt: 2025-07-18T15:19:23.000Z
agentTools:
  projectIndex: https://docs.ducky.ai/llms.txt
---

# Getting Started

Learn the basics of retrieval with Ducky

# Getting Started

Ducky is a fully managed retrieval system designed to accelerate development for Retrieval-Augmented Generation (RAG) applications. With an intuitive API and robust deployment infrastructure, Ducky lets you focus on building smarter applications without managing complex search infrastructure.

## Why Use Ducky

**Easy to use**: No headaches, no complexity. We spend all our time thinking about good retrieval, so you don't have to.

**Fully managed**: No infrastructure headaches, no hosting concerns. Focus on building your application while we handle the search infrastructure.

**Made for LLM agents**: Purpose-built for Retrieval-Augmented Generation with APIs designed specifically for AI applications and agent workflows.

## Installation

Install the SDK for your preferred language:

```python
pip install duckyai
```
```typescript
npm install duckyai-ts
```

## Account Setup

1. Create an account at [app.ducky.ai](https://app.ducky.ai/sign-up)
2. Follow the getting started guide to create your first Project
3. Create an Index within your project (an Index is a collection of your data)
4. Generate an API key from the [API keys](https://app.ducky.ai/api-keys) page

## Index Your First Document

Upload data to your index to start using Ducky's retrieval capabilities:

```python
from duckyai import DuckyAI

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

ducky.documents.index(
    index_name="recipes",
    content="""
        Chocolate chip cookies are a classic American treat. 
        Mix butter, sugar, eggs, flour, and chocolate chips. 
        Bake at 375°F for 9-11 minutes until golden brown.
    """,
    doc_id="chocolate-chip-cookies",
    metadata={
        "category": "dessert",
        "prep_time": 15,
        "cook_time": 10,
        "difficulty": "easy"
    }
)
```
```typescript
import { Ducky } from "duckyai-ts";

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

await ducky.documents.index({
  indexName: "recipes",
  content: `
    Chocolate chip cookies are a classic American treat. 
    Mix butter, sugar, eggs, flour, and chocolate chips. 
    Bake at 375°F for 9-11 minutes until golden brown.
  `,
  docId: "chocolate-chip-cookies",
  metadata: {
    category: "dessert",
    prep_time: 15,
    cook_time: 10,
    difficulty: "easy"
  }
});
```

## Make Your First Retrieval

Search your indexed documents with natural language queries:

```python
results = ducky.documents.retrieve(
    index_name="recipes",
    query="how to bake cookies?",
    top_k=5,
    rerank=False
)

print(f"Found {len(results.documents)} relevant documents")
for doc in results.documents:
    print(f"Document: {doc.doc_id}")
    print(f"Content: {doc.content_chunks[0]}")
```
```typescript
const results = await ducky.documents.retrieve({
  indexName: "recipes",
  query: "how to bake cookies?",
  topK: 5,
  rerank: false
});

console.log(`Found ${results.documents.length} relevant documents`);
results.documents.forEach(doc => {
  console.log(`Document: ${doc.docId}`);
  console.log(`Content: ${doc.contentChunks[0]}`);
});
```

### Understanding Parameters

* **`top_k`**: Number of results to return (1-100)
* **`rerank`**: Enable second-stage reranking for improved relevance

## Filter with Metadata

Use metadata to narrow search results based on specific criteria:

```python
# Add more documents with different metadata
ducky.documents.index(
    index_name="recipes",
    content="Grilled salmon with lemon and herbs. Season and grill for 6-8 minutes per side.",
    doc_id="grilled-salmon",
    metadata={
        "category": "main-course",
        "prep_time": 10,
        "cook_time": 15,
        "difficulty": "medium"
    }
)

# Search for easy recipes only
easy_recipes = ducky.documents.retrieve(
    index_name="recipes",
    query="quick cooking ideas",
    top_k=5,
    metadata_filter={
        "difficulty": "easy",
        "prep_time": {"$lte": 20}  # 20 minutes or less prep time
    }
)
```
```typescript
// Add more documents with different metadata
await ducky.documents.index({
  indexName: "recipes",
  content: "Grilled salmon with lemon and herbs. Season and grill for 6-8 minutes per side.",
  docId: "grilled-salmon",
  metadata: {
    category: "main-course",
    prep_time: 10,
    cook_time: 15,
    difficulty: "medium"
  }
});

// Search for easy recipes only
const easyRecipes = await ducky.documents.retrieve({
  indexName: "recipes",
  query: "quick cooking ideas",
  topK: 5,
  metadataFilter: {
    difficulty: "easy",
    prep_time: { "$lte": 20 }  // 20 minutes or less prep time
  }
});
```

### Understanding Results

Ducky returns results in two formats:

* **`documents`**: Complete document information grouped by `doc_id`
* **`chunks`**: Individual content segments with their scores

Each result includes the document's content, metadata, and a relevance score to help you understand result quality.

## Next Steps

* **[Core Concepts](core-concepts)**: Learn about Projects, Indexes, and document management
* **[Advanced Metadata](advanced-metadata)**: Master complex filtering and data organization
* **[Document Scores](document-scores)**: Understand how relevance scoring works
* **[API Reference](https://docs.ducky.ai/reference)**: Explore all available endpoints and parameters

> 🦆 [Get in touch](mailto:support@ducky.ai) or see our [roadmap](https://ducky.productlane.com/roadmap) if you need help