SODA: document model + insert + read by key (#200)

[lemenkov]

Second step of the #163 SODA umbrella, on top of the collection foundation (#199). Adds the document layer over DBMS_SODA.

API (sync + async)

• SodaDatabase.createDocument(content, key=None, mediaType="application/json") → a client-side SodaDocument (content may be a dict → JSON, str, or bytes).
• SodaCollection.insertOne(doc) / insertOneAndGet(doc) → a SodaDocument with the server key / version / mediaType / createdOn / lastModified (no content, matching oracledb). Both accept a SodaDocument or a bare value.
• SodaCollection.find().key(k).getOne() → read a document by key (None if absent). SodaOperation is the read-builder that QBE / multi-doc reads extend in SODA: query-by-example (QBE) find #201.
• SodaDocument: getContent() (JSON → Python value) / getContentAsString() / getContentAsBytes(), plus the metadata fields.

Content size

Content binds as bytes, so inserting a document over the 32767-byte PL/SQL limit rides the transparent temp-LOB bind (#91). Reading content comes through one DBMS_LOB.SUBSTR and is capped at 32767 bytes — a larger stored document raises NotSupportedError rather than silently truncating (chunked large reads are a follow-up).

RE notes

• get_created_on / get_last_modified return VARCHAR2 ISO strings, not timestamps (a to_char(…, datefmt) over them is ORA-06502 on 21c).
• The default collection shape differs by server — 23ai native-JSON + embedded-OID RAW key (no tracked timestamps); 21c BLOB/JSON + UUID key + tracked timestamps. Both are covered by tests.
• Depends on the NULL-OUT-bind fix (Fix decode crash on a NULL scalar OUT bind from a PL/SQL block (#205) #206, merged) — documents carry NULL fields.

Tests: offline document/content helpers; live insert + read-by-key + large-doc guard, sync + async — 23ai/21c pass, 11g/9i skip. Offline suite 526.

Closes #200

🤖 Generated with Claude Code