diff options
Diffstat (limited to 'doc/src/sgml/func.sgml')
| -rw-r--r-- | doc/src/sgml/func.sgml | 242 |
1 files changed, 63 insertions, 179 deletions
diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml index b405525a465..810b2b50f0d 100644 --- a/doc/src/sgml/func.sgml +++ b/doc/src/sgml/func.sgml @@ -1824,13 +1824,23 @@ SELECT NOT(ROW(table.*) IS NOT NULL) FROM TABLE; -- detect at least one null in which <parameter>operand</parameter> falls in a histogram having <parameter>count</parameter> equal-width buckets spanning the range <parameter>low</parameter> to <parameter>high</parameter>. - Returns <literal>0</literal> + The buckets have inclusive lower bounds and exclusive upper bounds. + Returns <literal>0</literal> for an input less + than <parameter>low</parameter>, or <literal><parameter>count</parameter>+1</literal> for an input - outside that range. + greater than or equal to <parameter>high</parameter>. + If <parameter>low</parameter> > <parameter>high</parameter>, + the behavior is mirror-reversed, with bucket <literal>1</literal> + now being the one just below <parameter>low</parameter>, and the + inclusive bounds now being on the upper side. </para> <para> <literal>width_bucket(5.35, 0.024, 10.06, 5)</literal> <returnvalue>3</returnvalue> + </para> + <para> + <literal>width_bucket(9, 10, 0, 10)</literal> + <returnvalue>2</returnvalue> </para></entry> </row> @@ -1842,8 +1852,8 @@ SELECT NOT(ROW(table.*) IS NOT NULL) FROM TABLE; -- detect at least one null in <para> Returns the number of the bucket in which <parameter>operand</parameter> falls given an array listing the - lower bounds of the buckets. Returns <literal>0</literal> for an - input less than the first lower + inclusive lower bounds of the buckets. + Returns <literal>0</literal> for an input less than the first lower bound. <parameter>operand</parameter> and the array elements can be of any type having standard comparison operators. The <parameter>thresholds</parameter> array <emphasis>must be @@ -14374,7 +14384,7 @@ CREATE TYPE rainbow AS ENUM ('red', 'orange', 'yellow', 'green', 'blue', 'purple <sect1 id="functions-uuid"> <title>UUID Functions</title> - <indexterm zone="datatype-uuid"> + <indexterm zone="functions-uuid"> <primary>UUID</primary> <secondary>generating</secondary> </indexterm> @@ -26743,6 +26753,23 @@ SELECT currval(pg_get_serial_sequence('sometable', 'id')); <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> + <primary>to_regdatabase</primary> + </indexterm> + <function>to_regdatabase</function> ( <type>text</type> ) + <returnvalue>regdatabase</returnvalue> + </para> + <para> + Translates a textual database name to its OID. A similar result is + obtained by casting the string to type <type>regdatabase</type> (see + <xref linkend="datatype-oid"/>); however, this function will return + <literal>NULL</literal> rather than throwing an error if the name is + not found. + </para></entry> + </row> + + <row> + <entry role="func_table_entry"><para role="func_signature"> + <indexterm> <primary>to_regcollation</primary> </indexterm> <function>to_regcollation</function> ( <type>text</type> ) @@ -27677,6 +27704,31 @@ acl | {postgres=arwdDxtm/postgres,foo=r/postgres} details. </para></entry> </row> + + <row> + <entry role="func_table_entry"><para role="func_signature"> + <indexterm> + <primary>pg_get_multixact_members</primary> + </indexterm> + <function>pg_get_multixact_members</function> ( <parameter>multixid</parameter> <type>xid</type> ) + <returnvalue>setof record</returnvalue> + ( <parameter>xid</parameter> <type>xid</type>, + <parameter>mode</parameter> <type>text</type> ) + </para> + <para> + Returns the transaction ID and lock mode for each member of the + specified multixact ID. The lock modes <literal>forupd</literal>, + <literal>fornokeyupd</literal>, <literal>sh</literal>, and + <literal>keysh</literal> correspond to the row-level locks + <literal>FOR UPDATE</literal>, <literal>FOR NO KEY UPDATE</literal>, + <literal>FOR SHARE</literal>, and <literal>FOR KEY SHARE</literal>, + respectively, as described in <xref linkend="locking-rows"/>. Two + additional modes are specific to multixacts: + <literal>nokeyupd</literal>, used by updates that do not modify key + columns, and <literal>upd</literal>, used by updates or deletes that + modify key columns. + </para></entry> + </row> </tbody> </tgroup> </table> @@ -27685,7 +27737,8 @@ acl | {postgres=arwdDxtm/postgres,foo=r/postgres} The internal transaction ID type <type>xid</type> is 32 bits wide and wraps around every 4 billion transactions. However, the functions shown in <xref linkend="functions-pg-snapshot"/>, except - <function>age</function> and <function>mxid_age</function>, use a + <function>age</function>, <function>mxid_age</function>, and + <function>pg_get_multixact_members</function>, use a 64-bit type <type>xid8</type> that does not wrap around during the life of an installation and can be converted to <type>xid</type> by casting if required; see <xref linkend="transaction-id"/> for details. @@ -28666,143 +28719,6 @@ acl | {postgres=arwdDxtm/postgres,foo=r/postgres} <row> <entry role="func_table_entry"><para role="func_signature"> <indexterm> - <primary>pg_get_process_memory_contexts</primary> - </indexterm> - <function>pg_get_process_memory_contexts</function> ( <parameter>pid</parameter> <type>integer</type>, <parameter>summary</parameter> <type>boolean</type>, <parameter>timeout</parameter> <type>float</type> ) - <returnvalue>setof record</returnvalue> - ( <parameter>name</parameter> <type>text</type>, - <parameter>ident</parameter> <type>text</type>, - <parameter>type</parameter> <type>text</type>, - <parameter>path</parameter> <type>integer[]</type>, - <parameter>level</parameter> <type>integer</type>, - <parameter>total_bytes</parameter> <type>bigint</type>, - <parameter>total_nblocks</parameter> <type>bigint</type>, - <parameter>free_bytes</parameter> <type>bigint</type>, - <parameter>free_chunks</parameter> <type>bigint</type>, - <parameter>used_bytes</parameter> <type>bigint</type>, - <parameter>num_agg_contexts</parameter> <type>integer</type>, - <parameter>stats_timestamp</parameter> <type>timestamptz</type> ) - </para> - <para> - This function handles requests to display the memory contexts of a - <productname>PostgreSQL</productname> process with the specified - process ID. The function can be used to send requests to backends as - well as <glossterm linkend="glossary-auxiliary-proc">auxiliary processes</glossterm>. - </para> - <para> - The returned record contains extended statistics per each memory - context: - <itemizedlist spacing="compact"> - <listitem> - <para> - <parameter>name</parameter> - The name of the memory context. - </para> - </listitem> - <listitem> - <para> - <parameter>ident</parameter> - Memory context ID (if any). - </para> - </listitem> - <listitem> - <para> - <parameter>type</parameter> - The type of memory context, possible - values are: AllocSet, Generation, Slab and Bump. - </para> - </listitem> - <listitem> - <para> - <parameter>path</parameter> - Memory contexts are organized in a - tree model with TopMemoryContext as the root, and all other memory - contexts as nodes in the tree. The <parameter>path</parameter> - displays the path from the root to the current memory context. The - path is limited to 100 children per node, which each node limited - to a max depth of 100, to preserve memory during reporting. The - printed path will also be limited to 100 nodes counting from the - TopMemoryContext. - </para> - </listitem> - <listitem> - <para> - <parameter>level</parameter> - The level in the tree of the current - memory context. - </para> - </listitem> - <listitem> - <para> - <parameter>total_bytes</parameter> - The total number of bytes - allocated to this memory context. - </para> - </listitem> - <listitem> - <para> - <parameter>total_nblocks</parameter> - The total number of blocks - used for the allocated memory. - </para> - </listitem> - <listitem> - <para> - <parameter>free_bytes</parameter> - The amount of free memory in - this memory context. - </para> - </listitem> - <listitem> - <para> - <parameter>free_chunks</parameter> - The number of chunks that - <parameter>free_bytes</parameter> corresponds to. - </para> - </listitem> - <listitem> - <para> - <parameter>used_bytes</parameter> - The total number of bytes - currently occupied. - </para> - </listitem> - <listitem> - <para> - <parameter>num_agg_contexts</parameter> - The number of memory - contexts aggregated in the displayed statistics. - </para> - </listitem> - <listitem> - <para> - <parameter>stats_timestamp</parameter> - When the statistics were - extracted from the process. - </para> - </listitem> - </itemizedlist> - </para> - <para> - When <parameter>summary</parameter> is <literal>true</literal>, statistics - for memory contexts at levels 1 and 2 are displayed, with level 1 - representing the root node (i.e., <literal>TopMemoryContext</literal>). - Statistics for contexts on level 2 and below are aggregates of all - child contexts' statistics, where <literal>num_agg_contexts</literal> - indicate the number aggregated child contexts. When - <parameter>summary</parameter> is <literal>false</literal>, - <literal>the num_agg_contexts</literal> value is <literal>1</literal>, - indicating that individual statistics are being displayed. - </para> - <para> - Busy processes can delay reporting memory context statistics, - <parameter>timeout</parameter> specifies the number of seconds - to wait for updated statistics. <parameter>timeout</parameter> can be - specified in fractions of a second. - </para> - <para> - After receiving memory context statistics from the target process, it - returns the results as one row per context. If all the contexts don't - fit within the pre-determined size limit, the remaining context - statistics are aggregated and a cumulative total is displayed. The - <literal>num_agg_contexts</literal> column indicates the number of - contexts aggregated in the displayed statistics. When - <literal>num_agg_contexts</literal> is <literal>1</literal> it means - that the context statistics are displayed separately. - </para></entry> - </row> - - <row> - <entry role="func_table_entry"><para role="func_signature"> - <indexterm> <primary>pg_log_backend_memory_contexts</primary> </indexterm> <function>pg_log_backend_memory_contexts</function> ( <parameter>pid</parameter> <type>integer</type> ) @@ -28939,40 +28855,6 @@ LOG: Grand total: 1651920 bytes in 201 blocks; 622360 free (88 chunks); 1029560 because it may generate a large number of log messages. </para> - <para> - <function>pg_get_process_memory_contexts</function> can be used to request - memory contexts statistics of any <productname>PostgreSQL</productname> - process. For example: -<programlisting> -postgres=# SELECT * FROM pg_get_process_memory_contexts( - (SELECT pid FROM pg_stat_activity - WHERE backend_type = 'checkpointer'), - false, 0.5) LIMIT 1; --[ RECORD 1 ]----+------------------------------ -name | TopMemoryContext -ident | -type | AllocSet -path | {1} -level | 1 -total_bytes | 90304 -total_nblocks | 3 -free_bytes | 2880 -free_chunks | 1 -used_bytes | 87424 -num_agg_contexts | 1 -stats_timestamp | 2025-03-24 13:55:47.796698+01 -</programlisting> - <note> - <para> - While <function>pg_get_process_memory_contexts</function> can be used to - query memory contexts of the local backend, - <structname>pg_backend_memory_contexts</structname> - (see <xref linkend="view-pg-backend-memory-contexts"/> for more details) - will be less resource intensive when only the local backend is of interest. - </para> - </note> - </para> - </sect2> <sect2 id="functions-admin-backup"> @@ -29869,7 +29751,7 @@ postgres=# SELECT '0/0'::pg_lsn + pd.segment_number * ps.setting::int + :offset </row> <row> - <entry role="func_table_entry"><para role="func_signature"> + <entry id="pg-logical-slot-get-binary-changes" role="func_table_entry"><para role="func_signature"> <indexterm> <primary>pg_logical_slot_get_binary_changes</primary> </indexterm> @@ -30141,7 +30023,9 @@ postgres=# SELECT '0/0'::pg_lsn + pd.segment_number * ps.setting::int + :offset standby server. Temporary synced slots, if any, cannot be used for logical decoding and must be dropped after promotion. See <xref linkend="logicaldecoding-replication-slots-synchronization"/> for details. - Note that this function cannot be executed if + Note that this function is primarily intended for testing and + debugging purposes and should be used with caution. Additionally, + this function cannot be executed if <link linkend="guc-sync-replication-slots"><varname> sync_replication_slots</varname></link> is enabled and the slotsync worker is already running to perform the synchronization of slots. |