Database Browsing

The Catalog Service provides endpoints for listing and inspecting databases registered in the catalog. Databases are organized by data source and are tenant-scoped.

List Databases

Retrieve a paginated list of all databases visible to the tenant.

Endpoint

GET /api/v1/catalog/databases?page={page}&size={size}

Example

curl "http://localhost:8086/api/v1/catalog/databases?page=0&size=20" \
  -H "X-Tenant-ID: 550e8400-e29b-41d4-a716-446655440000"

Response

{
  "content": [
    {
      "id": "db-001",
      "tenantId": "550e8400-...",
      "name": "analytics_warehouse",
      "fullyQualifiedName": "trino.analytics_warehouse",
      "description": "Central analytics data warehouse",
      "tableCount": 145,
      "dataSourceId": "ds-001"
    },
    {
      "id": "db-002",
      "tenantId": "550e8400-...",
      "name": "operational_db",
      "fullyQualifiedName": "postgres.operational_db",
      "description": "Operational application database",
      "tableCount": 89,
      "dataSourceId": "ds-002"
    }
  ],
  "totalElements": 12,
  "totalPages": 1,
  "number": 0,
  "size": 20
}

Get Database by FQN

Retrieve a specific database by its fully qualified name.

Endpoint

GET /api/v1/catalog/databases/{fqn}

Example

curl "http://localhost:8086/api/v1/catalog/databases/trino.analytics_warehouse" \
  -H "X-Tenant-ID: 550e8400-e29b-41d4-a716-446655440000"

Returns 200 OK with the database details or 404 Not Found.

List Databases by Data Source

Retrieve databases belonging to a specific data source.

Endpoint

GET /api/v1/catalog/databases/datasource/{dataSourceId}

Example

curl "http://localhost:8086/api/v1/catalog/databases/datasource/ds-001" \
  -H "X-Tenant-ID: 550e8400-e29b-41d4-a716-446655440000"

Response

[
  {
    "id": "db-001",
    "name": "analytics_warehouse",
    "fullyQualifiedName": "trino.analytics_warehouse",
    "tableCount": 145,
    "dataSourceId": "ds-001"
  }
]

Browse Hierarchy

The Discovery Controller provides hierarchical navigation through data sources, databases, schemas, and tables:

# List all data sources (top level)
curl "http://localhost:8086/api/v1/catalog/discovery/browse" \
  -H "X-Tenant-ID: 550e8400-..."
 
# List databases for a data source
curl "http://localhost:8086/api/v1/catalog/discovery/browse?dataSourceId=ds-001" \
  -H "X-Tenant-ID: 550e8400-..."
 
# List schemas for a database
curl "http://localhost:8086/api/v1/catalog/discovery/browse?dataSourceId=ds-001&database=analytics_warehouse" \
  -H "X-Tenant-ID: 550e8400-..."
 
# List tables for a schema
curl "http://localhost:8086/api/v1/catalog/discovery/browse?dataSourceId=ds-001&database=analytics_warehouse&schema=public" \
  -H "X-Tenant-ID: 550e8400-..."

Browse Response

{
  "tenantId": "550e8400-...",
  "currentDataSourceId": "ds-001",
  "currentDatabase": "analytics_warehouse",
  "currentSchema": null,
  "level": "SCHEMAS",
  "items": [
    { "name": "public", "type": "SCHEMA" },
    { "name": "staging", "type": "SCHEMA" },
    { "name": "reporting", "type": "SCHEMA" }
  ]
}

Source Reference

Component	File
Database listing	`CatalogController.java` -- `listDatabases()`, `getDatabaseByFqn()`
Data source filtering	`CatalogController.java` -- `getDatabasesByDataSource()`
Browse hierarchy	`CatalogDiscoveryController.java` -- `browse()`
Breadcrumb navigation	`CatalogDiscoveryController.java` -- `getBreadcrumb()`
Database entity	`CatalogDatabase.java`
Database repository	`CatalogDatabaseRepository.java`

Search & Autocomplete Table Management