Supported Regions:上海

Add data

Perform insert operations on MySQL databases via HTTP RESTful API. For details about specific interfaces, refer to HTTP API/MySQL Database.

Basic Syntax

POST https://your-envId.api.tcloudbasegateway.com/v1/rdb/rest/:table
Authorization: Bearer <access_token>
Content-Type: application/json

💡 Tip: For access_token, refer to Obtain AccessToken

Basic Insertion

# Insert a single record into the film table
curl -X POST 'https://{{host}}/v1/rdb/rest/film' \
-H 'Authorization: Bearer <access_token>' \
-H 'Content-Type: application/json' \
-d '{
  "title": "Inception",
  "release_year": 2010,
  "director": "Christopher Nolan",
  "duration": 148
}'

💡 Note: By default, insert operations do not return data, only status codes and the number of affected rows.

Response

content-range: */1 indicates the number of affected rows, meaning one data record has been inserted.
preference-applied: return=minimal indicates that the return=minimal policy was adopted for the write operation (default behavior for write operations, which does not generate a response body).

Response Example

HTTP/1.1 201 Created
Header:
    content-length: 0
    content-range: */1
    preference-applied: return=minimal
Body: (Empty)

Insertion with Data Return

# Inserting Data with Full Record Return
curl -X POST 'https://{{host}}/v1/rdb/rest/film?select=*' \
-H 'Authorization: Bearer <access_token>' \
-H 'Content-Type: application/json' \
-H 'Prefer: return=representation' \
-d '{
    "title": "The Shawshank Redemption",
    "release_year": 1994,
    "director": "Frank Darabont",
    "duration": 142
}'

Request

Specify the Header Prefer: return=representation in the request to indicate that the inserted data will be returned after insertion without an additional query, and all field data will be returned automatically.

Response

If the table contains auto-increment fields, the return values will contain the values of these auto-increment fields.

Response Example

HTTP/1.1 201 Created
Header:
    content-length: 266
    content-range: */1
    preference-applied: return=representation
Body:
[
    {
        "_openid": "1977683311217119233",
        "director": "Frank Darabont",
        "duration": 142,
        "id": 2,
        "release_year": 1994,
        "title": "The Shawshank Redemption"
    }
]

Specify Returned Fields

# Inserting Data with Specified Fields Returned
curl -X POST 'https://{{host}}/v1/rdb/rest/film?select=title,director' \
-H 'Authorization: Bearer <access_token>' \
-H 'Content-Type: application/json' \
-H 'Prefer: return=representation' \
-d '{
    "title": "The Godfather",
    "release_year": 1972,
    "director": "Francis Ford Coppola",
    "duration": 175
}'

Request

Specify the Header Prefer: return=representation in the request to indicate that the inserted data will be returned after insertion without an additional query, and all field data will be returned automatically.
When /table?select=* is specified, all inserted field data is returned by default; when /table?select=id,title,director is specified, only the inserted data for the specified fields is returned.

Response Example

HTTP/1.1 201 Created
Header:
    content-length: 78
    content-range: */1
    preference-applied: return=representation
Body:
[
    {
        "id": 1,
        "director": "Francis Ford Coppola",
        "title": "The Godfather"
    }
]

Batch Insertion

# Batch Insert Multiple Data
curl -X POST 'https://{{host}}/v1/rdb/rest/film?select=id,title,director,duration' \
-H 'Authorization: Bearer <access_token>' \
-H 'Content-Type: application/json' \
-H 'Prefer: return=representation' \
-d '[
    {
        "title": "The Godfather: Part II",
        "release_year": 1974,
        "director": "Francis Ford Coppola",
        "duration": 202
    },
    {
        "title": "The Godfather: Part III",
        "release_year": 1990,
        "director": "Francis Ford Coppola",
        "duration": 194
    }
]'

Response

content-range: */2 indicates that two data records were created in this request.
When creating data in batches, the entire operation is within a single transaction; if any failure occurs, the entire operation will be rolled back.

Response Example

HTTP/1.1 201 Created
Header:
    content-length: 312
    content-range: */2
    preference-applied: return=representation
Body:
[
    {
        "director": "Francis Ford Coppola",
        "duration": 202,
        "id": 4,
        "title": "The Godfather: Part II"
    },
    {
        "director": "Francis Ford Coppola",
        "duration": 194,
        "id": 5,
        "title": "The Godfather: Part III"
    }
]

Note

Note: During batch creation, auto-incrementing fields may be inaccurately backfilled. Do not rely on auto-incrementing fields returned during batch creation!

Reason: Due to the characteristics of the MySQL database, when creating data, MySQL can only know the number of affected rows and the final auto-increment value inserted, thus inferring the auto-increment values for this batch of data. However, the allocation of auto-increment values is not continuous; it may encounter situations such as "manual specification", "INSERT IGNORE", "INSERT ON DUPLICATE KEY UPDATE", resulting in non-continuous allocation of auto-increment values.

Perform an update when an insert conflict occurs

# Insert or Update Data
curl -X POST 'https://{{host}}/v1/rdb/rest/film?select=*' \
-H 'Authorization: Bearer <access_token>' \
-H 'Content-Type: application/json' \
-H 'Prefer: return=representation, resolution=merge-duplicates' \
-d '{
    "title": "The Godfather",
    "release_year": 1972,
    "director": "Francis Ford Coppola",
    "duration": 175
}'

Request

return=representation indicates that after performing a write operation, the written data is returned. Used in conjunction with select, it returns all field data by default.
resolution=merge-duplicates indicates that when a creation conflict occurs, an update operation will be performed. Conflict criteria: when a creation conflict occurs on a primary key or unique index, an update operation will be performed.
content-range: */2 indicates the number of affected rows. In this case, it means that during this request, when creating one data record, a conflict occurred, resulting in an update operation, thus the number of affected rows is 2.

Note

Due to MySQL database limitations, resolution=merge-duplicates carries a risk of deadlock in high concurrency scenarios. Use with caution.
When using resolution=merge-duplicates, ensure the request body includes primary key or unique index fields.
When using resolution=merge-duplicates, MySQL treats this case as attempting insertion first, then performing an update:
- Insertion attempt: is counted as one affected row (even if no actual insertion occurred).
- Update operation: is counted as one affected row.
- Total content-range returns 2

Response Example

HTTP/1.1 201 Created

Header:
    content-length: 116
    content-range: */2
    content-type: application/json; charset=utf-8
    preference-applied: return=representation, resolution=merge-duplicates

Body:
[
    {
        "_openid": "1977683311217119233",
        "director": "Nolan",
        "duration": 150,
        "id": 1,
        "release_year": 2010,
        "title": "Inception"
    }
]

Perform an ignore when an insert conflict occurs

# Insert or Update Data
curl -X POST 'https://{{host}}/v1/rdb/rest/film?select=*' \
-H 'Authorization: Bearer <access_token>' \
-H 'Content-Type: application/json' \
-H 'Prefer: return=representation, resolution=ignore-duplicates' \
-d '{
    "title": "The Godfather",
    "release_year": 1972,
    "director": "Francis Ford Coppola",
    "duration": 175
}'

Request

return=representation indicates that after performing a write operation, the written data is returned. Used in conjunction with select, it returns all field data by default.
resolution=ignore-duplicates indicates that when a creation conflict occurs, it will be ignored. Conflict basis: creation conflicts exist when primary keys or unique indexes are duplicated.
content-range: */0 When a creation conflict occurs, it is ignored, and the number of affected rows is 0, content-range: */0.

Note

When using resolution=ignore-duplicates, MySQL treats this situation as a silent ignore (no insertion or update), so the number of affected rows is 0. Even if the conflict is ignored, an auto-increment value is still consumed.

Response

HTTP/1.1 201 Created

Header:
    content-length: 125
    content-range: */0
    content-type: application/json; charset=utf-8
    preference-applied: return=representation, resolution=ignore-duplicates

Body: 
[
    {
        "_openid": "1977683311217119233",
        "director": "Sidney Lumet",
        "duration": 96,
        "id": 2,
        "release_year": 1957,
        "title": "12 Angry Men"
    }
]

Add data

Basic Syntax​

Basic Insertion​

Insertion with Data Return​

Specify Returned Fields​

Batch Insertion​

Perform an update when an insert conflict occurs​

Perform an ignore when an insert conflict occurs​

Basic Syntax

Basic Insertion

Insertion with Data Return

Specify Returned Fields

Batch Insertion

Perform an update when an insert conflict occurs

Perform an ignore when an insert conflict occurs