You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
141 lines
3.8 KiB
141 lines
3.8 KiB
# sql/_dml_constructors.py
|
|
# Copyright (C) 2005-2023 the SQLAlchemy authors and contributors
|
|
# <see AUTHORS file>
|
|
#
|
|
# This module is part of SQLAlchemy and is released under
|
|
# the MIT License: https://www.opensource.org/licenses/mit-license.php
|
|
|
|
from __future__ import annotations
|
|
|
|
from typing import TYPE_CHECKING
|
|
|
|
from .dml import Delete
|
|
from .dml import Insert
|
|
from .dml import Update
|
|
|
|
if TYPE_CHECKING:
|
|
from ._typing import _DMLTableArgument
|
|
|
|
|
|
def insert(table: _DMLTableArgument) -> Insert:
|
|
"""Construct an :class:`_expression.Insert` object.
|
|
|
|
E.g.::
|
|
|
|
from sqlalchemy import insert
|
|
|
|
stmt = (
|
|
insert(user_table).
|
|
values(name='username', fullname='Full Username')
|
|
)
|
|
|
|
Similar functionality is available via the
|
|
:meth:`_expression.TableClause.insert` method on
|
|
:class:`_schema.Table`.
|
|
|
|
.. seealso::
|
|
|
|
:ref:`tutorial_core_insert` - in the :ref:`unified_tutorial`
|
|
|
|
|
|
:param table: :class:`_expression.TableClause`
|
|
which is the subject of the
|
|
insert.
|
|
|
|
:param values: collection of values to be inserted; see
|
|
:meth:`_expression.Insert.values`
|
|
for a description of allowed formats here.
|
|
Can be omitted entirely; a :class:`_expression.Insert` construct
|
|
will also dynamically render the VALUES clause at execution time
|
|
based on the parameters passed to :meth:`_engine.Connection.execute`.
|
|
|
|
:param inline: if True, no attempt will be made to retrieve the
|
|
SQL-generated default values to be provided within the statement;
|
|
in particular,
|
|
this allows SQL expressions to be rendered 'inline' within the
|
|
statement without the need to pre-execute them beforehand; for
|
|
backends that support "returning", this turns off the "implicit
|
|
returning" feature for the statement.
|
|
|
|
If both :paramref:`_expression.insert.values` and compile-time bind
|
|
parameters are present, the compile-time bind parameters override the
|
|
information specified within :paramref:`_expression.insert.values` on a
|
|
per-key basis.
|
|
|
|
The keys within :paramref:`_expression.Insert.values` can be either
|
|
:class:`~sqlalchemy.schema.Column` objects or their string
|
|
identifiers. Each key may reference one of:
|
|
|
|
* a literal data value (i.e. string, number, etc.);
|
|
* a Column object;
|
|
* a SELECT statement.
|
|
|
|
If a ``SELECT`` statement is specified which references this
|
|
``INSERT`` statement's table, the statement will be correlated
|
|
against the ``INSERT`` statement.
|
|
|
|
.. seealso::
|
|
|
|
:ref:`tutorial_core_insert` - in the :ref:`unified_tutorial`
|
|
|
|
"""
|
|
return Insert(table)
|
|
|
|
|
|
def update(table: _DMLTableArgument) -> Update:
|
|
r"""Construct an :class:`_expression.Update` object.
|
|
|
|
E.g.::
|
|
|
|
from sqlalchemy import update
|
|
|
|
stmt = (
|
|
update(user_table).
|
|
where(user_table.c.id == 5).
|
|
values(name='user #5')
|
|
)
|
|
|
|
Similar functionality is available via the
|
|
:meth:`_expression.TableClause.update` method on
|
|
:class:`_schema.Table`.
|
|
|
|
:param table: A :class:`_schema.Table`
|
|
object representing the database
|
|
table to be updated.
|
|
|
|
|
|
.. seealso::
|
|
|
|
:ref:`tutorial_core_update_delete` - in the :ref:`unified_tutorial`
|
|
|
|
|
|
"""
|
|
return Update(table)
|
|
|
|
|
|
def delete(table: _DMLTableArgument) -> Delete:
|
|
r"""Construct :class:`_expression.Delete` object.
|
|
|
|
E.g.::
|
|
|
|
from sqlalchemy import delete
|
|
|
|
stmt = (
|
|
delete(user_table).
|
|
where(user_table.c.id == 5)
|
|
)
|
|
|
|
Similar functionality is available via the
|
|
:meth:`_expression.TableClause.delete` method on
|
|
:class:`_schema.Table`.
|
|
|
|
:param table: The table to delete rows from.
|
|
|
|
.. seealso::
|
|
|
|
:ref:`tutorial_core_update_delete` - in the :ref:`unified_tutorial`
|
|
|
|
|
|
"""
|
|
return Delete(table)
|