/[volute]/trunk/projects/dal/TAPNotes/TAPNotes-fmt.html
ViewVC logotype

Contents of /trunk/projects/dal/TAPNotes/TAPNotes-fmt.html

Parent Directory Parent Directory | Revision Log Revision Log


Revision 2620 - (show annotations)
Tue May 13 22:59:14 2014 UTC (7 years, 2 months ago) by yrvafhom@gmail.com
File MIME type: application/xhtml+xml
File size: 104123 byte(s)
Added DATETIME and CAST()
1 <?xml version="1.0" encoding="UTF-8"?><!-- $Id:$
2 Note that this file should be xhtml with div to mark sections - see README for more information
3 Paul Harrison -->
4 <!DOCTYPE html
5 PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
6 <html xmlns="http://www.w3.org/1999/xhtml">
7 <head profile="http://www.w3.org/1999/xhtml/vocab">
8 <title>TAP Implementation Notes IVOA Note 13 December 2013</title>
9 <meta http-equiv="content-type" value="text/html;charset=utf-8"/>
10 <meta name="Title" content="TAP Implementation Notes"/>
11 <meta name="author" content="Markus Demleitner, msdemlei@ari.uni-heidelberg.de"/>
12 <meta name="maintainedBy" content="Markus Demleitner, msdemlei@ari.uni-heidelberg.de"/>
13 <link href="http://www.ivoa.net/misc/ivoa_a.css" rel="stylesheet" type="text/css"/>
14 <!-- Add other styling information here (but this element, if present, mustn't be empty)
15 <style type="text/css"></style>
16 -->
17 <link href="./ivoadoc/XMLPrint.css" rel="stylesheet" type="text/css"/>
18 <link href="./ivoadoc/ivoa-extras.css" rel="stylesheet" type="text/css"/>
19 <style type="text/css" xml:space="preserve">
20
21 .tbw {
22 background: yellow;
23 }
24
25 p.tbw:before {
26 content: 'TO BE WRITTEN: ';
27 }
28
29
30 </style>
31 <link rel="stylesheet" type="text/css" href="http://www.ivoa.net/misc/ivoa_note.css"/></head>
32 <body>
33 <div class="head">
34 <div id="titlehead" style="position:relative;height:170px;width: 500px">
35 <div id="logo" style="position:absolute;width:300px;height:169px;left: 50px;top: 0px;">
36 <img src="http://www.ivoa.net/pub/images/IVOA_wb_300.jpg" alt="IVOA logo"/></div>
37 <div id="logo-title" style="position: absolute; width: 200px; height: 115px; left: 320px; top: 5px; font-size: 14pt; color: #005A9C; font-style: italic;">
38 <p style="position: absolute; left: 0px; top: 0px;"><span style="font-weight: bold;">I</span> nternational</p>
39 <p style="position: absolute; left: 15pt; top: 25pt;"><span style="font-weight: bold;">V</span> irtual</p>
40 <p style="position: absolute; left: 15pt; top: 50pt;"><span style="font-weight: bold;">O</span> bservatory</p>
41 <p style="position: absolute; left: 0px; top: 75pt;"><span style="font-weight: bold;">A</span> lliance</p>
42 </div>
43 </div>
44 <h1>TAP Implementation Notes<br clear="none"/>
45 Version <span class="docversion">1.0</span></h1>
46 <h2 class="subtitle">IVOA Note 13 December 2013</h2>
47
48 <dl>
49 <dt>Working Group</dt>
50 <dd><a href="http://www.ivoa.net/twiki/bin/view/IVOA/IvoaGridAndWebServices" shape="rect">http://www.ivoa.net/twiki/bin/view/IVOA/IvoaGridAndWebServices</a></dd>
51 <dt><b>This version:</b></dt>
52 <dd><a class="currentlink" href="http://www.ivoa.net/documents/TAPNotes/20131213">http://www.ivoa.net/documents/TAPNotes/20131213</a></dd>
53 <dt><b>Latest version:</b></dt>
54 <dd> not issued outside DAL WG</dd>
55 <dt><b>Previous version(s):</b></dt>
56 <dd>None</dd>
57 <dt>Authors:</dt><dd>
58 <a href="http://www.ivoa.net/cgi-bin/twiki/bin/view/IVOA/MarkusDemleitner" shape="rect">Markus Demleitner</a><br clear="none"/>
59 <a href="http://www.ivoa.net/cgi-bin/twiki/bin/view/IVOA/PaulHarrison" shape="rect">Paul Harrison</a><br clear="none"/>
60 <a href="http://www.ivoa.net/cgi-bin/twiki/bin/view/IVOA/MarkTaylor" shape="rect">Mark Taylor</a><br clear="none"/>
61 </dd>
62 </dl>
63
64 <h2>Abstract</h2>
65 <p>This IVOA Note discusses several clarifications to the TAP protocol
66 stack, i.e., to the ADQL dialect, the UWS job system, the VOSI metadata
67 interfaces, and TAP itself.
68 It also proposes a number of enhancements that might be incorporated
69 in the next versions of the respective standards. The authors hope
70 that the proposed text changes and additions can mature while in the
71 relatively fluid note state to achieve a rapid and easy standards
72 process later on.</p>
73 <p>Further contributions to this text are most welcome.</p>
74
75 <h2> Status of This Document</h2>
76 <p>This is an IVOA note published within the IVOA DAL working group.
77 The first release of this document was on 2013-12-13.</p>
78 <p id="statusdecl"><em>
79 This is an IVOA Note expressing suggestions from and
80 opinions of the authors. It is intended to share best
81 practices, possible approaches, or other perspectives on
82 interoperability with the Virtual Observatory. It should
83 not be referenced or otherwise interpreted as a standard
84 specification.
85 </em></p>
86 <p> <em>A list of </em><span style="background: transparent"><a href="http://www.ivoa.net/Documents/" shape="rect"><i>current
87 IVOA Recommendations and other technical documents</i></a></span><em> can be found at http://www.ivoa.net/Documents/.</em></p>
88
89 <h2>Acknowledgements</h2>
90
91 <p>Several sections of this document are based on the the <a href="http://wiki.ivoa.net/twiki/bin/view/IVOA/TAPImplementationNotes" shape="rect">TAPImplementationNotes</a>
92 page on the IVOA wiki <cite>[<a href="#IVOAWIKI">IVOAWIKI</a>]</cite>. Several persons
93 contributed to its content, including Mark Taylor, Paul Harrison,
94 Pierre LeSidaner, Tom McGlynn, and Markus Demleitner.</p>
95
96 </div> <!-- header -->
97
98 <h2>Contents</h2>
99 <div><!--The contents of this div are automatically generated from the following processing instruction when processed with ivoarestructure.xsl-->
100 <?toc?><div id="toc" class="toc"><ul><li><a href="#introduction"><span class="secnum">1. </span>Introduction</a></li><li><a href="#adql"><span class="secnum">2. </span>ADQL</a><ul><li><a href="#adql-clar"><span class="secnum">2.1. </span>ADQL: Clarifications, Errata, and Recommendations</a><ul><li><a href="#ac-sep"><span class="secnum">2.1.1. </span>The Separator Nonterminal</a></li><li><a href="#ac-typesystem"><span class="secnum">2.1.2. </span>Type System</a></li><li><a href="#ac-datetime"><span class="secnum">2.1.3. </span>DATETIME</a></li><li><a href="#ac-emptycoosys"><span class="secnum">2.1.4. </span>Empty Coordinate Systems</a></li><li><a href="#ac-geo-opt"><span class="secnum">2.1.5. </span>Explanation of optional features</a></li></ul></li><li><a href="#adql-features"><span class="secnum">2.2. </span>ADQL: Proposed New Features</a><ul><li><a href="#af-simplecrossmatch"><span class="secnum">2.2.1. </span>Simple Crossmatch Function</a></li><li><a href="#af-intersects"><span class="secnum">2.2.2. </span>No Type-based Decay of INTERSECTS</a></li><li><a href="#af-genudf"><span class="secnum">2.2.3. </span>Generalized User Defined Functions</a></li><li><a href="#af-casefolding"><span class="secnum">2.2.4. </span>Case-Insensitive String Comparisons</a></li><li><a href="#af-setops"><span class="secnum">2.2.5. </span>Set Operators</a></li><li><a href="#af-booleans"><span class="secnum">2.2.6. </span>Adding a Boolean Type</a></li><li><a href="#af-unitcast"><span class="secnum">2.2.7. </span>Casting to Unit</a></li><li><a href="#af-ucdcol"><span class="secnum">2.2.8. </span>Column References with UCD Patterns</a></li><li><a href="#af-modulo"><span class="secnum">2.2.9. </span>Modulo operator</a></li><li><a href="#af-bitwise"><span class="secnum">2.2.10. </span>Bitwise operators</a></li><li><a href="#af-cast"><span class="secnum">2.2.11. </span>CAST operator</a></li></ul></li></ul></li><li><a href="#uws"><span class="secnum">3. </span>UWS</a><ul><li><a href="#uws-clar"><span class="secnum">3.1. </span>UWS: Clarifications, Errata, and Recommendations</a><ul><li><a href="#uc-initpost"><span class="secnum">3.1.1. </span>Updating Parameters</a></li><li><a href="#uc-failedjobcreation"><span class="secnum">3.1.2. </span>Behaviour for Failed Job Creation</a></li></ul></li><li><a href="#uws-features"><span class="secnum">3.2. </span>UWS: Proposed New Features</a><ul><li><a href="#uf-quoteformat"><span class="secnum">3.2.1. </span>Format of Quote</a></li></ul></li></ul></li><li><a href="#tap"><span class="secnum">4. </span>TAP</a><ul><li><a href="#tap-clar"><span class="secnum">4.1. </span>TAP: Clarifications, Errata, and Recommendations</a><ul><li><a href="#tc-uploadsyntax"><span class="secnum">4.1.1. </span>Names of Uploaded Tables</a></li><li><a href="#tc-multiupload"><span class="secnum">4.1.2. </span>Multiple UPLOAD Posts</a></li><li><a href="#tc-dbregion"><span class="secnum">4.1.3. </span>Database Column Types</a></li><li><a href="#tc-size"><span class="secnum">4.1.4. </span>The size Column in TAP_SCHEMA</a></li><li><a href="#tc-errordoc"><span class="secnum">4.1.5. </span>Use of VOTable</a></li></ul></li><li><a href="#tap-features"><span class="secnum">4.2. </span>TAP: New Features</a><ul><li><a href="#tf-examples"><span class="secnum">4.2.1. </span>An examples Endpoint</a><ul><li><a href="#tf-ex-endpoint"><span class="secnum">4.2.1.1. </span>The Endpoint</a></li><li><a href="#tf-ex-content"><span class="secnum">4.2.1.2. </span>Document Content</a></li><li><a href="#tf-ex-use"><span class="secnum">4.2.1.3. </span>Intended Use</a></li><li><a href="#tf-ex-validation"><span class="secnum">4.2.1.4. </span>Validation</a></li></ul></li><li><a href="#tf-plan"><span class="secnum">4.2.2. </span>A plan Endpoint</a></li><li><a href="#tf-scaletable"><span class="secnum">4.2.3. </span>Scaleable tables Endpoint</a></li><li><a href="#tf-noasync"><span class="secnum">4.2.4. </span>Making the async Endpoint Optional</a></li><li><a href="#tf-tapschema-opt"><span class="secnum">4.2.5. </span>Making TAP_SCHEMA optional</a><ul><li><a href="#tf-tapschema-examples"><span class="secnum">4.2.5.1. </span>Examples</a><ul><li><a href="#tf-tapschema-virtual"><span class="secnum">4.2.5.1.1. </span>Virtual data</a></li><li><a href="#tf-tapschema-private"><span class="secnum">4.2.5.1.2. </span>Private data</a></li><li><a href="#tf-tapschema-nosql"><span class="secnum">4.2.5.1.3. </span>Alternative systems</a></li></ul></li></ul></li><li><a href="#tapschema-naming"><span class="secnum">4.2.6. </span>Letting TAP_SCHEMA name be custom</a></li><li><a href="#tf-meta-dyn"><span class="secnum">4.2.7. </span>Dynamic metadata</a><ul><li><a href="#tf-meta-ttl"><span class="secnum">4.2.7.1. </span>Time to live</a></li></ul></li></ul></li></ul></li><li><a href="#appA"><span class="secnum">A. </span>An Example for an /examples Document</a></li><li><a href="#appB"><span class="secnum">B. </span>An XSLT Stylesheet for Validating an examples Document</a></li><li><a href="#references"><span class="secnum"/>References</a></li></ul></div>
101 <!--end of autogenerated content--></div>
102
103 <div class="body">
104 <div class="section"><h2><a id="introduction" shape="rect"><span class="secnum">1. </span>Introduction</a></h2>
105 <p>The protocol stack for exchanging database queries and their results
106 within the Virtual Observatory context is, by 2013, implemented in
107 several software packages, both on the server and on the client
108 side.</p>
109
110 <p>Several implementors found that the respective standards leave some
111 questions open. The first purpose of this document is to collect these
112 questions and give answers reflecting a broad consensus on the part of
113 the implementors. The points raised in these clarifications, errata and
114 recommendations should be addressed in future revisions of the standard
115 texts. It is the intent of this document to serve as an evolving
116 reference for implementors that should eventually reflect the updates
117 to the actual standards.</p>
118
119 <p>With the experience gathered from roll-out and use of the protocols,
120 several additions to (or deletions from) the standards appeared
121 beneficial. This document collects such proposals for changes to the
122 content of the standards. Some of these changes have been written such
123 that neither servers nor clients break and thus are candidates for minor
124 updates to the standards, whereas the adoption of others might require
125 new major releases. Again, the authors plan to evolve this document to
126 have the note reflect the eventual plans for updates to the
127 standards.</p>
128
129 </div> <!-- section introduction -->
130
131 <div class="section"><h2><a id="adql" shape="rect"><span class="secnum">2. </span>ADQL</a></h2>
132 <div class="section"><h3><a id="adql-clar" shape="rect"><span class="secnum">2.1. </span>ADQL: Clarifications, Errata, and Recommendations</a></h3>
133
134 <div class="section"><h4><a id="ac-sep" shape="rect"><span class="secnum">2.1.1. </span>The Separator Nonterminal</a></h4>
135 <p>The grammar given in appendix A of <cite>[<a href="#std:ADQL">std:ADQL</a>]</cite> gives a
136 nonterminal <em>separator</em>, expanding to either a comment or
137 whitespace. This nonterminal, however, is only referenced within the
138 rule for <em>character_string_literal</em>. It is uncontentious that the
139 intent is to allow comments and whitespace wherever SQL1992 allows them.
140 With the nonterminal in the grammar, however, the ADQL standard says
141 differently, and there should be a clarification.</p>
142
143 <p>One option for such a clarification is to amend section 2.1 of
144 <cite>[<a href="#std:ADQL">std:ADQL</a>]</cite> with a subsection 2.1.4, "Tokens and literals",
145 containing text like the following (taken essentially from
146 <cite>[<a href="#std:SQL1992">std:SQL1992</a>]</cite>.</p>
147
148 <blockquote>
149 <p>
150 Any <em>token</em> may be followed by a <em>separator</em>. A
151 <em>nondelimiter token</em> shall be followed by a <em>delimiter
152 token</em> or a <em>separator</em>.
153 </p>
154 </blockquote>
155
156 <p>Since the full rules for the separator are somewhat more complex
157 in <cite>[<a href="#std:ADQL">std:ADQL</a>]</cite>, an attractive alternative could be
158 to omit the <em>separator</em> nonterminal from the grammar and to just
159 note:</p>
160
161 <blockquote>
162 <p>Whitespace and comments can occur wherever they can occur in
163 <cite>[<a href="#std:SQL1992">std:SQL1992</a>]</cite>.</p>
164 </blockquote>
165
166 </div> <!-- subsubseciton ac-sep -->
167
168 <div class="section"><h4><a id="ac-typesystem" shape="rect"><span class="secnum">2.1.2. </span>Type System</a></h4>
169 <p>The ADQL specification does not explicitly talk about types. Some
170 intentions regarding types can be taken from the grammar (e.g., the lack
171 of a boolean type), but it is clear that for a predictable behaviour
172 across individual ADQL implementations, ADQL should talk about
173 types. The TAP specification has already covered most of the ground
174 here, with a table on PDF page 19 in version 1.0. The following
175 proposal mainly builds on this.</p>
176
177 <p>To introduce a notion of types into section 2 of the ADQL
178 recommendation, it should be amended with a subsection 2.6, "ADQL Type
179 System", as follows:</p>
180
181 <blockquote>
182 <p>ADQL defines no data definition language (DDL). It is assumed that
183 table definition and data ingestion are performed in the backend
184 database's native language and type system.</p>
185
186 <p>However, column metadata needs to give column types in order to allow
187 the construction of queries that are both syntactically and semantically
188 correct. Examples of such metadata includes VODataService's
189 <code>vs:TAPType</code> <cite>[<a href="#std:VODS11">std:VODS11</a>]</cite> or TAP's TAP_SCHEMA.
190 Services SHOULD, if at all possible, try express their column
191 metadata in these terms even if the underlying database employs
192 different types. Services SHOULD also use the following mapping when
193 interfacing to user data, either by serializing result sets into
194 VOTables or by ingesting user-provided VOTables into ADQL-visible
195 tables. Where non-ADQL types are employed
196 in the backend, implementors SHOULD make sure that all operations that are
197 possible with the recommended ADQL type are also possible with the type
198 used in the backend engine. For instance, the ADQL string concatenation
199 operator || should be applicable to all columns resulting from VOTable
200 char-typed columns.</p>
201
202 <table border="1">
203 <tr><th colspan="3" rowspan="1">VOTable</th><th rowspan="1" colspan="1">ADQL</th></tr>
204 <tr><th rowspan="1" colspan="1">datatype</th><th rowspan="1" colspan="1">arraysize</th><th rowspan="1" colspan="1">xtype</th>
205 <th rowspan="1" colspan="1">type</th></tr>
206 <tr><td rowspan="1" colspan="1">boolean</td><td rowspan="1" colspan="1">1</td><td rowspan="1" colspan="1"/><td rowspan="1" colspan="1">implemenation defined</td></tr>
207 <tr><td rowspan="1" colspan="1">short</td><td rowspan="1" colspan="1">1</td><td rowspan="1" colspan="1"/><td rowspan="1" colspan="1">SMALLINT</td></tr>
208 <tr><td rowspan="1" colspan="1">int</td><td rowspan="1" colspan="1">1</td><td rowspan="1" colspan="1"/><td rowspan="1" colspan="1">INTEGER</td></tr>
209 <tr><td rowspan="1" colspan="1">long</td><td rowspan="1" colspan="1">1</td><td rowspan="1" colspan="1"/><td rowspan="1" colspan="1">BIGINT</td></tr>
210 <tr><td rowspan="1" colspan="1">float</td><td rowspan="1" colspan="1">1</td><td rowspan="1" colspan="1"/><td rowspan="1" colspan="1">REAL</td></tr>
211 <tr><td rowspan="1" colspan="1">double</td><td rowspan="1" colspan="1">1</td><td rowspan="1" colspan="1"/><td rowspan="1" colspan="1">DOUBLE</td></tr>
212 <tr><td rowspan="1" colspan="1">(numeric)</td><td rowspan="1" colspan="1">&gt; 1</td><td rowspan="1" colspan="1"/><td rowspan="1" colspan="1">
213 implementation defined</td></tr>
214 <tr><td rowspan="1" colspan="1">char</td><td rowspan="1" colspan="1">1</td><td rowspan="1" colspan="1"/><td rowspan="1" colspan="1">CHAR(1)</td></tr>
215 <tr><td rowspan="1" colspan="1">char</td><td rowspan="1" colspan="1">n*</td><td rowspan="1" colspan="1"/><td rowspan="1" colspan="1">VARCHAR(n)</td></tr>
216 <tr><td rowspan="1" colspan="1">char</td><td rowspan="1" colspan="1">n</td><td rowspan="1" colspan="1"/><td rowspan="1" colspan="1">CHAR(n)</td></tr>
217 <tr><td rowspan="1" colspan="1">unsignedByte</td><td rowspan="1" colspan="1">n*</td><td rowspan="1" colspan="1"/><td rowspan="1" colspan="1">VARBINARY(n)</td></tr>
218 <tr><td rowspan="1" colspan="1">unsignedByte</td><td rowspan="1" colspan="1">n</td><td rowspan="1" colspan="1"/><td rowspan="1" colspan="1">BINARY(n)</td></tr>
219
220 <tr><td rowspan="1" colspan="1">unsignedByte</td><td rowspan="1" colspan="1">n, *,
221 n*</td><td rowspan="1" colspan="1">adql:BLOB</td><td rowspan="1" colspan="1">BLOB</td></tr>
222 <tr><td rowspan="1" colspan="1">char</td><td rowspan="1" colspan="1">n, *, n*</td><td rowspan="1" colspan="1">adql:CLOB</td><td rowspan="1" colspan="1">CLOB</td></tr>
223 <tr><td rowspan="1" colspan="1">char</td><td rowspan="1" colspan="1">n, *,
224 n*</td><td rowspan="1" colspan="1">adql:TIMESTAMP</td><td rowspan="1" colspan="1">TIMESTAMP</td></tr>
225 <tr><td rowspan="1" colspan="1">char</td><td rowspan="1" colspan="1">n, *, n*</td><td rowspan="1" colspan="1">adql:POINT</td><td rowspan="1" colspan="1">POINT</td></tr>
226 <tr><td rowspan="1" colspan="1">char</td><td rowspan="1" colspan="1">n, *,
227 n*</td><td rowspan="1" colspan="1">adql:REGION</td><td rowspan="1" colspan="1">REGION</td></tr>
228 </table>
229
230 <p>"Implementation defined" in the above table means that an
231 implementation is free to reject attempts to (de-) serialize values in
232 these types. They are to be considered unsupported by ADQL, and the
233 language provides no means to manipulate "native" representations of
234 them.</p>
235
236 <p>References to REGION-typed columns must be valid wherever the
237 ADQL <em>region</em> nonterminal is allowed. References to POINT-typed
238 columns must be valid wherever the ADQL <em>point</em> nonterminal is
239 allowed.</p>
240
241 </blockquote>
242
243 </div> <!-- subsubsection ac-typesystem -->
244
245 <div class="section"><h4><a id="ac-datetime" shape="rect"><span class="secnum">2.1.3. </span>DATETIME</a></h4>
246 <p>
247 The term <code>TIMESTAMP</code> has additional meanings above and beyond the simple meaning of a date and time,
248 some of which impose additional constraints on the range of values that can be represented.
249 <ul>
250 <li>
251 <a href="http://en.wikipedia.org/wiki/Unix_time" shape="rect">Unix TIMESTAMP</a>, number of seconds since 1st January 1970.
252 </li>
253 <li>
254 <a href="http://dev.mysql.com/doc/refman/5.0/en/datetime.html" shape="rect">MySQL TIMESTAMP</a>, 1st January 1970 to 19th January 2038,
255 </li>
256 <li>
257 <a href="http://technet.microsoft.com/en-us/library/aa260631%28v=sql.80%29.aspx" shape="rect">SQLServer TIMESTAMP</a>, server generated binary number, NOT a date time.
258 </li>
259 </ul>
260 </p>
261 <p>
262 With this in mind we would like to propose replacing the terms
263 <code>TIMESTAMP</code> and <code>ADQL:TIMESTAMP</code>
264 in the preceeding section with <code>DATETIME</code>
265 and <code>ADQL:DATETIME</code>.
266 </p>
267 </div> <!-- subsubsection ac-datetime -->
268
269 <div class="section"><h4><a id="ac-emptycoosys" shape="rect"><span class="secnum">2.1.4. </span>Empty Coordinate Systems</a></h4>
270
271 <p>The legal values and the semantics of the first arguments to the
272 geometry constructors (POINT, BOX, CIRCLE, POLYGON) have been left
273 largely open by the ADQL standard. The TAP standard clarified those
274 somewhat to the effect that the prescriptions became implementable. On
275 the other hand, the only thing clients can reasonably expect according
276 to TAP (on a recommendation base) from a server is one of four reference
277 frames. Compared to the implementation effort and the potential for
278 user confusion, the additional expressiveness gained by keeping the
279 first argument seems minute. Even allowing more expressive system
280 strings will not help the feature much, since non-trivial
281 transformations (e.g., between reference positions) will need more data
282 than merely the celestial coordinates available to the geometry
283 constructors.</p>
284
285 <p>We therefore propose to deprecate the first argument in a point
286 release of ADQL. In the next major release, the first argument as
287 defined in ADQL2 should be declared as ignored. The standard should
288 require constructors both with and without the current first argument,
289 though, in order to ensure backward compatiblity for ADQL2 queries.</p>
290
291 <p>To implement the first step, we propose replacing the second
292 paragraph on PDF page 10 of <cite>[<a href="#std:ADQL">std:ADQL</a>]</cite> (starting with "For all
293 these functions...") with:</p>
294
295 <blockquote>
296 <p>For historical reasons, the geometry constructors (BOX, CIRCLE, POINT,
297 POLYGON) require a string-valued first argument. It was intended to
298 carry information on a reference system or other coordinate system
299 metadata. In this version, we recommend ignoring this first argument,
300 and clients are advised to pass an empty string here. Future versions
301 of this specification will make this first, string-valued parameter
302 optional for the listed functions.</p>
303 </blockquote>
304
305 <p>In consequence, the COORDSYS function would be taken out of the
306 enumeration on PDF page 9, and its description on PDF page 11 would be
307 removed, too. All examples would use an empty string rather than "ICRS
308 GEOCENTER" -- which is not contained in the TAP clarification anyway --
309 as in the current text.</p>
310
311 <p>A library of standard generalized user defined functions (see section
312 <span class="xref"><a href="#af-genudf">2.2.3</a></span>) could provide for simple conversion
313 between reference frames as well as more demanding transformations,
314 e.g., between epochs or reference positions. This, however, depends on
315 allowing geometry-valued user defined functions and is outside of the
316 scope of a clarification. See also section <span class="xref"><a href="#af-genudf">2.2.3</a></span>.</p>
317
318 </div> <!-- subsubsection adql-emptycoosys -->
319
320 <div class="section"><h4><a id="ac-geo-opt" shape="rect"><span class="secnum">2.1.5. </span>Explanation of optional features</a></h4>
321 <p>
322 We would like to propose adding a section of text to both the
323 <cite>[<a href="#std:TAP">std:TAP</a>]</cite> and <cite>[<a href="#std:ADQL">std:ADQL</a>]</cite> specifications that
324 clarifies the optional/required status of the geometric functions, and
325 explains how <code>tr:languageFeatures</code> elements from the
326 <cite>[<a href="#std:TAPREGEXT">std:TAPREGEXT</a>]</cite> schema extension can be used to describe
327 which of the geometric functions are supported by a particular TAP
328 service.
329 </p>
330 <p>
331 In the current release documents
332 <ul>
333 <li>Section 1.2.1 of <cite>[<a href="#std:TAP-20100327">std:TAP-20100327</a>]</cite> states that
334 <em>"Support for ADQL queries is mandatory"</em>.
335 </li>
336 <li>Section 2.4 of <cite>[<a href="#std:ADQL-20081030">std:ADQL-20081030</a>]</cite>
337 describes the geometric functions, and section 2.5 describes support for user defined functions.
338 </li>
339 </ul>
340 However, the current <cite>[<a href="#std:TAP-20100327">std:TAP-20100327</a>]</cite> and
341 <cite>[<a href="#std:ADQL-20081030">std:ADQL-20081030</a>]</cite> specifications do not describe how
342 <code>tr:languageFeatures</code> elements from the
343 <cite>[<a href="#std:TAPREGEXT-20120827">std:TAPREGEXT-20120827</a>]</cite> schema extension may be used to
344 describe which of the geometric functions are supported by a service.
345 </p>
346 <p>
347 The description of the <code>features-adqlgeo</code> feature in the
348 <cite>[<a href="#std:TAPREGEXT-20120827">std:TAPREGEXT-20120827</a>]</cite> schema extension implies that some
349 of the geometric functions may be optional.
350 However, the current text refers the user back to the <cite>[<a href="#std:TAP-20100327">std:TAP-20100327</a>]</cite>
351 specification for details of which combinations are permitted.
352 <blockquote>
353 "support for these functions is in general optional for ADQL implementations,
354 though TAP imposes some constraints on what combinations of support are permitted"
355 </blockquote>
356 </p>
357 <p>
358 The proposed changes would not alter the technical details of any of
359 the specifications. The aim is just to add some additional explanations,
360 references and examples.
361 </p>
362 </div> <!-- subsubsection ac-geo-opt -->
363
364 </div> <!-- subsection adql-clar -->
365 <div class="section"><h3><a id="adql-features" shape="rect"><span class="secnum">2.2. </span>ADQL: Proposed New Features</a></h3>
366
367 <div class="section"><h4><a id="af-simplecrossmatch" shape="rect"><span class="secnum">2.2.1. </span>Simple Crossmatch Function</a></h4>
368
369 <p>Since a simple positional crossmatch is such a common operation, we
370 should define a function <code>CROSSMATCH(ra1, dec1, ra2, dec2, radius) -&gt;
371 INTEGER</code> returning 1 if
372 (ra1, dec1) and (ra2, dec2) are within radius degrees of each other.
373 This allows more compact expressions than the conventional
374 CONTAINS(POINT, CIRCLE) construct, and ADQL to SQL translators can more
375 easily exploit special constructs for fast crossmatching that may be
376 built into the backend databases.</p>
377 </div> <!-- subsubsection af-simplecrossmatch -->
378
379 <div class="section"><h4><a id="af-intersects" shape="rect"><span class="secnum">2.2.2. </span>No Type-based Decay of INTERSECTS</a></h4>
380
381 <p>Section 2.4.11 of
382 <cite>[<a href="#std:ADQL">std:ADQL</a>]</cite> stipulates that a call to INTERSECTS should decay
383 to a CONTAINS when one argument is a POINT. This rule is a major
384 implementation liability for simple translators, since it is the only
385 place in the ADQL specification that actually requires a type calculus.
386 For a feature that does not actually add functionality, this seems a
387 high price to pay.</p>
388
389 <p>We therefore recommend to strike the text from "Note that if one of
390 the arguments" through "equivalent to INTERSECTS(b,a)" and add at the
391 end for 2.4.11:</p>
392
393 <blockquote>
394 <p>The arguments to INTERSECTS SHOULD be geometric expressions
395 evaluating to either BOX, CIRCLE, POLYGON, or REGION. Previous versions
396 of this specification allow POINTs as well and require servers to
397 interpret the expression as a CONTAINS with the POINT moved into the
398 first position. Servers SHOULD still implement that behaviour, but
399 clients SHOULD NOT expect it. It will be dropped in the next major
400 version of this specification.</p>
401 </blockquote>
402 </div> <!-- subsubsection af-intersects -->
403
404 <div class="section"><h4><a id="af-genudf" shape="rect"><span class="secnum">2.2.3. </span>Generalized User Defined Functions</a></h4>
405
406 <p>Currently, user defined functions may only return numbers or strings
407 (in terms of the grammar, only <em>numeric_value_function</em> and
408 <em>string_value_function</em> can expand to
409 <em>user_defined_function</em>). Many interesting functions (e.g.,
410 coordinate transforms, applying proper motions) are extremely
411 inconvenient to define with such a restriction. Therefore, we propose
412 to add <code>| &lt;user_defined_function&gt;</code> to the right hand
413 side of the <em>geometry_value_function</em> rule.</p>
414
415 <p>With this, we could define some standard functions for manipulating
416 geometries; these should be defined in the standard, but they could
417 remain optional. Clients can determine their availability using
418 <cite>[<a href="#std:TAPREGEXT">std:TAPREGEXT</a>]</cite>.</p>
419
420 <p>A future version of this note will propose a library of such
421 functions, including proper motion, precession, and system
422 transformation.</p>
423
424 </div> <!-- subsubsection af-genudf -->
425
426 <div class="section"><h4><a id="af-casefolding" shape="rect"><span class="secnum">2.2.4. </span>Case-Insensitive String Comparisons</a></h4>
427
428 <p>ADQL currently has no facility reliably allowing case-insensitive
429 string comparisons. This is particularly regrettable since UCDs and at least
430 the majority of the defined utypes are to be compared
431 case-insensitively.</p>
432
433 <p>Thus, we propose the addition of a string function <code>LOWER</code>
434 and the case-insensitive variant of <code>LIKE</code>,
435 <code>ILIKE</code>. Since case folding is a nontrivial operation in a
436 multi-encoding world, ADQL would only require standard behaviour for the
437 ASCII characters (which would suffice for UCDs and utypes) and only
438 recommend following algorithm R2 in section 3.13, "Default Case Algorithms" of
439 <cite>[<a href="#std:UNICODE">std:UNICODE</a>]</cite> outside of ASCII.</p>
440
441 <p>The grammar changes are trivial.</p>
442
443
444 </div> <!-- subsubsection af-casefolding -->
445
446 <div class="section"><h4><a id="af-setops" shape="rect"><span class="secnum">2.2.5. </span>Set Operators</a></h4>
447
448 <p>ADQL 2.0 does not support any of the SQL <code>UNION</code>,
449 <code>EXCEPT</code> and <code>INTERSECT</code> operators. Since
450 at least set union and intersection are basic operations of relational algebra
451 and combining data from several tables is an operation of significant
452 practical use, this is a serious deficit. Also, there is probably no
453 backend SQL system that does not support these operations.</p>
454
455 <p>Thus, to add minimal support of set operations to ADQL, ADQL systems
456 will mainly need to update their grammars. The following rules, adapted
457 from <cite>[<a href="#std:SQL1992">std:SQL1992</a>]</cite>, will suffice (the
458 <em>query_expression</em> rule replaces the one given in the current
459 grammar, all others are new rules):</p>
460
461 <pre xml:space="preserve">
462 &lt;query_expression&gt; ::=
463 &lt;non_join_query_expression&gt;
464 | &lt;joined_table&gt;
465
466 &lt;non_join_query_expression&gt; ::=
467 &lt;non_join_query_term&gt;
468 | &lt;query_expression&gt; UNION [ ALL ] &lt;query_term&gt;
469 | &lt;query_expression&gt; EXCEPT [ ALL ] &lt;query_term&gt;
470
471 &lt;query_term&gt; ::=
472 &lt;non_join_query_term&gt;
473 | &lt;joined_table&gt;
474
475 &lt;non_join_query_term&gt; ::=
476 &lt;non_join_query_primary&gt;
477 | &lt;query term&gt; INTERSECT [ ALL ]
478
479 &lt;query primary&gt; ::=
480 &lt;non_join_query_primary&gt;
481 | &lt;joined_table&gt;
482
483 &lt;non_join_query_primary&gt; ::=
484 &lt;query_specification&gt;
485 | &lt;left_paren&gt; &lt;non_join_query_expression&gt; &lt;right_paren&gt;
486
487 </pre>
488
489 <p>This leaves out the <code>CORRESPONDING</code> specifications of
490 SQL92, and it
491 still does not include <code>VALUES</code> and explicit table
492 specifications (which would enter through
493 <em>non_join_query_primary</em>) in ADQL. None of these seem
494 indispensible, although one could probably make a case for
495 <code>VALUES</code> .</p>
496
497
498 </div> <!-- subsubsection af-union -->
499
500
501 <div class="section"><h4><a id="af-booleans" shape="rect"><span class="secnum">2.2.6. </span>Adding a Boolean Type</a></h4>
502
503 <p>Having a boolean type in ADQL could make some expressions nicer
504 (e.g., it could eliminate the comparison against 1 for the geometry
505 predicate functions). However, adding boolean functions and allowing
506 references to boolean columns complicates catching syntax errors
507 significantly, since expressions like <code>WHERE colref</code> would
508 then parse and only would raise an error when it turns out that
509 colref does not refer to a boolean column. Simple ADQL translators
510 may not be able to verify this.</p>
511
512 <p>We therefore propose to add a boolean type to the ADQL type system
513 (see section <span class="xref"><a href="#ac-typesystem">2.1.2</a></span>) without any
514 grammatical support for it. However, the standard prose should be
515 amended to contain:</p>
516
517 <blockquote>
518 <p>If the backend database contains columns of type boolean, a
519 comparison of those against the literal strings <code>True</code> and
520 <code>False</code> must be true and false when the column is true and
521 false, respectively. The comparison to other literals is undefined by
522 this specification. Clients should note that the strings have to be
523 entered exactly as given here, without changing case, adding whitespace,
524 or any other modification.
525 </p>
526 </blockquote>
527
528 <p>If this change is adopted, the type system table given in section
529 <span class="xref"><a href="#ac-typesystem">2.1.2</a></span> should be updated; luckily, the
530 VODataService specification underlying VOSI already allows BOOLEAN as a
531 TAPType. In the table row for VOTable boolean,
532 "implementation defined" should be replaced with "BOOLEAN".</p>
533
534
535 </div> <!-- subsubsection af-booleans -->
536
537
538 <div class="section"><h4><a id="af-unitcast" shape="rect"><span class="secnum">2.2.7. </span>Casting to Unit</a></h4>
539
540 <p>ADQL translators can typically introspect the tables they operate on,
541 and thus can typically infer the (physical) unit of a column. Manually
542 converting units (as in <code>col_in_deg*3600</code> is error-prone, and
543 expressions like that make it almost impossible to infer the unit of the
544 result.</p>
545
546 <p>This problem is addressed by the introduction of a function
547 <code>IN_UNIT(expr, &lt;character_string_literal&gt;)</code>; the
548 second argument has to be a literal in order to make sure that an ADQL
549 translator has access to its value; this value must be in the format
550 defined by
551 <cite>[<a href="#std:VOUNIT">std:VOUNIT</a>]</cite>. The intended functionality is that the
552 translator replaces the function call with a new expression that
553 is <code>expr</code> given in the unit defined by
554 the second argument if the translator can figure out <code>expr</code>'s
555 unit, and it knows how to convert values in one unit into another.
556 In every other case, the query must be rejected as erroneous.</p>
557
558 </div> <!-- subsubsection af-unitcast -->
559
560 <div class="section"><h4><a id="af-ucdcol" shape="rect"><span class="secnum">2.2.8. </span>Column References with UCD Patterns</a></h4>
561 <p>In the same spirit of a function that really is a macro evaluated by
562 an ADQL translator, we suggest a new function
563 <code>UCDCOL(&lt;character_string_literal&gt;)</code>. The
564 <em>character_string_literal</em> in this case specifies a posix
565 shell pattern (i.e., users write * for a sequence of 0 or more arbitrary
566 chars, ? for exactly one arbitrary char, [] for a character range, and
567 the backslash is the escape character)
568 for a UCD. The translator replaces the entire
569 function call with the first match of a column matching this pattern.
570 If no such column exists, the query must be rejected as erroneous.</p>
571
572 </div> <!-- subsubsection af-ucdcol -->
573
574 <div class="section"><h4><a id="af-modulo" shape="rect"><span class="secnum">2.2.9. </span>Modulo operator</a></h4>
575 <p>
576 ADQL currently supports modulo as the <code>MOD(x,y)</code> function.
577 </p>
578 <p>
579 <pre xml:space="preserve">
580 SELECT x,y,z FROM table WHERE MOD(x,100) = 0
581 </pre>
582 </p>
583 <p>
584 Many of our science users are more familiar using the <code>x % y</code>
585 operator syntax.
586 </p>
587 <p>
588 <pre xml:space="preserve">
589 SELECT x,y,z FROM table WHERE x % 100 = 0
590 </pre>
591 </p>
592 <p>
593 We would therefore like to propose adding the <code>x % y</code> operator
594 syntax to ADQL.
595 </p>
596 <p>
597 Many of the poular RDBMS platforms support both the <code>MOD(x,y)</code>
598 function and the <code>x % y</code> operator syntax.
599 <ul>
600 <li>
601 <a href="http://www.postgresql.org/docs/9.3/static/functions-math.html" shape="rect">PostgreSQL</a>
602 </li>
603 <li>
604 <a href="https://dev.mysql.com/doc/refman/5.7/en/arithmetic-functions.html#operator_mod" shape="rect">MySQL</a>
605 </li>
606 <li>
607 <a href="https://mariadb.com/kb/en/modulo-operator/" shape="rect">MariaDB</a>
608 </li>
609 <li>
610 <a href="https://www.sqlite.org/lang_expr.html" shape="rect">SQLite</a>
611 </li>
612 <li>
613 <a href="http://technet.microsoft.com/en-us/library/ms190279.aspx" shape="rect">SQLServer</a>
614 </li>
615 </ul>
616 </p>
617 <p>
618 However, we are aware that some platforms only support the <code>MOD(x,y)</code>
619 function syntax and not the <code>x % y</code> operator.
620 <ul>
621 <li>
622 <a href="https://db.apache.org/derby/docs/10.10/ref/rrefsqlj19433.html" shape="rect">Derby</a>
623 </li>
624 <li>
625 <a href="http://hsqldb.org/doc/guide/builtinfunctions-chapt.html#bfc_numeric_functions" shape="rect">HyperSQL</a>
626 </li>
627 <li>
628 <a href="http://www.techonthenet.com/oracle/functions/mod.php" shape="rect">Oracle</a>
629 </li>
630 </ul>
631 Adding the <code>x % y</code> operator syntax to ADQL
632 would mean that some platforms would need translate the ADQL <code>x % y</code>
633 operator syntax into the <code>MOD(x,y)</code> function syntax.
634 </p>
635 </div> <!-- subsubsection af-modulo -->
636
637 <div class="section"><h4><a id="af-bitwise" shape="rect"><span class="secnum">2.2.10. </span>Bitwise operators</a></h4>
638 <p>
639 There are a number of fields in astronomy catalogs that contain combinations
640 of bit flags. For example, the
641 <a href="http://osa.roe.ac.uk//#ppErrBits_div" shape="rect">Quality Error Bit Flags</a>
642 in the <a href="http://osa.roe.ac.uk/" shape="rect">OmegaCAM Science Archive</a>
643 encodes 32 bits of quality error information for each source detection
644 in a single integer column.
645 </p>
646 <p>
647 In order to use these as filters in a WHERE clause we need to be able
648 to perform bitwise operations on them.
649 </p>
650 <p>
651 <pre xml:space="preserve">
652 SELECT
653 ksPetroMag,
654 jmksExt
655 FROM
656 videoSource
657 WHERE
658 mergedClass = 1
659 AND
660 ksPetroMag &gt; -9.99995e+8
661 AND
662 jmksExt &gt; -9.99995e+8
663 AND (
664 (jppErrBits | ksppErrBits) &lt; 0x10000
665 OR
666 (jppErrBits | ksppErrBits) &amp; 0x00800000 != 0
667 )
668 </pre>
669 </p>
670 <p>
671 We would therefore like to propose adding support for the four main bitwise
672 operators, AND, OR, XOR and NOT to the ADQL language.
673 </p>
674 <p>
675 <pre xml:space="preserve">
676 BIT_AND "&amp;"
677 BIT_OR "|"
678 BIT_XOR "^"
679 BIT_NOT "~"
680 </pre>
681 </p>
682 <p>
683 We would also like to propose adding support for hexadecimal literals.
684 </p>
685 <p>
686 <pre xml:space="preserve">
687 HEX_PREFIX "0x"
688 HEX_INTEGER &lt;HEX_PREFIX&gt;(&lt;HEX_DIGIT&gt;)+
689 HEX_DIGIT ["0"-"9","a"-"f","A"-"F"]
690 </pre>
691 </p>
692 <p>
693 Many of the popular RDBMS platforms provide the full set of bitwise operators.
694 However, some platforms only provide a limited set of bitwise operators.
695 </p>
696 <p>
697 <table border="1">
698 <tr>
699 <th rowspan="1" colspan="1">Platform</th>
700 <th rowspan="1" colspan="1">BIT_AND</th>
701 <th rowspan="1" colspan="1">BIT_OR</th>
702 <th rowspan="1" colspan="1">BIT_XOR</th>
703 <th rowspan="1" colspan="1">BIT_NOT</th>
704 </tr>
705 <tr>
706 <td rowspan="1" colspan="1">
707 <a href="http://www.postgresql.org/docs/9.3/static/functions-math.html" shape="rect">PostgreSQL</a>
708 </td>
709 <td rowspan="1" colspan="1">YES</td>
710 <td rowspan="1" colspan="1">YES</td>
711 <td rowspan="1" colspan="1">YES</td>
712 <td rowspan="1" colspan="1">YES</td>
713 </tr>
714 <tr>
715 <td rowspan="1" colspan="1">
716 <a href="https://dev.mysql.com/doc/refman/5.7/en/bit-functions.html" shape="rect">MySQL</a>
717 </td>
718 <td rowspan="1" colspan="1">YES</td>
719 <td rowspan="1" colspan="1">YES</td>
720 <td rowspan="1" colspan="1">YES</td>
721 <td rowspan="1" colspan="1">YES</td>
722 </tr>
723 <tr>
724 <td rowspan="1" colspan="1">
725 <a href="https://mariadb.com/kb/en/bit-functions-and-operators/" shape="rect">MariaDB</a>
726 </td>
727 <td rowspan="1" colspan="1">YES</td>
728 <td rowspan="1" colspan="1">YES</td>
729 <td rowspan="1" colspan="1">YES</td>
730 <td rowspan="1" colspan="1">YES</td>
731 </tr>
732 <tr>
733 <td rowspan="1" colspan="1">
734 <a href="http://hsqldb.org/doc/guide/builtinfunctions-chapt.html#bfc_numeric_functions" shape="rect">HyperSQL</a>
735 </td>
736 <td rowspan="1" colspan="1">YES</td>
737 <td rowspan="1" colspan="1">YES</td>
738 <td rowspan="1" colspan="1">YES</td>
739 <td rowspan="1" colspan="1">YES</td>
740 </tr>
741 <tr>
742 <td rowspan="1" colspan="1">
743 <a href="http://technet.microsoft.com/en-us/library/ms176122.aspx" shape="rect">SQLServer</a>
744 </td>
745 <td rowspan="1" colspan="1">YES</td>
746 <td rowspan="1" colspan="1">YES</td>
747 <td rowspan="1" colspan="1">YES</td>
748 <td rowspan="1" colspan="1">YES</td>
749 </tr>
750 <tr>
751 <td rowspan="1" colspan="1">
752 <a href="https://www.sqlite.org/lang_expr.html" shape="rect">SQLite</a>
753 </td>
754 <td rowspan="1" colspan="1">YES</td>
755 <td rowspan="1" colspan="1">YES</td>
756 <td rowspan="1" colspan="1"><strong>NO</strong></td>
757 <td rowspan="1" colspan="1">YES</td>
758 </tr>
759 <tr>
760 <td rowspan="1" colspan="1">
761 <a href="http://www.techonthenet.com/oracle/functions/bitand.php" shape="rect">Oracle</a>
762 </td>
763 <td rowspan="1" colspan="1">YES</td>
764 <td rowspan="1" colspan="1"><strong>NO</strong></td>
765 <td rowspan="1" colspan="1"><strong>NO</strong></td>
766 <td rowspan="1" colspan="1"><strong>NO</strong></td>
767 </tr>
768 <tr>
769 <td rowspan="1" colspan="1">
770 <a href="https://db.apache.org/derby/docs/10.10/ref/rrefsqlj55788.html" shape="rect">Derby</a>
771 </td>
772 <td rowspan="1" colspan="1"><strong>NO</strong></td>
773 <td rowspan="1" colspan="1"><strong>NO</strong></td>
774 <td rowspan="1" colspan="1"><strong>NO</strong></td>
775 <td rowspan="1" colspan="1"><strong>NO</strong></td>
776 </tr>
777 </table>
778 </p>
779 <p>
780 Given that support for the bitwise operators is not universal, it may be
781 necessary to define the bitwise operators as ADQL functions in addition to
782 the bitwise operators.
783 </p>
784 <p>
785 <pre xml:space="preserve">
786 BIT_AND(x, y)
787 BIT_OR(x, y)
788 BIT_XOR(x, y)
789 BIT_NOT(x)
790 </pre>
791 </p>
792 <p>
793 We can also define a <code>feature</code> in the <cite>[<a href="#std:TAPREGEXT">std:TAPREGEXT</a>]</cite>
794 specification, <code>features-bitwise</code>, to describe which of the
795 bitwise functions a service implements, similar to the
796 <code>features-adqlgeo</code> feature defined for the geometric
797 functions.
798 </p>
799 <p>
800 The meaning of the <code>features-bitwise</code> feature would cover both
801 the function syntax and the corresponding operator syntax.
802 </p>
803 <p>
804 So, a registration entry that declares support for the bitwise AND function
805 <pre xml:space="preserve">
806 BIT_AND(x, y)
807 </pre>
808 would also imply support for the bitwise AND operator.
809 <pre xml:space="preserve">
810 x &amp; y
811 </pre>
812 </p>
813 </div> <!-- subsubsection af-bitwise -->
814
815 <div class="section"><h4><a id="af-cast" shape="rect"><span class="secnum">2.2.11. </span>CAST operator</a></h4>
816 <p>
817 There are a number of cases where our scientists use the CAST operator
818 to control the type, size and precision of numerical values.
819 </p>
820 <p>
821 An example of this is a query described in
822 <a href="http://adsabs.harvard.edu/abs/2008MNRAS.384..637H" shape="rect">Hambly et al 2008,MNRAS,384,637–662</a>
823 which is useful for summarizing the contents of a selection and 'binning' the data.
824 <pre xml:space="preserve">
825 SELECT
826 COUNT(*) AS num
827 CAST(ROUND(l * 6.0, 0) AS INT) / 6.0 AS lon,
828 CAST(ROUND(b * 6.0, 0) AS INT) / 6.0 AS lat
829 FROM
830 gpsSource
831 WHERE
832 k_1Class BETWEEN −2 AND −1
833 AND
834 k_1ppErrBits &lt; 256
835 AND
836 (priOrSec = 0 OR priOrSec = frameSetID)
837 GROUP BY
838 CAST(ROUND(l * 6.0, 0) AS INT) / 6.0,
839 CAST(ROUND(b * 6.0, 0) AS INT) / 6.0
840 </pre>
841 </p>
842 <p>
843 With this use case in mind we would like to propose adding a limited version of the CAST operator to the ADQL language.
844 <pre xml:space="preserve">
845 CAST(&lt;numeric&gt; AS &lt;type&gt;)
846 </pre>
847 </p>
848 <p>
849 Note that the proposed syntax is slightly different to that of a normal ADQL function,
850 using <code>AS</code> rather than a comma as the separator, and a fixed enumeration of
851 types for the second parameter which would cover just the standard numeric types
852 <pre xml:space="preserve">
853 "SMALLINT" | "SHORT" | "INT" | "INTEGER" | "BIGINT" | "LONG" | "FLOAT" | "DOUBLE"
854 </pre>
855 </p>
856 <p>
857 The propsed <code>CAST(x AS &lt;type&gt;)</code> syntax is similar that used in many of the standard RDBMS.
858 <ul>
859 <li>
860 <a href="http://www.postgresql.org/docs/9.3/static/sql-expressions.html#SQL-SYNTAX-TYPE-CASTS" shape="rect">PostgreSQL</a>
861 </li>
862 <li>
863 <a href="https://dev.mysql.com/doc/refman/5.7/en/cast-functions.html#function_cast" shape="rect">MySQL</a>
864 </li>
865 <li>
866 <a href="http://msdn.microsoft.com/en-us/library/ms187928.aspx" shape="rect">SQLServer</a>
867 </li>
868 <li>
869 <a href="https://db.apache.org/derby/docs/10.2/ref/rrefsqlj33562.html" shape="rect">Apache Derby</a>
870 </li>
871 <li>
872 <a href="http://www.sqlite.org/lang_expr.html" shape="rect">SQLite</a>
873 </li>
874 <li>
875 <a href="http://www.techonthenet.com/oracle/functions/cast.php" shape="rect">Oracle</a>
876 </li>
877 </ul>
878 </p>
879 <p>
880 The proposed change does not aim to replicate the full functionality
881 and range of types provided by the different RDBMS implementations
882 of CAST. In particular we are not proposing to support <code>CHAR</code>,
883 <code>VARCHAR</code> or <code>DATETIME</code> conversions.
884 </p>
885 <p>
886 The aim of the proposed change is just to cover the primary use case of
887 provding a mechanism for converting between the standard numeric types.
888 <table>
889 <tr>
890 <th rowspan="1" colspan="1">&nbsp;</th>
891 <th rowspan="1" colspan="1">SHORT</th>
892 <th rowspan="1" colspan="1">INTEGER</th>
893 <th rowspan="1" colspan="1">LONG</th>
894 <th rowspan="1" colspan="1">FLOAT</th>
895 <th rowspan="1" colspan="1">DOUBLE</th>
896 </tr>
897 <tr>
898 <th rowspan="1" colspan="1">SHORT</th>
899 <td rowspan="1" colspan="1">-</td>
900 <td rowspan="1" colspan="1">Y</td>
901 <td rowspan="1" colspan="1">Y</td>
902 <td rowspan="1" colspan="1">Y</td>
903 <td rowspan="1" colspan="1">Y</td>
904 </tr>
905 <tr>
906 <th rowspan="1" colspan="1">INTEGER</th>
907 <td rowspan="1" colspan="1">Y</td>
908 <td rowspan="1" colspan="1">-</td>
909 <td rowspan="1" colspan="1">Y</td>
910 <td rowspan="1" colspan="1">Y</td>
911 <td rowspan="1" colspan="1">Y</td>
912 </tr>
913 <tr>
914 <th rowspan="1" colspan="1">LONG</th>
915 <td rowspan="1" colspan="1">Y</td>
916 <td rowspan="1" colspan="1">Y</td>
917 <td rowspan="1" colspan="1">-</td>
918 <td rowspan="1" colspan="1">Y</td>
919 <td rowspan="1" colspan="1">Y</td>
920 </tr>
921 <tr>
922 <th rowspan="1" colspan="1">FLOAT</th>
923 <td rowspan="1" colspan="1">Y</td>
924 <td rowspan="1" colspan="1">Y</td>
925 <td rowspan="1" colspan="1">Y</td>
926 <td rowspan="1" colspan="1">-</td>
927 <td rowspan="1" colspan="1">Y</td>
928 </tr>
929 <tr>
930 <th rowspan="1" colspan="1">DOUBLE</th>
931 <td rowspan="1" colspan="1">Y</td>
932 <td rowspan="1" colspan="1">Y</td>
933 <td rowspan="1" colspan="1">Y</td>
934 <td rowspan="1" colspan="1">Y</td>
935 <td rowspan="1" colspan="1">-</td>
936 </tr>
937 </table>
938 </p>
939 </div> <!-- subsubsection af-cast -->
940 </div> <!-- subsection adql-features -->
941 </div> <!-- section adql -->
942
943 <div class="section"><h2><a id="uws" shape="rect"><span class="secnum">3. </span>UWS</a></h2>
944 <div class="section"><h3><a id="uws-clar" shape="rect"><span class="secnum">3.1. </span>UWS: Clarifications, Errata, and Recommendations</a></h3>
945
946 <div class="section"><h4><a id="uc-initpost" shape="rect"><span class="secnum">3.1.1. </span>Updating Parameters</a></h4>
947
948 <p>Section 2.1.11 of
949 <cite>[<a href="#std:UWS">std:UWS</a>]</cite> states that a "particular implementation of UWS may
950 choose to allow the parameters to be updated after the initial job
951 creation step, before the Phase is set to the executing state" and
952 successively allows POSTing to jobs/job-id, jobs/job-id/parameters and
953 PUTting to jobs/job-id/parameters/parameter-name.</p>
954
955 <p>It turned out that the concrete semantics of this cavalier approach
956 quickly become difficult. We therefore propose to amend the language
957 on changing parameters post-creation by:</p>
958
959 <blockquote>
960 <p>
961 In most cases, the values of the parameters are all established during
962 the initial POST that creates the job. However, a particular
963 implementation of UWS may choose to allow the parameters to be updated
964 after the initial job creation step, before the Phase is set to the
965 executing state. It should, however, not offer the ability to create new
966 parameters nor delete existing parameters.
967 The next major version of this specification will remove the ability
968 to set an individual parameter.</p>
969
970 <p>From the client perspective, there is only one guaranteed way to set
971 a parameter that all UWS services must implement: In the initial POST
972 that creates the job.</p>
973 </blockquote>
974 </div> <!-- subsubsection uc-initpost -->
975
976 <div class="section"><h4><a id="uc-failedjobcreation" shape="rect"><span class="secnum">3.1.2. </span>Behaviour for Failed Job Creation</a></h4>
977 <p>In Section 2.2.3.1 of
978 <cite>[<a href="#std:UWS">std:UWS</a>]</cite> a UWS is required to return a "code 303 'See
979 other'" "unless the service rejects the request". It is not specified
980 what should happen when the service rejects the request.</p>
981
982 <p>We propose to add, at an appropriate position, the following
983 text:</p>
984
985 <blockquote>
986 <p>If the execution of an UWS request fails, the service has to
987 generate an appropriate error message with codes in the 400 (client
988 error) or 500 (server error) ranges according to
989 <cite>[<a href="#std:HTTP">std:HTTP</a>]</cite>. If the erroneous request is recoverable (e.g.,
990 a request for a transition to an impossible state), the job does not
991 go into the ERROR state because of a failed request.</p>
992
993 <p>The payload of such an error message SHOULD be a user-presentable
994 error message plain text, which SHOULD not be re-flowed by clients.
995 Clients MUST accept other
996 documents coming back as payloads of such request responses. As such
997 events can be assumed major server failures, it is recommended to
998 abandon a job that had a non-text/plain response to any UWS request.</p>
999 </blockquote>
1000
1001 </div> <!-- subsubsection uc-failedjobcreation -->
1002 </div> <!-- subsection uws-clar -->
1003
1004 <div class="section"><h3><a id="uws-features" shape="rect"><span class="secnum">3.2. </span>UWS: Proposed New Features</a></h3>
1005 <div class="section"><h4><a id="uf-quoteformat" shape="rect"><span class="secnum">3.2.1. </span>Format of Quote</a></h4>
1006 <p>Section 2.2.1 of
1007 <cite>[<a href="#std:UWS">std:UWS</a>]</cite> states that the jobs/job-id/quote resource
1008 represents quote as a number of seconds, while the schema represents
1009 quote as an xs:dateTime.</p>
1010
1011 <p>This is an unnecessary inconsistency. If no schema change is
1012 required by other changes in a UWS revision, we propose to solve it by
1013 requiring the representation in the resource to be in
1014 <cite>[<a href="#std:DALI">std:DALI</a>]</cite> YYYY-mm-ddThh:mm:ss form. While doing this, we
1015 should also clarify the format for the value of desctruction, that
1016 currently just defers to <cite>[<a href="#std:iso8601">std:iso8601</a>]</cite>; this should now refer
1017 to <cite>[<a href="#std:DALI">std:DALI</a>]</cite> as ISO 8601 allows many variants that are
1018 clearly not intended here.</p>
1019
1020 <p>If the UWS schema needs changing for other reasons, we suggest to
1021 unify the representations to the number of seconds on grounds that it is
1022 the more logical specification for the estimated duration of a job.</p>
1023
1024 </div> <!-- subsubsection uf-quoteformat -->
1025
1026 </div> <!-- subsection uws-features -->
1027 </div> <!-- section uws -->
1028
1029
1030 <div class="section"><h2><a id="tap" shape="rect"><span class="secnum">4. </span>TAP</a></h2>
1031 <div class="section"><h3><a id="tap-clar" shape="rect"><span class="secnum">4.1. </span>TAP: Clarifications, Errata, and Recommendations</a></h3>
1032
1033
1034 <div class="section"><h4><a id="tc-uploadsyntax" shape="rect"><span class="secnum">4.1.1. </span>Names of Uploaded Tables</a></h4>
1035 <p>Section 2.5 of
1036 <cite>[<a href="#std:TAP">std:TAP</a>]</cite> requires the name of the uploaded tables to be a
1037 "legal ADQL table name with no catalog or schema (e.g. an unqualified
1038 table name)". This language probably allows delimited identifiers,
1039 as the ADQL <em>table_name</em> can expand to one. This, however, was
1040 clearly not the intention of text, as the use of delimited identifiers
1041 is not (fully) supported by the syntax of the UPLOAD parameter. To
1042 resolve these difficulties, we propose to
1043 replace the parenthesis starting with "e.g." with:</p>
1044
1045 <blockquote>
1046 <p>i.e., a string following the <em>regular_identifier</em> production
1047 of
1048 <cite>[<a href="#std:ADQL">std:ADQL</a>]</cite>.</p>
1049 </blockquote>
1050
1051 <p>This could, in theory, invalidate existing clients that might want to
1052 use delimited identifiers in uploads. Due to the difficulties with the
1053 UPLOAD parameter syntax, however, that would not really be supported in
1054 version 1, either. Thus, we claim that this language can enter in a
1055 minor version.</p>
1056
1057 </div> <!-- subsubseciton tc-uploadsyntax -->
1058
1059 <div class="section"><h4><a id="tc-multiupload" shape="rect"><span class="secnum">4.1.2. </span>Multiple UPLOAD Posts</a></h4>
1060 <p>Since UWS allows posting parameters after job creation, Section 2.5.1
1061 of
1062 <cite>[<a href="#std:TAP">std:TAP</a>]</cite> needs to specify what happens when the UPLOAD
1063 parameter is posted into a job that already has one or more uploads. We
1064 propose to add at the end of the section:</p>
1065
1066 <blockquote>
1067 <p>UPLOADs are accumulating, i.e., each UPLOAD parameter given will
1068 create one or more tables in TAP_UPLOAD. When the table names from two
1069 or more upload items agree after case folding, the service behaviour is
1070 unspecified. Clients thus cannot reliably overwrite uploaded tables; to
1071 correct errors, they have to tear down the existing job and create a new
1072 one.</p>
1073 </blockquote>
1074 </div> <!-- subsubseciton tc-multiupload -->
1075
1076
1077 <div class="section"><h4><a id="tc-dbregion" shape="rect"><span class="secnum">4.1.3. </span>Database Column Types</a></h4>
1078 <p>Section 2.5 of
1079 <cite>[<a href="#std:TAP">std:TAP</a>]</cite> gives "database column types" for all kinds of
1080 VOTable objects. Given the lack of an ADQL type system, this must
1081 clearly be taken with a grain of salt; the types given in this column at
1082 least cannot be taken as conformance criteria. We propose to add the
1083 following language before section 2.5.1:</p>
1084
1085 <blockquote>
1086 <p>Note that the last column of Table (x) is not normative.
1087 Implementations SHOULD try to make sure that the actual types chosen are
1088 at least signature-compatible with the recommended types (i.e., integers
1089 should remain integers, floating-point values floating-point values,
1090 etc.), such that clients can reliably write queries against uploaded
1091 tables.</p>
1092 <p>For columns with xtype <code>adql:REGION</code>, this is particularly
1093 critical, since databases typically use different types to represent
1094 various STC-S objects. Clients are advised to assume that such columns
1095 will be approximated with polygons in the actual database table.</p>
1096 </blockquote>
1097 </div> <!-- subsubseciton tc-dbregion -->
1098
1099 <div class="section"><h4><a id="tc-size" shape="rect"><span class="secnum">4.1.4. </span>The size Column in TAP_SCHEMA</a></h4>
1100 <p>The table TAP_SCHEMA.columns as specified in section 2.6.3 of
1101 <cite>[<a href="#std:TAP">std:TAP</a>]</cite> has a column named size. This is unfortunate since
1102 SIZE is an ADQL reserved word, and thus must be quoted in queries.</p>
1103
1104 <p>We therefore propose to append the following language to section
1105 2.6.3:</p>
1106
1107 <blockquote>
1108 <p>To use <code>size</code> in a query, it must be put in double quotes
1109 since it collides with an ADQL reserved word. Since delimited
1110 identifiers are case-sensitive, for the size column both clients and
1111 servers MUST always (in particular, in the DDL for TAP_SCHEMA) use lower
1112 case exclusively.</p>
1113 <p>In the next major version of TAP, this column will be called
1114 <code>arraysize</code>.</p>
1115 </blockquote>
1116
1117 </div> <!-- subsubseciton tc-size -->
1118
1119
1120 <div class="section"><h4><a id="tc-errordoc" shape="rect"><span class="secnum">4.1.5. </span>Use of VOTable</a></h4>
1121 </div> <!-- subsubseciton tc-errordoc -->
1122 <p>To allow the text to be consistent with the rules for VOTable error
1123 documents, we propose the following changes in Section 2.9 of
1124 <cite>[<a href="#std:TAP">std:TAP</a>]</cite>:</p>
1125
1126
1127 <table>
1128 <tr><th rowspan="1" colspan="1">Current</th><th rowspan="1" colspan="1">New</th></tr>
1129 <tr>
1130 <td rowspan="1" colspan="1">
1131 The VOTable must contain a RESOURCE element identified with the
1132 attribute type='results', containing a single TABLE element with the
1133 results of the query.</td>
1134 <td rowspan="1" colspan="1">
1135 The VOTable must contain a RESOURCE element identified with the
1136 attribute type='results', containing exactly one TABLE element with the
1137 results of the query if the job execution was successful or no TABLE
1138 element if the job execution failed to produce a result.</td>
1139 </tr>
1140 <tr>
1141 <td rowspan="1" colspan="1">The RESOURCE element must contain, before the TABLE element, an INFO
1142 element with attribute name = "QUERY_STATUS". The value attribute must contain one of the following values:</td>
1143 <td rowspan="1" colspan="1">The RESOURCE element must contain an INFO
1144 element with attribute <code>name="QUERY_STATUS"</code> indicating the
1145 success of the operation. For RESOURCE elements
1146 that contain a TABLE element, this INFO element must appear lexically
1147 before the TABLE. The following values are defined for this INFO
1148 element's value attribute:</td>
1149 </tr>
1150 </table>
1151
1152
1153
1154
1155
1156 </div> <!-- subsection tap-clar -->
1157
1158
1159 <div class="section"><h3><a id="tap-features" shape="rect"><span class="secnum">4.2. </span>TAP: New Features</a></h3>
1160
1161 <div class="section"><h4><a id="tf-examples" shape="rect"><span class="secnum">4.2.1. </span>An examples Endpoint</a></h4>
1162 <p>Feedback from TAP users indicates that providing query examples is
1163 considered most helpful, which is probably not surprising since to
1164 effectively use a TAP service, a user has to combine knowlege of a
1165 fairly complex query language with server-specific metadata like table
1166 schemata and local extensions as well as domain knowledge. A head start
1167 as provided by examples doing something related to what the users
1168 actually want is therefore most welcome.</p>
1169
1170 <p>TAP services are usually accessed through specialized clients.
1171 Therefore, a simple link "for examples see here" will in general not
1172 work for them. In principle, one could simply communicate an example
1173 URL to a client and let the user browse it. Allowing a certain amount
1174 of structuring within the document at this URL, however, lets clients
1175 do some useful in-application presentation of the examples.</p>
1176
1177 <p><cite>[<a href="#std:DALI">std:DALI</a>]</cite> defines a simple system to communicate examples
1178 to humans and machine clients alike, based on RDFa. This section
1179 specifies how the generic DALI specification is to be applied to
1180 TAP.</p>
1181
1182 <div class="section"><h4><a id="tf-ex-endpoint" shape="rect"><span class="secnum">4.2.1.1. </span>The Endpoint</a></h4>
1183 <p>A TAP server exposes the example queries in an <code>examples</code>
1184 endpoint
1185 residing next to <code>sync</code>, <code>async</code> ,
1186 and the VOSI endpoints. A GET from
1187 this endpoint MUST yield a document with a MIME type of either
1188 <code>application/xhtml+xml</code> or <code>text/html</code>. A service
1189 that does not provide examples MUST return a 404 HTTP status on
1190 accessing this resource.</p>
1191
1192 <p>If present, the endpoint must be represented in a capability in the
1193 TAP service's registry record. The capability's standardID is, as
1194 defined by DALI, <code>ivo://ivoa.net/std/DALI#examples</code>. A
1195 capability element could hence look like this:</p>
1196
1197 <pre xml:space="preserve">
1198
1199 &lt;capability standardID="ivo://ivoa.net/std/DALI#examples"&gt;
1200 &lt;interface xsi:type="vr:WebBrowser"&gt;
1201 &lt;accessURL use="full"&gt;http://localhost:8080/tap/examples&lt;/accessURL&gt;
1202 &lt;/interface&gt;
1203 &lt;/capability&gt;
1204
1205 </pre>
1206
1207 </div> <!-- subsubseciton tf-ex-endpoint -->
1208
1209 <div class="section"><h4><a id="tf-ex-content" shape="rect"><span class="secnum">4.2.1.2. </span>Document Content</a></h4>
1210
1211 <p>The document at <code>examples</code> MUST follow the rules laid out
1212 for DALI-examples in <cite>[<a href="#std:DALI">std:DALI</a>]</cite>; in particular, it must be
1213 valid XML, viewable with "common web browsers".</p>
1214
1215 <p>TAP defines two additional properties within the
1216 <code>ivo://ivoa.net/std/DALI-examples</code> (note that at the time of
1217 writing the DALI PR has "DALI#examples" here, which we corrected here)
1218 vocabulary:</p>
1219
1220 <ul>
1221 <li><code>query</code> --
1222 each example MUST have a unique child
1223 element with simple text content having a <code>property</code>
1224 attribute valued <code>query</code>. It contains the query itself,
1225 preferably with extra whitespace for easy human consumption and editing.
1226 This will usually be a HTML <code>pre</code> element.</li>
1227
1228 <li><code>table</code> -- examples MAY also have descendants with
1229 <code>property</code> attributes having the value
1230 <code>table</code>. These must have pure text content and
1231 contain fully qualified table names to which the query is somehow
1232 "pertaining". Suitable HTML elements holding these include
1233 <code>span</code>, or <code>a</code> (which would
1234 allow linking to further information on the table).</li>
1235
1236 </ul>
1237 <p>An example for a document served from the examples endpoint is given
1238 in Appendix <span class="xref"><a href="#appA">A</a></span></p>
1239 </div> <!-- subsubsubsection tf-ex-content -->
1240
1241 <div class="section"><h4><a id="tf-ex-use" shape="rect"><span class="secnum">4.2.1.3. </span>Intended Use</a></h4>
1242
1243 <p>In the simplest case, TAP clients can provide links to the current
1244 server's example endpoint. A more advanced interface would give an
1245 interface element allowing the selection of example titles with the
1246 option of entering the sample query into the query field of the user
1247 interface. The documentation for the query would be accessed by opening
1248 a web browser using the base example URL and the example's fragment
1249 identfier.</p>
1250
1251 <p>Advanced clients could render the HTML div elements themselves, and they
1252 could provide a means to discover example queries involving particular
1253 tables in their table metadata browser based on
1254 <code>property=table</code> markup.</p>
1255 </div> <!-- subsubsubsection tf-ex-use -->
1256
1257
1258 <div class="section"><h4><a id="tf-ex-validation" shape="rect"><span class="secnum">4.2.1.4. </span>Validation</a></h4>
1259
1260 <p>Appendix <span class="xref"><a href="#appB">B</a></span> gives an XSLT 1.0 stylesheet
1261 that extracts the machine readable information from compliant documents
1262 and emits the results in text format.</p>
1263
1264 <p>The style sheet checks for proper vocabulary declaration. If you
1265 have no element declaring the vocabulary, the output will be empty.</p>
1266
1267 <p>Service operators should also use RDFa validation tools, e.g., the W3C RDFa
1268 validator <cite>[<a href="#svc:RDFaVal">svc:RDFaVal</a>]</cite>, to make sure their document is usable
1269 from RDF tools.</p>
1270 </div> <!-- subsubsubsection tf-ex-validation -->
1271
1272 </div> <!-- subsubseciton tf-examples -->
1273
1274 <div class="section"><h4><a id="tf-plan" shape="rect"><span class="secnum">4.2.2. </span>A plan Endpoint</a></h4>
1275
1276 <p class="tbw">CDS have a debug endpoint with additional information;
1277 join their concepts with this.</p>
1278
1279 <p>As already noted in <cite>[<a href="#std:TAP">std:TAP</a>]</cite>, it is notoriously
1280 difficult to predict the runtime of SQL queries. For nontrivial
1281 queries, even experts may have a hard time figuring out performance
1282 bottlenecks. Therefore, most database systems provide some mechanism to
1283 obtain a query plan, that is, to inspect what elementary operations will
1284 be performed for a given query.</p>
1285
1286 <p>Since TAP queries are typically formulated by persons not intimately
1287 familiar with the database queried, the need for a mechanism allowing
1288 insights into the database engine's reasoning is
1289 even more pronounced. On the other hand, different database systems
1290 give their plans in completely different formats and even schemata. In
1291 addition, as the Postgres Documentation
1292 says: "Plan-reading is an art that deserves an extensive tutorial"
1293 (<cite>[<a href="#doc:Postgres92">doc:Postgres92</a>]</cite>, Sect. 14.1).</p>
1294
1295 <p>Thus, specifying a fixed format for query plans that would be both
1296 expressive enough and sufficiently generic to be easily adaptible to
1297 various backend database engines is probably impossible. To still allow
1298 users to inspect actual query plans, we propose the following language
1299 be added at the end of section 2.2.2 of <cite>[<a href="#std:TAP">std:TAP</a>]</cite>:</p>
1300
1301 <blockquote>
1302 <p>In addition to the UWS resources, a TAP server SHOULD support a
1303 child <code>plan</code> for each job resource. If retrieving this
1304 resource is successful (i.e., results in a 200 HTTP response after
1305 possible redirects and authentication), it MUST be a preformatted
1306 document with MIME type <code>text/plain</code>. Within it, the actual
1307 query as executed by the database engine MUST come first.</p>
1308
1309 <p>After at least one blank line, a rendering of the query plan follows.
1310 Note that the query as excecuted may contain blank lines, which means
1311 that machine clients cannot use the blank line to separate query and
1312 plan. In general, clients SHOULD display the plan without any
1313 reformatting in a fixed-width font.</p>
1314
1315 <p>Since it is hard to define a generic and sufficiently
1316 expressive format for query plans and the authors want to avoid
1317 excessive implemenation cost for this feature, this specification does
1318 not give a format for the query plan. Implementors are advised to keep
1319 as much of the "native" plan format of their database engine as
1320 possible.</p>
1321
1322 <p>After the plan, the service is free to give additional debugging
1323 information. The indended audience for this information are again
1324 humans, so even in cases where proprietary clients actually parse out
1325 information from that area, such information should still be
1326 decipherable by knowledgeable humans.</p>
1327
1328 <p>If the creation of the query plan fails, the service MUST reply with
1329 a 400 (if the failure appears to be due to syntax errors in the query,
1330 the query plan not being available in this UWS phase, or
1331 similar problems) or 500 HTTP status code. Errors in plan generation do
1332 <em>not</em> change the phase of the job. Clients may thus use the plan
1333 endpoint to check the syntax of a query on services supporting it.</p>
1334
1335 <p>Services that cannot or choose not to support the retrieval of query
1336 plans MUST respond with a 404 HTTP code to requests for
1337 <code>plan</code> children of job resources.</p>
1338
1339 <p>Except for 404 responses, all documents delivered from the plan
1340 endpoint MUST have the MIME type text/plain. They should contain ASCII
1341 exclusively, but clients SHOULD assume UTF-8 encoding if no
1342 character set is declared by HTTP means.</p>
1343 </blockquote>
1344
1345 </div> <!-- subsubseciton tf-plan -->
1346
1347
1348
1349 <div class="section"><h4><a id="tf-scaletable" shape="rect"><span class="secnum">4.2.3. </span>Scaleable tables Endpoint</a></h4>
1350 <p>For archives serving hundreds or thousands of tables, the
1351 tables endpoint on TAP services as defined by <cite>[<a href="#std:VOSI">std:VOSI</a>]</cite>
1352 will have to return documents of several dozen megabytes. This results
1353 in nontrivial transfer times for data that in all likelihood is
1354 uninteresting to the user that typically will only write queries against
1355 fairly few of those tables.</p>
1356
1357 <p>To mitigate this problem, we propose to define that
1358 <code>vs:Table</code> typed elements in responses from VOSI table
1359 endpoints that have no <code>column</code> children are to be regarded
1360 as stubs by clients. A client SHOULD give the user the possibility to
1361 request "full" information on such a stubbed table. This full
1362 information is available from a child resource of tables named like the
1363 table, in exactly the captialization as given in the <code>name</code>
1364 child of the table stub; it would come as the full table element.</p>
1365
1366 <p>As an example, a service might return the following from its tables
1367 endpoint:</p>
1368
1369 <pre xml:space="preserve">
1370 &lt;tableset xmlns:vs="http://www.ivoa.net/xml/VODataService/v1.1"
1371 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
1372 xsi:type="vs:TableSet"&gt;
1373 &lt;schema&gt;
1374 &lt;name&gt;ppmxl&lt;/name&gt;
1375 &lt;table&gt;
1376 &lt;name&gt;ppmxl.main&lt;/name&gt;
1377 &lt;/table&gt;
1378 &lt;/schema&gt;
1379 &lt;/tableset&gt;
1380 </pre>
1381
1382 <p>A client could then retrieve the url
1383 <code>.../tables/ppmxl.main</code> and would receive something like
1384 this:</p>
1385
1386 <pre xml:space="preserve">
1387 &lt;table xmlns:vs="http://www.ivoa.net/xml/VODataService/v1.1"
1388 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
1389 xsi:type="vs:Table"&gt;
1390 &lt;name&gt;ppmxl.main&lt;/name&gt;
1391 &lt;description&gt; PPMXL is a catalog of positions, proper motions...
1392 &lt;/description&gt;
1393 &lt;column&gt;
1394 &lt;name&gt;ipix&lt;/name&gt;
1395 &lt;description&gt;Identifier (Q3C ipix of the USNO-B 1.0 object)&lt;/description&gt;
1396 ...
1397 &lt;/table&gt;
1398 </pre>
1399
1400 <p>More formally, we propose to replace the last paragraph of section
1401 3.4, "Table metadata", of <cite>[<a href="#std:VOSI">std:VOSI</a>]</cite>, Version 1.0, with the
1402 following text:</p>
1403
1404 <blockquote>
1405 <p>In the REST binding, the registred URL retrieves an XML document
1406 containing this element. However, services exposing a large number of
1407 tables may only write table stubs into the document retrieved from this
1408 web resource. Table stubs are table elements containing no column
1409 children. While the XSD requires a name child to be present, the
1410 services may or may not include any of the remaining table metadata.</p>
1411
1412 <p>Still in the REST binding, the server that has produced such a columnless
1413 table element should provide a child of the tables resource named like the
1414 content of the tables <code>name</code> child element, with any leading
1415 or trailing whitespace removed. If a request for this resource is
1416 successful, the document received must contain an XML document containing
1417 a single element of the type
1418 <em>{http://www.ivoa.net/xml/VODataService/v1.1}Table</em> with all metadata
1419 available for the table.</p>
1420 </blockquote>
1421
1422 </div> <!-- subsubseciton tf-scaletable -->
1423
1424 <div class="section"><h4><a id="tf-noasync" shape="rect"><span class="secnum">4.2.4. </span>Making the async Endpoint Optional</a></h4>
1425
1426 <p>Some existing TAP-like services have data that is small and simple enough
1427 that synchronous queries are likely to be sufficient. They therefore
1428 chose not to implement the async endpoint, which makes these services
1429 technically non-TAP. Given the implemenation overhead of a UWS for
1430 something that is not really required by the services in question, the
1431 choice seems reasonable, though, and the services are "mostly
1432 interoperable" with existing clients in that there are usually ways to
1433 operate the services from the clients.</p>
1434
1435 <p>It therefore seems reasonable to make the async endpoint optional and add
1436 language that requires clients to offer ways to fall back to synchronous
1437 operation for services that do not support async.</p>
1438
1439 <p>Against this proposal it has been levelled that</p>
1440
1441 <ol>
1442 <li>While it is nice to apply TAP to simple tasks, its primary focus is
1443 solving hard problems with potentially long runtimes. To make this possible
1444 (reliably), asynchronous operation is a must.</li>
1445 <li>Optional features cannot be relied upon by clients. They are thus
1446 undesirable in principle, but in particular whatever is necessary to
1447 deal with the principal problems which the standard is intended to solve
1448 must not be optional;</li>
1449 <li>Thus, if anything, sync should be made optional, as it is easily
1450 simulated using async but not the other way round;</li>
1451 <li>Given that, we should not downgrade the standard but upgrade the
1452 implementations. There are several good, interoperable, open TAP
1453 implementations available, so nobody should be forced to run homegrown,
1454 non-compliant services.</li>
1455 </ol>
1456 </div> <!-- subsubseciton tf-noasync -->
1457
1458 <div class="section"><h4><a id="tf-tapschema-opt" shape="rect"><span class="secnum">4.2.5. </span>Making TAP_SCHEMA optional</a></h4>
1459 <p>
1460 The TAP_SCHEMA specification makes a number of assumptions
1461 <ul>
1462 <li>The system is based on a standard RDBMS</li>
1463 <li>The data model closely follows the layout of the physical schema
1464 in the database</li>
1465 <li>All of the tables are visible to everyone</li>
1466 </ul>
1467 If these assumptions hold true, then implementing TAP_SCHEMA is relatively
1468 easy and provides a rich set of tools for clients to query the available
1469 information.
1470 However, if some of these assumptions are not true, then implementing
1471 TAP_SCHEMA can be problematic, and in some cases it may be impossible
1472 to publish a full set of metadata describing all of the tables and
1473 columns available in a service.
1474 </p>
1475 <p>
1476 We would therefore like to propose that TAP_SCHEMA is listed as an
1477 optional rather than mandatory feature of the TAP specification.
1478 </p>
1479 <p>
1480 The original intent of the TAP and ADQL specifications was to provide
1481 an abstraction layer which hides the details of the underlying database
1482 implementation.
1483 On the other hand, the TAP_SCHEMA data model is based directly on the
1484 system tables are available in many of the standard RDBMS.
1485 This close mapping between the TAP_SCHEMA data model and the RDBMS
1486 system tables means loosing a level of abstraction provided by TAP.
1487 </p>
1488 <div class="section"><h4><a id="tf-tapschema-examples" shape="rect"><span class="secnum">4.2.5.1. </span>Examples</a></h4>
1489 <div class="section"><h4><a id="tf-tapschema-virtual"><span class="secnum">4.2.5.1.1. </span>Virtual data</a></h4>
1490 <p>
1491 If a TAP service is providing access to a virtual dataset that contains
1492 data from more than one RDBMS, then there is no single set of system
1493 tables that contain information about all of the tables available via
1494 the TAP service.
1495 It may be possible to create a set of tables that combines the metadata
1496 from the individual component datasets, but if the list of tables in
1497 the datasets is itself dynamic (e.g. user uploaded tata) then maintaining
1498 an up to date copy of the table metadata becomes a problem.
1499 </p>
1500 </div> <!-- subsubseciton tapschema-virtual -->
1501 <div class="section"><h4><a id="tf-tapschema-private"><span class="secnum">4.2.5.1.2. </span>Private data</a></h4>
1502 <p>
1503 If a TAP service is providing storage for user data, then some or all
1504 of that may be in a protected space, not visible to other users.
1505 In this situation, the service would need to selectively filter the
1506 visibility of individual tables and columns depending on who is asking.
1507 This would mean selectively controlling the visibility of individual
1508 rows in the TAP_SCHEMA tables based on the identity of the user making
1509 the request.
1510 </p>
1511 </div> <!-- subsubseciton tf-tapschema-private -->
1512 <div class="section"><h4><a id="tf-tapschema-nosql"><span class="secnum">4.2.5.1.3. </span>Alternative systems</a></h4>
1513 <p>
1514 Many of the alternative 'NoSQL' systems do not have anything
1515 equivalent to the system tables available in many RDBMS.
1516 Requiring a TAP service to implement the TAP_SCHEMA tables on such
1517 a system adds a barrier to entry for new and experimental services
1518 based on alternative database providers.
1519 </p>
1520 </div> <!-- subsubseciton tf-tapschema-nosql -->
1521 </div> <!-- subsubseciton tf-tapschema-examples -->
1522 </div> <!-- subsubseciton tf-tapschema-opt -->
1523
1524 <div class="section"><h4><a id="tapschema-naming" shape="rect"><span class="secnum">4.2.6. </span>Letting TAP_SCHEMA name be custom</a></h4>
1525 <p>
1526 Even with TAP_SCHEMA set as an optional feature for a TAP service, the
1527 fixed name TAP_SCHEMA itself assumes that no more than one service per
1528 SQL server is possible unless some work around is in place.<br clear="none"/>
1529 A fixed schema name is useful, e.g., to let a unique query to be
1530 understood by all possible TAP services and simplifies, probably, the
1531 load of work on client applications. However it complicates the
1532 development of server side code for multiple services on a single
1533 server.<br clear="none"/>
1534 Given that client application usually interrogate the <i>tables</i>
1535 endpoint to retrieve the available tablesets from a TAP
1536 service, a solution could be to embed into it the information on the
1537 name of the schema that acts as the TAP_SCHEMA if a different name
1538 is used.<br clear="none"/>
1539 Letting the schema name be a custom publisher's choice (whatever the
1540 implementing solution to provide the schema name to the clients) will
1541 disrupt the idea of a single query running on all available TAP
1542 services. To fix this a possible solution is to reserve a word in ADQL
1543 to be used to identify the TAP_SCHEMA schema in a unique way at
1544 query level.
1545 </p>
1546 </div> <!-- end of section tapschema-naming -->
1547
1548 <div class="section"><h4><a id="tf-meta-dyn" shape="rect"><span class="secnum">4.2.7. </span>Dynamic metadata</a></h4>
1549 <p>
1550 With the advent of TAP services that publish user generated data,
1551 the metadata for the tables and columns in these services is likely
1552 to change on a regular basis.
1553 It would be useful to be able to describe the volatility of a
1554 particular metadata record in some way, enabling a client that
1555 caches the metadata to be able to manage their cache more efficiently.
1556 </p>
1557 <div class="section"><h4><a id="tf-meta-ttl" shape="rect"><span class="secnum">4.2.7.1. </span>Time to live</a></h4>
1558 <p>
1559 We would like to propose adding a <code>TimeToLive</code> attribute to elements
1560 in the metadata, which would function in a similar manner to the
1561 <code>TTL</code> attribute on <cite>[<a href="#std:DNS">std:DNS</a>]</cite> records.
1562 <ul>
1563 <li>
1564 Records that are expected to change regularly, e.g. recently
1565 uploaded user data, would be assigned a relatively low
1566 lifetime, in the order of a few minutes.
1567 </li>
1568 <li>
1569 Records that are not expected to change regularly, e.g. a
1570 published science archive, would be assigned a relatively
1571 high lifetime, in the order of a few hours.
1572 </li>
1573 </ul>
1574 </p>
1575 <p>
1576 These attributes would enable a client to prioritise
1577 which metadata records needed to be refreshed.
1578 </p>
1579 </div> <!-- subsubseciton tf-meta-ttl -->
1580 </div> <!-- subsubseciton tf-meta-dyn -->
1581 </div> <!-- subsection tap-features -->
1582 </div> <!-- section tap -->
1583
1584 <div class="appendices">
1585 <div class="section"><h2><a id="appA" shape="rect"><span class="secnum">A. </span>An Example for an /examples Document</a></h2>
1586 <?incxml href="../examples_ex.html"?><h:div xmlns:h="http://www.w3.org/1999/xhtml" class="viewxml"><div class="element"><span class="markup">&lt;</span><span class="start-tag">html</span> <span class="attribute-name">version</span><span class="markup">=</span><span class="attribute-value">"XHTML+RDFa 1.1"</span> <span class="attribute-name">xmlns:xml</span><span class="markup">=</span><span class="attribute-value">"http://www.w3.org/XML/1998/namespace"</span> <span class="attribute-name">xmlns:</span><span class="markup">=</span><span class="attribute-value">"http://www.w3.org/1999/xhtml"</span><span class="markup">&gt;</span><div class="indent"><div class="element"><span class="markup">&lt;</span><span class="start-tag">head</span><span class="markup">&gt;</span><div class="indent"><div class="element"><span class="markup">&lt;</span><span class="start-tag">title</span><span class="markup">&gt;</span><span class="text">TAP examples example</span><span class="markup">&lt;/</span><span class="end-tag">title</span><span class="markup">&gt;</span></div></div><span class="markup">&lt;/</span><span class="end-tag">head</span><span class="markup">&gt;</span></div><div class="element"><span class="markup">&lt;</span><span class="start-tag">body</span> <span class="attribute-name">vocab</span><span class="markup">=</span><span class="attribute-value">"ivo://ivoa.net/std/DALI-examples"</span><span class="markup">&gt;</span><div class="indent"><div class="element"><span class="markup">&lt;</span><span class="start-tag">h1</span><span class="markup">&gt;</span><span class="text">Example Queries for our TAP Service</span><span class="markup">&lt;/</span><span class="end-tag">h1</span><span class="markup">&gt;</span></div><div class="element"><span class="markup">&lt;</span><span class="start-tag">div</span> <span class="attribute-name">resource</span><span class="markup">=</span><span class="attribute-value">"#katkatbib"</span> <span class="attribute-name">typeof</span><span class="markup">=</span><span class="attribute-value">"example"</span> <span class="attribute-name">id</span><span class="markup">=</span><span class="attribute-value">"#katkatbib"</span><span class="markup">&gt;</span><div class="indent"><div class="element"><span class="markup">&lt;</span><span class="start-tag">h2</span> <span class="attribute-name">property</span><span class="markup">=</span><span class="attribute-value">"name"</span><span class="markup">&gt;</span><span class="text">katkat bibliography</span><span class="markup">&lt;/</span><span class="end-tag">h2</span><span class="markup">&gt;</span></div><div class="element"><span class="markup">&lt;</span><span class="start-tag">p</span><span class="markup">&gt;</span><div class="indent"><div class="text">To search for title (or other) words in
1587 </div><div class="element"><span class="markup">&lt;</span><span class="start-tag">a</span> <span class="attribute-name">property</span><span class="markup">=</span><span class="attribute-value">"table"</span> <span class="attribute-name">href</span><span class="markup">=</span><span class="attribute-value">"/tableinfo/katkat.katkat"</span><span class="markup">&gt;</span><span class="text">katkat.katkat</span><span class="markup">&lt;/</span><span class="end-tag">a</span><span class="markup">&gt;</span></div><div class="text">'s source field or in some other sort of
1588 bibliographic query, use the
1589 </div><div class="element"><span class="markup">&lt;</span><span class="start-tag">tt</span> <span class="attribute-name">class</span><span class="markup">=</span><span class="attribute-value">"literal"</span><span class="markup">&gt;</span><span class="text">gavo_hasword</span><span class="markup">&lt;/</span><span class="end-tag">tt</span><span class="markup">&gt;</span></div><div class="text"> locally defined function.
1590 This basically works a bit like you'd expect from search engines:
1591 case-insensitive, and oblivious to any context.</div></div><span class="markup">&lt;/</span><span class="end-tag">p</span><span class="markup">&gt;</span></div><div class="element"><span class="markup">&lt;</span><span class="start-tag">p</span><span class="markup">&gt;</span><span class="text">Try the following query:</span><span class="markup">&lt;/</span><span class="end-tag">p</span><span class="markup">&gt;</span></div><div class="element"><span class="markup">&lt;</span><span class="start-tag">pre</span> <span class="attribute-name">property</span><span class="markup">=</span><span class="attribute-value">"query"</span><span class="markup">&gt;</span><span class="text">select *
1592 from katkat.katkat
1593 where gavo_hasword('variable', source)
1594 and minEpoch&amp;lt;1900
1595 </span><span class="markup">&lt;/</span><span class="end-tag">pre</span><span class="markup">&gt;</span></div></div><span class="markup">&lt;/</span><span class="end-tag">div</span><span class="markup">&gt;</span></div><div class="element"><span class="markup">&lt;</span><span class="start-tag">div</span> <span class="attribute-name">resource</span><span class="markup">=</span><span class="attribute-value">"#arigfhmultiflags"</span> <span class="attribute-name">typeof</span><span class="markup">=</span><span class="attribute-value">"example"</span> <span class="attribute-name">id</span><span class="markup">=</span><span class="attribute-value">"arigfhmultiflags"</span><span class="markup">&gt;</span><div class="indent"><div class="element"><span class="markup">&lt;</span><span class="start-tag">h2</span> <span class="attribute-name">property</span><span class="markup">=</span><span class="attribute-value">"name"</span><span class="markup">&gt;</span><span class="text">arigfh multiflags</span><span class="markup">&lt;/</span><span class="end-tag">h2</span><span class="markup">&gt;</span></div><div class="element"><span class="markup">&lt;</span><span class="start-tag">p</span><span class="markup">&gt;</span><div class="indent"><div class="text">This query selects reflected observations and their epochs and
1596 equinoxes from the identified objects within
1597 </div><div class="element"><span class="markup">&lt;</span><span class="start-tag">a</span> <span class="attribute-name">property</span><span class="markup">=</span><span class="attribute-value">"table"</span> <span class="attribute-name">href</span><span class="markup">=</span><span class="attribute-value">"/tableinfo/arigfh.id"</span><span class="markup">&gt;</span><span class="text">arigfh.id</span><span class="markup">&lt;/</span><span class="end-tag">a</span><span class="markup">&gt;</span></div><div class="text">. This
1598 example in particular shows how to decode combined flags (i.e.,
1599 flags-like numbers in which digits (or groups of digits) need to
1600 be extracted to allow interpretation.</div></div><span class="markup">&lt;/</span><span class="end-tag">p</span><span class="markup">&gt;</span></div><div class="element"><span class="markup">&lt;</span><span class="start-tag">p</span><span class="markup">&gt;</span><span class="text">Try the following query:</span><span class="markup">&lt;/</span><span class="end-tag">p</span><span class="markup">&gt;</span></div><div class="element"><span class="markup">&lt;</span><span class="start-tag">pre</span> <span class="attribute-name">property</span><span class="markup">=</span><span class="attribute-value">"query"</span><span class="markup">&gt;</span><span class="text">
1601 SELECT decCat, raj2000, dej2000, epDec, eqDec
1602 FROM arigfh.id
1603 WHERE 4=mod(decflags/10000, 10)
1604 </span><span class="markup">&lt;/</span><span class="end-tag">pre</span><span class="markup">&gt;</span></div></div><span class="markup">&lt;/</span><span class="end-tag">div</span><span class="markup">&gt;</span></div></div><span class="markup">&lt;/</span><span class="end-tag">body</span><span class="markup">&gt;</span></div></div><span class="markup">&lt;/</span><span class="end-tag">html</span><span class="markup">&gt;</span></div></h:div>
1605 </div> <!-- appA -->
1606
1607 <div class="section"><h2><a id="appB" shape="rect"><span class="secnum">B. </span>An XSLT Stylesheet for Validating an examples Document</a></h2>
1608 <?incxml href="../tapexex.xslt"?><h:div xmlns:h="http://www.w3.org/1999/xhtml" class="viewxml"><div class="element"><span class="markup">&lt;</span><span class="start-tag">stylesheet</span> <span class="attribute-name">version</span><span class="markup">=</span><span class="attribute-value">"1.0"</span> <span class="attribute-name">xmlns:xml</span><span class="markup">=</span><span class="attribute-value">"http://www.w3.org/XML/1998/namespace"</span> <span class="attribute-name">xmlns:</span><span class="markup">=</span><span class="attribute-value">"http://www.w3.org/1999/XSL/Transform"</span> <span class="attribute-name">xmlns:http</span><span class="markup">=</span><span class="attribute-value">"http://www.w3.org/1999/xhtml"</span><span class="markup">&gt;</span><div class="indent"><div class="comment">&lt;!-- This XSLT stylesheet extracts from a TAP
1609 examples endpoint what machine-readable information is in there.
1610
1611
1612 See TAP Implementation Notes for details.
1613 --&gt;</div><div class="comment">&lt;!--
1614 This program is free software: you can redistribute it and/or modify
1615 it under the terms of the GNU General Public License as published by
1616 the Free Software Foundation, either version 3 of the License, or
1617 (at your option) any later version.
1618
1619 This program is distributed in the hope that it will be useful,
1620 but WITHOUT ANY WARRANTY; without even the implied warranty of
1621 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
1622 GNU General Public License for more details.
1623
1624 For the complete text of the GPL, see http://www.gnu.org/licenses/.
1625 --&gt;</div><div class="element"><span class="markup">&lt;</span><span class="start-tag">output</span> <span class="attribute-name">method</span><span class="markup">=</span><span class="attribute-value">"text"</span><span class="markup">/&gt;</span></div><div class="element"><span class="markup">&lt;</span><span class="start-tag">strip-space</span> <span class="attribute-name">elements</span><span class="markup">=</span><span class="attribute-value">"*"</span><span class="markup">/&gt;</span></div><div class="element"><span class="markup">&lt;</span><span class="start-tag">template</span> <span class="attribute-name">match</span><span class="markup">=</span><span class="attribute-value">"*[@property='example']"</span> <span class="attribute-name">mode</span><span class="markup">=</span><span class="attribute-value">"invocab"</span><span class="markup">&gt;</span><div class="indent"><div class="element"><span class="markup">&lt;</span><span class="start-tag">text</span><span class="markup">&gt;</span><span class="text">================================================
1626 Example id=</span><span class="markup">&lt;/</span><span class="end-tag">text</span><span class="markup">&gt;</span></div><div class="element"><span class="markup">&lt;</span><span class="start-tag">value-of</span> <span class="attribute-name">select</span><span class="markup">=</span><span class="attribute-value">"@id"</span><span class="markup">/&gt;</span></div><div class="element"><span class="markup">&lt;</span><span class="start-tag">text</span><span class="markup">&gt;</span><span class="text">
1627
1628 </span><span class="markup">&lt;/</span><span class="end-tag">text</span><span class="markup">&gt;</span></div><div class="element"><span class="markup">&lt;</span><span class="start-tag">apply-templates</span> <span class="attribute-name">mode</span><span class="markup">=</span><span class="attribute-value">"invocab"</span><span class="markup">/&gt;</span></div><div class="element"><span class="markup">&lt;</span><span class="start-tag">text</span><span class="markup">&gt;</span><span class="text">================================================
1629
1630 </span><span class="markup">&lt;/</span><span class="end-tag">text</span><span class="markup">&gt;</span></div></div><span class="markup">&lt;/</span><span class="end-tag">template</span><span class="markup">&gt;</span></div><div class="element"><span class="markup">&lt;</span><span class="start-tag">template</span> <span class="attribute-name">match</span><span class="markup">=</span><span class="attribute-value">"*[@property='name']"</span> <span class="attribute-name">mode</span><span class="markup">=</span><span class="attribute-value">"invocab"</span><span class="markup">&gt;</span><div class="indent"><div class="element"><span class="markup">&lt;</span><span class="start-tag">text</span><span class="markup">&gt;</span><span class="text">Name: </span><span class="markup">&lt;/</span><span class="end-tag">text</span><span class="markup">&gt;</span></div><div class="element"><span class="markup">&lt;</span><span class="start-tag">value-of</span> <span class="attribute-name">select</span><span class="markup">=</span><span class="attribute-value">"text()"</span><span class="markup">/&gt;</span></div><div class="element"><span class="markup">&lt;</span><span class="start-tag">text</span><span class="markup">&gt;</span><span class="text">
1631 </span><span class="markup">&lt;/</span><span class="end-tag">text</span><span class="markup">&gt;</span></div></div><span class="markup">&lt;/</span><span class="end-tag">template</span><span class="markup">&gt;</span></div><div class="element"><span class="markup">&lt;</span><span class="start-tag">template</span> <span class="attribute-name">match</span><span class="markup">=</span><span class="attribute-value">"*[@property='table']"</span> <span class="attribute-name">mode</span><span class="markup">=</span><span class="attribute-value">"invocab"</span><span class="markup">&gt;</span><div class="indent"><div class="element"><span class="markup">&lt;</span><span class="start-tag">text</span><span class="markup">&gt;</span><span class="text">Pertains to: </span><span class="markup">&lt;/</span><span class="end-tag">text</span><span class="markup">&gt;</span></div><div class="element"><span class="markup">&lt;</span><span class="start-tag">value-of</span> <span class="attribute-name">select</span><span class="markup">=</span><span class="attribute-value">"text()"</span><span class="markup">/&gt;</span></div><div class="element"><span class="markup">&lt;</span><span class="start-tag">text</span><span class="markup">&gt;</span><span class="text">
1632 </span><span class="markup">&lt;/</span><span class="end-tag">text</span><span class="markup">&gt;</span></div></div><span class="markup">&lt;/</span><span class="end-tag">template</span><span class="markup">&gt;</span></div><div class="element"><span class="markup">&lt;</span><span class="start-tag">template</span> <span class="attribute-name">match</span><span class="markup">=</span><span class="attribute-value">"*[@property='query']"</span> <span class="attribute-name">mode</span><span class="markup">=</span><span class="attribute-value">"invocab"</span><span class="markup">&gt;</span><div class="indent"><div class="element"><span class="markup">&lt;</span><span class="start-tag">text</span><span class="markup">&gt;</span><span class="text">Query:
1633 </span><span class="markup">&lt;/</span><span class="end-tag">text</span><span class="markup">&gt;</span></div><div class="element"><span class="markup">&lt;</span><span class="start-tag">value-of</span> <span class="attribute-name">select</span><span class="markup">=</span><span class="attribute-value">"text()"</span><span class="markup">/&gt;</span></div><div class="element"><span class="markup">&lt;</span><span class="start-tag">text</span><span class="markup">&gt;</span><span class="text">
1634 </span><span class="markup">&lt;/</span><span class="end-tag">text</span><span class="markup">&gt;</span></div></div><span class="markup">&lt;/</span><span class="end-tag">template</span><span class="markup">&gt;</span></div><div class="element"><span class="markup">&lt;</span><span class="start-tag">template</span> <span class="attribute-name">match</span><span class="markup">=</span><span class="attribute-value">"text()"</span> <span class="attribute-name">mode</span><span class="markup">=</span><span class="attribute-value">"invocab"</span><span class="markup">/&gt;</span></div><div class="element"><span class="markup">&lt;</span><span class="start-tag">template</span> <span class="attribute-name">match</span><span class="markup">=</span><span class="attribute-value">"text()"</span><span class="markup">/&gt;</span></div><div class="element"><span class="markup">&lt;</span><span class="start-tag">template</span> <span class="attribute-name">match</span><span class="markup">=</span><span class="attribute-value">"*[@vocab]"</span><span class="markup">&gt;</span><div class="indent"><div class="element"><span class="markup">&lt;</span><span class="start-tag">choose</span><span class="markup">&gt;</span><div class="indent"><div class="element"><span class="markup">&lt;</span><span class="start-tag">when</span> <span class="attribute-name">test</span><span class="markup">=</span><span class="attribute-value">"@vocab='ivo://ivoa.net/std/DALI-examples'"</span><span class="markup">&gt;</span><div class="indent"><div class="element"><span class="markup">&lt;</span><span class="start-tag">apply-templates</span> <span class="attribute-name">mode</span><span class="markup">=</span><span class="attribute-value">"invocab"</span><span class="markup">/&gt;</span></div></div><span class="markup">&lt;/</span><span class="end-tag">when</span><span class="markup">&gt;</span></div><div class="element"><span class="markup">&lt;</span><span class="start-tag">otherwise</span><span class="markup">&gt;</span><div class="indent"><div class="element"><span class="markup">&lt;</span><span class="start-tag">message</span> <span class="attribute-name">terminate</span><span class="markup">=</span><span class="attribute-value">"yes"</span><span class="markup">&gt;</span><div class="indent"><div class="element"><span class="markup">&lt;</span><span class="start-tag">text</span><span class="markup">&gt;</span><span class="text">Forbidden vocabulary encountered: </span><span class="markup">&lt;/</span><span class="end-tag">text</span><span class="markup">&gt;</span></div><div class="element"><span class="markup">&lt;</span><span class="start-tag">value-of</span> <span class="attribute-name">select</span><span class="markup">=</span><span class="attribute-value">"@vocab"</span><span class="markup">/&gt;</span></div></div><span class="markup">&lt;/</span><span class="end-tag">message</span><span class="markup">&gt;</span></div></div><span class="markup">&lt;/</span><span class="end-tag">otherwise</span><span class="markup">&gt;</span></div></div><span class="markup">&lt;/</span><span class="end-tag">choose</span><span class="markup">&gt;</span></div></div><span class="markup">&lt;/</span><span class="end-tag">template</span><span class="markup">&gt;</span></div></div><span class="markup">&lt;/</span><span class="end-tag">stylesheet</span><span class="markup">&gt;</span></div></h:div>
1635 </div> <!-- appB -->
1636
1637 </div> <!-- appendices -->
1638
1639 <div class="section-nonum"><h2><a id="references" shape="rect"><span class="secnum"/>References</a></h2>
1640 <?bibliography ivoadoc/refs ?><dl>
1641
1642 <dt><a name="std:UNICODE">[std:UNICODE] The Unicode Consortium.</a></dt> <dd>
1643 <a href="http://www.unicode.org/versions/Unicode6.1.0">The unicode standard,
1644 version 6.1 core specification</a>, 2012.
1645 </dd>
1646
1647 <dt><a name="std:TAPREGEXT">[std:TAPREGEXT] Markus Demleitner, Patrick Dowler,
1648 Ray Plante, Guy Rixon, and Mark Taylor.</a></dt> <dd>
1649 <a href="http://www.ivoa.net/Documents/TAPRegExt">TAPRegExt: a
1650 VOResource schema extension for describing TAP services, version 1.0</a>.
1651 IVOA Recommendation, August 2012.
1652 </dd>
1653
1654 <dt><a name="std:TAPREGEXT-20120827">[std:TAPREGEXT-20120827] Markus
1655 Demleitner, Patrick Dowler, Ray Plante, Guy Rixon, and Mark Taylor.</a></dt>
1656 <dd>
1657 <a href="http://www.ivoa.net/documents/TAPRegExt/20120827/index.html">TAPRegExt: a VOResource schema extension for describing TAP services,
1658 version 1.0, 2012-08-27</a>.
1659 IVOA Recommendation, August 2012.
1660 </dd>
1661
1662 <dt><a name="std:VOUNIT">[std:VOUNIT] Sebastien Derriere, Norman Gray, Mireille
1663 Louys, Jonathan McDowell, Francois Ochsenbein, Pedro Osuna, Bruno Rino, and
1664 Jesus Salgado, Sebastien Derriere, editor.</a></dt> <dd>
1665 <a href="http://www.ivoa.net/Documents/VOUnits/index.html">Units in the
1666 VO</a>.
1667 IVOA Proposed Recommendation, 2012.
1668 </dd>
1669
1670 <dt><a name="std:DALI">[std:DALI] Patrick Dowler, Markus Demleitner, Mark
1671 Taylor, and Doug Tody.</a></dt> <dd>
1672 <a href="http://www.ivoa.net/documents/DALI">Data access layer interface,
1673 version 1.0</a>.
1674 IVOA Recommendation, November 2013.
1675 </dd>
1676
1677 <dt><a name="std:TAP">[std:TAP] Patrick Dowler, Guy Rixon, and Doug
1678 Tody.</a></dt> <dd>
1679 <a href="http://www.ivoa.net/Documents/TAP">Table access protocol version
1680 1.0</a>.
1681 IVOA Recommendation, March 2010.
1682 </dd>
1683
1684 <dt><a name="std:TAP-20100327">[std:TAP-20100327] Patrick Dowler, Guy Rixon,
1685 and Doug Tody.</a></dt> <dd>
1686 <a href="http://www.ivoa.net/documents/TAP/20100327">Table access protocol
1687 version 1.0, 2010-03-27</a>.
1688 IVOA Recommendation, March 2010.
1689 </dd>
1690
1691 <dt><a name="std:HTTP">[std:HTTP] R. Fielding, J. Gettys, J. Mogul, H. Frystyk,
1692 L. Masinter, P. Leach, and T. Berners-Lee.</a></dt> <dd>
1693 <a href="http://www.w3.org/Protocols/rfc2616/rfc2616.html">Hypertext
1694 transfer protocol – HTTP/1.1</a>.
1695 rfc2616, June 1999.
1696 </dd>
1697
1698 <dt><a name="std:VOSI">[std:VOSI] Grid and Web Services Working Group,
1699 Matthew Graham and Guy Rixon, editors.</a></dt> <dd>
1700 <a href="http://www.ivoa.net/Documents/VOSI/index.html">IVOA support
1701 interfaces version 1.0</a>, 2011.
1702 </dd>
1703
1704 <dt><a name="std:UWS">[std:UWS] Paul Harrison and Guy Rixon.</a></dt> <dd>
1705 <a href="http://www.ivoa.net/Documents/UWS">Universal worker service
1706 pattern, version 1.0</a>.
1707 IVOA Recommendation, October 2010.
1708 </dd>
1709
1710 <dt><a name="IVOAWIKI">[IVOAWIKI] http://wiki.ivoa.net.</a></dt> <dd>
1711 <a href="http://wiki.ivoa.net/twiki/bin/view/IVOA/WebHome">IVOA wiki</a>.
1712 [Online].
1713 </dd>
1714
1715 <dt><a name="doc:Postgres92">[doc:Postgres92]
1716 http://www.postgresql.org/docs/9.2/static/index.html.</a></dt> <dd>
1717 <a href="http://www.postgresql.org/docs/9.2/static/index.html">PostgreSQL
1718 9.2.1 documentation</a>.
1719 [Online].
1720 </dd>
1721
1722 <dt><a name="svc:RDFaVal">[svc:RDFaVal]
1723 http://www.w3.org/2012/pyRdfa/Validator.html.</a></dt> <dd>
1724 <a href="http://www.w3.org/2012/pyRdfa/Validator.html">W3C RDFa
1725 validator</a>.
1726 [Online].
1727 </dd>
1728
1729 <dt><a name="std:iso8601">[std:iso8601] International Organization for
1730 Standardization).</a></dt> <dd>
1731 <a href="http://www.iso.org/iso/catalogue_detail?csnumber=40874">Data
1732 elements and interchange formats – information interchange – representation
1733 of dates and times</a>, 2004.
1734 </dd>
1735
1736 <dt><a name="std:DNS">[std:DNS] P. Mockapetris.</a></dt> <dd>
1737 <a href="http://www.ietf.org/rfc/rfc1034.txt">Domain names - concepts and
1738 facilities</a>.
1739 IETF RFC, November 1987.
1740 </dd>
1741
1742 <dt><a name="std:SQL1992">[std:SQL1992] International Standard
1743 Organization.</a></dt> <dd>
1744 The database language SQL.
1745 Technical Report, Document ISO/IEC9075:1992, 1992.
1746 </dd>
1747
1748 <dt><a name="std:ADQL">[std:ADQL] Iñaki Ortiz, Jeff Lusted, Pat Dowler,
1749 Alexander Szalay, Yuji Shirasaki, Maria A. Nieto-Santisteba, Masatoshi
1750 Ohishi, William O'Mullane, Pedro Osuna, the VOQL-TEG, and the VOQL
1751 Working Group, Pedro Osuna and Iñaki Ortiz, editors.</a></dt> <dd>
1752 <a href="http://www.ivoa.net/Documents/latest/ADQL.html">IVOA astronomical
1753 data query language</a>.
1754 IVOA Recommendation, 2008.
1755 </dd>
1756
1757 <dt><a name="std:ADQL-20081030">[std:ADQL-20081030] Iñaki Ortiz, Jeff
1758 Lusted, Pat Dowler, Alexander Szalay, Yuji Shirasaki, Maria A.
1759 Nieto-Santisteba, Masatoshi Ohishi, William O'Mullane, Pedro Osuna, the
1760 VOQL-TEG, and the VOQL Working Group, Pedro Osuna and Iñaki Ortiz,
1761 editors.</a></dt> <dd>
1762 <a href="http://www.ivoa.net/documents/cover/ADQL-20081030.html">IVOA
1763 astronomical data query language, version 2.0, 2008-10-30</a>.
1764 IVOA Recommendation, 2008.
1765 </dd>
1766
1767 <dt><a name="std:VODS11">[std:VODS11] Raymond Plante, Aurélien Stébé, Kevin
1768 Benson, Patrick Dowler, Matthew Graham, Gretchen Greene, Paul Harrison,
1769 Gerard Lemson, Tony Linde, and Guy Rixon.</a></dt> <dd>
1770 <a href="http://www.ivoa.net/Documents/VODataService/">VODataService: a
1771 VOResource schema extension for describing collections and services version
1772 1.1</a>.
1773 IVOA Recommendation, December 2010.
1774 </dd>
1775
1776 </dl>
1777
1778 </div> <!-- references -->
1779
1780 </div> <!-- body -->
1781 </body>
1782 </html><!-- vim: tw=72
1783 -->

Properties

Name Value
svn:mime-type application/xhtml+xml

msdemlei@ari.uni-heidelberg.de
ViewVC Help
Powered by ViewVC 1.1.26