Beef up MEVD docs: expanded conceptual article, new how-to guide, and working code snippets by Copilot · Pull Request #51846 · dotnet/docs

Copilot · 2026-02-24T01:20:14Z

Expand docs/ai/conceptual/vector-databases.md with MEVD API concepts and code samples
Create docs/ai/how-to/use-vector-stores.md how-to guide with working code samples and snippet files
Create compilable C# snippet project at docs/ai/how-to/snippets/use-vector-stores/csharp/VectorStoresExamples/
Update docs/ai/toc.yml to add a new "Vector stores" top-level section
Accessed SK vector store docs on learn.microsoft.com and ported additional content
Address review feedback (round 1): ai-usage, .gitignore, TOC duplicate, intro sentence, phrasing, xref headings
Address review feedback (round 2):
- Added xref links to parameter names in all three attribute parameter tables
- Changed GetCollection<TKey, TRecord> to use <xref:Microsoft.Extensions.VectorData.VectorStore.GetCollection*>
- Changed UpsertAsync to use <xref:Microsoft.Extensions.VectorData.VectorStoreCollection\2.UpsertAsync*>`
- Changed GetAsync mentions to use <xref:Microsoft.Extensions.VectorData.VectorStoreCollection\2.GetAsync*>`
- Changed VectorSearchOptions<TRecord> to use <xref:Microsoft.Extensions.VectorData.VectorSearchOptions\1>`

Original prompt

This section details on the original issue you should resolve

<issue_title>Beef up MEVD docs</issue_title>
<issue_description>### Describe the issue or suggestion

Port vector DB docs from What are Semantic Kernel Vector Stores? (Preview) | Microsoft Learn to this repo, but review and make improvements as well. MEVD has evolved since the docs were written.

We already have https://learn.microsoft.com/en-us/dotnet/ai/conceptual/vector-databases but it's woefully short (not a single code sample etc.). We might add a new top-level section (at the level of tokenization, evaluation...) to house the new content.

Associated WorkItem - 550641</issue_description>

Comments on the Issue (you are @copilot in this section)

Fixes Beef up MEVD docs #51443

🔒 GitHub Advanced Security automatically protects Copilot coding agent pull requests. You can protect all pull requests by enabling Advanced Security for your repositories. Learn more about Advanced Security.

Internal previews

📄 File	🔗 Preview link
docs/ai/conceptual/vector-databases.md	Vector databases for .NET AI apps
docs/ai/how-to/use-vector-stores.md	Use vector stores in .NET AI apps
docs/ai/toc.yml	docs/ai/toc

…how-to, new TOC section Co-authored-by: gewarren <24882762+gewarren@users.noreply.github.com>

gewarren · 2026-02-24T01:49:26Z

@copilot I added learn.microsoft.com to your allow list. Can you try to access the docs you need to port over to this repo?

…ybrid search, record definitions, more connectors Co-authored-by: gewarren <24882762+gewarren@users.noreply.github.com>

Copilot · 2026-02-24T01:59:03Z

@copilot I added learn.microsoft.com to your allow list. Can you try to access the docs you need to port over to this repo?

Accessed the SK vector store docs at learn.microsoft.com and ported relevant content. Commit fe8c80cc adds:

Attribute parameter tables for [VectorStoreKey], [VectorStoreData], and [VectorStoreVector] (including IndexKind, StorageName, etc.)
Automatic embedding generation — how to use a string-typed vector property with a configured IEmbeddingGenerator so the store generates embeddings automatically
Programmatic schema definition using VectorStoreCollectionDefinition as an alternative to attributes
VectorSearchOptions reference table covering Filter, VectorProperty, Skip, and IncludeVectors
Multi-vector targeting — using VectorProperty when a data model has multiple vector properties
Hybrid search — IKeywordHybridSearchable<TRecord> and HybridSearchAsync with a note about full-text indexing requirements
Expanded connector table — added Couchbase and Oracle, reordered alphabetically, added maintainer note

All code samples compile and run against the real Microsoft.Extensions.VectorData.Abstractions 9.7.0 / Microsoft.SemanticKernel.Connectors.InMemory 1.55.0-preview packages.

gewarren · 2026-02-24T02:21:20Z

docs/ai/conceptual/vector-databases.md

+# Vector databases for .NET AI apps

-Vector databases are designed to store and manage vector [embeddings](embeddings.md). Embeddings are numeric representations of non-numeric data that preserve semantic meaning. Words, documents, images, audio, and other types of data can all be vectorized. You can use embeddings to help an AI model understand the meaning of inputs so that it can perform comparisons and transformations, such as summarizing text, finding contextually related data, or creating images from text descriptions.
+Vector databases store and manage vector [embeddings](embeddings.md)—numeric representations of data that preserve semantic meaning. Words, documents, images, audio, and other types of data can all be vectorized. You can use embeddings to help an AI model understand the meaning of inputs so that it can perform comparisons and transformations, such as summarizing text, finding contextually related data, or creating images from text descriptions.


Suggested change

Vector databases store and manage vector [embeddings](embeddings.md)—numeric representations of data that preserve semantic meaning. Words, documents, images, audio, and other types of data can all be vectorized. You can use embeddings to help an AI model understand the meaning of inputs so that it can perform comparisons and transformations, such as summarizing text, finding contextually related data, or creating images from text descriptions.

Vector databases store and manage vector [*embeddings*](embeddings.md). Embeddings are numeric representations of data that preserve semantic meaning. Words, documents, images, audio, and other types of data can all be vectorized. You can use embeddings to help an AI model understand the meaning of inputs so that it can perform comparisons and transformations, such as summarizing text, finding contextually related data, or creating images from text descriptions.

Done in 1ddb6a13.

gewarren · 2026-02-24T02:23:40Z

docs/ai/conceptual/vector-databases.md

+}
+```
+
+You can configure the `IEmbeddingGenerator` at the vector store level, collection level, or on individual vector properties. With auto-embedding, you can also pass a `string` directly to `SearchAsync` instead of a precomputed vector—the store generates the search embedding for you. For more information, see [Use built-in embedding generation](../how-to/use-vector-stores.md#use-built-in-embedding-generation).


Suggested change

You can configure the `IEmbeddingGenerator` at the vector store level, collection level, or on individual vector properties. With auto-embedding, you can also pass a `string` directly to `SearchAsync` instead of a precomputed vector—the store generates the search embedding for you. For more information, see [Use built-in embedding generation](../how-to/use-vector-stores.md#use-built-in-embedding-generation).

You can configure the `IEmbeddingGenerator` at the vector store or collection level, or on individual vector properties. With auto-embedding, you can also pass a `string` directly to `SearchAsync` instead of a precomputed vector—the store generates the search embedding for you. For more information, see [Use built-in embedding generation](../how-to/use-vector-stores.md#use-built-in-embedding-generation).

Done in 1ddb6a13.

gewarren · 2026-02-24T02:25:30Z

docs/ai/how-to/snippets/use-vector-stores/csharp/VectorStoresExamples/.gitignore

Please remove this file.

Removed in 1ddb6a13.

docs/ai/toc.yml

gewarren · 2026-02-24T02:27:02Z

docs/ai/how-to/use-vector-stores.md

+description: Learn how to use Microsoft.Extensions.VectorData to store, search, and manage embeddings in vector databases for .NET AI applications.
+ms.topic: how-to
+ms.date: 02/24/2026
+ai-usage: ai-assisted


Suggested change

ai-usage: ai-assisted

ai-usage: ai-generated

Updated to ai-usage: ai-generated in 1ddb6a13.

gewarren · 2026-02-24T02:30:01Z

docs/ai/how-to/use-vector-stores.md

+
+| Parameter | Required | Description |
+|---|---|---|
+| `StorageName` | No | An alternative name for the property in storage. Not supported by all connectors. |


Please add xref links to the attribute parameters, for example, xref:Microsoft.Extensions.VectorData.VectorStoreKeyAttribute.StorageName.

Updated all three heading to use xref links: <xref:Microsoft.Extensions.VectorData.VectorStoreKeyAttribute>, <xref:Microsoft.Extensions.VectorData.VectorStoreDataAttribute>, and <xref:Microsoft.Extensions.VectorData.VectorStoreVectorAttribute> in 1ddb6a13.

@copilot I didn't mean update the headings. I meant update the parameters in the tables to use xref links.

Done in ab4c26a4. All parameter names in the three tables now use xref links (e.g., <xref:Microsoft.Extensions.VectorData.VectorStoreDataAttribute.IsIndexed>).

Done in ab4c26a4. All parameter names in the three attribute parameter tables now use xref links.

gewarren · 2026-02-24T02:30:32Z

docs/ai/how-to/use-vector-stores.md

+
+## Get a collection
+
+Call `GetCollection<TKey, TRecord>` on the vector store to get a typed reference to a collection. Then call `EnsureCollectionExistsAsync` to create the collection if it doesn't already exist:


Add xref links wherever possible.

Added xref links throughout the how-to guide in 1ddb6a13: VectorStore, VectorStoreCollection\2, EnsureCollectionExistsAsync, SearchAsync, VectorSearchResult`1, IKeywordHybridSearchable`1, DeleteAsync, and EnsureCollectionDeletedAsync`.

gewarren · 2026-02-25T23:59:25Z

@copilot please respond to all feedback

…tignore, fix TOC duplicate, update intro sentence Co-authored-by: gewarren <24882762+gewarren@users.noreply.github.com>

Copilot · 2026-02-26T00:03:56Z

@copilot please respond to all feedback

All feedback addressed in 1ddb6a13:

Updated intro sentence (split into two, [*embeddings*] link style)
Fixed "vector store level, collection level, or" phrasing
Removed .gitignore from snippets folder
Removed duplicate TOC entry
Changed ai-usage to ai-generated
Added xref links to all attribute parameter headings and to VectorStore, VectorStoreCollection, SearchAsync, VectorSearchResult, IKeywordHybridSearchable, DeleteAsync, and EnsureCollectionDeletedAsync

gewarren

@copilot Please respond to feedback

gewarren · 2026-02-26T00:12:50Z

docs/ai/how-to/use-vector-stores.md

+
+| Parameter | Required | Description |
+|---|---|---|
+| `StorageName` | No | An alternative name for the property in storage. Not supported by all connectors. |


@copilot I didn't mean update the headings. I meant update the parameters in the tables to use xref links.

gewarren · 2026-02-26T00:13:18Z

docs/ai/how-to/use-vector-stores.md

+
+## Upsert records
+
+Use `UpsertAsync` to insert or update records in the collection. If a record with the same key already exists, it gets updated:


Use an xref for UpsertAsync.

Done in ab4c26a4. Changed to <xref:Microsoft.Extensions.VectorData.VectorStoreCollection\2.UpsertAsync*>`.

gewarren · 2026-02-26T00:13:32Z

docs/ai/how-to/use-vector-stores.md

+
+## Get records
+
+Use `GetAsync` to retrieve a single record by its key. To retrieve multiple records, pass an `IEnumerable<TKey>` to `GetAsync`:


Use an xref for GetAsync.

Done in ab4c26a4. Changed to <xref:Microsoft.Extensions.VectorData.VectorStoreCollection\2.GetAsync*>`.

gewarren · 2026-02-26T00:13:56Z

docs/ai/how-to/use-vector-stores.md

+
+## Control search behavior with VectorSearchOptions
+
+Use `VectorSearchOptions<TRecord>` to control various aspects of vector search behavior:


Use an xref for VectorSearchOptions<TRecord>

Done in ab4c26a4. Changed to <xref:Microsoft.Extensions.VectorData.VectorSearchOptions\1>`.

gewarren · 2026-02-26T00:15:09Z

docs/ai/how-to/use-vector-stores.md

+
+## Get a collection
+
+Call `GetCollection<TKey, TRecord>` on the <xref:Microsoft.Extensions.VectorData.VectorStore> to get a typed <xref:Microsoft.Extensions.VectorData.VectorStoreCollection`2> reference. Then call <xref:Microsoft.Extensions.VectorData.VectorStoreCollection`2.EnsureCollectionExistsAsync*> to create the collection if it doesn't already exist:


Use an xref for GetCollection<>().

Done in ab4c26a4. Changed to <xref:Microsoft.Extensions.VectorData.VectorStore.GetCollection*>.

…rtAsync, GetAsync, VectorSearchOptions Co-authored-by: gewarren <24882762+gewarren@users.noreply.github.com>

Copilot · 2026-02-26T00:17:43Z

@copilot Please respond to feedback

All feedback addressed in ab4c26a4: xref links added to attribute parameter names in tables, GetCollection, UpsertAsync, GetAsync, and VectorSearchOptions.

docs/ai/how-to/use-vector-stores.md

Copilot

Pull request overview

This PR significantly expands the vector database documentation for .NET AI applications by adding comprehensive coverage of the Microsoft.Extensions.VectorData library. The changes transform a brief conceptual overview into detailed documentation with working code examples, covering both conceptual understanding and practical implementation.

Changes:

Expanded the vector databases conceptual article with detailed coverage of the Microsoft.Extensions.VectorData library, including API examples, data modeling patterns, and a complete list of available connectors
Created a new how-to guide for using vector stores with step-by-step instructions for common operations like upserting, searching, and filtering
Added a complete, compilable C# snippet project with working code examples demonstrating all major features

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
docs/ai/toc.yml	Reorganized TOC to create a new "Vector stores" top-level section containing both the conceptual overview and how-to guide
docs/ai/conceptual/vector-databases.md	Expanded from a brief overview to comprehensive conceptual documentation covering MEVD library features, data models, search patterns, and available connectors
docs/ai/how-to/use-vector-stores.md	New how-to guide with detailed step-by-step instructions for all vector store operations including CRUD, search, filtering, and hybrid search
docs/ai/how-to/snippets/use-vector-stores/csharp/VectorStoresExamples/VectorStoresExamples.csproj	Project file targeting net10.0 with required vector store dependencies
docs/ai/how-to/snippets/use-vector-stores/csharp/VectorStoresExamples/Hotel.cs	Data model example demonstrating vector store attributes
docs/ai/how-to/snippets/use-vector-stores/csharp/VectorStoresExamples/Program.cs	Main demonstration code with snippets for all basic operations
docs/ai/how-to/snippets/use-vector-stores/csharp/VectorStoresExamples/RecordDefinition.cs	Example of programmatic schema definition without attributes
docs/ai/how-to/snippets/use-vector-stores/csharp/VectorStoresExamples/AutoEmbedding.cs	Example of automatic embedding generation feature

roji · 2026-02-26T08:59:05Z

@gewarren great to see this! Just want to make sure you're aware of the vector store section in the Semantic Kernel docs (the entire section, not just that page). These are pretty high-quality docs that will go away as part of this effort, with their contents merged into the .NET docs you're working on. At least some of this content can simply be moved as-is, others can at least be a source for Copilot.

Let me know your thoughts... BTW I'm nearing the end of my coding work on MEVD, and am definitely happy to be involved in the docs side of things, as a reviewer or anything else that might be helpful.

BillWagner

This looks great @gewarren

I had a few questions on the code to consider.

BillWagner · 2026-02-26T15:26:23Z

docs/ai/conceptual/vector-databases.md

+The `Microsoft.Extensions.VectorData.Abstractions` library exposes the following main abstract classes:
+
+- <xref:Microsoft.Extensions.VectorData.VectorStore>: The top-level class for a vector database. Use it to retrieve and manage collections.
+- <xref:Microsoft.Extensions.VectorData.VectorStoreCollection`2>: Represents a named collection of records within a vector store. Use it to perform CRUD and search operations. Also inherits from `IVectorSearchable<TRecord>`.


technical nit:

Suggested change

- <xref:Microsoft.Extensions.VectorData.VectorStoreCollection`2>: Represents a named collection of records within a vector store. Use it to perform CRUD and search operations. Also inherits from `IVectorSearchable<TRecord>`.

- <xref:Microsoft.Extensions.VectorData.VectorStoreCollection`2>: Represents a named collection of records within a vector store. Use it to perform CRUD and search operations. It implements `IVectorSearchable<TRecord>`.

BillWagner · 2026-02-26T15:29:49Z

docs/ai/how-to/snippets/use-vector-stores/csharp/VectorStoresExamples/AutoEmbedding.cs

+// <AutoEmbeddingDataModel>
+// When the vector property type is string (not ReadOnlyMemory<float>),
+// the vector store automatically generates embeddings using the configured IEmbeddingGenerator.
+public class FinanceInfo


This looks like it could / should be a record?

Suggested change

public class FinanceInfo

public record class FinanceInfo

BillWagner · 2026-02-26T15:31:04Z

docs/ai/how-to/snippets/use-vector-stores/csharp/VectorStoresExamples/AutoEmbedding.cs

+    public string Text { get; set; } = "";
+
+    // The string value placed here before upsert is automatically converted to a vector.
+    [VectorStoreVector(1536)]
+    public string EmbeddingSource { get; set; } = "";


In both cases, required might be better than the empty string initialization:

Suggested change

public string Text { get; set; } = "";

// The string value placed here before upsert is automatically converted to a vector.

[VectorStoreVector(1536)]

public string EmbeddingSource { get; set; } = "";

public required string Text { get; set; } = "";

// The string value placed here before upsert is automatically converted to a vector.

[VectorStoreVector(1536)]

public required string EmbeddingSource { get; set; } = "";

BillWagner · 2026-02-26T15:31:48Z

docs/ai/how-to/snippets/use-vector-stores/csharp/VectorStoresExamples/Hotel.cs

+// <DataModel>
+using Microsoft.Extensions.VectorData;
+
+public class Hotel


same comment here on record:

Suggested change

public class Hotel

public record class Hotel

BillWagner · 2026-02-26T15:32:33Z

docs/ai/how-to/snippets/use-vector-stores/csharp/VectorStoresExamples/Program.cs

+await collection.UpsertAsync(hotels[0]);
+await collection.UpsertAsync(hotels[1]);
+await collection.UpsertAsync(hotels[2]);


Could be a loop, I guess?

BillWagner · 2026-02-26T15:33:50Z

docs/ai/how-to/snippets/use-vector-stores/csharp/VectorStoresExamples/Program.cs

+IAsyncEnumerable<Hotel> hotelBatch = collection.GetAsync([1, 2, 3]);
+await foreach (Hotel h in hotelBatch)
+{
+    Console.WriteLine($"Batch hotel: {h.HotelName}");
+}


Curious: GetAsync returns a nullable. This is a non-nullable enumeration. Is that correct? If so, could the returned enumerable have less than 3 items?

Initial plan

ffd718c

Copilot AI assigned Copilot and gewarren Feb 24, 2026

Copilot started work on behalf of gewarren February 24, 2026 01:20 View session

Beef up MEVD docs: expand vector-databases.md, add use-vector-stores …

424793f

…how-to, new TOC section Co-authored-by: gewarren <24882762+gewarren@users.noreply.github.com>

Copilot AI changed the title ~~[WIP] Port and enhance MEVD documentation from Microsoft Learn~~ Beef up MEVD docs: expanded conceptual article, new how-to guide, and working code snippets Feb 24, 2026

Copilot AI requested a review from gewarren February 24, 2026 01:33

Copilot finished work on behalf of gewarren February 24, 2026 01:33

Copilot started work on behalf of gewarren February 24, 2026 01:49 View session

Port SK vector store docs: attribute params tables, auto-embedding, h…

fe8c80c

…ybrid search, record definitions, more connectors Co-authored-by: gewarren <24882762+gewarren@users.noreply.github.com>

Copilot finished work on behalf of gewarren February 24, 2026 01:59

gewarren reviewed Feb 24, 2026

View reviewed changes

Copilot started work on behalf of gewarren February 25, 2026 23:59 View session

Address review feedback: xref links, ai-usage frontmatter, remove .gi…

1ddb6a1

…tignore, fix TOC duplicate, update intro sentence Co-authored-by: gewarren <24882762+gewarren@users.noreply.github.com>

Copilot AI requested a review from gewarren February 26, 2026 00:04

Copilot finished work on behalf of gewarren February 26, 2026 00:04

gewarren reviewed Feb 26, 2026

View reviewed changes

Copilot started work on behalf of gewarren February 26, 2026 00:15 View session

Add xref links to attribute parameters in tables, GetCollection, Upse…

ab4c26a

…rtAsync, GetAsync, VectorSearchOptions Co-authored-by: gewarren <24882762+gewarren@users.noreply.github.com>

Copilot AI requested a review from gewarren February 26, 2026 00:17

Copilot finished work on behalf of gewarren February 26, 2026 00:17

gewarren approved these changes Feb 26, 2026

View reviewed changes

docs/ai/how-to/use-vector-stores.md Outdated Show resolved Hide resolved

docs/ai/how-to/use-vector-stores.md Outdated Show resolved Hide resolved

docs/ai/how-to/use-vector-stores.md Outdated Show resolved Hide resolved

Apply suggestions from code review

21b049a

gewarren marked this pull request as ready for review February 26, 2026 00:21

gewarren requested a review from a team as a code owner February 26, 2026 00:21

Copilot AI review requested due to automatic review settings February 26, 2026 00:21

Copilot started reviewing on behalf of gewarren February 26, 2026 00:22 View session

Copilot AI reviewed Feb 26, 2026

View reviewed changes

BillWagner approved these changes Feb 26, 2026

View reviewed changes

gewarren marked this pull request as draft February 26, 2026 16:33


		## Get a collection

		Call `GetCollection<TKey, TRecord>` on the vector store to get a typed reference to a collection. Then call `EnsureCollectionExistsAsync` to create the collection if it doesn't already exist:


		## Upsert records

		Use `UpsertAsync` to insert or update records in the collection. If a record with the same key already exists, it gets updated:


		## Get records

		Use `GetAsync` to retrieve a single record by its key. To retrieve multiple records, pass an `IEnumerable<TKey>` to `GetAsync`:


		## Control search behavior with VectorSearchOptions

		Use `VectorSearchOptions<TRecord>` to control various aspects of vector search behavior:

	- <xref:Microsoft.Extensions.VectorData.VectorStoreCollection`2>: Represents a named collection of records within a vector store. Use it to perform CRUD and search operations. Also inherits from `IVectorSearchable<TRecord>`.
	- <xref:Microsoft.Extensions.VectorData.VectorStoreCollection`2>: Represents a named collection of records within a vector store. Use it to perform CRUD and search operations. It implements `IVectorSearchable<TRecord>`.

Conversation

Copilot AI commented Feb 24, 2026 • edited by github-actions bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Comments on the Issue (you are @copilot in this section)

Internal previews

Uh oh!

gewarren commented Feb 24, 2026

Uh oh!

Copilot AI commented Feb 24, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 26, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 26, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 26, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 26, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 26, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 26, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 26, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 26, 2026

Choose a reason for hiding this comment

Uh oh!

gewarren commented Feb 25, 2026

Uh oh!

Copilot AI commented Feb 26, 2026

Uh oh!

gewarren left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 26, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 26, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 26, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 26, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI commented Feb 26, 2026

Uh oh!

Copilot AI commented Feb 24, 2026 •

edited by github-actions bot

Loading