Advanced Search Types for Sophra

The search.ts file in Sophra’s cortex library defines a robust set of TypeScript interfaces that form the backbone of the system’s advanced search functionality. These types encapsulate the complex requirements of modern search operations, including text-based queries, vector searches for semantic similarity, and hybrid approaches that combine multiple search strategies. The file’s structure reflects Sophra’s commitment to type safety and clear API design, enabling developers to construct precise and powerful search requests while maintaining code clarity and reducing runtime errors.

At the core of Sophra’s search capabilities is the AdvancedSearchRequest interface, which orchestrates various search parameters into a cohesive query structure. This interface allows for fine-grained control over search behavior, supporting text-based searches, vector queries for semantic matching, and hybrid approaches that blend both methodologies. The flexibility of this design enables Sophra to adapt to a wide range of search scenarios, from simple keyword matching to complex, AI-driven semantic searches.

The search types defined in this file are tightly integrated with Sophra’s Elasticsearch implementation, as evidenced by the import of BaseDocument from the Elasticsearch types module. This integration ensures that search operations are optimized for Sophra’s specific Elasticsearch configuration, leveraging features such as vector embeddings for semantic search and custom scoring mechanisms.

Performance considerations are deeply embedded in the type definitions. The CachedSearchResult interface, for instance, extends the basic SearchResult to include caching metadata, facilitating efficient retrieval of frequently accessed search results. This caching mechanism is crucial for maintaining high performance under heavy load, reducing the need for repeated expensive search operations.

One of the unique features of Sophra’s search implementation is its support for hybrid searches, combining traditional text-based queries with vector searches. This capability is reflected in the AdvancedSearchRequest interface, which allows for separate weighting of text and vector components. This granular control over search behavior enables sophisticated ranking algorithms that can be fine-tuned for specific use cases, enhancing the relevance of search results.

​

Exported Components

interface TextQuery {
  fields: string[];        // Target fields for the text search
  query: string;           // The search query string
  fuzziness?: "AUTO" | "0" | "1" | "2";  // Fuzziness level for approximate matching
  operator?: "AND" | "OR"; // Logical operator for multi-term queries
}

​

Implementation Examples

const textSearchRequest: AdvancedSearchRequest = {
  index: "products",
  searchType: "text",
  textQuery: {
    fields: ["name", "description"],
    query: "organic coffee",
    fuzziness: "AUTO",
    operator: "AND"
  },
  size: 10
};

​

Sophra Integration Details

The search types defined in search.ts are integral to Sophra’s search service. They are typically used in the following workflow:

1. The client sends a search request to Sophra’s API gateway.
2. The request is validated and transformed into an AdvancedSearchRequest object.
3. The search service processes the request, potentially checking the cache first.
4. If not cached, the service constructs an Elasticsearch query based on the request.
5. The search is executed, and results are transformed into a SearchResult or CachedSearchResult.
6. The results are returned to the client and optionally cached for future use.

​

Error Handling

The search types do not explicitly define error structures, but Sophra’s search service should handle the following error scenarios:

• Invalid search parameters (e.g., malformed vector, unknown fields)
• Elasticsearch connection failures
• Index not found
• Insufficient permissions for the requested index

Error handling typically involves:

1. Validating the AdvancedSearchRequest before execution
2. Wrapping Elasticsearch operations in try-catch blocks
3. Logging errors with contextual information
4. Returning appropriate HTTP status codes and error messages to the client

​

Performance Considerations

​

Security Implementation

While the search types themselves do not implement security measures, Sophra’s search service should:

• Validate user permissions before executing searches on specific indices
• Sanitize and validate all input parameters to prevent injection attacks
• Implement rate limiting on search requests to prevent abuse
• Use Elasticsearch’s field-level security to restrict access to sensitive data

​

Configuration

The search behavior can be configured through:

• Environment variables for default search parameters
• Runtime configuration for adjusting boost weights and cache TTLs
• Elasticsearch index settings for controlling analysis and mapping behavior