> For the complete documentation index, see [llms.txt](https://docs.nuvolos.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.nuvolos.com/reference/data-storage/nuvolos-tables.md).

# Nuvolos Tables

## Activating tables in a Space

Before you can work with tables, the Tables feature must be activated for your Space. Only space administrators can activate tables, and only if tables are enabled for your organisation.

1. Navigate to the Space.
2. Open the Tables view from the sidebar.
3. Click Activate Tables.

Activation may take a few minutes. If you have running Applications when you activate tables, restart them so that database credentials and connection information can be loaded.

### The Tables view

The Tables view is organised around three main areas: navigation, table management, and table exploration.

### Layout

* **Navigation** - across the top, switch between **Tables**, **Query Builder**, and **Queries**.
* **Table management** - in the top right corner, open the **Connection Guide**, **Import Data**, or **Deactivate Tables**.
* **Table exploration** - on the **Tables** tab, browse available tables and review their description, size, row count, and external/internal status. Select tables for further actions.
* **List controls** - stage all tables, filter results, refresh the list, and paginate.
* **Query tools** - start querying a table directly with the **Query** action, or open the **SQL Edito**r to write SQL manually.

### Tables list

The tables list shows all tables in the currently selected snapshot or in the current state. To stage, delete, rename, or add a description to a table, use the More actions menu (...) at the end of the table row.

### Column list and table preview

Click the table name and select one of:

* **Explore columns** - see the column list. You can add a description to each column to aid documentation.
* **Preview table** - look at the first ten rows.

## Documenting your data

Data documentation in Nuvolos serves anyone who will reuse your data - colleagues, students, journal reviewers, or your future self. Three documentation artefacts are commonly used together:

* **Descriptive documentation files** - a PDF or `README.md` in the file system describing the dataset's provenance, methodology, and use cases. Often accompanied by ERD diagrams or other representations.
* **Column comments** - short-form information attached to each column (unit of measurement, definition, encoding).
* **Table comments** - short-form information attached to each table (what the table contains, how it was derived).

### Adding descriptive documentation

Descriptive documentation lives as files in the same instance as the data:

* \`README.md\` at the root of the instance is rendered automatically on the space overview. Use it as the primary documentation file.
* PDF documentation can be uploaded alongside data files in the file system, and can be previewed inline in the Nuvolos web UI.
* ERDs and other diagrams can be embedded in Markdown documentation files as images.

See [Reference › File Storage](/reference/file-system-and-storage.md) for the file upload, Markdown editor, and embed-image procedures.

### Adding column comments

Column comments can be added two ways:

#### Via the Tables view

{% stepper %}
{% step %}
Open the Tables view.
{% endstep %}

{% step %}
Click the table name and select Explore columns.
{% endstep %}

{% step %}
In the column list, edit the Description field for each column.
{% endstep %}
{% endstepper %}

#### Via SQL

Programmatic option, useful when documenting many columns at once. The SQL syntax follows the data warehouse standard:

{% code overflow="wrap" %}

```sql
COMMENT ON COLUMN "table_name"."column_name" IS 'Column description text';
```

{% endcode %}

Quote identifiers exactly. For the connection-mode and database/schema reference, see *Database and schema paths* later in this section.

### Adding table comments

Table comments use the same two options as column comments.

#### Via the Tables view

Use the ... More actions menu on the table row and select **Edit description**.

#### Via SQL

{% code overflow="wrap" %}

```sql
COMMENT ON TABLE "table_name" IS 'Table description text';
```

{% endcode %}

#### A few documentation conventions

* **Always include units** in column descriptions for numeric data (USD, GB, percentage points). Without units, downstream users have to dig through the methodology to confirm what a number means.
* **Document the source of the data**, even if briefly. "Loaded from the 2024-Q3 release of Vendor X dataset" is more useful than no source attribution.
* **Treat dataset spaces as the final published artefact**. Iterative documentation work belongs in the research space where the pipeline lives, not in the dataset space itself.

For the conceptual model behind documented datasets and vintaging, see [Concepts › Data storage](/concepts/data-integration.md).

## Running queries

Query data directly from the web interface. At this time, only SELECT queries are supported via the UI. For the full query syntax, refer to the underlying database engine's SQL reference.

### Designing the query

* Use the **Query Builder** to query data without writing SQL. Recommended for single-table queries when you are not very familiar with SQL.
* Use the **SQL Editor** for more complex queries or for combining data from multiple tables. Click the toggle to open it, enter your query, and click Preview.

### Reviewing and exporting results

After previewing the results, you can:

* **Run from Application** - selecting the target Application provides instructions for running the query either on Nuvolos or on your local machine. For repeated access to the same data, prefer exporting and saving the results.
* **Save full results (Export)** - retrieves the complete result set, useful for queries run in Preview mode.

### Working with .gz exports

Compressed result files are stored with the `.gz` extension (`gzip`).

* On macOS and Linux, extract with `gzip -d example.gz`.
* Windows does not have a native gzip extraction tool. Most standard archive utilities ([WinRar](https://www.win-rar.com/start.html?\&L=0), [7zip](https://www.7-zip.org/), [WinZip](https://www.winzip.com/win/en/gz-file.html)) can unzip gzip files.

### Connection Guide

Click **Connection Guide** to view the access credentials for the database associated with your workspace. The guide provides the username, password (a separate string from your Nuvolos credentials), and a convenience command containing the connection details. See *Obtaining tokens for data access* below for full details.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.nuvolos.com/reference/data-storage/nuvolos-tables.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.