Skip to content

search api guide

Jump to bottom
Anthony Bible edited this page Nov 21, 2025 · 2 revisions

Search API Guide

The Semantic Code Search API provides powerful search capabilities with advanced filtering options, including semantic type information. This guide covers all available search parameters and response formats with practical examples.

Table of Contents

  1. Search Endpoint
  2. Request Parameters
  3. Response Format
  4. Basic Search Examples
  5. Advanced Type Filtering
  6. Combining Filters
  7. Response Examples
  8. Best Practices

Search Endpoint

POST /search

Performs semantic search across indexed code chunks with support for various filtering options.

Request Parameters

SearchRequestDTO

Parameter Type Required Description Default
query string ✅ Search query text -
limit int ❌ Maximum results to return (1-100) 10
offset int ❌ Pagination offset 0
repository_ids []uuid ❌ Filter by specific repositories []
languages []string ❌ Filter by programming languages []
file_types []string ❌ Filter by file extensions []
similarity_threshold float64 ❌ Minimum similarity score (0.0-1.0) 0.7
sort string ❌ Sort order (see below) "similarity:desc"
Enhanced Type Filtering
types []string ❌ Filter by semantic construct types []
entity_name string ❌ Filter by entity name (partial match) ""
visibility []string ❌ Filter by visibility modifiers []

Sort Options

  • similarity:desc - Most similar first (default)
  • similarity:asc - Least similar first
  • file_path:asc - Alphabetical by file path
  • file_path:desc - Reverse alphabetical by file path

Semantic Construct Types

Available values for types parameter:

Type Description Example
function Standalone functions func calculateTax()
method Class/struct methods func (u *User) Login()
class Class definitions class UserManager
struct Struct definitions type User struct
interface Interface definitions type Repository interface
enum Enumerations enum Status { Active, Inactive }
variable Variable declarations var apiKey string
constant Constants const MaxRetries = 3
field Struct/class fields Name string
property Properties public string Name { get; set; }
module Modules/packages package auth
namespace Namespaces namespace MyApp.Auth
type Type definitions type UserID int
fragment Generic code fragments Mixed content

Visibility Modifiers

Available values for visibility parameter:

  • public - Publicly accessible
  • private - Private scope
  • protected - Protected scope
  • internal - Internal/package scope

Response Format

SearchResponseDTO

{
  "results": [SearchResultDTO],
  "search_metadata": {
    "total_results": 42,
    "execution_time_ms": 123,
    "query": "implement authentication middleware",
    "applied_filters": {
      "languages": ["go", "typescript"],
      "types": ["function", "method"],
      "file_types": [".go", ".ts"],
      "similarity_threshold": 0.7,
      "iterative_scan_used": true
    }
  }
}

SearchResultDTO

{
  "chunk_id": "550e8400-e29b-41d4-a716-446655440000",
  "content": "func AuthMiddleware(next http.Handler) http.Handler {\n    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {\n        // Authentication logic here\n        next.ServeHTTP(w, r)\n    })\n}",
  "similarity_score": 0.95,
  "repository": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "web-api",
    "url": "https://github.com/company/web-api"
  },
  "file_path": "middleware/auth.go",
  "language": "go",
  "start_line": 15,
  "end_line": 22,
  "type": "function",
  "entity_name": "AuthMiddleware",
  "parent_entity": "",
  "qualified_name": "middleware.AuthMiddleware",
  "signature": "AuthMiddleware(next http.Handler) http.Handler",
  "visibility": "public"
}

Basic Search Examples

Simple Text Search

curl -X POST http://localhost:8080/search \
  -H "Content-Type: application/json" \
  -d '{
    "query": "user authentication",
    "limit": 5
  }'

Language-Specific Search

{
  "query": "database connection",
  "languages": ["go", "python"],
  "limit": 10
}

Repository-Specific Search

{
  "query": "error handling",
  "repository_ids": ["123e4567-e89b-12d3-a456-426614174000"],
  "similarity_threshold": 0.8
}

Advanced Type Filtering

Find Only Functions

{
  "query": "calculate total price",
  "types": ["function"],
  "limit": 15
}

Find Class Methods

{
  "query": "user validation",
  "types": ["method"],
  "entity_name": "validate"
}

Find Public Interfaces

{
  "query": "repository pattern",
  "types": ["interface"],
  "visibility": ["public"]
}

Find Specific Entity Names

{
  "query": "authentication logic",
  "entity_name": "login",
  "types": ["function", "method"]
}

Combining Filters

Complex Multi-Filter Search

{
  "query": "implement user service",
  "languages": ["go"],
  "types": ["struct", "method"],
  "visibility": ["public"],
  "entity_name": "user",
  "similarity_threshold": 0.75,
  "limit": 20,
  "sort": "similarity:desc"
}

Enterprise API Search

{
  "query": "payment processing workflow",
  "repository_ids": [
    "123e4567-e89b-12d3-a456-426614174000",
    "987fcdeb-51a2-43d1-9876-543210987654"
  ],
  "types": ["function", "method", "class"],
  "languages": ["go", "typescript", "java"],
  "file_types": [".go", ".ts", ".java"],
  "visibility": ["public"],
  "limit": 50,
  "offset": 0
}

Response Examples

Successful Search Response

{
  "results": [
    {
      "chunk_id": "550e8400-e29b-41d4-a716-446655440000",
      "content": "func ProcessPayment(amount float64, method PaymentMethod) (*PaymentResult, error) {\n    // Validate payment amount\n    if amount <= 0 {\n        return nil, errors.New(\"invalid amount\")\n    }\n    \n    // Process payment based on method\n    switch method {\n    case CreditCard:\n        return processCreditCard(amount)\n    case PayPal:\n        return processPayPal(amount)\n    default:\n        return nil, errors.New(\"unsupported payment method\")\n    }\n}",
      "similarity_score": 0.92,
      "repository": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "name": "payment-service",
        "url": "https://github.com/company/payment-service"
      },
      "file_path": "internal/payment/processor.go",
      "language": "go",
      "start_line": 45,
      "end_line": 60,
      "type": "function",
      "entity_name": "ProcessPayment",
      "parent_entity": "",
      "qualified_name": "payment.ProcessPayment",
      "signature": "ProcessPayment(amount float64, method PaymentMethod) (*PaymentResult, error)",
      "visibility": "public"
    },
    {
      "chunk_id": "661f9500-f39c-52e5-b827-557766551111",
      "content": "type PaymentProcessor struct {\n    gateway PaymentGateway\n    logger  *log.Logger\n    config  *ProcessorConfig\n}\n\n// NewPaymentProcessor creates a new payment processor instance\nfunc NewPaymentProcessor(gateway PaymentGateway, logger *log.Logger, config *ProcessorConfig) *PaymentProcessor {\n    return &PaymentProcessor{\n        gateway: gateway,\n        logger:  logger,\n        config:  config,\n    }\n}",
      "similarity_score": 0.88,
      "repository": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "name": "payment-service",
        "url": "https://github.com/company/payment-service"
      },
      "file_path": "internal/payment/processor.go",
      "language": "go",
      "start_line": 15,
      "end_line": 28,
      "type": "struct",
      "entity_name": "PaymentProcessor",
      "parent_entity": "",
      "qualified_name": "payment.PaymentProcessor",
      "signature": "",
      "visibility": "public"
    }
  ],
  "search_metadata": {
    "total_results": 2,
    "execution_time_ms": 156,
    "query": "payment processing workflow",
    "applied_filters": {
      "languages": ["go"],
      "types": ["function", "struct"],
      "similarity_threshold": 0.7
    }
  }
}

Empty Results Response

{
  "results": [],
  "search_metadata": {
    "total_results": 0,
    "execution_time_ms": 45,
    "query": "nonexistent functionality",
    "applied_filters": {
      "similarity_threshold": 0.7
    }
  }
}

Error Response

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "limit must be between 1 and 100",
    "details": {
      "field": "limit",
      "provided_value": 150
    }
  }
}

Best Practices

Query Construction

  1. Use Natural Language: Write queries as you would describe the functionality

    {"query": "validate user email address"}

  2. Combine Semantic Types: Use multiple types for broader search

    {"types": ["function", "method"], "query": "authentication"}

  3. Entity Name Filtering: Use partial matching for flexible entity discovery

    {"entity_name": "auth", "query": "login functionality"}

Performance Optimization

  1. Set Appropriate Limits: Use reasonable limits to avoid overwhelming responses

    {"limit": 20, "offset": 0}

  2. Use Similarity Threshold: Filter out low-quality matches

    {"similarity_threshold": 0.8}

  3. Repository Filtering: Search specific repositories when possible - CRITICAL for pgvector iterative scanning

    {"repository_ids": ["known-repo-id"]}

  4. Language and File Extension Filtering: These work seamlessly with pgvector iterative scanning to guarantee result counts

    {"languages": ["go"], "file_types": [".go"]}

pgvector Iterative Scanning (New Feature)

Problem Solved: Traditional vector search with filters often returns fewer results than requested because filters are applied after the index scan. For example, asking for 20 results might only return 3 if the filters are very selective.

Solution: pgvector 0.8.0+ iterative scanning automatically continues searching when filters reduce result count, ensuring you get the requested number of results.

How It Works

{
  "query": "database connection",
  "repository_ids": ["backend-service"],
  "languages": ["go"],
  "limit": 15
}

With iterative scanning enabled:

  1. pgvector performs initial vector search for 15 candidates
  2. Applies repository/language filters at SQL level
  3. If < 15 results remain, pgvector automatically expands search
  4. Continues until 15 matching results found or no more candidates
  5. Returns exactly the number of results you requested (if available)

Filter Types

✅ SQL-Level Filters (Full iterative scanning benefits):

  • repository_ids - Repository filtering
  • languages - Programming language filtering
  • file_types - File extension filtering
  • types - Semantic construct filtering

⚠️ Application-Level Filters (Still work, but filters applied after search):

  • entity_name - Entity name matching
  • visibility - Visibility modifier filtering

Example with SQL-Level Filters:

{
  "query": "authentication middleware",
  "repository_ids": ["auth-service"],
  "languages": ["go", "typescript"],
  "types": ["function", "method"],
  "file_types": [".go", ".ts"],
  "limit": 20
}

This query will return up to 20 highly relevant results, with pgvector automatically expanding the search scope if needed to find enough matches across your filtered repositories and languages.

Advanced Usage Patterns

  1. Architecture Discovery: Find patterns across codebases

    {
  "query": "repository pattern implementation",
  "types": ["interface", "struct", "method"],
  "visibility": ["public"]
}

  2. Code Quality Analysis: Find specific implementation patterns

    {
  "query": "error handling best practices",
  "types": ["function"],
  "languages": ["go"]
}

  3. API Endpoint Discovery: Locate service endpoints

    {
  "query": "HTTP handler",
  "entity_name": "handler",
  "types": ["function", "method"],
  "file_types": [".go"]
}

Integration Examples

Search for Authentication Functions

curl -X POST http://localhost:8080/search \
  -H "Content-Type: application/json" \
  -d '{
    "query": "user authentication and authorization",
    "types": ["function", "method"],
    "entity_name": "auth",
    "visibility": ["public"],
    "languages": ["go"],
    "limit": 10
  }'

Find Database Repository Implementations

curl -X POST http://localhost:8080/search \
  -H "Content-Type: application/json" \
  -d '{
    "query": "database repository pattern",
    "types": ["struct", "interface", "method"],
    "entity_name": "repository",
    "visibility": ["public"],
    "limit": 25,
    "similarity_threshold": 0.75
  }'

Discover Error Handling Patterns

curl -X POST http://localhost:8080/search \
  -H "Content-Type: application/json" \
  -d '{
    "query": "error handling and validation",
    "types": ["function"],
    "languages": ["go"],
    "signature": "error",
    "limit": 15
  }'

Troubleshooting

Common Issues

  1. No Results: Check similarity threshold and filters are not too restrictive
  2. Slow Queries: Use repository filtering and appropriate limits
  3. Validation Errors: Ensure all parameters are within acceptable ranges

Rate Limits

  • Maximum 100 requests per minute per API key
  • Maximum 100 results per search request
  • Queries longer than 1000 characters will be truncated

For more information, see:

Configuration
Usage Guides
Performance - vector storage performance

Clone this wiki locally