<!-- doc/src/sgml/hstore.sgml -->

<sect1 id="hstore" xreflabel="hstore">
 <title>hstore &mdash; hstore key/value datatype</title>

 <indexterm zone="hstore">
  <primary>hstore</primary>
 </indexterm>

 <para>
  This module implements the <type>hstore</type> data type for storing sets of
  key/value pairs within a single <productname>PostgreSQL</productname> 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.
 </para>

 <para>
  This module is considered <quote>trusted</quote>, that is, it can be
  installed by non-superusers who have <literal>CREATE</literal> privilege
  on the current database.
 </para>

 <sect2 id="hstore-external-rep">
  <title><type>hstore</type> External Representation</title>

  <para>

   The text representation of an <type>hstore</type>, used for input and output,
   includes zero or more <replaceable>key</replaceable> <literal>=&gt;</literal>
   <replaceable>value</replaceable> pairs separated by commas. Some examples:

<synopsis>
k =&gt; v
foo =&gt; bar, baz =&gt; whatever
"1-a" =&gt; "anything at all"
</synopsis>

   The order of the pairs is not significant (and may not be reproduced on
   output). Whitespace between pairs or around the <literal>=&gt;</literal> sign is
   ignored. Double-quote keys and values that include whitespace, commas,
   <literal>=</literal>s or <literal>&gt;</literal>s. To include a double quote or a
   backslash in a key or value, escape it with a backslash.
  </para>

  <para>
   Each key in an <type>hstore</type> is unique. If you declare an <type>hstore</type>
   with duplicate keys, only one will be stored in the <type>hstore</type> and
   there is no guarantee as to which will be kept:

<programlisting>
SELECT 'a=&gt;1,a=&gt;2'::hstore;
  hstore
----------
 "a"=&gt;"1"
</programlisting>
  </para>

  <para>
   A value (but not a key) can be an SQL <literal>NULL</literal>. For example:

<programlisting>
key =&gt; NULL
</programlisting>

   The <literal>NULL</literal> keyword is case-insensitive. Double-quote the
   <literal>NULL</literal> to treat it as the ordinary string <quote>NULL</quote>.
  </para>

  <note>
  <para>
   Keep in mind that the <type>hstore</type> text format, when used for input,
   applies <emphasis>before</emphasis> any required quoting or escaping. If you are
   passing an <type>hstore</type> 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 <varname>standard_conforming_strings</varname> configuration parameter)
   backslash characters need to be escaped correctly. See
   <xref linkend="sql-syntax-strings"/> for more on the handling of string
   constants.
  </para>
  </note>

  <para>
   On output, double quotes always surround keys and values, even when it's
   not strictly necessary.
  </para>

 </sect2>

 <sect2 id="hstore-ops-funcs">
  <title><type>hstore</type> Operators and Functions</title>

  <para>
   The operators provided by the <literal>hstore</literal> module are
   shown in <xref linkend="hstore-op-table"/>, the functions
   in <xref linkend="hstore-func-table"/>.
  </para>

  <table id="hstore-op-table">
   <title><type>hstore</type> Operators</title>
    <tgroup cols="1">
     <thead>
      <row>
       <entry role="func_table_entry"><para role="func_signature">
        Operator
       </para>
       <para>
        Description
       </para>
       <para>
        Example(s)
       </para></entry>
      </row>
     </thead>

     <tbody>
      <row>
       <entry role="func_table_entry"><para role="func_signature">
        <type>hstore</type> <literal>-&gt;</literal> <type>text</type>
        <returnvalue>text</returnvalue>
       </para>
       <para>
        Returns value associated with given key, or <literal>NULL</literal> if
        not present.