ADQL-2_0-Err-2 < IVOA

---++ !ADQL-2.0 Erratum 2: Mathematical Functions' Table issues

Author: DAL WG

Date last changed: 2017-10-09

---+++ Rationale

IVOA DAL mailing list [[http://mail.ivoa.net/pipermail/dal/2016-July/007549.html][thread on July 2016]] highlighted a possible issue with the description of the *MOD* function. Discussion went on also on [[http://mail.ivoa.net/pipermail/dal/2016-July/007551.html][this other thread]].

Subsequently [[http://mail.ivoa.net/pipermail/dal/2016-July/007560.html][a different thread]] highlighted other mismatches between *Table 1* (Mathematical functions) descriptions and the !ADQL-2.0 grammar.

Here follows what emerged as possible erratum content from those discussions.

*MOD function description*

Considering what current TAP-1.0 services using ADQL implement and the usual SQL definition of the modulo operator:

M % N = R

with
   * R having the same sign as M
   * |R| is less than |N|
   * M = K * N + R for a given integer K
The definition of _mod(x, y)_ in [[http://www.ivoa.net/Documents/cover/ADQL-20081030.html][ADQL-2.0]] should be amended to _"Returns the remainder of x/y"_. It should also be made clear, maybe in a future revision, to follow the above rules for the remainder and its sign.

*RAND optional seed*

!ADQL !BNF grammar (page 29 of !ADQL-2.0) reports the =unsigned_integer x= to be an optional argument (the seed) to the random mathematical function. This is not made explicit in the description in Table 1.

We suggest to amend the description changing the final _"where x is a seed"_ into _"where x is an optional seed"_ value.

*ROUND optional places number*

!ADQL !BNF grammar (pages 29-30 of !ADQL-2.0) reports the =signed_integer n= of ROUND(x, n) to be an optional argument. This signed integer number of places to round the value of x to is not made explicit to be optional in Table 1 description. Also, as per SQL standard, it should default to 0 when not explicitly present.

We suggest to amend the description of round(x, n) in Table 1 by adding a final sentence reading _"The integer n is optional and its value should default to 0."_.

*TRUNCATE optional places number*

!ADQL !BNF grammar (page 30 of !ADQL-2.0) reports the =signed_integer n= of TRUNCATE(x, n) to be an optional argument. This signed integer number of places to truncate the value of x to is not made explicit to be optional in Table 1 description. Also, as per SQL standard, it should default to 0 when not explicitly present.

We suggest to amend the description of truncate(x, n) in Table 1 by adding a final sentence reading _"The integer n is optional and its value should default to 0."_.

---+++ Erratum Content

Table 1 on page 8 of the [[http://www.ivoa.net/documents/cover/ADQL-20081030.html][ADQL-2.0]] recommendation reports the following descriptions for the hereby discussed mathematical functions:
   $ mod(x, y): Returns the remainder of y/x.
   $ rand(x): Returns a random value between 0.0 and 1.0, where x is a seed value.
   $ round(x, n): Rounds double value x to n number of decimal places, with the default being to round to the nearest integer. To round to the left of the decimal point, a negative number should be provided.
   $ truncate(x, n): Returns the result of truncating the argument x to n decimal places.

This erratum amends these descriptions, given what's discussed in the rationale of this erratum, *substituting* them with the following ones:
   $ mod(x, y): Returns the remainder of *x/y*.
   $ rand(x): Returns a random value between 0.0 and 1.0.  *The
    optional argument, originally intended to provide a random seed,
    has undefined semantics.  Query writers are advised to use the
    form without the argument.*
   $ round(x, n): Rounds double value x to n number of decimal places, with the default being to round to the nearest integer. To round to the left of the decimal point, a negative number should be provided. *The integer n is optional and its value should default to 0*.
   $ truncate(x, n): Returns the result of truncating the argument x to n decimal places. *The integer n is optional and its value should default to 0*.

---+++ Impact Assessment

The changes proposed by this erratum should impact no existing IVOA resource. Checks against the major TAP services show they already act following the behaviour here above described for the modulo function, while for the remaining 3 issues, all of them simply require some explicit wording in the description to follow the grammar constraints. Checks against a choice of RDBMS-es (!PostgreSQL, !MySQL, !MariaDB, Apache Derby, !HyperSQL and Oracle) shows the same behaviour too. See the mail threads referenced in the introduction of this page for details.

<!--
      * Set ALLOWTOPICRENAME = IVOA.TWikiAdminGroup
-->
This topic: IVOA > WebHome > IvoaDAL > ADQL > ADQL-2_0-Next > ADQL-2_0-Err-2
Topic revision: r7 - 2017-10-09 - MarcoMolinaro