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.

Note

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

ParameterTypeDescriptionRequired
tenantNameStringThe tenant name (case-sensitive)Required
schemaNameStringSpecify the name (case-sensitive) of the business or physical schema that you want to list its objectsRequired

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.

ParameterTypeDescriptionRequired?Values
limitIntegerThe maximum number of objects (tables or views) to return, accounting for the offset you defineRequiredBetween 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.
offsetIntegerThe number of objects to skip before returning the number of objects defined in the limit parameterRequiredBetween 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.

CodeDescriptionPayload Response
200OK
The endpoint successfully ran and returned the schema objects if any.
{"total": integer,"limit": integer,"offset": integer,"tablesDetails": [...]"viewsDetails": [...]}
400Bad 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"]) 
401Unauthorized
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]..."}
403Forbidden
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]." }
404Not 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."}
422Unprocessable 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"}]}
500Internal 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.

ParameterDescriptionType/Value
totalThe total number of objects in the specified schemaInteger
limitThe maximum number of objects to return, which you defined in the request.Integer
offsetThe number of skipped objects, which you defined in the request.Integer
tablesDetailsThe 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
viewsDetailsThe 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.

ParameterDescriptionType/Value
nameThe object nameString
typeThe object typeString
Available values are:
  ●  table
  ●  materializedView
  ●  alias
  ●  incortaAnalyzer
  ●  incortaSql table
ownerThe physical schema ownerString
multiDataSourceSpecifies if the object is a multi-source table or not. Only a physical schema table can be a multi-source object.Boolean
hierarchySpecifies if the object has a self-join or notBoolean
rowsCountThe 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
lastVersionTimestampThe timestamp of the object’s last versionInteger
lastVersionPathThe path of the object’s last version on the shared storageString
incrementsPathsThe path of the object’s increments on the shared storageArray of strings
keyColumnsThe names of the key columns in this object if anyArray of strings
columnsThe details of each data or formula column in the objectArray of objects
columns > nameThe column nameString
columns > labelThe column labelString
columns > descriptionThe column descriptionString
columns > dataTypeThe data type of the column as specified in Incorta.
Applicable to data columns only.
String
columns > functionThe column function in IncortaString
Available values are:
  ●  key
  ●  measure
  ●  dimension
columns > formulaThe formula expression in the case of a formula columnString
columns > encryptSpecifies if the column is encrypted or notBoolean

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.

ParameterDescriptionType/Value
nameThe view nameString
descriptionThe view descriptionString
typeThe view typeString
Available values are:
  ●  BUSSINESS_VIEW
  ●  INCORTA_ANALYZER_VIEW
  ●  INCORTA_SQL_VIEW
ownerThe business schema ownerString
baseTableThe view’s base table.
Available only in the case of a business view.
String
queryThe view query.Available only in the case of an Analyzer or SQL viewString
columnsThe details of columns in each viewArray of objects
columns > nameThe column nameString
columns > labelThe column labelString
columns > descriptionThe column descriptionString
columns > functionThe column function in Incorta.
Applicable to formula columns only.
String
Available values are:
  ●  measure
  ●  dimension
columns > formulaThe formula expression in the case of a formula columnString

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...}]}