1. technology and computing
2. software
3. databases

1010data API Reference Manual
(212) 405.1010 | [email protected] | Follow: @1010data | www.1010data.com
1010data API Reference Manual | Contents | 2
Contents
1010data Application Program Interface...................................................4
login (Start the session)...................................................................................................................... 6
logout (End the session)..................................................................................................................... 7
dir (List the contents of a directory)....................................................................................................7
listdir (List the contents of a directory)............................................................................................... 9
getdir (Get information about a directory).........................................................................................12
putdir (Modify directory information)..................................................................................................14
mkdir (Create a directory)................................................................................................................. 16
gettab (Get information about a table)..............................................................................................17
tabinfo (Get information about a table)............................................................................................. 20
puttab (Modify table information)...................................................................................................... 22
query (Apply a query to a table).......................................................................................................26
getdata (Get the results of a query)................................................................................................. 27
querydata (Apply a query to a table and get results)....................................................................... 31
savefile (Save query results as a file).............................................................................................. 32
savetable (Save query results as a table)........................................................................................ 34
upload (Upload table)........................................................................................................................ 36
merge (Merge table)..........................................................................................................................38
droptable (Delete table).....................................................................................................................39
dropdir (Delete directory)...................................................................................................................40
drop (Delete several tables or folders)............................................................................................. 41
move (Move several tables or folders)............................................................................................. 43
order (Order the items in a directory)............................................................................................... 44
clear (Clear the cache)..................................................................................................................... 45
session (Set session parameters).....................................................................................................46
PowerLoader Transactions.......................................................................49
addtab (Load a large table).............................................................................................................. 49
status (Status of the addtab API)..................................................................................................... 52
convert (Convert a legacy spec)....................................................................................................... 53
edittab (Edit a table)..........................................................................................................................55
validate (Validate a table)................................................................................................................. 56
Table Tree...................................................................................................60
<table> (Top-level wrapper for table tree)........................................................................................ 61
<title> (Table title)............................................................................................................................. 61
<sdesc> (Short description of a table)..............................................................................................62
<ldesc> (Long description of a table)............................................................................................... 62
<links> (Top-level wrapper for links).................................................................................................63
<link> (Link header).......................................................................................................................... 64
<maxdown> (Download limit)............................................................................................................ 64
<segmentation> (Specify the segmentation of a table).................................................................... 64
<totals> (Table contains tabulation results)...................................................................................... 65
<cols> (Metadata for all columns).....................................................................................................65
<th> (Meta information for one column)........................................................................................... 65
<data> (Table data)...........................................................................................................................66
<tr> (Data for one row)..................................................................................................................... 67
<td> (One cell of data in a table)..................................................................................................... 67
©
2014 1010data, Inc. All rights reserved.
1010data API Reference Manual | Contents | 3
Users Tree.................................................................................................. 68
<users> (Top-level wrapper for users tree)...................................................................................... 68
<user> (User entry)........................................................................................................................... 69
Field Data Types........................................................................................70
Field Format Types................................................................................... 71
Deprecated Transactions.......................................................................... 72
rmdir (Delete a directory).................................................................................................................. 72
rmtab (Delete a table)....................................................................................................................... 73
prelink (Prelink tables).......................................................................................................................74
timeseries (Merge tables using time series)..................................................................................... 75
©
2014 1010data, Inc. All rights reserved.
1010data API Reference Manual | 1010data Application Program Interface | 4
1010data Application Program Interface
The 1010data Application Program Interface (API) is a facility whereby a client application running on a
user's machine can access and query data on the 1010data database servers. This allows for unlimited
customization of the application while taking advantage of 1010data's database management services and
fast database engine. The API uses HTTP and XML and is compatible with any client application written in
a language that supports HTTP transactions (such as Java, Visual Basic, C++, Python and PERL.)
Prerequisites
A working knowledge of the 1010data database service and user interface is assumed. In particular, the
reader is expected to be familiar with table operations (e.g., select rows, sort, tabulate) and the 1010data
Macro Language. To use the API, a valid 1010data username and password is required, and the username
must be authorized to use the API.
Transactions
Transactions through the API are a series of HTTP(S) POSTs. The client-to-server message consists of
a header followed by contents, where the two are separated by "
". Among other things, the
header must contain a query string that specifies the type of API transaction and certain information that
identifies the user. The contents, in XML format, contains the transaction details and possibly other data.
(For some transactions, the contents may be empty.) An example of such a message is as follows:
Note that the query string on the first line specifies that this is a "query" transaction and includes the user's
username (
) and password (
). The message must always contain a lowercase "
",
"
", "
", or "
", and the
must be set to the length
(number of characters) of the XML contents.
The response from the server is also in the form of a header followed by XML contents. An example of
such a message is as follows:
1010data API Reference Manual | 1010data Application Program Interface | 5
The information in the contents depends on the type of transaction, but it always includes the following two
elements:
The error codes are described in detail in the next section.
Error Codes
A nonzero value in the
tag indicates there was an error in processing your transaction. The error can
be related to the syntax or semantics of the XML content submitted to the server. The codes are designed
to give programs the ability to gracefully deal with errors without having to interpret the contents of the
tag. The universe of possible error codes is as follows:
1010data API Reference Manual | 1010data Application Program Interface | 6
The query string and XML input and output for each transaction are described in detail in the following
sections.
login (Start the session)
The
transaction starts a session and must precede all other transactions.
Query String
The query string in the HTTP header must contain the following parameters:
Connection String Value
Variable
[USERNAME]
[PASSWORD]
or
(optional)
If
and a session already exists for the specified username (i.e., the user is already logged in),
an error message is returned (see "XML Response from Server" below). If
or if
is not
specified, a new session is started and any existing session is logged out.
Query String Example
XML Input to Server
No XML input required.
XML Response from Server
The session ID and encrypted password are used in subsequent transactions. If the login is not successful,
only the return code and error message are returned. A successful result contains the following elements:
XML Element
Returned
Description of Returned Element Content
Return code
Session ID
Encrypted password
Message from the server
The version of 1010data you are using
XML Response Example
1010data API Reference Manual | 1010data Application Program Interface | 7
logout (End the session)
The
transaction ends the session.
Query String
The query string in the HTTP header must contain the following parameters:
Connection String Value
Variable
[USERNAME]
[ENCRYPTED PASSWORD] - returned from the
[SESSION ID] - returned from the
or
If
transaction (optional)
(optional)
and a query is processing, the query will be terminated and the session will logout as usual.
Query String Example
XML Input to Server
No XML input required.
XML Response from Server
A successful
produces the following result:
dir (List the contents of a directory)
The
transaction
transaction returns a listing of the contents of a directory (folder).
Query String
The query string in the HTTP header must contain the following parameters:
Connection String Value
Variable
1010data API Reference Manual | 1010data Application Program Interface | 8
Connection String Value
Variable
[USERNAME]
[ENCRYPTED PASSWORD] - returned from the
[SESSION ID] - returned from the
transaction
transaction (optional)
Query String Example
XML Input to Server
The specifications must contain the following element:
XML Element To
Send
Description of Sent Element Content
The full path to the directory in the 1010data database hierarchy
In general, a path has the form:
(similar to a Windows or Unix file-system path but with dots instead of slashes)
XML Input Example
XML Response from Server
A successful result contains the following elements:
XML Element
Returned
Description of Returned Element Content
Return code
Message
Directory listing
The directory listing is returned in the form of a table (see Table Tree on page 60) with one row for each
entry and two columns. The first column contains the name of the entry and the second indicates whether
it is a directory (
) or a table (
). In the event of an error, only the return code and error message are
returned.
XML Response Example
1010data API Reference Manual | 1010data Application Program Interface | 9
listdir (List the contents of a directory)
The
transaction returns a listing of the contents of a directory (folder) and provides more
information than the
transaction.
Query String
The query string in the HTTP header must contain the following parameters:
Connection String Value
Variable
[USERNAME]
[ENCRYPTED PASSWORD] - returned from the
[SESSION ID] - returned from the
transaction
transaction (optional)
Query String Example
XML Input to Server
The specifications must contain the following elements:
XML Element To
Send
Description of Sent Element Content
The full path to the directory in the 1010data database hierarchy
In general, a path has the form:
(similar to a Windows or Unix file-system path but with dots instead of slashes)
1010data API Reference Manual | 1010data Application Program Interface | 10
XML Element To
Send
Description of Sent Element Content
To list the contents of the top level directory ("All Databases"), leave the name blank
("
" or "
").
An optional filter to reduce the number of attributes returned in order to reduce
transmission size (optional)
Provide a list of
Also include a
•
•
elements containing the attributes you want in the results.
attribute, where:
- the operation should apply to parents as well as children
- the operation should apply to children only
XML Input Example
XML Response from Server
A successful response from the server contains the following elements:
XML Element
Returned
Description of Returned Element Content
Return code
Message from the server
Directory information
XML Response Example
A successful
produces the following result:
1010data API Reference Manual | 1010data Application Program Interface | 11
1010data API Reference Manual | 1010data Application Program Interface | 12
getdir (Get information about a directory)
The
transaction returns meta information of a directory.
Query String
The query string in the HTTP header must contain the following parameters:
Connection String Value
Variable
[USERNAME]
[ENCRYPTED PASSWORD] - returned from the
[SESSION ID] - returned from the
Query String Example
XML Input to Server
The specifications must contain the following elements:
transaction
transaction (optional)
1010data API Reference Manual | 1010data Application Program Interface | 13
XML Element To
Send
Description of Sent Element Content
The full path to the directory in the 1010data database hierarchy
In general, a path has the form:
(similar to a Windows or Unix file-system path but with dots instead of slashes)
To list the contents of the top level directory ("All Databases"), leave the name blank
("
" or "
").
An optional filter to reduce the number of attributes returned in order to reduce
transmission size (optional)
Provide a list of
Also include a
•
•
elements containing the attributes you want in the results.
attribute, where:
- the operation should apply to parents as well as children
- the operation should apply to children only
XML Input Example
XML Response from Server
A successful response from the server contains the following elements:
XML Element
Returned
Description of Returned Element Content
Return code
Message from the server
Directory information
The directory metadata is returned as a series of attributes contained within the
attributes are as follows:
XML Element
Returned
element. The
Description of Returned Element Content
ID of the directory
Full path of the directory
Title of the directory as displayed in the UI
Short description of the directory
Long description of the directory
Type of directory
Note: Currently, there is only one directory type:
Is the directory marked as secure?
Returns
or .
.
1010data API Reference Manual | 1010data Application Program Interface | 14
XML Element
Returned
Description of Returned Element Content
Indicates whether the API user is the owner of the directory specified in the
element
Returns
or .
The username of the owner of the directory
Specifies whether the API user can create new items in the directory specified in the
element
Returns
or .
The date and time the directory was created or its attributes last changed
GIF file associated with the directory to be displayed in the UI
Is this directory marked as a favorite for the API user?
Returns
or .
Space-separated list of users and groups who have permission to view the directory
Space-separated list of users and groups who have permission to create tables or
directories inside the directory
The number of visible items that descend from the directory specified in the
element
XML Response Example
A successful
produces the following result:
putdir (Modify directory information)
The
transaction modifies the meta information for a directory (folder).
Query String
The query string in the HTTP header must contain the following parameters:
Connection String Value
Variable
[USERNAME]
[ENCRYPTED PASSWORD] - returned from the
transaction
1010data API Reference Manual | 1010data Application Program Interface | 15
Connection String Value
Variable
[SESSION ID] - returned from the
transaction (optional)
Query String Example
XML Input to Server
The specifications must contain the following elements:
XML Element To
Send
Description of Sent Element Content
The transmission to the 1010data server must be a
the attributes described in the table below.
Include the following attributes with the
element that contains
element:
Note: Any attributes that are omitted will not be modified.
XML Element To
Send
Description of Sent Element Content
The ID of a directory.
The full path of the directory.
The title of the directory as displayed in the UI.
The short description of the directory.
The long description of the directory.
Is the directory marked as secure. Returns
or .
Space separated list of users and groups who have permission to view the
directory.
Who is the owner of the directory? Returns the
.
The GIF file associated with the directory to be displayed in the UI
Space separated list of users and groups who have permission to create tables or
directories inside the directory.
XML Input Example
XML Response from Server
A successful response from the server contains the following elements:
XML Element
Returned
Description of Returned Element Content
Return code
1010data API Reference Manual | 1010data Application Program Interface | 16
XML Element
Returned
Description of Returned Element Content
Message from the server
Directory information
The directory metadata is returned as a series of attributes contained within the
attributes are as follows:
element. The
XML Response Example
A successful
produces the following result:
mkdir (Create a directory)
The
transaction creates a directory. The API will check the permission of the user and create the
directory only if the user calling the transaction is authorized to create the directory in the parent folder.
Query String
The query string in the HTTP header must contain the following parameters:
Connection String Value
Variable
[USERNAME]
[ENCRYPTED PASSWORD] - returned from the
[SESSION ID] - returned from the
transaction
transaction (optional)
Query String Example
XML Input to Server
The specifications must contain the following elements:
XML Element To
Send
Description of Sent Element Content
The full path to the directory in the 1010data database hierarchy
In general, a path has the form:
1010data API Reference Manual | 1010data Application Program Interface | 17
XML Element To
Send
Description of Sent Element Content
(similar to a Windows or Unix file-system path but with dots instead of slashes)
Users authorized to browse the directory
See Users Tree on page 68 for the XML schema.
Users authorized to add content to the directory
See Users Tree on page 68 for the XML schema.
The title of the directory.
XML Input Example
XML Response from Server
A successful
produces the following result:
gettab (Get information about a table)
The
transaction returns metadata about a table. Note that this metadata does not include
information about columns or contents of the table.
Query String
The query string in the HTTP header must contain the following parameters:
Connection String Value
Variable
[USERNAME]
[ENCRYPTED PASSWORD] - returned from the
[SESSION ID] - returned from the
Query String Example
transaction
transaction (optional)
1010data API Reference Manual | 1010data Application Program Interface | 18
XML Input to Server
The specifications must contain the following elements:
XML Element To
Send
Description of Sent Element Content
The full path to the directory in the 1010data database hierarchy
In general, a path has the form:
(similar to a Windows or Unix file-system path but with dots instead of slashes)
To list the contents of the top level directory ("All Databases"), leave the name blank
("
" or "
").
An optional filter to reduce the number of attributes returned in order to reduce
transmission size (optional)
Provide a list of
Also include a
•
•
elements containing the attributes you want in the results.
attribute, where:
- the operation should apply to parents as well as children
- the operation should apply to children only
XML Input Example
XML Response from Server
A successful response from the server contains the following elements:
XML Element
Returned
Description of Returned Element Content
Return code
Message from the server
Table information
The table metadata is returned as a series of attributes contained within the
are as follows:
XML Element
Returned
Description of Returned Element Content
ID of the table
The full path to the table in the 1010data database hierarchy
Type of table
can be one of the following:
•
•
•
•
•
element. The attributes
1010data API Reference Manual | 1010data Application Program Interface | 19
XML Element
Returned
Description of Returned Element Content
•
The output type of the table
can be one of the following:
•
•
•
•
•
•
Indicates whether the table or query has report specifications saved
can be either
or .
Indicates whether the table or query has chart specifications saved
can be either
or .
Title of the table as displayed in the UI
Short description of the table
Long description of the table
A string to be prepended to column headers when linking in to other tables
Number of rows in the table
Number of bytes utilized by the table
Number of segments in the table
Specifies whether the table is accessible for time series functions
can be either
or .
Indicates if the table is accessible
can be either
or .
Specifies whether the table is marked as secure
can be either
or .
Limit to the number of rows a user can download for the table
Indicates whether the API user is the owner of the table specified in the
element
can be either
or .
Username of the owner of the table
The column on which the table is segmented
When the table was created or its attributes last changed
Indicates if this table is marked as a favorite for the API user
can be either
or .
1010data API Reference Manual | 1010data Application Program Interface | 20
XML Element
Returned
Description of Returned Element Content
Space-separated list of users and groups who have permission to view the table
If the table is a query (i.e.,
is
,
,
or
) then the
element will contain
and
elements. Any dependencies on other tables (i.e., links, merges) are available in
the
element, which contains a list of tables references if the table is a Quick Query or a
merged table.
XML Response Example
tabinfo (Get information about a table)
The
transaction returns information about a table.
Query String
The query string in the HTTP header must contain the following parameters:
Connection String Value
Variable
[USERNAME]
[ENCRYPTED PASSWORD] - returned from the
[SESSION ID] - returned from the
Query String Example
XML Input to Server
The specifications must contain the following element:
transaction
transaction (optional)
1010data API Reference Manual | 1010data Application Program Interface | 21
XML Element To
Send
Description of Sent Element Content
The full path to the table in the 1010data database hierarchy
In general, a path has the form:
(similar to a Windows or Unix file-system path but with dots instead of slashes)
The name of a table can be determined by clicking Info > About this Table in the
1010data web interface.
XML Input Example
XML Response from Server
The session ID and encrypted password are used in subsequent transactions. If the login is not successful,
only the return code and error message are returned. A successful result contains the following elements:
XML Element
Returned
Description of Returned Element Content
Return code
Message
Information about the table
The
element (see Table Tree on page 60) contains information about the table. It is
equivalent to the table with zero rows of data (i.e., the
element is empty.) In the event of an error,
only the return code and error message are returned.
XML Response Example
1010data API Reference Manual | 1010data Application Program Interface | 22
puttab (Modify table information)
The
transaction modifies the meta information for a table.
Query String
The query string in the HTTP header must contain the following parameters:
Connection String Value
Variable
[USERNAME]
1010data API Reference Manual | 1010data Application Program Interface | 23
Connection String Value
Variable
[ENCRYPTED PASSWORD] - returned from the
[SESSION ID] - returned from the
transaction
transaction (optional)
Query String Example
XML Input to Server
The specifications must contain the following elements:
XML Element To
Send
Description of Sent Element Content
The "table" element of the 1010data XML specification.
Information for modifying the table should be included in the attributes of the
element.
Descriptions for the attributes are listed in the table below.
Include the following attributes with the
element:
Note: Any attributes that are omitted will not be modified.
XML Element To
Send
Description of Sent Element Content
The ID of the table to modify
The full path to the table in the 1010data database hierarchy
In general, a path has the form:
(similar to a Windows or Unix file-system path but with dots instead of slashes)
The name of a table can be determined by clicking Info > About this Table in the
1010data web interface.
Title of the table as displayed in the UI
Short description of the table
Long description of the table
Specifies if the table is marked as secure
can be
or .
The owner of the table
The GIF file associated with the table to be displayed in the UI
Space-separated list of users and groups who have permission to view the table
Space-separated list of users and groups who have permission to create tables or
directories inside the table
1010data API Reference Manual | 1010data Application Program Interface | 24
XML Input Example
XML Response from Server
A successful response from the server contains the following elements:
XML Element
Returned
Description of Returned Element Content
Return code
Message from the server
New table information
See XML response of gettab (Get information about a table) on page 17.
The table metadata is returned as a series of attributes contained within the
are as follows:
XML Element
Returned
element. The attributes
Description of Returned Element Content
ID of the table
The full path to the table in the 1010data database hierarchy
Type of table
can be one of the following:
•
•
•
•
•
•
The output type of the table
can be one of the following:
•
•
•
•
•
•
Indicates whether the table or query has report specifications saved
can be either
or .
Indicates whether the table or query has chart specifications saved
can be either
or .
1010data API Reference Manual | 1010data Application Program Interface | 25
XML Element
Returned
Description of Returned Element Content
Title of the table as displayed in the UI
Short description of the table
Long description of the table
A string to be prepended to column headers when linking in to other tables
Number of rows in the table
Number of bytes utilized by the table
Number of segments in the table
Specifies whether the table is accessible for time series functions
can be either
or .
Indicates if the table is accessible
can be either
or .
Specifies whether the table is marked as secure
can be either
or .
Limit to the number of rows a user can download for the table
Indicates whether the API user is the owner of the table specified in the
element
can be either
or .
Username of the owner of the table
The column on which the table is segmented
When the table was created or its attributes last changed
Indicates if this table is marked as a favorite for the API user
can be either
or .
Space-separated list of users and groups who have permission to view the table
XML Response Example
A successful
produces the following result:
1010data API Reference Manual | 1010data Application Program Interface | 26
query (Apply a query to a table)
The
transaction applies a query to a table. A query is essentially a transformation on the table that
selects a subset of its rows, reorders rows based on one or more sort criteria, summarizes the data, and so
on. The result is conceptually another table. Once a query is set using the
transaction, the values in
the result table may be retrieved with the
transaction.
Query String
The query string in the HTTP header must contain the following parameters:
Connection String Value
Variable
[USERNAME]
[ENCRYPTED PASSWORD] - returned from the
[SESSION ID] - returned from the
transaction
transaction (optional)
Query String Example
XML Input to Server
The specifications must contain the following elements:
XML Element To
Send
Description of Sent Element Content
The full path to the table in the 1010data database hierarchy
A series of query operations in the XML macro language used on the Edit Actions
page of the 1010data user interface (optional)
If
is omitted, the result of the query will be the original table.
If
contains one or more
operations, the
transaction takes them into account (i.e.,
the columns reported in the result will be only those columns selected in the
operations, and
they will appear in the order specified in the
operations).
XML Input Example
1010data API Reference Manual | 1010data Application Program Interface | 27
XML Response from Server
A successful response from the server contains the following elements:
XML Element
Returned
Description of Returned Element Content
Return code
Message from the server
Number of rows in result table
Information about columns of result table
The
element (see Table Tree on page 60) essentially describes the columns of the result. It
is equivalent to the result table with zero rows of data (i.e. the
element is empty.) The table tree
does not contain
,
,
,
or
. In the event of an error, only the
return code and error message are returned.
XML Response Example
A successful
produces the following result:
getdata (Get the results of a query)
The
transaction retrieves the results of a query. More precisely,
the result table defined by a
transaction.
retrieves the values in
Query String
The query string in the HTTP header must contain the following parameters:
Connection String Value
Variable
[USERNAME]
[ENCRYPTED PASSWORD] - returned from the
transaction
1010data API Reference Manual | 1010data Application Program Interface | 28
Connection String Value
Variable
[SESSION ID] - returned from the
transaction (optional)
Query String Example
XML Input to Server
The specifications must contain the following elements:
XML Element To
Send
Description of Sent Element Content
The column(s) to be retrieved
This element must contain one or more
elements. Each identifies one
column and contains the name by which the column is referenced in formulas and
query operations.
The row(s) to be retrieved (optional)
must include the attribute
specification:
, which indicates the form of the row
•
•
allows a relative selection (e.g., next 10 rows)
allows an absolute selection (e.g., rows 10-20)
For
, the
Note:
For
element has the form:
is required if
.
, the form is:
Note:
and
are required if
.
If not specified, all rows are retrieved.
The data format for the result (XML or character-separated)
must include the
The
attribute and may include the
attribute indicates the format type (
or
If
, the
If
, it may contain the following elements:
•
•
attribute.
).
element has no contents.
- Character with which to separate columns (optional)
- Character with which to separate rows (optional)
If not specified, the column separator is a comma, and the line separator is a
newline (
).
The
attribute indicates whether the data values should be
.
or
Raw values are a simple representations of the data, while formatted values are the
way the data appears in a table view in the user interface. Examples of raw values
1010data API Reference Manual | 1010data Application Program Interface | 29
XML Element To
Send
Description of Sent Element Content
are
,
formatted values might be
, and
,
, and
If
and
,
specified, XML data with raw formatting is returned.
, while the corresponding
.
is optional. If not
XML Input Examples
XML Input Example 1: Relative row specification; XML
XML Input Example 2: Absolute row specification; tab-separated; raw values
XML Input Example 3: Absolute row specification; comma-separated; formatted
values
1010data API Reference Manual | 1010data Application Program Interface | 30
XML Response from Server
A successful response from the server contains the following elements:
XML Element
Returned
Description of Returned Element Content
Return code
Message from the server
The
element (see Table Tree on page 60) contains the data for the specified columns and
rows along with information about each column. (It does not contain
,
,
,
, or
.) Note that the
element in
will differ from the query response
if your
is set to
. Specifically, all the columns will report that they have been
converted to alphanumeric, which is what happens behind the scenes to properly format the data.
XML Response Examples
Example 1: XML
Example 2: Tab-separated; raw values
1010data API Reference Manual | 1010data Application Program Interface | 31
In this example, the
represents a
character.
Note: The
element contains a
section that contains the data
in row-major order. The first row of data contains the column headers. In
the event of an error, only the return code and error message are returned.
Example 3: Comma-separated; formatted values
Note: The
element contains a
section that contains the data
in row-major order. The first row of data contains the column headers. In
the event of an error, only the return code and error message are returned.
querydata (Apply a query to a table and get results)
The
single
transaction applies a query to a table and gets the results as if you called a query and a
transaction.
takes the union of parameters from
and
respectively and returns the union of
results from both
and
.
is convenient and useful when you know the resulting
dataset will be smaller than your maximum allowed download from a single transaction. Otherwise, you will
still have to subsequently call
to receive all of the results.
Query String
The query string in the HTTP header must contain the following parameters:
Connection String Value
Variable
[USERNAME]
[ENCRYPTED PASSWORD] - returned from the
[SESSION ID] - returned from the
transaction
transaction (optional)
1010data API Reference Manual | 1010data Application Program Interface | 32
Query String Example
XML Input to Server
The specifications must contain the following elements:
See XML input to
(query (Apply a query to a table) on page 26) and
(getdata (Get the
results of a query) on page 27), as the
transaction requires the input of both
and
.
XML Response from Server
A successful
XML Element
Returned
contains the following elements:
Description of Returned Element Content
Return code
Message from the system
Number of rows in result table
Information about columns of result table and the resulting data
savefile (Save query results as a file)
The
transaction saves the results of a query as a file in your 1010data FTP folder. The file can
then be downloaded via FTP.
Note: To use this transaction, you must be authorized for FTP downloads.
Query String
The query string in the HTTP header must contain the following parameters:
Connection String Value
Variable
[USERNAME]
[ENCRYPTED PASSWORD] - returned from the
[SESSION ID] - returned from the
Query String Example
XML Input to Server
The specifications must contain the following elements:
transaction
transaction (optional)
1010data API Reference Manual | 1010data Application Program Interface | 33
XML Element To
Send
Description of Sent Element Content
The name of the result file
If a file already exists with that name, it will be replaced.
The meta information to include in the file (optional)
must contain one or more
of information.
Each
element must include attribute
following values:
•
•
elements, each identifying one type
and
may have one of the
- Column headers
- Column names
If not specified, no meta information is included in the file.
The data format for the result (optional)
has no attributes and may contain the following elements:
•
•
- Character with which to separate fields (columns)
- Character with which to separate records (rows)
If not specified, the column separator is a comma, and the line separator is newline
(
).
is required; the others are optional.
XML Input Example
XML Response from Server
A successful
XML Element
Returned
contains the following elements:
Description of Returned Element Content
Return code
Message from the system
XML Response Example
1010data API Reference Manual | 1010data Application Program Interface | 34
savetable (Save query results as a table)
The
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:
Connection String Value
Variable
[USERNAME]
[ENCRYPTED PASSWORD] - returned from the
[SESSION ID] - returned from the
transaction
transaction (optional)
Query String Example
XML Input to Server
The specifications must contain the following elements:
XML Element To
Send
Description of Sent Element Content
The contents of this element is the full path for the new table in the 1010data
database hierarchy
may include optional attribute
. If a table already exists by this name
and
, the table will be replaced. If
, an
error message will be returned. If you want to append the data to the end of an
existing table, specifying
will insert the records from the results
for those columns whose names and types are compatible with the table specified
in
. If mode is omitted, the default is
.
The title for the new table (optional)
See <title> (Table title) on page 61.
The short description for the new table (optional)
See <sdesc> (Short description of a table) on page 62.
The long description for the new table (optional)
See <ldesc> (Long description of a table) on page 62.
The link header for the new table (optional)
See <link> (Link header) on page 64.
The download limit for the new table (optional)
See <maxdown> (Download limit) on page 64.
1010data API Reference Manual | 1010data Application Program Interface | 35
XML Element To
Send
Description of Sent Element Content
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
. However, your queries will run faster and use less
virtual memory if you specify
or omit the
element
entirely.
The access rights for the new table (optional)
See Users Tree on page 68.
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) on page 65.) Also, a new name can
be provided as the value of
XML element. See the example below for
more clarity.
is required; the others are optional.
XML Input Example
XML Response from Server
A successful
XML Element
Returned
contains the following elements:
Description of Returned Element Content
Return code
Message from the system
XML Response Example
1010data API Reference Manual | 1010data Application Program Interface | 36
upload (Upload table)
The
transaction uploads a table from the client machine to the 1010data database servers. The
table is added to the 1010data database hierarchy and may be made accessible to other users. There
is a 5 MB limit on the size of the input for this transaction. For large tables, its recommended to use the
PowerLoader API.
Query String
The query string in the HTTP header must contain the following parameters:
Connection String Value
Variable
[USERNAME]
[ENCRYPTED PASSWORD] - returned from the
[SESSION ID] - returned from the
transaction
transaction (optional)
Query String Example
XML Input to Server
The specifications must contain the following elements:
XML Element To
Send
Description of Sent Element Content
The table information in the form of a table tree (see Table Tree on page 60)
The name attribute of the
element optionally specifies the desired location
of the table in the 1010data database hierarchy (see also
below). The
parent directory must exist and the user must be authorized to add tables to it.
,
,
,
, and
are all optional.
(optional)
The name of the table
This element is ignored if the
attribute of the
element is specified. If
the
attribute of the
element is omitted, the contents of this element
specifies the full path for the new table in the 1010data database hierarchy.
may include optional attribute
. If a table already exists by this name
and
, the table will be replaced. If
, an
error message will be returned. If you want to append the data to the end of an
existing table, specifying
will insert the records from the results
for those columns whose names and types are compatible with the table specified
in
. If mode is omitted, the default is
.
A flag indicating whether the table should be able to be merged with other tables
If you plan to merge the uploaded table with another table that you upload or save,
specify
. However, your queries will run faster and use less
virtual memory if you specify
or omit the
element
entirely.
1010data API Reference Manual | 1010data Application Program Interface | 37
XML Element To
Send
Description of Sent Element Content
(optional) The access rights for the new table (see Users Tree on page 68)
If
is required;
is omitted, only the uploading user will have access to the table.
and
are optional.
XML Input Example
XML Response from Server
A successful
XML Element
Returned
contains the following elements:
Description of Returned Element Content
Return code
Message from the system
XML Response Example
1010data API Reference Manual | 1010data Application Program Interface | 38
merge (Merge table)
The
transaction creates a new table by combining one or more existing tables. The table is added
to the 1010data database hierarchy and may be made accessible to other users.
The tables are combined by appending all their rows together (i.e., the new table has similar columns to
the original tables but has as many rows as the sum of the rows of the original tables). The original tables
must have some columns in common, and each of those columns must have the same data type and
other attributes (NA values, alphabetic case, etc.) in all the tables. If some columns do not appear in all the
tables, those columns are not included in the new table.
Query String
The query string in the HTTP header must contain the following parameters:
Connection String Value
Variable
[USERNAME]
[ENCRYPTED PASSWORD] - returned from the
[SESSION ID] - returned from the
transaction
transaction (optional)
Query String Example
XML Input to Server
The specifications must contain the following elements:
XML Element To
Send
Description of Sent Element Content
The table(s) to be combined.
must contain one or more
elements. Each identifies one table and
contains its full path in the 1010data database hierarchy.
In general, a path has the form:
(similar to a Windows or Unix file-system path but with dots instead of slashes)
The name of a table can be determined by clicking Info > About this Table in the
1010data web interface.
The contents of this element is the full path for the new table in the 1010data
database hierarchy. The parent directory must exist and the user must be
authorized to add tables to it.
may include optional attribute
. If a table already exists by this name
and
, the table will be replaced. If
, an error
message will be returned. If
is omitted, the default is
.
The title for the new table (see <title> (Table title) on page 61).
1010data API Reference Manual | 1010data Application Program Interface | 39
XML Element To
Send
Description of Sent Element Content
The short description for the new table (see <sdesc> (Short description of a table)
on page 62).
The long description for the new table (see <ldesc> (Long description of a table) on
page 62).
The link header for the new table (see <link> (Link header) on page 64).
The download limit for the new table (see <maxdown> (Download limit) on page
64).
The access rights for the new table (see Users Tree on page 68).
and
are required; the others are optional.
XML Input Example
XML Response from Server
A successful
XML Element
Returned
contains the following elements:
Description of Returned Element Content
Return code
Message from the system
XML Response Example
droptable (Delete table)
The
transaction deletes a table from the 1010data database servers. All information about the
table, including all of its data, is lost. The user must be authorized to delete the table.
Query String
The query string in the HTTP header must contain the following parameters:
1010data API Reference Manual | 1010data Application Program Interface | 40
Connection String Value
Variable
[USERNAME]
[ENCRYPTED PASSWORD] - returned from the
[SESSION ID] - returned from the
transaction
transaction (optional)
Query String Example
XML Input to Server
The specifications must contain the following elements:
XML Element To
Send
Description of Sent Element Content
The full path to the table in the 1010data database hierarchy.
XML Input Example
XML Response from Server
A successful
XML Element
Returned
contains the following elements:
Description of Returned Element Content
Return code
Message from the system
XML Response Example
dropdir (Delete directory)
The
transaction deletes a directory from the 1010data database servers. All information about
the folder, including all of its data, is lost. The user must be authorized to delete the directory.
Query String
The query string in the HTTP header must contain the following parameters:
Connection String Value
Variable
1010data API Reference Manual | 1010data Application Program Interface | 41
Connection String Value
Variable
[USERNAME]
[ENCRYPTED PASSWORD] - returned from the
[SESSION ID] - returned from the
transaction
transaction (optional)
Query String Example
XML Input to Server
The specifications must contain the following elements:
XML Element To
Send
Description of Sent Element Content
The full path to the directory in the 1010data database hierarchy
In general, a path has the form:
(similar to a Windows or Unix file-system path but with dots instead of slashes)
XML Input Example
XML Response from Server
A successful
XML Element
Returned
contains the following elements:
Description of Returned Element Content
Return code
Message from the system
XML Response Example
drop (Delete several tables or folders)
The
transaction deletes any number of tables and directories from the 1010data database servers.
All information about the table, including all of its data, is lost. The user must be authorized to delete the
items.
Query String
The query string in the HTTP header must contain the following parameters:
1010data API Reference Manual | 1010data Application Program Interface | 42
Connection String Value
Variable
[USERNAME]
[ENCRYPTED PASSWORD] - returned from the
[SESSION ID] - returned from the
transaction
transaction (optional)
Query String Example
XML Input to Server
The specifications must contain the following elements:
XML Element To
Send
Description of Sent Element Content
A list of
to be deleted.
can contain paths or IDs.
XML Input Example
XML Response from Server
A successful
XML Element
Returned
contains the following elements:
Description of Returned Element Content
Return code
If
is nonzero, it means one or more of the drops did not work.
Message from the system
The result codes and messages for each of the items dropped
Statuses contains a list of
XML Element
Returned
elements with a
attribute and the following elements:
Description of Returned Element Content
Return code
Message from the system
XML Response Example
1010data API Reference Manual | 1010data Application Program Interface | 43
move (Move several tables or folders)
The
transaction moves any number of tables from anywhere in the folder hierarchy to a single
directory.
Query String
The query string in the HTTP header must contain the following parameters:
Connection String Value
Variable
[USERNAME]
[ENCRYPTED PASSWORD] - returned from the
[SESSION ID] - returned from the
transaction
transaction (optional)
Query String Example
XML Input to Server
The specifications must contain the following elements:
XML Element To
Send
Description of Sent Element Content
A list of
to be moved.
XML Input Example
XML Response from Server
A successful
contains the following elements:
can contain paths or IDs.
1010data API Reference Manual | 1010data Application Program Interface | 44
XML Element
Returned
Description of Returned Element Content
Return code
If
is nonzero, it means one or more of the moves did not work.
Message from the system
The result codes and messages for each of the items moved
Statuses contains a list of
XML Element
Returned
elements with a
attribute and the following elements:
Description of Returned Element Content
Return code
Message from the system
XML Response Example
order (Order the items in a directory)
The
transaction orders the items in a directory. Note that directories and tables can not be
interspersed with one another.
Query String
The query string in the HTTP header must contain the following parameters:
Connection String Value
Variable
[USERNAME]
[ENCRYPTED PASSWORD] - returned from the
[SESSION ID] - returned from the
Query String Example
XML Input to Server
The specifications must contain the following elements:
transaction
transaction (optional)
1010data API Reference Manual | 1010data Application Program Interface | 45
XML Element To
Send
Description of Sent Element Content
The full path to the directory in the 1010data database hierarchy where you want to
reorder items.
A list of
elements of the directories in the folder where the order of the
represents the order desired in 1010data.
A list of
elements of the tables in the folder where the order of the
represents the order desired in 1010data.
XML Input Example
XML Response from Server
A successful
XML Element
Returned
contains the following elements:
Description of Returned Element Content
Return code
Message from the system
XML Response Example
clear (Clear the cache)
Once the results of a query are retrieved or saved, it often makes sense to free up virtual memory before
running another query. The
transaction clears some or all of the memory used by the first query.
Be careful: Do not use the clear transaction until you are finished saving or retrieving the results of the first
query. If you do, the system will have to recompute the results from scratch.
Query String
The query string in the HTTP header must contain the following parameters:
Connection String Value
Variable
1010data API Reference Manual | 1010data Application Program Interface | 46
Connection String Value
Variable
[USERNAME]
[ENCRYPTED PASSWORD] - returned from the
[SESSION ID] - returned from the
transaction
transaction (optional)
Query String Example
XML Input to Server
None.
XML Response from Server
A successful
XML Element
Returned
contains the following elements:
Description of Returned Element Content
Return code
Message from the system
XML Response Example
session (Set session parameters)
Under certain circumstances it may be useful to adjust how queries use system resources such as
processing power and virtual memory. The
transaction provides a means to effect such changes.
Query String
The query string in the HTTP header must contain the following parameters:
Connection String Value
Variable
[USERNAME]
[ENCRYPTED PASSWORD] - returned from the
[SESSION ID] - returned from the
Query String Example
transaction
transaction (optional)
1010data API Reference Manual | 1010data Application Program Interface | 47
XML Input to Server
The specifications must contain the following elements:
XML Element To
Send
Description of Sent Element Content
Reduce or eliminate errors or infinity values returned from certain computations
(optional)
Some computations (e.g., dividing by zero) can result in errors or "infinity" values
( ,
, , or
). Setting this parameter to
can help reduce or eliminate this
behavior.
Specifically:
•
Division by zero (
•
Checking this box causes
to be returned instead of
and
.
Exponentiation (
) can generate error messages if is negative.
•
) returns
or
if the numerator is not zero.
Checking this box mostly eliminates such messages and causes
to be
returned in the event of an error.
The range functions (
,
etc.) return ,
, , or
for
column values that lie outside the specified ranges.
Valid values are
and
.
Perform step-wise aggregation (optional)
(optional)
Setting this parameter to
slowly.
saves memory but may cause queries to run more
Choose this setting only if you experience virtual memory problems when working
with large tables.
Valid values are
(optional)
and
.
Help alleviate virtual memory problems when doing row selections and tabulations
on large tables (optional)
Setting this parameter to lower numbers saves memory but may cause queries to
run more slowly.
Use lower numbers when doing row selections and tabulations on large tables if you
experience virtual memory problems.
Valid values are the integers 0 through 10.
XML Input Example
XML Response from Server
A successful
XML Element
Returned
contains the following elements:
Description of Returned Element Content
Return code
1010data API Reference Manual | 1010data Application Program Interface | 48
XML Element
Returned
Description of Returned Element Content
Message from the system
XML Response Example
1010data API Reference Manual | PowerLoader Transactions | 49
PowerLoader Transactions
This section provides a series of interactions for managing PowerLoader API sessions.
addtab (Load a large table)
The
transaction loads a large table into the 1010data system.
The transaction expects source data in your FTP account, so ensure the data is fully uploaded via FTP
before invoking this transaction.
As input,
accepts an XML version of the 1010 PowerLoader V1 spec file. If you still wish to use the
legacy format, use the
transaction to convert your PowerLoader V1 spec file into an XML spec.
This transaction can be invoked synchronously or asynchronously or with the
tag. In sync mode,
the transaction returns when the table is finished loading. In async mode, when the transaction returns a
response, it does not mean the table is created, it means table creation has successfully been initiated.
With async mode, you use the
transaction to check on the status of the table creation.
Sync mode is recommended for small tables (<1 million records) and async mode is recommended for
large tables (> 1 million records).
Note: To use this transaction, you must have a 1010data FTP account.
Query String
The query string in the HTTP header must contain the following parameters:
Connection String Value
Variable
[USERNAME]
[ENCRYPTED PASSWORD] - returned from the
[SESSION ID] - returned from the
transaction
transaction (optional)
Query String Example
XML Input to Server
The specifications must contain the following elements:
XML Element To Send
Description of Sent Element Content
Specifies whether you want to load synchronously or not
Possible values are:
•
•
if you want to load synchronously
if you want the table to load asynchronously
Outer specification element (required)
List of source files (required)
1010data API Reference Manual | PowerLoader Transactions | 50
XML Element To Send
Description of Sent Element Content
File element
File path of table in 1010data (e.g.,
).
If you reference an existing table,
will replace it.
Title as it appears in the user interface
Short description of the table
Long description of table
Link header
Specifies users provisioned for table access.
If the
table.
element is excluded, only the table owner may access the
See Users Tree on page 68 for XML schema and <users> (Top-level
wrapper for users tree) on page 68 for usage details.
Specifies each user that may access the table.
Used in conjunction with the
is omitted).
Each
element when
element is nested inside the
or
is
top-level wrapper.
(required)
Single character delimiter.
Required if
is
.
End of record delimiter
Byte order of data -
or
endian
Number of bytes to skip at the beginning of e/file
Number of records to skip in the beginning of e/file
Number of records to load in e/file
Time-series flag.
1 for true, or 0 for false.
Requires that
tags are provided in at least one column.
Column specifications (required)
List of
elements, one for each column in the file.
A column element (required)
There must be one of these for each column in the table.
Field name (required)
Must begin with an alphabetical character.
Field width in the raw file (required)
(Optional if
is
.)
(or if
1010data API Reference Manual | PowerLoader Transactions | 51
XML Element To Send
Description of Sent Element Content
Column help (text inside ? marker above column)
Field is read but not displayed in table
Field data type (required)
See Field Data Types on page 70.
Divisor used to divide raw value.
Force case, either
or
Ignore the field; don’t include it in the table.
Column placement relative to other columns (integer)
Column is non-scrolling (pink)
Column header
Use
to separate lines.
1010 expression applied to raw data (not nested)
Formatting Spec
Must specify
,
, and
See Field Format Types on page 71.
TS segmentation order (integer).
The number provided here is the relative segmentation order of this
column in relation to other columns with the
tag.
Think of
columns as tabulation breaks. The column that denotes
time should have the largest number in the sequence.
XML Input Example
1010data API Reference Manual | PowerLoader Transactions | 52
XML Response from Server
A successful
produces the following result:
status (Status of the addtab API)
The
transaction reports the status of an
of the load process.
transaction. The return code indicates the state
Query String
The query string in the HTTP header must contain the following parameters:
Connection String Value
Variable
[USERNAME]
[ENCRYPTED PASSWORD] - returned from the
[SESSION ID] - returned from the
Query String Example
transaction
transaction (optional)
1010data API Reference Manual | PowerLoader Transactions | 53
XML Input to Server
None.
XML Response from Server
A successful
produces the following result:
XML Element
Returned
Description of Returned Element Content
Return code
Message from the server
Number of records written to the table so far
Reported if
is in the Loading state.
Estimate of the number of records in the source file
Possible Return Codes
•
•
•
•
•
•
- Idle – Server is idle and has not started loading anything.
- Failed – Server could not load file.
- Initializing – Server is validating load specification. Loading has not commenced.
- Loading – Server is in the process of loading a table. More tables cannot be loaded until it is
complete.
- Completed – Server has completed an loading the table.
- Diagnosed – The server loaded the table but there were file format issues. The server attempted to
automatically correct the issues.
XML Response Example
convert (Convert a legacy spec)
The
transaction will parse and convert a legacy PowerLoader spec file into XML.
Note: The user must have a FTP account with a spec file in the top level directory.
Query String
The query string in the HTTP header must contain the following parameters:
Connection String Value
Variable
[USERNAME]
[ENCRYPTED PASSWORD] - returned from the
[SESSION ID] - returned from the
transaction
transaction (optional)
1010data API Reference Manual | PowerLoader Transactions | 54
Query String Example
XML Input to Server
The specifications must contain the following elements:
XML Element To
Send
Description of Sent Element Content
The spec filename to convert located on your FTP account. See PowerLoader
User's Guide for file format.
XML Response from Server
A successful
XML Element
Returned
produces the following result:
Description of Returned Element Content
Return code
Message from the system
XML Spec file – See addtab (Load a large table) on page 49 for transaction XML
Input.
XML Response Example
1010data API Reference Manual | PowerLoader Transactions | 55
edittab (Edit a table)
The
transaction changes the table metadata (table information acquired via
).
Query String
The query string in the HTTP header must contain the following parameters:
Connection String Value
Variable
[USERNAME]
[ENCRYPTED PASSWORD] - returned from the
[SESSION ID] - returned from the
transaction
transaction (optional)
Query String Example
XML Input to Server
The specifications consist of the table element from the XML response of
. The difference is that
one can opt to only transmit the top level elements being updated. See tabinfo (Get information about a
table) on page 20 for detailed info about the response specification.
The following element is required:
The table element is required and must contain at least one of the following. See
a detailed schema.
XML Element To
Send
Description of Sent Element Content
Table title
Secure SSL access
Table owner
Long description of the table
XML output for
1010data API Reference Manual | PowerLoader Transactions | 56
XML Element To
Send
Description of Sent Element Content
Link header
Column information
XML Input Example
XML Response from Server
A successful result contains the following elements:
XML Element
Returned
Description of Returned Element Content
Return code
Message
XML Response Example
validate (Validate a table)
The
transaction will parse and validate the XML spec input to
.
Query String
The query string in the HTTP header must contain the following parameters:
Connection String Value
Variable
[USERNAME]
[ENCRYPTED PASSWORD] - returned from the
[SESSION ID] - returned from the
Query String Example
XML Input to Server
The specifications must contain the following elements:
transaction
transaction (optional)
1010data API Reference Manual | PowerLoader Transactions | 57
XML Element To Send
Description of Sent Element Content
Specifies whether you want to load synchronously or not
Possible values are:
•
•
if you want to load synchronously
if you want the table to load asynchronously
Outer specification element (required)
List of source files (required)
File element
File path of table in 1010data (e.g.,
).
If you reference an existing table,
will replace it.
Title as it appears in the user interface
Short description of the table
Long description of table
Link header
Specifies users provisioned for table access.
If the
table.
element is excluded, only the table owner may access the
See Users Tree on page 68 for XML schema and <users> (Top-level
wrapper for users tree) on page 68 for usage details.
Specifies each user that may access the table.
Used in conjunction with the
is omitted).
Each
element when
element is nested inside the
or
is
top-level wrapper.
(required)
Single character delimiter.
Required if
is
.
End of record delimiter
Byte order of data -
or
endian
Number of bytes to skip at the beginning of e/file
Number of records to skip in the beginning of e/file
Number of records to load in e/file
Time-series flag.
1 for true, or 0 for false.
Requires that
tags are provided in at least one column.
Column specifications (required)
List of
(or if
elements, one for each column in the file.
1010data API Reference Manual | PowerLoader Transactions | 58
XML Element To Send
Description of Sent Element Content
A column element (required)
There must be one of these for each column in the table.
Field name (required)
Must begin with an alphabetical character.
Field width in the raw file (required)
(Optional if
is
.)
Column help (text inside ? marker above column)
Field is read but not displayed in table
Field data type (required)
See Field Data Types on page 70.
Divisor used to divide raw value.
Force case, either
or
Ignore the field; don’t include it in the table.
Column placement relative to other columns (integer)
Column is non-scrolling (pink)
Column header
Use
to separate lines.
1010 expression applied to raw data (not nested)
Formatting Spec
Must specify
,
, and
See Field Format Types on page 71.
TS segmentation order (integer).
The number provided here is the relative segmentation order of this
column in relation to other columns with the
tag.
Think of
columns as tabulation breaks. The column that denotes
time should have the largest number in the sequence.
XML Input Example
1010data API Reference Manual | PowerLoader Transactions | 59
XML Response from Server
A successful
XML Element
Returned
produces the following result:
Description of Returned Element Content
Return code
Message from the system
XML Response Example
1010data API Reference Manual | Table Tree | 60
Table Tree
The table tree is a generic way of representing a table in XML and is used in transmitting table data or
other tabular information to and from the server.
The overall format is as follows:
The component elements are described in detail in this section. Not all components are used in all
transactions. See the description of a transaction for information as to which components are relevant to
that transaction.
1010data API Reference Manual | Table Tree | 61
<table> (Top-level wrapper for table tree)
The table tree is required and may have one attribute (
) and must contain certain elements.
Attributes
Attribute
Value
Name of table
If the table corresponds to a table in the 1010data system, this is the full path to the table in the 1010data
database hierarchy.
In general, a path has the form:
(similar to a Windows or Unix file-system path but with dots instead of slashes)
The name of a table can be determined by clicking Info > About this Table in the 1010data web interface.
If the table does not correspond to a table in the 1010data system,
has no meaning and is omitted.
Example
Contents
Each of the following elements is described in detail on its own page.
present; the others may be omitted.
Element
and
are always
Description
Title of table
Short description of table
Long description of table
Link header
Download limit
Column meta information
Table data
<title> (Table title)
Returns the title of a table. The table title appears above the table when it is displayed in the 1010data web
interface.
Attributes
None
1010data API Reference Manual | Table Tree | 62
Contents
The title of the table (i.e., the text that appears in both a directory listing and above the table when it is
displayed in the 1010data web interface). For example, in the screenshot below, Sales Item Detail is the
table title.
<sdesc> (Short description of a table)
Returns the short description of a table from the table metadata.
Attributes
None
Contents
The short description of the table (i.e., the text that appears in the Short Description field in the 1010data
web interface).
<ldesc> (Long description of a table)
Returns the long description of a table from the table metadata.
Attributes
None
1010data API Reference Manual | Table Tree | 63
Contents
The long description of the table (i.e., the text that appears when the user clicks on the table in the
1010data file viewer and then clicks View Info to see information about the table). For example, in the
screenshot below, the text that appears under the heading Long Description.
<links> (Top-level wrapper for links)
can contain an arbitrary number of
transaction.
tags, which act a wrapper used by the
Attributes
None
Contents
can contain an arbitrary number of
tags, which act a wrapper used by the
transaction 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. Its basic syntax is given as follows.
Example
This syntax specifies that the table referenced by the
attribute within the
tag should
be joined along the columns indicated in the
and
attributes. If the
attribute is
present, columns from the foreign table are denormalized into the base table, otherwise a prelink between
the two tables is generated. In the general case, any valid
operation that could be applied in the
1010data Macro Language can be included in the
block.
1010data API Reference Manual | Table Tree | 64
<link> (Link header)
Returns the link header of a table. The link header is used to indicate which columns have come from a
foreign table after it has been linked to another table.
Attributes
None
Contents
A short (one or two word) title that is used when the table is linked to another table. In a link, this title is
prepended to the heading of each column from this table to distinguish them from columns from the other
table. For example, in the screenshot below, the Product Master table was linked to the Sales Item Detail
table. The headings of the columns from the Product Master table therefore begin with "
".
<maxdown> (Download limit)
The maximum amount of data that can be downloaded at one time.
Attributes
None
Contents
The maximum number of data items (rows × columns) that a user of the 1010data web interface may
download at one time. The download limit must be a non-negative whole number.
<segmentation> (Specify the segmentation of a table)
Specifies which columns should define the segmentation of a table.
1010data API Reference Manual | Table Tree | 65
Attributes
None
Contents
The
columns.
container is used by the
transaction to segment tables along the specified
Example
The
attribute of
specifies the columns to segment along. The
block can contain an arbitrary number of
tags. Each advise tag indicates that a particular
sequence of columns is also sortseg or segby, given the segmentation enforced in the
tag’s
attribute. For example, if you have your table segby
, then it is probably also segby
. If for some reason you want to enforce segmentation by a particular column (or columns),
but not to include it in the list of advised columns the
attribute may be included in the
tag.
<totals> (Table contains tabulation results)
Indicates whether table contains results from a tabulation.
Attributes
None
Contents
When the
of a tabulation.
element contains the value , it indicates the table contains columns that are a result
<cols> (Metadata for all columns)
Returns the metadata for all columns in a table.
Attributes
None
Contents
is a wrapper for column meta information and must contain one
the table (see <th> (Meta information for one column) on page 65).
<th> (Meta information for one column)
The metadata for a single column in a table.
element for each column in
1010data API Reference Manual | Table Tree | 66
Attributes
Attribute
Value
The name by which the column is referenced in formulas and query operations
Note: This is generally not the same as the column's heading (see
"Contents" below). E.g.,
.
The type of data in the column
must be one of:
•
•
•
(integer)
(float)
(alphanumeric)
The display format for the data in the column
Format specifications have the same form as is used in the XML Macro
Language in the Edit Actions dialog of the 1010data web interface (e.g.,
)
Indicates whether this is a fixed column or not
When
is , this indicates that the column is a fixed column.
Note: Fixed columns, when they exist in a table, are always visible and are
separated from the other columns by a vertical orange line.
Indicates whether this is the result of a tabulation or not
When
is , this indicates that the values in the column are from the result of
a tabulation.
and
must be present;
is optional.
Contents
The column heading that appears above the column when the table is displayed in the 1010data web
interface. Lines in the heading are separated by "
" (the newline character).
Example
<data> (Table data)
Returns the data in a table.
Attributes
None
Contents
is a wrapper for the table data and must contain one
<tr> (Data for one row) on page 67).
element for each row of the table (see
1010data API Reference Manual | Table Tree | 67
<tr> (Data for one row)
The data for a single row in a table.
Attributes
None
Contents
specifies a row of table data. It must contain one
element for each column of the table, each
of which contains the value for that column. The first
specifies a value for the first column listed in
the
element, the second
specifies a value for the second column, and so on. (See <cols>
(Metadata for all columns) on page 65 and <td> (One cell of data in a table) on page 67.)
<td> (One cell of data in a table)
Returns the value of a single cell (column/row) of the table.
Attributes
None
Contents
The value of a single cell (column/row) of the table. The type of value (integer, float or alphanumeric) must
conform to the column type as specified in the corresponding
entry under
.
1010data API Reference Manual | Users Tree | 68
Users Tree
The
tree is a way of representing access rights and is used in setting the access rights to a table
that is saved or uploaded.
The overall format is one of the following three options:
or
or
<users> (Top-level wrapper for users tree)
The
tree may have one attribute (
multiple instances of the
element.
) and, depending on the value of that attribute, may contain
Attributes
Attribute
Value
The type of access specification (optional)
may have one of the following values:
•
•
- No user, other than the table's owner, may access the table.
- Only the table's owner and users listed in the users tree may access the
table.
•
- All users that have access to the table's parent directory may access
the table.
If omitted, the default is
.
A user with access to a table's parent directory, but not to the table itself, will not see the table in the
directory's listing.
Note that a user's access to any table is subject to the user's "maximum row limit." The largest table (in
terms of number of rows) that a user may access is dependent on the user's subscription level. If a user is
granted access to a table via the
tree, but the table has more rows than the user's maximum row
limit, the user will see the table's title in the directory listing but will be unable to access it.
Contents
If
="
If
="
group.
" or
",
="
",
must be empty.
must contain one or more
elements, each identifying a single user or
1010data API Reference Manual | Users Tree | 69
<user> (User entry)
The username or group name. The name provided must be a user or group that already exists in
1010data.
Attributes
None.
Contents
The username or group name. The name provided must be a user or group that already exists in
1010data.
1010data API Reference Manual | Field Data Types | 70
Field Data Types
A field's data type may be one of the following:
Text (Picture)
Text
Integer (Picture)
Float (Picture)
1-Byte Char (Binary)
1-Byte Int (Binary)
2-Byte Int (Binary)
4-Byte Int (Binary)
8-Byte Int (Binary)
4-Byte Float (Binary)
8-Byte Double (Binary)
Decimal (BCD)
Signed (= Zoned)
YYYYMMDD
Date
YYMMDD
Date
MMDDYY
Date
DDMMYY
Date
MMDDYYYY
Date
DDMMYYYY
Date
YYYYMM
Month/Year
YYMM
Month/Year
MMYY
Month/Year
MMYYYY
Month/Year
HHMM
Time
YYYYMMDDHHMMSS
Date+Time
All non-numeric characters in dates are ignored. For example, the following are equivalent:
Input types YYYYMMDD and YYYYMM are tolerant of decoration characters (e.g., "
same as "
").
" is the
Upon load, dates are automatically converted to YYYYMMDD format, which is the format 1010data uses.
Similarly, month/years are converted to YYYYMM.
1010data API Reference Manual | Field Format Types | 71
Field Format Types
A field's display format may be one of the following:
Alphanumeric Text
Number: 1,234,567.89
Number: 1234567.89
Date: 10/15/98
Month/Year: 10/03
Quarter/Year: 2Q03
Time: 22:45:56
Date+Time: 10/15/98_22:45:56
1010data API Reference Manual | Deprecated Transactions | 72
Deprecated Transactions
These transactions have been deprecated in the 1010data XML API.
Please note that these transactions are still respected by the system and will not break your code.
However, they have been superseded by other transactions with more functionality.
The following table shows deprecated transactions and the transactions that should be used in their place.
Deprecated
Current
/
/
rmdir (Delete a directory)
The
transaction removes a directory. The API will check the permission of the user and the
directory, and it will remove the directory only if the user is an owner of the parent directory. Finally,
will only remove the directory if it is empty; therefore, be sure to remove all child tables and folders before
invoking this transaction.
Note: This transaction has been deprecated. Please use drop (Delete several tables or folders) on
page 41 instead.
Query String
The query string in the HTTP header must contain the following parameters:
Connection String Value
Variable
[USERNAME]
[ENCRYPTED PASSWORD] - returned from the
[SESSION ID] - returned from the
transaction
transaction (optional)
Query String Example
XML Input to Server
The specifications must contain the following elements:
XML Element To
Send
Description of Sent Element Content
The full path to the directory in the 1010data database hierarchy
In general, a path has the form:
1010data API Reference Manual | Deprecated Transactions | 73
XML Element To
Send
Description of Sent Element Content
(similar to a Windows or Unix file-system path but with dots instead of slashes)
XML Input Example
XML Response from Server
A successful
produces the following result:
rmtab (Delete a table)
The
transaction removes a table from 1010data. The API will check the permission of the user and
will remove the table if the user is an owner of the table.
Note: This transaction has been deprecated. Please use drop (Delete several tables or folders) on
page 41 instead.
Query String
The query string in the HTTP header must contain the following parameters:
Connection String Value
Variable
[USERNAME]
[ENCRYPTED PASSWORD] - returned from the
[SESSION ID] - returned from the
transaction
transaction (optional)
Query String Example
XML Input to Server
The specifications must contain the following elements:
XML Element To
Send
Description of Sent Element Content
The full path to the table in the 1010data database hierarchy
In general, a path has the form:
(similar to a Windows or Unix file-system path but with dots instead of slashes)
1010data API Reference Manual | Deprecated Transactions | 74
XML Element To
Send
Description of Sent Element Content
The name of a table can be determined by clicking Info > About this Table in the
1010data web interface.
XML Input Example
XML Response from Server
A successful
produces the following result:
prelink (Prelink tables)
The
transaction performs a link between two tables and persists the link result so ad hoc links
are faster and less memory consumptive.
Note: This transaction has been deprecated. Please use savetable (Save query results as a table)
on page 34 or addtab (Load a large table) on page 49 instead.
Query String
The query string in the HTTP header must contain the following parameters:
Connection String Value
Variable
[USERNAME]
[ENCRYPTED PASSWORD] - returned from the
[SESSION ID] - returned from the
transaction
transaction (optional)
Query String Example
XML Element To
Send
Description of Sent Element Content
The main link element. The attributes of
attributes are detailed in the next table.
provide the details for the link. The
Attributes for
XML Element To
Send
Description of Sent Element Content
The base table (local table) for the link.
The table being "linked in," or the "foreign" table of the link.
1010data API Reference Manual | Deprecated Transactions | 75
XML Element To
Send
Description of Sent Element Content
The column being used to link in the original table.
The column being used to link in the foreign table.
Tells the system to keep the cols in the original table. (optional)
Accepts
for true or
for false.
Accepts
for true or
for false. (optional)
Provides a suffix for the newly linked in columns. (optional)
XML Input Example
XML Response from Server
XML Element
Returned
Description of Returned Element Content
Return code
Message from the server
Number of records written to the table so far
Reported if
is in the loading state.
Number of records in the source file
XML Response Example
timeseries (Merge tables using time series)
The
transaction performs a time series process on one or multiple tables called source
tables and creates a new table containing the merge of all the source tables on which one can execute g_
and tstat functions.
Note: This transaction has been deprecated. Please use savetable (Save query results as a table)
on page 34 or addtab (Load a large table) on page 49 instead.
Query String
The query string in the HTTP header must contain the following parameters:
Connection String Required Value
Variable
[USERNAME]
1010data API Reference Manual | Deprecated Transactions | 76
Connection String Required Value
Variable
[ENCRYPTED PASSWORD] - returned from the
[SESSION ID] - returned from the
transaction
transaction (optional)
Query String Example
XML Input to Server
The specifications must contain the following elements:
XML Element To
Send
Description of Sent Element Content
The full path to the directory in the 1010data database hierarchy
In general, a path has the form:
(similar to a Windows or Unix file-system path but with dots instead of slashes)
List of source tables
Table Name Element
Title as it appears in the user interface
A
header
Users provisioned for table access. See Users Tree on page 68 for XML schema.
Excluding this element will set the table to inherit access rights.
List of source tables
XML Input Example
1010data API Reference Manual | Deprecated Transactions | 77
XML Response from Server
A successful
starts the process. Use the status transaction to keep track of its progress.