COMMENT ON SCHEMA util IS '

IMPORTANT: Functions must always return NULL in place of '''' (the empty string). This ensures that empty strings do not find their way into VegBIEN.

NOTE: IMMUTABLE SQL-language functions should never be declared STRICT, because this prevents them from being inlined. inlining can create a significant speed improvement (7x+), by avoiding function calls and enabling additional constant folding.

';

COMMENT ON FUNCTION _and("0" boolean, "1" boolean, "2" boolean, "3" boolean, "4" boolean) IS '

_and() ignores NULL values, while AND combines them with the other values to potentially convert true to NULL. AND should be used with required fields, and _and() with optional fields.

';

COMMENT ON FUNCTION _or("0" boolean, "1" boolean, "2" boolean, "3" boolean, "4" boolean) IS '

_or() ignores NULL values, while OR combines them with the other values to potentially convert false to NULL. OR should be used with required fields, and _or() with optional fields.

';

COMMENT ON FUNCTION added_cols(table_ regclass, names regclass) IS '

gets table_''s added columns (all the columns not in the original data)

';

COMMENT ON FUNCTION array_length("array" anyarray, dimension integer) IS '

returns 0 instead of NULL for empty arrays

';

COMMENT ON FUNCTION cluster_once(table_ regclass, index regclass) IS '

idempotent

';

COMMENT ON FUNCTION col_default_value(col col_ref, ret_type_null anyelement) IS '

ret_type_null: NULL::ret_type

';

COMMENT ON FUNCTION create_if_not_exists(sql text) IS '

idempotent

';

COMMENT ON FUNCTION derived_cols(table_ regclass, names regclass) IS '

gets table_''s derived columns (all the columns not in the names table)

';

COMMENT ON FUNCTION diff_cols(left_query text, right_query text, col_type_null anyelement, OUT left_ anyelement, OUT right_ anyelement) IS '

col_type_null (*required*): NULL::col_type

COMMENT ON FUNCTION diff_views(left_view regclass, right_view regclass, col_type_null anyelement, OUT left_ anyelement, OUT right_ anyelement) IS '

col_type_null (*required*): NULL::col_type

COMMENT ON FUNCTION do_optionally_ignore(sql text, ignore boolean) IS '

idempotent

';

COMMENT ON FUNCTION drop_column(col col_ref) IS '

idempotent

';

COMMENT ON FUNCTION drop_table(table_ text) IS '

idempotent

';

COMMENT ON FUNCTION drop_view(view_ text) IS '

idempotent

';

COMMENT ON FUNCTION empty_array(elem_type_null anyelement) IS '

constructs proper empty 1-dimensional array whose dimensions are not NULL ( ''{}''::text[] does not do this)

';

COMMENT ON FUNCTION eval2col_pair(sql text, col_type_null anyelement, OUT left_ anyelement, OUT right_ anyelement) IS '

col_type_null (*required*): NULL::col_type

';

COMMENT ON FUNCTION eval2set(sql text, ret_type_null anyelement) IS '

ret_type_null: NULL::ret_type

';

COMMENT ON FUNCTION eval2val(sql text, ret_type_null anyelement) IS '

ret_type_null: NULL::ret_type

';

COMMENT ON FUNCTION eval_expr(sql text, ret_type_null anyelement) IS '

ret_type_null: NULL::ret_type

';

COMMENT ON FUNCTION eval_expr_passthru(sql text, ret_type_null anyelement) IS '

sql: can be NULL, which will be passed through

ret_type_null: NULL::ret_type

';

COMMENT ON FUNCTION explain2table(sql text, table_ regclass) IS '

usage:

$$);

';

COMMENT ON FUNCTION fix_array("array" anyarray) IS '

ensures that an array will always have proper non-NULL dimensions

';

COMMENT ON FUNCTION force_recreate(cmd text, users text[]) IS '

idempotent

users: not necessary to provide this because it will be autopopulated

';

COMMENT ON FUNCTION force_update_view(view_ text, query text) IS '

idempotent

';

COMMENT ON FUNCTION hstore(keys text[], value text) IS '

avoids repeating the same value for each key

';

COMMENT ON FUNCTION ifnull(value anyelement, null_ anyelement) IS '

equivalent to MySQL''s IFNULL() (Postgres auto-lowercases the name)

';

COMMENT ON FUNCTION map_nulls(nulls text[], value anyelement) IS '

due to dynamic inlining[1], this is just as fast as util._map() which it wraps[2].

also, /inputs/REMIB/Specimen/postprocess.sql > country takes the same amount of time (56000 ms) to build with map_nulls() as with a literal hstore.

';

COMMENT ON FUNCTION materialize_query(table_ text, sql text) IS '

idempotent

';

COMMENT ON FUNCTION materialize_view(table_ text, view_ regclass) IS '

idempotent

';

COMMENT ON COLUMN $$||$1.table_||$$.$$||quote_ident($1.name)||$$ IS '

constant

';

COMMENT ON FUNCTION mk_const_col(col col_ref, value anyelement) IS '

idempotent

';

COMMENT ON FUNCTION mk_derived_col(col col_ref, expr text, overwrite boolean) IS '

idempotent

';

COMMENT ON FUNCTION mk_source_col(table_ regclass) IS '

idempotent

';

COMMENT ON FUNCTION mk_subset_by_row_num_no_sort_func(view_ regclass) IS '

creates subset function which turns off enable_sort

';

COMMENT ON FUNCTION nulls_map(nulls text[]) IS '

for use with _map()

';

COMMENT ON FUNCTION rename_cols(table_ regclass, renames anyelement) IS '

idempotent

';

COMMENT ON FUNCTION reset_col_names(table_ regclass, names regclass) IS '

idempotent.

alters the names table, so it will need to be repopulated after running this function.

';

COMMENT ON FUNCTION schema_bundle_get_schemas(schema_bundle text) IS '

a schema bundle is a group of schemas with a common prefix

';

COMMENT ON FUNCTION set_col_names(table_ regclass, names regclass) IS '

idempotent

';

COMMENT ON FUNCTION set_col_names_with_metadata(table_ regclass, names regclass) IS '

idempotent.

the metadata mappings must be *last* in the names table.

';

COMMENT ON FUNCTION set_col_types(table_ regclass, col_casts col_cast[]) IS '

idempotent

';

COMMENT ON FUNCTION table_flag__get(table_ regclass, flag text) IS '

gets whether a status flag is set by the presence of a table constraint

';

COMMENT ON FUNCTION table_flag__set(table_ regclass, flag text) IS '

stores a status flag by the presence of a table constraint.

idempotent.

';

COMMENT ON FUNCTION table_nulls_mapped__get(table_ regclass) IS '

gets whether a table''s NULL-equivalent strings have been replaced with NULL

';

COMMENT ON FUNCTION table_nulls_mapped__set(table_ regclass) IS '

sets that a table''s NULL-equivalent strings have been replaced with NULL.

idempotent.

';

COMMENT ON FUNCTION to_global_col_names(table_ regclass) IS '

idempotent

';

COMMENT ON FUNCTION "trim"(table_ regclass, names regclass) IS '

trims table_ to include only columns in the original data.

idempotent.

';

COMMENT ON FUNCTION truncate(table_ regclass) IS '

idempotent

';

COMMENT ON FUNCTION try_create(sql text) IS '

idempotent

';

COMMENT ON FUNCTION try_mk_derived_col(col col_ref, expr text) IS '

idempotent

';

COMMENT ON FUNCTION type_qual(value anyelement) IS '

a type''s NOT NULL qualifier

';

COMMENT ON FUNCTION type_qual_name(type regtype) IS '

a type''s schema-qualified name

';

COMMENT ON AGGREGATE all_same(anyelement) IS '

includes NULLs in comparison

';

COMMENT ON OPERATOR => (text[], text) IS '

usage: array[''key1'', ...]::text[] => ''value''

';

COMMENT ON OPERATOR ||% (text, text) IS '

% indicates an identifier, as in Perl hashes and one of the x86 assembler syntaxes for registers

';