↑↓ select ↵ open ⌫ change scope Open full search

PG.CENTER connects PostgreSQL documentation, reference, and ecosystem knowledge. Maintained by Pigsty.

Wiki / Data Types / Geometric

circle

circle on a plane

Reading PostgreSQL 18.6.

PG10–20 core source inventory. Casts and operator classes show explicitly declared relationships; absent rows do not rule out coercions or indexing through other mechanisms.

Definition

circle on a plane

circle
Catalog name
pg_catalog.circle
Type OID
718
Type kind
Base type
Declared length
24 bytes
Storage strategy
plain
Input function
circle_in
Output function
circle_out
Documented declaration
circle
Storage Size
24 bytes
Manual description
Circle
Representation
<(x,y),r> (center point and radius)

English manual

Read the complete manual section

Read the source definition

8.8. Geometric Types

Geometric data types represent two-dimensional spatial objects. Table 8.20 shows the geometric types available in PostgreSQL.

Table 8.20. Geometric Types

Name Storage Size Description Representation
point 16 bytes Point on a plane (x,y)
line 24 bytes Infinite line {A,B,C}
lseg 32 bytes Finite line segment [(x1,y1),(x2,y2)]
box 32 bytes Rectangular box (x1,y1),(x2,y2)
path 16+16n bytes Closed path (similar to polygon) ((x1,y1),...)
path 16+16n bytes Open path [(x1,y1),...]
polygon 40+16n bytes Polygon (similar to closed path) ((x1,y1),...)
circle 24 bytes Circle <(x,y),r> (center point and radius)

In all these types, the individual coordinates are stored as double precision (float8) numbers.

A rich set of functions and operators is available to perform various geometric operations such as scaling, translation, rotation, and determining intersections. They are explained in Section 9.11.

8.8.1. Points

Points are the fundamental two-dimensional building block for geometric types. Values of type point are specified using either of the following syntaxes:

( x , y )
  x , y

where x and y are the respective coordinates, as floating-point numbers.

Points are output using the first syntax.

8.8.2. Lines

Lines are represented by the linear equation Ax + By + C = 0, where A and B are not both zero. Values of type line are input and output in the following form:

{ A, B, C }

Alternatively, any of the following forms can be used for input:

[ ( x1 , y1 ) , ( x2 , y2 ) ]
( ( x1 , y1 ) , ( x2 , y2 ) )
  ( x1 , y1 ) , ( x2 , y2 )
    x1 , y1   ,   x2 , y2

where (x1,y1) and (x2,y2) are two different points on the line.

8.8.3. Line Segments

Line segments are represented by pairs of points that are the endpoints of the segment. Values of type lseg are specified using any of the following syntaxes:

[ ( x1 , y1 ) , ( x2 , y2 ) ]
( ( x1 , y1 ) , ( x2 , y2 ) )
  ( x1 , y1 ) , ( x2 , y2 )
    x1 , y1   ,   x2 , y2

where (x1,y1) and (x2,y2) are the end points of the line segment.

Line segments are output using the first syntax.

8.8.4. Boxes

Boxes are represented by pairs of points that are opposite corners of the box. Values of type box are specified using any of the following syntaxes:

( ( x1 , y1 ) , ( x2 , y2 ) )
  ( x1 , y1 ) , ( x2 , y2 )
    x1 , y1   ,   x2 , y2

where (x1,y1) and (x2,y2) are any two opposite corners of the box.

Boxes are output using the second syntax.

Any two opposite corners can be supplied on input, but the values will be reordered as needed to store the upper right and lower left corners, in that order.

8.8.5. Paths

Paths are represented by lists of connected points. Paths can be open, where the first and last points in the list are considered not connected, or closed, where the first and last points are considered connected.

Values of type path are specified using any of the following syntaxes:

[ ( x1 , y1 ) , ... , ( xn , yn ) ]
( ( x1 , y1 ) , ... , ( xn , yn ) )
  ( x1 , y1 ) , ... , ( xn , yn )
  ( x1 , y1   , ... ,   xn , yn )
    x1 , y1   , ... ,   xn , yn

where the points are the end points of the line segments comprising the path. Square brackets ([]) indicate an open path, while parentheses (()) indicate a closed path. When the outermost parentheses are omitted, as in the third through fifth syntaxes, a closed path is assumed.

Paths are output using the first or second syntax, as appropriate.

8.8.6. Polygons

Polygons are represented by lists of points (the vertices of the polygon). Polygons are very similar to closed paths; the essential semantic difference is that a polygon is considered to include the area within it, while a path is not.

An important implementation difference between polygons and paths is that the stored representation of a polygon includes its smallest bounding box. This speeds up certain search operations, although computing the bounding box adds overhead while constructing new polygons.

Values of type polygon are specified using any of the following syntaxes:

( ( x1 , y1 ) , ... , ( xn , yn ) )
  ( x1 , y1 ) , ... , ( xn , yn )
  ( x1 , y1   , ... ,   xn , yn )
    x1 , y1   , ... ,   xn , yn

where the points are the end points of the line segments comprising the boundary of the polygon.

Polygons are output using the first syntax.

8.8.7. Circles

Circles are represented by a center point and radius. Values of type circle are specified using any of the following syntaxes:

< ( x , y ) , r >
( ( x , y ) , r )
  ( x , y ) , r
    x , y   , r

where (x,y) is the center point and r is the radius of the circle.

Circles are output using the first syntax.

Catalog attributes

Source bootstrap values for this build. See pg_type for field meanings. Header defaults are included; build-dependent constants remain symbolic. This is not a live-server measurement.

oid
718
descr
geometric circle, format '<center point,radius>'
typacl
_null_
typlen
24
typelem
0
typname
circle
typsend
circle_send
typtype
b
typalign
d
typarray
0
typbyval
f
typdelim
','
typinput
circle_in
typmodin
-
typndims
0
typowner
POSTGRES
typrelid
0
typmodout
-
typoutput
circle_out
typtypmod
-1
typanalyze
-
typdefault
_null_
typnotnull
f
typreceive
circle_recv
typstorage
p
typbasetype
0
typcategory
G
typcollation
0
typisdefined
t
typnamespace
pg_catalog
typsubscript
-
typdefaultbin
_null_
array_type_oid
719
typispreferred
f
array_type_name
_circle

Catalog casts 5

Explicit pg_cast records involving this type. PostgreSQL also supports coercions outside pg_cast; an absent row does not prove that a conversion is impossible.

FromToContextMethodFunction
boxcircleExplicitFunctioncircle(box)
polygoncircleExplicitFunctioncircle(polygon)
circlepointExplicitFunctionpoint(circle)
circleboxExplicitFunctionbox(circle)
circlepolygonExplicitFunctionpolygon(circle)

Operator overloads 30

Each operand signature is a separate overload. Catalog implementation functions and result types belong to the same source build.

OperatorLeft operandRight operandResultMeaningImplementation
<@pointcircleboolis contained bypt_contained_circle
@>circlepointboolcontainscircle_contain_pt
@@None (unary)circlepointcenter ofcircle_center
=circlecircleboolequal by areacircle_eq
<>circlecircleboolnot equal by areacircle_ne
<circlecircleboolless than by areacircle_lt
>circlecircleboolgreater than by areacircle_gt
<=circlecircleboolless than or equal by areacircle_le
>=circlecircleboolgreater than or equal by areacircle_ge
<<circlecircleboolis left ofcircle_left
&<circlecirclebooloverlaps or is left ofcircle_overleft
&>circlecirclebooloverlaps or is right ofcircle_overright
>>circlecircleboolis right ofcircle_right
<@circlecircleboolis contained bycircle_contained
@>circlecircleboolcontainscircle_contain
~=circlecircleboolsame ascircle_same
&&circlecirclebooloverlapscircle_overlap
|>>circlecircleboolis abovecircle_above
<<|circlecircleboolis belowcircle_below
+circlepointcircleaddcircle_add_pt
-circlepointcirclesubtractcircle_sub_pt
*circlepointcirclemultiplycircle_mul_pt
/circlepointcircledividecircle_div_pt
<->circlecirclefloat8distance betweencircle_distance
<->pointcirclefloat8distance betweendist_pc
<->circlepointfloat8distance betweendist_cpoint
<->circlepolygonfloat8distance betweendist_cpoly
<->polygoncirclefloat8distance betweendist_polyc
&<|circlecirclebooloverlaps or is belowcircle_overbelow
|&>circlecirclebooloverlaps or is abovecircle_overabove

Operator classes 1

Operator classes whose declared input type matches this type. Polymorphic classes, casts and expression indexes can provide additional index paths; this list is not an exhaustive yes/no index-support test.

ClassIndex methodInput typeFamilyDefaultStorage type
circle_opsgistcirclegist/circle_opsYesbox

Version comparison

PostgreSQL 17.11 → 18.6. Source build identifiers and prose are excluded from attribute changes.

No catalog or structured attribute changes between these samples.

The documentation also differs between these builds; inspect the versioned manual definitions.

Documentation and source

Build
18.6 · https://ftp.postgresql.org/pub/source/v18.6/postgresql-18.6.tar.bz2
Fingerprint
555610c24d53e4316da5b7d3fc25c279d96856d5e0e23ee308c328c5fa881d9f

Related entries

All Data Types · Download this version as JSON · The first recorded sample does not establish when a type was introduced.