Implement support for SQL Server vector indexes

Closes #37281

Author: roji

src/EFCore.SqlServer/Extensions/SqlServerEntityTypeBuilderExtensions.cs

@@ -1,6 +1,8 @@
 // Licensed to the .NET Foundation under one or more agreements.
 // The .NET Foundation licenses this file to you under the MIT license.
 
+using System.Diagnostics.CodeAnalysis;
+using Microsoft.EntityFrameworkCore.Metadata.Builders;
 using Microsoft.EntityFrameworkCore.SqlServer.Metadata.Internal;
 
 // ReSharper disable once CheckNamespace
@@ -291,6 +293,111 @@ public static bool CanSetIsTemporal(
         bool fromDataAnnotation = false)
         => entityTypeBuilder.CanSetAnnotation(SqlServerAnnotationNames.IsTemporal, temporal, fromDataAnnotation);
 
+    /// <summary>
+    ///     Configures a vector index on the specified property for SQL Server.
+    /// </summary>
+    /// <remarks>
+    ///     See <see href="https://aka.ms/efcore-docs-modeling">Modeling entity types and relationships</see>, and
+    ///     <see href="https://aka.ms/efcore-docs-sqlserver">Accessing SQL Server and Azure SQL databases with EF Core</see>
+    ///     for more information and examples.
+    /// </remarks>
+    /// <typeparam name="TEntity">The entity type being configured.</typeparam>
+    /// <param name="entityTypeBuilder">The builder for the entity type being configured.</param>
+    /// <param name="indexExpression">
+    ///     A lambda expression representing the property to create the vector index on
+    ///     (<c>blog => blog.Vector</c>).
+    /// </param>
+    /// <param name="metric">
+    ///     <para>
+    ///         A string with the name of the distance metric to use to calculate the distance between the two given vectors.
+    ///         The following distance metrics are supported:
+    ///     </para>
+    ///     <list type="bullet">
+    ///         <item>
+    ///             <term>cosine</term>
+    ///             <description>Cosine distance</description>
+    ///         </item>
+    ///         <item>
+    ///             <term>euclidean</term>
+    ///             <description>Euclidean distance</description>
+    ///         </item>
+    ///         <item>
+    ///             <term>dot</term>
+    ///             <description>(Negative) Dot product</description>
+    ///         </item>
+    ///     </list>
+    /// </param>
+    /// <param name="name">The name to assign to the index.</param>
+    /// <returns>A builder to further configure the vector index.</returns>
+    [Experimental(EFDiagnostics.SqlServerVectorSearch)]
+    public static VectorIndexBuilder<TEntity> HasVectorIndex<TEntity>(
+        this EntityTypeBuilder<TEntity> entityTypeBuilder,
+        Expression<Func<TEntity, object?>> indexExpression,
+        string metric,
+        string? name = null)
+        where TEntity : class
+    {
+        Check.NotNull(indexExpression);
+        Check.NotEmpty(metric);
+
+        var indexBuilder = name is null
+            ? entityTypeBuilder.HasIndex(indexExpression)
+            : entityTypeBuilder.HasIndex(indexExpression, name);
+        indexBuilder.Metadata.SetVectorMetric(metric);
+
+        return new VectorIndexBuilder<TEntity>(indexBuilder);
+    }
+
+    /// <summary>
+    ///     Configures a vector index on the specified property for SQL Server.
+    /// </summary>
+    /// <remarks>
+    ///     See <see href="https://aka.ms/efcore-docs-modeling">Modeling entity types and relationships</see>, and
+    ///     <see href="https://aka.ms/efcore-docs-sqlserver">Accessing SQL Server and Azure SQL databases with EF Core</see>
+    ///     for more information and examples.
+    /// </remarks>
+    /// <param name="entityTypeBuilder">The builder for the entity type being configured.</param>
+    /// <param name="propertyName">The name of the property to create the vector index on.</param>
+    /// <param name="metric">
+    ///     <para>
+    ///         A string with the name of the distance metric to use to calculate the distance between the two given vectors.
+    ///         The following distance metrics are supported:
+    ///     </para>
+    ///     <list type="bullet">
+    ///         <item>
+    ///             <term>cosine</term>
+    ///             <description>Cosine distance</description>
+    ///         </item>
+    ///         <item>
+    ///             <term>euclidean</term>
+    ///             <description>Euclidean distance</description>
+    ///         </item>
+    ///         <item>
+    ///             <term>dot</term>
+    ///             <description>(Negative) Dot product</description>
+    ///         </item>
+    ///     </list>
+    /// </param>
+    /// <param name="name">The name to assign to the index.</param>
+    /// <returns>A builder to further configure the vector index.</returns>
+    [Experimental(EFDiagnostics.SqlServerVectorSearch)]
+    public static VectorIndexBuilder HasVectorIndex(
+        this EntityTypeBuilder entityTypeBuilder,
+        string propertyName,
+        string metric,
+        string? name = null)
+    {
+        Check.NotEmpty(propertyName);
+        Check.NotEmpty(metric);
+
+        var indexBuilder = name is null
+            ? entityTypeBuilder.HasIndex(propertyName)
+            : entityTypeBuilder.HasIndex(propertyName, name);
+        indexBuilder.Metadata.SetVectorMetric(metric);
+
+        return new VectorIndexBuilder(indexBuilder);
+    }
+
     /// <summary>
     ///     Configures a history table name for the entity mapped to a temporal table.
     /// </summary>

src/EFCore.SqlServer/Extensions/SqlServerIndexExtensions.cs

@@ -1,6 +1,7 @@
 // Licensed to the .NET Foundation under one or more agreements.
 // The .NET Foundation licenses this file to you under the MIT license.
 
+using System.Diagnostics.CodeAnalysis;
 using Microsoft.EntityFrameworkCore.SqlServer.Metadata.Internal;
 
 // ReSharper disable once CheckNamespace
@@ -431,4 +432,155 @@ public static void SetDataCompression(this IMutableIndex index, DataCompressionT
     /// <returns>The <see cref="ConfigurationSource" /> for the data compression the index uses.</returns>
     public static ConfigurationSource? GetDataCompressionConfigurationSource(this IConventionIndex index)
         => index.FindAnnotation(SqlServerAnnotationNames.DataCompression)?.GetConfigurationSource();
+
+    /// <summary>
+    ///     Returns whether the index is a vector index.
+    /// </summary>
+    /// <param name="index">The index.</param>
+    /// <returns>Whether the index is a vector index.</returns>
+    [Experimental(EFDiagnostics.SqlServerVectorSearch)]
+    public static bool IsVectorIndex(this IReadOnlyIndex index)
+        => index is RuntimeIndex
+            ? throw new InvalidOperationException(CoreStrings.RuntimeModelMissingData)
+            : index[SqlServerAnnotationNames.VectorIndexMetric] is not null;
+
+    /// <summary>
+    ///     Returns the similarity metric for the vector index.
+    /// </summary>
+    /// <param name="index">The index.</param>
+    /// <returns>The similarity metric for the vector index.</returns>
+    [Experimental(EFDiagnostics.SqlServerVectorSearch)]
+    public static string? GetVectorMetric(this IReadOnlyIndex index)
+        => index is RuntimeIndex
+            ? throw new InvalidOperationException(CoreStrings.RuntimeModelMissingData)
+            : (string?)index[SqlServerAnnotationNames.VectorIndexMetric];
+
+    /// <summary>
+    ///     Returns the similarity metric for the vector index.
+    /// </summary>
+    /// <param name="index">The index.</param>
+    /// <param name="storeObject">The identifier of the store object.</param>
+    /// <returns>The similarity metric for the vector index.</returns>
+    [Experimental(EFDiagnostics.SqlServerVectorSearch)]
+    public static string? GetVectorMetric(this IReadOnlyIndex index, in StoreObjectIdentifier storeObject)
+    {
+        if (index is RuntimeIndex)
+        {
+            throw new InvalidOperationException(CoreStrings.RuntimeModelMissingData);
+        }
+
+        var annotation = index.FindAnnotation(SqlServerAnnotationNames.VectorIndexMetric);
+        if (annotation != null)
+        {
+            return (string?)annotation.Value;
+        }
+
+        var sharedTableRootIndex = index.FindSharedObjectRootIndex(storeObject);
+        return sharedTableRootIndex?.GetVectorMetric(storeObject);
+    }
+
+    /// <summary>
+    ///     Sets the similarity metric for the vector index.
+    /// </summary>
+    /// <param name="index">The index.</param>
+    /// <param name="metric">The value to set.</param>
+    [Experimental(EFDiagnostics.SqlServerVectorSearch)]
+    public static void SetVectorMetric(this IMutableIndex index, string? metric)
+        => index.SetAnnotation(SqlServerAnnotationNames.VectorIndexMetric, metric);
+
+    /// <summary>
+    ///     Sets the similarity metric for the vector index.
+    /// </summary>
+    /// <param name="index">The index.</param>
+    /// <param name="metric">The value to set.</param>
+    /// <param name="fromDataAnnotation">Indicates whether the configuration was specified using a data annotation.</param>
+    /// <returns>The configured value.</returns>
+    [Experimental(EFDiagnostics.SqlServerVectorSearch)]
+    public static string? SetVectorMetric(
+        this IConventionIndex index,
+        string? metric,
+        bool fromDataAnnotation = false)
+        => (string?)index.SetAnnotation(
+            SqlServerAnnotationNames.VectorIndexMetric,
+            metric,
+            fromDataAnnotation)?.Value;
+
+    /// <summary>
+    ///     Returns the <see cref="ConfigurationSource" /> for the similarity metric of the vector index.
+    /// </summary>
+    /// <param name="index">The index.</param>
+    /// <returns>The <see cref="ConfigurationSource" /> for the similarity metric of the vector index.</returns>
+    [Experimental(EFDiagnostics.SqlServerVectorSearch)]
+    public static ConfigurationSource? GetVectorMetricConfigurationSource(this IConventionIndex index)
+        => index.FindAnnotation(SqlServerAnnotationNames.VectorIndexMetric)?.GetConfigurationSource();
+
+    /// <summary>
+    ///     Returns the type of the vector index.
+    /// </summary>
+    /// <param name="index">The index.</param>
+    /// <returns>The type of the vector index.</returns>
+    [Experimental(EFDiagnostics.SqlServerVectorSearch)]
+    public static string? GetVectorIndexType(this IReadOnlyIndex index)
+        => (index is RuntimeIndex)
+            ? throw new InvalidOperationException(CoreStrings.RuntimeModelMissingData)
+            : (string?)index[SqlServerAnnotationNames.VectorIndexType];
+
+    /// <summary>
+    ///     Returns the type of the vector index.
+    /// </summary>
+    /// <param name="index">The index.</param>
+    /// <param name="storeObject">The identifier of the store object.</param>
+    /// <returns>The type of the vector index.</returns>
+    [Experimental(EFDiagnostics.SqlServerVectorSearch)]
+    public static string? GetVectorIndexType(this IReadOnlyIndex index, in StoreObjectIdentifier storeObject)
+    {
+        if (index is RuntimeIndex)
+        {
+            throw new InvalidOperationException(CoreStrings.RuntimeModelMissingData);
+        }
+
+        var annotation = index.FindAnnotation(SqlServerAnnotationNames.VectorIndexType);
+        if (annotation != null)
+        {
+            return (string?)annotation.Value;
+        }
+
+        var sharedTableRootIndex = index.FindSharedObjectRootIndex(storeObject);
+        return sharedTableRootIndex?.GetVectorIndexType(storeObject);
+    }
+
+    /// <summary>
+    ///     Sets the type of the vector index.
+    /// </summary>
+    /// <param name="index">The index.</param>
+    /// <param name="type">The value to set.</param>
+    [Experimental(EFDiagnostics.SqlServerVectorSearch)]
+    public static void SetVectorIndexType(this IMutableIndex index, string? type)
+        => index.SetAnnotation(SqlServerAnnotationNames.VectorIndexType, type);
+
+    /// <summary>
+    ///     Sets the type of the vector index.
+    /// </summary>
+    /// <param name="index">The index.</param>
+    /// <param name="type">The value to set.</param>
+    /// <param name="fromDataAnnotation">Indicates whether the configuration was specified using a data annotation.</param>
+    /// <returns>The configured value.</returns>
+    [Experimental(EFDiagnostics.SqlServerVectorSearch)]
+    public static string? SetVectorIndexType(
+        this IConventionIndex index,
+        string? type,
+        bool fromDataAnnotation = false)
+        => (string?)index.SetAnnotation(
+            SqlServerAnnotationNames.VectorIndexType,
+            type,
+            fromDataAnnotation)?.Value;
+
+    /// <summary>
+    ///     Returns the <see cref="ConfigurationSource" /> for the type of the vector index.
+    /// </summary>
+    /// <param name="index">The index.</param>
+    /// <returns>The <see cref="ConfigurationSource" /> for the type of the vector index.</returns>
+    [Experimental(EFDiagnostics.SqlServerVectorSearch)]
+    public static ConfigurationSource? GetVectorIndexTypeConfigurationSource(this IConventionIndex index)
+        => index.FindAnnotation(SqlServerAnnotationNames.VectorIndexType)?.GetConfigurationSource();
 }

src/EFCore.SqlServer/Infrastructure/Internal/SqlServerModelValidator.cs

@@ -41,6 +41,7 @@ public SqlServerModelValidator(
     public override void Validate(IModel model, IDiagnosticsLogger<DbLoggerCategory.Model.Validation> logger)
     {
         ValidateIndexIncludeProperties(model, logger);
+        ValidateVectorIndexes(model, logger);
 
         base.Validate(model, logger);
 
@@ -267,6 +268,44 @@ protected virtual void ValidateIndexIncludeProperties(
         }
     }
 
+    /// <summary>
+    ///     This is an internal API that supports the Entity Framework Core infrastructure and not subject to
+    ///     the same compatibility standards as public APIs. It may be changed or removed without notice in
+    ///     any release. You should only use it directly in your code with extreme caution and knowing that
+    ///     doing so can result in application failures when updating to a new Entity Framework Core release.
+    /// </summary>
+#pragma warning disable EF9105 // Vector indexes are experimental
+    protected virtual void ValidateVectorIndexes(
+        IModel model,
+        IDiagnosticsLogger<DbLoggerCategory.Model.Validation> logger)
+    {
+        foreach (var index in model.GetEntityTypes().SelectMany(t => t.GetDeclaredIndexes()))
+        {
+            if (index.IsVectorIndex())
+            {
+                if (index.Properties is not [var property])
+                {
+                    throw new InvalidOperationException(
+                        SqlServerStrings.VectorIndexRequiresSingleProperty(
+                            index.DisplayName(),
+                            index.DeclaringEntityType.DisplayName()));
+                }
+
+                var typeMapping = property.FindTypeMapping();
+
+                if (typeMapping is not SqlServerVectorTypeMapping)
+                {
+                    throw new InvalidOperationException(
+                        SqlServerStrings.VectorIndexOnNonVectorProperty(
+                            index.DisplayName(),
+                            index.DeclaringEntityType.DisplayName(),
+                            property.Name));
+                }
+            }
+        }
+    }
+#pragma warning restore EF9105
+
     /// <summary>
     ///     This is an internal API that supports the Entity Framework Core infrastructure and not subject to
     ///     the same compatibility standards as public APIs. It may be changed or removed without notice in