Vektör veri türü (ODBC)

Bu makalede, 18.6.1.1 sürümünden başlayarak SQL Server için Microsoft ODBC Sürücüsü tarafından uygulanan vektör SQL veri türü belgelenmiştir. Bu belgede Vektör için Microsoft sürücüsünün davranışı özetlenmiştir ve kullanım kılavuzu, API'ye özgü notlar ve kod parçacıkları sağlanır. Vektör veri türlerine genel bakış için bkz. Vektör veri türü.

Genel Bakış

SQL Server için Microsoft ODBC Sürücüsü vektör veri türünü yerel olarak destekler. Uygulamalar makine öğrenmesi ve yapay zeka iş yüklerinde yaygın olarak kullanılan sabit boyutlu sayısal eklemeleri verimli bir şekilde depolayabilir, alabilir ve işleyebilir. Sürücü, standart ODBC API'leri ve C veri türleri aracılığıyla vektör desteğini kullanıma sunar. Uygulamalar, mevcut ODBC iş akışlarını değiştirmeden SQL Server vektör sütunlarıyla birlikte çalışabilir.

Şunlar için geçerlidir: SQL Server 18.6.1.1 ve sonraki sürümleri için Microsoft ODBC Sürücüsü. Temel tip için destek float16 18.7.1.1 veya daha yeni sürüm gerektirir.

Vektör desteği varsayılan olarak devre dışı bırakılmış ve açıkça etkinleştirilmiş olmalıdır.

Temel eleman türleri

Bir vektör sütunu, bir temel eleman tipini ilan eder. Sürücü, SQL Server'ın tanımladığı her iki türü de destekler.

Temel tür Tip göstergesi Tel üzerindeki eleman başına bayt Maksimum boyut Sürücü sürümü
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 varsayılan değerdir. Yarı hassasiyetli depolama kullanmak için sütunu veya parametreyi şu şekilde bildirin.VECTOR(<dimensions>, float16) Bir float16 eleman teldeki baytların yarısını kapladığı için, bir float16 vektör aynı 8.000 baytlık yük sınırı içinde iki kat fazla boyut tutar.

Important

Uygulama tamponu, her iki temel tip için her zaman (eleman başına 4 bayt) bir dizidir float . Sürücü, tel üzerinde yarı hassasiyet ile tamponunuzda tek hassasiyet arasında dönüşüm yapar. Her tamponu ile sizeof(float)boyutlandırın, hiçbir zaman bir sütun için bile eleman float16 başına 2 bayt ile ölçüleyin.

Çünkü float16 mantissa bitleri daha azdır float32, bir float16 sütundan geçen bir gidiş-dönüş kayıplıdır. Değerler, eklemede en yakın temsil edilebilir yarı hassasiyet değerine yuvarlanır ve geri float32 okunan değer, o yuvarlanan değerin genişletilmesiyle gösterilir.

Sunucuda, float16 veritabanı kapsamlı yapılandırması etkin olan SQL Server 2025 (17.x) PREVIEW_FEATURES gerektirir. Daha fazla bilgi için bkz. Vektör veri tipinde yarı hassasiyetli kayan nokta desteği.

Yerel C gösterimi

Vektör desteği etkinleştirildiğinde, vektör sütunları adlı SQL_SS_VECTOR_STRUCTbir türlenmiş C yapısı kullanılarak değiştirilir.

    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: vektördeki öğe sayısını açıklar
  • type: temel eleman türünü SQL_VECTOR_TYPE_FLOAT32 tanımlar, veya SQL_VECTOR_TYPE_FLOAT16
  • data.f32 / data.f16: vektör değerlerini içeren uygulama tamponuna işaret eder

Her iki birlik üyesi de ve float* değiştirilebilir olarak ilan edilir, çünkü istemci tarafı tamponu her iki temel tip için de değerleri taşır float32 . Niyetinizi belgeleyen üyeyi kullanın.

Vektör desteğini etkinleştirme

bağlantı dizesi anahtar kelimesi, vectorTypeSupport bağlantının müzakere ettiği yerel vektör desteği seviyesini seçer.

Değer Davranış
off (varsayılan) Vektör sütunları, JSON dizilerini içeren varchar(max) olarak görünür.
v1 Temel tip için float32 doğal vektör desteği.
v2 Hem float32 temel hem de float16 temel tipler için yerel vektör desteği. Sürücü sürüm 18.7.1.1 veya daha sonrasını gerektirir.

Ayrıca bağlantı kolunu tahsis ettikten sonra ve bağlanmadan önce pre-connect bağlantı özniteliğiyle SQL_COPT_SS_VECTOR_TYPE_SUPPORT seviyeyi ayarlayabilirsiniz.

  • Microsoft sürücüsü, sürücüye özgü bir C bağlaması SQL_C_SS_VECTOR sunar ve vektör çıkışını desteklerSQL_C_BINARY. Uygulamada:

    • vectorTypeSupport=v1 Etkinleştirdiğinizde veya v2, alım API'leri (örneğin SQLGetData ve SQLBindCol), vektör sütunlarını veya SQL_C_SS_VECTORSQL_C_BINARYveya şeklinde döndürebilir. SQL_C_SS_VECTOR vektörleri sıkıştırılmış, yazılan bir biçimde döndürür. SQL_C_BINARY bir varbinary yükü döndürür.

    • Giriş veya parametre bağlama için sürücü hem SQL_C_SS_VECTOR de SQL_C_BINARY. SQL_C_SS_VECTOR yazılan, sıkıştırılmış bir giriş bağlaması sağlar. SQL_C_BINARY eşdeğer ve taşınabilir. Sürücünün yükü yerel SQL_C_SS_VECTOR türü olarak işlemesini istediğinizde kullanın.

    • olduğunda vectorTypeSupport=off, vektör sütunları JSON dizilerini içeren varchar(max) olarak görünür.

v2, bir üst v1kümedir, yani üzerinde v2 müzakere edilen bir bağlantı sütunları tam olarak böyle v1 yönetirfloat32. Üzerinde v1 müzakere edilen bir bağlantıda bir float16 değer göndermek, uygulama bir float16 sütunla karşılaştığında Kullan v2 ile başarısız Requested vector base type is not supported for the negotiated vector version. olur.

Uygulamaların vektöre özgü türleri kullanmadan önce ODBC sürümünü ODBC 3.8 olarak da ayarlaması gerekir:

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

Desteklenen bağlama biçimleri

Yerel vektör bağlama

C türü: SQL_C_SS_VECTOR

Bu biçim, performans açısından kritik uygulamalar için önerilir.

İkili bağlama

C türü: SQL_C_BINARY

Vektörler, SQL_C_SS_VECTOR ile aynı düzen kullanılarak döndürülür. Uygulamalar, alt düzey birlikte çalışabilirlik senaryoları için bu biçimi kullanabilir. Veri işaretçisi arabelleği, yapı bellek adresiyle bitişik veya bitişik olmayabilir.

ODBC API kılavuzu

Bu bölümde ODBC API'lerinin arabellek düzeni gereksinimleri NULL , işleme ve desteklenen veri gösterimleri de dahil olmak üzere SQL Server vektör verileriyle nasıl etkileşime geçdiği açıklanmaktadır. Tüm davranışlar, vectorTypeSupport ortam ODBC v1 3.8 için ayarlandığında veya v2 ayarlandığında geçerlidir.

Bu bölümdeki her tampon boyutu formülü, her iki temel tip için bir eleman kullanır sizeof(float) , çünkü istemci tarafı tamponu her zaman değerleri taşır float32 . Bir float16 sütun, tamponunuzun düzenini değil, kablo üzerindeki baytları değiştirir.

SQLBindCol

SQLBindCol Sonuç kümesindeki vektör sütunlarını uygulama arabelleklerine bağlamak için kullanın.

  • Tipik çağrı:
    SQLRETURN SQLBindCol(
      SQLHSTMT       StatementHandle,
      SQLUSMALLINT   ColumnNumber,
      SQLSMALLINT    TargetType,
      SQLPOINTER     TargetValuePtr,
      SQLLEN         BufferLength,
      SQLLEN *       StrLen_or_IndPtr);

  • TargetType: SQL_C_SS_VECTOR veya SQL_C_BINARY kullanın.

  • TargetValuePtr: SQL_SS_VECTOR_STRUCT olduğunda bir ile TargetType dizisine işaretçi; aksi takdirde, SQL_C_SS_VECTOR içindeki değer kadar boyuta sahip bir arabelleğe işaretçi.

  • BufferLength: sizeof(SQL_SS_VECTOR_STRUCT) + sütun arabelleği için ayrılan bayt sayısı (boyut * 4).

  • StrLen_or_IndPtr: döndürülen vektörünün bayt uzunluğunu (SQL_DESC_OCTET_LENGTH) alan işaretçi. Değeri sizeof(SQL_SS_VECTOR_STRUCT) + float dizi boyutu (boyut * 4).

Bu boyutlar bir float16 sütun için aynıdır. Sürücü, tamponunuzu doldurdukça her yarı hassasiyet elemanını a'ya float genişletir ve genişletilmiş uzunluğu bildirir.

Arabellek düzeni beklentileri

Bitişik olmayan arabellek (önerilir)

  • Uygulama satır başına bir tane SQL_SS_VECTOR_STRUCT ayırır.
  • Uygulama data.f32 için bellek ayırır.
  • Sürücü vektör meta verilerini doldurur ve öğe değerlerini sağlanan kayan arabelleğe yazar.
    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());

Bitişik arabellek

  • Uygulama tek bir arabellek ayırır ve ODBC bunu buna göre doldurur.
  • Float dizisi yapıdan hemen sonra başlamalıdır.
  • Sürücü bu bitişik bölgeye işaret etmesi için data.f32 ayarlar.
    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());

SQLBindCol için NULL işleme

Sütun değeri NULL olduğunda, sürücü *StrLen_or_IndPtr'i SQL_NULL_DATA olarak ayarlar ve arabelleği doldurmaz. Vektör içeriğine erişmeden önce göstergeyi her zaman kontrol edin.

Uyarı

Vektör sütunları için okuma ve satır getirme davranışları, SQLFetch ve SQLFetchScroll altında ayrıntılı olarak açıklanmaktadır (getirme semantiği ve dizi getirme örnekleri için bu API başvurularına bakın).

SQLGetData

İlişkisiz sütunlardan vektör verilerini almak için kullanın SQLGetData .

  • Tipik çağrı:
    SQLRETURN SQLGetData(
      SQLHSTMT       StatementHandle,
      SQLUSMALLINT   Col_or_Param_Num,
      SQLSMALLINT    TargetType,
      SQLPOINTER     TargetValuePtr,
      SQLLEN         BufferLength,
      SQLLEN *       StrLen_or_IndPtr);

  • TargetType: SQL_C_SS_VECTOR veya SQL_C_BINARY kullanın.

  • TargetValuePtr: SQL_SS_VECTOR_STRUCT olduğunda bir ile TargetType dizisine işaretçi; aksi takdirde, SQL_C_SS_VECTOR içindeki değer kadar boyuta sahip bir arabelleğe işaretçi.

  • BufferLength: sizeof(SQL_SS_VECTOR_STRUCT) + sütun arabelleği için ayrılan bayt sayısı (boyut * 4).

  • StrLen_or_IndPtr: döndürülen vektörünün bayt uzunluğunu (SQL_DESC_OCTET_LENGTH) alan işaretçi. Değeri sizeof(SQL_SS_VECTOR_STRUCT) + kayan dizi boyutu (boyut * 4) şeklindedir.

Parçalı veri alma desteklenmez. Vektörlerin tamamını tek bir çağrıda almanız gerekir.

Örnek (yerel vektör):

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

SQLGetData için NULL işleme

Sütun değeri NULL olduğunda, sürücü *StrLen_or_IndPtr'i SQL_NULL_DATA olarak ayarlar ve arabelleği doldurmaz. Vektör içeriğine erişmeden önce göstergeyi her zaman kontrol edin.

Uyarı

Vektör sütunları için okuma ve satır getirme davranışları, SQLFetch ve SQLFetchScroll altında ayrıntılı olarak açıklanmaktadır (getirme semantiği ve dizi getirme örnekleri için bu API başvurularına bakın).

SQLFetch

Sonraki satırı almak ve bağlı SQLFetch sütunları doğru bir şekilde gerçekleştirmek için SqlVector kullanın.

  • Tipik çağrı:
    SQLRETURN SQLFetch(
     SQLHSTMT     StatementHandle);

standart döngüde SQLFetch çağrısını, sütunların zaten SqlVector ile bağlı olduğu SQLBindCol sütunlarla yapın. Veya SQLGetData öğesini, verileri uygulama arabelleğine almak için kullanın.

Örnek (yerel vektör):

    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

Belirtilen yönlendirmeye göre satır kümelerini getirmek için SQLFetchScroll kullanın (sonraki, önceki, mutlak, göreli, yer işareti). Sürücü, vektör verilerini uygulama arabelleklerine doğru şekilde kopyalar.

  • Tipik çağrı:
    SQLRETURN SQLFetchScroll(
      SQLHSTMT      StatementHandle,
      SQLSMALLINT   FetchOrientation,
      SQLLEN        FetchOffset);

Örnek (yerel vektör):

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

SQL Server'a vektör değerleri göndermek için kullanın SQLBindParameter .

  • Tipik çağrı:
    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: doldurulan bir SQL_SS_VECTOR_STRUCT
  • ColumnSize: giriş parametreleri için yoksayılır. Çıktı parametreleri ve yürütme sırasında veri senaryoları için toplam vektör boyutunu belirtin: sizeof(SQL_SS_VECTOR_STRUCT) + (kayan dizi boyutu)
  • DecimalDigits: giriş parametreleri için yoksayılır. Çıktı parametreleri ve yürütme sırasında veri senaryoları için vektör temel türünü belirtin
  • BufferLength: ≥ sizeof(SQL_SS_VECTOR_STRUCT) + (boyut * sizeof(float))
  • *StrLen_or_IndPtr: aynı toplam boyutu içermelidir

Temel tipin geldiği yer

Sürücü, temel eleman türünü parametre yönüne bağlı olarak farklı bir yerden okur. Bunu yanlış yapmak, parametredeki float16 en yaygın neden Invalid vector dimension veya Provided buffer length too small/large hatadır.

Parametre türü Baz tip kaynağı Boyut kaynağı
Giriş ve giriş/çıkış Geçtiği type alan SQL_SS_VECTOR_STRUCT dimension Aynı yapının alanı
Saf çıktı DecimalDigits Türeme ColumnSize(ColumnSize - sizeof(SQL_SS_VECTOR_STRUCT)) / sizeof(float)
Data-an-execut DecimalDigits Türetilir ColumnSizeve geçen uzunlukla çapraz kontrol edilir SQL_LEN_DATA_AT_EXEC

Bir giriş parametresi için, BufferLength tam olarak + (boyut * sizeof(float)) eşit sizeof(SQL_SS_VECTOR_STRUCT) olmalıdır. Daha büyük veya daha küçük bir değer tolere edilmek yerine başarısız olur.

Örnek (doğal vektör, 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);

Örnek (doğal vektör, float16):

Sadece alan type değişiyor. Değer dizisi bir float dizi olarak kalır ve cb aynı şekilde hesaplanır.

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

Örnek (float16 çıktı parametresi):

Saf çıktı parametresi girdi yapısı taşımaz, bu nedenle baz türü aktarılır DecimalDigits ve boyut türetilir 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);

SQLBindParameter için NULL işleme

Uygulamalar desteklenen yaklaşımlardan birini kullanarak bir NULL vektör gösterebilir:

  • *StrLen_or_IndPtr'yi SQL_NULL_DATA olarak ayarla ve NULL'yi ParameterValuePtr olarak geçir

  • SQL_SS_VECTOR_STRUCT ile sağlayın

    boyut kümesi tipi sütunun temel tipine göre ayarlandı data.f32 = NULL

SQLPutData

Sürücü şu kısıtlamalara sahip vektör parametrelerini destekler SQLPutData :

  • İlk çağrıda vektörlerin tamamını sağlamanız gerekir.

  • Sürücü öbekli veya artımlı vektör iletimini desteklemez.

  • NULL işlemi, SQLBindParameter ile aynı kurallara tabidir.

  • Tipik çağrı:

    SQLRETURN SQLPutData(
        SQLHSTMT     StatementHandle,
        SQLPOINTER   DataPtr,
        SQLLEN       StrLen_or_Ind);
  • DataPtr: doldurulan bir SQL_SS_VECTOR_STRUCT
  • StrLen_or_Ind: sizeof(SQL_SS_VECTOR_STRUCT) + (boyut * sizeof(float))

Örnek (yerel vektör):

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

Tanımlayıcı meta verileri

Vektör desteğini etkinleştirdiğinizde, SQL Server için Microsoft ODBC Sürücüsü vektör meta verilerini standart ODBC tanımlayıcı API'leri aracılığıyla kullanıma sunar. Uygulamalar tanımlayıcı bilgileri, vektör şeması ayrıntılarını keşfetmek, arabellek boyutlarını hesaplamak ve parametreler ile sonuç kümeleri için bağlamaları doğru yapılandırmak amacıyla kullanabilir.

Vektör için tanımlayıcı alan değerleri

Aşağıdaki tabloda SQL Server vektör sütunları ve parametreleri için tanımlayıcı alan değerleri özetlenmiştir.

Tanımlayıcı Alanı Değer Description
SQL_DESC_TYPE SQL_SS_VECTOR (-156) Temel SQL veri türü tanımlayıcısı
SQL_DESC_CONCISE_TYPE SQL_SS_VECTOR Kısa SQL veri türü
SQL_DESC_TYPE_NAME vector SQL türü adı
SQL_DESC_LOCAL_TYPE_NAME vector Sürücü yerel türü adı
SQL_DESC_LENGTH sizeof(SQL_SS_VECTOR_STRUCT) + (dimension * sizeof(float)) Vektör değerinin mantıksal boyutu
SQL_DESC_OCTET_LENGTH Aynı SQL_DESC_LENGTH gibi Bayt cinsinden fiziksel boyut
SQL_DESC_PRECISION Aynı SQL_DESC_LENGTH gibi Vektör boyutunu raporlamak için kullanılır
SQL_DESC_SCALE SQL_VECTOR_TYPE_FLOAT32 veya SQL_VECTOR_TYPE_FLOAT16 Vektör temel öğe türü
SQL_CA_SS_VECTOR_DIMENSION dimension Vektördeki eleman sayısı
SQL_DESC_DISPLAY_SIZE dimension * VECTOR_FLOAT32_TO_CHAR_JSON_MAX_SIZE En fazla JSON ekran uzunluğu
SQL_DESC_FIXED_PREC_SCALE SQL_FALSE Vektör sabit duyarlık/ölçek içermiyor
SQL_DESC_NULLABLE SQL_NULLABLE Vektör sütunları değerlere izin verir NULL
SQL_DESC_NUM_PREC_RADIX 0 Sayısal olmayan tür
SQL_DESC_SEARCHABLE SQL_PRED_NONE Önermelerde kullanılamaz
SQL_DESC_UNSIGNED SQL_TRUE Öğe türü işaretsiz
SQL_DESC_AUTO_UNIQUE_VALUE SQL_FALSE Otomatik olarak benzersiz değil
SQL_DESC_CASE_SENSITIVE SQL_FALSE Büyük/küçük harf duyarlılığı yok
SQL_DESC_UPDATABLE SQL_ATTR_READWRITE_UNKNOWN Güncelleştirilebilirlik bilinmiyor

SQL_DESC_LENGTH, SQL_DESC_OCTET_LENGTH, ve SQL_DESC_PRECISION hepsi istemci tarafı tamponunu tanımlar, böylece bir float16 sütun float32 ile birlikte + (boyut * sizeof(float)) raporlar sizeof(SQL_SS_VECTOR_STRUCT) . İkisi sadece SQL Server'ın depoladığı ve ilettiği bayt sayısına göre farklıdır.

SQL_DESC_SCALE temel türleri ayıran tek tanımlayıcı alandır. Bunu okumak, bir uygulamanın bir sütunun float32 mı yoksa float16.

Vektör boyutu için SQLColAttribute

18.7.1.1 sürümünden itibaren, SQL_CA_SS_VECTOR_DIMENSION bir vektör sütununun eleman sayısını doğrudan döndürür, böylece bir uygulama artık bunu bir uzunluk alanından türetmek zorunda kalmaz:

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

Ayrıca bir uygulama tanımlayıcısı veya IPD'de vektör parametresi için ayarlayabilirsiniz SQL_CA_SS_VECTOR_DIMENSION . Başka herhangi bir parametre türünü ayarlamak, geçersiz bir tanımlayıcı alanı hatası getirir.

SQLDescribeCol

SQLDescribeCol sütununu çağırdığınızda:

  • DataType eşittir SQL_SS_VECTOR
  • ColumnSize eşleşiyor SQL_DESC_PRECISION
  • DecimalDigits temel eleman tip göstergesidir, sayısal bir ölçek değildir: 0 için float32 ve 1 için float16
  • Nullable eşittir SQL_NULLABLE

Bildirilen sütun boyutu yerel vektör yükü boyutunu temsil eder: sizeof(SQL_SS_VECTOR_STRUCT) + (boyut * sizeof(float))

SQLDescribeParam

SQLDescribeParam bir vektör parametresi için kullandığınızda:

  • DataType eşittir SQL_SS_VECTOR
  • ColumnSize yerel vektör yükü boyutuna eşittir
  • DecimalDigits temel eleman tip göstergesidir, sayısal bir ölçek değildir: 0 için float32 ve 1 için float16
  • Nullable eşittir SQL_NULLABLE

Bu bilgiler, uygulamaların bağlamadan önce parametre arabelleklerini doğru bir şekilde ayırmasına olanak tanır.

SQLColAttribute

  • Vektör yükünün tam bayt uzunluğunu almak için kullanın SQLColAttribute(hstmt, ColumnNumber, SQL_DESC_OCTET_LENGTH, ...) . SQL_DESC_LENGTH ve SQL_DESC_PRECISION sürücüye özgü değerler taşıyabilir. Bayt sayısı için tercih edin SQL_DESC_OCTET_LENGTH.

    • NULL işleme: NULL bir sütun olduğunda, SQLColAttribute veya StrLen_or_IndPtrSQLBindCol ile kullanıldığında SQL_NULL_DATA döndürür. Döndürülen uzunlukları veya arabellekleri kullanmadan önce SQL_NULL_DATA'i denetleyin.

Toplu kopyalama (BCP)

Diğer veri türlerinde olduğu gibi BCP dosyaları ve API aracılığıyla vektör sütunlarını toplu olarak içeri ve bcp_bind dışarı aktarabilirsiniz. Şu anda vektör içeri ve dışarı aktarma yalnızca yerel biçimi (SQLVECTOR) veya varbinary (SQLBINARY ) destekler ancak karakter biçimini desteklemez. Vektör türü ile karakter türü arasında dönüştürme desteklenmez.

Toplu kopyalama, sürücünün geri kalanıyla aynı destek seviyesini sağlar. Bir sütun, float16 üzerinde vectorTypeSupport=v2müzakere edilen bir bağlantı gerektirir. BCP yardımcı programında, -z0 için float32 ve -z1 için float16kullanın. Daha fazla bilgi için bkz. bcp yardımcı programı.

Vektör için tür belirteci, varsayılan ön ek uzunluğu ve varsayılan alan uzunluğu hakkında daha fazla bilgi için bkz. Dosya Depolama Türü, Ön Ek Uzunluğu ve Alan Uzunluğu.

bcp_gettypename

bcp_gettypename SQL türü adını almak için kullandığınızda, BCP tür belirtecini (SQLVECTOR) ve "vector"döndürür.

bcp_bind

Program değişkenlerini bcp_bind sütununa toplu olarak eklemek için kullanın.

Tipik çağrı:

RETCODE bcp_bind (
        HDBC hdbc,
        LPCBYTE pData,
        INT cbIndicator,
        DBINT cbData,
        LPCBYTE pTerm,
        INT cbTerm,
        INT eDataType,
        INT idxServerCol);
  • pData: cbIndicator sıfırsa, içinde SQL_SS_VECTOR_STRUCT alanı bulunan verilerine işaret eden bir vectorStruct.data.f32 dizi verisi içerir. Sıfır cbIndicator değilse gösterge, veriden doğrudan önce bellekte görünür. Bu nedenle pData , önce bayt uzunluk göstergesine ve ardından vektör yapısına sahip cbIndicator bir arabelleğe işaret eder.
  • cbData: sağlanıyorsa, değerin - sizeof(SQL_SS_VECTOR_STRUCT) + (sizeof(float) * boyut) değerine tam olarak eşit olması gerekir. Aksi takdirde bir hata oluşur. Bu, her iki temel tipi için de aynıdır, çünkü sınırlı tampon her iki şekilde de değerleri tutar float32 .
  • eDataType: SQLVECTOR veya SQLBINARY

Yapının alanını type sütunun temel tipine ayarlayın. Bir float16 sütun için, sürücü bağlı diziyi kablo yükünü oluştururken yarı hassasiyete dönüştürür float32 ; böylece yerel formatta yazılmış veri dosyası her eleman için iki bayt tutar.

bcp_bind aracılığıyla bir vektör sütununa veri aktardığınızda, eDataType öğesini SQLVECTOR veya SQLBINARY olarak ayarlayın. Her iki durumda da SQL_SS_VECTOR_STRUCTbiçiminde veri sağlamanız gerekir.

Sorun giderme ve ipuçları

  • SQLGetTypeInfo listelemiyorsaVECTOR, vektörleri varchar olarak depolamaya geri dönün.
  • Requested vector base type is not supported for the negotiated vector version. float16 Bir bağlantıda bir değerin kullanıldığı anlamına gelirvectorTypeSupport=v1. Yeniden bağlantı kurun v2.
  • Provided buffer length too small/large.Means BufferLength tam olarak + (boyut * sizeof(float)) ile eşleşmiyordu sizeof(SQL_SS_VECTOR_STRUCT) . Tamponun bir sütun için bile iki bayt yerine bir element float16 başına iki bayt ile boyutlandırıldığından sizeof(float) emin olun.
  • Invalid vector dimension boyutun sıfır olduğu veya temel tip için maksimumu aştığı anlamına gelir: 1.998 için float32 ve 3.996 için float16.
  • Invalid vector base typeAlanın type veya SQL_VECTOR_TYPE_FLOAT16dışında SQL_VECTOR_TYPE_FLOAT32 bir değere sahip olduğu anlamına gelir. Sıfır başlatılmış bir yapı varsayılan olarak .float32
  • Bir float16 sütun varchar(max) olarak JSON dizisi içeriyorsa, sunucuda PREVIEW_FEATURES veritabanı kapsamlı yapılandırma etkinleştirilmez veya bağlantı daha düşük v2bir seviyede pazarlık yapılmıştır.
  • Last updated on