ADQL.tex

\documentclass[11pt,a4paper]{ivoa}
\input tthdefs


\usepackage[utf8]{inputenc}
\usepackage{tabularx}
\usepackage{multirow}
\usepackage{mathtools}
\usepackage{makecell}

\usepackage{listings}
\lstloadlanguages{XML,sh}
\lstset{flexiblecolumns=true,numberstyle=\small,numbers=left}

\usepackage{hyperref}

% Macros for referring to IVOA standards and notes.
\input{ivoa-cite.tex}

\title{Astronomical Data Query Language}

\ivoagroup{Data Access Layer Working Group}

%\author[http://wiki.ivoa.net/twiki/bin/view/IVOA/IvoaDAL]{The IVOA Data Access Layer (DAL) and Virtual Observatory Query Language (VOQL) working group members}
\author{Markus Demleitner}
\author{Pat Dowler}
\author{Jeff Lusted}
\author{Grégory Mantelet}
\author{Dave Morris}
\author{Maria A. Nieto-Santisteban}
\author{Masatoshi Ohishi}
\author{William O’Mullane}
\author{Inaki Ortiz}
\author{Pedro Osuna}
\author{Yuji Shirasaki}
\author{Alexander Szalay}

\editor[http://wiki.ivoa.net/twiki/bin/view/IVOA/GregoryMantelet]{Grégory Mantelet}
\editor[http://wiki.ivoa.net/twiki/bin/view/IVOA/DaveMorris]{Dave Morris}

\previousversion[http://www.ivoa.net/Documents/ADQL/2.0]{ADQL-2.0}

\begin{document}

\begin{abstract}
This document describes the Astronomical Data Query Language (ADQL).
ADQL has been developed based on SQL92.
This document describes the subset of the SQL grammar supported by ADQL.
Special restrictions and extensions to SQL92 have been defined in order
to support generic and astronomy specific operations.
\end{abstract}

\section*{Acknowledgements}

The authors would like to acknowledge the contributors to this standard by
the members of the IVOA Data Access Layer (DAL) and Virtual Observatory
Query Language (VOQL) working groups.

\section*{Conformance-related definitions}

The words ``MUST'', ``SHALL'', ``SHOULD'', ``MAY'', ``RECOMMENDED'' and
``OPTIONAL'' (in upper or lower case) used in this document are to be
interpreted as described in the
\href{https://www.ietf.org/}{Internet Engineering Task Force (IETF)}
standard, \citet{std:RFC2119}.

The \emph{Virtual Observatory (VO)} is a general term for a collection of
federated resources that can be used to conduct astronomical research,
education and outreach. The
\href{http://www.ivoa.net}{International Virtual Observatory Alliance (IVOA)}
is a global collaboration of separately funded
projects to develop standards and infrastructure that enable VO applications.

\clearpage % section cut
\section{Introduction}
\label{sec:introduction}

The Astronomical Data Query Language (ADQL) is the language used by the
IVOA to represent astronomy queries posted to VO services.
The IVOA has developed several standardized protocols to access astronomical
data, e.g., Simple Image Access (SIA) protocol and Simple Spectral Access (SSA)
protocol for image and spectral data respectively.
These protocols might be satisfied using a single
table query. However, different VO services have different needs in terms
of query complexity and ADQL arises in this context.

ADQL is based on the Structured Query Language (SQL), especially on SQL
92 \citep{std:SQL1992}\footnote{see also
\url{https://en.wikipedia.org/wiki/SQL-92},
\url{http://www.contrib.andrew.cmu.edu/~shadow/sql/sql1992.txt}.}.

The VO has a number of tabular data sets and many of them are stored in
relational databases, making SQL a convenient access means. A subset of the SQL
grammar has been extended to support queries that are specific to astronomy.

This specification provides a complete definition of the ADQL through a single
Backus Naur Form (BNF) based language definition. It includes both mandatory
and optional features.  This BNF aims to help implementing ADQL core
features as well as the defined optional ones.

\clearpage % to have the VOArch figure along its description and subsection title
\subsection{Role within the VO architecture}
\label{sec:role}

\begin{figure}[th]
\centering
\includegraphics[width=0.9\textwidth]{role_diagram.pdf}
\caption{Architecture diagram for this document}
\label{fig:archdiag}
\end{figure}

Figure \ref{fig:archdiag} shows the role this document plays within the
IVOA architecture \VOArch{}.

It is the only mandatory query language within the Table Access Protocol
\TAPSpec{}; it is thus an important element in
enabling interoperable queries against remote astronomical databases.

TAP services communicate their metadata, and hence metadata about the
specific version of ADQL they implement, in capabilities of the
VOResource type \xmlel{tr:TableAccess} defined in TAPRegExt
\citep{2012ivoa.spec.0827D}.  Within these TAPRegExt records, the
language defined in this document, ADQL 2.1, has the IVOA identifier $$
\hbox{\nolinkurl{ivo://ivoa.net/std/adql#v2.1}}.$$ Clients should note
that IVOA identifiers need to be compared case-insensitively.

DALI \citep{2017ivoa.spec.0517D} defines conventions for many of the
types ADQL is talking about, in particular geometry objects, timestamps,
and intervals.

\subsection{Extended functionality}
\label{sec:extending}

% Requested by Alberto Micol at ESO.
% Explicit permission for services that provide additional functionality.
This document defines the minimum set of functions, operators and data types
that a service MUST implement in order to register as a service that
implements this version of the ADQL specification. Optional features defined in
this specification MAY be implemented. However, if a service does provide one of
them, it MUST be implemented according to this specification.

Of course, service implementations are free to extend this functionality by
providing additional functions, operators or data types beyond those defined in
this specification, as long as the extended functionality does not conflict
with anything defined in this specification.

\clearpage % section cut
\section{Language structure}
\label{sec:language}

This section describes the ADQL language structure. We will define in
subsequent sections the syntax for the special characters, reserved and non-
reserved words, identifiers and literals and then, finally, the syntax for
the query expression.

The formal notation for syntax of computing languages is often expressed
in BNF. This syntax is used by popular tools for
producing parsers. Appendix A to this document provides the full BNF grammar
for ADQL. The following conventions are used through this document:

\begin{itemize}
    \item Optional items are enclosed in meta symbols \verb:[: and \verb:]:
    \item A group of items is enclosed in meta symbols \verb:{: and \verb:}:
    \item Repetitive item (zero or more times) are followed by \verb:...:
    \item Terminal symbols are enclosed by \verb:<: and \verb:>:
    \item Terminals of meta-symbol characters (\verb!:=[]{}<>."!) are surrounded by quotes (\verb:“:) to distinguish them from meta-symbols
    \item Case-insensitive unless otherwise stated.
\end{itemize}


\subsection{Characters, keywords, identifiers and literals}
\subsubsection{Characters}
\label{sec:characters}

The language allows simple Latin letters (lower and upper case, i.e.
\verb:{aA-zZ}):, digits (\verb:{0-9}:) and the following special characters:

\begin{itemize}
    \item space
    \item single quote \verb:':
    \item double quote \verb:":
    \item percent \verb:%:
    \item left and right parenthesis \verb:():
    \item asterisk \verb:*:
    \item plus sign \verb:+:
    \item minus sign \verb:-:
    \item comma \verb:,:
    \item period \verb:.:
    \item solidus \verb:/:
    \item colon \verb.:.
    \item semicolon \verb:;:
    \item less than operator \verb:<:
    \item equals operator \verb:=:
    \item greater than operator \verb:>:
    \item underscore \verb:_:
    \item ampersand \verb:&:
    \item question mark \verb:?:
    \item circumflex \verb:^:
    \item tilde \verb:~:
    \item vertical bar \verb:|:
\end{itemize}

\subsubsection{Keywords and identifiers}
\label{sec:keywords}

Besides the character set, the language provides a list of reserved keywords
plus the syntax description for regular identifiers.

A reserved keyword has a special meaning in ADQL and cannot be used as
an identifier unless it is isolated using the ADQL escape syntax defined
in \SectionRef{sec:adql.escape}.

The ADQL specification extends the list of SQL92 reserved keywords to accommodate
those useful for astronomical purposes and/or present in a subset of vendor
specific languages only (e.g. \verb:TOP:).

Although the following lists are all in UPPERCASE, the matching of keywords
is case-insensitive.

\subsubsection{SQL reserved keywords}
\label{sec:adql.keywords}

\begin{raggedright}
\noindent
\texttt{ABSOLUTE,} \texttt{ACTION,} \texttt{ADD,} \texttt{ALL,}
\texttt{ALLOCATE,} \texttt{ALTER,} \texttt{AND,} \texttt{ANY,}
\texttt{ARE,} \texttt{AS,} \texttt{ASC,} \texttt{ASSERTION,}
\texttt{AT,} \texttt{AUTHORIZATION,} \texttt{AVG,} \texttt{BEGIN,}
\texttt{BETWEEN,} \texttt{BIT,} \texttt{BIT\_LENGTH,} \texttt{BOTH,}
\texttt{BY,} \texttt{CASCADE,} \texttt{CASCADED,} \texttt{CASE,}
\texttt{CAST,} \texttt{CATALOG,} \texttt{CHAR,} \texttt{CHARACTER,}
\texttt{CHAR\_LENGTH,} \texttt{CHARACTER\_LENGTH,} \texttt{CHECK,}
\texttt{CLOSE,} \texttt{COALESCE,} \texttt{COLLATE,}
\texttt{COLLATION,} \texttt{COLUMN,} \texttt{COMMIT,}
\texttt{CONNECT,} \texttt{CONNECTION,} \texttt{CONSTRAINT,}
\texttt{CONSTRAINTS,} \texttt{CONTINUE,} \texttt{CONVERT,}
\texttt{CORRESPONDING,} \texttt{COUNT,} \texttt{CREATE,}
\texttt{CROSS,} \texttt{CURRENT,} \texttt{CURRENT\_DATE,}
\texttt{CURRENT\_TIME,} \texttt{CURRENT\_TIMESTAMP,}
\texttt{CURRENT\_USER,} \texttt{CURSOR,} \texttt{DATE,} \texttt{DAY,}
\texttt{DEALLOCATE,} \texttt{DECIMAL,} \texttt{DECLARE,}
\texttt{DEFAULT,} \texttt{DEFERRABLE,} \texttt{DEFERRED,}
\texttt{DELETE,} \texttt{DESC,} \texttt{DESCRIBE,}
\texttt{DESCRIPTOR,} \texttt{DIAGNOSTICS,} \texttt{DISCONNECT,}
\texttt{DISTINCT,} \texttt{DOMAIN,} \texttt{DOUBLE,} \texttt{DROP,}
\texttt{ELSE,} \texttt{END,} \texttt{END-EXEC,} \texttt{ESCAPE,}
\texttt{EXCEPT,} \texttt{EXCEPTION,} \texttt{EXEC,} \texttt{EXECUTE,}
\texttt{EXISTS,} \texttt{EXTERNAL,} \texttt{EXTRACT,} \texttt{FALSE,}
\texttt{FETCH,} \texttt{FIRST,} \texttt{FLOAT,} \texttt{FOR,}
\texttt{FOREIGN,} \texttt{FOUND,} \texttt{FROM,} \texttt{FULL,}
\texttt{GET,} \texttt{GLOBAL,} \texttt{GO,} \texttt{GOTO,}
\texttt{GRANT,} \texttt{GROUP,} \texttt{HAVING,} \texttt{HOUR,}
\texttt{IDENTITY,} \texttt{IMMEDIATE,} \texttt{IN,}
\texttt{INDICATOR,} \texttt{INITIALLY,} \texttt{INNER,}
\texttt{INPUT,} \texttt{INSENSITIVE,} \texttt{INSERT,} \texttt{INT,}
\texttt{INTEGER,} \texttt{INTERSECT,} \texttt{INTERVAL,}
\texttt{INTO,} \texttt{IS,} \texttt{ISOLATION,} \texttt{JOIN,}
\texttt{KEY,} \texttt{LANGUAGE,} \texttt{LAST,} \texttt{LEADING,}
\texttt{LEFT,} \texttt{LEVEL,} \texttt{LIKE,} \texttt{LOCAL,} \texttt{LOWER,}
\texttt{MATCH,} \texttt{MAX,} \texttt{MIN,}
\texttt{MINUTE,} \texttt{MODULE,} \texttt{MONTH,} \texttt{NAMES,}
\texttt{NATIONAL,} \texttt{NATURAL,} \texttt{NCHAR,} \texttt{NEXT,}
\texttt{NO,} \texttt{NOT,} \texttt{NULL,} \texttt{NULLIF,}
\texttt{NUMERIC,} \texttt{OCTET\_LENGTH,} \texttt{OF,} \texttt{ON,}
\texttt{ONLY,} \texttt{OPEN,} \texttt{OPTION,} \texttt{OR,}
\texttt{ORDER,} \texttt{OUTER,} \texttt{OUTPUT,} \texttt{OVERLAPS,}
\texttt{PAD,} \texttt{PARTIAL,} \texttt{POSITION,}
\texttt{PRECISION,} \texttt{PREPARE,} \texttt{PRESERVE,}
\texttt{PRIMARY,} \texttt{PRIOR,} \texttt{PRIVILEGES,}
\texttt{PROCEDURE,} \texttt{PUBLIC,} \texttt{READ,} \texttt{REAL,}
\texttt{REFERENCES,} \texttt{RELATIVE,} \texttt{RESTRICT,}
\texttt{REVOKE,} \texttt{RIGHT,} \texttt{ROLLBACK,} \texttt{ROWS,}
\texttt{SCHEMA,} \texttt{SCROLL,} \texttt{SECOND,} \texttt{SECTION,}
\texttt{SELECT,} \texttt{SESSION,} \texttt{SESSION\_USER,}
\texttt{SET,} \texttt{SIZE,} \texttt{SMALLINT,} \texttt{SOME,}
\texttt{SPACE,} \texttt{SQL,} \texttt{SQLCODE,} \texttt{SQLERROR,}
\texttt{SQLSTATE,} \texttt{SUBSTRING,} \texttt{SUM,}
\texttt{SYSTEM\_USER,} \texttt{TABLE,} \texttt{TEMPORARY,}
\texttt{THEN,} \texttt{TIME,} \texttt{TIMESTAMP,}
\texttt{TIMEZONE\_HOUR,} \texttt{TIMEZONE\_MINUTE,} \texttt{TO,}
\texttt{TRAILING,} \texttt{TRANSACTION,} \texttt{TRANSLATE,}
\texttt{TRANSLATION,} \texttt{TRIM,} \texttt{TRUE,} \texttt{UNION,}
\texttt{UNIQUE,} \texttt{UNKNOWN,} \texttt{UPDATE,} \texttt{UPPER,}
\texttt{USAGE,} \texttt{USER,} \texttt{USING,} \texttt{VALUE,}
\texttt{VALUES,} \texttt{VARCHAR,} \texttt{VARYING,} \texttt{VIEW,}
\texttt{WHEN,} \texttt{WHENEVER,} \texttt{WHERE,} \texttt{WITH,}
\texttt{WORK,} \texttt{WRITE,} \texttt{YEAR,} \texttt{ZONE}
\end{raggedright}

\subsubsection{ADQL reserved keywords}
\label{sec:adql.reswords}


\begin{raggedright}
\paragraph{Mathematical functions and operators}
\texttt{ABS,} \texttt{ACOS,} \texttt{ASIN,} \texttt{ATAN,}
\texttt{ATAN2,} \texttt{CEILING,} \texttt{COS,} \texttt{COT,}
\texttt{DEGREES,} \texttt{EXP,} \texttt{FLOOR,} \texttt{LOG,}
\texttt{LOG10,} \texttt{MOD,}  \texttt{PI,} \texttt{POWER,}
\texttt{RADIANS,} \texttt{RAND,} \texttt{ROUND,} \texttt{SIN,}
\texttt{SQRT,} \texttt{TAN,} \texttt{TRUNCATE}
\end{raggedright}


\begin{raggedright}
\paragraph{Geometric functions and operators}
\texttt{AREA,} \texttt{BOX,} \texttt{CENTROID,} \texttt{CIRCLE,}
\texttt{CONTAINS,} \texttt{COORD1,} \texttt{COORD2,}
\texttt{COORDSYS,} \texttt{DISTANCE,} \texttt{INTERSECTS,}
\texttt{POINT,} \texttt{POLYGON,} \texttt{REGION}
\end{raggedright}

\begin{raggedright}
\paragraph{CAST function and datatypes}
\texttt{BIGINT}
\end{raggedright}

\begin{raggedright}
\paragraph{String functions and operators}
\texttt{ILIKE}
\end{raggedright}

\begin{raggedright}
\paragraph{Conversion functions}
\texttt{IN\_UNIT}
\end{raggedright}

\begin{raggedright}
\paragraph{Cardinality}
\texttt{OFFSET} \texttt{TOP}
\end{raggedright}


\subsubsection{Identifiers}
\label{sec:adql.identifiers}

Identifiers MUST begin with a letter
\verb:{aA-zZ}:, subsequent characters MAY be letters, underscores or
digits \verb:{0-9}: as follows:

\begin{verbatim}
<Latin_letter>... [{ <digit> | <Latin_letter> | <underscore> }...]
\end{verbatim}

\subsubsection{Delimited identifiers}
\label{sec:adql.escape}

To address reserved keyword and special character conflicts the ADQL language
provides a way to escape a non-compliant identifier by using the double
quote character \verb:": as a delimiter.

For example, to use the reserved word SIZE as a column name, in upper or lower case,
it must be isolated using double quotes.

\begin{itemize}
    \item \verb:size: -- Invalid column name
    \item \verb:"size": -- Valid column name
\end{itemize}

\subsubsection{Case sensitivity}
\label{sec:adql.case}

In addition to isolating keyword conflicts and special characters,
the double quote escape syntax also denotes case sensitivity.

Without double quotes, the following identifiers are all equivalent:
\begin{verbatim}
    alpha == Alpha == ALPHA
\end{verbatim}

When escaped using double quotes, the same set of identifiers are not equivalent:
\begin{verbatim}
    "alpha" != "Alpha" != "ALPHA"
\end{verbatim}

Data providers should avoid defining column names using delimited identifiers.
Indeed, when identifiers are mixed-case or are not written in the default case
(uppercase by SQL92, lowercase in most modern RDBMSes), users must use delimited
identifiers. This, in turn, may lead to interoperability problems between
services offering the same table, or to failing backwards compatibility when
moving between backend RDBMSes.

\subsubsection{Literals}
\label{sec:literals}

String literals are expressed as a character expression delimited by single
quotes.

\begin{verbatim}
    <character_string_literal> ::=
        <quote> [ <character_representation>... ] <quote>
\end{verbatim}

A single quote inside a string literal must be escaped with a second single
quote. For instance:

\begin{verbatim}
    'Earth''s satellite is the Moon.'
\end{verbatim}

Numeric literals are expressed as an exact decimal value, e.g. \verb:12: or
\verb:12.3:, or a floating point number with an exponent, e.g. \verb:12.3E4:.

\begin{verbatim}
    <signed_numeric_literal> ::= [<sign>] <unsigned_numeric_literal>

    <unsigned_numeric_literal> ::=
        <exact_numeric_literal>
      | <approximate_numeric_literal>

    <exact_numeric_literal> ::=
        <unsigned_decimal> [<period> [<unsigned_decimal>]]
      | <period><unsigned_decimal>

    <approximate_numeric_literal> ::= <mantissa> E <exponent>

    <mantissa> ::= <exact_numeric_literal>

    <exponent> ::= <signed_decimal>

    <signed_decimal> ::= [<sign>] <unsigned_decimal>

    <unsigned_decimal> ::= <digit>...

    <digit> ::= 0 | 1  | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9

    <sign> ::= <plus_sign> | <minus_sign>
\end{verbatim}

\subsubsection{Whitespace}
\label{sec:whitespace}

The rules on where whitespace is allowed and required are as in SQL-92;
essentially, any \verb:<token>: may be followed by a \verb:<separator>:.

\subsubsection{Comments}
\label{sec:comments}

As in SQL-92, comments are supported in ADQL. A comment is syntactically legal
wherever whitespace is legal and can then stand in for that whitespace. It
starts with a double minus sign and ends with the end of line.

\begin{verbatim}
    <comment> ::= <comment_introducer> [ <comment_character>... ] <newline>

    <comment_character> ::= <nonquote_character> | <quote>

    <comment_introducer> ::= <minus_sign><minus_sign> [<minus_sign>...]
\end{verbatim}

Comments are not expected to be interpreted by ADQL parsers.

\clearpage % to keep the entire verbatim block for query syntax on the same page
\subsection{Query syntax}
\label{sec:syntax}

A more detailed definition of the \verb:SELECT: statement is given by the \verb:<query_specification>:
construct defined in \AppendixRef{sec:grammar}.

A simplified syntax for the \verb:SELECT: statement follows, showing the main constructs for
the query specification:

\begin{verbatim}
    [ WITH { cte_name AS ( SELECT ... ) }, ... ]
    SELECT
        [ ALL | DISTINCT ]
        [ TOP unsigned_decimal ]
        {
            *
          | { value_expression [ [AS] column_name ] }, ...
        }
    FROM {
        {
            table_name [ [AS] identifier ]
          | ( SELECT ...) [AS] identifier
          | table_reference [NATURAL]
            [ INNER | { LEFT | RIGHT | FULL [OUTER] } ]
            JOIN table_reference
            [ON search_condition | USING ( column_name,...) ]
        },
        ...
    }
    [ WHERE search_condition ]
    [ GROUP BY group_by_term, ... ]
    [ HAVING search_condition ]
    [ {
        { UNION | INTERSECT | EXCEPT } [ALL]
        SELECT ...
      }
      ...
    ]
    [ ORDER BY { order_by_expression } [ ASC | DESC ], ... ]
    [ OFFSET unsigned_decimal ]
\end{verbatim}

The \verb:SELECT: statement defines a query to apply to a set of tables specified
in the \verb:FROM: clause. As a result of this query, a subset of the tables
is returned.
The order of the rows MAY be arbitrary unless an \verb:ORDER BY: clause is specified.
A \verb:TOP: clause may be specified to limit the number of rows returned.
An \verb:OFFSET: clause may be specified to skip a number of rows at the start
of the results.
If both \verb:TOP: and \verb:OFFSET: are used together then \verb:OFFSET: is applied
first followed by \verb:TOP: \SectionSee{sec:offset}.

The order of the columns in the query results SHALL be the same as the
order specified in the selection list,
%or the order defined in the original table if
unless an asterisk is specified.

\subsubsection{Subqueries}
\label{sec:subqueries}
%TBD - cosmopterix tests for this

Table subqueries may be used by predicates such as \verb:IN: and \verb:EXISTS:
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
          )
\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
\end{verbatim}

If supported by the implementation, table subqueries may be used for declaring
named result sets in the \verb:WITH: clause of the main query:

\begin{verbatim}
    WITH subsample AS (
        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
\end{verbatim}

\subsubsection{Joins}
\label{sec:joins}
%TBD - cosmopterix tests for this

ADQL supports \verb:INNER: and \verb:OUTER:
(\verb:LEFT:, \verb:RIGHT: and \verb:FULL:) joins. If no type is specified, the
default is \verb:INNER:. All of these can be \verb:NATURAL: or not.

%REMOVED: The join condition does not support embedded sub joins.
%REASON: The BNF allows nested JOINs.

\subsubsection{Search condition}
\label{sec:search}

A search condition may be part of other clauses including \verb:JOIN:, \verb:HAVING: and \verb:WHERE:.

A search condition may contain the standard logical operators, \verb:AND:, \verb:OR: and \verb:NOT:.

A search condition may contain the following predicates:

\begin{itemize}
    \item Standard comparison operators: \verb:=:, \verb:!=:, \verb:<>:, \verb:<:, \verb:>:, \verb:<=:, \verb:>=:
    \item Range comparison: \verb:BETWEEN:
    \item Membership check: \verb:IN:
    \item Case-sensitive string comparison: \verb:LIKE:
    \item Null value checks: \verb:IS NULL:, \verb:IS NOT NULL:
    \item Non-empty subquery check: \verb:EXISTS:
\end{itemize}

In addition, some service implementations may also support the optional \verb:ILIKE:
case-insensitive string comparison operator, defined in \SectionRef{sec:string.functions.ilike}.

\begin{itemize}
    \item \verb:ILIKE:
\end{itemize}

\subsection{Mathematical and Trigonometrical Functions}
\label{sec:math.functions}

ADQL declares a list of reserved keywords \SectionSee{sec:keywords} which include
the mathematical and trigonometrical function names. Their syntax,
usage and description are detailed in tables~\ref{table:math.functions}
and \ref{table:trig.functions}.

\begin{table}[tpb]\footnotesize
    \begin{tabular}{|p{0.20\textwidth}|p{0.125\textwidth}|p{0.125\textwidth}|p{0.55\textwidth}|}

        \hline
        \textbf{Name} &
        \textbf{Argument \newline datatype} &
        \textbf{Return \newline datatype} &
        \textbf{Description}
        \tabularnewline

        \hline
        abs(x) &
        \textit{x} double &
        double &
        Returns the absolute value of \textit{x}.
        \tabularnewline

        \hline
        ceiling(x) &
        \textit{x} double &
        double &
        Returns the smallest integer that is not less than \textit{x}.
        \tabularnewline

        \hline
        degrees(x) &
        \textit{x} double &
        double &
        Converts the angle \textit{x} from radians to degrees.
        \tabularnewline

        \hline
        exp(x) &
        \textit{x} double &
        double &
        Returns Euler’s number \textit{e} raised to the power of \textit{x}.
        \tabularnewline

        \hline
        floor(x) &
        \textit{x} double &
        double &
        Returns the largest integer that is not greater than \textit{x}.
        \tabularnewline

        \hline
        log(x) &
        \textit{x} double &
        double &
        Returns the natural logarithm (base \textit{e}) of \textit{x}. The value of \textit{x} must be greater than zero.
        \tabularnewline

        \hline
        log10(x) &
        \textit{x} double &
        double &
        Returns the base 10 logarithm of \textit{x}. The value of \textit{x} must be greater than zero.
        \tabularnewline

        \hline
        mod(x,y) &
        \textit{x} double,
        \newline
        \textit{y} double &
        double &
        Returns the remainder \textit{r} of \textit{x/y} as a double,
        where:
        \begin{itemize}
            \item \textit{r} has the same sign as \textit{x}
            \item |\textit{r}| is less than |\textit{y}|
            \item \textit{x} = (\textit{f} * \textit{y}) + \textit{r} for a given integer \textit{f}
        \end{itemize}
        \tabularnewline

        \hline
        pi() &
        &
        double &
        The numeric constant \(\pi\).
        \tabularnewline

        \hline
        power(x,y) &
        \textit{x} double,
        \newline
        \textit{y} double &
        double &
        Returns the value of \textit{x} raised to the power of \textit{y}.
        \tabularnewline

        \hline
        radians(x) &
        \textit{x} double &
        double &
        Converts the angle \textit{x} from degrees to radians.
        \tabularnewline

        \hline
        sqrt(x) &
        \textit{x} double &
        double &
        Returns the positive square root of \textit{x}.
        \tabularnewline

        \hline
        rand(x) &
        \textit{x} double &
        double &
        Returns a random value between 0.0 and 1.0.
        The optional argument, \textit{x}, originally intended to provide a random seed,
        has undefined semantics. Query writers are advised to omit this argument.
        \tabularnewline

        \hline
        round(x,n) &
        \textit{x} double,
        \newline
        \textit{n} integer &
        double &
        Rounds \textit{x} to \textit{n} decimal places.
        The integer \textit{n} is optional and defaults to 0 if not specified.
        A negative value of \textit{n} will round to the left of the decimal point.
        \tabularnewline

        \hline
        truncate(x, n) &
        \textit{x} double
        \newline
        \textit{n} integer &
        double &
        Truncates \textit{x} to \textit{n} decimal places.
        The integer \textit{n} is optional and defaults to 0 if not specified.
        \tabularnewline
        \hline
    \end{tabular}
    \caption{Mathematical functions}
    \label{table:math.functions}
\end{table}

\begin{table}[tbh]\footnotesize
    \begin{tabular}{|p{0.20\textwidth}|p{0.125\textwidth}|p{0.125\textwidth}|p{0.55\textwidth}|}

        \hline
        \textbf{Name} &
        \textbf{Argument \newline datatype} &
        \textbf{Return \newline datatype} &
        \textbf{Description}
        \tabularnewline

        \hline
        acos(x) &
        \textit{x} double &
        double &
        Returns the arc cosine of \textit{x}, in the range of 0 through \(\pi\) radians. The absolute value of \textit{x} must be less than or equal to 1.0.
        \tabularnewline

        \hline
        asin(x) &
        \textit{x} double &
        double &
        Returns the arc sine of \textit{x}, in the range of -\(\pi\)/2 through \(\pi\)/2 radians. The absolute value of \textit{x} must be less than or equal to 1.0.
        \tabularnewline

        \hline
        atan(x) &
        \textit{x} double &
        double &
        Returns the arc tangent of \textit{x} , in the range of -\(\pi\)/2 through \(\pi\)/2 radians.
        \tabularnewline

        \hline
        atan2(y,x) &
        \textit{x} double,
        \newline
        \textit{y} double &
        double &
        Converts rectangular coordinates \textit{x,y} to polar angle. It computes the arc tangent of \textit{y/x} in the range of –\(\pi\) through \(\pi\) radians.
        \tabularnewline

        \hline
        cos(x) &
        \textit{x} double &
        double &
        Returns the cosine of the angle \textit{x} in radians, in the range of -1.0 through 1.0.
        \tabularnewline

        \hline
        sin(x) &
        \textit{x} double &
        double &
        Returns the sine of the angle \textit{x} in radians, in the range of -1.0 through 1.0.
        \tabularnewline

        \hline
        tan(x) &
        \textit{x} double &
        double &
        Returns the tangent of the angle \textit{x} in radians.
        \tabularnewline
        \hline
    \end{tabular}
    \caption{Trigonometrical functions}
    \label{table:trig.functions}
\end{table}

\section{Type system}
\label{sec:types}

ADQL defines no data definition language (DDL).
It is assumed that table definition and data ingestion are performed in
the underlying database's native language and type system.

However, service metadata needs to give column types in order to allow the
construction of queries that are both syntactically and semantically correct.
Examples of such metadata includes the \verb:TAP_SCHEMA: tables defined in the
\TAPSpec{} and the \verb:/tables: webservice response defined in the
\VOSISpec{}.

Services SHOULD, if at all possible, try to express their column metadata in
these terms even if the underlying database employs different types.
Services SHOULD also use the following mappings when interfacing to user data,
either by serializing result sets into VOTables or by ingesting user-provided
VOTables into ADQL-visible tables.

\subsection{Numeric types}
\label{sec:types.numeric}

\subsubsection{Numeric primitives}
\label{sec:types.numeric.primitive}

The numeric datatypes, \verb:BIT:, \verb:SMALLINT:, \verb:INTEGER:,
\verb:BIGINT:, \verb:REAL:  \linebreak and \verb:DOUBLE PRECISION: map to the
corresponding datatypes defined in the \VOTableSpec{}.

\begin{table}[h]\footnotesize
    \begin{tabular}
        {|p{0.30\textwidth}|p{0.26\textwidth}|p{0.15\textwidth}|p{0.15\textwidth}|}

        \hline
        \multicolumn{1}{|c|}{\textbf{ADQL}} &
        \multicolumn{3}{c|}{\textbf{VOTable}}
        \tabularnewline

        \hline
        \textbf{type} &
        \textbf{datatype} &
        \textbf{arraysize} &
        \textbf{xtype}
        \tabularnewline

        \hline
        BIT &
        bit &
        - &
        -
        \tabularnewline

        \hline
        SMALLINT &
        short &
        - &
        -
        \tabularnewline

        \hline
        INTEGER &
        int &
        - &
        -
        \tabularnewline

        \hline
        BIGINT &
        long &
        - &
        -
        \tabularnewline

        \hline
        REAL &
        float &
        - &
        -
        \tabularnewline

        \hline
        DOUBLE PRECISION &
        double &
        - &
        -
        \tabularnewline
        \hline
    \end{tabular}
    \caption{ADQL type mapping for numeric values}
    \label{table:types.numeric.primitive}
\end{table}

Where possible ADQL numeric values SHOULD be implemented using database types
that correspond to the VOTable serialization types, e.g. \verb:SMALLINT: should
map to a 16 bit integer, \verb:INTEGER: should map to a 32 bit integer, etc.

\subsubsection{INTERVAL}
\label{sec:types.numeric.interval}

The \DALISpec{} defines \verb:INTERVAL: as a pair of integer or floating-point
numeric values which are serialized as an array of numbers.

None of the ADQL operators apply to \verb:INTERVAL: values.
However, specific implementations MAY provide user defined functions that
operate on some \verb:INTERVAL: values.

\begin{table}[h]\footnotesize
    \begin{tabular}
        {|p{0.26\textwidth}|p{0.30\textwidth}|p{0.15\textwidth}|p{0.15\textwidth}|}

        \hline
        \multicolumn{1}{|c|}{\textbf{ADQL}} &
        \multicolumn{3}{|c|}{\textbf{VOTable}}
        \tabularnewline

        \hline
        \textbf{type} &
        \textbf{datatype} &
        \textbf{arraysize} &
        \textbf{xtype}
        \tabularnewline

        \hline
        INTERVAL &
        short, int, float, double &
        2 &
        interval
        \tabularnewline
        \hline
    \end{tabular}
    \caption{ADQL type mapping for INTERVAL}
    \label{table:types.numeric.interval}
\end{table}

The details of how \verb:INTERVAL: values behave in ADQL are not yet
defined.

\subsection{Date and time}
\label{sec:types.datetime}

Where possible, date and time values SHOULD be implemented as described in the
\DALISpec{}.

\subsubsection{TIMESTAMP}
\label{sec:types.datetime.timestamp}

The \verb:TIMESTAMP: datatype maps to the corresponding type defined in the
\DALISpec{}.

\begin{table}[h]\footnotesize
    \begin{tabular}
        {|p{0.26\textwidth}|p{0.30\textwidth}|p{0.15\textwidth}|p{0.15\textwidth}|}

        \hline
        \multicolumn{1}{|c|}{\textbf{ADQL}} &
        \multicolumn{3}{|c|}{\textbf{VOTable}}
        \tabularnewline

        \hline
        \textbf{type} &
        \textbf{datatype} &
        \textbf{arraysize} &
        \textbf{xtype}
        \tabularnewline

        \hline
        TIMESTAMP &
        char &
        n, n*, * &
        timestamp
        \tabularnewline
        \hline
    \end{tabular}
    \caption{ADQL type mapping for TIMESTAMP}
    \label{table:types.datetime.timestamp}
\end{table}

\verb:TIMESTAMP:-s can be created from string literals using the \verb:CAST(): function
(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.

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
are platform dependent. The primary requirement is that the results of the
comparison operators on \verb:TIMESTAMP: values are consistent with respect to
chronological time.

\subsection{Character types}
\label{sec:types.character}

\subsubsection{Character primitives}
\label{sec:types.character.primitive}

The \verb:CHAR: and \verb:VARCHAR: datatypes map to the \verb:char: or
\verb:unicodeChar: type defined in the \VOTableSpec{}.

The choice of whether \verb:CHAR: and \verb:VARCHAR: map to \verb:char: or
\verb:unicodeChar: is implementation dependent and may depend on the data
content.

\begin{table}[h]\footnotesize
    \begin{tabular}
        {|p{0.26\textwidth}|p{0.30\textwidth}|p{0.15\textwidth}|p{0.15\textwidth}|}

        \hline
        \multicolumn{1}{|c|}{\textbf{ADQL}} &
        \multicolumn{3}{|c|}{\textbf{VOTable}}
        \tabularnewline

        \hline
        \textbf{type} &
        \textbf{datatype} &
        \textbf{arraysize} &
        \textbf{xtype}
        \tabularnewline

        \hline
        CHAR(n) &
        char, unicodeChar &
        n &
        -
        \tabularnewline

        \hline
        VARCHAR(n) &
        char, unicodeChar &
        n* &
        -
        \tabularnewline
        \hline
    \end{tabular}
    \caption{ADQL type mapping for character strings}
    \label{table:types.character.primitive}
\end{table}

\subsubsection{CLOB}
\label{sec:types.character.clob}

To provide support for string values which are generated by the server,
ADQL includes the Character Large OBject (\verb:CLOB:) datatype,
which behaves as an opaque immutable string of characters.

None of the ADQL operators apply to \verb:CLOB: values.
However, specific database implementations MAY provide user
defined functions that operate on some \verb:CLOB: values.

\verb:CLOB: values are serialized as arrays of characters.

\begin{table}[h]\footnotesize
    \begin{tabular}
        {|p{0.26\textwidth}|p{0.30\textwidth}|p{0.15\textwidth}|p{0.15\textwidth}|}

        \hline
        \multicolumn{1}{|c|}{\textbf{ADQL}} &
        \multicolumn{3}{|c|}{\textbf{VOTable}}
        \tabularnewline

        \hline
        \textbf{type} &
        \textbf{datatype} &
        \textbf{arraysize} &
        \textbf{xtype}
        \tabularnewline

        \hline
        CLOB &
        char, unicodeChar &
        n, n*, * &
        adql:clob
        \tabularnewline
        \hline
    \end{tabular}
    \caption{ADQL type mapping for CLOB}
    \label{table:types.character.clob}
\end{table}

The details of how \verb:CLOB: values are handled within a
database is implementation dependent.

An example use case for \verb:CLOB: is a URL field that is generated on the fly
using one or more fields stored in the database.
Although some of the components are stored in the database, the final URL
that appears in the results is not stored in the database.
Hence it would not be possible to apply ADQL functions or operators to the
URL field without special knowledge of the internal database structure.
However, a service implementation could provide user defined functions
that used knowledge of the internal database structure to perform
specific operations on the generated URL field.

\subsection{Binary types}
\label{sec:types.binary}

\subsubsection{Binary primitives}
\label{sec:types.binary.primitive}

The \verb:BINARY: and \verb:VARBINARY: datatypes map to the \verb:unsignedByte:
type defined in the \VOTableSpec{}.

\begin{table}[h]\footnotesize
    \begin{tabular}
        {|p{0.26\textwidth}|p{0.30\textwidth}|p{0.15\textwidth}|p{0.15\textwidth}|}

        \hline
        \multicolumn{1}{|c|}{\textbf{ADQL}} &
        \multicolumn{3}{|c|}{\textbf{VOTable}}
        \tabularnewline

        \hline
        \textbf{type} &
        \textbf{datatype} &
        \textbf{arraysize} &
        \textbf{xtype}
        \tabularnewline

        \hline
        BINARY(n) &
        unsignedByte &
        n &
        -
        \tabularnewline

        \hline
        VARBINARY(n) &
        unsignedByte &
        n* &
        -
        \tabularnewline
        \hline
    \end{tabular}
    \caption{ADQL type mapping for binary arrays}
    \label{table:types.binary.primitive}
\end{table}

\subsubsection{BLOB}
\label{sec:types.binary.blob}

To support large blocks of binary data such as images,
ADQL includes the Binary Large OBject (\verb:BLOB:) datatype,
which behaves as an opaque immutable array of bytes.

None of the ADQL operators apply to \verb:BLOB: values.
However, specific database implementations MAY provide user
defined functions that operate on some \verb:BLOB: values.

\verb:BLOB: values are serialized as arrays of \verb:unsignedByte: defined
in the \VOTableSpec{}.

\begin{table}[h]\footnotesize
    \begin{tabular}
        {|p{0.26\textwidth}|p{0.30\textwidth}|p{0.15\textwidth}|p{0.15\textwidth}|}

        \hline
        \multicolumn{1}{|c|}{\textbf{ADQL}} &
        \multicolumn{3}{|c|}{\textbf{VOTable}}
        \tabularnewline

        \hline
        \textbf{type} &
        \textbf{datatype} &
        \textbf{arraysize} &
        \textbf{xtype}
        \tabularnewline

        \hline
        BLOB &
        unsignedByte  &
        n, n*, * &
        adql:blob
        \tabularnewline
        \hline
    \end{tabular}
    \caption{ADQL type mapping for BLOB}
    \label{table:types.binary.blob}
\end{table}

The details of how \verb:BLOB: values are handled within a
database is implementation dependent.

An example use case for \verb:BLOB: is for storing thumbnail images
in the database alongside the tabular data.
ADQL does not provide functions or operations that operate on
images.
However, a service implementation could provide user defined
functions that use implementation specific features to perform
operations on the image data.

\subsection{Geometric types}
\label{sec:types.geom}

ADQL provides support for the \verb:POINT:, \verb:CIRCLE: and \verb:POLYGON:
spherical geometry types defined in the \DALISpec{}.

ADQL also provides support for STC-S based geometric regions, as defined in the
\STCSAppendix{}, using the \verb:REGION: datatype.

\subsubsection{POINT}
\label{sec:types.geom.point}

The \verb:POINT: datatype maps to the corresponding type
for spherical coordinates defined in the
\DALISpec{}.

\verb:POINT: values are serialized as arrays of floating point numbers
using the \verb:point: xtype defined in the \DALISpec{}.

\begin{table}[h]\footnotesize
    \begin{tabular}
        {|p{0.26\textwidth}|p{0.30\textwidth}|p{0.15\textwidth}|p{0.15\textwidth}|}

        \hline
        \multicolumn{1}{|c|}{\textbf{ADQL}} &
        \multicolumn{3}{|c|}{\textbf{VOTable}}
        \tabularnewline

        \hline
        \textbf{type} &
        \textbf{datatype} &
        \textbf{arraysize} &
        \textbf{xtype}
        \tabularnewline

        \hline
        POINT &
        float, double &
        2 &
        point
        \tabularnewline
        \hline
    \end{tabular}
    \caption{ADQL type mapping for POINT}
    \label{table:types.geom.point}
\end{table}

\verb:POINT: literals can be expressed using the \verb:POINT():
constructor defined in \SectionRef{sec:functions.geom.point}.

For example:
\begin{verbatim}
    POINT(12.3, 45.6)
\end{verbatim}

\subsubsection{CIRCLE}
\label{sec:types.geom.circle}

The \verb:CIRCLE: datatype maps to the corresponding type
for spherical coordinates defined in the
\DALISpec{}.

\verb:CIRCLE: values are serialized as arrays of floating point numbers
using the \verb:circle: xtype defined in the \DALISpec{}.

\begin{table}[h]\footnotesize
    \begin{tabular}
        {|p{0.26\textwidth}|p{0.30\textwidth}|p{0.15\textwidth}|p{0.15\textwidth}|}

        \hline
        \multicolumn{1}{|c|}{\textbf{ADQL}} &
        \multicolumn{3}{|c|}{\textbf{VOTable}}
        \tabularnewline

        \hline
        \textbf{type} &
        \textbf{datatype} &
        \textbf{arraysize} &
        \textbf{xtype}
        \tabularnewline

        \hline
        CIRCLE &
        float, double &
        3 &
        circle
        \tabularnewline
        \hline
    \end{tabular}
    \caption{ADQL type mapping for CIRCLE}
    \label{table:types.geom.circle}
\end{table}

\verb:CIRCLE: literals can be expressed using the \verb:CIRCLE():
constructor defined in \SectionRef{sec:functions.geom.circle}.
For example:
\begin{verbatim}
    CIRCLE(12.3, 45.6, 0.5)
\end{verbatim}

\subsubsection{POLYGON}
\label{sec:types.geom.polygon}

The \verb:POLYGON: datatype maps to the corresponding type
for spherical coordinates defined in the
\DALISpec{}.

\verb:POLYGON: values are serialized as arrays of floating point numbers
using the \verb:polygon: xtype defined in the \DALISpec{}.

\begin{table}[h]\footnotesize
    \begin{tabular}
        {|p{0.26\textwidth}|p{0.30\textwidth}|p{0.15\textwidth}|p{0.15\textwidth}|}

        \hline
        \multicolumn{1}{|c|}{\textbf{ADQL}} &
        \multicolumn{3}{|c|}{\textbf{VOTable}}
        \tabularnewline

        \hline
        \textbf{type} &
        \textbf{datatype} &
        \textbf{arraysize} &
        \textbf{xtype}
        \tabularnewline

        \hline
        POLYGON &
        float, double &
        n, *, n* &
        polygon
        \tabularnewline
        \hline
    \end{tabular}
    \caption{ADQL type mapping for POLYGON}
    \label{table:types.geom.polygon}
\end{table}

\verb:POLYGON: literals can be expressed using the \verb:POLYGON():
constructor defined in \SectionRef{sec:functions.geom.polygon}.

For example:
\begin{verbatim}
    POLYGON(10.0, -10.5, 20.0, 20.5, 30.0, 30.5)
\end{verbatim}
\noindent
describes a triangle with vertices at (10.0, -10.5), (20.0, 20.5)
and (30.0, 30.5) degrees.

\subsubsection{REGION}
\label{sec:types.geom.region}

\verb:REGION: is introduced as the type of the result of intersections and
unions of other geometries (although ADQL at this point does not support
these operations).

We do not specify the serialisation of \verb:REGION:-typed values in result
sets.  It is expected that next version of DALI will provide normative
guidance on this. However, at least for the \textit{s\_region}
column described in the \ObsCoreSpec{},
% ObsCore 1.1 Section 4.12
% http://ivoa.net/documents/ObsCore/20170509/REC-ObsCore-v1.1-20170509.pdf#26
informal practice is to produce strings conforming to the \STCSAppendix{} with
an xtype of \texttt{adql:region}.

\clearpage % section cut
\section{Optional components}
\label{sec:optional}

In addition to the core components, the ADQL language also includes support
for optional features and functions.

The following sections define the optional features that are part of the
the ADQL grammar, but are not required in order to meet the standard for
a basic ADQL service.

It is up to each service implementation to declare which optional or
additional features it supports.

If a service does not declare support for an optional feature,
then a client SHOULD assume that the service does NOT support
that feature, and SHOULD NOT make use of that feature in any
ADQL queries that it sends.

\subsection{Service capabilities}
\label{sec:capabilities}

The \TAPRegSpec{} defines an XML schema that a service SHOULD
use to declare which optional features it supports.

In general, each group of language features is identified by a \verb:type:
URI, and each individual feature within the group is identified by the
feature name.

In the context of ADQL, the \verb:type: URI is expected to be an IVOID.

Note that IVOIDs are case insensitive. However, in order to minimize
interoperability issues when clients neglect to normalize IVOID case,
ADQL services MUST provide the feature IVOIDs in all-lower case as shown
in the present document.

\AppendixRef{sec:features} contains examples of how to declare support
for each of the language features defined in this document using the
XML schema from the \TAPRegSpec{}.

For full details on the XML schema and how it can be used, please refer to
the \TAPRegSpec{}.

\subsection{Geometrical functions}
\label{sec:functions.geom}
\subsubsection{Overview}
\label{sec:functions.geom.overview}

In addition to the mathematical functions, ADQL provides the following geometrical
functions to facilitate queries commonly useful in astronomy:

\begin{itemize}
    \item AREA
    \item BOX
    \item CENTROID
    \item CIRCLE
    \item CONTAINS
    \item COORD1
    \item COORD2
    \item COORDSYS
    \item DISTANCE
    \item INTERSECTS
    \item POINT
    \item POLYGON
    \item REGION
\end{itemize}

\subsubsection{Language feature}
\label{sec:functions.geom.feature}

All functions described in this section use the following IVOID:

\begin{verbatim}
    ivo://ivoa.net/std/tapregext#features-adqlgeo
\end{verbatim}

Each geometrical function is declared using this IVOID and its name.
See \SectionRef{sec:capabilities} for more details.

All other optional features have an IVOID starting with:

\begin{verbatim}
    ivo://ivoa.net/std/tapregext#features-adql-
\end{verbatim}

Note the ending hyphen. The IVOID for the geometry features does not have this
hyphen. This is not a typo. It actually comes from the \TAPRegSpec{} which
originally defined this IVOID. At that time, it was not clear yet that other
language features would be created for ADQL. So, for historical and
interoperability reasons the IVOID for the geometry features must not have this
hyphen.

\subsubsection{Datatype functions}
\label{sec:functions.geom.type}

Some of the functions described in this section (e.g. \verb:POINT:,
\verb:CIRCLE:) are constructors for each of the geometry datatypes. The
semantics of these datatypes are based on the corresponding concepts from the
\STCSpec{} data model.

The geometry datatypes and expressions are part of the core
\verb:<value_expression>: in the ADQL grammar.

\begin{verbatim}
    <value_expression> ::=
        NULL
      | <numeric_value_expression>
      | <string_value_expression>
      | <geometry_value_expression>
\end{verbatim}

A \verb:<geometry_value_expression>: does not simply cover the geometry datatype
constructors (POINT, CIRCLE, etc.) but also includes user defined functions and
column values where a geometry datatype is stored in a column.

Therefore, \verb:<geometry_value_expression>: is expanded as:
\begin{verbatim}
    <geometry_value_expression> ::=
        <value_expression_primary>
      | <geometry_value_function>
\end{verbatim}
\noindent
where
\begin{verbatim}
    <geometry_value_function> ::=
        <box>
      | <centroid>
      | <circle>
      | <point>
      | <polygon>
      | <region>
      | <user_defined_function>
\end{verbatim}
and \verb:<value_expression_primary>: enables the use of geometric functions
and column references.

\subsubsection{Coordinate limits}
\label{sec:functions.geom.limits}

The arguments for a geometric function represent spherical coordinates
in units of degrees (square degrees for area).

ADQL implementors and users MUST follow coordinate ranges defined in DALI 1.1
and later.

Note that at the time of the ADQL 2.1 recommendation, no agreed-upon, reliable,
IVOA-approved convention for what ranges apply to which reference system exists.
Such convention is foreseen to be defined in DALI. Presently, DALI 1.1 only
defines ranges for equatorial coordinates. However, this is expected to be
updated in future DALI versions.

Details of the mechanism for reporting the out of range arguments are
implementation dependent.

\subsubsection{Coordinate system}
\label{sec:geom.coordsys.param}

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.

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.

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 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

\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 or later 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}

Functions CONTAINS and INTERSECTS each accept two geometry datatypes
and return a numeric value of 1 or 0 according to whether the relevant
verb (e.g. contains) is satisfied against the two input geometries;
1 if the condition is met and 0 if it is not.

Each of these functions can be used as a WHERE clause predicate by
comparing the numeric result with zero or one.
For example:
\begin{verbatim}
    SELECT *
    FROM table
    WHERE 1 = CONTAINS(POINT(...), CIRCLE(...))
\end{verbatim}

%REMOVED - speculative, not definitive.
%\noindent
%One would expect later additions to ADQL to add to this range of functions. For
%example, equals, disjoint, touches, crosses, within, overlaps and relate
%are possibilities.

\subsubsection{Preferred sky crossmatch syntax}
\label{sec:functions.geom.crossmatch}

An especially common operation that astronomers require when working
with source catalogues is the positional sky crossmatch.
In its simplest form this is a join between two tables with the
requirement that the distance along a great circle between the
sky positions of the two associated rows is less than or equal to
a given threshold.

The geometrical functions provided by ADQL offer a number of
semantically equivalent ways to specify such a condition
in either the JOIN or the WHERE clause, using various
combinations of POINT, CIRCLE and DISTANCE.
While a correct implementation MUST generate the same result for
any of these alternatives, the performance characteristics may
differ dramatically depending on implementation.
Given this, it is difficult for (human or machine) ADQL authors
to know how to phrase a crossmatch with the expectation that it
will be executed efficiently, and difficult for services to know
which forms of query to optimise.  The result can be the
unnecessarily slow operation of the common sky crossmatch operation.

This section therefore recommends a preferred form of ADQL
to use for sky crossmatching and the related cone search operation,
namely to impose an upper limit on one of the two forms of the
DISTANCE function.
Clients submitting crossmatch-like and cone-like
queries are advised to phrase them in this way rather than using semantically
equivalent alternatives, and services are encouraged to ensure that
these forms of query are executed efficiently; this might involve
identifying such ADQL input clauses and rewriting them appropriately
for efficient processing on the database backend.
Alternative semantically equivalent forms however MAY still be
used by clients, and MUST still be handled correctly by services.

An example sky position-only crossmatch joining rows of tables
\textit{t1} and \textit{t2} within one arcsecond might therefore look like:
\begin{verbatim}
    JOIN ...
      ON DISTANCE(t1.ra, t1.dec, t2.ra, t2.dec) < 0.00027
\end{verbatim}
and a cone search for rows within 2.5 degrees of
the center of M31 might look like:
\begin{verbatim}
    SELECT ...
    WHERE DISTANCE(t.pos, POINT(10.68, 41.27)) <= 2.5
\end{verbatim}

\subsubsection{AREA}
\label{sec:functions.geom.area}
{\footnotesize Language feature :}\\
{\footnotesize \verb|type: ivo://ivoa.net/std/tapregext#features-adqlgeo|}\\
{\footnotesize \verb|name: AREA|}\\

The AREA function computes the area, in square degrees, of a given geometry.

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))
\end{verbatim}

The AREA of a single POINT is zero.

The geometry 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}
    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.

\subsubsection{BOX}
\label{sec:functions.geom.box}
{\footnotesize Language feature :}\\
{\footnotesize \verb|type: ivo://ivoa.net/std/tapregext#features-adqlgeo|}\\
{\footnotesize \verb|name: BOX|}\\

Note - the \verb|BOX| function has been deprecated in version 2.1 of the standard,
and will be removed from future versions of the specification.

The BOX function expresses a box on the sky. A BOX is a special case of POLYGON,
defined purely for convenience,
and it corresponds semantically to the equivalent term, Box, defined in
the \STCSpec{}.
%(STC Box, Section 4.5.1.5)

It is specified by a center position and size
(in both axes) defining a cross centered on the center position and
with arms extending, parallel to the coordinate axes at the center position,
for half the respective sizes on either side. The box’s sides are line
segments or great circles intersecting the arms of the cross in its end
points at right angles with the arms.

% Original text in ADQL.
% It is specified by a center position and size
% (in both axes) defining a cross centered on the center position and
% with arms extending, parallel to the coordinate axes at the center position,
% for half the respective sizes on either side. The box’s sides are line
% segments or great circles intersecting the arms of the cross in its end
% points at right angles with the arms.

% Text from STC-20071030
% A Box is a special case of a Polygon, defined purely for convenience.
% It is specified by a center position and size (in both coordinates)
% defining a cross centered on the center position and with arms
% extending, parallel to the coordinate axes at the center position,
% for half the respective sizes on either side.
% The box’s sides are line segments or great circles intersecting the
% arms of the cross in its end points at right angles with the arms.

The function arguments specify the center position and the width and height,
where:
\begin{itemize}
    \item the center position is given by a pair of numeric coordinates
          in degrees, or a single geometric POINT
    \item the values of coordinates of the center position are subject to the
          constraints laid down in \SectionRef{sec:functions.geom.limits}
    \item the width and height are given by numeric values in degrees
\end{itemize}

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)
\end{verbatim}

Alternatively, the center position could be expressed as a POINT:
\begin{verbatim}
    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
column references, functions or expressions that return the appropriate
datatypes.
For example:
\begin{verbatim}
    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
and DOUBLE values respectively.
%TODO - ObsCore example

%coordsys param
For historical reasons, the BOX function accepts an optional string literal as
the first argument.
As of version 2.1 of the specification this parameter has been
marked as deprecated.
Future versions of this specification may remove this parameter
\SectionSee{sec:geom.coordsys.param}.

\subsubsection{CENTROID}
\label{sec:functions.geom.centroid}
{\footnotesize Language feature :}\\
{\footnotesize \verb|type: ivo://ivoa.net/std/tapregext#features-adqlgeo|}\\
{\footnotesize \verb|name: CENTROID|}\\

The CENTROID function computes the centroid of a given geometry and returns a POINT.

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))
\end{verbatim}

The CENTROID of a single POINT is that POINT.

The geometry 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}
    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.
%TODO - ObsCore example

\subsubsection{CIRCLE}
\label{sec:functions.geom.circle}
{\footnotesize Language feature :}\\
{\footnotesize \verb|type: ivo://ivoa.net/std/tapregext#features-adqlgeo|}\\
{\footnotesize \verb|name: CIRCLE|}\\

The CIRCLE function expresses a circular region on the sky (a cone in space),
and it corresponds semantically to the equivalent term, Circle, defined in
the \STCSpec{}.
%(STC Circle, Section 4.5.1.2)

The function arguments specify the center position and the radius, where:
\begin{itemize}
    \item the center position is given by a pair of numeric coordinates
          in degrees, or a single geometric POINT
    \item the values of coordinates of the center position are subject to the
          constraints laid down in \SectionRef{sec:functions.geom.limits}
    \item the radius is a numeric value in degrees.
\end{itemize}

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)
\end{verbatim}

Alternatively, the center position may be expressed as a POINT:
\begin{verbatim}
    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)
\end{verbatim}
where \textit{t1.center} and \textit{t1.radius} are references to
database columns that contain POINT and DOUBLE values respectively.
%TODO - ObsCore example

%coordsys param
For historical reasons, the CIRCLE function accepts an optional string literal
as the first argument.
As of version 2.1 of the specification this parameter has been
marked as deprecated.
Future versions of this specification may remove this parameter
\SectionSee{sec:geom.coordsys.param}.

\subsubsection{CONTAINS}
\label{sec:functions.geom.contains}
{\footnotesize Language feature :}\\
{\footnotesize \verb|type: ivo://ivoa.net/std/tapregext#features-adqlgeo|}\\
{\footnotesize \verb|name: CONTAINS|}\\

The CONTAINS function determines if a geometry is wholly contained within
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:
\begin{verbatim}
    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.

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 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))
\end{verbatim}
\noindent
for ``does contain'' and
\begin{verbatim}
    WHERE 0 = CONTAINS(POINT(25.0, -19.5),
                       CIRCLE(25.4, -20.0, 10.0))
\end{verbatim}
\noindent
for ``does not contain''.

%TODO - CONTAINS(thing, POINT) ?

The geometric arguments for CONTAINS may be literal values, as above,
or they may be column references, functions or expressions that return
geometric values.
For example:
\begin{verbatim}
    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)
values respectively.
%TODO - ObsCore example

%coordsys trans
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}
{\footnotesize Language feature :}\\
{\footnotesize \verb|type: ivo://ivoa.net/std/tapregext#features-adqlgeo|}\\
{\footnotesize \verb|name: COORD1|}\\

The COORD1 function extracts the first coordinate value, in degrees, of a given
POINT \SectionSee{sec:functions.geom.point} or column reference.

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))
\end{verbatim}
\noindent
which would return a numeric value of 25.0 degrees.

For example:
\begin{verbatim}
    COORD1(t.center)
\end{verbatim}
\noindent
where \textit{t.center} is a reference to a column that contains POINT values.

\subsubsection{COORD2}
\label{sec:functions.geom.coord2}
{\footnotesize Language feature :}\\
{\footnotesize \verb|type: ivo://ivoa.net/std/tapregext#features-adqlgeo|}\\
{\footnotesize \verb|name: COORD2|}\\

The COORD2 function extracts the second coordinate value, in degrees, of a given
POINT \SectionSee{sec:functions.geom.point} or column reference.

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))
\end{verbatim}
\noindent
which would return a numeric value of -19.5 degrees.

The COORD2 function may be applied to any expression that returns a
geometric POINT value.
For example:
\begin{verbatim}
    COORD2(t.center)
\end{verbatim}
\noindent
where \textit{t.center} is a reference to a column that contains POINT values.

\subsubsection{COORDSYS}
\label{sec:functions.geom.coordsys}
{\footnotesize Language feature :}\\
{\footnotesize \verb|type: ivo://ivoa.net/std/tapregext#features-adqlgeo|}\\
{\footnotesize \verb|name: COORDSYS|}\\

As of version 2.1 of the specification the COORDSYS function has
been marked as deprecated. This function may be removed in future versions
of this specification.
Details of the coordinate system for a database column are available as part of
the service metadata, available via the \verb:TAP_SCHEMA: tables defined in the
\TAPSpec{} and the \verb:/tables: webservice response defined in the \VOSISpec{}.

%As described in \SectionRef{sec:functions.geom.overview}, the allowed return values must be defined
%by any service making use of ADQL, and a list of standard coordinate system
%literals can be found in the STC specification.
% STC-reference 'STC specification [3]'

The COORDSYS function returns the formal name of the coordinate system for
a given geometry as a string.

The following example would return the coordinate system of a POINT literal:
\begin{verbatim}
    COORDSYS(POINT(25.0, -19.5))
\end{verbatim}
\noindent
which would return a string value representing the coordinate system used
to create the POINT.

The COORDSYS function may be applied to any expression that returns a
geometric datatype. For example:
\begin{verbatim}
    COORDSYS(t.footprint)
\end{verbatim}
\noindent
where \textit{t.footprint} is a reference to a database column that
contains geometric (POINT, BOX, CIRCLE, POLYGON or REGION) values.

\subsubsection{DISTANCE}
\label{sec:functions.geom.distance}
{\footnotesize Language feature :}\\
{\footnotesize \verb|type: ivo://ivoa.net/std/tapregext#features-adqlgeo|}\\
{\footnotesize \verb|name: DISTANCE|}\\

The DISTANCE function computes the arc length along a great circle between two
points and returns a numeric value expression in degrees.

The specification defines two versions of the DISTANCE function, one that
accepts two POINT values, and a second that accepts four separate numeric
values.

If an ADQL service implementation declares support for DISTANCE,
then it must implement both the two parameter and four parameter
forms of the function.

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))
\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)
\end{verbatim}

The DISTANCE function may be applied to any expression that returns a
geometric POINT value. Behaviour for expressions returning a geometry different
from a POINT is undefined at this point (but may be defined later).

For example, the distance between two points stored in the database could
be calculated as follows:
\begin{verbatim}
    DISTANCE(t1.base, t2.target)
\end{verbatim}
\noindent
where \textit{t1.base} and \textit{t2.target} are references to
database columns that contain POINT values.

%coordsys trans
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}
{\footnotesize Language feature :}\\
{\footnotesize \verb|type: ivo://ivoa.net/std/tapregext#features-adqlgeo|}\\
{\footnotesize \verb|name: INTERSECTS|}\\

The INTERSECTS function determines if two geometry values overlap. This is
most commonly used to express a ``shape-vs-shape'' intersection test.

For example, an expression to determine whether a circle of one degree radius
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))
\end{verbatim}
\noindent
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 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,
                                 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))
\end{verbatim}
\noindent
for ``does not intersect''.

The geometric arguments for INTERSECTS may be literal values, as above,
or they may be column references, functions or expressions that return
geometric values.
For example:
\begin{verbatim}
    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.

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.

%coordsys trans
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}
{\footnotesize Language feature :}\\
{\footnotesize \verb|type: ivo://ivoa.net/std/tapregext#features-adqlgeo|}\\
{\footnotesize \verb|name: POINT|}\\

The POINT function expresses a single location on the sky,
and it corresponds semantically to the equivalent term, SpatialCoord, defined in
the \STCSpec{}.
%(STC SpatialCoord, Section 4.4.2.2)

The function arguments specify the position, where:
\begin{itemize}
    \item the position is given by a pair of numeric coordinates in degrees
    \item the values of coordinates are subject to the constraints laid down in
          \SectionRef{sec:functions.geom.limits}
\end{itemize}

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)
\end{verbatim}
\noindent
where numeric values are in degrees.

The coordinates for POINT may be literal values, as above,
or they may be column references, functions or expressions that return
numeric values.
For example:
\begin{verbatim}
    POINT(t.ra, t.dec)
\end{verbatim}
\noindent
where \textit{t.ra} and \textit{t.dec} are references to database
columns that contain numeric values.
%TODO - ObsCore example

%coordsys param
For historical reasons, the POINT function accepts an optional string literal
as the first argument.
As of version 2.1 of the specification this parameter has been
marked as deprecated.
Future versions of this specification may remove this parameter
\SectionSee{sec:geom.coordsys.param}.

\subsubsection{POLYGON}
\label{sec:functions.geom.polygon}
{\footnotesize Language feature :}\\
{\footnotesize \verb|type: ivo://ivoa.net/std/tapregext#features-adqlgeo|}\\
{\footnotesize \verb|name: POLYGON|}\\

The POLYGON function expresses a region on the sky with boundaries denoted by great
circles passing through specified coordinates. It corresponds semantically
to the STC Polygon.
%(STC Polygon, Section 4.5.1.4)

A polygon is described by a list of vertices in a single coordinate system, with
each vertex connected to the next along a great circle and the last vertex
implicitly connected to the first vertex.

The function arguments specify three or more vertices, where:
\begin{itemize}
    \item the position of the vertices are given as a sequence of numeric
          coordinates in degrees, or as a sequence of geometric POINTs
    \item the values of coordinates are subject to the constraints laid down in
          \SectionRef{sec:functions.geom.limits}
\end{itemize}

For example, a function expressing a triangle with vertices at (10.0,
-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)
\end{verbatim}
\noindent
where all numeric values are in degrees.

The coordinates for the POLYGON vertices may be literal values, as above,
or they may be column references, functions or expressions that return
numeric values.
For example:
\begin{verbatim}
    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
that contain numeric values.
%TODO - ObsCore example

Alternatively, the coordinates for the POLYGON vertices may be column references,
functions or expressions that return POINT values.
For example:
\begin{verbatim}
    POLYGON(t2.toppoint, t2.bottomleft, t2.bottomright)
\end{verbatim}
\noindent
where \textit{t2.toppoint}, \textit{t2.bottomleft} and \textit{t2.bottomright}
are references to database columns that contain POINT values.
%TODO - ObsCore example

The coordinates for the vertices MUST all be expressed in the same datatype.
The POLYGON function does not support a mixture of numeric and POINT
arguments.

%coordsys param
For historical reasons, the POLYGON function accepts an optional string literal
as the first argument.
As of version 2.1 of the specification this parameter has been
marked as deprecated.
Future versions of this specification may remove this parameter
\SectionSee{sec:geom.coordsys.param}.

\subsubsection{REGION}
\label{sec:functions.geom.region}

{\footnotesize Language feature :}\\
{\footnotesize \verb|type: ivo://ivoa.net/std/tapregext#features-adqlgeo|}\\
{\footnotesize \verb|name: REGION|}\\


The REGION function provides a way of expressing a complex region
represented by a single string literal. The standard expressly only
requires literals as arguments rather than string expressions or column
references. The latter would require parsing these representations
within the database, which is not intended.

This document does not specify possible syntaxes for REGION literals. A de-facto
standard that many services understanding ADQL 2.0 implemented at least
partially is given by the \STCSAppendix{}, and implementations of ADQL 2.1 are
encouraged to support as much of that as reasonable for them.

\subsection{User defined functions}
\label{sec:user.functions}
\subsubsection{Overview}

ADQL also provides a place holder to define user specific functions. The grammar
definition for user defined functions includes a variable list of parameters.

\begin{verbatim}
    <user_defined_function> ::=
        <user_defined_function_name> <left_paren>
            [
            <value_expression>
                [
                    {
                    <comma> <value_expression>
                    }...
                ]
            ]
        <right_paren>
\end{verbatim}

In order to avoid name conflicts, user defined function names SHOULD include
a prefix which indicates the name of the institute or project which created
the function.

For example, the names of \verb:align: and \verb:convert: functions developed
by the Wide Field Astronomy Unit (WFAU) could be prefixed as follows:
\begin{verbatim}
    wfau_align()
    wfau_convert()
\end{verbatim}

This enables users to distinguish between functions with similar names developed
by a different service provider, e.g. the German Astrophysical Virtual
Observatory (GAVO):
\begin{verbatim}
    gavo_align()
    gavo_convert()
\end{verbatim}

The \verb:ivo: prefix is reserved for functions that have been defined in an
IVOA specification or Endorsed Note. For example the \CatalogueUDF{} defines the
following functions:
\begin{verbatim}
    ivo_nocasematch()
    ivo_hasword()
    ivo_hashlist_has()
    ivo_string_agg()
\end{verbatim}

The \CatalogueUDF{} collects many \verb:ivo: prefixed functions defined in other
IVOA specifications, Endorsed Notes and functions defined in at least two
implementations. At the time of this writing it is the only endorsed IVOA
document providing such a collection of \verb:ivo: prefixed functions. It is
then strongly recommended to follow function names and definitions from this
catalogue when providing functions offering identical or similar functionnality.

\subsubsection{Metadata}
\label{sec:user.metadata}

The URI for identifying the language feature for a user defined function
is defined as part of the \TAPRegSpec{}.

\begin{verbatim}
    ivo://ivoa.net/std/tapregext#features-udf
\end{verbatim}

For user defined functions, the \verb:form: element of the language feature
declaration must contain the signature of the function, written to match
the signature nonterminal in the following grammar:
\begin{verbatim}
    signature ::= <funcname> <arglist> "->" <type_name>
    funcname ::= <regular_identifier>
    arglist ::= "(" <arg> { "," <arg> } ")"
    arg ::= <regular_identifier> <type_name>
\end{verbatim}

\verb:<type_name>: should be one of the terms defined in \SectionRef{sec:types}.

For example, the following fragment declares a user defined function that
takes two string parameters and returns an integer, zero or one,
depending on the regular expression pattern matching:
\begin{verbatim}
<languageFeatures type="ivo://ivoa.net/std/tapregext#features-udf">
    <feature>
        <form>match(pattern VARCHAR, string VARCHAR) -> INTEGER</form>
        <description>
            match returns 1 if the POSIX regular expression pattern
            matches anything in string, 0 otherwise.
        </description>
    </feature>
</languageFeatures>
\end{verbatim}

See the \TAPRegSpec{} for full details on how to use the
XML schema to declare user defined functions.

\subsection{String functions and operators}
\label{sec:string.functions}

An ADQL service implementation MAY include support for the following optional
string manipulation and comparison operators:

\begin{itemize}
    \item \verb:LOWER(): Lower case conversion
    \item \verb:UPPER(): Upper case conversion
    \item \verb:ILIKE: Case-insensitive comparison.
\end{itemize}

\subsubsection{Case folding}

Since case folding is a nontrivial operation in a multi-encoding world, ADQL
requires standard behaviour for the ASCII characters, and recommends
following algorithms described in Section 3.13, ``Default Case Algorithms''
of \citet{std:UNICODE} for characters outside the ASCII set:

\begin{itemize}
    \item algorithm R1 for \verb:UPPER():
    \item algorithm R2 for \verb:LOWER(): and \verb:ILIKE:
\end{itemize}

\subsubsection{LOWER}
\label{sec:string.functions.lower}
{\footnotesize Language feature :}\\
{\footnotesize \verb|type: ivo://ivoa.net/std/tapregext#features-adql-string|}\\
{\footnotesize \verb|name: LOWER|}\\

The LOWER function converts its string parameter to lower case in accordance with the rules of the database's locale.

\begin{verbatim}
    LOWER('Francis Albert Augustus Charles Emmanuel')
    =>
    francis albert augustus charles emmanuel
\end{verbatim}

\subsubsection{UPPER}
\label{sec:string.functions.upper}
{\footnotesize Language feature :}\\
{\footnotesize \verb|type: ivo://ivoa.net/std/tapregext#features-adql-string|}\\
{\footnotesize \verb|name: UPPER|}\\

The UPPER function converts its string parameter to upper case in accordance with the rules of the database's locale.

\begin{verbatim}
    UPPER('Francis Albert Augustus Charles Emmanuel')
    =>
    FRANCIS ALBERT AUGUSTUS CHARLES EMMANUEL
\end{verbatim}

\subsubsection{ILIKE}
\label{sec:string.functions.ilike}
{\footnotesize Language feature :}\\
{\footnotesize \verb|type: ivo://ivoa.net/std/tapregext#features-adql-string|}\\
{\footnotesize \verb|name: ILIKE|}\\

The ILIKE string comparison operator performs a case-insensitive comparison
of its string operands.

\begin{verbatim}
    'Francis'  LIKE 'francis' => False

    'Francis' ILIKE 'francis' => True
\end{verbatim}

\subsection{Common table expressions}
\label{sec:common-table}

An ADQL service implementation MAY include support for the following optional
common table expressions:

\begin{itemize}
    \item \verb:WITH:
\end{itemize}

\subsubsection{WITH}
{\footnotesize Language feature :}\\
{\footnotesize \verb|type: ivo://ivoa.net/std/tapregext#features-adql-common-table|}\\
{\footnotesize \verb|name: WITH|}\\

The WITH operator creates a temporary named result set that can be referred
to elsewhere in the main query.

Using a common table expression can make complex queries easier to understand
by factoring subqueries out of the main SQL statement.

For example, the following query with a nested subquery:
\begin{verbatim}
    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
\end{verbatim}

The current version of ADQL does not support recursive common table expressions.

Common table expressions can be defined only in the main
query. They are not allowed in sub-queries.

\subsection{Set operators}
\label{sec:set.operators}

An ADQL service implementation MAY include support for the following optional
set operators:

\begin{itemize}
    \item \verb:UNION:
    \item \verb:EXCEPT:
    \item \verb:INTERSECT:
\end{itemize}

For a set operation to be valid in ADQL, the following criteria must be met:
\begin{itemize}
    \item the two queries MUST result in the same number of columns
    \item the columns in the operands MUST have the same datatypes.
\end{itemize}

In addition, the columns returned by a set operation SHOULD have the same
metadata, e.g. units, UCD, etc. These metadata SHOULD be generated from the
left-hand operand of the set operation.

\subsubsection{UNION}
{\footnotesize Language feature :}\\
{\footnotesize \verb|type: ivo://ivoa.net/std/tapregext#features-adql-sets|}\\
{\footnotesize \verb|name: UNION|}\\

The UNION operator combines the results of two queries, accepting rows from
both the first and second set of results.

\subsubsection{EXCEPT}
{\footnotesize Language feature :}\\
{\footnotesize \verb|type: ivo://ivoa.net/std/tapregext#features-adql-sets|}\\
{\footnotesize \verb|name: EXCEPT|}\\

The EXCEPT operator combines the results of two queries, accepting rows that are
in the first set of results but are not in the second one.

\subsubsection{INTERSECT}
{\footnotesize Language feature :}\\
{\footnotesize \verb|type: ivo://ivoa.net/std/tapregext#features-adql-sets|}\\
{\footnotesize \verb|name: INTERSECT|}\\

The INTERSECT operator combines the results of two queries, accepting rows
that are strictly in both the first and second set of results.

\subsubsection{Duplicated rows}

\verb:UNION:, \verb:EXCEPT: and \verb:INTERSECT: remove duplicated rows,
while \verb:UNION ALL:, \verb:EXCEPT ALL: and \verb:INTERSECT ALL: keep all of
them.

Note that the comparison used for removing duplicated rows is based purely on
the column value and does not take into account the units. This means that a row
with a numeric value of \verb:2: and unit of \verb:m: and a row with a numeric
value of \verb:2: and unit of \verb:km: will be considered equal, despite the
difference in units.

\subsubsection{Operands}

Operands of any of the set operators can only be \verb:SELECT: queries.
Unless within parentheses, such queries can not use any \verb:ORDER BY: or
\verb:OFFSET: clause.

Example: sorting result of a \verb:UNION: operation:

\begin{verbatim}
        SELECT id, ra, dec FROM table1
    UNION
        SELECT id, ra, dec FROM table2
    ORDER BY id -- sort the UNION result
\end{verbatim}

Example: sorting result of the \verb:UNION: operands:

\begin{verbatim}
        -- take the 10 first
        (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)
\end{verbatim}

Common table expressions are not allowed in any set operator operand. They must
always be declared at the main level.

Example: sorting result of the \verb:UNION: operands: with common table
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)
  SELECT * FROM tenFirst
UNION
  SELECT * FROM tenLast
\end{verbatim}

\subsubsection{Precedence}

When set operators are used together, the resulting expression is
evaluated in the context of the following precedence:

\begin{enumerate}
    \item Expressions within parentheses
    \item The \verb:INTERSECT: operator
    \item The \verb:UNION: and \verb:EXCEPT: operators evaluated from left to right
\end{enumerate}

Example:

\begin{verbatim}
        SELECT id, ra, dec FROM table1
    UNION
        SELECT id, ra, dec FROM table2
    INTERSECT
        SELECT id, ra, dec FROM table3
\end{verbatim}

is equivalent to:

\begin{verbatim}
        SELECT id, ra, dec FROM table1
    UNION
        (
            SELECT id, ra, dec FROM table2
        INTERSECT
            SELECT id, ra, dec FROM table3
        )
\end{verbatim}

\subsection{Type operations}
\label{sec:type}

An ADQL service implementation MAY include support for the following optional
type conversion functions:

\begin{itemize}
    \item \verb:CAST():
\end{itemize}

\subsubsection{CAST}
\label{sec:type.cast}
{\footnotesize Language feature :}\\
{\footnotesize \verb|type: ivo://ivoa.net/std/tapregext#features-adql-type|}\\
{\footnotesize \verb|name: CAST|}\\

The \verb:CAST(): function returns the value of the first argument converted
into the datatype specified by the second argument.

\paragraph{Syntax} \verb:<cast_specification>:
\begin{verbatim}
CAST <left_paren>
         <value_expression> AS <cast_target>
     <right_paren>
\end{verbatim}

\paragraph{Target types}

This function does not replicate the full functionality and range of types
supported by common RDBMS implementations of \verb:CAST():. Here is the minimum
range of types that MUST be supported if \verb:CAST(): is implemented:

\begin{itemize}
    \item Exact numeric:
    \begin{itemize}
        \item \verb:INTEGER:
        \item \verb:SMALLINT:
        \item \verb:BIGINT:
    \end{itemize}
    \item Approximate numeric:
    \begin{itemize}
        \item \verb:REAL:
        \item \verb:DOUBLE PRECISION:
    \end{itemize}
    \item Character:
    \begin{itemize}
        \item \verb:CHAR: or \verb:CHAR(n): (where n is the fixed string length)
        \item \verb:VARCHAR: or \verb:VARCHAR(n): (where n is the maximum string length)
    \end{itemize}
    \item Date, Time:
    \begin{itemize}
        \item \verb:TIMESTAMP:
    \end{itemize}
\end{itemize}

Examples:

\begin{verbatim}
    CAST(3 AS REAL)
    CAST('3.14159265358979323846' AS DOUBLE PRECISION)
\end{verbatim}

\paragraph{Input types}

The range of types allowed for the value to cast entirely depends on the target
type. Although cast operations may vary from one implementation to another, ADQL
SHOULD support the ones listed in Table \ref{table:cast.inputtypes}.

\begin{table}[!h]
    \center{
        \resizebox{\linewidth}{!}{
            \begin{tabular}{| c | c | c | c | c | c |}
                \hline
                \multirow{3}{*}{\diaghead{\theadfont Output TyInput Ty}%
                {\textbf{Input}}{\textbf{Output}}}
                                     & \textbf{Exact}      & \textbf{Approximate} & \textbf{Variable}  & \textbf{Fixed}      &                    \\
                                     & \textbf{numeric}    & \textbf{numeric}     & \textbf{length}    & \textbf{length}     & \textbf{Timestamp} \\
                                     &                     &                      & \textbf{character} & \textbf{character}  &                    \\
                \hline
                \textbf{Exact}       & \multirow{2}{*}{X}  & \multirow{2}{*}{X}   & \multirow{2}{*}{X} & \multirow{2}{*}{X*} &                    \\
                \textbf{numeric}     & & & & & \\
                \hline
                \textbf{Approximate} & \multirow{2}{*}{X*} & \multirow{2}{*}{X}   & \multirow{2}{*}{X} & \multirow{2}{*}{X*} &                    \\
                \textbf{numeric}     & & & & & \\
                \hline
                \textbf{Character}   &         X           &          X           &          X         &          X*         &         X          \\
                \hline
                \textbf{Timestamp}   &                     &                      &          X         &          X*         &         X          \\
                \hline
            \end{tabular}
        }
    \textit{\footnotesize{X: supported ; X*: supported but possible implementation differences}}
    \caption{CAST allowed types}
    \label{table:cast.inputtypes}
    }
\end{table}

\paragraph{Cast into a smaller datatype}

Converting a value to a datatype that is too small to represent it SHOULD be
treated as an error. Details of the mechanism for reporting the error condition
are implementation dependent.

This rule especially applies when casting a value into a character string too
small to contain its entire serialization. The output string may be truncated,
adjusted to the needed length, or an error may be thrown.

\paragraph{Fixed-length character}

The creation of a fixed-length character string is implementation dependent.
In function of the implementation, \verb:CHAR: may be equivalent to
\verb:CHAR(1): or to a \verb:CHAR: just big enough to contain the entire string
to create.

\paragraph{Approximate numeric}

The rounding mechanism used when converting from approximate numerics
(\verb:REAL: or \verb:DOUBLE PRECISION:) to precise numerics (\verb:SMALLINT:,
\verb:INTEGER: or \verb:BIGINT:) is implementation dependent.

\paragraph{Timestamp}

Only a character string can be casted into a timestamp. This string MUST follow
the syntax defined in the \DALISpec{}:
\begin{verbatim}
    YYYY-MM-DD[’T’hh:mm:ss[.SSS][’Z’]]
\end{verbatim}

Example:

\begin{verbatim}
    CAST('2021-01-14T11:25:00' AS TIMESTAMP)
\end{verbatim}

Note that other serializations or any other kind of value MAY also be supported.

\paragraph{Geometry}

\verb:CAST(): MAY also produce geometries. If an implementation wants to support
this particular cast operation, it MUST accept a character string following the
DALI serialization matching the precise geometry type to produce.

Then, the supported geometry types SHOULD be:

\begin{itemize}
    \item \verb:POINT:
    \item \verb:CIRCLE:
    \item \verb:POLYGON:
\end{itemize}

Examples:

\begin{verbatim}
    CAST('12.3 45.6' AS POINT)
    CAST('12.3 45.6 1.0' AS CIRCLE)
    CAST('1.0 0.1 2.0 0.2 3.0 0.3' AS POLYGON)
\end{verbatim}

Note that other serializations (e.g. STC-S) or any other kind of value MAY also
be supported.

\subsection{Conditional Functions}
\label{sec:condfunc}

An ADQL service implementation MAY include support for the following optional
conditional functions:

\begin{itemize}
    \item \verb:COALESCE():
\end{itemize}

\subsubsection{COALESCE}
{\footnotesize Language feature :}\\
{\footnotesize \verb|type: ivo://ivoa.net/std/tapregext#features-adql-conditional|}\\
{\footnotesize \verb|name: COALESCE|}\\

The COALESCE function returns the first of its arguments that is not
NULL. NULL is returned only if all arguments are NULL.

All arguments must be of the same datatype. An error should be returned
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,

\begin{verbatim}
    COALESCE(access_url, '')
\end{verbatim}

\noindent will return an empty string when \verb|access_url| is NULL.


\subsection{Unit operations}
\label{sec:unit}

An ADQL service implementation MAY include support for the following optional
unit conversion functions:

\begin{itemize}
    \item \verb:IN_UNIT():
\end{itemize}

\subsubsection{IN\_UNIT}
\label{sec:unit.in_unit}
{\footnotesize Language feature :}\\
{\footnotesize \verb|type: ivo://ivoa.net/std/tapregext#features-adql-unit|}\\
{\footnotesize \verb|name: IN_UNIT|}\\

The \verb:IN_UNIT(): function returns the value of the first argument
transformed into the unit defined by the second argument.

The first argument MUST be a numeric value expression. If this argument is a
column name, the VOUnits for this column ought to be found in the metadata
attached to this column (e.g. \verb|TAP_SCHEMA.columns.unit| in a TAP service).

The second argument MUST be a string literal containing a valid unit
description using the formatting defined in the \VOUnitSpec{}.

Example:

\begin{verbatim}
    -- ra: column expressed in 'deg'
    IN_UNIT(ra, 'rad')     -- OK
    IN_UNIT(ra, 'arcmin')  -- OK
\end{verbatim}

It has to be noted that a unitless value, as defined by the \VOUnitSpec{}, can not
be converted. Similarly a non-unitless value can not be converted into a
unitless one.

The system MUST report an error in response to the following conditions:
\begin{itemize}
    \item if the second argument is not a valid unit description
    \item if the system is not able to convert the value into the requested unit
\end{itemize}

Examples:

\begin{verbatim}
    -- ra       : column expressed in 'deg'
    -- phot_cnt : column expressing a unitless quantity

    IN_UNIT(ra, '')          -- ERROR: Conversion into a 'unitless'
                             --        value impossible

    IN_UNIT(phot_cnt, 'deg') -- ERROR: Impossible to convert a
                             --        unitless value

    IN_UNIT(ra, 'foo')       -- ERROR: Incorrect unit definition

    IN_UNIT(ra, 'kg')        -- ERROR: Impossible conversion
                             --        (deg -> kg)
\end{verbatim}

Details of the mechanism for reporting the error condition are implementation
dependent.

Currently, ADQL does not provide any way to specify the unit of a numeric
literal (e.g. a number such as \verb:42: or \verb:3.14:) or of the result of an
operation or function. Consequently, regarding the unitless aspect of such
a numeric expression, \verb:IN_UNIT(): MUST report an error.

Examples:

\begin{verbatim}
    IN_UNIT(42, 'kg')        -- ERROR: no unit can be specified for
                             --        42, so, it is unitless
                             --        => its conversion is
                             --           impossible

    IN_UNIT(40+2, 'deg')     -- ERROR: idem

    IN_UNIT(sqrt(42), 'deg') -- ERROR: idem
\end{verbatim}

An ADQL service implementation could use a unit inference mechanism. In such
case, the units of numeric expressions can be inferred (or at least
guessed). With the
help of a such mechanism, \verb:IN_UNIT(): MAY convert more complex
expressions.

Examples, with an \emph{advanced} unit inference mechanism:

\begin{verbatim}
    -- ra       : column expressed in 'deg'
    -- ra_error : column expressed in 'deg'
    -- pm_ra    : column expressing in 'deg/yr'
    -- pm_dec   : column expressing in 'deg/yr'

    IN_UNIT(ra+ra_error, 'rad')                             -- OK

    IN_UNIT(ra+10, 'rad')                                   -- OK

    IN_UNIT(sqrt(power(pm_ra,2)+power(pm_dec,2)), 'rad/yr') -- OK
\end{verbatim}

Note that the complexity and the behavior of a unit inference mechanism is
implementation dependent. This mechanism is OPTIONAL and is described here
as it could significantly improve the behavior of \verb:IN_UNIT():.

\subsection{Cardinality}
\label{sec:cardinality}

An ADQL service implementation MAY include support for the following optional
clauses to modify the cardinality of query results:

\begin{itemize}
    \item \verb:OFFSET:
\end{itemize}

\subsubsection{OFFSET}
\label{sec:offset}

{\footnotesize Language feature :}\\
{\footnotesize \verb|type: ivo://ivoa.net/std/tapregext#features-adql-offset|}\\
{\footnotesize \verb|name: OFFSET|}\\

An ADQL service implementation MAY include support for the OFFSET clause
which limits the number of rows returned by removing a specified number
of rows from the beginning of the result set.

If a query contains both an ORDER BY clause and an OFFSET clause,
then the ORDER BY is applied before the specified number of
rows are dropped by the OFFSET clause.

If the total number of rows is less than the value
specified by the OFFSET clause, then the result set is empty.

If a query contains both an OFFSET clause and a TOP clause,
then the OFFSET clause is applied first, dropping the specified
number of rows from the beginning of the result set before the
TOP clause is applied to limit the number of rows returned.

\clearpage % section cut
\appendix
\section{BNF grammar}
\label{sec:grammar}

\lstinputlisting[numbers=none,basicstyle=\ttfamily\small]{adql.bnf}

\clearpage % section cut
\section{Language feature support}
\label{sec:features}

In the \TAPRegSpec{} XML schema, each group of features is
described by a \verb:languageFeatures: element, which has a \verb:type:
URI that identifies the group, and contains a \verb:form: element for each
individual feature from the group that the service supports.

For example, the following XML fragment describes a service that supports the
\verb:POINT: and \verb:CIRCLE: functions from the set of geometrical functions,

{\footnotesize Language feature :}\\
{\footnotesize \verb|type: ivo://ivoa.net/std/tapregext#features-adqlgeo|}\\
{\footnotesize \verb|name: POINT, CIRCLE|}\\

\begin{verbatim}
<languageFeatures type="ivo://ivoa.net/std/tapregext#features-adqlgeo">
    <feature>
        <form>POINT</form>
    </feature>
    <feature>
        <form>CIRCLE</form>
    </feature>
</languageFeatures>
\end{verbatim}

\clearpage % section cut
\section{Changes from previous versions}
\label{sec:changes}

\subsection{Between 2.0 and 2.1}
\label{sec:changes-2.1}

\begin{itemize}
    \item \textbf{Applied ADQL-2.0's errata}:
        \begin{itemize}
            \item Erratum 1 - add clarification about the usage of white spaces
                  between ADQL terms
            \item Erratum 2 - fix description of \verb:mod():, \verb:rand():,
                  \verb:round(): and \verb:truncate():
            \item Erratum 3 - the coordinate system argument of geometrical
                  functions must be a string literal
            \item Erratum 4 - accept \verb:NULL: as a valid expression value
        \end{itemize}
    \item \textbf{General}
        \begin{itemize}
            \item \textbf{Added}
                \begin{itemize}
                    \item IVOA architecture diagram \SectionSee{sec:role}
                    \item Recommendation to data providers about case folding
                          (see \SectionRef{sec:adql.escape} and
                          \SectionRef{sec:adql.case})
                    \item Description of accepted datatypes and their mapping
                          with VOTable: numeric types (including
                          \verb:INTERVAL:), character types (including
                          \verb:CLOB:), geometrical types, \verb:TIMESTAMP: and
                          \verb:BLOB: \SectionSee{sec:types}
                    \item Language feature description
                          (see \AppendixRef{sec:features})
                    \item Syntax description for comments inside a query
                          (see \SectionRef{sec:comments})
                    \item Description of how to escape single quotes in a string
                          literal (see \SectionRef{sec:literals})
                \end{itemize}
            \item \textbf{Updated}
                \begin{itemize}
                    \item Description of SQL-92 with links/URLs
                          \SectionSee{sec:introduction}
                    \item BNF grammar syntax fixes
                          (see \AppendixRef{sec:grammar})
                    \item \verb:ORDER BY: accepts qualified column names (i.e.
                          prefixed by a table name eventually prefixed by a
                          schema name)
                          (see \AppendixRef{sec:grammar})
                    \item \verb:ORDER BY: accepts expressions
                    (see \AppendixRef{sec:grammar})
                \end{itemize}
        \end{itemize}
    \item \textbf{Optional features}
        \begin{itemize}
            \item \textbf{Added}
                \begin{itemize}
                    \item Case sensitive functions and operators:
                          \verb:LOWER():, \verb:UPPER(): and \verb:ILIKE:
                          \SectionSee{sec:string.functions}
                    \item Common table expressions (i.e. \verb:WITH: keyword)
                          \SectionSee{sec:common-table}
                    \item Set operators: \verb:UNION:, \verb:INTERSECT: and
                          \verb:EXCEPT: \SectionSee{sec:set.operators}
                    \item Datatype conversion function: \verb:CAST():
                          \SectionSee{sec:type}
                    \item Conditional function: \verb:COALESCE():
                          \SectionSee{sec:condfunc}
                    \item Unit conversion function: \verb:IN_UNIT():
                          \SectionSee{sec:unit}
                    \item \verb:OFFSET:
                          \SectionSee{sec:cardinality}
                \end{itemize}
            \item \textbf{Updated}
                \begin{itemize}
                    \item A User Defined Function (UDF) can return a geometrical
                          value \SectionSee{sec:functions.geom.type}
                    \item Recommendation for data providers to look at the
                          \CatalogueUDF{} before implementing a UDF
                          \SectionSee{sec:user.functions}
                \end{itemize}
        \end{itemize}
    \item \textbf{Geometries}
        \begin{itemize}
            \item \textbf{Deprecated}
                \begin{itemize}
                    \item Coordinate system argument in all geometrical
                          functions ; temporarily made optional
                          \SectionSee{sec:geom.coordsys.param}
                    \item \verb:COORDSYS(): \SectionSee{sec:functions.geom.coordsys}
                    \item \verb:BOX(): \SectionSee{sec:functions.geom.box}
                \end{itemize}
            \item \textbf{Added}
                \begin{itemize}
                    \item Recommendation to use UDFs from the \CatalogueUDF{}
                          for coordinates conversions
                          \SectionSee{sec:geom.coordsys.param}
                \end{itemize}
            \item \textbf{Updated}
                \begin{itemize}
                    \item Clarification about the serialization of geometries in
                          the \verb:SELECT: clause: basically, use the syntax
                          described in DALI \SectionSee{sec:types.geom}
                    \item Clarification about coordinate limits
                          \SectionSee{sec:functions.geom.limits}
                    \item Clarification about geometry types and functions being
                          spherical
                          (see \SectionRef{sec:functions.geom.limits} and
                          \SectionRef{sec:functions.geom.point})
                    \item Recommendation of a preferred sky crossmatch and
                          cone search syntax (use
                          of \verb:DISTANCE(): instead of \verb:CONTAINS():)
                          \SectionSee{sec:functions.geom.crossmatch}
                    \item \verb:REGION(): argument restricted to a string
                          literal and clarification about its syntax
                          \SectionSee{sec:functions.geom.region}
                    \item Description and BNF of \verb:DISTANCE():
                          (see \SectionRef{sec:functions.geom.distance} and
                          \SectionRef{sec:grammar})
                    \item \verb:BOX():, \verb:CIRCLE():, \verb:DISTANCE(): and
                          \verb:POLYGON(): with a coordinate version of their
                          arguments instead of \verb:POINT(): (example:
                          \verb:CIRCLE(0, 0, 1/60.): equivalent to
                          \verb:CIRCLE(POINT(0,0), 1/60.):)
                          (see \SectionRef{sec:functions.geom.box},
                          \SectionRef{sec:functions.geom.circle},
                          \SectionRef{sec:functions.geom.distance},
                          \SectionRef{sec:functions.geom.polygon})
                \end{itemize}
        \end{itemize}
\end{itemize}

\clearpage % section cut
\bibliography{ivoatex/ivoabib,ivoatex/docrepo}

\end{document}