public inbox for [email protected]  

help / color / mirror / Atom feed

From: Dapeng Wang <[email protected]>
To: [email protected]
Subject: doc: add examples section to earthdistance documentation
Date: Tue, 7 Apr 2026 13:31:40 +0800
Message-ID: <CAKx0YhxzCT3werEz1Y81Us4sbYRjC62RXs1VP8kBi5B0KnS=ig@mail.gmail.com> (raw)

Hi,

I noticed that the earthdistance documentation has no usage
examples, which makes it harder for new users to get started
with the module. Other contrib modules like hstore already
include helpful examples.

I've attached a patch that adds an Examples section covering
the main functions and the point-based distance operator.
All examples were tested on PostgreSQL 18.3.

Regards,
Dapeng Wang


Attachments:

  [application/octet-stream] 0001-doc-add-examples-section-to-earthdistance-documentat.patch (3.2K, ../CAKx0YhxzCT3werEz1Y81Us4sbYRjC62RXs1VP8kBi5B0KnS=ig@mail.gmail.com/3-0001-doc-add-examples-section-to-earthdistance-documentat.patch)
  download | inline diff:
From a9194210a24a785c15afcad2543ffc174320589d Mon Sep 17 00:00:00 2001
From: wangdapeng <[email protected]>
Date: Tue, 7 Apr 2026 13:16:54 +0800
Subject: [PATCH] doc: add examples section to earthdistance documentation

---
 doc/src/sgml/earthdistance.sgml | 103 ++++++++++++++++++++++++++++++++
 1 file changed, 103 insertions(+)

diff --git a/doc/src/sgml/earthdistance.sgml b/doc/src/sgml/earthdistance.sgml
index 5a709e3..89e6059 100644
--- a/doc/src/sgml/earthdistance.sgml
+++ b/doc/src/sgml/earthdistance.sgml
@@ -262,4 +262,107 @@
 
  </sect2>
 
+ <sect2 id="earthdistance-examples">
+  <title>Examples</title>
+
+  <para>
+   The following examples demonstrate the use of the
+   <filename>earthdistance</filename> module with locations in
+   Tokyo (latitude 35.6762, longitude 139.6503) and
+   Osaka (latitude 34.6937, longitude 135.5023).
+  </para>
+
+  <para>
+   First, install the required extensions:
+<programlisting>
+CREATE EXTENSION cube;
+CREATE EXTENSION earthdistance CASCADE;
+</programlisting>
+  </para>
+
+  <para>
+   Retrieve the assumed radius of the Earth in meters:
+<programlisting>
+SELECT earth();
+  earth
+---------
+ 6378168
+(1 row)
+</programlisting>
+  </para>
+
+  <para>
+   Convert latitude and longitude to an <type>earth</type> point
+   (a 3D coordinate):
+<programlisting>
+SELECT ll_to_earth(35.6762, 139.6503);
+                         ll_to_earth
+-------------------------------------------------------------
+ (-3948591.2574923225, 3354541.741384729, 3719772.012205412)
+(1 row)
+</programlisting>
+  </para>
+
+  <para>
+   Calculate the great circle distance in meters between Tokyo and Osaka:
+<programlisting>
+SELECT earth_distance(
+  ll_to_earth(35.6762, 139.6503),
+  ll_to_earth(34.6937, 135.5023)
+);
+  earth_distance
+-------------------
+ 392882.7648340743
+(1 row)
+</programlisting>
+  </para>
+
+  <para>
+   Extract latitude and longitude back from an <type>earth</type> point:
+<programlisting>
+SELECT latitude(ll_to_earth(35.6762, 139.6503));
+      latitude
+--------------------
+ 35.676199999999994
+(1 row)
+
+SELECT longitude(ll_to_earth(35.6762, 139.6503));
+ longitude
+-----------
+  139.6503
+(1 row)
+</programlisting>
+  </para>
+
+  <para>
+   Using the point-based operator to calculate distance in statute miles:
+<programlisting>
+SELECT point(139.6503, 35.6762) &lt;@&gt; point(135.5023, 34.6937);
+     ?column?
+-------------------
+ 243.8511729296967
+(1 row)
+</programlisting>
+   Note that <type>point</type> takes (longitude, latitude) order,
+   not (latitude, longitude).
+  </para>
+
+  <para>
+   Use <function>earth_box</function> to find points within 50 km of
+   Tokyo.  This creates a bounding box suitable for an indexed search:
+<programlisting>
+SELECT earth_box(ll_to_earth(35.6762, 139.6503), 50000);
+</programlisting>
+   Since some points inside the box may be farther than 50 km,
+   combine it with <function>earth_distance</function> for exact filtering:
+<programlisting>
+SELECT name, location
+FROM cities
+WHERE earth_box(ll_to_earth(35.6762, 139.6503), 50000) @&gt; location
+  AND earth_distance(location, ll_to_earth(35.6762, 139.6503)) &lt; 50000;
+</programlisting>
+  </para>
+
+ </sect2>
+ 
 </sect1>
-- 
2.46.2.windows.1

reply

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Reply to all the recipients using the --to and --cc options:
  reply via email

  To: [email protected]
  Cc: [email protected], [email protected]
  Subject: Re: doc: add examples section to earthdistance documentation
  In-Reply-To: <CAKx0YhxzCT3werEz1Y81Us4sbYRjC62RXs1VP8kBi5B0KnS=ig@mail.gmail.com>

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

This inbox is served by agora; see mirroring instructions
for how to clone and mirror all data and code used for this inbox