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

## 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](/rest-api/buzzy-rest-api/rest-api/microapp-data-operations/microappdata-row.md#linkedtable-crossapp-row-field-example), [insertmicroapprow](/rest-api/buzzy-rest-api/rest-api/microapp-data-operations/insertmicroapprow.md#linked-table-field-example), and [updatemicroapprow](/rest-api/buzzy-rest-api/rest-api/microapp-data-operations/updatemicroapprow.md#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](/rest-api/buzzy-rest-api/rest-api/microapp-data-operations/microappdata.md) to list rows, paginate, filter, sort, and query child rows
* Use [microappdata/row](/rest-api/buzzy-rest-api/rest-api/microapp-data-operations/microappdata-row.md) 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](/rest-api/buzzy-rest-api/rest-api/microapp-data-operations/microappdata.md)
* [microappdata/row](/rest-api/buzzy-rest-api/rest-api/microapp-data-operations/microappdata-row.md)
* [insertmicroapprow](/rest-api/buzzy-rest-api/rest-api/microapp-data-operations/insertmicroapprow.md)
* [updatemicroapprow](/rest-api/buzzy-rest-api/rest-api/microapp-data-operations/updatemicroapprow.md)
* [Common API Examples](/rest-api/buzzy-rest-api/rest-api/common-api-examples.md)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.buzzy.buzz/rest-api/buzzy-rest-api/rest-api/microapp-data-operations/row-metadata-and-relationships.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.