Add missing definitions to glossary

improve formatting

Change-Id: Iea3b72187d7c8020e18babb72a53c39c5aeec68c
(cherry picked from commit 1b1fe518512441959f4ac9c9b715271e2b6d7977)

3 files changed, 190 insertions, 19 deletions

diff --git a/doc/build/glossary.rst b/doc/build/glossary.rst
index c431fce3d..83bf0b43a 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) <https://en.wikipedia.org/wiki/Relational_algebra>`_
+
+    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) <https://www.martinfowler.com/eaaCatalog/metadataMapping.html>`_
+
+    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) <https://martinfowler.com/eaaCatalog/registry.html>`_
+
+    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) <http://martinfowler.com/eaaCatalog/identityMap.html>`_
+
+    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) <https://en.wikipedia.org/wiki/Lazy_initialization>`_
 
     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) <http://martinfowler.com/eaaCatalog/lazyLoad.html>`_
+            `Lazy Load (via Martin Fowler) <http://martinfowler.com/eaaCatalog/lazyLoad.html>`_
 
             :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) <http://en.wikipedia.org/wiki/Domain_model>`_
+            `Domain Model (via Wikipedia) <http://en.wikipedia.org/wiki/Domain_model>`_
 
     unit of work
         This pattern is where the system transparently keeps
@@ -336,7 +454,7 @@ Glossary
 
         .. seealso::
 
-            `Unit of Work by Martin Fowler <http://martinfowler.com/eaaCatalog/unitOfWork.html>`_
+            `Unit of Work (via Martin Fowler) <http://martinfowler.com/eaaCatalog/unitOfWork.html>`_
 
             :doc:`orm/session`
 
@@ -530,7 +648,7 @@ Glossary
 
             :term:`durability`
 
-            http://en.wikipedia.org/wiki/ACID_Model
+            `ACID Model (via Wikipedia) <http://en.wikipedia.org/wiki/ACID_Model>`_
 
     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) <http://en.wikipedia.org/wiki/Atomicity_(database_systems)>`_
 
     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) <http://en.wikipedia.org/wiki/Consistency_(database_systems)>`_
 
     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) <http://en.wikipedia.org/wiki/Isolation_(database_systems)>`_
+
+            :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) <http://en.wikipedia.org/wiki/Durability_(database_systems)>`_
 
     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) <http://en.wikipedia.org/wiki/Candidate_key>`_
 
             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) <http://en.wikipedia.org/wiki/Primary_Key>`_
 
     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) <http://en.wikipedia.org/wiki/Foreign_key_constraint>`_
 
     check constraint
 
@@ -1036,7 +1205,7 @@ Glossary
 
         .. seealso::
 
-            http://en.wikipedia.org/wiki/Check_constraint
+            `CHECK constraint (via Wikipedia) <http://en.wikipedia.org/wiki/Check_constraint>`_
 
     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) <http://en.wikipedia.org/wiki/Unique_key#Defining_unique_keys>`_
 
     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 6c40639e0..57efb26af 100644
--- a/doc/build/orm/examples.rst
+++ b/doc/build/orm/examples.rst
@@ -83,6 +83,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 a168760b3..77567220b 100644
--- a/doc/build/orm/tutorial.rst
+++ b/doc/build/orm/tutorial.rst
@@ -1664,7 +1664,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.
 
 Subquery Load