get_training_documents

Nl2sqlApi.get_training_documents(role_id, offset=None, limit=None, sortorder=None, sortby=None, filter_expression=None, projection_expression=None, _request_timeout=None, _request_auth=None, _content_type=None, _headers=None, _host_index=0)

List SQL AI training documents

Returns a paginated list of the SQL AI training documents the caller added. A Super Admin sees every user’s documents instead. Requires SQLAI to be present in the environment’s enabled AI services; otherwise the request fails with AI-1004 before authorization is even evaluated. Items carry only the seven projected summary attributes, not the full document record: fetch GET /nl2sql/training-documents/{id} for the association fields, uploaded files and download URL. Pagination: read next_available in the response. While it is “yes”, request the next page by advancing offset by limit. When it is “no” this was the last page and the client must stop.

Parameters:

• role_id (str) – Amorphic role ID the request is authorized against. The role must carry the playground.view permission. Not required when the request carries Super Admin context. (required)

• offset (int) – One-based index of the first record to return.

• limit (int) – Maximum number of documents to return in one page. Values above 1000 are rejected with IPV-1050.

• sortorder (str) – Direction to sort by. Only the exact value “desc” sorts descending; the backend treats every other value as ascending rather than rejecting it.

• sortby (str) – Attribute to sort by. The backend does not validate this value: naming an attribute that is absent from the projected record set causes the request to fail with HTTP 500, so restrict it to the listed values.

• filter_expression (str) – Substring filter applied to DocumentName. Only matching documents are returned.

• projection_expression (str) – Comma-separated list of attributes to return per document. Caveat: this parameter does not currently work on this operation. The backend applies the projection to the response envelope rather than to the document list, so supplying it returns an array of empty objects and loses the pagination keys. Omit it until the backend is fixed.

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

NL2SQLTrainingDocumentsList

Returns:

Returns the result object.

Request and Response Examples

HTTP: GET /nl2sql/training-documents

Parameter examples

Name	In	Example
role_id	header	"role-admin"
offset	query	1
limit	query	100
sortorder	query	"desc"
sortby	query	"CreationTime"
filterExpression	query	"orders"
projectionExpression	query	"DocumentId,DocumentName"

Success (HTTP 200)

Page of training documents. Check next_available to decide whether to request a further page.

Page of training documents

{
  "TrainingDocuments": [
    {
      "DocumentId": "b1e6c2a0-9f4d-4c7a-8f2e-1a2b3c4d5e6f",
      "DocumentName": "monthly_orders_examples",
      "DocumentType": "SQL",
      "UserId": "user1",
      "CreationTime": "2025-01-15 10:30:00",
      "LastModifiedBy": "user1",
      "LastModifiedTime": "2025-06-01 14:22:00"
    },
    {
      "DocumentId": "c2f7d3b1-1a2b-4d8e-9f3a-2b3c4d5e6f70",
      "DocumentName": "sales_glossary",
      "DocumentType": "Documentation",
      "UserId": "user1",
      "CreationTime": "2025-02-02 08:10:00",
      "LastModifiedBy": "user1",
      "LastModifiedTime": "2025-02-02 08:10:00"
    }
  ],
  "next_available": "no",
  "count": 2,
  "total_count": 2
}

No training documents added yet

{
  "TrainingDocuments": [],
  "next_available": "no",
  "count": 0,
  "total_count": 0
}

Errors

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

HTTP 400

Input validation or authorization failure. Body is {“Message”: “<CODE> - <text>”}. Codes: AI-1004 (SQLAI is not enabled in this environment), IPV-1050 (limit above 1000), AUTH-1001 (role_id header missing), AUTH-1030 (role lacks playground.view).

SQLAI is not enabled for this environment

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

limit above the maximum of 1000

{
  "Message": "IPV-1050 - Out of range for items per page, Limit is 1000"
}

role_id header absent

{
  "Message": "AUTH-1001 - Missing role information in event header"
}

HTTP 500

Backend failure. Also returned when sortby names an attribute that is absent from the projected records. Body is {“Message”: “<CODE> - <text>”}.