8 SODA Guidelines and Restrictions

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

8.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.

    Note:

    In SODA implementations that allow collection metadata caching, such as SODA for Java and SODA for REST, this risk is increased if such caching is enabled. In that case, a (shared or local) 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

8.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

    Note:

    You must ensure that you have sufficient RAM to support your workload. For example, about 6.4 GB of RAM are needed if you simultaneously read or write 100 documents of size 64 MB.

  • JSON document content: In SODA, JSON content must conform to RFC 4627.

    In particular, JSON content must be either an object or an array; it cannot be a scalar value. For example, according to RFC 4627, the string value "hello" is not, by itself, valid JSON content.

    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.



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.