diff options
| author | mike bayer <mike_mp@zzzcomputing.com> | 2020-06-10 22:03:37 +0000 |
|---|---|---|
| committer | Gerrit Code Review <gerrit@bbpush.zzzcomputing.com> | 2020-06-10 22:03:37 +0000 |
| commit | 58dc9c00133e13e5690e686e680b8275f162aded (patch) | |
| tree | 82a3168341c21217dd2b2435c2c8ccc6246a0305 /doc | |
| parent | 2a2454a0ca42044301ca0c244b5074bd464359ca (diff) | |
| parent | b0cfa7379cf8513a821a3dbe3028c4965d9f85bd (diff) | |
| download | sqlalchemy-58dc9c00133e13e5690e686e680b8275f162aded.tar.gz | |
Merge "Turn on caching everywhere, add logging"
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/build/changelog/unreleased_14/bind_removed_from_compiler.rst | 8 | ||||
| -rw-r--r-- | doc/build/core/tutorial.rst | 110 | ||||
| -rw-r--r-- | doc/build/orm/tutorial.rst | 156 |
3 files changed, 141 insertions, 133 deletions
diff --git a/doc/build/changelog/unreleased_14/bind_removed_from_compiler.rst b/doc/build/changelog/unreleased_14/bind_removed_from_compiler.rst new file mode 100644 index 000000000..77c02f517 --- /dev/null +++ b/doc/build/changelog/unreleased_14/bind_removed_from_compiler.rst @@ -0,0 +1,8 @@ +.. change:: + :tags: change, engine + + Removed the concept of a bound engine from the :class:`.Compiler` object, + and removed the ``.execute()`` and ``.scalar()`` methods from :class:`.Compiler`. + These were essentially forgotten methods from over a decade ago and had no + practical use, and it's not appropriate for the :class:`.Compiler` object + itself to be maintaining a reference to an :class:`.Engine`. diff --git a/doc/build/core/tutorial.rst b/doc/build/core/tutorial.rst index a504f8578..7db84c7d6 100644 --- a/doc/build/core/tutorial.rst +++ b/doc/build/core/tutorial.rst @@ -157,7 +157,7 @@ each table first before creating, so it's safe to call multiple times: fullname VARCHAR, PRIMARY KEY (id) ) - () + [...] () COMMIT CREATE TABLE addresses ( id INTEGER NOT NULL, @@ -166,7 +166,7 @@ each table first before creating, so it's safe to call multiple times: PRIMARY KEY (id), FOREIGN KEY(user_id) REFERENCES users (id) ) - () + [...] () COMMIT .. note:: @@ -263,7 +263,7 @@ checked out DBAPI connection resource. Lets feed it our >>> result = conn.execute(ins) {opensql}INSERT INTO users (name, fullname) VALUES (?, ?) - ('jack', 'Jack Jones') + [...] ('jack', 'Jack Jones') COMMIT So the INSERT statement was now issued to the database. Although we got @@ -325,7 +325,7 @@ and use it in the "normal" way: >>> ins = users.insert() >>> conn.execute(ins, id=2, name='wendy', fullname='Wendy Williams') {opensql}INSERT INTO users (id, name, fullname) VALUES (?, ?, ?) - (2, 'wendy', 'Wendy Williams') + [...] (2, 'wendy', 'Wendy Williams') COMMIT {stop}<sqlalchemy.engine.cursor.LegacyCursorResult object at 0x...> @@ -349,7 +349,7 @@ inserted, as we do here to add some email addresses: ... {'user_id': 2, 'email_address' : 'wendy@aol.com'}, ... ]) {opensql}INSERT INTO addresses (user_id, email_address) VALUES (?, ?) - ((1, 'jack@yahoo.com'), (1, 'jack@msn.com'), (2, 'www@www.org'), (2, 'wendy@aol.com')) + [...] ((1, 'jack@yahoo.com'), (1, 'jack@msn.com'), (2, 'www@www.org'), (2, 'wendy@aol.com')) COMMIT {stop}<sqlalchemy.engine.cursor.LegacyCursorResult object at 0x...> @@ -384,7 +384,7 @@ statements is the :func:`_expression.select` function: >>> result = conn.execute(s) {opensql}SELECT users.id, users.name, users.fullname FROM users - () + [...] () Above, we issued a basic :func:`_expression.select` call, placing the ``users`` table within the COLUMNS clause of the select, and then executing. SQLAlchemy @@ -414,7 +414,7 @@ of these tuples as rows are fetched is through tuple assignment: {sql}>>> result = conn.execute(s) SELECT users.id, users.name, users.fullname FROM users - () + [...] () {stop}>>> for id, name, fullname in result: ... print("name:", name, "; fullname: ", fullname) @@ -430,7 +430,7 @@ access: {sql}>>> result = conn.execute(s) SELECT users.id, users.name, users.fullname FROM users - () + [...] () {stop}>>> for row in result: ... print("name:", row.name, "; fullname: ", row.fullname) @@ -446,7 +446,7 @@ progammatically generated, or contains non-ascii characters, the {sql}>>> result = conn.execute(s) SELECT users.id, users.name, users.fullname FROM users - () + [...] () {stop}>>> row = result.fetchone() >>> print("name:", row._mapping['name'], "; fullname:", row._mapping['fullname']) @@ -490,7 +490,7 @@ collection: ... print("name:", row._mapping[users.c.name], "; fullname:", row._mapping[users.c.fullname]) SELECT users.id, users.name, users.fullname FROM users - () + [...] () {stop}name: jack ; fullname: Jack Jones name: wendy ; fullname: Wendy Williams @@ -528,7 +528,7 @@ the ``c`` attribute of the :class:`~sqlalchemy.schema.Table` object: {sql}>>> result = conn.execute(s) SELECT users.name, users.fullname FROM users - () + [...] () {stop}>>> for row in result: ... print(row) (u'jack', u'Jack Jones') @@ -546,7 +546,7 @@ our :func:`_expression.select` statement: ... print(row) SELECT users.id, users.name, users.fullname, addresses.id, addresses.user_id, addresses.email_address FROM users, addresses - () + [...] () {stop}(1, u'jack', u'Jack Jones', 1, 1, u'jack@yahoo.com') (1, u'jack', u'Jack Jones', 2, 1, u'jack@msn.com') (1, u'jack', u'Jack Jones', 3, 2, u'www@www.org') @@ -571,7 +571,7 @@ WHERE clause. We do that using :meth:`_expression.Select.where`: addresses.user_id, addresses.email_address FROM users, addresses WHERE users.id = addresses.user_id - () + [...] () {stop}(1, u'jack', u'Jack Jones', 1, 1, u'jack@yahoo.com') (1, u'jack', u'Jack Jones', 2, 1, u'jack@msn.com') (2, u'wendy', u'Wendy Williams', 3, 2, u'www@www.org') @@ -801,7 +801,7 @@ not have a name: FROM users, addresses WHERE users.id = addresses.user_id AND users.name BETWEEN ? AND ? AND (addresses.email_address LIKE ? OR addresses.email_address LIKE ?) - (', ', 'm', 'z', '%@aol.com', '%@msn.com') + [...] (', ', 'm', 'z', '%@aol.com', '%@msn.com') {stop}[(u'Wendy Williams, wendy@aol.com',)] Once again, SQLAlchemy figured out the FROM clause for our statement. In fact @@ -830,7 +830,7 @@ A shortcut to using :func:`.and_` is to chain together multiple FROM users, addresses WHERE users.id = addresses.user_id AND users.name BETWEEN ? AND ? AND (addresses.email_address LIKE ? OR addresses.email_address LIKE ?) - (', ', 'm', 'z', '%@aol.com', '%@msn.com') + [...] (', ', 'm', 'z', '%@aol.com', '%@msn.com') {stop}[(u'Wendy Williams, wendy@aol.com',)] The way that we can build up a :func:`_expression.select` construct through successive @@ -865,7 +865,7 @@ unchanged. Below, we create a :func:`_expression.text` object and execute it: FROM users, addresses WHERE users.id = addresses.user_id AND users.name BETWEEN ? AND ? AND (addresses.email_address LIKE ? OR addresses.email_address LIKE ?) - ('m', 'z', '%@aol.com', '%@msn.com') + [...] ('m', 'z', '%@aol.com', '%@msn.com') {stop}[(u'Wendy Williams, wendy@aol.com',)] Above, we can see that bound parameters are specified in @@ -944,7 +944,7 @@ result column names in the textual SQL: {opensql}SELECT users.id, addresses.id, users.id, users.name, addresses.email_address AS email FROM users JOIN addresses ON users.id=addresses.user_id WHERE users.id = 1 - () + [...] () {stop} Above, there's three columns in the result that are named "id", but since @@ -1020,7 +1020,7 @@ need to refer to any pre-established :class:`_schema.Table` metadata: FROM users, addresses WHERE users.id = addresses.user_id AND users.name BETWEEN 'm' AND 'z' AND (addresses.email_address LIKE ? OR addresses.email_address LIKE ?) - ('%@aol.com', '%@msn.com') + [...] ('%@aol.com', '%@msn.com') {stop}[(u'Wendy Williams, wendy@aol.com',)] .. versionchanged:: 1.0.0 @@ -1074,7 +1074,7 @@ be quoted: WHERE users.id = addresses.user_id AND users.name BETWEEN 'm' AND 'z' AND (addresses.email_address LIKE ? OR addresses.email_address LIKE ?) - (', ', '%@aol.com', '%@msn.com') + [...] (', ', '%@aol.com', '%@msn.com') {stop}[(u'Wendy Williams, wendy@aol.com',)] Ordering or Grouping by a Label @@ -1101,7 +1101,7 @@ are rendered fully: {sql}>>> conn.execute(stmt).fetchall() SELECT addresses.user_id, count(addresses.id) AS num_addresses FROM addresses GROUP BY addresses.user_id ORDER BY addresses.user_id, num_addresses - () + [...] () {stop}[(1, 2), (2, 2)] We can use modifiers like :func:`.asc` or :func:`.desc` by passing the string @@ -1118,7 +1118,7 @@ name: {sql}>>> conn.execute(stmt).fetchall() SELECT addresses.user_id, count(addresses.id) AS num_addresses FROM addresses GROUP BY addresses.user_id ORDER BY addresses.user_id, num_addresses DESC - () + [...] () {stop}[(1, 2), (2, 2)] Note that the string feature here is very much tailored to when we have @@ -1141,7 +1141,7 @@ by a column name that appears more than once: users_2.name, users_2.fullname FROM users AS users_1, users AS users_2 WHERE users_1.name > users_2.name ORDER BY users_1.name - () + [...] () {stop}[(2, u'wendy', u'Wendy Williams', 1, u'jack', u'Jack Jones')] @@ -1193,7 +1193,7 @@ once for each address. We create two :class:`_expression.Alias` constructs aga AND users.id = addresses_2.user_id AND addresses_1.email_address = ? AND addresses_2.email_address = ? - ('jack@msn.com', 'jack@yahoo.com') + [...] ('jack@msn.com', 'jack@yahoo.com') {stop}[(1, u'jack', u'Jack Jones')] Note that the :class:`_expression.Alias` construct generated the names ``addresses_1`` and @@ -1235,7 +1235,7 @@ by making :class:`.Subquery` of the entire statement: AND addresses_1.email_address = ? AND addresses_2.email_address = ?) AS anon_1 WHERE users.id = anon_1.id - ('jack@msn.com', 'jack@yahoo.com') + [...] ('jack@msn.com', 'jack@yahoo.com') {stop}[(u'jack',)] .. versionchanged:: 1.4 Added the :class:`.Subquery` object and created more of a @@ -1291,7 +1291,7 @@ here we make use of the :meth:`_expression.Select.select_from` method: {sql}>>> conn.execute(s).fetchall() SELECT users.fullname FROM users JOIN addresses ON addresses.email_address LIKE users.name || ? - ('%',) + [...] ('%',) {stop}[(u'Jack Jones',), (u'Jack Jones',), (u'Wendy Williams',)] The :meth:`_expression.FromClause.outerjoin` method creates ``LEFT OUTER JOIN`` constructs, @@ -1350,7 +1350,7 @@ typically acquires using the :meth:`_expression.Select.cte` method on a SELECT addresses.id, addresses.user_id, addresses.email_address FROM addresses, anon_1 WHERE addresses.user_id = anon_1.id ORDER BY addresses.id - ('wendy',) + [...] ('wendy',) {stop}[(3, 2, 'www@www.org'), (4, 2, 'wendy@aol.com')] The CTE construct is a great way to provide a source of rows that is @@ -1388,7 +1388,7 @@ this form looks like: SELECT addresses.id, addresses.user_id, addresses.email_address FROM addresses, anon_1 WHERE addresses.user_id = anon_1.id ORDER BY addresses.id - () + [...] () {stop}[(1, 1, 'jack@yahoo.com'), (2, 1, 'jack@msn.com'), (3, 2, 'www@www.org'), (4, 2, 'wendy@aol.com')] @@ -1421,7 +1421,7 @@ at execution time, as here where it converts to positional for SQLite: SELECT users.id, users.name, users.fullname FROM users WHERE users.name = ? - ('wendy',) + [...] ('wendy',) {stop}[(2, u'wendy', u'Wendy Williams')] Another important aspect of :func:`.bindparam` is that it may be assigned a @@ -1436,7 +1436,7 @@ off to the database: SELECT users.id, users.name, users.fullname FROM users WHERE users.name LIKE ? || '%' - ('wendy',) + [...] ('wendy',) {stop}[(2, u'wendy', u'Wendy Williams')] @@ -1462,7 +1462,7 @@ single named value is needed in the execute parameters: FROM users LEFT OUTER JOIN addresses ON users.id = addresses.user_id WHERE users.name LIKE ? || '%' OR addresses.email_address LIKE ? || '@%' ORDER BY addresses.id - ('jack', 'jack') + [...] ('jack', 'jack') {stop}[(1, u'jack', u'Jack Jones', 1, 1, u'jack@yahoo.com'), (1, u'jack', u'Jack Jones', 2, 1, u'jack@msn.com')] .. seealso:: @@ -1531,7 +1531,7 @@ not important in this case: ... ).scalar() {opensql}SELECT max(addresses.email_address) AS maxemail FROM addresses - () + [...] () {stop}u'www@www.org' Databases such as PostgreSQL and Oracle which support functions that return @@ -1648,7 +1648,7 @@ object as arguments: >>> conn.execute(s).fetchall() {opensql}SELECT CAST(users.id AS VARCHAR) AS id FROM users - () + [...] () {stop}[('1',), ('2',)] The :func:`.cast` function is used not just when converting between datatypes, @@ -1724,7 +1724,7 @@ module level functions :func:`_expression.union` and SELECT addresses.id, addresses.user_id, addresses.email_address FROM addresses WHERE addresses.email_address LIKE ? ORDER BY email_address - ('foo@bar.com', '%@yahoo.com') + [...] ('foo@bar.com', '%@yahoo.com') {stop}[(1, 1, u'jack@yahoo.com')] Also available, though not supported on all databases, are @@ -1750,7 +1750,7 @@ Also available, though not supported on all databases, are SELECT addresses.id, addresses.user_id, addresses.email_address FROM addresses WHERE addresses.email_address LIKE ? - ('%@%.com', '%@msn.com') + [...] ('%@%.com', '%@msn.com') {stop}[(1, 1, u'jack@yahoo.com'), (4, 2, u'wendy@aol.com')] A common issue with so-called "compound" selectables arises due to the fact @@ -1788,7 +1788,7 @@ want the "union" to be stated as a subquery: SELECT addresses.id, addresses.user_id, addresses.email_address FROM addresses WHERE addresses.email_address LIKE ? - ('%@yahoo.com', '%@msn.com', '%@msn.com') + [...] ('%@yahoo.com', '%@msn.com', '%@msn.com') {stop}[(1, 1, u'jack@yahoo.com')] .. seealso:: @@ -1868,7 +1868,7 @@ other column within another :func:`_expression.select`: FROM addresses WHERE users.id = addresses.user_id) AS anon_1 FROM users - () + [...] () {stop}[(u'jack', 2), (u'wendy', 2)] To apply a non-anonymous column name to our scalar select, we create @@ -1884,7 +1884,7 @@ it using :meth:`_expression.SelectBase.label` instead: FROM addresses WHERE users.id = addresses.user_id) AS address_count FROM users - () + [...] () {stop}[(u'jack', 2), (u'wendy', 2)] .. seealso:: @@ -1918,7 +1918,7 @@ still have at least one FROM clause of its own. For example: FROM addresses WHERE addresses.user_id = users.id AND addresses.email_address = ?) - ('jack@yahoo.com',) + [...] ('jack@yahoo.com',) {stop}[(u'jack',)] Auto-correlation will usually do what's expected, however it can also be controlled. @@ -1943,7 +1943,7 @@ may be correlated: WHERE users.id = (SELECT users.id FROM users WHERE users.id = addresses.user_id AND users.name = ?) - ('jack',) + [...] ('jack',) {stop}[(u'jack', u'jack@yahoo.com'), (u'jack', u'jack@msn.com')] To entirely disable a statement from correlating, we can pass ``None`` @@ -1962,7 +1962,7 @@ as the argument: WHERE users.id = (SELECT users.id FROM users WHERE users.name = ?) - ('wendy',) + [...] ('wendy',) {stop}[(u'wendy',)] We can also control correlation via exclusion, using the :meth:`_expression.Select.correlate_except` @@ -1985,7 +1985,7 @@ by telling it to correlate all FROM clauses except for ``users``: WHERE users.id = (SELECT users.id FROM users WHERE users.id = addresses.user_id AND users.name = ?) - ('jack',) + [...] ('jack',) {stop}[(u'jack', u'jack@yahoo.com'), (u'jack', u'jack@msn.com')] .. _lateral_selects: @@ -2070,7 +2070,7 @@ Ordering is done by passing column expressions to the >>> conn.execute(stmt).fetchall() {opensql}SELECT users.name FROM users ORDER BY users.name - () + [...] () {stop}[(u'jack',), (u'wendy',)] Ascending or descending can be controlled using the :meth:`_expression.ColumnElement.asc` @@ -2082,7 +2082,7 @@ and :meth:`_expression.ColumnElement.desc` modifiers: >>> conn.execute(stmt).fetchall() {opensql}SELECT users.name FROM users ORDER BY users.name DESC - () + [...] () {stop}[(u'wendy',), (u'jack',)] Grouping refers to the GROUP BY clause, and is usually used in conjunction @@ -2099,7 +2099,7 @@ This is provided via the :meth:`_expression.SelectBase.group_by` method: FROM users JOIN addresses ON users.id = addresses.user_id GROUP BY users.name - () + [...] () {stop}[(u'jack', 2), (u'wendy', 2)] HAVING can be used to filter results on an aggregate value, after GROUP BY has @@ -2118,7 +2118,7 @@ method: ON users.id = addresses.user_id GROUP BY users.name HAVING length(users.name) > ? - (4,) + [...] (4,) {stop}[(u'wendy', 2)] A common system of dealing with duplicates in composed SELECT statements @@ -2135,7 +2135,7 @@ is the DISTINCT modifier. A simple DISTINCT clause can be added using the {opensql}SELECT DISTINCT users.name FROM users, addresses WHERE (addresses.email_address LIKE '%' || users.name || '%') - () + [...] () {stop}[(u'jack',), (u'wendy',)] Most database backends support a system of limiting how many rows @@ -2156,7 +2156,7 @@ into the current backend's methodology: {opensql}SELECT users.name, addresses.email_address FROM users JOIN addresses ON users.id = addresses.user_id LIMIT ? OFFSET ? - (1, 1) + [...] (1, 1) {stop}[(u'jack', u'jack@msn.com')] @@ -2181,7 +2181,7 @@ as a value: ... values(fullname="Fullname: " + users.c.name) >>> conn.execute(stmt) {opensql}UPDATE users SET fullname=(? || users.name) - ('Fullname: ',) + [...] ('Fullname: ',) COMMIT {stop}<sqlalchemy.engine.cursor.LegacyCursorResult object at 0x...> @@ -2210,7 +2210,7 @@ as in the example below: ... {'id':6, '_name':'name3'}, ... ]) {opensql}INSERT INTO users (id, name) VALUES (?, (? || ?)) - ((4, 'name1', ' .. name'), (5, 'name2', ' .. name'), (6, 'name3', ' .. name')) + [...] ((4, 'name1', ' .. name'), (5, 'name2', ' .. name'), (6, 'name3', ' .. name')) COMMIT <sqlalchemy.engine.cursor.LegacyCursorResult object at 0x...> @@ -2226,7 +2226,7 @@ that can be specified: >>> conn.execute(stmt) {opensql}UPDATE users SET name=? WHERE users.name = ? - ('ed', 'jack') + [...] ('ed', 'jack') COMMIT {stop}<sqlalchemy.engine.cursor.LegacyCursorResult object at 0x...> @@ -2246,7 +2246,7 @@ used to achieve this: ... {'oldname':'jim', 'newname':'jake'}, ... ]) {opensql}UPDATE users SET name=? WHERE users.name = ? - (('ed', 'jack'), ('mary', 'wendy'), ('jake', 'jim')) + [...] (('ed', 'jack'), ('mary', 'wendy'), ('jake', 'jim')) COMMIT {stop}<sqlalchemy.engine.cursor.LegacyCursorResult object at 0x...> @@ -2268,7 +2268,7 @@ subquery using :meth:`_expression.Select.scalar_subquery`: FROM addresses WHERE addresses.user_id = users.id LIMIT ? OFFSET ?) - (1, 0) + [...] (1, 0) COMMIT {stop}<sqlalchemy.engine.cursor.LegacyCursorResult object at 0x...> @@ -2385,13 +2385,13 @@ Finally, a delete. This is accomplished easily enough using the >>> conn.execute(addresses.delete()) {opensql}DELETE FROM addresses - () + [...] () COMMIT {stop}<sqlalchemy.engine.cursor.LegacyCursorResult object at 0x...> >>> conn.execute(users.delete().where(users.c.name > 'm')) {opensql}DELETE FROM users WHERE users.name > ? - ('m',) + [...] ('m',) COMMIT {stop}<sqlalchemy.engine.cursor.LegacyCursorResult object at 0x...> @@ -2439,7 +2439,7 @@ The value is available as :attr:`_engine.CursorResult.rowcount`: >>> result = conn.execute(users.delete()) {opensql}DELETE FROM users - () + [...] () COMMIT {stop}>>> result.rowcount 1 diff --git a/doc/build/orm/tutorial.rst b/doc/build/orm/tutorial.rst index c08daa7fd..8ea8af4a2 100644 --- a/doc/build/orm/tutorial.rst +++ b/doc/build/orm/tutorial.rst @@ -210,16 +210,16 @@ the actual ``CREATE TABLE`` statement: >>> Base.metadata.create_all(engine) PRAGMA main.table_info("users") - () + [...] () PRAGMA temp.table_info("users") - () + [...] () CREATE TABLE users ( id INTEGER NOT NULL, name VARCHAR, fullname VARCHAR, nickname VARCHAR, PRIMARY KEY (id) ) - () + [...] () COMMIT .. topic:: Minimal Table Descriptions vs. Full Descriptions @@ -373,7 +373,7 @@ added: {sql}>>> our_user = session.query(User).filter_by(name='ed').first() # doctest:+NORMALIZE_WHITESPACE BEGIN (implicit) INSERT INTO users (name, fullname, nickname) VALUES (?, ?, ?) - ('ed', 'Ed Jones', 'edsnickname') + [...] ('ed', 'Ed Jones', 'edsnickname') SELECT users.id AS users_id, users.name AS users_name, users.fullname AS users_fullname, @@ -381,7 +381,7 @@ added: FROM users WHERE users.name = ? LIMIT ? OFFSET ? - ('ed', 1, 0) + [...] ('ed', 1, 0) {stop}>>> our_user <User(name='ed', fullname='Ed Jones', nickname='edsnickname')> @@ -448,13 +448,13 @@ three new ``User`` objects we've added: {sql}>>> session.commit() UPDATE users SET nickname=? WHERE users.id = ? - ('eddie', 1) + [...] ('eddie', 1) INSERT INTO users (name, fullname, nickname) VALUES (?, ?, ?) - ('wendy', 'Wendy Williams', 'windy') + [...] ('wendy', 'Wendy Williams', 'windy') INSERT INTO users (name, fullname, nickname) VALUES (?, ?, ?) - ('mary', 'Mary Contrary', 'mary') + [...] ('mary', 'Mary Contrary', 'mary') INSERT INTO users (name, fullname, nickname) VALUES (?, ?, ?) - ('fred', 'Fred Flintstone', 'freddy') + [...] ('fred', 'Fred Flintstone', 'freddy') COMMIT :meth:`~.Session.commit` flushes the remaining changes to the @@ -475,7 +475,7 @@ If we look at Ed's ``id`` attribute, which earlier was ``None``, it now has a va users.nickname AS users_nickname FROM users WHERE users.id = ? - (1,) + [...] (1,) {stop}1 After the :class:`~sqlalchemy.orm.session.Session` inserts new rows in the @@ -519,16 +519,16 @@ Querying the session, we can see that they're flushed into the current transacti {sql}>>> session.query(User).filter(User.name.in_(['Edwardo', 'fakeuser'])).all() UPDATE users SET name=? WHERE users.id = ? - ('Edwardo', 1) + [...] ('Edwardo', 1) INSERT INTO users (name, fullname, nickname) VALUES (?, ?, ?) - ('fakeuser', 'Invalid', '12345') + [...] ('fakeuser', 'Invalid', '12345') SELECT users.id AS users_id, users.name AS users_name, users.fullname AS users_fullname, users.nickname AS users_nickname FROM users WHERE users.name IN (?, ?) - ('Edwardo', 'fakeuser') + [...] ('Edwardo', 'fakeuser') {stop}[<User(name='Edwardo', fullname='Ed Jones', nickname='eddie')>, <User(name='fakeuser', fullname='Invalid', nickname='12345')>] Rolling back, we can see that ``ed_user``'s name is back to ``ed``, and @@ -548,7 +548,7 @@ Rolling back, we can see that ``ed_user``'s name is back to ``ed``, and users.nickname AS users_nickname FROM users WHERE users.id = ? - (1,) + [...] (1,) {stop}u'ed' >>> fake_user in session False @@ -564,7 +564,7 @@ issuing a SELECT illustrates the changes made to the database: users.nickname AS users_nickname FROM users WHERE users.name IN (?, ?) - ('ed', 'fakeuser') + [...] ('ed', 'fakeuser') {stop}[<User(name='ed', fullname='Ed Jones', nickname='eddie')>] .. _ormtutorial_querying: @@ -590,7 +590,7 @@ returned: users.fullname AS users_fullname, users.nickname AS users_nickname FROM users ORDER BY users.id - () + [...] () {stop}ed Ed Jones wendy Wendy Williams mary Mary Contrary @@ -609,7 +609,7 @@ is expressed as tuples: SELECT users.name AS users_name, users.fullname AS users_fullname FROM users - () + [...] () {stop}ed Ed Jones wendy Wendy Williams mary Mary Contrary @@ -630,7 +630,7 @@ class: users.fullname AS users_fullname, users.nickname AS users_nickname FROM users - () + [...] () {stop}<User(name='ed', fullname='Ed Jones', nickname='eddie')> ed <User(name='wendy', fullname='Wendy Williams', nickname='windy')> wendy <User(name='mary', fullname='Mary Contrary', nickname='mary')> mary @@ -647,7 +647,7 @@ is mapped to one (such as ``User.name``): ... print(row.name_label) SELECT users.name AS name_label FROM users - (){stop} + [...] (){stop} ed wendy mary @@ -669,7 +669,7 @@ entities are present in the call to :meth:`~.Session.query`, can be controlled u user_alias.fullname AS user_alias_fullname, user_alias.nickname AS user_alias_nickname FROM users AS user_alias - (){stop} + [...] (){stop} <User(name='ed', fullname='Ed Jones', nickname='eddie')> <User(name='wendy', fullname='Wendy Williams', nickname='windy')> <User(name='mary', fullname='Mary Contrary', nickname='mary')> @@ -689,7 +689,7 @@ conjunction with ORDER BY: users.nickname AS users_nickname FROM users ORDER BY users.id LIMIT ? OFFSET ? - (2, 1){stop} + [...] (2, 1){stop} <User(name='wendy', fullname='Wendy Williams', nickname='windy')> <User(name='mary', fullname='Mary Contrary', nickname='mary')> @@ -703,7 +703,7 @@ and filtering results, which is accomplished either with ... print(name) SELECT users.name AS users_name FROM users WHERE users.fullname = ? - ('Ed Jones',) + [...] ('Ed Jones',) {stop}ed ...or :func:`~sqlalchemy.orm.query.Query.filter`, which uses more flexible SQL @@ -717,7 +717,7 @@ operators with the class-level attributes on your mapped class: ... print(name) SELECT users.name AS users_name FROM users WHERE users.fullname = ? - ('Ed Jones',) + [...] ('Ed Jones',) {stop}ed The :class:`~sqlalchemy.orm.query.Query` object is fully **generative**, meaning @@ -739,7 +739,7 @@ users named "ed" with a full name of "Ed Jones", you can call users.nickname AS users_nickname FROM users WHERE users.name = ? AND users.fullname = ? - ('ed', 'Ed Jones') + [...] ('ed', 'Ed Jones') {stop}<User(name='ed', fullname='Ed Jones', nickname='eddie')> Common Filter Operators @@ -861,7 +861,7 @@ database results. Here's a brief tour: users.nickname AS users_nickname FROM users WHERE users.name LIKE ? ORDER BY users.id - ('%ed',) + [...] ('%ed',) {stop}[<User(name='ed', fullname='Ed Jones', nickname='eddie')>, <User(name='fred', fullname='Fred Flintstone', nickname='freddy')>] @@ -893,7 +893,7 @@ database results. Here's a brief tour: FROM users WHERE users.name LIKE ? ORDER BY users.id LIMIT ? OFFSET ? - ('%ed', 1, 0) + [...] ('%ed', 1, 0) {stop}<User(name='ed', fullname='Ed Jones', nickname='eddie')> * :meth:`_query.Query.one()` fully fetches all rows, and if not @@ -937,7 +937,7 @@ database results. Here's a brief tour: SELECT users.id AS users_id FROM users WHERE users.name = ? ORDER BY users.id - ('ed',) + [...] ('ed',) {stop}1 .. _orm_tutorial_literal_sql: @@ -965,7 +965,7 @@ by most applicable methods. For example, users.nickname AS users_nickname FROM users WHERE id<224 ORDER BY id - () + [...] () {stop}ed wendy mary @@ -985,7 +985,7 @@ method: users.nickname AS users_nickname FROM users WHERE id<? and name=? ORDER BY users.id - (224, 'fred') + [...] (224, 'fred') {stop}<User(name='fred', fullname='Fred Flintstone', nickname='freddy')> To use an entirely string-based statement, a :func:`_expression.text` construct @@ -999,7 +999,7 @@ returned by the SQL statement based on column name:: {sql}>>> session.query(User).from_statement( ... text("SELECT * FROM users where name=:name")).params(name='ed').all() SELECT * FROM users where name=? - ('ed',) + [...] ('ed',) {stop}[<User(name='ed', fullname='Ed Jones', nickname='eddie')>] For better targeting of mapped columns to a textual SELECT, as well as to @@ -1013,7 +1013,7 @@ columns are passed in the desired order to :meth:`_expression.TextClause.columns >>> stmt = stmt.columns(User.name, User.id, User.fullname, User.nickname) {sql}>>> session.query(User).from_statement(stmt).params(name='ed').all() SELECT name, id, fullname, nickname FROM users where name=? - ('ed',) + [...] ('ed',) {stop}[<User(name='ed', fullname='Ed Jones', nickname='eddie')>] When selecting from a :func:`_expression.text` construct, the :class:`_query.Query` @@ -1028,7 +1028,7 @@ any other case: {sql}>>> session.query(User.id, User.name).\ ... from_statement(stmt).params(name='ed').all() SELECT name, id FROM users where name=? - ('ed',) + [...] ('ed',) {stop}[(1, u'ed')] .. seealso:: @@ -1052,7 +1052,7 @@ counting called :meth:`~sqlalchemy.orm.query.Query.count()`: users.nickname AS users_nickname FROM users WHERE users.name LIKE ?) AS anon_1 - ('%ed',) + [...] ('%ed',) {stop}2 .. sidebar:: Counting on ``count()`` @@ -1085,7 +1085,7 @@ use it to return the count of each distinct user name: {sql}>>> session.query(func.count(User.name), User.name).group_by(User.name).all() SELECT count(users.name) AS count_1, users.name AS users_name FROM users GROUP BY users.name - () + [...] () {stop}[(1, u'ed'), (1, u'fred'), (1, u'mary'), (1, u'wendy')] To achieve our simple ``SELECT count(*) FROM table``, we can apply it as: @@ -1095,7 +1095,7 @@ To achieve our simple ``SELECT count(*) FROM table``, we can apply it as: {sql}>>> session.query(func.count('*')).select_from(User).scalar() SELECT count(?) AS count_1 FROM users - ('*',) + [...] ('*',) {stop}4 The usage of :meth:`_query.Query.select_from` can be removed if we express the count in terms @@ -1106,7 +1106,7 @@ of the ``User`` primary key directly: {sql}>>> session.query(func.count(User.id)).scalar() SELECT count(users.id) AS count_1 FROM users - () + [...] () {stop}4 .. _orm_tutorial_relationship: @@ -1223,7 +1223,7 @@ already been created: PRIMARY KEY (id), FOREIGN KEY(user_id) REFERENCES users (id) ) - () + [...] () COMMIT Working with Related Objects @@ -1272,11 +1272,11 @@ known as **cascading**: >>> session.add(jack) {sql}>>> session.commit() INSERT INTO users (name, fullname, nickname) VALUES (?, ?, ?) - ('jack', 'Jack Bean', 'gjffdd') + [...] ('jack', 'Jack Bean', 'gjffdd') INSERT INTO addresses (email_address, user_id) VALUES (?, ?) - ('jack@google.com', 5) + [...] ('jack@google.com', 5) INSERT INTO addresses (email_address, user_id) VALUES (?, ?) - ('j25@yahoo.com', 5) + [...] ('j25@yahoo.com', 5) COMMIT Querying for Jack, we get just Jack back. No SQL is yet issued for Jack's addresses: @@ -1292,7 +1292,7 @@ Querying for Jack, we get just Jack back. No SQL is yet issued for Jack's addre users.nickname AS users_nickname FROM users WHERE users.name = ? - ('jack',) + [...] ('jack',) {stop}>>> jack <User(name='jack', fullname='Jack Bean', nickname='gjffdd')> @@ -1308,7 +1308,7 @@ Let's look at the ``addresses`` collection. Watch the SQL: addresses.user_id AS addresses_user_id FROM addresses WHERE ? = addresses.user_id ORDER BY addresses.id - (5,) + [...] (5,) {stop}[<Address(email_address='jack@google.com')>, <Address(email_address='j25@yahoo.com')>] When we accessed the ``addresses`` collection, SQL was suddenly issued. This @@ -1349,7 +1349,7 @@ Below we load the ``User`` and ``Address`` entities at once using this method: FROM users, addresses WHERE users.id = addresses.user_id AND addresses.email_address = ? - ('jack@google.com',) + [...] ('jack@google.com',) {stop}<User(name='jack', fullname='Jack Bean', nickname='gjffdd')> <Address(email_address='jack@google.com')> @@ -1367,7 +1367,7 @@ using the :meth:`_query.Query.join` method: users.nickname AS users_nickname FROM users JOIN addresses ON users.id = addresses.user_id WHERE addresses.email_address = ? - ('jack@google.com',) + [...] ('jack@google.com',) {stop}[<User(name='jack', fullname='Jack Bean', nickname='gjffdd')>] :meth:`_query.Query.join` knows how to join between ``User`` @@ -1435,7 +1435,7 @@ distinct email addresses at the same time: ON users.id = addresses_2.user_id WHERE addresses_1.email_address = ? AND addresses_2.email_address = ? - ('jack@google.com', 'j25@yahoo.com') + [...] ('jack@google.com', 'j25@yahoo.com') {stop}jack jack@google.com j25@yahoo.com In addition to using the :meth:`_orm.PropComparator.of_type` method, it is @@ -1496,7 +1496,7 @@ accessible through an attribute called ``c``: FROM addresses GROUP BY addresses.user_id) AS anon_1 ON users.id = anon_1.user_id ORDER BY users.id - ('*',) + [...] ('*',) {stop}<User(name='ed', fullname='Ed Jones', nickname='eddie')> None <User(name='wendy', fullname='Wendy Williams', nickname='windy')> None <User(name='mary', fullname='Mary Contrary', nickname='mary')> None @@ -1534,7 +1534,7 @@ to associate an "alias" of a mapped class to a subquery: FROM addresses WHERE addresses.email_address != ?) AS anon_1 ON users.id = anon_1.user_id - ('j25@yahoo.com',) + [...] ('j25@yahoo.com',) {stop}<User(name='jack', fullname='Jack Bean', nickname='gjffdd')> <Address(email_address='jack@google.com')> @@ -1559,7 +1559,7 @@ There is an explicit EXISTS construct, which looks like this: WHERE EXISTS (SELECT * FROM addresses WHERE addresses.user_id = users.id) - () + [...] () {stop}jack The :class:`~sqlalchemy.orm.query.Query` features several operators which make @@ -1576,7 +1576,7 @@ usage of EXISTS automatically. Above, the statement can be expressed along the WHERE EXISTS (SELECT 1 FROM addresses WHERE users.id = addresses.user_id) - () + [...] () {stop}jack :meth:`~.RelationshipProperty.Comparator.any` takes criterion as well, to limit the rows matched: @@ -1591,7 +1591,7 @@ usage of EXISTS automatically. Above, the statement can be expressed along the WHERE EXISTS (SELECT 1 FROM addresses WHERE users.id = addresses.user_id AND addresses.email_address LIKE ?) - ('%google%',) + [...] ('%google%',) {stop}jack :meth:`~.RelationshipProperty.Comparator.has` is the same operator as @@ -1609,7 +1609,7 @@ usage of EXISTS automatically. Above, the statement can be expressed along the WHERE NOT (EXISTS (SELECT 1 FROM users WHERE users.id = addresses.user_id AND users.name = ?)) - ('jack',) + [...] ('jack',) {stop}[] Common Relationship Operators @@ -1685,14 +1685,14 @@ at once: users.nickname AS users_nickname FROM users WHERE users.name = ? - ('jack',) + [...] ('jack',) SELECT addresses.user_id AS addresses_user_id, addresses.id AS addresses_id, addresses.email_address AS addresses_email_address FROM addresses WHERE addresses.user_id IN (?) ORDER BY addresses.id - (5,) + [...] (5,) {stop}>>> jack <User(name='jack', fullname='Jack Bean', nickname='gjffdd')> @@ -1728,7 +1728,7 @@ will emit the extra join regardless: FROM users LEFT OUTER JOIN addresses AS addresses_1 ON users.id = addresses_1.user_id WHERE users.name = ? ORDER BY addresses_1.id - ('jack',) + [...] ('jack',) {stop}>>> jack <User(name='jack', fullname='Jack Bean', nickname='gjffdd')> @@ -1792,7 +1792,7 @@ attribute: addresses.user_id AS addresses_user_id FROM addresses JOIN users ON users.id = addresses.user_id WHERE users.name = ? - ('jack',) + [...] ('jack',) {stop}>>> jacks_addresses [<Address(email_address='jack@google.com')>, <Address(email_address='j25@yahoo.com')>] @@ -1814,9 +1814,9 @@ in the session, then we'll issue a ``count`` query to see that no rows remain: >>> session.delete(jack) {sql}>>> session.query(User).filter_by(name='jack').count() UPDATE addresses SET user_id=? WHERE addresses.id = ? - ((None, 1), (None, 2)) + [...] ((None, 1), (None, 2)) DELETE FROM users WHERE users.id = ? - (5,) + [...] (5,) SELECT count(*) AS count_1 FROM (SELECT users.id AS users_id, users.name AS users_name, @@ -1824,7 +1824,7 @@ in the session, then we'll issue a ``count`` query to see that no rows remain: users.nickname AS users_nickname FROM users WHERE users.name = ?) AS anon_1 - ('jack',) + [...] ('jack',) {stop}0 So far, so good. How about Jack's ``Address`` objects ? @@ -1840,7 +1840,7 @@ So far, so good. How about Jack's ``Address`` objects ? addresses.user_id AS addresses_user_id FROM addresses WHERE addresses.email_address IN (?, ?)) AS anon_1 - ('jack@google.com', 'j25@yahoo.com') + [...] ('jack@google.com', 'j25@yahoo.com') {stop}2 Uh oh, they're still there ! Analyzing the flush SQL, we can see that the @@ -1914,7 +1914,7 @@ being deleted: users.nickname AS users_nickname FROM users WHERE users.id = ? - (5,) + [...] (5,) {stop} # remove one Address (lazy load fires off) @@ -1924,7 +1924,7 @@ being deleted: addresses.user_id AS addresses_user_id FROM addresses WHERE ? = addresses.user_id - (5,) + [...] (5,) {stop} # only one address remains @@ -1932,14 +1932,14 @@ being deleted: ... Address.email_address.in_(['jack@google.com', 'j25@yahoo.com']) ... ).count() DELETE FROM addresses WHERE addresses.id = ? - (2,) + [...] (2,) SELECT count(*) AS count_1 FROM (SELECT addresses.id AS addresses_id, addresses.email_address AS addresses_email_address, addresses.user_id AS addresses_user_id FROM addresses WHERE addresses.email_address IN (?, ?)) AS anon_1 - ('jack@google.com', 'j25@yahoo.com') + [...] ('jack@google.com', 'j25@yahoo.com') {stop}1 Deleting Jack will delete both Jack and the remaining ``Address`` associated @@ -1951,9 +1951,9 @@ with the user: {sql}>>> session.query(User).filter_by(name='jack').count() DELETE FROM addresses WHERE addresses.id = ? - (1,) + [...] (1,) DELETE FROM users WHERE users.id = ? - (5,) + [...] (5,) SELECT count(*) AS count_1 FROM (SELECT users.id AS users_id, users.name AS users_name, @@ -1961,7 +1961,7 @@ with the user: users.nickname AS users_nickname FROM users WHERE users.name = ?) AS anon_1 - ('jack',) + [...] ('jack',) {stop}0 {sql}>>> session.query(Address).filter( @@ -1973,7 +1973,7 @@ with the user: addresses.user_id AS addresses_user_id FROM addresses WHERE addresses.email_address IN (?, ?)) AS anon_1 - ('jack@google.com', 'j25@yahoo.com') + [...] ('jack@google.com', 'j25@yahoo.com') {stop}0 .. topic:: More on Cascades @@ -2086,7 +2086,7 @@ Create new tables: PRIMARY KEY (id), UNIQUE (keyword) ) - () + [...] () COMMIT CREATE TABLE posts ( id INTEGER NOT NULL, @@ -2096,7 +2096,7 @@ Create new tables: PRIMARY KEY (id), FOREIGN KEY(user_id) REFERENCES users (id) ) - () + [...] () COMMIT CREATE TABLE post_keywords ( post_id INTEGER NOT NULL, @@ -2105,7 +2105,7 @@ Create new tables: FOREIGN KEY(post_id) REFERENCES posts (id), FOREIGN KEY(keyword_id) REFERENCES keywords (id) ) - () + [...] () COMMIT Usage is not too different from what we've been doing. Let's give Wendy some blog posts: @@ -2121,7 +2121,7 @@ Usage is not too different from what we've been doing. Let's give Wendy some bl users.nickname AS users_nickname FROM users WHERE users.name = ? - ('wendy',) + [...] ('wendy',) {stop} >>> post = BlogPost("Wendy's Blog Post", "This is a test", wendy) >>> session.add(post) @@ -2144,13 +2144,13 @@ keyword string 'firstpost'": ... filter(BlogPost.keywords.any(keyword='firstpost')).\ ... all() INSERT INTO keywords (keyword) VALUES (?) - ('wendy',) + [...] ('wendy',) INSERT INTO keywords (keyword) VALUES (?) - ('firstpost',) + [...] ('firstpost',) INSERT INTO posts (user_id, headline, body) VALUES (?, ?, ?) - (2, "Wendy's Blog Post", 'This is a test') + [...] (2, "Wendy's Blog Post", 'This is a test') INSERT INTO post_keywords (post_id, keyword_id) VALUES (?, ?) - (...) + [...] (...) SELECT posts.id AS posts_id, posts.user_id AS posts_user_id, posts.headline AS posts_headline, @@ -2161,7 +2161,7 @@ keyword string 'firstpost'": WHERE posts.id = post_keywords.post_id AND keywords.id = post_keywords.keyword_id AND keywords.keyword = ?) - ('firstpost',) + [...] ('firstpost',) {stop}[BlogPost("Wendy's Blog Post", 'This is a test', <User(name='wendy', fullname='Wendy Williams', nickname='windy')>)] If we want to look up posts owned by the user ``wendy``, we can tell @@ -2183,7 +2183,7 @@ the query to narrow down to that ``User`` object as a parent: WHERE posts.id = post_keywords.post_id AND keywords.id = post_keywords.keyword_id AND keywords.keyword = ?)) - (2, 'firstpost') + [...] (2, 'firstpost') {stop}[BlogPost("Wendy's Blog Post", 'This is a test', <User(name='wendy', fullname='Wendy Williams', nickname='windy')>)] Or we can use Wendy's own ``posts`` relationship, which is a "dynamic" @@ -2204,7 +2204,7 @@ relationship, to query straight from there: WHERE posts.id = post_keywords.post_id AND keywords.id = post_keywords.keyword_id AND keywords.keyword = ?)) - (2, 'firstpost') + [...] (2, 'firstpost') {stop}[BlogPost("Wendy's Blog Post", 'This is a test', <User(name='wendy', fullname='Wendy Williams', nickname='windy')>)] Further Reference |
