> ## Documentation Index
> Fetch the complete documentation index at: https://backstage.spotify.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Portal database tables

> Find, inspect, query, visualize, and audit the database tables used by Portal plugins.

Portal plugins use database tables to store the data that powers their
features. Portal makes selected tables available as **Portal Database**
datasets in the Data Experience, giving Portal administrators a read-only way
to inspect operational data and create reports without direct database access.

Portal provisions this integration for your instance. You do not need to
configure a database connection or select tables.

## Understand Portal database datasets

Each Portal Database dataset represents one table owned by an installed Portal
plugin. Its display name uses the format `<plugin-id>.<table-name>`; for
example, `catalog.final_entities` is the `final_entities` table in the Catalog
plugin database.

The dataset page shows the table's columns and PostgreSQL data types. Tables
used for key storage and database migrations are not exposed.

Portal Database datasets are read-only. Queries cannot insert, update, or
delete Portal data.

## Find a table

1. Open **Data Experience** in Portal.
2. On the **Overview** page, find **Portal Database** under **Data Entities**
   and select it to open a filtered catalog view. You can also select
   **Browse Datasets** and filter the catalog by the **Portal Database** source.
3. Search for a plugin ID, table name, or full dataset name.
4. Open the dataset and select the **Query** tab. The **Open Dataset** action
   also takes you directly to this tab.

The number of cataloged Portal Database tables appears on the Data Experience
**Overview** page alongside the other dataset sources available in your
instance.

If you have a plugin or custom plugin that you don't see tables for, you can reach out to customer support.

## Query a table

The **Query** tab provides a PostgreSQL editor with the selected table's schema
beside it. The editor starts with a query that returns the first 10 rows from
the table.

You can:

* use table and column suggestions while writing SQL
* run read-only `SELECT` queries and common table expressions
* query the selected table or join other available tables in the same plugin
  database
* run a query with **Run Query** or <kbd>Command</kbd>/<kbd>Ctrl</kbd> +
  <kbd>Enter</kbd>
* save a query with a name and optional description
* reopen or delete saved queries
* load one of your recent queries back into the editor

Queries are limited to 1,000 returned rows and 30 seconds of execution time.
Portal displays a warning when a result is truncated. Add filters or grouping
to narrow the result when you need a complete view of a specific population.

## Work with query results

After a query runs, Portal shows the number of returned rows and the execution
time. Results open in a table where you can:

* open a row to inspect every field
* switch JSON values between formatted and raw views
* download the returned results as a CSV file

For compatible result shapes, Portal also provides a **Table**/**Chart**
control and automatically creates one of the following visualizations:

* a bar chart for grouped categories and numeric values
* a line chart for dates and numeric values
* statistic cards for a single row of numeric values

Results that do not fit one of these shapes remain in the table view.

## Review query activity

Your recent executions are available from **History** on each dataset's
**Query** tab. This history is specific to you and the selected dataset.

Portal administrators can review activity across users from **Data
Experience** > **Query Audit**. The audit trail shows:

* the user who ran the query
* the dataset and SQL statement
* when the query ran and how long it took
* how many rows were returned
* whether the query is running, succeeded, or failed

Use the filters to narrow records by user, dataset ID, status, or date range.
Select a record to inspect its full SQL and any error message, or follow its
dataset link back to the catalog. You can also export the filtered audit trail
as a CSV file and choose a date range for the export.

The **Query** and **Query Audit** views are available to users with the
corresponding Data Experience permissions. Portal administrators receive these
permissions by default.