# Connect EMQX Agents to EMQX Tables

The EMQX Tables connector lets an agent query and write time-series data through SQL. Use this connector to analyze telemetry history, enrich agent decisions with stored data, and write calculated results back to EMQX Tables.

## Common Use Cases

- Query recent telemetry before deciding whether to send an alert.
- Compare the latest reading with a historical baseline.
- Write an anomaly score or maintenance result to a table.
- Build a report from device data stored in EMQX Tables.

Example chat prompt:

```text
Use the factory-tables connector to query the last 20 temperature readings for the device ID in the MQTT event. Calculate the average and include it in the final response.
```

## Prerequisites

Before adding the connector, prepare:

- The EMQX Tables service address.
- A username and password if authentication is enabled.
- The database name.
- The table names and schemas required by the workflow.
- A database account with the minimum required SQL permissions.

## Add an EMQX Tables Connector

1. In the left navigation menu, click **Connectors**.
2. On the **Available** tab, locate **EMQX Tables** and click **Add**.
3. Configure the connector fields.
4. Click **Confirm**.
5. On the **Added** tab, verify that the connector appears in the list.

| Field | Required | Description |
|---|---|---|
| **Type** | Yes | The selected connector type, `EMQX Tables`. |
| **Name** | Yes | A display name, such as `factory-tables`. |
| **Address** | Yes | The Tables service address in `host:port` format. The default port is `4000`. If the port is omitted, EMQX Agents uses `4000`. |
| **Username** | No | The username used to authenticate with EMQX Tables. |
| **Password** | No | The password used to authenticate with EMQX Tables. |
| **Database Name** | No | The database to connect to. Default: `public`. |
| **Enable TLS/SSL** | No | Enables TLS for the connection. Disabled by default. |

<!-- TODO: Add a sanitized screenshot named agents_add_emqx_tables_connector.png if the final field order differs from the current documentation. -->

## Edit an EMQX Tables Connector

1. On the **Added** tab, click the edit icon for the EMQX Tables connector.
2. If the connector is not used by a deployed agent, update any of the following fields in the **Edit Connector** panel:
   - **Name**
   - **Address**
   - **Username**
   - **Password**
   - **Database Name**
   - **Enable TLS/SSL**
3. If the connector is used by a deployed agent, update only **Name**.
4. Click **Confirm**.

The **Type** field is read-only and cannot be changed.

::: warning Important Notice
Do not change the database name or other connection settings of a connector used by a deployed agent, even if a field is currently enabled.
:::

## Supported Tool

The connector provides the `tables.sql` tool. The tool accepts a SQL statement and can include parameters, a result limit, and a timeout.

Use the connector in a chat to inspect schemas, sample rows, and verify SQL before deploying an agent. The generated agent can then use the same connector at runtime.

::: warning Important Notice
SQL statements can modify or delete data if the connected account has write permissions. Use a read-only database account for read-only workflows and review SQL write operations before deployment.
:::

<!-- TODO: Confirm the user-visible maximum row limit, timeout range, and whether the Console exposes read-only or operation allow-list controls. -->

## Permissions and Security

- Grant the database account access only to the required database, schemas, and tables.
- Use a read-only account when the agent only needs to query data.
- Do not include the username or password in chat prompts or agent instructions.
- Use TLS when EMQX Tables is accessed over an untrusted network.

## Limitations

- Invalid SQL, missing tables, and insufficient database permissions cause tool calls to fail.
- Large result sets can exceed the agent's processing limits. Query only the columns and rows required by the workflow.
- The connector uses the permissions of the configured EMQX Tables account.

## Troubleshooting

| Symptom | Resolution |
|---|---|
| The connector cannot reach EMQX Tables. | Verify the address, port, TLS setting, and network access. |
| Authentication fails. | Verify the username, password, and database account status. |
| A query fails. | Verify the SQL syntax, database name, table names, and account permissions. |
| The result is truncated or too large. | Add filters, select fewer columns, or reduce the query limit. |

## Related Links

- [Connectors](../connectors.md)
- [Start a Chat](../chats.md)
- [Manage Agents](../agents.md)