delete_training_document

Nl2sqlApi.delete_training_document(id, role_id, file_name=None, _request_timeout=None, _request_auth=None, _content_type=None, _headers=None, _host_index=0)

Delete a training document, or one of its uploaded files

Deletes either a single uploaded file or the whole training document, depending on whether file_name is supplied. - With file_name: deletes just that file and its metadata, synchronously. - Without file_name: starts asynchronous deletion of the entire document. A 200 means deletion was triggered, not that it has completed, and failures during the asynchronous phase are never reported to the caller. Deleting training data does not immediately change the chatbot’s answers: run POST /nl2sql/sync-jobs to propagate the removal to the knowledge base. Requires SQLAI to be present in the environment’s enabled AI services; otherwise the request fails with AI-1004. Two backend defects are worth knowing about when calling this operation. Deleting a document id that does not exist returns HTTP 500 rather than the documented 400, because the handler dereferences the record before checking whether it was found. Supplying a file_name that the document does not contain also returns HTTP 500, and its message carries no error-code prefix, unlike every other error on this API.

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.fullaccess permission, which is a higher bar than the other operations on this path. (required)

  • file_name (str) – Name of a single uploaded file to delete, as recorded in UploadedFiles. When omitted, the entire document is deleted asynchronously instead. Note that this is the only query parameter this operation accepts: sending any other query parameter without also sending file_name causes the request to fail with HTTP 500.

  • _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:

NL2SQLTrainingDocumentDeleteResponse

Returns:

Returns the result object.

Request and Response Examples

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

Parameter examples

Name

In

Example

id

path

"b1e6c2a0-9f4d-4c7a-8f2e-1a2b3c4d5e6f"

role_id

header

"role-admin"

file_name

query

"doc.sql"

Success (HTTP 200)

File deleted, or whole-document deletion triggered. The message distinguishes the two.

Whole document, deleted asynchronously

{
  "Message": "Document monthly_orders_examples deletion is in progress."
}

Single file, deleted synchronously

{
  "Message": "File doc.sql deleted successfully from document monthly_orders_examples"
}

Errors

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

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, on the single-file branch only), AUTH-1001 / AUTH-1030 (authorization).

Unknown document id, single-file branch

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

Role lacks playground.fullaccess

{
  "Message": "AUTH-1030 - User does not have required permissions to perform this operation"
}

HTTP 500

Backend failure. Also returned, because of the defects noted in the operation description, when the document id does not exist on the whole-document branch, when file_name names a file the document does not contain, and when an unexpected query parameter is sent. The message for an unknown file_name carries no error-code prefix.

file_name not present on the document, message has no error-code prefix

{
  "Message": "File 'missing.sql' not found in document 'b1e6c2a0-9f4d-4c7a-8f2e-1a2b3c4d5e6f'"
}

Unknown document id on the whole-document branch

{
  "Message": "'NoneType' object has no attribute 'get'"
}