JDBC ドライバーでベクターデータ型を使用する

JDBC ドライバーのダウンロード

バージョン 13.2.0 以降、JDBC ドライバーは ベクター データ型をサポートしています。バージョン 13.4.0 以降では、ドライバーは vector(float16) サブタイプもサポートしています。 ベクター は、Table-Valued パラメーターや BulkCopy などの機能でもサポートされており、いくつかの制限があります。このページでは、JDBC Driver を使用した ベクター データ型のさまざまなユースケースを示します。 ベクター データ型の概要については、ベクターデータ型に関するページを参照してください。

ベクターオブジェクトを作成する

microsoft.sql.Vector クラスは、JDBC ドライバーのベクターデータを表すように設計されたカスタム実装です。これは、SQL Server の ベクター データ型との互換性を確保しながら、シリアル化や逆シリアル化を含む高次元データを処理するための構造化された方法を提供します。ベクターオブジェクトには、要素の数、型インジケーター、およびデータを含める必要があります。

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 Driver for SQL Server には、ベクターオブジェクトを初期化する 2 つの方法が用意されており、さまざまなユースケースと入力データに柔軟性を提供します。

次元数とベクトル型を持つベクターオブジェクトを作成する

コンストラクタ：

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

例:

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

精度とスケールを使用してベクターオブジェクトを作成する

コンストラクタ：

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

パラメーターは次のとおりです。

precision: ベクトル内の次元の数。
scale: ディメンションあたりのバイト数を表すスケール値。 4 バイトはFLOAT32を表します。
data: ベクトル内の数値を含む float[] 配列。

例:

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

テーブルへのデータ入力と取得

データベースから ベクター データを設定および取得するコード例をいくつか次に示します。この例では、次のように定義された ベクター 列を持つテーブルを想定しています。

CREATE TABLE sampleTable (vector_col vector(3))

単純な INSERT ステートメントを使用して値を挿入します。

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

準備されたステートメントと ベクター パラメーターを使用して値を挿入します。

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

準備されたステートメントとパラメーターを使用して null 値を挿入します。

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

テーブルから ベクター 値を読み取ります。

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

ベクターでストアドプロシージャを使用する

次のストアドプロシージャを使用します。

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

次の例を使用して 、ベクター 出力パラメーターを返します。

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

ベクターで TVP を使用する

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

SQLServerBulkCopy とベクターを使用してソーステーブルから変換先テーブルに移行する

ベクターは、一括コピーコマンドで使用できます。

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

ベクターを用いてCSVファイルから宛先テーブルにbulkCopyを行う

ベクターは CSV ファイルからインポートできます。

次の内容を、 vectors.csvという名前の 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);
}

ベクター FLOAT16データ型を使用する

FLOAT16 (IEEE 754 の半精度、16 ビット) ベクターでは、4 ではなくディメンションあたり 2 バイトを使用し、ストレージフットプリントを半減させ、8,000 バイトの TDS 制限内でベクターあたり最大 3,996 次元 (FLOAT32 の場合は 1,998) を有効にします。このサブタイプは、類似性検索やメモリ効率が重要なストレージの埋め込みなど、大規模な AI/ML ワークロードに特に価値があります。

FLOAT16ベクターサポートは、バージョン 2 ハンドシェイクを使用して既存のベクター機能拡張 (FE 識別子0x0E) を介して有効になります。クライアントは vectorTypeSupport 接続プロパティを介して v2 を要求し、サーバーは feature-ack 応答でFLOAT16機能を確認します。

FLOAT16ベクトルを使用するには、前の例と同じパターンに従い、FLOAT32をFLOAT16に置き換え、スケール値を4に2します。例えば次が挙げられます。

Vector.VectorDimensionType.FLOAT16の代わりに Vector.VectorDimensionType.FLOAT32 を使用します。
精度と小数点以下桁数でベクトルを構築する場合は、2の代わりに4のスケールを使用します。
SQL列をvector(3, float16)として定義し、vector(3)ではなく。

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

下位互換性

アプリケーションがベクター データ型を処理するように更新されていない場合、ドライバーは、ベクター データ型を下位互換性のある型として読み取ることができるようにすることで、下位互換性を提供します。この動作は、 vectorTypeSupport 接続文字列プロパティを使用して制御されます。サポートされる値は、 off (サーバーは JSON 形式で ベクター型を 文字列データとして送信)、 v1 (サーバーはベクターデータとしてFLOAT32の ベクター 型を送信)、 v2 (FLOAT16の ベクター 型のサポートを有効にする) です。既定値は v1 です。

ベクターの制限事項

詳細な制限事項については、ベクターデータ型の制限事項に関する記事を参照してください。

JDBC ドライバーのデータ型について

フィードバック

このページはお役に立ちましたか?

Last updated on 2026-03-18

次の方法で共有

JDBC ドライバーでベクター データ型を使用する

ベクター オブジェクトを作成する

次元数とベクトル型を持つベクター オブジェクトを作成する

精度とスケールを使用してベクター オブジェクトを作成する