Metadata, notes & organizing

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.

Technical details

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.

Technical details: editable and extracted metadata

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

From Home, double-click your project, then a collection, to open the Data list.
Click an asset row to open the right-hand record sidebar, then click the Metadata tab.
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.
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.)

Editing a field in the Metadata Tree view, with the Save bar visible

The raw JSON in the Metadata Editor view

From code

Read the asset first, update a copy of its metadata, and save it back.

Technical details

PATCH replaces the whole metadata object, so read-modify-write preserves existing keys. metadata must be a JSON object or the API returns 400.

# 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):

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

With an asset selected, click the Notes tab in the record sidebar.
The empty state shows “No note yet for this record. Capture context, observations, or links here.” and an Add note button.
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.
A saved note shows its title (the first heading/line), the author and edited <time>, plus a pencil to edit and a trash icon to delete.

The note editor open with sample Markdown, before saving

A saved note in view mode with author and edit/delete controls

From code

The notes tab is a single Markdown body. There is no SDK method for the note, so we use the same authenticated session.

Technical details

The note lives at /api/assets/{id}/markdown-note/: GET reads it (404 when none exists yet), PUT creates or updates it (201 on first create, 200 on later edits), and DELETE removes it.

# Read the current note (404 means there isn't one yet).
r = s.get(f"{API}/api/assets/{ASSET_ID}/markdown-note/")
note = r.json() if r.status_code == 200 else None
print("existing note:", None if note is None else note["content"])

# Create or update the note (upsert).
body = {"content": "# Lab notes\n\n"
                   "Instrument: PLD. Column `temp_K` is in kelvin; "
                   "`current_A` is the pyroelectric current."}
r = s.put(f"{API}/api/assets/{ASSET_ID}/markdown-note/",
          json=body)
r.raise_for_status()
print("created" if r.status_code == 201 else "updated", "->", r.json()["author"]["name"])

To remove the note entirely:

r = s.delete(f"{API}/api/assets/{ASSET_ID}/markdown-note/")
print("deleted" if r.status_code == 204 else r.status_code)

Project README

A project README gives the whole project a front page. It is rendered as Markdown on the project’s Readme tab. README is project-only (there is no per-collection README).

Technical details

Under the hood, the README is an ordinary asset named README.md in the project’s root collection. There is no dedicated README endpoint; editing it means uploading new content.

In the app

Open a project from Home. The top tab bar shows Data | Readme.
Click Readme. The empty state shows a document icon, “Add a README”, and a purple Add Readme button.
Click Add Readme to open the full editor (headings, lists, tables, images, code blocks, links), write your overview, and save.
When a README exists the tab renders the Markdown with an Edit button to revise it.

The README editor with a sample project overview, before saving

A rendered README on the project Readme tab with the Edit button

From code

First find the project’s root collection, then look for an existing README.md asset in it (this is exactly how the UI discovers the README). To add or replace the README, upload a README.md file into that root collection. Re-running the upload updates the existing README by title.

import re

# The README lives in the project's root collection.
proj = s.get(f"{API}/api/projects/{PROJECT_ID}/").json()
ROOT = proj["root_collection_id"]

# Discover an existing README the same way the UI does.
hits = s.get(f"{API}/api/assets/",
             params={"collection_id": ROOT, "title_prefix": "readme", "limit": 20}).json()
readme = next((a for a in hits
               if re.fullmatch(r"readme(\.[a-z0-9]+)?", a["title"], re.I)), None)
print("existing README asset:", None if not readme else readme["id"])

Now write a README.md and upload it into the root collection. Re-running this upserts by title, so it doubles as the “edit” path.

README_FILE = pathlib.Path.home() / "dataerai-tutorial" / "README.md"
README_FILE.write_text(
    "# Describe & organize tutorial\n\n"
    "Container for the sample pyroelectric scan used in this tutorial.\n\n"
    "## Contents\n\n"
    "- `Pyroelectric scan` - a small synthetic temperature/current sweep.\n"
)

res = client.upload(str(README_FILE), title="README.md",
                    owner_type="project", owner_id=PROJECT_ID,
                    collection_id=ROOT)
print("README asset:", res.asset_id)

Reorganize

Select one or more items and use the floating toolbar — Copy, Cut, Paste to move things between collections, plus delete/unlink — without leaving the list. (The toolbar appears at the bottom whenever something is selected.)

Get started

Get data in

Organize & describe

Verifiable identity

Datasets & analysis

Discover

AI & LLM search

Sharing & access

Account & organization

Attribution

Help & reference

Metadata, notes & organizing

Metadata

In the app

From code

Notes

In the app

From code

Project README

In the app

From code

Reorganize

Next steps

​Metadata

​In the app

​From code

​Notes

​In the app

​From code

​Project README

​In the app

​From code

​Reorganize

​Next steps

Metadata

In the app

From code

Notes

In the app

From code

Project README

In the app

From code

Reorganize

Next steps