> For the complete documentation index, see [llms.txt](https://docs.unitlab.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.unitlab.ai/documentation/annotations/tabular-annotation.md).

# Tabular Annotation

Annotate CSV records, cell text, column names, properties, and relationships while preserving row and field identity.

Tabular annotation turns CSV rows into individual annotation tasks. Review each record with its original fields, label text inside cells, describe column names, and connect entities across fields in the same row.

{% hint style="info" %}
**Use this guide when:** you need reviewed labels for support records, catalogs, business records, or other structured text datasets. For measurements plotted over an X-axis, use [Sensor Annotation](https://docs.unitlab.ai/documentation/annotations/sensor-annotation).
{% endhint %}

## See tabular annotation in action

The demo shows a CSV record in the native annotation view, with field context retained around the labels.

{% embed url="<https://homepage-files.s3.us-east-2.amazonaws.com/hero-videos/hero/tabular-annotation-1-20260917.mp4>" %}

[Open the demo in a new tab](https://homepage-files.s3.us-east-2.amazonaws.com/hero-videos/hero/tabular-annotation-1-20260917.mp4).

## Before you begin

1. Prepare a CSV whose rows are the intended units of annotation, with meaningful column names.
2. Select the row interpretation when configuring the CSV. Inspect the column mapping and sample records before proceeding.
3. Configure entity classes, column or header labeling classes, record Item Properties, and allowed relations.
4. Define rules for empty cells, repeated values, sensitive fields, ambiguous labels, and required record coverage.
5. Open an assigned record from the project data view or Task Queue.

See [Annotation Workbench](https://docs.unitlab.ai/documentation/annotations/annotation-workbench) for the shared shell, history, comments, and submission controls.

## Understand the record work surface

Each row is a separate work item with its own annotation history and workflow state. The native record view displays field names and values together. Record-level Item Properties are available through the shared inspector.

![CSV support record with customer, product, and issue fields beside a shared record-properties inspector.](https://content.gitbook.com/content/GjVLUz4wthGkGlRKM6rM/blobs/LWuZHOh6V1nihEqHOd3K/6aa5de1b8ed73124d1f903b7_unitlab%20tabular%2001%20record%20v1.webp)

*One support record provides the field context for entity labels and record-level properties.*

The primary column controls presentation order; it does not restrict annotation to that field. Text in other columns remains available for labeling. The annotation work surface records labels on the source, rather than editing CSV cells as a spreadsheet.

## Supported annotation model

| Annotation           | What it describes                                           | Example                                         |
| -------------------- | ----------------------------------------------------------- | ----------------------------------------------- |
| **Cell text entity** | A character span within one cell, with its column identity. | A product mentioned in a support message.       |
| **Column label**     | The role of a column within the current record.             | Customer name or product identifier.            |
| **Header text span** | Selected text within a column name.                         | A meaningful portion of a compound field name.  |
| **Class properties** | Structured details attached to a label.                     | Entity category or a task-specific attribute.   |
| **Item Properties**  | Classification or attributes of the complete row.           | Intent, priority, or resolution category.       |
| **Relation**         | A connection between labels within the same row.            | Product **has\_issue** Issue across two fields. |

Column and header labels belong to the current row's annotation history. Labeling a column name in one record does not automatically propagate that label to every row.

## Label cell text and column names

Select the required text inside the relevant cell and apply its class. Each cell has its own character offsets, so identical text or offset values in two columns remain separate annotations. Check that the selected field is the one intended by the instructions.

![Named entities highlighted within the text of a CSV record cell.](https://content.gitbook.com/content/GjVLUz4wthGkGlRKM6rM/blobs/xtytYF5VLlo9Uh6JyKcj/6aa5de1cc5e39a717570586a_unitlab%20tabular%2002%20cell%20v1.webp)

*Entity spans preserve their exact text and the field where they occur.*

For field-role annotation, label the column name or the relevant header text. Keep the distinction between describing the field and labeling a value inside that field.

![Column and header labels shown alongside the original values in a CSV record.](https://content.gitbook.com/content/GjVLUz4wthGkGlRKM6rM/blobs/7UwU040uIC6WBnSWHagW/6aa5de1c349216d9c9d1b80a_unitlab%20tabular%2003%20header%20v2.webp)

*Header and column labels describe field meaning alongside the current record values.*

## Relate labels across fields

Use the ontology's allowed relations to connect entities, column labels, or header spans within the record. Verify both endpoints and relation direction. A product in one field can be connected to an issue in another without losing the original column context.

![A product entity linked to an issue entity with a has\_issue relationship across fields in one record.](https://content.gitbook.com/content/GjVLUz4wthGkGlRKM6rM/blobs/HHwlkQSI1AX0Rey6qfDA/6aa5de1c8ed73124d1f904af_unitlab%20tabular%2005%20relations%20v2.webp)

*The relation connects a product to its issue across fields in the same record.*

Relations in this work surface do not join arbitrary rows or external database records. Include the necessary evidence in the same work item when the task depends on a relationship.

## Annotate one production record

1. **Read the complete row.** Inspect all relevant fields before deciding the record's meaning.
2. **Set record properties.** Apply required classifications such as intent or priority in the shared inspector.
3. **Label cell entities.** Mark precise spans in each field required by the instructions.
4. **Label field roles where required.** Apply column or header labels to the current record.
5. **Connect and check.** Add relations, complete label properties, and verify that repeated values point to the correct fields.
6. **Save and submit.** Resolve findings and use the available stage action to send the record forward.

## Quality review

| Review focus            | What to check                                                           |
| ----------------------- | ----------------------------------------------------------------------- |
| Record identity         | The labels belong to the intended source row.                           |
| Field identity          | Each entity and relation endpoint refers to the correct column.         |
| Text boundaries         | Spans contain the full entity without unrelated words or punctuation.   |
| Completeness            | All required fields and record properties follow the instructions.      |
| Empty or ambiguous data | Missing values use the agreed policy rather than invented labels.       |
| Relationships           | Endpoints are meaningful within the row and have the correct direction. |

![Tabular annotation review with record labels, comments, and quality decisions.](https://content.gitbook.com/content/GjVLUz4wthGkGlRKM6rM/blobs/b6cv9mhUmIo9QzmBKYm2/6aa5de1d0e862ea60fa1645e_unitlab%20tabular%2006%20review%20v1.webp)

*Review labels, record context, and feedback together before approving the work.*

Use [Consensus](https://docs.unitlab.ai/documentation/qa/consensus) for independent record annotations, [Quality Gate](https://docs.unitlab.ai/documentation/qa/quality-gate) for approved-reference comparisons, and [Review Stages](https://docs.unitlab.ai/documentation/qa/review-stages) for corrections and final human decisions.

## Curate and export records

Organize CSV assets using folders, tags, filenames, and available metadata. Inspect sample records before choosing a source cohort. A reusable CSV source can support different configured interpretations, so confirm that the project uses rows for this task.

Dataset versions preserve selected source membership. Project annotation releases freeze the reviewed labels. JSONL exports contain one line per record with row values, column schema, entities, relations, and supported record properties. Validate representative rows, empty values, character spans, and field identities with the downstream consumer.

## Troubleshooting

| Situation                                 | Recommended action                                                                   |
| ----------------------------------------- | ------------------------------------------------------------------------------------ |
| CSV opens as a chart                      | Check its configured interpretation and select rows for record annotation.           |
| A label appears in the wrong cell         | Inspect its column context, not just the displayed text.                             |
| A header label is absent from another row | Label that record as required; header annotation does not propagate across rows.     |
| A relationship needs another row          | Revisit the task design; within-record relations require endpoints in the same item. |

## Next steps

* Define record semantics in [Properties, relations, and Item Properties](https://docs.unitlab.ai/documentation/ontologies/properties-relations-and-item-properties).
* Add review routes with [QA Workflows](https://docs.unitlab.ai/documentation/qa/qa-workflows).
* Prepare a reproducible handoff with [Create a release](https://docs.unitlab.ai/documentation/releases/create-a-release).

Explore the [Unitlab Tabular Annotation overview](https://unitlab.ai/en/tabular-annotation).