API reference
Standard has no Groundzero Python helper library. Its programming surface is the Prep contract and the data request.
Prep code contract#
Prep is executed as a Python program. It sees these names.
| Name | Type | Meaning |
|---|---|---|
queryData |
list of dict | Rows fetched by the source query, one dictionary per row |
pd |
module | pandas |
json |
module | The standard JSON module |
outputDF |
any | You must assign this. The result |
Normalisation of outputDF into rows.
| You assign | Rows returned |
|---|---|
| DataFrame | One row per DataFrame row |
| Series | A one-column frame named after the Series (or value) |
| List of dictionaries | Unchanged |
| List of other values | One row per item with column value |
| Dictionary | A single row |
| Any other value | A single row with column value |
Raises. If Prep throws, or never assigns outputDF, the response is
{"status": "error", "message": "<exception text>"}. A missing outputDF
reports 'outputDF'.
Pass-through. Empty Prep and outputDF = queryData (whitespace and a
trailing semicolon ignored) skip execution entirely.
Example
rows = pd.DataFrame(queryData)
outputDF = rows[rows["amount"] > 100]Data request#
POST /getdata with a JSON object body.
| Field | Type | Required | Description |
|---|---|---|---|
ConnectionName |
string | yes | Name of a connection you may use |
DataSourceQuery |
string | yes | Source query, placeholders allowed |
TransformationQuery |
string | yes | Prep code, outputDF = queryData for none |
datasetId |
integer | no | Saved dataset id; enables permission check and lineage |
pageSize |
integer | no | Rows per page, default 1000, maximum 1000 |
pageNumber |
integer | no | 1-based page, default 1 |
filters |
array | no | Structured filters, below |
Data response#
| Field | Type | Description |
|---|---|---|
status |
string | success, error or Running |
data |
array | Rows for the page |
totalRecords |
integer | Rows across all pages |
hasMore |
boolean | More pages remain |
pageStart, pageEnd |
integer | 1-based row window |
pageNumber |
integer | Page returned |
schema |
array | columnName and dataType per column |
errorCode, message |
Present when status is error |
Structured filters#
Each element of filters:
| Field | Required | Meaning |
|---|---|---|
column |
yes | Column name, or dotted path such as o.region (max 128) |
table |
no | Table alias used in the query; not together with a dotted column |
op |
yes | in, eq, between, gte, gt, lte, lt |
values |
yes | Scalars: string, number or boolean |
Rules: between takes exactly two values; eq, gte, gt, lte and lt
take one; in takes 1 to 5000. Strings are limited to 1024 characters. null,
objects, arrays and non-finite numbers are rejected. Filters combine with AND
after any existing WHERE. A malformed filter fails with 400 and never runs the
unfiltered query:
{"status": "error", "errorCode": 400,
"message": "Invalid filters: filters[0].op must be a filter op"}Error messages#
| Source | Message |
|---|---|
| Standard | Request body must be an object (400) |
| Standard | datasetId must be a positive integer (400) |
| Standard | Invalid filters: ... (400) |
| Standard | Filter 'region' has no value (400) |
| Standard | You do not have "All" or "execute" permission on Dataset. |
| Standard | Connection type not supported. Please check the dataset. |