Exports

Overview

The Export API is an asynchronous API which enables you to export your data to s3 buckets.

The exports endpoint has two distinct behaviors, depending on whether the objects field or the select field has been used.

field used

behavior

select

Filtered export of the object against which this filter is applied.

objects

Full export of the objects named in this array.

Select provides a simple JSON syntax for selecting certain fields and filtering that can span several related Objects. Filters support conjunctions (and & or) to any depth and field comparisons include all the operators necessary for simple sql-like "where" clause filtering.

Completion

After triggering your export by calling the POST exports endpoint, you can determine when your job has been completed in two ways:

  1. Check the bucket specified in your export response for a file called complete.json, which will be written upon completion.

  2. Poll the GET exports/{export_id} endpoint with the export id returned from the export response and look for state completed.

Accessing Amazon S3

To learn how to access your exports within Amazon S3, please visit our Exports reference:

post
Start Export Job (Filtered)

https://api.zaius.com/v3/exports
Export all filtered set of data from Zaius to Amazon S3.
Request
Response
Body Parameters
format
required
string
The format of the export. Valid values are "csv" and "parquet".
delimiter
optional
string
Defaults to 'comma'. Valid options are comma, tab, and pipe. Not applicable to parquet exports.
select
required
object
The filtering rules to apply to this export.
select.object
optional
string
The object this selection filter applies to.
select.fields
optional
array
An array of fields to export. The array ['*'] captures all fields from select.object, but will not follow any relations.
select.filter
optional
object
Refer to "Filtering" section below
select.filter.field
required
string
The field path to retrieve, following relations via the name of the relation and starting at the containing select's object. For example, if select.object = 'event' and field = 'product.name', this would use the value of name on the Product table where the product_id is the same as the product_id on the Event. The string * can be used as a wildcard to select all fields, but will not follow any relations.
select.filter.operator
required
string
Available options include: "=" "!=" ">" ">=" "<" "<=" "like" "not like" "ilike" "not ilike" "is" "is not" The evaluation to apply to the field's value. For null comparisons, use = or != with a value of null.
select.filter.value
required
string
The value to evaluate the field against using operator. Use % to indicate a wildcard in string [not] [i]like comparisons.
select.sorts
optional
array
Sort by specification applied for each export file (a single table export will cross multiple files).
selects.sorts.field
required
string
The field path to retrieve, following relations via the relation name and starting at the containing select's object. For example, if select.object = 'event' and field = 'product.name', this would use the value of name on the Product table where the product_id is the same as the product_id on the Event. The string * can be used as a wildcard to select all fields, but will not follow any relations.
select.sorts.order
optional
string
Default: "asc" Options:"asc" "desc" Order in which to sort the coupled field value by in the result set.
200: OK
{
"id": "3aab9524-5248-45f9-8102-0399872a921e",
"path": "s3://zaius-outgoing/kIFB_X1VG2gf6caBn8LHtg/data-exports/3aab9524-5248-45f9-8102-0399872a921e",
"state": "pending",
"requested_at": "2018-09-10T21:07:10-05:00",
"detail": {
"id": "3aab9524-5248-45f9-8102-0399872a921e",
"format": "csv",
"delimiter": "comma",
"select": {
"object": "events",
"fields": [
"product.name"
],
"filter": {
"field": "product.name",
"operator": "=",
"value": "%shoe%"
},
"sorts": [
{
"field": "product.name",
"order": "asc"
}
]
},
"objects": [
"string"
]
}
}
400: Bad Request
{
"title": "Bad Request",
"status": 400,
"timestamp": "2018-09-10T21:07:10-05:00",
"detail": {
"invalids": [
{
"field": "delimiter",
"reason": "Unrecognized delimiter, valid options are comma, tab or pipe"
}
]
}
}
403: Forbidden
{
"title": "Forbidden",
"status": 403,
"timestamp": "2018-09-10T21:07:10-05:00",
"detail": {
"message": "Insufficient privileges to access this resource."
}
}
404: Not Found
{
"title": "Not Found",
"status": 404,
"timestamp": "2018-09-10T21:07:10-05:00",
"detail": {
"message": "Unable to locate field products.unknown_field"
}
}
422: Unprocessable Entity
{
"title": "Unprocessable Entity",
"status": 422,
"timestamp": "2018-09-10T21:07:10-05:00",
"detail": {
"message": "Unable to process request. The following object(s) are currently being exported: events"
}
}
Example Payload
{
"format": "csv",
"delimiter": "comma",
"select": {
"object": "events",
"fields": [
"product.name"
],
"filter": {
"field": "product.name",
"operator": "=",
"value": "%shoe%"
},
"sorts": [
{
"field": "product.name",
"order": "asc"
}
]
}
}

post
Start Export Job (Unfiltered)

https://api.zaius.com/v3/exports
Export all filtered set of data from Zaius to Amazon S3.
Request
Response
Body Parameters
format
required
string
The format of the export. Valid values are "csv" and "parquet".
delimiter
optional
string
Defaults to 'comma'. Valid options are comma, tab, and pipe. Not applicable to parquet exports.
objects
required
array
The objects to export in full.
200: OK
{
"id": "3aab9524-5248-45f9-8102-0399872a921e",
"path": "s3://zaius-outgoing/kIFB_X1VG2gf6caBn8LHtg/data-exports/3aab9524-5248-45f9-8102-0399872a921e",
"state": "pending",
"requested_at": "2018-09-10T21:07:10-05:00",
"detail": {
"id": "3aab9524-5248-45f9-8102-0399872a921e",
"format": "csv",
"delimiter": "comma",
"select": {
"object": "events",
"fields": [
"product.name"
],
"filter": {
"field": "product.name",
"operator": "=",
"value": "%shoe%"
},
"sorts": [
{
"field": "product.name",
"order": "asc"
}
]
},
"objects": [
"string"
]
}
}
400: Bad Request
{
"title": "Bad Request",
"status": 400,
"timestamp": "2018-09-10T21:07:10-05:00",
"detail": {
"invalids": [
{
"field": "delimiter",
"reason": "Unrecognized delimiter, valid options are comma, tab or pipe"
}
]
}
}
403: Forbidden
{
"title": "Forbidden",
"status": 403,
"timestamp": "2018-09-10T21:07:10-05:00",
"detail": {
"message": "Insufficient privileges to access this resource."
}
}
404: Not Found
{
"title": "Not Found",
"status": 404,
"timestamp": "2018-09-10T21:07:10-05:00",
"detail": {
"message": "Unable to locate field products.unknown_field"
}
}
422: Unprocessable Entity
{
"title": "Unprocessable Entity",
"status": 422,
"timestamp": "2018-09-10T21:07:10-05:00",
"detail": {
"message": "Unable to process request. The following object(s) are currently being exported: events"
}
}
Example Payload
{
"objects": [
"string"
],
"format": "csv",
"delimiter": "comma"
}

get
Get Export Job Status

https://api.zaius.com/v3/exports/{export_id}
Fetch the status of an export request.
Request
Response
Path Parameters
{export_id}
required
string
Example: "3aab9524-5248-45f9-8102-0399872a921e" The export job ID to check.
200: OK
{
"id": "3aab9524-5248-45f9-8102-0399872a921e",
"path": "s3://zaius-outgoing/kIFB_X1VG2gf6caBn8LHtg/data-exports/3aab9524-5248-45f9-8102-0399872a921e",
"state": "pending",
"requested_at": "2018-09-10T21:07:10-05:00",
"detail": {
"id": "3aab9524-5248-45f9-8102-0399872a921e",
"format": "csv",
"delimiter": "comma",
"select": {
"object": "events",
"fields": [
"product.name"
],
"filter": {
"field": "product.name",
"operator": "=",
"value": "%shoe%"
},
"sorts": [
{
"field": "product.name",
"order": "asc"
}
]
},
"objects": [
"string"
]
},
"started_at": "2018-09-10T21:07:10-05:00",
"completed_at": "2018-09-10T21:07:10-05:00"
}
403: Forbidden
{
"message": "Forbidden"
}
404: Not Found
{
"title": "Not Found",
"status": 404,
"timestamp": "2018-09-10T21:07:10-05:00",
"detail": {
"message": "Unable to locate status for export example"
}
}
Example Request
curl -iX GET \
'https://api.zaius.com/v3/exports/example-export-id' \
-H 'x-api-key: example.apiKey'

More on Filtering

The filtering section in the payload may contain one of the following:

  • Clause: A standalone clause for defining a filter on Zaius data elements.

  • AND (all sub-clauses): A combination of clauses - if all of the contained clauses (which may include nested AND/OR clauses) evaluate to true, this data element may pass the overall filter. If any one (or more) of them do not, the data element will not pass the filter.

  • OR (at least one sub-clause): A combination of clauses - if any one (or more) of the contained clauses (which may include nested AND/OR clauses) evaluates to true, this data element may pass the overall filter. If none do, the data element will not pass the filter.

Note that the nature of AND and OR clauses enables arbitrarily many criteria to be combined.