> ## Documentation Index > Fetch the complete documentation index at: https://docs.gp.scale.com/llms.txt > Use this file to discover all available pages before exploring further. # Query Vectors > Query documents using similarity search with optional reranking. Primary endpoint for semantic search, question-answering, and RAG (Retrieval-Augmented Generation) applications. Returns documents ranked by relevance to the query text with similarity scores. **Query Types:** - `semantic` (default): Approximate nearest-neighbor search using HNSW over cosine similarity of document embeddings. Optimal for question-answering, conceptual search, and finding semantically related content without requiring exact keyword matches. - `lexical`: Keyword-based text search (BM25 algorithm). Optimal for exact phrase matching, proper nouns, and scenarios where keyword presence is more important than semantic similarity. - `hybrid`: Combines semantic and lexical approaches with weighted scoring. Provides maximum recall by identifying documents matching either semantically or lexically. **Metadata Filtering:** Narrow the search scope by applying metadata filters (e.g., search only documents where `category: "technical"`). Only indexed fields can be used for filtering. Filters are applied before similarity search for optimal efficiency. **Reranking (Advanced):** Optionally enhance result quality using a cross-encoder reranking model. The reranker rescores the initial results using a more sophisticated model that evaluates the complete query-document pair (not solely embeddings). This adds 100-500ms latency but significantly improves precision for high-stakes applications. **Reranking Strategy:** Set `top_k` higher than the desired final count (e.g., 50) to retrieve more candidates from the initial search. Then configure `rerank_top_n` to the desired final count (e.g., 10) to return only the most relevant documents after reranking. This two-stage approach maximizes both recall and precision. **Performance Metrics:** The response includes detailed timing breakdowns (embedding generation time, index query time, reranking time) to facilitate search pipeline optimization and latency analysis. **Similarity Scores:** Each result includes a `score` field indicating relevance. Higher scores indicate greater relevance. Score ranges and semantics vary by query type (semantic scores use cosine similarity, lexical scores use BM25, hybrid scores combine both approaches). ## OpenAPI ````yaml https://api.dev-sgp.scale.com/openapi-versions/v5/openapi.json post /v5/vector-stores/{vector_store_name}/query openapi: 3.1.0 info: title: EGP API V5 description: >- This is the parent API for all EGP APIs. If you are looking for the EGP API, please go to https://api.egp.scale.com/docs. contact: name: Scale Generative AI Platform url: https://scale.com/genai-platform version: 0.1.0 servers: - url: https://api.egp.scale.com security: [] paths: /v5/vector-stores/{vector_store_name}/query: post: tags: - Vector Stores summary: Query Vectors description: >- Query documents using similarity search with optional reranking. Primary endpoint for semantic search, question-answering, and RAG (Retrieval-Augmented Generation) applications. Returns documents ranked by relevance to the query text with similarity scores. **Query Types:** - `semantic` (default): Approximate nearest-neighbor search using HNSW over cosine similarity of document embeddings. Optimal for question-answering, conceptual search, and finding semantically related content without requiring exact keyword matches. - `lexical`: Keyword-based text search (BM25 algorithm). Optimal for exact phrase matching, proper nouns, and scenarios where keyword presence is more important than semantic similarity. - `hybrid`: Combines semantic and lexical approaches with weighted scoring. Provides maximum recall by identifying documents matching either semantically or lexically. **Metadata Filtering:** Narrow the search scope by applying metadata filters (e.g., search only documents where `category: "technical"`). Only indexed fields can be used for filtering. Filters are applied before similarity search for optimal efficiency. **Reranking (Advanced):** Optionally enhance result quality using a cross-encoder reranking model. The reranker rescores the initial results using a more sophisticated model that evaluates the complete query-document pair (not solely embeddings). This adds 100-500ms latency but significantly improves precision for high-stakes applications. **Reranking Strategy:** Set `top_k` higher than the desired final count (e.g., 50) to retrieve more candidates from the initial search. Then configure `rerank_top_n` to the desired final count (e.g., 10) to return only the most relevant documents after reranking. This two-stage approach maximizes both recall and precision. **Performance Metrics:** The response includes detailed timing breakdowns (embedding generation time, index query time, reranking time) to facilitate search pipeline optimization and latency analysis. **Similarity Scores:** Each result includes a `score` field indicating relevance. Higher scores indicate greater relevance. Score ranges and semantics vary by query type (semantic scores use cosine similarity, lexical scores use BM25, hybrid scores combine both approaches). operationId: POST-V5-/v5/vector-stores/vector_store_name/query parameters: - name: vector_store_name in: path required: true schema: type: string description: The name of the vector store title: Vector Store Name description: The name of the vector store - name: x-selected-account-id in: header required: false schema: anyOf: - type: string - type: 'null' title: Account ID Header requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/QueryVectorsRequest' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/QueryVectorsResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' security: - APIKeyHeader: [] components: schemas: QueryVectorsRequest: properties: content: oneOf: - $ref: '#/components/schemas/TextContent' title: Content description: Query content for automatic embedding discriminator: propertyName: type mapping: text: $ref: '#/components/schemas/TextContent' query_type: $ref: '#/components/schemas/QueryType' description: 'Query type: semantic, lexical, or hybrid' default: semantic top_k: type: integer minimum: 1 title: Top K description: Number of search results to return default: 10 filter: title: Filter description: Metadata filter expression additionalProperties: true type: object rerank_config: $ref: '#/components/schemas/RerankConfig' description: >- Reranking configuration. Presence enables reranking; omit to disable. Pass an empty object ({}) to enable reranking with system defaults. rerank: type: boolean title: Rerank description: '[Deprecated: use rerank_config] Enable reranking of search results' default: false rerank_model: title: Rerank Model description: '[Deprecated: use rerank_config.model] Reranking model to use' type: string rerank_top_n: title: Rerank Top N description: >- [Deprecated: use rerank_config.top_n] Number of results after reranking type: integer minimum: 1 rerank_instruction: title: Rerank Instruction description: >- [Deprecated: use rerank_config.instruction] Custom instruction for reranker type: string include_vectors: type: boolean title: Include Vectors description: Include embedding vectors in response default: false type: object required: - content title: QueryVectorsRequest description: Request to query documents. QueryVectorsResponse: properties: vectors: items: $ref: '#/components/schemas/QueryVectorDocumentResponse' type: array title: Vectors description: Array of matching documents metadata: $ref: '#/components/schemas/QueryMetadata' description: Query execution metadata type: object required: - vectors - metadata title: QueryVectorsResponse description: Response for query operation. HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError TextContent: properties: type: type: string const: text title: Type description: Content type identifier default: text text: type: string title: Text description: Text content to be embedded type: object required: - text title: TextContent description: Text content for documents. QueryType: type: string enum: - semantic - lexical - hybrid title: QueryType description: Supported query types for vector search. RerankConfig: properties: type: type: string const: base title: Type description: Reranking configuration type. Currently only 'base' is supported. default: base model: title: Model description: Reranking model to use (uses system default if not specified) type: string top_n: title: Top N description: Number of results to keep after reranking (defaults to top_k) type: integer minimum: 1 instruction: title: Instruction description: >- Custom instruction for the reranking model (e.g., 'Given a medical question, retrieve relevant clinical passages'). Only applies to instruction-following rerankers like Qwen3. type: string type: object title: RerankConfig description: >- Configuration for reranking search results. Presence of this object enables reranking; omitting it (None) disables reranking. All fields are optional -- an empty config ({}) enables reranking with system defaults. QueryVectorDocumentResponse: properties: id: type: string title: Id description: Document ID content: title: Content description: Document content. None for raw-embedding documents without text. oneOf: - $ref: '#/components/schemas/TextContent' discriminator: propertyName: type mapping: text: $ref: '#/components/schemas/TextContent' metadata: additionalProperties: true type: object title: Metadata description: Key-value metadata vector: title: Vector description: Embedding vector (if requested) items: type: number type: array score: type: number title: Score description: Similarity score indicating relevance type: object required: - id - score title: QueryVectorDocumentResponse description: >- A document in query/search responses with similarity score. Extends VectorDocumentResponse to add a similarity score field for ranked search results. QueryMetadata: properties: search_type: type: string title: Search Type description: Type of search performed (semantic, lexical, hybrid) total_query_time_ms: type: integer title: Total Query Time Ms description: Total end-to-end query execution time in milliseconds embedding_config: $ref: '#/components/schemas/EmbeddingConfig' description: >- Embedding configuration used for query vectorization. None for lexical queries on model-less stores. embedding_time_ms: title: Embedding Time Ms description: >- Time spent generating embeddings in milliseconds (None for lexical queries) type: integer index_query_time_ms: title: Index Query Time Ms description: Time spent querying the vector index (OpenSearch) in milliseconds type: integer reranking_model: title: Reranking Model description: Reranking model used (None if reranking not enabled) type: string reranking_time_ms: title: Reranking Time Ms description: >- Time spent reranking results in milliseconds (None if reranking not enabled) type: integer type: object required: - search_type - total_query_time_ms title: QueryMetadata description: Metadata about query execution with performance breakdown. ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: title: Error Type type: string input: title: Input ctx: type: object title: Context additionalProperties: true type: object required: - loc - msg - type title: ValidationError EmbeddingConfig: anyOf: - $ref: '#/components/schemas/EmbeddingConfigModelsAPI' - $ref: '#/components/schemas/EmbeddingConfigBase' title: EmbeddingConfig EmbeddingConfigModelsAPI: properties: type: type: string const: models_api title: Type description: The type of the embedding configuration. model_deployment_id: type: string title: Model Deployment Id description: The ID of the deployment of the created model in the Models API V3. type: object required: - type - model_deployment_id title: EmbeddingConfigModelsAPI EmbeddingConfigBase: properties: type: type: string const: base title: Type description: The type of the embedding configuration. default: base embedding_model: $ref: '#/components/schemas/EmbeddingModelName' description: >- The name of the base embedding model to use. To use custom models, change to type 'models'. type: object required: - embedding_model title: EmbeddingConfigBase EmbeddingModelName: type: string enum: - sentence-transformers/all-MiniLM-L12-v2 - sentence-transformers/all-mpnet-base-v2 - sentence-transformers/multi-qa-distilbert-cos-v1 - sentence-transformers/paraphrase-multilingual-mpnet-base-v2 - openai/text-embedding-ada-002 - openai/text-embedding-3-small - openai/text-embedding-3-large - embed-english-v3.0 - embed-english-light-v3.0 - embed-multilingual-v3.0 - gemini/text-embedding-005 - gemini/text-multilingual-embedding-002 - gemini/gemini-embedding-001 title: EmbeddingModelName securitySchemes: APIKeyHeader: type: apiKey in: header name: x-api-key ````