Movatterモバイル変換

[0]ホーム
URL:

Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

 Sign up
Appearance settings

Commita32c092

Browse files
committed
Documentation improvements around domain types.
I was a bit surprised to find that domains were almost completelyunmentioned in the main SGML documentation, outside of the referencepages for CREATE/ALTER/DROP DOMAIN. In particular, noplace was itmentioned that we don't support domains over composite, making ithard to document the planned fix for that.Hence, add a section about domains to chapter 8 (Data Types).Also, modernize the type system overview in section 37.2; it had neverheard of range types, and insisted on calling arrays base types, whichseems a bit odd from a user's perspective; furthermore it didn't fit wellwith the fact that we now support arrays over types other than base types.It seems appropriate to use the term "container types" to describe all ofarrays, composites, and ranges, so let's do that.Also a few other minor improvements, notably improve an example queryin rowtypes.sgml by using a LATERAL function instead of an ad-hocOFFSET 0 clause.In part this is mop-up for commitc12d570, which missed updating 37.2to reflect the fact that it added arrays of domains. We could possiblyback-patch this without that claim, but I don't feel a strong need to.
1 parent8df4ce1 commita32c092

File tree

4 files changed

+124
-34
lines changed

4 files changed

+124
-34
lines changed

‎doc/src/sgml/datatype.sgml

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4359,6 +4359,60 @@ SET xmloption TO { DOCUMENT | CONTENT };
43594359

43604360
&rangetypes;
43614361

4362+
<sect1 id="domains">
4363+
<title>Domain Types</title>
4364+
4365+
<indexterm zone="domains">
4366+
<primary>domain</primary>
4367+
</indexterm>
4368+
4369+
<indexterm zone="domains">
4370+
<primary>data type</primary>
4371+
<secondary>domain</secondary>
4372+
</indexterm>
4373+
4374+
<para>
4375+
A <firstterm>domain</firstterm> is a user-defined data type that is
4376+
based on another <firstterm>underlying type</firstterm>. Optionally,
4377+
it can have constraints that restrict its valid values to a subset of
4378+
what the underlying type would allow. Otherwise it behaves like the
4379+
underlying type &mdash; for example, any operator or function that
4380+
can be applied to the underlying type will work on the domain type.
4381+
The underlying type can be any built-in or user-defined base type,
4382+
enum type, array or range type, or another domain. (Currently, domains
4383+
over composite types are not implemented.)
4384+
</para>
4385+
4386+
<para>
4387+
For example, we could create a domain over integers that accepts only
4388+
positive integers:
4389+
<programlisting>
4390+
CREATE DOMAIN posint AS integer CHECK (VALUE &gt; 0);
4391+
CREATE TABLE mytable (id posint);
4392+
INSERT INTO mytable VALUES(1); -- works
4393+
INSERT INTO mytable VALUES(-1); -- fails
4394+
</programlisting>
4395+
</para>
4396+
4397+
<para>
4398+
When an operator or function of the underlying type is applied to a
4399+
domain value, the domain is automatically down-cast to the underlying
4400+
type. Thus, for example, the result of <literal>mytable.id - 1</literal>
4401+
is considered to be of type <type>integer</type> not <type>posint</type>.
4402+
We could write <literal>(mytable.id - 1)::posint</literal> to cast the
4403+
result back to <type>posint</type>, causing the domain's constraints
4404+
to be rechecked. In this case, that would result in an error if the
4405+
expression had been applied to an <structfield>id</structfield> value of
4406+
1. Assigning a value of the underlying type to a field or variable of
4407+
the domain type is allowed without writing an explicit cast, but the
4408+
domain's constraints will be checked.
4409+
</para>
4410+
4411+
<para>
4412+
For additional information see <xref linkend="sql-createdomain">.
4413+
</para>
4414+
</sect1>
4415+
43624416
<sect1 id="datatype-oid">
43634417
<title>Object Identifier Types</title>
43644418

‎doc/src/sgml/extend.sgml

Lines changed: 55 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -106,31 +106,60 @@
106106
<secondary>composite</secondary>
107107
</indexterm>
108108

109+
<indexterm zone="extend-type-system">
110+
<primary>container type</primary>
111+
</indexterm>
112+
113+
<indexterm zone="extend-type-system">
114+
<primary>data type</primary>
115+
<secondary>container</secondary>
116+
</indexterm>
117+
109118
<para>
110-
<productname>PostgreSQL</productname> data typesare divided into base
111-
types,composite types, domains, and pseudo-types.
119+
<productname>PostgreSQL</productname> data typescan be divided into base
120+
types,container types, domains, and pseudo-types.
112121
</para>
113122

114123
<sect2>
115124
<title>Base Types</title>
116125

117126
<para>
118-
Base types are those, like <type>int4</type>, that are
127+
Base types are those, like <type>integer</type>, that are
119128
implemented below the level of the <acronym>SQL</acronym> language
120129
(typically in a low-level language such as C). They generally
121130
correspond to what are often known as abstract data types.
122131
<productname>PostgreSQL</productname> can only operate on such
123132
types through functions provided by the user and only understands
124133
the behavior of such types to the extent that the user describes
125-
them. Base types are further subdivided into scalar and array
126-
types. For each scalar type, a corresponding array type is
127-
automatically created that can hold variable-size arrays of that
128-
scalar type.
134+
them.
135+
The built-in base types are described in <xref linkend="datatype">.
136+
</para>
137+
138+
<para>
139+
Enumerated (enum) types can be considered as a subcategory of base
140+
types. The main difference is that they can be created using
141+
just <acronym>SQL</acronym> commands, without any low-level programming.
142+
Refer to <xref linkend="datatype-enum"> for more information.
129143
</para>
130144
</sect2>
131145

132146
<sect2>
133-
<title>Composite Types</title>
147+
<title>Container Types</title>
148+
149+
<para>
150+
<productname>PostgreSQL</productname> has three kinds
151+
of <quote>container</quote> types, which are types that contain multiple
152+
values of other types. These are arrays, composites, and ranges.
153+
</para>
154+
155+
<para>
156+
Arrays can hold multiple values that are all of the same type. An array
157+
type is automatically created for each base type, composite type, range
158+
type, and domain type. But there are no arrays of arrays. So far as
159+
the type system is concerned, multi-dimensional arrays are the same as
160+
one-dimensional arrays. Refer to <xref linkend="arrays"> for more
161+
information.
162+
</para>
134163

135164
<para>
136165
Composite types, or row types, are created whenever the user
@@ -139,26 +168,28 @@
139168
define a <quote>stand-alone</quote> composite type with no associated
140169
table. A composite type is simply a list of types with
141170
associated field names. A value of a composite type is a row or
142-
record of field values. The user can access the component fields
143-
from <acronym>SQL</acronym> queries. Refer to <xref linkend="rowtypes">
144-
for more information on composite types.
171+
record of field values. Refer to <xref linkend="rowtypes">
172+
for more information.
173+
</para>
174+
175+
<para>
176+
A range type can hold two values of the same type, which are the lower
177+
and upper bounds of the range. Range types are user-created, although
178+
a few built-in ones exist. Refer to <xref linkend="rangetypes">
179+
for more information.
145180
</para>
146181
</sect2>
147182

148183
<sect2 id="extend-type-system-domains">
149184
<title>Domains</title>
150185

151186
<para>
152-
A domain is based on a particular base type and for many purposes
153-
is interchangeable with its base type. However, a domain can
154-
have constraints that restrict its valid values to a subset of
155-
what the underlying base type would allow.
156-
</para>
157-
158-
<para>
159-
Domains can be created using the <acronym>SQL</acronym> command
160-
<xref linkend="sql-createdomain">.
161-
Their creation and use is not discussed in this chapter.
187+
A domain is based on a particular underlying type and for many purposes
188+
is interchangeable with its underlying type. However, a domain can have
189+
constraints that restrict its valid values to a subset of what the
190+
underlying type would allow. Domains are created using
191+
the <acronym>SQL</acronym> command <xref linkend="sql-createdomain">.
192+
Refer to <xref linkend="domains"> for more information.
162193
</para>
163194
</sect2>
164195

@@ -167,8 +198,8 @@
167198

168199
<para>
169200
There are a few <quote>pseudo-types</quote> for special purposes.
170-
Pseudo-types cannot appear as columns of tables orattributes of
171-
composite types, but they can be used to declare the argument and
201+
Pseudo-types cannot appear as columns of tables orcomponents of
202+
container types, but they can be used to declare the argument and
172203
result types of functions. This provides a mechanism within the
173204
type system to identify special classes of functions. <xref
174205
linkend="datatype-pseudotypes-table"> lists the existing
@@ -188,7 +219,7 @@
188219
</indexterm>
189220

190221
<indexterm zone="extend-types-polymorphic">
191-
<primary>type</primary>
222+
<primary>datatype</primary>
192223
<secondary>polymorphic</secondary>
193224
</indexterm>
194225

‎doc/src/sgml/ref/alter_domain.sgml

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -199,7 +199,7 @@ ALTER DOMAIN <replaceable class="parameter">name</replaceable>
199199
</varlistentry>
200200

201201
<varlistentry>
202-
<term><replaceable class="parameter">NOT VALID</replaceable></term>
202+
<term><literal>NOT VALID</literal></term>
203203
<listitem>
204204
<para>
205205
Do not verify existing column data for constraint validity.
@@ -274,11 +274,11 @@ ALTER DOMAIN <replaceable class="parameter">name</replaceable>
274274

275275
<para>
276276
Currently, <command>ALTER DOMAIN ADD CONSTRAINT</command>, <command>ALTER
277-
DOMAIN VALIDATE CONSTRAINT</command>, and <command>ALTER DOMAIN SET NOT NULL</command>
278-
will fail if thevalidatednamed domain or
279-
any derived domain is usedwithin acomposite-type columnof any
280-
table in the database. They should eventually be improved to be
281-
ableto verify the new constraint for such nestedcolumns.
277+
DOMAIN VALIDATE CONSTRAINT</command>, and <command>ALTER DOMAIN SET NOT
278+
NULL</command>will fail if the named domain or any derived domain is used
279+
within acontainer-type column(a composite, array, or range column) in
280+
anytable in the database. They should eventually be improved to be able
281+
to verify the new constraint for such nestedvalues.
282282
</para>
283283

284284
</refsect1>

‎doc/src/sgml/rowtypes.sgml

Lines changed: 9 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -328,11 +328,16 @@ SELECT (myfunc(x)).a, (myfunc(x)).b, (myfunc(x)).c FROM some_table;
328328
with either syntax. If it's an expensive function you may wish to
329329
avoid that, which you can do with a query like:
330330
<programlisting>
331-
SELECT(m).* FROM(SELECTmyfunc(x) AS m FROM some_table OFFSET 0) ss;
331+
SELECTm.* FROMsome_table, LATERALmyfunc(x) AS m;
332332
</programlisting>
333-
The <literal>OFFSET 0</literal> clause keeps the optimizer
334-
from <quote>flattening</quote> the sub-select to arrive at the form with
335-
multiple calls of <function>myfunc()</function>.
333+
Placing the function in
334+
a <literal>LATERAL</literal> <literal>FROM</literal> item keeps it from
335+
being invoked more than once per row. <literal>m.*</literal> is still
336+
expanded into <literal>m.a, m.b, m.c</literal>, but now those variables
337+
are just references to the output of the <literal>FROM</literal> item.
338+
(The <literal>LATERAL</literal> keyword is optional here, but we show it
339+
to clarify that the function is getting <structfield>x</structfield>
340+
from <structname>some_table</structname>.)
336341
</para>
337342
</tip>
338343

0 commit comments

Comments
 (0)
[8]ページ先頭
©2009-2025 Movatter.jp