2 files changed, 47 insertions, 3 deletions
diff --git a/doc/src/sgml/hstore.sgml b/doc/src/sgml/hstore.sgml
index 14a36ade00a..080706280e8 100644
--- a/doc/src/sgml/hstore.sgml
+++ b/doc/src/sgml/hstore.sgml
@@ -713,6 +713,39 @@ b
     </tbody>
    </tgroup>
   </table>
+
+  <para>
+   In addition to these operators and functions, values of
+   the <type>hstore</type> type can be subscripted, allowing them to act
+   like associative arrays.  Only a single subscript of type <type>text</type>
+   can be specified; it is interpreted as a key and the corresponding
+   value is fetched or stored.  For example,
+
+<programlisting>
+CREATE TABLE mytable (h hstore);
+INSERT INTO mytable VALUES ('a=>b, c=>d');
+SELECT h['a'] FROM mytable;
+ h
+---
+ b
+(1 row)
+
+UPDATE mytable SET h['c'] = 'new';
+SELECT h FROM mytable;
+          h
+----------------------
+ "a"=>"b", "c"=>"new"
+(1 row)
+</programlisting>
+
+   A subscripted fetch returns <literal>NULL</literal> if the subscript
+   is <literal>NULL</literal> or that key does not exist in
+   the <type>hstore</type>.  (Thus, a subscripted fetch is not greatly
+   different from the <literal>-&gt;</literal> operator.)
+   A subscripted update fails if the subscript is <literal>NULL</literal>;
+   otherwise, it replaces the value for that key, adding an entry to
+   the <type>hstore</type> if the key does not already exist.
+  </para>
  </sect2>
 
  <sect2>
@@ -767,8 +800,17 @@ CREATE INDEX hidx ON testhstore USING HASH (h);
   <para>
    Add a key, or update an existing key with a new value:
 <programlisting>
+UPDATE tab SET h['c'] = '3';
+</programlisting>
+   Another way to do the same thing is:
+<programlisting>
 UPDATE tab SET h = h || hstore('c', '3');
 </programlisting>
+   If multiple keys are to be added or changed in one operation,
+   the concatenation approach is more efficient than subscripting:
+<programlisting>
+UPDATE tab SET h = h || hstore(array['q', 'w'], array['11', '12']);
+</programlisting>
   </para>
 
   <para>
diff --git a/doc/src/sgml/ref/create_type.sgml b/doc/src/sgml/ref/create_type.sgml
index d909ee0d33b..d575f166142 100644
--- a/doc/src/sgml/ref/create_type.sgml
+++ b/doc/src/sgml/ref/create_type.sgml
@@ -333,9 +333,11 @@ CREATE TYPE <replaceable class="parameter">name</replaceable>
    return an <type>internal</type> result, which is a pointer to a struct
    of methods (functions) that implement subscripting.
    The detailed API for subscript functions appears
-   in <filename>src/include/nodes/subscripting.h</filename>;
-   it may also be useful to read the array implementation
-   in <filename>src/backend/utils/adt/arraysubs.c</filename>.
+   in <filename>src/include/nodes/subscripting.h</filename>.
+   It may also be useful to read the array implementation
+   in <filename>src/backend/utils/adt/arraysubs.c</filename>,
+   or the simpler code
+   in <filename>contrib/hstore/hstore_subs.c</filename>.
    Additional information appears in
    <xref linkend="sql-createtype-array"/> below.
   </para>