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

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
tableDetails	The details of each physical schema object that the endpoint returns. Available only in the case of a physical schema. See Table Details parameters.	Array of objects
viewDetails	The details of each view that the endpoint returns. Available only in the case of a business schema. See View Details parameters.	Array of objects

Table Details parameters

The following table describes the parameters in the Table 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

View Details parameters

The following table describes the parameters in the View Details. These parameters are available only when listing objects in a business schema.