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:

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.

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.

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.

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.

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
• Start a Chat
• Manage Agents