From: Mike Bayer Date: Mon, 13 Apr 2020 19:24:23 +0000 (-0400) Subject: Add missing definitions to glossary X-Git-Tag: rel_1_3_17~34 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=99ce1128b718010cd945318176623cbb5041ef3f;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git Add missing definitions to glossary improve formatting Change-Id: Iea3b72187d7c8020e18babb72a53c39c5aeec68c (cherry picked from commit 1b1fe518512441959f4ac9c9b715271e2b6d7977) --- diff --git a/doc/build/glossary.rst b/doc/build/glossary.rst index c431fce3df..83bf0b43ae 100644 --- a/doc/build/glossary.rst +++ b/doc/build/glossary.rst @@ -9,6 +9,25 @@ Glossary .. glossary:: :sorted: + relational + relational algebra + + An algrebraic system developed by Edgar F. Codd that is used for + modelling and querying the data stored in relational databases. + + .. seealso:: + + `Relational Algebra (via Wikipedia) `_ + + selectable + A term used in SQLAlchemy to describe a SQL construct that represents + a collection of rows. It's largely similar to the concept of a + "relation" in :term:`relational algebra`. In SQLAlchemy, objects + that subclass the :class:`.Selectable` class are considered to be + usable as "selectables" when using SQLAlchemy Core. The two most + common constructs are that of the :class:`.Table` and that of the + :class:`.Select` statement. + annotations Annotations are a concept used internally by SQLAlchemy in order to store additional information along with :class:`.ClauseElement` objects. A Python @@ -121,6 +140,79 @@ Glossary :term:`DDL` + metadata + table metadata + The term "metadata" generally refers to "data that describes data"; + data that itself represents the format and/or structure of some other + kind of data. In SQLAlchemy, the term "metadata" typically refers to + the :class:`.MetaData` construct, which is a collection of information + about the tables, columns, constraints, and other :term:`DDL` objects + that may exist in a particular database. + + .. seealso:: + + `Metadata Mapping (via Martin Fowler) `_ + + version id column + In SQLAlchemy, this refers to the use of a particular table column that + tracks the "version" of a particular row, as the row changes values. While + there are different kinds of relational patterns that make use of a + "version id column" in different ways, SQLAlchemy's ORM includes a particular + feature that allows for such a column to be configured as a means of + testing for stale data when a row is being UPDATEd with new information. + If the last known "version" of this column does not match that of the + row when we try to put new data into the row, we know that we are + acting on stale information. + + There are also other ways of storing "versioned" rows in a database, + often referred to as "temporal" data. In addition to SQLAlchemy's + versioning feature, a few more examples are also present in the + documentation, see the links below. + + .. seealso:: + + :ref:`mapper_version_counter` - SQLAlchemy's built-in version id feature. + + :ref:`examples_versioning` - other examples of mappings that version rows + temporally. + + registry + An object, typically globally accessible, that contains long-lived + information about some program state that is generally useful to many + parts of a program. + + .. seealso:: + + `Registry (via Martin Fowler) `_ + + cascade + A term used in SQLAlchemy to describe how an ORM persistence action that + takes place on a particular object would extend into other objects + which are directly associated with that object. In SQLAlchemy, these + object associations are configured using the :func:`.relationship` + construct. :func:`.relationship` contains a parameter called + :paramref:`.relationship.cascade` which provides options on how certain + persistence operations may cascade. + + The term "cascades" as well as the general architecture of this system + in SQLAlchemy was borrowed, for better or worse, from the Hibernate + ORM. + + .. seealso:: + + :ref:`unitofwork_cascades` + + dialect + In SQLAlchemy, the "dialect" is a Python object that represents information + and methods that allow database operations to proceed on a particular + kind of database backend and a particular kind of Python driver (or + :term`DBAPI`) for that database. SQLAlchemy dialects are subclasses + of the :class:`.Dialect` class. + + .. seealso:: + + :ref:`engines_toplevel` + discriminator A result-set column which is used during :term:`polymorphic` loading to determine what kind of mapped class should be applied to a particular @@ -159,7 +251,16 @@ Glossary .. seealso:: - Martin Fowler - Identity Map - http://martinfowler.com/eaaCatalog/identityMap.html + `Identity Map (via Martin Fowler) `_ + + lazy initialization + A tactic of delaying some initialization action, such as creating objects, + populating data, or establishing connectivity to other services, until + those resources are required. + + .. seealso:: + + `Lazy initialization (via Wikipedia) `_ lazy load lazy loads @@ -174,16 +275,33 @@ Glossary the complexity and time spent within object fetches can sometimes be reduced, in that attributes for related tables don't need to be addressed - immediately. + immediately. Lazy loading is the opposite of :term:`eager loading`. .. seealso:: - `Lazy Load (on Martin Fowler) `_ + `Lazy Load (via Martin Fowler) `_ :term:`N plus one problem` :doc:`orm/loading_relationships` + eager load + eager loads + eager loaded + eager loading + + In object relational mapping, an "eager load" refers to + an attribute that is populated with its database-side value + at the same time as when the object itself is loaded from the database. + In SQLAlchemy, "eager loading" usually refers to related collections + of objects that are mapped using the :func:`.relationship` construct. + Eager loading is the opposite of :term:`lazy loading`. + + .. seealso:: + + :doc:`orm/loading_relationships` + + mapping mapped We say a class is "mapped" when it has been passed through the @@ -191,7 +309,7 @@ Glossary class with a database table or other :term:`selectable` construct, so that instances of it can be persisted using a :class:`.Session` as well as loaded using a - :class:`.Query`. + :class:`.query.Query`. N plus one problem The N plus one problem is a common side effect of the @@ -239,7 +357,7 @@ Glossary The two SQLAlchemy objects that make the most use of method chaining are the :class:`~.expression.Select` - object and the :class:`~.orm.query.Query` object. + object and the :class:`.orm.query.Query` object. For example, a :class:`~.expression.Select` object can be assigned two expressions to its WHERE clause as well as an ORDER BY clause by calling upon the :meth:`~.Select.where` @@ -325,7 +443,7 @@ Glossary .. seealso:: - `Domain Model (wikipedia) `_ + `Domain Model (via Wikipedia) `_ unit of work This pattern is where the system transparently keeps @@ -336,7 +454,7 @@ Glossary .. seealso:: - `Unit of Work by Martin Fowler `_ + `Unit of Work (via Martin Fowler) `_ :doc:`orm/session` @@ -530,7 +648,7 @@ Glossary :term:`durability` - http://en.wikipedia.org/wiki/ACID_Model + `ACID Model (via Wikipedia) `_ atomicity Atomicity is one of the components of the :term:`ACID` model, @@ -545,7 +663,7 @@ Glossary :term:`ACID` - http://en.wikipedia.org/wiki/Atomicity_(database_systems) + `Atomicity (via Wikipedia) `_ consistency Consistency is one of the components of the :term:`ACID` model, @@ -560,10 +678,11 @@ Glossary :term:`ACID` - http://en.wikipedia.org/wiki/Consistency_(database_systems) + `Consistency (via Wikipedia) `_ isolation isolated + isolation level The isolation property of the :term:`ACID` model ensures that the concurrent execution of transactions results in a system state that would be @@ -577,7 +696,57 @@ Glossary :term:`ACID` - http://en.wikipedia.org/wiki/Isolation_(database_systems) + `Isolation (via Wikipedia) `_ + + :term:`read uncommitted` + + :term:`read committed` + + :term:`repeatable read` + + :term:`serializable` + + repeatable read + One of the four database :term:`isolation` levels, repeatable read + features all of the isolation of :term:`read committed`, and + additionally features that any particular row that is read within a + transaction is guaranteed from that point to not have any subsequent + external changes in value (i.e. from other concurrent UPDATE + statements) for the duration of that transaction. + + read committed + One of the four database :term:`isolation` levels, read committed + features that the transaction will not be exposed to any data from + other concurrent transactions that has not been committed yet, + preventing so-called "dirty reads". However, under read committed + there can be non-repeatable reads, meaning data in a row may change + when read a second time if another transaction has committed changes. + + read uncommitted + One of the four database :term:`isolation` levels, read uncommitted + features that changes made to database data within a transaction will + not become permanent until the transaction is committed. However, + within read uncommitted, it may be possible for data that is not + committed in other transactions to be viewable within the scope of + another transaction; these are known as "dirty reads". + + serializable + One of the four database :term:`isolation` levels, serializable + features all of the isolation of :term:`repeatable read`, and + additionally within a lock-based approach guarantees that so-called + "phantom reads" cannot occur; this means that rows which are INSERTed + or DELETEd within the scope of other transactions will not be + detectable within this transaction. A row that is read within this + transaction is guaranteed to continue existing, and a row that does not + exist is guaranteed that it cannot appear of inserted from another + transaction. + + Serializable isolation typically relies upon locking of rows or ranges + of rows in order to achieve this effect and can increase the chance of + deadlocks and degrade performance. There are also non-lock based + schemes however these necessarily rely upon rejecting transactions if + write collisions are detected. + durability Durability is a property of the :term:`ACID` model @@ -593,7 +762,7 @@ Glossary :term:`ACID` - http://en.wikipedia.org/wiki/Durability_(database_systems) + `Durability (via Wikipedia) `_ RETURNING This is a non-SQL standard clause provided in various forms by @@ -970,7 +1139,7 @@ Glossary :term:`primary key` - http://en.wikipedia.org/wiki/Candidate_key + `Candidate key (via Wikipedia) `_ https://www.databasestar.com/database-keys/ @@ -978,7 +1147,7 @@ Glossary primary key constraint A :term:`constraint` that uniquely defines the characteristics - of each :term:`row`. The primary key has to consist of + of each row in a table. The primary key has to consist of characteristics that cannot be duplicated by any other row. The primary key may consist of a single attribute or multiple attributes in combination. @@ -998,7 +1167,7 @@ Glossary .. seealso:: - http://en.wikipedia.org/wiki/Primary_Key + `Primary key (via Wikipedia) `_ foreign key constraint A referential constraint between two tables. A foreign key is a field or set of fields in a @@ -1016,7 +1185,7 @@ Glossary .. seealso:: - http://en.wikipedia.org/wiki/Foreign_key_constraint + `Foreign Key Constraint (via Wikipedia) `_ check constraint @@ -1036,7 +1205,7 @@ Glossary .. seealso:: - http://en.wikipedia.org/wiki/Check_constraint + `CHECK constraint (via Wikipedia) `_ unique constraint unique key index @@ -1053,7 +1222,7 @@ Glossary .. seealso:: - http://en.wikipedia.org/wiki/Unique_key#Defining_unique_keys + `Unique key (via Wikipedia) `_ transient This describes one of the major object states which diff --git a/doc/build/orm/examples.rst b/doc/build/orm/examples.rst index d3a1f8d319..e8bb894fd4 100644 --- a/doc/build/orm/examples.rst +++ b/doc/build/orm/examples.rst @@ -90,6 +90,8 @@ XML Persistence .. automodule:: examples.elementtree +.. _examples_versioning: + Versioning Objects ------------------ diff --git a/doc/build/orm/tutorial.rst b/doc/build/orm/tutorial.rst index 05d49c8aea..e6e1b71c35 100644 --- a/doc/build/orm/tutorial.rst +++ b/doc/build/orm/tutorial.rst @@ -1666,7 +1666,7 @@ was emitted. If you want to reduce the number of queries (dramatically, in many we can apply an :term:`eager load` to the query operation. SQLAlchemy offers three types of eager loading, two of which are automatic, and a third which involves custom criterion. All three are usually invoked via functions known -as :term:`query options` which give additional instructions to the :class:`.Query` on how +as query options which give additional instructions to the :class:`.Query` on how we would like various attributes to be loaded, via the :meth:`.Query.options` method. Selectin Load