Tipo de datos vectorial (ODBC)

En este artículo se documenta el tipo de datos SQL vector implementado por Microsoft ODBC Driver for SQL Server desde la versión 18.6.1.1. En este documento se describe el comportamiento del controlador de Microsoft para el vector y se proporcionan instrucciones de uso, notas específicas de api y fragmentos de código. Para obtener información general sobre los tipos de datos vectoriales, consulte Tipo de datos vectorial.

Información general

Microsoft ODBC Driver for SQL Server admite de forma nativa el tipo de datos vectorial . Las aplicaciones pueden almacenar, recuperar y procesar inserciones numéricas de dimensión fija de forma eficaz en cargas de trabajo de aprendizaje automático e inteligencia artificial. El controlador expone la compatibilidad de vectores a través de API ODBC estándar y tipos de datos del lenguaje C. Las aplicaciones pueden interoperar con columnas vectoriales de SQL Server sin cambiar los flujos de trabajo ODBC existentes.

Se aplica a: Microsoft ODBC Driver for SQL Server 18.6.1.1 y versiones posteriores. El soporte para el float16 tipo base requiere la versión 18.7.1.1 o posterior.

El soporte vectorial está deshabilitado por defecto y debe estar explícitamente habilitado.

Tipos de elementos base

Una columna vectorial declara un tipo de elemento base. El controlador soporta ambos tipos que define SQL Server.

Tipo base Indicador de tipo Bytes por elemento en el cable Dimensión máxima Versión del controlador
float32 SQL_VECTOR_TYPE_FLOAT32 (0) 4 1,998 18.6.1.1
float16 SQL_VECTOR_TYPE_FLOAT16 (1) 2 3,996 18.7.1.1

float32 es el valor predeterminado. Para usar almacenamiento de media precisión, declara la columna o parámetro como VECTOR(<dimensions>, float16). Como un float16 elemento ocupa la mitad de los bytes del cable, un float16 vector contiene el doble de dimensiones dentro del mismo límite de carga útil de 8.000 bytes.

Importante

El búfer de aplicación es siempre un array de float (4 bytes por elemento) para ambos tipos base. El driver cambia entre media precisión en el cable y simple precisión en tu buffer. Dimensiona cada búfer con sizeof(float), nunca con 2 bytes por elemento, ni siquiera para una float16 columna.

Como float16 tiene menos bits de mantissa que float32, un recorrido de ida y vuelta a través de una float16 columna es con pérdida. Los valores se redondean al valor de media precisión representable más cercano al insertar, y el valor leído de vuelta es la float32 expansión de ese valor redondeado.

En el servidor, float16 se requiere SQL Server 2025 (17.x) con la PREVIEW_FEATURES configuración con alcance de base de datos activada. Para obtener más información, consulte Compatibilidad con formato de punto flotante de media precisión en el tipo de dato vectorial.

Representación nativa de C

Cuando la compatibilidad con vectores está habilitada, las columnas vectoriales se intercambian mediante una estructura C con tipo denominada 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: describe el número de elementos del vector.
  • type: identifica el tipo de elemento base, SQL_VECTOR_TYPE_FLOAT32 o SQL_VECTOR_TYPE_FLOAT16
  • data.f32 / data.f16: apunta al búfer de aplicación que contiene los valores vectoriales

Ambos miembros de la unión se declaran como float* y son intercambiables, porque el buffer del lado del cliente contiene float32 valores para cualquiera de los dos tipos base. Utiliza el miembro que documente tu intención.

Habilitación de la compatibilidad con vectores

La vectorTypeSupport palabra clave cadena de conexión selecciona el nivel de soporte vectorial nativo que negocia la conexión.

Importancia Comportamiento
off (valor predeterminado) Las columnas vectoriales aparecen como varchar(max) que contienen arrays JSON.
v1 Soporte vectorial nativo para el float32 tipo base.
v2 Soporte vectorial nativo tanto para los float32 tipos base como float16 para los de base. Requiere la versión del controlador 18.7.1.1 o posterior.

También puedes establecer el nivel después de asignar la manilla de conexión, y antes de conectar, con el SQL_COPT_SS_VECTOR_TYPE_SUPPORT atributo pre-conexión conexión.

  • El controlador de Microsoft permite una asignación SQL_C_SS_VECTOR en C específica del controlador y soporta SQL_C_BINARY salida vectorial. En la práctica:

    • Cuando activas vectorTypeSupport=v1 o v2, las APIs de recuperación (por ejemplo, SQLGetData y SQLBindCol) pueden devolver columnas vectoriales como o SQL_C_SS_VECTORSQL_C_BINARY. SQL_C_SS_VECTOR devuelve el vector en un formato compacto y tipado. SQL_C_BINARY devuelve una carga varbinary .

    • Para la asignación de entrada o parámetros, el controlador soporta tanto SQL_C_SS_VECTOR como SQL_C_BINARY. SQL_C_SS_VECTOR proporciona un enlace de entrada tipificado y compacto. SQL_C_BINARY es equivalente y portátil. Use SQL_C_SS_VECTOR cuando desee que el controlador trate la carga como un tipo de vector nativo.

    • Cuando vectorTypeSupport=off, las columnas vectoriales aparecen como varchar(max) que contienen matrices JSON.

v2 es un superconjunto de v1, por lo que una conexión negociada en v2 maneja float32 columnas exactamente como v1 lo hace. Enviar un float16 valor en una conexión negociada v1 en falla con Requested vector base type is not supported for the negotiated vector version. Usar v2 siempre que la aplicación pueda encontrar una float16 columna.

Las aplicaciones también deben establecer la versión ODBC en ODBC 3.8 antes de usar tipos específicos del vector:

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

Formatos de enlace admitidos

Enlace de vectores nativos

Tipo de C: SQL_C_SS_VECTOR

Este formato se recomienda para aplicaciones críticas para el rendimiento.

Enlace binario

Tipo de C: SQL_C_BINARY

Los vectores se devuelven con el mismo diseño que SQL_C_SS_VECTOR. Las aplicaciones pueden usar este formato para escenarios de interoperabilidad de bajo nivel. El búfer del puntero de datos puede ser contiguo o no contiguo con la dirección de memoria de la estructura.

Guía de API de ODBC

En esta sección se describe cómo interactúan las API ODBC con los datos vectoriales de SQL Server, incluidos los requisitos de diseño del búfer, NULL el control y las representaciones de datos admitidas. Todos los comportamientos se aplican cuando vectorTypeSupport está configurado como v1 o v2 y el entorno está configurado para ODBC 3.8.

Cada fórmula de tamaño de búfer en esta sección usa sizeof(float) por elemento para ambos tipos base, porque el búfer del lado del cliente siempre contiene float32 valores. Una float16 columna cambia los bytes del cable, no la disposición de tu búfer.

SQLBindCol

Use SQLBindCol para enlazar columnas vectoriales en un conjunto de resultados a búferes de aplicación.

  • Llamada típica:
    SQLRETURN SQLBindCol(
      SQLHSTMT       StatementHandle,
      SQLUSMALLINT   ColumnNumber,
      SQLSMALLINT    TargetType,
      SQLPOINTER     TargetValuePtr,
      SQLLEN         BufferLength,
      SQLLEN *       StrLen_or_IndPtr);

  • TargetType: usar SQL_C_SS_VECTOR o SQL_C_BINARY.

  • TargetValuePtr: puntero a un SQL_SS_VECTOR_STRUCT con una matriz float cuando TargetType es SQL_C_SS_VECTOR; de lo contrario, puntero a un búfer con tamaño como valor en StrLen_or_IndPtr.

  • BufferLength: sizeof(SQL_SS_VECTOR_STRUCT) + el número de bytes asignados para el búfer de columnas (dimensión * 4).

  • StrLen_or_IndPtr: puntero que recibe la longitud de bytes del vector devuelto (SQL_DESC_OCTET_LENGTH). Su valor es sizeof(SQL_SS_VECTOR_STRUCT) + el tamaño de la matriz float (dimensión * 4).

Estos tamaños son los mismos para una float16 columna. El driver expande cada elemento de media precisión a float medida que llena tu búfer y reporta la longitud ampliada.

Expectativas de diseño de buffer

Búfer no contiguo (recomendado)

  • La aplicación asigna una SQL_SS_VECTOR_STRUCT por fila.
  • La aplicación asigna memoria para data.f32.
  • El controlador rellena los metadatos vectoriales y escribe valores de elemento en el búfer float proporcionado.
    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());

Búfer contiguo

  • La aplicación asigna un único búfer y ODBC lo rellena en consecuencia.
  • La matriz float debe comenzar inmediatamente después del struct.
  • El controlador establece data.f32 para que apunte a esta región 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());

Manejo de NULL para SQLBindCol

Cuando el valor de la columna es NULL, el controlador establece *StrLen_or_IndPtr en SQL_NULL_DATA y no rellena el búfer. Compruebe siempre el indicador antes de acceder al contenido del vector.

Nota:

El comportamiento de lectura y captura de filas para las columnas vectoriales se describe en detalle en SQLFetch y SQLFetchScroll (consulte esas referencias de API para obtener la semántica de captura y ejemplos de captura de matriz).

SQLGetData

Use SQLGetData para recuperar datos vectoriales de columnas sin enlazar.

  • Llamada típica:
    SQLRETURN SQLGetData(
      SQLHSTMT       StatementHandle,
      SQLUSMALLINT   Col_or_Param_Num,
      SQLSMALLINT    TargetType,
      SQLPOINTER     TargetValuePtr,
      SQLLEN         BufferLength,
      SQLLEN *       StrLen_or_IndPtr);

  • TargetType: usar SQL_C_SS_VECTOR o SQL_C_BINARY.

  • TargetValuePtr: puntero a un SQL_SS_VECTOR_STRUCT con una matriz float cuando TargetType es SQL_C_SS_VECTOR; de lo contrario, puntero a un búfer con tamaño como valor en StrLen_or_IndPtr.

  • BufferLength: sizeof(SQL_SS_VECTOR_STRUCT) + el número de bytes asignados para el búfer de columnas (dimensión * 4).

  • StrLen_or_IndPtr: puntero que recibe la longitud de bytes del vector devuelto (SQL_DESC_OCTET_LENGTH). Su valor es sizeof(SQL_SS_VECTOR_STRUCT) + el tamaño de la matriz float (dimensión * 4).

No se admite la recuperación fragmentada. Debe recuperar todo el vector en una llamada.

Ejemplo ( vector 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);

Manejo de valores NULL para SQLGetData

Cuando el valor de la columna es NULL, el controlador establece *StrLen_or_IndPtr en SQL_NULL_DATA y no rellena el búfer. Compruebe siempre el indicador antes de acceder al contenido del vector.

Nota:

El comportamiento de lectura y captura de filas para las columnas vectoriales se describe en detalle en SQLFetch y SQLFetchScroll (consulte esas referencias de API para obtener la semántica de captura y ejemplos de captura de matriz).

SQLFetch

Use SQLFetch para obtener la siguiente fila y materializar correctamente las columnas vinculadas SqlVector.

  • Llamada típica:
    SQLRETURN SQLFetch(
     SQLHSTMT     StatementHandle);

Llame a SQLFetch en el bucle estándar con SqlVector columnas ya enlazadas a través de SQLBindCol. O bien, use SQLGetData para recuperar datos en el búfer de la aplicación.

Ejemplo ( vector 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

Use SQLFetchScroll para capturar conjuntos de filas según una orientación especificada (siguiente, anterior, absoluto, relativo, marcador). El controlador copia correctamente los datos vectoriales en búferes de aplicación.

  • Llamada típica:
    SQLRETURN SQLFetchScroll(
      SQLHSTMT      StatementHandle,
      SQLSMALLINT   FetchOrientation,
      SQLLEN        FetchOffset);

Ejemplo ( vector 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

Use SQLBindParameter para enviar valores vectoriales a SQL Server.

  • Llamada típica:
    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: apunta a un SQL_SS_VECTOR_STRUCT poblado
  • ColumnSize: se omite para los parámetros de entrada. Para los parámetros de salida y los escenarios de datos en ejecución, especifique el tamaño total del vector: sizeof(SQL_SS_VECTOR_STRUCT) + (tamaño de matriz float )
  • DecimalDigits: se omite para los parámetros de entrada. Para los parámetros de salida y los escenarios de datos en ejecución, especifique el tipo base vectorial.
  • BufferLength: ≥ sizeof(SQL_SS_VECTOR_STRUCT) + (dimensión * sizeof(float))
  • *StrLen_or_IndPtr: debe tener el mismo tamaño total.

De dónde proviene el tipo base

El controlador lee el tipo de elemento base desde un lugar diferente dependiendo de la dirección del parámetro. Equivocarse es la causa más común de Invalid vector dimension errores Provided buffer length too small/large en un float16 parámetro.

Tipo de parámetro Fuente de tipo base Fuente dimensional
Entrada y entrada/salida El type campo de la SQL_SS_VECTOR_STRUCT pasa El dimension campo de la misma estructura
Salida pura DecimalDigits Derivado de ColumnSize como (ColumnSize - sizeof(SQL_SS_VECTOR_STRUCT)) / sizeof(float)
Datos en ejecución DecimalDigits Derivado de ColumnSize, y contrastado con la longitud transmitida a SQL_LEN_DATA_AT_EXEC

Para un parámetro de entrada, BufferLength debe ser igual sizeof(SQL_SS_VECTOR_STRUCT) a + (dimensión * sizeof(float)) exactamente. Un valor mayor o menor falla en lugar de ser tolerado.

Ejemplo ( vector 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);

Ejemplo ( vector nativo, float16):

Solo cambia el type campo. El array de valores permanece como float un array y cb se calcula de la misma manera.

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

Ejemplo (float16 parámetro de salida):

Un parámetro de salida puro no tiene estructura de entrada, por lo que el tipo base se pasa en DecimalDigits y la dimensión se deriva de 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);

Manejo de NULL para SQLBindParameter

Las aplicaciones pueden indicar un NULL vector mediante cualquiera de los enfoques admitidos:

  • Establecer *StrLen_or_IndPtr en SQL_NULL_DATA y pasar NULL como ParameterValuePtr

  • Proporcione un SQL_SS_VECTOR_STRUCT con:

    Tipo de conjunto de dimensiones establecido al tipo base de la columna data.f32 = NULL

SQLPutData

El controlador admite SQLPutData parámetros vectoriales con estas restricciones:

  • Debe proporcionar todo el vector en la primera llamada.

  • El controlador no admite la transmisión de vectores fragmentados ni incrementales.

  • NULL el control sigue las mismas reglas que SQLBindParameter.

  • Llamada típica:

    SQLRETURN SQLPutData(
        SQLHSTMT     StatementHandle,
        SQLPOINTER   DataPtr,
        SQLLEN       StrLen_or_Ind);
  • DataPtr: apunta a un SQL_SS_VECTOR_STRUCT poblado
  • StrLen_or_Ind: sizeof(SQL_SS_VECTOR_STRUCT) + (dimensión * sizeof(float))

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

Metadatos del descriptor

Al habilitar la compatibilidad con vectores, Microsoft ODBC Driver for SQL Server expone metadatos vectoriales a través de las API estándar del descriptor ODBC. Las aplicaciones pueden usar información de descriptores para descubrir detalles del esquema vectorial, calcular tamaños de búfer y configurar correctamente enlaces para parámetros y conjuntos de resultados.

Valores del campo descriptor para vectores

En la tabla siguiente se resumen los valores de campo de descriptor para las columnas y parámetros vectoriales de SQL Server.

Campo descriptor Importancia Description
SQL_DESC_TYPE SQL_SS_VECTOR (-156) Identificador de tipo de datos base de SQL
SQL_DESC_CONCISE_TYPE SQL_SS_VECTOR Tipo de datos SQL conciso
SQL_DESC_TYPE_NAME vector Nombre de tipo SQL
SQL_DESC_LOCAL_TYPE_NAME vector Nombre del tipo local del controlador
SQL_DESC_LENGTH sizeof(SQL_SS_VECTOR_STRUCT) + (dimension * sizeof(float)) Tamaño lógico del valor de vector
SQL_DESC_OCTET_LENGTH Igual que SQL_DESC_LENGTH. Tamaño físico en bytes
SQL_DESC_PRECISION Igual que SQL_DESC_LENGTH. Se usa para notificar el tamaño del vector
SQL_DESC_SCALE SQL_VECTOR_TYPE_FLOAT32 o SQL_VECTOR_TYPE_FLOAT16 Tipo de elemento base vectorial
SQL_CA_SS_VECTOR_DIMENSION dimension Número de elementos en el vector
SQL_DESC_DISPLAY_SIZE dimension * VECTOR_FLOAT32_TO_CHAR_JSON_MAX_SIZE Longitud máxima de la pantalla JSON
SQL_DESC_FIXED_PREC_SCALE SQL_FALSE El vector no tiene ninguna precisión y escala fijas
SQL_DESC_NULLABLE SQL_NULLABLE Las columnas vectoriales permiten valores de NULL
SQL_DESC_NUM_PREC_RADIX 0 Tipo no numérico
SQL_DESC_SEARCHABLE SQL_PRED_NONE No se puede usar en predicados
SQL_DESC_UNSIGNED SQL_TRUE El tipo de elemento es sin signo
SQL_DESC_AUTO_UNIQUE_VALUE SQL_FALSE No autounique
SQL_DESC_CASE_SENSITIVE SQL_FALSE No distingue mayúsculas de minúsculas
SQL_DESC_UPDATABLE SQL_ATTR_READWRITE_UNKNOWN Actualizabilidad desconocida

SQL_DESC_LENGTH, SQL_DESC_OCTET_LENGTH, y SQL_DESC_PRECISION todos describen el búfer del lado del cliente, por lo que informan sizeof(SQL_SS_VECTOR_STRUCT) de + (dimensión * sizeof(float)) tanto para una float16 columna como para uno float32 . Ambos solo difieren en el número de bytes que SQL Server almacena y transmite.

SQL_DESC_SCALE es el único campo descriptor que distingue los tipos base. Leerlo es como una aplicación descubre si una columna es float32 o float16.

SQLColAttribute para dimensión vectorial

A partir de la versión 18.7.1.1, SQL_CA_SS_VECTOR_DIMENSION devuelve directamente el conteo de elementos de una columna vectorial, de modo que una aplicación ya no tiene que derivarlo de un campo de longitud:

    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 */

También puedes poner SQL_CA_SS_VECTOR_DIMENSION un descriptor de aplicación o en el IPD para un parámetro vectorial. Configurarlo en cualquier otro tipo de parámetro devuelve un error de campo descriptor inválido.

SQLDescribeCol

Cuando se llama a SQLDescribeCol para una columna vectorial :

  • DataType es SQL_SS_VECTOR.
  • ColumnSize coincide con SQL_DESC_PRECISION
  • DecimalDigits es el indicador de tipo de elemento base, no una escala numérica: 0 para float32 y 1 para float16
  • Nullable es SQL_NULLABLE.

El tamaño de columna notificado representa el tamaño de carga de vector nativo: sizeof(SQL_SS_VECTOR_STRUCT) + (dimensión * sizeof(float))

SQLDescribeParam

Cuando se usa SQLDescribeParam para un parámetro vectorial :

  • DataType es SQL_SS_VECTOR.
  • ColumnSize es igual al tamaño de carga del vector nativo.
  • DecimalDigits es el indicador de tipo de elemento base, no una escala numérica: 0 para float32 y 1 para float16
  • Nullable es SQL_NULLABLE.

Esta información permite que las aplicaciones asignen búferes de parámetros correctamente antes del enlace.

SQLColAttribute

  • Use SQLColAttribute(hstmt, ColumnNumber, SQL_DESC_OCTET_LENGTH, ...) para obtener la longitud exacta de bytes de la carga vectorial. SQL_DESC_LENGTH y SQL_DESC_PRECISION pueden llevar valores específicos del controlador. Para el recuento de bytes, prefiera SQL_DESC_OCTET_LENGTH.

    • NULL handling: cuando una columna es NULL, SQLColAttribute (o el StrLen_or_IndPtr utilizado con SQLBindCol) devuelve SQL_NULL_DATA. Compruebe SQL_NULL_DATA antes de usar longitudes o búferes devueltos.

Copia masiva (BCP)

Puede importar y exportar columnas vectoriales de forma masiva a través de archivos BCP y la bcp_bind API, al igual que otros tipos de datos. Actualmente, la importación y exportación de vectores solo admite el formato nativo (SQLVECTOR) o varbinary (SQLBINARY), pero no el formato de caracteres. No se admite la conversión entre el tipo de vector y el tipo de carácter.

La copia masiva respeta el mismo nivel de soporte que el resto del conductor. Una float16 columna requiere una conexión negociada en vectorTypeSupport=v2. En la utilidad bcp , úsase -z0 para float32 y -z1 para float16. Para obtener más información, consulte la utilidad bcp.

Para obtener más información sobre el token de tipo, la longitud de prefijo predeterminada y la longitud de campo predeterminada para el vector, vea Tipo de almacenamiento de archivos, Longitud del prefijo y Longitud del campo.

bcp_gettypename

Cuando se usa bcp_gettypename para obtener el nombre de tipo SQL de vector, devuelve el token de tipo BCP (SQLVECTOR) y "vector".

bcp_bind

Use bcp_bind para insertar de forma masiva variables de programa en una columna vectorial .

Llamada típica:

RETCODE bcp_bind (
        HDBC hdbc,
        LPCBYTE pData,
        INT cbIndicator,
        DBINT cbData,
        LPCBYTE pTerm,
        INT cbTerm,
        INT eDataType,
        INT idxServerCol);
  • pData: si cbIndicator es cero, contiene un puntero a los datos SQL_SS_VECTOR_STRUCT, con un arreglo de float dentro de él (campo vectorStruct.data.f32). Si cbIndicator no es cero, el indicador aparece en memoria directamente antes de los datos. Por lo tanto, pData apunta a un búfer que primero tiene cbIndicator bytes del indicador de longitud, seguido por la estructura vectorial.
  • cbData: si se proporciona, debe tener el valor exactamente igual a - sizeof(SQL_SS_VECTOR_STRUCT) + (sizeof(float) * dimensión). Si no es así, se produce un error. Esto es igual para ambos tipos de base, porque el búfer acotado mantiene float32 valores en ambos sentidos.
  • eDataType: SQLVECTOR o SQLBINARY

Establece el type campo de la estructura al tipo base de la columna. Para una float16 columna, el controlador convierte el array limitado float32 a media precisión mientras construye la carga útil del cable, de modo que un archivo de datos escrito en formato nativo contiene dos bytes por elemento.

Al importar datos a una columna de vector a través de bcp_bind, establezca eDataType en SQLVECTOR o SQLBINARY. En ambos casos, debe proporcionar datos en forma de SQL_SS_VECTOR_STRUCT.

Solución de problemas y sugerencias

  • Si SQLGetTypeInfo no enumera VECTOR, vuelva al almacenamiento de vectores como varchar.
  • Requested vector base type is not supported for the negotiated vector version. significa que se utilizó un float16 valor sobre una conexión negociada en vectorTypeSupport=v1. Reconecta con v2.
  • Provided buffer length too small/large. Significa BufferLength que no coincidía sizeof(SQL_SS_VECTOR_STRUCT) exactamente + (dimensión * sizeof(float)). Comprueba que el buffer tenga un tamaño con sizeof(float) en lugar de dos bytes por elemento, incluso para una float16 columna.
  • Invalid vector dimension significa que la dimensión es cero, o supera el máximo para el tipo base: 1.998 para float32 y 3.996 para float16.
  • Invalid vector base type significa que el type campo tenía un valor distinto a SQL_VECTOR_TYPE_FLOAT32 o SQL_VECTOR_TYPE_FLOAT16. Una estructura inicializada en cero tiene por defecto .float32
  • Si una float16 columna se reporta como varchar(max) que contiene un array JSON, el servidor no tiene activada la PREVIEW_FEATURES configuración con alcance de base de datos, ni la conexión negociada un nivel inferior a v2.
  • Last updated on