ShapedQL is a SQL-like domain-specific language designed specifically for building recommendation and ranking queries. It provides a familiar SQL syntax while supporting advanced retrieval, filtering, scoring, and reordering operations that are essential for modern recommendation systems and search applications.

The language supports multiple retriever functions including similarity() for vector similarity search using embeddings, text_search() for full-text search using lexical or vector search, column_order() for retrieving candidates ordered by column values, filter() for retrieving candidates matching filter expressions, ids() for retrieving specific entity IDs, and candidate_attributes() for reranking items not in the catalog. Each retriever supports parameters like embedding_ref, limit, entity_type, where clauses, and optional step names for debugging.

ShapedQL queries map to a multi-stage ranking pipeline that includes retrieval (selecting candidates), filtering (applying rules to exclude candidates), scoring (computing relevance scores), and reordering (post-processing ordering). The query execution pipeline processes retrievers in parallel, combines results through union operations, applies filtering, evaluates scoring expressions, executes reordering functions, and finally limits the results. The language supports both SQL syntax for familiar query writing and YAML/JSON query objects for fine-grained control.

The system provides various query encoders including precomputed_user for user-based recommendations, precomputed_item for item-to-item similarity, interaction_pooling for pooling embeddings from user interaction history, interaction_round_robin for round-robin retrieval from interaction clusters, and attribute_pooling encoders for encoding user or item attributes. Reorder functions include diversity() for reducing similarity between results, exploration() for balancing exploitation and exploration, and boosted() for applying boost values from item metadata.

ShapedQL operates on entity types including items (products, content) and users (for user-to-user recommendations), with support for parameters using $parameter_name syntax that accepts various data types including integers, floats, strings, booleans, and arrays. The language is designed for developers building recommendation systems, search engines, and AI agents that require sophisticated ranking and retrieval capabilities.