trigger_documents_sync¶

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

Trigger a SQL AI documents sync

Starts a knowledge-base ingestion job that syncs the uploaded SQL AI training documents into the store backing the chatbot. Run this after adding, replacing or deleting training documents, since those changes do not affect the chatbot’s answers until a sync completes. The sync is asynchronous: a 200 means the job started, not that ingestion has finished. Poll GET /nl2sql/sync-jobs and match on the returned RunId to follow its progress. Only one sync may run at a time per tenant. A concurrent request is rejected, but note that the handler raises that conflict as a backend exception, so it surfaces as HTTP 500 rather than 409 or 400. Requires SQLAI to be present in the environment’s enabled AI services; otherwise the request fails with AI-1004.

Parameters:

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

NL2SQLSyncJobTriggerResponse

Returns:

Returns the result object.

Request and Response Examples¶

HTTP: POST /nl2sql/sync-jobs

Parameter examples¶

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

Request¶

The request body is optional.

Sync the environment’s own tenant

{}

Sync a named tenant

{
  "TenantName": "amorphic"
}

Success (HTTP 200)¶

Sync job started. Use RunId with GET /nl2sql/sync-jobs to track it.

Request / response example

{
  "RunId": "AB12CD34EF",
  "Message": "Successfully triggered the documents sync"
}

Errors¶

Documented error codes: AI-1004, GE-1034, AUTH-1001, AUTH-1030, DB-1001.

HTTP 400

Input validation or authorization failure. Body is {“Message”: “<CODE> - <text>”}. Codes: AI-1004 (SQLAI is not enabled), GE-1034 (the ingestion job could not be triggered), AUTH-1001 (role_id header missing), AUTH-1030 (role lacks playground.manage).

Ingestion job could not be started

{
  "Message": "GE-1034 - Failed to trigger sync job"
}

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, and also two conditions that are really caller errors: a sync is already running for the tenant (GE-1034), and an unknown TenantName, which fails while resolving the tenant’s configuration and produces a message with no error-code prefix. Codes: GE-1034, DB-1001 (the run record could not be persisted). Body is {“Message”: “<CODE> - <text>”}.

A sync is already in progress for this tenant

{
  "Message": "GE-1034 - A SQLAI knowledge base operation is already in progress, please try again later"
}

The sync run record could not be saved

{
  "Message": "DB-1001 - Failed to create the sync job record"
}