From 86c1180718e0a84d7ac757e3b8164744f95a6526 Mon Sep 17 00:00:00 2001 From: Peter Eisentraut Date: Mon, 11 Mar 2019 09:48:00 +0100 Subject: [PATCH] doc: Add some images --- doc/src/sgml/Makefile | 25 +- doc/src/sgml/gin.dot | 93 +++++++ doc/src/sgml/gin.sgml | 12 +- doc/src/sgml/gin.svg | 320 ++++++++++++++++++++++++ doc/src/sgml/pagelayout.svg | 40 +++ doc/src/sgml/pagelayout.txt | 11 + doc/src/sgml/storage.sgml | 13 + doc/src/sgml/stylesheet-html-common.xsl | 1 + 8 files changed, 510 insertions(+), 5 deletions(-) create mode 100644 doc/src/sgml/gin.dot create mode 100644 doc/src/sgml/gin.svg create mode 100644 doc/src/sgml/pagelayout.svg create mode 100644 doc/src/sgml/pagelayout.txt diff --git a/doc/src/sgml/Makefile b/doc/src/sgml/Makefile index 2420c55681..4ca6cc0259 100644 --- a/doc/src/sgml/Makefile +++ b/doc/src/sgml/Makefile @@ -57,6 +57,8 @@ GENERATED_SGML = version.sgml \ ALLSGML := $(wildcard $(srcdir)/*.sgml $(srcdir)/ref/*.sgml) $(GENERATED_SGML) +ALL_IMAGES = gin.svg pagelayout.svg + ## ## Man pages @@ -125,9 +127,10 @@ endif html: html-stamp -html-stamp: stylesheet.xsl postgres.sgml $(ALLSGML) +html-stamp: stylesheet.xsl postgres.sgml $(ALLSGML) $(ALL_IMAGES) $(XMLLINT) $(XMLINCLUDE) --noout --valid $(word 2,$^) $(XSLTPROC) $(XMLINCLUDE) $(XSLTPROCFLAGS) $(XSLTPROC_HTML_FLAGS) $(wordlist 1,2,$^) + cp $(ALL_IMAGES) html/ cp $(srcdir)/stylesheet.css html/ touch $@ @@ -136,7 +139,7 @@ htmlhelp: stylesheet-hh.xsl postgres.sgml $(ALLSGML) $(XSLTPROC) $(XMLINCLUDE) $(XSLTPROCFLAGS) $(wordlist 1,2,$^) # single-page HTML -postgres.html: stylesheet-html-nochunk.xsl postgres.sgml $(ALLSGML) +postgres.html: stylesheet-html-nochunk.xsl postgres.sgml $(ALLSGML) $(ALL_IMAGES) $(XMLLINT) $(XMLINCLUDE) --noout --valid $(word 2,$^) $(XSLTPROC) $(XMLINCLUDE) $(XSLTPROCFLAGS) $(XSLTPROC_HTML_FLAGS) -o $@ $(wordlist 1,2,$^) @@ -160,7 +163,7 @@ postgres.pdf: $(XMLLINT) $(XMLINCLUDE) --noout --valid $(word 2,$^) $(XSLTPROC) $(XMLINCLUDE) $(XSLTPROCFLAGS) --stringparam paper.type USletter -o $@ $(wordlist 1,2,$^) -%.pdf: %.fo +%.pdf: %.fo $(ALL_IMAGES) $(FOP) -fo $< -pdf $@ @@ -169,7 +172,7 @@ postgres.pdf: ## epub: postgres.epub -postgres.epub: postgres.sgml $(ALLSGML) +postgres.epub: postgres.sgml $(ALLSGML) $(ALL_IMAGES) $(XMLLINT) --noout --valid $< $(DBTOEPUB) -o $@ $< @@ -193,6 +196,20 @@ MAKEINFO = makeinfo $(MAKEINFO) --enable-encoding --no-split --no-validate $< -o $@ +## +## Images +## + +DITAA = ditaa +DOT = dot + +%.svg: %.dot + $(DOT) -T svg -o $@ $< + +%.svg: %.txt + $(DITAA) -E -S --svg $< $@ + + ## ## Check ## diff --git a/doc/src/sgml/gin.dot b/doc/src/sgml/gin.dot new file mode 100644 index 0000000000..097e91029a --- /dev/null +++ b/doc/src/sgml/gin.dot @@ -0,0 +1,93 @@ +digraph "gin" { + layout=dot; + node [label="", shape=box, style=filled, fillcolor=gray, width=1.4]; + + m1 [label="meta page"]; + + subgraph cluster01 { + label="entry tree"; + subgraph egroup1 { + rank=same; + e1; + } + subgraph egroup2 { + rank=same; + e2 -> e3 -> e4; + } + subgraph egroup3 { + rank=same; + e5 -> e6 -> e7 -> e8 -> e9; + } + e1 -> e4; + e1 -> e3; + e1 -> e2; + e2 -> e5; + e2 -> e6; + e3 -> e7; + e4 -> e8; + e4 -> e9; + + e6 [fillcolor=green, label="posting list"]; + e8 [fillcolor=green, label="posting list"]; + e9 [fillcolor=green, label="posting list"]; + } + + subgraph cluster02 { + label="posting tree"; + subgraph pgroup1 { + rank=same; + p1; + } + subgraph pgroup2 { + rank=same; + p2 -> p3; + } + p1 -> p2; + p1 -> p3; + + p2 [fillcolor=green, label="heap ptr"]; + p3 [fillcolor=green, label="heap ptr"]; + } + + subgraph cluster03 { + label="posting tree"; + subgraph pgroup3 { + rank=same; + p4; + } + + p4 [fillcolor=green, label="heap ptr"]; + } + + subgraph cluster04 { + label="posting tree"; + subgraph pgroup4 { + rank=same; + p5; + } + subgraph pgroup5 { + rank=same; + p6 -> p7; + } + p5 -> p6; + p5 -> p7; + + p6 [fillcolor=green, label="heap ptr"]; + p7 [fillcolor=green, label="heap ptr"]; + } + + subgraph cluster05 { + label="pending list"; + node [style=filled, fillcolor=red]; + n1 -> n2 -> n3 -> n4; + } + + m1 -> e1; + e5 -> p1; + e7 -> p4; + e7 -> p5; + m1 -> n1; + + e5 [style=filled, fillcolor=green4]; + e7 [style=filled, fillcolor=green4]; +} diff --git a/doc/src/sgml/gin.sgml b/doc/src/sgml/gin.sgml index cc7cd1ed2c..8913d7d99d 100644 --- a/doc/src/sgml/gin.sgml +++ b/doc/src/sgml/gin.sgml @@ -436,7 +436,8 @@ Implementation page contains either a pointer to a B-tree of heap pointers (a posting tree), or a simple list of heap pointers (a posting list) when the list is small enough to fit into a single index tuple along - with the key value. + with the key value. illustrates + these components of a GIN index. @@ -453,6 +454,15 @@ Implementation key values for different columns can be of different types. +
+ GIN Internals + + + + + +
+ GIN Fast Update Technique diff --git a/doc/src/sgml/gin.svg b/doc/src/sgml/gin.svg new file mode 100644 index 0000000000..eacb5c8c16 --- /dev/null +++ b/doc/src/sgml/gin.svg @@ -0,0 +1,320 @@ + + + + + + +gin + + +cluster01 + +entry tree + + +cluster02 + +posting tree + + +cluster03 + +posting tree + + +cluster04 + +posting tree + + +cluster05 + +pending list + + + +m1 + +meta page + + + +e1 + + + + +m1->e1 + + + + + +n1 + + + + +m1->n1 + + + + + +e2 + + + + +e1->e2 + + + + + +e3 + + + + +e1->e3 + + + + + +e4 + + + + +e1->e4 + + + + + +e2->e3 + + + + + +e5 + + + + +e2->e5 + + + + + +e6 + +posting list + + + +e2->e6 + + + + + +e3->e4 + + + + + +e7 + + + + +e3->e7 + + + + + +e8 + +posting list + + + +e4->e8 + + + + + +e9 + +posting list + + + +e4->e9 + + + + + +e5->e6 + + + + + +p1 + + + + +e5->p1 + + + + + +e6->e7 + + + + + +e7->e8 + + + + + +p4 + +heap ptr + + + +e7->p4 + + + + + +p5 + + + + +e7->p5 + + + + + +e8->e9 + + + + + +p2 + +heap ptr + + + +p1->p2 + + + + + +p3 + +heap ptr + + + +p1->p3 + + + + + +p2->p3 + + + + + +p6 + +heap ptr + + + +p5->p6 + + + + + +p7 + +heap ptr + + + +p5->p7 + + + + + +p6->p7 + + + + + +n2 + + + + +n1->n2 + + + + + +n3 + + + + +n2->n3 + + + + + +n4 + + + + +n3->n4 + + + + + diff --git a/doc/src/sgml/pagelayout.svg b/doc/src/sgml/pagelayout.svg new file mode 100644 index 0000000000..6b819a553e --- /dev/null +++ b/doc/src/sgml/pagelayout.svg @@ -0,0 +1,40 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + PageHeaderData + Item + ItemId + ItemId + Item + Special + + \ No newline at end of file diff --git a/doc/src/sgml/pagelayout.txt b/doc/src/sgml/pagelayout.txt new file mode 100644 index 0000000000..40bee5d169 --- /dev/null +++ b/doc/src/sgml/pagelayout.txt @@ -0,0 +1,11 @@ ++----------------+--------+--------+--------------------+ +| PageHeaderData | ItemId | ItemId +=--------> | ++----------------+---+----+---+----+ | +| | | | +| | +-----+ | +| +--+------+ | +| | | | +| v v | +| +----------+-----------------+---------+ +| <----=+ Item | Item | Special | ++----------------+----------+-----------------+---------+ diff --git a/doc/src/sgml/storage.sgml b/doc/src/sgml/storage.sgml index cbdad0c3fb..1ed3d1cab6 100644 --- a/doc/src/sgml/storage.sgml +++ b/doc/src/sgml/storage.sgml @@ -917,6 +917,19 @@ PageHeaderData Layout + + illustrates how these parts are layed out in a page. + + +
+ Page Layout + + + + + +
+ Table Row Layout diff --git a/doc/src/sgml/stylesheet-html-common.xsl b/doc/src/sgml/stylesheet-html-common.xsl index 8942d99472..b105005235 100644 --- a/doc/src/sgml/stylesheet-html-common.xsl +++ b/doc/src/sgml/stylesheet-html-common.xsl @@ -14,6 +14,7 @@ + pgsql-docs@lists.postgresql.org 2 -- 2.21.0