[HACKERS] [PATCH] Add some more documentation for array indexes/operators

[Ryan Kelly]

I had trouble finding what operators arrays supported or which ones
had index support or even determining that arrays could be indexed from
the documentation from the array data type. So, patch.

-Ryan Kelly

diff --git a/doc/src/sgml/array.sgml b/doc/src/sgml/array.sgml
index 3508ba3..51d996d 100644
--- a/doc/src/sgml/array.sgml
+++ b/doc/src/sgml/array.sgml
@@ -573,6 +573,33 @@ SELECT * FROM
   This function is described in <xref linkend="functions-srf-subscripts">.
  </para>
 
+ <para>
+  You can also search with arrays using the <literal>@&gt;</>,
+  <literal>&lt;@</>, and <literal>&amp;&amp;</> operators which check
+  whether the left operand contains, is contained by, or overlaps with
+  the right operand, respectively. For instance,
+
+<programlisting>
+SELECT * FROM sal_emp WHERE pay_by_quarter && ARRAY[10000];
+</programlisting>
+
+  Will find all rows where the <structfield>pay_by_quarter</structfield>
+  overlaps with an array containing <literal>10000</>, that is, any
+  employee with a quarterly salary of <literal>10000</> will be matched.
+ </para>
+
+ <para>
+  See <xref linkend="arrays"> for more details about array operator
+  behavior.
+ </para>
+
+ <para>
+  Additionally, a number of operators support indexed operations. This means
+  that the example above could utilize an index to efficiently locate those 
+  employees with the desired quarterly salary. See <xref linkend="indexes-types">
+  for more details about which operators support indexed operations.
+ </para>
+
  <tip>
   <para>
    Arrays are not sets; searching for specific array elements
diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index cd374ac..2cef8e4 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -10282,7 +10282,8 @@ SELECT NULLIF(value, '(none)') ...
 
   <para>
    See <xref linkend="arrays"> for more details about array operator
-   behavior.
+   behavior. See <xref linkend="indexes-types"> for more details about
+   which operators support indexed operations.
   </para>
 
   <para>

-- 
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers