get_training_document_details¶

Nl2sqlApi.get_training_document_details(id, role_id, action=None, document_name=None, file_name=None, projection_expression=None, _request_timeout=None, _request_auth=None, _content_type=None, _headers=None, _host_index=0)¶

Get training document details, or request a file upload URL

This operation has two modes, selected by the action query parameter. - Without action (the default), returns the full training document record, including UploadedFiles and a one-hour DownloadURL for the first uploaded file when at least one file exists. - With action=get_upload_url, returns a presigned URL to PUT a training file to. Both document_name and file_name are then required. The file is recorded against the document as soon as the URL is issued, before the upload itself completes, so a URL that is issued but never used leaves a dangling entry in UploadedFiles. Requires SQLAI to be present in the environment’s enabled AI services; otherwise the request fails with AI-1004.

Parameters:

id (str) – Identifier of the training document. (required)
role_id (str) – Amorphic role ID the request is authorized against. The role must carry the playground.view permission. (required)
action (str) – Selects the response shape. Omit to retrieve the document record; set to get_upload_url to obtain a presigned upload URL. The comparison is case-insensitive, and any unrecognised value falls through to the document-record mode rather than being rejected.
document_name (str) – Required when action=get_upload_url; omitting it or sending an empty value is rejected with IPV-1001. Note that the backend validates this value but does not otherwise use it, so it has no effect on the URL that is returned. Ignored in document-record mode.
file_name (str) – Required when action=get_upload_url; omitting it or sending an empty value is rejected with IPV-1001. The extension determines the stored object’s type, and the value is recorded as FileName in UploadedFiles. Ignored in document-record mode.
projection_expression (str) – Comma-separated list of attributes to return. Applies to document-record mode only and is ignored when action=get_upload_url. Any attribute may be omitted from the response, including DocumentId.
_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:

GetTrainingDocumentDetails200Response

Returns:

Returns the result object.

Request and Response Examples¶

HTTP: GET /nl2sql/training-documents/{id}

Parameter examples¶

Name	In	Example
`id`	path	`"b1e6c2a0-9f4d-4c7a-8f2e-1a2b3c4d5e6f"`
`role_id`	header	`"role-admin"`
`action`	query	`"get_upload_url"`
`document_name`	query	`"monthly_orders_examples"`
`file_name`	query	`"doc.sql"`
`projectionExpression`	query	`"DocumentId,DocumentName,UploadedFiles"`

Success (HTTP 200)¶

The training document record, or a presigned upload URL when action=get_upload_url.

Document record with an uploaded file

{
  "DocumentId": "b1e6c2a0-9f4d-4c7a-8f2e-1a2b3c4d5e6f",
  "DocumentName": "monthly_orders_examples",
  "DocumentType": "SQL",
  "AssociatedResourceType": "Dataset",
  "AssociatedResourceId": "c2f7d3b1-1a2b-4d8e-9f3a-2b3c4d5e6f70",
  "AssociatedResourceName": "monthly_orders",
  "AssociatedResourceDomain": "sales",
  "UserId": "user1",
  "CreationTime": "2025-01-15 10:30:00",
  "LastModifiedBy": "user1",
  "LastModifiedTime": "2025-06-01 14:22:00",
  "UploadedFiles": [
    {
      "S3Location": "s3://my-bucket/nl2sql/training/doc.sql",
      "FileName": "doc.sql",
      "UploadTime": "2025-01-15 10:35:00"
    }
  ],
  "DownloadURL": "https://s3.amazonaws.com/bucket/nl2sql/doc.sql?X-Amz-Signature=..."
}

Document registered but no file uploaded yet

{
  "DocumentId": "b1e6c2a0-9f4d-4c7a-8f2e-1a2b3c4d5e6f",
  "DocumentName": "monthly_orders_examples",
  "DocumentType": "SQL",
  "AssociatedResourceType": "Dataset",
  "AssociatedResourceId": "c2f7d3b1-1a2b-4d8e-9f3a-2b3c4d5e6f70",
  "AssociatedResourceName": "monthly_orders",
  "AssociatedResourceDomain": "sales",
  "UserId": "user1",
  "CreationTime": "2025-01-15 10:30:00",
  "LastModifiedBy": "user1",
  "LastModifiedTime": "2025-01-15 10:30:00"
}

Response when action=get_upload_url

{
  "UploadURL": "https://s3.amazonaws.com/bucket/nl2sql/training/doc.sql?X-Amz-Signature=..."
}

Errors¶

Documented error codes: AI-1004, IPV-1002, IPV-1001, AUTH-1001, AUTH-1030, GE-1110.

HTTP 400

Input validation or authorization failure. Body is {“Message”: “<CODE> - <text>”}. Codes: AI-1004 (SQLAI is not enabled), IPV-1002 (document id not found), IPV-1001 (document_name or file_name missing while action=get_upload_url), AUTH-1001 / AUTH-1030 (authorization).

Unknown document id

{
  "Message": "IPV-1002 - Invalid DocumentId - b1e6c2a0-9f4d-4c7a-8f2e-1a2b3c4d5e6f, resource not found."
}

file_name absent while requesting an upload URL

{
  "Message": "IPV-1001 - Parameter file_name is a required value."
}

SQLAI is not enabled for this environment

{
  "Message": "AI-1004 - SQLAI is not enabled. Please contact the administrator to enable it."
}

HTTP 500

Backend failure. Codes include GE-1110 (the presigned upload URL could not be generated). Body is {“Message”: “<CODE> - <text>”}.

Request / response example

{
  "Message": "GE-1110 - Failed to generate the presigned url"
}