GET/api/v1/datasources/{datasource_name}/catalog

Get Data Catalog

Retrieve the aggregated data catalog for a datasource, including all cataloged tables with their metadata. The catalog includes tables, columns, constraints, and statistics.

Path parameters

  • Name
    datasource_name
    Type
    string
    Required
    Description

    Name of the datasource to get catalog for.

Query parameters

  • Name
    mind
    Type
    string
    Required
    Description

    Optional mind name to filter catalog to only tables assigned to this mind.

Authorization

Request body

None.

Request

GET
/api/v1/datasources/{datasource_name}/catalog
curl --request GET \
--url 'https://mdb.ai/api/v1/datasources/my_datasource/catalog' \
--header 'Authorization: Bearer MINDS_API_KEY'

Response

{
  "datasource": {
    "id": "uuid",
    "name": "my_datasource",
    "description": "Datasource description",
    "engine": "postgres",
    "created_at": "2024-01-01T00:00:00Z",
    "modified_at": "2024-01-01T00:00:00Z"
  },
  "tables": [
    {
      "name": "users",
      "schema": "public",
      "description": "User table",
      "type": "BASE TABLE",
      "row_count": 1000,
      "status": "COMPLETED",
      "columns": [
        {
          "name": "id",
          "data_type": "integer",
          "description": "User ID",
          "default_value": null,
          "is_nullable": false,
          "statistics": {
            "most_common_values": null,
            "most_common_frequencies": null,
            "null_percentage": 0.0,
            "distinct_values_count": 1000,
            "min_value": "1",
            "max_value": "1000"
          }
        }
      ],
      "primary_key_constraints": [
        {
          "column_name": "id",
          "ordinal_position": 1,
          "constraint_name": "users_pkey"
        }
      ],
      "foreign_key_constraints": []
    }
  ],
  "total_tables": 1,
  "status": {
    "overall_status": "COMPLETED",
    "progress": 1.0,
    "message": "Catalog generation completed successfully",
    "active_flow_runs": 0
  }
}


POST/api/v1/datasources/{datasource_name}/catalog/refresh

Refresh Data Catalog

Refresh the data catalog for a datasource. This endpoint supports three refresh modes to update catalog metadata.

Path parameters

  • Name
    datasource_name
    Type
    string
    Required
    Description

    Name of the datasource to refresh catalog for.

Authorization

Request body

  • Name
    table_names
    Type
    array
    Required
    Description

    List of specific table names to refresh. If null or omitted, all tables are refreshed.

  • Name
    mode
    Type
    string
    Required
    Description

    Refresh mode: "missing_only" (only load uncataloged tables), "all" (refresh all specified tables), or "force" (delete and reload from scratch, requires mind-datasource relationship).

Request

POST
/api/v1/datasources/{datasource_name}/catalog/refresh
curl --request POST \
--url 'https://mdb.ai/api/v1/datasources/my_datasource/catalog/refresh' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer MINDS_API_KEY' \
--data '{
    "mode": "all"
}'

Response

{
  "datasource": {...},
  "tables": [...],
  "total_tables": 2,
  "status": {
    "overall_status": "LOADING",
    "progress": 0.5,
    "message": "Catalog generation in progress",
    "active_flow_runs": 1
  }
}


POST/api/v1/datasources/{datasource_name}/catalog/tables

Load Specific Tables

Load specific tables into the data catalog for a datasource. This is useful for on-demand cataloging of specific tables. Requires an existing mind-datasource relationship.

Path parameters

  • Name
    datasource_name
    Type
    string
    Required
    Description

    Name of the datasource.

Authorization

Request body

  • Name
    table_names
    Type
    array
    Required
    Description

    List of table names to load into the catalog.

Request

POST
/api/v1/datasources/{datasource_name}/catalog/tables
curl --request POST \
--url 'https://mdb.ai/api/v1/datasources/my_datasource/catalog/tables' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer MINDS_API_KEY' \
--data '{
    "table_names": ["users", "orders", "products"]
}'

Response

{
  "datasource": {...},
  "tables": [...],
  "total_tables": 3,
  "status": {...}
}


PATCH/api/v1/datasources/{datasource_name}/catalog/tables/{table_name}

Update Table Description

Update the description of a table in the data catalog. This allows you to add custom metadata without reloading from MindsDB.

Path parameters

  • Name
    datasource_name
    Type
    string
    Required
    Description

    Name of the datasource.

  • Name
    table_name
    Type
    string
    Required
    Description

    Name of the table to update.

Authorization

Request body

  • Name
    description
    Type
    string
    Required
    Description

    New description for the table. Set to null to clear the description.

Request

PATCH
/api/v1/datasources/{datasource_name}/catalog/tables/{table_name}
curl --request PATCH \
--url 'https://mdb.ai/api/v1/datasources/my_datasource/catalog/tables/users' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer MINDS_API_KEY' \
--data '{
    "description": "User accounts table containing authentication and profile information"
}'

Response

{
  "name": "users",
  "schema": "public",
  "description": "Updated table description",
  "type": "BASE TABLE",
  "row_count": 1000,
  "status": "COMPLETED",
  "columns": [...],
  "primary_key_constraints": [...],
  "foreign_key_constraints": [...]
}


PATCH/api/v1/datasources/{datasource_name}/catalog/tables/{table_name}/columns/{column_name}

Update Column Description

Update the description of a column in the data catalog. This allows you to add custom metadata without reloading from MindsDB.

Path parameters

  • Name
    datasource_name
    Type
    string
    Required
    Description

    Name of the datasource.

  • Name
    table_name
    Type
    string
    Required
    Description

    Name of the table containing the column.

  • Name
    column_name
    Type
    string
    Required
    Description

    Name of the column to update.

Authorization

Request body

  • Name
    description
    Type
    string
    Required
    Description

    New description for the column. Set to null to clear the description.

Request

PATCH
/api/v1/datasources/{datasource_name}/catalog/tables/{table_name}/columns/{column_name}
curl --request PATCH \
--url 'https://mdb.ai/api/v1/datasources/my_datasource/catalog/tables/users/columns/email' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer MINDS_API_KEY' \
--data '{
    "description": "User email address, must be unique and valid"
}'

Response

{
  "name": "email",
  "data_type": "varchar",
  "description": "Updated column description",
  "default_value": null,
  "is_nullable": false,
  "statistics": {
    "null_percentage": 0.0,
    "distinct_values_count": 950
  }
}


DELETE/api/v1/datasources/{datasource_name}/catalog/tables/{table_name}

Delete Table Catalog

Permanently delete catalog data for a specific table. This removes all metadata including columns, constraints, statistics, and relationships. Warning: This operation cannot be undone.

Path parameters

  • Name
    datasource_name
    Type
    string
    Required
    Description

    Name of the datasource.

  • Name
    table_name
    Type
    string
    Required
    Description

    Name of the table to delete catalog for.

Authorization

Request body

None.

Request

DELETE
/api/v1/datasources/{datasource_name}/catalog/tables/{table_name}
curl --request DELETE \
--url 'https://mdb.ai/api/v1/datasources/my_datasource/catalog/tables/users' \
--header 'Authorization: Bearer MINDS_API_KEY'

Response

204 No Content


DELETE/api/v1/datasources/{datasource_name}/catalog

Delete All Catalog for Datasource

Permanently delete all catalog data for a datasource. This removes all cataloged tables and their metadata. Warning: This operation cannot be undone.

Path parameters

  • Name
    datasource_name
    Type
    string
    Required
    Description

    Name of the datasource.

Authorization

Request body

None.

Request

DELETE
/api/v1/datasources/{datasource_name}/catalog
curl --request DELETE \
--url 'https://mdb.ai/api/v1/datasources/my_datasource/catalog' \
--header 'Authorization: Bearer MINDS_API_KEY'

Response

204 No Content


Catalog Status

The data catalog API includes status information to track catalog generation progress. Status is provided at two levels:

Overall Status (Datasource Level)

  • NOT_STARTED: No catalog generation has been initiated
  • PENDING: Catalog generation is scheduled but not yet running
  • LOADING: Catalog generation is currently in progress
  • COMPLETED: Catalog generation completed successfully
  • FAILED: Catalog generation failed
  • CANCELLED: Catalog generation was cancelled

Table Status (Table Level)

  • NOT_CATALOGED: Table exists in the datasource but hasn't been cataloged yet
  • PENDING: Table cataloging is scheduled but not yet running
  • LOADING: Table cataloging is currently in progress
  • COMPLETED: Table cataloging completed successfully
  • FAILED: Table cataloging failed
  • CANCELLED: Table cataloging was cancelled

Refresh Modes

  1. missing_only: Only loads tables that exist in the datasource but aren't cataloged. Safe to use repeatedly. Recommended for incremental catalog building.

  2. all (default): Refreshes metadata for all specified tables. Updates existing catalog entries. Use when you want to update statistics or schema changes.

  3. force: Deletes existing catalog data for specified tables and reloads from scratch. Requires: An existing mind-datasource relationship. Use when you need to completely rebuild catalog data.

Was this page helpful?