Documentation for JSON and Vector datatype support in SqlClient (#35789)

David-Engel · apoorvdeshmukh · web-flow · commit df4580e45a72 · 2025-11-07T14:07:43.000-07:00
* Commit initial draft for JSON and Vector documentation

* Fetch samples from sqlclient repo

* Remove hardcoded links

* Update docs/connect/ado-net/configure-parameters.md

Co-authored-by: David Engel &lt;dengel1012@gmail.com&gt;

* Update docs/connect/ado-net/sql/vector-data-sql-server.md

Co-authored-by: David Engel &lt;dengel1012@gmail.com&gt;

* Update docs/connect/ado-net/configure-parameters.md

Co-authored-by: David Engel &lt;dengel1012@gmail.com&gt;

* Update docs/connect/ado-net/sql/json-data-sql-server.md

Co-authored-by: David Engel &lt;dengel1012@gmail.com&gt;

* Address review comments

* Acrolinx improvements

Applied Acrolinx suggestions to increase the score above 80.

* Apply fix suggestions

* Escape back tick

---------

Co-authored-by: Apoorv Deshmukh &lt;apdeshmukh@microsoft.com&gt;
diff --git a/docs/connect/ado-net/configure-parameters.md b/docs/connect/ado-net/configure-parameters.md
@@ -72,11 +72,22 @@ The Microsoft SqlClient Data Provider for SQL Server type of a `Parameter` objec
 ||`StringFixedLength`|`NChar`|
 ||`Time`|`Time` in SQL Server 2008. Inferring a <xref:System.Data.SqlDbType> from `Time` isn't supported in versions of SQL Server earlier than SQL Server 2008.|
 ||`VarNumeric`|Inferring a <xref:System.Data.SqlDbType> from `VarNumeric` isn't supported.|
-|user-defined type (an object with <xref:Microsoft.SqlServer.Server.SqlUserDefinedAggregateAttribute>|SqlClient always returns an Object|`SqlDbType.Udt` if <xref:Microsoft.SqlServer.Server.SqlUserDefinedTypeAttribute> is present, otherwise `Variant`|
+|user-defined type (an object with <xref:Microsoft.SqlServer.Server.SqlUserDefinedAggregateAttribute>)|SqlClient always returns an Object|`SqlDbType.Udt` if <xref:Microsoft.SqlServer.Server.SqlUserDefinedTypeAttribute> is present, otherwise `Variant`|
+|<xref:Microsoft.Data.SqlTypes.SqlJson>|`String`|`SqlDbType.Json`|
+|<xref:Microsoft.Data.SqlTypes.SqlVector%601>|`Binary`|`SqlDbType.Vector`|
 
 > [!NOTE]
 > Conversions from decimal to other types are narrowing conversions that round the decimal value to the nearest integer value toward zero. If the result of the conversion isn't representable in the destination type, an <xref:System.OverflowException> is thrown.
 
+> [!NOTE]
+> **JSON**
+>
+> Set SqlDbType to Json when passing a parameter `Value` of type `string`. Otherwise SqlDbType defaults to `Nvarchar`.
+>
+> **Vector**
+>
+> For SQL vector datatype, a parameter `Value` of type `Microsoft.Data.SqlTypes.SqlVector<T>` must be specified. Parameter `Size` and vector dimension are inferred from the parameter `Value`. The parameter `Size` is ignored.
+
 > [!NOTE]
 > When you send a null parameter value to the server, you must specify <xref:System.DBNull>, not `null` (`Nothing` in Visual Basic). The null value in the system is an empty object that has no value. <xref:System.DBNull> is used to represent null values.
 
diff --git a/docs/connect/ado-net/sql-server-data-type-mappings.md b/docs/connect/ado-net/sql-server-data-type-mappings.md
@@ -53,6 +53,8 @@ The following table shows the inferred .NET Framework type, the <xref:System.Dat
 |varbinary|Byte[]|<xref:System.Data.SqlDbType.VarBinary>|<xref:Microsoft.Data.SqlClient.SqlDataReader.GetSqlBinary%2A>|<xref:System.Data.DbType.Binary>|<xref:Microsoft.Data.SqlClient.SqlDataReader.GetBytes%2A>|  
 |varchar|String<br /><br /> Char[]|<xref:System.Data.SqlDbType.VarChar>|<xref:Microsoft.Data.SqlClient.SqlDataReader.GetSqlString%2A>|<xref:System.Data.DbType.AnsiString>, <xref:System.Data.DbType.String>|<xref:Microsoft.Data.SqlClient.SqlDataReader.GetString%2A><br /><br /> <xref:Microsoft.Data.SqlClient.SqlDataReader.GetChars%2A>|  
 |xml|Xml|<xref:System.Data.SqlDbType.Xml>|<xref:Microsoft.Data.SqlClient.SqlDataReader.GetSqlXml%2A>|<xref:System.Data.DbType.Xml>|none|
+|json|String|<xref:System.Data.SqlDbType.Json>|<xref:Microsoft.Data.SqlClient.SqlDataReader.GetSqlJson%2A>|none|none|
+|vector|none|<xref:System.Data.SqlDbType.Vector>|<xref:Microsoft.Data.SqlClient.SqlDataReader.GetSqlVector%2A>|none|none|
 
 <sup>1</sup> You cannot set the `DbType` property of a `SqlParameter` to `SqlDbType.Date`.  
 <sup>2</sup> Use a specific typed accessor if you know the underlying type of the `sql_variant`.
diff --git a/docs/connect/ado-net/sql/json-data-sql-server.md b/docs/connect/ado-net/sql/json-data-sql-server.md
@@ -0,0 +1,39 @@
+---
+title: "JSON data type support in SqlClient"
+description: "Describes how to work with JSON data retrieved from SQL Server."
+author: apoorvdeshmukh
+ms.author: apdeshmukh
+ms.reviewer: 
+ms.date: 10/31/2025
+ms.service: sql
+ms.subservice: connectivity
+ms.topic: conceptual
+---
+# JSON datatype support in SqlClient
+
+[!INCLUDE[Driver_ADONET_Download](../../../includes/driver_adonet_download.md)]
+
+A native [JSON data type](../../../t-sql/data-types/json-data-type.md) is introduced in SQL Server 2025 and Azure SQL databases. This native JSON data type is available for structured JSON documents with automatic validation, efficient transport, and efficient storage.
+
+The Microsoft.Data.SqlClient provider offers built-in support for JSON columns through:
+- The common language runtime (CLR) `string` type for simple scenarios.
+- `SqlJson` type for advanced use cases, such as client-side validation and explicit handling of JSON semantics.
+- .NET 9 introduces a new SqlDbType.Json enumeration value for specifying JSON parameters. For earlier .NET versions, use `Microsoft.Data.SqlDbTypeExtensions`, which provides forward-compatible support for new SQL types.
+- .NET 9 introduces a new `SqlDbType.Json` enumeration value for specifying JSON parameters.
+- For earlier .NET versions, `Microsoft.Data.SqlDbTypeExtensions` is introduced as an alternative for `SqlDbType`.
+
+## Example
+
+The following example demonstrates the following scenarios to interact with JSON data.
+
+- Insert a JSON value using CLR type `string`.
+- Insert the JSON value using `SqlJson`. Using `SqlJson` is useful if you want to validate the JSON data before sending it to server.
+- Insert a JSON file by streaming.
+- Read JSON values using `SqlDataReader`.
+- Use stored procedure parameters for JSON data.
+
+[!code-csharp[SqlJsonExample#1](~/../sqlclient/doc/samples/SqlJsonExample.cs#1)]
+  
+## Next steps
+
+- [SQL Server and ADO.NET](index.md)
diff --git a/docs/connect/ado-net/sql/vector-data-sql-server.md b/docs/connect/ado-net/sql/vector-data-sql-server.md
@@ -0,0 +1,42 @@
+---
+title: "Vector datatype support in SqlClient"
+description: "Describes how to work with vector datatype for SQL Server using SqlClient."
+author: apoorvdeshmukh
+ms.author: apdeshmukh
+ms.reviewer: 
+ms.date: 10/31/2025
+ms.service: sql
+ms.subservice: connectivity
+ms.topic: conceptual
+---
+# Vector datatype support in SqlClient
+
+[!INCLUDE[Driver_ADONET_Download](../../../includes/driver_adonet_download.md)]
+
+SQL Server 2025 and Azure SQL Database introduce a native [Vector data type](../../../t-sql/data-types/vector-data-type.md) for storing fixed-dimension numeric embeddings with automatic validation and efficient binary storage. For backward compatibility, vectors are exposed as JSON arrays. Each element is float32 by default, and dimensions must range from 1 to 1998.
+
+In .NET, the `Microsoft.Data.SqlClient` provider adds native vector handling through the <xref:Microsoft.Data.SqlTypes.SqlVector`1> class (for example, `SqlVector<float>`), using optimized binary transport over the Tabular Data Stream (TDS) protocol. Older clients can still pass vectors as JSON strings transparently.
+
+The vector type enables similarity search and AI-driven scenarios, with server-side vector functions for efficient computation.
+
+In SqlClient, `vector` data is exchanged with SQL Server using the <xref:Microsoft.Data.SqlTypes.SqlVector`1> class.
+
+In newer .NET versions starting with version 10, a new `SqlDbType` enumeration value `Vector` is available for representing SQL parameters of type `vector`.
+
+For earlier versions, use `Microsoft.Data.SqlDbTypeExtensions` to declare SQL parameters of type `vector`.
+
+## Example
+
+The following code sample demonstrates the following scenarios for a vector column of three dimensions.
+
+- Insert non-null vectors using SqlParameter.
+- Insert null vectors for a given vector column.
+- Read a vector column.
+- Use a stored procedure with a vector datatype parameter.
+- Perform a bulk copy operation with vector data.
+
+[!code-csharp[SqlVectorExample#1](~/../sqlclient/doc/samples/SqlVectorExample.cs#1)]
+
+## Next steps
+
+- [SQL Server and ADO.NET](index.md)
diff --git a/docs/connect/ado-net/sqlclient-streaming-support.md b/docs/connect/ado-net/sqlclient-streaming-support.md
@@ -1,9 +1,9 @@
 ---
 title: "SqlClient streaming support"
-description: Discusses how to write applications that stream data from SQL Server without having it fully loaded in memory.
+description: Describes how to write applications that stream large data from SQL Server without loading it all in memory.
 author: David-Engel
 ms.author: davidengel
-ms.reviewer: v-chmalh
+ms.reviewer: cmalhotra
 ms.date: "12/04/2020"
 ms.service: sql
 ms.subservice: connectivity
@@ -15,14 +15,14 @@ ms.topic: conceptual
 
 [!INCLUDE[Driver_ADONET_Download](../../includes/driver_adonet_download.md)]
 
-Streaming support between SQL Server and an application supports unstructured data on the server (documents, images, and media files). A SQL Server database can store binary large objects (BLOBs), but retrieving BLOBS can use a lot of memory.
+Streaming support between SQL Server and an application supports unstructured data on the server (documents, images, and media files). A SQL Server database can store binary large objects (BLOBs), but retrieving BLOBS can use a large amount of memory.
 
 Streaming support to and from SQL Server simplifies writing applications that stream data, without having to fully load the data into memory, resulting in fewer memory overflow exceptions.
 
-Streaming support will also enable middle-tier applications to scale better, especially in scenarios where business objects connect to Azure SQL in order to send, retrieve, and manipulate large BLOBs.
+Streaming support also enables middle-tier applications to scale better, especially in scenarios where business objects connect to Azure SQL in order to send, retrieve, and manipulate large BLOBs.
 
 > [!WARNING]
-> The members that support streaming are used to retrieve data from queries and to pass parameters to queries and stored procedures. The streaming feature addresses basic OLTP and data migration scenarios and is applicable to on-premises and off-premises data migrations environments.
+> The members that support streaming are used to retrieve data from queries and to pass parameters to queries and stored procedures. The streaming feature addresses basic Online Transaction Processing (OLTP) and data migration scenarios and is applicable to on-premises and off-premises data migrations environments.
 
 ## Streaming support from SQL Server
 
@@ -55,31 +55,33 @@ The following members were added to <xref:System.Data.Common.DbDataReader> to en
 Streaming support to SQL Server is in the <xref:Microsoft.Data.SqlClient.SqlParameter> class so it can accept and react to <xref:System.Xml.XmlReader>, <xref:System.IO.Stream>, and <xref:System.IO.TextReader> objects. <xref:Microsoft.Data.SqlClient.SqlParameter> is used to pass parameters to queries and stored procedures.
 
 > [!NOTE]
-> Disposing a <xref:Microsoft.Data.SqlClient.SqlCommand> object or calling <xref:Microsoft.Data.SqlClient.SqlCommand.Cancel%2A> must cancel any streaming operation. If an application sends <xref:System.Threading.CancellationToken>, cancellation is not guaranteed.
+> Disposing a <xref:Microsoft.Data.SqlClient.SqlCommand> object or calling <xref:Microsoft.Data.SqlClient.SqlCommand.Cancel%2A> must cancel any streaming operation. If an application sends <xref:System.Threading.CancellationToken>, cancellation isn't guaranteed.
 
-The following <xref:Microsoft.Data.SqlClient.SqlParameter.SqlDbType%2A> types will accept a <xref:Microsoft.Data.SqlClient.SqlParameter.Value%2A> of <xref:System.IO.Stream>:
+The following <xref:Microsoft.Data.SqlClient.SqlParameter.SqlDbType%2A> types accept a <xref:Microsoft.Data.SqlClient.SqlParameter.Value%2A> of <xref:System.IO.Stream>:
 
-- **Binary**
+- `Binary`
 
-- **VarBinary**
+- `VarBinary`
 
-The following <xref:Microsoft.Data.SqlClient.SqlParameter.SqlDbType%2A> types will accept a <xref:Microsoft.Data.SqlClient.SqlParameter.Value%2A> of <xref:System.IO.TextReader>:
+The following <xref:Microsoft.Data.SqlClient.SqlParameter.SqlDbType%2A> types accept a <xref:Microsoft.Data.SqlClient.SqlParameter.Value%2A> of <xref:System.IO.TextReader>:
 
-- **Char**
+- `Char`
 
-- **NChar**
+- `NChar`
 
-- **NVarChar**
+- `NVarChar`
 
-- **Xml**
+- `Xml`
 
-The **Xml**<xref:Microsoft.Data.SqlClient.SqlParameter.SqlDbType%2A> type will accept a <xref:Microsoft.Data.SqlClient.SqlParameter.Value%2A> of <xref:System.Xml.XmlReader>.
+- `Json`
+
+The **Xml** <xref:Microsoft.Data.SqlClient.SqlParameter.SqlDbType%2A> type accepts a <xref:Microsoft.Data.SqlClient.SqlParameter.Value%2A> of <xref:System.Xml.XmlReader>.
 
 <xref:Microsoft.Data.SqlClient.SqlParameter.SqlValue%2A> can accept values of type <xref:System.Xml.XmlReader>, <xref:System.IO.TextReader>, and <xref:System.IO.Stream>.
 
-The <xref:System.Xml.XmlReader>, <xref:System.IO.TextReader>, and <xref:System.IO.Stream> object will be transferred up to the value defined by the <xref:Microsoft.Data.SqlClient.SqlParameter.Size%2A>.
+The <xref:System.Xml.XmlReader>, <xref:System.IO.TextReader>, and <xref:System.IO.Stream> object is transferred up to the value defined by the <xref:Microsoft.Data.SqlClient.SqlParameter.Size%2A>.
 
-## Sample -- streaming from SQL Server
+## Sample--streaming from SQL Server
 
 Use the following Transact-SQL to create the sample database:
 
@@ -100,7 +102,7 @@ INSERT INTO [Streams] (textdata, bindata, xmldata) VALUES (N'Another row', 0x666
 GO
 ```
 
-The sample shows how to do the following:
+The sample shows how to do the following actions:
 
 - Avoid blocking a user-interface thread by providing an asynchronous way to retrieve large files.
 
@@ -114,7 +116,7 @@ The sample shows how to do the following:
 
 [!code-csharp[SqlClient_Streaming_FromServer#1](~/../sqlclient/doc/samples/SqlClient_Streaming_FromServer.cs#1)]
 
-## Sample -- streaming to SQL Server
+## Sample--streaming to SQL Server
 
 Use the following Transact-SQL to create the sample database:
 
@@ -137,23 +139,23 @@ CREATE TABLE [BinaryStreamsCopy] (
 GO
 ```
 
-The sample shows how to do the following:
+The sample shows how to do the following actions:
 
 - Transferring a large BLOB to SQL Server in .NET.
 
 - Transferring a large text file to SQL Server in .NET.
 
 - Using the new asynchronous feature to transfer a large BLOB.
 
-- Using the new asynchronous feature and the await keyword to transfer a large BLOB.
+- Using the new asynchronous feature and the `await` keyword to transfer a large BLOB.
 
 - Cancelling the transfer of a large BLOB.
 
 - Streaming from one SQL Server to another using the asynchronous feature.
 
 [!code-csharp[SqlClient_Streaming_ToServer#1](~/../sqlclient/doc/samples/SqlClient_Streaming_ToServer.cs#1)]
 
-## Sample -- Streaming from one SQL Server to another SQL Server
+## Sample--Streaming from one SQL Server to another SQL Server
 
 This sample demonstrates how to asynchronously stream a large BLOB from one SQL Server to another, with support for cancellation.
 
diff --git a/docs/connect/toc.yml b/docs/connect/toc.yml
@@ -210,6 +210,10 @@
           href: ../connect/ado-net/sql/sql-xml-column-values.md
         - name: Specifying XML values as parameters
           href: ../connect/ado-net/sql/specify-xml-values-parameters.md
+      - name: JSON data type support in SqlClient
+        href: ../connect/ado-net/sql/json-data-sql-server.md
+      - name: Vector datatype support in SqlClient
+        href: ../connect/ado-net/sql/vector-data-sql-server.md  
     - name: SQL Server binary and large-value data
       href: ../connect/ado-net/sql/sql-server-binary-large-value-data.md
       items:
