From 199b031bc006517bd585d3dd166ce33125a1a61c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Gr=C3=A9gory=20Mantelet?= Date: Fri, 22 Sep 2023 09:48:05 +0200 Subject: [PATCH 1/5] Remove section "Utility functions". It was duplicating information given in the sections DISTANCE and COORDSYS. --- ADQL.tex | 74 -------------------------------------------------------- 1 file changed, 74 deletions(-) diff --git a/ADQL.tex b/ADQL.tex index d2b2b3a..21e0186 100644 --- a/ADQL.tex +++ b/ADQL.tex @@ -1541,80 +1541,6 @@ \subsubsection{Predicate functions} %example, equals, disjoint, touches, crosses, within, overlaps and relate %are possibilities. -\subsubsection{Utility functions} -\label{sec:functions.geom.utility} - -The COORDSYS function extracts the coordinate system string from a given -geometry. To do so it accepts a geometry expression and returns a calculated -string value. - -This function has been included as a string value function because it -returns a simple string value. - -\begin{verbatim} - ::= - | - - ::= - - ::= - COORDSYS -\end{verbatim} - -As of this version of the specification the COORDSYS function has -been marked as deprecated. This function may be removed in future versions -of this specification. - -The specification defines two versions of the DISTANCE function, -one that accepts two POINTs, and one that accepts four -separate numeric values, both forms return a numeric value. - -The predicate and most of the utility functions are included as numeric -value functions because they return simple numeric values. -Thus: -\begin{verbatim} - ::= - - | - | - | -\end{verbatim} -\noindent -where -\begin{verbatim} - ::= - - | -\end{verbatim} -\noindent -and -\begin{verbatim} - ::= | -\end{verbatim} -\noindent -and -\begin{verbatim} - ::= - AREA - | COORD1 - | COORD2 - | DISTANCE - - - - | DISTANCE - - - - - -\end{verbatim} -\noindent -where -\begin{verbatim} - ::= | -\end{verbatim} - \subsubsection{Preferred sky crossmatch syntax} \label{sec:functions.geom.crossmatch} From d129e93d8e254c676bada49d3e2c84e32e1b2b11 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Gr=C3=A9gory=20Mantelet?= Date: Fri, 22 Sep 2023 09:59:20 +0200 Subject: [PATCH 2/5] Rename `Coordsys` section into `Coordinate System` The aim of this change is to avoid confusion with the COORDSYS section speaking about the COORDSYS() function. --- ADQL.tex | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ADQL.tex b/ADQL.tex index 21e0186..c392f3c 100644 --- a/ADQL.tex +++ b/ADQL.tex @@ -1490,7 +1490,7 @@ \subsubsection{Datatype functions} and \verb:: enables the use of geometric functions and column references. -\subsubsection{Coordsys} +\subsubsection{Coordinate system} \label{sec:geom.coordsys.param} For historical reasons, the geometry constructors (\verb:BOX:, \verb:CIRCLE:, From 078a0f72c6a4578694bb190abcdffbcd482d8281 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Gr=C3=A9gory=20Mantelet?= Date: Fri, 22 Sep 2023 11:03:50 +0200 Subject: [PATCH 3/5] Fix explanations about coordinate conversion in `DISTANCE`, `CONTAINS` and `INTERSECTS`. The explanations about the deprecated parameter COOSYS have been rephrased for more clarity. --- ADQL.tex | 84 +++++++++++++++++++++++--------------------------------- 1 file changed, 35 insertions(+), 49 deletions(-) diff --git a/ADQL.tex b/ADQL.tex index c392f3c..83d8ef0 100644 --- a/ADQL.tex +++ b/ADQL.tex @@ -1495,29 +1495,33 @@ \subsubsection{Coordinate system} For historical reasons, the geometry constructors (\verb:BOX:, \verb:CIRCLE:, \verb:POINT: and \verb:POLYGON:) all accept a string literal as the first -argument, hereafter called the COOSYS argument. Since version 2.1 of the -specification, this parameter has been made optional and marked as deprecated. -Future versions of this specification may remove this parameter from the listed -functions. - -This specification makes no guarantees about any semantics for the deprecated -COOSYS argument. Queries against services implementing ADQL 2.1 (or higher) -SHOULD omit it. For interoperability, queries against 2.0 services SHOULD NOT -pass arguments with differing COOSYS arguments to \verb:CONTAINS: or -\verb:INTERSECTS:, as behaviour is undefined in that case. +argument, hereafter called the COOSYS argument. The COOSYS argument was originally intended to carry information on a reference system or other coordinate system metadata. This was helpful in order to deal with data specified in different coordinate systems while performing geometric operations. It was up to the ADQL service to perform -the appropriate conversion to make these operations possible. Now this argument -is deprecated and will later be removed, the users should explicitly ask for -such conversion. If this behavior is desired, the ADQL implementers have to -allow it through User Defined Functions. Then, it is recommended to define them -as declared in the \CatalogueUDF{}. +the appropriate conversion to make these operations possible. + +Since version 2.1, this argument is deprecated and has been made optional. +Future versions of this specification will remove this parameter from the listed +functions. + +Coordinate conversions SHOULD now be explictly asked. The ADQL implementers have +to allow it through User Defined Functions. Then, it is recommended to define +them as declared in the \CatalogueUDF{}. % Catalogue of {ADQL} User Defined Functions - Endorsed Note 1.0+ % http://www.ivoa.net/documents/udf-catalogue/index.html +\verb:DISTANCE:, \verb:CONTAINS: and \verb:INTERSECTS: MAY still convert +coordinates of its geometric operands if they are expressed in different +coordinate systems. However, be aware that in a future version of ADQL, these +functions will no longer be expected to perform any coordinate conversion. +Consequently, it is recommanded to avoid relying on this deprecated feature. +For interoperability reasons, queries against 2.0 services SHOULD NOT pass +arguments with differing COOSYS arguments to \verb:DISTANCE:, \verb:CONTAINS: +or \verb:INTERSECTS:, as behaviour is undefined in that case. + \subsubsection{Predicate functions} \label{sec:functions.geom.predicate} @@ -1780,8 +1784,8 @@ \subsubsection{CONTAINS} another. This is most commonly used to express a ``point-in-shape'' condition. For example, an expression to determine whether the point (25.0, -19.5) degrees -is within a circle of ten degrees radius centered on position (25.4, -20.0) degrees, -could be written as follows: +is within a circle of ten degrees radius centered on position (25.4, -20.0) +degrees, could be written as follows: \begin{verbatim} CONTAINS(POINT(25.0, -19.5), CIRCLE(25.4, -20.0, 10.0)) \end{verbatim} @@ -1792,7 +1796,7 @@ \subsubsection{CONTAINS} is in, or on, the boundary of the second argument and the numeric value 0 if it is not. -When used as a predicate in the WHERE clause of a query, the numeric return +When used as a predicate in the WHERE clause of a query, the numeric returned value must be compared to the numeric values 0 or 1 to form a SQL predicate: \begin{verbatim} WHERE 1 = CONTAINS(POINT(25.0, -19.5), @@ -1822,13 +1826,8 @@ \subsubsection{CONTAINS} %TODO - ObsCore example %coordsys trans -If the geometric arguments are expressed in different coordinate systems, -the CONTAINS function is responsible for converting one, or both, of the -arguments into a different coordinate system. -If the CONTAINS function cannot perform the required conversion then -it SHOULD throw an error. -Details of the mechanism for reporting the error condition are -implementation dependent. +Geometric arguments SHOULD be expressed in the same coordinate system. +See \SectionRef{sec:geom.coordsys.param} for more details. \subsubsection{COORD1} \label{sec:functions.geom.coord1} @@ -1962,16 +1961,9 @@ \subsubsection{DISTANCE} database columns that contain POINT values. %coordsys trans -If the geometric arguments are expressed in different coordinate systems, -the DISTANCE function is responsible for converting one, or both, of the -arguments into a different coordinate system. -If the DISTANCE function cannot perform the required conversion then -it SHOULD throw an error. -Details of the mechanism for reporting the error condition are -implementation dependent. - -It is assumed that the arguments for the four numeric parameter form all -use the same coordinate system. +Geometric arguments SHOULD be expressed in the same coordinate system, even in +the four numeric parameter form. See \SectionRef{sec:geom.coordsys.param} for +more details. \subsubsection{INTERSECTS} \label{sec:functions.geom.intersects} @@ -2027,24 +2019,18 @@ \subsubsection{INTERSECTS} where \textit{t1.target} and \textit{t2.footprint} are references to database columns that contain geometric (BOX, CIRCLE, POLYGON or REGION) values. -%TODO The arguments to INTERSECTS SHOULD be geometric expressions evaluating to either BOX, CIRCLE, POLYGON or REGION. -Previous versions of this -specification also allowed POINT values and required server implementations to -interpret the expression as a CONTAINS with the POINT moved into the first position. -Server implementations SHOULD still implement that behaviour, but clients -SHOULD NOT expect it. -This behaviour MAY be dropped in the next major version of this specification. + +Previous versions of this specification also allowed POINT values and required +server implementations to interpret the expression as a CONTAINS with the POINT +moved into the first position. Server implementations SHOULD still implement +that behaviour, but clients SHOULD NOT expect it. This behaviour MAY be dropped +in the next major version of this specification. %coordsys trans -If the geometric arguments are expressed in different coordinate systems, -the INTERSECTS function is responsible for converting one, or both, of the -arguments into a different coordinate system. -If the INTERSECTS function cannot perform the required conversion then -it SHOULD throw an error. -Details of the mechanism for reporting the error condition are -implementation dependent. +Geometric arguments SHOULD be expressed in the same coordinate system. +See \SectionRef{sec:geom.coordsys.param} for more details. \subsubsection{POINT} \label{sec:functions.geom.point} From 0a36ec34cba8aaa5f09d2f5547c4aa61a0e0a12f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Gr=C3=A9gory=20Mantelet?= Date: Fri, 22 Sep 2023 11:30:58 +0200 Subject: [PATCH 4/5] Update the submodule 'ivoatex'. --- ivoatex | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ivoatex b/ivoatex index 30e1cfd..19f2060 160000 --- a/ivoatex +++ b/ivoatex @@ -1 +1 @@ -Subproject commit 30e1cfd64f9d0d621a8c23d85628e50729daf42b +Subproject commit 19f206001a1f8f583f1ff0dcd8792285492b4891 From ebe82170a98e62a0e96a8549e8fa32cd847deda1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Gr=C3=A9gory=20Mantelet?= Date: Fri, 22 Sep 2023 13:40:19 +0200 Subject: [PATCH 5/5] Fix typo and fix description of the UDF catalogue --- ADQL.tex | 21 +++++++++++---------- 1 file changed, 11 insertions(+), 10 deletions(-) diff --git a/ADQL.tex b/ADQL.tex index 83d8ef0..9483e3c 100644 --- a/ADQL.tex +++ b/ADQL.tex @@ -1507,9 +1507,10 @@ \subsubsection{Coordinate system} Future versions of this specification will remove this parameter from the listed functions. -Coordinate conversions SHOULD now be explictly asked. The ADQL implementers have -to allow it through User Defined Functions. Then, it is recommended to define -them as declared in the \CatalogueUDF{}. +Coordinate conversions SHOULD now be explictly requested. The ADQL implementers +have to allow it through User Defined Functions. An interoperable facility for +frame transformations is in preparation as of this writing and is expected to be +part of the \CatalogueUDF{}. % Catalogue of {ADQL} User Defined Functions - Endorsed Note 1.0+ % http://www.ivoa.net/documents/udf-catalogue/index.html @@ -1792,12 +1793,12 @@ \subsubsection{CONTAINS} The CONTAINS function is not symmetric in the meaning of the arguments. -The CONTAINS function returns the numeric value 1 if the first argument -is in, or on, the boundary of the second argument and the numeric value 0 +The CONTAINS function returns the integer value 1 if the first argument +is in, or on, the boundary of the second argument and the integer value 0 if it is not. -When used as a predicate in the WHERE clause of a query, the numeric returned -value must be compared to the numeric values 0 or 1 to form a SQL predicate: +When used as a predicate in the WHERE clause of a query, the returned integer +value must be compared to the integer values 0 or 1 to form a SQL predicate: \begin{verbatim} WHERE 1 = CONTAINS(POINT(25.0, -19.5), CIRCLE(25.4, -20.0, 10.0)) @@ -1985,11 +1986,11 @@ \subsubsection{INTERSECTS} 10.0, -15.0)) \end{verbatim} \noindent -where the INTERSECTS function returns the numeric value 1 if the two arguments +where the INTERSECTS function returns the integer value 1 if the two arguments overlap and 0 if they do not. -When used as a predicate in the WHERE clause of a query, the numeric return -value should be compared to the numeric values 0 or 1 to form a SQL predicate: +When used as a predicate in the WHERE clause of a query, the returned integer +value should be compared to the integer values 0 or 1 to form a SQL predicate: \begin{verbatim} WHERE 1 = INTERSECTS(CIRCLE(25.4, -20.0, 1), POLYGON(20.0, -15.0,