> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/avnlp/vectordb/llms.txt
> Use this file to discover all available pages before exploring further.

# Utilities

> Shared utility APIs for evaluation, sparse embeddings, and document conversion

Utility modules providing shared functionality across all vector database integrations.

## Evaluation Metrics

### compute\_recall\_at\_k

Compute Recall\@k for a single query.

```python theme={null}
compute_recall_at_k(
    retrieved_ids: list[str],
    relevant_ids: set[str],
    k: int
) -> float
```

<ParamField path="retrieved_ids" type="list[str]" required>
  List of retrieved document IDs in ranked order
</ParamField>

<ParamField path="relevant_ids" type="set[str]" required>
  Set of ground truth relevant document IDs
</ParamField>

<ParamField path="k" type="int" required>
  Number of top results to consider
</ParamField>

<ResponseField name="recall" type="float">
  Recall score between 0 and 1. Formula: (relevant docs in top-k) / (total relevant docs)
</ResponseField>

### compute\_precision\_at\_k

Compute Precision\@k for a single query.

```python theme={null}
compute_precision_at_k(
    retrieved_ids: list[str],
    relevant_ids: set[str],
    k: int
) -> float
```

<ParamField path="retrieved_ids" type="list[str]" required>
  List of retrieved document IDs in ranked order
</ParamField>

<ParamField path="relevant_ids" type="set[str]" required>
  Set of ground truth relevant document IDs
</ParamField>

<ParamField path="k" type="int" required>
  Number of top results to consider
</ParamField>

<ResponseField name="precision" type="float">
  Precision score between 0 and 1. Formula: (relevant docs in top-k) / k
</ResponseField>

### compute\_mrr

Compute Mean Reciprocal Rank for a single query.

```python theme={null}
compute_mrr(
    retrieved_ids: list[str],
    relevant_ids: set[str]
) -> float
```

<ParamField path="retrieved_ids" type="list[str]" required>
  List of retrieved document IDs in ranked order
</ParamField>

<ParamField path="relevant_ids" type="set[str]" required>
  Set of ground truth relevant document IDs
</ParamField>

<ResponseField name="mrr" type="float">
  Reciprocal rank score between 0 and 1. Formula: 1 / (rank of first relevant document)
</ResponseField>

### compute\_ndcg\_at\_k

Compute Normalized Discounted Cumulative Gain at k.

```python theme={null}
compute_ndcg_at_k(
    retrieved_ids: list[str],
    relevant_ids: set[str],
    k: int
) -> float
```

<ParamField path="retrieved_ids" type="list[str]" required>
  List of retrieved document IDs in ranked order
</ParamField>

<ParamField path="relevant_ids" type="set[str]" required>
  Set of ground truth relevant document IDs
</ParamField>

<ParamField path="k" type="int" required>
  Number of top results to consider
</ParamField>

<ResponseField name="ndcg" type="float">
  NDCG score between 0 and 1. Formula: DCG\@k / IDCG\@k (Ideal DCG)
</ResponseField>

### compute\_hit\_rate

Compute hit rate (binary success) for a single query.

```python theme={null}
compute_hit_rate(
    retrieved_ids: list[str],
    relevant_ids: set[str],
    k: int
) -> float
```

<ParamField path="retrieved_ids" type="list[str]" required>
  List of retrieved document IDs in ranked order
</ParamField>

<ParamField path="relevant_ids" type="set[str]" required>
  Set of ground truth relevant document IDs
</ParamField>

<ParamField path="k" type="int" required>
  Number of top results to consider
</ParamField>

<ResponseField name="hit_rate" type="float">
  1.0 if any relevant doc is in top-k, else 0.0
</ResponseField>

### evaluate\_retrieval

Evaluate retrieval quality over multiple queries.

```python theme={null}
evaluate_retrieval(
    query_results: list[QueryResult],
    k: int = 5
) -> RetrievalMetrics
```

<ParamField path="query_results" type="list[QueryResult]" required>
  List of QueryResult objects with retrieved and relevant IDs
</ParamField>

<ParamField path="k" type="int" default="5">
  Cutoff for top-k metrics
</ParamField>

<ResponseField name="metrics" type="RetrievalMetrics">
  RetrievalMetrics object with averaged scores across all queries
</ResponseField>

***

## Sparse Embeddings

### normalize\_sparse

Normalize any sparse format to Haystack SparseEmbedding.

```python theme={null}
normalize_sparse(
    sparse: Union[SparseEmbedding, Dict[int, float], Dict[str, List], None]
) -> Optional[SparseEmbedding]
```

<ParamField path="sparse" type="Union[SparseEmbedding, Dict[int, float], Dict[str, List], None]" required>
  Sparse embedding in any supported format:

  * SparseEmbedding object (passthrough)
  * Dict with int keys and float values (Milvus format)
  * Dict with indices and values lists (Pinecone format)
  * None (passthrough)
</ParamField>

<ResponseField name="sparse" type="Optional[SparseEmbedding]">
  Normalized SparseEmbedding or None
</ResponseField>

### to\_milvus\_sparse

Convert SparseEmbedding to Milvus format.

```python theme={null}
to_milvus_sparse(sparse: SparseEmbedding) -> Dict[int, float]
```

<ParamField path="sparse" type="SparseEmbedding" required>
  Haystack SparseEmbedding object
</ParamField>

<ResponseField name="milvus_sparse" type="Dict[int, float]">
  Dictionary mapping indices to values in Milvus format
</ResponseField>

### to\_pinecone\_sparse

Convert SparseEmbedding to Pinecone sparse\_values format.

```python theme={null}
to_pinecone_sparse(sparse: SparseEmbedding) -> Dict[str, List]
```

<ParamField path="sparse" type="SparseEmbedding" required>
  Haystack SparseEmbedding object
</ParamField>

<ResponseField name="pinecone_sparse" type="Dict[str, List]">
  Dictionary with 'indices' and 'values' keys in Pinecone format
</ResponseField>

### to\_qdrant\_sparse

Convert SparseEmbedding to Qdrant SparseVector format.

```python theme={null}
to_qdrant_sparse(sparse: SparseEmbedding) -> SparseVector
```

<ParamField path="sparse" type="SparseEmbedding" required>
  Haystack SparseEmbedding object
</ParamField>

<ResponseField name="qdrant_sparse" type="SparseVector">
  Qdrant SparseVector object
</ResponseField>

### get\_doc\_sparse\_embedding

Extract sparse embedding from Document, checking standard and legacy locations.

```python theme={null}
get_doc_sparse_embedding(
    doc: Any,
    fallback_meta_key: str = "sparse_embedding"
) -> Optional[SparseEmbedding]
```

<ParamField path="doc" type="Any" required>
  Haystack Document object
</ParamField>

<ParamField path="fallback_meta_key" type="str" default="sparse_embedding">
  Legacy meta key to check if doc.sparse\_embedding is None
</ParamField>

<ResponseField name="sparse" type="Optional[SparseEmbedding]">
  SparseEmbedding from doc.sparse\_embedding or doc.meta\[fallback\_meta\_key], or None
</ResponseField>

***

## Document Converters

### ChromaDocumentConverter

Utility class for converting between Haystack Documents and Chroma format.

#### prepare\_haystack\_documents\_for\_upsert

```python theme={null}
ChromaDocumentConverter.prepare_haystack_documents_for_upsert(
    documents: List[Document]
) -> Dict[str, Any]
```

<ParamField path="documents" type="List[Document]" required>
  List of Haystack Document objects
</ParamField>

<ResponseField name="data" type="Dict[str, Any]">
  Dictionary with keys: ids, texts, metadatas, embeddings formatted for Chroma upsert
</ResponseField>

### PineconeDocumentConverter

Utility class for converting between Haystack Documents and Pinecone format.

#### prepare\_haystack\_documents\_for\_upsert

```python theme={null}
PineconeDocumentConverter.prepare_haystack_documents_for_upsert(
    documents: List[Document]
) -> List[Dict[str, Any]]
```

<ParamField path="documents" type="List[Document]" required>
  List of Haystack Document objects
</ParamField>

<ResponseField name="vectors" type="List[Dict[str, Any]]">
  List of Pinecone vector dictionaries with id, values, metadata keys
</ResponseField>

#### convert\_query\_results\_to\_haystack\_documents

```python theme={null}
PineconeDocumentConverter.convert_query_results_to_haystack_documents(
    results: Dict[str, Any],
    include_embeddings: bool = False
) -> List[Document]
```

<ParamField path="results" type="Dict[str, Any]" required>
  Pinecone query results dictionary
</ParamField>

<ParamField path="include_embeddings" type="bool" default="False">
  Whether to include vector embeddings in Documents
</ParamField>

<ResponseField name="documents" type="List[Document]">
  List of Haystack Document objects
</ResponseField>

***

## Configuration

### load\_config

Load configuration from YAML file.

```python theme={null}
load_config(config_path: str) -> Dict[str, Any]
```

<ParamField path="config_path" type="str" required>
  Path to YAML configuration file
</ParamField>

<ResponseField name="config" type="Dict[str, Any]">
  Loaded configuration dictionary with environment variables resolved
</ResponseField>

### resolve\_env\_vars

Resolve environment variable references in configuration.

```python theme={null}
resolve_env_vars(config: Dict[str, Any]) -> Dict[str, Any]
```

<ParamField path="config" type="Dict[str, Any]" required>
  Configuration dictionary potentially containing \${ENV_VAR} references
</ParamField>

<ResponseField name="resolved" type="Dict[str, Any]">
  Configuration with all environment variables resolved
</ResponseField>