Vektordatatyp (ODBC)

Den här artikeln dokumenterar sql-vektordatatypen som implementerats av Microsoft ODBC-drivrutinen för SQL Server med början i version 18.6.1.1. Det här dokumentet beskriver Microsoft-drivrutinens beteende för vektor och ger användningsvägledning, API-specifika anteckningar och kodfragment. En översikt över vektordatatyper finns i Vektordatatyp.

Översikt

Microsoft ODBC-drivrutinen för SQL Server har inbyggt stöd för vektordatatypen . Program kan effektivt lagra, hämta och bearbeta numeriska inbäddningar med fast dimension som ofta används i maskininlärning och AI-arbetsbelastningar. Drivrutinen exponerar vektorstöd via standard-ODBC-API:er och C-datatyper. Program kan samverka med SQL Server-vektorkolumner utan att ändra befintliga ODBC-arbetsflöden.

Gäller för: Microsoft ODBC-drivrutin för SQL Server 18.6.1.1 och senare versioner. Stöd för float16 bastypen kräver version 18.7.1.1 eller senare.

Vektorstöd är inaktiverat som standard och måste vara explicit aktiverat.

Baselementtyper

En vektorkolumn deklarerar en baselementtyp. Drivrutinen stöder båda typerna som SQL Server definierar.

float32 används som standard. För att använda halvprecisionslagring, deklarera kolumnen eller parametern som VECTOR(<dimensions>, float16). Eftersom ett float16 element upptar hälften av bytena på ledningen, har en float16 vektor dubbelt så många dimensioner inom samma 8 000-bytes nyttolastgräns.

Eftersom float16 har färre mantissbitar än float32, är en rundresa genom en float16 kolumn förlustgiv. Värden avrundas till det närmaste representerbara halvprecisionsvärdet vid insättningen, och det värde som läses tillbaka är expansionen float32 av det avrundade värdet.

På servern float16 krävs SQL Server 2025 (17.x) med PREVIEW_FEATURES databasens scoped-konfiguration aktiverad. Mer information finns i Stöd för halvprecisionsflöd i vektordatatyp.

Inbyggd C-representation

När vektorstöd är aktiverat utbyts vektorkolumner med hjälp av en typbaserad C-struktur med namnet 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: beskriver antalet element i vektorn
• type: identifierar grundelementtypen, SQL_VECTOR_TYPE_FLOAT32 eller SQL_VECTOR_TYPE_FLOAT16
• data.f32 / data.f16: pekar på applikationsbufferten som innehåller vektorvärden

Båda unionmedlemmarna deklareras som float* och är utbytbara, eftersom klientbufferten innehåller float32 värden för båda bastyperna. Använd den medlem som dokumenterar din avsikt.

Aktivera stöd för vektor

Nyckelordet vectorTypeSupport reťazec pripojenia väljer nivån av nativt vektorstöd som anslutningen förhandlar om.

Du kan också ställa in nivån efter att anslutningshandtaget har allokerats, och innan anslutning, med attributet SQL_COPT_SS_VECTOR_TYPE_SUPPORT pre-connect connection.

• Microsoft-drivrutinen exponerar en drivrutinsspecifik C-bindning SQL_C_SS_VECTOR och stödjer SQL_C_BINARY vektorutdata. I praktiken:

  • När du aktiverar vectorTypeSupport=v1 eller v2, kan hämtande API:er (till exempel SQLGetData och SQLBindCol) returnera vektorkolumner som antingen SQL_C_SS_VECTOR eller SQL_C_BINARY. SQL_C_SS_VECTOR returnerar vektorn i ett kompakt, skrivet formulär. SQL_C_BINARY returnerar en varbinär nyttolast.

  • För inmatnings- eller parameterbindning stöder drivrutinen både SQL_C_SS_VECTOR och SQL_C_BINARY. SQL_C_SS_VECTOR innehåller en typinskriven, kompakt indatabindning. SQL_C_BINARY är likvärdig och bärbar. Använd SQL_C_SS_VECTOR när du vill att drivrutinen ska behandla nyttolasten som en intern vektortyp .

  • När vectorTypeSupport=offvisas vektorkolumner som varchar(max) som innehåller JSON-matriser.

v2 är en övermängd av v1, så en förbindelse som förhandlas vid v2 hanterar float32 kolumner exakt som v1 gör. Att skicka ett float16 värde på en förhandlad anslutning misslyckas v1 med Requested vector base type is not supported for the negotiated vector version. Use v2 när applikationen kan stöta på en float16 kolumn.

Program måste också ange ODBC-versionen till ODBC 3.8 innan vektorspecifika typer används:

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

Bindningsformat som stöds

Inbyggd vektorbindning

C-typ: SQL_C_SS_VECTOR

Det här formatet rekommenderas för prestandakritiska program.

Binär bindning

C-typ: SQL_C_BINARY

Vektorer returneras med samma layout som SQL_C_SS_VECTOR. Program kan använda det här formatet för driftskompatibilitetsscenarier på låg nivå. Datapekarbufferten kan vara sammanhängande eller icke-sammanhängande med strukturminnesadress.

VÄGLEDNING FÖR ODBC API

Det här avsnittet beskriver hur ODBC-API:er interagerar med SQL Server-vektordata, inklusive krav för buffertlayout, NULL hantering och datarepresentationer som stöds. Alla beteenden gäller när vectorTypeSupport är inställd på v1 eller v2 och miljön är konfigurerad för ODBC 3.8.

Varje buffertstorleksformel i detta avsnitt använder sizeof(float) per element för båda bastyperna, eftersom klientsidans buffert alltid innehåller float32 värden. En float16 kolumn ändrar bytena på kabeln, inte layouten på din buffert.

SQLBindCol

Använd SQLBindCol för att binda vektorkolumner i en resultatuppsättning till programbuffertar.

• Typiskt anrop:

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

• TargetType: använd SQL_C_SS_VECTOR eller SQL_C_BINARY.

• TargetValuePtr: pekare till en SQL_SS_VECTOR_STRUCT med en flyttalmatris när TargetType är SQL_C_SS_VECTOR, annars pekare till en buffert med storlek som värdet i StrLen_or_IndPtr.

• BufferLength: sizeof(SQL_SS_VECTOR_STRUCT) + antalet byte som allokerats för kolumnbufferten (dimension * 4).

• StrLen_or_IndPtr: pekare som tar emot bytelängden för den returnerade vektorn (SQL_DESC_OCTET_LENGTH). Dess värde är sizeof(SQL_SS_VECTOR_STRUCT) + storleken på flyttalsmatrisen (dimension * 4).

Dessa storlekar är desamma för en float16 kolumn. Drivern expanderar varje halvprecisionselement till a float när det fyller din buffert och rapporterar den utökade längden.

Förväntningar på buffert-layout

Icke-sammanhängande buffert (rekommenderas)

• Programmet allokerar en SQL_SS_VECTOR_STRUCT per rad.
• Programmet allokerar minne för data.f32.
• Drivrutinen fyller i vektormetadata och skriver elementvärden i den angivna flyttalsbufferten .

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

Sammanhängande buffert

• Programmet allokerar en enda buffert och ODBC fyller den i enlighet med detta.
• Flyttalsmatrisen måste börja omedelbart efter struct:en.
• Drivrutinen ställer in data.f32 till att peka på den här sammanhängande regionen.

    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-hantering för SQLBindCol

När kolumnvärdet är NULL sätter drivrutinen *StrLen_or_IndPtr till SQL_NULL_DATA och fyller inte i bufferten. Kontrollera alltid indikatorn innan du kommer åt vektorinnehållet.

SQLGetData

Använd SQLGetData för att hämta vektordata från obundna kolumner.

• Typiskt anrop:

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

• TargetType: använd SQL_C_SS_VECTOR eller SQL_C_BINARY.

• TargetValuePtr: pekare till en SQL_SS_VECTOR_STRUCT med en flyttalmatris när TargetType är SQL_C_SS_VECTOR, annars pekare till en buffert med storlek som värdet i StrLen_or_IndPtr.

• BufferLength: sizeof(SQL_SS_VECTOR_STRUCT) + antalet byte som allokerats för kolumnbufferten (dimension * 4).

• StrLen_or_IndPtr: pekare som tar emot bytelängden för den returnerade vektorn (SQL_DESC_OCTET_LENGTH). Dess värde är sizeof(SQL_SS_VECTOR_STRUCT) + storleken på flyttalsmatrisen (dimension * 4).

Segmenterad hämtning stöds inte. Du måste hämta hela vektorn i ett anrop.

Exempel (intern vektor):

    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-hantering för SQLGetData

När kolumnvärdet är NULL sätter drivrutinen *StrLen_or_IndPtr till SQL_NULL_DATA och fyller inte i bufferten. Kontrollera alltid indikatorn innan du kommer åt vektorinnehållet.

SQLFetch

Använd SQLFetch för att hämta nästa rad och materialisera eventuella bundna SqlVector kolumner korrekt.

• Typiskt anrop:

    SQLRETURN SQLFetch(
     SQLHSTMT     StatementHandle);

Anropa SQLFetch i standardloopen med SqlVector kolumner som redan är bundna via SQLBindCol. Du kan också använda SQLGetData för att hämta data till programbufferten.

Exempel (intern vektor):

    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

Använd SQLFetchScroll för att hämta raduppsättningar enligt en angiven orientering (nästa, tidigare, absolut, relativ, bokmärke). Drivrutinen kopierar korrekt vektordata till programbuffertar.

• Typiskt anrop:

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

Exempel (intern vektor):

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

Använd SQLBindParameter för att skicka vektorvärden till SQL Server.

• Typiskt anrop:

    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: pekar på en befolkad SQL_SS_VECTOR_STRUCT
• ColumnSize: ignoreras för inmatningsparametrar. För utdataparametrar och scenarier för data vid körning, ange den totala vektorstorleken: sizeof(SQL_SS_VECTOR_STRUCT) + (storleken på flyttalsmatrisen)
• DecimalDigits: ignoreras för inmatningsparametrar. För utdataparametrar och scenarier för data vid körning anger du vektorbastypen
• BufferLength: ≥ sizeof(SQL_SS_VECTOR_STRUCT) + (dimension * sizeof(float))
• *StrLen_or_IndPtr: måste innehålla samma totala storlek

Varifrån bastypen kommer

Drivrutinen läser baselementtypen från en annan plats beroende på parameterns riktning. Att göra fel är den vanligaste orsaken till Invalid vector dimension eller Provided buffer length too small/large fel på en float16 parameter.

För en indataparameter BufferLength måste vara exakt lika med sizeof(SQL_SS_VECTOR_STRUCT) + (dimension * sizeof(float)). Ett större eller mindre värde misslyckas snarare än att tolereras.

Exempel (inhemsk vektor, 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);

Exempel (inhemsk vektor, float16):

Endast fältet förändras type . Värdearrayen förblir en float array och cb beräknas på samma sätt.

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

Exempel (float16 utdataparameter):

En ren utdataparameter bär ingen indatastruktur, så bastypen skickas in DecimalDigits och dimensionen härleds från 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-hantering för SQLBindParameter

Program kan indikera en NULL vektor med någon av de metoder som stöds:

• Ange *StrLen_or_IndPtr till SQL_NULL_DATA och skicka NULL som ParameterValuePtr

• Ange en SQL_SS_VECTOR_STRUCT med:

  Dimension set-typ inställd på kolumnens bastyp data.f32 = NULL

SQLPutData

Drivrutinen stöder SQLPutData vektorparametrar med följande begränsningar:

• Du måste ange hela vektorn i det första anropet.

• Drivrutinen stöder inte segmenterad eller inkrementell vektoröverföring.

• NULL hantering följer samma regler som SQLBindParameter.

• Typiskt anrop:

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

• DataPtr: pekar på en befolkad SQL_SS_VECTOR_STRUCT
• StrLen_or_Ind: sizeof(SQL_SS_VECTOR_STRUCT) + (dimension * sizeof(float))

Exempel (intern vektor):

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

Beskrivningsmetadata

När du aktiverar vektorstöd exponerar Microsoft ODBC-drivrutinen för SQL Server vektormetadata via standard-ODBC-beskrivnings-API:er. Program kan använda beskrivande information för att identifiera information om vektorschema, beräkningsbuffertstorlekar och korrekt konfigurera bindningar för parametrar och resultatuppsättningar.

Deskriptorfältvärden för vektor

I följande tabell sammanfattas deskriptorfältvärden för SQL Server-vektorkolumner och parametrar.

SQL_DESC_LENGTH, SQL_DESC_OCTET_LENGTH, och SQL_DESC_PRECISION alla beskriver klientsidans buffert, så de rapporterar sizeof(SQL_SS_VECTOR_STRUCT) + (dimension * sizeof(float)) för en float16 kolumn såväl som en float32 ett. De två skiljer sig endast i antalet byte som SQL Server lagrar och överför.

SQL_DESC_SCALE är det enda beskrivande fältet som skiljer bastyperna. Att läsa den är hur en applikation upptäcker om en kolumn är float32 eller float16.

SQLColAttribute för vektordimension

Från och med version 18.7.1.1 returnerar SQL_CA_SS_VECTOR_DIMENSION en vektorkolumns elementantal direkt, så en applikation behöver inte längre härleda det från ett längdfält:

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

Du kan också ställa SQL_CA_SS_VECTOR_DIMENSION in på en applikationsbeskrivning eller på IPD för en vektorparameter. Att sätta den på någon annan typ av parameter ger ett fel med ogiltig beskrivande fält.

SQLDescribeCol

När du anropar SQLDescribeCol en vektorkolumn :

• DataType är SQL_SS_VECTOR
• ColumnSize matchar SQL_DESC_PRECISION
• DecimalDigits är baselementtypindikatorn, inte en numerisk skala: 0 för float32 och 1 för float16
• Nullable är SQL_NULLABLE

Den rapporterade kolumnstorleken representerar den inbyggda vektornyttolastens storlek: sizeof(SQL_SS_VECTOR_STRUCT) + (dimension * sizeof(float))

SQLDescribeParam

När du använder SQLDescribeParam för en vektorparameter :

• DataType är SQL_SS_VECTOR
• ColumnSize är lika med den ursprungliga vektornyttolaststorleken
• DecimalDigits är baselementtypindikatorn, inte en numerisk skala: 0 för float32 och 1 för float16
• Nullable är SQL_NULLABLE

Med den här informationen kan program allokera parameterbuffertar korrekt innan bindningen.

SQLColAttribute

• Använd SQLColAttribute(hstmt, ColumnNumber, SQL_DESC_OCTET_LENGTH, ...) för att hämta den exakta bytelängden för vektornyttolasten. SQL_DESC_LENGTH och SQL_DESC_PRECISION kan innehålla drivrutinsspecifika värden. För byteantal föredrar du SQL_DESC_OCTET_LENGTH.

  • NULLhantering: När en kolumn är NULL returnerar SQLColAttribute (eller används StrLen_or_IndPtr med SQLBindCol) SQL_NULL_DATA. Kontrollera efter SQL_NULL_DATA innan du använder returnerade längder eller buffertar.

Masskopiering (BCP)

Du kan massimportera och exportera vektorkolumner via BCP-filer och API:et bcp_bind , precis som andra datatyper. För närvarande stöder vektorimport och export endast internt format (SQLVECTOR) eller varbinärt (SQLBINARY), men inte teckenformat. Konvertering mellan vektortyp och teckentyp stöds inte.

Masskopiering hedrar samma supportnivå som resten av drivrutinen. En kolumn kräver en förbindelse förhandlad float16 vid vectorTypeSupport=v2. I bcp-verktyget , använd -z0 för float32 och -z1 för float16. Mer information finns i bcp-verktyget.

Mer information om typtoken, standardprefixlängd och standardfältlängd för vektor finns i Fillagringstyp, Prefixlängd och Fältlängd.

bcp_gettypename

När du använder bcp_gettypename för att hämta SQL-typnamnet för vektor returneras BCP-typtoken (SQLVECTOR) och "vector".

bcp_bind

Använd bcp_bind för att massinfogar programvariabler i en vektorkolumn .

Typiskt anrop:

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

• pData: om cbIndicator är noll, innehåller en pekare till SQL_SS_VECTOR_STRUCT data, med en flyttalsmatris inuti ( fält). Om cbIndicator är icke-noll visas indikatorn i minnet direkt före data. Så pData pekar på en buffert som först har cbIndicator byte av längdindikator, följt av vektorstruktur.
• cbData: om det anges måste ha ett värde som är exakt lika med - sizeof(SQL_SS_VECTOR_STRUCT) + (sizeof(float) * dimension). Annars uppstår ett fel. Detta gäller för båda bastyperna, eftersom boundbufferten håller float32 värden åt båda hållen.
• eDataType: SQLVECTOR eller SQLBINARY

Ställ in type strukturens fält till kolumnens bastyp. För en float16 kolumn konverterar drivrutinen den bundna float32 matrisen till halvprecisionen när den bygger trådlasten, så en datafil skriven i native-format innehåller två byte per element.

När du importerar data till en vektorkolumn via bcp_bindanger du eDataType till SQLVECTOR eller SQLBINARY. I båda fallen måste du ange data i form av SQL_SS_VECTOR_STRUCT.

Felsökning och tips

• Om SQLGetTypeInfo inte listar VECTOR, återgår du till att lagra vektorer som varchar.
• Requested vector base type is not supported for the negotiated vector version. betyder att ett float16 värde användes på en förbindelse som förhandlats vid vectorTypeSupport=v1. Återanslut till v2.
• Provided buffer length too small/large. Medelvärdena BufferLength matchade sizeof(SQL_SS_VECTOR_STRUCT) inte exakt + (dimension * sizeof(float)). Kontrollera att bufferten är storleksdimensionerad med sizeof(float) istället för två byte per element, även för en float16 kolumn.
• Invalid vector dimension betyder att dimensionen är noll, eller överstiger maximumet för bastypen: 1 998 för float32 och 3 996 för float16.
• Invalid vector base type betyder att type fältet hade ett annat värde än SQL_VECTOR_TYPE_FLOAT32 eller SQL_VECTOR_TYPE_FLOAT16. En noll-initierad struktur är som standard .float32
• Om en float16 kolumn rapporteras som varchar(max) som innehåller en JSON-array, har PREVIEW_FEATURES servern inte databasscoped-konfigurationen aktiverad, eller så har anslutningen förhandlats en nivå lägre än v2.