Azure / Azure/azure-sdk-for-python

[Cosmos] [Embedding V0] Plan-info accessor + _QueryFeature.EmbeddingGeneration + supported-features advertisement

Aperta
#46,731 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub
Cosmos feature-request
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

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.