# 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](https://docs.buzzy.buzz/rest-api/buzzy-rest-api/rest-api/microapp-data-operations/microappdata) for reading row collections
* [microappdata/row](https://docs.buzzy.buzz/rest-api/buzzy-rest-api/rest-api/microapp-data-operations/microappdata-row) for reading one row
* [insertmicroapprow](https://docs.buzzy.buzz/rest-api/buzzy-rest-api/rest-api/microapp-data-operations/insertmicroapprow) for creating rows
* [updatemicroapprow](https://docs.buzzy.buzz/rest-api/buzzy-rest-api/rest-api/microapp-data-operations/updatemicroapprow) for updating rows
* [Common API Examples](https://docs.buzzy.buzz/rest-api/buzzy-rest-api/rest-api/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:

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

Get these values by calling [login](https://docs.buzzy.buzz/rest-api/buzzy-rest-api/rest-api/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:

```json
{
  "_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:

```json
{
  "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](https://docs.buzzy.buzz/rest-api/buzzy-rest-api/rest-api/microappdata-row#linkedtable-crossapp-row-field-example), [insertmicroapprow](https://docs.buzzy.buzz/rest-api/buzzy-rest-api/rest-api/insertmicroapprow#linked-table-field-example), and [updatemicroapprow](https://docs.buzzy.buzz/rest-api/buzzy-rest-api/rest-api/updatemicroapprow#linked-table-field-update-example).

## Common Payload Shapes

### Read many rows

```json
{
  "microAppID": "datatable-id"
}
```

### Read one row

```json
{
  "rowID": "row-id"
}
```

### Insert a row

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

### Insert a child row under a parent

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

### Update a row

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

### Delete a row

```json
{
  "rowID": "row-id"
}
```

## Canonical Read Patterns

* Use [microappdata](https://docs.buzzy.buzz/rest-api/buzzy-rest-api/rest-api/microapp-data-operations/microappdata) to list rows, paginate, filter, sort, and query child rows
* Use [microappdata/row](https://docs.buzzy.buzz/rest-api/buzzy-rest-api/rest-api/microapp-data-operations/microappdata-row) when you already know a specific `rowID`
* Use `optViewFilters` with `embeddingRowID` to fetch child rows for one parent

Example child-row query:

```json
{
  "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](https://docs.buzzy.buzz/rest-api/buzzy-rest-api/rest-api/microapp-data-operations/microappdata)
* [microappdata/row](https://docs.buzzy.buzz/rest-api/buzzy-rest-api/rest-api/microapp-data-operations/microappdata-row)
* [insertmicroapprow](https://docs.buzzy.buzz/rest-api/buzzy-rest-api/rest-api/microapp-data-operations/insertmicroapprow)
* [updatemicroapprow](https://docs.buzzy.buzz/rest-api/buzzy-rest-api/rest-api/microapp-data-operations/updatemicroapprow)
* [Common API Examples](https://docs.buzzy.buzz/rest-api/buzzy-rest-api/rest-api/common-api-examples)