Vectorgegevenstype (ODBC)

In dit artikel wordt het vector-SQL-gegevenstype beschreven, zoals geïmplementeerd door het Microsoft ODBC-stuurprogramma voor SQL Server vanaf versie 18.6.1.1. In dit document wordt het gedrag van het Microsoft-stuurprogramma voor vector beschreven en vindt u gebruiksrichtlijnen, API-specifieke notities en codefragmenten. Zie Vector-gegevenstype voor een overzicht van vectorgegevenstypen.

Overzicht

Het Microsoft ODBC-stuurprogramma voor SQL Server biedt systeemeigen ondersteuning voor het vectorgegevenstype . Toepassingen kunnen numerieke insluitingen met vaste dimensies die vaak worden gebruikt in machine learning- en AI-workloads efficiënt opslaan, ophalen en verwerken. Het stuurprogramma biedt vectorondersteuning via standaard ODBC-API's en C-gegevenstypen. Toepassingen kunnen samenwerken met SQL Server-vectorkolommen zonder bestaande ODBC-werkstromen te wijzigen.

Van toepassing op: Microsoft ODBC-stuurprogramma voor SQL Server 18.6.1.1 en nieuwere versies. Ondersteuning voor het float16 basistype vereist versie 18.7.1.1 of later.

Vectorondersteuning is standaard uitgeschakeld en moet expliciet ingeschakeld zijn.

Typen basiselementen

Een vectorkolom geeft een basiselementtype aan. De driver ondersteunt beide typen die SQL Server definieert.

float32 is de standaardwaarde. Om half-precisie opslag te gebruiken, verklaar je de kolom of parameter als VECTOR(<dimensions>, float16). Omdat een float16 element de helft van de bytes op de draad inneemt, heeft een float16 vector twee keer zoveel dimensies binnen dezelfde payloadlimiet van 8.000 bytes.

Omdat float16 er minder bidsprinkhanbits zijn dan float32, is een heen-en-weer door een float16 kolom verliesgevend. Waarden worden afgerond op de dichtstbijzijnde representabele halfprecisiewaarde op de insert, en de teruggelezen waarde is de float32 uitbreiding van die afgeronde waarde.

Op de server vereist het float16 SQL Server 2025 (17.x) met de PREVIEW_FEATURES database-scoped configuratie ingeschakeld. Voor meer informatie, zie ondersteuning voor halfprecisie float in vectorgegevenstype.

Systeemeigen C-weergave

Wanneer vectorondersteuning is ingeschakeld, worden vectorkolommen uitgewisseld met behulp van een getypeerde C-structuur met de naam 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: beschrijft het aantal elementen in de vector
• type: identificeert het basiselementtype, SQL_VECTOR_TYPE_FLOAT32 of SQL_VECTOR_TYPE_FLOAT16
• data.f32 / data.f16: wijst naar de applicatiebuffer die vectorwaarden bevat

Beide unionleden worden gedeclareerd als float* en zijn uitwisselbaar, omdat de client-side buffer waarden bevat float32 voor beide basistypes. Gebruik het lid dat je intentie aangeeft.

Vectorondersteuning inschakelen

Het vectorTypeSupport verbindingsreeks-sleutelwoord kiest het niveau van native vectorondersteuning dat de verbinding onderhandelt.

Je kunt ook het niveau instellen na het allokeren van de verbindingshand, en vóór het verbinden, met het SQL_COPT_SS_VECTOR_TYPE_SUPPORT pre-connect connection-attribuut.

• De Microsoft-driver biedt een driver-specifieke C-binding SQL_C_SS_VECTOR en ondersteunt SQL_C_BINARY vectoruitvoer. In de praktijk:

  • Wanneer je of v2inschakeltvectorTypeSupport=v1, kunnen ophaal-API's (bijvoorbeeld SQLGetData en SQLBindCol) vectorkolommen teruggeven als ofwel SQL_C_SS_VECTOR of SQL_C_BINARY. SQL_C_SS_VECTOR retourneert de vector in een compacte, getypte vorm. SQL_C_BINARY retourneert een varbinary-payload.

  • Voor invoer- of parameterbinding ondersteunt de driver zowel SQL_C_SS_VECTOR als SQL_C_BINARY. SQL_C_SS_VECTOR biedt een getypte, compacte invoerbinding. SQL_C_BINARY is gelijkwaardig en draagbaar. Gebruik SQL_C_SS_VECTOR wanneer u wilt dat de driver de payload behandelt als een native vectortype.

  • Wanneer vectorTypeSupport=offworden vectorkolommen weergegeven als varchar(max) die JSON-matrices bevatten.

v2 is een bovenverzameling van v1, dus een verbinding die in v2 onderhandeld is, hanteert float32 kolommen precies zoals v1 doet. Het verzenden van een float16 waarde op een verbinding die onderhandeld is, v1 faalt met Requested vector base type is not supported for the negotiated vector version. Gebruik v2 telkens wanneer de applicatie een float16 kolom tegenkomt.

Toepassingen moeten ook de ODBC-versie instellen op ODBC 3.8 voordat u vectorspecifieke typen gebruikt:

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

Ondersteunde bindingsindelingen

Inheemse vectorbinding

Type C: SQL_C_SS_VECTOR

Deze indeling wordt aanbevolen voor prestatiekritieke toepassingen.

Binaire binding

Type C: SQL_C_BINARY

Vectoren worden geretourneerd met dezelfde indeling als SQL_C_SS_VECTOR. Toepassingen kunnen deze indeling gebruiken voor interoperabiliteitsscenario's op laag niveau. De gegevenspointerbuffer kan aaneengesloten of niet-aaneengesloten zijn met het geheugenadres van de structuur.

RICHTLIJNEN voor ODBC-API

In deze sectie wordt beschreven hoe ODBC-API's communiceren met SQL Server-vectorgegevens, waaronder vereisten voor bufferindeling, NULL verwerking en ondersteunde gegevensweergaven. Alle gedragingen zijn van toepassing wanneer vectorTypeSupport ingesteld is op v1 of v2 en de omgeving is geconfigureerd voor ODBC 3.8.

Elke buffergrootte-formule in deze sectie gebruikt sizeof(float) per element voor beide basistypen, omdat de client-side buffer altijd waarden bevat float32 . Een float16 kolom verandert de bytes op de draad, niet de indeling van je buffer.

SQLBindCol

Gebruik SQLBindCol dit om vectorkolommen in een resultatenset te binden aan toepassingsbuffers.

• Typische oproep:

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

• TargetType: gebruik SQL_C_SS_VECTOR of SQL_C_BINARY.

• TargetValuePtr: aanwijzer naar een SQL_SS_VECTOR_STRUCT met een floatarray wanneer TargetTypeSQL_C_SS_VECTOR is; anders een aanwijzer naar een buffer met de grootte zoals de waarde in StrLen_or_IndPtr.

• BufferLength: sizeof(SQL_SS_VECTOR_STRUCT) + het aantal bytes dat is toegewezen voor de kolombuffer (dimensie * 4).

• StrLen_or_IndPtr: aanwijzer die de bytelengte van de geretourneerde vector (SQL_DESC_OCTET_LENGTH) ontvangt. De waarde is sizeof(SQL_SS_VECTOR_STRUCT) + de floatmatrixgrootte (dimensie * 4).

Deze afmetingen zijn hetzelfde voor een float16 kolom. De driver breidt elk half-precisie-element uit tot een float terwijl hij je buffer vult, en rapporteert de uitgebreide lengte.

Verwachtingen voor bufferindeling

Niet-aaneengesloten buffer (aanbevolen)

• De toepassing wijst één SQL_SS_VECTOR_STRUCT per rij toe.
• De toepassing wijst geheugen toe voor data.f32.
• Het stuurprogramma vult vectormetagegevens en schrijft elementwaarden naar de opgegeven floatbuffer .

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

Aaneengesloten buffer

• De toepassing wijst één buffer toe en ODBC vult deze dienovereenkomstig.
• De floatmatrix moet direct na de struct beginnen.
• Het stuurprogramma verwijst data.f32 naar dit aaneengesloten gebied.

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

NULL-verwerking voor SQLBindCol

Wanneer de kolomwaarde NULL is, stelt de driver *StrLen_or_IndPtr in op SQL_NULL_DATA en vult de buffer niet. Controleer altijd de indicator voordat u vectorinhoud opent.

SQLGetData

Gebruik SQLGetData dit om vectorgegevens op te halen uit niet-afhankelijke kolommen.

• Typische oproep:

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

• TargetType: gebruik SQL_C_SS_VECTOR of SQL_C_BINARY.

• TargetValuePtr: aanwijzer naar een SQL_SS_VECTOR_STRUCT met een floatarray wanneer TargetTypeSQL_C_SS_VECTOR is; anders een aanwijzer naar een buffer met de grootte zoals de waarde in StrLen_or_IndPtr.

• BufferLength: sizeof(SQL_SS_VECTOR_STRUCT) + het aantal bytes dat is toegewezen voor de kolombuffer (dimensie * 4).

• StrLen_or_IndPtr: aanwijzer die de bytelengte van de geretourneerde vector (SQL_DESC_OCTET_LENGTH) ontvangt. De waarde is sizeof(SQL_SS_VECTOR_STRUCT) + de floatmatrixgrootte (dimensie * 4).

Gesegmenteerd ophalen wordt niet ondersteund. U moet de hele vector in één aanroep ophalen.

Voorbeeld (systeemeigen vector):

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

NULL-verwerking voor SQLGetData

Wanneer de kolomwaarde NULL is, stelt de driver *StrLen_or_IndPtr in op SQL_NULL_DATA en vult de buffer niet. Controleer altijd de indicator voordat u vectorinhoud opent.

SQLFetch

Gebruik SQLFetch om de volgende rij op te halen en gebonden SqlVector kolommen correct te materialiseren.

• Typische oproep:

    SQLRETURN SQLFetch(
     SQLHSTMT     StatementHandle);

Roep SQLFetch aan in de standaardlus met SqlVector kolommen die al zijn gebonden via SQLBindCol. Of gebruik SQLGetData om gegevens op te halen naar de toepassingsbuffer.

Voorbeeld (systeemeigen vector):

    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

Gebruik SQLFetchScroll om rijenverzamelingen op te halen volgens een opgegeven oriëntatie (volgende, vorige, absoluut, relatief, bladwijzer). Het stuurprogramma kopieert vectorgegevens correct naar toepassingsbuffers.

• Typische oproep:

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

Voorbeeld (systeemeigen vector):

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

Gebruik SQLBindParameter dit om vectorwaarden naar SQL Server te verzenden.

• Typische oproep:

    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: verwijst naar een gevulde SQL_SS_VECTOR_STRUCT
• ColumnSize: genegeerd voor invoerparameters. Geef voor uitvoerparameters en scenario's voor gegevens bij uitvoering de totale vectorgrootte op: sizeof(SQL_SS_VECTOR_STRUCT) + (matrixgrootte float)
• DecimalDigits: genegeerd voor invoerparameters. Geef voor uitvoerparameters en scenario's voor het uitvoeren van gegevens het vectorbasistype op
• BufferLength: ≥ sizeof(SQL_SS_VECTOR_STRUCT) + (dimensie * sizeof(float))
• *StrLen_or_IndPtr: moet dezelfde totale grootte bevatten

Waar het basistype vandaan komt

De driver leest het basiselementtype vanuit een andere plek, afhankelijk van de richting van de parameter. Dit verkeerd doen is de meest voorkomende oorzaak van Invalid vector dimension of Provided buffer length too small/large fouten in een float16 parameter.

Voor een invoerparameter BufferLength moet exact gelijk zijn sizeof(SQL_SS_VECTOR_STRUCT) aan + (dimensie * sizeof(float)). Een grotere of kleinere waarde faalt in plaats van getolereerd te worden.

Voorbeeld (native vector, 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);

Voorbeeld (native vector, float16):

Alleen het type veld verandert. De waardearray blijft een float array en cb wordt op dezelfde manier berekend.

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

Voorbeeld (float16 outputparameter):

Een zuivere outputparameter draagt geen invoerstructuur, dus het basistype wordt doorgegeven DecimalDigits en de dimensie wordt afgeleid uit 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);

NULL-verwerking voor SQLBindParameter

Toepassingen kunnen een NULL vector aangeven met behulp van een van de ondersteunde benaderingen:

• Zet *StrLen_or_IndPtr op SQL_NULL_DATA en pas NULL door als ParameterValuePtr

• Geef een SQL_SS_VECTOR_STRUCT van de volgende gegevens op:

  Dimensieset-type ingesteld op het basistype van de kolom data.f32 = NULL

SQLPutData

Het stuurprogramma ondersteunt SQLPutData vectorparameters met deze beperkingen:

• U moet de hele vector opgeven in de eerste aanroep.

• Het stuurprogramma biedt geen ondersteuning voor segment- of incrementele vectoroverdracht.

• NULL verwerking volgt dezelfde regels als SQLBindParameter.

• Typische oproep:

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

• DataPtr: verwijst naar een gevulde SQL_SS_VECTOR_STRUCT
• StrLen_or_Ind: sizeof(SQL_SS_VECTOR_STRUCT) + (dimensie * sizeof(float))

Voorbeeld (systeemeigen vector):

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

Descriptor metagegevens

Wanneer u vectorondersteuning inschakelt, maakt het Microsoft ODBC-stuurprogramma voor SQL Server vectormetagegevens beschikbaar via standaard-ODBC-descriptor-API's. Toepassingen kunnen descriptorgegevens gebruiken om details van vectorschema's, rekenbuffergrootten te detecteren en bindingen voor parameters en resultatensets correct te configureren.

Descriptorveldwaarden voor vector

In de volgende tabel worden descriptorveldwaarden voor SQL Server-vectorkolommen en -parameters samengevat.

SQL_DESC_LENGTH, SQL_DESC_OCTET_LENGTH, en SQL_DESC_PRECISION allemaal beschrijven ze de buffer aan de clientzijde, zodat ze + (dimensie * sizeof(float)) rapporteren sizeof(SQL_SS_VECTOR_STRUCT) voor een float16 kolom evenals een float32 één. De twee verschillen alleen in het aantal bytes dat SQL Server opslaat en verzendt.

SQL_DESC_SCALE is het enige descriptorveld dat de basistypen onderscheidt. Door het te lezen ontdekt een applicatie of een kolom is float32 of float16.

SQLColAttribuut voor vectordimensie

Vanaf versie 18.7.1.1 SQL_CA_SS_VECTOR_DIMENSION wordt direct het aantal elementen van een vectorkolom teruggegeven, zodat een applicatie het niet langer hoeft af te leiden uit een lengteveld:

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

Je kunt ook SQL_CA_SS_VECTOR_DIMENSION instellen op een applicatiedescriptor of op de IPD voor een vectorparameter. Het instellen op een ander type parameter levert een fout op het veld van een ongeldige descriptor.

SQLDescribeCol

Wanneer u SQLDescribeCol aanroept voor een vectorkolom:

• DataType Is SQL_SS_VECTOR
• ColumnSize komt overeen met SQL_DESC_PRECISION
• DecimalDigits is de basiselementtype-indicator, geen numerieke schaal: 0 voor float32 en 1 voor float16
• Nullable Is SQL_NULLABLE

De gerapporteerde kolomgrootte vertegenwoordigt de systeemeigen vectorbelastinggrootte: sizeof(SQL_SS_VECTOR_STRUCT) + (dimensie * sizeof(float))

SQLDescribeParam

Wanneer u SQLDescribeParam gebruikt voor een vector-parameter:

• DataType Is SQL_SS_VECTOR
• ColumnSize is gelijk aan de payloadgrootte van de native vector
• DecimalDigits is de basiselementtype-indicator, geen numerieke schaal: 0 voor float32 en 1 voor float16
• Nullable Is SQL_NULLABLE

Met deze informatie kunnen toepassingen parameterbuffers correct toewijzen voordat ze worden gebonden.

SQLColAttribute

• Gebruik SQLColAttribute(hstmt, ColumnNumber, SQL_DESC_OCTET_LENGTH, ...) om de exacte bytelengte van de payload van de vector te verkrijgen. SQL_DESC_LENGTH en SQL_DESC_PRECISION kan stuurprogrammaspecifieke waarden bevatten. Voor het aantal bytes geeft u de voorkeur aan SQL_DESC_OCTET_LENGTH.

  • NULL afhandeling: Wanneer een kolom NULL is, geeft SQLColAttribute (of de met StrLen_or_IndPtr gebruikte SQLBindCol) SQL_NULL_DATA. Controleer SQL_NULL_DATA voordat u de geretourneerde lengten of buffers gebruikt.

Bulkkopie (BCP)

U kunt vectorkolommen bulksgewijs importeren en exporteren via BCP-bestanden en de bcp_bind API, net als andere gegevenstypen. Op dit moment ondersteunt vectorimport en -export alleen systeemeigen formaat (SQLVECTOR) of varbinary (SQLBINARY), maar niet tekenformaat. Conversie tussen het vectortype en het tekentype wordt niet ondersteund.

Bulkkopieën houden hetzelfde ondersteuningsniveau als de rest van de driver. Een float16 kolom vereist een verbinding die onderhandeld is bij vectorTypeSupport=v2. In de bcp-hulp , gebruik -z0 voor float32 en -z1 voor float16. Zie het hulpprogramma bcp voor meer informatie.

Zie File Storage Type, Lengte van voorvoegsel en Veldlengte voor meer informatie over het typetoken, de standaardlengte van het voorvoegsel en de standaardveldlengte voor vector.

bcp_gettypename

Wanneer u bcp_gettypename gebruikt om de naam van het SQL-type vector op te vragen, retourneert het het BCP-typetoken (SQLVECTOR) en "vector".

bcp_bind

Hiermee bcp_bind kunt u programmavariabelen bulksgewijs invoegen in een vectorkolom .

Typische oproep:

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

• pData: als cbIndicator nul is, bevat een aanwijzer naar SQL_SS_VECTOR_STRUCT gegevens, met floatmatrixgegevens erin (vectorStruct.data.f32 veld). Als cbIndicator ongelijk aan nul is, verschijnt de indicator in het geheugen direct vóór de gegevens. Verwijst dus pData naar een buffer die eerst bytes aan lengte-indicator heeft cbIndicator , gevolgd door de vectorstruct.
• cbData: indien opgegeven, moet de waarde exact gelijk zijn aan - + sizeof(SQL_SS_VECTOR_STRUCT) ( *sizeof(float) dimensie). Als dat niet het geval is, treedt er een fout op. Dit geldt voor beide basistypen, omdat de boundbuffer in beide richtingen waarden bevat float32 .
• eDataType: of SQLVECTORSQLBINARY

Stel het type veld van de structuur in op het basistype van de kolom. Voor een float16 kolom zet de driver de gebonden float32 array om tot halve precisie terwijl hij de draadpayload bouwt, zodat een databestand in native formaat twee bytes per element bevat.

Wanneer u gegevens in een vectorkolom importeert via bcp_bind, zet eDataType op SQLVECTOR of SQLBINARY. In beide gevallen moet u gegevens opgeven in de vorm van SQL_SS_VECTOR_STRUCT.

Problemen oplossen en tips

• Als SQLGetTypeInfoVECTOR niet vermeldt, val dan terug op het opslaan van vectoren als varchar.
• Requested vector base type is not supported for the negotiated vector version. betekent dat een float16 waarde werd gebruikt op een verbinding die werd onderhandeld op vectorTypeSupport=v1. Maak opnieuw contact met v2.
• Provided buffer length too small/large. De middelen BufferLength kwamen niet exact overeen sizeof(SQL_SS_VECTOR_STRUCT) + (dimensie * sizeof(float)) aan. Controleer of de buffer is voorzien van sizeof(float) een kolom in plaats van twee bytes per element.float16
• Invalid vector dimension betekent dat de dimensie nul is, of hoger is dan het maximum voor het basistype: 1.998 voor float32 en 3.996 voor float16.
• Invalid vector base type betekent dat het type veld een andere waarde had dan SQL_VECTOR_TYPE_FLOAT32 of SQL_VECTOR_TYPE_FLOAT16. Een nul-geïnitialiseerde structuur is standaard .float32
• Als een float16 kolom wordt gerapporteerd als varchar(max) met een JSON-array, heeft de server de PREVIEW_FEATURES database-scoped-configuratie niet ingeschakeld, of is de verbinding onderhandeld over een niveau lager dan v2.