10 SODA Guidelines and Restrictions

General guidelines and restrictions that apply across SODA implementations are presented.

10.1 SODA Guidelines

Guidelines that apply across SODA implementations are described.

  • AL32UTF8 database character set — Oracle recommendsFoot 1 that you use AL32UTF8 (Unicode) for your database character set. Otherwise:

    • Data can be altered by SODA when documents are written to a collection, because of lossy conversion to the database character set. (This affects only collections stored as VARCHAR2 and CLOB data; collections stored as BLOB data do not depend on the database character set.

    • Query-by-example (QBE) can return unpredictable results.

  • Re-creating a collectionFoot 2 — Do not drop a collection and then re-create it with different metadata if there is any application running that uses the collection in any way. Shut down any such applications before re-creating the collection, so that all live SODA objects are released.

    There is no problem just dropping a collection. Any read or write operation on a dropped collection raises an error. And there is no problem dropping a collection and then re-creating it with the same metadata. But if you re-create a collection with different metadata, and if there are any live applications using SODA objects, then there is a risk that a stale collection is accessed, and no error is raised in this case.


    In SODA implementations that allow collection metadata caching, such as SODA for Java, this risk is increased if such caching is enabled. In that case, a cache can return an entry for a stale collection object even if the collection has been dropped.

See Also:

  • Key Column Type for information about the importance of using AL32UTF8 with client-assigned document keys

  • Oracle Database SODA for Java Developer's Guide for information about collection metadata caching

10.2 SODA Restrictions (Reference)

Restrictions that apply across SODA implementations are described.

  • Document size:

    • For SODA for REST and SODA for Java the limit is approximately 2 gigabytes.

    • For SODA for PL/SQL the size is limited by the maximum possible LOB size.

      See Also:

      Oracle Database SQL Language Reference for information about the maximum size for BLOB and CLOB


    You must ensure that you have sufficient RAM to support your workload.

  • JSON document content:

    In SODA, JSON content must conform to the JSON RFC 8259 standard, if database initialization parameter compatible is at least 20, or to the RFC 4627 standard, if compatible is less than 20. RFC 8259 support includes RFC 4627 support (and RFC 7159 support).

    In Oracle Database release 19c and prior, only RFC 4627 was supported. RFC 4627 allows only a JSON object or an array, not a scalar, at the top level of a JSON document. For example, according to RFC 8259, the string value "hello" is, by itself, valid JSON content; but according to RFC 4627, it is not.

    In addition, SODA JSON content can be UTF-8 or UTF-16 (big endian (BE) or little endian (LE)). Although RFC 4627 also allows UTF-32 (BE and LE) encodings, SODA does not support them. Some implementations may support additional, non-Unicode, encodings.

    See Also:

Footnote Legend

Footnote 1: SODA for C requires that you use AL32UTF8 as the database character set.
Footnote 2:

Day-to-day use of a typical application that makes use of SODA does not require that you drop and re-create collections. But if you need to do that for any reason then this guideline applies.