Semantic Search

The Zapdos SDK provides powerful semantic search capabilities that allow you to find content based on natural language queries rather than just keyword matching.

Basic Usage

To perform semantic search, you can use the search method on the Client:

from zapdos import Client

# Create a client with your API key
client = Client(api_key="your_api_key_here")

# Search with a single string query
search_result = client.search("cat playing with ball")
print(f"Found {len(search_result['results'])} result sets")

Search Input Formats

The search method supports three different input formats:

Single String Query

# Search with a single string
result = client.search("your search query")

Multiple String Queries

# Search with multiple string queries
result = client.search(["dog", "cat", "bird"])

Complex Query Structures

# Search with complex query structures
result = client.search([
    {"type": "text", "value": "query 1"},
    {"type": "text", "value": "query 2"}
])

Understanding Search Results

The search method returns a dictionary with a "results" key containing an array of result sets. Each result set corresponds to one of your queries:

search_result = client.search(["dog", "cat"])

# Access the results
results = search_result["results"]
print(f"Number of result sets: {len(results)}")

# Process each result set
for i, result_set in enumerate(results):
    print(f"Query {i+1} returned {len(result_set)} results")
    for j, result in enumerate(result_set):
        # Each result contains field and media_unit information
        field_value = result['field']['value'].get('string_value', 'N/A')
        print(f"  Result {j+1}: {field_value}")

How Semantic Search Works

When you perform a search:

The SDK sends your text query to the Zapdos API
The API generates vector embeddings for your query using the same models that processed your indexed content
The system performs vector similarity searches against the embeddings stored in our database
Results are returned ranked by semantic similarity

This approach allows you to find content that is conceptually related to your query, even if the exact words don't match.

CLI Usage

You can also perform semantic searches using the CLI:

# Set your API key
export ZAPDOS_API_KEY=your_api_key_here

# Search with a single query
zapdos-py search "cat playing with ball"

# Search with multiple queries
zapdos-py search '["dog", "cat", "bird"]'

# Search with complex query structures
zapdos-py search '[{"type": "text", "value": "query 1"}, {"type": "text", "value": "query 2"}]'

Combining Indexing and Search

A typical workflow involves indexing content and then searching it:

from zapdos import Client

# Create a client
client = Client(api_key="your_api_key_here")

# First, index a video
index_result = client.index("path/to/your/video.mp4")

# Then, search for content
search_result = client.search("things that happened in the video")

The semantic search capabilities make it easy to retrieve relevant video segments based on natural language descriptions of what you're looking for.

Semantic Search

On this page