Row Metadata and Relationships

This page is the canonical reference for how Buzzy represents row metadata, parent-child relationships, and linked-table values in the REST API.

Use this page together with:

microappdata for reading row collections
microappdata/row for reading one row
insertmicroapprow for creating rows
updatemicroapprow for updating rows
Common API Examples for end-to-end examples across REST, Async API, and Node.js

Authentication

All authenticated row operations use the same request headers:

X-Auth-Token: <authToken from /api/login>
X-User-Id: <userId from /api/login>
Content-Type: application/json

Get these values by calling login.

Row Data vs Metadata

When Buzzy returns a row, the response usually contains two kinds of fields:

user-defined row data such as name, status, email, or price
system-managed metadata such as _id, userID, submitted, and embeddingRowID

In practice, both appear in the same JSON object. Treat the user-defined fields as your business data and the metadata fields as platform-managed context.

Canonical Metadata Fields

The following system fields may appear on a row or be available in Buzzy row semantics:

Field

Meaning

_id

Unique ID of the current row

_currentUrl

Current browser URL in insert/capture contexts

_contextRow

Parent or surrounding context row when one exists

userID

User ID of the row creator

_currentUserID

Currently logged-in user ID

viewers

Additional user IDs allowed to view the row

isLocked

Whether the row is locked

submitted

Server-side created timestamp, typically as Epoch milliseconds

clientSubmitted

Client-side submitted timestamp

deviceID

Device identifier captured for debugging

appVersion

App version captured when the row was created

hasConflict

Conflict information for sync/debug workflows

clientCounter

Client-side sync/debug counter

embeddingRowID

ID of the parent row for sub-table / embedded relationships

Parent-Child Relationships with `embeddingRowID`

embeddingRowID is the canonical way Buzzy represents a parent-child relationship for sub-tables.

Typical pattern:

Parent table: Invoices
Child table: Invoice Lines
Each invoice line row stores the parent invoice row ID in embeddingRowID

Example child row:

{
  "_id": "invoice-line-row-id",
  "product": "Widget",
  "quantity": 2,
  "price": 19.95,
  "embeddingRowID": "invoice-row-id"
}

Use embeddingRowID when:

creating child rows under a parent
fetching only the child rows for one parent
reasoning about sub-table data returned by API calls

Linked-Table (Cross-App) Values

Linked-table fields are different from embeddingRowID.

embeddingRowID represents a parent-child sub-table relationship
linked-table fields represent an explicit reference to a row in another datatable

Linked-table fields are stored as structured objects such as:

{
  "assignedUser": {
    "crossAppRowID": "user-row-id",
    "value": {
      "label": "name",
      "value": "Jane Doe"
    }
  }
}

Key fields:

crossAppRowID: ID of the linked row in the other datatable
value.label: field label used for display
value.value: displayed value
additionalValues: optional extra linked values returned by Buzzy

See microappdata/row, insertmicroapprow, and updatemicroapprow.

Common Payload Shapes

Read many rows

{
  "microAppID": "datatable-id"
}

Read one row

{
  "rowID": "row-id"
}

Insert a row

{
  "microAppID": "datatable-id",
  "rowData": {
    "name": "Example"
  }
}

Insert a child row under a parent

{
  "microAppID": "child-datatable-id",
  "embeddingRowID": "parent-row-id",
  "rowData": {
    "name": "Child row"
  }
}

Update a row

{
  "rowID": "row-id",
  "rowData": {
    "status": "Approved"
  }
}

Delete a row

{
  "rowID": "row-id"
}

Canonical Read Patterns

Use microappdata to list rows, paginate, filter, sort, and query child rows
Use microappdata/row when you already know a specific rowID
Use optViewFilters with embeddingRowID to fetch child rows for one parent

Example child-row query:

{
  "microAppID": "invoice-lines-table-id",
  "optViewFilters": [
    {
      "embeddingRowID": "invoice-row-id"
    }
  ]
}

Notes

Buzzy docs still contain historical Microapp naming in endpoint names such as microappdata and insertmicroapprow
In product UI and newer docs, prefer Datatable when describing the concept
submitted and clientSubmitted may differ because one is server-generated and the other is client-generated