Skip to content

FEAT: Support FLOAT32/FLOAT16 vectors in bulk copy and Arrow - #903

Draft
gargsaumya wants to merge 4 commits into
saumya/vector-supportfrom
saumya/vector-bulkcopy-arrow
Draft

gargsaumya wants to merge 4 commits into
saumya/vector-supportfrom
saumya/vector-bulkcopy-arrow

Conversation

@gargsaumya

@gargsaumya gargsaumya commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

Work Item / Issue Reference

AB#50377


Summary

Add FLOAT32/FLOAT16 row bulk-copy adaptation and native Arrow vector reads/writes.

  • Preserve vector dimensions/base type through a typed pycore bridge for tuple, Row, generator and list-cell input flows.
  • Follow Microsoft.Data.SqlClient SqlBulkCopy for base types: the client never converts between FLOAT32 and FLOAT16. Each vector column is declared with its source base type (first row's Vector; Arrow mssql.vector.base_type metadata) and SQL Server converts it (round-to-nearest; out-of-range FLOAT16 values fail on the server). JSON text for FLOAT16 columns is sent as text. Lists and untagged Arrow data use the destination base type.
  • Represent both SQL vector types in Arrow as fixed-size float32 lists with non-nullable elements and mssql.vector.base_type field metadata.
  • Support Arrow tables, record batches/readers, iterables and C stream/array producers, including Arrow-reader-to-bulk-copy pipelines.
  • Cover NULL/empty inputs, column mappings, buffer ownership and slices, numeric/shape failures and maximum dimensions.
  • Preserve ordinary Arrow paths and explicit errors for older pycore builds. Buffered callproc() results remain row-fetch only.
  • Update documentation and add unit/live coverage, gating backend-dependent live tests explicitly when the companion bridge is unavailable.

API examples: bulk copy and both Arrow flows

These examples assume a cursor connected with VectorTypeSupport="v2", ODBC 18.7.1.1+, the companion vector-capable pycore runtime, and existing dbo.VectorData / dbo.VectorDataCopy tables with one nullable VECTOR(3, FLOAT16) column named value. FLOAT32 uses the same APIs with a matching base type/schema.

Row bulk copy: pass the same public Vector objects inside rows.

from mssql_python import Vector

v = Vector([1.0, 2.0, 3.0], base_type="float16")
cursor.bulkcopy("dbo.VectorData", [(v,), (None,)])

SQL -> Arrow fetching, then Arrow -> SQL bulk loading:

cursor.execute("SELECT value FROM dbo.VectorData")
table = cursor.arrow()
cursor.bulkcopy_arrow("dbo.VectorDataCopy", table)

arrow_batch() and streaming arrow_reader() also support vectors; a reader can be passed directly to bulkcopy_arrow(). Both SQL base types use Arrow fixed-size lists of float32, with mssql.vector.base_type field metadata preserving float32 versus float16. Parent NULLs are supported; vector elements cannot be NULL.

Validation

  • Native Release build, 115 vector units, 55 existing bulk/Arrow units, 6 strict typing checks, pinned full Black and whitespace checks passed.
  • 90 new Azure E2E cases passed with zero skips across v1/FLOAT32, v2/FLOAT32 and v2/FLOAT16.
  • Cross-base update (merged with the reviewed FEAT: Add native FLOAT32 and FLOAT16 vector support #902): 146 vector units, typing and Black passed; on Azure SQL every live vector case passed (full matrix plus a fixed rerun of all 104 bulk/Arrow cases), with 83 existing row/Arrow bulk-copy tests and 16 regressions. New live tests cover row/Arrow/JSON cross-base conversion, rounding, the server out-of-range error and mixed base types in a column; they fail against the previous pycore wheel.
  • 51 existing Azure Arrow/bulk-copy/input-size/prepared/native-fetch regressions passed.
  • Validation used Windows x64/Python 3.13, the locally built companion pycore runtime and isolated Microsoft ODBC 18.7.1.1.
  • Long full-matrix runs were interrupted by transport failures; targeted feature/regression reruns passed. This is not a claim that the full suite or cross-platform matrix completed.
  • Temporary Azure SQL resources and credentials were deleted and cleanup verified.

Dependencies / scope

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

bulk copy and arrow both round trip vectors correctly for me, including sliced tables and reader to bulk copy, and plain bulk copy throughput is unchanged. this still needs the latest native vector changes merged in and the vector-capable runtime published before it leaves draft. commented, no blockers.

gargsaumya and others added 3 commits November 18, 2026 22:08
Pick up the reviewed #902 changes (TVP removal, OutputParameter triple, trusted vector construction, exact Vector type checks, SQL Server 2025 FLOAT16 preview docs).

Align vector bulk copy and Arrow docs/tests with Microsoft.Data.SqlClient: the client never converts between base types; columns are declared with their source base type (JSON text for FLOAT16 columns as text) and SQL Server converts them. Replace base-type mismatch rejection tests with live conversion, rounding, out-of-range and mixed-column tests.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Arrow fixed-size float32 lists represent both base types, so untagged columns convert to the destination like numeric lists; only mssql.vector.base_type-tagged columns declare their own base type for server-side conversion. This keeps FLOAT16 columns above 1998 dimensions loadable from untagged Arrow data.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

pr-size: large Substantial code update

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants