<?xml version="1.0" encoding="UTF-8"?>
<sect1 id="PostGIS_Types">
<sect1info>
<abstract>
<para>This section lists the custom PostgreSQL
data types installed by PostGIS to represent spatial data.
</para>
<para>Each data type describes its type casting behavior.
A <ulink url="https://www.postgresql.org/docs/current/sql-expressions.html#SQL-SYNTAX-TYPE-CASTS">type cast</ulink>
converts values of one data type into another type.
PostgreSQL allows defining casting behavior for custom types, along with the functions used to convert type values.
Casts can have <emphasis role="bold">automatic</emphasis> behavior,
which allows automatic conversion of a function argument to a type supported by the function.</para>
<para>
Some casts have <emphasis role="bold">explicit</emphasis> behavior,
which means the cast must be specified using the syntax <varname>CAST(myval As sometype)</varname>
or <varname>myval::sometype</varname>.
Explicit casting avoids the issue of ambiguous casts,
which can occur when using an overloaded function which does not support a given type.
For example, a function may accept a box2d or a box3d, but not a geometry.
Since geometry has an automatic cast to both box types, this produces an "ambiguous function" error.
To prevent the error use an explicit cast to the desired box type.</para>
<para>All data types can be cast to <varname>text</varname>, so this does not need to be specified explicitly.</para>
</abstract>
</sect1info>
<title>PostGIS Geometry/Geography/Box Data Types</title>
<refentry id="box2d_type">
<refnamediv>
<refname>box2d</refname>
<refpurpose>The type representing a 2-dimensional bounding box. </refpurpose>
</refnamediv>
<refsection>
<title>Description</title>
<para><varname>box2d</varname> is a spatial data type used to represent
the two-dimensional bounding box enclosing a geometry or collection of geometries.
For example, the <xref linkend="ST_Extent" /> aggregate function returns a <varname>box2d</varname> object.</para>
<para>The representation contains the values <varname>xmin, ymin, xmax, ymax</varname>.
These are the minimum and maximum values of the X and Y extents.
</para>
<para><varname>box2d</varname> objects have a text representation which looks like <code>BOX(1 2,5 6)</code>.
</para>
</refsection>
<refsection>
<title>Casting Behavior</title>
<para>This table lists the automatic and explicit casts allowed for this data type:</para>
<informaltable rowsep="1" frame="all">
<tgroup cols="2">
<tbody>
<row>
<entry>Cast To</entry> <entry>Behavior</entry>
</row>
<row>
<entry>box3d</entry> <entry>automatic</entry>
</row>
<row>
<entry>geometry</entry> <entry>automatic</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</refsection>
<refsection>
<title>See Also</title>
<para><xref linkend="PostGIS_BoxFunctions" /></para>
</refsection>
</refentry>
<refentry id="box3d_type">
<refnamediv>
<refname>box3d</refname>
<refpurpose>The type representing a 3-dimensional bounding box. </refpurpose>
</refnamediv>
<refsection>
<title>Description</title>
<para><varname>box3d</varname> is a PostGIS spatial data type used to represent
the three-dimensional bounding box enclosing a geometry or collection of geometries.
For example, the <xref linkend="ST_3DExtent" /> aggregate function returns a <varname>box3d</varname> object.
</para>
<para>The representation contains the values <varname>xmin, ymin, zmin, xmax, ymax, zmax</varname>.
These are the minimum and maxium values of the X, Y and Z extents.
</para>
<para><varname>box3d</varname> objects have a text representation which looks like <code>BOX3D(1 2 3,5 6 5)</code>.
</para>
</refsection>
<refsection>
<title>Casting Behavior</title>
<para>This table lists the automatic and explicit casts allowed for this data type:</para>
<informaltable rowsep="1" frame="all">
<tgroup cols="2">
<tbody>
<row>
<entry>Cast To</entry>
<entry>Behavior</entry>
</row>
<row>
<entry>box</entry>
<entry>automatic</entry>
</row>
<row>
<entry>box2d</entry>
<entry>automatic</entry>
</row>
<row>
<entry>geometry</entry>
<entry>automatic</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</refsection>
<refsection>
<title>See Also</title>
<para><xref linkend="PostGIS_BoxFunctions" /></para>
</refsection>
</refentry>
<refentry id="geometry">
<refnamediv>
<refname>geometry</refname>
<refpurpose>The type representing spatial features with planar coordinate systems.</refpurpose>
</refnamediv>
<refsection>
<title>Description</title>
<para><varname>geometry</varname> is a fundamental PostGIS spatial data type used to represent a feature in planar (Euclidean) coordinate systems.</para>
<para>All spatial operations on geometry use the units of the Spatial Reference System the geometry is in.</para>
</refsection>
<refsection>
<title>Casting Behavior</title>
<para>This table lists the automatic and explicit casts allowed for this data type:</para>
<informaltable rowsep="1" frame="all">
<tgroup cols="2">
<tbody>
<row>
<entry>Cast To</entry>
<entry>Behavior</entry>
</row>
<row>
<entry>box</entry>
<entry>automatic</entry>
</row>
<row>
<entry>box2d</entry>
<entry>automatic</entry>
</row>
<row>
<entry>box3d</entry>
<entry>automatic</entry>
</row>
<row>
<entry>bytea</entry>
<entry>automatic</entry>
</row>
<row>
<entry>geography</entry>
<entry>automatic</entry>
</row>
<row>
<entry>text</entry>
<entry>automatic</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</refsection>
<refsection>
<title>See Also</title>
<para><xref linkend="RefObject" />, <xref linkend="PostGIS_SQLMM_Functions" /></para>
</refsection>
</refentry>
<refentry id="geometry_dump">
<refnamediv>
<refname>geometry_dump</refname>
<refpurpose>A composite type used to describe the parts of complex geometry.</refpurpose>
</refnamediv>
<refsection>
<title>Description</title>
<para><varname>geometry_dump</varname> is a
<ulink url="https://www.postgresql.org/docs/current/rowtypes.html">composite data type</ulink>
containing the fields:</para>
<itemizedlist>
<listitem>
<para><varname>geom</varname> - a geometry representing a component of the dumped geometry.
The geometry type depends on the originating function.</para>
</listitem>
<listitem>
<para><varname>path[]</varname> - an integer array
that defines the navigation path within the dumped geometry to the <varname>geom</varname> component.
The path array is 1-based (i.e. <varname>path[1]</varname> is the first element.)</para>
</listitem>
</itemizedlist>
<para>
It is used by the <varname>ST_Dump*</varname> family of functions as an output type to explode a complex geometry into its
constituent parts.</para>
</refsection>
<refsection>
<title>See Also</title>
<para><xref linkend="PostGIS_Geometry_DumpFunctions" /> </para>
</refsection>
</refentry>
<refentry id="geography">
<refnamediv>
<refname>geography</refname>
<refpurpose>The type representing spatial features with geodetic (ellipsoidal) coordinate systems.</refpurpose>
</refnamediv>
<refsection>
<title>Description</title>
<para><varname>geography</varname> is a spatial data type used to represent a feature in geodetic coordinate systems.
Geodetic coordinate systems model the earth using an ellipsoid.
</para>
<para>
Spatial operations on the geography type provide more accurate results
by taking the ellipsoidal model into account.
</para>
</refsection>
<refsection>
<title>Casting Behavior</title>
<para>This table lists the automatic and explicit casts allowed for this data type:</para>
<informaltable rowsep="1" frame="all">
<tgroup cols="2">
<tbody>
<row>
<entry>Cast To</entry>
<entry>Behavior</entry>
</row>
<row>
<entry>geometry</entry>
<entry>explicit</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</refsection>
<refsection>
<title>See Also</title>
<para><xref linkend="PostGIS_Geography" />, <xref linkend="PostGIS_GeographyFunctions" /></para>
</refsection>
</refentry>
</sect1>