BatchCreateMetaEntities-阿里云帮助中心

Operation description

You must purchase DataWorks Professional Edition or a higher edition to use this operation.

Try it now

Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

Test

RAM authorization

No authorization for this operation. If you encounter issues with this operation, contact technical support.

Request syntax

POST  HTTP/1.1

Request parameters

Parameter	Type	Required	Description	Example
Entities	array<object>	Yes	An entity list. You can create up to five entities in a batch. All entities in the batch must have the same `EntityType`.	[]
	array<object>	No	An object that represents a metadata entity.
EntityType	string	Yes	The entity type. All entities in a batch must have the same type. The following types are supported: Custom types, such as `custom_entity-biz_api`. Extended table types. For example, if you have registered the `custom_dw-table` metadata entity type, you can create objects of the corresponding `custom_dw-database` (database) and `custom_dw-table` (table) types.	custom_entity-customer_api
Name	string	Yes	The entity name. The name can contain uppercase letters, lowercase letters, digits, and underscores (_). It must start with a letter and not exceed 64 characters.	api_001
Comment	string	No	The comment for the entity.	this is a comment
Attributes	object	No	The entity attributes. Complex values must be serialized into a JSON string.
	string	No	An entity attribute.	key1
CustomAttributes	object	No	The custom attribute values. The key is the identifier of the custom attribute, and the value is a single-element list. Important The custom attributes used here must be created in advance by using the CreateCustomAttribute API. For example, after you create a custom attribute with the ID `custom-attribute:owner_name`, you can configure the custom attribute by setting this parameter to {'owner_name': ['Bob']}.
	array	No	A list of custom attribute values.
	string	No	A custom attribute value.	value1

Extended database

Set the EntityType to custom_xxx-database. The xxx placeholder is derived from an existing extended entity definition (EntityDef) for a table, such as custom_xxx-table.

Attributes

Attribute key	Required	Type	Description
`parentMetaEntityId`	Yes	String	The parent instance ID. It must be at the instance level and cannot contain catalog, database, schema, table, or column identifiers.
`technicalMetadata.location`	No	String	The storage location of the database.

Extended table

Set the EntityType to custom_xxx-table. You must also register the table columns by using the Attributes.columns parameter.

Attributes

Attribute key	Required	Type	Description
`parentMetaEntityId`	Yes	String	The parent database ID. It must be at the database level.
`tableType`	No	String	The table type. If you do not set this parameter, the default value TABLE is used.
`partitionKeys`	No	JSON array string	The partition keys. Example: `["dt"]`.
`technicalMetadata.location`	No	String	The storage location.
`technicalMetadata.compressed`	No	Boolean string or JSON boolean	Specifies whether the data is compressed.
`technicalMetadata.inputFormat`	No	String	The input format.
`technicalMetadata.outputFormat`	No	String	The output format.
`technicalMetadata.serializationLibrary`	No	String	The serialization/deserialization (SerDe) library.
`technicalMetadata.parameters`	No	JSON object string	Parameter information. Example: `{"retention":"30"}`.
`columns`	No	JSON array string	A list of embedded columns. Use this parameter to register extended columns when the table is created.

Attributes.columns

The columns parameter is a JSON array string within Attributes. Each object in the array supports the following fields:

Parameter	Required	Type	Description
`name`	Yes	String	The column name. If this property is empty, the column is skipped.
`type`	Yes	String	The column type. If this property is missing, the system reports an error for `attributes.columns[i].type`.
`comment`	No	String	The column comment.
`position`	No	Integer	The position of the column. If not specified, it defaults to the array index `i + 1`.
`partitionKey`	No	Boolean	Specifies whether the column is a partition key.
`primaryKey`	No	Boolean	Specifies whether the column is a primary key.
`customAttributes`	No	Object	The custom attribute values for the column.

Examples

Create an extended database

{
  "Entities": [
    {
      "EntityType": "custom_demo-database",
      "Name": "ods",
      "Comment": "ODS database",
      "Attributes": {
        "parentMetaEntityId": "custom_demo:demo_source",
        "technicalMetadata.location": "oss://bucket/ods"
      },
      "CustomAttributes": {
        "biz_owner": ["data_team"]
      }
    }
  ]
}

Create an extended table and columns

{
  "Entities": [
    {
      "EntityType": "custom_demo-table",
      "Name": "order_fact",
      "Comment": "Order fact table",
      "Attributes": {
        "parentMetaEntityId": "custom_demo-database:demo_source::ods",
        "tableType": "TABLE",
        "partitionKeys": "[\"dt\"]",
        "technicalMetadata.location": "oss://bucket/ods/order_fact",
        "technicalMetadata.compressed": "true",
        "technicalMetadata.parameters": "{\"retention\":\"30\",\"bizDomain\":\"trade\"}",
        "columns": "[{\"name\":\"id\",\"type\":\"BIGINT\",\"comment\":\"Primary key\",\"position\":1,\"primaryKey\":true,\"customAttributes\":{\"security_level\":[\"P1\"]}},{\"name\":\"dt\",\"type\":\"STRING\",\"comment\":\"Partition date\",\"position\":2,\"partitionKey\":true}]"
      },
      "CustomAttributes": {
        "biz_owner": ["data_team"]
      }
    }
  ]
}

Usage notes

The parentMetaEntityId for an extended database must be at the instance level, such as custom_demo:demo_source.
The parentMetaEntityId for an extended table must be at the database level, such as custom_demo-database:demo_source::ods.
Parent and child entities must belong to the same extension family. For example, the parent of a custom_demo-table entity must be a custom_demo-database entity.
The columns parameter can be provided only when you create a table. You cannot use the BatchCreateMetaEntities operation to create custom_xxx-column entities separately.
For extended entities, the write path does not strictly block unknown keys in the Attributes parameter based on MetaEntityDef.AttributeDefs. Unknown keys are typically ignored.

Response elements

Element	Type	Description	Example
	object	The response body.
RequestId	string	The request ID.	9E0C8E7A-C6BE-5A73-9562-2A030A80E8C6
Success	boolean	Indicates whether the request was successful. This parameter returns `true` even if creating some entities fails. To determine the outcome for each entity, check the `Success` and `ErrorMessage` fields in the `Results` array.	true
Results	array	A list of results for the batch creation operation. This list provides the success status and any error messages for each individual entity in the request.
	MetaEntityWriteResult	The result of a single entity creation within the batch.

Examples

Success response

JSON format

{
  "RequestId": "9E0C8E7A-C6BE-5A73-9562-2A030A80E8C6",
  "Success": true,
  "Results": [
    {
      "Name": "entity_01",
      "EntityType": "custom_entity-demo",
      "Id": "custom_entity-demo:entity_01",
      "Success": true,
      "ErrorMessage": "The specified parameters are invalid."
    }
  ]
}

Error codes

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.