[Quim Muntal (qmuntal)]

Summary

• Port the CommunityToolkit Cosmos DB connector to azureprovider.CosmosDB, using stable azcosmos v1.5.0 and a caller-owned native client.
• Support container lifecycle, typed and dynamic records, CRUD and sequential batches, generated UUIDs, scalar/composite lookup keys, and hierarchical/nullable partition keys.
• Add float32/uint8/int8 vectors, embedding generation, portable filters, vector search, and full-text/vector hybrid search.
• Include Go documentation, a runnable example, protocol regression tests, and four opt-in live integration tests.

Compatibility and limits

• The client and database must already exist. The provider does not close the borrowed client or configure account-level capabilities.
• Stable azcosmos does not execute cross-partition ranking/ordering. Vector search, hybrid search, and ordered retrieval require equality filters for every partition-key property; unsupported queries fail before service I/O or embedding generation.
• Unordered filtered retrieval supports cross-partition paging and applies Skip/top while iterating.
• Generated-vector collections do not support IncludeVectors; sequential batches may partially succeed. These contracts are documented in Go comments.
• No preview SDK or experimental query engine is introduced.

Validation

• Focused provider and VectorData tests passed.
• Cosmos regression tests and all four live integration tests passed on Go 1.26.1 and Go 1.27.0.
• Live validation used a real Entra ID-only, serverless Cosmos DB account and real 3072-dimensional Foundry embeddings. It covered native container lifecycle, CRUD/batches, all supported vector types, score thresholds, hybrid ranking, dynamic records, hierarchical numeric/null partition keys, named keys, cross-partition paging, and cancellation.
• The example ran successfully against the real services; the Go 1.27 example build also passed.
• golangci-lint v2.15.0 reported zero issues.
• All temporary Cosmos resources were deleted after validation. Live tests remain opt-in and clean up only their own containers.

[Copilot]

🟡 Changes recommended

Unresolved schema-path, score-field collision, and timestamp-query defects affect correctness.

4 open issues

• Reserve __cosmos_score to prevent search result collisions · New
• Cosmos paths mishandle JSON Pointer escape sequences · New
• Normalize timestamps for correct Cosmos ordering and filtering · New
• Avoid transferring vectors when IncludeVectors is false · New

What changed in this PR

Adds an Azure Cosmos DB backend to VectorData using a caller-owned native client.

Changes:

• Supports container lifecycle, typed/dynamic records, CRUD, and partition keys.
• Adds embedding generation and partition-scoped vector/hybrid search.
• Includes protocol tests, opt-in live tests, and a runnable example.

File	Description
provider/​azureprovider/​cosmosdb.go	Store configuration and public contracts.
provider/​azureprovider/​cosmosdb_test.go	Protocol regression tests.
provider/​azureprovider/​cosmosdb_query.go	Filters, routing, and ranked queries.
provider/​azureprovider/​cosmosdb_e2e_test.go	Four opt-in live integration tests.
provider/​azureprovider/​cosmosdb_collection.go	Container policies, record mapping, CRUD, and paging.
go.sum	Cosmos SDK dependency checksums.
go.mod	Adds stable azcosmos dependency.
examples/​02-agents/​providers/​azure/​cosmosdb/​main.go	Demonstrates generated embeddings and scoped search.

_{Review effort: Balanced}

[github-actions]

API consistency review

Result	Scope
aligned	public API

Changed Go contract

New azureprovider exports: CosmosDB (embeds *vectordata.Store), NewCosmosDB(client *azcosmos.Client, databaseName string, config CosmosDBConfig) (*CosmosDB, error), CosmosDBConfig{PartitionKeyProperties, IndexingMode, Automatic, EmbeddingGenerator}, and CosmosKey{DocumentID, PartitionKey}. Internal cosmosDBStore implements vectordata.StoreProvider, plus a new example under examples/02-agents/providers/azure/cosmosdb/.

Upstream evidence reviewed

Implementation	Source	Contract checked
C# (CommunityToolkit MEVD, cited in PR description)	CosmosCollectionOptions.cs	PartitionKeyProperties (null ⇒ document ID is the partition key, string/Guid key type only), IndexingMode (default Consistent), Automatic (default true) — all match CosmosDBConfig defaults and semantics in cosmosdb.go
C# (CommunityToolkit MEVD)	CosmosKey.cs	Composite document-ID + partition-key struct; Go's CosmosKey{DocumentID, PartitionKey} is the idiomatic Go analog (slice of any vs. hierarchical PartitionKey builder)
C# (CommunityToolkit MEVD)	CosmosCollection.cs (lines ~359, 396, 543, 648)	IncludeVectors throws NotSupportedException when embedding generation is required — Go's documented "IncludeVectors is unsupported on collections with generated vector fields" matches
C# (CommunityToolkit MEVD)	CosmosModelBuilder.cs	Key property type restricted to string/Guid; vector types restricted to float/byte/sbyte — matches Go's string/uuid.UUID keys and float32/uint8/int8 vectors
C# (CommunityToolkit MEVD)	CosmosCollectionQueryBuilder.cs (RRF ranking, lines ~84-139)	Hybrid search uses RANK RRF(...), with ordering/offset-limit constraints — Go's documented reciprocal-rank-fusion hybrid search and cross-partition ordering limitations align

Assessment

This PR is an explicitly documented, scoped port of the CommunityToolkit MEVD Azure Cosmos DB connector, using stable azcosmos instead of the preview SDK used upstream. Defaults (consistent indexing mode, automatic indexing enabled, document-ID-as-partition-key when no partition properties are configured), supported key/data/vector types, and documented constraints (IncludeVectors incompatible with generated vectors, cross-partition ordering requiring equality filters) all match the cited upstream connector. Naming follows existing Go vectordata/azureprovider conventions (e.g., parallels AISearchConfig/NewAISearch). No parity gaps were found; test coverage (26 unit tests plus 4 opt-in live integration tests) and the new example are consistent with the existing aisearch.go provider pattern in this repo.

Generated by Go API Consistency Review Agent for #1304 · copilot · auto · 117.9 AIC · ⌖ 13.8 AIC · ⊞ 14K · ◷