Add vector(float16) support

[apoorvdeshmukh]

Adds support for the float16 base type of the vector data type, by advertising version 2 of the VECTORSUPPORT feature extension. A vector(N, float16) column is now exchanged in its native binary form rather than as a varchar(max) JSON string.

Opened as a draft: this is an integration branch. The five commits are independently buildable and can be split into separate PRs on request.

Representation

	.NET	.NET Framework
Default	SqlVector<Half>	string (JSON)
Typed read	GetSqlVector<Half> exact, or GetSqlVector<float> widened	GetSqlVector<float> widened
Write	SqlVector<Half>	SqlVector<float>, JSON string, or SqlBulkCopy

System.Half does not exist on .NET Framework, so a float16 column is reported as a string there, matching how it is already presented when the server does not negotiate float16 support. GetSqlVector<float> widens the elements, which is exact. .NET Framework decodes binary16 itself, as no BCL package supplies System.Half for net462; on .NET the same methods delegate to BitConverter.

SqlVector<T> keeps its shipped contract: T alone determines the base type written to the wire. Conversion between base types is left to the server, except for SqlBulkCopy, which states the destination's base type in the INSERT BULK statement and so must convert the payload itself.

Behaviour changes

• Reading a vector(N, float16) column no longer returns varchar(max). String read paths still work, but the text changes from the server's scientific notation ([1.0000000e+000,2.0000000e+000]) to a compact JSON array ([1,2]). Both parse to the same values. This is the same transition float32 columns made when vector support was added in 6.1, so the two base types now render identically.
• On .NET, GetFieldType, GetValue and the column type of a filled DataTable change from string to SqlVector<Half>; casting GetValue directly to string now throws InvalidCastException.
• SqlVector<T>.ToString() now returns the values as a JSON array rather than the type name, which also affects existing SqlVector<float> callers.
• float16 is server-side preview-gated (PREVIEW_FEATURES = ON), so applications which have not enabled it are unaffected.

Also included

Vector column metadata. A vector column's base type and dimension count are now available from the column schema as ["VectorBaseType"] and ["VectorDimensions"], via DbColumn's virtual indexer, so no new public API. This is a v1 gap affecting float32 today: the dimension count previously required hardcoding (ColumnSize - 8) / 4. The vector type is also registered in the DataTypes schema collection, where it was missing.

Bulk copy between vector columns now transfers the raw payload. It previously read the column through the representation the reader surfaces, which is a JSON string where System.Half is unavailable. That round trip is several times larger than the payload it encodes — a 1998-dimension float16 vector is about 4 KB as a payload and about 24 KB as text — and it silently dropped a negative zero, because System.Text.Json on .NET Framework serialises one as 0 and parses -0 back as positive zero. The decision is made once per column, alongside the existing decimal and streaming decisions.

Validation

Verified against SQL Server 18.0.258.0.

Suite	net9.0	net462
Vector manual tests	206/206	138/138
Bulk copy manual tests	456/456	—
Unit tests	1067/1067	1102/1102

The binary16 codec is validated bit-exactly against System.Half across all 65,536 patterns and a strided sweep of the single precision range. It is compiled on every framework so that the .NET Framework path is the one under test.

Every SqlBulkCopy source type was checked against a float16 destination on .NET Framework — SqlDataReader over both base types, DataTable, DataRow[], and a non-SqlClient DbDataReader — and all now preserve values exactly. A caller-supplied JSON string still normalises a negative zero, which matches what the server does when parsing a vector literal.

Existing Float16VectorTypeBackwardCompatibilityTests pass unchanged. CI has no float16-capable server, so those tests will skip.

Commits

Commit	Contents	Depends on
9a935eb	Vector column metadata	—
8fc82cb	binary16 codec (internal)	—
dad19a3	float16 support	8fc82cb
734a90a	Docs and sample	dad19a3
37e871d	Bulk copy raw payload transfer	dad19a3

dad19a3 cannot be split further: advertising version 2 without the reader, parameter and bulk copy wiring would leave float16 columns arriving natively with nothing able to interpret them.

Note for the TVP work

WriteSmiTypeInfo has no Vector case in main; TVP support for vectors is on the unmerged dev/ad/tvp-json-vector. This change neither breaks nor covers that path. When the TVP branch lands it must write the base type into the TVP column metadata scale byte, as WriteParameterMetadata does.

Checklist

• Tests added or updated
• Public API changes documented
• Breaking changes assessed — see Behaviour changes above
• Release note entry for the next 7.1 preview

[Copilot]

Pull request overview

Adds end-to-end support for SQL Server vector(N, float16) by negotiating VECTORSUPPORT feature extension version 2, introducing an IEEE-754 binary16 codec, and wiring float16 handling through SqlVector<T> read/write paths (including bulk copy), with accompanying docs and tests.

Changes:

• Negotiate vector feature extension v2 and track negotiated vector capability version (float32/float16) on the connection.
• Add float16 vector support across SqlVector<T>, SqlDataReader, SqlBuffer, SqlParameter, SqlCommand, and SqlBulkCopy, including payload conversion for bulk copy.
• Add unit/manual tests plus docs/snippets/sample updates; expose vector base type + dimensions via DbColumn indexer and register vector in the DataTypes schema collection.

Reviewed changes

Copilot reviewed 23 out of 23 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
src/Microsoft.Data.SqlClient/tests/UnitTests/SimulatedServerTests/ConnectionTests.cs	Updates simulated negotiation tests for vector feature extension v2.
src/Microsoft.Data.SqlClient/tests/UnitTests/Microsoft/Data/SqlTypes/SqlVectorTest.cs	Adds float16 construction/rendering tests and payload conversion tests.
src/Microsoft.Data.SqlClient/tests/UnitTests/Microsoft/Data/SqlTypes/Float16ConverterTest.cs	New unit tests validating binary16 codec (incl. exhaustive bit-pattern validation on .NET).
src/Microsoft.Data.SqlClient/tests/ManualTests/SQL/VectorTest/VectorFloat16BehaviourTests.cs	Manual tests for float16-specific behaviors (read/write/cross-base-type/bulk copy).
src/Microsoft.Data.SqlClient/tests/ManualTests/SQL/VectorTest/VectorColumnMetadataTests.cs	Manual tests for vector column metadata + schema collection registration.
src/Microsoft.Data.SqlClient/tests/ManualTests/SQL/VectorTest/NativeVectorFloat16Tests.cs	Manual typed tests for SqlVector<Half> on .NET.
src/Microsoft.Data.SqlClient/src/Microsoft/Data/SqlTypes/SqlVector.cs	Implements float16 support in SqlVector<T>, adds JSON ToString(), payload widening/conversion helpers.
src/Microsoft.Data.SqlClient/src/Microsoft/Data/SqlClient/TdsEnums.cs	Adds vector version constants and sets max supported vector version to float16 (v2).
src/Microsoft.Data.SqlClient/src/Microsoft/Data/SqlClient/SqlParameter.cs	Handles float16 vector return/coercion paths (Half on .NET, widening on netfx).
src/Microsoft.Data.SqlClient/src/Microsoft/Data/SqlClient/SqlMetaDataFactory.DataTypes.cs	Registers vector in GetSchema("DataTypes").
src/Microsoft.Data.SqlClient/src/Microsoft/Data/SqlClient/SqlEnums.cs	Adds float16 vector element type and element-size mapping; meta type inference includes SqlVector<Half> on .NET.
src/Microsoft.Data.SqlClient/src/Microsoft/Data/SqlClient/SqlDbColumn.cs	Exposes VectorBaseType/VectorDimensions via DbColumn indexer.
src/Microsoft.Data.SqlClient/src/Microsoft/Data/SqlClient/SqlDataReader.cs	Adds float16 field-type mapping and broadens GetSqlVector<T> to allow Half on .NET.
src/Microsoft.Data.SqlClient/src/Microsoft/Data/SqlClient/SqlCommand.cs	Emits (N, float16) parameter declaration when needed (keeps float32 declaration unchanged).
src/Microsoft.Data.SqlClient/src/Microsoft/Data/SqlClient/SqlBulkCopy.cs	Emits float16 vector type in INSERT BULK declaration and converts payload base type to match destination.
src/Microsoft.Data.SqlClient/src/Microsoft/Data/SqlClient/SqlBuffer.cs	Centralizes float16 vector rendering/value-shaping across frameworks.
src/Microsoft.Data.SqlClient/src/Microsoft/Data/SqlClient/Connection/SqlConnectionInternal.cs	Records negotiated vector feature version on FEATUREEXTACK.
src/Microsoft.Data.SqlClient/src/Microsoft/Data/SqlClient/Connection/ConnectionCapabilities.cs	Replaces bool flag with VectorVersion and derived float32/float16 capability properties.
src/Microsoft.Data.SqlClient/src/Microsoft/Data/Common/Float16Converter.cs	New internal binary16<->binary32 conversion implementation.
src/Microsoft.Data.SqlClient/ref/Microsoft.Data.SqlTypes.cs	Updates reference surface to include SqlVector<T>.ToString() override.
doc/snippets/Microsoft.Data.SqlTypes/SqlVector.xml	Documents float16 support, size constraints, and ToString() JSON rendering.
doc/samples/SqlVectorFloat16Example.cs	New sample demonstrating float16 vectors (insert/read/metadata).
.github/instructions/features.instructions.md	Updates repo feature reference docs for float16 vector base type and negotiation versions.

Suppressed comments (1)

src/Microsoft.Data.SqlClient/src/Microsoft/Data/SqlTypes/SqlVector.cs:420

• ConvertPayloadElementType doesn’t validate the vector header magic/version bytes before using the length and element type fields. This can cause non-vector payloads to be converted (or to fail later with less appropriate exceptions). Validate VecHeaderMagicNo/VecVersionNo up front, consistent with GetCountsOrThrow.

        if (tdsBytes.Length < TdsEnums.VECTOR_HEADER_SIZE)
        {
            throw ADP.InvalidVectorHeader();
        }

[Copilot]

Pull request overview

Copilot reviewed 23 out of 23 changed files in this pull request and generated no new comments.

Suppressed comments (4)

src/Microsoft.Data.SqlClient/src/Microsoft/Data/SqlClient/SqlBulkCopy.cs:1755

• SqlTypes.SqlVector<float> doesn’t resolve to any namespace/type in this file (there’s no using SqlTypes = ... and no SqlTypes namespace). This should be fully qualified to Microsoft.Data.SqlTypes.SqlVector<float> (or add an alias) to avoid a compile error.

            // The payload is converted directly rather than through a strongly typed vector,
            // so that .NET Framework, which has no System.Half, can also write to float16
            // destinations.
            return SqlTypes.SqlVector<float>.ConvertPayloadElementType(payload, destinationElementType);

src/Microsoft.Data.SqlClient/src/Microsoft/Data/SqlTypes/SqlVector.cs:154

• FromTdsPayload reads header fields (element type/length) without validating the vector magic/version bytes. This makes the widening path accept malformed payloads that GetCountsOrThrow would reject.

        if (tdsBytes.Length < TdsEnums.VECTOR_HEADER_SIZE)
        {
            throw ADP.InvalidVectorHeader();
        }

src/Microsoft.Data.SqlClient/src/Microsoft/Data/SqlTypes/SqlVector.cs:420

• ConvertPayloadElementType should validate the vector header magic/version before interpreting element type and length; otherwise malformed byte[] values can be converted and sent on the wire rather than failing fast with InvalidVectorHeader.

        if (tdsBytes.Length < TdsEnums.VECTOR_HEADER_SIZE)
        {
            throw ADP.InvalidVectorHeader();
        }

doc/samples/SqlVectorFloat16Example.cs:146

• These interpolated strings won’t compile because the expression uses double quotes (e.g., column["VectorBaseType"]) inside a double-quoted string literal. Escape the quotes (or assign to a local variable) before interpolating.

        Console.WriteLine($"\nColumn base type:  {column["VectorBaseType"]}");
        Console.WriteLine($"Column dimensions: {column["VectorDimensions"]}");

[Copilot]

Pull request overview

Copilot reviewed 23 out of 23 changed files in this pull request and generated no new comments.

Suppressed comments (2)

doc/samples/SqlVectorFloat16Example.cs:146

• These interpolated strings won’t compile because the expression contains a string literal with double quotes (e.g., column["VectorBaseType"]) which terminates the outer interpolated string. Assign the indexer results to variables (or constants) first, then interpolate those variables.

        Console.WriteLine($"\nColumn base type:  {column["VectorBaseType"]}");
        Console.WriteLine($"Column dimensions: {column["VectorDimensions"]}");

src/Microsoft.Data.SqlClient/src/Microsoft/Data/SqlClient/SqlParameter.cs:2408

• This SqlVector special-case is redundant/unreachable because SqlVector implements ISqlVector (so it will already be handled by the earlier value is ISqlVector branch). Keeping the extra branch increases maintenance burden and risks diverging behavior.

                    else if (currentType == typeof(SqlVector<Half>))
                    {
                        value = ((ISqlVector)value).VectorPayload;
                    }
                    #endif

[cheenamalhotra]

How do we make it a non-breaking change for existing applications because this time we're not in a major release milestone.

GetFieldType/GetValue for a float16 column now returns SqlVector<Half> on .NET and string on .NET Framework — a behavior change for existing apps once VECTORSUPPORT v2 is negotiated (previously varchar/string everywhere). Worth calling out as potentially breaking.

@saurabh500 for awareness.

[edwardneal]

Other type conversions within the driver use SqlConnectionStringBuilder.TypeSystemVersion as a decision point. This hasn't been used for a long time, but might be appropriate.

[saurabh500]

@cheenamalhotra good catch.
I think this is a classic catch of AppContext Switch to allow customers to go to back to a compatible change. An AppContext to not negotiate feature extension, till customers can adapt the App, could be a viable solution

@edwardneal TypeSystemVersion could have been a good candidate if we only had SQL On-prem. But the API doesn't hold true in the world of ever evolving cloud offerings which are versionless.

[apoorvdeshmukh]

Not addressed yet — this is the one open item, and I'd like to agree the approach before implementing it.

To be precise about the scope: .NET Framework is unaffected (it returns string before and after). The change is .NET-only, and only once VECTORSUPPORT v2 is negotiated: GetValue/GetFieldType for a float16 column move from string to SqlVector<Half>.

Proposal — an opt-in AppContext switch that makes .NET return the string form as well, matching .NET Framework:

	Default	Switch enabled
.NET GetValue	SqlVector<Half>	string
.NET GetFieldType	typeof(SqlVector<Half>)	typeof(string)
.NET Framework	string	string (unchanged)
GetSqlVector<T>	unchanged	unchanged

That keeps the faithful representation as the default while giving affected applications a documented, single-line workaround outside a major release. It also follows existing precedent (LegacyRowVersionNullBehavior, UseCompatibilityAsyncBehaviour, etc.), so the docs path already exists.

@edwardneal's TypeSystemVersion suggestion is the alternative; it seems heavier, and couples an unrelated legacy knob to a new feature.

I'm reviewing this with the team and will follow up here with the outcome and the switch name. Leaving this thread open until then.

@saurabh500 @edwardneal for visibility.

[saurabh500]

Summary

This adds vector(N, float16) by advertising VECTORSUPPORT v2, introducing a hand-written binary16 codec, teaching SqlVector<T> about System.Half, and switching vector→vector bulk copy to a raw-payload transfer. The engineering is careful, and I want to call out specifically that the endianness and element-size arithmetic is correct throughout — I went looking for a missed (ColumnSize - 8) / 4 and there isn't one. The commit split is clean and the rationale in the description is unusually good.

I have one blocking correctness issue, plus a set of suggestions. Inline comments carry the detail and suggested diffs; this is the map.

Blocking

• SqlBuffer.GetSqlVector<T>() succeeds or throws depending on the row's nullness. The IsNull branch builds a vector for any T without consulting the column's base type, while the non-null branch validates. GetSqlVector<Half>() over a float32 column therefore returns Null for NULL rows and throws NotSupportedException for non-NULL rows in the same result set. Data-dependent rather than schema-dependent, so it is hard to find in testing and impossible to guard against in caller code.

Suggestions

• The codec is not bit-exact against System.Half for NaN, contrary to the description, and the tests are written to step around exactly that case (continue / IsNaN-only). float.NaN carries the sign bit, so widening flips the sign of every NaN relative to System.Half; narrowing canonicalises payloads that (Half)float preserves. Either match System.Half or pin the canonical form with explicit assertions and drop the "bit-exact" claim.
• Bulk copy's vector case uses metadata.scale rather than the scale local that the surrounding code establishes for encrypted columns.
• The widening path skips the magic-number and version validation that the matching path gets via GetCountsOrThrow.
• Capabilities.Float16VectorType is never read anywhere in src/, so a SqlVector<Half> on a v1-negotiated connection fails server-side rather than client-side. (Float32VectorType was already dead in main; this adds a second.)
• The negotiation theory's 0x3 case doesn't test what its comment claims — the simulated server caps the ack itself, so the client's own ceiling check at SqlConnectionInternal.cs:1660 stays untested.
• Docs say narrowing "fails for values outside its range"; the code saturates to ±Infinity and leaves it to the server.
• MetaData is dereferenced without a null check in CreateSourceColumnMetadata.

Things I checked and found correct

Worth recording, since they're the parts most likely to be wrong in a change like this:

• Subnormal widening, signed zero, overflow to infinity, the flush-to-zero boundary (2⁻²⁵ ties to even → 0, 2⁻²⁶ flushes), binary32 subnormal inputs, and the rounding carry into the exponent are all correct. Compiling Manual* on every TFM so the netfx path is under test on .NET too is a good arrangement.
• Bulk copy null handling is correct as-is — GetValueFromSourceRow returns DBNull.Value with isNull = true and ConvertValue returns before ConvertVectorToBaseType. Note a5de733c3 is test-only; it documents behaviour that already worked rather than fixing anything.
• The raw-payload path can't be taken by DataTable, DataRow[], or non-SqlClient DbDataReader sources (they keep ValueMethod.GetValue), and reordering column mappings are safe because sourceOrdinal is the mapped ordinal.
• No unacknowledged breaking changes beyond the three listed: GetDataTypeName is unchanged, GetFieldType/GetProviderSpecificFieldType both route through the single new GetVectorFieldType so they stay consistent, SqlMetaDataFactory.DataTypes only adds a row (gated on MinimumVersionKey), the float32 declaration is deliberately unchanged, and SqlDbColumn's new indexer falls through to base[property].
• No shared mutable state: Float16Converter is stateless and SqlVector<T> is a readonly struct with no static caches.

On testing

Taking as given that CI has no float16-capable server and no Azure SQL DB connectivity, so the manual suite is the only gate that will ever run — I looked at whether it is complete enough for a lab run rather than whether CI covers it. It is substantial: 11 behaviour tests plus the inherited NativeVectorTestsBase matrix, and the sample data is well chosen (Half.MaxValue, Half.Epsilon, -0.0f, exactly-representable eighths). Gaps I'd close:

1. .NET Framework gets none of the NativeVectorTestsBase matrix — NativeVectorFloat16Tests.cs is entirely #if NET. That is where the hand-rolled Manual* codec is the production path.
2. No async coverage for the new representation on any framework, and none at all for float16 on netfx.
3. DataTestUtility.CheckVectorFloat16Supported fails open through the code under test. It reads the probe vector with GetString + JsonSerializer.Deserialize and catches JsonException → false. A driver regression that produces malformed JSON silently skips the whole float16 suite green. Since the manual run is the only gate, that is the wrong failure mode. (Outside this diff, so no inline comment — but worth fixing alongside. It also leaves PREVIEW_FEATURES = ON on the shared test database as a side effect.)
4. Two range tests assert only that some SqlException was thrown; they'd pass on an unrelated failure, and they can't distinguish "client rejects" from "client saturates and server rejects" — which is exactly the ambiguity in the doc wording above.
5. Nothing covers the blocking issue: reading a float32 column as SqlVector<Half>, for a NULL and a non-NULL row.
6. Bulk copy with a dimension-count mismatch between source and destination is uncovered. Mitigating: float32→float32 now routes through the new raw-payload path too and is covered by the existing NativeVectorFloat32Tests, which runs against any vector-capable server — so regression risk to shipped functionality is covered.

Minor

• SqlVector<T>.ToString() changing for existing SqlVector<float> callers is justified and correctly surfaced in the ref assembly and docs, but it is unrelated to float16 — it wants its own release-note entry as a behavioural break, not just an API-list line. Related: GetString() uses JsonSerializer.Serialize, which throws on NaN/Infinity by default, and on .NET Framework that is now the default GetValue() path.
• ConvertPayloadElementType is internal static on SqlVector<T> but never uses T, so callers write SqlVector<float>.ConvertPayloadElementType(...), which reads as though it returns a float32 result.
• On .NET Framework the reader surfaces a float16 column as string while an output parameter surfaces it as SqlVector<float>. Self-consistent, but worth documenting.
• Preprocessor directives in the new code are indented to the surrounding block; the dominant style in these files is column 0.
• ConnectionCapabilities.cs:179 says vectors were "introduced in SQL Server 2022" — pre-existing, but the new Float16VectorType doc sits right beside it.
• Worth confirming the doc/samples build resolves the locally-packed driver: SqlVectorFloat16Example.cs references SqlVector<Half> and GetSqlVector<Half>, which exist in no released package.

_{Review assisted by GitHub Copilot; findings verified against the code at a5de733c3.}

[saurabh500]

@apoorvdeshmukh and @cheenamalhotra, I think we will need to call this API a known limitation for preventing backward migration from .Net Runtime to NetFx.

I believe this is a known reasonable compromise.

[saurabh500]

BTW, I saw changes to ref assembly. Should I expect two copies of changes, one for netcore and another for NetFx? I am curious about how the APIs will show up in contract assemblies targeting 2 different frameworks.

[Copilot]

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

Note

This error may be related to your runner configuration. You can now configure runners for Copilot code review separately from Copilot cloud agent by creating a copilot-code-review.yml file with your setup steps. Read the docs for details.