From 91a890bd7fef1cd8bfe3c8832eea114290f16b02 Mon Sep 17 00:00:00 2001 From: Alvaro Herrera Date: Fri, 19 Jun 2020 12:55:43 -0400 Subject: [PATCH] Adjust some glossary terms MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Mostly in response to Jürgen Purtz critique of previous definitions, though I added many other changes. Author: Álvaro Herrera Reviewed-by: Jürgen Purtz Reviewed-by: Justin Pryzby Reviewed-by: Erik Rijkers Discussion: https://postgr.es/m/c1e06008-2132-30f4-9b38-877e8683d418@purtz.de --- doc/src/sgml/glossary.sgml | 411 ++++++++++++++++++++++--------------- 1 file changed, 246 insertions(+), 165 deletions(-) diff --git a/doc/src/sgml/glossary.sgml b/doc/src/sgml/glossary.sgml index 25b03f3b37..c7c931c17e 100644 --- a/doc/src/sgml/glossary.sgml +++ b/doc/src/sgml/glossary.sgml @@ -23,7 +23,7 @@ - Aggregate function + Aggregate function (routine) A function that @@ -39,6 +39,11 @@ + + Analytic function + + + Analyze (operation) @@ -54,14 +59,13 @@ (Don't confuse this term with the ANALYZE option to the command.) + + For more information, see + . + - - Analytic function - - - Atomic @@ -98,8 +102,7 @@ An element with a certain name and data type found within a - tuple or - table. + tuple. @@ -389,36 +392,12 @@ - - Data directory - - - The base directory on the filesystem of a - server that contains all - data files and subdirectories associated with an - instance (with the - exception of tablespaces). - The environment variable PGDATA is commonly used to - refer to the - data directory. - - - An instance's storage - space comprises the data directory plus any additional tablespaces. - - - For more information, see - . - - - - Database A named collection of - SQL objects. + local SQL objects. For more information, see @@ -427,11 +406,53 @@ + + Database cluster + + + A collection of databases and global SQL objects, + and their common static and dynamic metadata. + Sometimes referred to as a + cluster. + + + In PostgreSQL, the term + cluster is also sometimes used to refer to an instance. + (Don't confuse this term with the SQL command CLUSTER.) + + + + Database server + + Data directory + + + The base directory on the filesystem of a + server that contains all + data files and subdirectories associated with a + database cluster + (with the exception of + tablespaces, + and optionally WAL). + The environment variable PGDATA is commonly used to + refer to the data directory. + + + A cluster's storage + space comprises the data directory plus any additional tablespaces. + + + For more information, see + . + + + + Data page @@ -578,7 +599,7 @@ - Foreign table + Foreign table (relation) A relation which appears to have @@ -631,12 +652,20 @@ - Function + Function (routine) - Any defined transformation of data. Many functions are already defined - within PostgreSQL itself, but user-defined - ones can also be added. + A type of routine that receives zero or more arguments, returns zero or more + output values, and is constrained to run within one transaction. + Functions are invoked as part of a query, for example via + SELECT. + Certain functions can return + sets; those are + called set-returning functions. + + + Functions can also be used for + triggers to invoke. For more information, see @@ -689,13 +718,12 @@ - Index + Index (relation) A relation that contains data derived from a table - (or relation types - such as a materialized view). + or materialized view. Its internal structure supports fast retrieval of and access to the original data. @@ -724,14 +752,12 @@ Instance - A set of databases and accompanying global SQL objects that are stored in - the same data directory - in a single server. - If running, one + A group of backend and auxiliary processes that communicate using + a common shared memory area. One postmaster process - manages a group of backend and auxiliary processes that communicate - using a common shared memory - area. Many instances can run on the same + manages the instance; one instance manages exactly one + database cluster + with all its databases. Many instances can run on the same server as long as their TCP ports do not conflict. @@ -739,14 +765,10 @@ The instance handles all key features of a DBMS: read and write access to files and shared memory, assurance of the ACID properties, - connections to client processes, + connections to + client processes, privilege verification, crash recovery, replication, etc. - - In PostgreSQL, the term - cluster is also sometimes used to refer to an instance. - (Don't confuse this term with the SQL command CLUSTER.) - @@ -769,8 +791,10 @@ Join - An SQL keyword used in SELECT statements for - combining data from multiple relations. + An operation and SQL keyword used in + queries + for combining data from multiple + relations. @@ -781,10 +805,10 @@ A means of identifying a row within a table or - relation by + other relation by values contained within one or more attributes - in that table. + in that relation. @@ -813,15 +837,6 @@ - - Log record - - - Archaic term for a WAL record. - - - - Logged @@ -855,6 +870,15 @@ + + Log record + + + Archaic term for a WAL record. + + + + Master (server) @@ -883,12 +907,13 @@ - Materialized view + Materialized view (relation) A relation that is - defined in the same way that a view - is, but stores data in the same way that a + defined by a SELECT statement + (just like a view), + but stores data in the same way that a table does. It cannot be modified via INSERT, UPDATE, or DELETE operations. @@ -949,6 +974,8 @@ One of several disjoint (not overlapping) subsets of a larger set. + + In reference to a partitioned table: @@ -961,16 +988,18 @@ - In reference to a window function: + In reference to a window function + in a query, a partition is a user-defined criterion that identifies which neighboring - rows can be considered by the - function. + rows + of the query's result set + can be considered by the function. - Partitioned table + Partitioned table (relation) A relation that is @@ -997,20 +1026,6 @@ - - Primary (server) - - - When two or more databases - are linked via replication, - the server - that is considered the authoritative source of information is called - the primary, - also known as a master. - - - - Primary key @@ -1031,19 +1046,29 @@ - - Procedure + + Primary (server) - A defined set of instructions for manipulating data within a - database. - A procedure can - be written in a variety of programming languages. They are - similar to functions, - but are different in that they must be invoked via the CALL - command rather than the SELECT or PERFORM - commands, and they are allowed to make transactional statements such + When two or more databases + are linked via replication, + the server + that is considered the authoritative source of information is called + the primary, + also known as a master. + + + + + + Procedure (routine) + + + A type of routine. + Their distinctive qualities are that they do not return values, + and that they are allowed to make transactional statements such as COMMIT and ROLLBACK. + They are invoked via the CALL command. For more information, see @@ -1115,6 +1140,11 @@ indexes are all relations. + More generically, a relation is a set of tuples; for example, + the result of a query is also a relation. + + + In PostgreSQL, Class is an archaic synonym for relation. @@ -1155,16 +1185,23 @@ Result set - A data structure transmitted from a - backend process to - a client upon the - completion of an SQL - command, usually a SELECT but it can be an + A relation transmitted + from a backend process + to a client upon the + completion of an SQL command, usually a + SELECT but it can be an INSERT, UPDATE, or DELETE command if the RETURNING - clause is specified. The data structure consists of zero or more - rows with the same ordered set of - attributes. + clause is specified. + + + The fact that a result set is a relation means that a query can be used + in the definition of another query, becoming a + subquery. + + + + @@ -1216,6 +1253,27 @@ + + Routine + + + A defined set of instructions stored in the database system + that can be invoked for execution. + A routine can be written in a variety of programming + languages. Routines can be + functions + (including set-returning functions and + trigger functions), + aggregate functions, + and procedures. + + + Many routines are already defined within PostgreSQL + itself, but user-defined ones can also be added. + + + + Row @@ -1248,16 +1306,7 @@ Each SQL object must reside in exactly one schema. - The names of SQL objects of the same type in the same schema are enforced - to be unique. - There is no restriction on reusing a name in multiple schemas. - - - All system-defined SQL objects reside in schema pg_catalog, - and commonly many user-defined SQL objects reside in the default schema - public, - but it is common and recommended that other schemas are created to hold - application-specific SQL objects. + All system-defined SQL objects reside in schema pg_catalog. @@ -1299,6 +1348,19 @@ + + Sequence (relation) + + + A type of relation that is used to generate values. + Typically the generated values are sequential non-repeating numbers. + They are commonly used to generate surrogate + primary key + values. + + + +