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

See Also

• microappdata

• microappdata/row

• insertmicroapprow

• updatemicroapprow

• Common API Examples