Remarque
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de vous connecter ou de modifier des répertoires.
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de modifier des répertoires.
À compter de la version 13.2.0, le pilote JDBC prend en charge le type de données vectorielles . À compter de la version 13.4.0, le pilote prend également en charge le sous-type vector(float16). Vector est également pris en charge avec des fonctionnalités telles que Table-Valued Parameters et BulkCopy, avec certaines limitations. Cette page présente différents cas d’usage du type de données vectorielles avec le pilote JDBC. Pour obtenir une vue d’ensemble des types de données vectorielles , consultez Le type de données Vector.
Créer un objet vector
La classe microsoft.sql.Vector est une implémentation personnalisée conçue pour représenter des données vectorielles dans le pilote JDBC. Il offre un moyen structuré de gérer des données à grande dimension, notamment la sérialisation et la désérialisation, tout en garantissant la compatibilité avec le type de données vectorielles de SQL Server. L’objet vector doit inclure le nombre d’éléments, d’indicateur de type et de données.
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 pour SQL Server propose deux méthodes d’initialisation d’un objet vectoriel, offrant une flexibilité pour différents cas d’usage et données d’entrée.
Créer un objet vector avec le nombre de dimensions et le type de vecteur
Constructeur:
public Vector(int dimensionCount, VectorDimensionType vectorType, Object[] data);
Exemple :
Vector vector = new Vector(3, Vector.VectorDimensionType.FLOAT32, new Float[]{1.0f, 2.0f, 3.0f});
Créer un objet vectoriel avec précision et mise à l’échelle
Constructeur:
public Vector(int precision, int scale, Object[] data);
Où sont les paramètres :
- précision : nombre de dimensions dans le vecteur.
- scale : valeur d’échelle, qui représente le nombre d’octets par dimension. 4 octets représentent un FLOAT32.
- données : tableau float[] contenant les valeurs numériques dans le vecteur.
Exemple :
Vector vector = new Vector(3, 4, new Float[]{1.0f, 2.0f, 3.0f});
Remplir et récupérer une table
Voici quelques exemples de code qui remplissent et récupèrent des données vectorielles à partir d’une base de données. Les exemples supposent qu’une table avec une colonne vectorielle définie comme suit :
CREATE TABLE sampleTable (vector_col vector(3))
Insérez des valeurs avec une instruction simple INSERT :
try (Statement stmt = connection.createStatement()){
stmt.execute("insert into sampleTable values ('[0.1, 2.0, 3.0]')");
}
Insérez des valeurs avec une instruction préparée et un paramètre vectoriel :
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();
}
Insérez une valeur Null avec une instruction préparée et un paramètre :
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();
}
Lire les valeurs vectorielles d’une table :
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 + ")");
}
}
}
Utiliser des procédures stockées avec un vecteur
Avec la procédure stockée suivante :
String sql = "CREATE PROCEDURE " + inputProc +
" @p0 VECTOR(3) OUTPUT AS " +
" SELECT TOP 1 @p0 = col_vector FROM sampleTable ";
Retourne un paramètre de sortie vectorielle avec l’exemple suivant :
try (CallableStatement callableStatement = con.prepareCall("{call " + inputProc + " (?) }")) {
callableStatement.registerOutParameter(1, microsoft.sql.Types.VECTOR, 3, 4);
callableStatement.execute();
}
À partir de la version 13.6, la surcharge nommée SQLServerCallableStatement.setObject(String, Object, int, int) et sa forceEncrypt variante préservent le nombre de dimensions vectorielles fournies par le quatrième argument.
Utiliser TVP avec vecteur
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();
}
À partir de la version 13.6, le pilote valide le support vectoriel négocié avant d’écrire les métadonnées de colonnes TVP. Un vecteur FLOAT16 nécessite vectorTypeSupport=v2 un serveur qui négocie la version 2 du vecteur. Le pilote rejette les valeurs TVP FLOAT16 sur une connexion de version 1 et rejette toutes les valeurs TVP vectorielles natives lorsque vectorTypeSupport=off.
Utiliser SQLServerBulkCopy à partir d’une table source vers une table de destination avec un vecteur
Les vecteurs peuvent être utilisés dans les commandes de copie en bloc :
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);
}
Utiliser bulkCopy à partir d’un fichier csv vers une table de destination avec vecteur
Les vecteurs peuvent être importés à partir de fichiers CSV.
Collez le contenu suivant dans un fichier CSV nommé 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);
}
Utiliser le type de données vecteur FLOAT16
FLOAT16 (IEEE 754 demi-précision, 16 bits) utilisent 2 octets par dimension au lieu de 4, réduisant ainsi l’empreinte de stockage et permettant jusqu’à 3 996 dimensions par vecteur (contre 1 998 pour FLOAT32) dans la limite de 8 000 octets du TDS. Ce sous-type est particulièrement utile pour les charges de travail IA/ML à grande échelle, telles que la recherche de similarité et l’incorporation du stockage où l’efficacité de la mémoire est importante.
La prise en charge des vecteurs FLOAT16 est activée via l’extension de fonctionnalité vectorielle existante (identificateur FE 0x0E) avec une procédure d'entente de version 2 : le client demande v2 via la propriété de connexion vectorTypeSupport, et le serveur reconnaît la fonctionnalité FLOAT16 dans la réponse de fonctionnalité.
Pour utiliser FLOAT16 vecteurs, suivez les mêmes modèles présentés dans les exemples précédents et remplacez FLOAT32 par FLOAT16 et la valeur 4 d’échelle par 2. Par exemple:
- Utilisez
Vector.VectorDimensionType.FLOAT16au lieu deVector.VectorDimensionType.FLOAT32. - Utilisez une échelle de
2plutôt que de4lors de la construction d'un vecteur avec précision et échelle. - Définissez des colonnes SQL en tant que
vector(3, float16)au lieu devector(3).
Voici un exemple de création d’un objet vectoriel 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});
Convertir entre vecteurs FLOAT16 et FLOAT32
Sur les serveurs qui supportent la conversion vectorielle cross-type, SQL Server peut convertir implicitement ou explicitement entre FLOAT16 et FLOAT32 vecteurs. Par exemple:
INSERT INTO float32Table (vector_col)
SELECT vector_col FROM float16Table;
SELECT CAST(vector_col AS VECTOR(3, float32))
FROM float16Table;
SELECT CONVERT(VECTOR(3, float16), vector_col)
FROM float32Table;
Les vecteurs source et destination doivent avoir le même nombre de dimensions. Convertir de FLOAT32 en FLOAT16 peut perdre en précision car FLOAT16 a une plage représentable plus petite et moins de bits significatifs. Les valeurs nulles restent nulles après conversion. Ces conversions s’appliquent également aux affectations effectuées via des instructions préparées, des paramètres de procédures stockées, des paramètres de type table et la copie en masse.
Compatibilité descendante
Si une application n’est pas mise à jour pour gérer le type de données vectorielles , le pilote assure une compatibilité descendante en autorisant les types de données vectorielles à lire en tant que types compatibles descendants. Ce comportement est contrôlé avec la propriété de connexion de chaîne vectorTypeSupport.
Les valeurs prises en charge sont off (le serveur envoie des types de vecteurs en tant que données de chaîne au format JSON), v1 (le serveur envoie des types de vecteurs de FLOAT32 en tant que données vectorielles) et v2 ( pour activer la prise en charge des types de vecteurs pour FLOAT16). La valeur par défaut est v1.
Limitations du vecteur
Pour obtenir des limitations détaillées, consultez limitations du type de données Vector.