Received: from malur.postgresql.org ([217.196.149.56]) by arkaria.postgresql.org with esmtps (TLS1.3:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1jm4Jc-0002qT-4q for pgsql-docs@arkaria.postgresql.org; Thu, 18 Jun 2020 23:51:28 +0000 Received: from localhost ([127.0.0.1] helo=malur.postgresql.org) by malur.postgresql.org with esmtp (Exim 4.92) (envelope-from ) id 1jm4Ja-0001M4-Tb for pgsql-docs@arkaria.postgresql.org; Thu, 18 Jun 2020 23:51:26 +0000 Received: from makus.postgresql.org ([2001:4800:3e1:1::229]) by malur.postgresql.org with esmtps (TLS1.3:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1jm4Ja-0001Lw-9k for pgsql-docs@lists.postgresql.org; Thu, 18 Jun 2020 23:51:26 +0000 Received: from mail-qt1-x844.google.com ([2607:f8b0:4864:20::844]) by makus.postgresql.org with esmtps (TLS1.3:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.92) (envelope-from ) id 1jm4JS-0004oR-Vy for pgsql-docs@lists.postgresql.org; Thu, 18 Jun 2020 23:51:25 +0000 Received: by mail-qt1-x844.google.com with SMTP id y1so5914659qtv.12 for ; Thu, 18 Jun 2020 16:51:18 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=2ndquadrant-com.20150623.gappssmtp.com; s=20150623; h=date:from:to:cc:subject:message-id:mime-version:content-disposition :content-transfer-encoding:in-reply-to:user-agent; bh=ss2CXKobv9Oy0XCPzbTAL9ajdMxbzsPtup4P8Tfpbc8=; b=SE+A173/bW+W5R5DPhHkL6VJrxp+AnvUjB3+F8L3M34Xck518UzL0wvEIkg84rGXHO SDf9TN9ayJxXRV5L0BFDFWUNNGei96807+VSqZ1CPlyyud3Sx06fGGbtP8bQ9O1ssNqA 4H6e+Ey9NEtCdS2wnvlBrPu7eW5T8cc1q9veHOI67BtmsrE2tt5xuS6oOvShmHkH9+NZ HzPZeF1EQs+hAMY+6nMnRfXsJvD8BxwyOPE38BxCjzjyAk7A8OokhW9c/p2ipyGAHMTV CGidbWhUF4EgtCNZ7JKlH9THPDeCNUV6cAzJ/7kMnswzX/l/qI9abHxT1m5BE73HhNlW /uMg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:date:from:to:cc:subject:message-id:mime-version :content-disposition:content-transfer-encoding:in-reply-to :user-agent; bh=ss2CXKobv9Oy0XCPzbTAL9ajdMxbzsPtup4P8Tfpbc8=; b=LstxYflM/WpP590KliFLzdA+v356xlxIY6PjWMz1AMrjPKtCBoDgcKxjBtbt3T8tR4 r27Q97NU4NA4/RCnv92osfk6BaltWQJNpwUSNqaK8yp0z2gBXBJ/1nqRUYqR5bD9K8lp EiRS2HTBfR0EqywmDf+X76jp6elje4aWE8Fz8TbuKA2oaaskZvAuDMrxebP4Yv81xVVo ZbMvmL/M20eoGG0dEccq0X3Hjxh4RC5nLF+E4IYldjG3hK35yvYwGGD3erZxDpUKOu8S 6uhWKjRzW+M/gy9zNFk0JvYj+gh/T7DUZmjAOT0t544cx9hu0nZHUEWEV7l1eISbXkue jZsQ== X-Gm-Message-State: AOAM530XM8u3TxTp7opyd0McCw3vhLBdp7BO9CsTuep6lC/5PPaYG2K0 0OLuIMqzkKI1eTYrg7dsmjQPlQ== X-Google-Smtp-Source: ABdhPJy5yqGgp0BPR2jj0RKaoKEaAMtAoCX1IB2yb0SzF+cdM0tscRBVDQKIzTao6Ky+gqMDFb7huw== X-Received: by 2002:ac8:758c:: with SMTP id s12mr844413qtq.162.1592524278025; Thu, 18 Jun 2020 16:51:18 -0700 (PDT) Received: from perhan.alvh.no-ip.org ([190.95.18.252]) by smtp.gmail.com with ESMTPSA id g132sm4288222qkb.78.2020.06.18.16.51.15 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 18 Jun 2020 16:51:16 -0700 (PDT) Received: by perhan.alvh.no-ip.org (Postfix, from userid 1000) id A18D92A3ADD; Thu, 18 Jun 2020 19:51:13 -0400 (-04) Date: Thu, 18 Jun 2020 19:51:13 -0400 From: Alvaro Herrera To: Justin Pryzby , =?iso-8859-1?Q?J=FCrgen?= Purtz Cc: Erik Rijkers , Laurenz Albe , Fabien COELHO , Peter Eisentraut , Corey Huinker , Roger Harkavy , pgsql-hackers@postgresql.org, Michael Paquier , Pg Docs Subject: Re: Add A Glossary Message-ID: <20200618235113.GA1137@alvherre.pgsql> MIME-Version: 1.0 Content-Type: multipart/mixed; boundary="n8g4imXOkfNTN/H1" Content-Disposition: inline Content-Transfer-Encoding: 8bit In-Reply-To: <292d6f42-e31c-bc73-6cfb-9083bc2c07fc@purtz.de> <20200617003349.GN20404@telsasoft.com> User-Agent: Mutt/1.10.1 (2018-07-13) List-Id: List-Help: List-Subscribe: List-Post: List-Owner: List-Archive: Precedence: bulk --n8g4imXOkfNTN/H1 Content-Type: text/plain; charset=iso-8859-1 Content-Disposition: inline Content-Transfer-Encoding: 8bit On 2020-Jun-16, Justin Pryzby wrote: > On Tue, Jun 16, 2020 at 08:09:26PM -0400, Alvaro Herrera wrote: Thanks for the review. I merged all your suggestions. This one: > > Most local objects belong to a specific > > + schema in their > > + containing database, such as > > + all types of relations, > > + all types of functions, > > Maybe say: >Relations< (all types), and >Functions< (all types) led me down not one but two rabbit holes; first I realized that "functions" is an insufficient term since procedures should also be included but weren't, so I had to add the more generic term "routine" and then modify the definitions of all routine types to mix in well. I think overall the quality of these definitions is improved as a result. I also felt the need to revise the definition of "relations", so I did that too; this made me change the definition of resultset too. On 2020-Jun-17, Jürgen Purtz wrote: > +1, with two formal changes: > > -  Rearrangement of term "Data page" to meet alphabetical order. To forestall these ordering issues (look, another rabbit hole), I grepped the file for all glossterms and sorted that under en_US rules, then reordered the terms to match that. Turns out there were several other ordering mistakes. git grep '' | sed -e 's/<[^>]*>\([^<]*\)<[^>]*>/\1/' > orig LC_COLLATE=en_US.UTF-8 sort orig > sorted (Eliminating the tags is important, otherwise the sort uses the tags themselves to disambiguate) > One last question: The definition of "Data directory" reads "... A cluster's > storage space comprises the data directory plus ..." and 'cluster' links to > '"glossary-instance". Shouldn't it link to "glossary-db-cluster"? Yes, an oversight, thanks. I also added TPS, because I had already written it. -- Álvaro Herrera https://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services --n8g4imXOkfNTN/H1 Content-Type: text/x-diff; charset=us-ascii Content-Disposition: attachment; filename="glossary-2.patch" diff --git a/doc/src/sgml/glossary.sgml b/doc/src/sgml/glossary.sgml index 25b03f3b37..5274feabba 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) @@ -57,11 +62,6 @@ - - Analytic function - - - Atomic @@ -389,40 +389,33 @@ - - Data directory + + 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 - . + . - - Database + + 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.) @@ -432,6 +425,31 @@ + + 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 +596,7 @@ - Foreign table + Foreign table (relation) A relation which appears to have @@ -631,12 +649,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 +715,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 +749,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 +762,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 +788,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 +802,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 +834,6 @@ - - Log record - - - Archaic term for a WAL record. - - - - Logged @@ -855,6 +867,15 @@ + + Log record + + + Archaic term for a WAL record. + + + + Master (server) @@ -883,12 +904,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 +971,8 @@ One of several disjoint (not overlapping) subsets of a larger set. + + In reference to a partitioned table: @@ -961,16 +985,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 +1023,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 +1043,29 @@ + + 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 @@ -1115,6 +1137,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 +1182,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 +1250,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), + aggregates functions, + and procedures. + + + Many routines are already defined within PostgreSQL + itself, but user-defined ones can also be added. + + + + Row @@ -1248,16 +1303,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 +1345,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. + + + +