Datasets

The Datasets page (route /datasets, under the DATA section of the sidebar) lists all the datasets in your workspace. A dataset is a container for documents and all subsequent operations. See Datasets for the underlying concept.

​

Dataset list

The page uses a Finder-style two-column layout:

• The left column lists your datasets. Each dataset shows a status dot, its document count, and Share and Delete actions.
• The right column lists the documents in the currently selected dataset.

Select a dataset in the left column to load its documents on the right.

​

Status dots

The status dot reflects the dataset’s processing state: A dataset whose graph is outdated (its config changed after files were processed) also shows an amber dot. A build that ran out of workspace credits part-way through is reported separately from a generic failure: the dot is lavender and labelled Failed — insufficient credits, with the hint “Your workspace ran out of credits mid-run — top up on the billing page”. The same distinction appears on the dataset detail status pill, where the label links straight to Billing. The Mindmap carries no status chip of its own — it draws whatever graph exists and says nothing about how the last build ended.

​

Create a dataset

Click New dataset to open the Create dataset modal, enter a name, and click Create dataset. The field uses the placeholder e.g. product-docs, sec-filings… and explains itself under the input: Spaces become hyphens as you type — periods aren’t allowed. Saved as lowercase. Spaces are not rejected, they are converted: each one is replaced with a hyphen as you type. Periods are the only character blocked outright — type one and the input turns red with Dataset name cannot contain periods., and Create dataset stays disabled until you remove it. The name is lowercased on create. In a cloud (multi-tenant) workspace, newly created datasets are automatically granted tenant-level read and write permissions, so every member of the current tenant can see and write to them. To restrict a dataset to specific users, revoke the tenant grant and assign per-user permissions through the permissions API. The grant is best-effort: if it fails, the dataset is still created — it is just not shared with the workspace yet. In local self-hosted mode that grant is skipped entirely. There the active tenant is the local sentinel rather than a real tenant UUID, and there are no other members to share with, so the UI makes no tenant-permission call at all. The dataset is created normally and you keep full owner access to it.

​

Manage documents

The documents column header includes two actions:

• Add files — Browse and upload files. Supported formats: PDF, CSV, TXT, Markdown, JSON, DOCX.
• Paste text — Open a textarea modal and paste raw text. The text is saved as pasted-text-{timestamp}.txt.

You can also drag files anywhere onto the documents column — a Drop to upload overlay appears while dragging. You can upload at most 100 files in a single batch. Selecting more shows You selected files. Please upload 100 or fewer at a time. and the upload is not started. If the estimated cost of the selected files reaches your workspace credit balance, a This upload might use more credits than you have dialog appears before the upload is sent, offering Cancel and Top up first — the upload does not proceed until the balance covers it. See When credits run out for how the estimate is framed. Each document row shows a file-type badge (PDF, DOC, MD, TXT, CSV, JSON), the file size, the upload date, and a Delete button (confirm dialog Delete document). Uploaded files appear in the document list automatically — no manual page refresh is needed. Because the background ingestion step can save document records a few moments after the upload call returns, the page keeps polling for the new documents and updates the list as soon as they are available. After upload, the add and cognify pipeline runs in the background. Once the files are saved, the upload is treated as successful — a later failure in status polling or the background graph build is reported separately and no longer surfaces as a false Upload failed error.

​

Refresh and polling

Click Refresh to re-poll dataset statuses on demand. The page also polls automatically every 5 seconds while any dataset is in a pending or running state, updating the status dots as processing completes.

​

Dataset detail

The dataset detail page (route /datasets/[id]) shows a single dataset. The header displays the dataset name (with a Default badge for default_dataset), the document count, and a status pill: Header actions:

• Sync — Re-runs cognify. Appears only for connected (integration) sources.
• Delete — Removes the dataset. Hidden for default_dataset.
• Share — Manage access.
• Upload files — Add documents.

When a knowledge-graph build fails, the dataset shows Building the knowledge graph failed. Your files are still here — you can retry the build. with a Retry build action, so a failed build never loses your uploaded documents. The same retry is offered from the failed-dataset banner on the Dataset list. When the build failed specifically because the workspace ran out of credits, the banner instead reads Building the knowledge graph failed — your workspace ran out of credits mid-run. Your files are still here. and offers Go to billing rather than a retry, because retrying on an empty balance fails the same way.

​

Extraction settings

How Cognee extracts knowledge from a dataset is configured on its detail page, under the Memory customization heading: a Graph Model, a Prompt, and an Ontology, each a dropdown defaulting to Automatic and each carrying an info tooltip explaining what it controls. The settings are per dataset. For the API equivalents, see Configuration & Ontologies.

​

Graph model

The Graph Model dropdown chooses which entity types and relationships Cognee extracts:

• Automatic (marked Default) — Cognee infers the structure from your data.
• A saved model — one you created and named. Each row carries a pencil that opens it in the editor.

Create new opens the Create Graph Model modal with two starting points:

• Infer from data — Cognee analyses the dataset’s files and proposes entity types and relationships. The option reads Analyze files to suggest a schema, and is disabled with No files in this dataset yet on an empty dataset.
• Start blank — define the entity types and relationships yourself.

Either way the model is created as Schema and opens straight into the editor.

​

Graph Model editor

The Graph Model editor is the visual node editor for a model. It has no sidebar entry and opens full-screen at /graph-models/[id], reachable only from the Graph Model dropdown above. Visiting /graph-models directly bounces you back to Datasets. The canvas draws each entity type as a node. Add entity type sits at the top left, and a hint bar reads Click a type to edit · Drag to reposition. Selecting a node opens a right sidebar carrying that type’s Name, Description, and Fields (). A field is one of: A relation added here is always many-valued — the editor has no cardinality control. Single-valued relations come only from an inferred schema. The canvas labels each relation edge with the field name and its cardinality. The header carries the model name (double-click to rename), a types, relationships count, an amber Unsaved flag while edits are pending, and Delete, Regenerate, and Save. Regenerate opens the Regenerate Schema modal — Select a dataset and files to analyze. Cognee will infer entity types and relationships from the selected files. Pick a dataset, choose which of its files to use (all are selected for you), and confirm with Regenerate from files. A Schema regenerated notification reports Detected entity types from files.

​

Prompt

The Prompt dropdown chooses the extraction prompt: Automatic (marked Default), or a named prompt of your own. Create new opens Create Custom Prompt with two starting points:

• Generate from graph model — seeds the prompt from the currently selected graph model. It stays disabled until one is selected, reading Select a graph model first.
• Start blank — write your own extraction prompt.

The pencil on a saved prompt opens the Edit Prompt modal, which holds its Name and Prompt text, a bin to delete it, and Save prompt.

​

Ontology

The Ontology dropdown attaches an optional OWL ontology to guide extraction: Automatic for none, or one you have uploaded — those are listed by filename, each with a bin to delete it. Upload new opens Upload Ontology — Upload an OWL ontology file to guide how Cognee structures your knowledge graph. It takes a Key (required, placeholder e.g. biomedical-ontology), an OWL File (required, .owl only), and an optional Description.

​

Sync a dataset

For datasets connected to an external (integration) source, the dataset detail header includes a Sync button that re-runs the cognify pipeline against the current contents. Use this to rebuild the knowledge graph after source data changes without uploading new files again. Datasets without a connected source do not show this button.

​

Share a dataset

Use the Share action (on a dataset in the left column or in the dataset detail header) to open the Share dataset modal. From here you can:

• Share with your whole workspace — Grant access to Everyone in workspace, which covers all current and future members. Choose Can edit (read and write — members can query the dataset and run cognify on it) or Can view (read-only). This grants the permission to the workspace (tenant) principal, so newly added members are included automatically without any per-member step.
• Share with individual agents and users — Grant read-only access to a specific agent or user from the list.

Sharing is applied immediately for the current session. The modal does not yet list shares granted previously; to manage grants in detail, use the permissions API.

​

Dataset selector

The dataset selector is an in-page control, not part of the breadcrumb — the top bar carries only the workspace switcher and the page name. On Search it sits above the input and scopes the query to exactly one dataset — there is no All datasets option there, and if you have not picked one, the first dataset in the list is used. Pages that scope to one dataset but keep their own switcher rather than the breadcrumb one:

• Mindmap — a dataset switcher above the canvas; it visualizes one dataset’s graph at a time.
• Memory Coverage — a dataset switcher under the score, since a coverage run is always scoped to a single dataset.
• Activity — a dataset filter behind + More filters rather than a selector, so you can compare several at once. Analytics has no dataset control at all; it always covers the whole workspace and splits it in the By dataset breakdown.

​

Empty state

When you have no datasets yet, the page shows No datasets yet with a Create dataset call to action. If the dataset list fails to load (for example, while a large upload is still processing and the server is briefly unreachable), the page shows a distinct error state — Couldn’t load your datasets with Your datasets are safe — we just couldn’t reach the server and a Retry button — rather than the empty No datasets yet state. A failed fetch is never mistaken for a genuinely empty account.

​

Delete a dataset

Use the Delete action on a dataset (in the left column or the dataset detail header). The confirm dialog warns that this will permanently remove the dataset and all its files. This action cannot be undone. The default_dataset dataset cannot be deleted: it has no Delete button and shows a Default badge on its detail page.