Change description

POST /api/meta/entity/bulk#changeDescription

Change an asset's description.

There are two fields in Atlan that capture the description of an asset: description and userDescription.

In the UI, userDescription will take precedence. This is the field that is updated when a user updates the description through the UI.

When a system updates a description, it will populate the description field. This field is only shown in the UI when the userDescription field is empty.

So, if you want to only override the fallback system-defined description, update the description field. If you want to override the users' own descriptions, then update the userDescription field.

To remove either (or both) descriptions, set them to null.

Note that the update relies on a match being found for the provided qualifiedNames. If the qualifiedNames do not match any existing asset, those assets will instead be created with the provided properties and values, rather than updating an existing asset by changing its properties. Also be aware that the qualifiedName is case-sensitive.

For more details on the semantics and other attributes available through this interface, see the Upsert entities operation.

Body Required

List of assets and the descriptions to set on them.

  • entities array[object] Required

    Instance of an asset in Atlan, with its detailed information.

    • typeName string Required

      Name of the type definition that defines this instance.

    • attributes object | null Required

      Attributes that can exist across all assets in Atlan.

      • qualifiedName string Required

        Unique name for this asset. This is typically a concatenation of the asset's name onto its parent's qualifiedName.

      • name string Required

        Human-readable name of the asset.

      • displayName string | null

        Name used for display purposes (in user interfaces).

      • description string | null

        Description of the asset, as crawled from a source.

      • userDescription string | null

        Description of the asset, as provided by a user. If present, this will be used for the description in user interfaces. If not present, the description will be used.

      • tenantId string

        Name of the Atlan workspace in which the table exists.

      • certificateStatus string | null

        Status of the asset's certification.

        Values are VERIFIED, DRAFT, or DEPRECATED.

      • certificateStatusMessage string | null

        Human-readable descriptive message that can optionally be submitted when the certificateStatus is changed.

      • announcementTitle string | null

        Brief title for the announcement on this asset. Required when announcementType is specified.

      • announcementMessage string | null

        Detailed message to include in the announcement on this asset.

      • announcementType string | null

        Type of announcement on the asset.

        Values are information, warning, or issue.

      • ownerUsers array[string] | null

        List of users who own the asset.

      • ownerGroups array[string] | null

        List of groups who own the asset.

      • adminUsers array[string] | null

        List of users who administer the asset. (This is only used for Connection assets?)

      • adminGroups array[string] | null

        List of groups who administer the asset. (This is only used for Connection assets?)

      • viewerUsers array[string] | null
      • viewerGroups array[string] | null
      • connectorName string | null

        Name of the connector through which this asset is accessible.

      • connectionName string | null Deprecated

        Unused.

      • connectionQualifiedName string | null

        Unique name of the connection through which this asset is accessible.

      • isDiscoverable boolean
      • isEditable boolean
      • subType object | null
      • viewScore number | null
      • popularityScore number | null
      • sourceOwners array[string] | null
      • sourceURL string | null
      • lastSyncWorkflowName string | null

        Name of the crawler that last synchronized this asset.

      • lastSyncRunAt integer | null

        Time (epoch) at which the table was last crawled, in milliseconds.

      • lastSyncRun string | null

        Name of the last run of the crawler that last synchronized this asset.

    • classifications array[object] | null

      Instance of a classification in Atlan.

      • typeName string

        Name of the classification. Note that this is the static-hashed unique name of the classification, not the human-readable displayName.

      • entityGuid string

        Unique identifier of the entity to which this classification is attached.

      • propagate boolean | null

        Whether to propagate this classification to other entities related to the entity to which the classification is attached.

      • removePropagationsOnEntityDelete boolean | null

        Whether to remove this classification from other entities to which it has been propagated when the classification is removed from this entity.

    • displayText string | null

      Human-readable name of the entity.

    • guid string

      Unique identifier of the entity instance.

    • isIncomplete boolean | null

      Default value is false.

    • businessAttributes object | null

      Map of custom metadata attributes and values defined on the entity.

    • relationshipAttributes object | null

      Map of the relationships to this asset.

      • links array[object]

        Details to use within an asset when referring to a link (resource).

        • typeName string

          Should always be Link.

        • guid string | null

          Unique identifier of the related link. If the uniqueAttributes are not provided, this must be provided.

        • uniqueAttributes object | null

          Attribute(s) that uniquely identify the related link. If the guid is not provided, these must be provided.

          • qualifiedName string

            Unique name of the related link. Note that this is a generated unique name which is not visible in the UI.

      • readme object

        Details to use within an asset when referring to a readme.

        • typeName string

          Should always be Readme.

        • guid string | null

          Unique identifier of the related readme. If the uniqueAttributes are not provided, this must be provided.

        • uniqueAttributes object | null

          Attribute(s) that uniquely identify the related readme. If the guid is not provided, these must be provided.

      • meanings array[object]

        Details to use within an asset when referring to a term.

        • typeName string

          Should always be AtlasnGlossaryTerm.

        • guid string | null

          Unique identifier of the related term. If the uniqueAttributes are not provided, this must be provided.

        • uniqueAttributes object | null

          Attribute(s) that uniquely identify the related term. If the guid is not provided, these must be provided.

          • qualifiedName string

            Unique name of the related term. Note that in Atlan this unique name is a hashed value, not the name you see in the UI.

Responses

  • • 200 object

    Asset descriptions were successfully added or updated.

    • mutatedEntities object | null

      Assets that were changed.

      • CREATE array[object]

        Instance of an asset in Atlan, with its detailed information.

        • entity object

          Instance of an entity in Atlan, with its detailed information.

          • typeName string

            Name of the type definition that defines this instance.

          • attributes object | null

            Will be further documented in sub-types of EntityHeader.

          • classifications array[object] | null

            Instance of a classification in Atlan, with its detailed information.

            • typeName string

              Name of the classification. Note that this is the static-hashed unique name of the classification, not the human-readable displayName.

            • entityGuid string

              Unique identifier of the entity to which this classification is attached.

            • propagate boolean | null

              Whether to propagate this classification to other entities related to the entity to which the classification is attached.

            • removePropagationsOnEntityDelete boolean | null

              Whether to remove this classification from other entities to which it has been propagated when the classification is removed from this entity.

            • entityStatus string | null

              Status of the entity to which this classification is attached.

              Values are ACTIVE or DELETED.

          • displayText string | null

            Human-readable name of the entity.

          • guid string

            Unique identifier of the entity instance.

          • isIncomplete boolean | null

            Default value is false.

          • businessAttributes object | null

            Map of custom metadata attributes and values defined on the entity.

          • relationshipAttributes object

            Map of relationships for the entity. The specific keys of this map will vary by type, so are described in the sub-types of this schema.

          • createdBy string | null

            Username of the user who created the object.

          • updatedBy string | null

            Username of the user who last updated the object.

          • createTime integer | null

            Time (epoch) at which this object was created, in milliseconds.

          • updateTime integer | null

            Time (epoch) at which this object was last updated, in milliseconds.

          • version integer | null

            Version of this object.

          • classificationNames array[string] | null

            List of classifications for this entity. Note that these are the internal hashed names used in Atlan, not the displayText of the classification.

          • labels array[string] | null

            Internal use only.

          • status string

            Status of the entity, either ACTIVE or DELETED.

            Values are ACTIVE or DELETED.

          • customAttributes object | null

            Internal use only.

          • pendingTasks array[string] | null

            Internal use only.

        • referredEntities object

          Map of related entities keyed by the GUID of the related entity. The values will be the detailed entity object of the related entity.

        • typeName string

          Name of the type definition that defines this instance.

        • attributes object | null

          Attributes that can exist across all assets in Atlan.

        • classifications array[object] | null

          Instance of a classification in Atlan.

          • typeName string

            Name of the classification. Note that this is the static-hashed unique name of the classification, not the human-readable displayName.

          • entityGuid string

            Unique identifier of the entity to which this classification is attached.

          • propagate boolean | null

            Whether to propagate this classification to other entities related to the entity to which the classification is attached.

          • removePropagationsOnEntityDelete boolean | null

            Whether to remove this classification from other entities to which it has been propagated when the classification is removed from this entity.

        • displayText string | null

          Human-readable name of the entity.

        • guid string

          Unique identifier of the entity instance.

        • isIncomplete boolean | null

          Default value is false.

        • businessAttributes object | null

          Map of custom metadata attributes and values defined on the entity.

        • relationshipAttributes object | null

          Map of the relationships to this asset.

          • links array[object]

            Details to use within an asset when referring to a link (resource).

          • readme object

            Details to use within an asset when referring to a readme.

            • typeName string

              Should always be Readme.

            • guid string | null

              Unique identifier of the related readme. If the uniqueAttributes are not provided, this must be provided.

            • uniqueAttributes object | null

              Attribute(s) that uniquely identify the related readme. If the guid is not provided, these must be provided.

          • meanings array[object]

            Details to use within an asset when referring to a term.

            • typeName string

              Should always be AtlasnGlossaryTerm.

            • guid string | null

              Unique identifier of the related term. If the uniqueAttributes are not provided, this must be provided.

            • uniqueAttributes object | null

              Attribute(s) that uniquely identify the related term. If the guid is not provided, these must be provided.

              • qualifiedName string

                Unique name of the related term. Note that in Atlan this unique name is a hashed value, not the name you see in the UI.

      • UPDATE array[object]

        Instance of an asset in Atlan, with its detailed information.

        • entity object

          Instance of an entity in Atlan, with its detailed information.

          • typeName string

            Name of the type definition that defines this instance.

          • attributes object | null

            Will be further documented in sub-types of EntityHeader.

          • classifications array[object] | null

            Instance of a classification in Atlan, with its detailed information.

            • typeName string

              Name of the classification. Note that this is the static-hashed unique name of the classification, not the human-readable displayName.

            • entityGuid string

              Unique identifier of the entity to which this classification is attached.

            • propagate boolean | null

              Whether to propagate this classification to other entities related to the entity to which the classification is attached.

            • removePropagationsOnEntityDelete boolean | null

              Whether to remove this classification from other entities to which it has been propagated when the classification is removed from this entity.

            • entityStatus string | null

              Status of the entity to which this classification is attached.

              Values are ACTIVE or DELETED.

          • displayText string | null

            Human-readable name of the entity.

          • guid string

            Unique identifier of the entity instance.

          • isIncomplete boolean | null

            Default value is false.

          • businessAttributes object | null

            Map of custom metadata attributes and values defined on the entity.

          • relationshipAttributes object

            Map of relationships for the entity. The specific keys of this map will vary by type, so are described in the sub-types of this schema.

          • createdBy string | null

            Username of the user who created the object.

          • updatedBy string | null

            Username of the user who last updated the object.

          • createTime integer | null

            Time (epoch) at which this object was created, in milliseconds.

          • updateTime integer | null

            Time (epoch) at which this object was last updated, in milliseconds.

          • version integer | null

            Version of this object.

          • classificationNames array[string] | null

            List of classifications for this entity. Note that these are the internal hashed names used in Atlan, not the displayText of the classification.

          • labels array[string] | null

            Internal use only.

          • status string

            Status of the entity, either ACTIVE or DELETED.

            Values are ACTIVE or DELETED.

          • customAttributes object | null

            Internal use only.

          • pendingTasks array[string] | null

            Internal use only.

        • referredEntities object

          Map of related entities keyed by the GUID of the related entity. The values will be the detailed entity object of the related entity.

        • typeName string

          Name of the type definition that defines this instance.

        • attributes object | null

          Attributes that can exist across all assets in Atlan.

        • classifications array[object] | null

          Instance of a classification in Atlan.

          • typeName string

            Name of the classification. Note that this is the static-hashed unique name of the classification, not the human-readable displayName.

          • entityGuid string

            Unique identifier of the entity to which this classification is attached.

          • propagate boolean | null

            Whether to propagate this classification to other entities related to the entity to which the classification is attached.

          • removePropagationsOnEntityDelete boolean | null

            Whether to remove this classification from other entities to which it has been propagated when the classification is removed from this entity.

        • displayText string | null

          Human-readable name of the entity.

        • guid string

          Unique identifier of the entity instance.

        • isIncomplete boolean | null

          Default value is false.

        • businessAttributes object | null

          Map of custom metadata attributes and values defined on the entity.

        • relationshipAttributes object | null

          Map of the relationships to this asset.

          • links array[object]

            Details to use within an asset when referring to a link (resource).

          • readme object

            Details to use within an asset when referring to a readme.

            • typeName string

              Should always be Readme.

            • guid string | null

              Unique identifier of the related readme. If the uniqueAttributes are not provided, this must be provided.

            • uniqueAttributes object | null

              Attribute(s) that uniquely identify the related readme. If the guid is not provided, these must be provided.

          • meanings array[object]

            Details to use within an asset when referring to a term.

            • typeName string

              Should always be AtlasnGlossaryTerm.

            • guid string | null

              Unique identifier of the related term. If the uniqueAttributes are not provided, this must be provided.

            • uniqueAttributes object | null

              Attribute(s) that uniquely identify the related term. If the guid is not provided, these must be provided.

              • qualifiedName string

                Unique name of the related term. Note that in Atlan this unique name is a hashed value, not the name you see in the UI.

    • guidAssignments object

      Map of assigned unique identifiers for the changed assets.

  • • 404 object

    Entity does not exist, or is deleted.

    • errorCode string

      Unique code for the type of error that occurred.

    • errorMessage string

      Human-readable description of the error that occurred.

POST /api/meta/entity/bulk#changeDescription 
curl \
 -X POST https://tenant.atlan.com/api/meta/entity/bulk#changeDescription \
 -H "Authorization: Bearer $ACCESS_TOKEN" \
 -H "Content-Type: application/json" \
 -d '{"entities":[{"typeName":"Column","attributes":{"name":"id","qualifiedName":"default/mongodb/mongodb.atlan.com/test_db/default/customer/id","description":"Unique identifier of a customer"}},{"typeName":"Column","guid":"dc14ffca-bf43-4731-b641-51408c4d892c","attributes":{"name":"name","qualifiedName":"default/mongodb/mongodb.atlan.com/test_db/default/customer/name","description":"Name of the customer"}}]}'
Request example 
{
  "entities": [
    {
      "typeName": "Column",
      "attributes": {
        "name": "id",
        "qualifiedName": "default/mongodb/mongodb.atlan.com/test_db/default/customer/id",
        "description": "Unique identifier of a customer"
      }
    },
    {
      "typeName": "Column",
      "guid": "dc14ffca-bf43-4731-b641-51408c4d892c",
      "attributes": {
        "name": "name",
        "qualifiedName": "default/mongodb/mongodb.atlan.com/test_db/default/customer/name",
        "description": "Name of the customer"
      }
    }
  ]
}
Response example (200) 
{
  "mutatedEntities": {
    "UPDATE": [
      {
        "typeName": "Column",
        "attributes": {
          "qualifiedName": "default/mongodb/mongodb.atlan.com/test_db/default/customer/id",
          "name": "id",
          "description": "Unique identifier of a customer"
        },
        "guid": "f5740924-fe74-4462-96ff-5da0bc970cec",
        "status": "ACTIVE",
        "displayText": "id",
        "classificationNames": [],
        "meaningNames": [],
        "meanings": [],
        "isIncomplete": false,
        "labels": [],
        "createdBy": "service-account-apikey-bea1e1d1-e4e7-465e-8adf-7c61c227a59b",
        "updatedBy": "service-account-apikey-bea1e1d1-e4e7-465e-8adf-7c61c227a59b",
        "createTime": 1652796319437,
        "updateTime": 1652795647900
      },
      {
        "typeName": "Column",
        "attributes": {
          "qualifiedName": "default/mongodb/mongodb.atlan.com/test_db/default/customer/name",
          "name": "name",
          "description": "Name of the customer"
        },
        "guid": "dc14ffca-bf43-4731-b641-51408c4d892c",
        "status": "ACTIVE",
        "displayText": "name",
        "classificationNames": [],
        "classifications": [],
        "meaningNames": [],
        "meanings": [],
        "isIncomplete": false,
        "labels": [],
        "createdBy": "service-account-apikey-bea1e1d1-e4e7-465e-8adf-7c61c227a59b",
        "updatedBy": "service-account-apikey-bea1e1d1-e4e7-465e-8adf-7c61c227a59b",
        "createTime": 1652795647900,
        "updateTime": 1652795647900
      }
    ]
  },
  "guidAssignments": {
    "-10887525374266605": "f5740924-fe74-4462-96ff-5da0bc970cec",
    "-10887525374266606": "dc14ffca-bf43-4731-b641-51408c4d892c"
  }
}
Response example (404) 
{
  "errorCode": "ATLAS-404-00-005",
  "errorMessage": "Given instance guid abc123 is invalid/not found\n"
}