Функция bindparam

Функция bindparam создает объект именованного параметра, который подставляется в SQL-выражение. Первым параметром функция принимает имя параметра. Вторым необязательным параметром передается значение. Также можно указать тип через параметр type_ и дополнительные опции через value и required.

Синтаксис

bindparam(key, [value], [type_], [unique])

Пример

Давайте создадим простой параметр и подставим его в SQL-выражение:

from sqlalchemy import bindparam, text

stmt = text('SELECT :name AS result').bindparams(
	bindparam('name', value='article')
)

print(stmt)

Результат выполнения кода:

"SELECT :name AS result"

Пример

Давайте выполним запрос с параметром через соединение с базой данных:

from sqlalchemy import create_engine, bindparam, text

engine = create_engine('sqlite:///:memory:')

stmt = text('SELECT :title AS result').bindparams(
	bindparam('title', value='article')
)

with engine.connect() as conn:
	res = conn.execute(stmt)
	print(res.fetchone())

Результат выполнения кода:

('article',)

Пример

Давайте передадим значение параметра во время выполнения запроса, а не при создании:

from sqlalchemy import create_engine, bindparam, text

engine = create_engine('sqlite:///:memory:')

stmt = text('SELECT :status AS result').bindparams(
	bindparam('status')
)

with engine.connect() as conn:
	res = conn.execute(stmt, {'status': 'published'})
	print(res.fetchone())

Результат выполнения кода:

('published',)

Пример

Давайте укажем тип параметра через параметр type_:

from sqlalchemy import bindparam, text, Integer

stmt = text('SELECT :num AS result').bindparams(
	bindparam('num', value=10, type_=Integer)
)

print(stmt)

Результат выполнения кода:

"SELECT :num AS result"

Пример

Давайте используем bindparam вместе с функцией insert для вставки данных в таблицу:

from sqlalchemy import (
	create_engine, MetaData, Table, Column,
	Integer, String, insert, bindparam
)

engine = create_engine('sqlite:///:memory:')
metadata = MetaData()

articles = Table(
	'articles', metadata,
	Column('id', Integer, primary_key=True),
	Column('title', String),
	Column('status', String)
)

metadata.create_all(engine)

stmt = insert(articles).values(
	title=bindparam('title'),
	status=bindparam('status')
)

with engine.connect() as conn:
	conn.execute(stmt, [
		{'title': 'article 1', 'status': 'published'},
		{'title': 'article 2', 'status': 'draft'}
	])
	conn.commit()
	
	res = conn.execute(articles.select())
	print(res.fetchall())

Результат выполнения кода:

[(1, 'article 1', 'published'), (2, 'article 2', 'draft')]

Пример

Давайте расширим один параметр на список значений с помощью метода expanding:

from sqlalchemy import create_engine, bindparam, text

engine = create_engine('sqlite:///:memory:')

stmt = text('SELECT title FROM articles WHERE status IN :statuses').bindparams(
	bindparam('statuses', expanding=True)
)

with engine.connect() as conn:
	conn.execute(text('CREATE TABLE articles (id INTEGER, title TEXT, status TEXT)'))
	conn.execute(text("INSERT INTO articles VALUES (1, 'article 1', 'published')"))
	conn.execute(text("INSERT INTO articles VALUES (2, 'article 2', 'draft')"))
	conn.execute(text("INSERT INTO articles VALUES (3, 'article 3', 'published')"))
	conn.commit()
	
	res = conn.execute(stmt, {'statuses': ['published', 'draft']})
	print(res.fetchall())

Результат выполнения кода:

[('article 1',), ('article 2',), ('article 3',)]

Итоговый SQL запрос:

SELECT title FROM articles WHERE status IN (?, ?)

Смотрите также

функцию text,
которая создает текстовый SQL-запрос
функцию literal,
которая подставляет значение прямо в SQL
функцию literal_column,
которая создает литеральное выражение колонки
функцию type_coerce,
которая приводит выражение к заданному типу