Change custom metadata on assets¶
Structures must exist before setting values on assets
Remember that you must first create the custom metadata structures before you will be able to set or change any values for custom metadata on an asset.
Value representation¶
To update custom metadata values on an asset, you need to use the correct representation:
Property type | Value representation | Example |
---|---|---|
Text | String | "a value" |
Integer | Number: without decimals | 42 |
Decimal | Number: with decimals | 42.0 |
Boolean | Boolean: either true or false |
true |
Date | Number: milliseconds since epoch (January 1, 1970), to a specific day | 1681171200000 |
Options | String: exact value from the options list | "success" |
Users | String: username of the user | "jsmith" |
Groups | String: unique name of the group, which appears under the name of the group in the UI list of groups | "finance" |
URL | String: starting with http[s]:// |
https://www.google.com |
SQL | String | "SELECT *\nFROM somewhere;" |
Multi-value attributes
Custom attributes in Atlan can be configured to allow multiple values. For these, you must wrap all values in a multi-valued collection, even if there is only a single value you are setting. Each value in that collection needs to follow the appropriate representation as indicated in the table above.
For example, if you want to set just a single group in a field that allows multiple values:
Multi-valued attribute | |
---|---|
1 2 3 4 5 6 7 8 |
|
- You must provide the value(s) as a list in YAML: each value on a new line, indented below the attribute, and prefixed with
-
.
Multi-valued attribute | |
---|---|
1 2 3 |
|
- You must provide the value(s) as a collection (List, Set, etc).
Multi-valued attribute | |
---|---|
1 2 3 4 |
|
-
Provide the name of the custom metadata set.
Name will be validated
The name will be validated at runtime to ensure that a custom metadata set with the given name exists.
-
For any property that can be multi-valued, we need to send a list of values.
Name will be validated
The metadata property name will be validated at runtime to ensure that a property with the given name exists in the custom metadata set.
Multi-valued attribute | |
---|---|
1 2 3 |
|
- You must provide the value(s) as a collection (List, Set, etc).
POST /api/meta/entity/guid/a89ff15b-f5e6-48bc-870b-acfa11e212ae/businessmetadata/MNJ8mpLsIOaP4OQnLNhRta | |
---|---|
1 2 3 4 5 6 7 |
|
- You must provide the value(s) in a JSON-style array.
Add to existing assets¶
Update only some custom metadata attributes¶
To update only some custom metadata attributes (leaving all others unchanged):
This is currently not possible via dbt, custom metadata is replaced rather than selectively updated.
Update only some custom metadata attributes | |
---|---|
1 2 3 4 5 6 7 8 9 |
|
- Create a custom metadata attributes object that will contain only the attributes and values for custom metadata that you want to update on the asset. All other custom metadata attributes (those not specified in this object) will remain unchanged on the asset.
-
For each attribute, use the
attribute()
method and pass:- the name of the attribute within that set
- the value for that attribute
The value can be any object valid for the attribute: a string, a boolean, or a number. (Note that dates are sent as
long
(epoch) numbers.) -
For any attribute that can be multi-valued, we can send a list of values.
- Use the
updateCustomMetadataAttributes()
method to update only theResponsible
andConsulted
attributes in theRACI
custom metadata on the existing asset. Any other custom metadata attributes inRACI
and all other custom metadata will be left unchanged. - Because this operation will directly change the asset in Atlan, you must provide it an
AtlanClient
through which to connect to the tenant. - Note that for this operation you must know the GUID of the asset you want to apply the custom metadata to. Also, the operation returns no result: if there is an error it will throw an exception, but the result of the operation must be determined by retrieving the asset through a separate API call, if you want to confirm it.
- Provide the name for the custom metadata you want to update.
- Provide the custom metadata attributes object with the attributes and values you want to update for that custom metadata.
Update only some custom metadata attributes | |
---|---|
1 2 3 4 5 6 7 8 9 |
|
- Use the
updater()
method to create an asset suitable for modifiaction i.e. with all the requisite attributes.
Update the custom metadata on the table | |
---|---|
10 11 12 |
|
-
Get the custom metadata set from the table via the
get_custom_metadata
method by specifying the name of the custom metadata set.Name will be validated
The name will be validated at runtime to ensure that a custom metadata set with the given name exists.
-
For each property of the metadata set you wish to update specify the name of the property.
Name will be validated
The metadata property name will be validated at runtime to ensure that a property with the given name exists in the custom metadata set.
-
For any attribute that can be multi-valued, we need to send a list of values.
Alternatively, create a custom metadata set and add it to the table | |
---|---|
10 11 12 13 |
|
-
Create an empty custom metadata set by specifying the name of an existing custom metadata set.
Name will be validated
The name will be validated at runtime to ensure that a custom metadata set with the given name exists.
-
For each property of the metadata set you wish to update specify the name of the property.
Name will be validated
The metadata property name will be validated at runtime to ensure that a property with the given name exists in the custom metadata set.
-
For any attribute that can be multi-valued, we need to send a list of values.
- Use the
set_custom_metadata
method to set the custom metadata set on the table.
Update the model object on the server | |
---|---|
14 15 16 17 |
|
- Use the
save_merging_cm()
method to update the model object on the server. - Assert that a
Table
asset has been updated.
Update only some custom metadata attributes | |
---|---|
1 2 3 4 5 6 7 8 9 |
|
- Create a custom metadata attributes object that will contain only the attributes and values for custom metadata that you want to update on the asset. All other custom metadata attributes (those not specified in this object) will remain unchanged on the asset.
-
For each attribute, use the
attribute()
method and pass:- the name of the attribute within that set
- the value for that attribute
The value can be any object valid for the attribute: a string, a boolean, or a number. (Note that dates are sent as
long
(epoch) numbers.) -
For any attribute that can be multi-valued, we can send a list of values.
- Use the
updateCustomMetadataAttributes()
method to update only theResponsible
andConsulted
attributes in theRACI
custom metadata on the existing asset. Any other custom metadata attributes inRACI
and all other custom metadata will be left unchanged. - Because this operation will directly change the asset in Atlan, you must provide it an
AtlanClient
through which to connect to the tenant. - Note that for this operation you must know the GUID of the asset you want to apply the custom metadata to. Also, the operation returns no result: if there is an error it will throw an exception, but the result of the operation must be determined by retrieving the asset through a separate API call, if you want to confirm it.
- Provide the name for the custom metadata you want to update.
- Provide the custom metadata attributes object with the attributes and values you want to update for that custom metadata.
POST /api/meta/entity/guid/a89ff15b-f5e6-48bc-870b-acfa11e212ae/businessmetadata?isOverwrite=false | |
---|---|
1 2 3 4 5 6 7 8 9 |
|
- You must pass the GUID of the asset to change for this operation. There is no alternative that works with the qualifiedName.
- Each custom metadata set you want to add or update must be given using its hashed-string representation.
- Each custom metadata attribute you want to update must be given using its hashed-string representation.
- For multivalued custom metadata attributes, specify the value as an array.
Replace some custom metadata on an asset¶
You can also add/replace an entire set of custom metadata to existing assets. If you do this individually, you can selectively update individual sets of custom metadata (leaving any others unchanged):
Replace some custom metadata on an asset | |
---|---|
1 2 3 4 5 6 7 8 |
|
- You must of course give the name of the object.
- The custom metadata must be nested within the
meta
.atlan
.businessAttributes
structure. - Each custom metadata set you want to add or update must be given using its hashed-string representation.
- Each custom metadata attribute you want to update must be given using its hashed-string representation.
- For multivalued custom metadata attributes, specify the value as an array.
Replace some custom metadata on an asset | |
---|---|
1 2 3 4 5 6 7 8 9 |
|
- Create a custom metadata attributes object that will contain the attributes and values for custom metadata you want to add to the asset.
-
For each attribute, use the
attribute()
method and pass:- the name of the attribute within that set
- the value for that attribute
The value can be any object valid for the attribute: a string, a boolean, or a number. (Note that dates are sent as
long
(epoch) numbers.) -
For any attribute that can be multi-valued, we can send a list of values.
- Use the
replaceCustomMetadata()
method to replace only this namedRACI
custom metadata on the existing asset. Any other custom metadata will be left unchanged. Note that any attributes inRACI
that are not included in the custom metadata attributes object we send will be removed from the custom metadata on that asset. (In our examples, this means any existing values in theAccountable
andInformed
attributes ofRACI
on this asset would be removed.) - Because this operation will directly change the asset in Atlan, you must provide it an
AtlanClient
through which to connect to the tenant. - Note that for this operation you must know the GUID of the asset you want to apply the custom metadata to. Also, the operation returns no result: if there is an error it will throw an exception, but the result of the operation must be determined by retrieving the asset through a separate API call, if you want to confirm it.
- Provide the name for the custom metadata you want to add/replace.
- Provide the custom metadata attributes object with the attributes and values you want to be the complete set for that custom metadata.
Replace some custom metadata on an asset | |
---|---|
1 2 3 4 5 6 7 8 9 10 11 |
|
-
Create an empty custom metadata set by specifying the name of an existing custom metadata set.
Name will be validated
The name will be validated at runtime to ensure that a custom metadata set with the given name exists.
-
For each property of the metadata set you wish to update specify the name of the property.
Name will be validated
The metadata property name will be validated at runtime to ensure that a property with the given name exists in the custom metadata set.
-
For any property that can be multi-valued, we need to send a list of values.
- Use the
asset.replace_custom_metadata()
method to replace only this namedRACI
custom metadata on the existing asset. Any other custom metadata will be left unchanged. Note that any properties inRACI
that are not included in the custom metadata object we send will be removed from the custom metadata on that asset. (In our examples, this means any existing values in theAccountable
andInformed
properties ofRACI
on this asset would be removed.) - Note that for this operation you must know the GUID of the asset you want to apply the custom metadata to. Also, the operation returns no result: if there is an error it will throw an exception, but the result of the operation must be determined by retrieving the asset through a separate API call, if you want to confirm it.
- Provide the custom metadata set object with the properties and values you want to be the complete set for that custom metadata.
Replace some custom metadata on an asset | |
---|---|
1 2 3 4 5 6 7 8 9 |
|
- Create a custom metadata attributes object that will contain the attributes and values for custom metadata you want to add to the asset.
-
For each attribute, use the
attribute()
method and pass:- the name of the attribute within that set
- the value for that attribute
The value can be any object valid for the attribute: a string, a boolean, or a number. (Note that dates are sent as
long
(epoch) numbers.) -
For any attribute that can be multi-valued, we can send a list of values.
- Use the
replaceCustomMetadata()
method to replace only this namedRACI
custom metadata on the existing asset. Any other custom metadata will be left unchanged. Note that any attributes inRACI
that are not included in the custom metadata attributes object we send will be removed from the custom metadata on that asset. (In our examples, this means any existing values in theAccountable
andInformed
attributes ofRACI
on this asset would be removed.) - Because this operation will directly change the asset in Atlan, you must provide it an
AtlanClient
through which to connect to the tenant. - Note that for this operation you must know the GUID of the asset you want to apply the custom metadata to. Also, the operation returns no result: if there is an error it will throw an exception, but the result of the operation must be determined by retrieving the asset through a separate API call, if you want to confirm it.
- Provide the name for the custom metadata you want to add/replace.
- Provide the custom metadata attributes object with the attributes and values you want to be the complete set for that custom metadata.
POST /api/meta/entity/guid/a89ff15b-f5e6-48bc-870b-acfa11e212ae/businessmetadata/MNJ8mpLsIOaP4OQnLNhRta | |
---|---|
1 2 3 4 5 6 7 8 9 |
|
- You must pass the GUID of the asset to change for this operation. There is no alternative that works with the qualifiedName. Note that you also need the hashed-string representation of the custom metadata set in the URL itself.
- Each custom metadata set you want to replace must be given using its hashed-string representation.
- Each custom metadata attribute you want to include in the replacement must be given using its hashed-string representation.
- For multivalued custom metadata attributes, specify the value as an array.
Replace all custom metadata on an asset¶
Could create a new asset
Remember that Atlan matches the provided qualifiedName
to determine whether to update or create the asset.
You can also replace all the custom metadata on one or many existing assets at the same time.
Replaces any existing custom metadata
This approach will replace all existing custom metadata (across all attributes) on the asset. If you have only a few custom metadata attributes defined in the update, this will remove any other custom metadata attributes that are already set on the asset within Atlan.
Replace all custom metadata on existing assets | |
---|---|
1 2 3 4 5 6 7 8 9 10 |
|
- You must of course give the name of the object.
- The custom metadata must be nested within the
meta
.atlan
.businessAttributes
structure. - Each custom metadata set you want to add or update must be given using its hashed-string representation.
- Each custom metadata attribute you want to update must be given using its hashed-string representation.
- For multivalued custom metadata attributes, specify the value as an array.
- Additional custom metadata sets would be listed as additional sub-objects of the
businessAttributes
object. (Still using a hashed-string representation.) - ...and custom metadata attributes within those sets would be listed as sub-objects of the custom metadata set object. (Still using a hashed-string representation.)
Replace all custom metadata on existing assets | |
---|---|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
|
- Create one or more custom metadata attributes objects that will contain all the custom metadata you want the asset to have.
- You can create as many custom metadata attributes objects as you have named sets of custom metadata.
- Use the
updater()
method to initialize the object with all necessary attributes for updating it. - Directly chain the custom metadata attributes onto the
updater()
method's result. Note that the first parameter needs to be the name of the custom metadata that contains these attributes. - Continue chaining custom metadata attributes onto each other, if you have multiple sets of custom metadata you want to include in the replacement.
- Call the
build()
method to build the enriched object. - Call the
saveReplacingCM()
method to replace the custom metadata for the asset in Atlan. (If you usesave()
then no custom metadata updates will be made; while usingsaveMergingCM()
will only update any new or changed values.) Because this operation will persist the asset in Atlan, you must provide it anAtlanClient
through which to connect to the tenant. - The response will include all assets that were updated.
Replace all custom metadata on existing assets | |
---|---|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 |
|
- Use the
updater()
method to create an asset suitable for modifiaction i.e. with all the required attributes. - Create a new instance of CustomMetadataDict.
-
Provide the name of an existing custom metadata set.
Name will be validated
The name will be validated at runtime to ensure that a custom metadata set with the given name exists.
-
For each property that you want to set, specify the property name.
Name will be validated
The metadata property name will be validated at runtime to ensure that a property with the given name exists in the custom metadata set.
-
For any property that can be multi-valued, we need to send a list of values.
- Use the
set_custom_metadata()
method to add the custom metadata to the model object. - You must call
set_custom_metadata()
for each set of custom metadata. - Use the
save_replacing_cm()
method to update the model object on the server. - Assert that a
Table
asset has been updated.
Replace all custom metadata on existing assets | |
---|---|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
|
- Create one or more custom metadata attributes objects that will contain all the custom metadata you want the asset to have.
- You can create as many custom metadata attributes objects as you have named sets of custom metadata.
- Use the
updater()
method to initialize the object with all necessary attributes for updating it. - Directly chain the custom metadata attributes onto the
updater()
method's result. Note that the first parameter needs to be the name of the custom metadata that contains these attributes. - Continue chaining custom metadata attributes onto each other, if you have multiple sets of custom metadata you want to include in the replacement.
- Call the
build()
method to build the enriched object. - Call the
saveReplacingCM()
method to replace the custom metadata for the asset in Atlan. (If you usesave()
then no custom metadata updates will be made; while usingsaveMergingCM()
will only update any new or changed values.) Because this operation will persist the asset in Atlan, you must provide it anAtlanClient
through which to connect to the tenant. - The response will include all assets that were updated.
POST /api/meta/entity/bulk?replaceClassifications=false&replaceBusinessAttributes=true&overwriteBusinessAttributes=true | |
---|---|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 |
|
- Note that the query parameters
replaceBusinessAttributes
andoverwriteBusinessAttributes
must both equaltrue
in the request. This is what causes the replacement behavior. - All assets must be wrapped in an
entities
array. - You must provide the exact type name for the asset (case-sensitive).
- You must provide the exact
qualifiedName
of the asset (case-sensitive). - You must provide the exact name of the asset (case-sensitive).
- Each custom metadata set you want to include in the replacement must be a sub-object of the
businessAttributes
object. - Each custom metadata set must be specified using its hashed-string representation.
- Each custom metadata attribute you want to update must be given using its hashed-string representation.
- Additional custom metadata sets would be listed as additional sub-objects of the
businessAttributes
object. (Still using a hashed-string representation.) - ...and custom metadata attributes within those sets would be listed as sub-objects of the custom metadata set object. (Still using a hashed-string representation.)
Remove from an existing asset¶
Remove only some custom metadata attributes¶
To remove only some custom metadata attributes (leaving all others unchanged):
This currently isn't possible via dbt.
Remove only some custom metadata attributes | |
---|---|
1 2 3 4 5 6 7 8 |
|
- Create a custom metadata attributes object that will contain only the attributes and values for custom metadata that you want to remove from the asset. All other custom metadata attributes (those not specified in this object) will remain unchanged on the asset.
-
For each attribute, use the
attribute()
method and pass:- the name of the attribute within that set
- a special value of
Removable.NULL
This special value will ensure that the custom metadata attribute (
Accountable
in this example) is removed from the asset. -
Use the
updateCustomMetadataAttributes()
method to update only theAccountable
attribute in theRACI
custom metadata on the existing asset. Since we're sending a special value tonull
this attribute, it will be removed by the update. Any other custom metadata attributes inRACI
and all other custom metadata will be left unchanged. - Because this operation will directly change the asset in Atlan, you must provide it an
AtlanClient
through which to connect to the tenant. - Note that for this operation you must know the GUID of the asset you want to remove the custom metadata from. Also, the operation returns no result: if there is an error it will throw an exception, but the result of the operation must be determined by retrieving the asset through a separate API call, if you want to confirm it.
- Provide the name for the custom metadata you want to remove.
- Provide the custom metadata attributes object with the attributes and special
Removable.NULL
values you want to remove for that custom metadata.
Remove only some custom metadata attributes | |
---|---|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 |
|
- Use the
updater()
method to create an asset suitable for modifiaction i.e. with all the required attributes. - Create an instance of
CustomMetadataDict
. -
Provide the name of an existing of an existing custom metadata set.
Name will be validated
The name will be validated at runtime to ensure that a custom metadata set with the given name exists.
-
Set the value of the property you wish to replace to
None
.Name will be validated
The metadata property name will be validated at runtime to ensure that a property with the given name exists in the custom metadata set.
-
Use the
set_custom_metadata()
method to add the custom metadata to the model object. - Use the
save_merging_cm()
method to update the model object on the server. - Assert that a
Table
asset has been updated.
Remove only some custom metadata attributes | |
---|---|
1 2 3 4 5 6 7 8 |
|
- Create a custom metadata attributes object that will contain only the attributes and values for custom metadata that you want to remove from the asset. All other custom metadata attributes (those not specified in this object) will remain unchanged on the asset.
-
For each attribute, use the
attribute()
method and pass:- the name of the attribute within that set
- a special value of
Removable.NULL
This special value will ensure that the custom metadata attribute (
Accountable
in this example) is removed from the asset. -
Use the
updateCustomMetadataAttributes()
method to update only theAccountable
attribute in theRACI
custom metadata on the existing asset. Since we're sending a special value tonull
this attribute, it will be removed by the update. Any other custom metadata attributes inRACI
and all other custom metadata will be left unchanged. - Because this operation will directly change the asset in Atlan, you must provide it an
AtlanClient
through which to connect to the tenant. - Note that for this operation you must know the GUID of the asset you want to remove the custom metadata from. Also, the operation returns no result: if there is an error it will throw an exception, but the result of the operation must be determined by retrieving the asset through a separate API call, if you want to confirm it.
- Provide the name for the custom metadata you want to remove.
- Provide the custom metadata attributes object with the attributes and special
Removable.NULL
values you want to remove for that custom metadata.
POST /api/meta/entity/guid/a89ff15b-f5e6-48bc-870b-acfa11e212ae/businessmetadata?isOverwrite=false | |
---|---|
1 2 3 4 5 |
|
- Note that the query parameters
isOverwrite
must befalse
in the request. This is what allows the removal of only the attributes provided in the request (and leaving all others unchanged). Also note that you must provide the GUID of the asset — there is no equivalent operation using the qualifiedName. - Each custom metadata set you want to include in the partial removal must be specified using its hashed-string representation.
- Each custom metadata attribute you want to remove must be given using its hashed-string representation, with a value of
null
. You would either need to first retrieve the list of custom metadata definitions via API to determine this value, or look through the development console of your browser while opening the custom metadata in the Atlan UI.
Remove some custom metadata from an asset¶
You can also remove an entire set of custom metadata from existing assets. If you do this individually, you can selectively remove individual sets of custom metadata:
Remove some custom metadata from an existing asset | |
---|---|
1 2 3 4 5 6 |
|
- You must of course give the name of the object.
- The custom metadata must be nested within the
meta
.atlan
.businessAttributes
structure. To remove all properties for some custom metadata, send an explicit empty dictionary{}
to the custom metadata's hashed-string representation.
Remove some custom metadata from an asset | |
---|---|
1 2 3 4 |
|
- Use the
removeCustomMetadata()
method to remove an entire named set of custom metadata from an asset. Any other custom metadata in other named sets will be left unchanged. - Because this operation will directly change the asset in Atlan, you must provide it an
AtlanClient
through which to connect to the tenant. - Note that for this operation you must know the GUID of the asset you want to remove the custom metadata from. Also, the operation returns no result: if there is an error it will throw an exception, but the result of the operation must be determined by retrieving the asset through a separate API call, if you want to confirm it.
- Provide the name for the custom metadata you want to remove.
Remove some custom metadata from an asset | |
---|---|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 |
|
- Use the
updater()
method to create an asset suitable for modifiaction i.e. with all the required attributes. - Create a new instance of
CustomMetadataDict
. -
Provide the name of an existing custom metadata set.
Name will be validated
The name will be validated at runtime to ensure that a custom metadata set with the given name exists.
-
Use the
set_custom_metadata()
method to add the custom metadata to the model object. - Use the
save_merging_cm()
method to update the model object on the server. - Assert that a
Table
asset has been updated.
Remove some custom metadata from an asset | |
---|---|
1 2 3 4 |
|
- Use the
removeCustomMetadata()
method to remove an entire named set of custom metadata from an asset. Any other custom metadata in other named sets will be left unchanged. - Because this operation will directly change the asset in Atlan, you must provide it an
AtlanClient
through which to connect to the tenant. - Note that for this operation you must know the GUID of the asset you want to remove the custom metadata from. Also, the operation returns no result: if there is an error it will throw an exception, but the result of the operation must be determined by retrieving the asset through a separate API call, if you want to confirm it.
- Provide the name for the custom metadata you want to remove.
POST /api/meta/entity/guid/a89ff15b-f5e6-48bc-870b-acfa11e212ae/businessmetadata?isOverwrite=false | |
---|---|
1 2 3 4 5 6 7 8 |
|
- Note that the query parameters
isOverwrite
must befalse
in the request. This is what allows the removal of only the custom metadata set provided in the request (and leaving all others unchanged). Also note that you must provide the GUID of the asset — there is no equivalent operation using the qualifiedName. - The custom metadata set you want to remove must be specified using its hashed-string representation.
- Each custom metadata attribute in that custom metadata set must be specified using its hashed-string representation, with a value of
null
. You would either need to first retrieve the list of custom metadata definitions via API to determine this value, or look through the development console of your browser while opening the custom metadata in the Atlan UI.
Remove all custom metadata from an asset¶
Could create a new asset
Remember that Atlan matches the provided qualifiedName
to determine whether to update or create the asset.
To remove all custom metadata from an existing asset:
Remove all custom metadata from an existing asset | |
---|---|
1 2 3 4 5 |
|
- You must of course give the name of the object.
- The custom metadata must be nested within the
meta
.atlan
.businessAttributes
structure. To remove all custom metadata, send an explicit empty dictionary{}
.
Remove all custom metadata from an existing asset | |
---|---|
1 2 3 4 5 |
|
- Use the
updater()
method to initialize the object with all necessary attributes for updating it. (Removing the custom metadata is still an update to the asset, we are not deleting the asset itself.) - Call the
saveReplacingCM()
method to actually update the asset, and overwrite custom metadata. Since we have not provided any custom metadata in our object, this will replace the existing custom metadata on the asset with no custom metadata. (In other words, it will remove all custom metadata from the asset.) Because this operation will persist the asset in Atlan, you must provide it anAtlanClient
through which to connect to the tenant. - The response will include that single asset that was updated (again, removing custom metadata is an update to the asset — we are not deleting the asset itself).
Remove all custom metadata from an existing asset | |
---|---|
1 2 3 4 5 6 7 8 9 10 11 12 |
|
- Use the
updater()
method to initialize the object with all necessary attributes for updating it. (Removing the custom metadata is still an update to the asset, we are not deleting the asset itself.) - Call the
save_replacing_cm()
method to actually update the asset. - Assert that a
Table
asset has been updated.
Remove all custom metadata from an existing asset | |
---|---|
1 2 3 4 5 |
|
- Use the
updater()
method to initialize the object with all necessary attributes for updating it. (Removing the custom metadata is still an update to the asset, we are not deleting the asset itself.) - Call the
saveReplacingCM()
method to actually update the asset, and overwrite custom metadata. Since we have not provided any custom metadata in our object, this will replace the existing custom metadata on the asset with no custom metadata. (In other words, it will remove all custom metadata from the asset.) Because this operation will persist the asset in Atlan, you must provide it anAtlanClient
through which to connect to the tenant. - The response will include that single asset that was updated (again, removing custom metadata is an update to the asset — we are not deleting the asset itself).
POST /api/meta/entity/bulk?replaceClassifications=false&replaceBusinessAttributes=true&overwriteBusinessAttributes=true | |
---|---|
1 2 3 4 5 6 7 8 9 10 11 |
|
- Note that the query parameters
replaceBusinessAttributes
andoverwriteBusinessAttributes
must both equaltrue
in the request. This is what causes the replacement behavior. - All assets must be wrapped in an
entities
array. - You must provide the exact type name for the asset (case-sensitive).
- You must provide the exact
qualifiedName
of the asset (case-sensitive). - You must provide the exact name of the asset (case-sensitive).
- By not providing any
businessAttributes
in the request, you will replace whatever custom metadata is on the asset with no custom metadata — equivalent to removing all custom metadata.
When creating an asset¶
To add custom metadata when creating one or many assets:
Add custom metadata when creating asset | |
---|---|
1 2 3 4 5 6 7 8 9 10 |
|
- You must of course give the name of the object.
- The custom metadata must be nested within the
meta
.atlan
.businessAttributes
structure. - Each custom metadata set you want to add or update must be given using its hashed-string representation.
- Each custom metadata attribute you want to update must be given using its hashed-string representation.
- For multivalued custom metadata attributes, specify the value as an array.
Add custom metadata when creating asset | |
---|---|
1 2 3 4 5 6 7 8 9 10 11 12 13 |
|
- Create a custom metadata attributes object that will contain the attributes and values for custom metadata you want to add to the asset.
-
For each attribute, use the
attribute()
method and pass:- the name of the attribute within that set
- the value for that attribute
The value can be any object valid for the attribute: a string, a boolean, or a number. (Note that dates are sent as
long
(epoch) numbers.) -
For any attribute that can be multi-valued, we can send a list of values.
- Use the
creator()
method to initialize the object with all necessary attributes for creating it. -
Set the custom metadata that should be added (using the custom metadata attributes object you built earlier).
- Note that the first parameter to this method is the name of the custom metadata for which you're providing the attributes and values.
- You can chain this
customMetadata()
method as many times as you like to add other custom metadata and attributes, but you should only call it once per named custom metadata set. (If you call it multiple times for the same named custom metadata, only the last one will be applied.)
-
Call the
build()
method to build the enriched object. - Call the
saveReplacingCM()
method to create the asset, including its custom metadata. (During creation you could also usesaveMergingCM()
, but if you use onlysave()
then no custom metadata will be attached to the assets.) Because this operation will persist the asset in Atlan, you must provide it anAtlanClient
through which to connect to the tenant. - The response will include all assets that were created.
Add custom metadata when creating asset | |
---|---|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 |
|
- Use the
creator()
method to initialize the object with all necessary attributes for creating it. - Create a new instance of
CustomMetadataDict
. -
Provide the name of and existing custom metadata set.
Name will be validated
The name will be validated at runtime to ensure that a custom metadata set with the given name exists.
-
For each property that you want to set, specify the property name.
Name will be validated
The metadata property name will be validated at runtime to ensure that a property with the given name exists in the custom metadata set.
-
For any attribute that can be multi-valued, we need to send a list of values.
- Use the
set_custom_metadata()
method to add the custom metadata to the model object. - Use the
save()
method to update the model object on the server. - assert that a
Table
asset was created.
Add custom metadata when creating asset | |
---|---|
1 2 3 4 5 6 7 8 9 10 11 12 13 |
|
- Create a custom metadata attributes object that will contain the attributes and values for custom metadata you want to add to the asset.
-
For each attribute, use the
attribute()
method and pass:- the name of the attribute within that set
- the value for that attribute
The value can be any object valid for the attribute: a string, a boolean, or a number. (Note that dates are sent as
long
(epoch) numbers.) -
For any attribute that can be multi-valued, we can send a list of values.
- Use the
creator()
method to initialize the object with all necessary attributes for creating it. -
Set the custom metadata that should be added (using the custom metadata attributes object you built earlier).
- Note that the first parameter to this method is the name of the custom metadata for which you're providing the attributes and values.
- You can chain this
customMetadata()
method as many times as you like to add other custom metadata and attributes, but you should only call it once per named custom metadata set. (If you call it multiple times for the same named custom metadata, only the last one will be applied.)
-
Call the
build()
method to build the enriched object. - Call the
saveReplacingCM()
method to create the asset, including its custom metadata. (During creation you could also usesaveMergingCM()
, but if you use onlysave()
then no custom metadata will be attached to the assets.) Because this operation will persist the asset in Atlan, you must provide it anAtlanClient
through which to connect to the tenant. - The response will include all assets that were created.
POST /api/meta/entity/bulk | |
---|---|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 |
|
- All assets must be wrapped in an
entities
array. - You must provide the exact type name for the asset (case-sensitive).
- You must provide a name for the asset.
- In the case of a table, the
qualifiedName
must be the concatenation of the parent schema's qualifiedName and the name of the table. - When creating a table, you must specify the schema to create it within. This is defined by the
atlanSchema
attribute. You must specify both the type (must beSchema
) and qualifiedName of the schema within theatlanSchema
attribute — and the schema must already exist. - Each custom metadata set you want to include on the asset must be a sub-object of the
businessAttributes
object. - Each custom metadata set must be specified using its hashed-string representation.
- Each custom metadata attribute you want to add must be given using its hashed-string representation.
- For multivalued custom metadata attributes, specify the value as an array.
Find hashed-string names¶
When using either the raw APIs or dbt, you must provide the classification names using Atlan's hashed-string representation.
Not necessary for SDKs
Note that this is not needed when using the SDKs, which translate these for you!
To look up the hashed-string representations:
The response will include displayName
and name
, both at overall custom metadata level and for each attribute (property). The displayName
is what you see in Atlan's UI, and the name
is the hashed-string representation:
Simplified response | |
---|---|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 |
|