Entity - Bulk Create Or Update

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>, array<map<string, int>>. For each contact type, the maximum number of contacts is 20.

POST {endpoint}/datamap/api/atlas/v2/entity/bulk
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

api-version
query

string

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

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

{
  "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

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

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

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

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

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

The update time of the record.

updatedBy

string

The user who updated the record.

version

integer

The version of the entity.

AtlasEntityHeader

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

An error response from the service

Name Type Description
errorCode

string

The error code.

errorMessage

string

The error message.

requestId

string

The request ID.

AtlasTermAssignmentHeader

The header for term assignment.

Name Type Description
confidence

integer

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

The GUID of the relationship.

status

AtlasTermAssignmentStatus

The status of terms assignment.

steward

string

The steward of the term.

termGuid

string

The GUID of the term.

AtlasTermAssignmentStatus

Status for term assignment

Name Type Description
DEPRECATED

string

The status is deprecated.

DISCOVERED

string

The status is discovered.

IMPORTED

string

The status is imported.

OBSOLETE

string

The status is obsolete.

OTHER

string

Other status.

PROPOSED

string

The status is proposed.

VALIDATED

string

The status is validated.

BusinessAttributeUpdateBehavior

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

Name Type Description
ignore

string

Ignore the business attribute payload for update.

merge

string

Merge the business attributes. Business attributes will not be updated if not provided.

replace

string

Replace all the business attributes using the payload.

EntityMutationResult

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

Status - can be active or deleted

Name Type Description
ACTIVE

string

The status is active.

DELETED

string

The status is deleted.

TimeBoundary

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.