`run`

Run (and optionally save data for) an MDB query.

URL

https://[host]/[1010-version]/api/run

Use this URL to test your MDB query in the editor. Click Submit to view the results of your MDB query below the text editor as HTML.

Click text or json in the upper right corner to view your query results as a simple text table or as JSON.

Note that the /api/run endpoint supports running only a single query at a time. To run multiple queries, you should instead instantiate the api/run endpoint by posting to api/new/run. The api/new/run endpoint creates an instance of an MDB query and returns a number called a tag, which represents a new endpoint with its own state. You reference the instance with the endpoint api/[tag_number].

Methods

POST

Parameters

@xml: A string containing a <dynamic> query to be run.
@savetable: If you want to save the results of the query as a table, a string containing the path name of the table. The default value is "" (do not save the table). You must have write permissions to the path you specify.
@replace: A boolean value. Set to 0 to not replace the table if it already exists, and set to 1 to replace the existing table. If set to 0 and the table exists, you will get an error message.
@title: A string containing the title of the saved table.

Response

The result of your MDB query, which can be formatted as HTML, text, or JSON.

Fetching Result Data and Metadata

The run endpoint contains an index widget, so you can retrieve metadata and column information from your MDB query. The index widget is @index, which can be abbreviated as !.

You can use the following methods to refine your data:

!cols (@index/cols): Returns a dictionary of metadata about the columns, including column name, label, description, type, fixed/not fixed, width, and format. The values are the same as the corresponding values in <columns/> in macro code. For more information, see <columns/> in the 1010data Reference Manual.
!rows (@index/rows): Returns the total number of rows in the query
!data?range_=x&to_=y (@index/data?range_=x&to_=y): Query all rows or a range of rows. ?range is optional. x and y represent row numbers. The first row is row 0. Note that this breaks from the Macro Language convention, where i_() (row number) begins at 1.
!head (@index/head): Returns the result of !cols, !rows, and !data?range_=0&to_=500 (the to_ number is subject to change).
!data:json.rows: By specifying json.rows as the output, the client application can obtain JSON data in row-major format instead of the default column-major format.
!data:json.keyed: By specifying json.keyed as the output, the client application can obtain data as a list of dictionaries. Each row becomes a dictionary mapping the names of columns in the table to the values for that row.
!stop?force_=1: Attempts to stop the running query. The ?force_=1 argument is optional.

User Interface Example

The following MDB query instance uses default.test.solar and returns a table of the planets that orbit the sun, displaying the columns name, vol, mass, and dist, sorted by distance from the sun.

Click the json link in the upper right corner to return your query results as JSON, as follows:

{"name":
      ["Mercury","Venus","Earth","Mars","Jupiter",
       "Saturn","Uranus","Neptune"],
"type":
      ["planet","planet","planet","planet","planet",
       "planet","planet","planet"],
"vol":
      [60,928,1083,163,1431280,827130,68340,62540],
"mass":
      [330,4868,59736,6417,1898600,568460,86832,102430],
"dist":
      [57900000,108200000,149600000,227900000,778300000,1427000000,
       2871000000,4497100000]}

You can also click the text link to see your query results as a simple text table.

curl Example: Return selected rows of a query

In the following example, curl sends a command to run an MDB query and then return rows 2 through 4 of the query:

$ curl -s -b cookie.txt -d xml='<base table="default.test.solar"/>'
   'https://www2.1010data.com/beta-latest/api/run/!data:text?range_=2&to_=4'

This command returns the following rows of the table:

name     type     orbits      rkm      vol       mass     dist
-------  -------  -------     ------   -------   -------  -----------
Saturn    planet    Sun       58232    827130    568460   1427000000
Uranus    planet    Sun       25362    68340     86832    2871000000

curl Example: Return JSON rows instead of columns

In the following example, curl sends a command to run an MDB query and then return rows 2 through 4 of the query in row-major JSON format instead of the default column-major format:

$ curl -s -b cookie.txt -d xml='<base table="default.test.solar"/>'
   'https://www2.1010data.com/beta-latest/api/run/!data:json.rows?range_=2&to_=4'

This commands returns the following JSON output:

{"cols":
    ["name","type","orbits","rkm","vol","mass","dist"],
"rows":
    [["Saturn","planet","Sun",58232,827130,568460,1427000000],
    ["Uranus","planet","Sun",25362,68340,86832,2871000000]]}

curl Example: Return column metadata

In the following example curl sends a command to return the column metadata for the table default.test.solar:

curl -s -b cookie.txt -d xml='<base table="default.test.solar"/>'
'https://www2.1010data.com/beta-latest/api/run/!cols:text'

This command returns the following column metadata:

name    label   desc  type  fixed  width  format                
 ------- ------- ----- ----- ------ ------ ----------------------
 name       name       a          0      8      type:char;width:8
 type       type       a          0     12     type:char;width:12
 orbits   orbits       a          0      7      type:char;width:7
 rkm         rkm       i          0      5  type:nocommas;width:5
 vol         vol       i          0      7  type:nocommas;width:7
 mass       mass       i          0      7  type:nocommas;width:7
 dist       dist       f          0      7  type:nocommas;width:7

curl Example: Save query results as a table

In the following curl example, the run endpoint saves the query as a table, using the path specified in the savetable parameter:

curl -s -b cookie.txt -d xml='<base table="default.test.solar"/>' 
-d savetable='tablepath.table' -d title='MyTable' -d replace=1 
'https://www2.1010data.com/beta-latest/api/run/!data:text'

If you have the proper permissions, this command creates a table in the specified table path with the specified title, and replaces the table with the same path name, if one already exists.