Adjust some glossary terms
authorAlvaro Herrera
Fri, 19 Jun 2020 16:55:43 +0000 (12:55 -0400)
committerAlvaro Herrera
Fri, 19 Jun 2020 16:55:43 +0000 (12:55 -0400)
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

index 25b03f3b370f8280ae407e17d99baf57f4725a15..c7c931c17e1b46d0b99cda9178b7a683d63f810f 100644 (file)
@@ -23,7 +23,7 @@
   
 
   
-   Aggregate function
+   Aggregate function (routine)
    
     
      A function that
    
   
 
+  
+   Analytic function
+   
+  
+
   
    Analyze (operation)
    
      (Don't confuse this term with the ANALYZE option
      to the  command.)
     
+    
+     For more information, see
+     .
+    
    
   
 
-  
-   Analytic function
-   
-  
-
   
    Atomic
    
    
     
      An element with a certain name and data type found within a
-     tuple or
-     table.
+     tuple.
     
    
   
    
   
 
-  -directory">
-   Data directory
+  base">
+   Database
    
     
-     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.
+     A named collection of
+     local SQL objects.
     
     
      For more information, see
-     storage-file-layout"/>.
+     manage-ag-overview"/>.
     
    
   
 
-  atabase">
-   Database
+  b-cluster">
+   Database cluster
    
     
-     A named collection of
-     SQL objects.
+     A collection of databases and global SQL objects,
+     and their common static and dynamic metadata.
+     Sometimes referred to as a
+     cluster.
     
     
-     For more information, see
-     .
+     In PostgreSQL, the term
+     cluster is also sometimes used to refer to an instance.
+     (Don't confuse this term with the SQL command CLUSTER.)
     
    
   
    
   
 
+  
+   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
    
   
 
   
-   Foreign table
+   Foreign table (relation)
    
     
      A relation which appears to have
   
 
   
-   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
   
 
   
-   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.
     
    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.
     
      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.)
-    
    
   
 
    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.
     
    
   
     
      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.
     
    
   
    
   
 
-  
-   Log record
-    
-     
-      Archaic term for a WAL record.
-     
-    
-  
-
   
    Logged
    
    
   
 
+  
+   Log record
+    
+     
+      Archaic term for a WAL record.
+     
+    
+  
+
   
    Master (server)
    
   
 
   
-   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 INSERTUPDATE, or
      DELETE operations.
     
      One of several disjoint (not overlapping) subsets of a larger set.
     
+   
+   
     
      In reference to a
      partitioned table:
    
    
     
-     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
    
   
 
-  
-   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
    
    
   
 
+  
+   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.
+    
+   
+  
+
   
-   Procedure
+   Procedure (routine)
    
     
-     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
+     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
      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.
     
    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 client upon the
+     completion of an SQL command, usually a
+     SELECT but it can be an
      INSERTUPDATE, 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.
+    
+   
+   
+    
     
    
   
    
   
 
+  
+   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
    
      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.
     
    
    
    
   
 
+  
+   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.
+    
+   
+  
+