--- title: How to use a SQL query as a Scenario Outline data source description: This article details what the SQL Examples data source is, as well as why and how to use it. --- [Skip to content](https://kb.cyclelabs.io/how-to-use-a-sql-query-as-a-scenario-outline-data-source#main-content) English - United States Show submenu for translations ![](https://kb.cyclelabs.io/hs-fs/hubfs/main-lockup-color-Aug-11-2026-06-33-05-0386-PM.png?width=500&height=93&name=main-lockup-color-Aug-11-2026-06-33-05-0386-PM.png) Open main navigation Close main navigation - English - United States Show submenu for translations - [Get Support & Track Tickets](https://help.cyclelabs.io/) [Get Support & Track Tickets](https://help.cyclelabs.io/?hsLang=en-us) How can we help you? - There are no suggestions because the search field is empty. 1. [Cycle Knowledge Base](https://kb.cyclelabs.io/?hsLang=en-us) 2. [Getting started](https://kb.cyclelabs.io/getting-started?hsLang=en-us) # How to use a SQL query as a Scenario Outline data source ## This article details what the SQL Examples data source is, as well as why and how to use it. With the enhancements to Scenario Outlines, it is now possible to use multiple sources for test parameter data. Previously, parameters were set in the Feature in an Examples section specified and maintained by the user. The addition of Example Row, CSV, SQL, MOCA, and Datastore sources provide more dynamic permutations and less maintenance. ### What are SQL Examples? SQL stands for Structured Query Language and is a mechanism for interaction with databases. SQL Examples in Cycle is the keyword used in Scenario Outlines to use a SQL query result set as the test parameters to be used in execution. The query is contained in a .sql file. The SQL query will return column names and those names will become the Cycle variable names. Each row in the result set will generate an iteration of the Scenario Outline. Example: ``` Scenario Outline: SQL TestSQL Examples: scripts\wh.sql connected to logged in as ``` ### Why use a SQL query? Using a SQL query for Scenario Outline provides a dynamic way to build test parameter iterations. Static data values are not required. Once the query is built that generates the necessary parameters to use in the test it can be reused over and over. The data elements themselves may change but the query remains the same and therefore requires little maintenance if any. ### How to use SQL queries? First and foremost you will need to have valid SQL syntax in your .sql file. For help writing proper SQL there are many tutorials available for free on the web. Also, there are many open source tools to use while developing the query for your .sql file. A very popular one is [DBeaver](https://dbeaver.io) due to its ability to connect to many database platforms. SQL Examples are used with the keyword **Scenario Outline:**. As in the above example illustrates, it is declared on the line immediately following Scenario Outline. Another critical step to using SQL files in Scenario Outlines is you must provide Connection and Credentials for access to your database. **Before going any further please review the KB article on [setting up Connections and Credentials](https://kb.cyclelabs.io/how-to-store-connections-and-credentials-in-cycle?hsLang=en-us) in Cycle.** Once you have your Connections and Credentials saved, they are referenced with the following syntax immediately following the file path. ``` Scenario Outline: SQL TestSQL Examples: scripts\wh.sql connected to logged in as ``` If you reference saved connections or credentials by an incorrect name or that have not yet been created you will receive the following error at execution.  ![](https://i18ndesk.zoho.com/DocsDisplay?zgId=745719688&mode=inline&blockId=q9l842279fc60b88b47c3adf98ce92812bc09)  If your connection string is invalid you will receive an error similar to below at execution.  ![](https://i18ndesk.zoho.com/DocsDisplay?zgId=745719688&mode=inline&blockId=q9l840a893e357c1449e1b5935c9ec8448c31)  If your credentials are invalid you will receive an error similar to below at execution.  ![](https://i18ndesk.zoho.com/DocsDisplay?zgId=745719688&mode=inline&blockId=q9l844140fd8f21fe41c6a894519cda0bc41d)  The **SQL** **Examples** keyword requires a Project relative directory path to a valid SQL file. In the example above we provided **scripts\\wh.sql** as the path. The full path would be similar to C:\\Cycle\\PROJECT\_DIR\\scripts\\wh.sql with PROJECT\_DIR being the example Project directory. When the Scenario Outline is executed Cycle converts the column names from the result set to variable names as chevron variables and the subsequent data rows as the values to use in the Steps. Each data row will be an iteration of the Scenario Outline executions steps. For example if you have a SQL file formatted like: ``` /* In my DB this query will return 2 rows*/SELECT wh_idFROM wh;/*Result set*/  ``` then Steps use the chevron and variable replacement to use the information provided. **Given I echo \** When the Step executes \ will be replaced with WMD1 in the first iteration and WMD2 in the second. ### Putting it all together In this example, the Steps verify successful connection for a specific terminal device. The SQL file contains a query to return the list of terminal devices to validate. SQL file example: ``` SELECT term_id as TERMINAL_ID FROM rf_term_mst where wh_id = 'WMD1' and term_typ = 'vehicle'; ``` ``` Scenario Outline:Vehicle Terminal TestSQL Examples:Datasets\vehicle_terminals.sql connected to TEST_DB logged in as TEST_CREDENTIALSThen I open terminal connected to "HOST:PORT" for terminal If I see "Terminal ID" on line 1 in terminal within 5 secondsThen I enter in terminalEndifOnce I see "User ID" in terminalThen I close terminal ``` When new terminals are added to the system that have the same criteria they will automatically get validated at Scenario Outline execution with no change to the SQL file or the Feature. The Output in the Output Panel shows each Example numbered individually for troubleshooting.  ![](https://i18ndesk.zoho.com/DocsDisplay?zgId=745719688&mode=inline&blockId=q9l84cb0131c8524440ecb4dec067dc8aeeb8)  - [Getting started](https://kb.cyclelabs.io/getting-started?hsLang=en-us) - [Using Cycle with BYWMS](https://kb.cyclelabs.io/using-cycle-with-bywms?hsLang=en-us) - [Cycle Appliance and CI/CD](https://kb.cyclelabs.io/cycle-appliance-and-ci-cd?hsLang=en-us) - [Tips and Tricks](https://kb.cyclelabs.io/tips-and-tricks?hsLang=en-us) - [Native App](https://kb.cyclelabs.io/native-app?hsLang=en-us) - [Deprecated Steps](https://kb.cyclelabs.io/deprecated-steps?hsLang=en-us) - [Common Issues](https://kb.cyclelabs.io/common-issues?hsLang=en-us) [![](https://kb.cyclelabs.io/hs-fs/hubfs/main-lockup-color-Aug-11-2026-06-33-05-0386-PM.png?width=500&height=93&name=main-lockup-color-Aug-11-2026-06-33-05-0386-PM.png)](http://cyclelabs.io) [mailto:email@email.com](mailto:email@email.com) Copyright © 2026, Cycle Labs