execute_scalar_async

execute_scalar_async executes the query, and returns the first column of the first row in the result set returned by the query. The additional columns or rows are ignored.

Parameters

All command methods also accept keyword-only options=; see Command options.

name	type	description	optional	default
sql	str	the sql query str to execute
params	ParamType	params to substitute in the query		None

param= remains accepted as a 1.x compatibility alias for params=. Pass only one of the two names.

Parameter Shapes

params accepts one parameter record: a mapping, mapping subclass, mutable mapping, or object/dataclass with attributes matching the placeholder names. Top-level list params are only for execute and execute_async; read and scalar methods raise InvalidParameterShapeException for top-level lists before opening a cursor.

params=None, param=None, or omitting both names means there is no parameter object. If the SQL contains pydapper placeholders such as ?id?, every referenced placeholder must be supplied or pydapper raises MissingParameterException before calling the DBAPI. An empty mapping is a real parameter record with no keys. A list inside one parameter record, such as {"ids": []} or {"ids": [1, 2, 3]}, is one value and is reserved for future IN list expansion support.

Cardinality

• 0 rows: raises NoResultException.
• 1+ rows: returns the first column of the first row.
• SQL NULL in the first column is returned as Python None.

Example

Get the name of the first task owner in the database.

import asyncio

from pydapper import connect_async


async def main():
    async with connect_async() as commands:
        owner_name = await commands.execute_scalar_async("select name from owner")

    print(owner_name)
    # Zach Schumacher


asyncio.run(main())

(This script is complete, it should run "as is")