---
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.

## Client Permission Restrictions

This scripting function has no Client Permission 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`. 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: typically either a dataset when set to **Query**, an integer representing the number of rows affected when set to **Update Query**, or an object matching the data type of the value returned by a **Scalar Query**.

**PyDataset** - The results of the Named Query as a PyDataset.

### 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`. 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: typically either a dataset when set to **Query**, an integer representing the number of rows affected when set to **Update Query**, or an object matching the data type of the value returned by a **Scalar Query**.

### Scope
Gateway

## Code Examples

```python title="Simple Example - 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="Gateway Scope Example"
# 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")
```

```python title="Simple Example - 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)
```