diff options
Diffstat (limited to 'doc/build/glossary.rst')
| -rw-r--r-- | doc/build/glossary.rst | 641 |
1 files changed, 635 insertions, 6 deletions
diff --git a/doc/build/glossary.rst b/doc/build/glossary.rst index 564668691..defeabcff 100644 --- a/doc/build/glossary.rst +++ b/doc/build/glossary.rst @@ -1,15 +1,11 @@ +:orphan: + .. _glossary: ======== Glossary ======== -.. note:: - - The Glossary is a brand new addition to the documentation. While - sparse at the moment we hope to fill it up with plenty of new - terms soon! - .. glossary:: :sorted: @@ -95,8 +91,26 @@ Glossary class which each represent a particular database column or relationship to a related class. + identity map + A mapping between Python objects and their database identities. + The identity map is a collection that's associated with an + ORM :term:`session` object, and maintains a single instance + of every database object keyed to its identity. The advantage + to this pattern is that all operations which occur for a particular + database identity are transparently coordinated onto a single + object instance. When using an identity map in conjunction with + an :term:`isolated` transaction, having a reference + to an object that's known to have a particular primary key can + be considered from a practical standpoint to be a + proxy to the actual database row. + + .. seealso:: + + Martin Fowler - Identity Map - http://martinfowler.com/eaaCatalog/identityMap.html + lazy load lazy loads + lazy loading In object relational mapping, a "lazy load" refers to an attribute that does not contain its database-side value for some period of time, typically when the object is @@ -249,6 +263,15 @@ Glossary `PEP 249 - Python Database API Specification v2.0 <http://www.python.org/dev/peps/pep-0249/>`_ + domain model + + A domain model in problem solving and software engineering is a conceptual model of all the topics related to a specific problem. It describes the various entities, their attributes, roles, and relationships, plus the constraints that govern the problem domain. + + (via Wikipedia) + + .. seealso:: + + `Domain Model (wikipedia) <http://en.wikipedia.org/wiki/Domain_model>`_ unit of work This pattern is where the system transparently keeps @@ -263,6 +286,16 @@ Glossary :doc:`orm/session` + Session + The container or scope for ORM database operations. Sessions + load instances from the database, track changes to mapped + instances and persist changes in a single unit of work when + flushed. + + .. seealso:: + + :doc:`orm/session` + columns clause The portion of the ``SELECT`` statement which enumerates the SQL expressions to be returned in the result set. The expressions @@ -411,3 +444,599 @@ Glossary query via its ``FROM`` clause is not possible, because the correlation can only proceed once the original source rows from the enclosing statement's FROM clause are available. + + + ACID + ACID model + An acronym for "Atomicity, Consistency, Isolation, + Durability"; a set of properties that guarantee that + database transactions are processed reliably. + (via Wikipedia) + + .. seealso:: + + :term:`atomicity` + + :term:`consistency` + + :term:`isolation` + + :term:`durability` + + http://en.wikipedia.org/wiki/ACID_Model + + atomicity + Atomicity is one of the components of the :term:`ACID` model, + and requires that each transaction is "all or nothing": + if one part of the transaction fails, the entire transaction + fails, and the database state is left unchanged. An atomic + system must guarantee atomicity in each and every situation, + including power failures, errors, and crashes. + (via Wikipedia) + + .. seealso:: + + :term:`ACID` + + http://en.wikipedia.org/wiki/Atomicity_(database_systems) + + consistency + Consistency is one of the compoments of the :term:`ACID` model, + and ensures that any transaction will + bring the database from one valid state to another. Any data + written to the database must be valid according to all defined + rules, including but not limited to :term:`constraints`, cascades, + triggers, and any combination thereof. + (via Wikipedia) + + .. seealso:: + + :term:`ACID` + + http://en.wikipedia.org/wiki/Consistency_(database_systems) + + isolation + isolated + The isolation property of the :term:`ACID` model + ensures that the concurrent execution + of transactions results in a system state that would be + obtained if transactions were executed serially, i.e. one + after the other. Each transaction must execute in total + isolation i.e. if T1 and T2 execute concurrently then each + should remain independent of the other. + (via Wikipedia) + + .. seealso:: + + :term:`ACID` + + http://en.wikipedia.org/wiki/Isolation_(database_systems) + + durability + Durability is a property of the :term:`ACID` model + which means that once a transaction has been committed, + it will remain so, even in the event of power loss, crashes, + or errors. In a relational database, for instance, once a + group of SQL statements execute, the results need to be stored + permanently (even if the database crashes immediately + thereafter). + (via Wikipedia) + + .. seealso:: + + :term:`ACID` + + http://en.wikipedia.org/wiki/Durability_(database_systems) + + RETURNING + This is a non-SQL standard clause provided in various forms by + certain backends, which provides the service of returning a result + set upon execution of an INSERT, UPDATE or DELETE statement. Any set + of columns from the matched rows can be returned, as though they were + produced from a SELECT statement. + + The RETURNING clause provides both a dramatic performance boost to + common update/select scenarios, including retrieval of inline- or + default- generated primary key values and defaults at the moment they + were created, as well as a way to get at server-generated + default values in an atomic way. + + An example of RETURNING, idiomatic to Postgresql, looks like:: + + INSERT INTO user_account (name) VALUES ('new name') RETURNING id, timestamp + + Above, the INSERT statement will provide upon execution a result set + which includes the values of the columns ``user_account.id`` and + ``user_account.timestamp``, which above should have been generated as default + values as they are not included otherwise (but note any series of columns + or SQL expressions can be placed into RETURNING, not just default-value columns). + + The backends that currently support + RETURNING or a similar construct are Postgresql, SQL Server, Oracle, + and Firebird. The Postgresql and Firebird implementations are generally + full featured, whereas the implementations of SQL Server and Oracle + have caveats. On SQL Server, the clause is known as "OUTPUT INSERTED" + for INSERT and UPDATE statements and "OUTPUT DELETED" for DELETE statements; + the key caveat is that triggers are not supported in conjunction with this + keyword. On Oracle, it is known as "RETURNING...INTO", and requires that the + value be placed into an OUT paramter, meaning not only is the syntax awkward, + but it can also only be used for one row at a time. + + SQLAlchemy's :meth:`.UpdateBase.returning` system provides a layer of abstraction + on top of the RETURNING systems of these backends to provide a consistent + interface for returning columns. The ORM also includes many optimizations + that make use of RETURNING when available. + + one to many + A style of :func:`~sqlalchemy.orm.relationship` which links + the primary key of the parent mapper's table to the foreign + key of a related table. Each unique parent object can + then refer to zero or more unique related objects. + + The related objects in turn will have an implicit or + explicit :term:`many to one` relationship to their parent + object. + + An example one to many schema (which, note, is identical + to the :term:`many to one` schema): + + .. sourcecode:: sql + + CREATE TABLE department ( + id INTEGER PRIMARY KEY, + name VARCHAR(30) + ) + + CREATE TABLE employee ( + id INTEGER PRIMARY KEY, + name VARCHAR(30), + dep_id INTEGER REFERENCES department(id) + ) + + The relationship from ``department`` to ``employee`` is + one to many, since many employee records can be associated with a + single department. A SQLAlchemy mapping might look like:: + + class Department(Base): + __tablename__ = 'department' + id = Column(Integer, primary_key=True) + name = Column(String(30)) + employees = relationship("Employee") + + class Employee(Base): + __tablename__ = 'employee' + id = Column(Integer, primary_key=True) + name = Column(String(30)) + dep_id = Column(Integer, ForeignKey('department.id')) + + .. seealso:: + + :term:`relationship` + + :term:`many to one` + + :term:`backref` + + many to one + A style of :func:`~sqlalchemy.orm.relationship` which links + a foreign key in the parent mapper's table to the primary + key of a related table. Each parent object can + then refer to exactly zero or one related object. + + The related objects in turn will have an implicit or + explicit :term:`one to many` relationship to any number + of parent objects that refer to them. + + An example many to one schema (which, note, is identical + to the :term:`one to many` schema): + + .. sourcecode:: sql + + CREATE TABLE department ( + id INTEGER PRIMARY KEY, + name VARCHAR(30) + ) + + CREATE TABLE employee ( + id INTEGER PRIMARY KEY, + name VARCHAR(30), + dep_id INTEGER REFERENCES department(id) + ) + + + The relationship from ``employee`` to ``department`` is + many to one, since many employee records can be associated with a + single department. A SQLAlchemy mapping might look like:: + + class Department(Base): + __tablename__ = 'department' + id = Column(Integer, primary_key=True) + name = Column(String(30)) + + class Employee(Base): + __tablename__ = 'employee' + id = Column(Integer, primary_key=True) + name = Column(String(30)) + dep_id = Column(Integer, ForeignKey('department.id')) + department = relationship("Department") + + .. seealso:: + + :term:`relationship` + + :term:`one to many` + + :term:`backref` + + backref + bidirectional relationship + An extension to the :term:`relationship` system whereby two + distinct :func:`~sqlalchemy.orm.relationship` objects can be + mutually associated with each other, such that they coordinate + in memory as changes occur to either side. The most common + way these two relationships are constructed is by using + the :func:`~sqlalchemy.orm.relationship` function explicitly + for one side and specifying the ``backref`` keyword to it so that + the other :func:`~sqlalchemy.orm.relationship` is created + automatically. We can illustrate this against the example we've + used in :term:`one to many` as follows:: + + class Department(Base): + __tablename__ = 'department' + id = Column(Integer, primary_key=True) + name = Column(String(30)) + employees = relationship("Employee", backref="department") + + class Employee(Base): + __tablename__ = 'employee' + id = Column(Integer, primary_key=True) + name = Column(String(30)) + dep_id = Column(Integer, ForeignKey('department.id')) + + A backref can be applied to any relationship, including one to many, + many to one, and :term:`many to many`. + + .. seealso:: + + :term:`relationship` + + :term:`one to many` + + :term:`many to one` + + :term:`many to many` + + many to many + A style of :func:`sqlalchemy.orm.relationship` which links two tables together + via an intermediary table in the middle. Using this configuration, + any number of rows on the left side may refer to any number of + rows on the right, and vice versa. + + A schema where employees can be associated with projects: + + .. sourcecode:: sql + + CREATE TABLE employee ( + id INTEGER PRIMARY KEY, + name VARCHAR(30) + ) + + CREATE TABLE project ( + id INTEGER PRIMARY KEY, + name VARCHAR(30) + ) + + CREATE TABLE employee_project ( + employee_id INTEGER PRIMARY KEY, + project_id INTEGER PRIMARY KEY, + FOREIGN KEY employee_id REFERENCES employee(id), + FOREIGN KEY project_id REFERENCES project(id) + ) + + Above, the ``employee_project`` table is the many-to-many table, + which naturally forms a composite primary key consisting + of the primary key from each related table. + + In SQLAlchemy, the :func:`sqlalchemy.orm.relationship` function + can represent this style of relationship in a mostly + transparent fashion, where the many-to-many table is + specified using plain table metadata:: + + class Employee(Base): + __tablename__ = 'employee' + + id = Column(Integer, primary_key) + name = Column(String(30)) + + projects = relationship( + "Project", + secondary=Table('employee_project', Base.metadata, + Column("employee_id", Integer, ForeignKey('employee.id'), + primary_key=True), + Column("project_id", Integer, ForeignKey('project.id'), + primary_key=True) + ), + backref="employees" + ) + + class Project(Base): + __tablename__ = 'project' + + id = Column(Integer, primary_key) + name = Column(String(30)) + + Above, the ``Employee.projects`` and back-referencing ``Project.employees`` + collections are defined:: + + proj = Project(name="Client A") + + emp1 = Employee(name="emp1") + emp2 = Employee(name="emp2") + + proj.employees.extend([emp1, emp2]) + + .. seealso:: + + :term:`association relationship` + + :term:`relationship` + + :term:`one to many` + + :term:`many to one` + + relationship + relationships + A connecting unit between two mapped classes, corresponding + to some relationship between the two tables in the database. + + The relationship is defined using the SQLAlchemy function + :func:`~sqlalchemy.orm.relationship`. Once created, SQLAlchemy + inspects the arguments and underlying mappings involved + in order to classify the relationship as one of three types: + :term:`one to many`, :term:`many to one`, or :term:`many to many`. + With this classification, the relationship construct + handles the task of persisting the appropriate linkages + in the database in response to in-memory object associations, + as well as the job of loading object references and collections + into memory based on the current linkages in the + database. + + .. seealso:: + + :ref:`relationship_config_toplevel` + + association relationship + A two-tiered :term:`relationship` which links two tables + together using an association table in the middle. The + association relationship differs from a :term:`many to many` + relationship in that the many-to-many table is mapped + by a full class, rather than invisibly handled by the + :func:`sqlalchemy.orm.relationship` construct as in the case + with many-to-many, so that additional attributes are + explicitly available. + + For example, if we wanted to associate employees with + projects, also storing the specific role for that employee + with the project, the relational schema might look like: + + .. sourcecode:: sql + + CREATE TABLE employee ( + id INTEGER PRIMARY KEY, + name VARCHAR(30) + ) + + CREATE TABLE project ( + id INTEGER PRIMARY KEY, + name VARCHAR(30) + ) + + CREATE TABLE employee_project ( + employee_id INTEGER PRIMARY KEY, + project_id INTEGER PRIMARY KEY, + role_name VARCHAR(30), + FOREIGN KEY employee_id REFERENCES employee(id), + FOREIGN KEY project_id REFERENCES project(id) + ) + + A SQLAlchemy declarative mapping for the above might look like:: + + class Employee(Base): + __tablename__ = 'employee' + + id = Column(Integer, primary_key) + name = Column(String(30)) + + + class Project(Base): + __tablename__ = 'project' + + id = Column(Integer, primary_key) + name = Column(String(30)) + + + class EmployeeProject(Base): + __tablename__ = 'employee_project' + + employee_id = Column(Integer, ForeignKey('employee.id'), primary_key=True) + project_id = Column(Integer, ForeignKey('project.id'), primary_key=True) + role_name = Column(String(30)) + + project = relationship("Project", backref="project_employees") + employee = relationship("Employee", backref="employee_projects") + + + Employees can be added to a project given a role name:: + + proj = Project(name="Client A") + + emp1 = Employee(name="emp1") + emp2 = Employee(name="emp2") + + proj.project_employees.extend([ + EmployeeProject(employee=emp1, role="tech lead"), + EmployeeProject(employee=emp2, role="account executive") + ]) + + .. seealso:: + + :term:`many to many` + + constraint + constraints + constrained + Rules established within a relational database that ensure + the validity and consistency of data. Common forms + of constraint include :term:`primary key constraint`, + :term:`foreign key constraint`, and :term:`check constraint`. + + candidate key + + A :term:`relational algebra` term referring to an attribute or set + of attributes that form a uniquely identifying key for a + row. A row may have more than one candidate key, each of which + is suitable for use as the primary key of that row. + The primary key of a table is always a candidate key. + + .. seealso:: + + :term:`primary key` + + http://en.wikipedia.org/wiki/Candidate_key + + primary key + primary key constraint + + A :term:`constraint` that uniquely defines the characteristics + of each :term:`row`. 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. + (via Wikipedia) + + The primary key of a table is typically, though not always, + defined within the ``CREATE TABLE`` :term:`DDL`: + + .. sourcecode:: sql + + CREATE TABLE employee ( + emp_id INTEGER, + emp_name VARCHAR(30), + dep_id INTEGER, + PRIMARY KEY (emp_id) + ) + + .. seealso:: + + 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 + relational table that matches a :term:`candidate key` of another table. + The foreign key can be used to cross-reference tables. + (via Wikipedia) + + A foreign key constraint can be added to a table in standard + SQL using :term:`DDL` like the following: + + .. sourcecode:: sql + + ALTER TABLE employee ADD CONSTRAINT dep_id_fk + FOREIGN KEY (employee) REFERENCES department (dep_id) + + .. seealso:: + + http://en.wikipedia.org/wiki/Foreign_key_constraint + + check constraint + + A check constraint is a + condition that defines valid data when adding or updating an + entry in a table of a relational database. A check constraint + is applied to each row in the table. + + (via Wikipedia) + + A check constraint can be added to a table in standard + SQL using :term:`DDL` like the following: + + .. sourcecode:: sql + + ALTER TABLE distributors ADD CONSTRAINT zipchk CHECK (char_length(zipcode) = 5); + + .. seealso:: + + http://en.wikipedia.org/wiki/Check_constraint + + unique constraint + unique key index + A unique key index can uniquely identify each row of data + values in a database table. A unique key index comprises a + single column or a set of columns in a single database table. + No two distinct rows or data records in a database table can + have the same data value (or combination of data values) in + those unique key index columns if NULL values are not used. + Depending on its design, a database table may have many unique + key indexes but at most one primary key index. + + (via Wikipedia) + + .. seealso:: + + http://en.wikipedia.org/wiki/Unique_key#Defining_unique_keys + + transient + This describes one of the four major object states which + an object can have within a :term:`session`; a transient object + is a new object that doesn't have any database identity + and has not been associated with a session yet. When the + object is added to the session, it moves to the + :term:`pending` state. + + .. seealso:: + + :ref:`session_object_states` + + pending + This describes one of the four major object states which + an object can have within a :term:`session`; a pending object + is a new object that doesn't have any database identity, + but has been recently associated with a session. When + the session emits a flush and the row is inserted, the + object moves to the :term:`persistent` state. + + .. seealso:: + + :ref:`session_object_states` + + persistent + This describes one of the four major object states which + an object can have within a :term:`session`; a persistent object + is an object that has a database identity (i.e. a primary key) + and is currently associated with a session. Any object + that was previously :term:`pending` and has now been inserted + is in the persistent state, as is any object that's + been loaded by the session from the database. When a + persistent object is removed from a session, it is known + as :term:`detached`. + + .. seealso:: + + :ref:`session_object_states` + + detached + This describes one of the four major object states which + an object can have within a :term:`session`; a detached object + is an object that has a database identity (i.e. a primary key) + but is not associated with any session. An object that + was previously :term:`persistent` and was removed from its + session either because it was expunged, or the owning + session was closed, moves into the detached state. + The detached state is generally used when objects are being + moved between sessions or when being moved to/from an external + object cache. + + .. seealso:: + + :ref:`session_object_states` |