---
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 runPrepQuery 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
```