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.
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}/list
Request URL Parameters
Parameter | Type | Description | Required |
---|---|---|---|
tenantName | String | The tenant name (case-sensitive) | Required starting with 2023.7.0 |
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://mycluster.incorta.com/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 | 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 (as of the 2023.7.0 release) when the endpoint returns the object list and details successfully (code 200).
{"total": integer,"limit": integer,"offset": integer,"globalErrorMessages": ["string"],"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","isEncrypt": boolean}]}],"viewsDetails": [{"name": "string","description": "string","type": "string","owner": "string","baseTable": "string","query": "string","columns": [{"name": "string","label": "string","description": "string","function": "string","isFormula": boolean"source": "string","dataType": "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 |
globalErrorMessages | Error messages. This parameter is available starting with 2023.7.0. | Array of strings |
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 > isEncrypt | Specifies if the column is encrypted or not. The name of this parameter was encrypt in releases before 2023.7.0. | 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.
2023.7.0 introduced some updates to the view details, including the source column and its data type parameters.
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 source column function in Incorta | String Available values are: ● key (SQL and business schema views only) ● measure ● dimension |
columns > isFormula | Specifies if the column is a formula column or not. Applicable to business schema views only. This parameter is available starting with 2023.7.0. | Boolean |
columns > source | The source column of a business schema view column or the formula expression in the case of a business schema view formula column. Applicable to business schema views only. This parameter is available starting with 2023.7.0. In previous releases, only the formula parameter was available to show the formula expression of formula columns. | String |
columns > dataType | The data type of the source column or the calculated formula column. This parameter is available starting with 2023.7.0. | 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": "","isEncrypt": false},{"name": "LineCost","label": "Line Cost","description": "","dataType": "","function": "measure","formula": "OnlineStore.product.StandardCost * OnlineStore.salesorderdetail.OrderQty","isEncrypt": 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": "dimension","isFormula": false,"source": "EBS_ONT.OE_ORDER_LINES_ALL.LINE_CATEGORY_CODE","dataType": "string"},{"name": "On_TIME_SHIP_FLAG","label": "On Time Shipment Flag","description": "","function": "measure","isFormula": true,"source": "if(daysBetween( ifNull(OrderManagement.SalesOrderLine.ACTUAL_SHIPMENT_DATE,$currentDate), ifNull(OrderManagement.SalesOrderLine.PROMISE_DATE,$currentDate)) > 0, 'N', 'Y' )","dataType": "string"},{...other columns...}]},{...other views...}]}