Använda vektordatatyp med JDBC-drivrutinen

Ladda ned JDBC-drivrutin

Från och med version 13.2.0 stöder JDBC-drivrutinen vektordatatypen . Från och med version 13.4.0 stöder drivrutinen även undertypen vector(float16). Vektor stöds också med funktioner som tabellvärdesparametrar och masskopiering, med vissa begränsningar. Den här sidan visar olika användningsfall av vektordatatypen med JDBC-drivrutinen. En översikt över vektordatatyper finns i Vektordatatyp.

Skapa ett vektorobjekt

Klassen microsoft.sql.Vector är en anpassad implementering som är utformad för att representera vektordata i JDBC-drivrutinen. Det ger ett strukturerat sätt att hantera högdimensionella data, inklusive serialisering och deserialisering, samtidigt som kompatibilitet med SQL Server-vektordatatypen säkerställs. Vektorobjektet ska innehålla antalet element, typindikator och data.

public enum VectorDimensionType {
        FLOAT32 // 32-bit (single precision) float
}

private VectorDimensionType vectorType; // The type of values in the data array
private int dimensionCount; // Number of dimensions in the vector
private Object[] data; // An array containing the vector's numerical values

Microsoft JDBC-drivrutinen för SQL Server erbjuder två metoder för att initiera ett vektorobjekt, vilket ger flexibilitet för olika användningsfall och indata.

Skapa ett vektorobjekt med dimensionsantal och vektortyp

Konstruktor:

public Vector(int dimensionCount, VectorDimensionType vectorType, Object[] data);

Exempel:

Vector vector = new Vector(3, Vector.VectorDimensionType.FLOAT32, new Float[]{1.0f, 2.0f, 3.0f});

Skapa ett vektorobjekt med precision och skala

Konstruktor:

public Vector(int precision, int scale, Object[] data);

Var parametrarna finns:

precision: Antalet dimensioner i vektorn.
skala: Skalningsvärdet, som representerar antalet byte per dimension. 4 bytes representerar FLOAT32.
data: En float[] matris som innehåller de numeriska värdena i vektorn.

Exempel:

Vector vector = new Vector(3, 4, new Float[]{1.0f, 2.0f, 3.0f});

Fylla i och hämta en tabell

Här följer några kodexempel som fyller i och hämtar vektordata från en databas. Exemplen förutsätter att en tabell med en vektorkolumn definieras på följande sätt:

CREATE TABLE sampleTable (vector_col vector(3))

Infoga värden med en vanlig INSERT-instruktion:

try (Statement stmt = connection.createStatement()){
    stmt.execute("insert into sampleTable values ('[0.1, 2.0, 3.0]')");
}

Infoga värden med en förberedd instruktion och en vektorparameter :

Vector vector = new Vector(3, Vector.VectorDimensionType.FLOAT32, new Float[]{1.0f, 2.0f, 3.0f});
try (PreparedStatement preparedStatement = con.prepareStatement("insert into sampleTable values (?)")) {
    preparedStatement.setObject(1, vector, microsoft.sql.Types.VECTOR);
    preparedStatement.execute();
}

Infoga ett null-värde med en förberedd instruktion och en parameter:

Vector vector = new Vector(1, Vector.VectorDimensionType.FLOAT32, null);
try (PreparedStatement preparedStatement = con.prepareStatement("insert into sampleTable values (?)")) {
    preparedStatement.setObject(1, vector, microsoft.sql.Types.VECTOR);
    preparedStatement.execute();
}

try (PreparedStatement preparedStatement = con.prepareStatement("insert into sampleTable values (?)")) {
    preparedStatement.setObject(1, null)
    preparedStatement.execute();
}

Läsa vektorvärden från en tabell:

try (SQLServerResultSet resultSet = (SQLServerResultSet) stmt.executeQuery("select * from sampleTable")) {
    assertTrue(resultSet.next(), "No result found for inserted vector.");
    ResultSetMetaData metaData = resultSet.getMetaData();
    int columnCount = metaData.getColumnCount();

    while (resultSet.next()) {
        for (int i = 1; i <= columnCount; i++) {
            String columnName = metaData.getColumnName(i);
            int columnType = metaData.getColumnType(i); // from java.sql.Types

            Object value = null;
            switch (columnType) {
                case Types.VARCHAR:
                case Types.NVARCHAR:
                    value = resultSet.getString(i);
                    break;
                case microsoft.sql.Types.VECTOR:
                    value = resultSet.getObject(i, microsoft.sql.Vector.class);
            }

            System.out.println(columnName + " = " + value + " (type: " + columnType + ")");
        }
    }
}

Använda lagrade procedurer med vektor

Med följande lagrade procedur:

String sql = "CREATE PROCEDURE " + inputProc +
             " @p0 VECTOR(3) OUTPUT AS " +
             " SELECT TOP 1 @p0 = col_vector FROM sampleTable ";

Returnera en vektorutdataparameter med följande exempel:

try (CallableStatement callableStatement = con.prepareCall("{call " + inputProc + " (?) }")) {
    callableStatement.registerOutParameter(1, microsoft.sql.Types.VECTOR, 3, 4);
    callableStatement.execute();
}

Använd TVP med vektor

Vector vector = new Vector(3, Vector.VectorDimensionType.FLOAT32, new Float[]{1.0f, 2.0f, 3.0f});
SQLServerDataTable tvp = new SQLServerDataTable();
tvp.addColumnMetadata("vector_col", microsoft.sql.Types.VECTOR);
tvp.addRow(vector);

try (SQLServerPreparedStatement preparedStatement = (SQLServerPreparedStatement) con.prepareStatement( "insert into sampleTable select * from (?)")) {
    pstmt.setStructured(1, TVP_NAME, tvp);
    pstmt.execute();
}

Använda SQLServerBulkCopy från källtabell till måltabell med vektor

Vektorer kan användas i masskopieringskommandon:

Vector vector = new Vector(3, Vector.VectorDimensionType.FLOAT32, new Float[]{1.0f, 2.0f, 3.0f});
try (Statement stmt = con.createStatement();
        SQLServerBulkCopy bulkCopy = new SQLServerBulkCopy(con)) {

        stmt.executeUpdate("create table destinationTable (vector_col vector(3))");

        bulkCopy.setDestinationTableName("destinationTable");
        bulkCopy.writeToServer(vector);
    }

Använd bulkCopy från csv-fil till måltabell med vektor

Vektorer kan importeras från CSV-filer.

Klistra in följande innehåll i en CSV-fil med namnet vectors.csv:

vector_col
"[1.0,2.0,3.0]"
"[4.0,5.0,6.0]"

try (Statement stmt = con.createStatement();
    SQLServerBulkCopy bulkCopy = new SQLServerBulkCopy(con);
    SQLServerBulkCSVFileRecord fileRecord = new SQLServerBulkCSVFileRecord("vectors.csv", null, ",", true)) {

        stmt.executeUpdate("create table destinationTable (vector_col vector(3))");

        // Add column metadata for the CSV file
        fileRecord.addColumnMetadata(1, "vector_col", microsoft.sql.Types.VECTOR, 3, 4);
        fileRecord.setEscapeColumnDelimitersCSV(true);

        bulkCopy.setDestinationTableName("destinationTable");
        bulkCopy.writeToServer(fileRecord);
}

Använd vektor FLOAT16 datatypen

FLOAT16 (IEEE 754 halvprecision, 16-bitars) vektorer använder 2 byte per dimension i stället för 4, vilket halverar lagringsfotavtrycket och aktiverar upp till 3 996 dimensioner per vektor (jämfört med 1 998 för FLOAT32) inom TDS-gränsen på 8 000 byte. Den här undertypen är särskilt värdefull för storskaliga AI/ML-arbetsbelastningar, till exempel likhetssökning och inbäddning av lagring där minneseffektivitet är viktigt.

FLOAT16 vektorstöd aktiveras via det befintliga vektorfunktionstillägget (FE-identifierare 0x0E) med handskakning version 2: klienten begär v2 via anslutningsegenskapen vectorTypeSupport, och servern bekräftar FLOAT16 kapacitet i funktions-ack-svaret.

Om du vill använda FLOAT16 vektorer följer du samma mönster som visas i föregående exempel och ersätter FLOAT32 med FLOAT16 och skalningsvärdet 4 med 2. Som exempel:

Använd Vector.VectorDimensionType.FLOAT16 i stället för Vector.VectorDimensionType.FLOAT32.
Använd en skala 2 i stället för 4 när du skapar en vektor med precision och skala.
Definiera SQL-kolumner som vector(3, float16) i stället för vector(3).

Här är ett exempel på hur du skapar ett FLOAT16 vektorobjekt:

// Using dimension count and vector type
Vector vector = new Vector(3, Vector.VectorDimensionType.FLOAT16, new Float[]{1.0f, 2.0f, 3.0f});

// Using precision and scale (2 bytes = FLOAT16)
Vector vector = new Vector(3, 2, new Float[]{1.0f, 2.0f, 3.0f});

Bakåtkompatibilitet

Om ett program inte uppdateras för att hantera vektordatatypen ger drivrutinen bakåtkompatibilitet genom att låta vektordatatyper läsas som bakåtkompatibla typer. Det här beteendet styrs med egenskapen vectorTypeSupport anslutningssträngens. Värden som stöds är off (servern skickar vektortyper som strängdata i JSON-format), v1 (servern skickar vektortyper av FLOAT32 som vektordata) och v2 (för att aktivera stöd för vektortyp för FLOAT16). Standardvärdet är v1.

Begränsningar för vektor

Detaljerade begränsningar finns i Begränsningar för vektordatatyp.

Förstå JDBC-drivrutinsdatatyperna

Feedback

Var den här sidan till hjälp?

Last updated on 2026-03-18