savetable (Save query results as a table)

The savetable transaction saves the results of a query as a new table. The table is added to the 1010data database hierarchy and may be made accessible to other users.

Query string

The query string in the HTTP header must contain the following parameters:

api
Specify the name of the API transaction.
apiversion
Specify the version of the API that should handle the requested transaction.

For the most up-to-date version, use apiversion=3.

uid
Specify a valid 1010data user name.
pswd
Specify a valid password for the 1010data user name provided to the uid parameter.
Note: The pswd value should be the encrypted password returned from the login transaction.
sid
The session ID for the current API session.

This value is returned by the login transaction and must be provided to every transaction (except login).

kill (optional)
Valid values for kill are as follows:
yes
Terminate the existing session and start a new one.
no
Do not terminate the existing session.

If no session exists, a new one will be created. If a session does exist, an error is returned.

Note: If kill=no and a session is active, the system returns an error.
possess
Log in and possess the existing session.
auth
Authenticate with the system but do not kill, possess, or start any session.

The default is yes.

XML input to server

The savetable transaction must be provided with the following information:

<name>
The content of this element is the full path for the table in the 1010data database hierarchy.

<name> may also contain any of the following optional attributes and corresponding valid values:

mode
mode specifies how the system will respond when a table is sent that has the same name as an existing table.
  • mode="replace" will replace the existing table with the new one.
  • mode="noreplace" will return an error and will not save the new table.
  • mode="append" will append the new data to an existing table with the name specified.

If mode is omitted, the default is noreplace.

materialize
The materialize attribute is used to activate some of the more powerful table-creation features in 1010data, such as segmentation.

To activate these features, use materialize="1".

<title>
Specify the name of the new table.

See <title> (Table title).

<sdesc>
The short description for the new table (optional).

See <sdesc> (Short description of a table).

<ldesc>
The long description for the new table.

See <ldesc> (Long description of a table).

<link>
The link header for the new table (optional).

See <link> (Link header).

<maxdown>
The download limit for the new table (optional).

See <maxdown> (Download limit).

<merge>
A flag indicating whether the table should be able to be merged with other tables (optional).
If you plan to merge the saved table with another table that you save or upload, specify <merge>1</merge>. However, your queries will run faster and use less virtual memory if you specify <merge>0</merge> or omit the <merge> element entirely.
Note: It is currently not possible to append a tabulated table to an existing table with the materialize attribute invoked.
<users>
The access rights for the new table (optional).

See Users Tree.

<modcol>
Modify a column by changing its name, title, and/or display format (optional).
Specify the column you wish to modify with the required name attribute and optionally specify title to change the title and format to change the display format (See <th> (Meta information for one column).) Also, a new name can be provided as the value of <modcol> XML element. See the example below for more clarity.
Note: <modcol> cannot be used with materialize=1.
<segmentation>
Specifies which column or columns by which to segment a table. This option requires materialize=1.
The required cols attribute of <segmentation> specifies the columns to segment along. If the optional sort attribute is set to 1, the segments will also be sorted along the same columns. Specify segmentation as follows:
<segmentation cols="[COL_1],[COL_2],...[COL_N]" sort="1"/>
<links>
links can contain an arbitrary number of <link> elements, which act as a wrapper used by the prelink and addtab transactions to create a persistent link between two tables along a set of columns or to bring some subset of columns from a second table into the base table. It’s basic syntax is given as follows:
<links>            
  <link table2="foreign.table.name" col="col1,col2" col2="fcol1,fcol2" denormalize="1"   keepcols=""   suffix=""/>
</links>

This syntax specifies that the table referenced by the table2 attribute within the <link> element should be joined along the columns indicated in the col and col2 attributes. If the denormalize attribute is 1, columns from the foreign table are denormalized into the base table, otherwise a prelink between the two tables is generated.

<sort>
The <sort> element is used to sort individual segments along the columns enumerated in the required cols attribute. This is in contrast to specifying a segmentation with sort=1 in the <segmentation> element, where the sort is applied across all segmented columns. Basic syntax for <sort> is as follows:
<sort cols="[COL_1], [COL_2],...COL_N"/>
Note: name is the only required element of the list of above. The others are optional.

XML response from server

A savetable transaction successfully received by the API will return the following information:

<rc>
The return code from system.
<msg>
The message the system returns.

Query string example

https://www2.1010data.com/gw.k?api=savetable&apiversion=3&uid=$UID&pswd=$PSWD&sid=$SID

XML input example

<in>
  <name mode="replace" materialize="1">demos.apistock</name>
  <title>Materialized Title</title>
  <users type="list">
      <user>sandy</user>
  </users>
  <segmentation cols="symbol" sort="1" />
  <links>
      <link table2="demos.apicompanynames" col="symbol" col2="symbol" denormalize="1" 
      keepcols="1" suffix="foo" />
  </links>
</in>

XML response example

<out>
    <rc>0</rc>
    <msg>Saved table myfolder.mytable</msg>
</out>