> > It seems like this could be a good idea, still the patch has been > waiting on his author for more than two weeks now, so I have marked it > as returned with feedback. >
In light of feedback, I enlisted the help of an actual technical writer (Roger Harkavy, CCed) and we eventually found the time to take a second pass at this. Attached is a revised patch.
From f087e44fe4db7996880cf4df982297018d444363 Mon Sep 17 00:00:00 2001 From: Corey Huinker <corey.huin...@gmail.com> Date: Wed, 12 Feb 2020 04:17:59 +0000 Subject: [PATCH] add glossary page with initial definitions --- doc/src/sgml/filelist.sgml | 1 + doc/src/sgml/glossary.sgml | 540 +++++++++++++++++++++++++++++++++++++ doc/src/sgml/postgres.sgml | 1 + 3 files changed, 542 insertions(+) create mode 100644 doc/src/sgml/glossary.sgml diff --git a/doc/src/sgml/filelist.sgml b/doc/src/sgml/filelist.sgml index 3da2365ea9..504c8a6326 100644 --- a/doc/src/sgml/filelist.sgml +++ b/doc/src/sgml/filelist.sgml @@ -170,6 +170,7 @@ <!ENTITY limits SYSTEM "limits.sgml"> <!ENTITY acronyms SYSTEM "acronyms.sgml"> +<!ENTITY glossary SYSTEM "glossary.sgml"> <!ENTITY features-supported SYSTEM "features-supported.sgml"> <!ENTITY features-unsupported SYSTEM "features-unsupported.sgml"> diff --git a/doc/src/sgml/glossary.sgml b/doc/src/sgml/glossary.sgml new file mode 100644 index 0000000000..1b881690fa --- /dev/null +++ b/doc/src/sgml/glossary.sgml @@ -0,0 +1,540 @@ +<!-- doc/src/sgml/glossary.sgml --> + +<appendix id="glossary"> + <title>Glossary</title> + <para> + This is a list of terms and their definitions in the context of <productname>PostgreSQL</productname> and databases in general. + </para> + <glosslist> + <glossentry> + <glossterm>Aggregate</glossterm> + <glossdef> + <para> + The act of combining a defined collection of data values into a single value that may not be the same type as the original values. Aggregate <glossterm>functions</glossterm> are most often used with Grouping operations which define the separate sets of data by the common values shared within those sets. + </para> + </glossdef> + </glossentry> + + <glossentry> + <glossterm>Analytic</glossterm> + <glossdef> + <para> + A <glossterm>function</glossterm> whose computed value can reference values found in nearby <glossterm>rows</glossterm> of the same result set. + </para> + </glossdef> + </glossentry> + + <glossentry> + <glossterm>Atomic</glossterm> + <glossdef> + <para> + When referring to the value of an <glossterm>attribute</glossterm> or <glossterm>datum</glossterm>: cannot be broken up into smaller components. + </para> + <para> + When referring to an operation: An event that cannot be partially completed; it must either completely succeed or completely fail. A series of <acronym>SQL</acronym> statements can be combined into a <glossterm>transaction</glossterm>, and that transaction is described as atomic. + </para> + </glossdef> + </glossentry> + + <glossentry> + <glossterm>Attribute</glossterm> + <glossdef> + <para> + A typed data element found within a <glossterm>tuple</glossterm> or <glossterm>relation</glossterm> or <glossterm>table</glossterm>. + </para> + </glossdef> + </glossentry> + + <glossentry> + <glossterm>BYTEA</glossterm> + <glossdef> + <para> + A data type for storing binary data. It is roughly analogous to the <literal>BLOB</literal> data type in other database products. + </para> + </glossdef> + </glossentry> + + <glossentry> + <glossterm>Cast</glossterm> + <glossdef> + <para> + The act of converting of a <glossterm>datum</glossterm> from its current data type to another data type. + </para> + </glossdef> + </glossentry> + + <glossentry> + <glossterm>Check Constraint</glossterm> + <glossdef> + <para> + A type of <glossterm>constraint</glossterm> defined for a <glossterm>relation</glossterm> which restricts the values allowed in one or more <glossterm>attribute</glossterm>s. The check constraint can make reference to any attribute in the relation, but cannot reference other rows of the same relation or other relations. + </para> + </glossdef> + </glossentry> + + <glossentry> + <glossterm>Column</glossterm> + <glossdef> + <para> + An <glossterm>attribute</glossterm> found in a <glossterm>table</glossterm> or <glossterm>view</glossterm>. + </para> + </glossdef> + </glossentry> + + <glossentry> + <glossterm>Commit</glossterm> + <glossdef> + <para> + The act of finalizing a <glossterm>transaction</glossterm> within the database. + </para> + </glossdef> + </glossentry> + + <glossentry> + <glossterm>Concurrency</glossterm> + <glossdef> + <para> + The concept that multiple independent operations can be happening within the database at the same time. + </para> + </glossdef> + </glossentry> + + <glossentry> + <glossterm>Constraint</glossterm> + <glossdef> + <para> + A method of restricting the values of data allowed within a <glossterm>relation</glossterm>. Constraints can currently be of the following types: <glossterm>Check Constraint</glossterm>, <glossterm>Unique Constraint</glossterm>, and <glossterm>Exclusion Constraint</glossterm>. + </para> + </glossdef> + </glossentry> + + <glossentry> + <glossterm>Datum</glossterm> + <glossdef> + <para> + The internal representation of a <acronym>SQL</acronym> datatype. + </para> + </glossdef> + </glossentry> + + <glossentry> + <glossterm>Delete</glossterm> + <glossdef> + <para> + A <acronym>SQL</acronym> command that removes rows from a given <glossterm>table</glossterm> or <glossterm>relation</glossterm>. + </para> + </glossdef> + </glossentry> + + <glossentry> + <glossterm>Exclusion Constraint</glossterm> + <glossdef> + <para> + Exclusion constraints define both a set of <glossterm>column</glossterm>s for matching <glossterm>row</glossterm>s, and rules where values in one row would conflict with values in another. + </para> + </glossdef> + </glossentry> + + <glossentry> + <glossterm>Foreign Data Wrapper</glossterm> + <glossdef> + <para> + A means of representing data outside the local database so that it appears as if it were in local tables. With a Foreign Data Wrapper it is possible to define a <glossterm>Foreign Server</glossterm> and <glossterm>Foreign Tables</glossterm>. + </para> + </glossdef> + </glossentry> + + <glossentry> + <glossterm>Foreign Key</glossterm> + <glossdef> + <para> + A type of <glossterm>constraint</glossterm> defined on one or more columns in a <glossterm>table</glossterm> which requires the value in those <glossterm>column</glossterm>s to uniquely identify a <glossterm>row</glossterm> in the specified table. + </para> + </glossdef> + </glossentry> + + <glossentry> + <glossterm>Foreign Server</glossterm> + <glossdef> + <para> + A named collection of <glossterm>Foreign Table</glossterm>s which all use the same <glossterm>Foreign Data Wrapper</glossterm> and have other configured <glossterm>attribute</glossterm>s in common. + </para> + </glossdef> + </glossentry> + + <glossentry> + <glossterm>Foreign Table</glossterm> + <glossdef> + <para> + A <glossterm>relation</glossterm> which appears to have <glossterm>row</glossterm>s and <glossterm>column</glossterm>s like a regular <glossterm>table</glossterm>, but when queried will instead forward the request for data through its <glossterm>Foreign Data Wrapper</glossterm>, which will return results structured according to the definition of the Foreign Table. + </para> + </glossdef> + </glossentry> + + <glossentry> + <glossterm>Function</glossterm> + <glossdef> + <para> + Any pre-defined transformation of data. Many functions are already defined within <productname>PostgreSQL</productname> itself, but user-defined <glossterm>function</glossterm>s can be added. + </para> + </glossdef> + </glossentry> + + <glossentry> + <glossterm>Grant</glossterm> + <glossdef> + <para> + A <acronym>SQL</acronym> command that is used to enable <glossterm>user</glossterm>s or <glossterm>role</glossterm>s to access specific objects within the database. + </para> + </glossdef> + </glossentry> + + <glossentry> + <glossterm>Index</glossterm> + <glossdef> + <para> + A relation that contains data derived from a <glossterm>table</glossterm> (or a <glossterm>relation</glossterm> such as a <glossterm>materialized view</glossterm>) that stores the data in a way that makes specific values easier to retrieve. + </para> + </glossdef> + </glossentry> + + <glossentry> + <glossterm>Insert</glossterm> + <glossdef> + <para> + A <acronym>SQL</acronym> command used to add new data into a <glossterm>table</glossterm>. + </para> + </glossdef> + </glossentry> + + <glossentry> + <glossterm>Join</glossterm> + <glossdef> + <para> + A technique used with <command>SELECT</command> statements to correlate data in one data set (usually a <glossterm>table</glossterm>) with the data set already defined up to the current point in the <command>SELECT</command> statement. + </para> + </glossdef> + </glossentry> + + <glossentry> + <glossterm>Key</glossterm> + <glossdef> + <para> + A means of identifying a <glossterm>row</glossterm> within a <glossterm>table</glossterm> or <glossterm>relation</glossterm> using values contained within one or more <glossterm>attribute</glossterm>s in that table. + </para> + </glossdef> + </glossentry> + + <glossentry> + <glossterm>Lock</glossterm> + <glossdef> + <para> + A mechanism that enables one process to perform actions on a defined <glossterm>object</glossterm> or set of <glossterm>row</glossterm>s within that object while preventing other processes from querying and/or modifying them. + </para> + </glossdef> + </glossentry> + + <glossentry> + <glossterm>Logged</glossterm> + <glossdef> + <para> + A <glossterm>table</glossterm> is considered logged if changes to the table are sent to the <acronym>WAL</acronym>. By default, all regular tables are logged. A table can be defined as unlogged either at creation time or via the <command>ALTER TABLE</command> command. The primary use of unlogged tables is for storing transient work data that must be shared across processes, but with a final result stored in logged tables. <glossterm>Temporary</glossterm> tables are always unlogged. + </para> + </glossdef> + </glossentry> + + <glossentry> + <glossterm>Master</glossterm> + <glossdef> + <para> + The server that is considered the authoritative source of information for databases that are linked via replication. + </para> + </glossdef> + </glossentry> + + <glossentry> + <glossterm>Materialized</glossterm> + <glossdef> + <para> + The state of being stored information rather than just a defined means of accessing the information. This term is used in <glossterm>Materialized View</glossterm>s, meaning that the data derived from the <glossterm>view</glossterm> is actually stored on disk separate from the sources of that data. When materialized is used in describing multi-step queries, it means that the data of a given step is stored (in memory, but that storage may spill over onto disk). + </para> + </glossdef> + </glossentry> + + <glossentry> + <glossterm>Materialized View</glossterm> + <glossdef> + <para> + A <glossterm>relation</glossterm> that is defined in the same way that a <glossterm>view</glossterm> is, but it stores data in the same way that a <glossterm>table</glossterm> does. It cannot be modified via <command>INSERT</command>, <command>UPDATE</command>, or <command>DELETE</command> operations. + </para> + </glossdef> + </glossentry> + + <glossentry> + <glossterm>Null</glossterm> + <glossdef> + <para> + A concept of non-existence that is a central tenet of relational database theory. It represents the absence of value. + </para> + </glossdef> + </glossentry> + + <glossentry> + <glossterm>Partition</glossterm> + <glossdef> + <para> + A member of a collection of <glossterm>table</glossterm>s organized to act as if it were itself a single unified table. Each partition is defined to hold a specific subset of data for the partitioned table that cannot overlap with any other partition in that partitioned table. Therefore, no <glossterm>row</glossterm> of data can belong in more than one partition. + </para> + <para> + Partitions have a name and can be queried directly through that name, but they can also be queried implicitly by querying the name of the partitioned table. + </para> + </glossdef> + </glossentry> + + <glossentry> + <glossterm>Primary Key</glossterm> + <glossdef> + <para> + A <glossterm>unique</glossterm> <glossterm>index</glossterm> defined on a <glossterm>table</glossterm> or other <glossterm>relation</glossterm> that also guarantees that all of the <glossterm>attribute</glossterm>s within the <glossterm>Primary Key</glossterm> do not have null values. As the name implies, there can be only one Primary Key per table, though it is possible to have multiple unique indexes that also have no <glossterm>null</glossterm>-capable attributes. + </para> + </glossdef> + </glossentry> + + <glossentry> + <glossterm>Procedure</glossterm> + <glossdef> + <para> + A defined set of instructions for manipulating data within a database. Procedures can be written in a variety of programming languages. They may appear like <glossterm>function</glossterm>s but are different in that they must be invoked via the <command>CALL</command> command rather than the <command>SELECT</command> or <command>PERFORM</command> commands, and they are allowed to make transactional statements like <command>COMMIT</command> and <command>ROLLBACK</command>. + </para> + </glossdef> + </glossentry> + + <glossentry> + <glossterm>Record</glossterm> + <glossdef> + <para> + A data structure that consists of one or more <glossterm>attribute</glossterm>s in a defined order. A record that belongs to a table or other relation is more commonly called a <glossterm>row</glossterm>. + </para> + </glossdef> + </glossentry> + + <glossentry> + <glossterm>Referential Integrity</glossterm> + <glossdef> + <para> + The means of restricting data in one <glossterm>relation</glossterm> so that it must have matching data in another relation. + </para> + </glossdef> + </glossentry> + + <glossentry> + <glossterm>Relation</glossterm> + <glossdef> + <para> + The generic term for all objects in a database that have a name and a list of attributes defined in a specific order. <glossterm>Table</glossterm>s, <glossterm>view</glossterm>s, <glossterm>foreign table</glossterm>s, <glossterm>materialized view</glossterm>s and <glossterm>index</glossterm>es are all Relations. + </para> + </glossdef> + </glossentry> + + <glossentry> + <glossterm>Replica</glossterm> + <glossdef> + <para> + A database that is paired with a <glossterm>master</glossterm> database and maintains a copy of some or all of the master database's data. The primary reasons for doing this are to allow for greater access to that data, and to maintain availability of the data in the event that the master becomes unavailable. + </para> + </glossdef> + </glossentry> + + <glossentry> + <glossterm>Revoke</glossterm> + <glossdef> + <para> + A command to reduce access to a named set of database objects for a named list of <glossterm>user</glossterm>s and <glossterm>role</glossterm>s. + </para> + </glossdef> + </glossentry> + + <glossentry> + <glossterm>Role</glossterm> + <glossdef> + <para> + A collection of access privileges for the database. Roles are themselves a privilege that can be granted to other roles. This is often done for convenience or to ensure completeness when multiple <glossterm>user</glossterm>s need the same privileges. + </para> + </glossdef> + </glossentry> + + <glossentry> + <glossterm>Rollback</glossterm> + <glossdef> + <para> + A command to undo all of the operations performed since the beginning of a <glossterm>transaction</glossterm>. + </para> + </glossdef> + </glossentry> + + <glossentry> + <glossterm>Row</glossterm> + <glossdef> + <para> + A <glossterm>tuple</glossterm> or <glossterm>record</glossterm> found within a <glossterm>relation</glossterm> or result set. This term is often used interchangably with Tuple and Record. + </para> + </glossdef> + </glossentry> + + <glossentry> + <glossterm>Schema</glossterm> + <glossdef> + <para> + A named collection of database objects organized to facilitate clarity or security. Most often used in the same way a namespace is used in programming languages. All objects belong to exactly one schema, most commonly <literal>public</literal>, the default schema. + </para> + <para> + More generically, the term Schema is used to mean all data descriptions (<glossterm>table</glossterm> definitions, <glossterm>constraint</glossterm>s, comments) for a given database. + </para> + </glossdef> + </glossentry> + + <glossentry> + <glossterm>Select</glossterm> + <glossdef> + <para> + The command used to query a database. Normally, <command>SELECT</command> commands are not expected to modify the database in any way, but it is possible that <glossterm>Functions</glossterm> invoked within the query could have side effects that do modify data. + </para> + </glossdef> + </glossentry> + + <glossentry> + <glossterm>Serializable</glossterm> + <glossdef> + <para> + Database <glossterm>session</glossterm>s in a <glossterm>transaction</glossterm> defined as <literal>SERIALIZABLE</literal> are unable to see changes made to the database by other sessions. In effect, the entire database appears to be frozen in time for the duration of the transaction. + </para> + </glossdef> + </glossentry> + + <glossentry> + <glossterm>Session</glossterm> + <glossdef> + <para> + A connection to the database. Can also be used to describe a series of commands that were issued in the life cycle of a particular connection to the database. + </para> + </glossdef> + </glossentry> + + <glossentry> + <glossterm>Table</glossterm> + <glossdef> + <para> + A collection of <glossterm>tuple</glossterm>s (also known as <glossterm>row</glossterm>s or <glossterm>record</glossterm>s) having a common data structure (the same number of <glossterm>column</glossterm>s, in the same order, having the same type). A table is the most common form of relation in <productname>PostgreSQL</productname>. + </para> + </glossdef> + </glossentry> + + <glossentry> + <glossterm>Temporary</glossterm> + <glossdef> + <para> + Temporary <glossterm>table</glossterm>s are tables that exist either for the lifetime of a <glossterm>session</glossterm> or a <glossterm>transaction</glossterm>, as defined at creation time. The data in them is not visible to other sessions, and is not logged. Temporary tables are most often used to store intermediate data for a multi-step data transformation. + </para> + </glossdef> + </glossentry> + + <glossentry> + <glossterm>Transaction</glossterm> + <glossdef> + <para> + A combination of one or more commands that must act as a single <glossterm>atomic</glossterm> command: they all succeed or fail together, and their effects are not visible to other <glossterm>session</glossterm>s until the <glossterm>transaction</glossterm> is complete. + </para> + </glossdef> + </glossentry> + + <glossentry> + <glossterm>Trigger</glossterm> + <glossdef> + <para> + A <glossterm>function</glossterm> which can be defined to execute whenever a certain operation (<command>INSERT</command>, <command>UPDATE</command>, or <command>DELETE</command>) is applied to that <glossterm>relation</glossterm>. A trigger executes within the same <glossterm>transaction</glossterm> as the statement which invoked it, and if the function fails then the invoking statement also fails. + </para> + </glossdef> + </glossentry> + + <glossentry> + <glossterm>Tuple</glossterm> + <glossdef> + <para> + A collection of <glossterm>attribute</glossterm>s in a fixed order. That order may be defined by the <glossterm>table</glossterm> where the Tuple is found, in which case the Tuple is often called a <glossterm>row</glossterm> or <glossterm>record</glossterm>. It may also be defined by the structure of a result set. + </para> + </glossdef> + </glossentry> + + <glossentry> + <glossterm>Unique</glossterm> + <glossdef> + <para> + The state of having a set of columns with no matching values in the same <glossterm>relation</glossterm>. Most often used in the concept of unique indexes. + </para> + </glossdef> + </glossentry> + + <glossentry> + <glossterm>Unique Constraint</glossterm> + <glossdef> + <para> + A rule that defines a set of <glossterm>column</glossterm>s for which no two <glossterm>row</glossterm>s in the <glossterm>table</glossterm> can share the same set of values. + </para> + </glossdef> + </glossentry> + + <glossentry> + <glossterm>Unlogged</glossterm> + <glossdef> + <para> + A relation that is unlogged will not have changes reflected in the <acronym>WAL</acronym>, which would enable those changes to be duplicated on a <glossterm>replica</glossterm>, and also enables the change to survive a database crash. + </para> + </glossdef> + </glossentry> + + <glossentry> + <glossterm>Update</glossterm> + <glossdef> + <para> + A command used to modify <glossterm>row</glossterm>s that already exist in a specified <glossterm>table</glossterm>. It cannot create <glossterm>row</glossterm>s nor can it remove them. + </para> + </glossdef> + </glossentry> + + <glossentry> + <glossterm>User</glossterm> + <glossdef> + <para> + A specific case of a <glossterm>role</glossterm> that is entitled to access (log into) the database. + </para> + </glossdef> + </glossentry> + + <glossentry> + <glossterm>User Mapping</glossterm> + <glossdef> + <para> + The translation of <glossterm>user</glossterm> credentials in the local database to credentials in a remote data system defined by a <glossterm>Foreign Data Wrapper</glossterm>. + </para> + </glossdef> + </glossentry> + + <glossentry> + <glossterm>View</glossterm> + <glossdef> + <para> + A <glossterm>relation</glossterm> that is defined by a <command>SELECT</command> statement, but has no storage of its own. Any time a query references a View, the definition of the View is substituted into the query as if the user had typed that subquery instead of the name of the View. + </para> + </glossdef> + </glossentry> + + <glossentry> + <glossterm>Window Function</glossterm> + <glossdef> + <para> + A type of <glossterm>function</glossterm> similar to an <glossterm>aggregate</glossterm> in that it can derive its value from a set of <glossterm>row</glossterm>s in a result set, but still retaining the original source data. + </para> + </glossdef> + </glossentry> + </glosslist> +</appendix> diff --git a/doc/src/sgml/postgres.sgml b/doc/src/sgml/postgres.sgml index e59cba7997..2183e33bea 100644 --- a/doc/src/sgml/postgres.sgml +++ b/doc/src/sgml/postgres.sgml @@ -278,6 +278,7 @@ &docguide; &limits; &acronyms; + &glossary; </part> -- 2.17.1
