Skip to content

README.md

Latest commit

 

History

History
167 lines (100 loc) · 5.31 KB

README.md

File metadata and controls

167 lines (100 loc) · 5.31 KB
Raw

ParadeDB for Django: Examples & Cookbook

Welcome to the ParadeDB for Django examples! This directory contains a collection of self-contained scripts designed to teach you how to integrate full-text search, vector retrieval, and aggregations into your Django application using ParadeDB.

Think of this as a cookbook: whether you need simple keyword search, an e-commerce filtering system, or a cutting-edge RAG (Retrieval-Augmented Generation) pipeline, you'll find a recipe here.

🚀 Getting Started

Before running any example, you need to set up your environment.

1. Install Dependencies

All examples share a common set of dependencies.

# Install uv: https://docs.astral.sh/uv/getting-started/installation/

# Create or update an environment with the example dependencies
uv sync --extra examples

2. Start ParadeDB

You need a running ParadeDB instance. We provide a helper script to start one via Docker and set the necessary environment variables.

# Sourcing this script starts ParadeDB and exports DATABASE_URL
source scripts/run_paradedb.sh

Note: If you already have a Postgres instance with ParadeDB installed, you can simply set the DATABASE_URL environment variable manually: export DATABASE_URL=postgresql://user:password@localhost:5432/dbname

📚 The Examples

We've organized the examples into three categories:

  1. Essentials: Core search features used in almost every app.
  2. Smart Features: UX enhancements like autocomplete and recommendations.
  3. AI & Vectors: Advanced semantic search and generative AI flows.

🔹 Essentials

1. Quickstart (quickstart/quickstart.py)

The "Hello World" of ParadeDB.

This script demonstrates the fundamental building blocks of search. You will learn how to:

  • Index data: Define a BM25Index on your model.
  • Search: Perform basic keyword queries.
  • Score: Sort results by relevance (BM25 score).
  • Highlight: Generate snippets (e.g., <b>run</b>ning) to show users why a result matched.

Run it:

uv run python examples/quickstart/quickstart.py

2. Faceted Search (faceted_search/faceted_search.py)

Building an E-commerce Sidebar.

Facets are the "filters" you see on shopping sites (e.g., "Brand (5)", "Color (3)"). This example shows how to compute these counts efficiently in a single query.

Key Concepts:

  • Aggregations: Counting documents by category, rating, etc.
  • Hybrid Results: Getting search results and facet counts together.

Run it:

uv run python examples/faceted_search/faceted_search.py

🔹 Smart Features

3. Autocomplete (autocomplete/)

Instant "As-You-Type" Suggestions.

Standard search requires hitting "Enter". Autocomplete gives immediate feedback. This example uses N-gram tokenization to match substrings (e.g., "wir" matches "wireless").

How it works:

  1. We create a specialized index that breaks text into small chunks (n-grams).
  2. Queries match these chunks, allowing for partial matches even in the middle of words.

Run it:

uv run python examples/autocomplete/autocomplete.py

autocomplete.py bootstraps its own setup. Run examples/autocomplete/setup.py only if you want to inspect or prepare the demo data separately.

4. More Like This (more_like_this/more_like_this.py)

Recommendations & "Related Content".

Want to show "Related Articles" or "Customers also bought"? This feature analyzes the text of a document to find others with similar keywords, using TF-IDF logic—no complex vector embeddings required.

Run it:

uv run python examples/more_like_this/more_like_this.py

🔹 AI & Vectors

5. Hybrid Search with RRF (hybrid_rrf/)

The Best of Both Worlds: Keywords + Semantics.

Keyword search (BM25) is great for exact matches ("Part #123"). Vector search is great for meaning ("warm clothing" matches "coat"). Hybrid Search combines them using Reciprocal Rank Fusion (RRF) for superior results.

Prerequisites:

  • pgvector must be installed (included in the ParadeDB Docker image).

Run it:

uv run python examples/hybrid_rrf/hybrid_rrf.py

hybrid_rrf.py runs its setup step automatically. Run examples/hybrid_rrf/setup.py on its own only when you want to preload the sample embeddings before the demo.

6. RAG: Retrieval-Augmented Generation (rag/)

Chat with your Data.

This example builds a mini QA system. It searches your data for relevant context and feeds it to an LLM (Large Language Model) to answer questions based only on your data.

Prerequisites:

  • An API Key from OpenRouter (provides access to GPT-4, Claude, etc.).
  • Set export OPENROUTER_API_KEY=sk-... in your terminal.

Run it:

uv run python examples/rag/rag.py

🛠 Under the Hood: common.py

You might notice that many examples import from common. This is a helper module located at examples/common.py. It handles the boring stuff so the examples remain focused:

  • configure_django(): Sets up a minimal in-memory Django configuration.
  • MockItem: A simple Django model used across examples to simulate products.
  • setup_mock_items(): Populates the database with dummy data.

Feel free to read common.py if you're curious how to set up standalone Django scripts!