Skip to content

execute_scalar

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

Tuple-query APIs (query_multiple and query_multiple_async) apply this validation to the complete tuple: the placeholders of every query are scanned and every referenced value is resolved before a cursor is acquired or the first query executes, so a missing parameter in any query means no query reaches the database. This is client-side prevalidation, not transaction atomicity; after validation succeeds, a later query can still fail at runtime after earlier queries have executed.

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.

from pydapper import connect

with connect() as commands:
    owner_name = commands.execute_scalar("select name from owner")

print(owner_name)
# Zach Schumacher
(This script is complete, it should run "as is")