> Source: https://wexa.ai/docs/context/connector-read

# connector-read

Run a read-only query for the rows of a database source, live against the source: nothing is copied into Wexa. Needs the `fabric:query.read` grant.

The shape of `result` for `connector-read` is not recorded here: it was not captured against a live deployment. Call it once and read what comes back rather than assuming a shape.

**Read rows live**

**Wexa MCP server**

```bash
curl -sS -X POST https://fabric.wexa.ai/mcp/$FABRIC_PROJECT_ID \
  -H "authorization: Bearer $FABRIC_API_KEY" \
  -H "Mcp-Session-Id: $MCP_SESSION_ID" \
  -H "content-type: application/json" -H "accept: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"connector-read","arguments":{"connectorId":"6ab3608bf19beb4f0ed39e77","table":"orders","limit":10}}}'
```

**REST API**

```bash
curl -sS https://fabric.wexa.ai/v1/connector-read \
  -H "authorization: Bearer $FABRIC_API_KEY" \
  -H "content-type: application/json" \
  -d '{"connectorId":"6ab3608bf19beb4f0ed39e77","table":"orders","limit":10}'
```

**TypeScript SDK**

```ts
import { Fabric } from '@wexa-fabric/sdk'

const fabric = new Fabric()
const result = await fabric.connectorRead({
  connectorId: '6ab3608bf19beb4f0ed39e77',
  table: 'orders',
  limit: 10
})
```

**Python SDK**

```python
from wexa import Fabric

fabric = Fabric()
out = fabric.connector_read(
    connectorId="6ab3608bf19beb4f0ed39e77",
    table="orders",
    limit=10,
)
```

## Parameters

| Parameter | Type | Required | Notes |
| --- | --- | --- | --- |
| `connectorId` | string | Optional | Connector id of the database source, from a `liveReadable` ontology node. A node without one is not live-readable. A connector wired to this project. |
| `sql` | string | Optional | One read-only `SELECT` formed from the project ontology (SQL sources). Writes are rejected. |
| `table` | string | Optional | Table or collection to read when not passing `sql`. |
| `filter` | object | Optional | Mongo find filter. |
| `aggregate` | array | Optional | Mongo read-only aggregation stages, used with `table`. `$out` and `$merge` are rejected. |
| `list_collections` | boolean | Optional | Mongo: list the source's collection names, with no row data. |
| `action` | string | Optional | Name of a read action, for example `linear.get_issues`, for connectors with synced read actions. |
| `params` | object | Optional | Parameters for the `action` read. |
| `limit` | integer | Optional | Max rows (default 100, hard cap 10000). |

**More details**

The `aggregate` parameter takes Mongo aggregation stages, for example `[{"$group":{"_id":"$siteId","posts":{"$sum":1}}}]` with `table` set to the collection. For how a source becomes reachable and what ingestion brings in, see [Connectors](/docs/connectors/overview).

Full description from the tool, as the gateway advertises it:

Run a READ-ONLY query for the ACTUAL ROWS of an OM-synced/Wexa DB source, LIVE against the source (nothing is copied into Wexa — ideal for large warehouse/DB sources). Use this ONLY for data/rows. For the shape of the source (which tables/collections exist and their fields), do NOT call this — read it from the ontology graph instead (fast, no live call): the connector's tables are Table nodes carrying name + fields. FIRST get a connectorId from the ontology with query-context: `MATCH (t:Table) WHERE t.liveReadable = true AND t.connectorId IS NOT NULL RETURN t.name, t.connectorId, t.serviceType, t.readAction, t.fields` (or DataService for source-level). ONLY use a connectorId from a node where liveReadable=true — nodes without connectorId are OM-crawled metadata and are NOT live-readable (passing one yields "invalid connector id"). Then call this with that connectorId + a query you formed from that shape: SQL → 'sql' (read-only SELECT) or 'table'; Mongo → 'table' + 'filter'/'aggregate', or 'list_collections'. Write/CRUD actions are blocked.

Not marked consequential: it is audited lightly and the project's write gate never holds it.

Every tool call works the same way: [How every tool call works](/docs/sdks-and-apis/how-every-tool-call-works).