add_training_data¶

Nl2sqlApi.add_training_data(role_id, nl2_sql_training_documents_post, content_type=None, _request_timeout=None, _request_auth=None, _content_type=None, _headers=None, _host_index=0)¶

Add SQL AI training data

Registers a training document used to improve SQL AI responses. This call creates metadata only. To attach the actual file, follow it with GET /nl2sql/training-documents/{id}?action=get_upload_url and PUT the file to the returned URL. The document only reaches the chatbot’s knowledge base after a sync job runs, so trigger POST /nl2sql/sync-jobs once the upload is complete. Requires SQLAI to be present in the environment’s enabled AI services; otherwise the request fails with AI-1004. Not idempotent: a duplicate DocumentName is rejected with IPV-1018.

Parameters:

role_id (str) – Amorphic role ID the request is authorized against. The role must carry the playground.manage permission. (required)
nl2_sql_training_documents_post (NL2SQLTrainingDocumentsPost) – (required)
content_type (str) – Must be application/json.
_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:

NL2SQLTrainingDocumentCreateResponse

Returns:

Returns the result object.

Request and Response Examples¶

HTTP: POST /nl2sql/training-documents

Parameter examples¶

Name	In	Example
`role_id`	header	`"role-admin"`

Request¶

SQL example queries for a dataset

{
  "DocumentName": "monthly_orders_examples",
  "DocumentType": "SQL",
  "AssociatedResourceType": "Dataset",
  "AssociatedResourceId": "c2f7d3b1-1a2b-4d8e-9f3a-2b3c4d5e6f70"
}

Free-form reference documentation

{
  "DocumentName": "sales_glossary",
  "DocumentType": "Documentation",
  "AssociatedResourceType": "Dataset",
  "AssociatedResourceId": "c2f7d3b1-1a2b-4d8e-9f3a-2b3c4d5e6f70"
}

Question and answer pairs

{
  "DocumentName": "orders_qna",
  "DocumentType": "QnA",
  "AssociatedResourceType": "Dataset",
  "AssociatedResourceId": "c2f7d3b1-1a2b-4d8e-9f3a-2b3c4d5e6f70"
}

Success (HTTP 200)¶

Training document registered. Upload the file next, then trigger a sync job.

Request / response example

{
  "DocumentId": "b1e6c2a0-9f4d-4c7a-8f2e-1a2b3c4d5e6f",
  "Message": "Training document created successfully"
}

Errors¶

Documented error codes: AI-1004, GE-1001, IPV-1008, IPV-1004, IPV-1018, IPV-1041, AUTH-1001, AUTH-1030.

HTTP 400

Input validation or authorization failure. Body is {“Message”: “<CODE> - <text>”}. Codes: AI-1004 (SQLAI is not enabled), GE-1001 (body missing or unparseable), IPV-1008 (a required key is absent), IPV-1004 (DocumentName fails the name pattern, the caller lacks access to the dataset, or the dataset’s TargetLocation is not s3athena or redshift), IPV-1018 (duplicate DocumentName), IPV-1041 (unknown DocumentType or AssociatedResourceType), AUTH-1001 / AUTH-1030 (authorization).

A required key is absent from the body

{
  "Message": "IPV-1008 - Invalid request body, missing key(s) - ['AssociatedResourceId']"
}

DocumentName already in use

{
  "Message": "IPV-1018 - Duplicate name, monthly_orders_examples already exists"
}

Unknown DocumentType

{
  "Message": "IPV-1041 - Invalid value for DocumentType"
}

Associated dataset is not queryable by SQL AI

{
  "Message": "IPV-1004 - Invalid value for AssociatedResourceId, dataset TargetLocation must be one of s3athena, redshift"
}

SQLAI is not enabled for this environment

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

HTTP 500

Something went wrong at backend