create_dataset

DatasetsApi.create_dataset(role_id, dataset_metadata, content_type=None, x_app_integrations=None, _request_timeout=None, _request_auth=None, _content_type=None, _headers=None, _host_index=0)

Registers a new dataset

Creates a new dataset with initial metadata. Supports three dataset types: internal, external (references existing S3 data), and view (SQL-based DWH view). Caller must have editor or owner access on the target domain. Duplicate DatasetName within the same domain returns IPV-1018.

Parameters:

  • role_id (str) – Amorphic role ID the request is authorized against. Must be a role the user belongs to. (required)

  • dataset_metadata (DatasetMetadata) – (required)

  • content_type (str)

  • x_app_integrations (str) – JSON-encoded list of app integration identifiers (e.g. ‘[“ACE”,”MDM”]’)

  • _request_timeout (int, tuple(int, int), optional) – timeout setting for this request. If one number provided, it will be total request timeout. It can also be a pair (tuple) of (connection, read) timeouts.

  • _request_auth (dict, optional) – set to override the auth_settings for an a single request; this effectively ignores the authentication in the spec for a single request.

  • _content_type (str, Optional) – force content-type for the request.

  • _headers (dict, optional) – set to override the headers for a single request; this effectively ignores the headers in the spec for a single request.

  • _host_index (int, optional) – set to override the host_index for a single request; this effectively ignores the host_index in the spec for a single request.

Return type:

CreateDatasetResponse

Returns:

Returns the result object.

Request and Response Examples

HTTP: POST /datasets

Request

Request / response example

{
  "DatasetName": "monthly_orders",
  "DisplayName": "Monthly Orders",
  "DatasetDescription": "Order line items refreshed monthly",
  "DatasetType": "internal",
  "Domain": "sales",
  "FileType": "csv",
  "TargetLocation": "s3athena",
  "Keywords": [
    "Owner: user2"
  ],
  "SkipFileHeader": false,
  "TableUpdate": "append",
  "DatasourceType": "api",
  "IsDataValidationEnabled": true
}

Success (HTTP 200)

Dataset created successfully. DatasetId is a UUID that identifies the new dataset for all subsequent operations.

Standard dataset creation

{
  "Message": "Dataset registration completed successfully.",
  "DatasetId": "b1e6c2a0-9f4d-4c7a-8f2e-1a2b3c4d5e6f"
}

View dataset (async)

{
  "Message": "Dataset creation in progress",
  "DatasetId": "a2f7d3b1-8e5c-4a6f-9d1e-2b3c4d5e6f7a"
}

Dataset with query results upload

{
  "Message": "Dataset created and schema registered successfully. Query results file upload is in progress.",
  "DatasetId": "c3d8e4f2-9a6b-5c7d-0e1f-3a4b5c6d7e8f"
}

Errors

Documented error codes: IPV-1001, IPV-1004, IPV-1018, IPV-1041, AUTH-1014, DS-1015, GE-1035, GE-1034, RS-1026, RTE-1001.

HTTP 400

Validation failure. Common error codes: IPV-1001 (empty mandatory field), IPV-1004 (name validation failed), IPV-1018 (name already exists), IPV-1041 (invalid enum value), AUTH-1014 (no domain permission), DS-1015 (FileType not supported for target).

Dataset name already exists in domain

{
  "Message": "IPV-1018 - Dataset Name already exists"
}

TargetLocation not supported

{
  "Message": "GE-1035 - dynamodb is not supported"
}

User lacks domain access

{
  "Message": "AUTH-1014 - sales does not allow creating dataset"
}

FileType not supported for target

{
  "Message": "DS-1015 - xlsx not supported for dynamodb"
}

HTTP 500

Backend failure. Error codes: GE-1034 (registration lambda failed), RS-1026 (Redshift cluster not available), RTE-1001 (unhandled exception).