Skip to main content
The Cortex Search API Route serves as a critical component in Sophra’s sophisticated search infrastructure, providing a robust and flexible interface for executing complex search operations across the platform’s data ecosystem. This Next.js API route, built on TypeScript, integrates seamlessly with Elasticsearch 8.x to deliver powerful text-based, vector-based, and hybrid search capabilities. It forms the backbone of Sophra’s data retrieval system, enabling clients to perform nuanced queries with support for faceted search, pagination, and relevance boosting. At its core, this component acts as a bridge between client applications and Sophra’s search service, translating incoming HTTP requests into optimized Elasticsearch queries. It leverages Zod for runtime type checking and validation, ensuring the integrity and correctness of search parameters before execution. The route’s architecture is designed to handle various search paradigms, from traditional keyword-based searches to cutting-edge vector similarity searches, catering to a wide range of use cases within the Sophra ecosystem. One of the key architectural decisions in this component is the separation of concerns between query construction, execution, and result processing. This modular approach enhances maintainability and allows for easy extension of search capabilities. The use of a service manager pattern facilitates dependency injection and promotes loose coupling between the API route and underlying services, improving testability and flexibility. Performance optimization is a central focus of the Cortex Search API Route. It implements efficient query construction techniques to minimize Elasticsearch processing time and supports pagination to manage large result sets. The component also integrates with Sophra’s caching layer, though this integration is not explicitly shown in the provided code snippet and would be a valuable addition to further improve response times for frequently executed queries. A unique feature of this search route is its built-in support for search event tracking. Each search operation is automatically logged to the database, capturing valuable metadata such as query details, result counts, and execution time. This data forms the foundation for Sophra’s analytics and machine learning pipelines, enabling continuous improvement of search relevance and performance.

​
Exported Components

export const runtime = "nodejs";
The POST function is the main export of this component, serving as the handler for incoming search requests. It accepts a NextRequest object and returns a Promise<NextResponse>, encapsulating the entire search process from request parsing to response generation.

​
Implementation Examples

const result = await services.elasticsearch.search<BaseDocument>(
  searchOptions.index,
  {
    size,
    from,
    query: elasticsearchQuery,
    ...(validatedBody.facets && {
      aggregations: buildFacetsAggregation(validatedBody.facets),
    }),
  }
);
These examples demonstrate the core functionality of the search route:
  1. Executing an Elasticsearch query with dynamic parameters and optional faceting.
  2. Creating a search event to track the executed query and its results.

​
Sophra Integration Details

The Cortex Search API Route integrates with several Sophra components:
  • Elasticsearch Service: For executing search queries
  • Prisma ORM: For logging search events
  • Logger: For error tracking and debugging
  • Service Manager: For dependency injection and service access

​
Error Handling

The route implements comprehensive error handling to manage various failure scenarios:
Zod schema validation ensures that incoming requests are properly formatted. Invalid requests result in a 400 Bad Request response.
Errors during the Elasticsearch query execution are caught and logged. A 500 Internal Server Error response is returned to the client with error details.
Failures in creating the search event are logged but do not prevent the search results from being returned to the client.
All errors are logged using the Sophra logging system for monitoring and debugging purposes.

​
Performance Considerations

Optimization Strategies

  • Query construction optimized for Elasticsearch
  • Pagination support to handle large result sets
  • Facet aggregation for efficient category filtering
  • Potential for result caching (not implemented in current snippet)

​
Security Implementation

The provided code snippet does not show explicit authentication or authorization checks. It’s crucial to implement these security measures at the API route level or through middleware to ensure proper access control.

​
Configuration

The search route relies on several configuration points: 
POSTGRESQL_URL="your-database-url"
ELASTICSEARCH_URL="your-elasticsearch-url"
ELASTICSEARCH_API_KEY="your-elasticsearch-api-key"
These environment variables should be set to connect to the required services.

Runtime Options

  • VECTOR_DIMENSIONS: Set to 3072, defines the expected size of vector embeddings
  • Default result size: 10 items per page
  • Default fuzziness for text search: “AUTO”
  • Minimum score for vector search: 0.7 (configurable per request)
By leveraging this powerful and flexible search API route, Sophra provides its clients with a sophisticated tool for data retrieval and analysis, forming a cornerstone of its data intelligence platform.
⌘I