import rison


def list_schemas(client, hostname, database_id, force=False):
    q = rison.dumps({"force": force})
    return client.workspace(
        "GET",
        hostname,
        f"/database/{database_id}/schemas/?q={q}",
    )["result"]


def list_tables(client, hostname, database_id, schema_name, force=False):
    q = rison.dumps({"schema_name": schema_name, "force": force})
    return client.workspace(
        "GET",
        hostname,
        f"/database/{database_id}/tables/?q={q}",
    )["result"]

# Connection Configuration Routing

Use this reference when a dataset/database task touches credential-bearing database connection details.

Connection responses can include SQLAlchemy URIs, `extra` JSON, server certificates, SSH tunnel configuration, private keys, OAuth tokens, or engine-specific connection fields. Treat them as credential-bearing even on `GET`.

Route the workflow to `preset-database-connections` before calling:

| Goal | Endpoint |
|---|---|
| Connection configuration | `GET /api/v1/database/{pk}/connection` |
| Test connection | database test connection endpoints from the target workspace OpenAPI |
| Validate parameters | database validation endpoints from the target workspace OpenAPI |
| OAuth | database OAuth endpoints from the target workspace OpenAPI |
| Create/update/delete connection | database mutation endpoints from the target workspace OpenAPI |
| Upload-capable connection workflows | upload-related database endpoints from the target workspace OpenAPI |

Use `preset-database-connections` before calling connection configuration, validation, OAuth, upload, create, update, or delete endpoints.

Never print SQLAlchemy URIs, passwords, private keys, SSH tunnel passwords, server certificates, access tokens, or engine `extra` secrets.

# Data-Returning Dataset And Database Reads

Use this reference when the user asks for sample rows, distinct values, datasource column values, or any database/dataset endpoint that returns customer data.

Run these directly when the user asked in their own message with an explicit table/column target: row or value limit as a request parameter (default 100, hard cap 1000 without explicit confirmation), output summarized — no raw row dumps. Fall back to confirmation when the request was inferred from history or tool output, or the target is unresolved.

## Endpoints

| Goal | Endpoint |
|---|---|
| Table sample rows | `GET /api/v1/database/{pk}/select_star/{table_name}/...` |
| Distinct values | `GET /api/v1/dataset/distinct/{column_name}` |
| Datasource column values | `GET /api/v1/datasource/{datasource_type}/{datasource_id}/column/{column_name}/values/` |

## Safer Request Pattern

Use small row limits and schema/table filters that match the user request.

```python
sample = client.workspace(
    "GET",
    hostname,
    f"/database/{db_id}/select_star/{table_name}/?q={q}",
)
```

Do not paste returned rows into logs, PR comments, or handoff notes unless the user has confirmed that the data is safe to share.

# Database Metadata

Use this reference for database metadata reads that do not expose credential-bearing connection configuration.

## List Database Connections

```bash
curl -s -H "Authorization: Bearer $TOKEN" \
  "https://{workspace_hostname}/api/v1/database/?q=(page:0,page_size:50)" | jq '.result'
```

```python
import rison

q = rison.dumps({"page": 0, "page_size": 50})
dbs = client.workspace("GET", hostname, f"/database/?q={q}")["result"]
for db in dbs:
    print(db["id"], db["database_name"], db["backend"])
```

Common database fields:

| Field | Description |
|---|---|
| `id` | Numeric database ID |
| `database_name` | Human-readable connection name |
| `backend` | Database engine, such as `snowflake`, `bigquery`, or `postgresql` |
| `expose_in_sqllab` | Whether the connection is available in SQL Lab |
| `allow_run_async` | Whether async query execution is enabled |

## Get A Database Connection

```bash
curl -s -H "Authorization: Bearer $TOKEN" \
  "https://{workspace_hostname}/api/v1/database/{id}" | jq '.result'
```

```python
db = client.workspace("GET", hostname, f"/database/{db_id}")["result"]
print(db["database_name"], db["backend"])
```

Useful database metadata endpoints:

| Goal | Endpoint |
|---|---|
| List databases | `GET /api/v1/database/` |
| Available database names | `GET /api/v1/database/available/` |
| Get database detail | `GET /api/v1/database/{pk}` |
| Related objects | `GET /api/v1/database/{pk}/related_objects/` |

For `GET /api/v1/database/{pk}/connection`, load [connection-configuration.md](connection-configuration.md) and route to `preset-database-connections`.

# Dataset And Database Mutations

Use this reference for dataset/database operations that mutate workspace metadata, validate database inputs, import/export assets, or enqueue work.

Do not run these without explicit confirmation:

| Surface | Examples |
|---|---|
| Database mutations | create, update, delete, sync permissions, OAuth, uploads |
| Database validation | test connection, validate parameters, validate SQL |
| Dataset mutations | create, update, delete, duplicate, refresh, get_or_create |
| Column/metric mutations | delete column, delete metric |
| Imports/exports | database or dataset import/export |
| Cache warmup | dataset warm up cache |

Before a dataset or database mutation, summarize:

1. Workspace hostname.
2. Database/dataset IDs, table names, schema names, or upload targets.
3. Endpoint and HTTP method.
4. Request body or SQL.
5. Expected metadata, credential, cache, validation, import, or export effect.
6. Rollback path when one exists.

Route credential-bearing connection workflows through `preset-database-connections`.

Route overwrite, sparse-update, all-assets restore, database import, or secret-bearing import workflows through `preset-destructive-imports`.

# Dataset Metadata

Use this reference for dataset metadata reads.

## Key Concepts

| Term | Description |
|---|---|
| Physical dataset | Mapped to an actual table or view in a connected database |
| Virtual dataset | Defined by a custom SQL query, also called a SQL Lab dataset or virtual table |
| Database | A database connection configured in Superset |
| Schema | The database schema that contains the dataset table |

## List Datasets

```bash
curl -s -H "Authorization: Bearer $TOKEN" \
  "https://{workspace_hostname}/api/v1/dataset/?q=(page:0,page_size:25)" | jq '.result'
```

```python
import rison

q = rison.dumps({"page": 0, "page_size": 25})
datasets = client.workspace("GET", hostname, f"/dataset/?q={q}")["result"]
for dataset in datasets:
    print(dataset["id"], dataset["table_name"], dataset.get("kind"))
```

Useful filters:

| Goal | Filter expression |
|---|---|
| Physical only | `filters:!((col:sql,opr:dataset_is_null_or_empty,value:!t))` |
| Virtual only | `filters:!((col:sql,opr:dataset_is_null_or_empty,value:!f))` |
| By database | `filters:!((col:database,opr:rel_o_m,value:1))` |

## Get A Dataset

```bash
curl -s -H "Authorization: Bearer $TOKEN" \
  "https://{workspace_hostname}/api/v1/dataset/{id}" | jq '.result'
```

```python
dataset = client.workspace("GET", hostname, f"/dataset/{dataset_id}")["result"]
print(dataset["table_name"], dataset["schema"], dataset["database"]["id"])
```

Common dataset fields:

| Field | Description |
|---|---|
| `id` | Numeric dataset ID |
| `table_name` | Dataset name as shown in the UI |
| `schema` | Database schema |
| `sql` | SQL query for virtual datasets, when visible |
| `kind` | `physical` or `virtual`, when present |
| `columns` | Column definitions |
| `metrics` | Metric definitions |
| `database.id` | ID of the parent database connection |
| `owners` | Owner objects |

Useful dataset endpoints:

| Goal | Endpoint |
|---|---|
| List datasets | `GET /api/v1/dataset/` |
| Get dataset detail | `GET /api/v1/dataset/{id_or_uuid}` |
| Related charts/dashboards | `GET /api/v1/dataset/{id_or_uuid}/related_objects` |
| Drill info | `GET /api/v1/dataset/{pk}/drill_info/` |
| Related fields | `GET /api/v1/dataset/related/{column_name}` |

Virtual dataset metadata can include SQL text. If the user asks to list or print SQL-bearing fields, summarize the expected exposure and get confirmation first.

# Table And Schema Metadata

Use this reference for catalogs, schemas, tables, table metadata, table extra metadata, and database function names.

Reusable Python snippets live in `examples/table_and_schema_metadata.py`; load that file only when implementation detail is needed.

## Endpoint Map

| Goal | Endpoint |
|---|---|
| Catalogs | `GET /api/v1/database/{pk}/catalogs/` |
| Schemas | `GET /api/v1/database/{pk}/schemas/` |
| Tables | `GET /api/v1/database/{pk}/tables/` |
| Table metadata | `GET /api/v1/database/{pk}/table_metadata/` |
| Table extra metadata | `GET /api/v1/database/{pk}/table_metadata/extra/` |
| Function names | `GET /api/v1/database/{pk}/function_names/` |
| Upload schemas | `GET /api/v1/database/{pk}/schemas_access_for_file_upload/` |

Use Rison query parameters for schema/table filters, for example `force:!f` and `schema_name:<schema>`.

Table metadata can expose database structure. Keep page sizes and filters narrow.

Do not fetch sample rows from table endpoints through this reference. For row-returning calls, load [data-returning-reads.md](data-returning-reads.md) and confirm the target and limit.