Legacy Query API¶

Для ознакомления с написанием SQL для объектов ORM в стиле 2.0 начните с . Дополнительная справка по составлению запросов в стиле 2.0 находится в разделе .¶

Query производится в терминах заданного Session, используя метод Session.query():

q = session.query(SomeMappedClass)

Ниже приведен полный интерфейс для объекта Query.

class sqlalchemy.orm.Query¶

Объект построения SQL на уровне ORM.

Legacy Feature

Объект ORM Query является унаследованной конструкцией по сравнению с SQLAlchemy 2.0. Обзор, включая ссылки на документацию по миграции, см. в примечаниях в верхней части Legacy Query API.

Объекты Query обычно первоначально создаются с помощью метода Session.query() в Session, а в менее распространенных случаях - путем инстанцирования Query напрямую и связывания с Session с помощью метода Query.with_session().

Members

__init__(), add_column(), add_columns(), add_entity(), all(), apply_labels(), as_scalar(), autoflush(), column_descriptions, correlate(), count(), cte(), delete(), distinct(), enable_assertions(), enable_eagerloads(), except_(), except_all(), execution_options(), exists(), filter(), filter_by(), first(), from_statement(), get(), get_children(), get_execution_options(), get_label_style, group_by(), having(), instances(), intersect(), intersect_all(), is_single_entity, join(), label(), lazy_loaded_from, limit(), merge_result(), offset(), one(), one_or_none(), only_return_tuples(), options(), order_by(), outerjoin(), params(), populate_existing(), prefix_with(), reset_joinpoint(), scalar(), scalar_subquery(), select_from(), selectable, set_label_style(), slice(), statement, subquery(), suffix_with(), tuples(), union(), union_all(), update(), value(), values(), where(), whereclause, with_entities(), with_for_update(), with_hint(), with_labels(), with_parent(), with_session(), with_statement_hint(), with_transformation(), yield_per()

Классическая подпись.

class sqlalchemy.orm.Query (sqlalchemy.sql.expression._SelectFromElements, sqlalchemy.sql.annotation.SupportsCloneAnnotations, sqlalchemy.sql.expression.HasPrefixes, sqlalchemy.sql.expression.HasSuffixes, sqlalchemy.sql.expression.HasHints, sqlalchemy.event.registry.EventTarget, sqlalchemy.log.Identified, sqlalchemy.sql.expression.Generative, sqlalchemy.sql.expression.Executable, typing.Generic)

method sqlalchemy.orm.Query.__init__(entities: Sequence[_ColumnsClauseArgument[Any]], session: Optional[Session] = None)¶

Конструирование Query напрямую.

Например:

q = Query([User, Address], session=some_session)

Вышесказанное эквивалентно:

q = some_session.query(User, Address)

Параметры:

• entities – последовательность сущностей и/или SQL-выражений.

• session – Session, с которым будет ассоциирован Query. Необязательно; Query может быть ассоциирован с Session также генеративно через метод Query.with_session().

См.также

Session.query()

Query.with_session()

method sqlalchemy.orm.Query.add_column(column: _ColumnExpressionArgument[Any]) → Query[Any]¶

Добавляет выражение столбца в список возвращаемых столбцов результата.

Не рекомендуется, начиная с версии 1.4: Query.add_column() является устаревшим и будет удален в будущем релизе. Пожалуйста, используйте Query.add_columns()

method sqlalchemy.orm.Query.add_columns(*column: _ColumnExpressionArgument[Any]) → Query[Any]¶

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

См.также

Select.add_columns() - v2 сопоставимый метод.

method sqlalchemy.orm.Query.add_entity(entity: _EntityType[Any], alias: Optional[Union[Alias, Subquery]] = None) → Query[Any]¶

добавить сопоставленную сущность в список возвращаемых колонок результата.

См.также

Select.add_columns() - v2 сопоставимый метод.

method sqlalchemy.orm.Query.all() → List[_T]¶

Возвращает результаты, представленные данным Query, в виде списка.

Это приводит к выполнению базового SQL-оператора.

Предупреждение

Объект Query, если его попросить вернуть последовательность или итератор, состоящий из полных ORM-сопоставленных сущностей, будет дублировать записи на основе первичного ключа. Более подробная информация приведена в FAQ.

См.также

Мой запрос не возвращает то количество объектов, которое мне сообщает query.count() - почему?

См.также

Result.all() - v2 сопоставимый метод.

Result.scalars() - v2 сопоставимый метод.

method sqlalchemy.orm.Query.apply_labels() → Self¶

Не рекомендуется, начиная с версии 2.0: Метод Query.with_labels() и Query.apply_labels() считается унаследованным от серии SQLAlchemy 1.x и становится унаследованной конструкцией в версии 2.0. Вместо этого используйте set_label_style(LABEL_STYLE_TABLENAME_PLUS_COL). (Справочная информация по SQLAlchemy 2.0 на сайте: SQLAlchemy 2.0 - руководство по миграции)

method sqlalchemy.orm.Query.as_scalar() → ScalarSelect[Any]¶

Возвращает полный оператор SELECT, представленный данным Query, преобразованный в скалярный подзапрос.

Не рекомендуется, начиная с версии 1.4: Метод Query.as_scalar() является устаревшим и будет удален в одном из будущих выпусков. Обратитесь к методу Query.scalar_subquery().

method sqlalchemy.orm.Query.autoflush(setting: bool) → Self¶

Возвращает запрос с определенной настройкой „autoflush“.

Начиная с версии SQLAlchemy 1.4, метод Query.autoflush() эквивалентен использованию опции выполнения autoflush на уровне ORM. Подробнее об этой опции см. в разделе Автопромывка.

attribute sqlalchemy.orm.Query.column_descriptions¶

Возвращает метаданные о столбцах, которые были бы возвращены этим Query.

Формат представляет собой список словарей:

user_alias = aliased(User, name='user2')
q = sess.query(User, User.id, user_alias)

# this expression:
q.column_descriptions

# would return:
[
    {
        'name':'User',
        'type':User,
        'aliased':False,
        'expr':User,
        'entity': User
    },
    {
        'name':'id',
        'type':Integer(),
        'aliased':False,
        'expr':User.id,
        'entity': User
    },
    {
        'name':'user2',
        'type':User,
        'aliased':True,
        'expr':user_alias,
        'entity': user_alias
    }
]

См.также

Этот API доступен и при использовании запросов 2.0 style, документированных на сайте:

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

• Select.column_descriptions

method sqlalchemy.orm.Query.correlate(*fromclauses: Union[Literal[None, False], FromClauseRole, Type[Any], Inspectable[_HasClauseElement], _HasClauseElement]) → Self¶

Возвращает конструкцию Query, которая соотнесет заданные условия FROM с условиями вложенного Query или select().

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

Аргументы корреляции в конечном итоге передаются в Select.correlate() после приведения к конструкциям выражений.

Аргументы корреляции действуют в тех случаях, когда используется Query.from_self() или когда подзапрос, возвращаемый Query.subquery(), встраивается в другую конструкцию select().

См.также

Select.correlate() - эквивалентный метод v2.

method sqlalchemy.orm.Query.count() → int¶

Возвращает счетчик строк, которые вернул бы SQL, сформированный этим Query.

При этом SQL для данного запроса формируется следующим образом:

SELECT count(1) AS count_1 FROM (
    SELECT <rest of query follows...>
) AS anon_1

Приведенный выше SQL возвращает одну строку, которая является суммарным значением функции count; метод Query.count() затем возвращает это единственное целочисленное значение.

Предупреждение

Важно отметить, что значение, возвращаемое функцией count(), не совпадает с количеством ORM-объектов, которые данный запрос вернет с помощью такого метода, как .all(). Объект Query, когда его просят вернуть полные сущности, будет дублировать записи на основе первичного ключа, то есть если одно и то же значение первичного ключа появится в результатах более одного раза, то будет присутствовать только один объект с таким первичным ключом. Это не относится к запросам к отдельным столбцам.

См.также

Мой запрос не возвращает то количество объектов, которое мне сообщает query.count() - почему?

Для более тонкого контроля над конкретными столбцами для подсчета, отказа от использования подзапроса или иного контроля над предложением FROM, а также для использования других агрегатных функций, используйте выражения expression.func в сочетании с Session.query(), т.е.:

from sqlalchemy import func

# count User records, without
# using a subquery.
session.query(func.count(User.id))

# return count of user "id" grouped
# by "name"
session.query(func.count(User.id)).\
        group_by(User.name)

from sqlalchemy import distinct

# count distinct "name" values
session.query(func.count(distinct(User.name)))

См.также

2.0 Миграция - использование ORM

method sqlalchemy.orm.Query.cte(name: Optional[str] = None, recursive: bool = False, nesting: bool = False) → CTE¶

Возвращает полный оператор SELECT, представленный данным Query, представленный в виде общего табличного выражения (CTE).

Параметры и использование аналогичны параметрам метода SelectBase.cte(), подробнее см. в этом методе.

Вот PostgreSQL WITH RECURSIVE example. Обратите внимание, что в данном примере кте included_parts и его псевдоним incl_alias являются Core selectables, а значит, доступ к столбцам осуществляется через атрибут .c.. Объект parts_alias является aliased() экземпляром сущности Part, поэтому атрибуты, отображающие столбцы, доступны непосредственно:

from sqlalchemy.orm import aliased

class Part(Base):
    __tablename__ = 'part'
    part = Column(String, primary_key=True)
    sub_part = Column(String, primary_key=True)
    quantity = Column(Integer)

included_parts = session.query(
                Part.sub_part,
                Part.part,
                Part.quantity).\
                    filter(Part.part=="our part").\
                    cte(name="included_parts", recursive=True)

incl_alias = aliased(included_parts, name="pr")
parts_alias = aliased(Part, name="p")
included_parts = included_parts.union_all(
    session.query(
        parts_alias.sub_part,
        parts_alias.part,
        parts_alias.quantity).\
            filter(parts_alias.part==incl_alias.c.sub_part)
    )

q = session.query(
        included_parts.c.sub_part,
        func.sum(included_parts.c.quantity).
            label('total_quantity')
    ).\
    group_by(included_parts.c.sub_part)

См.также

Select.cte() - эквивалентный метод v2.

method sqlalchemy.orm.Query.delete(synchronize_session: SynchronizeSessionArgument = 'auto') → int¶

Выполните DELETE с произвольным предложением WHERE.

Удаляет из базы данных строки, соответствующие данному запросу.

Например:

sess.query(User).filter(User.age == 25).\
    delete(synchronize_session=False)

sess.query(User).filter(User.age == 25).\
    delete(synchronize_session='evaluate')

Предупреждение

Важные предостережения и предупреждения, в том числе ограничения при использовании массовых UPDATE и DELETE с конфигурациями наследования mapper, см. в разделе Операции INSERT, UPDATE и DELETE с поддержкой ORM.

Параметры:

synchronize_session – выбирает стратегию обновления атрибутов объектов в сессии. Обсуждение этих стратегий см. в разделе Операции INSERT, UPDATE и DELETE с поддержкой ORM.

Результат:

количество совпавших строк, возвращаемое функцией «row count» базы данных.

См.также

Операции INSERT, UPDATE и DELETE с поддержкой ORM

method sqlalchemy.orm.Query.distinct(*expr: _ColumnExpressionArgument[Any]) → Self¶

Примените к запросу DISTINCT и верните только что полученный Query.

Примечание

Вызов distinct() на уровне ORM включает логику, которая автоматически добавляет столбцы из ORDER BY запроса в предложение columns оператора SELECT, чтобы удовлетворить общую потребность бэкенда базы данных в том, чтобы столбцы ORDER BY были частью списка SELECT при использовании DISTINCT. Однако эти столбцы не добавляются к списку столбцов, фактически извлекаемых оператором Query, поэтому не влияют на результаты. Однако при использовании аксессора Query.statement эти столбцы передаются.

Не рекомендуется, начиная с версии 2.0: Эта логика устарела и будет удалена в SQLAlchemy 2.0. Описание этого варианта использования в версии 2.0 см. в Использование DISTINCT с дополнительными столбцами, но выбор только сущности.

См.также

Select.distinct() - эквивалентный метод v2.

Параметры:

*expr – необязательные выражения столбцов. Если оно присутствует, то диалект PostgreSQL выводит конструкцию DISTINCT ON (<expressions>). … deprecated:: 1.4 Использование *expr в других диалектах является устаревшим и приведет к появлению CompileError в будущей версии.

method sqlalchemy.orm.Query.enable_assertions(value: bool) → Self¶

Управление тем, генерируются ли утверждения.

При установке значения False возвращаемый запрос не будет подтверждать свое состояние перед некоторыми операциями, в том числе, что при вызове filter() не был применен LIMIT/OFFSET, при вызове get() не существует критерия, при вызове filter()/order_by()/group_by() и т.д. не существует «from_statement()». Этот более свободный режим используется пользовательскими подклассами Query для задания критериев и других модификаторов, выходящих за рамки обычных шаблонов.

Следует внимательно отнестись к тому, чтобы убедиться в возможности использования данного шаблона. Оператор, примененный с помощью функции from_statement(), будет отменять любые критерии, заданные, например, с помощью filter() или order_by().

method sqlalchemy.orm.Query.enable_eagerloads(value: bool) → Self¶

Контролирует, будут ли выводиться на экран расширенные соединения и подзапросы.

Если установлено значение False, то возвращаемый запрос не будет отображать eager joins независимо от опций joinedload(), subqueryload() или конфигураций lazy='joined'/lazy='subquery' на уровне mapper.

Это используется в основном при вложении оператора Query в подзапрос или другой selectable, а также при использовании Query.yield_per().

method sqlalchemy.orm.Query.except_(*q: Query) → Self¶

Создайте ИСКЛЮЧЕНИЕ данного запроса из одного или нескольких запросов.

Работает так же, как и Query.union(). Примеры использования см. в этом методе.

См.также

Select.except_() - эквивалентный метод v2.

method sqlalchemy.orm.Query.except_all(*q: Query) → Self¶

Создайте запрос EXCEPT ALL of this Query против одного или нескольких запросов.

Работает так же, как и Query.union(). Примеры использования см. в этом методе.

См.также

Select.except_all() - эквивалентный метод v2.

method sqlalchemy.orm.Query.execution_options(**kwargs: Any) → Self¶

Установить опции, не относящиеся к языку SQL, которые вступают в силу во время выполнения.

Здесь допускаются все опции, принимаемые в Connection.execution_options(), а также ряд специфических для ORM опций:

populate_existing=True - эквивалентно использованию Query.populate_existing()

autoflush=True|False - эквивалентно использованию Query.autoflush()

yield_per=<value> - эквивалентно использованию Query.yield_per()

Обратите внимание, что опция выполнения stream_results включается автоматически, если используется метод или опция выполнения Query.yield_per().

Добавлено в версии 1.4: - added ORM options to Query.execution_options()

Параметры выполнения также могут быть заданы отдельно для каждого выполнения при использовании запросов 2.0 style через параметр Session.execution_options.

Предупреждение

Параметр Connection.execution_options.stream_results не следует использовать на уровне выполнения отдельных операторов ORM, так как Session не будет отслеживать объекты из разных карт трансляции схем в рамках одной сессии. Для работы с несколькими картами трансляции схем в рамках одного Session смотрите Горизонтальное разделение.

См.также

Использование курсоров на стороне сервера (они же потоковые результаты)

Query.get_execution_options()

Select.execution_options() - эквивалентный метод v2.

method sqlalchemy.orm.Query.exists() → Exists¶

Удобный метод, который превращает запрос в подзапрос EXISTS вида EXISTS (SELECT 1 FROM … WHERE …).

например:

q = session.query(User).filter(User.name == 'fred')
session.query(q.exists())

Производить SQL, аналогичный:

SELECT EXISTS (
    SELECT 1 FROM users WHERE users.name = :name_1
) AS anon_1

Конструкция EXISTS обычно используется в предложении WHERE:

session.query(User.id).filter(q.exists()).scalar()

Обратите внимание, что некоторые базы данных, например SQL Server, не допускают присутствия выражения EXISTS в предложении columns в SELECT. Чтобы выбрать простое булево значение на основе exists в качестве WHERE, используйте literal():

from sqlalchemy import literal

session.query(literal(True)).filter(q.exists()).scalar()

См.также

Select.exists() - v2 сопоставимый метод.

method sqlalchemy.orm.Query.filter(*criterion: _ColumnExpressionArgument[bool]) → Self¶

Применить заданный критерий фильтрации к экземпляру данного Query, используя SQL-выражения.

например:

session.query(MyClass).filter(MyClass.name == 'some name')

Несколько критериев могут быть указаны через запятую; в результате они будут объединены с помощью функции and_():

session.query(MyClass).\
    filter(MyClass.name == 'some name', MyClass.id > 5)

Критерием является любой объект SQL-выражения, применимый к предложению WHERE селекта. Строковые выражения преобразуются в конструкции SQL-выражений с помощью конструкции text().

См.также

Query.filter_by() - фильтр по выражениям с ключевыми словами.

Select.where() - эквивалентный метод v2.

method sqlalchemy.orm.Query.filter_by(**kwargs: Any) → Self¶

Применить заданный критерий фильтрации к копии данного Query, используя выражения с ключевыми словами.

например:

session.query(MyClass).filter_by(name = 'some name')

Несколько критериев могут быть указаны через запятую; в результате они будут объединены с помощью функции and_():

session.query(MyClass).\
    filter_by(name = 'some name', id = 5)

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

См.также

Query.filter() - фильтр по SQL-выражениям.

Select.filter_by() - v2 сопоставимый метод.

method sqlalchemy.orm.Query.first() → Optional[_T]¶

Возвращает первый результат данного Query или None, если результат не содержит ни одной строки.

first() применяет ограничение на единицу в генерируемом SQL, так что на стороне сервера генерируется только одна строка первичной сущности (обратите внимание, что она может состоять из нескольких строк результатов, если присутствуют коллекции с объединенной загрузкой).

Вызов Query.first() приводит к выполнению базового запроса.

См.также

Query.one()

Query.one_or_none()

Result.first() - v2 сопоставимый метод.

Result.scalars() - v2 сопоставимый метод.

method sqlalchemy.orm.Query.from_statement(statement: ExecutableReturnsRows) → Self¶

Выполнить заданный оператор SELECT и вернуть результаты.

Этот метод позволяет обойти всю внутреннюю компиляцию оператора, и он выполняется без модификации.

Утверждение обычно представляет собой конструкцию text() или select() и должно возвращать набор столбцов, соответствующих классу сущности, представленному данной Query.

См.также

Select.from_statement() - v2 сопоставимый метод.

method sqlalchemy.orm.Query.get(ident: _PKIdentityArgument) → Optional[Any]¶

Возвращает экземпляр, основанный на заданном идентификаторе первичного ключа, или None, если он не найден.

Не рекомендуется, начиная с версии 2.0: Метод Query.get() считается унаследованным от серии SQLAlchemy 1.x и становится унаследованной конструкцией в версии 2.0. Теперь метод доступен в виде Session.get() (Справочная информация по SQLAlchemy 2.0 на сайте: SQLAlchemy 2.0 - руководство по миграции)

Например:

my_user = session.query(User).get(5)

some_object = session.query(VersionedFoo).get((5, 10))

some_object = session.query(VersionedFoo).get(
    {"id": 5, "version_id": 10})

Особенностью коллекции Query.get() является то, что она предоставляет прямой доступ к карте идентификаторов владельца Session. Если заданный идентификатор первичного ключа присутствует в локальной карте идентификации, то объект возвращается непосредственно из этой коллекции и никакого SQL не выдается, если только объект не был помечен как полностью истекший. Если он отсутствует, то для поиска объекта выполняется SELECT.

Query.get() также выполнит проверку, присутствует ли объект в карте идентификации и помечен ли он как истекший - будет выдан SELECT для обновления объекта, а также для того, чтобы убедиться, что строка все еще присутствует. Если нет, то выдается сообщение ObjectDeletedError.

Query.get() используется только для возврата одного сопоставленного экземпляра, а не нескольких экземпляров или отдельных конструкций столбцов, и строго по одному значению первичного ключа. Исходный Query должен быть построен именно таким образом, т.е. по единственному сопоставленному объекту, без дополнительных критериев фильтрации. Однако могут быть применены опции загрузки через Query.options(), которые будут использованы, если объект еще не присутствует локально.

Параметры:

ident – Скаляр, кортеж или словарь, представляющий первичный ключ. Для составного (например, многоколоночного) первичного ключа следует передавать кортеж или словарь. Для первичного ключа, состоящего из одного столбца, как правило, наиболее удобна скалярная форма вызова. Если первичным ключом строки является значение «5», то вызов выглядит так:: my_object = query.get(5) Кортежная форма содержит значения первичных ключей обычно в том порядке, в котором они соответствуют столбцам первичного ключа сопоставленного объекта Table, или, если использовался конфигурационный параметр Mapper.primary_key, в порядке, используемом для этого параметра. Например, если первичный ключ строки представлен целыми числами «5, 10», то вызов будет выглядеть так:: my_object = query.get((5, 10)) Словарная форма должна включать в качестве ключей имена отображаемых атрибутов, соответствующих каждому элементу первичного ключа. Если в качестве атрибутов, хранящих значение первичного ключа объекта, в отображаемом классе используются атрибуты id, version_id, то вызов будет выглядеть так:: my_object = query.get({«id»: 5, «version_id»: 10}) … versionadded:: 1.3 метод Query.get() теперь опционально принимает словарь имен атрибутов к значениям для указания идентификатора первичного ключа.

Результат:

Экземпляр объекта, или None.

method sqlalchemy.orm.Query.get_children(*, omit_attrs: Tuple[str, ...] = (), **kw: Any) → Iterable[HasTraverseInternals]¶

наследуется от HasTraverseInternals.get_children() метода HasTraverseInternals

Возвращает непосредственные дочерние HasTraverseInternals элементы данного HasTraverseInternals.

Это используется для обхода посещений.

**kw может содержать флаги, изменяющие возвращаемую коллекцию, например, для возврата подмножества элементов, чтобы сократить объем обхода, или для возврата дочерних элементов из другого контекста (например, коллекции на уровне схемы вместо коллекции на уровне клаузы).

method sqlalchemy.orm.Query.get_execution_options() → _ImmutableExecuteOptions¶

Получить опции, не относящиеся к языку SQL, которые будут действовать во время выполнения.

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

См.также

Query.execution_options()

Select.get_execution_options() - v2 сопоставимый метод.

attribute sqlalchemy.orm.Query.get_label_style¶

Получение текущего стиля этикетки.

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

См.также

Select.get_label_style() - эквивалентный метод v2.

method sqlalchemy.orm.Query.group_by(_Query__first: Union[Literal[None, False, _NoArg.NO_ARG], _ColumnExpressionOrStrLabelArgument[Any]] = _NoArg.NO_ARG, *clauses: _ColumnExpressionOrStrLabelArgument[Any]) → Self¶

Примените к запросу один или несколько критериев GROUP BY и верните полученный результат Query.

Все существующие настройки GROUP BY могут быть подавлены путем передачи None - при этом будут подавлены все GROUP BY, настроенные также и на мапперах.

См.также

Эти разделы описывают GROUP BY с точки зрения вызова 2.0 style, но применимы и к Query:

Агрегатные функции с GROUP BY / HAVING - в Унифицированный учебник по SQLAlchemy

Упорядочивание или группировка по метке - в Унифицированный учебник по SQLAlchemy

Select.group_by() - эквивалентный метод v2.

method sqlalchemy.orm.Query.having(*having: _ColumnExpressionArgument[bool]) → Self¶

Примените к запросу критерий HAVING и верните полученный результат Query.

Query.having() используется совместно с Query.group_by().

Критерий HAVING позволяет использовать фильтры на агрегатных функциях типа COUNT, SUM, AVG, MAX и MIN, например:

q = session.query(User.id).\
            join(User.addresses).\
            group_by(User.id).\
            having(func.count(Address.id) > 2)

См.также

Select.having() - эквивалентный метод v2.

method sqlalchemy.orm.Query.instances(result_proxy: CursorResult[Any], context: Optional[QueryContext] = None) → Any¶

Возвращает результат ORM, заданный CursorResult и QueryContext.

Не рекомендуется, начиная с версии 2.0: Метод Query.instances() является устаревшим и будет удален в одном из будущих выпусков. Вместо него используйте метод Select.from_statement() или конструкцию aliased() в сочетании с Session.execute().

method sqlalchemy.orm.Query.intersect(*q: Query) → Self¶

Произвести ИНТЕРСЕКЦИЮ данного запроса с одним или несколькими запросами.

Работает так же, как и Query.union(). Примеры использования см. в этом методе.

См.также

Select.intersect() - эквивалентный метод v2.

method sqlalchemy.orm.Query.intersect_all(*q: Query) → Self¶

Вывести INTERSECT ALL данного запроса по отношению к одному или нескольким запросам.

Работает так же, как и Query.union(). Примеры использования см. в этом методе.

См.также

Select.intersect_all() - эквивалентный метод v2.

attribute sqlalchemy.orm.Query.is_single_entity¶

Указывает, возвращает ли данный Query кортежи или одиночные сущности.

Возвращает True, если запрос возвращает одну сущность для каждого экземпляра в списке результатов, и False, если запрос возвращает кортеж сущностей для каждого результата.

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

См.также

Query.only_return_tuples()

method sqlalchemy.orm.Query.join(target: _JoinTargetArgument, onclause: Optional[_OnClauseArgument] = None, *, isouter: bool = False, full: bool = False) → Self¶

Создать SQL JOIN по критерию данного объекта Query и применить генеративно, вернув только что полученный Query.

Простые соединения отношений.

Рассмотрим отображение между двумя классами User и Address, с отношением User.addresses, представляющим собой коллекцию Address объектов, связанных с каждым User. Наиболее частое использование Query.join() заключается в создании JOIN вдоль этого отношения, используя атрибут User.addresses в качестве индикатора того, как это должно происходить:

q = session.query(User).join(User.addresses)

Там, где выше, вызов Query.join() вместе с User.addresses приведет к SQL, примерно эквивалентному:

SELECT user.id, user.name
FROM user JOIN address ON user.id = address.user_id

В приведенном примере мы называем User.addresses, переданный в Query.join(), «клаузой включения», то есть он указывает, как должна быть построена часть «ON» в JOIN.

Для построения цепочки соединений можно использовать несколько вызовов Query.join(). Атрибут relationship-bound подразумевает сразу и левую, и правую сторону соединения:

q = session.query(User).\
        join(User.orders).\
        join(Order.items).\
        join(Item.keywords)

Примечание

Как видно из приведенного примера, порядок следования каждого вызова метода join() важен. Например, Query не поймет, как правильно соединять, если в цепочке соединений указать User, затем Item, затем Order; в этом случае, в зависимости от переданных аргументов, он может выдать ошибку, что не знает, как соединять, или выдать некорректный SQL, в результате чего база данных выдаст ошибку. В правильной практике метод Query.join() вызывается таким образом, чтобы соответствовать тому, как мы хотим, чтобы выглядели предложения JOIN в SQL, и каждый вызов должен представлять собой четкую связь с тем, что ему предшествует.

Соединение с целевой сущностью или выбираемым объектом.

Вторая форма Query.join() позволяет использовать в качестве цели любую сопоставленную сущность или выбираемую конструкцию ядра. В данном случае Query.join() попытается создать JOIN по естественной связи внешнего ключа между двумя сущностями:

q = session.query(User).join(Address)

В приведенной выше форме вызова вызывается Query.join(), чтобы автоматически создать для нас предложение «on clause». Эта форма вызова в конечном итоге выдаст ошибку, если между двумя сущностями нет внешних ключей, или если между целевой сущностью и сущностью или сущностями, уже присутствующими на левой стороне, существует множество связей по внешним ключам, так что для создания соединения требуется дополнительная информация. Обратите внимание, что при указании присоединения к целевой сущности без предложения ON настроенные ORM отношения не учитываются.

Присоединение к цели с помощью предложения ON.

Третья форма вызова позволяет передавать как целевую сущность, так и предложение ON в явном виде. Пример, включающий SQL-выражение в качестве условия ON, выглядит следующим образом:

q = session.query(User).join(Address, User.id==Address.user_id)

В приведенной форме в качестве предложения ON также может использоваться атрибут, связанный с отношениями:

q = session.query(User).join(Address, User.addresses)

Приведенный выше синтаксис может быть полезен в случае, когда мы хотим присоединиться к псевдониму конкретной целевой сущности. Если бы мы хотели дважды присоединиться к Address, то это можно было бы сделать с помощью двух псевдонимов, заданных с помощью функции aliased():

a1 = aliased(Address)
a2 = aliased(Address)

q = session.query(User).\
        join(a1, User.addresses).\
        join(a2, User.addresses).\
        filter(a1.email_address=='ed@foo.com').\
        filter(a2.email_address=='ed@bar.com')

В форме вызова, связанной с отношениями, можно также указать целевую сущность с помощью метода PropComparator.of_type(); запрос, эквивалентный приведенному выше, будет выглядеть так:

a1 = aliased(Address)
a2 = aliased(Address)

q = session.query(User).\
        join(User.addresses.of_type(a1)).\
        join(User.addresses.of_type(a2)).\
        filter(a1.email_address == 'ed@foo.com').\
        filter(a2.email_address == 'ed@bar.com')

Дополнение встроенных ON-клаузеров.

В качестве замены полного пользовательского условия ON для существующего отношения можно применить функцию PropComparator.and_() к атрибуту отношения для добавления дополнительных критериев в условие ON; дополнительные критерии будут объединены с критериями по умолчанию с помощью AND:

q = session.query(User).join(
    User.addresses.and_(Address.email_address != 'foo@bar.com')
)

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

Соединение с таблицами и подзапросами.

Целью join может быть также любая таблица или оператор SELECT, который может быть связан с целевой сущностью или нет. Для создания подзапроса из запроса используйте соответствующий метод .subquery():

subq = session.query(Address).\
    filter(Address.email_address == 'ed@foo.com').\
    subquery()


q = session.query(User).join(
    subq, User.id == subq.c.user_id
)

Присоединение к подзапросу с точки зрения конкретного отношения и/или целевой сущности может быть достигнуто путем связывания подзапроса с сущностью с помощью aliased():

subq = session.query(Address).\
    filter(Address.email_address == 'ed@foo.com').\
    subquery()

address_subq = aliased(Address, subq)

q = session.query(User).join(
    User.addresses.of_type(address_subq)
)

Контроль за тем, к чему присоединиться.

Query Query.select_from() I

q = session.query(Address).select_from(User).\
                join(User.addresses).\
                filter(User.name == 'ed')

В результате будет получен SQL, аналогичный:

SELECT address.* FROM user
    JOIN address ON user.id=address.user_id
    WHERE user.name = :name_1

См.также

Select.join() - эквивалентный метод v2.

Параметры:

• *props – Входящие аргументы для Query.join(), коллекции реквизитов в современном использовании следует рассматривать как форму с одним или двумя аргументами, либо как единственную «целевую» сущность или ORM-отношение с привязкой к атрибутам, либо как целевую сущность плюс «условие включения», которое может быть SQL-выражением или ORM-отношением с привязкой к атрибутам.

• isouter=False – Если True, то используемое объединение будет левым внешним объединением, как если бы был вызван метод Query.outerjoin().

• full=False – render FULL OUTER JOIN; подразумевает isouter.

method sqlalchemy.orm.Query.label(name: Optional[str]) → Label[Any]¶

Возвращает полный оператор SELECT, представленный данным Query, преобразованный в скалярный подзапрос с меткой заданного имени.

См.также

Select.label() - v2 сопоставимый метод.

attribute sqlalchemy.orm.Query.lazy_loaded_from¶

InstanceState, который использует данный Query для операции ленивой загрузки.

Не рекомендуется, начиная с версии 1.4: Этот атрибут следует рассматривать через атрибут ORMExecuteState.lazy_loaded_from, в контексте события SessionEvents.do_orm_execute().

См.также

ORMExecuteState.lazy_loaded_from

method sqlalchemy.orm.Query.limit(limit: _LimitOffsetType) → Self¶

Примените к запросу LIMIT и верните только что полученный Query.

См.также

Select.limit() - эквивалентный метод v2.

method sqlalchemy.orm.Query.merge_result(iterator: Union[FrozenResult[Any], Iterable[Sequence[Any]], Iterable[object]], load: bool = True) → Union[FrozenResult[Any], Iterable[Any]]¶

Объединить результат в сессию данного объекта Query.

Не рекомендуется, начиная с версии 2.0: Метод Query.merge_result() считается унаследованным от серии 1.x SQLAlchemy и становится унаследованной конструкцией в версии 2.0. Метод заменяется функцией merge_frozen_result(). (Справочная информация по SQLAlchemy 2.0 на сайте: SQLAlchemy 2.0 - руководство по миграции)

Учитывая итератор, возвращенный методом Query с той же структурой, что и данный, верните идентичный итератор результатов, причем все отображенные экземпляры будут объединены в сессию с помощью метода Session.merge(). Это оптимизированный метод, который объединит все сопоставленные экземпляры, сохранив структуру строк результатов и не сопоставленных столбцов с меньшими накладными расходами, чем при явном вызове Session.merge() для каждого значения.

Структура результатов определяется исходя из списка столбцов данного Query - при их несоответствии будут возникать непроверенные ошибки.

Аргумент „load“ аналогичен аргументу Session.merge().

Пример использования Query.merge_result() приведен в исходном коде примера Кэширование Dogpile, где Query.merge_result() используется для эффективного восстановления состояния из кэша обратно в целевой Session.

method sqlalchemy.orm.Query.offset(offset: _LimitOffsetType) → Self¶

Примените к запросу OFFSET и верните только что полученный Query.

См.также

Select.offset() - эквивалентный метод v2.

method sqlalchemy.orm.Query.one() → _T¶

Вернуть ровно один результат или выдать исключение.

Возникает sqlalchemy.orm.exc.NoResultFound, если запрос не выбрал ни одной строки. Возникает sqlalchemy.orm.exc.MultipleResultsFound, если возвращается несколько идентификаторов объектов, или если возвращается несколько строк для запроса, который возвращает только скалярные значения, а не полные сущности, отображенные на идентификаторы.

Вызов one() приводит к выполнению базового запроса.

См.также

Query.first()

Query.one_or_none()

Result.one() - v2 сопоставимый метод.

Result.scalar_one() - v2 сопоставимый метод.

method sqlalchemy.orm.Query.one_or_none() → Optional[_T]¶

Возвращать не более одного результата или вызывать исключение.

Возвращает None, если запрос не выбрал ни одной строки. Возвращает sqlalchemy.orm.exc.MultipleResultsFound, если возвращается несколько идентификаторов объектов, или если возвращается несколько строк для запроса, который возвращает только скалярные значения, а не полные идентификационные сущности.

Вызов Query.one_or_none() приводит к выполнению базового запроса.

См.также

Query.first()

Query.one()

Result.one_or_none() - v2 сопоставимый метод.

Result.scalar_one_or_none() - v2 сопоставимый метод.

method sqlalchemy.orm.Query.only_return_tuples(value: bool) → Query¶

При установке значения True результаты запроса всегда будут представлять собой объект Row.

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

См.также

Query.tuples() - возвращает кортежи, но также на уровне типизации будет выводить результаты как Tuple.

Query.is_single_entity()

Result.tuples() - v2 сопоставимый метод.

method sqlalchemy.orm.Query.options(*args: ExecutableOption) → Self¶

Возвращает новый объект Query, применяющий заданный список опций отображения.

Большинство поставляемых опций связано с изменением способа загрузки атрибутов, отображаемых в столбцах и отношениях.

См.также

Варианты загрузки колонн

Загрузка отношений с помощью опций загрузчика

method sqlalchemy.orm.Query.order_by(_Query__first: Union[Literal[None, False, _NoArg.NO_ARG], _ColumnExpressionOrStrLabelArgument[Any]] = _NoArg.NO_ARG, *clauses: _ColumnExpressionOrStrLabelArgument[Any]) → Self¶

Примените к запросу один или несколько критериев ORDER BY и верните полученный результат Query.

например:

q = session.query(Entity).order_by(Entity.id, Entity.name)

Многократный вызов этого метода эквивалентен его однократному вызову с конкатенацией всех пунктов. Все существующие критерии ORDER BY могут быть отменены путем передачи None самостоятельно. Новые критерии ORDER BY могут быть добавлены повторным вызовом Query.order_by(), например:

# will erase all ORDER BY and ORDER BY new_col alone
q = q.order_by(None).order_by(new_col)

См.также

Эти разделы описывают ORDER BY с точки зрения вызова 2.0 style, но применимы и к Query:

ПОРЯДОК СЛЕДОВАНИЯ - в Унифицированный учебник по SQLAlchemy

Упорядочивание или группировка по метке - в Унифицированный учебник по SQLAlchemy

Select.order_by() - эквивалентный метод v2.

method sqlalchemy.orm.Query.outerjoin(target: _JoinTargetArgument, onclause: Optional[_OnClauseArgument] = None, *, full: bool = False) → Self¶

Создать левое внешнее объединение по критерию данного объекта Query и применить генеративно, вернув только что полученный Query.

Использование аналогично методу join().

См.также

Select.outerjoin() - эквивалентный метод v2.

method sqlalchemy.orm.Query.params(_Query__params: Optional[Dict[str, Any]] = None, **kw: Any) → Self¶

Добавляет значения для параметров привязки, которые могли быть указаны в filter().

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

method sqlalchemy.orm.Query.populate_existing() → Self¶

Возвращает Query, который будет истекать и обновлять все экземпляры по мере их загрузки или повторного использования из текущего Session.

Начиная с версии SQLAlchemy 1.4, метод Query.populate_existing() эквивалентен использованию опции выполнения populate_existing на уровне ORM. Подробнее об этой опции см. в разделе Заполнить существующие.

method sqlalchemy.orm.Query.prefix_with(*prefixes: _TextCoercedExpressionArgument[Any], dialect: str = '*') → Self¶

наследуется от HasPrefixes.prefix_with() метода HasPrefixes

Добавьте одно или несколько выражений после ключевого слова statement, т.е. SELECT, INSERT, UPDATE или DELETE. Генеративный.

Он используется для поддержки префиксных ключевых слов, специфичных для бэкенда, таких как те, что предоставляет MySQL.

Например:

stmt = table.insert().prefix_with("LOW_PRIORITY", dialect="mysql")

# MySQL 5.7 optimizer hints
stmt = select(table).prefix_with(
    "/*+ BKA(t1) */", dialect="mysql")

Несколько префиксов могут быть заданы несколькими обращениями к HasPrefixes.prefix_with().

Параметры:

• *prefixes – текстовая или ClauseElement конструкция, которая будет выводиться после ключевого слова INSERT, UPDATE или DELETE.

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

method sqlalchemy.orm.Query.reset_joinpoint() → Self¶

Возвращает новый Query, в котором «точка соединения» была сброшена обратно на базовые сущности FROM запроса.

Этот метод обычно используется совместно с функцией aliased=True метода Query.join(). Как это используется, см. пример в Query.join().

method sqlalchemy.orm.Query.scalar() → Any¶

Возвращает первый элемент первого результата или None, если строк нет. Если возвращается несколько строк, то возникает ошибка MultipleResultsFound.

>>> session.query(Item).scalar()
<Item>
>>> session.query(Item.id).scalar()
1
>>> session.query(Item.id).filter(Item.id < 0).scalar()
None
>>> session.query(Item.id, Item.name).scalar()
1
>>> session.query(func.count(Parent.id)).scalar()
20

Это приводит к выполнению базового запроса.

См.также

Result.scalar() - v2 сопоставимый метод.

method sqlalchemy.orm.Query.scalar_subquery() → ScalarSelect[Any]¶

Возвращает полный оператор SELECT, представленный данным Query, преобразованный в скалярный подзапрос.

Аналогично SelectBase.scalar_subquery().

Изменено в версии 1.4: Метод Query.scalar_subquery() заменяет метод Query.as_scalar().

См.также

Select.scalar_subquery() - v2 сопоставимый метод.

method sqlalchemy.orm.Query.select_from(*from_obj: Union[FromClauseRole, Type[Any], Inspectable[_HasClauseElement], _HasClauseElement]) → Self¶

Задайте явно предложение FROM данного Query.

Query.select_from() часто используется в сочетании с Query.join() для управления тем, какая сущность выбирается из «левой» части соединения.

Здесь сущность или выбираемый объект эффективно заменяет «левый край» любого вызова Query.join(), когда иным образом не устанавливается точка соединения - обычно по умолчанию «точкой соединения» является самая левая сущность в списке выбираемых сущностей объекта Query.

Типичный пример:

q = session.query(Address).select_from(User).\
    join(User.addresses).\
    filter(User.name == 'ed')

Что в SQL эквивалентно:

SELECT address.* FROM user
JOIN address ON user.id=address.user_id
WHERE user.name = :name_1

Параметры:

*from_obj – коллекция из одной или нескольких сущностей для применения к предложению FROM. Сущностями могут быть сопоставленные классы, объекты AliasedClass, объекты Mapper, а также основные элементы FromClause, такие как подзапросы.

См.также

Query.join()

Query.select_entity_from()

Select.select_from() - эквивалентный метод v2.

attribute sqlalchemy.orm.Query.selectable¶

Возвращает объект Select, испускаемый данным Query.

Используется для совместимости с inspect(), что эквивалентно:

query.enable_eagerloads(False).with_labels().statement

method sqlalchemy.orm.Query.set_label_style(style: SelectLabelStyle) → Self¶

Примените метки столбцов к возвращаемому значению Query.statement.

Указывает, что аксессор statement этого запроса должен возвращать оператор SELECT, который применяет метки ко всем столбцам в форме <tablename>_<columnname>; это обычно используется для разотождествления столбцов из нескольких таблиц, имеющих одинаковые имена.

Когда Query фактически выдает SQL для загрузки строк, он всегда использует маркировку столбцов.

Примечание

Метод Query.set_label_style() только применяет вывод Query.statement, и не ни к одной из систем вызова строки результата самого Query, например, Query.first(), Query.all() и т.д. Чтобы выполнить запрос с помощью Query.set_label_style(), вызовите Query.statement с помощью Session.execute():

result = session.execute(
    query
    .set_label_style(LABEL_STYLE_TABLENAME_PLUS_COL)
    .statement
)

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

См.также

Select.set_label_style() - эквивалентный метод v2.

method sqlalchemy.orm.Query.slice(start: int, stop: int) → Self¶

Вычисляет «срез» Query, представленный заданными индексами, и возвращает полученный Query.

Индексы start и stop ведут себя как аргументы встроенной в Python функции range(). Этот метод является альтернативой использованию LIMIT/OFFSET для получения фрагмента запроса.

Например,

session.query(User).order_by(User.id).slice(1, 3)

отображается как

SELECT users.id AS users_id,
       users.name AS users_name
FROM users ORDER BY users.id
LIMIT ? OFFSET ?
(2, 1)

См.также

Query.limit()

Query.offset()

Select.slice() - эквивалентный метод v2.

attribute sqlalchemy.orm.Query.statement¶

Полный оператор SELECT, представленный данным запросом.

По умолчанию к конструкции statement не будут применены дезамбигирующие метки, если только сначала не будет вызвана функция with_labels(True).

method sqlalchemy.orm.Query.subquery(name: Optional[str] = None, with_labels: bool = False, reduce_columns: bool = False) → Subquery¶

Возвращает полный оператор SELECT, представленный данным Query, вложенный в Alias.

Генерация Eager JOIN внутри запроса отключена.

См.также

Select.subquery() - v2 сопоставимый метод.

Параметры:

• name – строковое имя, которое будет назначено в качестве псевдонима; оно передается через FromClause.alias(). Если None, то имя будет детерминированно сгенерировано во время компиляции.

• with_labels – если True, то with_labels() будет вызван на Query первым для применения табличных меток ко всем столбцам.

• reduce_columns – если True, то в результирующей конструкции select() будет вызвана функция Select.reduce_columns() для удаления одноименных столбцов, если один из них ссылается на другой через эквивалентность внешнего ключа или предложения WHERE.

method sqlalchemy.orm.Query.suffix_with(*suffixes: _TextCoercedExpressionArgument[Any], dialect: str = '*') → Self¶

наследуется от HasSuffixes.suffix_with() метода HasSuffixes

Добавьте одно или несколько выражений, следующих за высказыванием в целом.

Это используется для поддержки суффиксных ключевых слов, специфичных для бэкенда, в некоторых конструкциях.

Например:

stmt = select(col1, col2).cte().suffix_with(
    "cycle empno set y_cycle to 1 default 0", dialect="oracle")

Несколько суффиксов могут быть заданы несколькими обращениями к HasSuffixes.suffix_with().

Параметры:

• *suffixes – текстовая или ClauseElement конструкция, которая будет выведена после целевой клаузы.

• dialect – Необязательное строковое имя диалекта, которое ограничивает отображение данного суффикса только этим диалектом.

method sqlalchemy.orm.Query.tuples() → Query¶

возвращает кортежно-типизированную форму данного Query.

Этот метод вызывает метод Query.only_return_tuples() со значением True, что само по себе гарантирует, что этот Query всегда будет возвращать Row объекты, даже если запрос выполняется к одной сущности. Кроме того, на уровне типизации он будет возвращать «типизированный» запрос, если это возможно, который будет выводить строки результатов как Tuple объекты с типизированными элементами.

Этот метод можно сравнить с методом Result.tuples(), который возвращает «self», но с точки зрения типизации возвращает объект, который будет давать типизированные объекты Tuple для результатов. Типизация действует только в том случае, если этот объект Query уже является типизированным объектом запроса.

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

См.также

Result.tuples() - эквивалентный метод v2.

method sqlalchemy.orm.Query.union(*q: Query) → Self¶

Произвести СОЕДИНЕНИЕ данного запроса с одним или несколькими запросами.

например:

q1 = sess.query(SomeClass).filter(SomeClass.foo=='bar')
q2 = sess.query(SomeClass).filter(SomeClass.bar=='foo')

q3 = q1.union(q2)

Метод принимает несколько объектов Query, что позволяет контролировать уровень вложенности. Серия вызовов union(), таких как:

x.union(y).union(z).all()

будет гнездиться на каждом union(), а производит:

SELECT * FROM (SELECT * FROM (SELECT * FROM X UNION
                SELECT * FROM y) UNION SELECT * FROM Z)

Где:

x.union(y, z).all()

производит:

SELECT * FROM (SELECT * FROM X UNION SELECT * FROM y UNION
                SELECT * FROM Z)

Обратите внимание, что многие базы данных не позволяют отображать ORDER BY в запросе, вызванном в рамках UNION, EXCEPT и т.д. Чтобы отключить все клаузулы ORDER BY, включая те, которые настроены на мапперах, выдайте query.order_by(None) - результирующий объект Query не будет отображать ORDER BY в своем операторе SELECT.

См.также

Select.union() - эквивалентный метод v2.

method sqlalchemy.orm.Query.union_all(*q: Query) → Self¶

Произвести UNION ALL данного запроса по отношению к одному или нескольким запросам.

Работает так же, как и Query.union(). Примеры использования см. в этом методе.

См.также

Select.union_all() - эквивалентный метод v2.

method sqlalchemy.orm.Query.update(values: Dict[_DMLColumnArgument, Any], synchronize_session: SynchronizeSessionArgument = 'auto', update_args: Optional[Dict[Any, Any]] = None) → int¶

Выполните UPDATE с произвольным предложением WHERE.

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

Например:

sess.query(User).filter(User.age == 25).\
    update({User.age: User.age - 10}, synchronize_session=False)

sess.query(User).filter(User.age == 25).\
    update({"age": User.age - 10}, synchronize_session='evaluate')

Предупреждение

В разделе Операции INSERT, UPDATE и DELETE с поддержкой ORM приведены важные предостережения и предупреждения, в том числе ограничения при использовании произвольных конфигураций UPDATE и DELETE с наследованием mapper.

Параметры:

• values – словарь, в котором в качестве ключей используются имена атрибутов, или, как вариант, сопоставленные атрибуты или SQL-выражения, а в качестве значений - литеральные значения или sql-выражения. При желании parameter-ordered mode значения могут быть переданы в виде списка из двух кортежей; для этого необходимо, чтобы в словарь Query.update.update_args также был передан флаг update.preserve_parameter_order.

• synchronize_session – выбирает стратегию обновления атрибутов объектов в сессии. Обсуждение этих стратегий см. в разделе Операции INSERT, UPDATE и DELETE с поддержкой ORM.

• update_args – Необязательный словарь, если он присутствует, то будет передан в базовую конструкцию update() в качестве **kw для объекта. Может использоваться для передачи специфических для диалекта аргументов, таких как mysql_limit, а также других специальных аргументов, таких как update.preserve_parameter_order.

Результат:

количество совпавших строк, возвращаемое функцией «row count» базы данных.

См.также

Операции INSERT, UPDATE и DELETE с поддержкой ORM

method sqlalchemy.orm.Query.value(column: _ColumnExpressionArgument[Any]) → Any¶

Возвращает скалярный результат, соответствующий заданному выражению столбца.

Не рекомендуется, начиная с версии 1.4: Query.value() является устаревшим и будет удален в одном из будущих выпусков. Пожалуйста, используйте Query.with_entities() в сочетании с Query.scalar()

method sqlalchemy.orm.Query.values(*columns: _ColumnsClauseArgument[Any]) → Iterable[Any]¶

Возвращает итератор, содержащий кортежи результатов, соответствующие заданному списку столбцов

Не рекомендуется, начиная с версии 1.4: Query.values() является устаревшим и будет удален в будущем релизе. Пожалуйста, используйте Query.with_entities()

method sqlalchemy.orm.Query.where(*criterion: _ColumnExpressionArgument[bool]) → Self¶

Синоним для Query.filter().

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

См.также

Select.where() - эквивалентный метод v2.

attribute sqlalchemy.orm.Query.whereclause¶

Атрибут, доступный только для чтения, который возвращает текущий критерий WHERE для данного запроса.

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

См.также

Select.whereclause - эквивалентное свойство v2.

method sqlalchemy.orm.Query.with_entities(*entities: _ColumnsClauseArgument[Any], **_Query__kw: Any) → Query[Any]¶

Возвращает новый Query, заменяющий список SELECT заданными сущностями.

например:

# Users, filtered on some arbitrary criterion
# and then ordered by related email address
q = session.query(User).\
            join(User.address).\
            filter(User.name.like('%ed%')).\
            order_by(Address.email)

# given *only* User.id==5, Address.email, and 'q', what
# would the *next* User in the result be ?
subq = q.with_entities(Address.email).\
            order_by(None).\
            filter(User.id==5).\
            subquery()
q = q.join((subq, subq.c.email < Address.email)).\
            limit(1)

См.также

Select.with_only_columns() - v2 сопоставимый метод.

method sqlalchemy.orm.Query.with_for_update(*, nowait: bool = False, read: bool = False, of: Optional[Union[_ColumnExpressionArgument[Any], Sequence[_ColumnExpressionArgument[Any]]]] = None, skip_locked: bool = False, key_share: bool = False) → Self¶

возвращает новый Query с указанными параметрами для пункта FOR UPDATE.

Поведение этого метода идентично поведению GenerativeSelect.with_for_update(). При вызове без аргументов в результирующий оператор SELECT будет добавлена клаузула FOR UPDATE. При указании дополнительных аргументов могут быть использованы опции, специфичные для бэкенда, такие как FOR UPDATE NOWAIT или LOCK IN SHARE MODE.

Например:

q = sess.query(User).populate_existing().with_for_update(nowait=True, of=User)

Приведенный выше запрос на бэкенде PostgreSQL будет выглядеть так:

SELECT users.id AS users_id FROM users FOR UPDATE OF users NOWAIT

Предупреждение

Использование with_for_update в контексте отношений с нетерпеливой загрузкой официально не поддерживается и не рекомендуется SQLAlchemy и может не работать с некоторыми запросами на различных платформах баз данных. При успешном использовании with_for_update в запросе, включающем joinedload(), SQLAlchemy попытается выдать SQL, блокирующий все задействованные таблицы.

Примечание

Как правило, использование метода Query.populate_existing() при использовании метода Query.with_for_update() является хорошей идеей. Цель Query.populate_existing() - заставить все данные, прочитанные из SELECT, заполнить возвращаемые ORM-объекты, даже если эти объекты уже находятся в identity map.

См.также

GenerativeSelect.with_for_update() - Метод базового уровня с полным описанием аргументов и поведения.

Query.populate_existing() - перезаписывает атрибуты объектов, уже загруженных в карту идентификации.

method sqlalchemy.orm.Query.with_hint(selectable: _FromClauseArgument, text: str, dialect_name: str = '*') → Self¶

наследуется от HasHints.with_hint() метода HasHints

Добавляет в данный Select или другой объект selectable подсказку индексации или другого контекста выполнения для данного selectable.

Текст подсказки отображается в соответствующем для используемого бэкенда базы данных месте относительно заданного аргумента Table или Alias, переданного в качестве аргумента selectable. Реализация диалекта обычно использует синтаксис подстановки строк Python с маркером %(name)s для отображения имени таблицы или псевдонима. Например, при использовании Oracle можно использовать следующее:

select(mytable).\
    with_hint(mytable, "index(%(name)s ix_mytable)")

SQL будет выглядеть так:

select /*+ index(mytable ix_mytable) */ ... from mytable

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

select(mytable).\
    with_hint(mytable, "index(%(name)s ix_mytable)", 'oracle').\
    with_hint(mytable, "WITH INDEX ix_mytable", 'mssql')

См.также

Select.with_statement_hint()

method sqlalchemy.orm.Query.with_labels() → Self¶

Не рекомендуется, начиная с версии 2.0: Метод Query.with_labels() и Query.apply_labels() считается унаследованным от серии SQLAlchemy 1.x и становится унаследованной конструкцией в версии 2.0. Вместо этого используйте set_label_style(LABEL_STYLE_TABLENAME_PLUS_COL). (Справочная информация по SQLAlchemy 2.0 на сайте: SQLAlchemy 2.0 - руководство по миграции)

method sqlalchemy.orm.Query.with_parent(instance: object, property: Optional[attributes.QueryableAttribute[Any]] = None, from_entity: Optional[_ExternalEntityType[Any]] = None) → Self¶

Добавьте критерий фильтрации, который связывает данный экземпляр с дочерним объектом или коллекцией, используя состояние его атрибутов, а также установленную конфигурацию relationship().

Не рекомендуется, начиная с версии 2.0: Метод Query.with_parent() считается унаследованным от серии 1.x SQLAlchemy и становится унаследованной конструкцией в версии 2.0. Используйте самостоятельную конструкцию with_parent(). (Справочная информация по SQLAlchemy 2.0 на сайте: SQLAlchemy 2.0 - руководство по миграции)

Метод использует функцию with_parent() для генерации клаузулы, результат которой передается в Query.filter().

Параметры те же, что и у with_parent(), за исключением того, что заданное свойство может быть None, в этом случае поиск выполняется по целевому мапперу данного объекта Query.

Параметры:

• instance – Экземпляр, который имеет некоторое relationship().

• property – Атрибут, связанный с классом, который указывает, какое отношение из экземпляра должно быть использовано для согласования отношений родитель/ребенок.

• from_entity – Сущность, которую следует рассматривать в качестве левой стороны. По умолчанию это «нулевая» сущность самого Query.

method sqlalchemy.orm.Query.with_session(session: Session) → Self¶

Возвращает Query, который будет использовать заданный Session.

Хотя объект Query обычно инстанцируется с помощью метода Session.query(), вполне допустимо построить Query напрямую, не обязательно используя Session. Такой объект Query или любой Query, уже связанный с другим Session, может создать новый объект Query, связанный с целевой сессией, используя этот метод:

from sqlalchemy.orm import Query

query = Query([MyClass]).filter(MyClass.id == 5)

result = query.with_session(my_session).one()

method sqlalchemy.orm.Query.with_statement_hint(text: str, dialect_name: str = '*') → Self¶

наследуется от HasHints.with_statement_hint() метода HasHints

Добавляет подсказку утверждения к данному Select или другому выбираемому объекту.

Этот метод аналогичен методу Select.with_hint(), за исключением того, что он не требует отдельной таблицы, а применяется ко всему высказыванию в целом.

Подсказки здесь специфичны для внутренней базы данных и могут включать такие директивы, как уровни изоляции, файловые директивы, директивы выборки и т.д.

См.также

Select.with_hint()

Select.prefix_with() - общий префикс SELECT, который также может подходить для некоторых специфических для базы данных синтаксисов HINT, таких как подсказки оптимизатора MySQL

method sqlalchemy.orm.Query.with_transformation(fn: Callable[[Query], Query]) → Query¶

Возвращает новый объект Query, преобразованный заданной функцией.

Например:

def filter_something(criterion):
    def transform(q):
        return q.filter(criterion)
    return transform

q = q.with_transformation(filter_something(x==5))

Это позволяет создавать специальные рецепты для объектов Query.

method sqlalchemy.orm.Query.yield_per(count: int) → Self¶

Одновременно выдавать только count строк.

Цель этого метода - при получении очень больших наборов результатов (> 10 тыс. строк) объединять результаты в подколлекции и выдавать их частично, чтобы интерпретатору Python не приходилось объявлять очень большие области памяти, что отнимает много времени и приводит к чрезмерному расходу памяти. Производительность при получении сотен тысяч строк часто может удвоиться, если использовать подходящее значение yield-per (например, около 1000), даже при использовании DBAPI, буферизирующих строки (которых большинство).

Начиная с версии SQLAlchemy 1.4, метод Query.yield_per() эквивалентен использованию опции выполнения yield_per на уровне ORM. Подробнее об этой опции см. в разделе Получение больших наборов результатов с доходностью за.

См.также

Получение больших наборов результатов с доходностью за

Конструкции запросов, специфичные для ORM¶

Этот раздел переместился в Дополнительные конструкции ORM API.