Tipo di dati Vector (ODBC)

Questo articolo illustra il tipo di dati SQL vettoriale implementato da Microsoft ODBC Driver per SQL Server a partire dalla versione 18.6.1.1. Questo documento descrive il comportamento del driver Microsoft per il vettore e fornisce indicazioni sull'utilizzo, note specifiche dell'API e frammenti di codice. Per una panoramica dei tipi di dati vettoriali, vedere Tipo di dati Vector.

Informazioni generali

Microsoft ODBC Driver per SQL Server supporta in modo nativo il tipo di dati vector . Le applicazioni possono archiviare, recuperare ed elaborare in modo efficiente incorporamenti numerici a dimensione fissa comunemente usati nei carichi di lavoro di Machine Learning e intelligenza artificiale. Il driver espone il supporto vettoriale tramite API ODBC standard e tipi di dati C. Le applicazioni possono interagire con le colonne vettoriali di SQL Server senza modificare i flussi di lavoro ODBC esistenti.

Si applica a: Microsoft ODBC Driver per SQL Server 18.6.1.1 e versioni successive. Il supporto per il float16 tipo base richiede la versione 18.7.1.1 o successiva.

Il supporto vettoriale è disabilitato di default e deve essere esplicitamente abilitato.

Tipi di elementi base

Una colonna vettoriale dichiara un tipo di elemento base. Il driver supporta entrambi i tipi definiti da SQL Server.

float32 è l'impostazione predefinita. Per usare l'archiviazione a mezza precisione, dichiarare la colonna o il parametro come VECTOR(<dimensions>, float16). Poiché un float16 elemento occupa metà dei byte sul filo, un float16 vettore contiene il doppio delle dimensioni all'interno dello stesso limite di payload di 8.000 byte.

Poiché float16 ha meno bit di mantissa rispetto a float32, un giro di andata e ritorno attraverso una float16 colonna è con perdita. I valori vengono arrotondati al valore di mezza precisione rappresentabile più vicino all'inserimento, e il valore letto a ritorno è l'espansione float32 di quel valore arrotondato.

Sul server, float16 è necessario SQL Server 2025 (17.x) con la PREVIEW_FEATURES configurazione con ambito del database abilitata. Per ulteriori informazioni, vedere Supporto a virgola mobile a bassa precisione nel tipo di dati vettore.

Rappresentazione C nativa

Quando il supporto vettoriale è abilitato, le colonne vettoriali vengono scambiate usando una struttura C tipizzata denominata SQL_SS_VECTOR_STRUCT.

    typedef enum
    {
        SQL_VECTOR_TYPE_FLOAT32 = 0,  /* 32-bit floating point */
        SQL_VECTOR_TYPE_FLOAT16 = 1   /* 16-bit floating point */
    } SQLVECTORTYPE;

    typedef struct tagSS_VECTOR_STRUCT {
        SQLSMALLINT   dimension;  /* Number of elements */
        SQLVECTORTYPE type;       /* Element base type indicator */
        union data {
            float* f32;           /* Pointer to float32 data */
            float* f16;           /* Pointer to float16 data */
        } data;
    } SQL_SS_VECTOR_STRUCT;

• dimension: descrive il numero di elementi nel vettore
• type: identifica il tipo di elemento base, SQL_VECTOR_TYPE_FLOAT32 oppure SQL_VECTOR_TYPE_FLOAT16
• data.f32 / data.f16: punta al buffer dell'applicazione contenente i valori vettoriali

Entrambi i membri dell'unione sono dichiarati come float* e sono intercambiabili, perché il buffer lato client contiene float32 valori per ciascun tipo base. Usa il membro che documenta la tua intenzione.

Abilitare il supporto vettoriale

La vectorTypeSupport parola chiave stringa di connessione seleziona il livello di supporto vettoriale nativo che la connessione negozia.

Puoi anche impostare il livello dopo aver allocato la handle di connessione, e prima di connetterti, con l'attributo SQL_COPT_SS_VECTOR_TYPE_SUPPORT pre-connessione.

• Il driver Microsoft espone un binding SQL_C_SS_VECTOR C specifico per driver e supporta SQL_C_BINARY l'output vettoriale. In pratica:

  • Quando abiliti vectorTypeSupport=v1 o v2, le API di recupero (ad esempio, SQLGetData e SQLBindCol) possono restituire colonne vettoriali come o SQL_C_SS_VECTORSQL_C_BINARY. SQL_C_SS_VECTOR restituisce il vettore in una forma compatta e tipizzata. SQL_C_BINARY restituisce un payload varbinary.

  • Per il binding di input o parametri, il driver supporta sia SQL_C_SS_VECTOR che SQL_C_BINARY. SQL_C_SS_VECTOR fornisce un'associazione di input tipizzata e compatta. SQL_C_BINARY è equivalente e portabile. Usare SQL_C_SS_VECTOR quando si vuole che il driver consideri il payload come un tipo di vettore nativo.

  • Quando vectorTypeSupport=off, le colonne vettoriali vengono visualizzate come varchar(max) contenenti matrici JSON.

v2 è un superinsieme di v1, quindi una connessione negoziata in v2 gestisce float32 le colonne esattamente come v1 fa. Inviare un float16 valore su una connessione negoziata in v1 fallisce con Requested vector base type is not supported for the negotiated vector version. Usa v2 ogni volta che l'applicazione può incontrare una float16 colonna.

Le applicazioni devono anche impostare la versione ODBC su ODBC 3.8 prima di usare tipi specifici del vettore:

    SQLSetEnvAttr(
    hEnv,
    SQL_ATTR_ODBC_VERSION,
    (SQLPOINTER)SQL_OV_ODBC3_80,
    0);

Formati di associazione supportati

Associazione vettoriale nativa

Tipo C: SQL_C_SS_VECTOR

Questo formato è consigliato per le applicazioni critiche per le prestazioni.

Collegamento binario

Tipo C: SQL_C_BINARY

I vettori vengono restituiti usando lo stesso layout di SQL_C_SS_VECTOR. Le applicazioni possono usare questo formato per scenari di interoperabilità di basso livello. Il buffer del puntatore dati può essere contiguo o non contiguo con l'indirizzo di memoria della struttura.

Linee guida per l'API ODBC

Questa sezione descrive in che modo le API ODBC interagiscono con i dati vettoriali di SQL Server, inclusi i requisiti di layout del buffer, NULL la gestione e le rappresentazioni di dati supportate. Tutti i comportamenti si applicano quando vectorTypeSupport è impostato su v1 o v2 e l'ambiente è configurato per ODBC 3.8.

Ogni formula della dimensione del buffer in questa sezione usa sizeof(float) per elemento per entrambi i tipi di base, perché il buffer lato client contiene float32 sempre i valori. Una float16 colonna cambia i byte sul filo, non la disposizione del buffer.

SQLBindCol

Usare SQLBindCol per associare colonne vettoriali in un set di risultati ai buffer dell'applicazione.

• Chiamata tipica:

    SQLRETURN SQLBindCol(
      SQLHSTMT       StatementHandle,
      SQLUSMALLINT   ColumnNumber,
      SQLSMALLINT    TargetType,
      SQLPOINTER     TargetValuePtr,
      SQLLEN         BufferLength,
      SQLLEN *       StrLen_or_IndPtr);

• TargetType: usare SQL_C_SS_VECTOR o SQL_C_BINARY.

• TargetValuePtr: puntatore a un SQL_SS_VECTOR_STRUCT con una matrice float quando TargetType è SQL_C_SS_VECTOR; in caso contrario, puntatore a un buffer con dimensione pari al valore in StrLen_or_IndPtr.

• BufferLength: sizeof(SQL_SS_VECTOR_STRUCT) + il numero di byte allocati per il buffer di colonna (dimensione * 4).

• StrLen_or_IndPtr: puntatore che riceve la lunghezza in byte del vettore restituito (SQL_DESC_OCTET_LENGTH). Il valore è sizeof(SQL_SS_VECTOR_STRUCT) + le dimensioni della matrice float (dimensione * 4).

Queste dimensioni sono le stesse per una float16 colonna. Il driver espande ogni elemento di mezza precisione a float a man mano che riempie il buffer, e segnala la lunghezza espansa.

Aspettative del layout del buffer

Buffer non contiguo (scelta consigliata)

• L'applicazione alloca una SQL_SS_VECTOR_STRUCT per riga.
• L'applicazione alloca memoria per data.f32.
• Il driver popola i metadati vettoriali e scrive i valori degli elementi nel buffer float fornito.

    SQLLEN numberOfRow = 1000; // set to SQL_ATTR_ROW_ARRAY_SIZE
    SQLULEN columnSize = x; // use SQLDescribeCol or SQLColAttributeW or sizeof(SQL_SS_VECTOR_STRUCT) + (dimension * 4)
    SQL_SS_VECTOR_STRUCT vecBuffer[numberOfRow]
    std::vector<SQLLEN> indicator(numberOfRow, 0);
    for (int i = 0; i < numberOfRow; i++)
    {
        vecBuffer[i].dimension = static_cast<SQLUSMALLINT>((columnSizes[col - 1] - sizeof(SQL_SS_VECTOR_STRUCT)) / 4);
        vecBuffer[i].type = SQL_VECTOR_TYPE_FLOAT32; // or SQL_VECTOR_TYPE_FLOAT16
        vecBuffer[i].data.f32 = (float*)malloc(vecBuffer[i].dimension * sizeof(float));
        if (!vecBuffer[i].data.f32) {
            std::cerr << "Memory allocation failed for vector data." << std::endl;
            return SQL_ERROR;
        }
    }
    SQLBindCol(hStmt, col, SQL_C_SS_VECTOR, vecBuffer, columnSize, indicators.data());

Buffer contiguo

• L'applicazione alloca un singolo buffer e ODBC lo riempie di conseguenza.
• La matrice float deve iniziare immediatamente dopo lo struct.
• Il driver imposta data.f32 in modo che punti a questa area contigua.

    SQLLEN numberOfRow = 1000; // set to SQL_ATTR_ROW_ARRAY_SIZE
    SQLULEN columnSize = x; // use SQLDescribeCol or SQLColAttributeW or sizeof(SQL_SS_VECTOR_STRUCT) + (dimension * 4)
    std::vector<BYTE> vecBuffer;
    std::vector<SQLLEN> indicator(numberOfRow, 0);
    vecBuffer.resize(numberOfRow * columnSize);
    SQLBindCol(hStmt, col, SQL_C_BINARY, vecBuffer.data(), columnSize, indicators.data());

Gestione NULL per SQLBindCol

Quando il valore della colonna è NULL, il driver imposta *StrLen_or_IndPtr su SQL_NULL_DATA e non popola il buffer. Controllare sempre l'indicatore prima di accedere al contenuto del vettore.

SQLGetData

Usare SQLGetData per recuperare i dati vettoriali da colonne non vincolate.

• Chiamata tipica:

    SQLRETURN SQLGetData(
      SQLHSTMT       StatementHandle,
      SQLUSMALLINT   Col_or_Param_Num,
      SQLSMALLINT    TargetType,
      SQLPOINTER     TargetValuePtr,
      SQLLEN         BufferLength,
      SQLLEN *       StrLen_or_IndPtr);

• TargetType: usare SQL_C_SS_VECTOR o SQL_C_BINARY.

• TargetValuePtr: puntatore a un SQL_SS_VECTOR_STRUCT con una matrice float quando TargetType è SQL_C_SS_VECTOR; in caso contrario, puntatore a un buffer con dimensione pari al valore in StrLen_or_IndPtr.

• BufferLength: sizeof(SQL_SS_VECTOR_STRUCT) + il numero di byte allocati per il buffer di colonna (dimensione * 4).

• StrLen_or_IndPtr: puntatore che riceve la lunghezza in byte del vettore restituito (SQL_DESC_OCTET_LENGTH). Il valore è sizeof(SQL_SS_VECTOR_STRUCT) + le dimensioni della matrice float (dimensione * 4).

L'estrazione in blocchi non è supportata. È necessario recuperare l'intero vettore in una sola chiamata.

Esempio ( vettore nativo):

    SQLLEN dataLen = 0;
    SQL_SS_VECTOR_STRUCT vec = {};
    vec.data.f32 = (float*)malloc(x * sizeof(float)); // x is the dimension
    if (!vec.data.f32) {
        std::cerr << "Memory allocation failed for vector data." << std::endl;
        return SQL_ERROR;
    }
    SQLGetData(hStmt, col, SQL_C_SS_VECTOR, &vec, sizeof(vec) + sizeof(float) * vec.dimension, &dataLen);

La gestione dei NULL per SQLGetData

Quando il valore della colonna è NULL, il driver imposta *StrLen_or_IndPtr su SQL_NULL_DATA e non popola il buffer. Controllare sempre l'indicatore prima di accedere al contenuto del vettore.

SQLFetch

Usare SQLFetch per recuperare la riga successiva e rappresentare correttamente le colonne legate SqlVector.

• Chiamata tipica:

    SQLRETURN SQLFetch(
     SQLHSTMT     StatementHandle);

Chiamare SQLFetch nel ciclo standard con SqlVector colonne già associate tramite SQLBindCol. In alternativa, usare SQLGetData per recuperare i dati nel buffer dell'applicazione.

Esempio ( vettore nativo):

    while ((ret = SQLFetch(hStmt)) == SQL_SUCCESS || ret == SQL_SUCCESS_WITH_INFO) {
        // if SQLBindCol was used directly jump to read buffer
        // else use SQLGetData and than read buffer.
        std::cout << "  data: [";
        if (dataLen != SQL_NULL_DATA)
        {
            for (SQLUSMALLINT d = 0; d < vec.dimension; ++d) {
                std::cout << vec.data.f32[d];
                if (d + 1 < vec.dimension) std::cout << ", ";
            }
        }
        std::cout << "]" << std::endl;
    }

SQLFetchScroll

Utilizzare SQLFetchScroll per recuperare set di righe in base a un orientamento specificato (successivo, precedente, assoluto, relativo, segnalibro). Il driver copia correttamente i dati vettoriali nei buffer dell'applicazione.

• Chiamata tipica:

    SQLRETURN SQLFetchScroll(
      SQLHSTMT      StatementHandle,
      SQLSMALLINT   FetchOrientation,
      SQLLEN        FetchOffset);

Esempio ( vettore nativo):

    // Fetch rows in batches
    while ((ret = SQLFetchScroll(hStmt, SQL_FETCH_NEXT, 0)) != SQL_NO_DATA) {
        for (SQLULEN i = 0; i < numRowsFetched; i++) {
            // In case of Contiguous Buffer
                SQL_SS_VECTOR_STRUCT* vecptr = reinterpret_cast<SQL_SS_VECTOR_STRUCT*>(
                vecBuffer.data() + (i * columnSizes[col - 1]));
                float* floats = reinterpret_cast<float*>(
                reinterpret_cast<char*>(vecptr) + sizeof(SQL_SS_VECTOR_STRUCT)
            );
            // in Case of non-contiguous Buffer
            SQL_SS_VECTOR_STRUCT* vecptr = &vecBuffer[i];
            float* floats = vecptr->data.f32;

            if (indicators[i] != SQL_NULL_DATA)
            {
                for (SQLUSMALLINT d = 0; d < vecptr->dimension; ++d) {
                    std::cout << floats[d];
                    if (d + 1 < vecptr->dimension) std::cout << ", ";
                }
            }
            std::cout << "]" << std::endl;
        }
    }

SQLBindParameter

Usare SQLBindParameter per inviare valori vettoriali a SQL Server.

• Chiamata tipica:

    SQLRETURN SQLBindParameter(
        SQLHSTMT        StatementHandle,
        SQLUSMALLINT    ParameterNumber,
        SQLSMALLINT     InputOutputType,
        SQLSMALLINT     ValueType,
        SQLSMALLINT     ParameterType,
        SQLULEN         ColumnSize,
        SQLSMALLINT     DecimalDigits,
        SQLPOINTER      ParameterValuePtr,
        SQLLEN          BufferLength,
        SQLLEN *        StrLen_or_IndPtr);

• ParameterValuePtr: punta a un SQL_SS_VECTOR_STRUCT popolato
• ColumnSize: ignorato nei parametri di input. Per i parametri di output e gli scenari di data-at-execution, specificare le dimensioni totali del vettore: sizeof(SQL_SS_VECTOR_STRUCT) + (dimensioni della matrice float )
• DecimalDigits: ignorato nei parametri di input. Per i parametri di output e gli scenari di data-at-execution, specificare il tipo di base vettoriale
• BufferLength: ≥ sizeof(SQL_SS_VECTOR_STRUCT) + (dimensione * sizeof(float))
• *StrLen_or_IndPtr: deve contenere la stessa dimensione totale

Da dove proviene il tipo base

Il driver legge il tipo di elemento base da un punto diverso a seconda della direzione del parametro. Sbagliare questo è la causa più comune di Invalid vector dimension errori Provided buffer length too small/large su un float16 parametro.

Per un parametro di input, BufferLength deve essere uguale sizeof(SQL_SS_VECTOR_STRUCT) esattamente a + (dimensione * sizeof(float)). Un valore maggiore o più piccolo fallisce invece di essere tollerato.

Esempio ( vettore nativo, float32):

    float values[3] = {1.0f, 2.0f, 3.0f};
    SQL_SS_VECTOR_STRUCT vec;
    SQLLEN cb;

    vec.dimension = 3;
    vec.type = SQL_VECTOR_TYPE_FLOAT32;
    vec.data.f32 = values;

    cb = sizeof(vec) + sizeof(values);

    SQLBindParameter(
        hStmt, 1, SQL_PARAM_INPUT, SQL_C_SS_VECTOR, SQL_SS_VECTOR, 0, 0, &vec, cb, &cb);

Esempio ( vettore nativo, float16):

Solo il type campo cambia. L'array di valori rimane un float array ed cb è calcolato allo stesso modo.

    float values[3] = {1.0f, 2.0f, 3.0f};
    SQL_SS_VECTOR_STRUCT vec;
    SQLLEN cb;

    vec.dimension = 3;
    vec.type = SQL_VECTOR_TYPE_FLOAT16;
    vec.data.f16 = values; /* still a float32 array */

    cb = sizeof(vec) + sizeof(values);

    SQLBindParameter(
        hStmt, 1, SQL_PARAM_INPUT, SQL_C_SS_VECTOR, SQL_SS_VECTOR, 0, 0, &vec, cb, &cb);

Esempio (float16 parametro di uscita):

Un parametro di output puro non porta struttura in ingresso, quindi il tipo base viene passato in DecimalDigits e la dimensione deriva da ColumnSize.

    SQL_SS_VECTOR_STRUCT vec = {};
    float values[3] = {};
    vec.data.f16 = values;

    SQLULEN columnSize = sizeof(SQL_SS_VECTOR_STRUCT) + 3 * sizeof(float);
    SQLLEN cb = (SQLLEN)columnSize;

    SQLBindParameter(
        hStmt, 1, SQL_PARAM_OUTPUT, SQL_C_SS_VECTOR, SQL_SS_VECTOR,
        columnSize, SQL_VECTOR_TYPE_FLOAT16, &vec, cb, &cb);

Gestione NULL per SQLBindParameter

Le applicazioni possono indicare un vettore usando uno NULL dei due approcci supportati:

• Impostare *StrLen_or_IndPtr a SQL_NULL_DATA e passare NULL come ParameterValuePtr

• Specificare un oggetto SQL_SS_VECTOR_STRUCT con:

  Tipo di set di dimensione impostato al tipo base della colonna data.f32 = NULL

SQLPutData

Il driver supporta SQLPutData per i parametri vettoriali con questi vincoli:

• È necessario specificare l'intero vettore nella prima chiamata.

• Il driver non supporta la trasmissione di vettori in blocchi o incrementali.

• NULL la gestione segue le stesse regole di SQLBindParameter.

• Chiamata tipica:

    SQLRETURN SQLPutData(
        SQLHSTMT     StatementHandle,
        SQLPOINTER   DataPtr,
        SQLLEN       StrLen_or_Ind);

• DataPtr: punta a un SQL_SS_VECTOR_STRUCT popolato
• StrLen_or_Ind: sizeof(SQL_SS_VECTOR_STRUCT) + (dimensione * sizeof(float))

Esempio ( vettore nativo):

    std::vector<float> floatArray = { 1.0f, 2.0f, 3.0f };

    SQL_SS_VECTOR_STRUCT vectorValue = {0};
    vectorValue.type = SQL_VECTOR_TYPE_FLOAT32; // or SQL_VECTOR_TYPE_FLOAT16
    vectorValue.dimension = (SQLUSMALLINT)floatArray.size();
    vectorValue.data.f32 = floatArray.data();

    // Tell ODBC this parameter will be supplied at execution time
    SQLLEN cbVectorLen = SQL_LEN_DATA_AT_EXEC(
        (SQLLEN)(sizeof(SQL_SS_VECTOR_STRUCT) + floatArray.size() * sizeof(float))
    );

    // Optional token to identify which parameter needs data
    SQLPOINTER token = (SQLPOINTER)1;

    // Bind as DATA_AT_EXEC: BufferLength is 0, value pointer can be a token
    SQLRETURN rc = SQLBindParameter(hStmt, 1, SQL_PARAM_INPUT, SQL_C_SS_VECTOR, SQL_SS_VECTOR, 0, 0, token, 0, &cbVectorLen);

    if (rc != SQL_SUCCESS && rc != SQL_SUCCESS_WITH_INFO) {
        // handle error
    }

    rc = SQLExecute(hStmt);
    if (rc != SQL_SUCCESS && rc != SQL_SUCCESS_WITH_INFO && rc != SQL_NEED_DATA) {
        // handle error
    }

    SQLPOINTER pParamToken = NULL;
    rc = SQLParamData(hStmt, &pParamToken);

    if (rc == SQL_NEED_DATA) {
        // Provide entire vector in first SQLPutData call (no chunking)
        rc = SQLPutData(
            hStmt,
            (SQLPOINTER)&vectorValue,
            (SQLLEN)(sizeof(SQL_SS_VECTOR_STRUCT) + floatArray.size() * sizeof(float))
        );

        if (rc != SQL_SUCCESS && rc != SQL_SUCCESS_WITH_INFO) {
            // handle error
        }

        // Finalize parameter transfer
        rc = SQLParamData(hStmt, &pParamToken);
    }

Metadati del descrittore

Quando si abilita il supporto vettoriale, Microsoft ODBC Driver per SQL Server espone i metadati vettoriali tramite API del descrittore ODBC standard. Le applicazioni possono usare informazioni sul descrittore per individuare i dettagli dello schema vettoriale, le dimensioni del buffer di calcolo e configurare correttamente le associazioni per parametri e set di risultati.

Valori dei campi del descrittore per vector

La tabella seguente riepiloga i valori dei campi del descrittore per le colonne vettoriali e i parametri di SQL Server.

SQL_DESC_LENGTH, SQL_DESC_OCTET_LENGTH, e SQL_DESC_PRECISION tutti descrivono il buffer lato client, quindi riportano sizeof(SQL_SS_VECTOR_STRUCT) + (dimensione * sizeof(float)) per una float16 colonna oltre che per uno float32 . I due differiscono solo per il numero di byte che SQL Server memorizza e trasmette.

SQL_DESC_SCALE è l'unico campo descrittivo che distingue i tipi base. Leggerlo è il modo in cui un'applicazione scopre se una colonna è float32 o float16.

SQLColAttribute per dimensione vettoriale

A partire dalla versione 18.7.1.1, SQL_CA_SS_VECTOR_DIMENSION restituisce direttamente il conteggio degli elementi di una colonna vettoriale, così un'applicazione non deve più derivarlo da un campo di lunghezza:

    SQLLEN dimension = 0;
    SQLColAttribute(hStmt, col, SQL_CA_SS_VECTOR_DIMENSION, NULL, 0, NULL, &dimension);

    SQLLEN baseType = 0;
    SQLColAttribute(hStmt, col, SQL_DESC_SCALE, NULL, 0, NULL, &baseType);
    /* baseType is SQL_VECTOR_TYPE_FLOAT32 or SQL_VECTOR_TYPE_FLOAT16 */

Puoi anche impostare SQL_CA_SS_VECTOR_DIMENSION un descrittore applicativo o un parametro vettoriale sull'IPD. Impostandolo su qualsiasi altro tipo di parametro restituisce un errore di campo descrittore non valido.

SQLDescribeCol

Quando si chiama SQLDescribeCol per una colonna vettoriale :

• DataType è SQL_SS_VECTOR
• ColumnSize corrisponde a SQL_DESC_PRECISION
• DecimalDigits è l'indicatore del tipo di elemento base, non una scala numerica: 0 per float32 e 1 per float16
• Nullable è SQL_NULLABLE

Le dimensioni della colonna segnalata rappresentano le dimensioni del payload del vettore nativo: sizeof(SQL_SS_VECTOR_STRUCT) + (dimensione * sizeof(float))

SQLDescribeParam

Quando si usa SQLDescribeParam per un parametro vector :

• DataType è SQL_SS_VECTOR
• ColumnSize è uguale alla dimensione del payload del vettore nativo
• DecimalDigits è l'indicatore del tipo di elemento base, non una scala numerica: 0 per float32 e 1 per float16
• Nullable è SQL_NULLABLE

Queste informazioni consentono alle applicazioni di allocare correttamente i buffer dei parametri prima dell'associazione.

SQLColAttribute

• Usare SQLColAttribute(hstmt, ColumnNumber, SQL_DESC_OCTET_LENGTH, ...) per ottenere la lunghezza esatta dei byte del payload del vettore. SQL_DESC_LENGTH e SQL_DESC_PRECISION possono contenere valori specifici del driver. Per il conteggio dei byte, preferire SQL_DESC_OCTET_LENGTH.

  • NULL handling: quando una colonna è NULL, SQLColAttribute (o l'oggetto StrLen_or_IndPtr usato con SQLBindCol) restituisce SQL_NULL_DATA. Verificare la presenza di SQL_NULL_DATA prima di usare le lunghezze o i buffer restituiti.

Copia massiva (BCP)

È possibile importare ed esportare in blocco le colonne vettoriali tramite file BCP e l'API bcp_bind , proprio come altri tipi di dati. Attualmente, l'importazione e l'esportazione di vettori supporta solo il formato nativo (SQLVECTOR) o varbinary (SQLBINARY), ma non il formato carattere. La conversione tra il tipo di vettore e il tipo di carattere non è supportata.

La copia in blocco rispetta lo stesso livello di supporto del resto del pilota. Una float16 colonna richiede una connessione negoziata in vectorTypeSupport=v2. Nell'utilità bcp , usa -z0 per float32 e -z1 per float16. Per altre informazioni, vedere utilità bcp.

Per altre informazioni sul token di tipo, sulla lunghezza predefinita del prefisso e sulla lunghezza predefinita del campo per vector, vedere Tipo di archiviazione file, Lunghezza prefisso e Lunghezza campo.

bcp_gettypename

Quando si usa bcp_gettypename per ottenere il nome del tipo SQL del vettore, restituisce il token di tipo BCP (SQLVECTOR) e "vector".

bcp_bind

Usare bcp_bind per inserire in blocco le variabili di programma in una colonna vettoriale .

Chiamata tipica:

RETCODE bcp_bind (
        HDBC hdbc,
        LPCBYTE pData,
        INT cbIndicator,
        DBINT cbData,
        LPCBYTE pTerm,
        INT cbTerm,
        INT eDataType,
        INT idxServerCol);

• pData: se cbIndicator è zero, contiene un puntatore ai SQL_SS_VECTOR_STRUCT dati, con dati di matrice float al suo interno (vectorStruct.data.f32 campo). Se cbIndicator è diverso da zero, l'indicatore viene visualizzato in memoria direttamente prima dei dati. Quindi pData è un puntatore a un buffer che inizia con cbIndicator byte di indicatore di lunghezza, seguito da una struct vettoriale.
• cbData: se specificato, deve avere un valore esattamente uguale a - sizeof(SQL_SS_VECTOR_STRUCT) + ( *sizeof(float) dimensione). In caso contrario, si verifica un errore. Questo vale per entrambi i tipi di base, perché il buffer vincente mantiene float32 valori in entrambi i sensi.
• eDataType: SQLVECTOR o SQLBINARY

Imposta il type campo della struttura al tipo base della colonna. Per una float16 colonna, il driver converte l'array limitato float32 a metà precisione mentre costruisce il payload del filo, quindi un file dati scritto in formato nativo contiene due byte per elemento.

Quando si importano dati in una colonna vettoriale tramite bcp_bind, impostare eDataType su SQLVECTOR o SQLBINARY. In entrambi i casi, è necessario fornire dati sotto forma di SQL_SS_VECTOR_STRUCT.

Risoluzione dei problemi e suggerimenti

• Se SQLGetTypeInfo non elenca VECTOR, utilizzare il fallback per archiviare i vettori come varchar.
• Requested vector base type is not supported for the negotiated vector version. significa che un float16 valore è stato usato su una connessione negoziata in vectorTypeSupport=v1. Riconnettiti con v2.
• Provided buffer length too small/large. significa BufferLength che non corrispondeva sizeof(SQL_SS_VECTOR_STRUCT) esattamente a + (dimensione * sizeof(float)). Controlla che il buffer sia dimensionato con sizeof(float) invece che con due byte per elemento, anche per una float16 colonna.
• Invalid vector dimension significa che la dimensione è zero, o supera il massimo per il tipo base: 1.998 per float32 e 3.996 per float16.
• Invalid vector base type significa che il type campo aveva un valore diverso da SQL_VECTOR_TYPE_FLOAT32 o SQL_VECTOR_TYPE_FLOAT16. Una struttura inizializzata a zero ha di default .float32
• Se una float16 colonna viene segnalata come varchar(max) contenente un array JSON, il server non ha abilitata la PREVIEW_FEATURES configurazione con scope del database, o la connessione negoziata a un livello inferiore a v2.