Вставка, обновление, удаление¶

Основополагающие конструкторы DML¶

Конструкторы верхнего уровня «INSERT», «UPDATE», «DELETE».

function sqlalchemy.sql.expression.delete(table: _DMLTableArgument) → Delete¶

Постройте объект Delete.

Например:

from sqlalchemy import delete

stmt = (
    delete(user_table).
    where(user_table.c.id == 5)
)

Аналогичная функциональность доступна через метод TableClause.delete() на Table.

Параметры:

table – Таблица, из которой нужно удалить строки.

См.также

Использование операторов UPDATE и DELETE - в Унифицированный учебник по SQLAlchemy

function sqlalchemy.sql.expression.insert(table: _DMLTableArgument) → Insert¶

Создайте объект Insert.

Например:

from sqlalchemy import insert

stmt = (
    insert(user_table).
    values(name='username', fullname='Full Username')
)

Аналогичная функциональность доступна через метод TableClause.insert() на Table.

См.также

Использование операторов INSERT - в Унифицированный учебник по SQLAlchemy

Параметры:

• table – TableClause, который является предметом вставки.

• values – коллекция значений для вставки; описание допустимых форматов см. в Insert.values(). Может быть опущен полностью; конструкция Insert также будет динамически отображать предложение VALUES во время выполнения на основе параметров, переданных в Connection.execute().

• inline – если True, то не будет предприниматься попытка получить значения по умолчанию, генерируемые SQL, которые должны быть предоставлены в операторе; в частности, это позволяет отображать SQL-выражения «в линию» в операторе без необходимости их предварительного выполнения; для бэкендов, поддерживающих «возврат», это отключает функцию «неявного возврата» для оператора.

Если присутствуют и insert.values, и параметры привязки времени компиляции, параметры привязки времени компиляции переопределяют информацию, указанную в insert.values на основе каждого ключа.

Ключи в Insert.values могут быть либо объектами Column, либо их строковыми идентификаторами. Каждый ключ может ссылаться на один из:

• буквальное значение данных (т.е. строка, число и т.д.);

• объект Column;

• оператор SELECT.

Если указан оператор SELECT, который ссылается на таблицу этого оператора INSERT, то этот оператор будет соотнесен с оператором INSERT.

См.также

Использование операторов INSERT - в Унифицированный учебник по SQLAlchemy

function sqlalchemy.sql.expression.update(table: _DMLTableArgument) → Update¶

Создайте объект Update.

Например:

from sqlalchemy import update

stmt = (
    update(user_table).
    where(user_table.c.id == 5).
    values(name='user #5')
)

Аналогичная функциональность доступна через метод TableClause.update() на Table.

Параметры:

table – Объект Table, представляющий обновляемую таблицу базы данных.

См.также

Использование операторов UPDATE и DELETE - в Унифицированный учебник по SQLAlchemy

Документация класса DML Конструкторы¶

Документация класса для конструкторов, перечисленных в Основополагающие конструкторы DML.

class sqlalchemy.sql.expression.Delete¶

Представляет собой конструкцию DELETE.

Объект Delete создается с помощью функции delete().

Members

where(), returning()

Классная подпись

класс sqlalchemy.sql.expression.Delete (sqlalchemy.sql.expression.DMLWhereBase, sqlalchemy.sql.expression.UpdateBase)

method sqlalchemy.sql.expression.Delete.where(*whereclause: _ColumnExpressionArgument[bool]) → Self¶

наследуется от DMLWhereBase.where() метода DMLWhereBase

Возвращает новую конструкцию с заданным выражением (выражениями), добавленным к пункту WHERE, присоединенным к существующему пункту через AND, если таковой имеется.

И Update.where(), и Delete.where() поддерживают формы с несколькими таблицами, включая специфические для базы данных UPDATE...FROM, а также DELETE..USING. Для бэкендов, не имеющих поддержки множественных таблиц, независимый от бэкенда подход к использованию множественных таблиц заключается в использовании коррелированных подзапросов. Примеры приведены в разделах учебника по ссылкам ниже.

См.также

Корреляционные обновления

UPDATE…FROM

Удаление нескольких таблиц

method sqlalchemy.sql.expression.Delete.returning(*cols: _ColumnsClauseArgument[Any], sort_by_parameter_order: bool = False, **_UpdateBase__kw: Any) → UpdateBase¶

наследуется от UpdateBase.returning() метода UpdateBase

Добавьте к этому утверждению предложение RETURNING или эквивалентное ему предложение.

например:

>>> stmt = (
...     table.update()
...     .where(table.c.data == "value")
...     .values(status="X")
...     .returning(table.c.server_flag, table.c.updated_timestamp)
... )
>>> print(stmt)
{printsql}UPDATE some_table SET status=:status
WHERE some_table.data = :data_1
RETURNING some_table.server_flag, some_table.updated_timestamp

Метод может быть вызван несколько раз для добавления новых записей в список возвращаемых выражений.

Добавлено в версии 1.4.0b2: Метод может быть вызван несколько раз для добавления новых записей в список возвращаемых выражений.

Заданная коллекция выражений столбцов должна быть получена из таблицы, которая является целью INSERT, UPDATE или DELETE. Хотя типичными являются объекты Column, элементы также могут быть выражениями:

>>> stmt = table.insert().returning(
...     (table.c.first_name + " " + table.c.last_name).label("fullname")
... )
>>> print(stmt)
{printsql}INSERT INTO some_table (first_name, last_name)
VALUES (:first_name, :last_name)
RETURNING some_table.first_name || :first_name_1 || some_table.last_name AS fullname

После компиляции в операторе будет отображено предложение RETURNING или его эквивалент в базе данных. Для INSERT и UPDATE значениями являются новые вставленные/обновленные значения. Для DELETE значениями являются значения строк, которые были удалены.

После выполнения, значения возвращаемых столбцов становятся доступными через набор результатов и могут быть итерированы с помощью CursorResult.fetchone() и т.п. Для DBAPI, которые не поддерживают возврат значений (например, cx_oracle), SQLAlchemy будет аппроксимировать это поведение на уровне результатов, чтобы обеспечить разумную поведенческую нейтральность.

Обратите внимание, что не все базы данных/DBAPI поддерживают RETURNING. Для тех бэкендов, которые его не поддерживают, при компиляции и/или выполнении возникает исключение. Для тех, кто его поддерживает, функциональность бэкендов сильно различается, включая ограничения на выполнение executemany() и других операторов, возвращающих несколько строк. Чтобы определить наличие RETURNING, ознакомьтесь с документацией по используемой базе данных.

Параметры:

• *cols – ряд столбцов, SQL-выражений или целых таблиц, которые должны быть возвращены.

• sort_by_parameter_order – для пакетного INSERT, выполняемого по нескольким наборам параметров, упорядочить результаты RETURNING так, чтобы возвращаемые строки соответствовали порядку переданных наборов параметров. Это применимо только к выполнению executemany для поддерживающих диалектов и обычно использует функцию insertmanyvalues. … версия добавлена:: 2.0.10 .. seealso:: Соотнесение строк RETURNING с наборами параметров - история сортировки строк RETURNING для массового INSERT (обсуждение на уровне ядра) Соотнесение записей о возврате с порядком входных данных - пример использования с ORM Bulk INSERT Statements (обсуждение на уровне ORM)

См.также

UpdateBase.return_defaults() - альтернативный метод, предназначенный для эффективной выборки значений по умолчанию на стороне сервера и триггеров для однорядных INSERT или UPDATE.

ВСТАВКА… ВОЗВРАТ - в Унифицированный учебник по SQLAlchemy

class sqlalchemy.sql.expression.Insert¶

Представляет собой конструкцию INSERT.

Объект Insert создается с помощью функции insert().

Members

values(), returning(), from_select(), inline(), select

Классная подпись

класс sqlalchemy.sql.expression.Insert (sqlalchemy.sql.expression.ValuesBase)

method sqlalchemy.sql.expression.Insert.values(*args: Union[_DMLColumnKeyMapping[Any], Sequence[Any]], **kwargs: Any) → Self¶

наследуется от ValuesBase.values() метода ValuesBase

Укажите фиксированное предложение VALUES для оператора INSERT или предложение SET для UPDATE.

Обратите внимание, что конструкции Insert и Update поддерживают форматирование клаузул VALUES и/или SET по времени выполнения на основе аргументов, переданных в Connection.execute(). Однако метод ValuesBase.values() может быть использован для «фиксации» определенного набора параметров в операторе.

При многократном вызове ValuesBase.values() будет создаваться новая конструкция, в каждой из которых список параметров будет изменен, чтобы включить новые переданные параметры. В типичном случае с одним словарем параметров, вновь переданные ключи заменяют те же самые ключи в предыдущей конструкции. В случае конструкции «множество значений», основанной на списке, каждый новый список значений расширяется на существующий список значений.

Параметры:

• **kwargs – пары ключ-значение, представляющие строковый ключ Column, сопоставленный со значением, которое должно быть выведено в предложение VALUES или SET:: users.insert().values(name=»some name») users.update().where(users.c.id==5).values(name=»some name»)

• *args – В качестве альтернативы передаче параметров ключ/значение, словарь, кортеж или список словарей или кортежей может быть передан в качестве единственного позиционного аргумента для формирования предложения VALUES или SET оператора. Принимаемые формы зависят от того, является ли это конструкцией Insert или Update. Для конструкции Insert или Update можно передать один словарь, который работает так же, как и форма kwargs:: users.insert().values({«name»: «some name»}) users.update().values({«name»: «some new name»}) Также для любой формы, но более типично для конструкции Insert, принимается кортеж, содержащий запись для каждого столбца таблицы:: users. insert().values((5, «some name»)) Конструкция Insert также поддерживает передачу списка словарей или кортежей полной таблицы, которые на сервере будут иметь менее распространенный синтаксис SQL «multiple values» - этот синтаксис поддерживается такими бэкендами, как SQLite, PostgreSQL, MySQL, но не обязательно другими:: users.insert().values([ {«name»: «какое-то имя»}, { {«имя»: «какое-то другое имя»}, {«имя»: «еще одно имя»}, ]) Приведенная выше форма выведет множественный оператор VALUES, подобный следующему:: INSERT INTO users (name) VALUES (:name_1), (:name_2), (:name_3) Важно отметить, что передача множественных значений - это НЕ то же самое, что использование традиционной формы executemany(). Приведенный выше синтаксис является специальным синтаксисом, который обычно не используется. Чтобы выполнить оператор INSERT для нескольких строк, обычным методом является передача списка из нескольких значений в метод Connection.execute(), который поддерживается всеми бэкендами баз данных и обычно более эффективен для очень большого количества параметров. … см. также:: Отправка нескольких параметров - введение в традиционный метод Core вызова множественного набора параметров для INSERT’ов и других операторов. Конструкция UPDATE также поддерживает вывод параметров SET в определенном порядке. Для этой возможности обратитесь к методу Update.ordered_values(). … см. также:: Update.ordered_values()

method sqlalchemy.sql.expression.Insert.returning(*cols: _ColumnsClauseArgument[Any], sort_by_parameter_order: bool = False, **_UpdateBase__kw: Any) → UpdateBase¶

наследуется от UpdateBase.returning() метода UpdateBase

Добавьте к этому утверждению предложение RETURNING или эквивалентное ему предложение.

например:

>>> stmt = (
...     table.update()
...     .where(table.c.data == "value")
...     .values(status="X")
...     .returning(table.c.server_flag, table.c.updated_timestamp)
... )
>>> print(stmt)
{printsql}UPDATE some_table SET status=:status
WHERE some_table.data = :data_1
RETURNING some_table.server_flag, some_table.updated_timestamp

Метод может быть вызван несколько раз для добавления новых записей в список возвращаемых выражений.

Добавлено в версии 1.4.0b2: Метод может быть вызван несколько раз для добавления новых записей в список возвращаемых выражений.

Заданная коллекция выражений столбцов должна быть получена из таблицы, которая является целью INSERT, UPDATE или DELETE. Хотя типичными являются объекты Column, элементы также могут быть выражениями:

>>> stmt = table.insert().returning(
...     (table.c.first_name + " " + table.c.last_name).label("fullname")
... )
>>> print(stmt)
{printsql}INSERT INTO some_table (first_name, last_name)
VALUES (:first_name, :last_name)
RETURNING some_table.first_name || :first_name_1 || some_table.last_name AS fullname

После компиляции в операторе будет отображено предложение RETURNING или его эквивалент в базе данных. Для INSERT и UPDATE значениями являются новые вставленные/обновленные значения. Для DELETE значениями являются значения строк, которые были удалены.

После выполнения, значения возвращаемых столбцов становятся доступными через набор результатов и могут быть итерированы с помощью CursorResult.fetchone() и т.п. Для DBAPI, которые не поддерживают возврат значений (например, cx_oracle), SQLAlchemy будет аппроксимировать это поведение на уровне результатов, чтобы обеспечить разумную поведенческую нейтральность.

Обратите внимание, что не все базы данных/DBAPI поддерживают RETURNING. Для тех бэкендов, которые его не поддерживают, при компиляции и/или выполнении возникает исключение. Для тех, кто его поддерживает, функциональность бэкендов сильно различается, включая ограничения на выполнение executemany() и других операторов, возвращающих несколько строк. Чтобы определить наличие RETURNING, ознакомьтесь с документацией по используемой базе данных.

Параметры:

• *cols – ряд столбцов, SQL-выражений или целых таблиц, которые должны быть возвращены.

• sort_by_parameter_order – для пакетного INSERT, выполняемого по нескольким наборам параметров, упорядочить результаты RETURNING так, чтобы возвращаемые строки соответствовали порядку переданных наборов параметров. Это применимо только к выполнению executemany для поддерживающих диалектов и обычно использует функцию insertmanyvalues. … версия добавлена:: 2.0.10 .. seealso:: Соотнесение строк RETURNING с наборами параметров - история сортировки строк RETURNING для массового INSERT (обсуждение на уровне ядра) Соотнесение записей о возврате с порядком входных данных - пример использования с ORM Bulk INSERT Statements (обсуждение на уровне ORM)

См.также

UpdateBase.return_defaults() - альтернативный метод, предназначенный для эффективной выборки значений по умолчанию на стороне сервера и триггеров для однорядных INSERT или UPDATE.

ВСТАВКА… ВОЗВРАТ - в Унифицированный учебник по SQLAlchemy

method sqlalchemy.sql.expression.Insert.from_select(names: Sequence[_DMLColumnArgument], select: Selectable, include_defaults: bool = True) → Self¶

Возвращает новую конструкцию Insert, которая представляет оператор INSERT...FROM SELECT.

например:

sel = select(table1.c.a, table1.c.b).where(table1.c.c > 5)
ins = table2.insert().from_select(['a', 'b'], sel)

Параметры:

• names – последовательность строковых имен столбцов или объектов Column, представляющих целевые столбцы.

• select – конструкция select(), FromClause или другая конструкция, переходящая в FromClause, например, объект ORM Query и т.д. Порядок колонок, возвращаемых из этого предложения FROM, должен соответствовать порядку колонок, переданных в качестве параметра names; хотя это не проверяется перед передачей в базу данных, база данных обычно вызывает исключение, если эти списки колонок не соответствуют друг другу.

• include_defaults – если True, несерверные значения по умолчанию и SQL-выражения, указанные на объектах Column (как документировано в Колонки INSERT/UPDATE по умолчанию), не указанные в списке имен, будут отображены в операторы INSERT и SELECT, так что эти значения также будут включены в вставляемые данные. … примечание:: Умолчание на стороне Python, использующее вызываемую функцию Python, будет вызвано только один раз для всего оператора, а не для каждой строки.

method sqlalchemy.sql.expression.Insert.inline() → Self¶

Сделайте эту конструкцию Insert «встроенной» .

Если установлено, не будет предприниматься попытка получить значения по умолчанию, генерируемые SQL, которые должны быть предоставлены в операторе; в частности, это позволяет отображать SQL-выражения «в линию» в операторе без необходимости их предварительного выполнения; для бэкендов, поддерживающих «возврат», это отключает функцию «неявного возврата» для оператора.

Изменено в версии 1.4: параметр Insert.inline теперь заменен методом Insert.inline().

attribute sqlalchemy.sql.expression.Insert.select: Optional[Select[Any]] = None¶

Оператор SELECT для INSERT … FROM SELECT

class sqlalchemy.sql.expression.Update¶

Представляет собой конструкцию Update.

Объект Update создается с помощью функции update().

Members

returning(), where(), values(), inline(), ordered_values()

Классная подпись

класс sqlalchemy.sql.expression.Update (sqlalchemy.sql.expression.DMLWhereBase, sqlalchemy.sql.expression.ValuesBase)

method sqlalchemy.sql.expression.Update.returning(*cols: _ColumnsClauseArgument[Any], sort_by_parameter_order: bool = False, **_UpdateBase__kw: Any) → UpdateBase¶

наследуется от UpdateBase.returning() метода UpdateBase

Добавьте к этому утверждению предложение RETURNING или эквивалентное ему предложение.

например:

>>> stmt = (
...     table.update()
...     .where(table.c.data == "value")
...     .values(status="X")
...     .returning(table.c.server_flag, table.c.updated_timestamp)
... )
>>> print(stmt)
{printsql}UPDATE some_table SET status=:status
WHERE some_table.data = :data_1
RETURNING some_table.server_flag, some_table.updated_timestamp

Метод может быть вызван несколько раз для добавления новых записей в список возвращаемых выражений.

Добавлено в версии 1.4.0b2: Метод может быть вызван несколько раз для добавления новых записей в список возвращаемых выражений.

Заданная коллекция выражений столбцов должна быть получена из таблицы, которая является целью INSERT, UPDATE или DELETE. Хотя типичными являются объекты Column, элементы также могут быть выражениями:

>>> stmt = table.insert().returning(
...     (table.c.first_name + " " + table.c.last_name).label("fullname")
... )
>>> print(stmt)
{printsql}INSERT INTO some_table (first_name, last_name)
VALUES (:first_name, :last_name)
RETURNING some_table.first_name || :first_name_1 || some_table.last_name AS fullname

После компиляции в операторе будет отображено предложение RETURNING или его эквивалент в базе данных. Для INSERT и UPDATE значениями являются новые вставленные/обновленные значения. Для DELETE значениями являются значения строк, которые были удалены.

После выполнения, значения возвращаемых столбцов становятся доступными через набор результатов и могут быть итерированы с помощью CursorResult.fetchone() и т.п. Для DBAPI, которые не поддерживают возврат значений (например, cx_oracle), SQLAlchemy будет аппроксимировать это поведение на уровне результатов, чтобы обеспечить разумную поведенческую нейтральность.

Обратите внимание, что не все базы данных/DBAPI поддерживают RETURNING. Для тех бэкендов, которые его не поддерживают, при компиляции и/или выполнении возникает исключение. Для тех, кто его поддерживает, функциональность бэкендов сильно различается, включая ограничения на выполнение executemany() и других операторов, возвращающих несколько строк. Чтобы определить наличие RETURNING, ознакомьтесь с документацией по используемой базе данных.

Параметры:

• *cols – ряд столбцов, SQL-выражений или целых таблиц, которые должны быть возвращены.

• sort_by_parameter_order – для пакетного INSERT, выполняемого по нескольким наборам параметров, упорядочить результаты RETURNING так, чтобы возвращаемые строки соответствовали порядку переданных наборов параметров. Это применимо только к выполнению executemany для поддерживающих диалектов и обычно использует функцию insertmanyvalues. … версия добавлена:: 2.0.10 .. seealso:: Соотнесение строк RETURNING с наборами параметров - история сортировки строк RETURNING для массового INSERT (обсуждение на уровне ядра) Соотнесение записей о возврате с порядком входных данных - пример использования с ORM Bulk INSERT Statements (обсуждение на уровне ORM)

См.также

UpdateBase.return_defaults() - альтернативный метод, предназначенный для эффективной выборки значений по умолчанию на стороне сервера и триггеров для однорядных INSERT или UPDATE.

ВСТАВКА… ВОЗВРАТ - в Унифицированный учебник по SQLAlchemy

method sqlalchemy.sql.expression.Update.where(*whereclause: _ColumnExpressionArgument[bool]) → Self¶

наследуется от DMLWhereBase.where() метода DMLWhereBase

Возвращает новую конструкцию с заданным выражением (выражениями), добавленным к пункту WHERE, присоединенным к существующему пункту через AND, если таковой имеется.

И Update.where(), и Delete.where() поддерживают формы с несколькими таблицами, включая специфические для базы данных UPDATE...FROM, а также DELETE..USING. Для бэкендов, не имеющих поддержки множественных таблиц, независимый от бэкенда подход к использованию множественных таблиц заключается в использовании коррелированных подзапросов. Примеры приведены в разделах учебника по ссылкам ниже.

См.также

Корреляционные обновления

UPDATE…FROM

Удаление нескольких таблиц

method sqlalchemy.sql.expression.Update.values(*args: Union[_DMLColumnKeyMapping[Any], Sequence[Any]], **kwargs: Any) → Self¶

наследуется от ValuesBase.values() метода ValuesBase

Укажите фиксированное предложение VALUES для оператора INSERT или предложение SET для UPDATE.

Обратите внимание, что конструкции Insert и Update поддерживают форматирование клаузул VALUES и/или SET по времени выполнения на основе аргументов, переданных в Connection.execute(). Однако метод ValuesBase.values() может быть использован для «фиксации» определенного набора параметров в операторе.

При многократном вызове ValuesBase.values() будет создаваться новая конструкция, в каждой из которых список параметров будет изменен, чтобы включить новые переданные параметры. В типичном случае с одним словарем параметров, вновь переданные ключи заменяют те же самые ключи в предыдущей конструкции. В случае конструкции «множество значений», основанной на списке, каждый новый список значений расширяется на существующий список значений.

Параметры:

• **kwargs – пары ключ-значение, представляющие строковый ключ Column, сопоставленный со значением, которое должно быть выведено в предложение VALUES или SET:: users.insert().values(name=»some name») users.update().where(users.c.id==5).values(name=»some name»)

• *args – В качестве альтернативы передаче параметров ключ/значение, словарь, кортеж или список словарей или кортежей может быть передан в качестве единственного позиционного аргумента для формирования предложения VALUES или SET оператора. Принимаемые формы зависят от того, является ли это конструкцией Insert или Update. Для конструкции Insert или Update можно передать один словарь, который работает так же, как и форма kwargs:: users.insert().values({«name»: «some name»}) users.update().values({«name»: «some new name»}) Также для любой формы, но более типично для конструкции Insert, принимается кортеж, содержащий запись для каждого столбца таблицы:: users. insert().values((5, «some name»)) Конструкция Insert также поддерживает передачу списка словарей или кортежей полной таблицы, которые на сервере будут иметь менее распространенный синтаксис SQL «multiple values» - этот синтаксис поддерживается такими бэкендами, как SQLite, PostgreSQL, MySQL, но не обязательно другими:: users.insert().values([ {«name»: «какое-то имя»}, { {«имя»: «какое-то другое имя»}, {«имя»: «еще одно имя»}, ]) Приведенная выше форма выведет множественный оператор VALUES, подобный следующему:: INSERT INTO users (name) VALUES (:name_1), (:name_2), (:name_3) Важно отметить, что передача множественных значений - это НЕ то же самое, что использование традиционной формы executemany(). Приведенный выше синтаксис является специальным синтаксисом, который обычно не используется. Чтобы выполнить оператор INSERT для нескольких строк, обычным методом является передача списка из нескольких значений в метод Connection.execute(), который поддерживается всеми бэкендами баз данных и обычно более эффективен для очень большого количества параметров. … см. также:: Отправка нескольких параметров - введение в традиционный метод Core вызова множественного набора параметров для INSERT’ов и других операторов. Конструкция UPDATE также поддерживает вывод параметров SET в определенном порядке. Для этой возможности обратитесь к методу Update.ordered_values(). … см. также:: Update.ordered_values()

method sqlalchemy.sql.expression.Update.inline() → Self¶

Сделайте эту конструкцию Update «встроенной» .

Если установлено, то значения по умолчанию SQL, присутствующие в объектах Column через ключевое слово default, будут компилироваться «inline» в оператор и не будут предварительно выполняться. Это означает, что их значения не будут доступны в словаре, возвращаемом из CursorResult.last_updated_params().

Изменено в версии 1.4: параметр update.inline теперь заменен методом Update.inline().

method sqlalchemy.sql.expression.Update.ordered_values(*args: Tuple[_DMLColumnArgument, Any]) → Self¶

Укажите в пункте VALUES этого оператора UPDATE явный порядок параметров, который будет сохранен в пункте SET результирующего оператора UPDATE.

Например:

stmt = table.update().ordered_values(
    ("name", "ed"), ("ident": "foo")
)

См.также

Упорядоченные по параметрам обновления - полный пример метода Update.ordered_values().

Изменено в версии 1.4: Метод Update.ordered_values() заменяет параметр update.preserve_parameter_order, который будет удален в SQLAlchemy 2.0.

class sqlalchemy.sql.expression.UpdateBase¶

Формируют основу для утверждений INSERT, UPDATE и DELETE.

Members

entity_description, exported_columns, params(), return_defaults(), returning(), returning_column_descriptions, with_dialect_options(), with_hint()

Классная подпись

class sqlalchemy.sql.expression.UpdateBase (sqlalchemy.sql.roles.DMLRole, sqlalchemy.sql.expression.HasCTE, sqlalchemy.sql.expression.HasCompileState, sqlalchemy.sql.base.DialectKWArgs, sqlalchemy.sql.expression.HasPrefixes, sqlalchemy.sql.expression.Generative, sqlalchemy.sql.expression.ExecutableReturnsRows, sqlalchemy.sql.expression.ClauseElement)

attribute sqlalchemy.sql.expression.UpdateBase.entity_description¶

Возвращает plugin-enabled описание таблицы и/или сущности, с которой работает данная конструкция DML.

Этот атрибут обычно полезен при использовании ORM, так как возвращается расширенная структура, включающая информацию о сопоставленных сущностях. В разделе Проверка сущностей и столбцов из операторов SELECT и DML с поддержкой ORM содержится более подробная информация.

Для оператора Core структура, возвращаемая этим аксессором, является производной от атрибута UpdateBase.table и относится к вставляемому, обновляемому или удаляемому Table:

>>> stmt = insert(user_table)
>>> stmt.entity_description
{
    "name": "user_table",
    "table": Table("user_table", ...)
}

Добавлено в версии 1.4.33.

См.также

UpdateBase.returning_column_descriptions

Select.column_descriptions - информация об объекте для конструкции select()

Проверка сущностей и столбцов из операторов SELECT и DML с поддержкой ORM - фон ORM

attribute sqlalchemy.sql.expression.UpdateBase.exported_columns¶

Возвращает столбцы RETURNING как коллекцию столбцов для этого оператора.

Добавлено в версии 1.4.

method sqlalchemy.sql.expression.UpdateBase.params(*arg: Any, **kw: Any) → NoReturn¶

Установите параметры для утверждения.

Этот метод вызывает NotImplementedError на базовом классе, и переопределяется ValuesBase для обеспечения SET/VALUES clause UPDATE и INSERT.

method sqlalchemy.sql.expression.UpdateBase.return_defaults(*cols: _DMLColumnArgument, supplemental_cols: Optional[Iterable[_DMLColumnArgument]] = None, sort_by_parameter_order: bool = False) → Self¶

Используйте предложение RETURNING для получения выражений и значений по умолчанию на стороне сервера, только для поддерживающих бэкендов.

Deep Alchemy

Метод UpdateBase.return_defaults() используется ORM для своей внутренней работы по извлечению вновь созданных значений первичного ключа и значений по умолчанию сервера, в частности, для обеспечения реализации функции Mapper.eager_defaults ORM, а также для обеспечения поддержки RETURNING при массовых вставках ORM. Его поведение довольно идиосинкразично и не предназначено для общего использования. Конечным пользователям следует придерживаться использования UpdateBase.returning() для добавления условий RETURNING в свои операторы INSERT, UPDATE и DELETE.

Обычно при выполнении оператора INSERT одной строки автоматически заполняется атрибут CursorResult.inserted_primary_key, который хранит первичный ключ только что вставленной строки в виде объекта Row с именами столбцов в качестве именованных ключей кортежа (при этом представление Row._mapping также полностью заполняется). Используемый диалект выбирает стратегию, которую следует использовать для заполнения этих данных; если они были созданы с использованием значений по умолчанию на стороне сервера и/или выражений SQL, то для получения нового значения первичного ключа обычно используются такие специфические для диалекта подходы, как cursor.lastrowid или RETURNING.

Однако, когда утверждение модифицируется путем вызова UpdateBase.return_defaults() перед выполнением утверждения, дополнительное поведение имеет место только для бэкендов, поддерживающих RETURNING, и для объектов Table, которые поддерживают параметр Table.implicit_returning в значении по умолчанию True. В этих случаях, когда CursorResult возвращается после выполнения оператора, не только CursorResult.inserted_primary_key будет заполнен, как всегда, но и атрибут CursorResult.returned_defaults будет заполнен именованным кортежем Row, представляющим полный диапазон значений, сгенерированных сервером из этой единственной строки, включая значения для любых столбцов, в которых указано Column.server_default или которые используют Column.default с помощью выражения SQL.

При вызове операторов INSERT с несколькими строками с помощью insertmanyvalues, модификатор UpdateBase.return_defaults() будет иметь эффект того, что атрибуты CursorResult.inserted_primary_key_rows и CursorResult.returned_defaults_rows будут полностью заполнены списками объектов Row, представляющих вновь вставленные значения первичного ключа, а также вновь вставленные значения, сгенерированные сервером для каждой вставленной строки. Атрибуты CursorResult.inserted_primary_key и CursorResult.returned_defaults также будут продолжать заполняться первой строкой этих двух коллекций.

Если бэкенд не поддерживает RETURNING или используемый Table отключен Table.implicit_returning, то предложение RETURNING не добавляется и дополнительные данные не извлекаются, однако оператор INSERT, UPDATE или DELETE выполняется нормально.

Например:

stmt = table.insert().values(data='newdata').return_defaults()

result = connection.execute(stmt)

server_created_at = result.returned_defaults['created_at']

При использовании против оператора UPDATE UpdateBase.return_defaults() вместо этого ищет столбцы, которые включают Column.onupdate или Column.server_onupdate назначенные параметры, при построении столбцов, которые будут включены в предложение RETURNING по умолчанию, если явные столбцы не были указаны. При использовании против оператора DELETE никакие столбцы не включаются в RETURNING по умолчанию, вместо этого они должны быть указаны явно, поскольку нет столбцов, которые обычно изменяют значения при выполнении оператора DELETE.

Добавлено в версии 2.0: UpdateBase.return_defaults() поддерживается также для операторов DELETE и перенесен из ValuesBase в UpdateBase.

Метод UpdateBase.return_defaults() является взаимоисключающим по отношению к методу UpdateBase.returning(), и в процессе компиляции SQL будут возникать ошибки при одновременном использовании обоих методов в одном операторе. Поэтому пункт RETURNING оператора INSERT, UPDATE или DELETE одновременно управляется только одним из этих методов.

Метод UpdateBase.return_defaults() отличается от UpdateBase.returning() следующим образом:

1. Метод UpdateBase.return_defaults() вызывает заполнение коллекции CursorResult.returned_defaults первой строкой из результата RETURNING. Этот атрибут не заполняется при использовании UpdateBase.returning().

2. UpdateBase.return_defaults() совместимо с существующей логикой, используемой для получения автоматически генерируемых значений первичного ключа, которые затем заполняются в атрибут CursorResult.inserted_primary_key. Напротив, использование UpdateBase.returning() приведет к тому, что атрибут CursorResult.inserted_primary_key останется незаполненным.

3. UpdateBase.return_defaults() может быть вызвана против любого бэкенда. Бэкенды, которые не поддерживают RETURNING, пропустят использование функции, а не вызовут исключение. Возвращаемое значение CursorResult.returned_defaults будет None для бэкендов, которые не поддерживают RETURNING или для которых целевой Table устанавливает Table.implicit_returning в False.

4. Оператор INSERT, вызванный с помощью executemany(), поддерживается, если драйвер базы данных бэкенда поддерживает функцию insertmanyvalues, которая в настоящее время поддерживается большинством бэкендов, включенных в SQLAlchemy. При использовании executemany аксессоры CursorResult.returned_defaults_rows и CursorResult.inserted_primary_key_rows возвращают вставленные значения по умолчанию и первичные ключи.

   Добавлено в версии 1.4: Добавлены аксессоры CursorResult.returned_defaults_rows и CursorResult.inserted_primary_key_rows. В версии 2.0 базовая реализация, которая получает и заполняет данные для этих атрибутов, была обобщена и поддерживается большинством бэкендов, в то время как в версии 1.4 они поддерживались только драйвером psycopg2.

Параметры:

• cols – необязательный список имен ключей колонок или Column, который действует как фильтр для тех колонок, которые будут извлечены.

• supplemental_cols – необязательный список выражений RETURNING, в той же форме, в какой они передаются методу UpdateBase.returning(). Если дополнительные столбцы присутствуют, они будут включены в выражение RETURNING, а объект CursorResult будет «перемотан» при возврате, так что методы типа CursorResult.all() будут возвращать новые строки в основном так же, как если бы оператор использовал UpdateBase.returning() напрямую. Однако, в отличие от прямого использования UpdateBase.returning(), порядок столбцов не определен, поэтому их можно нацеливать только с помощью имен или ключей Row._mapping; они не могут быть надежно нацелены позиционно. … версия добавлена:: 2.0

• sort_by_parameter_order – для пакетного INSERT, выполняемого по нескольким наборам параметров, упорядочить результаты RETURNING так, чтобы возвращаемые строки соответствовали порядку переданных наборов параметров. Это применимо только к выполнению executemany для поддерживающих диалектов и обычно использует функцию insertmanyvalues. … версия добавлена:: 2.0.10 .. seealso:: Соотнесение строк RETURNING с наборами параметров - фон для сортировки возвращаемых строк для массового INSERT

См.также

UpdateBase.returning()

CursorResult.returned_defaults

CursorResult.returned_defaults_rows

CursorResult.inserted_primary_key

CursorResult.inserted_primary_key_rows

method sqlalchemy.sql.expression.UpdateBase.returning(*cols: _ColumnsClauseArgument[Any], sort_by_parameter_order: bool = False, **_UpdateBase__kw: Any) → UpdateBase¶

Добавьте к этому утверждению предложение RETURNING или эквивалентное ему предложение.

например:

>>> stmt = (
...     table.update()
...     .where(table.c.data == "value")
...     .values(status="X")
...     .returning(table.c.server_flag, table.c.updated_timestamp)
... )
>>> print(stmt)
{printsql}UPDATE some_table SET status=:status
WHERE some_table.data = :data_1
RETURNING some_table.server_flag, some_table.updated_timestamp

Метод может быть вызван несколько раз для добавления новых записей в список возвращаемых выражений.

Добавлено в версии 1.4.0b2: Метод может быть вызван несколько раз для добавления новых записей в список возвращаемых выражений.

Заданная коллекция выражений столбцов должна быть получена из таблицы, которая является целью INSERT, UPDATE или DELETE. Хотя типичными являются объекты Column, элементы также могут быть выражениями:

>>> stmt = table.insert().returning(
...     (table.c.first_name + " " + table.c.last_name).label("fullname")
... )
>>> print(stmt)
{printsql}INSERT INTO some_table (first_name, last_name)
VALUES (:first_name, :last_name)
RETURNING some_table.first_name || :first_name_1 || some_table.last_name AS fullname

После компиляции в операторе будет отображено предложение RETURNING или его эквивалент в базе данных. Для INSERT и UPDATE значениями являются новые вставленные/обновленные значения. Для DELETE значениями являются значения строк, которые были удалены.

После выполнения, значения возвращаемых столбцов становятся доступными через набор результатов и могут быть итерированы с помощью CursorResult.fetchone() и т.п. Для DBAPI, которые не поддерживают возврат значений (например, cx_oracle), SQLAlchemy будет аппроксимировать это поведение на уровне результатов, чтобы обеспечить разумную поведенческую нейтральность.

Обратите внимание, что не все базы данных/DBAPI поддерживают RETURNING. Для тех бэкендов, которые его не поддерживают, при компиляции и/или выполнении возникает исключение. Для тех, кто его поддерживает, функциональность бэкендов сильно различается, включая ограничения на выполнение executemany() и других операторов, возвращающих несколько строк. Чтобы определить наличие RETURNING, ознакомьтесь с документацией по используемой базе данных.

Параметры:

• *cols – ряд столбцов, SQL-выражений или целых таблиц, которые должны быть возвращены.

• sort_by_parameter_order – для пакетного INSERT, выполняемого по нескольким наборам параметров, упорядочить результаты RETURNING так, чтобы возвращаемые строки соответствовали порядку переданных наборов параметров. Это применимо только к выполнению executemany для поддерживающих диалектов и обычно использует функцию insertmanyvalues. … версия добавлена:: 2.0.10 .. seealso:: Соотнесение строк RETURNING с наборами параметров - история сортировки строк RETURNING для массового INSERT (обсуждение на уровне ядра) Соотнесение записей о возврате с порядком входных данных - пример использования с ORM Bulk INSERT Statements (обсуждение на уровне ORM)

См.также

UpdateBase.return_defaults() - альтернативный метод, предназначенный для эффективной выборки значений по умолчанию на стороне сервера и триггеров для однорядных INSERT или UPDATE.

ВСТАВКА… ВОЗВРАТ - в Унифицированный учебник по SQLAlchemy

attribute sqlalchemy.sql.expression.UpdateBase.returning_column_descriptions¶

Возвращает plugin-enabled описание столбцов, по которым возвращается данная конструкция DML, другими словами, выражения, установленные как часть UpdateBase.returning().

Этот атрибут обычно полезен при использовании ORM, так как возвращается расширенная структура, включающая информацию о сопоставленных сущностях. В разделе Проверка сущностей и столбцов из операторов SELECT и DML с поддержкой ORM содержится более подробная информация.

Для оператора Core структура, возвращаемая этим аксессором, является производной от тех же объектов, которые возвращаются аксессором UpdateBase.exported_columns:

>>> stmt = insert(user_table).returning(user_table.c.id, user_table.c.name)
>>> stmt.entity_description
[
    {
        "name": "id",
        "type": Integer,
        "expr": Column("id", Integer(), table=<user>, ...)
    },
    {
        "name": "name",
        "type": String(),
        "expr": Column("name", String(), table=<user>, ...)
    },
]

Добавлено в версии 1.4.33.

См.также

UpdateBase.entity_description

Select.column_descriptions - информация об объекте для конструкции select()

Проверка сущностей и столбцов из операторов SELECT и DML с поддержкой ORM - фон ORM

method sqlalchemy.sql.expression.UpdateBase.with_dialect_options(**opt: Any) → Self¶

Добавьте параметры диалекта к этому объекту INSERT/UPDATE/DELETE.

например:

upd = table.update().dialect_options(mysql_limit=10)

method sqlalchemy.sql.expression.UpdateBase.with_hint(text: str, selectable: Optional[_DMLTableArgument] = None, dialect_name: str = '*') → Self¶

Добавьте подсказку таблицы для одной таблицы к этому оператору INSERT/UPDATE/DELETE.

Примечание

UpdateBase.with_hint() в настоящее время применяется только к Microsoft SQL Server. Для подсказок MySQL INSERT/UPDATE/DELETE используйте UpdateBase.prefix_with().

Текст подсказки отображается в соответствующем месте для используемого бэкенда базы данных, относительно Table, который является предметом этого утверждения, или, опционально, относительно данного Table, переданного в качестве аргумента selectable.

Опция dialect_name ограничивает отображение конкретной подсказки для определенного бэкенда. Например, чтобы добавить подсказку, которая будет действовать только для SQL Server:

mytable.insert().with_hint("WITH (PAGLOCK)", dialect_name="mssql")

Параметры:

• text – Текст подсказки.

• selectable – необязательная Table, указывающая элемент предложения FROM в UPDATE или DELETE в качестве объекта подсказки - применяется только для определенных бэкендов.

• dialect_name – по умолчанию *, если указано как имя конкретного диалекта, то эти подсказки будут применяться только при использовании этого диалекта.

class sqlalchemy.sql.expression.ValuesBase¶

Обеспечивает поддержку ValuesBase.values() в конструкциях INSERT и UPDATE.

Members

select, values()

Классная подпись

класс sqlalchemy.sql.expression.ValuesBase (sqlalchemy.sql.expression.UpdateBase)

attribute sqlalchemy.sql.expression.ValuesBase.select: Optional[Select[Any]] = None¶

Оператор SELECT для INSERT … FROM SELECT

method sqlalchemy.sql.expression.ValuesBase.values(*args: Union[_DMLColumnKeyMapping[Any], Sequence[Any]], **kwargs: Any) → Self¶

Укажите фиксированное предложение VALUES для оператора INSERT или предложение SET для UPDATE.

Обратите внимание, что конструкции Insert и Update поддерживают форматирование клаузул VALUES и/или SET по времени выполнения на основе аргументов, переданных в Connection.execute(). Однако метод ValuesBase.values() может быть использован для «фиксации» определенного набора параметров в операторе.

При многократном вызове ValuesBase.values() будет создаваться новая конструкция, в каждой из которых список параметров будет изменен, чтобы включить новые переданные параметры. В типичном случае с одним словарем параметров, вновь переданные ключи заменяют те же самые ключи в предыдущей конструкции. В случае конструкции «множество значений», основанной на списке, каждый новый список значений расширяется на существующий список значений.

Параметры:

• **kwargs – пары ключ-значение, представляющие строковый ключ Column, сопоставленный со значением, которое должно быть выведено в предложение VALUES или SET:: users.insert().values(name=»some name») users.update().where(users.c.id==5).values(name=»some name»)

• *args – В качестве альтернативы передаче параметров ключ/значение, словарь, кортеж или список словарей или кортежей может быть передан в качестве единственного позиционного аргумента для формирования предложения VALUES или SET оператора. Принимаемые формы зависят от того, является ли это конструкцией Insert или Update. Для конструкции Insert или Update можно передать один словарь, который работает так же, как и форма kwargs:: users.insert().values({«name»: «some name»}) users.update().values({«name»: «some new name»}) Также для любой формы, но более типично для конструкции Insert, принимается кортеж, содержащий запись для каждого столбца таблицы:: users. insert().values((5, «some name»)) Конструкция Insert также поддерживает передачу списка словарей или кортежей полной таблицы, которые на сервере будут иметь менее распространенный синтаксис SQL «multiple values» - этот синтаксис поддерживается такими бэкендами, как SQLite, PostgreSQL, MySQL, но не обязательно другими:: users.insert().values([ {«name»: «какое-то имя»}, { {«имя»: «какое-то другое имя»}, {«имя»: «еще одно имя»}, ]) Приведенная выше форма выведет множественный оператор VALUES, подобный следующему:: INSERT INTO users (name) VALUES (:name_1), (:name_2), (:name_3) Важно отметить, что передача множественных значений - это НЕ то же самое, что использование традиционной формы executemany(). Приведенный выше синтаксис является специальным синтаксисом, который обычно не используется. Чтобы выполнить оператор INSERT для нескольких строк, обычным методом является передача списка из нескольких значений в метод Connection.execute(), который поддерживается всеми бэкендами баз данных и обычно более эффективен для очень большого количества параметров. … см. также:: Отправка нескольких параметров - введение в традиционный метод Core вызова множественного набора параметров для INSERT’ов и других операторов. Конструкция UPDATE также поддерживает вывод параметров SET в определенном порядке. Для этой возможности обратитесь к методу Update.ordered_values(). … см. также:: Update.ordered_values()