Rework/improve the vector store documentation#52874
Open
roji wants to merge 3 commits intodotnet:mainfrom
Open
Rework/improve the vector store documentation#52874roji wants to merge 3 commits intodotnet:mainfrom
roji wants to merge 3 commits intodotnet:mainfrom
Conversation
Contributor
There was a problem hiding this comment.
Pull request overview
Reworks the vector store documentation set by consolidating embedding generation and hybrid search guidance into existing articles, and adds a new CRUD-focused page requested in #52610.
Changes:
- Added a new Manage data article covering upsert, delete, and retrieval operations.
- Reworked Vector search to include filtering, paging options, vector selection, and hybrid search guidance (and removed standalone hybrid search and embedding generation pages/snippets).
- Updated navigation and cross-links to reflect the new doc structure.
Reviewed changes
Copilot reviewed 12 out of 12 changed files in this pull request and generated 13 comments.
Show a summary per file
| File | Description |
|---|---|
| docs/ai/vector-stores/vector-search.md | Expanded vector search article to include more scenarios, and added hybrid search section. |
| docs/ai/vector-stores/manage-data.md | New page documenting CRUD-style operations for vector store collections. |
| docs/ai/vector-stores/overview.md | Updated overview narrative and added a minimal end-to-end code sample. |
| docs/ai/vector-stores/define-your-data-model.md | Reorganized data model guidance and moved embedding-generation content into this article. |
| docs/ai/vector-stores/how-to/use-vector-stores.md | Updated links to point to the new/merged content. |
| docs/ai/conceptual/embeddings.md | Updated related-content link to the new embedding-generation section location. |
| docs/ai/toc.yml | Added Manage data entry and removed deleted pages from TOC. |
| docs/ai/vector-stores/snippets/conceptual/vector-search.cs | Removed (content moved inline into markdown). |
| docs/ai/vector-stores/snippets/conceptual/hybrid-search.cs | Removed (content moved inline into markdown). |
| docs/ai/vector-stores/snippets/conceptual/embedding-generation.cs | Removed (content moved into markdown). |
| docs/ai/vector-stores/hybrid-search.md | Removed (hybrid search content moved into vector-search.md). |
| docs/ai/vector-stores/embedding-generation.md | Removed (embedding content moved into define-your-data-model.md). |
gewarren
approved these changes
Apr 6, 2026
| ## Number of results and skipping results | ||
|
|
||
| ## Search with auto-generated embeddings | ||
| <xref:Microsoft.Extensions.VectorData.VectorStoreCollection`2.SearchAsync*> has a mandatory `top` parameter which controls the maximum number of records returned from the search; always consider how many top records you actually need, as overfetching can reduce application performance: |
Contributor
There was a problem hiding this comment.
Suggested change
| <xref:Microsoft.Extensions.VectorData.VectorStoreCollection`2.SearchAsync*> has a mandatory `top` parameter which controls the maximum number of records returned from the search; always consider how many top records you actually need, as overfetching can reduce application performance: | |
| <xref:Microsoft.Extensions.VectorData.VectorStoreCollection`2.SearchAsync*> has a mandatory `top` parameter that controls the maximum number of records returned from the search. Always consider how many top records you actually need, as overfetching can reduce application performance: |
| ``` | ||
|
|
||
| ## Supported vector types | ||
| `top` and `Skip` can be used to perform paging to retrieve a large number of results using separate calls. However, this technique may not perform very well on your database, as it must still find and process the skipped records. Consult your database documentation for more information. |
Contributor
There was a problem hiding this comment.
Suggested change
| `top` and `Skip` can be used to perform paging to retrieve a large number of results using separate calls. However, this technique may not perform very well on your database, as it must still find and process the skipped records. Consult your database documentation for more information. | |
| `top` and `Skip` can be used to perform paging to retrieve a large number of results using separate calls. However, this technique might not perform well on your database, as it must still find and process the skipped records. For more information, consult your database documentation. |
| ### Include vectors in results | ||
|
|
||
| The default value for `Skip` is 0. | ||
| By default, vector properties are not included in the search results, to reduce data transfer. You can configure the search to include them: |
Contributor
There was a problem hiding this comment.
Suggested change
| By default, vector properties are not included in the search results, to reduce data transfer. You can configure the search to include them: | |
| By default, vector properties aren't included in the search results, which reduces data transfer. You can configure the search to include them: |
| ``` | ||
|
|
||
| The <xref:Microsoft.Extensions.VectorData.VectorSearchOptions`1.IncludeVectors?displayProperty=nameWithType> option lets you specify whether you want to return vectors in the search results. If `false`, the vector properties on the returned model are left null. Using `false` can significantly reduce the amount of data retrieved from the vector store during search, making searches more efficient. | ||
| ## Specifying the vector property |
Contributor
There was a problem hiding this comment.
Suggested change
| ## Specifying the vector property | |
| ## Specify the vector property |
|
|
||
| > [!TIP] | ||
| > For more information on how to enable <xref:Microsoft.Extensions.VectorData.VectorStoreDataAttribute.IsIndexed>, see [VectorStoreDataAttribute](./define-your-data-model.md#vectorstoredataattribute) or [VectorStoreDataProperty](./define-your-data-model.md#vectorstoredataproperty). | ||
| All the options described above for vector search (`top`, `Skip`, `Filter`, `IncludeVectors`, `VectorProperty`) are also available for hybrid search via <xref:Microsoft.Extensions.VectorData.HybridSearchOptions`1>. |
Contributor
There was a problem hiding this comment.
Suggested change
| All the options described above for vector search (`top`, `Skip`, `Filter`, `IncludeVectors`, `VectorProperty`) are also available for hybrid search via <xref:Microsoft.Extensions.VectorData.HybridSearchOptions`1>. | |
| All the options described for vector search (`top`, `Skip`, `Filter`, `IncludeVectors`, `VectorProperty`) are also available for hybrid search via <xref:Microsoft.Extensions.VectorData.HybridSearchOptions`1>. |
| ## Dynamic mapping to a .NET Dictionary | ||
|
|
||
| There are cases where it isn't desirable or possible to define your own data model. For example, imagine that you don't know at compile time what your database schema looks like, and the schema is only provided via configuration. Creating a data model that reflects the schema would be impossible in this case. Instead, you can map *dynamically* by using a `Dictionary<string, object?>` for the record type. Properties are added to the `Dictionary` with key as the property name and the value as the property value. | ||
| There are cases where it isn't desirable or possible to map a strongly-typed .NET type to the database. For example, imagine that you don't know at compile time what your database schema looks like, and the schema is only provided via configuration. Creating a .NET type that reflects the schema would be impossible in this case. Instead, you can map *dynamically* by using a `Dictionary<string, object?>` for the record type. Properties are added to the `Dictionary` with key as the property name and the value as the property value. |
Contributor
There was a problem hiding this comment.
Suggested change
| There are cases where it isn't desirable or possible to map a strongly-typed .NET type to the database. For example, imagine that you don't know at compile time what your database schema looks like, and the schema is only provided via configuration. Creating a .NET type that reflects the schema would be impossible in this case. Instead, you can map *dynamically* by using a `Dictionary<string, object?>` for the record type. Properties are added to the `Dictionary` with key as the property name and the value as the property value. | |
| There are cases where it isn't desirable or possible to map a strongly typed .NET type to the database. For example, imagine that you don't know at compile time what your database schema looks like, and the schema is only provided via configuration. Creating a .NET type that reflects the schema would be impossible in this case. Instead, you can map *dynamically* by using a `Dictionary<string, object?>` for the record type. Properties are added to the `Dictionary` with key as the property name and the value as the property value. |
|
|
||
| # Manage data | ||
|
|
||
| Once you've [defined your data model](./define-your-data-model.md) and obtained a <xref:Microsoft.Extensions.VectorData.VectorStoreCollection`2>, you can manage records in your vector store collection. This page covers the core data management operations: upserting, deleting, and retrieving records. Searching your data using vector similarity is covered in the [next section](./vector-search.md). |
Contributor
There was a problem hiding this comment.
Suggested change
| Once you've [defined your data model](./define-your-data-model.md) and obtained a <xref:Microsoft.Extensions.VectorData.VectorStoreCollection`2>, you can manage records in your vector store collection. This page covers the core data management operations: upserting, deleting, and retrieving records. Searching your data using vector similarity is covered in the [next section](./vector-search.md). | |
| Once you've [defined your data model](./define-your-data-model.md) and obtained a <xref:Microsoft.Extensions.VectorData.VectorStoreCollection`2>, you can manage records in your vector store collection. This article covers the core data management operations: upserting, deleting, and retrieving records. Searching your data using vector similarity is covered in [Vector search](./vector-search.md). |
| Hotel? hotel = await collection.GetAsync(key: 1); | ||
| ``` | ||
|
|
||
| `GetAsync` returns the record if found, or `null` if no record with the given key exists: |
Contributor
There was a problem hiding this comment.
Suggested change
| `GetAsync` returns the record if found, or `null` if no record with the given key exists: | |
| `GetAsync` returns the record if found, or `null` if no record with the given key exists. |
|
|
||
| ### Include vectors in results | ||
|
|
||
| By default, vector properties are not included in the retrieved records, to reduce data transfer. To include them, pass a <xref:Microsoft.Extensions.VectorData.RecordRetrievalOptions> with <xref:Microsoft.Extensions.VectorData.RecordRetrievalOptions.IncludeVectors> set to `true`: |
Contributor
There was a problem hiding this comment.
Suggested change
| By default, vector properties are not included in the retrieved records, to reduce data transfer. To include them, pass a <xref:Microsoft.Extensions.VectorData.RecordRetrievalOptions> with <xref:Microsoft.Extensions.VectorData.RecordRetrievalOptions.IncludeVectors> set to `true`: | |
| By default, vector properties are not included in the retrieved records, which reduces data transfer. To include them, pass a <xref:Microsoft.Extensions.VectorData.RecordRetrievalOptions> with <xref:Microsoft.Extensions.VectorData.RecordRetrievalOptions.IncludeVectors> set to `true`: |
| Filters are expressed as LINQ expressions. The supported expressions vary depending on the database provider, but all providers support common comparisons such as equality, inequality, and logical `&&` and `||`. | ||
|
|
||
| > [!IMPORTANT] | ||
| > For properties to be usable in filters, many databases require them to be indexed; even where indexes aren't required, they can greatly increase the performance of filters. Set `IsIndexed = true` on the <xref:Microsoft.Extensions.VectorData.VectorStoreDataAttribute> when defining your data model to enable this. For more information, see [Data property](./define-your-data-model.md#data-property). |
Contributor
There was a problem hiding this comment.
Suggested change
| > For properties to be usable in filters, many databases require them to be indexed; even where indexes aren't required, they can greatly increase the performance of filters. Set `IsIndexed = true` on the <xref:Microsoft.Extensions.VectorData.VectorStoreDataAttribute> when defining your data model to enable this. For more information, see [Data property](./define-your-data-model.md#data-property). | |
| > For properties to be usable in filters, many databases require them to be indexed. Even where indexes aren't required, they can greatly increase the performance of filters. To index properties, set `IsIndexed = true` on the <xref:Microsoft.Extensions.VectorData.VectorStoreDataAttribute> when you define your data model. For more information, see [Data property](./define-your-data-model.md#data-property). |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Some work on the new vector store docs ported over from SK. I plan some more improvements but don't want to submit a single huge PR.
/cc @westey-m @gewarren
Closes #52610
Internal previews