diff --git a/doc/src/sgml/array.sgml b/doc/src/sgml/array.sgml
index f4d4a610ef..a2dfd4de0a 100644
--- a/doc/src/sgml/array.sgml
+++ b/doc/src/sgml/array.sgml
@@ -14,6 +14,12 @@
or domain can be created.
+
+ A multi-dimensional array is not the same as an array-of-arrays. In
+ particular it is not useful to access a two-dimensional array with
+ a single dimension - you will be given null instead of an array
+ containing the elements of the specified row.
+
Declaration of Array Types
@@ -115,7 +121,7 @@ CREATE TABLE tictactoe (
'{{1,2,3},{4,5,6},{7,8,9}}'
This constant is a two-dimensional, 3-by-3 array consisting of
- three subarrays of integers.
+ nine integers.
@@ -374,6 +380,25 @@ SELECT cardinality(schedule) FROM sal_emp WHERE name = 'Carol';
(1 row)
+
+
+ unnest, and other iteration access of arrays, is performed
+ depth-first, for each lower dimension all higher dimension cells are returned
+ before the next lower bound index. For a two-dimensional array this is termed
+ row-first.
+
+
+SELECT unnest(schedule) FROM sal_emp WHERE name = 'Bill';
+
+ unnest
+--------------
+ meeting
+ lunch
+ training
+ presentation
+(4 rows)
+
+