diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml index c46a8f452e..2dd99d33ff 100644 --- a/doc/src/sgml/func.sgml +++ b/doc/src/sgml/func.sgml @@ -1,4 +1,4 @@ - + Functions and Operators @@ -2375,6 +2375,32 @@ \\Post'gres\000 + + get_bit(string, offset) + int + + Extract bit from string + + get_bit + + + get_bit('Th\\000omas'::bytea, 45) + 1 + + + + get_byte(string, offset) + int + + Extract byte from string + + get_byte + + + get_byte('Th\\000omas'::bytea, 4) + 109 + + octet_length(string) int @@ -2391,6 +2417,34 @@ 3 + + set_bit(string, + offset, newvalue) + bytea + + Set bit in string + + set_bit + + + set_bit('Th\\000omas'::bytea, 45, 0) + Th\000omAs + + + + set_byte(string, + offset, newvalue) + bytea + + Set byte in string + + set_byte + + + set_byte('Th\\000omas'::bytea, 4, 64) + Th\000o@as + + substring(string from int for int) bytea @@ -2419,60 +2473,6 @@ trim('\\000'::bytea from '\\000Tom\\000'::bytea) Tom - - - get_byte(string, offset) - int - - Extract byte from string - - get_byte - - - get_byte('Th\\000omas'::bytea, 4) - 109 - - - - set_byte(string, - offset, newvalue) - bytea - - Set byte in string - - set_byte - - - set_byte('Th\\000omas'::bytea, 4, 64) - Th\000o@as - - - - get_bit(string, offset) - int - - Extract bit from string - - get_bit - - - get_bit('Th\\000omas'::bytea, 45) - 1 - - - - set_bit(string, - offset, newvalue) - bytea - - Set bit in string - - set_bit - - - set_bit('Th\\000omas'::bytea, 45, 0) - Th\000omAs - @@ -2512,6 +2512,34 @@ trim + + + decode(string text, + type text) + + bytea + + Decode binary string from string previously + encoded with encode. Parameter type is same as in encode. + + decode('123\\000456', 'escape') + 123\000456 + + + + + encode(string bytea, + type text) + + text + + Encode binary string to ASCII-only representation. Supported + types are: base64, hex, escape. + + encode('123\\000456'::bytea, 'escape') + 123\000456 + + length(string) int @@ -2541,35 +2569,6 @@ md5('Th\\000omas'::bytea) 8ab2d3c9689aaf18 b4958c334c82d8b1 - - - - decode(string text, - type text) - - bytea - - Decode binary string from string previously - encoded with encode. Parameter type is same as in encode. - - decode('123\\000456', 'escape') - 123\000456 - - - - - encode(string bytea, - type text) - - text - - Encode binary string to ASCII-only representation. Supported - types are: base64, hex, escape. - - encode('123\\000456'::bytea, 'escape') - 123\000456 - - @@ -4321,10 +4320,10 @@ SELECT SUBSTRING('XY1234Z', 'Y*?([0-9]{1,3})'); to_date - to_timestamp + to_number - to_number + to_timestamp @@ -4394,6 +4393,12 @@ SELECT SUBSTRING('XY1234Z', 'Y*?([0-9]{1,3})'); convert string to date to_date('05 Dec 2000', 'DD Mon YYYY') + + to_number(text, text) + numeric + convert string to numeric + to_number('12,454.8-', '99G999D9S') + to_timestamp(text, text) timestamp with time zone @@ -4406,12 +4411,6 @@ SELECT SUBSTRING('XY1234Z', 'Y*?([0-9]{1,3})'); convert UNIX epoch to time stamp to_timestamp(200120400) - - to_number(text, text) - numeric - convert string to numeric - to_number('12,454.8-', '99G999D9S') - @@ -5271,6 +5270,9 @@ SELECT SUBSTRING('XY1234Z', 'Y*?([0-9]{1,3})'); age + + clock_timestamp + current_date @@ -5310,17 +5312,14 @@ SELECT SUBSTRING('XY1234Z', 'Y*?([0-9]{1,3})'); now - - transaction_timestamp - statement_timestamp - clock_timestamp + timeofday - timeofday + transaction_timestamp @@ -5354,6 +5353,16 @@ SELECT SUBSTRING('XY1234Z', 'Y*?([0-9]{1,3})'); 43 years 8 mons 3 days + + clock_timestamp() + timestamp with time zone + Current date and time (changes during statement execution); + see + + + + + current_date date @@ -5503,16 +5512,6 @@ SELECT SUBSTRING('XY1234Z', 'Y*?([0-9]{1,3})'); - - transaction_timestamp() - timestamp with time zone - Current date and time (start of current transaction); - see - - - - - statement_timestamp() timestamp with time zone @@ -5523,16 +5522,6 @@ SELECT SUBSTRING('XY1234Z', 'Y*?([0-9]{1,3})'); - - clock_timestamp() - timestamp with time zone - Current date and time (changes during statement execution); - see - - - - - timeofday() text @@ -5544,6 +5533,15 @@ SELECT SUBSTRING('XY1234Z', 'Y*?([0-9]{1,3})'); + + transaction_timestamp() + timestamp with time zone + Current date and time (start of current transaction); + see + + + +
@@ -6944,6 +6942,20 @@ SELECT pg_sleep(1.5); + + abbrev(inet) + text + abbreviated display format as text + abbrev(inet '10.1.0.0/16') + 10.1.0.0/16 + + + abbrev(cidr) + text + abbreviated display format as text + abbrev(cidr '10.1.0.0/16') + 10.1/16 + broadcast(inet) inet @@ -6951,6 +6963,14 @@ SELECT pg_sleep(1.5); broadcast('192.168.1.5/24') 192.168.1.255/24 + + family(inet) + int + extract family of address; 4 for IPv4, + 6 for IPv6 + family('::1') + 6 + host(inet) text @@ -6958,6 +6978,13 @@ SELECT pg_sleep(1.5); host('192.168.1.5/24') 192.168.1.5 + + hostmask(inet) + inet + construct host mask for network + hostmask('192.168.23.20/30') + 0.0.0.3 + masklen(inet) int @@ -6965,6 +6992,20 @@ SELECT pg_sleep(1.5); masklen('192.168.1.5/24') 24 + + netmask(inet) + inet + construct netmask for network + netmask('192.168.1.5/24') + 255.255.255.0 + + + network(inet) + cidr + extract network part of address + network('192.168.1.5/24') + 192.168.1.0/24 + set_masklen(inet, int) inet @@ -6979,27 +7020,6 @@ SELECT pg_sleep(1.5); set_masklen('192.168.1.0/24'::cidr, 16) 192.168.0.0/16 - - netmask(inet) - inet - construct netmask for network - netmask('192.168.1.5/24') - 255.255.255.0 - - - hostmask(inet) - inet - construct host mask for network - hostmask('192.168.23.20/30') - 0.0.0.3 - - - network(inet) - cidr - extract network part of address - network('192.168.1.5/24') - 192.168.1.0/24 - text(inet) text @@ -7007,28 +7027,6 @@ SELECT pg_sleep(1.5); text(inet '192.168.1.5') 192.168.1.5/32 - - abbrev(inet) - text - abbreviated display format as text - abbrev(inet '10.1.0.0/16') - 10.1.0.0/16 - - - abbrev(cidr) - text - abbreviated display format as text - abbrev(cidr '10.1.0.0/16') - 10.1/16 - - - family(inet) - int - extract family of address; 4 for IPv4, - 6 for IPv6 - family('::1') - 6 - @@ -7132,11 +7130,6 @@ SELECT pg_sleep(1.5); - - nextval(regclass) - bigint - Advance sequence and return new value - currval(regclass) bigint @@ -7144,9 +7137,9 @@ SELECT pg_sleep(1.5); nextval for specified sequence - lastval() + nextval(regclass) bigint - Return value most recently obtained with nextval + Advance sequence and return new value setval(regclass, bigint) @@ -7691,18 +7684,6 @@ SELECT NULLIF(value, '(none)') ... - - array_cat - (anyarray, anyarray) - - - anyarray - concatenate two arrays - array_cat(ARRAY[1,2,3], ARRAY[4,5]) - {1,2,3,4,5} - - - array_append (anyarray, anyelement) @@ -7716,14 +7697,14 @@ SELECT NULLIF(value, '(none)') ... - array_prepend - (anyelement, anyarray) + array_cat + (anyarray, anyarray) anyarray - append an element to the beginning of an array - array_prepend(1, ARRAY[2,3]) - {1,2,3} + concatenate two arrays + array_cat(ARRAY[1,2,3], ARRAY[4,5]) + {1,2,3,4,5} @@ -7752,14 +7733,14 @@ SELECT NULLIF(value, '(none)') ... - array_upper - (anyarray, int) + array_prepend + (anyelement, anyarray) - int - returns upper bound of the requested array dimension - array_upper(ARRAY[1,2,3,4], 1) - 4 + anyarray + append an element to the beginning of an array + array_prepend(1, ARRAY[2,3]) + {1,2,3} @@ -7775,6 +7756,18 @@ SELECT NULLIF(value, '(none)') ... + + array_upper + (anyarray, int) + + + int + returns upper bound of the requested array dimension + array_upper(ARRAY[1,2,3,4], 1) + 4 + + + string_to_array (text, text) @@ -8954,18 +8947,18 @@ select current_date + s.a as dates from generate_series(0,14,7) as s(a); port of the local connection - - session_user - name - session user name - - pg_postmaster_start_time() timestamp with time zone server start time + + session_user + name + session user name + + user name @@ -9104,21 +9097,6 @@ SET search_path TO schema , schema, .. - - has_table_privilege(user, - table, - privilege) - - boolean - does user have privilege for table - - - has_table_privilege(table, - privilege) - - boolean - does current user have privilege for table - has_database_privilege(user, database, @@ -9164,21 +9142,6 @@ SET search_path TO schema , schema, .. boolean does current user have privilege for language - - pg_has_role(user, - role, - privilege) - - boolean - does user have privilege for role - - - pg_has_role(role, - privilege) - - boolean - does current user have privilege for role - has_schema_privilege(user, schema, @@ -9194,6 +9157,21 @@ SET search_path TO schema , schema, .. boolean does current user have privilege for schema + + has_table_privilege(user, + table, + privilege) + + boolean + does user have privilege for table + + + has_table_privilege(table, + privilege) + + boolean + does current user have privilege for table + has_tablespace_privilege(user, tablespace, @@ -9209,13 +9187,25 @@ SET search_path TO schema , schema, .. boolean does current user have privilege for tablespace + + pg_has_role(user, + role, + privilege) + + boolean + does user have privilege for role + + + pg_has_role(role, + privilege) + + boolean + does current user have privilege for role + - - has_table_privilege - has_database_privilege @@ -9226,36 +9216,17 @@ SET search_path TO schema , schema, .. has_language_privilege - pg_has_role + has_schema_privilege - has_schema_privilege + has_table_privilege has_tablespace_privilege - - - has_table_privilege checks whether a user - can access a table in a particular way. The user can be - specified by name or by OID - (pg_authid.oid), or if the argument is - omitted - current_user is assumed. The table can be specified - by name or by OID. (Thus, there are actually six variants of - has_table_privilege, which can be distinguished by - the number and types of their arguments.) When specifying by name, - the name can be schema-qualified if necessary. - The desired access privilege type - is specified by a text string, which must evaluate to one of the - values SELECT, INSERT, UPDATE, - DELETE, RULE, REFERENCES, or - TRIGGER. (Case of the string is not significant, however.) - An example is: - -SELECT has_table_privilege('myschema.mytable', 'select'); - - + + pg_has_role + has_database_privilege checks whether a user @@ -9292,19 +9263,6 @@ SELECT has_function_privilege('joeuser', 'myfunc(int, text)', 'execute'); USAGE. - - pg_has_role checks whether a user - can access a role in a particular way. The possibilities for its - arguments are analogous to has_table_privilege. - The desired access privilege type must evaluate to - MEMBER or - USAGE. - MEMBER denotes direct or indirect membership in - the role (that is, the right to do SET ROLE), while - USAGE denotes whether the privileges of the role - are immediately available without doing SET ROLE. - - has_schema_privilege checks whether a user can access a schema in a particular way. The possibilities for its @@ -9314,6 +9272,28 @@ SELECT has_function_privilege('joeuser', 'myfunc(int, text)', 'execute'); USAGE. + + has_table_privilege checks whether a user + can access a table in a particular way. The user can be + specified by name or by OID + (pg_authid.oid), or if the argument is + omitted + current_user is assumed. The table can be specified + by name or by OID. (Thus, there are actually six variants of + has_table_privilege, which can be distinguished by + the number and types of their arguments.) When specifying by name, + the name can be schema-qualified if necessary. + The desired access privilege type + is specified by a text string, which must evaluate to one of the + values SELECT, INSERT, UPDATE, + DELETE, RULE, REFERENCES, or + TRIGGER. (Case of the string is not significant, however.) + An example is: + +SELECT has_table_privilege('myschema.mytable', 'select'); + + + has_tablespace_privilege checks whether a user can access a tablespace in a particular way. The possibilities for its @@ -9322,9 +9302,22 @@ SELECT has_function_privilege('joeuser', 'myfunc(int, text)', 'execute'); CREATE. + + pg_has_role checks whether a user + can access a role in a particular way. The possibilities for its + arguments are analogous to has_table_privilege. + The desired access privilege type must evaluate to + MEMBER or + USAGE. + MEMBER denotes direct or indirect membership in + the role (that is, the right to do SET ROLE), while + USAGE denotes whether the privileges of the role + are immediately available without doing SET ROLE. + + To test whether a user holds a grant option on the privilege, - append WITH GRANT OPTION to the privilege key + append WITH GRANT OPTION to the privilege key word; for example 'UPDATE WITH GRANT OPTION'. @@ -9351,16 +9344,10 @@ SELECT relname FROM pg_class WHERE pg_table_is_visible(oid); - pg_table_is_visible(table_oid) + pg_conversion_is_visible(conversion_oid) boolean - is table visible in search path - - - pg_type_is_visible(type_oid) - - boolean - is type (or domain) visible in search path + is conversion visible in search path pg_function_is_visible(function_oid) @@ -9381,20 +9368,23 @@ SELECT relname FROM pg_class WHERE pg_table_is_visible(oid); is operator class visible in search path - pg_conversion_is_visible(conversion_oid) + pg_table_is_visible(table_oid) boolean - is conversion visible in search path + is table visible in search path + + + pg_type_is_visible(type_oid) + + boolean + is type (or domain) visible in search path - pg_table_is_visible - - - pg_type_is_visible + pg_conversion_is_visible pg_function_is_visible @@ -9406,23 +9396,26 @@ SELECT relname FROM pg_class WHERE pg_table_is_visible(oid); pg_opclass_is_visible - pg_conversion_is_visible + pg_table_is_visible + + + pg_type_is_visible - pg_table_is_visible performs the check for - tables (or views, or any other kind of pg_class entry). - pg_type_is_visible, - pg_function_is_visible, - pg_operator_is_visible, - pg_opclass_is_visible, and - pg_conversion_is_visible perform the same sort of - visibility check for types (and domains), functions, operators, operator classes - and conversions, respectively. For functions and operators, an object in - the search path is visible if there is no object of the same name - and argument data type(s) earlier in the path. For - operator classes, both name and associated index access method are - considered. + pg_conversion_is_visible, + pg_function_is_visible, + pg_operator_is_visible, + pg_opclass_is_visible, + pg_table_is_visible, and + pg_type_is_visible perform the visibility check for + conversions, functions, operators, operator classes, tables, and + types. Note that pg_table_is_visible can also be used + with views, indexes and sequences; pg_type_is_visible + can also be used with domains. For functions and operators, an object in + the search path is visible if there is no object of the same name + and argument data type(s) earlier in the path. For operator + classes, both name and associated index access method are considered. @@ -9545,11 +9538,6 @@ SELECT pg_type_is_visible('myschema.widget'::regtype); get name of the sequence that a serial or bigserial column uses - - pg_tablespace_databases(tablespace_oid) - setof oid - get the set of database OIDs that have objects in the tablespace - pg_get_triggerdef(trigger_oid) text @@ -9580,6 +9568,11 @@ SELECT pg_type_is_visible('myschema.widget'::regtype); text get underlying SELECT command for view + + pg_tablespace_databases(tablespace_oid) + setof oid + get the set of database OIDs that have objects in the tablespace + @@ -9617,6 +9610,11 @@ SELECT pg_type_is_visible('myschema.widget'::regtype); returned if the column does not have an associated sequence. + + pg_get_userbyid extracts a role's name given + its OID. + + pg_tablespace_databases allows a tablespace to be examined. It returns the set of OIDs of databases that have objects stored @@ -9627,17 +9625,12 @@ SELECT pg_type_is_visible('myschema.widget'::regtype); pg_class catalogs. - - pg_get_userbyid extracts a role's name given - its OID. - - - obj_description + col_description - col_description + obj_description @@ -9650,11 +9643,10 @@ SELECT pg_type_is_visible('myschema.widget'::regtype); - The functions shown in extract comments - previously stored with the COMMENT command. A - null value is returned if no comment could be found matching the - specified parameters. + The functions shown in + extract comments previously stored with the command. A null value is returned if no + comment could be found matching the specified parameters. @@ -9665,6 +9657,11 @@ SELECT pg_type_is_visible('myschema.widget'::regtype); + + col_description(table_oid, column_number) + text + get comment for a table column + obj_description(object_oid, catalog_name) text @@ -9675,11 +9672,6 @@ SELECT pg_type_is_visible('myschema.widget'::regtype); text get comment for a database object (deprecated) - - col_description(table_oid, column_number) - text - get comment for a table column - shobj_description(object_oid, catalog_name) text @@ -9689,6 +9681,13 @@ SELECT pg_type_is_visible('myschema.widget'::regtype);
+ + col_description returns the comment for a table column, + which is specified by the OID of its table and its column number. + obj_description cannot be used for table columns since + columns do not have OIDs of their own. + + The two-parameter form of obj_description returns the comment for a database object specified by its OID and the name of the @@ -9701,13 +9700,6 @@ SELECT pg_type_is_visible('myschema.widget'::regtype); comment could be returned. - - col_description returns the comment for a table column, - which is specified by the OID of its table and its column number. - obj_description cannot be used for table columns since - columns do not have OIDs of their own. - - shobj_description is used just like obj_description only that it is used for retrieving @@ -9961,9 +9953,6 @@ SELECT set_config('log_statement_stats', 'off', false); pg_column_size - - pg_tablespace_size - pg_database_size @@ -9971,10 +9960,13 @@ SELECT set_config('log_statement_stats', 'off', false); pg_relation_size - pg_total_relation_size + pg_size_pretty - pg_size_pretty + pg_tablespace_size + + + pg_total_relation_size @@ -9991,20 +9983,6 @@ SELECT set_config('log_statement_stats', 'off', false); intNumber of bytes used to store a particular value (possibly compressed) - - - pg_tablespace_size(oid) - - bigint - Disk space used by the tablespace with the specified OID - - - - pg_tablespace_size(name) - - bigint - Disk space used by the tablespace with the specified name - pg_database_size(oid) @@ -10036,6 +10014,27 @@ SELECT set_config('log_statement_stats', 'off', false); The table name may be qualified with a schema name + + + pg_size_pretty(bigint) + + text + Converts a size in bytes into a human-readable format with size units + + + + pg_tablespace_size(oid) + + bigint + Disk space used by the tablespace with the specified OID + + + + pg_tablespace_size(name) + + bigint + Disk space used by the tablespace with the specified name + pg_total_relation_size(oid) @@ -10057,13 +10056,6 @@ SELECT set_config('log_statement_stats', 'off', false); qualified with a schema name - - - pg_size_pretty(bigint) - - text - Converts a size in bytes into a human-readable format with size units -
@@ -10074,9 +10066,9 @@ SELECT set_config('log_statement_stats', 'off', false); - pg_tablespace_size and pg_database_size accept - the OID or name of a tablespace or database, and return the total disk - space used therein. + pg_database_size and pg_tablespace_size + accept the OID or name of a database or tablespace, and return the total + disk space used therein. @@ -10084,18 +10076,18 @@ SELECT set_config('log_statement_stats', 'off', false); toast table, and returns the size in bytes. - - pg_total_relation_size accepts the OID or name of a - table or toast table, and returns the size in bytes of the data - and all associated indexes and toast tables. - - pg_size_pretty can be used to format the result of one of the other functions in a human-readable way, using kB, MB, GB or TB as appropriate. + + pg_total_relation_size accepts the OID or name of a + table or toast table, and returns the size in bytes of the data + and all associated indexes and toast tables. + + The functions shown in provide native file access to