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 Editor 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 for the file upload, Markdown editor, and embed-image procedures.

Adding column comments

Column comments can be added two ways:

Via the Tables view

1

Open the Tables view.

2

Click the table name and select Explore columns.

3

In the column list, edit the Description field for each column.

Via SQL

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

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

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

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

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.

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, 7zip, WinZip) 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.