SQL Column Operator Functions

## Functions

hash | SqlUtil::cop_append (any column, string arg)
| returns a hash for the `"append"` operator with the given argument More...
hash | SqlUtil::cop_as (any column, string arg)
| returns a hash for the `"as"` operator with the given argument More...
hash | SqlUtil::cop_avg (any column)
| returns a hash for the `"avg"` operator; returns average column values More...
hash | SqlUtil::cop_cast (any column, string arg, *any arg1, *any arg2)
| returns a hash for the `"cast"` operator with the given argument(s) More...
hash | SqlUtil::cop_coalesce (any col1, any col2)
| returns a hash for the `"coalesce"` operator with the given column arguments; the first non-NULL column value will be returned More...
hash | SqlUtil::cop_count (any column="")
| returns a hash for the `"count"` operator; returns row counts More...
hash | SqlUtil::cop_distinct (any column)
| returns a hash for the `"distinct"` operator with the given argument; returns distinct column values More...
hash | SqlUtil::cop_divide (any column1, any column2)
| returns a hash for the `"/"` operator with the given arguments More...
hash | SqlUtil::cop_lower (any column)
| returns a hash for the `"lower"` operator with the given argument; returns a column value in lower case More...
hash | SqlUtil::cop_max (any column)
| returns a hash for the `"max"` operator; returns maximum column values More...
hash | SqlUtil::cop_min (any column)
| returns a hash for the `"min"` operator; returns minimum column values More...
hash | SqlUtil::cop_minus (any column1, any column2)
| returns a hash for the `"-"` operator with the given arguments More...
hash | SqlUtil::cop_multiply (any column1, any column2)
| returns a hash for the `"*"` operator with the given arguments More...
hash | SqlUtil::cop_over (any column, string arg)
| returns a hash for the `"over"` clause More...
hash | SqlUtil::cop_plus (any column1, any column2)
| returns a hash for the `"+"` operator with the given arguments More...
hash | SqlUtil::cop_prepend (any column, string arg)
| returns a hash for the `"prepend"` operator with the given argument More...
hash | SqlUtil::cop_seq (string seq, *string as)
| returns a hash for the `"seq"` operator with the given argument giving the sequence name whose value should be returned More...
hash | SqlUtil::cop_seq_currval (string seq, *string as)
| returns a hash for the `"seq_currval"` operator with the given argument giving the sequence name whose current value should be returned More...
hash | SqlUtil::cop_substr (any column, int start, *int count)
| returns a hash for the `"substr"` operator with the given arguments; returns a substring of a column value More...
hash | SqlUtil::cop_sum (any column)
| returns a hash for the `"sum"` operator; returns the total sum of a numeric column. More...
hash | SqlUtil::cop_upper (any column)
| returns a hash for the `"upper"` operator with the given argument; returns a column value in upper case More...
hash | SqlUtil::cop_value (any arg)
| returns a hash for the `"value"` (literal) operator with the given argument More...
hash | SqlUtil::cop_year (any column)
| returns a hash for the `"year"` operator with the given argument More...
hash | SqlUtil::cop_year_day (any column)
| returns a hash for the `"year_day"` operator with the given argument More...
hash | SqlUtil::cop_year_hour (any column)
| returns a hash for the `"year_hour"` operator with the given argument More...
hash | SqlUtil::cop_year_month (any column)
| returns a hash for the `"year_month"` operator with the given argument More...
hash | SqlUtil::make_cop (string cop, any column, any arg)
| returns a hash with `cop`, `column`, and `arg` keys More...

## Detailed Description

These are functions that can be used in the `"columns"` argument for select statements:

- cop_as(): rename columns
- cop_cast(): convert column value into another datatype
- cop_prepend(): prepend a string to the output of a column
- cop_append(): append a string to the output of a column
- cop_value(): return a constant value (SQL literal) in a column
- cop_upper(): return a column in upper case
- cop_lower(): return a column in lower case

Column operator functions can be nested as in the following example:

Example:
  *hash rows = t.selectRows(("columns": cop_as(cop_lower("permission_type"), "perm"), "where": ("permission_type": "USER"), "limit": 100, "offset": 200));

## Function Documentation

hash SqlUtil::cop_append | ( | any | column,
|  | string | arg
| ) |  |

returns a hash for the `"append"` operator with the given argument

Example:
  *list rows = table.selectRows(("columns": ("id", cop_append("name", "-migrated")), "where": ("type": "user")));

Parameters

  column | the column specification for the column (string name or dot notation for use in joins)
  arg | the text to append (ie concatenate) to the row values in the output column

Returns
  a column operator description hash corresponding to the arguments for use in the columns argument of a select option hash

hash SqlUtil::cop_as | ( | any | column,
|  | string | arg
| ) |  |

returns a hash for the `"as"` operator with the given argument

Example:
  *list rows = table.selectRows(("columns": ("id", "name", cop_as("errors", "error_count")), "where": ("type": "user")));

Parameters

  column | the column specification for the column (string name or dot notation for use in joins) or any other column "cop_..." function
  arg | the new name of the output column

Returns
  a column operator description hash corresponding to the arguments for use in the columns argument of a select option hash

See also
  SqlUtil::cop_value for SQL literals handling

hash SqlUtil::cop_avg | ( | any | column | ) |

returns a hash for the `"avg"` operator; returns average column values

Example:
  *list rows = table.selectRows(("columns": (cop_avg("quantity")), "where": ("order_type": "wholesale")));

Parameters

  column | the column specification for the column (string name or dot notation for use in joins)

Returns
  a column operator description hash corresponding to the arguments for use in the columns argument of a select option hash

hash SqlUtil::cop_cast | ( | any | column,
|  | string | arg,
|  | *any | arg1,
|  | *any | arg2
| ) |  |

returns a hash for the `"cast"` operator with the given argument(s)

Example:
  *list rows = table.selectRows(("columns": ("id", cop_cast("id", "string")), "where": ("type": "user")));

Parameters

  column | the column specification for the column (string name or dot notation for use in joins) or any other column "cop_..." function
  arg | the new datatype to cast the column value(s) to
  arg1 | optional, type dependent, specification (e.g. size or precision)
  arg2 | optional, type dependent, specification (e.g. scale)

Returns
  a column operator description hash corresponding to the arguments for use in the columns argument of a select option hash

See also
  SqlUtil::cop_value for SQL literals handling

hash SqlUtil::cop_coalesce | ( | any | col1,
|  | any | col2
| ) |  |

returns a hash for the `"coalesce"` operator with the given column arguments; the first non-NULL column value will be returned

Example:
  *list rows = table.selectRows(("columns": ("first_name", "last_name", cop_colesce("first_name", "last_name")), "where": ("type": "user")));

Parameters

  col1 | the name or column operator hash for the first value
  col2 | the name or column operator hash for the second value, additional values should follow this argument

Returns
  a column operator description hash corresponding to the arguments for use in the columns argument of a select option hash

Exceptions

  COALESCE-ERROR | the arguments must be either string column designators or column operator hashes

hash SqlUtil::cop_count | ( | any | column = `""` | ) |

returns a hash for the `"count"` operator; returns row counts

Example:
  *list rows = table.selectRows(("columns": ("account_type", cop_count()), "where": ("type": "user"), "groupby": "account_type"));

Returns
  a column operator description hash corresponding to the arguments for use in the columns argument of a select option hash

hash SqlUtil::cop_distinct | ( | any | column | ) |

returns a hash for the `"distinct"` operator with the given argument; returns distinct column values

Example:
  *list rows = table.selectRows(("columns": ("id", cop_distinct("name")), "where": ("type": "user")));

Parameters

  column | the column specification for the column (string name or dot notation for use in joins)

Returns
  a column operator description hash corresponding to the arguments for use in the columns argument of a select option hash

hash SqlUtil::cop_divide | ( | any | column1,
|  | any | column2
| ) |  |

returns a hash for the `"/"` operator with the given arguments

Example:
  *list rows = table.selectRows(("columns": ("id", "name", cop_divide("complete_count", "error_count")), "where": ("type": "user")));

Parameters

  column1 | the column specification for the first argument (string name or dot notation for use in joins)
  column2 | the column specification for the second argument (string name or dot notation for use in joins)

Returns
  a column operator description hash corresponding to the arguments for use in the columns argument of a select option hash

hash SqlUtil::cop_lower | ( | any | column | ) |

returns a hash for the `"lower"` operator with the given argument; returns a column value in lower case

Example:
  *list rows = table.selectRows(("columns": ("id", cop_lower("name")), "where": ("type": "user")));

Parameters

  column | the column specification for the column (string name or dot notation for use in joins)

Returns
  a column operator description hash corresponding to the arguments for use in the columns argument of a select option hash

hash SqlUtil::cop_max | ( | any | column | ) |

returns a hash for the `"max"` operator; returns maximum column values

Example:
  *list rows = table.selectRows(("columns": (cop_max("id")), "where": ("type": "user")));

Parameters

  column | the column specification for the column (string name or dot notation for use in joins)

Returns
  a column operator description hash corresponding to the arguments for use in the columns argument of a select option hash

hash SqlUtil::cop_min | ( | any | column | ) |

returns a hash for the `"min"` operator; returns minimum column values

Example:
  *list rows = table.selectRows(("columns": (cop_min("id")), "where": ("type": "user")));

Parameters

  column | the column specification for the column (string name or dot notation for use in joins)

Returns
  a column operator description hash corresponding to the arguments for use in the columns argument of a select option hash

hash SqlUtil::cop_minus | ( | any | column1,
|  | any | column2
| ) |  |

returns a hash for the `"-"` operator with the given arguments

Example:
  *list rows = table.selectRows(("columns": ("id", "name", cop_minus("complete_count", "error_count")), "where": ("type": "user")));

Parameters

  column1 | the column specification for the first argument (string name or dot notation for use in joins)
  column2 | the column specification for the second argument (string name or dot notation for use in joins)

Returns
  a column operator description hash corresponding to the arguments for use in the columns argument of a select option hash

hash SqlUtil::cop_multiply | ( | any | column1,
|  | any | column2
| ) |  |

returns a hash for the `"*"` operator with the given arguments

Example:
  *list rows = table.selectRows(("columns": ("id", "name", cop_multiply("complete_count", "error_count")), "where": ("type": "user")));

Parameters

  column1 | the column specification for the first argument (string name or dot notation for use in joins)
  column2 | the column specification for the second argument (string name or dot notation for use in joins)

Returns
  a column operator description hash corresponding to the arguments for use in the columns argument of a select option hash

hash SqlUtil::cop_over | ( | any | column,
|  | string | arg
| ) |  |

returns a hash for the `"over"` clause

Example:
  *list rows = table.selectRows(("columns": ("account_type", cop_count(), cop_as(cop_over(cop_max("qty"), "account_id"), "max_qty_per_account")), "where": ("type": "user"), "groupby": "account_type"));

Returns
  a column operator description hash corresponding to the arguments for use in the columns argument of a select option hash

hash SqlUtil::cop_plus | ( | any | column1,
|  | any | column2
| ) |  |

returns a hash for the `"+"` operator with the given arguments

Example:
  *list rows = table.selectRows(("columns": ("id", "name", cop_plus("complete_count", "error_count")), "where": ("type": "user")));

Parameters

  column1 | the column specification for the first argument (string name or dot notation for use in joins)
  column2 | the column specification for the second argument (string name or dot notation for use in joins)

Returns
  a column operator description hash corresponding to the arguments for use in the columns argument of a select option hash

hash SqlUtil::cop_prepend | ( | any | column,
|  | string | arg
| ) |  |

returns a hash for the `"prepend"` operator with the given argument

Example:
  *list rows = table.selectRows(("columns": ("id", cop_prepend("name", "migrated-")), "where": ("type": "user")));

Parameters

  column | the column specification for the column (string name or dot notation for use in joins)
  arg | the text to prepend to the row values in the output column

Returns
  a column operator description hash corresponding to the arguments for use in the columns argument of a select option hash

hash SqlUtil::cop_seq | ( | string | seq,
|  | *string | as
| ) |  |

returns a hash for the `"seq"` operator with the given argument giving the sequence name whose value should be returned

Example:
  *list rows = table.selectRows(("columns": ("id", "name", cop_seq("xid", "xis")), "where": ("type": "user")));

Parameters

  seq | the name of the sequence whose value should be returned
  as | an optional column name that should be returned for the sequence value (so that SqlUtil::cop_as() need not be used)

Returns
  a column operator description hash corresponding to the arguments for use in the columns argument of a select option hash

hash SqlUtil::cop_seq_currval | ( | string | seq,
|  | *string | as
| ) |  |

returns a hash for the `"seq_currval"` operator with the given argument giving the sequence name whose current value should be returned

Example:
  *list rows = table.selectRows(("columns": ("id", "name", cop_seq("xid", "xid_val"), cop_seq_currval("xid", "xid_current")), "where": ("type": "user")));

Parameters

  seq | the name of the sequence whose current value should be returned
  as | an optional column name that should be returned for the sequence value (so that SqlUtil::cop_as() need not be used)

Returns
  a column operator description hash corresponding to the arguments for use in the columns argument of a select option hash

hash SqlUtil::cop_substr | ( | any | column,
|  | int | start,
|  | *int | count
| ) |  |

returns a hash for the `"substr"` operator with the given arguments; returns a substring of a column value

Example:
  *list rows = table.selectRows(("columns": ("id", cop_substr("name", 1, 1)), "where": ("type": "user")));

Parameters

  column | the column specification for the column (string name or dot notation for use in joins)
  start | position where the substring starts
  count | length of the substring in characters

Returns
  a column operator description hash corresponding to the arguments for use in the columns argument of a select option hash

hash SqlUtil::cop_sum | ( | any | column | ) |

returns a hash for the `"sum"` operator; returns the total sum of a numeric column.

Example:
  *list rows = table.selectRows(("columns": (cop_sum("quantity")), "where": ("order_type": "wholesale")));

Parameters

  column | the column specification for the column (string name or dot notation for use in joins)

Returns
  a column operator description hash corresponding to the arguments for use in the columns argument of a select option hash

hash SqlUtil::cop_upper | ( | any | column | ) |

returns a hash for the `"upper"` operator with the given argument; returns a column value in upper case

Example:
  *list rows = table.selectRows(("columns": ("id", cop_upper("name")), "where": ("type": "user")));

Parameters

  column | the column specification for the column (string name or dot notation for use in joins)

Returns
  a column operator description hash corresponding to the arguments for use in the columns argument of a select option hash

hash SqlUtil::cop_value | ( | any | arg | ) |

returns a hash for the `"value"` (literal) operator with the given argument

Example:
  *list rows = table.selectRows(("columns": ("id", "name", cop_value(100)), "where": ("type": "user")));

Parameters

  arg | the value to be returned in the column

Returns
  a column operator description hash corresponding to the arguments for use in the columns argument of a select option hash

SQL literals can be useful in some cases - as dummy values for select statements where there is exact columns required, unions, expected values for `arc.insertFromIterator`(src.getRowIterator(sh)) "insert as select", etc.

The term literal refers to a fixed data value. For example, 123, 'foobar' etc.

Mapping of Qore values to literals:

Qore Type | SQL Type | Qore Example | SQL interpretation
Integer | NUMBER as it is | `123` | `123`
Float | NUMBER as it is | `12.3` | `12.3`
Numeric | NUMBER as it is | `1.2n` | `1.2`
Date | String representation of the date using DB native implementation like TO_TIMESTAMP for Oracle. | `now()` | `to_timestamp`('20150421104825000000', 'YYYYMMDDHH24MISSFF6')
Bool | Internal representation of the bool value using DB native implementation | `True` | `1`
String | Standard and escaped string literal. No additional literal methods like Oracle's `nq{foobar}` are supported now | `"foo bar"` | `'foo` bar'
`NULL` | Direct null literal | `NULL` | `null`
`NOTHING` | Direct null literal | `NOTHING` | `null`

Note
  Passing an existing SQL function name as a value to the op_value does not result in function call. The string value is escaped as it is. Example: sysdate becomes 'sysdate'. See example below.

The most useful SqlUtil::cop_value usage is with cooperation of SqlUtil::cop_as which allows nice and human readable column name aliases.

Warning
  Using SqlUtil::cop_value without SqlUtil::cop_as can result in errors depending on the DB backend. For example Oracle's use of `cop_value(1), cop_value(True)` ends with `ORA-00918: column ambiguously defined` because both values are interpreted as 1 in the resulting SQL.

Example

%new-style
%requires SqlUtil
DatasourcePool ds("oracle:pvanek_omq/omq@xbox(al32utf8)");
Database db(ds);
Table t(ds, "dual");
hash sh = (
"columns" : (
cop_as(cop_value(1), "as_int"),
cop_as(cop_value(1.2), "as_float"),
cop_as(cop_value(3.2n), "as_numeric"),
cop_as(cop_value(now()), "as_date"),
cop_as(cop_value("foo bar"), "as_string"),
cop_as(cop_value("sysdate"), "as_function_call"),
cop_as(cop_value(True), "as_bool"),
cop_as(cop_value(NULL), "as_null"),
cop_as(cop_value(NOTHING), "as_nothing"),
),
);
string sql;
on_exit { printf("sql: %s\n", sql); }
printf("%N\n", t.selectRow(sh, \sql));
# results in:
hash: (9 members)
as_int : 1
as_float : 1.2
as_numeric : 3.2
as_date : 2015-04-21 10:56:57.000000 Tue +02:00 (CEST)
as_string : "foo bar"
as_function_call : "sysdate"
as_bool : 1
as_null : <NULL>
as_nothing : <NULL>
sql: select 1 as as_int,1.2 as as_float,3.2 as as_numeric,to_timestamp('20150421105657000000', 'YYYYMMDDHH24MISSFF6') as as_date,'foo bar' as as_string,'sysdate' as as_function_call,1 as as_bool,null as as_null,null as as_nothing from pvanek_omq.workflows fetch next %v rows only

hash SqlUtil::cop_year | ( | any | column | ) |

returns a hash for the `"year"` operator with the given argument

Example:
  *list rows = table.selectRows(("columns": ("id", "name", cop_year("error_time")), "where": ("type": "user")));

Parameters

  column | the column specification for the column (string name or dot notation for use in joins)

Returns
  a column operator description hash corresponding to the arguments for use in the columns argument of a select option hash

hash SqlUtil::cop_year_day | ( | any | column | ) |

returns a hash for the `"year_day"` operator with the given argument

Example:
  *list rows = table.selectRows(("columns": ("id", "name", cop_year_day("error_time")), "where": ("type": "user")));

Parameters

  column | the column specification for the column (string name or dot notation for use in joins)

Returns
  a column operator description hash corresponding to the arguments for use in the columns argument of a select option hash

hash SqlUtil::cop_year_hour | ( | any | column | ) |

returns a hash for the `"year_hour"` operator with the given argument

Example:
  *list rows = table.selectRows(("columns": ("id", "name", cop_year_hour("error_time")), "where": ("type": "user")));

Parameters

  column | the column specification for the column (string name or dot notation for use in joins)

Returns
  a column operator description hash corresponding to the arguments for use in the columns argument of a select option hash

hash SqlUtil::cop_year_month | ( | any | column | ) |

returns a hash for the `"year_month"` operator with the given argument

Example:
  *list rows = table.selectRows(("columns": ("id", "name", cop_year_month("error_time")), "where": ("type": "user")));

Parameters

  column | the column specification for the column (string name or dot notation for use in joins)

Returns
  a column operator description hash corresponding to the arguments for use in the columns argument of a select option hash

hash SqlUtil::make_cop | ( | string | cop,
|  | any | column,
|  | any | arg
| ) |  |

returns a hash with `cop`, `column`, and `arg` keys

Parameters

  cop | the column operator (one of SQL Column Operators)
  column | the column name
  arg | the argument to the operator

Returns
  a column operator description hash corresponding to the arguments for use in the columns argument of a select option hash

Note
  Normally this function is not called directly, but rather by the other column operator functions