# View browsable connectors

Lists the connectors in the current workspace that can browse databases, tables, or collections, and displays the query operations supported by each connector. After selecting an available connector, query the database, schema, object and field structure.

```text
GET https://moi.matrixorigin.cn/newmoi/connectors/structured/v1/sources
```

## Preparation before calling

Prepare a personal access token and target workspace ID that has access to the target workspace. The response only contains connectors that you have permission to use.

The example below uses:

- `$AI_STUDIO_API_KEY`: The actual personal access token, passed through the `X-API-Key` Header.
- `$WORKSPACE_ID`: The workspace ID to be queried, passed through the `X-Workspace-ID` Header.

### Supported sources and discovery paths

Structured discovery currently supports Hive, MySQL, SQL Server, Oracle, PostgreSQL, and MongoDB. The following table explains each type of object discovery path; when actually called, the ability marked as `true` in the response shall prevail.

| connector type | `source_type` | discovery path | Object identifier |
| --- | --- | --- | --- |
| Hive | `SOURCE_TYPE_HIVE` | Database → Table → Table Structure | `table` |
| MySQL | `SOURCE_TYPE_MYSQL` | Database → Table → Table Structure | `table` |
| SQL Server | `SOURCE_TYPE_SQLSERVER` | Database → Schema → Table → Table structure | `schema`, `table` |
| Oracle | `SOURCE_TYPE_ORACLE` | Database → Schema → Table → Table structure | `schema`, `table` |
| PostgreSQL | `SOURCE_TYPE_POSTGRESQL` | Database → Schema → Table → Table structure | `schema`, `table` |
| MongoDB | `SOURCE_TYPE_MONGODB` | Database → Collection → Table Structure | `collection` |

Although MatrixOne can be created as a database connector, it is currently not returned through this interface, and its database, table or table structure cannot be queried using this set of interfaces.

## Request example

```bash
curl "https://moi.matrixorigin.cn/newmoi/connectors/structured/v1/sources" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID"
```

## Successful response

Returns `200` on success.

```json
{
  "code": "OK",
  "msg": "OK",
  "data": {
    "sources": [
      {
        "connector_id": "conn_01",
        "connector_name": "orders_mysql",
        "source_type": "SOURCE_TYPE_MYSQL",
        "enabled": true,
        "disabled_reason": "",
        "capability_profile_hash": "capability-profile-hash",
        "capabilities": {
          "list_databases": true,
          "list_schemas": false,
          "list_tables": true,
          "describe_schema": true,
          "sample": false,
          "backfill_start_resolve": false,
          "hive_partitions": false,
          "mongodb_flatten": false
        }
      }
    ]
  }
}
```

The response fields are as follows.

| Field | Type | Description |
| --- | --- | --- |
| `code` | string | `OK` on success. |
| `msg` | string | `OK` on success. |
| `data.sources` | object[] | The connectors in the current workspace that are available or evaluable for structured discovery. |
| `data.sources[].connector_id` | string | Connector ID. Subsequent discovery of the interface uses this ID. |
| `data.sources[].connector_name` | string | Connector name. |
| `data.sources[].source_type` | string | Structured source type. |
| `data.sources[].enabled` | boolean | Whether the discovery interface corresponding to this entry can continue to be called. Only entries are available to proceed to subsequent steps. |
| `data.sources[].disabled_reason` | string | The reason why it is not available. When the value is `STRUCTURED_LOAD_MONGODB_DISABLED`, the current workspace cannot use MongoDB structured discovery; the entry should not continue to call subsequent interfaces. |
| `data.sources[].capability_profile_hash` | string | A summary of the current capability description. This value may change when the capability configuration changes; when creating a structured import task, fill in this value into `consistency_contract.capability_profile_hash`. May be omitted when capability information is not available. |
| `data.sources[].capabilities` | object | The structured source capabilities that the current connector can call. Only make corresponding requests for capabilities marked as `true`. |
| `data.sources[].capabilities.list_databases` | boolean | Whether the database can be queried. |
| `data.sources[].capabilities.list_schemas` | boolean | Whether the database Schema can be queried. |
| `data.sources[].capabilities.list_tables` | boolean | Whether the table or collection can be queried. |
| `data.sources[].capabilities.describe_schema` | boolean | Whether the field structure of the table or collection can be queried. |
| `data.sources[].capabilities.sample` | boolean | Whether source data sampling is supported. |
| `data.sources[].capabilities.backfill_start_resolve` | boolean | Whether to support parsing the backfill starting point of structured import. |
| `data.sources[].capabilities.hive_partitions` | boolean | Whether to support querying Hive partitions. |
| `data.sources[].capabilities.mongodb_flatten` | boolean | Whether to support MongoDB's flat mapping capability. |

`[]` after a type denotes an array. `[]` in a field path denotes each item in an array.

In field paths, `[]` means each item in an array. For example, `data.sources[].connector_id` is the `connector_id` field of each item in `data.sources`.

## Error response

```json
{
  "code": "STRUCTURED_CONNECTOR_SERVICE_UNAVAILABLE",
  "msg": "service unavailable",
  "data": null
}
```

### Common HTTP errors

```{list-table}
:header-rows: 1
:widths: 12 30 28 30

* - HTTP status code
  - error code
  - Common causes
  - Recommended actions
* - `501`
  - `STRUCTURED_CONNECTOR_SERVICE_UNAVAILABLE`
  - The current service does not provide structured data source discovery.
  - This group of interfaces is temporarily unavailable.
* - `200`
  - `STRUCTURED_LOAD_FEATURE_DISABLED`
  - The structured data source feature is not enabled in the current workspace.
  - Check if this feature is available for this workspace.
* - `500`
  - `ErrServer`
  - The service failed to list available connectors.
  - Keep the desensitization error message and try again.
```

## Follow-up operations

With a saved connector selected, [query the connector database](list-databases.md) with its ID. Continue only if the connector has a capability tag in the list that supports enumerating databases.