Public API v2 → List Schema Objects
About the /schema/{schemaName}/list endpoint
The /schema/{schemaName}/list endpoint returns the list and details of tables or views in a specific physical schema or business schema.
Only users who have permission to access physical schemas or business schemas can use the /schema/{schemaName}/list endpoint to list the objects in a business or physical schema that they own or have access rights to.
For information about how to get started with Public API v2, refer to References → Public API v2.
Use the HTTPS
or HTTP
scheme according to your installation.
Request URL
https://<cluster_URL>/incorta/api/v2/{tenantName}/schema/{schemaName}/list
https://<server address>:<port>/incorta/api/v2/{tenantName}/schema/{schemaName}/list
Request URL Parameters
Parameter | Type | Description | Required |
---|---|---|---|
tenantName | String | The tenant name (case-sensitive) | Required |
schemaName | String | Specify the name (case-sensitive) of the business or physical schema that you want to list its objects | Required |
Request URL example
https://10.0.0.1/incorta/api/v2/default/schema/OnlineStore/list
HTTP method
POST
Request headers
{"Content-Type": "application/json","Accept": "application/json","Authorization": "Bearer {access_token}"}
You must use a valid access token of a user who owns or has access rights to the physical or business schema you want to list its tables or views. For information about how to create an access token, refer to Public API v2 → Create an API access token.
Request body
{"limit": number,"offset": number,}
Request body parameters
The following table describes the request body parameters in the /schema/{schemaName}/list endpoint.
Parameter | Type | Description | Required? | Values |
---|---|---|---|---|
limit | Integer | The maximum number of objects (tables or views) to return, accounting for the offset you define | Required | Between 0 and 200. A value of 0 means all objects if their number is less than or equal to 200. Otherwise, the endpoint returns only 200 objects. |
offset | Integer | The number of objects to skip before returning the number of objects defined in the limit parameter | Required | Between 0 and 2147483647 (the maximum value of an integer) |
Request body example
{"limit": 2,"offset": 1,}
Endpoint response
The following table shows the HTTP response status codes for this endpoint.
Code | Description | Payload Response |
---|---|---|
200 | OK The endpoint successfully ran and returned the schema objects if any. | {"total": integer,"limit": integer,"offset": integer,"tablesDetails": [...]"viewsDetails": [...]} |
400 | Bad Request You provided invalid values for the request parameters. | {"message": "string"} Example: Numeric value (9999999999999) out of range of int (-2147483648 - 2147483647) at [Source: (org.glassfish.jersey.message.internal.ReaderInterceptorExecutor$UnCloseableInputStream); line: 3, column: 54] (through reference chain: com.incorta.publicapi.model.schema.list.SchemasListRequest["offset"]) |
401 | Unauthorized The endpoint couldn’t return the object list due to authentication errors, such as an invalid or expired access token, or the tenant name doesn’t match the tenant in the access token. | {"message": "string"} Example: {"message": "INC_09030108: Invalid authentication header. Invalid Token [abcd1234]..."} |
403 | Forbidden You don’t have access rights to view the specified schema. | {"message": "string"} Example: {"message": "INC_02010000: You are not authorized to VIEW the SCHEMADEFINITION of ID [259]." } |
404 | Not Found ● The endpoint couldn’t find the specified schema. ● The tenant doesn't exist or is disabled. | {"message": "string"} Example: {"message": "INC_05022801: The [onlineStore] SCHEMADEFINITION cannot be found."} |
422 | Unprocessable Entity You provided a value for the limit or offset that is out of the accepted range. | {"errorMessages":[{"message": "string"}] Example: {"errorMessages": [{"message": "INC_01210000: offset must be between 0 and 2147483647"},{"message": "INC_01210000: limit must be between 0 and 200"}]} |
500 | Internal Server Error The endpoint couldn’t return the schema list due to a server error. | {"message": "string"} Example: {"message": "Schema model definition is being updated, please try again later"} |
Response parameters
The following are the parameters in the /schema/{schemaName}/list endpoint response when the endpoint returns the object list and details successfully (code 200).
{"total": integer,"limit": integer,"offset": integer,"tablesDetails": [{"name": "string","type": "string","owner": "string","multiDataSource": boolean,"hierarchy": boolean,"rowsCount": integer,"lastVersionTimestamp": integer,"lastVersionPath": "string","incrementsPaths": ["string"],"keyColumns": ["string"],"columns": [{"name": "string","label": "string","description": "string","dataType": "string","function": "string","formula": "string","encrypt": boolean}]}],"viewsDetails": [{"name": "string","description": "string","type": "string","owner": "string","baseTable": "string","query": "string","columns": [{"name": "string","label": "string","description": "string","function": "string","formula": "string"}]}]}
The following table describes these response parameters.
Parameter | Description | Type/Value |
---|---|---|
total | The total number of objects in the specified schema | Integer |
limit | The maximum number of objects to return, which you defined in the request. | Integer |
offset | The number of skipped objects, which you defined in the request. | Integer |
tablesDetails | The details of each physical schema object that the endpoint returns. Available only in the case of a physical schema. See Tables Details parameters. | Array of objects |
viewsDetails | The details of each view that the endpoint returns. Available only in the case of a business schema. See Views Details parameters. | Array of objects |
Tables Details parameters
The following table describes the parameters in the Tables Details. These parameters are available only when listing objects in a physical schema.
Parameter | Description | Type/Value |
---|---|---|
name | The object name | String |
type | The object type | String Available values are: ● table ● materializedView ● alias ● incortaAnalyzer ● incortaSql table |
owner | The physical schema owner | String |
multiDataSource | Specifies if the object is a multi-source table or not. Only a physical schema table can be a multi-source object. | Boolean |
hierarchy | Specifies if the object has a self-join or not | Boolean |
rowsCount | The number of rows: ● In the case of performance-optimized objects, this is the number of rows loaded into the Engine memory.- ● In the case of non-performance-optimized objects, this is the number of rows in the parquet files | Integer |
lastVersionTimestamp | The timestamp of the object’s last version | Integer |
lastVersionPath | The path of the object’s last version on the shared storage | String |
incrementsPaths | The path of the object’s increments on the shared storage | Array of strings |
keyColumns | The names of the key columns in this object if any | Array of strings |
columns | The details of each data or formula column in the object | Array of objects |
columns > name | The column name | String |
columns > label | The column label | String |
columns > description | The column description | String |
columns > dataType | The data type of the column as specified in Incorta. Applicable to data columns only. | String |
columns > function | The column function in Incorta | String Available values are: ● key ● measure ● dimension |
columns > formula | The formula expression in the case of a formula column | String |
columns > encrypt | Specifies if the column is encrypted or not | Boolean |
Views Details parameters
The following table describes the parameters in the Views Details. These parameters are available only when listing objects in a business schema.
Parameter | Description | Type/Value |
---|---|---|
name | The view name | String |
description | The view description | String |
type | The view type | String Available values are: ● BUSSINESS_VIEW ● INCORTA_ANALYZER_VIEW ● INCORTA_SQL_VIEW |
owner | The business schema owner | String |
baseTable | The view’s base table. Available only in the case of a business view. | String |
query | The view query.Available only in the case of an Analyzer or SQL view | String |
columns | The details of columns in each view | Array of objects |
columns > name | The column name | String |
columns > label | The column label | String |
columns > description | The column description | String |
columns > function | The column function in Incorta. Applicable to formula columns only. | String Available values are: ● measure ● dimension |
columns > formula | The formula expression in the case of a formula column | String |
Physical schema response example
{"total": 36,"limit": 0,"offset": 0,"tablesDetails": [{"name": "salesorderdetail","type": "table","owner": "System Admin","multiDataSource": false,"hierarchy": false,"rowsCount": 9067608,"lastVersionTimestamp": 1679052,"lastVersionPath": "gs://cluster-12abc-bucket/Tenants/default/source/OnlineStore/salesorderdetail/1679052","incrementsPaths": ["gs://cluster-12abc-bucket/Tenants/default/source/OnlineStore/salesorderdetail/1679052/1679052"],"keyColumns": ["SalesOrderID", "SalesOrderDetailID"],"columns": [{"name": "SalesOrderID","label": "Salesorderid","description": "","dataType": "integer","function": "key","formula": "","encrypt": false},{"name": "LineCost","label": "Line Cost","description": "","dataType": "","function": "measure","formula": "OnlineStore.product.StandardCost * OnlineStore.salesorderdetail.OrderQty","encrypt": false},{...other columns...}]},{...other tables...}]}
Business schema response example
{"total": 9,"limit": 0,"offset": 0,"viewsDetails": [{"name": "SalesOrderLine","description": "","type": "BUSSINESS_VIEW","owner": "System Admin","baseTable": "EBS_ONT.OrderDetails","columns": [{"name": "LINE_CATEGORY_CODE","label": "Line Category Code","description": "","function": "","formula": ""},{"name": "On_TIME_SHIP_FLAG","label": "On Time Shipment Flag","description": "","function": "measure","formula": "if(daysBetween( ifNull(OrderManagement.SalesOrderLine.ACTUAL_SHIPMENT_DATE,$currentDate), ifNull(OrderManagement.SalesOrderLine.PROMISE_DATE,$currentDate)) > 0, 'N', 'Y' )"},{...other columns...}]},{...other views...}]}