> For the complete documentation index, see [llms.txt](https://docs.scaleflex.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.scaleflex.com/portals/portal-settings/datasets.md).

# Datasets

Keep a structured set of records in a Portal, and render it in list sections.

A **dataset** is a small table you define inside a Portal: you decide the fields, then fill in the rows. It holds content and nothing else — no layout, no styling, no decision about where it appears.

Use one when the same structured information shows up in more than one place, or changes often enough that editing it inside a page would be tedious: a changelog, a job board, a partner directory, a schedule, a set of product records.

Find it under **Settings** → **Content** → **Datasets**.

<figure><img src="https://2536208400-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fqsq2dR7Fjagf5eTifWZx%2Fuploads%2FsCTdE8nBrBvhfULXX9EL%2Fimage.png?alt=media&#x26;token=3c453128-54d5-4f37-9f3f-ab05ad878888" alt=""><figcaption><p>The <strong>Datasets</strong> page, listing each dataset with its handle, field and item counts.</p></figcaption></figure>

## How a dataset reaches a visitor

Three steps, in two different parts of the product. Keeping them apart is what makes the feature make sense:

| Step                                              | Where                             | Covered in                                                                                              |
| ------------------------------------------------- | --------------------------------- | ------------------------------------------------------------------------------------------------------- |
| **1. Describe a record** — the fields             | **Settings → Content → Datasets** | [Fields](https://docs.scaleflex.com/portals/portal-settings/datasets/fields.md)                         |
| **2. Write the records** — the rows               | **Settings → Content → Datasets** | [Items](https://docs.scaleflex.com/portals/portal-settings/datasets/items.md)                           |
| **3. Show them** — point a section at the dataset | The builder, on a list section    | [Connect to dataset](https://docs.scaleflex.com/portals/portal-settings/datasets/connect-to-dataset.md) |

A section never copies the rows. It stores a question — *this dataset, these criteria, this order* — and asks it each time the page loads. Three consequences worth holding on to:

* **One dataset can feed several sections**, each asking something different of it.
* **Editing a row is live.** No republishing — see [Items](https://docs.scaleflex.com/portals/portal-settings/datasets/items.md).
* **Fields are the contract.** Sections bind to field *keys*, which is why keys are permanent and deleting a field is a careful operation.

## Creating a dataset

**Create dataset**, give it a **Name**, and it appears in the list with its **Handle**, how many **Fields** and **Items** it has, and when it was **Updated**. **Search dataset** narrows a long list; a dataset's own menu offers **Rename** and **Delete**.

<figure><img src="https://2536208400-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fqsq2dR7Fjagf5eTifWZx%2Fuploads%2FEb5LE6KvVBGdBGMmOdVv%2Fimage.png?alt=media&#x26;token=651e91d8-1ab5-47eb-8077-6e3fbb980449" alt="" width="375"><figcaption><p>The <strong>New dataset</strong> dialog — a name is all it needs; the handle is derived from it.</p></figcaption></figure>

A dataset belongs to the Portal it was created in. Another Portal doesn't see it — a list section can only connect to a dataset of its own Portal, and the connect dialog says **This portal has no datasets yet** until you make one.

## The two tabs

Opening a dataset gives you two tabs, and you work through them in order:

| Tab                                                                                 | Holds                                                             |
| ----------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
| [**Fields**](https://docs.scaleflex.com/portals/portal-settings/datasets/fields.md) | The shape of a record — what columns exist and what type each is. |
| [**Items**](https://docs.scaleflex.com/portals/portal-settings/datasets/items.md)   | The records themselves, one row each.                             |

Define the fields first; the Items tab has nothing to show until you do, and says so.

Each tab also has its own **Editor / JSON** switch, for editing that half as a document — the schema on one, the rows on the other. They're separate: applying one never touches the other.

## Next: show it to someone

A dataset does nothing on its own. [Connect to dataset](https://docs.scaleflex.com/portals/portal-settings/datasets/connect-to-dataset.md) covers pointing a section at it — the **Context** tab for which dataset and in what order, the **Criteria** tab for which rows and what visitors may filter, and binding each slot of the row to a field.
