diff --git a/doc/src/sgml/hstore.sgml b/doc/src/sgml/hstore.sgml index 78a2eb57ca..bf3d7a476d 100644 --- 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. - A value (but not a key) can be a SQL NULL. This is represented as + 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: - key => NULL +% select 'a=>1,a=>2'::hstore; + hstore +---------- + "a"=>"1" + + + + + A value (but not a key) can be an SQL NULL. For example: + + + 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 andrew@tao11.riddles.org.uk, United Kingdom + Additional enhancements by Andrew Gierth andrew@tao11.riddles.org.uk, + United Kingdom