hstore docs

Update hstore docs, mostly word-smithing.

David E. Wheeler

diff --git a/doc/src/sgml/hstore.sgml b/doc/src/sgml/hstore.sgml
index 78a2eb57ca510431a619177976b78a148e4e906d..bf3d7a476d4d39f44e996af8709fc9679dd7dcb8 100644 (file)
--- a/doc/src/sgml/hstore.sgml
+++ b/doc/src/sgml/hstore.sgml
@@ -1,4 +1,4 @@
-
+
 
 
  hstore
@@ -8,62 +8,76 @@
  
 
  
-  This module implements a data type hstore for storing sets of
-  (key,value) pairs within a single PostgreSQL data field.
+  This module implements the hstore data type for storing sets of
+  key/value pairs within a single PostgreSQL value.
   This can be useful in various scenarios, such as rows with many attributes
   that are rarely examined, or semi-structured data.  Keys and values are
-  arbitrary text strings.
+  simply text strings.
  
 
  
   <type>hstore</> External Representation
 
   
-   The text representation of an hstore value includes zero
-   or more key => value
-   items, separated by commas.  For example:
+
+   The text representation of an hstore, used for input and output,
+   includes zero or more key =>
+   value pairs separated by commas. Some examples:
 
    
-    k => v
-    foo => bar, baz => whatever
-    "1-a" => "anything at all"
+    k => v
+    foo => bar, baz => whatever
+    "1-a" => "anything at all"
    
 
-   The order of the items is not considered significant (and may not be
-   reproduced on output).  Whitespace between items or around the
-   => sign is ignored.  Use double quotes if a key or
-   value includes whitespace, comma, = or >.
-   To include a double quote or a backslash in a key or value, precede
-   it with another backslash.
+   The order of the pairs is not significant (and may not be reproduced on
+   output). Whitespace between pairs or around the => sign is
+   ignored. Double-quote keys and values that include whitespace, commas,
+   =s or >s. To include a double quote or a
+   backslash in a key or value, escape it with a backslash.
+  
+
+  
+   Each key in an hstore is unique. If you declare an hstore
+   with duplicate keys, only one will be stored in the hstore and
+   there is no guarantee as to which will be kept:
+
+   
+% select 'a=>1,a=>2'::hstore;
+  hstore
+----------
+ "a"=>"1"
+   
   
 
   
-   A value (but not a key) can be a SQL NULL.  This is represented as
+   A value (but not a key) can be an SQL NULL. For example:
 
    
-    key => NULL
+    key => NULL
    
 
-   The NULL keyword is not case-sensitive.  Again, use
-   double quotes if you want the string null to be treated
-   as an ordinary data value.
+   The NULL keyword is case-insensitive. Double-quote the
+   NULL to treat it as the ordinary string "NULL".
   
 
   
   
-   Keep in mind that the above format, when used to input hstore values,
-   applies before any required quoting or escaping. If you
-   are passing an hstore literal via a parameter, then no additional
-   processing is needed. If you are passing it as a quoted literal
-   constant, then any single-quote characters and (depending on the
-   setting of standard_conforming_strings) backslash characters
-   need to be escaped correctly. See .
+   Keep in mind that the hstore text format, when used for input,
+   applies before any required quoting or escaping. If you are
+   passing an hstore literal via a parameter, then no additional
+   processing is needed. But if you're passing it as a quoted literal
+   constant, then any single-quote characters and (depending on the setting of
+   the standard_conforming_strings configuration parameter)
+   backslash characters need to be escaped correctly. See
+    for more on the handling of string
+   constants.
   
   
 
   
-   Double quotes are always used to surround key and value
-   strings on output, even when this is not strictly necessary.
+   On output, double quotes always surround keys and values, even when it's
+   not strictly necessary.
   
 
  
@@ -87,42 +101,42 @@
     
      
       hstore -> text
-      get value for key (null if not present)
+      get value for key (NULL if not present)
       'a=>x, b=>y'::hstore -> 'a'
       x
      
 
      
       hstore -> text[]
-      get values for keys (null if not present)
+      get values for keys (NULL if not present)
       'a=>x, b=>y, c=>z'::hstore -> ARRAY['c','a']
       {"z","x"}
      
 
      
       text => text
-      make single-item hstore
+      make single-pair hstore
       'a' => 'b'
       "a"=>"b"
      
 
      
       text[] => text[]
-      construct an hstore value from separate key and value arrays
+      construct an hstore from separate key and value arrays
       ARRAY['a','b'] => ARRAY['1','2']
       "a"=>"1","b"=>"2"
      
 
      
       hstore => text[]
-      extract a subset of an hstore value
+      extract a subset of an hstore
       'a=>1,b=>2,c=>3'::hstore => ARRAY['b','c','x']
       "b"=>"2", "c"=>"3"
      
 
      
       hstore || hstore
-      concatenation
+      concatenate hstores
       'a=>b, c=>d'::hstore || 'c=>x, d=>q'::hstore
       "a"=>"b", "c"=>"x", "d"=>"q"
      
@@ -178,28 +192,28 @@
 
      
       hstore - hstore
-      delete matching key/value pairs from left operand
+      delete matching pairs from left operand
       'a=>1, b=>2, c=>3'::hstore - 'a=>4, b=>2'::hstore
       "a"=>"1", "c"=>"3"
      
 
      
       record #= hstore
-      replace fields in record with matching values from hstore
+      replace fields in record with matching values from hstore
       see Examples section
       
      
 
      
       %% hstore
-      convert hstore to array of alternating keys and values
+      convert hstore to array of alternating keys and values
       %% 'a=>foo, b=>bar'::hstore
       {a,foo,b,bar}
      
 
      
       %# hstore
-      convert hstore to two-dimensional key/value array
+      convert hstore to two-dimensional key/value array
       %# 'a=>foo, b=>bar'::hstore
       {{a,foo},{b,bar}}
      
@@ -208,13 +222,15 @@
    
   
 
+  
   
-   (Before PostgreSQL 8.2, the containment operators @> and <@ were
-   respectively called @ and ~.  These names are still available, but are
-   deprecated and will eventually be retired.  Notice that the old names
-   are reversed from the convention formerly followed by the core geometric
-   datatypes!)
-  
+   Prior to PostgreSQL 8.2, the containment operators @>
+   and <@ were called @ and ~,
+   respectively. These names are still available, but are deprecated and will
+   eventually be removed. Notice that the old names are reversed from the
+   convention formerly followed by the core geometric datatypes!
+   
+  
 
   
    <type>hstore</> Functions
@@ -251,7 +267,7 @@
      
       akeys(hstore)
       text[]
-      get hstore's keys as array
+      get hstore's keys as an array
       akeys('a=>1,b=>2')
       {a,b}
      
@@ -259,10 +275,10 @@
      
       skeys(hstore)
       setof text
-      get hstore's keys as set
+      get hstore's keys as a set
       skeys('a=>1,b=>2')
       
-
+22
 a
 b
 
@@ -271,7 +287,7 @@ b
      
       avals(hstore)
       text[]
-      get hstore's values as array
+      get hstore's values as an array
       avals('a=>1,b=>2')
       {1,2}
      
@@ -279,7 +295,7 @@ b
      
       svals(hstore)
       setof text
-      get hstore's values as set
+      get hstore's values as a set
       svals('a=>1,b=>2')
       
 
@@ -307,8 +323,8 @@ b
 
      
       each(hstore)
-      setof (key text, value text)
-      get hstore's keys and values as set
+      setof(key text, value text)
+      get hstore's keys and values as a set
       select * from each('a=>1,b=>2')
       
 
@@ -330,7 +346,7 @@ b
      
       defined(hstore,text)
       boolean
-      does hstore contain non-null value for key?
+      does hstore contain non-NULL value for key?
       defined('a=>NULL','a')
       f
      
@@ -338,7 +354,7 @@ b
      
       delete(hstore,text)
       hstore
-      delete any item matching key
+      delete pair with matching key
       delete('a=>1,b=>2','b')
       "a"=>"1"
      
@@ -346,7 +362,7 @@ b
      
       delete(hstore,text[])
       hstore
-      delete any item matching any of the keys
+      delete pairs with matching keys
       delete('a=>1,b=>2,c=>3',ARRAY['a','b'])
       "c"=>"3"
      
@@ -354,7 +370,7 @@ b
      
       delete(hstore,hstore)
       hstore
-      delete any key/value pair with an exact match in the second argument
+      delete pairs matching those in the second argument
       delete('a=>1,b=>2','a=>4,b=>2'::hstore)
       "a"=>"1"
      
@@ -362,7 +378,7 @@ b
      
       populate_record(record,hstore)
       record
-      replace fields in record with matching values from hstore
+      replace fields in record with matching values from hstore
       see Examples section
       
      
@@ -374,7 +390,7 @@ b
   
    
     The function populate_record is actually declared
-    with anyelement, not record, as its first argument;
+    with anyelement, not record, as its first argument,
     but it will reject non-record types with a runtime error.
    
   
@@ -384,9 +400,8 @@ b
   Indexes
 
   
-   hstore has index support for @>, ?,
-   ?& and ?| operators.  You can use either
-   GiST or GIN index types.  For example:
+   hstore has GiST and GIN index support for the @>,
+   ?, ?& and ?| operators. For example:
   
   
 CREATE INDEX hidx ON testhstore USING GIST (h);
@@ -395,14 +410,13 @@ CREATE INDEX hidx ON testhstore USING GIN (h);
   
 
   
-   Additionally, hstore has index support for the =
-   operator using the btree or hash index types. This
-   allows hstore columns to be declared UNIQUE, or used with
-   GROUP BY, ORDER BY or DISTINCT. The sort ordering for hstore
-   values is not intended to be particularly useful; it merely brings
-   exactly equal values together.
-   If an index is needed to support = comparisons it can be
-   created as follows:
+   hstore also supports btree or hash indexes for
+   the = operator. This allows hstore columns to be
+   declared UNIQUE, or to be used in GROUP BY,
+   ORDER BY or DISTINCT expressions. The sort ordering
+   for hstore values is not particularly useful, but these indexes
+   may be useful for equivalence lookups. Create indexes for =
+   comparisons as follows:
   
   
 CREATE INDEX hidx ON testhstore USING BTREE (h);
@@ -418,7 +432,7 @@ CREATE INDEX hidx ON testhstore USING HASH (h);
    Add a key, or update an existing key with a new value:
   
   
-UPDATE tab SET h = h || ('c' => '3');
+UPDATE tab SET h = h || ('c' => '3');
   
 
   
@@ -429,7 +443,7 @@ UPDATE tab SET h = delete(h, 'k1');
   
 
   
-   Convert a record to an hstore:
+   Convert a record to an hstore:
   
   
 CREATE TABLE test (col1 integer, col2 text, col3 text);
@@ -438,18 +452,18 @@ INSERT INTO test VALUES (123, 'foo', 'bar');
 SELECT hstore(t) FROM test AS t;
                    hstore                    
 ---------------------------------------------
- "col1"=>"123", "col2"=>"foo", "col3"=>"bar"
+ "col1"=>"123", "col2"=>"foo", "col3"=>"bar"
 (1 row)
   
 
   
-   Convert an hstore to a predefined record type:
+   Convert an hstore to a predefined record type:
   
   
 CREATE TABLE test (col1 integer, col2 text, col3 text);
 
 SELECT * FROM populate_record(null::test,
-                              '"col1"=>"456", "col2"=>"zzz"');
+                              '"col1"=>"456", "col2"=>"zzz"');
  col1 | col2 | col3 
 ------+------+------
   456 | zzz  | 
@@ -457,13 +471,13 @@ SELECT * FROM populate_record(null::test,
   
 
   
-   Modify an existing record using the values from an hstore:
+   Modify an existing record using the values from an hstore:
   
   
 CREATE TABLE test (col1 integer, col2 text, col3 text);
 INSERT INTO test VALUES (123, 'foo', 'bar');
 
-SELECT (r).* FROM (SELECT t #= '"col3"=>"baz"' AS r FROM test t) s;
+SELECT (r).* FROM (SELECT t #= '"col3"=>"baz"' AS r FROM test t) s;
  col1 | col2 | col3 
 ------+------+------
   123 | foo  | baz
@@ -477,15 +491,15 @@ SELECT (r).* FROM (SELECT t #= '"col3"=>"baz"' AS r FROM test t) s;
   
    The hstore type, because of its intrinsic liberality, could
    contain a lot of different keys. Checking for valid keys is the task of the
-   application.  Examples below demonstrate several techniques for checking
-   keys and obtaining statistics.
+   application. The following examples demonstrate several techniques for
+   checking keys and obtaining statistics.
   
 
   
    Simple example:
   
   
-SELECT * FROM each('aaa=>bq, b=>NULL, ""=>1');
+SELECT * FROM each('aaa=>bq, b=>NULL, ""=>1');
   
 
   
@@ -523,8 +537,8 @@ SELECT key, count(*) FROM
 
   
    When upgrading from older versions, always load the new
-   version of this module into the database before restoring an old
-   dump. Otherwise, many new features will be unavailable.
+   version of this module into the database before restoring a dump.
+   Otherwise, many new features will be unavailable.
   
 
   
@@ -535,12 +549,11 @@ SELECT key, count(*) FROM
   
 
   
-   In the event of doing a binary upgrade, upward
-   compatibility is maintained by having the new code recognize
-   old-format data. This will entail a slight performance penalty when
-   processing data that has not yet been modified by the new code. It is
-   possible to force an upgrade of all values in a table column
-   by doing an UPDATE statement as follows:
+   In the event of a binary upgrade, upward compatibility is maintained by
+   having the new code recognize old-format data. This will entail a slight
+   performance penalty when processing data that has not yet been modified by
+   the new code. It is possible to force an upgrade of all values in a table
+   column by doing an UPDATE statement as follows:
   
   
 UPDATE tablename SET hstorecol = hstorecol || '';
@@ -569,7 +582,8 @@ ALTER TABLE tablename ALTER hstorecol TYPE hstore USING hstorecol || '';
   
 
   
-   Additional enhancements by Andrew Gierth [email protected], United Kingdom
+   Additional enhancements by Andrew Gierth [email protected],
+   United Kingdom