Public API v2 → Extract to External Table Endpoint

About the POST /extraction/table endpoint

The POST /extraction/table endpoint creates a new external table in the Spark Metastore within an existing external schema, extracts data from the specified business view, and saves the Parquet files to the specified path. If the specified path contains Parquet files or the table already exists in the Spark Metastore, the endpoint returns an error. However, you can instruct the endpoint to replace or overwrite the existing external table or Parquet files. This endpoint is available starting 2024.1.4.

Before using this endpoint, you must set the required configurations, such as enabling and configuring Advanced SQLi and setting the CMC configurations, and create the external schema first. For more information, refer to References → Data Extraction via Advanced SQLi and Public API.

Only the Super admin user (and users with the SuperRole when the Super User Mode is enabled) can use this endpoint.

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. You must use the HTTPS scheme to successfully run the API endpoints on Cloud installations.

Request URL

https://<cluster_URL>/incorta/api/v2/{tenant}/extraction/table

Examples:

https://mycluster.incorta.com/incorta/api/v2/default/extraction/table
https://10.1.2.3:8080/incorta/api/v2/default/extraction/table

Request URL Parameters

Parameter	Description	Type	Required
tenant	The tenant name (case-sensitive)	String	Required

HTTP method

POST

Request headers

{
"Content-Type": "application/json",
"Accept": "application/json",
"Authorization": "Bearer {access_token}"
}

You must use a valid access token for the Super admin user (or a user with the SuperRole if the Super User Mode is enabled). For information about creating an access token, refer to Public API v2 → Create an API access token.

Request body

{
  "sourceTableName": "string",
  "targetTableName": "string",
  "targetPath": "string",
  "overwrite": "string",
  "limit": "string"
}

Request body parameters

Parameter	Type	Description	Required
sourceTableName	String	The fully qualified name of the verified business view in the following format: `business_schema.business_view`	Required
targetTableName	String	The fully qualified name of the external table in the following format: `external_schema.external_table`. The external schema must be one of the schemas specified for data extraction in the CMC > Tenant Configurations > Incorta Labs > External Schemas for Data Extraction.	Required
targetPath	String	The path of the destination to save the extracted Parquet files. The parent path must be one of the valid paths specified for data extraction in the CMC > Tenant Configurations > Incorta Labs > Target Paths for Data Extraction. Incorta must have read and write access to these paths. It is recommended to add a sub-directory to the parent path for each external table.	Required
overwrite	Boolean	Set to `true` to instruct the endpoint to replace existing Parquet files and the external table definition if the provided path is not empty or the target table already exists in the Spark Metastore. In such cases, if you set this parameter to `false`, the endpoint returns an error. If it is not set, the default is `false`.	Optional
limit	String/Integer	Specify if you want to extract all the view data, a specific number of records, or no data. Valid values are: ● "ALL" ● "NONE" ● An Integer value (For now, you cannot control the records to return. The endpoint automatically returns this first number of records.)	Required

Request body example

{
  "sourceTableName": "SalesBsSchema.CustomersView",
  "targetTableName": "externalSchema1.Sales_externalTable1",
  "targetPath": "gs://Mybucket/data_extraction/SalesParquerFiles",
  "overwrite": "false",
  "limit": 20
}

Endpoint response

The following table shows the HTTP response status codes for this endpoint.

Code	Description	Payload Response
200	OK The endpoint successfully ran, created the new external table, extracted the view data, and stored Parquet files to the specified path.
400	Bad Request You provided invalid values.	`{"errorMessages": [{"message": "string"}]}` Example: `{"Unrecognized token 'All': was expecting (JSON String, Number, Array, Object or token 'null', 'true' or 'false') at [Source: (org.glassfish.jersey.message.internal.ReaderInterceptorExecutor$UnCloseableInputStream); line: 6, column: 16]"}]}`
401	Unauthenticated The endpoint couldn’t create the external table due to authentication errors, such as an invalid or expired access token.	`{"message": "string"}` Example: `{"message": "INC_09030108: Invalid authentication header. Invalid Token [abcd1234]"}`
404	Not Found The tenant doesn't exist or is disabled.	`{"message": "string"}` Example: `{"message": "Invalid [DEFAULT] tenant in resource path"}`
500	Internal Server Error The endpoint couldn’t run successfully due to a server error.	`{"message": "string"}` Example: `{"message": "The target location gs://Mybucket/data_extraction/SalesParquerFiles not allowed for extraction"}`

Content