CreateDataset

Usage notes

• By default, an Alibaba Cloud account has the permission to create a dataset. To create a dataset by using a RAM user, you must grant the RAM user the oss:MetaQuery permission.

• Before you call this operation, you must call the OpenMetaQuery operation to enable metadata management and vector search for the bucket. Otherwise, the operation returns the MetaQueryNotExist or InvalidArgument error.

• If you attempt to create a dataset with a name that already exists, the operation returns a ResourceAlreadyExists error (HTTP 400).

• If RouteRule.AutoCreateDataset=True is configured when you call the OpenMetaQuery operation, OSS automatically creates a dataset based on the tag value when an object that matches the routing tag is written. In this case, you do not need to call this operation in advance. A typical use case for this operation is to pre-create a dataset with a specific DatasetConfig.

• The WorkflowParameters parameter is a legacy setting for basic workflows and is retained for backward compatibility. This parameter will not be updated with new AI content analysis capabilities. We recommend using datasetConfig for new integrations.

• If you do not specify the datasetConfig parameter when you create a dataset, the system does not copy the DatasetConfig settings from the OpenMetaQuery operation to the dataset's persistent configuration. To ensure that a dataset has its own queryable and maintainable configuration, you must explicitly pass the datasetConfig parameter when you create or update the dataset.

• The request body is empty. Pass the description, workflowParameters, and datasetConfig parameters in the URL query string.

Request syntax

POST /?metaQuery&action=createDataset&datasetName=DatasetName HTTP/1.1
Host: BucketName.oss-cn-hangzhou.aliyuncs.com
Date: GMT Date
Authorization: SignatureValue

Request headers

This operation uses only common request headers. For more information, see Common request headers.

Request elements

Response headers

This operation returns only common response headers. For more information, see Common response headers.

Response elements

Examples

Request examples

Minimal request:

POST /?metaQuery&action=createDataset&datasetName=photos-2026 HTTP/1.1
Host: examplebucket.oss-cn-hangzhou.aliyuncs.com
Date: Wed, 20 May 2026 08:00:00 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20260520/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e

Create a content analysis dataset with datasetConfig:

POST /?metaQuery&action=createDataset&datasetName=videos-en&datasetConfig=%7B%22Insights%22%3A%7B%22Language%22%3A%22en%22%2C%22Video%22%3A%7B%22Caption%22%3A%7B%22Enable%22%3Atrue%7D%7D%7D%7D HTTP/1.1
Host: examplebucket.oss-cn-hangzhou.aliyuncs.com
Date: Wed, 20 May 2026 08:00:00 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20260520/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e

Creating a dataset with the legacy workflowParameters parameter. Note: This parameter is for backward compatibility and will not be updated with new features:

POST /?metaQuery&action=createDataset&datasetName=videos-basic&workflowParameters=%5B%7B%22Name%22%3A%22VideoInsightEnable%22%2C%22Value%22%3A%22True%22%7D%2C%7B%22Name%22%3A%22ImageInsightEnable%22%2C%22Value%22%3A%22True%22%7D%5D HTTP/1.1
Host: examplebucket.oss-cn-hangzhou.aliyuncs.com
Date: Wed, 20 May 2026 08:00:00 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20260520/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e

The URL-decoded value of the workflowParameters parameter:

[
  {"Name": "VideoInsightEnable", "Value": "True"},
  {"Name": "ImageInsightEnable", "Value": "True"}
]

Response example

HTTP/1.1 200 OK
x-oss-request-id: 64C8B6F4E7C5A3A8B9D6E7F1
Date: Wed, 20 May 2026 08:00:01 GMT
Content-Type: application/xml
Server: AliyunOSS

<?xml version="1.0" encoding="UTF-8"?>
<CreateDatasetResponse>
  <Dataset>
    <DatasetName>photos-2026</DatasetName>
    <Description>Photo gallery for 2026</Description>
    <CreateTime>2026-05-20T08:00:00.000+08:00</CreateTime>
    <UpdateTime>2026-05-20T08:00:00.000+08:00</UpdateTime>
    <DatasetMaxFileCount>100000000</DatasetMaxFileCount>
    <DatasetMaxEntityCount>10000000000</DatasetMaxEntityCount>
    <DatasetMaxRelationCount>100000000000</DatasetMaxRelationCount>
    <DatasetMaxTotalFileSize>90000000000000000</DatasetMaxTotalFileSize>
    <DatasetConfig>
      <Insights>
        <Language>en</Language>
        <Video>
          <Caption>
            <Enable>True</Enable>
          </Caption>
        </Video>
      </Insights>
    </DatasetConfig>
  </Dataset>
</CreateDatasetResponse>