[PATCH] hstore documentation update
[PATCH] hstore documentation update
От:
"David E. Wheeler" <david@kineticode.com>
Дата:
From: David E. Wheeler
As I threatened when I reviewed hstore in the last two commit
fests, I've finally seen may way to edit the documentation. This
is mostly word-smithing, making sure that all `>`s are encoded,
making sure that various text is properly tagged with ``
and `` tags, plus an extra note or two. I submit this
patch for the next CommitFest (though I don't know how much CFing
is needed for a pure documenation patch).
Best,
David
---doc/src/sgml/hstore.sgml | 190 +++++++++++++++++++++++++---------------------1 files changed, 102 insertions(+), 88 deletions(-)
diff --git a/doc/src/sgml/hstore.sgml b/doc/src/sgml/hstore.sgml
index f237be7..fcff6e3 100644
*** a/doc/src/sgml/hstore.sgml
--- b/doc/src/sgml/hstore.sgml
***************
*** 8,69 ****
! This module implements a data type hstore</> for storing sets of
! (key,value) pairs within a single PostgreSQL</> data field. 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. <type>hstore</> External Representation
! The text representation of an hstore</> value includes zero
! or more key</> =></> value</>
! items, separated by commas. For example:
! 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.
! A value (but not a key) can be a SQL NULL. This is represented as
! 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.
! 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 .
! Double quotes are always used to surround key and value
! strings on output, even when this is not strictly necessary.
--- 8,83 ----
! 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
! simply text strings. <type>hstore</> External Representation
!
! 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"
! 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 an SQL NULL</>. For example:
!
!
! key => NULL
!
!
! The NULL</> keyword is case-insensitive. Double-quote the
! NULL</> to treat it as the ordinary string "NULL".
! 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.
! On output, double quotes always surround keys and values, even when it's
! not strictly necessary.
***************
*** 87,128 **** hstore</> -></> text</>
! 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) 'a=>x, b=>y, c=>z'::hstore -> ARRAY['c','a'] {"z","x"} text</> =></> text</>
! make single-item hstore</> 'a' => 'b' "a"=>"b" text[]</> =></> text[]</>
! construct an hstore</> value 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 'a=>1,b=>2,c=>3'::hstore => ARRAY['b','c','x'] "b"=>"2", "c"=>"3" hstore</> ||</> hstore</>
! concatenation 'a=>b, c=>d'::hstore || 'c=>x, d=>q'::hstore "a"=>"b", "c"=>"x", "d"=>"q"
--- 101,142 ---- hstore</> -></> text</>
! 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) 'a=>x, b=>y, c=>z'::hstore -> ARRAY['c','a'] {"z","x"} text</> =></> text</>
! make single-pair hstore</> 'a' => 'b' "a"=>"b" text[]</> =></> text[]</>
! 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</> 'a=>1,b=>2,c=>3'::hstore => ARRAY['b','c','x'] "b"=>"2", "c"=>"3" hstore</> ||</> hstore</>
! concatenate hstore</>s 'a=>b, c=>d'::hstore || 'c=>x, d=>q'::hstore "a"=>"b", "c"=>"x", "d"=>"q"
***************
*** 178,205 **** hstore</> -</> hstore</>
! delete matching key/value 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 see Examples section %%</> hstore</>
! 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 %# 'a=>foo, b=>bar'::hstore {{a,foo},{b,bar}}
--- 192,219 ---- hstore</> -</> hstore</>
! 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</> see Examples section %%</> hstore</>
! 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 %# 'a=>foo, b=>bar'::hstore {{a,foo},{b,bar}}
***************
*** 208,220 ****
! (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!)
! <type>hstore</> Functions
--- 222,236 ----
+
! 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,257 **** akeys(hstore) text[]
! get hstore</>'s keys as array akeys('a=>1,b=>2') {a,b}
--- 267,273 ---- akeys(hstore) text[]
! get hstore</>'s keys as an array akeys('a=>1,b=>2') {a,b}
***************
*** 259,268 **** skeys(hstore) setof text
! get hstore</>'s keys as set skeys('a=>1,b=>2')
! a b
--- 275,284 ---- skeys(hstore) setof text
! get hstore</>'s keys as a set skeys('a=>1,b=>2')
! 22 a b
*************** b
*** 271,277 **** avals(hstore) text[]
! get hstore</>'s values as array avals('a=>1,b=>2') {1,2}
--- 287,293 ---- avals(hstore) text[]
! get hstore</>'s values as an array avals('a=>1,b=>2') {1,2}
*************** b
*** 279,285 **** svals(hstore) setof text
! get hstore</>'s values as set svals('a=>1,b=>2')
--- 295,301 ---- svals(hstore) setof text
! get hstore</>'s values as a set svals('a=>1,b=>2')
*************** b
*** 307,314 **** each(hstore)
! setof (key text, value text)
! get hstore</>'s keys and values as set select * from each('a=>1,b=>2')
--- 323,330 ---- each(hstore)
! setof (key text, value text)</>
! get hstore</>'s keys and values as a set select * from each('a=>1,b=>2')
*************** b
*** 330,336 **** defined(hstore,text) boolean
! does hstore</> contain non-null value for key? defined('a=>NULL','a') f
--- 346,352 ---- defined(hstore,text) boolean
! does hstore</> contain non-NULL</> value for key? defined('a=>NULL','a') f
*************** b
*** 338,344 **** delete(hstore,text) hstore
! delete any item matching key delete('a=>1,b=>2','b') "a"=>"1"
--- 354,360 ---- delete(hstore,text) hstore
! delete pair with matching key delete('a=>1,b=>2','b') "a"=>"1"
*************** b
*** 346,352 **** delete(hstore,text[]) hstore
! delete any item matching any of the keys delete('a=>1,b=>2,c=>3',ARRAY['a','b']) "c"=>"3"
--- 362,368 ---- delete(hstore,text[]) hstore
! delete pairs with matching keys delete('a=>1,b=>2,c=>3',ARRAY['a','b']) "c"=>"3"
*************** b
*** 354,360 **** delete(hstore,hstore) hstore
! delete any key/value pair with an exact match in the second argument delete('a=>1,b=>2','a=>4,b=>2'::hstore) "a"=>"1"
--- 370,376 ---- delete(hstore,hstore) hstore
! delete pairs matching those in the second argument delete('a=>1,b=>2','a=>4,b=>2'::hstore) "a"=>"1"
*************** b
*** 362,368 **** populate_record(record,hstore) record
! replace fields in record with matching values from hstore see Examples section
--- 378,384 ---- populate_record(record,hstore) record
! replace fields in record</> with matching values from hstore</> see Examples section
*************** b
*** 374,380 **** The function populate_record is actually declared
! with anyelement</>, not record</>, as its first argument; but it will reject non-record types with a runtime error.
--- 390,396 ---- The function populate_record is actually declared
! with anyelement</>, not record</>, as its first argument, but it will reject non-record types with a runtime error.
*************** b
*** 384,392 **** Indexes
! hstore</> has index support for @></>, ?</>,
! ?&</> and ?|</> operators. You can use either
! GiST or GIN index types. For example: CREATE INDEX hidx ON testhstore USING GIST (h);
--- 400,407 ---- Indexes
! hstore</> has GiST and GIN index support for the @></>,
! ?</>, ?&</> and ?|</> operators. For example: CREATE INDEX hidx ON testhstore USING GIST (h);
*************** CREATE INDEX hidx ON testhstore USING GI
*** 395,408 ****
! 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: CREATE INDEX hidx ON testhstore USING BTREE (h);
--- 410,422 ----
! 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);
*************** CREATE INDEX hidx ON testhstore USING HA
*** 418,424 **** Add a key, or update an existing key with a new value:
! UPDATE tab SET h = h || ('c' => '3');
--- 432,438 ---- Add a key, or update an existing key with a new value:
! UPDATE tab SET h = h || ('c' => '3');
*************** UPDATE tab SET h = delete(h, 'k1');
*** 429,435 ****
! Convert a record to an hstore: CREATE TABLE test (col1 integer, col2 text, col3 text);
--- 443,449 ----
! Convert a record</> to an hstore</>: CREATE TABLE test (col1 integer, col2 text, col3 text);
*************** INSERT INTO test VALUES (123, 'foo', 'ba
*** 438,455 **** SELECT hstore(t) FROM test AS t; hstore ---------------------------------------------
! "col1"=>"123", "col2"=>"foo", "col3"=>"bar" (1 row)
! 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 | col2 | col3 ------+------+------ 456 | zzz |
--- 452,469 ---- SELECT hstore(t) FROM test AS t; hstore ---------------------------------------------
! "col1"=>"123", "col2"=>"foo", "col3"=>"bar" (1 row)
! 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 | col2 | col3 ------+------+------ 456 | zzz |
*************** SELECT * FROM populate_record(null::test
*** 457,469 ****
! 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; col1 | col2 | col3 ------+------+------ 123 | foo | baz
--- 471,483 ----
! 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; col1 | col2 | col3 ------+------+------ 123 | foo | baz
*************** SELECT (r).* FROM (SELECT t #= '"col3"=>
*** 477,491 **** 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. Simple example:
! SELECT * FROM each('aaa=>bq, b=>NULL, ""=>1');
--- 491,505 ---- 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. The following examples demonstrate several techniques for
! checking keys and obtaining statistics. Simple example:
! SELECT * FROM each('aaa=>bq, b=>NULL, ""=>1');
*************** SELECT key, count(*) FROM
*** 523,530 **** 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.
--- 537,544 ---- When upgrading from older versions, always load the new
! version of this module into the database before restoring a dump.
! Otherwise, many new features will be unavailable.
*************** SELECT key, count(*) FROM
*** 535,546 ****
! 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: UPDATE tablename SET hstorecol = hstorecol || '';
--- 549,559 ----
! 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 || '';
*************** ALTER TABLE tablename ALTER hstorecol TY
*** 569,575 ****
! Additional enhancements by Andrew Gierth andrew@tao11.riddles.org.uk, United Kingdom
--- 582,589 ----
! Additional enhancements by Andrew Gierth andrew@tao11.riddles.org.uk,
! United Kingdom
--
1.6.4
Re: [PATCH] hstore documentation update
От:
Bruce Momjian <bruce@momjian.us>
Дата:
Applied. Thanks.
---------------------------------------------------------------------------
David E. Wheeler wrote:
> From: David E. Wheeler
>
> As I threatened when I reviewed hstore in the last two commit
> fests, I've finally seen may way to edit the documentation. This
> is mostly word-smithing, making sure that all `>`s are encoded,
> making sure that various text is properly tagged with ``
> and `` tags, plus an extra note or two. I submit this
> patch for the next CommitFest (though I don't know how much CFing
> is needed for a pure documenation patch).
>
> Best,
>
> David
>
> ---
> doc/src/sgml/hstore.sgml | 190 +++++++++++++++++++++++++---------------------
> 1 files changed, 102 insertions(+), 88 deletions(-)
>
> diff --git a/doc/src/sgml/hstore.sgml b/doc/src/sgml/hstore.sgml
> index f237be7..fcff6e3 100644
> *** a/doc/src/sgml/hstore.sgml
> --- b/doc/src/sgml/hstore.sgml
> ***************
> *** 8,69 ****
>
>
>
> ! This module implements a data type hstore</> for storing sets of
> ! (key,value) pairs within a single PostgreSQL</> data field.
> 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.
>
>
>
> <type>hstore</> External Representation
>
>
> ! The text representation of an hstore</> value includes zero
> ! or more key</> =></> value</>
> ! items, separated by commas. For example:
>
>
> ! 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.
>
>
>
> ! A value (but not a key) can be a SQL NULL. This is represented as
>
>
> ! 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.
>
>
>
>
> ! 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 .
>
>
>
>
> ! Double quotes are always used to surround key and value
> ! strings on output, even when this is not strictly necessary.
>
>
>
> --- 8,83 ----
>
>
>
> ! 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
> ! simply text strings.
>
>
>
> <type>hstore</> External Representation
>
>
> !
> ! 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"
>
>
> ! 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 an SQL NULL</>. For example:
> !
> !
> ! key => NULL
> !
> !
> ! The NULL</> keyword is case-insensitive. Double-quote the
> ! NULL</> to treat it as the ordinary string "NULL".
>
>
>
>
> ! 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.
>
>
>
>
> ! On output, double quotes always surround keys and values, even when it's
> ! not strictly necessary.
>
>
>
> ***************
> *** 87,128 ****
>
>
> hstore</> -></> text</>
> ! 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)
> 'a=>x, b=>y, c=>z'::hstore -> ARRAY['c','a']
> {"z","x"}
>
>
>
> text</> =></> text</>
> ! make single-item hstore</>
> 'a' => 'b'
> "a"=>"b"
>
>
>
> text[]</> =></> text[]</>
> ! construct an hstore</> value 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
> 'a=>1,b=>2,c=>3'::hstore => ARRAY['b','c','x']
> "b"=>"2", "c"=>"3"
>
>
>
> hstore</> ||</> hstore</>
> ! concatenation
> 'a=>b, c=>d'::hstore || 'c=>x, d=>q'::hstore
> "a"=>"b", "c"=>"x", "d"=>"q"
>
> --- 101,142 ----
>
>
> hstore</> -></> text</>
> ! 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)
> 'a=>x, b=>y, c=>z'::hstore -> ARRAY['c','a']
> {"z","x"}
>
>
>
> text</> =></> text</>
> ! make single-pair hstore</>
> 'a' => 'b'
> "a"=>"b"
>
>
>
> text[]</> =></> text[]</>
> ! 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</>
> 'a=>1,b=>2,c=>3'::hstore => ARRAY['b','c','x']
> "b"=>"2", "c"=>"3"
>
>
>
> hstore</> ||</> hstore</>
> ! concatenate hstore</>s
> 'a=>b, c=>d'::hstore || 'c=>x, d=>q'::hstore
> "a"=>"b", "c"=>"x", "d"=>"q"
>
> ***************
> *** 178,205 ****
>
>
> hstore</> -</> hstore</>
> ! delete matching key/value 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
> see Examples section
>
>
>
>
> %%</> hstore</>
> ! 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
> %# 'a=>foo, b=>bar'::hstore
> {{a,foo},{b,bar}}
>
> --- 192,219 ----
>
>
> hstore</> -</> hstore</>
> ! 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</>
> see Examples section
>
>
>
>
> %%</> hstore</>
> ! 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
> %# 'a=>foo, b=>bar'::hstore
> {{a,foo},{b,bar}}
>
> ***************
> *** 208,220 ****
>
>
>
>
> ! (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!)
> !
>
>
> <type>hstore</> Functions
> --- 222,236 ----
>
>
>
> +
>
> ! 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,257 ****
>
> akeys(hstore)
> text[]
> ! get hstore</>'s keys as array
> akeys('a=>1,b=>2')
> {a,b}
>
> --- 267,273 ----
>
> akeys(hstore)
> text[]
> ! get hstore</>'s keys as an array
> akeys('a=>1,b=>2')
> {a,b}
>
> ***************
> *** 259,268 ****
>
> skeys(hstore)
> setof text
> ! get hstore</>'s keys as set
> skeys('a=>1,b=>2')
>
> !
> a
> b
>
> --- 275,284 ----
>
> skeys(hstore)
> setof text
> ! get hstore</>'s keys as a set
> skeys('a=>1,b=>2')
>
> ! 22
> a
> b
>
> *************** b
> *** 271,277 ****
>
> avals(hstore)
> text[]
> ! get hstore</>'s values as array
> avals('a=>1,b=>2')
> {1,2}
>
> --- 287,293 ----
>
> avals(hstore)
> text[]
> ! get hstore</>'s values as an array
> avals('a=>1,b=>2')
> {1,2}
>
> *************** b
> *** 279,285 ****
>
> svals(hstore)
> setof text
> ! get hstore</>'s values as set
> svals('a=>1,b=>2')
>
>
> --- 295,301 ----
>
> svals(hstore)
> setof text
> ! get hstore</>'s values as a set
> svals('a=>1,b=>2')
>
>
> *************** b
> *** 307,314 ****
>
>
> each(hstore)
> ! setof (key text, value text)
> ! get hstore</>'s keys and values as set
> select * from each('a=>1,b=>2')
>
>
> --- 323,330 ----
>
>
> each(hstore)
> ! setof (key text, value text)</>
> ! get hstore</>'s keys and values as a set
> select * from each('a=>1,b=>2')
>
>
> *************** b
> *** 330,336 ****
>
> defined(hstore,text)
> boolean
> ! does hstore</> contain non-null value for key?
> defined('a=>NULL','a')
> f
>
> --- 346,352 ----
>
> defined(hstore,text)
> boolean
> ! does hstore</> contain non-NULL</> value for key?
> defined('a=>NULL','a')
> f
>
> *************** b
> *** 338,344 ****
>
> delete(hstore,text)
> hstore
> ! delete any item matching key
> delete('a=>1,b=>2','b')
> "a"=>"1"
>
> --- 354,360 ----
>
> delete(hstore,text)
> hstore
> ! delete pair with matching key
> delete('a=>1,b=>2','b')
> "a"=>"1"
>
> *************** b
> *** 346,352 ****
>
> delete(hstore,text[])
> hstore
> ! delete any item matching any of the keys
> delete('a=>1,b=>2,c=>3',ARRAY['a','b'])
> "c"=>"3"
>
> --- 362,368 ----
>
> delete(hstore,text[])
> hstore
> ! delete pairs with matching keys
> delete('a=>1,b=>2,c=>3',ARRAY['a','b'])
> "c"=>"3"
>
> *************** b
> *** 354,360 ****
>
> delete(hstore,hstore)
> hstore
> ! delete any key/value pair with an exact match in the second argument
> delete('a=>1,b=>2','a=>4,b=>2'::hstore)
> "a"=>"1"
>
> --- 370,376 ----
>
> delete(hstore,hstore)
> hstore
> ! delete pairs matching those in the second argument
> delete('a=>1,b=>2','a=>4,b=>2'::hstore)
> "a"=>"1"
>
> *************** b
> *** 362,368 ****
>
> populate_record(record,hstore)
> record
> ! replace fields in record with matching values from hstore
> see Examples section
>
>
> --- 378,384 ----
>
> populate_record(record,hstore)
> record
> ! replace fields in record</> with matching values from hstore</>
> see Examples section
>
>
> *************** b
> *** 374,380 ****
>
>
> The function populate_record is actually declared
> ! with anyelement</>, not record</>, as its first argument;
> but it will reject non-record types with a runtime error.
>
>
> --- 390,396 ----
>
>
> The function populate_record is actually declared
> ! with anyelement</>, not record</>, as its first argument,
> but it will reject non-record types with a runtime error.
>
>
> *************** b
> *** 384,392 ****
> Indexes
>
>
> ! hstore</> has index support for @></>, ?</>,
> ! ?&</> and ?|</> operators. You can use either
> ! GiST or GIN index types. For example:
>
>
> CREATE INDEX hidx ON testhstore USING GIST (h);
> --- 400,407 ----
> Indexes
>
>
> ! hstore</> has GiST and GIN index support for the @></>,
> ! ?</>, ?&</> and ?|</> operators. For example:
>
>
> CREATE INDEX hidx ON testhstore USING GIST (h);
> *************** CREATE INDEX hidx ON testhstore USING GI
> *** 395,408 ****
>
>
>
> ! 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:
>
>
> CREATE INDEX hidx ON testhstore USING BTREE (h);
> --- 410,422 ----
>
>
>
> ! 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);
> *************** CREATE INDEX hidx ON testhstore USING HA
> *** 418,424 ****
> Add a key, or update an existing key with a new value:
>
>
> ! UPDATE tab SET h = h || ('c' => '3');
>
>
>
> --- 432,438 ----
> Add a key, or update an existing key with a new value:
>
>
> ! UPDATE tab SET h = h || ('c' => '3');
>
>
>
> *************** UPDATE tab SET h = delete(h, 'k1');
> *** 429,435 ****
>
>
>
> ! Convert a record to an hstore:
>
>
> CREATE TABLE test (col1 integer, col2 text, col3 text);
> --- 443,449 ----
>
>
>
> ! Convert a record</> to an hstore</>:
>
>
> CREATE TABLE test (col1 integer, col2 text, col3 text);
> *************** INSERT INTO test VALUES (123, 'foo', 'ba
> *** 438,455 ****
> SELECT hstore(t) FROM test AS t;
> hstore
> ---------------------------------------------
> ! "col1"=>"123", "col2"=>"foo", "col3"=>"bar"
> (1 row)
>
>
>
> ! 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 | col2 | col3
> ------+------+------
> 456 | zzz |
> --- 452,469 ----
> SELECT hstore(t) FROM test AS t;
> hstore
> ---------------------------------------------
> ! "col1"=>"123", "col2"=>"foo", "col3"=>"bar"
> (1 row)
>
>
>
> ! 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 | col2 | col3
> ------+------+------
> 456 | zzz |
> *************** SELECT * FROM populate_record(null::test
> *** 457,469 ****
>
>
>
> ! 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;
> col1 | col2 | col3
> ------+------+------
> 123 | foo | baz
> --- 471,483 ----
>
>
>
> ! 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;
> col1 | col2 | col3
> ------+------+------
> 123 | foo | baz
> *************** SELECT (r).* FROM (SELECT t #= '"col3"=>
> *** 477,491 ****
>
> 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.
>
>
>
> Simple example:
>
>
> ! SELECT * FROM each('aaa=>bq, b=>NULL, ""=>1');
>
>
>
> --- 491,505 ----
>
> 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. The following examples demonstrate several techniques for
> ! checking keys and obtaining statistics.
>
>
>
> Simple example:
>
>
> ! SELECT * FROM each('aaa=>bq, b=>NULL, ""=>1');
>
>
>
> *************** SELECT key, count(*) FROM
> *** 523,530 ****
>
>
> 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.
>
>
>
> --- 537,544 ----
>
>
> When upgrading from older versions, always load the new
> ! version of this module into the database before restoring a dump.
> ! Otherwise, many new features will be unavailable.
>
>
>
> *************** SELECT key, count(*) FROM
> *** 535,546 ****
>
>
>
> ! 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:
>
>
> UPDATE tablename SET hstorecol = hstorecol || '';
> --- 549,559 ----
>
>
>
> ! 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 || '';
> *************** ALTER TABLE tablename ALTER hstorecol TY
> *** 569,575 ****
>
>
>
> ! Additional enhancements by Andrew Gierth andrew@tao11.riddles.org.uk, United Kingdom
>
>
>
> --- 582,589 ----
>
>
>
> ! Additional enhancements by Andrew Gierth andrew@tao11.riddles.org.uk,
> ! United Kingdom
>
>
>
> --
> 1.6.4
>
> --
> Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
> To make changes to your subscription:
> http://www.postgresql.org/mailpref/pgsql-hackers
-- Bruce Momjian http://momjian.us EnterpriseDB http://enterprisedb.com
+ If your life is a hard drive, Christ can be your backup. +
Re: [PATCH] hstore documentation update
От:
"David E. Wheeler" <david@kineticode.com>
Дата:
On Dec 1, 2009, at 2:56 AM, Bruce Momjian wrote: > Applied. Thanks. Thanks, I'll remove it from the next CF list, then. Best, David
Re: [PATCH] hstore documentation update
От:
David E. Wheeler <david@kineticode.com>
Дата:
On Dec 1, 2009, at 3:01 AM, David E. Wheeler wrote: > On Dec 1, 2009, at 2:56 AM, Bruce Momjian wrote: > >> Applied. Thanks. > > Thanks, I'll remove it from the next CF list, then. Oh, you already marked it as committed. Thanks! David
