.. index:: single: API pair: service; interface pair: query; manager .. _sec_QueryManager: ************* Query Manager ************* Introduction ============ The Query Manager API provides a uniform HTTP interface to query tabular data in the DL databases via SQL. It also supports management of tables in a DL user’s personal database (:ref:`sec_Mydb`). Anonymous access is available for synchronous queries of public data sets. Authorized access is required for all other operations. The results of authorized queries may be saved to a user’s virtual storage (VOSpace) or their :ref:`sec_Mydb`. Query results may also be serialized in a number of specified formats, e.g., CSV/TSV, FITS binary. Note: this description of the Query Manager is intended for developers - a revised version for users is a TO DO. Query Manager API ================= The Query Manager API defines a number of service endpoints, URLs where the service can be accessed by a client application, to provide specific functionalities. +-----------------------------------+-----------------------------+--------------------------------------------------------------+ | Endpoint | Params | Description | +===================================+=============================+==============================================================+ | :ref:`sec_QueryManager_query` | adql, out, ofmt, uri, async | Submit a query | +-----------------------------------+-----------------------------+--------------------------------------------------------------+ | :ref:`sec_QueryManager_status` | jobid | Check the status of an asynchronous query | +-----------------------------------+-----------------------------+--------------------------------------------------------------+ | :ref:`sec_QueryManager_results` | jobid | Retrieve the results of an asynchronous query | +-----------------------------------+-----------------------------+--------------------------------------------------------------+ | :ref:`sec_QueryManager_available` | user, service, dataid | Check whether a user has access to particular data | +-----------------------------------+-----------------------------+--------------------------------------------------------------+ | :ref:`sec_QueryManager_metadata` | service, dataid | Returns the metadata associated with a specific service | +-----------------------------------+-----------------------------+--------------------------------------------------------------+ | :ref:`sec_QueryManager_create` | table, schema | Create a table in MyDB | +-----------------------------------+-----------------------------+--------------------------------------------------------------+ | :ref:`sec_QueryManager_delete` | table | Delete a table in MyDB | +-----------------------------------+-----------------------------+--------------------------------------------------------------+ | :ref:`sec_QueryManager_rename` | source, target | Rename a table in MyDB | +-----------------------------------+-----------------------------+--------------------------------------------------------------+ | :ref:`sec_QueryManager_copy` | source, target | Copy a table in MyDB | +-----------------------------------+-----------------------------+--------------------------------------------------------------+ | :ref:`sec_QueryManager_list` | table | List a table in MyDB | +-----------------------------------+-----------------------------+--------------------------------------------------------------+ | :ref:`sec_QueryManager_sia` | | Perform a SIA query | +-----------------------------------+-----------------------------+--------------------------------------------------------------+ .. _sec_QueryManager_query: /query ------ This sends the specified query to the Data Lab. It takes the following arguments: *adql* - the query to submit against the Data Lab data sets [optional] *out* - the location which will receive the output results. This can be a local filename, a VOSpace (vos://someLocation) or MyDB table (mydb://some.table). If no output location is specified then the output is returned directly [optional] *ofmt* - the output format of the results. Supported formats are: FITS (binary), CSV, and ASCII. [optional] *uri* - the URI of a service from which to retrieve data. Note that saving the result in MyDB is not yet supported [optional] *async* - a boolean indicating whether the query is to be run synchronously or asynchronously [optional] .. _sec_QueryManager_status: /status ------- This returns the status of the specified asynchronous query. It takes the following arguments: *jobid* - the identifier of the asynchronous query job [required] .. _sec_QueryManager_results: /results -------- This retrieves the results of an asynchronous query once it has completed. It takes the following arguments: *jobid* - the identifier of the asynchronous query job [required] .. _sec_QueryManager_available: /available ---------- This checks whether a user has access to a particular data set and service. It takes the following arguments: *user* - the user identifier [required] *service* - the type of service: tap, scs, sia, ssa [required] *dataid* - the identifier of the data set [required] .. _sec_QueryManager_metadata: /metadata --------- This returns the metadata for the specific service serving the particular data set. It takes the following arguments: *service* - the type of service: tap, scs, sia, ssa [required] *dataid* - the identifier of the data set [required] .. _sec_QueryManager_create: /create ------- This creates the specified table in a user’s MyDB. It takes the following arguments: *table* - the name of the table to be created [required] *schema* - the SQL schema (file or string) for table [required] If the schema is a file then the service request must be an HTTP POST. .. _sec_QueryManager_delete: /delete ------- This deletes the specified table in a user’s MyDB. It takes the following arguments: *table* - the name of the table to be deleted [required] .. _sec_QueryManager_rename: /rename ------- This renames the specified table to the new name. Note that indexes are not copied. It takes the following arguments: *source* - the table to rename [required] *target* - the new name of the table [required] .. _sec_QueryManager_copy: /copy ----- This copies the specified table to a new one. Note that indexes are not copied. It takes the following arguments: *source* - the table to copy from [required] *target* - the table to copy to [required] .. _sec_QueryManager_list: /list ----- This lists the tables in the user’s MyDB. If a table is specified then the schema for the table is returned. It takes the following arguments: *table* - the table whose schema to return [optional] .. _sec_QueryManager_sia: /sia ---- This makes a Simple Image Access query of the Data Lab. .. todo:: Write this section.