/[volute]/trunk/projects/dal/TAP/TAP.tex
ViewVC logotype

Diff of /trunk/projects/dal/TAP/TAP.tex

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 2915 by pdowler.cadc@gmail.com, Thu Dec 4 22:05:11 2014 UTC revision 2916 by pdowler.cadc@gmail.com, Wed Apr 22 16:09:54 2015 UTC
# Line 23  Line 23 
23  Access is provided for both database and table metadata as well as for actual  Access is provided for both database and table metadata as well as for actual
24  table data. This version of the protocol includes support for multiple query  table data. This version of the protocol includes support for multiple query
25  languages, including queries specified using the Astronomical Data Query  languages, including queries specified using the Astronomical Data Query
26  Language (ADQL [1]) and the Parameterised Query Language (PQL, under  Language (ADQL [1]) within an integrated interface. It also includes support
27  development) within an integrated interface. It also includes support for both  for both synchronous and asynchronous queries. Special support is provided for
28  synchronous and asynchronous queries. Special support is provided for spatially  spatially indexed queries using the spatial extensions in ADQL. A multi-position
29  indexed queries using the spatial extensions in ADQL. A multi-position query  query capability permits queries against an arbitrarily large list of
30  capability permits queries against an arbitrarily large list of astronomical  astronomical targets, providing a simple spatial cross-matching capability.
31  targets, providing a simple spatial cross-matching capability. More  More sophisticated distributed cross-matching capabilities are possible by
 sophisticated distributed cross-matching capabilities are possible by  
32  orchestrating a distributed query across multiple TAP services.    orchestrating a distributed query across multiple TAP services.  
33  \end{abstract}  \end{abstract}
34    
# Line 63  Line 62 
62  return the query response as another table, in accord with the relational model.  return the query response as another table, in accord with the relational model.
63   Queries may be submitted using various query languages and may execute   Queries may be submitted using various query languages and may execute
64  synchronously or asynchronously. Support for the Astronomical Data Query  synchronously or asynchronously. Support for the Astronomical Data Query
65  Language (ADQL, [1]) is mandatory; support for other query languages such as  Language (ADQL, [1]) is mandatory; support for other query languages is allowed
66  Parameterised Query Language (PQL, under development) or native SQL is optional.  and optional.
67    
68  The result of a TAP query is another table, normally returned as a VOTable.  The result of a TAP query is another table, normally returned as a VOTable.
69  Support for VOTable output is mandatory; all other formats are optional.  Support for VOTable output is mandatory; all other formats are optional.
# Line 80  Line 79 
79  cross match are also possible, but require combining the results of multiple TAP  cross match are also possible, but require combining the results of multiple TAP
80  services.  services.
81    
82  \subsection{Query Types}  \subsection{Role within the VO Architecture}
 TAP services support three kinds of queries: data queries, metadata queries, and  
 Virtual Observatory Support Interface (VOSI [6]) queries.  
   
 \subsubsection{Data Queries}  
 Data queries apply to the astronomical content served by a TAP service. This is  
 the reason for providing a TAP service. All the other kinds of query support the  
 ability to make data queries. Data queries may be specified in any query  
 language supported by the service.  
   
 \subsubsection{Metadata Queries}  
 Metadata queries work like data queries, using the same query languages, but  
 they are applied to standardized tables that are a subset of, and patterned  
 after, information schema in RDBMS; the content of these tables explains the  
 data model of a particular TAP service. Metadata queries allow a client to  
 discover the names of tables and columns to be used in data queries.  
   
 \subsubsection{VOSI}  
 Metadata queries work like data queries, using the same query languages, but  
 they are applied to standardized tables that are a subset of, and patterned  
 after, information schema in RDBMS; the content of these tables explains the  
 data model of a particular TAP service. Metadata queries allow a client to  
 discover the names of tables and columns to be used in data queries.  
   
 \subsection{Query Languages}  
 TAP supports the use of multiple query languages, some of which are described  
 here.  
83    
84  \subsubsection{ADQL Queries}  NOTE: not in TAP-1.0
85  Support for ADQL queries is mandatory. ADQL can be used to specify queries  that  
86  access one or more tables provided by the TAP service, including the standard  \begin{figure}
87  metadata tables. In general, the client must access table metadata in order to  \centering
88  discover the names of tables and columns and then formulate queries. ADQL  
89  queries provide a direct (low-level) access to the tables; a query will be  % Get the architecture diagram from the TCG chair
90  written for a specific TAP service and will not be usable with other services  % http://wiki.ivoa.net/twiki/bin/view/IVOA/IvoaTCG
91  unless the query refers only to common tables and columns. It is also possible  % If they give you a PDF, for now dumb it down to a png by
92  that the service registration (in an IVOA Registry)  may include sufficient  % convert -antialias -density 72x72 archdiag.pdf archdiag.png
93  table metadata to enable queries to be written directly.  % Oh -- Notes don't need this; you'd have to remove archdiag.png
94    % from FIGURES in the Makefile, too.
95  Details of the ADQL language may be found in [1].  
96    \includegraphics[width=0.9\textwidth]{archdiag.png}
97  \subsubsection{PQL}  \caption{Architecture diagram for this document}
98  Support for PQL is optional. PQL can be used to formulate queries that access a  \label{fig:archdiag}
99  single table provided by the TAP service, including the standard set of metadata  \end{figure}
100  tables. PQL can also be used in some cases without first querying the metadata  
101  tables by using the PQL parameters which carry sufficient meaning to enable the  Fig.~\ref{fig:archdiag} shows the role this document plays within the
102  service to decide which tables and columns to use (e.g. POS, SIZE, REGION, BAND,  IVOA architecture \citep{note:VOARCH}.
 TIME).  
103    
104  Details of the PQL language (parameters) are not part of the TAP specification.  
105    \subsection{Motivating Use Cases}
106    Below are some of the more common use cases that have motivated the development
107    of the TAP specification. While this is not complete, it helps to understand the
108    problem area covered by this specification.
109    
110    \subsubsection{Discover Metadata}
111    Since content in relational databases is often custom and project-specific,
112    users of a TAP service must be able to discover the names of tables and
113    columns, datatypes, units, and other information necessary to construct
114    meaningful correct queries.
115    
116    \subsubsection{Query Custom Tables}
117    A large amount of astronomical data and metadata is stored in tables in
118    relational databases. Historically, users could query these tables through
119    custom user interfaces (usually web page forms), but such approaches could not
120    provide support for truly ad-hoc querying. A TAP service should enable users to
121    discover and query custom tables with a flexible and expressive input that
122    supports ad-hoc querying: selecting output, filtering the result, joining
123    multiple tables, computing aggregate quantities, etc.
124    
125    \subsubsection{Query Standard Tables}
126    A TAP service should enable users to query externally defined standard tables
127    in a uniform way such that the same web service request can be sent to multiple
128    services. Services must be able to declare their support for standard tables in
129    the service metadata.
130    
131    \subsubsection{Query Standard Data Models}
132    A TAP service should enable users to query (parts of) externally defined data
133    models that are (partially or fully) implemented by the service. Services must
134    be able to declare their support for data models as well as the way that model
135    elements are mapped to tables and columns.
136    
137    \subsubsection{ADQL Queries}
138    The Astronomical Data Query Language (ADQL) [std:ADQL] is the standard
139    query language for the IVOA. Support for ADQL queries is mandatory. ADQL can be
140    used to specify queries  that access one or more tables provided by the TAP
141    service, including the standard metadata tables. In general, the client must
142    access table metadata in order to discover the names of tables and columns and
143    then formulate queries. ADQL queries provide a direct (low-level) access to the
144    tables; a query will be written for a specific TAP service and will not be
145    usable with other services unless the query refers only to common tables and
146    columns. It is also possible that the service registration (in an IVOA Registry)
147    may include sufficient table metadata to enable queries to be written directly.
148    
149  \subsubsection{Other Query Languages}  \subsubsection{Other Query Languages}
150  A TAP service may also support use of other query languages, including  A TAP service must be able to support use of other query languages, such
151  pass-through of native SQL directly to an underlying DBMS, by describing such  pass-through of native SQL directly to an underlying DBMS or simple key-vale
152  capabilities in the service metadata and allowing custom values of the service  (parameter-based) constraints. The service interface must allow for
153  parameters. This mechanism allows future developments within the VOQL Working  this and the service capabilities must be able to describe it. This mechanism
154  Group and outside the IVOA to be used without revising the TAP specification.  also allows future developments within and outside the IVOA to be used without
155    revising the TAP specification.
 \subsection{Query Execution}  
 The TAP service specification defines both synchronous and asynchronous query  
 execution. Users select synchronous or asynchronous execution by chosing the  
 appropriate resource below the base URL for the service (see 2.2 ). A query is  
 synchronous if the results of the query are delivered in the HTTP response to  
 the request that originally posed the query. If the service returns an immediate  
 HTTP-response upon accepting a query and the client later obtains the results of  
 the query in response to a separate HTTP request, then we say the request is  
 asynchronous.  
156    
157  \subsubsection{Asynchronous Queries}  \subsubsection{Asynchronous Queries}
158  Asynchronous query support is mandatory. Asynchronous queries require that  Asynchronous queries allow for long running queries to complete without
159  client and server share knowledge of the state of the query during its execution  the client maintaining a connection to the service. Results are stored by
160  and between HTTP exchanges.  They are an example of stateful interactions.  In  the service for later retrieval by the client. Asynchronous query
161  TAP, the mechanism by which the clients and services share the state of  execution is generally more robust and not susceptible to time-outs or other
162  transactions is based on the Universal Worker Service (UWS) pattern [3].  transient failures. They are especially suited to queries that run for a long
163    time before producing output (e.g. queries that compute or aggregate values).
164    
165  \subsubsection{Synchronous Queries}  \subsubsection{Synchronous Queries}
166  Synchronous query support is mandatory. Synchronous queries execute immediately  Synchronous queries execute immediately  and the client must wait for the query
167  and the client must wait for the query to finish.  If the HTTP request times out  to finish. Synchronous query execution is generally simpler and provides a
168  or the client otherwise loses the connection to the service before receiving the  faster (low latency) response and should be adequate when the query will execute
169  response, then the query fails.  and start returning results quickly. Even with large query results, synchronous
170    queries are a good approach as long as the service can stream the output
171  Synchronous query execution is adequate when the query will execute quickly and  and consume modest internal resources.
172  with a small number of results, or when they can at least start returning  
 results quickly. They are generally simple to implement using standard web  
 technologies and easy to use from a browser or scripting environment. However,  
 synchronous requests are generally not sufficient and are likely to fail for  
 queries that take a long time to execute, especially before returning any  
 results.  
173    
174  \subsection{Interface Overview}  \subsection{Interface Overview -- move to examples section?}
175  Table Access Protocol (TAP) is implemented over the HTTP protocol using standard  Table Access Protocol (TAP) is implemented over the HTTP protocol using standard
176  HTTP GET and POST requests and conventions. A TAP request specifies one or more  HTTP GET and POST requests and conventions. A TAP request specifies one or more
177  parameter key/value pairs; both keys and values are strings. The keys used are  parameter key/value pairs; both keys and values are strings. The keys used are
# Line 187  Line 189 
189  QUERY=SELECT * FROM magnitudes as m where m.r>=10 and m.r<=16  QUERY=SELECT * FROM magnitudes as m where m.r>=10 and m.r<=16
190  \end{verbatim}  \end{verbatim}
191    
 NOTE: equivalent PQL that was in TAP-1.0 doc removed  
   
192  Synchronous queries return the table of results in the HTTP response to the  Synchronous queries return the table of results in the HTTP response to the
193  initial request. In the examples above, the output format defaults to VOTable;  initial request. In the examples above, the output format defaults to VOTable;
194  the FORMAT parameter could be added to select a different format.  the FORMAT parameter could be added to select a different format.
# Line 203  Line 203 
203  QUERY=SELECT * FROM magnitudes AS m WHERE m.r>=10 AND m.r<=16  QUERY=SELECT * FROM magnitudes AS m WHERE m.r>=10 AND m.r<=16
204  \end{verbatim}  \end{verbatim}
205    
206  NOTE: equivalent PQL that was in TAP-1.0 doc removed  The service's response to these requests is a URL representing the query's
207    state and progress and where the state may be monitored and controlled. The
208  The service's response to these requests is a URL representing the query's state  query
 and progress and where the state may be monitored and controlled. The query  
209  result or an error document can then be retrieved from a URL associated with the  result or an error document can then be retrieved from a URL associated with the
210  job. This is an application of the UWS pattern. The query is then executed  job. This is an application of the UWS pattern. The query is then executed
211  with a separate request to run the job URL:  with a separate request to run the job URL:
# Line 216  Line 215 
215  PHASE=RUN  PHASE=RUN
216  \end{verbatim}  \end{verbatim}
217    
218    The state of the job can be retrieved from the phase resource:
219    
220    \begin{verbatim}
221    HTTP GET http://example.com/tap/async/<jobid>/phase
222    \end{verbatim}
223    
224    The client may have to check the phase multiple times until the job
225    finishes. Once the returned value is COMPLETED, the results can be obtained
226    from the results resource:
227    
228    \begin{verbatim}
229    HTTP GET http://example.com/tap/async/<jobid>/results/result
230    \end{verbatim}
231    
232  In addition to the sync and async resources for query execution, a TAP service  In addition to the sync and async resources for query execution, a TAP service
233  also has metadata resources defined by the VOSI standard. The availability of a  also has metadata resources defined by the VOSI standard. The availability of a
234  service can be monitored by accessing:  service can be monitored by accessing:
# Line 224  Line 237 
237  HTTP GET http://example.com/tap/availability  HTTP GET http://example.com/tap/availability
238  \end{verbatim}  \end{verbatim}
239    
 See 2.2.3 for details of the availability resource.  
   
240  The complete table metadata can be obtained:  The complete table metadata can be obtained:
241    
242  \begin{verbatim}  \begin{verbatim}
243  HTTP GET http://example.com/tap/tables  HTTP GET http://example.com/tap/tables
244  \end{verbatim}  \end{verbatim}
245    
 See 2.2.5 for details of the table metadata resource.  
   
246  The capabilities can be obtained by:  The capabilities can be obtained by:
247    
248  \begin{verbatim}  \begin{verbatim}
# Line 248  Line 257 
257  \end{verbatim}  \end{verbatim}
258    
259  This output lists support for optional TAP functionality and additional  This output lists support for optional TAP functionality and additional
260  implemented interfaces. See 2.2.4 for details.  implemented interfaces.
   
261    
262  \subsection{Role within the VO Architecture}  \section{Resources}
   
 NOTE: not in TAP-1.0  
263    
264  \begin{figure}  An implementation of a TAP service provides the following RESTful resources
265  \centering  under the base URL.
   
 % Get the architecture diagram from the TCG chair  
 % http://wiki.ivoa.net/twiki/bin/view/IVOA/IvoaTCG  
 % If they give you a PDF, for now dumb it down to a png by  
 % convert -antialias -density 72x72 archdiag.pdf archdiag.png  
 % Oh -- Notes don't need this; you'd have to remove archdiag.png  
 % from FIGURES in the Makefile, too.  
   
 \includegraphics[width=0.9\textwidth]{archdiag.png}  
 \caption{Architecture diagram for this document}  
 \label{fig:archdiag}  
 \end{figure}  
   
 Fig.~\ref{fig:archdiag} shows the role this document plays within the  
 IVOA architecture \citep{note:VOARCH}.  
   
   
   
 \section{Requirements for a TAP Service}  
   
 NOTE: pre-amble about must, should, and may that was here in 1.0 removed since  
 it is alteady included above  
   
 The TAP standard is identified using standardID="ivo://ivoa.net/std/TAP". This  
 document specified version 1.0 of the standard.  
   
 \subsection{Feature Overview}  
 An implementation of a TAP service provides features as follows.  
266    
267  \begin{tabular}{l l l l l}  \begin{tabular}{l l l l l}
268  synchronous query execution & /sync & must & & \\  resource type & resource name & required \\
269  asynchronous query execution & /async & must & & \\  {sync} & /sync & must (anonymous) & \\
270  VOSI-availability & /availability & should & & \\  {async} & /async & must (anonymous) & \\
271  VOSI-capabilities & /capabilities & must & & \\  {sync} & service specific & may (alternate authentication method) & \\
272  VOSI-tables & /tables & should & REQUEST=getCapabilities & must \\  {async} & service specific & may (alternate authentication method) & \\
273  ADQL queries & & & REQUEST=doQuery LANG=ADQL & must \\  VOSI-availability & /availability & should & \\
274  PQL queries & & & REQUEST=doQuery LANG=PQL & may \\  VOSI-capabilities & /capabilities & must & \\
275  other query languages & & & REQUEST=doQuery LANG=<other> & may \\  VOSI-tables & /tables & should & \\
276  VOTable output & & & FORMAT & must \\  DALI-examples & /examples & should & \\
 other formats & & & FORMAT & should \\  
 limiting output & & & MAXREC & must \\  
 logging & & & RUNID & should \\  
277  \end{tabular}  \end{tabular}
278    
279  The resources and parameters are described in detail below. The description of  At least one set of {sync} and {async} resources must be named /sync and
280  these resources and parameters spell out how the requirements here are to be  /async respectively for backwards compatibility with TAP-1.0 (which required
281  implemented.  these names. These resources must be used for anonymous query execution. Other
282    {sync} and {async} resources may have service specific names, but all resources
283  TAP service registration in the IVOA resource-registry is specified in section  listed above must be siblings so that a client with one such URL can find the
284  3.  VOSI-capabilities URL and thus discover other available resources.
285    
286  \subsection{Resources}  A TAP service must be represented as a set of sibling web resources each
 A TAP service must be represented as a tree structure of web resources each  
287  addressable via a URL in the http scheme, or the https scheme, or both.  addressable via a URL in the http scheme, or the https scheme, or both.
288    
289  The web resource at the root of the tree must represent the service as a whole.  The web resource at the root of the tree must represent the service as a whole.
# Line 319  Line 293 
293  an HTML page describing the scientific usage and content of the service. TAP  an HTML page describing the scientific usage and content of the service. TAP
294  clients must not depend on a specific representation of the root web-resource.  clients must not depend on a specific representation of the root web-resource.
295    
296  \subsubsection{/sync}  \subsection{\{sync\}}
297  A TAP service must provide a web resource with relative URL /sync that is a  A TAP service must provide a web resource with relative URL /sync that is a
298  direct child of the root web resource. This web resource represents the results  direct child of the root web resource. This web resource represents the results
299  of synchronous requests. The exact form of the query, and hence the  of synchronous requests. The exact form of the query, and hence the
# Line 338  Line 312 
312  which require an up-to-date representation of volatile data or metadata must use  which require an up-to-date representation of volatile data or metadata must use
313  HTTP POST.  HTTP POST.
314    
315  \subsubsection{/async}  \subsection{\{async\}}
316  A TAP service must provide a web resource with relative URL /async that is a  A TAP service must provide a web resource with relative URL /async that is a
317  direct child of the root web resource. This web resource represents controls for  direct child of the root web resource. This web resource represents controls for
318  asynchronous queries. Specifically, the web resource must represent the job-list  asynchronous queries. Specifically, the web resource must represent the job-list
# Line 405  Line 379 
379  data rows. Details on interacting with these resources are specified in the UWS  data rows. Details on interacting with these resources are specified in the UWS
380  standard; for examples specific to TAP see Section 5 below.  standard; for examples specific to TAP see Section 5 below.
381    
382  \subsubsection{/availability}  \subsection{/availability}
383  The VOSI availability metadata should be accessible from a web resource with  The VOSI availability metadata should be accessible from a web resource with
384  relative URL /availability that is a direct child of the root web resource. If  relative URL /availability that is a direct child of the root web resource. If
385  implemented, the /availability resource must be accessible via the http GET  implemented, the /availability resource must be accessible via the http GET
# Line 414  Line 388 
388  Services which do not implement the /availability resource must respond with an  Services which do not implement the /availability resource must respond with an
389  HTTP response code of 404 when this resource is accessed.  HTTP response code of 404 when this resource is accessed.
390    
391  \subsubsection{/capabilities}  \subsection{/capabilities}
392    The TAP-1.0 standard is identified using
393    \begin{verbatim}
394    ivo://ivoa.net/std/TAP
395    \end{verbatim}
396    
397    For TAP-1.1 we define new standard identifiers for each of the
398    features. Asynchronous query execution is described by standardID:
399    
400    \begin{verbatim}
401    ivo://ivoa.net/std/TAP#async-1.1
402    \end{verbatim}
403    
404    Synchronous query execution is described by standardID:
405    
406    \begin{verbatim}
407    standardID="ivo://ivoa.net/std/TAP#sync-1.1
408    \end{verbatim}
409    
410    In TAP-1.0 the base URL was described with a single standard identifier; in
411    TAP-1.1 and beyond, individual resources are described with their on
412    standardID. This allows service providers to describe multiple resources that
413    deliver the specified feature (e.g with different authentication methods) in
414    the VOSI-capabilities resource.
415    
416    The VOSI standard specifies that the capability metadata is encoded as an XML
417    document which lists each of the service's capabilities as a <capability>
418    element. The type of this element (which defines the contents) is
419    {http://www.ivoa.net/xml/VOResource/v1.0}Capability from the VOResource XML
420    standard [8].
421    
422    In addition, the capabilities output must also comply with the following    
423    requirements:
424    
425    * the returned document must include <capability> elements
426    that describes the service's support for the TAP protocol using the TAP and
427    VOSI standardID values
428    
429    * this capability element must include at least one <interface> element
430    with its "role" attribute set to "std",  
431    
432    Note: VO registries recognize a service's support for a standard protocol
433    through this capability description. In particular, a different standard
434    Capability sub-type is used for each standard protocol to provide capability
435    metadata that is specific to that protocol. At the time of this writing, a
436    Capability sub-type for TAP has not yet been defined. Thus for compliance with
437    this standard, any legal Capability description that meets the above
438    restrictions is sufficient. However, once a VOResource extension for TAP is
439    standardized, it is strongly recommended that TAP services emit its
440    capabilities using that the Capability sub-type specialized for TAP.
441    
442    For example, the returned capabilities document for a service supporting  TAP
443    might look as follows:
444    
445    \begin{verbatim}
446    <?xml version="1.0" encoding="UTF-8"?>
447    
448    <vosi:capabilities xmlns=""
449       xmlns:vosi="http://www.ivoa.net/xml/VOSI/v1.0"
450       xmlns:vs="http://www.ivoa.net/xml/VODataService/v1.0"
451       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
452       xsi:schemaLocation="http://www.ivoa.net/xml/VOSI/v1.0
453                           http://www.ivoa.net/xml/VOSI/v1.0
454                 http://www.ivoa.net/xml/VODataService/v1.0
455                 http://www.ivoa.net/xml/VODataService/v1.0">
456    
457      <vosi:capability standardID="ivo://ivoa.net/std/TAP#async-1.1">
458        <interface xsi:type="vs:ParamHTTP" role="std">
459          <accessURL use="base"> http://myarchive.net/myTAP/async </accessURL>
460        </interface>
461      </vosi:capability>
462    
463      <vosi:capability standardID="ivo://ivoa.net/std/TAP#sync-1.1">
464        <interface xsi:type="vs:ParamHTTP" role="std">
465          <accessURL use="base"> http://myarchive.net/myTAP/sync </accessURL>
466        </interface>
467      </vosi:capability>
468    
469      <vosi:capability standardID="ivo://ivoa.net/std/VOSI#capabilities">
470        <interface xsi:type="vs:ParamHTTP">
471          <accessURL use="full">
472            http://myarchive.net/myTAP/capabilities </accessURL>
473        </interface>
474      </vosi:capability>
475    
476      <vosi:capability standardID="ivo://ivoa.net/std/VOSI#availability">
477        <interface xsi:type="vs:ParamHTTP">
478          <accessURL use="full">
479            http://myarchive.net/myTAP/availability
480          </accessURL>
481        </interface>
482      </vosi:capability>
483    
484      <vosi:capability standardID="ivo://ivoa.net/std/VOSI#tables">
485        <interface xsi:type="vs:ParamHTTP">
486          <accessURL use="full">
487            http://myarchive.net/myTAP/tables </accessURL>
488        </interface>
489      </vosi:capability>
490    
491    </vosi:capabilities>
492    \end{verbatim}
493    
494  The service capabilities must be accessible from a web resource with relative  The service capabilities must be accessible from a web resource with relative
495  URL /capabilities that is a direct child of the root web resource. The  URL /capabilities that is a direct child of the root web resource. The
496  /capabilities resource must be accessible via the http GET method. The content  /capabilities resource must be accessible via the http GET method. The content
497  is described by [8].  is described by [8].
498    
499  \subsubsection{/tables}  \subsection{/tables}
500  The table metadata should be accessible from a web resource with relative URL  The table metadata should be accessible from a web resource with relative URL
501  /tables that is a direct child of the root web resource. The /tables resource  /tables that is a direct child of the root web resource. The /tables resource
502  must be accessible via the http GET method.  The content is described by [7] and  must be accessible via the http GET method. The content is described by [7] and
503  is equivalent to the metadata from the TAP\underline{' '}SCHEMA described in 2.6  is equivalent to the metadata from the TAP\underline{' '}SCHEMA described in
504  .  XREF.
505    
506  Services which do not implement the /tables resource must respond with an HTTP  Services which do not implement the /tables resource must respond with an HTTP
507  response code of 404 when this resource is accessed.  response code of 404 when this resource is accessed.
508    
509  \subsection{Parameters}  \subsection{/examples}
510  The /sync and /async web-resources must accept the parameters listed in the  A GET from this endpoint MUST yield a document with a MIME type of either
511  following sub-sections. In a synchronous request, the parameters select the  application/xhtml+xml or text/html. A service that does not provide examples
512    MUST return a 404 HTTP status on accessing this resource.
513    
514    If present, the endpoint must be represented in a capability in the TAP
515    service's registry record. The capability's standardID is defined by
516    [std:DALI]. A capability element could hence look like this:
517    
518    \begin{verbatim}
519       <capability standardID="ivo://ivoa.net/std/DALI#examples">
520         <interface xsi:type="vr:WebBrowser">
521           <accessURL use="full">http://myarchive.net/myTAP/examples</accessURL>
522         </interface>
523       </capability>
524    \end{verbatim}
525    
526    TAP defines two additional properties vocabulary:
527    
528    * query -- each example MUST have a unique child element with simple text
529    content having a property attribute valued query. It contains the query itself,
530    preferably with extra whitespace for easy human consumption and editing. This
531    will usually be a HTML pre element.
532        
533    * table -- examples MAY also have descendants with property attributes having
534    the value table. These must have pure text content and contain fully qualified
535    table names to which the query is somehow "pertaining". Suitable HTML elements
536    holding these include span, or a (which would allow linking to further
537    information on the table).
538    
539    When using elements with src or href attributes to carry the property
540    attributes, note that the element content must be repeated in a content
541    attribute, as otherwise RDFa clients would interpret the embedded link rather
542    than the element content as the object in the triple.
543    
544    TODO: add example(s) here
545    
546    \subsection{Parameters for \{async\} and \{sync\}}
547    The \{async\} and \{sync\} web-resources must accept the parameters listed in
548    the following sub-sections. In a synchronous request, the parameters select the
549  representation returned in the response message. In an asynchronous request, the  representation returned in the response message. In an asynchronous request, the
550  parameters select the representation of the eventual query result rather than  parameters select the representation of the eventual query result rather than
551  the response to the initial request.  the response to the initial request.
# Line 449  Line 562 
562  carries  LANG=ADQL then the SELECT parameter (from PQL) is spurious. If a  carries  LANG=ADQL then the SELECT parameter (from PQL) is spurious. If a
563  service receives a spurious parameter in an otherwise correct request, then the  service receives a spurious parameter in an otherwise correct request, then the
564  service must ignore the spurious parameter, must respond to the request normally  service must ignore the spurious parameter, must respond to the request normally
565  and must not report errors concerning the  spurious parameter.  and must not report errors concerning the spurious parameter.
566    
567  \subsubsection{REQUEST}  \subsubsection{REQUEST - remove? }
568  This parameter distinguishes current service operations, makes it possible to  This parameter distinguishes current service operations, makes it possible to
569  extend the service specification (with additional or custom operations), and  extend the service specification (with additional or custom operations), and
570  specifies how other parameters should be interpreted. If a TAP service attempts  specifies how other parameters should be interpreted. If a TAP service attempts
# Line 465  Line 578 
578    
579  getCapabilities: return VOSI-capabilities metadata  getCapabilities: return VOSI-capabilities metadata
580    
581  All requests to execute (/async or /sync) a query using a query language must  All requests to execute a query using a query language must
582  include REQUEST=doQuery and must include the LANG parameter. For other values of  include REQUEST=doQuery and must include the LANG parameter. For other values of
583  REQUEST, additional parameters may or may not be required. The  REQUEST, additional parameters may or may not be required. The
584  REQUEST=getCapabilities service operation must be supported for synchronous  REQUEST=getCapabilities service operation must be supported for synchronous
# Line 480  Line 593 
593  to the created job resource, in one or more separate HTTP requests. The  to the created job resource, in one or more separate HTTP requests. The
594  parameter names remain the same in both cases.  parameter names remain the same in both cases.
595    
 \subsubsection{VERSION}  
 The VERSION parameter specifies the TAP protocol version number. The format of  
 the version number, and version negotiation, are described in section 2.9.2 .  
   
 A TAP service must support the VERSION parameter. This specification is for TAP  
 1.0; the client would specify VERSION=1.0 if the request is made using the  
 protocol described here.  
   
596  \subsubsection{LANG}  \subsubsection{LANG}
597  The LANG parameter specifies the query language. The service must support LANG  The LANG parameter specifies the query language. The service must support LANG
598  and the client must provide a value with REQUEST=doQuery. The only standard  and the client must provide a value with REQUEST=doQuery. The only standard
599  values for the LANG parameter are ADQL (a required language) and PQL (reserved  values for the LANG parameter is ADQL (a required language). Support for other
 value for an optional language which is under development). Support for other  
600  languages and the LANG value to use with them is described in the service  languages and the LANG value to use with them is described in the service
601  capabilities.  capabilities.
602    
# Line 528  Line 632 
632  sensitive except for character  literals; schema, table, and column names,  sensitive except for character  literals; schema, table, and column names,
633  function names, and other ADQL keywords are not case sensitive.  function names, and other ADQL keywords are not case sensitive.
634    
635  Within the ADQL query, the service must support the use of timestamp values in  Within the ADQL query, the service must support the use of timestamp values as
636  ISO8601 format, specifically yyyy-MM-dd['T'HH:mm:ss[.SSS]], where square  described in [std:DALI].
 brackets denote optional parts and the 'T' denotes a single character separator  
 (T) between the date and time parts.  
637    
638  If the tables that are queried through a service contain columns with spatial  If the tables that are queried through a service contain columns with spatial
639  coordinates and the service supports spatial querying via the ADQL “region”  coordinates and the service supports spatial querying via the ADQL “region”
# Line 550  Line 652 
652  be transformed to ICRS; it simply tells the service to treat the values  as  be transformed to ICRS; it simply tells the service to treat the values  as
653  being expressed in that coordinate system.  being expressed in that coordinate system.
654    
655  \subsubsection{Parameters for PQL}  \subsubsection{FORMAT and RESPONSEFORMAT}
656  A number of parameters will be defined by the PQL standard for use in parametric  The RESPONSEFORMAT parameter is fully described in [std:DALI]. For backwards
657  queries. All of the parameters for PQL are are used unchanged in TAP.  compatibility, TAP-1.1 must also accept the FORMAT parameter as equivalent to
658    RESPONSEFORMAT.
 Within the PQL query, the service must support the use of timestamp values in  
 ISO8601 format (see 2.3.4 ).  
   
 If the table that is queried contains columns with spatial coordinates and the  
 service provider wants to enable the caller to perform spatial queries, the  
 service must support the PQL spatial constraint parameters (POS,SIZE and  
 REGION). If a service supports the REGION parameter, it  must support region  
 encoding in STC-S as decribed in section 6 ; the extent of STC-S support within  
 the REGION function is left up to the implementation. Coordinate system  
 qualifiers must use values from from STC-S as described in section 6 .  
   
 PQL defines symbolic values (@something). In TAP these can be used to refer to    
 an uploaded table (see 2.5 ) with parameters that support a table reference.  
 When used in this way, the uploaded table must be treated as if in the  
 TAP\underline{' '}UPLOAD schema (e.g. @TAP\underline{' '}UPLOAD.mytable).  
 Details on how to use table references in PQL will be described in the PQL  
 specification.  
   
 \subsubsection{FORMAT}  
 The FORMAT parameter indicates the client's desired format for the table of  
 results of a query. Its value should be a MIME type for tabular data or one of  
 the following shorthand forms:  
   
 TODO: add table here  
   
 Both MIME types and the shorthand forms are insensitive to case. If the FORMAT  
 parameter is omitted, the default format is VOTable.  
   
 A TAP service must support VOTable as an output format, should support CSV and  
 TSV output and may support other formats. A TAP service must accept a FORMAT  
 parameter indicating a format that the service supports and should reject  
 queries where the FORMAT parameter specifies a format not supported by the  
 service implementation.  
659    
660  \subsubsection{MAXREC}  \subsubsection{MAXREC}
661  The service must accept a MAXREC parameter specifying the maximum number of  The MAXREC parameter and its effect on the query result is fully described in
662  table records (rows) to be returned. If MAXREC is not specified in a query, the  [std:DALI]. If the result set is truncated in this fashion, it must include an
663  service may apply a default value or may set no limit. If the result set for a  overflow indicator as specified in section XREF.
664  query exceeds this value, the service must only return the requested number of  
665  rows. If the result set is truncated in this fashion, it must include an  For the special value of MAXREC=0, the service is not required to execute the
666  overflow indicator as specified in section 2.7.4 .  query; a successful  MAXREC=0 request does not necessarily mean that the query
667    is valid and the overflow indicator does not necessarily mean that there is at
668  The service must support the special value of MAXREC=0. This value indicates  least one row satisfying the query. The service may perform validation and may
669  that, in the event of an otherwise valid request, a valid output table be  try to execute the query, in which case a MAXREC=0 request can fail. A query
670  returned containing metadata, no table data rows, and an overflow indicator as  with MAXREC=0 can be used with a simple query (e.g. SELECT * FROM  
 specified in section 2.7.4 .  The service is not required to execute the query;  
 a successful  MAXREC=0 request does not necessarily mean that the query is valid  
 and the overflow indicator does not necessarily mean that there is at least one  
 row satisfying the query. The service may perform validation and may try to  
 execute the query, in which case a MAXREC=0 request can fail.  
   
 A query with MAXREC=0 can be used with a simple query (e.g. SELECT * FROM    
671  some\underline{' '}table) to extract and examine the VOTable metadata (assuming  some\underline{' '}table) to extract and examine the VOTable metadata (assuming
672  FORMAT=votable). Note: in this version of TAP, this is the only mechanism to  FORMAT=votable). Note: in this version of TAP, this is the only mechanism to
673  learn some of the detailed metadata, such as coordinate systems used.  learn some of the detailed metadata, such as coordinate systems used.
674    
675  \subsubsection{RUNID}  \subsubsection{RUNID}
676  The service should implement the RUNID parameter, used to tag service requests  The RUNID parameter is fully described in [std:DALI].
 with the job ID of a larger job of which the request may be part. The RUNID  
 parameter is defined in [3] for /async requests; services should also implement  
 it for /sync requests.  
   
 For example, if a cross match portal issues multiple requests to remote TAP  
 services to carry out a cross-match operation, all would receive the same RUNID,  
 and the service logs could later be analyzed to reconstruct the service  
 operations initiated in response to the job.  
677    
678  The service should ensure that RUNID is preserved in any service logs and    \subsubsection{VERSION}
679  should pass on the RUNID value in any calls to other services.  The VERSION parameter is fully described in {std:DALI].
680    
681  \subsubsection{UPLOAD}  \subsubsection{UPLOAD}
682  The service should support table upload via the UPLOAD parameter. The value is a  The UPLOAD parameter is described in [std:DALI]. Services should support the
683  list of table-name,URI pairs. Table names must be legal ADQL table names as  upload of temporary tables (in [std:VOTable] format) via the standard UPLOAD
684  defined in [1]. URIs maybe be simple URLs (e.g. with a URI scheme of http) or  parameter. The table-name(s) must be legal ADQL table names as defined in
685  URIs (e.g. with a URI scheme of vos or param) that must be resolved to give the  [std:ADQL] but restricted as described below XREF. URIs maybe be simple URLs
686  location of the table content. See section 2.5 for details.  (e.g. with a URI scheme of http) or URIs (e.g. with a URI scheme of vos or
687    param) that must be resolved to give the location of the table content. See
688  \subsubsection{Case of Parameters}  section XREF for details.
689  NOTE: this is in DALI now  
690    If table upload supported, the service must accept tables in VOTable format.
691  \subsubsection{Order and Cardinality of Parameters}  The client specifies the name of the uploaded table; this name must be a legal
692  NOTE: this is in DALI now  ADQL table name with no catalog or schema (i.e., a string following the
693    regular identifier production of [std:ADQL]). Uploaded tables must be referred
694  \subsection{Table Names}  to in queries as TAP\underline{' '}UPLOAD.<tablename>, where <tablename> is the
695  A fully qualified table name has the form  specified by the user. Tables in the TAP\underline{' '}UPLOAD schema are
696  \begin{verbatim}  transient and persist only for the lifetime of the query (although caching might
697  [[catalog_name”.”]schema_name”.”]table_name  be used behind the scenes) and are never visible in the
698  \end{verbatim}  TAP\underline{' '}SCHEMA metadata.
699  where catalog\underline{' '}name is the name of the DB catalogue (often the  
700  “database” name) in SQL DBMS terminology, schema\underline{' '}name is the name  The [std:DALI] UPLOAD parameter supports both external resources and in-line
701  of the “schema” in DBMS terminology (often also called a “database”; a DBMS  content. For external resources, one provides a URI (usually an HTTP URL) the
702  schema is a type of data model where the top level data model elements are  TAP service can use to obtain the table content. For example,
703  tables), and table\underline{' '}name is the actual table name.  All elements of  \begin{verbatim}
704  the table name are optional except table\underline{' '}name.  Depending upon the  HTTP POST http://example.com/tap/async/42
705  DBMS, “catalog” or “schema” may or may not be implemented; some DBMS implement  UPLOAD=mytable,http://otherplace.com/path/votable.xml
706  both, others one or the other, and the simplest database systems might not  \end{verbatim}
707  implement either.  The service would retrieve the table from the provided URL and
708    make it visible to the query as TAP\underline{' '}UPLOAD.mytable.
709  The implementation of a TAP service must define the table names acceptable in  
710  queries and must reveal these to clients through metadata queries or through  If the TAP service supports VOSpace (TBD: how to declare this?), one may
711  VOSI-tables output, and the names must be identical in each of these sources. A  specify an upload table using a URI to a table stored in a VOSpace, for example:
712  TAP client must determine the acceptable names from one of these sources or from  \begin{verbatim}
713  the cached form of the VOSI-tables output included in the service's  HTTP POST http://example.com/tap/async/42
714  registration.  UPLOAD=mytable,vos://space/path/votable.xml
715    \end{verbatim}
716  \subsection{Table Upload}  The service would resolve the URI, contact the VOSpace, retrieve the table, and
717  The service should implement the table upload capability. If upload is  make it visible to the query as TAP\underline{' '}UPLOAD.mytable.
718  supported,  the service must accept tables in VOTable format. The client  
719  specifies the name of the uploaded table; this name must be a legal ADQL table  UPLOADs are accumulating, i.e., each UPLOAD parameter given will create one or
720  name with no catalog or schema (e.g. an unqualified table name). Uploaded tables  more tables in TAP\underline{' '}UPLOAD. When the table names from two or more
721  must be referred to in queries as TAP\underline{' '}UPLOAD.<tablename>, where  upload items agree after case folding, the service behaviour is unspecified.
722  <tablename> is the specified by the user.  Clients thus cannot reliably overwrite uploaded tables; to correct errors, they
723    have to tear down the existing job and create a new one. In principle, any
724  Tables in the TAP\underline{' '}UPLOAD schema are transient and  number of tables can be uploaded using the UPLOAD parameter and any combination
725  persist only for the lifetime of the query (although caching might be used  of URI schemes supported by the service as long as they are assigned unique
726  behind the scenes) and are never visible in the TAP\underline{' '}SCHEMA  table names within the query. Services may limit the size and number of
727  metadata.  uploaded tables; if the service refuses to accept the entire table it must
728    respond with an error as described in 2.7.3 .
729    
730    
731    \section{Use of VOTable}
732    The [std:VOTable] format is the standard format for output (query results) and
733    input (table upload) in a TAP service.
734    
735    
736    \subsection{INFO elements}
737    The RESOURCE element must contain an INFO element with attribute
738    name="QUERY\underline{' '}STATUS" indicating the success of the operation. For
739    RESOURCE elements that contain a TABLE element, this INFO element must appear
740    lexically before the TABLE. The following values are defined for this INFO
741    element's value attribute:
742    
743    “OK”, meaning that the query executed successfully and a result table is
744    included in the resource
745    
746    "ERROR”, meaning that an error was detected at the level of the TAP
747    protocol or the query failed to execute
748    
749    The content of the INFO element conveying the status should be a message
750    suitable for display to the user describing the status.
751    
752    \begin{verbatim}
753    <INFO name="QUERY_STATUS" value="OK"/>
754    \end{verbatim}
755    
756    \begin{verbatim}
757    <INFO name="QUERY_STATUS" value="OK">Successful query</INFO>
758    \end{verbatim}
759    
760    \begin{verbatim}
761    <INFO name="QUERY_STATUS" value="ERROR">
762       value out of range in POS=45,91
763    </INFO>
764    \end{verbatim}
765    
766    Additional INFO elements may be provided, e.g., to echo the input parameters
767    back to the client in the query response (a useful feature for debugging or to
768    self-document the query response), but clients should not depend on these.
769    
770    \begin{verbatim}
771    <RESOURCE type=”results”>
772    <INFO name="QUERY_STATUS" value="ERROR">
773        unrecognized operation
774    </INFO>
775    <INFO name="SPECIFICATION" value="TAP"/>
776    <INFO name=”VERSION” value=”1.0”/>
777    <INFO name="REQUEST" value="doQuery"/>
778    <INFO name="baseUrl" value="http://webtest.aoc.nrao.edu/ivoa-dal"/>
779    <INFO name="serviceVersion" value="1.0"/
780    ...
781    </RESOURCE>
782    \end{verbatim}
783    
784    If an overflow occurs (result exceeds MAXREC), the service must close the table
785    and append another INFO element to the RESOURCE (after the TABLE) with
786    name=”QUERY\underline{' '}STATUS” and the value=”OVERFLOW”.
787    \begin{verbatim}
788    <RESOURCE type=”results”>
789    <INFO name="QUERY_STATUS" value="OK"/>
790    ...
791    <TABLE>...</TABLE>
792    <INFO name="QUERY_STATUS" value="OVERFLOW"/>
793    </RESOURCE>
794    \end{verbatim}
795    
796    In the above example, the TABLE should have exactly MAXREC rows.
797    
798    If an error occurs while writing the rows of the VOTable, the service must
799    close the table and append another INFO element to the RESOURCE, after the
800    TABLE, with name=”QUERY\underline{' '}STATUS” and the value=”ERROR”.
801    \begin{verbatim}
802    <RESOURCE type=”results”>
803    <INFO name="QUERY_STATUS" value="OK"/>
804    ...
805    <TABLE>...</TABLE>
806    <INFO name="QUERY_STATUS" value="ERROR" />
807    </RESOURCE>
808    \end{verbatim}
809    The content of these trailing INFO elements is optional and intended for users;
810    client software should not depend on it.
811    
812    Thus, one INFO element with name=”QUERY\underline{' '}STATUS” and value=”OK” or
813    value=”ERROR” must be included before the TABLE. If the TABLE does not contain
814    the entire query result, one INFO element with value=”OVERFLOW” or
815    value=”ERROR”
816     must be included after the table.
817    2.9.2 Version Mismatch Errors
818    
819    Errors due to version mismatch from either the VERSION parameter (TAP version)
820    or specific version used in the LANG parameter (query language version) are
821    specified using an INFO element with name=”QUERY\underline{' '}STATUS” and
822    value=”ERROR” as described above.  
823    
824    \subsection{Successful Queries}
825    
826    The result of a query depends on the query language used and may be one or more
827    tables in one or more resources. Unsupportable combinations of query result and
828    FORMAT (e.g. queries that produce multiple tables and an inherently
829    single-table format like CSV) will cause the request to fail. Currently, an ADQL
830    query result must be a single table (in a single file).
831    
832    The output table must include the same number and order of columns as specified
833    in the SELECT clause of the query. For VOTable output, the name attribute of
834    FIELD elements must be the same as the column names (or aliases if specified in
835    the query) from the query and the datatype, arraysize, and xtype attributes of
836    FIELD elements must be set using the mapping specified in section 2.5 . The
837    xtype attribute in the output must match the datatype for the column in the
838    TAP\underline{' '}SCHEMA.
839    
840    VOTable structure follows the rules in section 2.9 and must be returned with an
841    allowed VOTable MIME type (application/x-votable+xml or text/xml). If the
842    FORMAT parameter (see 2.3.6 ) of the request specified a specific VOTable MIME
843    type, the requested MIME type must be used in the HTTP response.
844    
845    CSV formatted data should represent the output table with one row of text per
846    table row, with the table column values rendered as text and separated by
847    commas. If a column value contains a comma the entire column value should be
848    enclosed in double quotes.  Text lines may be arbitrarily long.  The first data
849    row should give the column name as the data value.   CSV data must be returned
850    with a MIME type of text/csv; if the optional header line (with column names)
851    is included, the MIME type must be text/csv;header=present. Full details of CSV
852    format are defined in RFC 4180 [14].
853    
854    TSV formatted data should represent the output table with one row of text per
855    table row, with the table column values rendered as text and separated by the
856    TAB character. TSV data must be returned with a MIME type of
857    text/tab-separated-values [15]. Column values may not contain the TAB
858    character.
859    
860    \subsection{Errors}
861    If the service detects an exceptional condition, it must return an error
862    document with an appropriate HTTP-status code. TAP distinguishes three classes
863    of exceptions.
864    
865    Errors in the use of the HTTP protocol.
866    
867    Errors in the use of the TAP protocol, including both invalid requests and
868    failure of the service to complete valid requests.
869    
870    Error documents for HTTP-level errors are not specified in the TAP protocol.
871    Responses to these errors are typically generated by service containers and
872    cannot be controlled by TAP implementations. There are several cases where a
873    TAP
874    service could return an HTTP error. First, the /async endpoint could return a
875    404 (not found) error if the client accesses a job within the UWS joblist that
876    does not exist. Second, access to a resource could result in an HTTP 401 (not
877    authorized) error if authentication is required or an HTTP 403 (forbidden)
878    error if the client is not allowed to access the resource.
879    
880    Error documents for TAP errors must be VOTable documents;  any result-format
881    specified in the request is ignored. If the error document is being retrieved
882    from the /async/<jobid>/error resource (specified by UWS) after an asynchronous
883    query, the HTTP status code should be 200. If the error document is being
884    returned directly after a synchronous query, the service may use an appropriate
885    HTTP status code, including 200 (successfully returning a response to the
886    request) and various 4xx and 5xx values. The exception condition must be
887    described to the client using a status code in the VOTable header.  Section  
888    2.9 specifies the use of VOTable for error documents in TAP services.
889    
890    \subsection{Overflows}
891    If a query is executed by a TAP service, the number of rows in the table of
892    results may exceed a limit requested by the user (using the MAXREC parameter)
893    or a limit set by the service implementation (the default or maximum value of
894    MAXREC). In these cases, the query is said to have 'overflowed'. Typically, a
895    TAP service will not detect an overflow until some part of the table of results
896    has been sent to the client.
897    
898    If an overflow occurs, the TAP service must produce a table of results that is
899    valid, in the required output format, and which contains all the results up to
900    the point of overflow. Since an output overflow is not an error condition, the
901    MIME type of the output must be the same as for any successful query and the
902    HTTP status-code must be as for a successful, complete query.
903    
904    If the output format is VOTable, section 2.9.1 describes the method by which
905    the overflow is reported. No method of reporting an overflow is defined for
906    formats other than VOTable.
907    
908    \subsection{VOTable vs RDBMS Tables and Columns}
909    
910    TODO: describe the bi-directional mapping of VOTable <-> RDBMS table aka the
911    old section on uploading tables... should this come earlier in the doc?
912    
913  The column names in the transient database table are taken directly from the  The column names in the transient database table are taken directly from the
914  name attribute of the VOTable FIELD and PARAM elements. The datatypes of the  name attribute of the VOTable FIELD and PARAM elements. TODO: add column name
915    restrictions here to avoid quoted identifiers. The datatypes of the
916  transient table are determined from the FIELD and PARAM attributes as follows:  transient table are determined from the FIELD and PARAM attributes as follows:
917    
918  TODO: table  TODO: something like the table from TAP-1.0
919    
920  The default mapping of data types are shown above (no arraysize or xtype). If  The default mapping of data types are shown above (no arraysize or xtype). If
921  the xtype attribute is set, this is the preferred internal datatype. If xtype is  the xtype attribute is set, this is the preferred internal datatype. If xtype is
922  not set, then the datatype and arraysize indicate the most suitable internal  not set, then the datatype and arraysize indicate the most suitable internal
923  datatype.  datatype. Note that the last column of Table (x) is not normative.
924    Implementations SHOULD try to make sure that the actual types chosen are at
925    least signature-compatible with the recommended types (i.e., integers should
926    remain integers, floating-point values floating-point values, etc.), such that
927    clients can reliably write queries against uploaded tables.
928    
929    For columns with xtype adql:REGION, this is particularly critical, since
930    databases typically use different types to represent various STC-S objects.
931    Clients are advised to assume that such columns will be approximated with
932    polygons in the actual database table.
933    
934  In the arraysize column above, [1] means the arraysize is not set or is set to  In the arraysize column above, [1] means the arraysize is not set or is set to
935  1, n means arraysize is set to a specific value, * means arraysize=”*”, and n*  1, n means arraysize is set to a specific value, * means arraysize=”*”, and n*
# Line 704  Line 952 
952  or, more likely, transform a column value (an identifier) into a URL while  or, more likely, transform a column value (an identifier) into a URL while
953  writing the results.  writing the results.
954    
955  TIMESTAMP values are specified using ISO8601 format without a timezone (as in  TIMESTAMP values are specified as described in [std:DALI]. The
956  2.3.4 ) and are assumed to be in UTC. The xtype=”adql:TIMESTAMP” attribute must  xtype=”adql:TIMESTAMP” attribute must be specified in an uploaded VOTable in
957  be specified in an uploaded VOTable in order for the values to be inserted in a  order for the values to be inserted in a column of type TIMESTAMP; without the
958  column of type TIMESTAMP; without the xtype, the values would be inserted into a  xtype, the values would be inserted into a CHAR(n) or VARCHAR column.
 CHAR(n) or VARCHAR column.  
959    
960  POINT and REGION values are specified in STC-S format (see section 6 ). The  POINT and REGION values are specified in STC-S format (see section 6 ). The
961  xtype=”adql:POINT” attribute must be specified in an uploaded VOTable in order  xtype=”adql:POINT” attribute must be specified in an uploaded VOTable in order
# Line 718  Line 965 
965  to be parsed and treated as REGIONs (e.g. to be used with some of the ADQL  to be parsed and treated as REGIONs (e.g. to be used with some of the ADQL
966  region functions).  region functions).
967    
968  \subsubsection{UPLOAD}  \section{Metadata: TAP SCHEMA}
 The UPLOAD parameter is used to reference read-only external tables via their  
 URI, to be uploaded for use as input tables to the query.   The value of the  
 UPLOAD parameter is a list of table name-URI pairs. Elements of the list are    
 delimited by semicolon and the two parts of the pair are delimited by comma. For  
 example:  
 \begin{verbatim}  
 UPLOAD=table_a,http://host_a/path;table_b,http://host_b/path  
 \end{verbatim}  
   
 would define two input tables table\underline{' '}a and  
 table\underline{' '}b, located at the given URIs. Services that implement  
 UPLOAD must support http as a URI scheme (e.g. must support treating an http URI  
 as a URL). A VOSpace URI (vos:<something>)  is a more generic example of a URI  
 that requires more service-side functionality; support for the vos scheme is  
 optional.  
   
 \subsubsection{Inline Table Upload}  
 To upload a table inline, the caller must specify the UPLOAD parameter (as  
 above) using a special URI scheme “param”. This scheme indicates that the value  
 after the colon will be the name of the inline content. The content type used is  
 multipart/form-data, using a “file” type input element. The “name” attribute  
 must match that used in the UPLOAD parameter.  
   
 For example, in the POST data we might have this parameter:  
 \begin{verbatim}  
 UPLOAD=table_c,param:table1  
 \end{verbatim}  
 and this content:  
 \begin{verbatim}  
 Content-Type: multipart/form-data; boundary=AaB03  
   
 [...]  
   
 --AaB03x  
   
 Content-disposition: form-data; name="table1"; filename="table1.xml"  
969    
 Content-type: application/x-votable+xml  
   
 [...]  
   
 --AaB03x  
   
 [...]  
 \end{verbatim}  
 The uploaded table would be referenced in queries as  
 TAP\underline{' '}UPLOAD.table\underline{' '}c (the table name in the UPLOAD  
 parameter). Services that implement table upload must support the param scheme  
 for inline uploads.  
   
 In principle, any number of tables can be uploaded using the UPLOAD parameter  
 and any combination of URI schemes supported by the service as long as they are  
 assigned unique table names within the query. Services may limit the size and  
 number of uploaded tables; if the service refuses to accept the entire table it  
 must respond with an error as described in 2.7.3 .  
   
 \subsection{Metadata and TAP SCHEMA}  
970  There are several approaches to getting metadata for a given TAP service. All  There are several approaches to getting metadata for a given TAP service. All
971  TAP services must support a set of tables in a schema named  TAP services must support a set of tables in a schema named
972  TAP\underline{' '}SCHEMA that describe the tables and columns included in the  TAP\underline{' '}SCHEMA that describe the tables and columns included in the
# Line 811  Line 1002 
1002  in the standard tables described below. For example, one could include a column  in the standard tables described below. For example, one could include a column
1003  with a timestamp saying when metadata values were was last modified.  with a timestamp saying when metadata values were was last modified.
1004    
1005  \subsubsection{Schemas}  \subsection{Schemas}
1006  The table TAP\underline{' '}SCHEMA.schemas must contain the following columns:  The table TAP\underline{' '}SCHEMA.schemas must contain the following columns:
1007    
1008  TODO: table  TODO: table
# Line 822  Line 1013 
1013  [catalog.]schema. The schema metadata are included for reference and are not  [catalog.]schema. The schema metadata are included for reference and are not
1014  used directly to construct queries.  used directly to construct queries.
1015    
1016  \subsubsection{Tables}  \subsection{Tables}
1017  The table TAP\underline{' '}SCHEMA.tables must contain the following columns:  The table TAP\underline{' '}SCHEMA.tables must contain the following columns:
1018    
1019  TODO: table  TODO: table
# Line 833  Line 1024 
1024  depending on the implementation requirements. The fully qualified table name is  depending on the implementation requirements. The fully qualified table name is
1025  defined by the ADQL language and follows the pattern [[catalog.]schema.]table.  defined by the ADQL language and follows the pattern [[catalog.]schema.]table.
1026    
1027  \subsubsection{Columns}  \subsection{Columns}
1028  The table TAP\underline{' '}SCHEMA.columns must contain the following columns:  The table TAP\underline{' '}SCHEMA.columns must contain the following columns:
1029    
1030  TODO: table  TODO: table
# Line 844  Line 1035 
1035  Data types and how they map to VOTable datatypes are described in section 2.5  Data types and how they map to VOTable datatypes are described in section 2.5
1036  above. The “size” gives the length of variable length datatypes, for example  above. The “size” gives the length of variable length datatypes, for example
1037  varchar(256); this size does not map to the VOTable arraysize attribute when the  varchar(256); this size does not map to the VOTable arraysize attribute when the
1038  latter specifies the size and shape of a multi-dimensional array. The  latter specifies the size and shape of a multi-dimensional array. To use size in
1039  “principal” flag indicates that the column is considered a core part the  a query, it must be put in double quotes since it collides with an ADQL reserved
1040    word. Since delimited identifiers are case-sensitive, for the size column both
1041    clients and servers MUST always (in particular, in the DDL for
1042    TAP\underline{' '}SCHEMA) use lower case exclusively. In the next major version
1043    of TAP, this column will be called arraysize.
1044    
1045    The “principal” flag indicates that the column is considered a core part the
1046  content; clients can use this hint to make the principal column(s) visible, for  content; clients can use this hint to make the principal column(s) visible, for
1047  example by selecting them by default in generating an ADQL query. In cases where  example by selecting them by default in generating an ADQL query. In cases where
1048  the services selects the columns to return (such as PQL without a SELECT  the services selects the columns to return (such as PQL without a SELECT
1049  parameter), the principal column indicates those columns that are returned by  parameter), the principal column indicates those columns that are returned by
1050  default. The “indexed” flag indicates that the column is indexed, potentially  default.
1051  making queries run much faster if this column is used in a constraint. The “std”  
1052  is included for compatibility with the registry, which uses this value to  The “indexed” flag indicates that the column is indexed, potentially
1053  indicate that a given column is defined by some standard, as opposed to a custom  making queries run much faster if this column is used in a constraint.
1054  column defined by a particular service.  
1055    The “std” is included for compatibility with the registry, which uses this value
1056    to indicate that a given column is defined by some standard, as opposed to a
1057    custom column defined by a particular service.
1058    
1059  \subsubsection{Foreign Keys}  \subsection{Foreign Keys}
1060  The table TAP\underline{' '}SCHEMA.keys must contain the following columns to  The table TAP\underline{' '}SCHEMA.keys must contain the following columns to
1061  describe foreign key relations between tables:  describe foreign key relations between tables:
1062    
# Line 878  Line 1078 
1078  A TAP service must provide the tables listed above and may provide other tables  A TAP service must provide the tables listed above and may provide other tables
1079  in the TAP\underline{' '}SCHEMA namespace.  in the TAP\underline{' '}SCHEMA namespace.
1080    
 \subsection{Access to and Representation of Results}  
 \subsubsection{Data and Metadata Queries}  
 The result of a data query or a metadata query depends on the query language  
 used and may be one or more tables in one or more resources. Unsupportable  
 combinations of query result and FORMAT (e.g. queries that produce multiple  
 tables and an inherently single-table format like CSV) will cause the request to  
 fail. Currently, an ADQL query result must be a single table (in a single file).  
   
 This table must be encoded in the output format specified by the FORMAT  
 parameter of the query. See section 2.3.6 for required, optional and default  
 formats. VOTable is the default format and VOTable support is mandatory.  
   
 The output table must include the same number and order of columns as specified  
 in the SELECT clause of the query. For VOTable output, the name attribute of  
 FIELD elements must be the same as the column names (or aliases if specified in  
 the query) from the query and the datatype, arraysize, and xtype attributes of  
 FIELD elements must be set using the mapping specified in section 2.5 . The  
 xtype attribute in the output must match the datatype for the column in the  
 TAP\underline{' '}SCHEMA.  
   
 VOTable structure follows the rules in section 2.9 and must be returned with an  
 allowed VOTable MIME type (application/x-votable+xml or text/xml). If the FORMAT  
 parameter (see 2.3.6 ) of the request specified a specific VOTable MIME type,  
 the requested MIME type must be used in the HTTP response.  
   
 CSV formatted data should represent the output table with one row of text per  
 table row, with the table column values rendered as text and separated by  
 commas. If a column value contains a comma the entire column value should be  
 enclosed in double quotes.  Text lines may be arbitrarily long.  The first data  
 row should give the column name as the data value.   CSV data must be returned  
 with a MIME type of text/csv; if the optional header line (with column names) is  
 included, the MIME type must be text/csv;header=present. Full details of CSV  
 format are defined in RFC 4180 [14].  
   
 TSV formatted data should represent the output table with one row of text per  
 table row, with the table column values rendered as text and separated by the  
 TAB character. TSV data must be returned with a MIME type of  
 text/tab-separated-values [15]. Column values may not contain the TAB  
 character.  
   
 \subsubsection{VOSI}  
 Representations of VOSI outputs (capabilities, availability, table metadata)  
 must be as defined in the VOSI standard [6].  
   
 The representation of table metadata must include all tables in the service's  
 tableset. VOSI's representation of table metadata is specified in VODataService  
 [7].  
   
 The VOSI standard specifies that the capability metadata is encoded as an XML  
 document which lists each of the service's capabilities as a <capability>  
 element. The type of this element (which defines the contents) is  
 {http://www.ivoa.net/xml/VOResource/v1.0}Capability from the VOResource XML  
 standard [8].  
   
 In addition, the capabilities output must also comply with the following      
 requirements:  
   
     •.the returned document must include one <capability> element that describes  
 the service's support for the TAP protocol  
   
     •.this <capability> element must have its "standardID" attribute set to  
 "ivo://ivoa.net/std/TAP"  
   
     •.this capability element must include at least one "<interface>" element  
 with its "role" attribute set to "std",    
   
     •.this "<interface>" element must contain a child "<accessURL>" element with  
 the attribute "use" set to "base" which contains the root web resource for the  
 service as defined in section 2.2 .  
   
 Note: VO registries recognize a service's support for a standard protocol  
 through this capability description. In particular, a different standard  
 Capability sub-type is used for each standard protocol to provide capability  
 metadata that is specific to that protocol. At the time of this writing, a  
 Capability sub-type for TAP has not yet been defined. Thus for compliance with  
 this standard, any legal Capability description that meets the above  
 restrictions is sufficient. However, once a VOResource extension for TAP is  
 standardized, it is strongly recommended that TAP services emit its capabilities  
 using that the Capability sub-type specialized for TAP.  
   
 For example, the returned capabilities document for a service supporting    TAP  
 might look as follows:  
   
 \begin{verbatim}  
 <?xml version="1.0" encoding="UTF-8"?>  
   
 <vosi:capabilities xmlns=""  
   
    xmlns:vosi="http://www.ivoa.net/xml/VOSI/v1.0"  
   
    xmlns:vs="http://www.ivoa.net/xml/VODataService/v1.0"  
   
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"  
   
    xsi:schemaLocation="http://www.ivoa.net/xml/VOSI/v1.0  
   
                        http://www.ivoa.net/xml/VOSI/v1.0  
   
              http://www.ivoa.net/xml/VODataService/v1.0  
   
              http://www.ivoa.net/xml/VODataService/v1.0">  
   
   <vosi:capability standardID="ivo://ivoa.net/std/TAP">  
   
     <interface xsi:type="vs:ParamHTTP" role="std">  
   
       <accessURL use="base"> http://myarchive.net/myTAP </accessURL>  
   
     </interface>  
   
   </vosi:capability>  
   
   <vosi:capability standardID="ivo://ivoa.net/std/VOSI#capabilities">  
   
     <interface xsi:type="vs:ParamHTTP">  
   
       <accessURL use="full">  
   
         http://myarchive.net/myTAP/capabilities </accessURL>  
   
     </interface>  
   
   </vosi:capability>  
   
   <vosi:capability standardID="ivo://ivoa.net/std/VOSI#availability">  
   
     <interface xsi:type="vs:ParamHTTP">  
   
       <accessURL use="full">  
   
         http://myarchive.net/myTAP/availability  
   
       </accessURL>  
   
     </interface>  
   
   </vosi:capability>  
1081    
1082    <vosi:capability standardID="ivo://ivoa.net/std/VOSI#tables">  \section{Examples}
   
     <interface xsi:type="vs:ParamHTTP">  
   
       <accessURL use="full">  
   
         http://myarchive.net/myTAP/tables </accessURL>  
   
     </interface>  
   
   </vosi:capability>  
   
 </vosi:capabilities>  
 \end{verbatim}  
   
 \subsubsection{Errors}  
 If the service detects an exceptional condition, it must return an error  
 document with an appropriate HTTP-status code. TAP distinguishes three classes  
 of exceptions.  
   
 Errors in the use of the HTTP protocol.  
   
 Errors in the use of the TAP protocol, including both invalid requests and  
 failure of the service to complete valid requests.  
   
 Error documents for HTTP-level errors are not specified in the TAP protocol.  
 Responses to these errors are typically generated by service containers and  
 cannot be controlled by TAP implementations. There are several cases where a TAP  
 service could return an HTTP error. First, the /async endpoint could return a  
 404 (not found) error if the client accesses a job within the UWS joblist that  
 does not exist. Second, access to a resource could result in an HTTP 401 (not  
 authorized) error if authentication is required or an HTTP 403 (forbidden) error  
 if the client is not allowed to access the resource.  
   
 Error documents for TAP errors must be VOTable documents;  any result-format  
 specified in the request is ignored. If the error document is being retrieved  
 from the /async/<jobid>/error resource (specified by UWS) after an asynchronous  
 query, the HTTP status code should be 200. If the error document is being  
 returned directly after a synchronous query, the service may use an appropriate  
 HTTP status code, including 200 (successfully returning a response to the  
 request) and various 4xx and 5xx values. The exception condition must be  
 described to the client using a status code in the VOTable header.  Section    
 2.9 specifies the use of VOTable for error documents in TAP services.  
   
 \subsubsection{Overflows}  
 If a query is executed by a TAP service, the number of rows in the table of  
 results may exceed a limit requested by the user (using the MAXREC parameter) or  
 a limit set by the service implementation (the default or maximum value of  
 MAXREC). In these cases, the query is said to have 'overflowed'. Typically, a  
 TAP service will not detect an overflow until some part of the table of results  
 has been sent to the client.  
   
 If an overflow occurs, the TAP service must produce a table of results that is  
 valid, in the required output format, and which contains all the results up to  
 the point of overflow. Since an output overflow is not an error condition, the  
 MIME type of the output must be the same as for any successful query and the  
 HTTP status-code must be as for a successful, complete query.  
   
 If the output format is VOTable, section 2.9.1 describes the method by which the  
 overflow is reported. No method of reporting an overflow is defined for formats  
 other than VOTable.  
   
 \subsection{Versioning of the TAP Protocol}  
 The TAP protocol provides explicitly for versioning of the interface in order to  
 support version negotiation between a client and a service where one or both  
 parties support more than one version of the protocol. The TAP version refers  
 only to the TAP protocol; query languages are versioned separately and TAP and  
 ADQL versions may differ.  
   
 Version numbers follow IVOA document conventions [17].  
   
 \subsubsection{Appearance in requests and in service metadata}  
 The version number may appear in at least three places: in the service metadata,  
 as a parameter in client requests to a server, and in the query response. The  
 version number used in a client’s request of a particular server must be equal  
 to a version number which that server has declared it supports (except during  
 negotiation, as described below). A server may support several versions, whose  
 values clients may discover according to the negotiation rules.  
   
 \subsubsection{Version number negotiation}  
 If a TAP client does not specify the version number in a request, the server  
 assumes the highest standard version supported by the service, and no explicit  
 version checking takes place.   If the client specifies an explicit version  
 number, and this does not match a version available from the service, the  
 service returns a version number mismatch error as described in 2.9.2 . The  
 client can determine what versions of the protocol the service supports by a  
 prior call to VOSI-capabilities or via a registry query.  
   
 \subsection{Use of VOTable}  
 VOTable is a general format. TAP requires that it be used in a particular way.  
   
 The result VOTable document must comply with VOTable v1.2 or greater [9]. For  
 columns containing coordinate values, the coordinate system metadata should be  
 provided as described in [13].  
   
 The VOTable must contain a RESOURCE element identified with the attribute  
 type="results", containing a single TABLE element with the results of the query.  
 Additional RESOURCE elements may be present, but the usage of any such elements  
 is not defined here and TAP clients should not depend upon them.  
   
 \subsubsection{INFO elements}  
 The RESOURCE element must contain, before the TABLE element, an INFO element  
 with attribute name = "QUERY\underline{' '}STATUS". The value attribute must  
 contain one of the following values:  
   
 “OK”, meaning that the query executed successfully and a result table is  
 included in the resource  
   
 "ERROR”, meaning that an error was detected at the level of the TAP  
 protocol or the query failed to execute  
   
 The content of the INFO element conveying the status should be a message  
 suitable for display to the user describing the status.  
   
 \begin{verbatim}  
 <INFO name="QUERY_STATUS" value="OK"/>  
 \end{verbatim}  
   
 \begin{verbatim}  
 <INFO name="QUERY_STATUS" value="OK">Successful query</INFO>  
 \end{verbatim}  
   
 \begin{verbatim}  
 <INFO name="QUERY_STATUS" value="ERROR">  
    value out of range in POS=45,91  
 </INFO>  
 \end{verbatim}  
   
 Additional INFO elements may be provided, e.g., to echo the input parameters  
 back to the client in the query response (a useful feature for debugging or to  
 self-document the query response), but clients should not depend on these.  
   
 \begin{verbatim}  
 <RESOURCE type=”results”>  
 <INFO name="QUERY_STATUS" value="ERROR">  
     unrecognized operation  
 </INFO>  
 <INFO name="SPECIFICATION" value="TAP"/>  
 <INFO name=”VERSION” value=”1.0”/>  
 <INFO name="REQUEST" value="doQuery"/>  
 <INFO name="baseUrl" value="http://webtest.aoc.nrao.edu/ivoa-dal"/>  
 <INFO name="serviceVersion" value="1.0"/  
 ...  
 </RESOURCE>  
 \end{verbatim}  
   
 If an overflow occurs (result exceeds MAXREC), the service must close the table  
 and append another INFO element to the RESOURCE (after the TABLE) with  
 name=”QUERY\underline{' '}STATUS” and the value=”OVERFLOW”.  
 \begin{verbatim}  
 <RESOURCE type=”results”>  
 <INFO name="QUERY_STATUS" value="OK"/>  
 ...  
 <TABLE>...</TABLE>  
 <INFO name="QUERY_STATUS" value="OVERFLOW"/>  
 </RESOURCE>  
 \end{verbatim}  
   
 In the above example, the TABLE should have exactly MAXREC rows.  
   
 If an error occurs while writing the rows of the VOTable, the service must close  
 the table and append another INFO element to the RESOURCE, after the TABLE, with  
 name=”QUERY\underline{' '}STATUS” and the value=”ERROR”.  
 \begin{verbatim}  
 <RESOURCE type=”results”>  
 <INFO name="QUERY_STATUS" value="OK"/>  
 ...  
 <TABLE>...</TABLE>  
 <INFO name="QUERY_STATUS" value="ERROR" />  
 </RESOURCE>  
 \end{verbatim}  
 The content of these trailing INFO elements is optional and intended for users;  
 client software should not depend on it.  
   
 Thus, one INFO element with name=”QUERY\underline{' '}STATUS” and value=”OK” or  
 value=”ERROR” must be included before the TABLE. If the TABLE does not contain  
 the entire query result, one INFO element with value=”OVERFLOW” or value=”ERROR”  
  must be included after the table.  
 2.9.2 Version Mismatch Errors  
   
 Errors due to version mismatch from either the VERSION parameter (TAP version)  
 or specific version used in the LANG parameter (query language version) are  
 specified using an INFO element with name=”QUERY\underline{' '}STATUS” and  
 value=”ERROR” as described above.    
   
 \section{Service Registration}  
 Publication of a service to the VO requires that it be registered with an IVOA  
 registry, including describing the identity and capabilities of the service.  
   
 The resource document for a TAP service instance must be structured according to  
 VOResource [8] using the sub-type CatalogService as defined in VODataService  
 [7].  
   
 The resource document must include a capability element denoting the TAP  
 interface and functions. This element must contain the URL for the root web  
 resource (as defined in section 2.2 ). Clients would add to this URL /sync or  
 /async as appropriate.  
   
 The resource document must contain capability elements for the  
 VOSI-capabilities, VOSI-availability and VOSI-tables outputs. These must be  
 formatted as in the VOSI standard [6].  
   
 The resource document should include the table metadata, except where the    
 database-schema of the archive changes frequently. Where table metadata are  
 provided, they must be represented as XML elements drawn from VODataService  
 [7].  
   
 \section{Extended Capabilities}  
 The TAP service allows for optional extended capabilities and operations.  
 Extensions may be defined within an information community when needed for  
 additional functionality or specialization.  A generic client must not be  
 required or expected to make use of such extensions.  Extended capabilities or  
 operations must be defined by the service metadata. Extended capabilities  
 provide additional metadata about the service, and may or may not enable  
 optional new parameters to be included in operation requests.  Extended  
 operations may allow additional operations to be defined.  
   
 A server must produce a valid response to the operations defined in this  
 document, even if parameters used by extended capabilities are missing or  
 malformed (i.e. the server must supply a default value for any extended  
 capabilities it defines), or if parameters are supplied that are not known to  
 the server.  
   
 Service providers must choose extension names with care to avoid conflicting  
 with standard metadata fields, parameters and operations.  
   
 \section{Use of UWS}  
1083  The UWS pattern is specified in [3] and its application to TAP in section  The UWS pattern is specified in [3] and its application to TAP in section
1084  2.2.2. This section explains the exchange of messages between a TAP client and  XREF. This section gives examples of the exchange of messages between a
1085  service when using UWS to run an asynchronous query.  TAP client and service when using UWS to run an asynchronous query.
1086    
1087    \subsection{Example: Asynchronous Query}
1088  Consider a TAP service at http://example.com/tap. TAP mandates that the  Consider a TAP service at http://example.com/tap. TAP mandates that the
1089  asynchronous requests be directed to http://example.com/tap/async. This URL  asynchronous requests be directed to http://example.com/tap/async (e.g. for
1090  points to the list of 'jobs'; i.e. the list of queries currently or recently  anonymous queries). This URL points to the list of 'jobs'; i.e. the list of
1091  executed.  queries currently or recently executed.
1092    
1093  \subsection{Creating a Query}  \subsubsection{Creating a Query}
1094  To create a new query, the client POSTs a request to the job list:  To create a new query, the client POSTs a request to the job list:
1095    
1096  \begin{verbatim}  \begin{verbatim}
# Line 1336  Line 1174 
1174  DESTRUCTION=2008-11-11T11:11:11Z  DESTRUCTION=2008-11-11T11:11:11Z
1175  \end{verbatim}  \end{verbatim}
1176    
1177  \subsection{Running a Query}  \subsubsection{Running a Query}
1178  The phase URL shows the progress of the job. When the job is created by the  The phase URL shows the progress of the job. When the job is created by the
1179  service it will normally be set to PENDING, but might be set to ERROR if the  service it will normally be set to PENDING, but might be set to ERROR if the
1180  service has rejected the job. If the phase is ERROR, then the error URL should  service has rejected the job. If the phase is ERROR, then the error URL should
# Line 1411  Line 1249 
1249  curl http://example.com/tap/42/results/result  curl http://example.com/tap/42/results/result
1250  \end{verbatim}  \end{verbatim}
1251    
1252  \section{Use of STC-S in TAP}  \subsubsection{Example: Synchronous Query}
1253    
1254  NOT: not included from TAP-1.0 since it was informative and does not belong in  TODO
 this docuemnt.  
1255    
1256  \section{VOSpace Integration}  \subsubsection{Example: DALI-examples Document}
1257  This version of TAP provides limited VOSpace integration, although better  
1258  support for VOSpace is planned for a later version following further  TODO
1259  implementation experience. In this version, one may specify an upload table  
1260  using a URI to a table stored in a VOSpace, e.g.:  \section{Use of STC-S in TAP - deprecated}
1261  \begin{verbatim}  
1262  HTTP POST http://example.com/tap/async/42  NOTE: The old section 6 is not included from TAP-1.0 since it was informative
1263  UPLOAD=mytable,vos://space/path/votable.xml  and does not belong in this document. If we need to define syntax for
1264  \end{verbatim}  points, circles, and polygons then that should be done in [std:DALI], which
1265  The service would resolve the URI, contact the VOSpace, retrieve the table, and  already defines timestamp syntax.
1266  make it visible to the query as TAP\underline{' '}UPLOAD.mytable.  
1267    \section{VOSpace Integration - deprecated}
1268    
1269  A future version of TAP may specify additional use and more integration with  Note: some text moved to the UPLOAD section; may propose DEST parameter for
1270  VOSpace.  outout.
1271    
1272  \section{Use of HTTP}  \section{Use of HTTP - deprecated}
1273  Note: This section is in or belongs in DALI.  Note: This section is in or belongs in DALI.
1274    
1275  \appendix  \appendix
# Line 1440  Line 1278 
1278    
1279  \subsection{Changes from TAP-1.0}  \subsection{Changes from TAP-1.0}
1280    
1281    Restructured the document and removed text that duplicates material from DALI.
1282    Rewrite the overly long introduction with some basic use cases to help define
1283    the scope and tell readers what TAP is supposed to accomplish.
1284    
1285    Made clarifications: restricted allowed table names for UPLOAD, clarified that
1286    multiple UPLOAD pamaters accumulate, deprecated the size column in
1287    TAP\underline{' '}SCHEMA.columns and added advice to quote it as a delimited
1288    identifier, made presence of a TABLE element on VOTable output only required for
1289    successful queries, added optional DALI-examples endpoint (text TBD).
1290    
1291    Defined standardID values for the async and sync resource types and explicitly
1292    allow for multiple of each resource (typically to support authentication). The
1293    fixed paths /async and /sync are still required and are to provide anonymous
1294    query access, which should be compatible with existing services.
1295    
1296  \bibliography{ivoatex/ivoabib}  \bibliography{ivoatex/ivoabib}
1297    

Legend:
Removed from v.2915  
changed lines
  Added in v.2916

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