openapi: 3.2.0
info:
title: Pingcap Import API
version: '1.0'
description: 'Operations tagged Import across 3 of this provider''s published API definitions: pingcap-tidb-cloud-dedicated-v1beta1-openapi-original.json, pingcap-tidb-cloud-starter-essential-v1beta1-openapi-original.json, pingcap-tidb-cloud-v1beta-openapi-original.json. Each path carries the servers of the definition it was published in.'
basePath: /v1beta1
schemes:
- https
tags:
- name: Import
description: List import tasks, create an import task, get an import task, and cancel an import task.
paths:
/clusters/{clusterId}/imports:
get:
summary: List import tasks
description: Lists all import tasks for a cluster. You can use query parameters to control sorting, pagination, and the number of results returned.
operationId: ListImports
responses:
'200':
description: A successful response.
schema:
$ref: '#/definitions/v1beta1ListImportsResponse'
default:
description: An unexpected error response.
schema:
$ref: '#/definitions/rpcStatus'
parameters:
- name: clusterId
description: The ID of the cluster to list import tasks for.
in: path
required: true
type: string
- name: pageToken
description: The pagination token received from a previous [List import tasks](#tag/Import/operation/ListImports) request. Use this token to retrieve the next page of results.
in: query
required: false
type: string
- name: pageSize
description: The maximum number of import tasks to return. If not specified, at most 10 node specs will be returned.
in: query
required: false
type: integer
format: int32
default: 10
minimum: 1
maximum: 100
- name: orderBy
description: Specifies the sorting order of results. Use a comma-separated list of field names, optionally appending `desc` for descending order. For example, `createTime, name desc`. By default, fields are sorted in ascending order.
in: query
required: false
type: string
tags:
- Import
x-code-samples:
- lang: curl
label: curl
source: "curl --digest --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \\\n --location 'https://dedicated.tidbapi.com/v1beta1/clusters/{clusterId}/imports'"
post:
summary: Create an import task
description: Creates an import task to import data into a cluster.
operationId: CreateImport
responses:
'200':
description: A successful response.
schema:
$ref: '#/definitions/v1beta1Import'
default:
description: An unexpected error response.
schema:
$ref: '#/definitions/rpcStatus'
parameters:
- name: clusterId
description: The ID of the target cluster where data will be imported.
in: path
required: true
type: string
- name: import
description: The configuration details of the import task to be created.
in: body
required: true
schema:
$ref: '#/definitions/v1beta1Import'
tags:
- Import
x-code-samples:
- lang: curl
label: curl
source: "curl --digest --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \\\n --location 'https://dedicated.tidbapi.com/v1beta1/clusters/{clusterId}/imports' --header 'Content-Type: application/json' --data '{\n \"creationDetails\": {\n \"importOptions\": {\n \"fileType\": \"CSV\"\n },\n \"source\": {\n \"type\": \"S3\",\n \"s3\": {\n \"uri\": \"s3://{bucket_name}/{path_to_data}/\",\n \"authType\": \"ACCESS_KEY\",\n \"accessKey\": {\n \"id\": \"YOUR_ACCESS_KEY\",\n \"secret\": \"YOUR_SECRET_KEY\"\n }\n }\n }\n }\n}'"
/clusters/{clusterId}/imports/{importId}:
get:
summary: Get an import task
description: Retrieves details of a specific import task by its ID.
operationId: GetImport
responses:
'200':
description: A successful response.
schema:
$ref: '#/definitions/v1beta1Import'
default:
description: An unexpected error response.
schema:
$ref: '#/definitions/rpcStatus'
parameters:
- name: clusterId
description: The ID of the cluster that contains the import task.
in: path
required: true
type: string
- name: importId
description: The ID of the import task to retrieve.
in: path
required: true
type: string
tags:
- Import
x-code-samples:
- lang: curl
label: curl
source: "curl --digest --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \\\n --location 'https://dedicated.tidbapi.com/v1beta1/clusters/{clusterId}/imports/{importId}'"
/clusters/{clusterId}/imports/{importId}:cancel:
post:
summary: Cancel an import task
description: Cancels a running import task by its ID.
operationId: CancelImport
responses:
'200':
description: A successful response.
schema:
type: object
properties: {}
default:
description: An unexpected error response.
schema:
$ref: '#/definitions/rpcStatus'
parameters:
- name: clusterId
description: The ID of the cluster that contains the import task.
in: path
required: true
type: string
- name: importId
description: The ID of the import task to cancel.
in: path
required: true
type: string
- name: body
in: body
required: true
schema:
type: object
description: The ID of the import task.
tags:
- Import
x-code-samples:
- lang: curl
label: curl
source: "curl --digest --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \\\n --location --request POST 'https://dedicated.tidbapi.com/v1beta1/clusters/{clusterId}/imports/{importId}:cancel'"
/clusters/{clusterId}/imports/{id}:
get:
summary: Get details of an import task
operationId: ImportService_GetImport
responses:
'200':
description: A successful response.
schema:
$ref: '#/definitions/v1beta1Import_2'
'400':
description: A request field is invalid.
schema:
$ref: '#/definitions/googlerpcStatus'
'401':
description: The API key cannot be authenticated.
schema:
$ref: '#/definitions/googlerpcStatus'
'403':
description: The API key does not have permission to access the resource.
schema:
$ref: '#/definitions/googlerpcStatus'
'429':
description: You have exceed the rate limit.
schema:
$ref: '#/definitions/googlerpcStatus'
'500':
description: Internal server error.
schema:
$ref: '#/definitions/googlerpcStatus'
default:
description: An unexpected error response.
schema:
$ref: '#/definitions/googlerpcStatus'
parameters:
- name: clusterId
description: The ID of the TiDB Cloud Starter or Essential instance.
in: path
required: true
type: string
- name: id
description: The ID of the import task.
in: path
required: true
type: string
tags:
- Import
x-codeSamples:
- label: curl
lang: cURL
source: 'curl --location ''https://serverless.tidbapi.com/v1beta1/clusters/{cluster_id}/imports/{import_id}'' \
--digest --user ''YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY'' \
--header ''Accept: application/json'''
/clusters/{clusterId}/imports/{id}:cancel:
post:
summary: Cancel an import task
operationId: ImportService_CancelImport
responses:
'200':
description: A successful response.
schema:
type: object
properties: {}
'400':
description: A request field is invalid.
schema:
$ref: '#/definitions/googlerpcStatus'
'401':
description: The API key cannot be authenticated.
schema:
$ref: '#/definitions/googlerpcStatus'
'403':
description: The API key does not have permission to access the resource.
schema:
$ref: '#/definitions/googlerpcStatus'
'429':
description: You have exceed the rate limit.
schema:
$ref: '#/definitions/googlerpcStatus'
'500':
description: Internal server error.
schema:
$ref: '#/definitions/googlerpcStatus'
default:
description: An unexpected error response.
schema:
$ref: '#/definitions/googlerpcStatus'
parameters:
- name: clusterId
description: The ID of the TiDB Cloud Starter or Essential instance.
in: path
required: true
type: string
- name: id
description: The ID of the import task.
in: path
required: true
type: string
tags:
- Import
x-codeSamples:
- label: curl
lang: cURL
source: 'curl --location --request POST ''https://serverless.tidbapi.com/v1beta1/clusters/{cluster_id}/imports/{import_id}:cancel'' \
--digest --user ''YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY'' \
--header ''Accept: application/json'''
/api/v1beta/projects/{project_id}/clusters/{cluster_id}/imports:
get:
summary: List all import tasks for a cluster.
operationId: ListImportTasks
responses:
'200':
description: A successful response.
schema:
type: object
properties:
items:
type: array
items:
type: object
properties:
metadata:
description: The metadata of the import task.
type: object
properties:
id:
type: string
format: uint64
example: '1'
description: The ID of the import task.
name:
type: string
example: my_import
description: The name of the import task.
create_timestamp:
type: string
format: timestamp
example: '1676450597'
description: The creation time of the import task in Unix timestamp seconds (epoch time).
title: ImportMetadata
required:
- id
- create_timestamp
spec:
description: The specification of the import task.
type: object
properties:
source:
description: The data source settings of the import task.
type: object
properties:
type:
example: S3
description: 'The data source type of an import task.
- `"S3"`: import data from Amazon S3
- `"GCS"`: import data from Google Cloud Storage (only available for [TiDB Cloud Dedicated](https://docs.pingcap.com/tidbcloud/select-cluster-tier#tidb-cloud-dedicated) clusters)
- `"LOCAL_FILE"`: import data from a local file (only available for [TiDB Cloud Starter](https://docs.pingcap.com/tidbcloud/select-cluster-tier/#tidb-cloud-serverless) clusters). Before you import from a local file, you need to first upload the file using the [Upload a local file for an import task](#tag/Import/operation/UploadLocalFile) endpoint.
**Note:** Currently, if this import spec is used for a [preview](#tag/Import/operation/PreviewImportData) request, only the `LOCAL_FILE` source type is supported.'
type: string
enum:
- S3
- GCS
- LOCAL_FILE
uri:
type: string
example: s3://example-bucket/example-source-data/
description: 'The data source URI of an import task. The URI scheme must match the data source type. Here are the scheme of each source type:
* `S3`: `s3://`
* `GCS`: `gs://`
* `LOCAL_FILE`: `file://`.
**Note:** If the import source type is `LOCAL_FILE`, just provide the `upload_stub_id` of the uploaded file from the response of [Upload a local file for an import task](#tag/Import/operation/UploadLocalFile), and make it as the data source folder. For example: `file://12345/`.
**Limitation**: If the import source type is `LOCAL_FILE`, only the `CSV` source format type is supported.'
aws_assume_role_access:
description: 'The settings to access the S3 data by assuming a specific AWS role. This field is only needed if you need to access S3 data by assuming an AWS role.
**Note:** Provide only one of `aws_assume_role_access` and `aws_key_access`. If both `aws_assume_role_access` and `aws_key_access` are provided, an error will be reported.'
type: object
properties:
assume_role:
type: string
example: arn:aws:iam::999999999999:role/sample-role
description: The specific AWS role ARN that needs to be assumed to access the Amazon S3 data source.
title: AwsAssumeRoleAccess
required:
- assume_role
aws_key_access:
description: 'The settings to access the S3 data with an access key. This field is only needed if you want to access the S3 data with an access key.
**Note:** Provide only one of `aws_assume_role_access` and `aws_key_access`. If both `aws_assume_role_access` and `aws_key_access` are provided, an error will be reported.'
type: object
properties:
access_key_id:
type: string
example: YOUR_ACCESS_KEY_ID
description: The access key ID of the account to access the data. This information will be redacted when it is retrieved to obtain the import task information.
secret_access_key:
type: string
example: YOUR_SECRET_ACCESS_KEY
description: The secret access key for the account to access the data. This information will be redacted when it is retrieved to obtain the import task information.
title: AwsKeyAccess
required:
- access_key_id
- secret_access_key
format:
description: The format settings of the import data source.
type: object
properties:
type:
example: CSV
description: The format type of an import source.
type: string
enum:
- CSV
- PARQUET
- SQL
- AURORA_SNAPSHOT
csv_config:
description: The CSV format settings to parse the source CSV files. This field is only needed if the source format is CSV.
type: object
properties:
delimiter:
type: string
default: ','
description: The delimiter character used to separate fields in the CSV data.
quote:
type: string
default: '"'
description: The character used to quote the fields in the CSV data.
backslash_escape:
type: boolean
default: true
description: 'Whether a backslash (`\`) symbol followed by a character should be combined as a whole and treated as an escape sequence in a CSV field. For example, if this parameter is set to `true`, `\n` will be treated as a ''new-line'' character. If it is set to `false`, `\n` will be treated as two separate characters: backslash and `n`.
Currently, these are several supported escape sequences: `\0`, `\b`, `\n`, `\r`, `\t`, and `\Z`. If the parameter is set to `true`, but the backslash escape sequence is not recognized, the backslash character is ignored.'
has_header_row:
type: boolean
default: true
description: Whether the CSV data has a header row, which is not part of the data. If it is set to `true`, the import task will use the column names in the header row to match the column names in the target table.
title: ImportSourceCSVConfig
title: ImportSourceFormat
required:
- type
title: ImportSource
required:
- type
- uri
- format
target:
description: The target settings of the import task.
type: object
properties:
tables:
type: array
items:
type: object
properties:
database_name:
type: string
example: db01
description: The target database name.
table_name:
type: string
example: table01
description: The target table name.
file_name_pattern:
type: string
example: data/db01/table01.*.csv
description: 'The filename pattern used to map the files in the data source to this target table. The pattern should be a simple glob pattern. Here are some examples:
* `my-data?.csv`: all CSV files starting with `my-data` and one character (such as `my-data1.csv` and `my-data2.csv`) will be imported into the same target table.
* `my-data*.csv`: all CSV files starting with `my-data` will be imported into the same target table.
If no pattern is specified, a default pattern is used. The default pattern will try to find files with this naming convention as the data files for this table: `${db_name}.${table_name}.[numeric_index].${format_suffix}`.
Here are some examples of filenames that can be matched as data files for the table `db01.table01`: `db01.table01.csv`, `db01.table01.00001.csv`.
For more information about the custom file pattern and the default pattern, refer to [Import CSV Files from Amazon S3 or GCS into TiDB Cloud](https://docs.pingcap.com/tidbcloud/import-csv-files).
**Note:** For `LOCAL_FILE` import tasks, use the local file name for this field. The local file name must match the local file name in [Upload a local file for an import task](#tag/Import/operation/UploadLocalFile).'
description: ImportTargetTable represents the settings for importing source data into a single target table of an import task.
title: ImportTargetTable
required:
- database_name
- table_name
description: 'The settings for each target table that is being imported for the import task. If you leave it empty, the system will scan all the files in the data source using the default file patterns and collect all the tables to import. The files include data files, table schema files, and DB schema files. If you provide a list of tables, only those tables will be imported. For more information about the default file pattern, see [Import CSV Files from Amazon S3 or GCS into TiDB Cloud](https://docs.pingcap.com/tidbcloud/import-csv-files).
**Limitations:**
* Currently, if you want to use a custom filename pattern, you can only specify one table. If all the tables use the default filename pattern, you can specify more than one target table in `tables`.
* It is recommended that you pre-create the target tables before creating an import task. You can do this either by executing the `CREATE TABLE` statement in the cluster or by specifying the table definition in the table creation options.
* If a target table is not created, the import module tries to find a **TABLE SCHEMA FILE** containing the `CREATE TABLE` statement of the table in the data source folder with the name `${db_name}.${table_name}-schema.sql` (for example, `db01.tbl01-schema.sql`). If this file is found, the `CREATE TABLE` statement is automatically executed if the table doesn''t exist before the actual import process starts. If the table is still missing after this pre-create step, an error will occur.'
title: ImportTarget
title: ImportSpec
required:
- source
- target
status:
description: The status of the import task.
type: object
properties:
phase:
example: IMPORTING
description: The current phase that the import task is in.
type: string
enum:
- PREPARING
- IMPORTING
- COMPLETED
- FAILED
- CANCELING
- CANCELED
error_message:
type: string
example: some error occurs
description: The error message of the import task.
start_timestamp:
type: string
format: timestamp
example: '1676450597'
description: The start timestamp of the import task. The format is Unix timestamp (the seconds elapsed since the Unix epoch)
end_timestamp:
type: string
format: timestamp
example: '1676450897'
description: The end timestamp of the import task. The format is Unix timestamp (the seconds elapsed since the Unix epoch).
progress:
description: The progress of the import task.
type: object
properties:
import_progress:
type: number
format: double
example: 59
description: The overall importing progress of the import task.
maximum: 100
validation_progress:
type: number
format: double
example: 59
description: The overall validation progress of the import task after the data has been imported into the target cluster.
maximum: 100
title: ImportProgress
required:
- import_progress
- validation_progress
source_total_size_bytes:
type: string
format: uint64
example: '10737418240'
description: The total size of the import task's data source. The unit is bytes.
title: ImportStatus
required:
- phase
description: ImportItem represents the information of a single import task.
title: ImportItem
description: The import tasks in the cluster in the request page area.
total:
type: integer
format: int64
example: 20
description: The total number of import tasks in the cluster.
description: ListImportTasksResp is the response for listing the import tasks of a cluster.
title: ListImportTasksResp
required:
- items
- total
'400':
description: A request field is invalid.
schema:
type: object
properties:
code:
type: integer
format: integer
description: Error code returned with this error.
title: code
message:
type: string
description: Error message returned with this error.
title: message
details:
type: array
items:
type: string
description: Error details returned with this error.
title: details
'401':
description: The API key cannot be authenticated.
schema: {}
'403':
description: The API key does not have permission to access the resource.
schema:
type: object
properties:
code:
type: integer
format: integer
description: Error code returned with this error.
title: code
message:
type: string
description: Error message returned with this error.
title: message
details:
type: array
items:
type: string
description: Error details returned with this error.
title: details
'404':
description: The requested resource does not exist.
schema:
type: object
properties:
code:
type: integer
format: integer
description: Error code returned with this error.
title: code
message:
type: string
description: Error message returned with this error.
title: message
details:
type: array
items:
type: string
description: Error details returned with this error.
title: details
'429':
description: You have exceed the rate limit.
schema:
type: object
properties:
code:
type: integer
format: integer
description: Error code returned with this error.
title: code
message:
type: string
description: Error message returned with this error.
title: message
details:
type: array
items:
type: string
description: Error details returned with this error.
title: details
'500':
description: Server error.
schema:
type: object
properties:
code:
type: integer
format: integer
description: Error code returned with this error.
title: code
message:
type: string
description: Error message returned with this error.
title: message
details:
type: array
items:
type: string
description: Error details returned with this error.
title: details
default:
description: An unexpected error response.
schema:
type: object
properties:
code:
type: integer
format: int32
message:
type: string
details:
type: array
items:
type: object
properties:
'@type':
type: string
additionalProperties: {}
parameters:
- name: project_id
description: The ID of your project. You can get the project ID from the response of [List all accessible projects](#tag/Project/operation/ListProjects).
in: path
required: true
type: string
format: uint64
- name: cluster_id
description: The ID of your cluster. You can get the cluster ID from the response of [List all clusters in a project](#tag/Cluster/operation/ListClustersOfProject).
in: path
required: true
type: string
format: uint64
- name: page
description: The number of pages.
in: query
required: false
type: integer
format: int64
default: 1
- name: page_size
description: The size of a page.
in: query
required: false
type: integer
format: int64
default: 10
tags:
- Import
x-code-samples:
- lang: curl
source: "curl --digest \\\n --user 'YOUR_PUBLIC_KEY:YOUR_PRIVATE_KEY' \\\n --request GET \\\n --url 'https://api.tidbcloud.com/api/v1beta/projects/{project_id}/clusters/{cluster_id}/imports?page=1&page_size=10'"
post:
summary: Create an import task.
operationId: CreateImportTask
responses:
'200':
description: A successful r
# --- truncated at 32 KB (147 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/pingcap/refs/heads/main/openapi/pingcap-import-api-openapi.yml