Справочник оператора¶

Операторы сравнения¶

Базовые сравнения, которые применяются ко многим типам данных, включая числа, строки, даты и многие другие:

• ColumnOperators.__eq__() (оператор Python «==»):

  >>> print(column("x") == 5)
  {printsql}x = :x_1

• ColumnOperators.__ne__() (оператор Python «!=»):

  >>> print(column("x") != 5)
  {printsql}x != :x_1

• ColumnOperators.__gt__() (оператор Python «>»):

  >>> print(column("x") > 5)
  {printsql}x > :x_1

• ColumnOperators.__lt__() (оператор Python «<»):

  >>> print(column("x") < 5)
  {printsql}x < :x_1

• ColumnOperators.__ge__() (оператор Python «>=»):

  >>> print(column("x") >= 5)
  {printsql}x >= :x_1

• ColumnOperators.__le__() (оператор Python «<=»):

  >>> print(column("x") <= 5)
  {printsql}x <= :x_1

• ColumnOperators.between():

  >>> print(column("x").between(5, 10))
  {printsql}x BETWEEN :x_1 AND :x_2

Сравнения IN¶

Оператор SQL IN - это отдельная тема в SQLAlchemy. Поскольку оператор IN обычно используется против списка фиксированных значений, функция SQLAlchemy по принуждению связанных параметров использует специальную форму компиляции SQL, которая выдает промежуточную строку SQL для компиляции, которая формируется в окончательный список связанных параметров на втором этапе. Другими словами, «это просто работает».

>>> print(column("x").in_([1, 2, 3]))
{printsql}x IN (__[POSTCOMPILE_x_1])

>>> stmt = select(User.id).where(User.id.in_([1, 2, 3]))
>>> result = conn.execute(stmt)
{execsql}SELECT user_account.id
FROM user_account
WHERE user_account.id IN (?, ?, ?)
[...] (1, 2, 3){stop}

>>> stmt = select(User.id).where(User.id.in_([]))
>>> result = conn.execute(stmt)
{execsql}SELECT user_account.id
FROM user_account
WHERE user_account.id IN (SELECT 1 FROM (SELECT 1) WHERE 1!=1)
[...] ()

>>> print(column("x").not_in([1, 2, 3]))
{printsql}(x NOT IN (__[POSTCOMPILE_x_1]))

>>> print(~column("x").in_([1, 2, 3]))
{printsql}(x NOT IN (__[POSTCOMPILE_x_1]))

>>> from sqlalchemy import tuple_
>>> tup = tuple_(column("x", Integer), column("y", Integer))
>>> expr = tup.in_([(1, 2), (3, 4)])
>>> print(expr)
{printsql}(x, y) IN (__[POSTCOMPILE_param_1])

>>> tup = tuple_(User.id, Address.id)
>>> stmt = select(User.name).join(Address).where(tup.in_([(1, 1), (2, 2)]))
>>> conn.execute(stmt).all()
{execsql}SELECT user_account.name
FROM user_account JOIN address ON user_account.id = address.user_id
WHERE (user_account.id, address.id) IN (VALUES (?, ?), (?, ?))
[...] (1, 1, 2, 2){stop}
[('spongebob',), ('sandy',)]

>>> print(column("x").in_(select(user_table.c.id)))
{printsql}x IN (SELECT user_account.id
FROM user_account)

>>> print(
...     tuple_(column("x"), column("y")).in_(
...         select(user_table.c.id, address_table.c.id).join(address_table)
...     )
... )
{printsql}(x, y) IN (SELECT user_account.id, address.id
FROM user_account JOIN address ON user_account.id = address.user_id)

Сравнения идентичностей¶

Эти операторы включают проверку на специальные значения SQL, такие как NULL, булевы константы, такие как true или false, которые поддерживаются некоторыми базами данных:

• ColumnOperators.is_():

  Этот оператор предоставляет SQL для «x IS y», который чаще всего выглядит как «<expr> IS NULL». Константу NULL проще всего получить с помощью обычного Python None:

  >>> print(column("x").is_(None))
  {printsql}x IS NULL

  SQL NULL также доступен в явном виде, если это необходимо, с помощью конструкции null():

  >>> from sqlalchemy import null
  >>> print(column("x").is_(null()))
  {printsql}x IS NULL

  Оператор ColumnOperators.is_() автоматически вызывается при использовании перегруженного оператора ColumnOperators.__eq__(), то есть ==, в сочетании со значением None или null(). Таким образом, обычно нет необходимости использовать ColumnOperators.is_() явно, особенно при использовании с динамическим значением:

  >>> a = None
  >>> print(column("x") == a)
  {printsql}x IS NULL

  Обратите внимание, что оператор Python is является не перегруженным. Хотя Python предоставляет крючки для перегрузки таких операторов, как == и !=, он не предоставляет никакого способа переопределить is.

• ColumnOperators.is_not():

  Аналогично ColumnOperators.is_(), выдает «IS NOT»:

  >>> print(column("x").is_not(None))
  {printsql}x IS NOT NULL

  Аналогично эквивалентен != None:

  >>> print(column("x") != None)
  {printsql}x IS NOT NULL

• ColumnOperators.is_distinct_from():

  Производит SQL IS DISTINCT FROM:

  >>> print(column("x").is_distinct_from("some value"))
  {printsql}x IS DISTINCT FROM :x_1

• ColumnOperators.isnot_distinct_from():

  Выдает SQL IS NOT DISTINCT FROM:

  >>> print(column("x").isnot_distinct_from("some value"))
  {printsql}x IS NOT DISTINCT FROM :x_1

Сравнение строк¶

• ColumnOperators.like():

  >>> print(column("x").like("word"))
  {printsql}x LIKE :x_1

• ColumnOperators.ilike():

  Нечувствительный к регистру LIKE использует функцию SQL lower() на общем бэкенде. На бэкенде PostgreSQL она будет использовать ILIKE:

  >>> print(column("x").ilike("word"))
  {printsql}lower(x) LIKE lower(:x_1)

• ColumnOperators.notlike():

  >>> print(column("x").notlike("word"))
  {printsql}x NOT LIKE :x_1

• ColumnOperators.notilike():

  >>> print(column("x").notilike("word"))
  {printsql}lower(x) NOT LIKE lower(:x_1)

Сдерживание строк¶

Операторы сдерживания строк в основном построены как комбинация LIKE и оператора конкатенации строк, который в большинстве бэкендов представляет собой || или иногда функцию типа concat():

• ColumnOperators.startswith():

  >>> print(column("x").startswith("word"))
  {printsql}x LIKE :x_1 || '%'

• ColumnOperators.endswith():

  >>> print(column("x").endswith("word"))
  {printsql}x LIKE '%' || :x_1

• ColumnOperators.contains():

  >>> print(column("x").contains("word"))
  {printsql}x LIKE '%' || :x_1 || '%'

Сопоставление строк¶

Операторы сопоставления всегда зависят от бэкенда и могут давать разное поведение и результаты в разных базах данных:

• ColumnOperators.match():

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

  >>> print(column("x").match("word"))
  {printsql}x MATCH :x_1

• ColumnOperators.regexp_match():

  Этот оператор зависит от диалекта. Мы можем проиллюстрировать его, например, на примере диалекта PostgreSQL:

  >>> from sqlalchemy.dialects import postgresql
  >>> print(column("x").regexp_match("word").compile(dialect=postgresql.dialect()))
  {printsql}x ~ %(x_1)s

  Или MySQL:

  >>> from sqlalchemy.dialects import mysql
  >>> print(column("x").regexp_match("word").compile(dialect=mysql.dialect()))
  {printsql}x REGEXP %s

Изменение строк¶

• ColumnOperators.concat():

  Конкатенация строк:

  >>> print(column("x").concat("some string"))
  {printsql}x || :x_1

  Этот оператор доступен через ColumnOperators.__add__(), то есть оператор Python +, при работе с выражением столбца, которое является производным от String:

  >>> print(column("x", String) + "some string")
  {printsql}x || :x_1

  Оператор будет выдавать соответствующую специфическую для базы данных конструкцию, например, в MySQL это исторически была SQL-функция concat():

  >>> print((column("x", String) + "some string").compile(dialect=mysql.dialect()))
  {printsql}concat(x, %s)

• ColumnOperators.regexp_replace():

  Дополнением к ColumnOperators.regexp() является эквивалент REGEXP REPLACE для бэкендов, которые его поддерживают:

  >>> print(column("x").regexp_replace("foo", "bar").compile(dialect=postgresql.dialect()))
  {printsql}REGEXP_REPLACE(x, %(x_1)s, %(x_2)s)

• ColumnOperators.collate():

  Производит SQL-оператор COLLATE, который обеспечивает определенные колляции во время выражения:

  >>> print(
  ...     (column("x").collate("latin1_german2_ci") == "Müller").compile(
  ...         dialect=mysql.dialect()
  ...     )
  ... )
  {printsql}(x COLLATE latin1_german2_ci) = %s

  Чтобы использовать COLLATE против буквального значения, используйте конструкцию literal():

  >>> from sqlalchemy import literal
  >>> print(
  ...     (literal("Müller").collate("latin1_german2_ci") == column("x")).compile(
  ...         dialect=mysql.dialect()
  ...     )
  ... )
  {printsql}(%s COLLATE latin1_german2_ci) = x

Арифметические операторы¶

• ColumnOperators.__add__(), ColumnOperators.__radd__() (оператор Python «+»):

  >>> print(column("x") + 5)
  {printsql}x + :x_1{stop}
  
  >>> print(5 + column("x"))
  {printsql}:x_1 + x{stop}

  Обратите внимание, что если тип данных выражения String или аналогичный, оператор ColumnOperators.__add__() вместо него выдает string concatenation.

• ColumnOperators.__sub__(), ColumnOperators.__rsub__() (оператор Python «-«):

  >>> print(column("x") - 5)
  {printsql}x - :x_1{stop}
  
  >>> print(5 - column("x"))
  {printsql}:x_1 - x{stop}

• ColumnOperators.__mul__(), ColumnOperators.__rmul__() (оператор Python «*»):

  >>> print(column("x") * 5)
  {printsql}x * :x_1{stop}
  
  >>> print(5 * column("x"))
  {printsql}:x_1 * x{stop}

• ColumnOperators.__truediv__(), ColumnOperators.__rtruediv__() (оператор Python «/»). Это оператор Python truediv, который обеспечит целочисленное истинное деление:

  >>> print(column("x") / 5)
  {printsql}x / CAST(:x_1 AS NUMERIC){stop}
  >>> print(5 / column("x"))
  {printsql}:x_1 / CAST(x AS NUMERIC){stop}

  Изменено в версии 2.0: Оператор Python / теперь обеспечивает целочисленное истинное деление

• ColumnOperators.__floordiv__(), ColumnOperators.__rfloordiv__() (оператор Python «//»). Это оператор Python floordiv, который обеспечивает деление на пол. Для бэкенда по умолчанию, а также таких бэкендов, как PostgreSQL, оператор SQL / обычно ведет себя так для целочисленных значений:

  >>> print(column("x") // 5)
  {printsql}x / :x_1{stop}
  >>> print(5 // column("x", Integer))
  {printsql}:x_1 / x{stop}

  Для бэкендов, которые не используют деление на пол по умолчанию, или при использовании с числовыми значениями, функция FLOOR() используется для обеспечения деления на пол:

  >>> print(column("x") // 5.5)
  {printsql}FLOOR(x / :x_1){stop}
  >>> print(5 // column("x", Numeric))
  {printsql}FLOOR(:x_1 / x){stop}

  Добавлено в версии 2.0: Поддержка разделения FLOOR

• ColumnOperators.__mod__(), ColumnOperators.__rmod__() (оператор Python «%»):

  >>> print(column("x") % 5)
  {printsql}x % :x_1{stop}
  >>> print(5 % column("x"))
  {printsql}:x_1 % x{stop}

Побитовые операторы¶

Функции побитовых операторов обеспечивают единообразный доступ к побитовым операторам для различных бэкендов, которые, как ожидается, будут работать с совместимыми значениями, такими как целые числа и битовые строки (например, PostgreSQL BIT и подобные). Обратите внимание, что это не общие булевы операторы.

• ColumnOperators.bitwise_not(), bitwise_not(). Доступен как метод на уровне столбцов, производящий побитовое предложение NOT по отношению к родительскому объекту:

  >>> print(column("x").bitwise_not())
  ~x

  Этот оператор также доступен как метод на уровне выражений столбцов, применяя побитовое NOT к выражению отдельного столбца:

  >>> from sqlalchemy import bitwise_not
  >>> print(bitwise_not(column("x")))
  ~x

• ColumnOperators.bitwise_and() производит побитовое AND:

  >>> print(column("x").bitwise_and(5))
  x & :x_1

• ColumnOperators.bitwise_or() производит побитовое ИЛИ:

  >>> print(column("x").bitwise_or(5))
  x | :x_1

• ColumnOperators.bitwise_xor() производит побитовый XOR:

  >>> print(column("x").bitwise_xor(5))
  x ^ :x_1

  Для диалектов PostgreSQL символ «#» используется для представления побитового XOR; он автоматически появляется при использовании одного из этих бэкендов:

  >>> from sqlalchemy.dialects import postgresql
  >>> print(column("x").bitwise_xor(5).compile(dialect=postgresql.dialect()))
  x # %(x_1)s

• ColumnOperators.bitwise_rshift(), ColumnOperators.bitwise_lshift() производят побитовые операторы сдвига:

  >>> print(column("x").bitwise_rshift(5))
  x >> :x_1
  >>> print(column("x").bitwise_lshift(5))
  x << :x_1

Использование конъюнкции и отрицания¶

Самая распространенная связка, «AND», применяется автоматически, если мы неоднократно используем метод Select.where(), а также аналогичные методы, такие как Update.where() и Delete.where():

>>> print(
...     select(address_table.c.email_address)
...     .where(user_table.c.name == "squidward")
...     .where(address_table.c.user_id == user_table.c.id)
... )
{printsql}SELECT address.email_address
FROM address, user_account
WHERE user_account.name = :name_1 AND address.user_id = user_account.id

Select.where(), Update.where() и Delete.where() также принимают несколько выражений с тем же эффектом:

>>> print(
...     select(address_table.c.email_address).where(
...         user_table.c.name == "squidward",
...         address_table.c.user_id == user_table.c.id,
...     )
... )
{printsql}SELECT address.email_address
FROM address, user_account
WHERE user_account.name = :name_1 AND address.user_id = user_account.id

Конъюнкция «AND», как и ее партнер «OR», доступны непосредственно с помощью функций and_() и or_():

>>> from sqlalchemy import and_, or_
>>> print(
...     select(address_table.c.email_address).where(
...         and_(
...             or_(user_table.c.name == "squidward", user_table.c.name == "sandy"),
...             address_table.c.user_id == user_table.c.id,
...         )
...     )
... )
{printsql}SELECT address.email_address
FROM address, user_account
WHERE (user_account.name = :name_1 OR user_account.name = :name_2)
AND address.user_id = user_account.id

Отрицание доступно с помощью функции not_(). Обычно это инвертирует оператор в булевом выражении:

>>> from sqlalchemy import not_
>>> print(not_(column("x") == 5))
{printsql}x != :x_1

Он также может применить ключевое слово, такое как NOT, когда это уместно:

>>> from sqlalchemy import Boolean
>>> print(not_(column("x", Boolean)))
{printsql}NOT x

Операторы конъюнкции¶

Приведенные выше функции конъюнкции and_(), or_(), not_() также доступны как перегруженные операторы Python:

• Operators.__and__() (оператор Python «&»):

  Бинарный оператор Python & перегружен, чтобы вести себя так же, как and_() (обратите внимание на скобки вокруг двух операндов):

  >>> print((column("x") == 5) & (column("y") == 10))
  {printsql}x = :x_1 AND y = :y_1

• Operators.__or__() (оператор Python «|»):

  Бинарный оператор Python | перегружен, чтобы вести себя так же, как or_() (обратите внимание на скобки вокруг двух операндов):

  >>> print((column("x") == 5) | (column("y") == 10))
  {printsql}x = :x_1 OR y = :y_1

• Operators.__invert__() (оператор Python «~»):

  Бинарный оператор Python ~ перегружен, чтобы вести себя так же, как not_(), либо инвертируя существующий оператор, либо применяя ключевое слово NOT к выражению в целом:

  >>> print(~(column("x") == 5))
  {printsql}x != :x_1{stop}
  
  >>> from sqlalchemy import Boolean
  >>> print(~column("x", Boolean))
  {printsql}NOT x{stop}