diff --git a/ADQL.tex b/ADQL.tex index 9742c79..f911de0 100644 --- a/ADQL.tex +++ b/ADQL.tex @@ -498,34 +498,29 @@ \subsubsection{Subqueries} in the \verb:WHERE: clause of a query: \begin{verbatim} - SELECT - alpha_source.id - FROM - alpha_source - WHERE - alpha_sourceid >=5 - AND - alpha_sourceid IN - ( - SELECT id FROM alpha_source WHERE id < 10 - ) + SELECT alpha_source.id + FROM alpha_source + WHERE alpha_sourceid >=5 + AND alpha_sourceid IN ( + SELECT id + FROM alpha_source + WHERE id < 10 + ) \end{verbatim} Table subqueries MAY be used for declaring derived tables in the \verb:FROM: clause of a query: \begin{verbatim} - SELECT - alpha_source.id - FROM - alpha_source, - ( - SELECT alpha_source.id FROM alpha_source WHERE id < 10 - ) AS subsample - WHERE - alpha_source.id >=5 - AND - alpha_source.id = subsample.id + SELECT alpha_source.id + FROM alpha_source, + ( + SELECT alpha_source.id + FROM alpha_source + WHERE id < 10 + ) AS subsample + WHERE alpha_source.id >=5 + AND alpha_source.id = subsample.id \end{verbatim} If supported by the implementation, table subqueries MAY be used for declaring @@ -533,14 +528,14 @@ \subsubsection{Subqueries} \begin{verbatim} WITH subsample AS ( - SELECT alpha_source.id FROM alpha_source WHERE id < 10 + SELECT alpha_source.id + FROM alpha_source + WHERE id < 10 ) - SELECT - alpha_source.id - FROM - alpha_source INNER JOIN subsample USING(id) - WHERE - alpha_source.id >= 5 + SELECT alpha_source.id + FROM alpha_source + INNER JOIN subsample USING(id) + WHERE alpha_source.id >= 5 \end{verbatim} \subsubsection{Joins} @@ -973,19 +968,20 @@ \subsubsection{TIMESTAMP} (if supported) described in \SectionRef{sec:type.cast}. The basic comparison operators \verb:=:, \verb:<:, \verb:>:, \verb:<=:, \verb:>=:, -\verb:<>: and \verb:BETWEEN: can all be applied to \verb:TIMESTAMP: values: -\begin{verbatim} - SELECT - .. - WHERE - obstime > CAST('2015-01-01' AS TIMESTAMP) - OR - obstime - BETWEEN - CAST('2014-01-01' AS TIMESTAMP) - AND - CAST('2014-01-02' AS TIMESTAMP) -\end{verbatim} +\verb:<>: and \verb:BETWEEN: can all be applied to \verb:TIMESTAMP: values. + +For instance: +\begin{itemize} + \item \begin{verbatim} + obstime > CAST('2015-01-01' AS TIMESTAMP) +\end{verbatim} + \item \begin{verbatim} + obstime BETWEEN + CAST('2014-01-01' AS TIMESTAMP) + AND + CAST('2014-01-02' AS TIMESTAMP) + \end{verbatim} +\end{itemize} Within the database, the details of how \verb:TIMESTAMP: values are implemented is platform dependent. The primary requirement is that the results of the @@ -1243,10 +1239,7 @@ \subsubsection{POINT} For example: \begin{verbatim} - POINT( - 12.3, - 45.6 - ) + POINT(12.3, 45.6) \end{verbatim} \subsubsection{CIRCLE} @@ -1291,11 +1284,7 @@ \subsubsection{CIRCLE} constructor defined in \SectionRef{sec:functions.geom.circle}. For example: \begin{verbatim} - CIRCLE( - 12.3, - 45.6, - 0.5 - ) + CIRCLE(12.3, 45.6, 0.5) \end{verbatim} \subsubsection{POLYGON} @@ -1341,14 +1330,7 @@ \subsubsection{POLYGON} For example: \begin{verbatim} - POLYGON( - 10.0, - -10.5, - 20.0, - 20.5, - 30.0, - 30.5 - ) + POLYGON(10.0, -10.5, 20.0, 20.5, 30.0, 30.5) \end{verbatim} \noindent describes a triangle, whose vertices are (10.0, -10.5), (20.0, 20.5) @@ -1557,15 +1539,9 @@ \subsubsection{Predicate functions} comparing the numeric result with zero or one. For example: \begin{verbatim} - SELECT - * - FROM - table - WHERE - 1 = CONTAINS( - POINT(...), - CIRCLE(...) - ) + SELECT * + FROM table + WHERE 1 = CONTAINS(POINT(...), CIRCLE(...)) \end{verbatim} %REMOVED - speculative, not definitive. @@ -1681,12 +1657,8 @@ \subsubsection{Preferred crossmatch syntax} The preferred way to specify a sky position-only crossmatch is: \begin{verbatim} - JOIN ... ON DISTANCE( - t1.lon, - t1.lat, - t2.lon, - t2.lat - ) < r_max_deg + JOIN ... + ON DISTANCE(t1.lon, t1.lat, t2.lon, t2.lat) < r_max_deg \end{verbatim} where \textit{t1.lon}, \textit{t1.lat}, and \textit{t2.lon}, \textit{t2.lat} are references to numeric columns for the latitude and longitude @@ -1694,10 +1666,8 @@ \subsubsection{Preferred crossmatch syntax} Alternatively, using geometric POINT values, \begin{verbatim} - JOIN ... ON DISTANCE( - t1.point, - t2.point - ) < r_max_deg + JOIN ... + ON DISTANCE(t1.point, t2.point) < r_max_deg \end{verbatim} where \textit{t1.point} and \textit{t2.point} are references to columns containing geometric POINT values @@ -1717,16 +1687,7 @@ \subsubsection{AREA} For example, an expression to calculate the area of a POLYGON could be written as follows: \begin{verbatim} - AREA( - POLYGON( - 10.0, - -10.5, - 20.0, - 20.5, - 30.0, - 30.5 - ) - ) + AREA(POLYGON(10.0, -10.5, 20.0, 20.5, 30.0, 30.5)) \end{verbatim} The AREA of a single POINT is zero. @@ -1735,9 +1696,7 @@ \subsubsection{AREA} column reference, function or expression that returns a geometric type. For example: \begin{verbatim} - AREA( - t1.footprint - ) + AREA(t1.footprint) \end{verbatim} where \textit{t1.footprint} is a reference to a database column that contains geometric (POINT, BOX, CIRCLE, POLYGON or REGION) values. @@ -1794,24 +1753,12 @@ \subsubsection{BOX} For example, a BOX of ten degrees centered on a position (25.4, -20.0) in degrees could be written as follows: \begin{verbatim} - BOX( - 25.4, - -20.0, - 10.0, - 10.0 - ) + BOX(25.4, -20.0, 10.0, 10.0) \end{verbatim} Alternatively, the center position could be expressed as a POINT: \begin{verbatim} - BOX( - POINT( - 25.4, - -20.0 - ), - 10.0, - 10.0 - ) + BOX(POINT(25.4, -20.0), 10.0, 10.0) \end{verbatim} The function arguments may be literal values, as above, or they may be @@ -1819,11 +1766,7 @@ \subsubsection{BOX} datatypes. For example: \begin{verbatim} - BOX( - t1.center, - t1.width, - t1.height - ) + BOX(t1.center, t1.width, t1.height) \end{verbatim} where \textit{t1.center}, \textit{t1.width} and \textit{t1.height} are references to database columns that contain POINT, DOUBLE @@ -1849,16 +1792,7 @@ \subsubsection{CENTROID} For example, an expression to calculate the centroid of a POLYGON could be written as follows : \begin{verbatim} - CENTROID( - POLYGON( - 10.0, - -10.5, - 20.0, - 20.5, - 30.0, - 30.5 - ) - ) + CENTROID(POLYGON(10.0, -10.5, 20.0, 20.5, 30.0, 30.5)) \end{verbatim} The CENTROID of a single POINT is that POINT. @@ -1867,9 +1801,7 @@ \subsubsection{CENTROID} column reference, function or expression that returns a geometric type. For example: \begin{verbatim} - CENTROID( - t1.footprint - ) + CENTROID(t1.footprint) \end{verbatim} where \textit{t1.footprint} is a reference to a database column that contains geometric (POINT, BOX, CIRCLE, POLYGON or REGION) values. @@ -1898,32 +1830,19 @@ \subsubsection{CIRCLE} For example, a CIRCLE of ten degrees radius centered on position (25.4, -20.0) in degrees could be written as follows: \begin{verbatim} - CIRCLE( - 25.4, - -20.0, - 10.0 - ) + CIRCLE(25.4, -20.0, 10.0) \end{verbatim} Alternatively, the center position may be expressed as a POINT: \begin{verbatim} - CIRCLE( - POINT( - 25.4, - -20.0, - ), - 10.0 - ) + CIRCLE(POINT(25.4, -20.0), 10.0) \end{verbatim} The position argument may be a literal value, as above, or it may be a column reference, function or expression that returns a geometric type. For example: \begin{verbatim} - CIRCLE( - t1.center, - t1.radius - ) + CIRCLE(t1.center, t1.radius) \end{verbatim} where \textit{t1.center} and \textit{t1.radius} are references to database columns that contain POINT and DOUBLE values respectively. @@ -1950,17 +1869,7 @@ \subsubsection{CONTAINS} 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 - ) - ) + CONTAINS(POINT(25.0, -19.5), CIRCLE(25.4, -20.0, 10.0)) \end{verbatim} The CONTAINS function is not symmetric in the meaning of the arguments. @@ -1972,34 +1881,14 @@ \subsubsection{CONTAINS} When used as a predicate in the WHERE clause of a query, the numeric return 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 - ), - CIRCLE( - 25.4, - -20.0, - 10.0 - ) - ) + WHERE 1 = CONTAINS(POINT(25.0, -19.5), + CIRCLE(25.4, -20.0, 10.0)) \end{verbatim} \noindent for "does contain" and \begin{verbatim} - WHERE - 0 = CONTAINS( - POINT( - 25.0, - -19.5 - ), - CIRCLE( - 25.4, - -20.0, - 10.0 - ) - ) + WHERE 0 = CONTAINS(POINT(25.0, -19.5), + CIRCLE(25.4, -20.0, 10.0)) \end{verbatim} \noindent for "does not contain". @@ -2011,11 +1900,7 @@ \subsubsection{CONTAINS} geometric values. For example: \begin{verbatim} - WHERE - 0 = CONTAINS( - t1.center, - t2.footprint - ) + WHERE 0 = CONTAINS(t1.center, t2.footprint) \end{verbatim} where \textit{t1.center} and \textit{t2.footprint} are references to database columns that contain POINT and geometric (BOX, CIRCLE, POLYGON or REGION) @@ -2043,21 +1928,14 @@ \subsubsection{COORD1} For example, the right ascension of a point with position (25, -19.5) in degrees would be obtained using the following expression: \begin{verbatim} - COORD1( - POINT( - 25.0, - -19.5 - ) - ) + COORD1(POINT(25.0, -19.5)) \end{verbatim} \noindent which would return a numeric value of 25.0 degrees. For example: \begin{verbatim} - COORD1( - t.center - ) + COORD1(t.center) \end{verbatim} \noindent where \textit{t.center} is a reference to a column that contains POINT values. @@ -2074,12 +1952,7 @@ \subsubsection{COORD2} For example, the declination of a point with position (25, -19.5) in degrees, could be obtained using the following expression: \begin{verbatim} - COORD2( - POINT( - 25.0, - -19.5 - ) - ) + COORD2(POINT(25.0, -19.5)) \end{verbatim} \noindent which would return a numeric value of -19.5 degrees. @@ -2088,9 +1961,7 @@ \subsubsection{COORD2} geometric POINT value. For example: \begin{verbatim} - COORD2( - t.center - ) + COORD2(t.center) \end{verbatim} \noindent where \textit{t.center} is a reference to a column that contains POINT values. @@ -2118,12 +1989,7 @@ \subsubsection{COORDSYS} The following example would return the coordinate system of a POINT literal: \begin{verbatim} - COORDSYS( - POINT( - 25.0, - -19.5 - ) - ) + COORDSYS(POINT(25.0, -19.5)) \end{verbatim} \noindent which would return a string value representing the coordinate system used @@ -2132,9 +1998,7 @@ \subsubsection{COORDSYS} The COORDSYS function may be applied to any expression that returns a geometric datatype. For example: \begin{verbatim} - COORDSYS( - t.footprint - ) + COORDSYS(t.footprint) \end{verbatim} \noindent where \textit{t.footprint} is a reference to a database column that @@ -2160,28 +2024,14 @@ \subsubsection{DISTANCE} For example, an expression calculating the distance between two points of coordinates (25,-19.5) and (25.4,-20) could be written as follows: \begin{verbatim} - DISTANCE( - POINT( - 25.0, - -19.5 - ), - POINT( - 25.4, - -20.0 - ) - ) + DISTANCE(POINT(25.0, -19.5), POINT(25.4, -20.0)) \end{verbatim} \noindent where all numeric values and the returned arc length are in degrees. The equivalent call to the four parameter form of the function would be: \begin{verbatim} - DISTANCE( - 25.0, - -19.5, - 25.4, - -20.0 - ) + DISTANCE(25.0, -19.5, 25.4, -20.0) \end{verbatim} The DISTANCE function may be applied to any expression that returns a @@ -2191,10 +2041,7 @@ \subsubsection{DISTANCE} For example, the distance between two points stored in the database could be calculated as follows: \begin{verbatim} - DISTANCE( - t1.base, - t2.target - ) + DISTANCE(t1.base, t2.target) \end{verbatim} \noindent where \textit{t1.base} and \textit{t2.target} are references to @@ -2225,19 +2072,11 @@ \subsubsection{INTERSECTS} centered on position (25.4, -20.0) degrees overlaps with a POLYGON, could be written as follows: \begin{verbatim} - INTERSECTS( - CIRCLE( - 25.4, - -20.0, - 1 - ), - POLYGON( - 20.0, -15.0, - 20.0, -5.0, - 10.0, -5.0, - 10.0, -15.0 - ) - ) + INTERSECTS(CIRCLE(25.4, -20.0, 1), + POLYGON(20.0, -15.0, + 20.0, -5.0, + 10.0, -5.0, + 10.0, -15.0)) \end{verbatim} \noindent where the INTERSECTS function returns the numeric value 1 if the two arguments @@ -2246,38 +2085,20 @@ \subsubsection{INTERSECTS} 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: \begin{verbatim} - WHERE - 1 = INTERSECTS( - CIRCLE( - 25.4, - -20.0, - 1 - ), - POLYGON( - 20.0, -15.0, - 20.0, -5.0, - 10.0, -5.0, - 10.0, -15.0 - ) - ) + WHERE 1 = INTERSECTS(CIRCLE(25.4, -20.0, 1), + POLYGON(20.0, -15.0, + 20.0, -5.0, + 10.0, -5.0, + 10.0, -15.0)) \end{verbatim} \noindent for "does intersect" and \begin{verbatim} - WHERE - 0 = INTERSECTS( - CIRCLE( - 25.4, - -20.0, - 1 - ), - POLYGON( - 20.0, -15.0, - 20.0, -5.0, - 10.0, -5.0, - 10.0, -15.0 - ) - ) + WHERE 0 = INTERSECTS(CIRCLE(25.4, -20.0, 1), + POLYGON(20.0, -15.0, + 20.0, -5.0, + 10.0, -5.0, + 10.0, -15.0)) \end{verbatim} \noindent for "does not intersect". @@ -2287,11 +2108,7 @@ \subsubsection{INTERSECTS} geometric values. For example: \begin{verbatim} - WHERE - 0 = INTERSECTS( - t1.target, - t2.footprint - ) + WHERE 0 = INTERSECTS(t1.target, t2.footprint) \end{verbatim} where \textit{t1.target} and \textit{t2.footprint} are references to database columns that contain geometric (BOX, CIRCLE, POLYGON or REGION) values. @@ -2336,10 +2153,7 @@ \subsubsection{POINT} For example, a function expressing a point with right ascension of 25 degrees and declination of -19.5 degrees would be written as follows: \begin{verbatim} - POINT( - 25.0, - -19.5 - ) + POINT(25.0, -19.5) \end{verbatim} \noindent where numeric values are in degrees. @@ -2349,10 +2163,7 @@ \subsubsection{POINT} numeric values. For example: \begin{verbatim} - POINT( - t.ra, - t.dec - ) + POINT(t.ra, t.dec) \end{verbatim} \noindent where \textit{t.ra} and \textit{t.dec} are references to database @@ -2394,14 +2205,7 @@ \subsubsection{POLYGON} -10.5), (20.0, 20.5) and (30.0,30.5) in degrees would be written as follows: \begin{verbatim} - POLYGON( - 10.0, - -10.5, - 20.0, - 20.5, - 30.0, - 30.5 - ) + POLYGON(10.0, -10.5, 20.0, 20.5, 30.0, 30.5) \end{verbatim} \noindent where all numeric values are in degrees. @@ -2411,14 +2215,9 @@ \subsubsection{POLYGON} numeric values. For example: \begin{verbatim} - POLYGON( - t1.ra, - t1.dec + 5, - t1.ra - 5, - t1.dec - 5, - t1.ra - 5, - t1.dec + 5, - ) + POLYGON(t1.ra , t1.dec + 5, + t1.ra - 5, t1.dec - 5, + t1.ra - 5, t1.dec + 5,) \end{verbatim} \noindent where \textit{t1.ra} and \textit{t1.dec} are references to database columns @@ -2429,11 +2228,7 @@ \subsubsection{POLYGON} functions or expressions that return POINT values. For example: \begin{verbatim} - POLYGON( - t2.toppoint, - t2.bottomleft, - t2.bottomright - ) + POLYGON(t2.toppoint, t2.bottomleft, t2.bottomright) \end{verbatim} \noindent where \textit{t2.toppoint}, \textit{t2.bottomleft} and \textit{t2.bottomright} @@ -2665,45 +2460,27 @@ \subsubsection{WITH} For example, the following query with a nested subquery: \begin{verbatim} - SELECT - ra, - dec - FROM - ( - SELECT - * - FROM - alpha_source - WHERE - id % 10 = 0 - ) - WHERE - ra > 10 - AND - ra < 20 + SELECT ra, dec + FROM ( + SELECT * + FROM alpha_source + WHERE id % 10 = 0 + ) AS alpha_subset + WHERE ra > 10 + AND ra < 20 \end{verbatim} \noindent can be refactored as a named WITH query and a simpler main query: \begin{verbatim} - WITH alpha_subset AS - ( - SELECT - * - FROM - alpha_source - WHERE - id % 10 = 0 - ) - - SELECT - ra, - dec - FROM - alpha_subset - WHERE - ra > 10 - AND - ra < 20 + WITH alpha_subset AS ( + SELECT * + FROM alpha_source + WHERE id % 10 = 0 + ) + SELECT ra, dec + FROM alpha_subset + WHERE ra > 10 + AND ra < 20 \end{verbatim} The current version of ADQL does not support recursive common table expressions. @@ -2788,10 +2565,10 @@ \subsubsection{Operands} \begin{verbatim} -- take the 10 first - ( SELECT TOP 10 id, ra, dec FROM atable ORDER BY id ASC) + (SELECT TOP 10 id, ra, dec FROM atable ORDER BY id ASC) UNION -- take the 10 last - ( SELECT TOP 10 id, ra, dec FROM atable ORDER BY id DESC) + (SELECT TOP 10 id, ra, dec FROM atable ORDER BY id DESC) \end{verbatim} Common table expressions are not allowed in any set operator operand. They must @@ -2801,8 +2578,8 @@ \subsubsection{Operands} expressions \begin{verbatim} -WITH tenFirst AS ( SELECT TOP 10 id, ra, dec FROM atable ORDER BY id ASC), - tenLast AS ( SELECT TOP 10 id, ra, dec FROM atable ORDER BY id DESC) +WITH tenFirst AS (SELECT TOP 10 id, ra, dec FROM atable ORDER BY id ASC), + tenLast AS (SELECT TOP 10 id, ra, dec FROM atable ORDER BY id DESC) SELECT * FROM tenFirst UNION SELECT * FROM tenLast @@ -3022,10 +2799,10 @@ \subsubsection{COALESCE} if this rule is not respected. The way to report this error is implementation dependent. -This is typically used to provide fallback values. For instance, +This is typically used to provide fallback values. For instance, \begin{verbatim} -COALESCE(access_url, '') + COALESCE(access_url, '') \end{verbatim} \noindent will return an empty string when \verb|access_url| is NULL.