Document SQL Server vector search and JSON data type (#5082)

Closes #5081
Closes #4818

Author: roji

entity-framework/core/providers/sql-server/columns.md

@@ -11,11 +11,7 @@ This page details column configuration options that are specific to the SQL Serv
 
 ## Unicode and UTF-8
 
-SQL Server 2019 introduced [introduced UTF-8](/sql/relational-databases/collations/collation-and-unicode-support#utf8) support, which allows storing UTF-8 data in `char` and `varchar` columns by configuring them with special UTF-8 collations.
-
-### [EF Core 7.0](#tab/ef-core-7)
-
-EF Core 7.0 includes first-class support for UTF-8 columns. To configure them, simply configure the column's type to `char` or `varchar`, specify a UTF-8 collation (ending with `_UTF8`), and specify that the column should be Unicode:
+SQL Server 2019 introduced [introduced UTF-8](/sql/relational-databases/collations/collation-and-unicode-support#utf8) support, which allows storing UTF-8 data in `char` and `varchar` columns by configuring them with special UTF-8 collations. You can use UTF-8 columns with EF simply by configuring the column's type to `char` or `varchar`, specify a UTF-8 collation (ending with `_UTF8`), and specifying that the column should be Unicode:
 
 ```c#
 protected override void OnModelCreating(ModelBuilder modelBuilder)
@@ -28,25 +24,6 @@ protected override void OnModelCreating(ModelBuilder modelBuilder)
 }
 ```
 
-#### [Older versions](#tab/older-versions)
-
-In EF Core versions prior to 7.0, UTF-8 columns do not work out-of-the-box with EF Core's SQL Server provider. To map a string property to a `varchar(x)` column, the Fluent or Data Annotation API is typically used to disable Unicode ([see these docs](xref:core/modeling/entity-properties#unicode)). While this causes the correct column type to be created in the database, it also makes EF Core send database parameters in a way which is incompatible with UTF-8 data: `DbType.AnsiString` is used (signifying non-Unicode data), but `DbType.String` is needed to properly send Unicode data.
-
-As a result, you'll have to configure the EF property as a regular `nvarchar` column, ensuring that parameters are sent with the correct `DbType`:
-
-```c#
-protected override void OnModelCreating(ModelBuilder modelBuilder)
-{
-    modelBuilder.Entity<Blog>()
-        .Property(b => b.Name)
-        .UseCollation("LATIN1_GENERAL_100_CI_AS_SC_UTF8");
-}
-```
-
-Once you've created the migration for the column, edit it and manually change the column's type from `nvarchar` to `varchar`.
-
-***
-
 ## Sparse columns
 
 Sparse columns are ordinary columns that have an optimized storage for null values, reducing the space requirements for null values at the cost of more overhead to retrieve non-null values.

entity-framework/core/providers/sql-server/functions.md

@@ -13,25 +13,25 @@ This page shows which .NET members are translated into which SQL functions when
 
 .NET                                                                    | SQL                              | Added in
 ----------------------------------------------------------------------- | -------------------------------- | --------
-EF.Functions.StandardDeviationSample(group.Select(x => x.Property))     | STDEV(Property)                  | EF Core 7.0
-EF.Functions.StandardDeviationPopulation(group.Select(x => x.Property)) | STDEVP(Property)                 | EF Core 7.0
-EF.Functions.VarianceSample(group.Select(x => x.Property))              | VAR(Property)                    | EF Core 7.0
-EF.Functions.VariancePopulation(group.Select(x => x.Property))          | VARP(Property)                   | EF Core 7.0
+EF.Functions.StandardDeviationSample(group.Select(x => x.Property))     | STDEV(Property)
+EF.Functions.StandardDeviationPopulation(group.Select(x => x.Property)) | STDEVP(Property)
+EF.Functions.VarianceSample(group.Select(x => x.Property))              | VAR(Property)
+EF.Functions.VariancePopulation(group.Select(x => x.Property))          | VARP(Property)
 group.Average(x => x.Property)                                          | AVG(Property)
 group.Count()                                                           | COUNT(*)
 group.LongCount()                                                       | COUNT_BIG(*)
 group.Max(x => x.Property)                                              | MAX(Property)
 group.Min(x => x.Property)                                              | MIN(Property)
 group.Sum(x => x.Property)                                              | SUM(Property)
-string.Concat(group.Select(x => x.Property))                            | STRING_AGG(Property, N'')        | EF Core 7.0
-string.Join(separator, group.Select(x => x.Property))                   | STRING_AGG(Property, @separator) | EF Core 7.0
+string.Concat(group.Select(x => x.Property))                            | STRING_AGG(Property, N'')
+string.Join(separator, group.Select(x => x.Property))                   | STRING_AGG(Property, @separator)
 
 ## Binary functions
 
 .NET                         | SQL                           | Added in
 ---------------------------- | ----------------------------- | --------
 bytes.Contains(value)        | CHARINDEX(@value, @bytes) > 0
-bytes.ElementAt(i)           | SUBSTRING(@bytes, @i + 1, 1)  | EF Core 8.0
+bytes.ElementAt(i)           | SUBSTRING(@bytes, @i + 1, 1)
 bytes.First()                | SUBSTRING(@bytes, 1, 1)
 bytes.Length                 | DATALENGTH(@bytes)
 bytes.SequenceEqual(second)  | @bytes = @second
@@ -53,7 +53,7 @@ Convert.ToInt16(value)    | CONVERT(smallint, @value)
 Convert.ToInt32(value)    | CONVERT(int, @value)
 Convert.ToInt64(value)    | CONVERT(bigint, @value)
 Convert.ToString(value)   | CONVERT(nvarchar(max), @value)
-dateOnly.ToString()       | CONVERT(varchar(100), @dateOnly)       | EF Core 8.0
+dateOnly.ToString()       | CONVERT(varchar(100), @dateOnly)
 dateTime.ToString()       | CONVERT(varchar(100), @dateTime)
 dateTimeOffset.ToString() | CONVERT(varchar(100), @dateTimeOffset)
 decimalValue.ToString()   | CONVERT(varchar(100), @decimalValue)
@@ -64,7 +64,7 @@ intValue.ToString()       | CONVERT(varchar(11), @intValue)
 longValue.ToString()      | CONVERT(varchar(20), @longValue)
 sbyteValue.ToString()     | CONVERT(varchar(4), @sbyteValue)
 shortValue.ToString()     | CONVERT(varchar(6), @shortValue)
-timeOnly.ToString()       | CONVERT(varchar(100), @timeOnly)       | EF Core 8.0
+timeOnly.ToString()       | CONVERT(varchar(100), @timeOnly)
 timeSpan.ToString()       | CONVERT(varchar(100), @timeSpan)
 uintValue.ToString()      | CONVERT(varchar(10), @uintValue)
 ulongValue.ToString()     | CONVERT(varchar(19), @ulongValue)
@@ -116,19 +116,19 @@ dateTimeOffset.Month                                        | DATEPART(month, @d
 dateTimeOffset.Nanosecond                                   | DATEPART(nanosecond, @dateTimeOffset) % 1000                                    | EF Core 10.0
 dateTimeOffset.Second                                       | DATEPART(second, @dateTimeOffset)
 dateTimeOffset.TimeOfDay                                    | CONVERT(time, @dateTimeOffset)
-dateTimeOffset.ToUnixTimeSeconds()                          | DATEDIFF_BIG(second, '1970-01-01T00:00:00.0000000+00:00', @dateTimeOffset)      | EF Core 8.0
-dateTimeOffset.ToUnixTimeMilliseconds()                     | DATEDIFF_BIG(millisecond, '1970-01-01T00:00:00.0000000+00:00', @dateTimeOffset) | EF Core 8.0
+dateTimeOffset.ToUnixTimeSeconds()                          | DATEDIFF_BIG(second, '1970-01-01T00:00:00.0000000+00:00', @dateTimeOffset)
+dateTimeOffset.ToUnixTimeMilliseconds()                     | DATEDIFF_BIG(millisecond, '1970-01-01T00:00:00.0000000+00:00', @dateTimeOffset)
 dateTimeOffset.Year                                         | DATEPART(year, @dateTimeOffset)
-DateOnly.FromDateTime(dateTime)                             | CONVERT(date, @dateTime)                                                        | EF Core 8.0
-dateOnly.AddDays(value)                                     | DATEADD(day, @value, @dateOnly)                                                 | EF Core 8.0
-dateOnly.AddMonths(months)                                  | DATEADD(month, @months, @dateOnly)                                              | EF Core 8.0
-dateOnly.AddYears(value)                                    | DATEADD(year, @value, @dateOnly)                                                | EF Core 8.0
-dateOnly.Day                                                | DATEPART(day, @dateOnly)                                                        | EF Core 8.0
-dateOnly.DayOfYear                                          | DATEPART(dayofyear, @dateOnly)                                                  | EF Core 8.0
-dateOnly.Month                                              | DATEPART(month, @dateOnly)                                                      | EF Core 8.0
-dateOnly.Year                                               | DATEPART(year, @dateOnly)                                                       | EF Core 8.0
+DateOnly.FromDateTime(dateTime)                             | CONVERT(date, @dateTime)
+dateOnly.AddDays(value)                                     | DATEADD(day, @value, @dateOnly)
+dateOnly.AddMonths(months)                                  | DATEADD(month, @months, @dateOnly)
+dateOnly.AddYears(value)                                    | DATEADD(year, @value, @dateOnly)
+dateOnly.Day                                                | DATEPART(day, @dateOnly)
+dateOnly.DayOfYear                                          | DATEPART(dayofyear, @dateOnly)
+dateOnly.Month                                              | DATEPART(month, @dateOnly)
+dateOnly.Year                                               | DATEPART(year, @dateOnly)
 dateOnly.DayNumber                                          | DATEDIFF(day, '0001-01-01', @dateOnly)                                          | EF Core 10.0
-EF.Functions.AtTimeZone(dateTime, timeZone)                 | @dateTime AT TIME ZONE @timeZone                                                | EF Core 7.0
+EF.Functions.AtTimeZone(dateTime, timeZone)                 | @dateTime AT TIME ZONE @timeZone
 EF.Functions.DateDiffDay(start, end)                        | DATEDIFF(day, @start, @end)
 EF.Functions.DateDiffHour(start, end)                       | DATEDIFF(hour, @start, @end)
 EF.Functions.DateDiffMicrosecond(start, end)                | DATEDIFF(microsecond, @start, @end)
@@ -146,15 +146,15 @@ EF.Functions.DateTimeOffsetFromParts(year, month, day, ...) | DATETIMEOFFSETFROM
 EF.Functions.IsDate(expression)                             | ISDATE(@expression)
 EF.Functions.SmallDateTimeFromParts(year, month, day, ...)  | SMALLDATETIMEFROMPARTS(@year, @month, @day, ...)
 EF.Functions.TimeFromParts(hour, minute, second, ...)       | TIMEFROMPARTS(@hour, @minute, @second, ...)
-timeOnly.AddHours(value)                                    | DATEADD(hour, @value, @timeOnly)                                                | EF Core 8.0
-timeOnly.AddMinutes(value)                                  | DATEADD(minute, @value, @timeOnly)                                              | EF Core 8.0
-timeOnly.Hour                                               | DATEPART(hour, @timeOnly)                                                       | EF Core 8.0
-timeOnly.IsBetween(start, end)                              | @timeOnly >= @start AND @timeOnly < @end                                        | EF Core 8.0
+timeOnly.AddHours(value)                                    | DATEADD(hour, @value, @timeOnly)
+timeOnly.AddMinutes(value)                                  | DATEADD(minute, @value, @timeOnly)
+timeOnly.Hour                                               | DATEPART(hour, @timeOnly)
+timeOnly.IsBetween(start, end)                              | @timeOnly >= @start AND @timeOnly < @end
 timeOnly.Microsecond                                        | DATEPART(microsecond, @timeOnly) % 1000                                         | EF Core 10.0
-timeOnly.Millisecond                                        | DATEPART(millisecond, @timeOnly)                                                | EF Core 8.0
-timeOnly.Minute                                             | DATEPART(minute, @timeOnly)                                                     | EF Core 8.0
+timeOnly.Millisecond                                        | DATEPART(millisecond, @timeOnly)
+timeOnly.Minute                                             | DATEPART(minute, @timeOnly)
 timeOnly.Nanosecond                                         | DATEPART(nanosecond, @timeOnly) % 1000                                          | EF Core 10.0
-timeOnly.Second                                             | DATEPART(second, @timeOnly)                                                     | EF Core 8.0
+timeOnly.Second                                             | DATEPART(second, @timeOnly)
 timeSpan.Hours                                              | DATEPART(hour, @timeSpan)
 timeSpan.Microsecond                                        | DATEPART(microsecond, @timeSpan) % 1000                                         | EF Core 10.0
 timeSpan.Milliseconds                                       | DATEPART(millisecond, @timeSpan)
@@ -166,8 +166,8 @@ timeSpan.Seconds                                            | DATEPART(second, @
 
 .NET                       | SQL                  | Added in
 -------------------------- | -------------------- | --------
-double.DegreesToRadians(x) | RADIANS(@x)          | EF Core 8.0
-double.RadiansToDegrees(x) | DEGREES(@x)          | EF Core 8.0
+double.DegreesToRadians(x) | RADIANS(@x)
+double.RadiansToDegrees(x) | DEGREES(@x)
 EF.Functions.Random()      | RAND()
 Math.Abs(value)            | ABS(@value)
 Math.Acos(d)               | ACOS(@d)
@@ -219,7 +219,7 @@ stringValue.Contains(value)                                             | @strin
 stringValue.EndsWith(value)                                             | @stringValue LIKE N'%' + @value
 stringValue.FirstOrDefault()                                            | SUBSTRING(@stringValue, 1, 1)
 stringValue.IndexOf(value)                                              | CHARINDEX(@value, @stringValue) - 1
-stringValue.IndexOf(value, startIndex)                                  | CHARINDEX(@value, @stringValue, @startIndex) - 1                       | EF Core 7.0
+stringValue.IndexOf(value, startIndex)                                  | CHARINDEX(@value, @stringValue, @startIndex) - 1
 stringValue.LastOrDefault()                                             | SUBSTRING(@stringValue, LEN(@stringValue), 1)
 stringValue.Length                                                      | LEN(@stringValue)
 stringValue.Replace(@oldValue, @newValue)                               | REPLACE(@stringValue, @oldValue, @newValue)
@@ -242,9 +242,10 @@ nullable.GetValueOrDefault()             | COALESCE(@nullable, 0)
 nullable.GetValueOrDefault(defaultValue) | COALESCE(@nullable, @defaultValue)
 
 > [!NOTE]
-> Some SQL has been simplified for illustration purposes. The actual SQL is more complex to handle a wider range of values.
+> Some SQL translations have been simplified for illustration purposes. The actual SQL is more complex to handle a wider range of values.
 
 ## See also
 
+* [Vector Search Function Mappings](xref:core/providers/sql-server/vector-search)
 * [Spatial Function Mappings](xref:core/providers/sql-server/spatial#spatial-function-mappings)
 * [HierarchyId Function Mappings](xref:core/providers/sql-server/hierarchyid#function-mappings)

entity-framework/core/providers/sql-server/vector-search.md

@@ -0,0 +1,80 @@
+---
+title: Microsoft SQL Server Database Provider - Vector Search - EF Core
+description: Using vectors and embeddings to perform similarity search with the Entity Framework Core Microsoft SQL Server database provider
+author: roji
+ms.date: 08/17/2025
+uid: core/providers/sql-server/vector-and-full-text-search
+---
+# Vector search in the SQL Server EF Core Provider
+
+## Vector search
+
+> [!NOTE]
+> Vector support was introduced in EF Core 10.0, and is only supported with SQL Server 2025 and above.
+
+The SQL Server vector data type allows storing *embeddings*, which are representation of meaning that can be efficiently searched over for similarity, powering AI workloads such as semantic search and retrieval-augmented generation (RAG).
+
+To use the `vector` data type, simply add a .NET property of type `SqlVector<float>` to your entity type, specifying the dimensions as follows:
+
+### [Data Annotations](#tab/data-annotations)
+
+```c#
+public class Blog
+{
+    // ...
+
+    [Column(TypeName = "vector(1536)")]
+    public SqlVector<float> Embedding { get; set; }
+}
+```
+
+### [Fluent API](#tab/fluent-api)
+
+```c#
+public class Blog
+{
+    // ...
+
+    public SqlVector<float> Embedding { get; set; }
+}
+
+protected override void OnModelCreating(ModelBuilder modelBuilder)
+{
+    modelBuilder.Entity<Blog>()
+        .Property(b => b.Embedding)
+        .HasColumnType("vector(1536)");
+}
+```
+
+***
+
+Once your property is added and the corresponding column created in the database, you can start inserting embeddings. Embedding generation is done outside of the database, usually via a service, and the details for doing this are out of scope for this documentation. However, [the .NET Microsoft.Extensions.AI libraries](/dotnet/ai/microsoft-extensions-ai) contains [`IEmbeddingGenerator`](/dotnet/ai/microsoft-extensions-ai#create-embeddings), which is an abstraction over embedding generators that has implementations for the major providers.
+
+Once you've chosen your embedding generator and set it up, use it to generate embeddings and insert them as follows
+
+```c#
+IEmbeddingGenerator<string, Embedding<float>> embeddingGenerator = /* Set up your preferred embedding generator */;
+
+var embedding = await embeddingGenerator.GenerateVectorAsync("Some text to be vectorized");
+context.Blogs.Add(new Blog
+{
+    Name = "Some blog",
+    Embedding = new SqlVector<float>(embedding)
+});
+await context.SaveChangesAsync();
+```
+
+Finally, use the [`EF.Functions.VectorDistance()`](/sql/t-sql/functions/vector-distance-transact-sql) function to perform similarity search for a given user query:
+
+```c#
+var sqlVector = new SqlVector<float>(await embeddingGenerator.GenerateVectorAsync("Some user query to be vectorized"));
+var topSimilarBlogs = context.Blogs
+    .OrderBy(b => EF.Functions.VectorDistance("cosine", b.Embedding, sqlVector))
+    .Take(3)
+    .ToListAsync();
+```
+
+> [!NOTE]
+> The built-in support in EF 10 replaces the previous [EFCore.SqlServer.VectorSearch](https://github.com/efcore/EFCore.SqlServer.VectorSearch) extension, which allowed performing vector search before the `vector` data type was introduced. As part of upgrading to EF 10, remove the extension from your projects.
+>
+> The [`VECTOR_SEARCH()`](/sql/t-sql/functions/vector-search-transact-sql) function (in preview) for approximate search with DiskANN is currently unsupported.