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]

Can you write a sample/test case that uses this property?
I want to know the customer use case of why it is required to be exposed.

[cheenamalhotra]

Please write float16 tests for .NET Framework as well.

[cheenamalhotra]

Does this trait work at class level?

[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.

[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]

Blocking — this succeeds or throws depending on the row's nullness.

The IsNull branch above (981-984) calls SqlVector<T>.CreateNull for any T without consulting _value._vectorInfo._elementType, while this line delegates to FromTdsPayload, which throws SQL.VectorTypeNotSupported for any narrowing pair (SqlVector.cs:170-172).

Concretely, on .NET, reader.GetSqlVector<Half>(i) against a vector(N, float32) column returns a valid SqlVector<Half>.Null for NULL rows and throws NotSupportedException for non-NULL rows in the same result set. GetFieldValue<SqlVector<Half>> inherits this because it routes here. The outcome depends on the data rather than the schema, which makes it very hard to discover in testing and impossible for a caller to guard against.

There's a secondary problem in the same branch: a null float32 column read as SqlVector<Half> yields a Half vector of the same element count, which is a different wire size. Round-tripping that value back as a parameter declares vector(N, float16) against a float32 column.

Validating the pairing before the null check fixes both, and makes the behaviour depend on the column:

internal SqlVector<T> GetSqlVector<T>() where T : unmanaged
{
    if (_type is StorageType.Vector)
    {
        // The payload's base type may differ from T: a float16 column can be read as a
        // vector of single precision values, which is the only strongly typed form
        // available on .NET Framework. Validate the pairing before considering
        // nullness, so that the outcome depends on the column's base type rather than
        // on whether a particular row happens to be null.
        SqlVector<T>.ThrowIfNotConvertibleFrom(_value._vectorInfo._elementType);

        if (IsNull)
        {
            return SqlVector<T>.CreateNull(_value._vectorInfo._elementCount);
        }

        return SqlVector<T>.FromTdsPayload(SqlBinary.Value);
    }
    return (SqlVector<T>)SqlValue;
}

where ThrowIfNotConvertibleFrom factors out the source/target check FromTdsPayload already performs at SqlVector.cs:156-172, so the two cannot drift.

Please also add a test that reads both a NULL and a non-NULL row of a float32 column as SqlVector<Half> and asserts they behave the same way — that pairing isn't covered anywhere today.

[saurabh500]

The PR description says the codec is "validated bit-exactly against System.Half across all 65,536 patterns". That isn't true for NaN, and it's this line.

float.NaN is 0xFFC00000 — it has the sign bit set. (float)Half.NaN is 0x7FC00000. So every NaN widened here comes out with the opposite sign to what System.Half produces, and System.Half also preserves the payload bits rather than canonicalising them:

input	#if NET path (production on .NET)	this path (production on netfx)
0x7E00	0x7FC00000	0xFFC00000
0xFE00	0xFFC00000	0xFFC00000

That's a real cross-framework difference in a conversion the driver ships, even if SQL Server never stores a NaN in a vector. Preserving sign and payload costs nothing and removes the divergence:

Suggested change

	return mantissa == 0
	? Int32BitsToSingle((sign << 31) | (Binary32MaxExponent << Binary32MantissaBits))
	: float.NaN;
	return mantissa == 0
	? Int32BitsToSingle((sign << 31) | (Binary32MaxExponent << Binary32MantissaBits))
	: Int32BitsToSingle(
	(sign << 31) |
	(Binary32MaxExponent << Binary32MantissaBits) |
	(mantissa << MantissaShift));

The comment on 85-86 needs updating either way, since it documents canonicalisation.

If the canonicalisation is deliberate, that's defensible — but then the claim should come out of the description and the tests should pin the canonical form explicitly rather than skipping NaN (see my comments on Float16ConverterTest.cs).

[saurabh500]

Same divergence in the narrowing direction. (Half)float preserves the top payload bits and forces the quiet bit; this canonicalises every NaN to 0x7E00, so ManualFromSingle(0x7FFFFFFF) returns 0x7E00 where System.Half returns 0x7FFF.

To match:

Suggested change

	// Infinity or NaN. NaN is canonicalised to a quiet NaN, matching the
	// representation produced by System.Half.
	int payload = mantissa == 0 ? 0x7C00 : 0x7E00;
	return (ushort)((sign << 15) | payload);
	// Infinity or NaN. A NaN keeps its sign and the high bits of its payload,
	// with the quiet bit forced, which is what a System.Half conversion produces.
	int payload = mantissa == 0
	? 0x7C00
	: 0x7C00 | 0x0200 | ((mantissa >> MantissaShift) & 0x1FF);
	return (ushort)((sign << 15) | payload);

Whichever way you resolve this and the widening case, the two directions should agree with each other.

[saurabh500]

Nit: the prose doesn't match the guard. "More than eleven binade below the smallest subnormal" doesn't describe targetExponent < -Binary16MantissaBits, and "eleven" doesn't correspond to Binary16MantissaBits (10) either.

Suggested change

	// Too small to represent as a normal value. Values more than eleven
	// binade below the smallest subnormal cannot round up to one, so they
	// are flushed to zero rather than shifted by more than the mantissa width.
	// Too small to represent as a normal value. Values below half of the
	// smallest subnormal cannot round up to it, so they are flushed to zero
	// rather than shifted by more than the mantissa width.

For the record, I verified the boundary itself is right: exactly 2⁻²⁵ ties to even and yields zero, and 2⁻²⁶ flushes. Binary32 subnormal inputs always land in this branch too, so the implicit-bit restore below is never misapplied to them.

[saurabh500]

This should use the scale local rather than metadata.scale. Lines 1778-1788 establish it precisely so that encrypted columns read their base type info:

byte scale = metadata.scale;
...
if (metadata.isEncrypted)
{
    type = metadata.baseTI.metaType;
    scale = metadata.baseTI.scale;
    ...
}

For an encrypted column, metadata.scale is the wrapping varbinary metadata's scale — 0, i.e. Float32 — not the vector's base type, which is in metadata.baseTI.scale. Whether Always Encrypted currently permits a vector column or not, every other conversion in this method reads the redirected value, and this one silently won't.

Suggested change

	value = ConvertVectorToBaseType(value, metadata.scale);
	value = ConvertVectorToBaseType(value, scale);

updateBulkCommandText at 883-886 has the same shape (metadata.scale used for both the dimension count and the float16 test) — worth a look for consistency, though that path may legitimately want the outer metadata.

[saurabh500]

This asserts only that the result is a NaN, not that it's the same NaN — which is what lets the sign divergence I flagged in Float16Converter.cs:87-89 through. ManualToSingle(0x7E00) returns 0xFFC00000 while (float)Half returns 0x7FC00000, and this passes.

Once the production behaviour is settled, this should assert the bit pattern like the non-NaN case below does. If you match System.Half, the special case disappears entirely and the existing bitwise assertion covers all 65,536 patterns — which is what the PR description claims today.

If canonicalisation stays deliberate, assert it explicitly rather than skipping:

Suggested change

	if (float.IsNaN(expected))
	{
	Assert.True(float.IsNaN(actual), $"0x{bits:X4} should convert to NaN.");
	continue;
	}
	if (float.IsNaN(expected))
	{
	// Deliberately canonicalised rather than payload preserving, so compare
	// against the documented canonical form rather than against Half.
	Assert.Equal(
	BitConverter.SingleToInt32Bits(float.NaN),
	BitConverter.SingleToInt32Bits(actual));
	continue;
	}

The rest of this test is excellent — exhaustive over the bit patterns, and comparing bitwise so signed zero is distinguished.

[saurabh500]

Same gap in the narrowing direction: skipping NaN here is what hides ManualFromSingle canonicalising payloads that (Half)float preserves. FromSingle_MatchesHalf_AcrossTheSinglePrecisionRange has the same continue at 82-85.

Whichever way Float16Converter.cs:137-140 is resolved, please replace both continues with an assertion, so the NaN behaviour is pinned rather than merely undefined. As it stands, the two codec implementations could drift arbitrarily on NaN and every test here would still pass.

[saurabh500]

Understood why this file is #if NET — SqlVector<Half> doesn't exist on netfx. The consequence, though, is that .NET Framework gets none of the NativeVectorTestsBase matrix for float16: no sync/async parameter round trip, no stored proc params, no bulk copy source modes, no Prepare. On netfx those go entirely untested for this base type.

That's the framework where it matters most, because netfx is where the hand-rolled ManualToSingle/ManualFromSingle path is the production codec rather than a test double.

NativeVectorTestsBase is generic over TElement, so the documented netfx usage — write SqlVector<float>, read widened — can reuse the whole harness:

// Runs on every framework: exercises the float16 column through the single precision
// representation, which is the only strongly typed form available without System.Half.
public sealed class VectorFloat16AsSingleTestData : NativeVectorTestDataBase<float>
{
    public override bool IsSupported => DataTestUtility.IsSqlVectorFloat16Supported;
    public override string SqlServerTypeName => "float16";
    // sample data restricted to values exactly representable in binary16
}

[Trait("Set", "3")]
public sealed class NativeVectorFloat16AsSingleTests
    : NativeVectorTestsBase<float, VectorFloat16AsSingleTestData>
{
}

That would also give netfx its only async float16 coverage, since VectorFloat16BehaviourTests is entirely synchronous.

[saurabh500]

This passes on any SqlException — including "invalid object name" if the table setup ever regresses — so it doesn't establish that the server rejected the value rather than something else going wrong. BulkCopyRejectsValuesOutsideTheFloat16Range at 271 has the same shape.

Worth asserting the error number instead, so the test fails if the failure mode changes:

Assert.Equal(/* the server's vector range error number */, exception.Number);

This matters more than usual here because of the doc/behaviour mismatch I flagged on SqlVector.cs:494: the client saturates 70000 to +Infinity and the server rejects that, which is a different failure from the client rejecting an out-of-range value. As written the test passes either way, so it can't tell you which behaviour you shipped.

[saurabh500]

This covers double and int, but not the case that actually breaks: reading a float32 column as SqlVector<Half> (see my blocking comment on SqlBuffer.cs). That pairing throws for non-null rows and silently succeeds for null ones.

_float32Table is already available here, so it's a short addition:

[ConditionalFact(nameof(IsSupported))]
public void ReportsNarrowingReadsConsistentlyForNullAndNonNullRows()
{
    // The base type pairing is a property of the column, so a null row must be
    // rejected the same way a populated one is.
    Insert(_float32Table, DBNull.Value);
    Insert(_float32Table, new SqlVector<float>(new float[] { 1.5f, 2.5f, 3.5f }));

    using SqlConnection connection = new(_connectionString);
    connection.Open();
    using SqlCommand command =
        new($"SELECT {ColumnName} FROM {_float32Table.Name} ORDER BY Id", connection);
    using SqlDataReader reader = command.ExecuteReader();

    Assert.True(reader.Read());
    Assert.Throws<NotSupportedException>(() => reader.GetSqlVector<Half>(0));   // null row
    Assert.True(reader.Read());
    Assert.Throws<NotSupportedException>(() => reader.GetSqlVector<Half>(0));   // populated row
}

More generally: VectorFloat16BehaviourTests is entirely synchronous, and it's the suite that pins the new representation and the acknowledged breaking changes. GetFieldValueAsync<SqlVector<Half>> and GetFieldValueAsync<SqlVector<float>> over a float16 column aren't exercised anywhere. Given CI can never run any of this, the lab suite is the only gate and async is worth covering here.

[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.