Documents

SODA is designed primarily for working with JSON documents. Here’s a simple example:

{
  "_id"     : ...,
  "name"    : "Alexander",
  "address" : "1234 Main Street",
  "city"    : "Anytown",
  "state"   : "CA",
  "zip"     : "12345"
}

Every SODA document has four components:

Component	Description
Content	The document data itself (typically JSON).
Key	A unique identifier, stored inside the content under the _id field. You can supply your own _id value or let the database generate one. It can be a scalar (e.g. string or number) or an object.
Version (eTag)	A GUID value stored separately from the content and updated automatically when the content is changed. Enables optimistic locking: update, replace, and remove operations can include a version match condition - if the document version matches, the operation proceeds; if not, the operation fails and the application can retry.
Media type	Identifies the document format. For JSON documents, this is always application/json.

Note: An encoded form of _id, useful for identifying a document by key in REST URLs, is also stored separately from the content and automatically maintained.

How Documents Are Represented

In non-REST SODA implementations, documents are represented as language-specific objects with accessors for content, key, version, and so on.

In SODA REST, these components are serialized in request/response bodies.

At the database level, documents are rows in tables:

Component	Location
Content	DATA column (type JSON)
Key (_id)	Inside content, plus a encoded value in a hidden RESID column
Version	Hidden ETAG column (auto-maintained)

Documents and Pre-26ai Collections

Documents in pre-26ai collections differ in a few ways:

• The key is stored outside the document content only - not inside under _id.
• Documents include additional components that have been simplified away in 26ai JSON collection tables and views.
• Pre-26ai collections also support non-JSON documents.

For details, see Pre-26ai Collections.