<secondary>in configuration file</secondary>

</indexterm>

The <filename>postgresql.conf</> file can also contain

<firstterm>include_dir directives</>, which specify an entire directory

<literal>include_dir</literal> directives, which specify an entire directory

of configuration files to include. It is used similarly:

<programlisting>

include_dir 'directory'

names end with the suffix <literal>.conf</literal> will be included. File

names that start with the <literal>.</literal> character are also excluded,

to prevent mistakes as they are hidden on some platforms. Multiple files

within an include directory are processed infilenameorder. Thefilenames

within an include directory are processed infile nameorder. Thefile names

are ordered by C locale rules, ie. numbers before letters, and uppercase

letters before lowercase ones.

</para>

Specifies the maximum amount of disk space that a session can use

for temporary files, such as sort and hash temporary files, or the

storage file for a held cursor. A transaction attempting to exceed

this limit will becancelled.

this limit will becanceled.

The value is specified in kilobytes, and <literal>-1</> (the

default) means no limit.

Only superusers can change this setting.

<para>

When <varname>logging_collector</varname> is enabled,

this parameter sets the file names of the created log files. The value

is treated as a <systemitem>strftime</systemitem> pattern,

is treated as a <function>strftime</function> pattern,

so <literal>%</literal>-escapes can be used to specify time-varying

file names. (Note that if there are

any time-zone-dependent <literal>%</literal>-escapes, the computation

representations of XML values, such as in the above examples.

This would ordinarily mean that encoding declarations contained in

XML data can become invalid as the character data is converted

to other encodings whiletravelling between client and server,

to other encodings whiletraveling between client and server,

because the embedded encoding declaration is not changed. To cope

with this behavior, encoding declarations contained in

character strings presented for input to the <type>xml</type> type

query has a <literal>RETURNING</> clause. Hence, the FDW could choose

to optimize away returning some or all columns depending on the contents

of the <literal>RETURNING</> clause. However, some slot must be

returned to indicate success, or the query's reportedrowcount will be

returned to indicate success, or the query's reportedrow count will be

wrong.

</para>

query has a <literal>RETURNING</> clause. Hence, the FDW could choose

to optimize away returning some or all columns depending on the contents

of the <literal>RETURNING</> clause. However, some slot must be

returned to indicate success, or the query's reportedrowcount will be

returned to indicate success, or the query's reportedrow count will be

wrong.

</para>

query has a <literal>RETURNING</> clause. Hence, the FDW could choose

to optimize away returning some or all columns depending on the contents

of the <literal>RETURNING</> clause. However, some slot must be

returned to indicate success, or the query's reportedrowcount will be

returned to indicate success, or the query's reportedrow count will be

wrong.

</para>

</indexterm>

<literal>array_to_json(anyarray [, pretty_bool])</literal>

</entry>

<entry>json</entry>

<entry><type>json</type></entry>

<entry>

Returns the array as JSON. A PostgreSQL multidimensional array

becomes a JSON array of arrays. Line feeds will be added between

</indexterm>

<literal>row_to_json(record [, pretty_bool])</literal>

</entry>

<entry>json</entry>

<entry><type>json</type></entry>

<entry>

Returns the row as JSON. Line feeds will be added between level

1 elements if <parameter>pretty_bool</parameter> is true.

</indexterm>

<literal>to_json(anyelement)</literal>

</entry>

<entry>json</entry>

<entry><type>json</type></entry>

<entry>

Returns the value as JSON. If the data type is notbuiltin, and there

is a cast from the type to json, the cast function will be used to

Returns the value as JSON. If the data type is notbuilt in, and there

is a cast from the type to<type>json</type>, the cast function will be used to

perform the conversion. Otherwise, for any value other than a number,

aboolean orNULL, the text representation will be used, escaped and

aBoolean, ora null value, the text representation will be used, escaped and

quoted so that it is legal JSON.

</entry>

<entry><literal>to_json('Fred said "Hi."'::text)</literal></entry>

</indexterm>

<literal>json_array_length(json)</literal>

</entry>

<entry>int</entry>

<entry><type>int</type></entry>

<entry>

Returns the number of elements in the outermostjson array.

Returns the number of elements in the outermostJSON array.

</entry>

<entry><literal>json_array_length('[1,2,3,{"f1":1,"f2":[5,6]},4]')</literal></entry>

<entry><literal>5</literal></entry>

</indexterm>

<literal>json_each(json)</literal>

</entry>

<entry>SETOF key text, value json</entry>

<entry><type>SETOF key text, value json</type></entry>

<entry>

Expands the outermostjson object into a set of key/value pairs.

Expands the outermostJSON object into a set of key/value pairs.

</entry>

<entry><literal>select * from json_each('{"a":"foo", "b":"bar"}')</literal></entry>

<entry>

</indexterm>

<literal>json_each_text(from_json json)</literal>

</entry>

<entry>SETOF key text, value text</entry>

<entry><type>SETOF key text, value text</type></entry>

<entry>

Expands the outermostjson object into a set of key/value pairs. The

Expands the outermostJSON object into a set of key/value pairs. The

returned value will be of type text.

</entry>

<entry><literal>select * from json_each_text('{"a":"foo", "b":"bar"}')</literal></entry>

</indexterm>

<literal>json_extract_path(from_json json, VARIADIC path_elems text[])</literal>

</entry>

<entry>json</entry>

<entry><type>json</type></entry>

<entry>

Returnsjson object pointed to by <parameter>path_elems</parameter>.

ReturnsJSON object pointed to by <parameter>path_elems</parameter>.

</entry>

<entry><literal>json_extract_path('{"f2":{"f3":1},"f4":{"f5":99,"f6":"foo"}}','f4')</literal></entry>

<entry><literal>{"f5":99,"f6":"foo"}</literal></entry>

</indexterm>

<literal>json_extract_path_text(from_json json, VARIADIC path_elems text[])</literal>

</entry>

<entry>text</entry>

<entry><type>text</type></entry>

<entry>

Returnsjson object pointed to by <parameter>path_elems</parameter>.

ReturnsJSON object pointed to by <parameter>path_elems</parameter>.

</entry>

<entry><literal>json_extract_path_text('{"f2":{"f3":1},"f4":{"f5":99,"f6":"foo"}}','f4', 'f6')</literal></entry>

<entry><literal>foo</literal></entry>

</indexterm>

<literal>json_object_keys(json)</literal>

</entry>

<entry>SETOF text</entry>

<entry><type>SETOF text</type></entry>

<entry>

Returns set of keys in thejson object. Only the"outer" object will be displayed.

Returns set of keys in theJSON object. Only the<quote>outer</quote> object will be displayed.

</entry>

<entry><literal>json_object_keys('{"f1":"abc","f2":{"f3":"a", "f4":"b"}}')</literal></entry>

<entry>

</indexterm>

<literal>json_populate_record(base anyelement, from_json json, [, use_json_as_text bool=false]</literal>

</entry>

<entry>anyelement</entry>

<entry><type>anyelement</type></entry>

<entry>

Expands the object in from_json to a row whose columns match

Expands the object in<replaceable>from_json</replaceable> to a row whose columns match

the record type defined by base. Conversion will be best

effort; columns in base with no corresponding key in from_json

effort; columns in base with no corresponding key in<replaceable>from_json</replaceable>

will be left null. A column may only be specified once.

</entry>

<entry><literal>select * from json_populate_record(null::x, '{"a":1,"b":2}')</literal></entry>

</indexterm>

<literal>json_populate_recordset(base anyelement, from_json json, [, use_json_as_text bool=false]</literal>

</entry>

<entry>SETOF anyelement</entry>

<entry><type>SETOF anyelement</type></entry>

<entry>

Expands the outermost set of objects in from_json to a set

Expands the outermost set of objects in<replaceable>from_json</replaceable> to a set

whose columns match the record type defined by base.

Conversion will be best effort; columns in base with no

corresponding key in from_json will be left null. A column

corresponding key in<replaceable>from_json</replaceable> will be left null. A column

may only be specified once.

</entry>

<entry><literal>select * from json_populate_recordset(null::x, '[{"a":1,"b":2},{"a":3,"b":4}]')</literal></entry>

</indexterm>

<literal>json_array_elements(json)</literal>

</entry>

<entry>SETOF json</entry>

<entry><type>SETOF json</type></entry>

<entry>

Expands ajson array to a set ofjson elements.

Expands aJSON array to a set ofJSON elements.

</entry>

<entry><literal>json_array_elements('[1,true, [2,false]]')</literal></entry>

<entry>

<note>

<para>

The <xref linkend="hstore"> extension has a cast from hstore to

json, so that converted hstore values are represented asjson objects,

The <xref linkend="hstore"> extension has a cast from<type>hstore</type> to

<type>json</type>, so that converted<type>hstore</type> values are represented asJSON objects,

not as string values.

</para>

</note>

<para>

See also <xref linkend="functions-aggregate"> about the aggregate

function <function>json_agg</function> which aggregates record

values asjson efficiently.

values asJSON efficiently.

</para>

</sect1>

<entry>

<type>json</type>

</entry>

<entry>aggregates records as ajson array of objects</entry>

<entry>aggregates records as aJSON array of objects</entry>

</row>

<row>

</sect2>

<sect2 id="functions-admin-signal">

<title>ServerSignalling Functions</title>

<title>ServerSignaling Functions</title>

<indexterm>

<primary>pg_cancel_backend</primary>

</para>

<table id="functions-admin-signal-table">

<title>ServerSignalling Functions</title>

<title>ServerSignaling Functions</title>

<tgroup cols="3">

<thead>

<row><entry>Name</entry> <entry>Return Type</entry> <entry>Description</entry>

Returns a palloc'd array of keys given an item to be indexed. The

number of returned keys must be stored into <literal>*nkeys</>.

If any of the keys can be null, also palloc an array of

<literal>*nkeys</>booleans, store its address at

<literal>*nkeys</><type>bool</type> fields, store its address at

<literal>*nullFlags</>, and set these null flags as needed.

<literal>*nullFlags</> can be left <symbol>NULL</symbol> (its initial value)

if all keys are non-null.

<literal>query</> and the method it should use to extract key values.

The number of returned keys must be stored into <literal>*nkeys</>.

If any of the keys can be null, also palloc an array of

<literal>*nkeys</>booleans, store its address at

<literal>*nkeys</><type>bool</type> fields, store its address at

<literal>*nullFlags</>, and set these null flags as needed.

<literal>*nullFlags</> can be left NULL (its initial value)

<literal>*nullFlags</> can be left<symbol>NULL</symbol> (its initial value)

if all keys are non-null.

The return value can be NULL if the <literal>query</> contains no keys.

The return value can be<symbol>NULL</symbol> if the <literal>query</> contains no keys.

</para>

<para>

an array of <literal>*nkeys</> booleans and store its address at

<literal>*pmatch</>. Each element of the array should be set to TRUE

if the corresponding key requires partial match, FALSE if not.

If <literal>*pmatch</> is set to NULL then GIN assumes partial match

is not required. The variable is initialized to NULL before call,

If <literal>*pmatch</> is set to<symbol>NULL</symbol> then GIN assumes partial match

is not required. The variable is initialized to<symbol>NULL</symbol> before call,

so this argument can simply be ignored by operator classes that do

not support partial match.

</para>

To use it, <function>extractQuery</> must allocate

an array of <literal>*nkeys</> Pointers and store its address at

<literal>*extra_data</>, then store whatever it wants to into the

individual pointers. The variable is initialized to NULL before

individual pointers. The variable is initialized to<symbol>NULL</symbol> before

call, so this argument can simply be ignored by operator classes that

do not require extra data. If <literal>*extra_data</> is set, the

whole array is passed to the <function>consistent</> method, and

and so are the <literal>queryKeys[]</> and <literal>nullFlags[]</>

arrays previously returned by <function>extractQuery</>.

<literal>extra_data</> is the extra-data array returned by

<function>extractQuery</>, or NULL if none.

<function>extractQuery</>, or<symbol>NULL</symbol> if none.

</para>

<para>

that generated the partial match query is provided, in case its

semantics are needed to determine when to end the scan. Also,

<literal>extra_data</> is the corresponding element of the extra-data

array made by <function>extractQuery</>, or NULL if none.

array made by <function>extractQuery</>, or<symbol>NULL</symbol> if none.

Null keys are never passed to this function.

</para>

</listitem>

</para>

<para>

As of <productname>PostgreSQL</productname> 9.1,NULL key values can be

included in the index. Also, placeholderNULLs are included in the index

for indexed items that areNULL or contain no keys according to

As of <productname>PostgreSQL</productname> 9.1,null key values can be

included in the index. Also, placeholdernulls are included in the index

for indexed items that arenull or contain no keys according to

<function>extractValue</>. This allows searches that should find empty

items to do so.

</para>

<para>

<acronym>GIN</acronym> assumes that indexable operators are strict. This

means that <function>extractValue</> will not be called at all on aNULL

means that <function>extractValue</> will not be called at all on anull

item value (instead, a placeholder index entry is created automatically),

and <function>extractQuery</function> will not be called on aNULL query

and <function>extractQuery</function> will not be called on anull query

value either (instead, the query is presumed to be unsatisfiable). Note

however thatNULL key values contained within a non-null composite item

however thatnull key values contained within a non-null composite item

or query value are supported.

</para>

</sect1>

<row>

<entry><function>hstore_to_json(hstore)</function></entry>

<entry><type>json</type></entry>

<entry>get <type>hstore</type> as a json value</entry>

<entry>get <type>hstore</type> as a<type>json</type> value</entry>

<entry><literal>hstore_to_json('"a key"=&gt;1, b=&gt;t, c=&gt;null, d=&gt;12345, e=&gt;012345, f=&gt;1.234, g=&gt;2.345e+4')</literal></entry>

<entry><literal>{"a key": "1", "b": "t", "c": null, "d": "12345", "e": "012345", "f": "1.234", "g": "2.345e+4"}</literal></entry>

</row>

<row>

<entry><function>hstore_to_json_loose(hstore)</function></entry>

<entry><type>json</type></entry>

<entry>get <type>hstore</type> as a json value, but attempting to distinguish numerical andboolean values so they are unquoted in thejson</entry>

<entry>get <type>hstore</type> as a<type>json</type> value, but attempting to distinguish numerical andBoolean values so they are unquoted in theJSON</entry>

<entry><literal>hstore_to_json_loose('"a key"=&gt;1, b=&gt;t, c=&gt;null, d=&gt;12345, e=&gt;012345, f=&gt;1.234, g=&gt;2.345e+4')</literal></entry>

<entry><literal>{"a key": 1, "b": true, "c": null, "d": 12345, "e": "012345", "f": 1.234, "g": 2.345e+4}</literal></entry>

</row>

<structfield>amoptionalkey</structfield> false.

One reason that an index AM might set

<structfield>amoptionalkey</structfield> false is if it doesn't index

NULLs. Since most indexable operators are

strict and hence cannot returnTRUE forNULL inputs,

null values. Since most indexable operators are

strict and hence cannot returntrue fornull inputs,

it is at first sight attractive to not store index entries for null values:

they could never be returned by an index scan anyway. However, this

argument fails when an index scan has no restriction clause for a given

information schema is defined in the SQL standard and can therefore

be expected to be portable and remain stable &mdash; unlike the system

catalogs, which are specific to

<productname>PostgreSQL</productname> and aremodelled after

<productname>PostgreSQL</productname> and aremodeled after

implementation concerns. The information schema views do not,

however, contain information about

<productname>PostgreSQL</productname>-specific features; to inquire