20. API: AsyncLOB Objects
20.1. AsyncLOB Class
- class oracledb.AsyncLOB
An AsyncLOB object can be created with
This object is an extension to the DB API definition.AsyncConnection.createlob(). Also, this object is returned whenever OracleCLOB,BLOBandBFILEcolumns are fetched.See Using CLOB, BLOB, NCLOB, and BFILE Data for more information about using LOBs.
Note
AsyncLOB objects are only supported in python-oracledb Thin mode.
20.2. AsyncLOB Methods
- async AsyncLOB.close() None
Closes the LOB. Call this when writing is completed so that the indexes associated with the LOB can be updated -– but only if open() was called first.
- async AsyncLOB.fileexists() bool
Returns a boolean indicating if the file referenced by a BFILE type LOB exists.
- async AsyncLOB.getchunksize() int
Returns the chunk size for the LOB. Reading and writing to the LOB in chunks of multiples of this size will improve performance.
- AsyncLOB.getfilename() tuple
Returns a two-tuple consisting of the directory alias and file name for a BFILE type LOB.
- async AsyncLOB.isopen() bool
Returns a boolean indicating if the LOB has been opened using the method open().
- async AsyncLOB.open() None
Opens the LOB for writing. This will improve performance when writing to the LOB in chunks and there are functional or extensible indexes associated with the LOB. If this method is not called, each write will perform an open internally followed by a close after the write has been completed.
- async AsyncLOB.read(offset: int = 1, amount: int | None = None) str | bytes
Returns a portion (or all) of the data in the LOB. Note that the amount and offset are in bytes for BLOB and BFILE type LOBs and in UCS-2 code points for CLOB and NCLOB type LOBs. UCS-2 code points are equivalent to characters for all but supplemental characters. If supplemental characters are in the LOB, the offset and amount will have to be chosen carefully to avoid splitting a character.
- AsyncLOB.setfilename(dir_alias: str, name: str) None
Sets the directory alias and name of a BFILE type LOB.
- async AsyncLOB.size() int
Returns the size of the data in the LOB. For BLOB and BFILE type LOBs this is the number of bytes. For CLOB and NCLOB type LOBs this is the number of UCS-2 code points. UCS-2 code points are equivalent to characters for all but supplemental characters.
- async AsyncLOB.trim(new_size: int = 0, *, newSize: int | None = None) None
Trims the LOB to the new size (the second parameter is deprecated and should not be used).
- async AsyncLOB.write(data: str | bytes, offset: int = 1) None
Writes the data to the LOB at the given offset. The offset is in bytes for BLOB type LOBs and in UCS-2 code points for CLOB and NCLOB type LOBs. UCS-2 code points are equivalent to characters for all but supplemental characters. If supplemental characters are in the LOB, the offset will have to be chosen carefully to avoid splitting a character. Note that if you want to make the LOB value smaller, you must use the trim() function.