v20251230-0002-Fix-some-more-references-and-edit-document.patch

From 13f4ca52167e220d2feadd11e010d1b79b3456a5 Mon Sep 17 00:00:00 2001
From: Ashutosh Bapat <ashutosh.bapat.oss@gmail.com>
Date: Thu, 18 Dec 2025 14:13:02 +0530
Subject: [PATCH v20251230 2/4] Fix some more : references and edit
 documentation

Make property graph's role, as a method of exposing underlying
relational data as a graph logically, more explicit.
---
 doc/src/sgml/ddl.sgml | 58 ++++++++++++++++++++++++-------------------
 1 file changed, 32 insertions(+), 26 deletions(-)

diff --git a/doc/src/sgml/ddl.sgml b/doc/src/sgml/ddl.sgml
index e55d46713c0..d9033164427 100644
--- a/doc/src/sgml/ddl.sgml
+++ b/doc/src/sgml/ddl.sgml
@@ -5701,21 +5701,21 @@ EXPLAIN SELECT count(*) FROM measurement WHERE logdate &gt;= DATE '2008-01-01';
   </indexterm>
 
   <para>
-   A property graph is a way to represent database contents, instead of using
-   relational structures such as tables.  A property graph can then be queried
-   using graph pattern matching syntax, instead of join queries typical of
-   relational databases.  PostgreSQL implements SQL/PGQ<footnote><para>Here,
-   PGQ stands for <quote>property graph query</quote>.  In the jargon of graph
-   databases, <quote>property graph</quote> is normally abbreviated as PG,
-   which is clearly confusing for practioners of PostgreSQL, also usually
-   abbreviated as PG.</para></footnote>, which is part of the SQL standard,
-   where a property graph is defined as a kind of read-only view over
-   relational tables.  So the actual data is still in tables or table-like
-   objects, but is exposed as a graph for graph querying operations.  (This is
-   in contrast to native graph databases, where the data is stored directly in
-   a graph structure.)  Underneath, both relational queries and graph queries
-   use the same query planning and execution infrastucture, and in fact
-   relational and graph queries can be combined and mixed in single queries.
+   A property graph is a way to represent database contents, which are in
+   relational form, as a graph.  A property graph can then be queried using
+   graph pattern matching syntax, instead of join queries typical of relational
+   databases.  PostgreSQL implements SQL/PGQ<footnote><para>Here, PGQ stands for
+   <quote>property graph query</quote>.  In the jargon of graph databases,
+   <quote>property graph</quote> is normally abbreviated as PG, which is clearly
+   confusing for practioners of PostgreSQL, also usually abbreviated as
+   PG.</para></footnote>, which is part of the SQL standard, where a property
+   graph is defined as a kind of read-only view over relational tables.  So the
+   actual data is still in tables or table-like objects, but is exposed as a
+   graph for graph querying operations.  (This is in contrast to native graph
+   databases, where the data is stored directly in a graph structure.)
+   Underneath, both relational queries and graph queries use the same query
+   planning and execution infrastucture, and in fact relational and graph
+   queries can be combined and mixed in single queries.
   </para>
 
   <para>
@@ -5836,12 +5836,12 @@ CREATE PROPERTY GRAPH myshop
   </para>
 
   <para>
-   One use of labels is to expose a table through a different name in the
-   graph.  For example, in graphs, vertices typically have singular nouns as
-   labels and edges typically have verbs as labels, such as <quote>is</quote>,
+   One use of labels is to expose a table through a different name in the graph.
+   For example, in graphs, vertices typically have singular nouns as labels and
+   edges typically have verbs or phrases derived from verbs as labels, such as
    <quote>has</quote>, <quote>contains</quote>, or something specific like
-   <quote>approves</quote>.  We can introduce such labels into our example
-   like this:
+   <quote>approved_by</quote>. We can introduce such labels into our example like
+   this:
 <programlisting>
 CREATE PROPERTY GRAPH myshop
     VERTEX TABLES (
@@ -5851,7 +5851,7 @@ CREATE PROPERTY GRAPH myshop
     )
     EDGE TABLES (
         order_items SOURCE orders DESTINATION products LABEL contains,
-        customer_orders SOURCE customers DESTINATION orders LABEL has
+        customer_orders SOURCE customers DESTINATION orders LABEL has_placed
     );
 </programlisting>
   </para>
@@ -5859,11 +5859,9 @@ CREATE PROPERTY GRAPH myshop
   <para>
    With this definition, we can write a query like this:
 <programlisting>
-SELECT customer_name FROM GRAPH_TABLE (myshop MATCH (c:customer)-[:has]->(o:"order" WHERE o.ordered_when = current_date) COLUMNS (c.name AS customer_name));
+SELECT customer_name FROM GRAPH_TABLE (myshop MATCH (c IS customer)-[ IS has_placed]->(o IS "order" WHERE o.ordered_when = current_date) COLUMNS (c.name AS customer_name));
 </programlisting>
-   With the new labels and using the colon instead of <literal>IS</literal>,
-   which are equivalent, the <literal>MATCH</literal> clause is now more
-   compact and intuitive.
+   With the new labels the <literal>MATCH</literal> clause is now more intuitive.
   </para>
   <para>
    Please notice that label <literal>order</literal> is quoted. If we run above
@@ -5899,7 +5897,7 @@ CREATE PROPERTY GRAPH myshop
    <literal>employees</literal> table to something, but it is allowed like
    this.)  Then we can run a query like this (incomplete):
 <programlisting>
-SELECT ... FROM GRAPH_TABLE (myshop MATCH (:person WHERE name = '...')-[]->... COLUMNS (...));
+SELECT ... FROM GRAPH_TABLE (myshop MATCH (IS person WHERE name = '...')-[]->... COLUMNS (...));
 </programlisting>
    This would automatically consider both the <literal>customers</literal> and
    the <literal>employees</literal> tables when looking for an edge with the
@@ -5913,6 +5911,14 @@ SELECT ... FROM GRAPH_TABLE (myshop MATCH (:person WHERE name = '...')-[]->... C
    to achieve this.
   </para>
 
+  <para>
+   Using more than one label associated with an element table and each label
+   exposing a different set of properties, the same relational data, and the
+   graph structure contained therein, can be exposed through multiple
+   co-existing logical views, which can be queried using graph pattern matching
+   constructs.
+  </para>
+
   <para>
    For more details on the syntax for creating property graphs, see <link
    linkend="sql-create-property-graph"><command>CREATE PROPERTY
-- 
2.34.1