Azure / Azure/azure-sdk-for-python
[Cosmos] [Embedding V0] Plan-info accessor + _QueryFeature.EmbeddingGeneration + supported-features advertisement
- Lingua principale
- Python
- Stelle
- 5.6k
- Fork
- 3.4k
- Merge medio
- 2g 2h
- PR unite (30g)
- 213
Descrizione
# Plan DTO accessor + `_QueryFeature.EmbeddingGeneration` + supported-features advertisement
Parent: 46729
## Goal
Teach the SDK to (a) read the new `embeddingParameterMap` field out of a query-plan response and (b) advertise the new feature so the gateway emits it.
## Scope
1. `azure/cosmos/documents.py` – add to `_QueryFeature`:
```python
EmbeddingGeneration: Literal["EmbeddingGeneration"] = "EmbeddingGeneration"
```
2. `azure/cosmos/_execution_context/query_execution_info.py` – new accessor on `_PartitionedQueryExecutionInfo`:
```python
EmbeddingParameterMapPath = [QueryInfoPath, "embeddingParameterMap"]
HybridEmbeddingParameterMapPath = [HybridSearchQueryInfoPath, "embeddingParameterMap"]
def get_embedding_parameter_map(self):
return (self._extract(self.HybridEmbeddingParameterMapPath)
or self._extract(self.EmbeddingParameterMapPath)
or {})
```
3. `azure/cosmos/_cosmos_client_connection.py :: _GetQueryPlanThroughGateway` (sync) – build `supported_query_features` per-request, conditionally appending `documents._QueryFeature.EmbeddingGeneration` when `options.get("embeddingGenerator") is not None`.
4. `azure/cosmos/aio/_cosmos_client_connection_async.py :: _GetQueryPlanThroughGateway` (async) – mirror the same change.
5. Move the now-conditional supported-features string out of the inline ladder into a small helper to avoid further duplication.
## Non-goals
- Do NOT yet wire the accessor into the aggregator (covered by 46733).
- Do NOT change the on-wire JSON parser; the existing `_extract` walk handles new keys.
## Files touched
- `sdk/cosmos/azure-cosmos/azure/cosmos/documents.py`
- `sdk/cosmos/azure-cosmos/azure/cosmos/_execution_context/query_execution_info.py`
- `sdk/cosmos/azure-cosmos/azure/cosmos/_cosmos_client_connection.py`
- `sdk/cosmos/azure-cosmos/azure/cosmos/aio/_cosmos_client_connection_async.py`
- `sdk/cosmos/azure-cosmos/CHANGELOG.md`
## Acceptance
- A canned plan-response dict containing `embeddingParameterMap` returns the right map from `get_embedding_parameter_map()`.
- A plan-response dict with no map returns `{}` (not `None`) so callers can iterate freely.
- When `embedding_generator` is configured, the outgoing `supportedQueryFeatures` header contains `EmbeddingGeneration`; otherwise it does not.
- All existing query-plan tests still pass.
Guida per i contributori
Apri la guida per i contributori
Direzione di ricerca
Inizia con _QueryFeature in azure/cosmos/documents.py e _PartitionedQueryExecutionInfo in azure/cosmos/_execution_context/query_execution_info.py, quindi esamina gli entry point sincrono e asincrono _GetQueryPlanThroughGateway e i test esistenti del piano di query. Verifica che entrambi i percorsi di accesso alla mappa dei piani restituiscano la mappa prevista o {}, che l’annuncio della funzionalità sia condizionale e che tutti i test esistenti del piano di query superino l’esecuzione.
Scritto dal modello di indicizzazione a partire dal testo della issue.
Valutazione
- Stack tecnologico
- python
- Ambito
- backend-api-design, databases
- Tipo di issue
- Funzionalità
- Difficoltà
- 4/5
- Tempo stimato
- 3-5 giorni
- Stato di attività
- Tranquilla
- Chiarezza
- Specificata chiaramente
- Idoneità per principianti
- 68/100