savefile (Save query results as a file)

The savefile transaction saves the results of a query as a file in your 1010data FTP folder or cloud storage (ex. AWS S3, Azure Blob). The file can then be downloaded via FTP or retrieved from the cloud storage. To save results to cloud storage, the user account must be configured with the appropriate keys to access the storage. See Storage account management for instructions on how to add keys to your user account.

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:

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.

Query string example

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

XML Input to Server

The specifications must contain the following elements:

<file>
The name of the result file

If a file already exists with that name, it will be replaced.

<content>
The meta information to include in the file (optional)

<content> must contain one or more <meta> elements, each identifying one type of information.

Each <meta> element must include attribute type and type may have one of the following values:
  • headers - Column headers
  • names - Column names
  • formatted - Formats the values in the appropriate output type, instead of presenting the raw value

If not specified, no meta information is included in the file.

<format>
The data format for the result (optional)
<format> has no attributes and may contain the following elements:
  • <sep> - Character with which to separate fields (columns)
  • <linesep> - Character with which to separate records (rows)
  • <max_row_group_length> - Integer to specify row group size for parquet files.
  • <created_by> - String to set creator of parquet files.
  • <compression> - The type of compression used to save the file. Options are zip (the default value), gzip, raw_gzip, and zstd (parquet compression).

If not specified, the column separator is a comma, and the line separator is newline ( &#10;).

<target>
Saves the file to an external storage location.
<target> must contain one of the following child elements:
  • file - Saves the file to the user's ftp folder (same as <file> element)
  • s3 - Saves the file to Amazon S3 storage.
  • abs - Saves the file to Azure blob storage.
  • gcs - Saves the file to Google Cloud Storage.
Note: In order to use s3, abs, or gcs, the user must have saved their storage account key to their platform account with the addkey transaction.

Each storage option has one of the following format attributes: txt (the default value), csv, xlsx, pdf, tde, data, and parquet.

The s3 and gcs targets require these attributes: api_key, bucket

The abs target requires these attributes: api_key, storage_account_name, container.

The s3 target also accepts these additional attributes:
  • aws_role_arn - AWS IAM role used to access the S3 bucket (ex. arn:aws:iam::123456:role/my_role)
  • external_id - AWS External ID, to be optionally specified when authenticating with aws_role_arn
  • region - specify when exporting to a region that is different from the “default region” that is associated with the provided AWS credentials.

Either <file> or <target> is required; the others elements are optional.

<target> examples

<target><file>filename</file></target>
<target><s3 api_key="mykey" bucket="xxxxxx" format="xlsx">filename</s3></target>
<target>
  <abs api_key="mykey" storage_account_name="xxxxxx" container="yyyyyy">filename.csv
  </abs>
</target>
<target><gcs api_key="secret_key" bucket="my_bucket">path/to/object</gcs></target>

XML input examples

<in>
<file>My File</file>
<content>
   <meta type="names"/>
</content>
<format>
   <sep>,</sep>
</format>
</in>

XML response from server

A successful savefile contains the following elements:

<rc>
The return code generated by the transaction. For a list of return codes, see Return codes.
<msg>
The message returned by the system. Specific messages correspond to specific return codes.

XML response example

<out>
  <rc>0</rc>
  <msg>Saved file My File</msg>
</out>