Update Documentation for Binary Vectors and BFILE support

Author: sharadraju

doc/src/api_manual/connection.rst

@@ -611,8 +611,8 @@ Connection Methods
     LOBs created with ``createLob()`` can be bound for IN, IN OUT and OUT
     binds.
 
-    See :ref:`Working with CLOB, NCLOB and BLOB Data <lobhandling>` and :ref:`LOB
-    Bind Parameters <lobbinds>` for more information.
+    See :ref:`Working with CLOB, NCLOB, BLOB and BFILE Data <lobhandling>` and
+    :ref:`LOB Bind Parameters <lobbinds>` for more information.
 
     The parameters of the ``connection.createLob()`` method are:
 
@@ -632,7 +632,7 @@ Connection Methods
           - Description
         * - ``type``
           - Number
-          - One of the constants :ref:`oracledb.CLOB <oracledbconstantsnodbtype>`, :ref:`oracledb.BLOB <oracledbconstantsnodbtype>`, or :ref:`oracledb.NCLOB <oracledbconstantsnodbtype>` (or equivalent ``DB_TYPE_*`` constants).
+          - One of the constants :ref:`oracledb.CLOB <oracledbconstantsnodbtype>`, :ref:`oracledb.BLOB <oracledbconstantsnodbtype>`, :ref:`oracledb.NCLOB <oracledbconstantsnodbtype>`, or :ref:`oracledb.BFILE <oracledbconstantsnodbtype>` (or equivalent ``DB_TYPE_*`` constants).
 
     **Callback**:
 

doc/src/api_manual/lob.rst

@@ -155,6 +155,46 @@ Lob Methods
         * - Error ``error``
           - This optional parameter is used for the error emitted in an ``error`` event.
 
+.. method:: lob.fileExists()
+
+    .. versionadded:: 6.6
+
+    **Promise**::
+
+        promise = fileExists();
+
+    Returns a boolean which indicates whether the file specified by the LOB
+    exists in the directory alias or not. This method returns *true* if the
+    file exists in the directory and *false* if it does not. If the directory
+    that this method is trying to access does not exist, then this method
+    returns an error. This method can only be used if the LOB type is BFILE.
+    For all other LOB types, this method returns the ``NJS-156: operation is
+    only supported on BFILE LOBs`` error.
+
+    **Callback**:
+
+    If you are using the callback programming style::
+
+        fileExists(function(Error error, Boolean val));
+
+    The parameters of the callback function
+    ``function(Error error, Boolean val)`` are:
+
+    .. list-table-with-summary::
+        :header-rows: 1
+        :class: wy-table-responsive
+        :align: center
+        :widths: 15 30
+        :summary: The first column displays the callback function parameter.
+          The second column displays the description of the parameter.
+
+        * - Callback Function Parameter
+          - Description
+        * - Error ``error``
+          - If ``fileExists()`` succeeds, ``error`` is NULL. If an error occurs, then ``error`` contains the :ref:`error message <errorobj>`.
+        * - Boolean ``val``
+          - Indicates whether the file exists in the directory. This parameter will be *true* if the file exists in the directory and *false* if it does not.
+
 .. method:: lob.getData()
 
     .. versionadded:: 4.0
@@ -241,3 +281,49 @@ Lob Methods
           - If ``getData()`` succeeds, ``error`` is NULL. If an error occurs, then ``error`` contains the :ref:`error message <errorobj>`.
         * - String ``data`` or Buffer ``data``
           - The value of the LOB.
+
+.. method:: lob.getDirFileName()
+
+    .. versionadded:: 6.6
+
+    .. code-block:: javascript
+
+        getDirFileName();
+
+    This synchronous method returns an object containing the directory alias
+    and file name of the LOB object. This method can only be used if the LOB
+    type is BFILE. For all other LOB types, this method returns the
+    ``NJS-156: operation is only supported on BFILE LOBs`` error.
+
+.. method:: lob.setDirFileName()
+
+    .. versionadded:: 6.6
+
+    .. code-block:: javascript
+
+        setDirFileName(Object dirFileName);
+
+    This synchronous method sets the directory alias and file name of the LOB.
+    This method can only be used if the LOB type is BFILE. For all other LOB
+    types, this method returns the ``NJS-156: operation is only supported on
+    BFILE LOBs`` error.
+
+    .. note::
+
+        This method can only be used in node-oracledb Thin mode.
+
+    The parameters of the ``lob.setDirFileName()`` method are:
+
+    .. list-table-with-summary:: lob.setDirFileName() Parameters
+        :header-rows: 1
+        :class: wy-table-responsive
+        :align: center
+        :widths: 10 10 30
+        :summary: The first column displays the parameter. The second column displays the data type of the parameter. The third column displays the description of the parameter.
+
+        * - Parameter
+          - Data Type
+          - Description
+        * - ``dirFileName``
+          - Object
+          - This parameter contains the directory alias and file name of the BFILE type LOB.

doc/src/api_manual/oracledb.rst

@@ -214,6 +214,10 @@ for common :ref:`Oracle Database Type Constants <oracledbconstantsdbtype>`.
       - Value
       - ``DbType`` Object Equivalent
       - Notes
+    * - ``oracledb.BFILE``
+      - 2020
+      - ``oracledb.DB_TYPE_BFILE``
+      -
     * - ``oracledb.BLOB``
       - 2019
       - ``oracledb.DB_TYPE_BLOB``
@@ -874,6 +878,7 @@ Constants for two-phase commit (TPC) functions
 
 Vector Type Constants
 ---------------------
+
 .. versionadded:: 6.5
 
 Constants for the :ref:`vectorFormat <execmetadata>` attribute.
@@ -899,6 +904,13 @@ Constants for the :ref:`vectorFormat <execmetadata>` attribute.
     * - ``oracledb.VECTOR_FORMAT_INT8``
       - 4
       - The storage format of each dimension value in the VECTOR column is an 8-bit signed integer.
+    * - ``oracledb.VECTOR_FORMAT_BINARY``
+      - 5
+      - The storage format of each dimension value in the VECTOR column is represented as a single bit. All the dimensions for the vector are stored as an array of 8-bit unsigned integers.
+
+.. versionchanged:: 6.6
+
+    The ``oracledb.VECTOR_FORMAT_BINARY`` constant was added.
 
 .. _oracledbproperties:
 

doc/src/user_guide/appendix_a.rst

@@ -156,7 +156,7 @@ node-oracledb Thin and Thick modes. For more details see :ref:`modediff`.
       - No
       - Yes
     * - SQL execution (see :ref:`sqlexecution`)
-      - Yes - Bind and fetch all types except BFILE
+      - Yes
       - Yes
     * - PL/SQL execution (see :ref:`plsqlexecution`)
       - Yes - For scalar types and collection types using array interface
@@ -297,8 +297,8 @@ node-oracledb Thin and Thick modes. For more details see :ref:`modediff`.
       - Yes
       - Yes - May need to fetch as CLOB
     * - BFILE data type
-      - No
-      - No
+      - Yes
+      - Yes
     * - TIMESTAMP WITH TIME ZONE data type (see :ref:`oracledbconstantsdbtype`)
       - Yes
       - Yes
@@ -734,7 +734,7 @@ when binding numeric values.
       - Yes
     * - BFILE
       - DB_TYPE_BFILE
-      - No
+      - Yes
     * - BLOB
       - DB_TYPE_BLOB
       - Yes

doc/src/user_guide/lob_data.rst

@@ -1,16 +1,26 @@
 .. _lobhandling:
 
-*******************************
-Using CLOB, NCLOB and BLOB Data
-*******************************
+***************************************
+Using CLOB, NCLOB, BLOB, and BFILE Data
+***************************************
 
 Oracle Database uses LOB data types to store long objects. The CLOB type
 is used for character data and the BLOB type is used for binary data.
 NCLOB can hold character data in the database’s alternative `national
 character set <https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=GUID
--AA8D783D-7337-4A61-BD7D-5DB580C46D9A>`__.
-In node-oracledb, LOBs can be represented by instances of the
-:ref:`Lob <lobclass>` class or as Strings and Buffers.
+-AA8D783D-7337-4A61-BD7D-5DB580C46D9A>`__. The `BFILE <https://www.oracle.com/
+pls/topic/lookup?ctx=dblatest&id=GUID-D4642C92-F343-4700-9F1F-486F82249FB8>`__
+type is used for referencing a file stored on the server operating system
+where Oracle Database is running, outside the database tablespace. The BFILE
+LOB type was introduced in node-oracledb 6.6.
+
+node-oracledb uses :ref:`oracledb.CLOB <oracledbconstantsdbtype>`,
+:ref:`oracledb.BLOB <oracledbconstantsdbtype>`,
+:ref:`oracledb.NCLOB <oracledbconstantsdbtype>`, and
+:ref:`oracledb.BFILE <oracledbconstantsdbtype>` to represent CLOB, BLOB,
+NCLOB, and BFILE data types respectively. In node-oracledb, LOBs can be
+represented by instances of the :ref:`Lob <lobclass>` class or as Strings and
+Buffers.
 
 There are runnable LOB examples in the GitHub
 `examples <https://github.com/oracle/node-oracledb/tree/main/examples>`__
@@ -25,6 +35,11 @@ Node.js String or Buffer types can be passed into PL/SQL blocks or
 inserted into the database by binding to LOB columns or PL/SQL
 parameters.
 
+.. _insertclobblob:
+
+Inserting CLOBs and BLOBs
+-------------------------
+
 Given the table:
 
 .. code-block:: sql
@@ -99,13 +114,105 @@ Node.js or node-oracledb, it will need to be streamed to a
 :ref:`Lob <lobclass>`, as discussed in :ref:`Streaming
 Lobs <streamsandlobs>`.
 
+See :ref:`fetchinglob` for information on how to fetch CLOBs, BLOBs, and NCLOBs.
+
+.. _insertbfile:
+
+Inserting BFILEs
+----------------
+
+The data of `BFILE <https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=
+GUID-D4642C92-F343-4700-9F1F-486F82249FB8>`__ type LOB is stored as files in a
+directory in the Oracle Database server. The column of type BFILE stores a
+reference to the file stored in the Oracle Database server file system.
+The BFILE column data cannot be updated from within your application since
+Oracle Database allows read-only access to the data stored in BFILE columns.
+
+Before using the BFILE data type, ensure that you have created a directory in
+the database server file system to store the file. Each BFILE object is
+associated with:
+
+- A DIRECTORY object which is an alias for the directory on the database
+  server file system that stores the file with BFILE data. For example, if
+  your server is running on a Linux machine, you can create a DIRECTORY object
+  by using:
+
+  .. code-block:: sql
+
+        CREATE OR REPLACE DIRECTORY MYBFILEDIR AS '/tmp/my-bfile-dir'
+
+  ``MYBFILEDIR`` is the directory alias.
+  ``/tmp/my-bfile-dir`` is the physical operating system directory in the
+  database server file system. It is a string containing the full path name of
+  the directory and follows the operating system rules.
+
+  This directory and alias are used in subsequent examples.
+- The file name of the physical file which is stored in the directory in the
+  database server file system. For example, ``MYBFILE.JPG``. The file in this
+  directory can be copied using operating system commands such as ``cp`` or
+  ``COPY``. This file name is used in subsequent examples.
+
+Ensure that you have the required access permissions to the directory. For
+Windows platform, ensure that you have set the Access Control Lists (ACL) or
+Discretionary Access Control List (DACL) correctly to access the file.
+
+The following table will be used in the subsequent examples to demonstrate
+using ``BFILE`` data with node-oracledb:
+
+.. code-block:: sql
+
+    CREATE TABLE bfile_table(
+        id NUMBER,
+        bfilecol BFILE
+    );
+
+To insert data of BFILE data type:
+
+.. code-block:: javascript
+
+    const result = await connection.execute(
+        `INSERT INTO bfile_table VALUES (:id, BFILENAME(:BFILEDIR, :BFILENAME))`,
+        [101, "MYBFILEDIR", "MYBFILE.JPG"]);
+
+This example inserts a row in ``bfile_table`` with BFILE properties,
+directory alias ``MYBFILEDIR`` and file name ``MYBFILE.JPG``.
+
+Note that the content in the BFILE column cannot be updated. You can only
+update the properties such as directory alias and the file name. Once updated,
+the LOB object references the new file name specified. To update the file name
+to ``NEWBFILE.JPG``, you can use:
+
+.. code-block:: javascript
+
+    const result = await connection.execute(
+        `UPDATE bfile_table SET bfilecol = BFILENAME("MYBFILEDIR", "NEWBFILE.JPG") WHERE id = :ID`,
+        [101]);
+
+In node-oracledb Thin mode, you can set the directory alias and file name
+using :meth:`lob.setDirFileName()`. For example:
+
+.. code-block:: javascript
+
+    const result = await conn.execute(`
+        SELECT bfilecol FROM bfile_table WHERE id = :id`, [101]);
+    const lob = result.rows[0][0];
+    const dirFile = lob.getDirFileName();
+    lob.setDirFileName({dirName: "NEWALIASNAME", fileName: "NEWBFILENAME"});
+
+This will update the directory alias to ``NEWALIASNAME`` and file name to
+``NEWBFILENAME``.
+
+See :ref:`fetchbfile` for information on how to query a BFILE column.
+
 .. _queryinglobs:
 
 Simple LOB Queries and PL/SQL OUT Binds
 =======================================
 
-Querying LOBs
--------------
+.. _fetchinglob:
+
+Fetching CLOBs, BLOBs, and NCLOBs
+---------------------------------
 
 LOBs queried from the database that are shorter than 1 GB can be
 returned as Strings or Buffers by using
@@ -219,6 +326,48 @@ in Node.js or node-oracledb, it will need to be explicitly streamed to a
 Lobs <streamsandlobs>`. See :ref:`LOB Bind Parameters <lobbinds>` for
 size considerations regarding LOB binds.
 
+.. _fetchbfile:
+
+Fetching BFILEs
+---------------
+
+To query the BFILE column of ``bfile_table``, you can use:
+
+.. code-block:: javascript
+
+    const result = await connection.execute(
+         `SELECT bfilecol FROM bfile_table WHERE id = :id`, [101]);
+    const lob = result.rows[0][0];
+    const dirFile = lob.getDirFileName();
+    console.log("Directory Alias:", dirFile.dirName, "File Name:", dirFile.fileName);
+
+This prints the following output::
+
+    MYBFILEDIR, MYBFILE.JPG
+
+To query the metadata of a BFILE column, you can use:
+
+.. code-block:: javascript
+
+    const result = await connection.execute(`SELECT bfilecol FROM bfile_table`);
+    console.log("Metadata:", result.metaData);
+
+This query prints the metadata for the ``bfilecol`` column and displays the
+dbType as ``DB_TYPE_BFILE``::
+
+    MetaData: [
+        {
+            name: 'BFILECOL',
+            dbType: [DbType DB_TYPE_BFILE],
+            nullable: false,
+            isJson: false,
+            isOson: false,
+            dbTypeName: 'BFILE',
+            fetchType: [DbType DB_TYPE_BFILE],
+            converter: [Function: converter]
+        },
+    ]
+
 .. _streamsandlobs:
 
 Streaming Lobs