From b2fd8ebe239f726b99923f827e908a92f6f4f232 Mon Sep 17 00:00:00 2001 From: Tom Lane Date: Thu, 7 May 2020 14:25:18 -0400 Subject: [PATCH] Doc: update remaining tables of functions/operators for new layout. This converts the contrib documentation to the new style, and mops up a couple of function tables that were outside chapter 9 in the main docs. A few contrib modules choose not to present their functions in the standard tabular format. There might be room to rethink those decisions now that the standard format is more friendly to verbose descriptions. But I have not undertaken to do that here; I just converted existing tables. --- doc/src/sgml/adminpack.sgml | 104 ++-- doc/src/sgml/cube.sgml | 610 ++++++++++++---------- doc/src/sgml/earthdistance.sgml | 224 ++++---- doc/src/sgml/hstore.sgml | 839 +++++++++++++++++++---------- doc/src/sgml/intarray.sgml | 469 +++++++++++------ doc/src/sgml/isn.sgml | 89 ++-- doc/src/sgml/lobj.sgml | 133 ++--- doc/src/sgml/ltree.sgml | 606 ++++++++++++--------- doc/src/sgml/monitoring.sgml | 531 ++++++++++++------- doc/src/sgml/pgtrgm.sgml | 411 ++++++++------- doc/src/sgml/ref/pgbench.sgml | 898 ++++++++++++++++++++++---------- doc/src/sgml/seg.sgml | 176 ++++--- doc/src/sgml/sepgsql.sgml | 112 ++-- doc/src/sgml/tablefunc.sgml | 158 +++--- doc/src/sgml/uuid-ossp.sgml | 213 ++++---- doc/src/sgml/xml2.sgml | 236 ++++----- 16 files changed, 3558 insertions(+), 2251 deletions(-) diff --git a/doc/src/sgml/adminpack.sgml b/doc/src/sgml/adminpack.sgml index 977073f7c8d..0dd89be3534 100644 --- a/doc/src/sgml/adminpack.sgml +++ b/doc/src/sgml/adminpack.sgml @@ -29,49 +29,69 @@ <filename>adminpack</filename> Functions - - - Name Return Type Description - - + + + + + Function + + + Description + + + - - - pg_catalog.pg_file_write(filename text, data text, append boolean) - bigint - - Write, or append to, a text file - - - - pg_catalog.pg_file_sync(filename text) - void - - Flush a file or directory to disk - - - - pg_catalog.pg_file_rename(oldname text, newname text , archivename text) - boolean - - Rename a file - - - - pg_catalog.pg_file_unlink(filename text) - boolean - - Remove a file - - - - pg_catalog.pg_logdir_ls() - setof record - - List the log files in the log_directory directory - - - + + + + pg_catalog.pg_file_write ( filename text, data text, append boolean ) + bigint + + + Writes, or appends to, a text file. + + + + + + pg_catalog.pg_file_sync ( filename text ) + void + + + Flushes a file or directory to disk. + + + + + + pg_catalog.pg_file_rename ( oldname text, newname text , archivename text ) + boolean + + + Renames a file. + + + + + + pg_catalog.pg_file_unlink ( filename text ) + boolean + + + Removes a file. + + + + + + pg_catalog.pg_logdir_ls () + setof record + + + Lists the log files in the log_directory directory. + + +
diff --git a/doc/src/sgml/cube.sgml b/doc/src/sgml/cube.sgml index 71772d799fe..70037a193fd 100644 --- a/doc/src/sgml/cube.sgml +++ b/doc/src/sgml/cube.sgml @@ -112,114 +112,113 @@ Usage - shows the operators provided for - type cube. + shows the specialized operators + provided for type cube. Cube Operators - - - - Operator - Result - Description - - + + + + + Operator + + + Description + + + - - - a = b - boolean - The cubes a and b are identical. - + + + + cube && cube + boolean + + + Do the cubes overlap? + + - - a && b - boolean - The cubes a and b overlap. - + + + cube @> cube + boolean + + + Does the first cube contain the second? + + - - a @> b - boolean - The cube a contains the cube b. - + + + cube <@ cube + boolean + + + Is the first cube contained in the second? + + - - a <@ b - boolean - The cube a is contained in the cube b. - + + + cube -> integer + float8 + + + Extracts the n-th coordinate of the cube + (counting from 1). + + - - a < b - boolean - The cube a is less than the cube b. - - - - a <= b - boolean - The cube a is less than or equal to the cube b. - - - - a > b - boolean - The cube a is greater than the cube b. - - - - a >= b - boolean - The cube a is greater than or equal to the cube b. - - - - a <> b - boolean - The cube a is not equal to the cube b. - - - - a -> n - float8 - Get n-th coordinate of cube (counting from 1). - - - - a ~> n - float8 - - Get n-th coordinate of cube in following way: - n = 2 * k - 1 means lower bound of k-th - dimension, n = 2 * k means upper bound of - k-th dimension. Negative - n denotes the inverse value of the corresponding + + + cube ~> integer + float8 + + + Extracts the n-th coordinate of the cube, + counting in the following way: n = 2 + * k - 1 means lower bound + of k-th dimension, n = 2 + * k means upper bound of + k-th dimension. Negative + n denotes the inverse value of the corresponding positive coordinate. This operator is designed for KNN-GiST support. - - + + - - a <-> b - float8 - Euclidean distance between a and b. - + + + cube <-> cube + float8 + + + Computes the Euclidean distance between the two cubes. + + - - a <#> b - float8 - Taxicab (L-1 metric) distance between a and b. - + + + cube <#> cube + float8 + + + Computes the taxicab (L-1 metric) distance between the two cubes. + + - - a <=> b - float8 - Chebyshev (L-inf metric) distance between a and b. - - - + + + cube <=> cube + float8 + + + Computes the Chebyshev (L-inf metric) distance between the two cubes. + + +
@@ -232,12 +231,14 @@ - The scalar ordering operators (<, >=, etc) - do not make a lot of sense for any practical purpose but sorting. These + In addition to the above operators, the usual comparison + operators shown in are + available for type cube. These operators first compare the first coordinates, and if those are equal, compare the second coordinates, etc. They exist mainly to support the b-tree index operator class for cube, which can be useful for example if you would like a UNIQUE constraint on a cube column. + Otherwise, this ordering is not of much practical use. @@ -281,195 +282,262 @@ SELECT c FROM test ORDER BY c ~> 3 DESC LIMIT 5; Cube Functions - - - - Function - Result - Description - Example - - + + + + + Function + + + Description + + + Example(s) + + + - - - cube(float8) - cube - Makes a one dimensional cube with both coordinates the same. - - - cube(1) == '(1)' - - + + + + cube ( float8 ) + cube + + + Makes a one dimensional cube with both coordinates the same. + + + cube(1) + (1) + + - - cube(float8, float8) - cube - Makes a one dimensional cube. - - - cube(1,2) == '(1),(2)' - - + + + cube ( float8, float8 ) + cube + + + Makes a one dimensional cube. + + + cube(1,2) + (1),(2) + + - - cube(float8[]) - cube - Makes a zero-volume cube using the coordinates - defined by the array. - - - cube(ARRAY[1,2]) == '(1,2)' - - + + + cube ( float8[] ) + cube + + + Makes a zero-volume cube using the coordinates defined by the array. + + + cube(ARRAY[1,2,3]) + (1, 2, 3) + + - - cube(float8[], float8[]) - cube - Makes a cube with upper right and lower left - coordinates as defined by the two arrays, which must be of the - same length. - - - cube(ARRAY[1,2], ARRAY[3,4]) == '(1,2),(3,4)' - - - + + + cube ( float8[], float8[] ) + cube + + + Makes a cube with upper right and lower left coordinates as defined by + the two arrays, which must be of the same length. + + + cube(ARRAY[1,2], ARRAY[3,4]) + (1, 2),(3, 4) + + - - cube(cube, float8) - cube - Makes a new cube by adding a dimension on to an existing cube, - with the same values for both endpoints of the new coordinate. This - is useful for building cubes piece by piece from calculated values. - - - cube('(1,2),(3,4)'::cube, 5) == '(1,2,5),(3,4,5)' - - + + + cube ( cube, float8 ) + cube + + + Makes a new cube by adding a dimension on to an existing cube, + with the same values for both endpoints of the new coordinate. This + is useful for building cubes piece by piece from calculated values. + + + cube('(1,2),(3,4)'::cube, 5) + (1, 2, 5),(3, 4, 5) + + - - cube(cube, float8, float8) - cube - Makes a new cube by adding a dimension on to an existing - cube. This is useful for building cubes piece by piece from calculated - values. - - - cube('(1,2),(3,4)'::cube, 5, 6) == '(1,2,5),(3,4,6)' - - + + + cube ( cube, float8, float8 ) + cube + + + Makes a new cube by adding a dimension on to an existing cube. This is + useful for building cubes piece by piece from calculated values. + + + cube('(1,2),(3,4)'::cube, 5, 6) + (1, 2, 5),(3, 4, 6) + + - - cube_dim(cube) - integer - Returns the number of dimensions of the cube. - - - cube_dim('(1,2),(3,4)') == '2' - - + + + cube_dim ( cube ) + integer + + + Returns the number of dimensions of the cube. + + + cube_dim('(1,2),(3,4)') + 2 + + - - cube_ll_coord(cube, integer) - float8 - Returns the n-th coordinate value for the lower - left corner of the cube. - - - cube_ll_coord('(1,2),(3,4)', 2) == '2' - - + + + cube_ll_coord ( cube, integer ) + float8 + + + Returns the n-th coordinate value for the lower + left corner of the cube. + + + cube_ll_coord('(1,2),(3,4)', 2) + 2 + + - - cube_ur_coord(cube, integer) - float8 - Returns the n-th coordinate value for the - upper right corner of the cube. - - - cube_ur_coord('(1,2),(3,4)', 2) == '4' - - + + + cube_ur_coord ( cube, integer ) + float8 + + + Returns the n-th coordinate value for the + upper right corner of the cube. + + + cube_ur_coord('(1,2),(3,4)', 2) + 4 + + - - cube_is_point(cube) - boolean - Returns true if the cube is a point, that is, - the two defining corners are the same. - - - + + + cube_is_point ( cube ) + boolean + + + Returns true if the cube is a point, that is, + the two defining corners are the same. + + + cube_is_point(cube(1,1)) + t + + - - cube_distance(cube, cube) - float8 - Returns the distance between two cubes. If both - cubes are points, this is the normal distance function. - - - - + + + cube_distance ( cube, cube ) + float8 + + + Returns the distance between two cubes. If both + cubes are points, this is the normal distance function. + + + cube_distance('(1,2)', '(3,4)') + 2.8284271247461903 + + - - cube_subset(cube, integer[]) - cube - Makes a new cube from an existing cube, using a list of - dimension indexes from an array. Can be used to extract the endpoints - of a single dimension, or to drop dimensions, or to reorder them as - desired. - - - cube_subset(cube('(1,3,5),(6,7,8)'), ARRAY[2]) == '(3),(7)' - cube_subset(cube('(1,3,5),(6,7,8)'), ARRAY[3,2,1,1]) == - '(5,3,1,1),(8,7,6,6)' - - + + + cube_subset ( cube, integer[] ) + cube + + + Makes a new cube from an existing cube, using a list of + dimension indexes from an array. Can be used to extract the endpoints + of a single dimension, or to drop dimensions, or to reorder them as + desired. + + + cube_subset(cube('(1,3,5),(6,7,8)'), ARRAY[2]) + (3),(7) + + + cube_subset(cube('(1,3,5),(6,7,8)'), ARRAY[3,2,1,1]) + (5, 3, 1, 1),(8, 7, 6, 6) + + - - cube_union(cube, cube) - cube - Produces the union of two cubes. - - - - + + + cube_union ( cube, cube ) + cube + + + Produces the union of two cubes. + + + cube_union('(1,2)', '(3,4)') + (1, 2),(3, 4) + + - - cube_inter(cube, cube) - cube - Produces the intersection of two cubes. - - - - + + + cube_inter ( cube, cube ) + cube + + + Produces the intersection of two cubes. + + + cube_inter('(1,2)', '(3,4)') + (3, 4),(1, 2) + + - - cube_enlarge(c cube, r double, n integer) - cube - Increases the size of the cube by the specified - radius r in at least n dimensions. - If the radius is negative the cube is shrunk instead. - All defined dimensions are changed by the radius r. - Lower-left coordinates are decreased by r and - upper-right coordinates are increased by r. If a - lower-left coordinate is increased to more than the corresponding - upper-right coordinate (this can only happen when r - < 0) than both coordinates are set to their average. - If n is greater than the number of defined dimensions - and the cube is being enlarged (r > 0), then extra - dimensions are added to make n altogether; - 0 is used as the initial value for the extra coordinates. - This function is useful for creating bounding boxes around a point for - searching for nearby points. - - - cube_enlarge('(1,2),(3,4)', 0.5, 3) == - '(0.5,1.5,-0.5),(3.5,4.5,0.5)' - - - - + + + cube_enlarge ( c cube, r double, n integer ) + cube + + + Increases the size of the cube by the specified + radius r in at least n + dimensions. If the radius is negative the cube is shrunk instead. + All defined dimensions are changed by the + radius r. Lower-left coordinates are decreased + by r and upper-right coordinates are increased + by r. If a lower-left coordinate is increased + to more than the corresponding upper-right coordinate (this can only + happen when r < 0) than both coordinates are + set to their average. If n is greater than the + number of defined dimensions and the cube is being enlarged + (r > 0), then extra dimensions are added to + make n altogether; 0 is used as the initial + value for the extra coordinates. This function is useful for creating + bounding boxes around a point for searching for nearby points. + + + cube_enlarge('(1,2),(3,4)', 0.5, 3) + (0.5, 1.5, -0.5),(3.5, 4.5, 0.5) + + + +
diff --git a/doc/src/sgml/earthdistance.sgml b/doc/src/sgml/earthdistance.sgml index 7ca2c40e37d..22762b02f4b 100644 --- a/doc/src/sgml/earthdistance.sgml +++ b/doc/src/sgml/earthdistance.sgml @@ -67,76 +67,120 @@ Cube-Based Earthdistance Functions - - - - Function - Returns - Description - - - - - earth()earth - float8 - Returns the assumed radius of the Earth. - - - sec_to_gc(float8)sec_to_gc - float8 - Converts the normal straight line - (secant) distance between two points on the surface of the Earth - to the great circle distance between them. - - - - gc_to_sec(float8)gc_to_sec - float8 - Converts the great circle distance between two points on the - surface of the Earth to the normal straight line (secant) distance - between them. - - - - ll_to_earth(float8, float8)ll_to_earth - earth - Returns the location of a point on the surface of the Earth given - its latitude (argument 1) and longitude (argument 2) in degrees. - - - - latitude(earth)latitude - float8 - Returns the latitude in degrees of a point on the surface of the - Earth. - - - - longitude(earth)longitude - float8 - Returns the longitude in degrees of a point on the surface of the - Earth. - - - - earth_distance(earth, earth)earth_distance - float8 - Returns the great circle distance between two points on the - surface of the Earth. - - - - earth_box(earth, float8)earth_box - cube - Returns a box suitable for an indexed search using the cube - @> - operator for points within a given great circle distance of a location. - Some points in this box are further than the specified great circle - distance from the location, so a second check using - earth_distance should be included in the query. - - - + + + + + Function + + + Description + + + + + + + + earth + earth () + float8 + + + Returns the assumed radius of the Earth. + + + + + + sec_to_gc + sec_to_gc ( float8 ) + float8 + + + Converts the normal straight line + (secant) distance between two points on the surface of the Earth + to the great circle distance between them. + + + + + + gc_to_sec + gc_to_sec ( float8 ) + float8 + + + Converts the great circle distance between two points on the + surface of the Earth to the normal straight line (secant) distance + between them. + + + + + + ll_to_earth + ll_to_earth ( float8, float8 ) + earth + + + Returns the location of a point on the surface of the Earth given + its latitude (argument 1) and longitude (argument 2) in degrees. + + + + + + latitude + latitude ( earth ) + float8 + + + Returns the latitude in degrees of a point on the surface of the + Earth. + + + + + + longitude + longitude ( earth ) + float8 + + + Returns the longitude in degrees of a point on the surface of the + Earth. + + + + + + earth_distance + earth_distance ( earth, earth ) + float8 + + + Returns the great circle distance between two points on the + surface of the Earth. + + + + + + earth_box + earth_box ( earth, float8 ) + cube + + + Returns a box suitable for an indexed search using the cube + @> + operator for points within a given great circle distance of a location. + Some points in this box are further than the specified great circle + distance from the location, so a second check using + earth_distance should be included in the query. + + +
@@ -161,23 +205,29 @@ Point-Based Earthdistance Operators - - - - Operator - Returns - Description - - - - - point <@> point - float8 - Gives the distance in statute miles between - two points on the Earth's surface. - - - + + + + + Operator + + + Description + + + + + + + point <@> point + float8 + + + Computes the distance in statute miles between + two points on the Earth's surface. + + +
diff --git a/doc/src/sgml/hstore.sgml b/doc/src/sgml/hstore.sgml index b2e04d08158..9173f27dbef 100644 --- a/doc/src/sgml/hstore.sgml +++ b/doc/src/sgml/hstore.sgml @@ -99,118 +99,223 @@ key => NULL <type>hstore</type> Operators + + + + + Operator + + + Description + + + Example(s) + + + - - - - Operator - Description - Example - Result - - + + + + hstore -> text + text + + + Returns value associated with given key, or NULL if + not present. + + + 'a=>x, b=>y'::hstore -> 'a' + x + + - - - hstore -> text - get value for key (NULL if not present) - 'a=>x, b=>y'::hstore -> 'a' - x - + + + hstore -> text[] + text[] + + + Returns values associated with given keys, or NULL + if not present. + + + 'a=>x, b=>y, c=>z'::hstore -> ARRAY['c','a'] + {"z","x"} + + - - hstore -> text[] - get values for keys (NULL if not present) - 'a=>x, b=>y, c=>z'::hstore -> ARRAY['c','a'] - {"z","x"} - + + + hstore || hstore + hstore + + + Concatenates two hstores. + + + 'a=>b, c=>d'::hstore || 'c=>x, d=>q'::hstore + "a"=>"b", "c"=>"x", "d"=>"q" + + - - hstore || hstore - concatenate hstores - 'a=>b, c=>d'::hstore || 'c=>x, d=>q'::hstore - "a"=>"b", "c"=>"x", "d"=>"q" - + + + hstore ? text + boolean + + + Does hstore contain key? + + + 'a=>1'::hstore ? 'a' + t + + - - hstore ? text - does hstore contain key? - 'a=>1'::hstore ? 'a' - t - + + + hstore ?& text[] + boolean + + + Does hstore contain all the specified keys? + + + 'a=>1,b=>2'::hstore ?& ARRAY['a','b'] + t + + - - hstore ?& text[] - does hstore contain all specified keys? - 'a=>1,b=>2'::hstore ?& ARRAY['a','b'] - t - + + + hstore ?| text[] + boolean + + + Does hstore contain any of the specified keys? + + + 'a=>1,b=>2'::hstore ?| ARRAY['b','c'] + t + + - - hstore ?| text[] - does hstore contain any of the specified keys? - 'a=>1,b=>2'::hstore ?| ARRAY['b','c'] - t - + + + hstore @> hstore + boolean + + + Does left operand contain right? + + + 'a=>b, b=>1, c=>NULL'::hstore @> 'b=>1' + t + + - - hstore @> hstore - does left operand contain right? - 'a=>b, b=>1, c=>NULL'::hstore @> 'b=>1' - t - + + + hstore <@ hstore + boolean + + + Is left operand contained in right? + + + 'a=>c'::hstore <@ 'a=>b, b=>1, c=>NULL' + f + + - - hstore <@ hstore - is left operand contained in right? - 'a=>c'::hstore <@ 'a=>b, b=>1, c=>NULL' - f - + + + hstore - text + hstore + + + Deletes key from left operand. + + + 'a=>1, b=>2, c=>3'::hstore - 'b'::text + "a"=>"1", "c"=>"3" + + - - hstore - text - delete key from left operand - 'a=>1, b=>2, c=>3'::hstore - 'b'::text - "a"=>"1", "c"=>"3" - + + + hstore - text[] + hstore + + + Deletes keys from left operand. + + + 'a=>1, b=>2, c=>3'::hstore - ARRAY['a','b'] + "c"=>"3" + + - - hstore - text[] - delete keys from left operand - 'a=>1, b=>2, c=>3'::hstore - ARRAY['a','b'] - "c"=>"3" - + + + hstore - hstore + hstore + + + Deletes pairs from left operand that match pairs in the right operand. + + + 'a=>1, b=>2, c=>3'::hstore - 'a=>4, b=>2'::hstore + "a"=>"1", "c"=>"3" + + - - hstore - hstore - delete matching pairs from left operand - 'a=>1, b=>2, c=>3'::hstore - 'a=>4, b=>2'::hstore - "a"=>"1", "c"=>"3" - + + + anyelement #= hstore + anyelement + + + Replaces fields in the left operand (which must be a composite type) + with matching values from hstore. + + + ROW(1,3) #= 'f1=>11'::hstore + (11,3) + + - - record #= hstore - replace fields in record with matching values from hstore - see Examples section - - + + + %% hstore + text[] + + + Converts hstore to an array of alternating keys and + values. + + + %% 'a=>foo, b=>bar'::hstore + {a,foo,b,bar} + + - - %% 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}} - - - - + + + %# hstore + text[] + + + Converts hstore to a two-dimensional key/value array. + + + %# 'a=>foo, b=>bar'::hstore + {{a,foo},{b,bar}} + + + +
@@ -225,233 +330,389 @@ key => NULL <type>hstore</type> Functions + + + + + Function + + + Description + + + Example(s) + + + - - - - Function - Return Type - Description - Example - Result - - + + + + hstore + hstore ( record ) + hstore + + + Constructs an hstore from a record or row. + + + hstore(ROW(1,2)) + "f1"=>"1", "f2"=>"2" + + - - - hstore(record)hstore - hstore - construct an hstore from a record or row - hstore(ROW(1,2)) - f1=>1,f2=>2 - + + + hstore ( text[] ) + hstore + + + Constructs an hstore from an array, which may be either + a key/value array, or a two-dimensional array. + + + hstore(ARRAY['a','1','b','2']) + "a"=>"1", "b"=>"2" + + + hstore(ARRAY[['c','3'],['d','4']]) + "c"=>"3", "d"=>"4" + + - - hstore(text[]) - hstore - construct an hstore from an array, which may be either - a key/value array, or a two-dimensional array - hstore(ARRAY['a','1','b','2']) || hstore(ARRAY[['c','3'],['d','4']]) - a=>1, b=>2, c=>3, d=>4 - + + + hstore ( text[], text[] ) + hstore + + + Constructs an hstore from separate key and value arrays. + + + hstore(ARRAY['a','b'], ARRAY['1','2']) + "a"=>"1", "b"=>"2" + + - - hstore(text[], text[]) - hstore - construct an hstore from separate key and value arrays - hstore(ARRAY['a','b'], ARRAY['1','2']) - "a"=>"1","b"=>"2" - + + + hstore ( text, text ) + hstore + + + Makes a single-item hstore. + + + hstore('a', 'b') + "a"=>"b" + + - - hstore(text, text) - hstore - make single-item hstore - hstore('a', 'b') - "a"=>"b" - + + + akeys + akeys ( hstore ) + text[] + + + Extracts an hstore's keys as an array. + + + akeys('a=>1,b=>2') + {a,b} + + - - akeys(hstore)akeys - text[] - get hstore's keys as an array - akeys('a=>1,b=>2') - {a,b} - - - - skeys(hstore)skeys - setof text - get hstore's keys as a set - skeys('a=>1,b=>2') - + + + skeys + skeys ( hstore ) + setof text + + + Extracts an hstore's keys as a set. + + + skeys('a=>1,b=>2') + a b - - + + + - - avals(hstore)avals - text[] - get hstore's values as an array - avals('a=>1,b=>2') - {1,2} - + + + avals + avals ( hstore ) + text[] + + + Extracts an hstore's values as an array. + + + avals('a=>1,b=>2') + {1,2} + + - - svals(hstore)svals - setof text - get hstore's values as a set - svals('a=>1,b=>2') - + + + svals + svals ( hstore ) + setof text + + + Extracts an hstore's values as a set. + + + svals('a=>1,b=>2') + 1 2 - - + + + - - hstore_to_array(hstore)hstore_to_array - text[] - get hstore's keys and values as an array of alternating - keys and values - hstore_to_array('a=>1,b=>2') - {a,1,b,2} - + + + hstore_to_array + hstore_to_array ( hstore ) + text[] + + + Extracts an hstore's keys and values as an array of + alternating keys and values. + + + hstore_to_array('a=>1,b=>2') + {a,1,b,2} + + - - hstore_to_matrix(hstore)hstore_to_matrix - text[] - get hstore's keys and values as a two-dimensional array - hstore_to_matrix('a=>1,b=>2') - {{a,1},{b,2}} - + + + hstore_to_matrix + hstore_to_matrix ( hstore ) + text[] + + + Extracts an hstore's keys and values as a two-dimensional + array. + + + hstore_to_matrix('a=>1,b=>2') + {{a,1},{b,2}} + + - - hstore_to_json(hstore)hstore_to_json - json - get hstore as a json value, converting - all non-null values to JSON strings - hstore_to_json('"a key"=>1, b=>t, c=>null, d=>12345, e=>012345, f=>1.234, g=>2.345e+4') - {"a key": "1", "b": "t", "c": null, "d": "12345", "e": "012345", "f": "1.234", "g": "2.345e+4"} - + + + hstore_to_json + hstore_to_json ( hstore ) + json + + + Converts an hstore to a json value, + converting all non-null values to JSON strings. + + + This function is used implicitly when an hstore value is + cast to json. + + + hstore_to_json('"a key"=>1, b=>t, c=>null, d=>12345, e=>012345, f=>1.234, g=>2.345e+4') + {"a key": "1", "b": "t", "c": null, "d": "12345", "e": "012345", "f": "1.234", "g": "2.345e+4"} + + - - hstore_to_jsonb(hstore)hstore_to_jsonb - jsonb - get hstore as a jsonb value, converting - all non-null values to JSON strings - hstore_to_jsonb('"a key"=>1, b=>t, c=>null, d=>12345, e=>012345, f=>1.234, g=>2.345e+4') - {"a key": "1", "b": "t", "c": null, "d": "12345", "e": "012345", "f": "1.234", "g": "2.345e+4"} - + + + hstore_to_jsonb + hstore_to_jsonb ( hstore ) + jsonb + + + Converts an hstore to a jsonb value, + converting all non-null values to JSON strings. + + + This function is used implicitly when an hstore value is + cast to jsonb. + + + hstore_to_jsonb('"a key"=>1, b=>t, c=>null, d=>12345, e=>012345, f=>1.234, g=>2.345e+4') + {"a key": "1", "b": "t", "c": null, "d": "12345", "e": "012345", "f": "1.234", "g": "2.345e+4"} + + - - hstore_to_json_loose(hstore)hstore_to_json_loose - json - get hstore as a json value, but attempt to distinguish numerical and Boolean values so they are unquoted in the JSON - hstore_to_json_loose('"a key"=>1, b=>t, c=>null, d=>12345, e=>012345, f=>1.234, g=>2.345e+4') - {"a key": 1, "b": true, "c": null, "d": 12345, "e": "012345", "f": 1.234, "g": 2.345e+4} - + + + hstore_to_json_loose + hstore_to_json_loose ( hstore ) + json + + + Converts an hstore to a json value, but + attempts to distinguish numerical and Boolean values so they are + unquoted in the JSON. + + + hstore_to_json_loose('"a key"=>1, b=>t, c=>null, d=>12345, e=>012345, f=>1.234, g=>2.345e+4') + {"a key": 1, "b": true, "c": null, "d": 12345, "e": "012345", "f": 1.234, "g": 2.345e+4} + + - - hstore_to_jsonb_loose(hstore)hstore_to_jsonb_loose - jsonb - get hstore as a jsonb value, but attempt to distinguish numerical and Boolean values so they are unquoted in the JSON - hstore_to_jsonb_loose('"a key"=>1, b=>t, c=>null, d=>12345, e=>012345, f=>1.234, g=>2.345e+4') - {"a key": 1, "b": true, "c": null, "d": 12345, "e": "012345", "f": 1.234, "g": 2.345e+4} - + + + hstore_to_jsonb_loose + hstore_to_jsonb_loose ( hstore ) + jsonb + + + Converts an hstore to a jsonb value, but + attempts to distinguish numerical and Boolean values so they are + unquoted in the JSON. + + + hstore_to_jsonb_loose('"a key"=>1, b=>t, c=>null, d=>12345, e=>012345, f=>1.234, g=>2.345e+4') + {"a key": 1, "b": true, "c": null, "d": 12345, "e": "012345", "f": 1.234, "g": 2.345e+4} + + - - slice(hstore, text[])slice - hstore - extract a subset of an hstore - slice('a=>1,b=>2,c=>3'::hstore, ARRAY['b','c','x']) - "b"=>"2", "c"=>"3" - + + + slice + slice ( hstore, text[] ) + hstore + + + Extracts a subset of an hstore containing only the + specified keys. + + + slice('a=>1,b=>2,c=>3'::hstore, ARRAY['b','c','x']) + "b"=>"2", "c"=>"3" + + - - each(hstore)each - setof(key text, value text) - get hstore's keys and values as a set - select * from each('a=>1,b=>2') - + + + each + each ( hstore ) + setof record + ( key text, + value text ) + + + Extracts an hstore's keys and values as a set of records. + + + select * from each('a=>1,b=>2') + key | value -----+------- a | 1 b | 2 - - + + + - - exist(hstore,text)exist - boolean - does hstore contain key? - exist('a=>1','a') - t - + + + exist + exist ( hstore, text ) + boolean + + + Does hstore contain key? + + + exist('a=>1','a') + t + + - - defined(hstore,text)defined - boolean - does hstore contain non-NULL value for key? - defined('a=>NULL','a') - f - + + + defined + defined ( hstore, text ) + boolean + + + Does hstore contain a non-NULL value + for key? + + + defined('a=>NULL','a') + f + + - - delete(hstore,text)delete - hstore - delete pair with matching key - delete('a=>1,b=>2','b') - "a"=>"1" - + + + delete + delete ( hstore, text ) + hstore + + + Deletes pair with matching key. + + + delete('a=>1,b=>2','b') + "a"=>"1" + + - - delete(hstore,text[]) - hstore - delete pairs with matching keys - delete('a=>1,b=>2,c=>3',ARRAY['a','b']) - "c"=>"3" - + + + delete ( hstore, text[] ) + hstore + + + Deletes pairs with matching keys. + + + delete('a=>1,b=>2,c=>3',ARRAY['a','b']) + "c"=>"3" + + - - delete(hstore,hstore) - hstore - delete pairs matching those in the second argument - delete('a=>1,b=>2','a=>4,b=>2'::hstore) - "a"=>"1" - - - - populate_record(record,hstore)populate_record - record - replace fields in record with matching values from hstore - see Examples section - - + + + delete ( hstore, hstore ) + hstore + + + Deletes pairs matching those in the second argument. + + + delete('a=>1,b=>2','a=>4,b=>2'::hstore) + "a"=>"1" + + + + + populate_record + populate_record ( anyelement, hstore ) + anyelement + + + Replaces fields in the left operand (which must be a composite type) + with matching values from hstore. + + + populate_record(ROW(1,2), 'f1=>42'::hstore) + (42,2) + +
- - - - The function hstore_to_json is used when - an hstore value is cast to json. - Likewise, hstore_to_jsonb is used when - an hstore value is cast to jsonb. - - - - - - The function populate_record is actually declared - with anyelement, not record, as its first argument, - but it will reject non-record types with a run-time error. - - diff --git a/doc/src/sgml/intarray.sgml b/doc/src/sgml/intarray.sgml index c4be4145670..9d2eb52eeb4 100644 --- a/doc/src/sgml/intarray.sgml +++ b/doc/src/sgml/intarray.sgml @@ -41,186 +41,325 @@ <filename>intarray</filename> Functions + + + + + Function + + + Description + + + Example(s) + + + - - - - Function - Return Type - Description - Example - Result - - + + + + icount + icount ( integer[] ) + integer + + + Returns the number of elements in the array. + + + icount('{1,2,3}'::integer[]) + 3 + + - - - icount(int[])icount - int - number of elements in array - icount('{1,2,3}'::int[]) - 3 - + + + sort + sort ( integer[], dir text ) + integer[] + + + Sorts the array in either ascending or descending order. + dir must be asc + or desc. + + + sort('{1,3,2}'::integer[], 'desc') + {3,2,1} + + - - sort(int[], text dir)sort - int[] - sort array — dir must be asc or desc - sort('{1,2,3}'::int[], 'desc') - {3,2,1} - + + + sort ( integer[] ) + integer[] + + + sort_asc + sort_asc ( integer[] ) + integer[] + + + Sorts in ascending order. + + + sort(array[11,77,44]) + {11,44,77} + + - - sort(int[]) - int[] - sort in ascending order - sort(array[11,77,44]) - {11,44,77} - + + + sort_desc + sort_desc ( integer[] ) + integer[] + + + Sorts in descending order. + + + sort_desc(array[11,77,44]) + {77,44,11} + + - - sort_asc(int[])sort_asc - int[] - sort in ascending order - - - + + + uniq + uniq ( integer[] ) + integer[] + + + Removes adjacent duplicates. + + + uniq(sort('{1,2,3,2,1}'::integer[])) + {1,2,3} + + - - sort_desc(int[])sort_desc - int[] - sort in descending order - - - + + + idx + idx ( integer[], item integer ) + integer + + + Returns index of the first array element + matching item, or 0 if no match. + + + idx(array[11,22,33,22,11], 22) + 2 + + - - uniq(int[])uniq - int[] - remove adjacent duplicates - uniq(sort('{1,2,3,2,1}'::int[])) - {1,2,3} - + + + subarray + subarray ( integer[], start integer, len integer ) + integer[] + + + Extracts the portion of the array starting at + position start, with len + elements. + + + subarray('{1,2,3,2,1}'::integer[], 2, 3) + {2,3,2} + + - - idx(int[], int item)idx - int - index of first element matching item (0 if none) - idx(array[11,22,33,22,11], 22) - 2 - - - - subarray(int[], int start, int len)subarray - int[] - portion of array starting at position start, len elements - subarray('{1,2,3,2,1}'::int[], 2, 3) - {2,3,2} - - - - subarray(int[], int start) - int[] - portion of array starting at position start - subarray('{1,2,3,2,1}'::int[], 2) - {2,3,2,1} - - - - intset(int)intset - int[] - make single-element array - intset(42) - {42} - + + + subarray ( integer[], start integer ) + integer[] + + + Extracts the portion of the array starting at + position start. + + + subarray('{1,2,3,2,1}'::integer[], 2) + {2,3,2,1} + + + + + intset + intset ( integer ) + integer[] + + + Makes a single-element array. + + + intset(42) + {42} + +
<filename>intarray</filename> Operators + + + + + Operator + + + Description + + + - - - - Operator - Returns - Description - - + + + + integer[] && integer[] + boolean + + + Do arrays overlap (have at least one element in common)? + + - - - int[] && int[] - boolean - overlap — true if arrays have at least one common element - - - int[] @> int[] - boolean - contains — true if left array contains right array - - - int[] <@ int[] - boolean - contained — true if left array is contained in right array - - - # int[] - int - number of elements in array - - - int[] # int - int - index (same as idx function) - - - int[] + int - int[] - push element onto array (add it to end of array) - - - int[] + int[] - int[] - array concatenation (right array added to the end of left one) - - - int[] - int - int[] - remove entries matching right argument from array - - - int[] - int[] - int[] - remove elements of right array from left - - - int[] | int - int[] - union of arguments - - - int[] | int[] - int[] - union of arrays - - - int[] & int[] - int[] - intersection of arrays - - - int[] @@ query_int - boolean - true if array satisfies query (see below) - - - query_int ~~ int[] - boolean - true if array satisfies query (commutator of @@) - + + + integer[] @> integer[] + boolean + + + Does left array contain right array? + + + + + + integer[] <@ integer[] + boolean + + + Is left array contained in right array? + + + + + + # integer[] + integer + + + Returns the number of elements in the array. + + + + + + integer[] # integer + integer + + + Returns index of the first array element + matching the right argument, or 0 if no match. + (Same as idx function.) + + + + + + integer[] + integer + integer[] + + + Adds element to end of array. + + + + + + integer[] + integer[] + integer[] + + + Concatenates the arrays. + + + + + + integer[] - integer + integer[] + + + Removes entries matching the right argument from the array. + + + + + + integer[] - integer[] + integer[] + + + Removes elements of the right array from the left array. + + + + + + integer[] | integer + integer[] + + + Computes the union of the arguments. + + + + + + integer[] | integer[] + integer[] + + + Computes the union of the arguments. + + + + + + integer[] & integer[] + integer[] + + + Computes the intersection of the arguments. + + + + + + integer[] @@ query_int + boolean + + + Does array satisfy query? (see below) + + + + + + query_int ~~ integer[] + boolean + + + Does array satisfy query? (commutator of @@) + +
@@ -274,7 +413,7 @@ The implementation uses an RD-tree data structure with built-in lossy compression. - + gist__int_ops approximates an integer set as an array of integer ranges. Its optional integer parameter numranges @@ -284,7 +423,7 @@ keys leads to a more precise search (scanning a smaller fraction of the index and fewer heap pages), at the cost of a larger index. - + gist__intbig_ops approximates an integer set as a bitmap signature. Its optional integer parameter siglen diff --git a/doc/src/sgml/isn.sgml b/doc/src/sgml/isn.sgml index 6c61f14fdcd..e1ea209ff11 100644 --- a/doc/src/sgml/isn.sgml +++ b/doc/src/sgml/isn.sgml @@ -38,6 +38,8 @@ <filename>isn</filename> Data Types + + Data Type @@ -235,38 +237,63 @@
<filename>isn</filename> Functions - - - - Function - Returns - Description - - + + + + + Function + + + Description + + + - - - isn_weak(boolean)isn_weak - boolean - Sets the weak input mode (returns new setting) - - - isn_weak() - boolean - Gets the current status of the weak mode - - - make_valid(isn)make_valid - isn - Validates an invalid number (clears the invalid flag) - - - is_valid(isn)is_valid - boolean - Checks for the presence of the invalid flag - - - + + + + isn_weak + isn_weak ( boolean ) + boolean + + + Sets the weak input mode, and returns new setting. + + + + + + isn_weak () + boolean + + + Returns the current status of the weak mode. + + + + + + make_valid + make_valid ( isn ) + isn + + + Validates an invalid number (clears the invalid flag). + + + + + + is_valid + is_valid ( isn ) + boolean + + + Checks for the presence of the invalid flag. + + + +
diff --git a/doc/src/sgml/lobj.sgml b/doc/src/sgml/lobj.sgml index be6375a51c9..b6b626a4afd 100644 --- a/doc/src/sgml/lobj.sgml +++ b/doc/src/sgml/lobj.sgml @@ -542,69 +542,82 @@ int lo_unlink(PGconn *conn, Oid lobjId); listed in . - - SQL-Oriented Large Object Functions - - - - Function - Return Type - Description - Example - Result - - +
+ SQL-Oriented Large Object Functions + + + + + Function + + + Description + + + Example(s) + + + - - - - - lo_from_bytea - - lo_from_bytea(loid oid, string bytea) - - oid - - Create a large object and store data there, returning its OID. - Pass 0 to have the system choose an OID. - - lo_from_bytea(0, '\xffffff00') - 24528 - + + + + + lo_from_bytea + + lo_from_bytea ( loid oid, data bytea ) + oid + + + Creates a large object and stores data in it. + If loid is zero then the system will choose a + free OID, otherwise that OID is used (with an error if some large + object already has that OID). On success, the large object's OID is + returned. + + + lo_from_bytea(0, '\xffffff00') + 24528 + + - - - - lo_put - - lo_put(loid oid, offset bigint, str bytea) - - void - - Write data at the given offset. - - lo_put(24528, 1, '\xaa') - - + + + + lo_put + + lo_put ( loid oid, offset bigint, data bytea ) + void + + + Writes data starting at the given offset within + the large object; the large object is enlarged if necessary. + + + lo_put(24528, 1, '\xaa') + + + - - - - lo_get - - lo_get(loid oid , from bigint, for int) - - bytea - - Extract contents or a substring thereof. - - lo_get(24528, 0, 3) - \xffaaff - - - - -
+ + + + lo_get + + lo_get ( loid oid , offset bigint, length integer ) + bytea + + + Extracts the large object's contents, or a substring thereof. + + + lo_get(24528, 0, 3) + \xffaaff + + + + + There are additional server-side functions corresponding to each of the diff --git a/doc/src/sgml/ltree.sgml b/doc/src/sgml/ltree.sgml index e342d454e51..dea453fc759 100644 --- a/doc/src/sgml/ltree.sgml +++ b/doc/src/sgml/ltree.sgml @@ -201,169 +201,221 @@ Europe & Russia*@ & !Transportation <type>ltree</type> Operators + + + + + Operator + + + Description + + + - - - - Operator - Returns - Description - - + + + + ltree @> ltree + boolean + + + Is left argument an ancestor of right (or equal)? + + - - - ltree @> ltree - boolean - is left argument an ancestor of right (or equal)? - + + + ltree <@ ltree + boolean + + + Is left argument a descendant of right (or equal)? + + - - ltree <@ ltree - boolean - is left argument a descendant of right (or equal)? - + + + ltree ~ lquery + boolean + + + lquery ~ ltree + boolean + + + Does ltree match lquery? + + - - ltree ~ lquery - boolean - does ltree match lquery? - + + + ltree ? lquery[] + boolean + + + lquery[] ? ltree + boolean + + + Does ltree match any lquery in array? + + - - lquery ~ ltree - boolean - does ltree match lquery? - + + + ltree @ ltxtquery + boolean + + + ltxtquery @ ltree + boolean + + + Does ltree match ltxtquery? + + - - ltree ? lquery[] - boolean - does ltree match any lquery in array? - + + + ltree || ltree + ltree + + + Concatenates ltree paths. + + - - lquery[] ? ltree - boolean - does ltree match any lquery in array? - + + + ltree || text + ltree + + + text || ltree + ltree + + + Converts text to ltree and concatenates. + + - - ltree @ ltxtquery - boolean - does ltree match ltxtquery? - + + + ltree[] @> ltree + boolean + + + ltree <@ ltree[] + boolean + + + Does array contain an ancestor of ltree? + + - - ltxtquery @ ltree - boolean - does ltree match ltxtquery? - + + + ltree[] <@ ltree + boolean + + + ltree @> ltree[] + boolean + + + Does array contain a descendant of ltree? + + - - ltree || ltree - ltree - concatenate ltree paths - + + + ltree[] ~ lquery + boolean + + + lquery ~ ltree[] + boolean + + + Does array contain any path matching lquery? + + - - ltree || text - ltree - convert text to ltree and concatenate - + + + ltree[] ? lquery[] + boolean + + + lquery[] ? ltree[] + boolean + + + Does ltree array contain any path matching + any lquery? + + - - text || ltree - ltree - convert text to ltree and concatenate - + + + ltree[] @ ltxtquery + boolean + + + ltxtquery @ ltree[] + boolean + + + Does array contain any path matching ltxtquery? + + - - ltree[] @> ltree - boolean - does array contain an ancestor of ltree? - + + + ltree[] ?@> ltree + ltree + + + Returns first array entry that is an ancestor of ltree, + or NULL if none. + + - - ltree <@ ltree[] - boolean - does array contain an ancestor of ltree? - + + + ltree[] ?<@ ltree + ltree + + + Returns first array entry that is a descendant of ltree, + or NULL if none. + + - - ltree[] <@ ltree - boolean - does array contain a descendant of ltree? - + + + ltree[] ?~ lquery + ltree + + + Returns first array entry that matches lquery, + or NULL if none. + + - - ltree @> ltree[] - boolean - does array contain a descendant of ltree? - - - - ltree[] ~ lquery - boolean - does array contain any path matching lquery? - - - - lquery ~ ltree[] - boolean - does array contain any path matching lquery? - - - - ltree[] ? lquery[] - boolean - does ltree array contain any path matching any lquery? - - - - lquery[] ? ltree[] - boolean - does ltree array contain any path matching any lquery? - - - - ltree[] @ ltxtquery - boolean - does array contain any path matching ltxtquery? - - - - ltxtquery @ ltree[] - boolean - does array contain any path matching ltxtquery? - - - - ltree[] ?@> ltree - ltree - first array entry that is an ancestor of ltree; NULL if none - - - - ltree[] ?<@ ltree - ltree - first array entry that is a descendant of ltree; NULL if none - - - - ltree[] ?~ lquery - ltree - first array entry that matches lquery; NULL if none - - - - ltree[] ?@ ltxtquery - ltree - first array entry that matches ltxtquery; NULL if none - - - - + + + ltree[] ?@ ltxtquery + ltree + + + Returns first array entry that matches ltxtquery, + or NULL if none. + + + +
@@ -380,114 +432,178 @@ Europe & Russia*@ & !Transportation <type>ltree</type> Functions + + + + + Function + + + Description + + + Example(s) + + + - - - - Function - Return Type - Description - Example - Result - - + + + + subltree + subltree ( ltree, start integer, end integer ) + ltree + + + Returns subpath of ltree from + position start to + position end-1 (counting from 0). + + + subltree('Top.Child1.Child2',1,2) + Child1 + + - - - subltree(ltree, int start, int end)subltree - ltree - subpath of ltree from position start to - position end-1 (counting from 0) - subltree('Top.Child1.Child2',1,2) - Child1 - + + + subpath + subpath ( ltree, offset integer, len integer ) + ltree + + + Returns subpath of ltree starting at + position offset, with + length len. If offset + is negative, subpath starts that far from the end of the path. + If len is negative, leaves that many labels off + the end of the path. + + + subpath('Top.Child1.Child2',0,2) + Top.Child1 + + - - subpath(ltree, int offset, int len)subpath - ltree - subpath of ltree starting at position - offset, length len. - If offset is negative, subpath starts that far from the - end of the path. If len is negative, leaves that many - labels off the end of the path. - subpath('Top.Child1.Child2',0,2) - Top.Child1 - + + + subpath ( ltree, offset integer ) + ltree + + + Returns subpath of ltree starting at + position offset, extending to end of path. + If offset is negative, subpath starts that far + from the end of the path. + + + subpath('Top.Child1.Child2',1) + Child1.Child2 + + - - subpath(ltree, int offset) - ltree - subpath of ltree starting at position - offset, extending to end of path. - If offset is negative, subpath starts that far from the - end of the path. - subpath('Top.Child1.Child2',1) - Child1.Child2 - + + + nlevel + nlevel ( ltree ) + integer + + + Returns number of labels in path. + + + nlevel('Top.Child1.Child2') + 3 + + - - nlevel(ltree)nlevel - integer - number of labels in path - nlevel('Top.Child1.Child2') - 3 - + + + index + index ( a ltree, b ltree ) + integer + + + Returns position of first occurrence of b in + a, or -1 if not found. + + + index('0.1.2.3.5.4.5.6.8.5.6.8','5.6') + 6 + + - - index(ltree a, ltree b)index - integer - position of first occurrence of b in - a; -1 if not found - index('0.1.2.3.5.4.5.6.8.5.6.8','5.6') - 6 - + + + index ( a ltree, b ltree, offset integer ) + integer + + + Returns position of first occurrence of b + in a, or -1 if not found. The search starts at + position offset; + negative offset means + start -offset labels from the end of the path. + + + index('0.1.2.3.5.4.5.6.8.5.6.8','5.6',-4) + 9 + + - - index(ltree a, ltree b, int offset) - integer - position of first occurrence of b in - a, searching starting at offset; - negative offset means start -offset - labels from the end of the path - index('0.1.2.3.5.4.5.6.8.5.6.8','5.6',-4) - 9 - + + + text2ltree + text2ltree ( text ) + ltree + + + Casts text to ltree. + + - - text2ltree(text)text2ltree - ltree - cast text to ltree - - - + + + ltree2text + ltree2text ( ltree ) + text + + + Casts ltree to text. + + - - ltree2text(ltree)ltree2text - text - cast ltree to text - - - + + + lca + lca ( ltree , ltree , ... ) + ltree + + + Computes longest common ancestor of paths + (up to 8 arguments are supported). + + + lca('1.2.3','1.2.3.4.5.6') + 1.2 + + - - lca(ltree, ltree, ...)lca - ltree - longest common ancestor of paths - (up to 8 arguments supported) - lca('1.2.3','1.2.3.4.5.6') - 1.2 - - - - lca(ltree[]) - ltree - longest common ancestor of paths in array - lca(array['1.2.3'::ltree,'1.2.3.4']) - 1.2 - - - - + + + lca ( ltree[] ) + ltree + + + Computes longest common ancestor of paths in array. + + + lca(array['1.2.3'::ltree,'1.2.3.4']) + 1.2 + + + +
diff --git a/doc/src/sgml/monitoring.sgml b/doc/src/sgml/monitoring.sgml index 842e553e1ec..6eb4df1d2e9 100644 --- a/doc/src/sgml/monitoring.sgml +++ b/doc/src/sgml/monitoring.sgml @@ -3375,122 +3375,179 @@ SELECT pid, wait_event_type, wait_event FROM pg_stat_activity WHERE wait_event i linkend="monitoring-stats-funcs-table"/>. - - Additional Statistics Functions +
+ Additional Statistics Functions + + + + + Function + + + Description + + + - - - - Function - Return Type - Description - - - - - - + + - pg_backend_pid() - integer - - Process ID of the server process handling the current session - - + + pg_backend_pid () + integer + + + Returns the process ID of the server process attached to the current + session. + + - - pg_stat_get_activity(integer)pg_stat_get_activity - setof record - - Returns a record of information about the backend with the specified PID, or - one record for each active backend in the system if NULL is - specified. The fields returned are a subset of those in the - pg_stat_activity view. - - + + + + pg_stat_get_activity + + pg_stat_get_activity ( integer ) + setof record + + + Returns a record of information about the backend with the specified + process ID, or one record for each active backend in the system + if NULL is specified. The fields returned are a + subset of those in the pg_stat_activity view. + + - - pg_stat_get_snapshot_timestamp()pg_stat_get_snapshot_timestamp - timestamp with time zone - - Returns the timestamp of the current statistics snapshot - - + + + + pg_stat_get_snapshot_timestamp + + pg_stat_get_snapshot_timestamp () + timestamp with time zone + + + Returns the timestamp of the current statistics snapshot. + + - - pg_stat_clear_snapshot()pg_stat_clear_snapshot - void - - Discard the current statistics snapshot - - + + + + pg_stat_clear_snapshot + + pg_stat_clear_snapshot () + void + + + Discards the current statistics snapshot. + + - - pg_stat_reset()pg_stat_reset - void - - Reset all statistics counters for the current database to zero - (requires superuser privileges by default, but EXECUTE for this - function can be granted to others.) - - + + + + pg_stat_reset + + pg_stat_reset () + void + + + Resets all statistics counters for the current database to zero. + + + This function is restricted to superusers by default, but other users + can be granted EXECUTE to run the function. + + - - pg_stat_reset_shared(text)pg_stat_reset_shared - void - - Reset some cluster-wide statistics counters to zero, depending on the - argument (requires superuser privileges by default, but EXECUTE for - this function can be granted to others). - Calling pg_stat_reset_shared('bgwriter') will zero all the - counters shown in the pg_stat_bgwriter view. - Calling pg_stat_reset_shared('archiver') will zero all the - counters shown in the pg_stat_archiver view. - - + + + + pg_stat_reset_shared + + pg_stat_reset_shared ( text ) + void + + + Resets some cluster-wide statistics counters to zero, depending on the + argument. The argument can be bgwriter to reset + all the counters shown in + the pg_stat_bgwriter + view,or archiver to reset all the counters shown in + the pg_stat_archiver view. + + + This function is restricted to superusers by default, but other users + can be granted EXECUTE to run the function. + + - - pg_stat_reset_single_table_counters(oid)pg_stat_reset_single_table_counters - void - - Reset statistics for a single table or index in the current database to - zero (requires superuser privileges by default, but EXECUTE for this - function can be granted to others) - - + + + + pg_stat_reset_single_table_counters + + pg_stat_reset_single_table_counters ( oid ) + void + + + Resets statistics for a single table or index in the current database + to zero. + + + This function is restricted to superusers by default, but other users + can be granted EXECUTE to run the function. + + - - pg_stat_reset_single_function_counters(oid)pg_stat_reset_single_function_counters - void - - Reset statistics for a single function in the current database to - zero (requires superuser privileges by default, but EXECUTE for this - function can be granted to others) - - + + + + pg_stat_reset_single_function_counters + + pg_stat_reset_single_function_counters ( oid ) + void + + + Resets statistics for a single function in the current database to + zero. + + + This function is restricted to superusers by default, but other users + can be granted EXECUTE to run the function. + + - - pg_stat_reset_slru(text)pg_stat_reset_slru - void - - Reset statistics either for a single SLRU or all SLRUs in the cluster - to zero (requires superuser privileges by default, but EXECUTE for this - function can be granted to others). - Calling pg_stat_reset_slru(NULL) will zero all the - counters shown in the pg_stat_slru view for - all SLRU caches. - Calling pg_stat_reset_slru(name) with names from a - predefined list (async, clog, - commit_timestamp, multixact_offset, - multixact_member, oldserxid, - subtrans and other) resets counters - for only that entry. Names not included in this list are treated as - other. - - - - -
+ + + + pg_stat_reset_slru + + pg_stat_reset_slru ( text ) + void + + + Resets statistics to zero for a single SLRU cache, or for all SLRUs in + the cluster. If the argument is NULL, all counters shown in + the pg_stat_slru view for all SLRU caches are + reset. The argument can be one of async, + clog, commit_timestamp, + multixact_offset, + multixact_member, oldserxid, or + subtrans to reset the counters for only that entry. + If the argument is other (or indeed, any + unrecognized name), then the counters for all other SLRU caches, such + as extension-defined caches, are reset. + + + This function is restricted to superusers by default, but other users + can be granted EXECUTE to run the function. + + + + + pg_stat_get_activity, the underlying function of @@ -3514,100 +3571,182 @@ SELECT pg_stat_get_backend_pid(s.backendid) AS pid, - - Per-Backend Statistics Functions - - - - - Function - Return Type - Description - - - - - - - pg_stat_get_backend_idset() - setof integer - Set of currently active backend ID numbers (from 1 to the - number of active backends) - - - - pg_stat_get_backend_activity(integer) - text - Text of this backend's most recent query - - - - pg_stat_get_backend_activity_start(integer) - timestamp with time zone - Time when the most recent query was started - - - - pg_stat_get_backend_client_addr(integer) - inet - IP address of the client connected to this backend - - - - pg_stat_get_backend_client_port(integer) - integer - TCP port number that the client is using for communication - - - - pg_stat_get_backend_dbid(integer) - oid - OID of the database this backend is connected to - - - - pg_stat_get_backend_pid(integer) - integer - Process ID of this backend - - - - pg_stat_get_backend_start(integer) - timestamp with time zone - Time when this process was started - - - - pg_stat_get_backend_userid(integer) - oid - OID of the user logged into this backend - - +
+ Per-Backend Statistics Functions + + - pg_stat_get_backend_wait_event_type(integer) - text - Wait event type name if backend is currently waiting, otherwise NULL. - See for details. - + + Function + + + Description + + + + + + + + + pg_stat_get_backend_idset + + pg_stat_get_backend_idset () + setof integer + + + Returns the set of currently active backend ID numbers (from 1 to the + number of active backends). + - - pg_stat_get_backend_wait_event(integer) - text - Wait event name if backend is currently waiting, otherwise NULL. - See for details. - - + + + + pg_stat_get_backend_activity + + pg_stat_get_backend_activity ( integer ) + text + + + Returns the text of this backend's most recent query. + + - - pg_stat_get_backend_xact_start(integer) - timestamp with time zone - Time when the current transaction was started - + + + + pg_stat_get_backend_activity_start + + pg_stat_get_backend_activity_start ( integer ) + timestamp with time zone + + + Returns the time when the backend's most recent query was started. + + - - -
+ + + + pg_stat_get_backend_client_addr + + pg_stat_get_backend_client_addr ( integer ) + inet + + + Returns the IP address of the client connected to this backend. + + + + + + + pg_stat_get_backend_client_port + + pg_stat_get_backend_client_port ( integer ) + integer + + + Returns the TCP port number that the client is using for communication. + + + + + + + pg_stat_get_backend_dbid + + pg_stat_get_backend_dbid ( integer ) + oid + + + Returns the OID of the database this backend is connected to. + + + + + + + pg_stat_get_backend_pid + + pg_stat_get_backend_pid ( integer ) + integer + + + Returns the process ID of this backend. + + + + + + + pg_stat_get_backend_start + + pg_stat_get_backend_start ( integer ) + timestamp with time zone + + + Returns the time when this process was started. + + + + + + + pg_stat_get_backend_userid + + pg_stat_get_backend_userid ( integer ) + oid + + + Returns the OID of the user logged into this backend. + + + + + + + pg_stat_get_backend_wait_event_type + + pg_stat_get_backend_wait_event_type ( integer ) + text + + + Returns the wait event type name if this backend is currently waiting, + otherwise NULL. See for details. + + + + + + + pg_stat_get_backend_wait_event + + pg_stat_get_backend_wait_event ( integer ) + text + + + Returns the wait event name if this backend is currently waiting, + otherwise NULL. See for details. + + + + + + + pg_stat_get_backend_xact_start + + pg_stat_get_backend_xact_start ( integer ) + timestamp with time zone + + + Returns the time when the backend's current transaction was started. + + + + + @@ -3834,7 +3973,7 @@ SELECT pg_stat_get_backend_pid(s.backendid) AS pid, finalizing analyze - The command is updating pg_class. When this phase is completed, + The command is updating pg_class. When this phase is completed, ANALYZE will end. diff --git a/doc/src/sgml/pgtrgm.sgml b/doc/src/sgml/pgtrgm.sgml index 97b3d13a887..5365b0681e5 100644 --- a/doc/src/sgml/pgtrgm.sgml +++ b/doc/src/sgml/pgtrgm.sgml @@ -70,83 +70,106 @@ <filename>pg_trgm</filename> Functions - - - - Function - Returns - Description - - + + + + + Function + + + Description + + + - - - similarity(text, text)similarity - real - - Returns a number that indicates how similar the two arguments are. - The range of the result is zero (indicating that the two strings are - completely dissimilar) to one (indicating that the two strings are - identical). - - - - show_trgm(text)show_trgm - text[] - - Returns an array of all the trigrams in the given string. - (In practice this is seldom useful except for debugging.) - - - - - word_similarity(text, text) - word_similarity - - real - - Returns a number that indicates the greatest similarity between - the set of trigrams in the first string and any continuous extent - of an ordered set of trigrams in the second string. For details, see - the explanation below. - - - - - strict_word_similarity(text, text) - strict_word_similarity - - real - - Same as word_similarity(text, text), but forces - extent boundaries to match word boundaries. Since we don't have - cross-word trigrams, this function actually returns greatest similarity - between first string and any continuous extent of words of the second - string. - - - - show_limit()show_limit - real - - Returns the current similarity threshold used by the % - operator. This sets the minimum similarity between - two words for them to be considered similar enough to - be misspellings of each other, for example - (deprecated). - - - - set_limit(real)set_limit - real - - Sets the current similarity threshold that is used by the % - operator. The threshold must be between 0 and 1 (default is 0.3). - Returns the same value passed in (deprecated). - - - - + + + + similarity + similarity ( text, text ) + real + + + Returns a number that indicates how similar the two arguments are. + The range of the result is zero (indicating that the two strings are + completely dissimilar) to one (indicating that the two strings are + identical). + + + + + + show_trgm + show_trgm ( text ) + text[] + + + Returns an array of all the trigrams in the given string. + (In practice this is seldom useful except for debugging.) + + + + + + word_similarity + word_similarity ( text, text ) + real + + + Returns a number that indicates the greatest similarity between + the set of trigrams in the first string and any continuous extent + of an ordered set of trigrams in the second string. For details, see + the explanation below. + + + + + + strict_word_similarity + strict_word_similarity ( text, text ) + real + + + Same as word_similarity, but forces + extent boundaries to match word boundaries. Since we don't have + cross-word trigrams, this function actually returns greatest similarity + between first string and any continuous extent of words of the second + string. + + + + + + show_limit + show_limit () + real + + + Returns the current similarity threshold used by the % + operator. This sets the minimum similarity between + two words for them to be considered similar enough to + be misspellings of each other, for example. + (Deprecated; instead use SHOW + pg_trgm.similarity_threshold.) + + + + + + set_limit + set_limit ( real ) + real + + + Sets the current similarity threshold that is used by the % + operator. The threshold must be between 0 and 1 (default is 0.3). + Returns the same value passed in. + (Deprecated; instead use SET + pg_trgm.similarity_threshold.) + + + +
@@ -178,9 +201,9 @@ - At the same time, strict_word_similarity(text, text) + At the same time, strict_word_similarity selects an extent of words in the second string. In the example above, - strict_word_similarity(text, text) would select the + strict_word_similarity would select the extent of a single word 'words', whose set of trigrams is {" w"," wo","wor","ord","rds","ds "}. @@ -194,117 +217,141 @@ - Thus, the strict_word_similarity(text, text) function + Thus, the strict_word_similarity function is useful for finding the similarity to whole words, while - word_similarity(text, text) is more suitable for + word_similarity is more suitable for finding the similarity for parts of words. <filename>pg_trgm</filename> Operators - - - - Operator - Returns - Description - - + + + + + Operator + + + Description + + + - - - text % text - boolean - - Returns true if its arguments have a similarity that is - greater than the current similarity threshold set by - pg_trgm.similarity_threshold. - - - - text <% text - boolean - - Returns true if the similarity between the trigram - set in the first argument and a continuous extent of an ordered trigram - set in the second argument is greater than the current word similarity - threshold set by pg_trgm.word_similarity_threshold - parameter. - - - - text %> text - boolean - - Commutator of the <% operator. - - - - text <<% text - boolean - - Returns true if its second argument has a continuous - extent of an ordered trigram set that matches word boundaries, - and its similarity to the trigram set of the first argument is greater - than the current strict word similarity threshold set by the - pg_trgm.strict_word_similarity_threshold parameter. - - - - text %>> text - boolean - - Commutator of the <<% operator. - - - - text <-> text - real - - Returns the distance between the arguments, that is - one minus the similarity() value. - - - - - text <<-> text - - real - - Returns the distance between the arguments, that is - one minus the word_similarity() value. - - - - - text <->> text - - real - - Commutator of the <<-> operator. - - - - - text <<<-> text - - real - - Returns the distance between the arguments, that is - one minus the strict_word_similarity() value. - - - - - text <->>> text - - real - - Commutator of the <<<-> operator. - - - - + + + + text % text + boolean + + + Returns true if its arguments have a similarity + that is greater than the current similarity threshold set by + pg_trgm.similarity_threshold. + + + + + + text <% text + boolean + + + Returns true if the similarity between the trigram + set in the first argument and a continuous extent of an ordered trigram + set in the second argument is greater than the current word similarity + threshold set by pg_trgm.word_similarity_threshold + parameter. + + + + + + text %> text + boolean + + + Commutator of the <% operator. + + + + + + text <<% text + boolean + + + Returns true if its second argument has a continuous + extent of an ordered trigram set that matches word boundaries, + and its similarity to the trigram set of the first argument is greater + than the current strict word similarity threshold set by the + pg_trgm.strict_word_similarity_threshold parameter. + + + + + + text %>> text + boolean + + + Commutator of the <<% operator. + + + + + + text <-> text + real + + + Returns the distance between the arguments, that is + one minus the similarity() value. + + + + + + text <<-> text + real + + + Returns the distance between the arguments, that is + one minus the word_similarity() value. + + + + + + text <->> text + real + + + Commutator of the <<-> operator. + + + + + + text <<<-> text + real + + + Returns the distance between the arguments, that is + one minus the strict_word_similarity() value. + + + + + + text <->>> text + real + + + Commutator of the <<<-> operator. + + + +
diff --git a/doc/src/sgml/ref/pgbench.sgml b/doc/src/sgml/ref/pgbench.sgml index 8fe561bbd61..4df31f3bc45 100644 --- a/doc/src/sgml/ref/pgbench.sgml +++ b/doc/src/sgml/ref/pgbench.sgml @@ -198,8 +198,6 @@ pgbench options d Generate data and load it into the standard tables, replacing any data already present. - The default is to generate data client-side (g) - and transmit it over the connection. With g (client-side data generation), @@ -207,18 +205,21 @@ pgbench options d sent to the server. This uses the client/server bandwidth extensively through a COPY. Using g causes logging to print one message - every 100,000 rows when generating data into + every 100,000 rows while generating data for the pgbench_accounts table. With G (server-side data generation), - only limited queries are sent from pgbench + only small queries are sent from the pgbench client and then data is actually generated in the server. No significant bandwidth is required for this variant, but the server will do more work. Using G causes logging not to print any progress - message when generating data into - pgbench_accounts table. + message while generating data. + + + The default initialization behavior uses client-side data + generation (equivalent to g). @@ -897,14 +898,14 @@ pgbench options d - + This utility, like most other PostgreSQL utilities, uses the environment variables supported by libpq (see ). - + The environment variable PG_COLOR specifies whether to use color in diagnostic messages. Possible values are @@ -912,7 +913,7 @@ pgbench options d never. - + Notes @@ -1011,8 +1012,10 @@ pgbench options d - Automatic Variables + pgbench Automatic Variables + + Variable @@ -1253,167 +1256,368 @@ SELECT 4 AS four \; SELECT 5 AS five \aset are built into pgbench and may be used in expressions appearing in \set. + The operators are listed in increasing precedence order. + Except as noted, operators taking two numeric inputs will produce + a double value if either input is double, otherwise they produce + an integer result. -
- pgbench Operators by Increasing Precedence - - - - Operator - Description - Example - Result - - - - - OR - logical or - 5 or 0 - TRUE - - - AND - logical and - 3 and 0 - FALSE - - - NOT - logical not - not false - TRUE - - - IS [NOT] (NULL|TRUE|FALSE) - value tests - 1 is null - FALSE - - - ISNULL|NOTNULL - null tests - 1 notnull - TRUE - - - = - is equal - 5 = 4 - FALSE - - - <> - is not equal - 5 <> 4 - TRUE - - - != - is not equal - 5 != 5 - FALSE - - - < - lower than - 5 < 4 - FALSE - - - <= - lower or equal - 5 <= 4 - FALSE - - - > - greater than - 5 > 4 - TRUE - - - >= - greater or equal - 5 >= 4 - TRUE - - - | - integer bitwise OR - 1 | 2 - 3 - - - # - integer bitwise XOR - 1 # 3 - 2 - - - & - integer bitwise AND - 1 & 3 - 1 - - - ~ - integer bitwise NOT - ~ 1 - -2 - - - << - integer bitwise shift left - 1 << 2 - 4 - - - >> - integer bitwise shift right - 8 >> 2 - 2 - - - + - addition - 5 + 4 - 9 - - - - - subtraction - 3 - 2.0 - 1.0 - - - * - multiplication - 5 * 4 - 20 - - - / - division (integer truncates the results) - 5 / 3 - 1 - - - % - modulo - 3 % 2 - 1 - - - - - opposite - - 2.0 - -2.0 - - - -
+ + pgbench Operators + + + + + Operator + + + Description + + + Example(s) + + + + + + + + boolean OR boolean + boolean + + + Logical OR + + + 5 or 0 + TRUE + + + + + + boolean AND boolean + boolean + + + Logical AND + + + 3 and 0 + FALSE + + + + + + NOT boolean + boolean + + + Logical NOT + + + not false + TRUE + + + + + + boolean IS [NOT] (NULL|TRUE|FALSE) + boolean + + + Boolean value tests + + + 1 is null + FALSE + + + + + + value ISNULL|NOTNULL + boolean + + + Nullness tests + + + 1 notnull + TRUE + + + + + + number = number + boolean + + + Equal + + + 5 = 4 + FALSE + + + + + + number <> number + boolean + + + Not equal + + + 5 <> 4 + TRUE + + + + + + number != number + boolean + + + Not equal + + + 5 != 5 + FALSE + + + + + + number < number + boolean + + + Less than + + + 5 < 4 + FALSE + + + + + + number <= number + boolean + + + Less than or equal to + + + 5 <= 4 + FALSE + + + + + + number > number + boolean + + + Greater than + + + 5 > 4 + TRUE + + + + + + number >= number + boolean + + + Greater than or equal to + + + 5 >= 4 + TRUE + + + + + + integer | integer + integer + + + Bitwise OR + + + 1 | 2 + 3 + + + + + + integer # integer + integer + + + Bitwise XOR + + + 1 # 3 + 2 + + + + + + integer & integer + integer + + + Bitwise AND + + + 1 & 3 + 1 + + + + + + ~ integer + integer + + + Bitwise NOT + + + ~ 1 + -2 + + + + + + integer << integer + integer + + + Bitwise shift left + + + 1 << 2 + 4 + + + + + + integer >> integer + integer + + + Bitwise shift right + + + 8 >> 2 + 2 + + + + + + number + number + number + + + Addition + + + 5 + 4 + 9 + + + + + + number - number + number + + + Subtraction + + + 3 - 2.0 + 1.0 + + + + + + number * number + number + + + Multiplication + + + 5 * 4 + 20 + + + + + + number / number + number + + + Division (truncates the result towards zero if both inputs are integers) + + + 5 / 3 + 1 + + + + + + integer % integer + integer + + + Modulo (remainder) + + + 3 % 2 + 1 + + + + + + - number + number + + + Negation + + + - 2.0 + -2.0 + + + + +
@@ -1428,156 +1632,298 @@ SELECT 4 AS four \; SELECT 5 AS five \aset pgbench Functions - + - Function - Return Type - Description - Example - Result + + Function + + + Description + + + Example(s) + + - abs(a) - same as a - absolute value - abs(-17) - 17 + + abs ( number ) + same type as input + + + Absolute value + + + abs(-17) + 17 + + - debug(a) - same as a - print a to stderr, - and return a - debug(5432.1) - 5432.1 + + debug ( number ) + same type as input + + + Prints the argument to stderr, + and returns the argument. + + + debug(5432.1) + 5432.1 + + - double(i) - double - cast to double - double(5432) - 5432.0 + + double ( number ) + double + + + Casts to double. + + + double(5432) + 5432.0 + + - exp(x) - double - exponential - exp(1.0) - 2.718281828459045 + + exp ( number ) + double + + + Exponential (e raised to the given power) + + + exp(1.0) + 2.718281828459045 + + - greatest(a [, ... ] ) - double if any a is double, else integer - largest value among arguments - greatest(5, 4, 3, 2) - 5 + + greatest ( number , ... ) + double if any argument is double, else integer + + + Selects the largest value among the arguments. + + + greatest(5, 4, 3, 2) + 5 + + - hash(a [, seed ] ) - integer - alias for hash_murmur2() - hash(10, 5432) - -5817877081768721676 + + hash ( value , seed ) + integer + + + This is an alias for hash_murmur2. + + + hash(10, 5432) + -5817877081768721676 + + - hash_fnv1a(a [, seed ] ) - integer - FNV-1a hash - hash_fnv1a(10, 5432) - -7793829335365542153 + + hash_fnv1a ( value , seed ) + integer + + + Computes FNV-1a hash. + + + hash_fnv1a(10, 5432) + -7793829335365542153 + + - hash_murmur2(a [, seed ] ) - integer - MurmurHash2 hash - hash_murmur2(10, 5432) - -5817877081768721676 + + hash_murmur2 ( value , seed ) + integer + + + Computes MurmurHash2 hash. + + + hash_murmur2(10, 5432) + -5817877081768721676 + + - int(x) - integer - cast to int - int(5.4 + 3.8) - 9 + + int ( number ) + integer + + + Casts to integer. + + + int(5.4 + 3.8) + 9 + + - least(a [, ... ] ) - double if any a is double, else integer - smallest value among arguments - least(5, 4, 3, 2.1) - 2.1 + + least ( number , ... ) + double if any argument is double, else integer + + + Selects the smallest value among the arguments. + + + least(5, 4, 3, 2.1) + 2.1 + + - ln(x) - double - natural logarithm - ln(2.718281828459045) - 1.0 + + ln ( number ) + double + + + Natural logarithm + + + ln(2.718281828459045) + 1.0 + + - mod(i, j) - integer - modulo - mod(54, 32) - 22 + +mod ( integer, integer ) + integer + + + Modulo (remainder) + + + mod(54, 32) + 22 + + - pi() - double - value of the constant π - pi() - 3.14159265358979323846 + + pi () + double + + + Approximate value of π + + + pi() + 3.14159265358979323846 + + - pow(x, y), power(x, y) - double - exponentiation - pow(2.0, 10), power(2.0, 10) - 1024.0 + + pow ( x, y ) + double + + + power ( x, y ) + double + + + x raised to the power of y + + + pow(2.0, 10) + 1024.0 + + - random(lb, ub) - integer - uniformly-distributed random integer in [lb, ub] - random(1, 10) - an integer between 1 and 10 + + random ( lb, ub ) + integer + + + Computes a uniformly-distributed random integer in [lb, + ub]. + + + random(1, 10) + an integer between 1 and 10 + + - random_exponential(lb, ub, parameter) - integer - exponentially-distributed random integer in [lb, ub], - see below - random_exponential(1, 10, 3.0) - an integer between 1 and 10 + + random_exponential ( lb, ub, parameter ) + integer + + + Computes an exponentially-distributed random integer in [lb, + ub], see below. + + + random_exponential(1, 10, 3.0) + an integer between 1 and 10 + + - random_gaussian(lb, ub, parameter) - integer - Gaussian-distributed random integer in [lb, ub], - see below - random_gaussian(1, 10, 2.5) - an integer between 1 and 10 + + random_gaussian ( lb, ub, parameter ) + integer + + + Computes a gaussian-distributed random integer in [lb, + ub], see below. + + + random_gaussian(1, 10, 2.5) + an integer between 1 and 10 + + - random_zipfian(lb, ub, parameter) - integer - Zipfian-distributed random integer in [lb, ub], - see below - random_zipfian(1, 10, 1.5) - an integer between 1 and 10 + + random_zipfian ( lb, ub, parameter ) + integer + + + Computes a Zipfian-distributed random integer in [lb, + ub], see below. + + + random_zipfian(1, 10, 1.5) + an integer between 1 and 10 + + - sqrt(x) - double - square root - sqrt(2.0) - 1.414213562 + + sqrt ( number ) + double + + + Square root + + + sqrt(2.0) + 1.414213562 + - +
@@ -1819,7 +2165,7 @@ END; format is used for the log files: -interval_start num_transactions sum_latency sum_latency_2 min_latency max_latency sum_lag sum_lag_2 min_lag max_lag skipped +interval_start num_transactions&zwsp; sum_latency sum_latency_2 min_latency max_latency&zwsp; sum_lag sum_lag_2 min_lag max_lag skipped where diff --git a/doc/src/sgml/seg.sgml b/doc/src/sgml/seg.sgml index 2492de911ad..8178bc20b5d 100644 --- a/doc/src/sgml/seg.sgml +++ b/doc/src/sgml/seg.sgml @@ -141,6 +141,8 @@ test=> select '6.25 .. 6.50'::seg as "pH"; Examples of Valid <type>seg</type> Input + + 5.0 @@ -248,65 +250,106 @@ test=> select '6.25 .. 6.50'::seg as "pH";
Seg GiST Operators - - - - Operator - Description - - + + + + + Operator + + + Description + + + - - - [a, b] << [c, d] - [a, b] is entirely to the left of [c, d]. That is, [a, - b] << [c, d] is true if b < c and false otherwise. - + + + + seg << seg + boolean + + + Is the first seg entirely to the left of the second? + [a, b] << [c, d] is true if b < c. + + - - [a, b] >> [c, d] - [a, b] is entirely to the right of [c, d]. That is, [a, - b] >> [c, d] is true if a > d and false otherwise. - + + + seg >> seg + boolean + + + Is the first seg entirely to the right of the second? + [a, b] >> [c, d] is true if a > d. + + - - [a, b] &< [c, d] - Overlaps or is left of — This might be better read - as does not extend to right of. It is true when - b <= d. - + + + seg &< seg + boolean + + + Does the first seg not extend to the right of the + second? + [a, b] &< [c, d] is true if b <= d. + + - - [a, b] &> [c, d] - Overlaps or is right of — This might be better read - as does not extend to left of. It is true when - a >= c. - + + + seg &> seg + boolean + + + Does the first seg not extend to the left of the + second? + [a, b] &> [c, d] is true if a >= c. + + - - [a, b] = [c, d] - Same as — The segments [a, b] and [c, d] are - identical, that is, a = c and b = d. - + + + seg = seg + boolean + + + Are the two segs equal? + + - - [a, b] && [c, d] - The segments [a, b] and [c, d] overlap. - + + + seg && seg + boolean + + + Do the two segs overlap? + + - - [a, b] @> [c, d] - The segment [a, b] contains the segment [c, d], that is, - a <= c and b >= d. - + + + seg @> seg + boolean + + + Does the first seg contain the second? + + - - [a, b] <@ [c, d] - The segment [a, b] is contained in [c, d], that is, a - >= c and b <= d. - - - + + + seg <@ seg + boolean + + + Is the first seg contained in the second? + + + +
@@ -318,33 +361,10 @@ test=> select '6.25 .. 6.50'::seg as "pH"; - The standard B-tree operators are also provided, for example - - - - - - Operator - Description - - - - - - [a, b] < [c, d] - Less than - - - - [a, b] > [c, d] - Greater than - - - - - - These operators do not make a lot of sense for any practical - purpose but sorting. These operators first compare (a) to (c), + In addition to the above operators, the usual comparison + operators shown in are + available for type seg. These operators + first compare (a) to (c), and if these are equal, compare (b) to (d). That results in reasonably good sorting in most cases, which is useful if you want to use ORDER BY with this type. diff --git a/doc/src/sgml/sepgsql.sgml b/doc/src/sgml/sepgsql.sgml index 658599306a5..0d6b1b733dc 100644 --- a/doc/src/sgml/sepgsql.sgml +++ b/doc/src/sgml/sepgsql.sgml @@ -605,7 +605,7 @@ regression=# select sepgsql_getcon(); (1 row) regression=# SELECT sepgsql_setcon('unconfined_u:unconfined_r:unconfined_t:s0-s0:c1.c4'); - sepgsql_setcon + sepgsql_setcon ---------------- t (1 row) @@ -659,45 +659,77 @@ ERROR: SELinux: security policy violation Sepgsql Functions - - - - sepgsql_getcon() returns text - - Returns the client domain, the current security label of the client. - - - - sepgsql_setcon(text) returns bool - - Switches the client domain of the current session to the new domain, - if allowed by the security policy. - It also accepts NULL input as a request to transition - to the client's original domain. - - - - sepgsql_mcstrans_in(text) returns text - Translates the given qualified MLS/MCS range into raw format if - the mcstrans daemon is running. - - - - sepgsql_mcstrans_out(text) returns text - Translates the given raw MLS/MCS range into qualified format if - the mcstrans daemon is running. - - - - sepgsql_restorecon(text) returns bool - - Sets up initial security labels for all objects within the - current database. The argument may be NULL, or the name of a specfile - to be used as alternative of the system default. - - - - + + + + + Function + + + Description + + + + + + + + sepgsql_getcon () + text + + + Returns the client domain, the current security label of the client. + + + + + + sepgsql_setcon ( text ) + boolean + + + Switches the client domain of the current session to the new domain, + if allowed by the security policy. + It also accepts NULL input as a request to transition + to the client's original domain. + + + + + + sepgsql_mcstrans_in ( text ) + text + + + Translates the given qualified MLS/MCS range into raw format if + the mcstrans daemon is running. + + + + + + sepgsql_mcstrans_out ( text ) + text + + + Translates the given raw MLS/MCS range into qualified format if + the mcstrans daemon is running. + + + + + + sepgsql_restorecon ( text ) + boolean + + + Sets up initial security labels for all objects within the + current database. The argument may be NULL, or the + name of a specfile to be used as alternative of the system default. + + + +
diff --git a/doc/src/sgml/tablefunc.sgml b/doc/src/sgml/tablefunc.sgml index ad435d6dc3e..356e2b0f002 100644 --- a/doc/src/sgml/tablefunc.sgml +++ b/doc/src/sgml/tablefunc.sgml @@ -24,83 +24,99 @@ Functions Provided - shows the functions provided + summarizes the functions provided by the tablefunc module. <filename>tablefunc</filename> Functions - - - - Function - Returns - Description - - - - - normal_rand(int numvals, float8 mean, float8 stddev) - setof float8 - - Produces a set of normally distributed random values - - - - crosstab(text sql) - setof record - - Produces a pivot table containing - row names plus N value columns, where - N is determined by the row type specified in the calling - query - - - - crosstabN(text sql) - setof table_crosstab_N - - Produces a pivot table containing - row names plus N value columns. - crosstab2, crosstab3, and - crosstab4 are predefined, but you can create additional - crosstabN functions as described below - - - - crosstab(text source_sql, text category_sql) - setof record - - Produces a pivot table - with the value columns specified by a second query - - - - crosstab(text sql, int N) - setof record - - Obsolete version of crosstab(text). - The parameter N is now ignored, since the number of - value columns is always determined by the calling query + + + + + Function - - - - - - connectby(text relname, text keyid_fld, text parent_keyid_fld - [, text orderby_fld ], text start_with, int max_depth - [, text branch_delim ]) - - connectby - - setof record - - Produces a representation of a hierarchical tree structure - - - - + + Description + + + + + + + + normal_rand ( numvals integer, mean float8, stddev float8 ) + setof float8 + + + Produces a set of normally distributed random values. + + + + + + crosstab ( sql text ) + setof record + + + Produces a pivot table containing + row names plus N value columns, where + N is determined by the row type specified + in the calling query. + + + + + + crosstabN ( sql text ) + setof table_crosstab_N + + + Produces a pivot table containing + row names plus N value columns. + crosstab2, crosstab3, and + crosstab4 are predefined, but you can create additional + crosstabN functions as described below. + + + + + + crosstab ( source_sql text, category_sql text ) + setof record + + + Produces a pivot table + with the value columns specified by a second query. + + + + + + crosstab ( sql text, N integer ) + setof record + + + Obsolete version of crosstab(text). + The parameter N is now ignored, since the + number of value columns is always determined by the calling query. + + + + + + connectby + connectby ( relname text, keyid_fld text, parent_keyid_fld text + , orderby_fld text , start_with text, max_depth integer + , branch_delim text ) + setof record + + + Produces a representation of a hierarchical tree structure. + + + +
diff --git a/doc/src/sgml/uuid-ossp.sgml b/doc/src/sgml/uuid-ossp.sgml index 54d7813d38e..460be97fdd8 100644 --- a/doc/src/sgml/uuid-ossp.sgml +++ b/doc/src/sgml/uuid-ossp.sgml @@ -37,46 +37,59 @@ Functions for UUID Generation - - - - Function - Description - - - - - uuid_generate_v1()uuid_generate_v1 - + + + + + Function + - This function generates a version 1 UUID. This involves the MAC + Description + + + + + + + + uuid_generate_v1 + uuid_generate_v1 () + uuid + + + Generates a version 1 UUID. This involves the MAC address of the computer and a time stamp. Note that UUIDs of this kind reveal the identity of the computer that created the identifier and the time at which it did so, which might make it unsuitable for certain security-sensitive applications. - - - - - uuid_generate_v1mc()uuid_generate_v1mc - - - This function generates a version 1 UUID but uses a random multicast - MAC address instead of the real MAC address of the computer. - - - - - uuid_generate_v3(namespace uuid, name text)uuid_generate_v3 - - - This function generates a version 3 UUID in the given namespace using - the specified input name. The namespace should be one of the special - constants produced by the uuid_ns_*() functions shown - in . (It could be any UUID in theory.) The name is an identifier - in the selected namespace. - + + + + + uuid_generate_v1mc + uuid_generate_v1mc () + uuid + + + Generates a version 1 UUID, but uses a random multicast + MAC address instead of the real MAC address of the computer. + + + + + + uuid_generate_v3 + uuid_generate_v3 ( namespace uuid, name text ) + uuid + + + Generates a version 3 UUID in the given namespace using + the specified input name. The namespace should be one of the special + constants produced by the uuid_ns_*() functions + shown in . (It could be any UUID + in theory.) The name is an identifier in the selected namespace. + For example: @@ -88,82 +101,106 @@ SELECT uuid_generate_v3(uuid_ns_url(), 'http://www.postgresql.org'); derived from the generated UUID. The generation of UUIDs by this method has no random or environment-dependent element and is therefore reproducible. + + + + + + uuid_generate_v4 () + uuid - - - - uuid_generate_v4() - - This function generates a version 4 UUID, which is derived entirely + Generates a version 4 UUID, which is derived entirely from random numbers. + + + + + + uuid_generate_v5 ( namespace uuid, name text ) + uuid - - - - uuid_generate_v5(namespace uuid, name text) - - This function generates a version 5 UUID, which works like a version 3 + Generates a version 5 UUID, which works like a version 3 UUID except that SHA-1 is used as a hashing method. Version 5 should be preferred over version 3 because SHA-1 is thought to be more secure than MD5. - - - - - + + + +
Functions Returning UUID Constants - - - - uuid_nil() - - - A nil UUID constant, which does not occur as a real UUID. + + + + + Function - - - - uuid_ns_dns() - - Constant designating the DNS namespace for UUIDs. + Description + + + + + + + + uuid_nil () + uuid - - - - uuid_ns_url() - - Constant designating the URL namespace for UUIDs. + Returns a nil UUID constant, which does not occur as a + real UUID. + + + + + + uuid_ns_dns () + uuid - - - - uuid_ns_oid() - - Constant designating the ISO object identifier (OID) namespace for + Returns a constant designating the DNS namespace for UUIDs. + + + + + + uuid_ns_url () + uuid + + + Returns a constant designating the URL namespace for UUIDs. + + + + + + uuid_ns_oid () + uuid + + + Returns a constant designating the ISO object identifier (OID) namespace for UUIDs. (This pertains to ASN.1 OIDs, which are unrelated to the OIDs used in PostgreSQL.) + + + + + + uuid_ns_x500 () + uuid - - - - uuid_ns_x500() - - Constant designating the X.500 distinguished name (DN) namespace for - UUIDs. - - - - - + Returns a constant designating the X.500 distinguished name (DN) + namespace for UUIDs. + + + +
diff --git a/doc/src/sgml/xml2.sgml b/doc/src/sgml/xml2.sgml index 560faa000ec..a61ec44337f 100644 --- a/doc/src/sgml/xml2.sgml +++ b/doc/src/sgml/xml2.sgml @@ -36,161 +36,135 @@ shows the functions provided by this module. These functions provide straightforward XML parsing and XPath queries. - All arguments are of type text, so for brevity that is not shown. - Functions - - - - Function - Returns - Description - - - - - - - xml_valid(document) - - - - bool - - + <filename>xml2</filename> Functions + + + + + Function + - This parses the document text in its parameter and returns true if the + Description + + + + + + + + xml_valid ( document text ) + boolean + + + Parses the given document and returns true if the document is well-formed XML. (Note: this is an alias for the standard PostgreSQL function xml_is_well_formed(). The name xml_valid() is technically incorrect since validity and well-formedness have different meanings in XML.) + + + + + + xpath_string ( document text, query text ) + text - - - - - - xpath_string(document, query) - - - - text - - - These functions evaluate the XPath query on the supplied document, and - cast the result to the specified type. + Evaluates the XPath query on the supplied document, and + casts the result to text. + + + + + + xpath_number ( document text, query text ) + real - - - - - - xpath_number(document, query) - - - - float4 - - - - - - xpath_bool(document, query) - - - - bool - - - - - - xpath_nodeset(document, query, toptag, itemtag) - - - - text - - - This evaluates query on document and wraps the result in XML tags. If - the result is multivalued, the output will look like: + Evaluates the XPath query on the supplied document, and + casts the result to real. + + + + + + xpath_bool ( document text, query text ) + boolean + + + Evaluates the XPath query on the supplied document, and + casts the result to boolean. + + + + + + xpath_nodeset ( document text, query text, toptag text, itemtag text ) + text + + + Evaluates the query on the document and wraps the result in XML + tags. If the result is multivalued, the output will look like: <toptag> <itemtag>Value 1 which could be an XML fragment</itemtag> <itemtag>Value 2....</itemtag> </toptag> - If either toptag or itemtag is an empty string, the relevant tag is omitted. + If either toptag + or itemtag is an empty string, the relevant tag + is omitted. + + + + + + xpath_nodeset ( document text, query text, itemtag text ) + text + + + Like xpath_nodeset(document, query, toptag, itemtag) but result omits toptag. + + + + + + xpath_nodeset ( document text, query text ) + text - - - - - - xpath_nodeset(document, query) - - - - text - - Like xpath_nodeset(document, query, toptag, itemtag) but result omits both tags. + + + + + + xpath_list ( document text, query text, separator text ) + text - - - - - - xpath_nodeset(document, query, itemtag) - - - - text - - - Like xpath_nodeset(document, query, toptag, itemtag) but result omits toptag. + Evaluates the query on the document and returns multiple values + separated by the specified separator, for example Value + 1,Value 2,Value 3 if separator + is ,. + + + + + + xpath_list ( document text, query text ) + text - - - - - - xpath_list(document, query, separator) - - - - text - - - This function returns multiple values separated by the specified - separator, for example Value 1,Value 2,Value 3 if - separator is ,. - - - - - - - xpath_list(document, query) - - - - text - - - This is a wrapper for the above function that uses , - as the separator. - - - - + This is a wrapper for the above function that uses , + as the separator. + + + +
@@ -217,6 +191,8 @@ xpath_table(text key, text document, text relation, text xpaths, text criteria) <function>xpath_table</function> Parameters + + Parameter