feat: add SQL Server 2025 VECTOR type support

[David Levy (dlevy-msft-sql)]

SQL Server 2025 VECTOR Type Support

Overview

This PR adds native support for SQL Server 2025's VECTOR data type, enabling efficient storage and retrieval of vector embeddings for AI/ML workloads in Go applications.

The VECTOR type is designed for similarity search scenarios, storing fixed-dimensional arrays of floating-point numbers optimized for operations like VECTOR_DISTANCE.

Features

Core Types

• Vector - Vector type implementing driver.Valuer and sql.Scanner interfaces
• NullVector - Nullable wrapper for database columns that allow NULL values
• VectorElementType - Enum for element precision (float32/float16)

Element Type Support

Type	Constant	Bytes	Max Dimensions	Notes
float32	VectorElementFloat32	4	1998	Default, fully supported
float16	VectorElementFloat16	2	3996	Preview feature, requires PREVIEW_FEATURES = ON

Wire Format Support

• Binary TDS format: Native encoding/decoding matching SQL Server's internal format
• JSON format: Backward-compatible parameter transmission for older drivers/servers
• Automatic format selection: Uses binary when supported, falls back to JSON

Framework Compatibility

• Direct support for []float32 and []float64 parameter binding (no wrapper needed)
• Vector and NullVector types implement sql.Scanner for decoding binary data
• Float16 vectors preserve ElementType metadata when scanned to Vector/NullVector

Connection String Option

vectortypesupport=v1    # Enable native binary TDS format (SQL Server 2025+)
vectortypesupport=off   # Default: JSON format for backward compatibility

API Summary

Creating Vectors

// From float32 slice (default)
v, err := mssql.NewVector([]float32{1.0, 2.0, 3.0})

// From float64 slice (converted to float32)
v, err := mssql.NewVectorFromFloat64([]float64{1.0, 2.0, 3.0})

// With explicit element type (for float16)
v, err := mssql.NewVectorWithType(mssql.VectorElementFloat16, values)

Inserting Vectors

// Using Vector type
_, err = db.Exec("INSERT INTO embeddings (v) VALUES (@p1)", v)

// Using []float32 directly (convenient for frameworks)
_, err = db.Exec("INSERT INTO embeddings (v) VALUES (@p1)", []float32{1.0, 2.0, 3.0})

// Using []float64 (auto-converted to float32)
_, err = db.Exec("INSERT INTO embeddings (v) VALUES (@p1)", []float64{1.0, 2.0, 3.0})

Reading Vectors

// To Vector type (recommended)
var v mssql.Vector
err := row.Scan(&v)
fmt.Println(v.Dimensions(), v.Values())

// Nullable columns
var nv mssql.NullVector
err := row.Scan(&nv)
if nv.Valid {
    // Use nv.Vector
}

Similarity Search

queryVec, _ := mssql.NewVector([]float32{1.0, 0.0, 0.0})
rows, _ := db.Query(`
    SELECT name, VECTOR_DISTANCE('cosine', embedding, @p1) as distance
    FROM documents
    ORDER BY distance
`, queryVec)

Files Changed

New Files

File	Purpose
vector.go	Core Vector/NullVector types, encoding/decoding, float16 conversion
vector_test.go	Comprehensive unit tests (50+ test cases)
vector_db_test.go	Database integration tests with SQL Server 2025
doc/how-to-use-vectors.md	Complete usage guide with examples

Modified Files

File	Changes
types.go	Added typeVectorN constant, TDS read/write functions, type metadata
mssql.go	Vector parameter binding with binary/JSON format selection
mssql_go19.go	convertInputParameter for Vector types
tds.go	Feature extension negotiation for vector support
token.go	Feature ack parsing for vector support
msdsn/conn_str.go	vectortypesupport connection string parameter
msdsn/conn_str_test.go	Connection string parsing tests
tds_login_test.go	Login packet tests with vector feature extension
README.md	Added Vector to supported types list
CHANGELOG.md	Version 1.9.7 feature documentation
.gitignore	Additional test artifact patterns

Implementation Details

TDS Protocol Integration

• New feature extension featExtVECTORSUPPORT (0x0E) for LOGIN7 negotiation
• Binary format: 8-byte header + float32/float16 payload
• Header structure: magic (0xA9), version (0x01), dimensions (2 bytes), element type, reserved (3 bytes)

NULL Handling

• NullVector{Valid: false} sends as NVARCHAR(1) NULL for dimension-agnostic NULL insertion
• This workaround avoids SQL Server's requirement for matching dimensions on NULL vector parameters

Special Value Handling

• NaN: Encoded as JSON null, decoded back to NaN for round-trip support
• Infinity: Rejected with error in Value() since JSON cannot represent ±Inf losslessly
• Precision warnings: Optional callback for float64→float32 precision loss detection

Thread Safety

• SetVectorPrecisionLossHandler() uses mutex for thread-safe handler updates
• Precision warnings fire once per vector (first loss only) for performance

Driver Value Types

The readVectorType function returns []byte (raw binary vector payload), which is a standard database/sql/driver.Value type. This follows Go database driver conventions where drivers return primitive types and custom types handle decoding via sql.Scanner.

Applications should scan to Vector or NullVector types, which implement sql.Scanner and decode the binary representation automatically.

Testing

Unit Tests (go test ./...)

• Vector encoding/decoding (float32 and float16)
• Float16 conversion accuracy
• JSON serialization/deserialization
• NULL handling
• Error cases (invalid data, unsupported types)
• Maximum dimension limits
• Type metadata functions

Integration Tests (requires SQL Server 2025)

• Insert/select round-trips
• NULL vector handling
• Different dimension counts (1D to 500D)
• Special floating-point values
• VECTOR_DISTANCE similarity search
• Column metadata verification
• Batch operations
• Float16 with PREVIEW_FEATURES

Test Coverage

• New vector-specific tests: 50+ test functions
• All existing tests continue to pass
• Graceful skip on pre-2025 SQL Server instances

Requirements

• SQL Server 2025 or later for VECTOR type support
• go-mssqldb 1.9.7 or later
• For float16: ALTER DATABASE SCOPED CONFIGURATION SET PREVIEW_FEATURES = ON

Migration Notes

• Backward compatible: Default vectortypesupport=off uses JSON format
• No breaking changes: Existing code continues to work unchanged
• Opt-in optimization: Set vectortypesupport=v1 for binary format with SQL Server 2025+

Related Documentation

• How to Use Vectors Guide
• SQL Server 2025 Vector Documentation
• VECTOR_DISTANCE Function

Acknowledgments

Thanks to David Shiflet (@shueybubbles) for the review feedback that improved:

• Direct []float32 and []float64 parameter support
• Thread-safe precision warning API

[Codecov Comments Bot (codecov-commenter)]

Codecov Report

❌ Patch coverage is 72.78481% with 172 lines in your changes missing coverage. Please review.
✅ Project coverage is 96.39%. Comparing base (296a83a) to head (20a09c0).
⚠️ Report is 43 commits behind head on main.

Files with missing lines	Patch %	Lines
vector.go	82.33%	60 Missing and 11 partials ⚠️
types.go	54.54%	39 Missing and 11 partials ⚠️
mssql.go	45.90%	26 Missing and 7 partials ⚠️
tds.go	66.66%	9 Missing and 1 partial ⚠️
msdsn/conn_str.go	69.23%	3 Missing and 1 partial ⚠️
token.go	50.00%	3 Missing and 1 partial ⚠️

Additional details and impacted files

@@             Coverage Diff             @@
##             main     #307       +/-   ##
===========================================
+ Coverage   79.92%   96.39%   +16.46%     
===========================================
  Files          34       92       +58     
  Lines        6656    74705    +68049     
===========================================
+ Hits         5320    72013    +66693     
- Misses       1065     2325     +1260     
- Partials      271      367       +96     

Flag	Coverage Δ
unittests	96.40% <77.28%> (?)

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
mssql_go19.go	94.79% <100.00%> (+0.22%)	⬆️
msdsn/conn_str.go	88.28% <69.23%> (ø)
token.go	68.86% <50.00%> (+0.15%)	⬆️
tds.go	69.86% <66.66%> (+0.83%)	⬆️
mssql.go	85.75% <45.90%> (-2.47%)	⬇️
types.go	80.00% <54.54%> (-2.09%)	⬇️
vector.go	82.33% <82.33%> (ø)

... and 56 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[Copilot]

Pull request overview

This PR adds native support for SQL Server 2025's VECTOR data type, enabling efficient storage and retrieval of vector embeddings for AI/ML workloads. The implementation includes Vector and NullVector types that implement standard database interfaces, support for both float32 and float16 element types, binary format encoding/decoding, JSON format transmission for parameterized queries, and comprehensive test coverage with graceful degradation for pre-2025 servers.

Changes:

• Added Vector and NullVector types with driver.Valuer and sql.Scanner interface implementations
• Implemented binary format encoding/decoding matching SQL Server's native TDS format
• Added float16 conversion functions with IEEE 754 half-precision support
• Extended types.go with typeVectorN constant and read/write functions for vector data handling
• Updated parameter binding in mssql.go to transmit vectors as JSON strings for backward compatibility

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
vector.go	Core Vector type implementation with encoding/decoding, float16 conversion, and helper functions
vector_test.go	Comprehensive unit tests for Vector type including encoding, decoding, and edge cases
vector_db_test.go	Database integration tests with SQL Server 2025+ version detection and preview feature handling
types.go	Added typeVectorN constant and TDS stream read/write functions for vector data
mssql.go	Extended makeParam to handle Vector/NullVector types via JSON string transmission
doc/how-to-use-vectors.md	Complete usage documentation with examples and best practices
README.md	Added Vector type to supported features list
CHANGELOG.md	Documented new feature in version 1.9.4

[David Shiflet (shueybubbles)]

Copilot what's the expected behavior if an app tries to scan a vector to []float64 or insert a []float64 to a vector column?

[Copilot]

Pull request overview

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

[Copilot]

Pull request overview

Copilot reviewed 12 out of 13 changed files in this pull request and generated 5 comments.

[Copilot]

Pull request overview

Copilot reviewed 12 out of 13 changed files in this pull request and generated 9 comments.

[Copilot]

Pull request overview

Copilot reviewed 12 out of 13 changed files in this pull request and generated 3 comments.

[Copilot]

Pull request overview

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

[Copilot]

Pull request overview

Copilot reviewed 12 out of 13 changed files in this pull request and generated 6 comments.

[Copilot]

Pull request overview

Copilot reviewed 12 out of 13 changed files in this pull request and generated 7 comments.

[Copilot]

Pull request overview

Copilot reviewed 18 out of 21 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 18 out of 21 changed files in this pull request and generated 3 comments.

[Copilot]

Pull request overview

Copilot reviewed 18 out of 21 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 18 out of 21 changed files in this pull request and generated 4 comments.

[Copilot]

Pull request overview

Copilot reviewed 18 out of 21 changed files in this pull request and generated 3 comments.

[Copilot]

Pull request overview

Copilot reviewed 18 out of 21 changed files in this pull request and generated 3 comments.

[Copilot]

Pull request overview

Copilot reviewed 18 out of 21 changed files in this pull request and generated 3 comments.

[Copilot]

Pull request overview

Copilot reviewed 18 out of 21 changed files in this pull request and generated 3 comments.

[Copilot]

Pull request overview

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

[Copilot]

Pull request overview

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