Public API v1 → 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 v1, refer to References → Public API v1.
You must use the HTTPS
scheme to be able to successfully run the API endpoints.
Request URL
https://<cluster_URL>/incorta/api/v1/schema/<schemaName>/status
HTTP method
GET
Request URL parameters
Parameter | Type | Description | Required | Values | Example |
---|---|---|---|---|---|
schemaName | String | The name of the physical or business schema you want to check its status | Yes | The physical or business schema name (case-sensitive) | "Schema1" |
Request URL example
https://my-cluster.cloud.incorta.com/incorta/api/v1/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 v1 → Create Token Endpoint.
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 | {"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 | Resource Not Found | {"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 ● EXTRACTION ● WAITING_FOR_RESOURCES ● TRANSFORMATION ● LOADING ● 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 |
Starting the 2022.11.0 release, the EXTRACTION, TRANSFORMATION, LOADING stages won't be available as the stages of a running load job are now limited to PLANNING, RUNNING and POST_LOAD.
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}]}