---
title: "system.db.runScalarPrepQuery"
description: "Runs a prepared statement against a database connection just like the runPrepQuery function, but only returns the value from the first row and column."
---

# system.db.runScalarPrepQuery

> Runs a prepared statement against a database connection just like the runPrepQuery function, but only returns the value from the first row and column.

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

## Description

Runs a prepared statement against a database connection just like the [`system.db.runPrepQuery`](appendix\scripting-functions\system-db\system-db-runPrepUpdate.md) function, but only returns the value from the first row and column. If no results are returned from the query, the special value None is returned.

## Client Permission Restrictions

[Permission Type](ignition-modules\vision\vision-project-properties\vision-project-properties.md#vision-permissions-properties): Legacy Database Access

Client access to this scripting function is blocked to users that do not meet the role/zone requirements for the above permission type. This function is unaffected when run in the Gateway scope.

## Syntax - Gateway

`system.db.runScalarPrepQuery(query, args, database, [tx])`

### Parameters
Type | Parameter | Description 
------- | ------- | -----
String| `query` | A SQL query (typically a SELECT) to run as a prepared statement with placeholders (?) denoting where the arguments go, that should be designed to return one row and one column.
List[Any]| `args` | A list of arguments. Will be used in order to match each placeholder (?) found in the query.
String| `database` | The name of the database connection to execute against.
 String| `tx` | A transaction identifier. If omitted, the query will be executed in its own transaction. [optional]

### Returns
**Any** - The value from the first row and first column of the results. Returns None if no rows were returned.

### Scope
Gateway

## Syntax - Vision and Perspective

`system.db.runScalarPrepQuery(query, args, [database], [tx])`

### Parameters
Type | Parameter | Description 
------- | ------- | -----
String| `query` | A SQL query (typically a SELECT) to run as a prepared statement with placeholders (?) denoting where the arguments go, that should be designed to return one row and one column.
List[Any]| `args` | A list of arguments. Will be used in order to match each placeholder (?) found in the query.
String| `database` | The name of the database connection to execute against. If omitted or "", the project's default database connection will be used. [optional]
 String| `tx` | A transaction identifier. If omitted, the query will be executed in its own transaction. [optional]

### Returns
**Any** - The value from the first row and first column of the results. Returns None if no rows were returned.

### Scope
Vision Client, Perspective Session

## Code Examples

```python title="Code Snippet - Executing Query"
# This example searches for the user id of someone based on a typed in username.
name = event.source.parent.getComponent("User Search").text
 
result = system.db.runScalarPrepQuery("SELECT user_id FROM users WHERE username = ?", [name])
event.source.parent.getComponent("Text Field").data = result
```