Public API v2 → Schema Status Endpoint

About the /schema/{schemaName}/status endpoint

The /schema/{schemaName}/status endpoint returns the details of a specific physical or business schema. The details include the available objects (tables or views), number of column per object, creation and modification time, and schema owner. In addition, it returns the status of the recent model update and load jobs and the data size in the case of physical schemas.

For information about how to get started with Public API v2, refer to References → Public API v2.

Note

You must use the HTTPS scheme to be able to successfully run the API endpoints. Additionally, you must specify the tenant name (case-sensitive) in the endpoint request URL starting with the 2023.7.0 release.

Request URL

https://<cluster_URL>/incorta/api/v2/{tenantName}/schema/<schemaName>/status

HTTP method

GET

Request URL parameters

Parameter	Description	Type	Required
tenantName	The tenant name (case-sensitive)	String	Required starting with 2023.7.0
schemaName	The name of the physical or business schema you want to check its status (case-sensitive)	String	Required

Request URL example

https://my-cluster.cloud.incorta.com/incorta/api/v2/default/schema/SALES/status

Request headers

{
"Authorization": "Bearer {access_token}"
}

You must use a valid access token of a user who has access rights to the physical or business schema you want to check its status.

For information about how to create an access token, refer to Public API v2 → Create an API access token.

Request headers example

{
"Authorization": "Bearer ABC123456789"
}

Endpoint response

The following table shows the HTTP response status codes for this endpoint.

Code	Description	Payload Response
200	The endpoint returned the schema status successfully.	The status and details of the physical or business schema in the request. `{schemaName: "string" schemaDescription: "string" schemaType: "string" ownerName: "string" creationDate: "string($date-time)" lastModifierName: "string" lastModificationDate: "string($date-time" physicalSchemaDetails:{} tables: [...] }}` For more information, see Response parameters and Response examples.
400	Bad request	`{"message": "string"}`
401	Unauthorized ● Invalid or expired access token. ● The tenant name doesn’t match the tenant in the access token.	`{"message": "string"}` Example: {"message": "INC_09030101: Invalid access token or access token may have expired."}
403	Forbidden	`{"message": "string"}` Example: {"message": "INC_02010000: You are not authorized to VIEW the HR_BS SCHEMADEFINITION of ID [46,846]."}
404	Not Found ● The schema doesn't exist. ● The tenant doesn't exist or is disabled.	`{"message": "string"}` Example: {"message": "INC_05022803: The [HR_BS1] SCHEMADEFINITION cannot be found."}
500	Internal Server Error	`{"message": "string"}` Example: {"message": "INC_05000301: Runtime exception occurred [null]."}

Response parameters

The following are the parameters in the /schema/{schemaName}/status endpoint response when the endpoint returns the schema status and details successfully (code 200).

{
  "schemaName": "string",
  "schemaDescription": "string",
  "schemaType": "string",
  "ownerName": "string",
  "creationDate": "timestamp",
  "lastModifierName": "string",
  "lastModificationDate": "timestamp",
  "physicalSchemaDetails": {
    "dataSizeInMemoryInMegaBytes": 0,
    "dataSizeOnDiskInMegaBytes": 0,
    "elapsedLoadTimeInMilliseconds": 0,
    "lastLoadStatus": {
      "jobStatus": "string",
      "stateType": "string"
    },
    "modelUpdateStatus": {
      "jobStatus": "string",
      "stateType": "string"
    },
    "lastLoadTime": "timestamp",
    "lastLoadType": "string",
    "nextLoadTime": "timestamp",
    "nextLoadType": "string"
  },
  "tables": [
    {
      "tableName": "string",
      "numberOfColumns": 0,
      "physicalTableDetails": {
        "numberOfRows": 0,
        "dataSizeInMemoryInMegaBytes": 0,
        "dataSizeOnDiskInMegaBytes": 0,
        "requiredLoadAction": "string"
      }
    }
  ]
}

The following table describes these response parameters.

Parameter	Description	Type/Values
schemaName	The schema name	String
schemaDescription	The schema description	String
schemaType	The schema type	String ● PHYSICAL ● BUSINESS
ownerName	The name of the schema owner	String
creationDate	The schema creation date and time	Timestamp (converted to long)
lastModifierName	The name of the user who last modified the schema	String
lastModificationDate	The schema modification date and time	Timestamp (converted to long)
physicalSchemaDetails	Attributes related to physical schemas only and not available when checking the status of a business schema. See Physical Schema Details parameters.
tables	The details of each table or view in the physical or business schema in the request
tables > tableName	The name of the table or view	String
tables > numberOfColumns	The number of columns in the table or view	Long
tables > physicalTableDetails	Parameters related to physical schema objects only and not available when checking the status of a business schema. See Physical Table Details parameters.

Physical Schema Details parameters

The following table describes the additional parameters in the code-200 response of the /schema/{schemaName}/status endpoint when checking the status of a physical schema.

Parameter	Description	Type/Values
dataSizeInMemoryInMegaBytes	The total size of the physical schema data in memory (MBs)	Double
dataSizeOnDiskInMegaBytes	The total size of the physical schema data on disk including snapshot DDM files and staging parquet files (MBs)	Double
elapsedLoadTimeInMilliseconds	Time elapsed during the last load job	Long
lastLoadStatus	The state and status of the scheme’s latest (last or current) load job. See Job statuses and states.
lastLoadStatus > jobStatus	The status of the respective load state The value varies depending on the state type.	String
lastLoadStatus > stateType	The state of the load job when executing the endpoint	String ● Compaction State ● Load State ● Terminator State ● N/A State
modelUpdateStatus	The state and status of the scheme’s latest (last or current) model update job See Job statuses and states.	String
modelUpdateStatus > jobStatus	The status of the respective model update state The value varies depending on the state type.	String
modelUpdateStatus > stateType	The state of the model update job when executing the endpoint	String ● Sync State ● Terminator State ● Update State ● N/A State
lastLoadTime	The starting time of the latest load job	Timestamp (converted to long)
lastLoadType	The load type of the latest load job	String ● FULL ● INCREMENTAL ● STAGING
nextLoadTime	The time of the next scheduled load job	Timestamp (converted to long)
nextLoadType	The load type of the next scheduled load job	String ● FULL ● INCREMENTAL ● STAGING

Physical Table Details parameters

The following table describes the Physical Table Details parameters. These parameters are available only when checking the status of a physical schema. In addition, most of these parameters apply to all physical schema objects and are not limited to physical schema tables only.

Parameter	Description	Type/Values
numberOfRows	The number of rows loaded into the engine memory	Long
dataSizeInMemoryInMegaBytes	The total size of the table data in the engine memory (MBs)	Double
dataSizeOnDiskInMegaBytes	The total size of the table data on disk including snapshot DDM files and staging parquet files (MBs)	Double
requiredLoadAction	The required load type. Applicable to physical schema tables and materialized views only. For more details, refer to Changes that require data load.	String ● NONE ● FULL_LOAD ● LOAD_FROM_STAGING

Job statuses and states

The following table describes the different state types and corresponding statuses that the endpoint returns when checking the status of a physical schema.

State Type	Description	Statuses
Compaction State	Shows the stages of a running compaction job.	● INITIAL ● STARTED ● NA
Load State	Shows the stages of a running load job	● IN_QUEUE ● PLANNING ● WAITING_FOR_RESOURCES ● RUNNING ● POST_LOAD ● INTERRUPTING ● NA
Sync State	Shows the status of the synchronization process in the model update or load job	● NOT_SYNCED ● SYNC ● NA
Terminator State	Shows the status of the last job. The endpoint returns this state when there is no running job.	● SUCCESS ● FAILED ● FINISHED_WITH_ERRORS ● INTERRUPTED ● ABORTED ● NA The INTERRUPTED and ABORTED statuses apply only to the `jobStatus` object in the `lastLoadStatus` property.
Update State	Shows the stages of a running model update job	● IN_QUEUE ● UPDATE ● POST_UPDATE_CALCULATION ● COMMIT ● SYNC ● NA
N/A State	Returned when there is no previous or current job for the physical schema (load, compaction, model update, or synchronization)	● NA

Response examples

The following are two examples of the endpoint response.

Physical schema example

{
 "schemaName": "HR",
 "schemaDescription": "",
 "schemaType": "PHYSICAL",
 "ownerName": "Super User",
 "creationDate": 1664700099000,
 "lastModifierName": "Super User",
 "lastModificationDate": 1664831153000,
 "physicalSchemaDetails": {
   "dataSizeInMemoryInMegaBytes": 0.0625,
   "dataSizeOnDiskInMegaBytes": 0.009608268737792969,
   "elapsedLoadTimeInMilliseconds": 0,
   "lastLoadStatus": {
     "stateType": "Load State",
     "jobStatus": "Extraction"
   },
   "modelUpdateStatus": {
     "stateType": "Terminator State",
     "jobStatus": "Success"
   },
   "lastLoadTime": 1664831153000,
   "lastLoadType": "FULL",
   "nextLoadTime": 0,
   "nextLoadType": "NA"
 },
 "tables": [
   {
     "tableName": "HR.DEPARTMENTS",
     "numberOfColumns": 5,
     "physicalTableDetails": {
       "numberOfRows": 11,
       "dataSizeInMemoryInMegaBytes": 0,
       "dataSizeOnDiskInMegaBytes": 0.0012922286987304688,
       "requiredLoadAction": "NONE"
     }
   },
   {
     "tableName": "HR.EMPLOYEES",
     "numberOfColumns": 14,
     "physicalTableDetails": {
       "numberOfRows": 107,
       "dataSizeInMemoryInMegaBytes": 0.015625,
       "dataSizeOnDiskInMegaBytes": 0.00791168212890625,
       "requiredLoadAction": "LOAD_FROM_STAGING"
     }
   }
 ]
}

Business schema example

{
  "schemaName": "HR_BS",
  "schemaDescription": "",
  "schemaType": "BUSINESS",
  "ownerName": "Super User",
  "creationDate": 1664700099000,
  "lastModifierName": "Super User",
  "lastModificationDate": 1664700099000,
  "tables": [
    {
      "tableName": "HR_BS.Dept_BS",
      "numberOfColumns": 5
    },
    {
      "tableName": "HR_BS.Employee_BS",
      "numberOfColumns": 9
    }
  ]
}

Content