> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dataerai.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Metadata, notes & organizing
> Describe assets with structured metadata and a Markdown note, give a project a README, and reorganize with copy / cut / paste and delete.
Use this tutorial to make data easier to understand later.
You'll work with three kinds of context:
* **Metadata** for structured facts such as instrument, temperature, or sample
id.
* **Notes** for free-form Markdown about one asset.
* **Readme** for a project-level overview.
You'll also practice:
* Editing metadata in the app.
* Adding and removing a note.
* Creating a project Readme.
* Moving items with copy, cut, paste, and delete.
Good to know:
* Notes are one per asset.
* Comments are separate from notes.
* A Readme belongs to a project, not an individual collection.
Metadata values must be a JSON object and a `PATCH` replaces the whole object,
so code examples use read-modify-write. Notes are last-write-wins with no
conflict detection. The README is stored as an ordinary asset named
`README.md`, so editing it means uploading replacement content.
## Metadata
Metadata is a per-asset JSON object (the asset's `metadata` field) for structured,
queryable facts: instrument, temperature, sample id, and so on. You can hand-edit
it, or — for supported instrument files (`.h5`, `.xrdml`, `.dm4`, `.ibw`) — let
**Dataerai** populate it automatically.
The Metadata tab shows
`current_content.extracted_metadata` (auto-extracted metadata) when it exists and *only
falls back* to the editable `metadata` field otherwise. When extracted metadata is
present the Tree/Editor views are **read-only** and the Merge/Replace modes are
hidden. Editing always writes the asset's own `metadata` field. That's why the
tutorial uses a `.csv` (extraction is skipped), so the editor stays writable.
### In the app
1. From **Home**, double-click your project, then a collection, to open the
**Data** list.
2. Click an asset row to open the right-hand record sidebar, then click the
**Metadata** tab.
3. The pill control offers **Tree** and **Editor**. In **Tree** mode, click a field
value to edit it, or use the **+** affordance to add a key; in **Editor** mode you
see the same object as formatted JSON.
4. A sticky **Cancel** / **Save** bar appears at the bottom once you have changes —
click **Save** to write them back.
*(For supported instrument files, a **Re-extract** affordance reruns extraction.
Tree/Editor are read-only while extracted metadata is shown.)*
### From code
Read the asset first, update a copy of its `metadata`, and save it back.
`PATCH` replaces the whole `metadata` object, so read-modify-write preserves
existing keys. `metadata` must be a JSON object or the API returns `400`.
```python theme={null}
# Read-modify-write so we don't clobber any existing keys.
asset = s.get(f"{API}/api/assets/{ASSET_ID}/").json()
print("current metadata :", asset["metadata"])
print("extracted metadata :", (asset.get("current_content") or {}).get("extracted_metadata"))
meta = dict(asset.get("metadata") or {})
meta.update({"instrument": "PLD", "temp_max_K": 370.5, "capacitor_id": "S3_c015"})
r = s.patch(f"{API}/api/assets/{ASSET_ID}/",
json={"metadata": meta, "tags": ["pld", "pyroelectric"]})
r.raise_for_status()
print("updated metadata :", r.json()["metadata"])
```
The SDK exposes the same write via `set_metadata` (and `get_metadata` to read):
```python theme={null}
current = client.get_metadata(ASSET_ID)
print("title:", current.title, "| tags:", current.tags)
client.set_metadata(ASSET_ID, tags=["pld", "pyroelectric"],
metadata={"instrument": "PLD", "temp_max_K": 370.5,
"capacitor_id": "S3_c015"})
```
## Notes
The **Notes** tab holds a single free-form Markdown note per asset — a canonical
place for descriptions, lab-notebook entries, and caveats. It is **one note per
asset** (not a thread): writing again replaces the body. Don't confuse it with the
**Comments** tab, which is the threaded, multi-author surface.
The note is capped at **1 MiB**. Its `author` records the *first* writer and is
preserved on later edits (last-write-wins, no conflict detection).
### In the app
1. With an asset selected, click the **Notes** tab in the record sidebar.
2. The empty state shows *"No note yet for this record. Capture context,
observations, or links here."* and an **Add note** button.
3. Click **Add note** to open the rich-text / Markdown editor (Bold, Italic,
Underline, Heading 1–3, bullet & numbered lists, a Link popover, inline code),
type your note, and click **Save**.
4. A saved note shows its title (the first heading/line), the author and *edited
\
### From code
Read the asset first, update a copy of its `metadata`, and save it back.