Partilhar via

Usar o tipo de dados vetoriais com o driver JDBC

Baixar driver JDBC

A partir da versão 13.2.0, o driver JDBC suporta o tipo de dados vetoriais . A partir da versão 13.4.0, o driver também suporta o subtipo vector(float16). O Vetor também é suportado com recursos como Table-Valued Parameters e BulkCopy, com algumas limitações. Esta página mostra vários casos de uso do tipo de dados vetoriais com o JDBC Driver. Para obter uma visão geral dos tipos de dados vetoriais , consulte Tipo de dados vetoriais.

Criar um objeto vetorial

A classe microsoft.sql.Vetor é uma implementação personalizada projetada para representar dados vetoriais no driver JDBC. Ele fornece uma maneira estruturada de lidar com dados de alta dimensão, incluindo serialização e desserialização, garantindo a compatibilidade com o tipo de dados vetoriais do SQL Server. O objeto vetorial deve incluir o número de elementos, indicador de tipo e dados.

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

O Microsoft JDBC Driver para SQL Server oferece dois métodos para inicializar um objeto vetorial, fornecendo flexibilidade para diferentes casos de uso e dados de entrada.

Criar um objeto vetorial com contagem de dimensões e tipo de vetor

Construtor:

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

Exemplo:

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

Crie um objeto vetorial com precisão e escala

Construtor:

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

Onde os parâmetros são:

  • precisão: O número de dimensões no vetor.
  • scale: O valor da escala, que representa o número de bytes por dimensão. 4 bytes representam um tipo de dado FLOAT32.
  • data: Uma matriz float[] que contém os valores numéricos no vetor.

Exemplo:

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

Preencher e recuperar uma tabela

Aqui estão alguns exemplos de código que preenchem e recuperam dados vetoriais de um banco de dados. Os exemplos pressupõem uma tabela com uma coluna vetorial , definida da seguinte forma:

CREATE TABLE sampleTable (vector_col vector(3))

Insira valores com uma instrução INSERT simples:

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

Insira valores com uma instrução preparada e um parâmetro vetorial :

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();
}

Insira um valor nulo com uma instrução preparada e um parâmetro:

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();
}

Leia os valores vetor de uma tabela:

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 + ")");
        }
    }
}

Usar procedimentos armazenados com vetor

Com o seguinte procedimento armazenado:

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

Retornar um parâmetro de saída vetorial com o seguinte exemplo:

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

Use TVP com vetor

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();
}

Use SQLServerBulkCopy para transferir dados da tabela de origem para a tabela de destino com vetor.

Os vetores podem ser usados em comandos de cópia em massa:

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);
    }

Utilizar bulkCopy do ficheiro csv para a tabela de destino com vetor

Os vetores podem ser importados de arquivos CSV.

Cole o seguinte conteúdo em um arquivo CSV chamado 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);
}

Usar tipo de dados vetor FLOAT16

Vetores FLOAT16 (IEEE 754 meia-precisão, 16 bits) usam 2 bytes por dimensão em vez de 4, reduzindo pela metade a necessidade de armazenamento e permitindo até 3.996 dimensões por vetor (contra 1.998 para FLOAT32) no limite de 8.000 bytes do TDS. Este subtipo é especialmente valioso para cargas de trabalho de IA/ML em grande escala, como pesquisa por similaridade e armazenamento incorporado, onde a eficiência da memória é importante.

O suporte vetorial FLOAT16 é ativado por meio da extensão de funcionalidades vetoriais existente (identificador FE 0x0E) com um handshake de versão 2: o cliente solicita a v2 através da propriedade de conexão vectorTypeSupport, e o servidor reconhece a capacidade FLOAT16 na resposta de reconhecimento de funcionalidades.

Para usar FLOAT16 vetores, siga os mesmos padrões mostrados nos exemplos anteriores e substitua FLOAT32 por FLOAT16 e o valor 4 da escala por 2. Por exemplo:

  • Use Vector.VectorDimensionType.FLOAT16 em vez de Vector.VectorDimensionType.FLOAT32.
  • Use uma escala de 2 em vez de 4 ao construir um vetor com precisão e escala.
  • Defina colunas SQL como vector(3, float16) em vez de vector(3).

Aqui está um exemplo de criação de um objeto vetorial FLOAT16:

// 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});

Compatibilidade com versões anteriores

Se um aplicativo não for atualizado para lidar com o tipo de dados vetoriais , o driver fornece compatibilidade com versões anteriores, permitindo que os tipos de dados vetoriais sejam lidos como tipos compatíveis com versões anteriores. Esse comportamento é controlado com a vectorTypeSupport propriedade de cadeia de conexão. Os valores suportados são off (o servidor envia tipos vetoriais como dados de cadeia em formato JSON), v1 (o servidor envia tipos vetoriais de FLOAT32 como dados vetoriais), e v2 (para permitir suporte a tipos vetoriais para FLOAT16). O valor predefinido é v1.

Limitações do vetor

Para obter limitações detalhadas, consulte Limitações de tipo de dados vetoriais.

Conteúdo relacionado

Noções básicas sobre os tipos de dados do driver JDBC

  • Last updated on