This section describes how the OCIVector descriptor is used to represent a VECTOR in OCI (Oracle Call Interface).

OCIVector descriptor is identified by the descriptor type OCI_DTYPE_VECTOR. The OCIVector descriptor can be allocated and freed using OCIDescriptorAlloc() and OCIDescriptorFree() functions respectively. An instance of OCIVector descriptor can be used to read (OCIDefine*()) and write (OCIBind*()) VECTOR content from or to the server. The OCIVectorFromText or OCIVectorFromArray function can also be used to populate the vector descriptor. The vector data present in the OCIVector descriptor can be fetched using the OCIVectorToText or OCIVectorToArray function.

This section describes the attributes of OCIVector descriptor.

This section introduces the Oracle Call Interface(OCI) data type constant for the SQL data type VECTOR. VECTOR is an Oracle Database recognized datatype.

To support bind or define for the VECTOR data type, OCI enables the external data type constant SQLT_VEC (OCIVector*) to set the native representation of the array of double, or float or integers using OCIVectorFromArray for binding purpose. The OCIVector descriptor has the canonical representation during define. User can get an array of native representation using OCIVectorToArray function.

Oracle database enables implicit conversion from char, nchar, varchar2, nvarchar2, CLOB and NCLOB to VECTOR data type and vice-versa. Therefore, users can make use of these external data types. Oracle Database takes care of the implicit conversions for binds and the client takes care of implicit conversions for defines. For older clients that cannot specify VECTOR as a bind or define type, the only bind or define type supported is the string type bind or define that corresponds to char, char varchar2, nvarchar2, CLOB, and NCLOB.

The describe Information for tables with vector column type is exposed through OCIDescribeAny().

A new external type SQLT_VEC has been introduced for PL/SQL out binds. This external data type is overloaded to do bind or define for the columns of the VECTOR data type.

OCI vector support functions are provided for converting native C array to or from the OCIVector descriptor. Additionally, char, nchar, varchar2, nvarchar2, CLOB, and NCLOB external data types can be used in binding or defining of the vector columns.

OCI users can allocate a descriptor of type OCIVector*, assign array of integers, or float, or double content to it, and then use it to write to the database table columns whose SQL data type is VECTOR. The input data type for bind and define must be SQLT_VEC.

This section describes the enhancements included in OCIDescribeAny to provide support for describe on tables or views with the new VECTOR column type.

OCI provides the ability to explicitly describe a database object (for example: table) to obtain its metadata. OCI also implicitly receives metadata of the columns being selected as part of the response to the query execution. In both explicit and implicit describe cases, the column metadata is accessed through a parameter handle of type OCIParam * or the Vector descriptor. The newly introduced OCIParam handle attributes OCI_ATTR_VECTOR_DIMENSION, OCI_ATTR_VECTOR_DATA_FORMAT, and OCI_ATTR_VECTOR_PROPERTY are used to access the vector dimension, vector data format, and vector property respectively.

OCIAttrGet((dvoid*) colParamHandle, (ub4) OCI_DTYPE_PARAM, 
           (dvoid*) &vector_dimension, (ub4 *) &vector_dimension_len,
           (ub4) OCI_ATTR_VECTOR DIMENSION, 
           (OCIError *) errhp)

OCIAttrGet((dvoid*) colParamHandle, (ub4) OCI_DTYPE_PARAM, 
           (dvoid*) &vector_data_format, (ub4 *) &vector_data_format_len,
           (ub4) OCI_ATTR_VECTOR_DATA_FORMAT, 
           (OCIError *) errhp) 

The following call returns the property of the vector for the given column parameter handle, or returns 0, if the column has no properties associated with it. Currently, the only property implemented is OCI_ATTR_VECTOR_COL_PROPERTY_IS_FLEX.

OCIAttrGet((dvoid*) colParamHandle, (ub4) OCI_DTYPE_PARAM, 
           (dvoid*) &vector_property, (ub4 *) &vector_property_len,
           (ub4) OCI_ATTR_VECTOR_PROPERTY, 
           (OCIError *) errhp) 

The attributes OCI_ATTR_VECTOR_DIMENSION, OCI_ATTR_VECTOR_DATA_FORMAT, and OCI_ATTR_VECTOR_PROPERTY must be honored for base table columns, view columns, and all elements in a SELECT list that have a vector associated with it.

SELECT statement

OCIStmt  *ociStmt = (OCIStmt *)NULL;
  	OCIDefine *defnhp1 = NULL;
  	OCIVector *vecp = NULL;
  	OraText *selstmt = "SELECT embedding FROM test ORDER BY id";
  
 	 sb2 ind1 = 0;

 	OCIHandleAlloc(ociEnv, (void*) &ociStmt, OCI_HTYPE_STMT, 0, 0);
        OCIStmtPrepare2(ociSvcCtx, ociStmt, ociError, selstmt, (ub4)sizeof((selstmt) - 1),
                         (ub4)OCI_NTV_SYNTAX, (ub4)OCI_DEFAULT);
        OCIDescriptorAlloc(ociEnv, (void**) &vecp, OCI_DTYPE_VECTOR, 0, 0);
        OCIDefineByPos(ociStmt, &defnhp1, ociError,1, &vecp, 0, SQLT_VEC, &ind1, NULL, 0, OCI_DEFAULT);
        OCIStmtExecute(ociSvcCtx, ociStmt, ociError, 0, 0, 0, 0, OCI_DEFAULT);

OraText *insStmt = "INSERT INTO test VALUES(%d, '[%d.1, %d.2, %d.3]')";

OCIHandleAlloc(ociEnv, (void*) &insStmt, OCI_HTYPE_STMT, 0, 0);
  	OCIStmtPrepare2(ociSvcCtx, ociStmt, ociError, insStmt, (ub4)stmtlen,
                         (ub4)OCI_NTV_SYNTAX, (ub4)OCI_DEFAULT);
  	OCIStmtExecute(ociSvcCtx, ociStmt, ociError, 0, 0, 0, 0, OCI_DEFAULT);

OCIStmt * ociStmt = (OCIStmt *)NULL;
OCIBind * ociBind1 = (OCIBind *)NULL;
OCIBind * ociBind2 = (OCIBind *)NULL;
OraText *insstmtbnd = "INSERT INTO test VALUES(:1, :2)";
signed int bnd1 = 500;
OCIVector *vecp = NULL;
sb2 ind1 = 0;
sb2 ind2 = 0;
OCIHandleAlloc(ociEnv, (void*) &ociStmt, OCI_HTYPE_STMT, 0, 0);
OCIStmtPrepare2(ociSvcCtx, ociStmt, ociError, insstmtbnd, (ub4)(sizeof(insstmtbnd) - 1),
                   (ub4)OCI_NTV_SYNTAX, (ub4)OCI_DEFAULT);
OCIDescriptorAlloc(ociEnv, (void**) &vecp, OCI_DTYPE_VECTOR, 0, 0);
OCIBindByPos(ociStmt, &ociBind1, ociError,                       
                1, &bnd1, sizeof(signed int), SQLT_INT,                       
				&ind1, NULL, NULL, 0, NULL, OCI_DEFAULT);
OCIBindByPos(ociStmt, &ociBind2, ociError,2, &vecp, 0, SQLT_VEC, &ind2, NULL, NULL, 0, NULL,                                          
OCI_DEFAULT);

OCIVector API

ub2   vformat = LVECTOR_IEEE_FLOAT32;
ub4   vdim = 3;
float vfarr[3];
text vtext[UB2MAXVAL];
OCIError *errhp = (OCIError *) NULL;
OCIVector *vecp = NULL;
ub4   indx;

OCIVectorToText(vecp, errhp, &vtext[0], &vtextl, OCI_DEFAULT);
for (indx=0; indx++; indx < vdim)
     vfarr[idx] = indx + indx * 3.1427;
OCIVectorFromArray(vecp, errhp, vformat, vdim,
                               (void *)&vfarr[0], OCI_DEFAULT);