Usage Logs
The SQL Database Reader logs every query execution automatically. Each log entry records the user's original question, the generated SQL, execution status, row count, and any error messages. Use logs to audit data access, debug query failures, and understand usage patterns over time.
Navigate to Actions → Plugins → SQL Database Reader → Logs in the agent sidebar.
Log Summary
The summary view shows daily aggregated counts for the plugin configuration.
| Column | Description |
|---|---|
| Date | The calendar day in yyyy-MM-dd format. |
| Total | Total number of query executions on that day. |
| Success | Queries that executed and returned results. |
| Failed | Queries that encountered an error during translation or execution. |
The summary loads the most recent days first. Click Load More to page through older entries.
Viewing Detailed Logs
Click on a date row in the summary to open the detail view for that day. Each row represents one query execution.
| Field | Description |
|---|---|
| Time | Timestamp of the query execution. |
| User ID | The user who asked the question. |
| Question | The original natural language question entered by the user. |
| SQL Query | The SQL generated and executed by the plugin. |
| Status | success or failed. |
| Row Count | Number of rows returned by the query. |
| Error | Error message if the query failed, empty otherwise. |
Use the page controls at the bottom to navigate through large numbers of entries. Up to 100 rows are returned per page.
Downloading Logs as CSV
Click Download CSV on any date in the summary to export all log entries for that day as a CSV file. The export includes all fields: timestamp, user ID, question, SQL query, status, row count, and error message.
CSV exports are useful for sharing logs with a data governance team or loading them into an external analytics tool.
What Causes a Failed Status
| Cause | Typical error message |
|---|---|
| Invalid SQL generated by AI | Syntax error near... |
| Table or column name not found | Invalid object name... |
| Query execution timeout | Execution timeout exceeded 30 seconds |
| Database connection lost during execution | Network error / Connection refused |
| Insufficient database permissions | The SELECT permission was denied on object... |
When a query fails, the original question and the attempted SQL are still logged. Review the SQL Query field to understand what the AI generated. If the SQL is syntactically correct but logically wrong, improve table and column descriptions in the schema configuration. If the SQL cannot be generated at all, the error points to a translation failure.
Log Storage and Retention
Logs are stored in CosmosDB, partitioned by agent ID, configuration ID, and log day. There is no automatic expiry — logs accumulate until manually removed or until storage limits are reached.
Related Pages
- Testing Queries — reproduce a failed query in the safe testing environment.
- Configure Tables and Columns — improve schema descriptions to reduce translation failures.
- SQL Database Reader Overview