Entity - Bulk Create Or Update

Service:: Purview

API Version:: 2023-09-01

Create or update entities in bulk. Existing entity is matched using its unique guid if supplied or by its unique attributes eg: qualifiedName. Map and array of collections are not well supported. E.g., array<array<int>>, array<map<string, int>>. For each contact type, the maximum number of contacts is 20.

POST {endpoint}/datamap/api/atlas/v2/entity/bulk

With optional parameters:

POST {endpoint}/datamap/api/atlas/v2/entity/bulk?api-version=2023-09-01&collectionId={collectionId}&businessAttributeUpdateBehavior={businessAttributeUpdateBehavior}

URI Parameters

Name	In	Required	Type	Description
endpoint	path	True	string (uri)
api-version	query		string minLength: 1	The API version to use for this operation.
businessAttributeUpdateBehavior	query		BusinessAttributeUpdateBehavior	Used to define the update behavior for business attributes when updating entities.
collectionId	query		string	The collection where entities will be moved to. Only specify a value if you need to move an entity to another collection.

Request Body

Name	Type	Description
entities	AtlasEntity[]	An array of entities.
referredEntities	<string, AtlasEntity>	The referred entities.

Responses

Name	Type	Description
200 OK	EntityMutationResult	The request has succeeded.
Other Status Codes	AtlasErrorResponse	An unexpected error response.

Security

OAuth2Auth

Type: oauth2
Flow: implicit
Authorization URL: https://login.microsoftonline.com/common/oauth2/authorize

Scopes

Name	Description
https://purview.azure.net/.default

Examples

Entity_BulkCreateOrUpdate

Sample request

HTTP

POST {endpoint}/datamap/api/atlas/v2/entity/bulk?api-version=2023-09-01

{
  "referredEntities": {},
  "entities": [
    {
      "typeName": "azure_storage_account",
      "attributes": {
        "owner": "ExampleOwner",
        "modifiedTime": 0,
        "createTime": 0,
        "qualifiedName": "exampleaccount1",
        "name": "ExampleStorageAccount1",
        "description": null,
        "publicAccessLevel": null
      },
      "contacts": {
        "Expert": [
          {
            "id": "30435ff9-9b96-44af-a5a9-e05c8b1ae2df",
            "info": "Example Expert Info"
          }
        ],
        "Owner": [
          {
            "id": "30435ff9-9b96-44af-a5a9-e05c8b1ae2df",
            "info": "Example Owner Info"
          }
        ]
      },
      "status": "ACTIVE",
      "createdBy": "ExampleCreator",
      "updatedBy": "ExampleUpdator",
      "version": 0
    },
    {
      "typeName": "azure_storage_account",
      "attributes": {
        "owner": "ExampleOwner",
        "modifiedTime": 0,
        "createTime": 0,
        "qualifiedName": "exampleaccount2",
        "name": "ExampleStorageAccount2",
        "description": "Example Description",
        "publicAccessLevel": null
      },
      "contacts": {
        "Expert": [
          {
            "id": "30435ff9-9b96-44af-a5a9-e05c8b1ae2df",
            "info": "Example Expert Info"
          }
        ],
        "Owner": [
          {
            "id": "30435ff9-9b96-44af-a5a9-e05c8b1ae2df",
            "info": "Example Owner Info"
          }
        ]
      },
      "status": "ACTIVE",
      "createdBy": "ExampleCreator",
      "updatedBy": "ExampleUpdator",
      "version": 0
    }
  ]
}

Sample response

Status code:: 200

{
  "mutatedEntities": {
    "UPDATE": [
      {
        "typeName": "azure_storage_account",
        "attributes": {
          "qualifiedName": "exampleaccount2"
        },
        "lastModifiedTS": "2",
        "guid": "b2f9c306-cf65-4bb0-878e-cfaafde156b1",
        "status": "ACTIVE"
      }
    ],
    "CREATE": [
      {
        "typeName": "azure_storage_account",
        "attributes": {
          "qualifiedName": "exampleaccount1"
        },
        "lastModifiedTS": "1",
        "guid": "321493e3-3fb7-4b3e-9df7-3b69154174c2",
        "status": "ACTIVE"
      }
    ]
  },
  "guidAssignments": {
    "-9514774903018192": "321493e3-3fb7-4b3e-9df7-3b69154174c2",
    "-9514774903018193": "b2f9c306-cf65-4bb0-878e-cfaafde156b1"
  }
}

Definitions

Name	Description
AtlasClassification	An instance of a classification; it doesn't have an identity, this object exists only when associated with an entity.
AtlasEntitiesWithExtInfo	An instance of an entity along with extended info - like hive_table, hive_database.
AtlasEntity	An instance of an entity - like hive_table, hive_database.
AtlasEntityHeader	An instance of an entity - like hive_table, hive_database.
AtlasErrorResponse	An error response from the service
AtlasTermAssignmentHeader	The header for term assignment.
AtlasTermAssignmentStatus	Status for term assignment
BusinessAttributeUpdateBehavior	Used to define the update behavior for business attributes when updating entities.
EntityMutationResult	The mutation response result of entity.
EntityStatus	Status - can be active or deleted
TimeBoundary	Captures time-boundary details

AtlasClassification

Object

An instance of a classification; it doesn't have an identity, this object exists only when associated with an entity.

Name	Type	Description
attributes		The attributes of the struct.
entityGuid	string	The GUID of the entity.
entityStatus	EntityStatus	Status of the entity - can be active or deleted. Deleted entities are not removed.
lastModifiedTS	string	ETag for concurrency control.
removePropagationsOnEntityDelete	boolean	Determines if propagations will be removed on entity deletion.
typeName	string	The name of the type.
validityPeriods	TimeBoundary[]	An array of time boundaries indicating validity periods.

AtlasEntitiesWithExtInfo

Object

An instance of an entity along with extended info - like hive_table, hive_database.

Name	Type	Description
entities	AtlasEntity[]	An array of entities.
referredEntities	<string, AtlasEntity>	The referred entities.

AtlasEntity

Object

An instance of an entity - like hive_table, hive_database.

Name	Type	Description
attributes		The attributes of the struct.
businessAttributes		Business attributes
classifications	AtlasClassification[]	An array of classifications.
collectionId	string	The collection ID of the entity.
contacts	object	The dictionary of contacts for entities. Key could be Expert or Owner.
createTime	integer (int64)	The created time of the record.
createdBy	string	The user who created the record.
customAttributes	object	Custom Attribute
guid	string	The GUID of the entity.
homeId	string	The home ID of the entity.
isIncomplete	boolean	Whether it is a shell entity
labels	string[]	labels
lastModifiedTS	string	ETag for concurrency control.
meanings	AtlasTermAssignmentHeader[]	An array of term assignment headers indicating the meanings of the entity.
provenanceType	integer (int32)	Used to record the provenance of an instance of an entity or relationship.
proxy	boolean	Determines if there's a proxy.
relationshipAttributes		The attributes of relationship.
status	EntityStatus	Status of the entity - can be active or deleted. Deleted entities are not removed.
typeName	string	The name of the type.
updateTime	integer (int64)	The update time of the record.
updatedBy	string	The user who updated the record.
version	integer (int64)	The version of the entity.

AtlasEntityHeader

Object

An instance of an entity - like hive_table, hive_database.

Name	Type	Description
attributes		The attributes of the struct.
classificationNames	string[]	An array of classification names.
classifications	AtlasClassification[]	An array of classifications.
displayText	string	The display text.
guid	string	The GUID of the record.
isIncomplete	boolean	Whether it is a shell entity
labels	string[]	labels
lastModifiedTS	string	ETag for concurrency control.
meaningNames	string[]	An array of meanings.
meanings	AtlasTermAssignmentHeader[]	An array of term assignment headers.
status	EntityStatus	Status of the entity - can be active or deleted. Deleted entities are not removed.
typeName	string	The name of the type.

AtlasErrorResponse

Object

An error response from the service

Name	Type	Description
errorCode	string	The error code.
errorMessage	string	The error message.
requestId	string (uuid)	The request ID.

AtlasTermAssignmentHeader

Object

The header for term assignment.

Name	Type	Description
confidence	integer (int32)	The confidence of the term assignment.
createdBy	string	The user who created the record.
description	string	The description of the term assignment.
displayText	string	The display text.
expression	string	The expression of the term assignment.
relationGuid	string (uuid)	The GUID of the relationship.
status	AtlasTermAssignmentStatus	The status of terms assignment.
steward	string	The steward of the term.
termGuid	string (uuid)	The GUID of the term.

AtlasTermAssignmentStatus

Enumeration

Status for term assignment

Value	Description
DISCOVERED	The status is discovered.
PROPOSED	The status is proposed.
IMPORTED	The status is imported.
VALIDATED	The status is validated.
DEPRECATED	The status is deprecated.
OBSOLETE	The status is obsolete.
OTHER	Other status.

BusinessAttributeUpdateBehavior

Enumeration

Used to define the update behavior for business attributes when updating entities.

Value	Description
ignore	Ignore the business attribute payload for update.
replace	Replace all the business attributes using the payload.
merge	Merge the business attributes. Business attributes will not be updated if not provided.

EntityMutationResult

Object

The mutation response result of entity.

Name	Type	Description
guidAssignments	object	A map of GUID assignments with entities.
mutatedEntities	object	The entity headers of mutated entities.
partialUpdatedEntities	AtlasEntityHeader[]	An array of entity headers that partially updated.

EntityStatus

Enumeration

Status - can be active or deleted

Value	Description
ACTIVE	The status is active.
DELETED	The status is deleted.

TimeBoundary

Object

Captures time-boundary details

Name	Type	Description
endTime	string	The end of the time boundary.
startTime	string	The start of the time boundary.
timeZone	string	The timezone of the time boundary.

Share via

Entity - Bulk Create Or Update

URI Parameters

Request Body

Responses

Security

OAuth2Auth

Scopes

Examples

Entity_BulkCreateOrUpdate

Sample request

Sample response

Definitions

AtlasClassification

AtlasEntitiesWithExtInfo

AtlasEntity

AtlasEntityHeader

AtlasErrorResponse

AtlasTermAssignmentHeader

AtlasTermAssignmentStatus

BusinessAttributeUpdateBehavior

EntityMutationResult

EntityStatus

TimeBoundary