---
updatedAt: 2026-10-15T13:55:01.000Z
agentTools:
  projectIndex: https://docs.pebblestream.com/llms.txt
---

# row-oriented-headers

A **sheet-level hint** telling the extractor that the template worksheet's tables are laid out with their **headers on rows** — i.e. the tables are _stacked vertically_, one below another, and each record is a row.

`pebblestream:row-oriented-headers`

Without either orientation hint the extractor tries both orientations and keeps
whichever matches more of the worksheet's expected headers. Use this directive
when the template's layout is ambiguous (for example when the header words also
appear as data values) and the automatic choice would be wrong.

## Syntax

```
pebblestream:row-oriented-headers
```

* No arguments.
* Placed on any cell of the worksheet.
* Requires [`template-name`](template-name.md) on the same worksheet.
* **Mutually exclusive** with [`column-oriented-headers`](column-oriented-headers.md).

## Example

A template with two stacked tables:

```text
        A          B        C
1   Domestic
2   Item         Qty      Price
3   Widget       10       2.50
4   Gadget       3        7.00
5
6   International
7   Item         Qty      Price
8   Sprocket     5        4.10
```

The pebble's input sheet declares:

```
pebblestream:template-name:Template
pebblestream:row-oriented-headers
```

so the extractor reads records downward from each header row instead of treating
the columns as records.

## Errors

| Error                                 | Cause                                                   |
| ------------------------------------- | ------------------------------------------------------- |
| `dir-too-many-args`                   | Arguments were supplied.                                |
| `incompatible-template-directives`    | `column-oriented-headers` is also present on the sheet. |
| `missing-the-template-name-directive` | The sheet has no `template-name`.                       |

## Related

* [Template directives](template-directives.md) — the extraction algorithm
* [column-oriented-headers](column-oriented-headers.md) — the opposite orientation
* [block-id](block-id.md) — identify which stacked table a row came from