​
How it Works

When you add the database query tool and the specified database context to your API request, Zylon follows these steps:
  1. Analyzes natural language: Zylon interprets your natural language question and understands what data you’re looking for.
  2. Generates SQL query: Automatically converts your question into the appropriate SQL query based on the database schema.
  3. Executes query: Runs the generated SQL query against your specified database connection.
  4. Returns results: Provides a coherent results based in the database response.

​
Important Notes

  • To use this tool, you must specify the type database_query_v1.
  • The tool_context must contain at least one sql_database with a valid connection_string.
  • You can use /v1/messages/validate to validate connectivity before.
  • The tool automatically generates SQL queries from natural language - no SQL knowledge required.
  • Results contains the SQL query, and results. If the content is too long, it will create a CSV file.
  • SSL connections are supported through the ssl parameter in the tool context.
  • Detailed instructions on how to establish database connections Database Connector documentation.

​
Example Usage

In this practical example, we connect to a SQL Server database and query customer information using natural language.
1

Perform Database Query

Send a request with your natural language question and the database connection details. The tool will automatically generate and execute the appropriate SQL query.
curl --location 'https://<your-host>/api/gpt/v1/messages' \
--header 'Authorization: Bearer <your-token>' \
--header 'x-org: default' \
--header 'Content-Type: application/json' \
--data '{
  "messages": [
    {
      "role": "user",
      "content": "What is the number of customers?"
    }
  ],
  "tools": [
    {
      "name": "database_query",
      "type": "database_query_v1"
    }
  ],
  "tool_choice": { "type": "auto" },
  "tool_context": [
    {
      "type": "sql_database",
      "connection_string": "__redacted__",
      "ssl": true
    }
  ]
}'
2

Response

The system responds with the generated SQL query, execution results, and a natural language answer:
 {
   "id": "msg_b8223938b59d471b90d19ec3aac01e82",
   "type": "message",
   "role": "assistant",
   "content": [
       {
           "type": "tool_use",
           "start_timestamp": "2025-09-24T14:24:34.937013Z",
           "stop_timestamp": "2025-09-24T14:24:36.074038Z",
           "id": "toolu_01997c1ca0787a20a01f1e445dac4ff7",
           "name": "database_query",
           "input": {
               "query": "What is the number of customers?"
           }
       },
       {
           "type": "tool_result",
           "start_timestamp": "2025-09-24T14:26:07.509036Z",
           "stop_timestamp": "2025-09-24T14:26:07.510799Z",
           "tool_use_id": "toolu_01997c1ca0787a20a01f1e445dac4ff7",
           "content": [
               {
                   "type": "text",
                   "text": "Query:\n```sql\nSELECT COUNT(*) AS NumberOfCustomers\nFROM Sales.Customers\n```
               },
               {
                   "type": "binary",
                   "filename": "What is the number of customers?.csv",
                   "data": "TnVtYmVyT2ZDdXN0b21lcnMKNjYzCg==",
                   "mime_type": "text/csv"
               },
               {
                   "type": "text",
                   "text": "Query result: \nNumberOfCustomers\n663\n"
               }
           ],
           "is_error": false
       },
       {
           "type": "text",
           "start_timestamp": "2025-09-24T14:26:07.834526Z",
           "stop_timestamp": "2025-09-24T14:26:08.504033Z",
           "text": "The number of customers is 663."
       }
   ],
   "model": "private-gpt",
   "stop_reason": "end_turn",
   "stop_sequence": null,
   "usage": {
       "input_tokens": 421,
       "output_tokens": 11
   }
}