---
title: "system.db.runNamedQuery"
description: "Runs a named query and returns the results."
---

# system.db.runNamedQuery

> Runs a named query and returns the results.

This function is used in **Python Scripting**.

## Description

Runs a Named Query and returns the results. Note that the number of parameters in the function is determined by scope. Both versions of the function are listed below.

This function accepts [keyword arguments](platform\scripting\python-scripting\user-defined-functions.md).

## Client Permission Restrictions

This scripting function has no [Client Permission](ignition-modules\vision\vision-project-properties\vision-project-properties.md#vision-permissions-properties) restrictions.

## Project Scope Syntax

`system.db.runNamedQuery(path, [parameters], [tx], [getKey])`

### Parameters
Type | Parameter | Description 
------- | ------- | -----
String| `path` | The path to the named query to run. Note that this is the full path to the query, including any folders.
Dictionary[String, Any]| `parameters` | A Python dictionary of parameters for the Named Query to use. [optional]
String| `tx` | An transaction ID, obtained from [beginNamedQueryTransaction](appendix\scripting-functions\system-db\system-db-beginNamedQueryTransaction.md). If blank, it will not be part of a transaction. [optional]
Boolean | `getKey` | Only used for Update Query types. A flag indicating whether or not the result should be the number of rows affected (getKey=0) or the newly generated key value that was created as a result of the update (getKey=1). Not all databases support automatic retrieval of generated keys. [optional]

### Returns
**PyDataset** -  The results of the Named Query as a [PyDataset](platform\scripting\python-scripting\variables-datatypes-and-objects\datasets.md#accessing-data-in-a-pydataset).

**Any** - Prior to 8.1.29, the exact object returned depends on the Query Type property of the Named Query. Query Types are selected on the Authoring Tab of a Named Query, and typically return the following: 
* Query: A dataset
* Scalar Query: An integer representing the number of rows affected  
* Update Query: An object matching the data type of the value returned

### Scope
Vision Client, Perspective Session

## Gateway Scope Syntax

`system.db.runNamedQuery(project, path,  [parameters], [tx], [getKey])`

### Parameters
Type | Parameter | Description 
------- | ------- | -----
String| `project` | The project name the query exists in.
String| `path` | The path to the Named Query to run. Note that this is the full path to the query, including any folders.
Dictionary[String, Any]| `parameters` | A Python dictionary of parameters for the Named Query to use. [optional]
String| `tx` | An optional transaction ID, obtained from [beginNamedQueryTransaction](appendix\scripting-functions\system-db\system-db-beginNamedQueryTransaction.md). If blank, will not be part of a transaction. [optional]
Boolean| `getKey` | Only used for Update Query types. A flag indicating whether or not the result should be the number of rows affected (getKey=0) or the newly generated key value that was created as a result of the update (getKey=1). Not all databases support automatic retrieval of generated keys. [optional]

### Returns
**Any** - The results of the query. The exact object returned depends on the Query Type property of the Named Query. Query Types are selected on the Authoring Tab of a Named Query, and typically return the following: 
* Query: A dataset
* Scalar Query: An integer representing the number of rows affected  
* Update Query: An object matching the data type of the value returned

### Scope
Gateway

## Code Examples

```python title="Example #1 Project Scope - Without Parameters"
# This example runs a Named Query without any parameters in the Project scope.
 
# Request the Named Query to execute.
system.db.runNamedQuery("folderName/myNamedQuery")
```

```python title="Example #2 Project Scope - With Parameters"
# This example runs a Named Query while passing some parameters in the Project scope.
# The Named Query is assumed to have two parameters already defined on the Named Query:
# param1 : A string
# param2 : An integer
 
# Create a Python dictionary of parameters to pass.
parameters  = {"param1":"my string", "param2":10}
  
# Run the Named Query.
system.db.runNamedQuery("myUpdateQuery", parameters)
```

```python title="Example #3 Gateway Scope"
# This example runs a Named Query without any parameters in the Gateway scope.
 
# Request the Named Query to execute.
system.db.runNamedQuery("ProjectName", "folderName/myNamedQuery")
```