ss-tools/specs/010-refactor-cli-to-web/quickstart.md

Quickstart: CLI Tools Web Interface

This guide explains how to use the new web-based tools for Superset management, which replace the legacy CLI scripts.

1. Accessing the Tools

1. Log in to the Web Application.
2. Navigate to the Tools section in the main navigation bar.
3. You will see three tabs/cards:
   • Search: Find text patterns in datasets.
   • Dataset Mapper: Map column names from external sources.
   • Debug: Run system diagnostics.

2. Searching Datasets

Use this tool to find specific SQL code, table names, or column definitions across the entire Superset instance.

1. Go to Tools > Search.
2. Select the Environment (e.g., dev, prod).
3. Enter your Search Query (supports Regex, e.g., from dm.*account).
4. Click Search.
5. Results will appear below, showing the dataset name, the field where the match was found, and the context.

3. Mapping Dataset Columns

Use this tool to update dataset column names (verbose_name) using comments from a database or an Excel file.

Step 3.1: Configure a Connection (One-time setup)

1. Go to Settings > Connections.
2. Click Add Connection.
3. Enter a name (e.g., "DWH Production") and the database credentials (Host, Port, DB, User, Password).
4. Click Save.

Step 3.2: Run the Mapper

1. Go to Tools > Dataset Mapper.
2. Select the target Environment and Dataset ID.
3. Select the Source Type (Postgres, Excel, or Both).
4. If using Postgres, select the Saved Connection you created in Step 3.1.
5. Enter the Table Name and Schema (e.g., public.sales).
6. Click Run Mapping.
7. The job will be submitted to the Task Manager. You can track progress in the Tasks view.

4. System Debugging

Use this tool to verify connectivity and API structures.

1. Go to Tools > Debug.
2. Select a diagnostic routine:
   • Test DB API: Checks if the backend can list databases from Superset.
   • Get Dataset Structure: Dumps the raw JSON structure of a specific dataset for inspection.
3. View the output log directly in the browser.