Вставка, обновление, удаление¶
Операторы INSERT, UPDATE и DELETE строятся по иерархии, начинающейся с UpdateBase
. Конструкции Insert
и Update
строятся на промежуточной ValuesBase
.
Основополагающие конструкторы DML¶
Конструкторы верхнего уровня «INSERT», «UPDATE», «DELETE».
Object Name | Description |
---|---|
delete(table) |
Постройте объект |
insert(table) |
Создайте объект |
update(table) |
Создайте объект |
- 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 – Таблица, из которой нужно удалить строки.
- 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
.- Параметры:
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
.
- 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
, представляющий обновляемую таблицу базы данных.
Документация класса DML Конструкторы¶
Документация класса для конструкторов, перечисленных в Основополагающие конструкторы DML.
Object Name | Description |
---|---|
Представляет собой конструкцию DELETE. |
|
Представляет собой конструкцию INSERT. |
|
Представляет собой конструкцию Update. |
|
Формируют основу для утверждений |
|
Обеспечивает поддержку |
- class sqlalchemy.sql.expression.Delete¶
Представляет собой конструкцию DELETE.
Объект
Delete
создается с помощью функцииdelete()
.Members
Классная подпись
класс
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
. Для бэкендов, не имеющих поддержки множественных таблиц, независимый от бэкенда подход к использованию множественных таблиц заключается в использовании коррелированных подзапросов. Примеры приведены в разделах учебника по ссылкам ниже.
-
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.
-
method
- class sqlalchemy.sql.expression.Insert¶
Представляет собой конструкцию INSERT.
Объект
Insert
создается с помощью функцииinsert()
.Members
Классная подпись
класс
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.
-
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
, например, объект ORMQuery
и т.д. Порядок колонок, возвращаемых из этого предложения 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
-
method
- class sqlalchemy.sql.expression.Update¶
Представляет собой конструкцию Update.
Объект
Update
создается с помощью функцииupdate()
.Members
Классная подпись
класс
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.
-
method
sqlalchemy.sql.expression.Update.
where(*whereclause: _ColumnExpressionArgument[bool]) Self ¶ наследуется от
DMLWhereBase.where()
методаDMLWhereBase
Возвращает новую конструкцию с заданным выражением (выражениями), добавленным к пункту WHERE, присоединенным к существующему пункту через AND, если таковой имеется.
И
Update.where()
, иDelete.where()
поддерживают формы с несколькими таблицами, включая специфические для базы данныхUPDATE...FROM
, а такжеDELETE..USING
. Для бэкендов, не имеющих поддержки множественных таблиц, независимый от бэкенда подход к использованию множественных таблиц заключается в использовании коррелированных подзапросов. Примеры приведены в разделах учебника по ссылкам ниже.
-
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.
-
method
- 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()
следующим образом:Метод
UpdateBase.return_defaults()
вызывает заполнение коллекцииCursorResult.returned_defaults
первой строкой из результата RETURNING. Этот атрибут не заполняется при использованииUpdateBase.returning()
.UpdateBase.return_defaults()
совместимо с существующей логикой, используемой для получения автоматически генерируемых значений первичного ключа, которые затем заполняются в атрибутCursorResult.inserted_primary_key
. Напротив, использованиеUpdateBase.returning()
приведет к тому, что атрибутCursorResult.inserted_primary_key
останется незаполненным.UpdateBase.return_defaults()
может быть вызвана против любого бэкенда. Бэкенды, которые не поддерживают RETURNING, пропустят использование функции, а не вызовут исключение. Возвращаемое значениеCursorResult.returned_defaults
будетNone
для бэкендов, которые не поддерживают RETURNING или для которых целевойTable
устанавливаетTable.implicit_returning
вFalse
.Оператор 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.0sort_by_parameter_order – для пакетного INSERT, выполняемого по нескольким наборам параметров, упорядочить результаты RETURNING так, чтобы возвращаемые строки соответствовали порядку переданных наборов параметров. Это применимо только к выполнению executemany для поддерживающих диалектов и обычно использует функцию insertmanyvalues. … версия добавлена:: 2.0.10 .. seealso:: Соотнесение строк RETURNING с наборами параметров - фон для сортировки возвращаемых строк для массового INSERT
-
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.
-
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.
См.также
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 – по умолчанию
*
, если указано как имя конкретного диалекта, то эти подсказки будут применяться только при использовании этого диалекта.
-
attribute
- class sqlalchemy.sql.expression.ValuesBase¶
Обеспечивает поддержку
ValuesBase.values()
в конструкциях INSERT и UPDATE.Классная подпись
класс
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()
-
attribute