Implementation:Microsoft Semantic kernel VectorStore Attributes

Overview

This page documents the attribute-based data model pattern for defining vector store records in Microsoft Semantic Kernel. The three core attributes — [VectorStoreKey], [VectorStoreData], and [VectorStoreVector] — are applied to C# class properties to declaratively define the schema of records stored in a vector database.

Source Reference

File: dotnet/samples/GettingStartedWithVectorStores/Glossary.cs (lines 14-30)
Type: Pattern Doc

Complete Data Model Example

The following example defines a glossary record with a key, three data fields (one indexed), and one vector field:

internal sealed class Glossary
{
    [VectorStoreKey]
    public string Key { get; set; }

    [VectorStoreData(IsIndexed = true)]
    public string Category { get; set; }

    [VectorStoreData]
    public string Term { get; set; }

    [VectorStoreData]
    public string Definition { get; set; }

    [VectorStoreVector(Dimensions: 1536)]
    public ReadOnlyMemory<float> DefinitionEmbedding { get; set; }
}

Attribute Reference

`[VectorStoreKey]`

Aspect	Detail
Purpose	Designates the unique identifier property for the record
Cardinality	Exactly one per class (required)
Supported types	`string`, `int`, `long`, `Guid`
Parameters	None

Usage:

[VectorStoreKey]
public string Key { get; set; }

The key property serves as the primary identifier for upsert (create-or-update) and direct retrieval operations. Each record in a collection must have a unique key value.

`[VectorStoreData]`

Aspect	Detail
Purpose	Marks a property as a stored data field
Cardinality	Zero or more per class
Supported types	`string`, `int`, `float`, `double`, `bool`, `DateTime`, and other primitive types
Parameters	`IsIndexed` (optional, default `false`), `IsFullTextSearchable` (optional, default `false`)

Usage without indexing:

[VectorStoreData]
public string Term { get; set; }

[VectorStoreData]
public string Definition { get; set; }

Usage with indexing enabled:

[VectorStoreData(IsIndexed = true)]
public string Category { get; set; }

Setting IsIndexed = true signals to the vector store connector that this field should be indexed, making it available for metadata filtering during vector search. Only indexed fields can be used in filter expressions passed to SearchAsync.

`[VectorStoreVector(Dimensions)]`

Aspect	Detail
Purpose	Marks a property as a vector embedding field
Cardinality	One or more per class (at least one required for vector search)
Supported types	`ReadOnlyMemory<float>`, `ReadOnlyMemory<double>`
Required parameters	`Dimensions` — the number of dimensions in the embedding vector

Usage:

[VectorStoreVector(Dimensions: 1536)]
public ReadOnlyMemory<float> DefinitionEmbedding { get; set; }

The Dimensions value must match the output size of the embedding model. Common values:

Embedding Model	Dimensions
OpenAI `text-embedding-ada-002`	1536
OpenAI `text-embedding-3-small`	1536
OpenAI `text-embedding-3-large`	3072

Pattern: Multi-Field Data Model

A more elaborate data model might include multiple data fields with different indexing strategies:

internal sealed class Document
{
    [VectorStoreKey]
    public string Id { get; set; }

    [VectorStoreData(IsIndexed = true)]
    public string Source { get; set; }

    [VectorStoreData(IsIndexed = true)]
    public DateTime CreatedAt { get; set; }

    [VectorStoreData(IsFullTextSearchable = true)]
    public string Content { get; set; }

    [VectorStoreData]
    public string Summary { get; set; }

    [VectorStoreVector(Dimensions: 1536)]
    public ReadOnlyMemory<float> ContentEmbedding { get; set; }
}

Key decisions in this pattern:

Source and CreatedAt are indexed for equality and range filtering
Content is marked as full-text searchable for hybrid search scenarios
Summary is stored but not indexed — it is returned in results but cannot be filtered on
ContentEmbedding holds the 1536-dimensional vector for similarity search

Common Mistakes

Missing Key Attribute

Every data model class must have exactly one [VectorStoreKey] property. Omitting it will cause a runtime exception when the collection is created.

Dimension Mismatch

If Dimensions: 1536 is specified but the embedding model produces 3072-dimensional vectors, upsert operations will fail. Always verify the embedding model's output dimensions.

Filtering on Non-Indexed Fields

Attempting to filter on a [VectorStoreData] field that does not have IsIndexed = true will result in an error. Only indexed fields support metadata filtering.

Relationship to Principle

This implementation page corresponds to the Vector Store Data Model principle, which explains the motivation and design philosophy behind attribute-based schema definition.

Principle:Microsoft_Semantic_kernel_Vector_Store_Data_Model

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment