Skip to content

Manage data contracts via SDKs

Limited availability

Data contracts can currently only be managed for tables, views, and materialized views.

Create a new contract

2.2.4 1.12.5

To create a contract for an existing asset in Atlan:

Create a data contract
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
Map<String, Object> contractDetails = Map.ofEntries( // (1)
    Map.entry("type", "Table"),
    Map.entry("status", "DRAFT"),
    Map.entry("kind", "DataContract"),
    Map.entry("dataset", "SALE_TXN"),
    Map.entry("data_source", "snowflake"),
    Map.entry("description", "Created by Java SDK."),
    Map.entry("columns", Map.ofEntries(
        Map.entry("name", "order_id"),
        Map.entry("data_type", "BIGNUMERIC"),
        Map.entry("description", ""))));
DataContract contract = DataContract.creator(
    Serde.allInclusiveMapper.writeValueAsString(contractDetails),
    "default/snowflake/1717514525/RAW/WIDEWORLD/SALE_TXN"
).build();
AssetMutationResponse response = contract.save(); // (3)

  1. Start by constructing the data contract JSON. In this example, we're defining it with only the minimal required properties as specified by the API. Please check the reference section for the complete data contract specification.

    • type of the asset in Atlan (Table, View, or MaterializedView).
    • state of the contract (DRAFT or VERIFIED).
    • must always be DataContract.
    • name of the asset as it exists inside Atlan.
    • name of the asset connection as it exists inside Atlan.
    • (Optional) description of this dataset, for documentation purposes.
    • (Optional) columns:
      • name of the column as it is defined in the source system (often technical).
      • physical data type of values in this column.
      • description of this column, for documentation purposes.

  2. You need to provide the the contract JSON (must be string) and the qualifiedName of your asset (in this example, the qualifiedName of a Snowflake table) to the creator() method.

  3. Finally, you can call the save() method to create the new data contract in Atlan.
Create a data contract
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
from json import dumps
from pyatlan.client.atlan import AtlanClient
from pyatlan.model.assets import DataContract

client = AtlanClient()

contract_json = {  # (1)
    "type": "Table",
    "status": "DRAFT",
    "kind": "DataContract",
    "dataset": "SALE_TXN",
    "data_source": "snowflake",
    "description": "Created by Python SDK.",
    "columns": [{"name": "order_id", "data_type": "BIGNUMERIC", "description": ""}],
}

contract = DataContract.creator( # (2)
    asset_qualified_name="default/snowflake/1717514525/RAW/WIDEWORLD/SALE_TXN",
    contract_json=dumps(contract_json),
)

response = client.asset.save(contract) # (3)

  1. Start by constructing the data contract JSON. In this example, we're defining it with only the minimal required properties as specified by the API. Please check the reference section for the complete data contract specification.

    • type of the asset in Atlan (Table, View, or MaterializedView).
    • state of the contract (DRAFT or VERIFIED).
    • must always be DataContract.
    • name of the asset as it exists inside Atlan.
    • name of the asset connection as it exists inside Atlan.
    • (Optional) description of this dataset, for documentation purposes.
    • (Optional) columns:
      • name of the column as it is defined in the source system (often technical).
      • physical data type of values in this column.
      • description of this column, for documentation purposes.

  2. You need to provide the qualified_name of your asset (in this example, the qualifiedName of a Snowflake table) and the contract JSON (must be string) to the creator() method.

  3. Finally, you can call the save() method to create the new data contract in Atlan.
Create a data contract
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
val contractDetails = mapOf( // (1)
    "type" to "Table",
    "status" to "DRAFT",
    "kind" to "DataContract",
    "dataset" to "SALE_TXN",
    "data_source" to "snowflake",
    "description" to "Created by Java SDK.",
    "columns" to mapOf(
        "name" to "order_id",
        "data_type" to "BIGNUMERIC",
        "description" to "",
    )
)
val contract = DataContract.creator( // (2)
    Serde.allInclusiveMapper.writeValueAsString(contractDetails),
    "default/snowflake/1717514525/RAW/WIDEWORLD/SALE_TXN"
).build()
val response = contract.save() // (3)

  1. Start by constructing the data contract JSON. In this example, we're defining it with only the minimal required properties as specified by the API. Please check the reference section for the complete data contract specification.

    • type of the asset in Atlan (Table, View, or MaterializedView).
    • state of the contract (DRAFT or VERIFIED).
    • must always be DataContract.
    • name of the asset as it exists inside Atlan.
    • name of the asset connection as it exists inside Atlan.
    • (Optional) description of this dataset, for documentation purposes.
    • (Optional) columns:
      • name of the column as it is defined in the source system (often technical).
      • physical data type of values in this column.
      • description of this column, for documentation purposes.

  2. You need to provide the the contract JSON (must be string) and the qualifiedName of your asset (in this example, the qualifiedName of a Snowflake table) to the creator() method.

  3. Finally, you can call the save() method to create the new data contract in Atlan.
POST /api/meta/entity/bulk
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
{
"entities": [
    {
       "typeName": "DataContract", // (1)
       "attributes": { // (2)
           "dataContractJson": "{\"type\": \"Table\", \"status\": \"DRAFT\", \"kind\": \"DataContract\", \"dataset\": \"SALE_TXN\", \"data_source\": \"snowflake\", \"description\": \"Created by Python SDK.\", \"columns\": [{\"name\": \"order_id\", \"data_type\": \"BIGNUMERIC\", \"description\": \"\"}]}",
           "name": "Data contract for SALE_TXN", // (3)
           "qualifiedName": "default/snowflake/1717514525/RAW/WIDEWORLD/SALE_TXN/contract" // (4)
       }
    }
]
}
  1. The typeName must be exactly DataContract.

  2. Provide the data contract JSON. In this example, we're creating it with only the minimal required properties as specified by the API. Please check the reference section for the complete data contract specification.

    • type of the asset in Atlan (Table, View, or MaterializedView).
    • state of the contract (DRAFT or VERIFIED).
    • must always be DataContract.
    • name of the asset as it exists inside Atlan.
    • name of the asset connection as it exists inside Atlan.
    • (Optional) description of this dataset, for documentation purposes.
    • (Optional) columns:
      • name of the column as it is defined in the source system (often technical).
      • physical data type of values in this column.
      • description of this column, for documentation purposes.

  3. You must provide a human-readable name for your contract.

  4. The qualifiedName should follow the pattern: <assetQualifiedName>/contract (where assetQualifiedName is, in this example, the qualifiedName of a Snowflake table).

Retrieve a contract

2.2.4 1.12.5

By asset:

To retrieve the latest contract and certified contract of a given asset using its qualified name:

Retrieve latest and certified data contract of a asset
1
2
3
Table table = Table.get("default/snowflake/1717514525/RAW/WIDEWORLD/SALE_TXN"); // (1)
DataContract latest = table.getDataContractLatest(); // (2)
DataContract certified  = table.getDataContractLatestCertified(); // (3)
  1. First, retrieve the asset by its qualifiedName.
  2. Retrieve the latest data contract by using .getDataContractLatest().
  3. Retrieve the certified data contract by using the .getDataContractLatestCertified().
Retrieve latest and certified data contract of a asset
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
from pyatlan.client.atlan import AtlanClient
from pyatlan.model.assets import DataContract

client = AtlanClient()

table = client.asset.get_by_qualified_name( # (1)
    asset_type=Table,
    qualified_name="default/snowflake/1717514525/RAW/WIDEWORLD/SALE_TXN"
)

latest_contract = table.data_contract_latest # (2)
certified_contract  = table.data_contract_latest_certified # (3)
  1. First, retrieve the asset by its qualified_name.
  2. Retrieve the latest data contract by using the table.data_contract_latest attribute.
  3. Retrieve the certified data contract by using the table.data_contract_latest_certified attribute.
Retrieve latest and certified data contract of a asset
1
2
3
val table = Table.get("default/snowflake/1717514525/RAW/WIDEWORLD/SALE_TXN") // (1)
val latest = table.dataContractLatest // (2)
val certified  = table.dataContractLatestCertified // (3)
  1. First, retrieve the asset by its qualifiedName.
  2. Retrieve the latest data contract by using .dataContractLatest.
  3. Retrieve the certified data contract by using the .dataContractLatestCertified.
GET /api/meta/entity/uniqueAttribute/type/Table?attr%3AqualifiedName=default%2Fsnowflake%2F1717514525%2FRAW%2FWIDEWORLD%2FSALE_TXN&minExtInfo=False&ignoreRelationships=False
1
// (1)

  1. All details are in the URL itself.

    URL-encoded filter

    Note that the filter is URL-encoded. decoded it would be: /api/meta/entity/uniqueAttribute/type/Table?attr:qualifiedName=default/snowflake/1717514525/RAW/WIDEWORLD/SALE_TXN&minExtInfo=False&ignoreRelationships=False

By qualified name:

To retrieve a contract by its version (V1, V2, etc) using its qualified name:

Retrieve a data contract by its version
1
2
3
DataContract contract = DataContract.get( // (1)!
    "default/snowflake/1717514525/RAW/WIDEWORLD/SALE_TXN/Table/contract/V1"
);
  1. The qualifiedName of the data contract must be in the format: <assetQualifiedName>/<assetType>/contract/V<versionNumber>. For this example:
    • assetQualifiedName: qualifiedName of a Snowflake table.
    • assetType: type of this asset in Atlan, i.e: Table.
    • versionNumber: specific version of the data contract to retrieve, e.g: 1, 2, and so on.
Retrieve a data contract by its version
1
2
3
4
5
6
7
8
9
from pyatlan.client.atlan import AtlanClient
from pyatlan.model.assets import DataContract

client = AtlanClient()

contract = client.asset.get_by_qualified_name(
    asset_type=DataContract,  # (1)
    qualified_name="default/snowflake/1717514525/RAW/WIDEWORLD/SALE_TXN/Table/contract/V1"
)
  1. The qualifiedName of the data contract must be in the format: <assetQualifiedName>/<assetType>/contract/V<versionNumber>. For this example:
    • assetQualifiedName: qualifiedName of a Snowflake table.
    • assetType: type of this asset in Atlan, i.e: Table.
    • versionNumber: specific version of the data contract to retrieve, e.g: 1, 2, and so on.
Retrieve a data contract by its version
1
2
3
val contract = DataContract.get( // (1)!
    "default/snowflake/1717514525/RAW/WIDEWORLD/SALE_TXN/Table/contract/V1"
)
  1. The qualifiedName of the data contract must be in the format: <assetQualifiedName>/<assetType>/contract/V<versionNumber>. For this example:
    • assetQualifiedName: qualifiedName of a Snowflake table.
    • assetType: type of this asset in Atlan, i.e: Table.
    • versionNumber: specific version of the data contract to retrieve, e.g: 1, 2, and so on.
GET /api/meta/entity/uniqueAttribute/type/DataContract?attr%3AqualifiedName=dedefault%2Fsnowflake%2F1717514525%2FRAW%2FWIDEWORLD%2FSALE_TXN%2FTable%2Fcontract%2FV1&minExtInfo=False&ignoreRelationships=False
1
// (1)

  1. All details are in the URL itself.

    URL-encoded filter

    Note that the filter is URL-encoded. decoded it would be: attr:qualifiedName=default/snowflake/1717514525/RAW/WIDEWORLD/SALE_TXN/Table/contract/V1&minExtInfo=False&ignoreRelationships=False

    where the qualifiedName of the data contract must be in the format: <assetQualifiedName>/<assetType>/contract/V<versionNumber>. For this example:

    • assetQualifiedName: qualifiedName of a Snowflake table.
    • assetType: type of this asset in Atlan, i.e: Table.
    • versionNumber: specific version of the data contract to retrieve, e.g: 1, 2, and so on.

Update a contract

2.2.4 1.12.5

In the following example, we are updating the contact certificateStatus field to VERIFIED (shown as PUBLISHED in the UI):

Update a data contract
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
Map<String, Object> updatedContractDetails = Map.ofEntries( // (1)
    Map.entry("type", "Table"),
    // Update certificate status to 'VERIFIED'
    Map.entry("status", "VERIFIED"),
    Map.entry("kind", "DataContract"),
    Map.entry("dataset", "SALE_TXN"),
    Map.entry("data_source", "snowflake"),
    Map.entry("description", "Created by Java SDK."),
    Map.entry("columns", Map.ofEntries(
        Map.entry("name", "order_id"),
        Map.entry("data_type", "BIGNUMERIC"),
        Map.entry("description", ""))));
DataContract contract = DataContract.updater( // (2)
    "default/snowflake/1717514525/RAW/WIDEWORLD/SALE_TXN/contract",
    "Data contract for SALE_TXN"
)
    .dataContractJson(Serde.allInclusiveMapper.writeValueAsString(updatedContractDetails)) // (3)
    .build();
AssetMutationResponse response = contract.save(); // (4)
  1. Begin by constructing the updated data contract JSON.

  2. Use the updater() method to update a data contract.

    • qualifiedName of the data contract, ie: <assetQualifiedName>/contract (where assetQualifiedName is, in this example, the qualifiedName of a Snowflake table).
    • name of the data contract. (NOTE: SDKs and CLI always generate it in the format: "Data contract for dataset (asset.name)").

  3. You can then add any other updates or attributes. In this example, we're updating the contract JSON (must be string).

  4. To update the data contract in Atlan, call the save() method with the object you've built.
Update a data contract
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
from json import dumps
from pyatlan.client.atlan import AtlanClient
from pyatlan.model.assets import DataContract

client = AtlanClient()

updated_contract_json = {  # (1)
    "type": "Table",
    # Update certificate status to 'VERIFIED'
    "status": "VERIFIED"
    "kind": "DataContract",
    "dataset": "SALE_TXN",
    "data_source": "snowflake",
    "description": "Created by Python SDK.",
    "columns": [{"name": "order_id", "data_type": "BIGNUMERIC", "description": ""}],
}

contract = DataContract.updater( # (2)
    qualified_name="default/snowflake/1717514525/RAW/WIDEWORLD/SALE_TXN/contract",
    name="Data contract for SALE_TXN",
)
contact.data_contract_json = dumps(updated_contract_json) # (3)

response = client.asset.save(contract)  # (4)
  1. Begin by constructing the updated data contract JSON.

  2. Use the updater() method to update a data contract.

    • qualifiedName of the data contract, ie: <assetQualifiedName>/contract (where assetQualifiedName is, in this example, the qualifiedName of a Snowflake table).
    • name of the data contract. (NOTE: SDKs and CLI always generate it in the format: "Data contract for dataset (asset.name)").

  3. You can then add any other updates or attributes. In this example, we're updating the contract JSON (must be string).

  4. To update the data contract in Atlan, call the save() method with the object you've built.
Update a data contract
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
val contractDetails = mapOf( // (1)
    "type" to "Table",
    // Update certificate status to 'VERIFIED'
    "status" to "VERIFIED",
    "kind" to "DataContract",
    "dataset" to "SALE_TXN",
    "data_source" to "snowflake",
    "description" to "Created by Java SDK.",
    "columns" to mapOf(
        "name" to "order_id",
        "data_type" to "BIGNUMERIC",
        "description" to "",
    )
)
val contract = DataContract.updater( // (2)
    "default/snowflake/1717514525/RAW/WIDEWORLD/SALE_TXN/contract",
    "Data contract for SALE_TXN"
)
    .dataContractJson(Serde.allInclusiveMapper.writeValueAsString(updatedContractDetails)) // (3)
    .build()
val response = contract.save() // (4)
  1. Begin by constructing the updated data contract JSON.

  2. Use the updater() method to update a data contract.

    • qualifiedName of the data contract, ie: <assetQualifiedName>/contract (where assetQualifiedName is, in this example, the qualifiedName of a Snowflake table).
    • name of the data contract. (NOTE: SDKs and CLI always generate it in the format: "Data contract for dataset (asset.name)").

  3. You can then add any other updates or attributes. In this example, we're updating the contract JSON (must be string).

  4. To update the data contract in Atlan, call the save() method with the object you've built.
POST /api/meta/entity/bulk
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
{
"entities": [
    {
       "typeName": "DataContract", // (1)
       "attributes": { // (2)
           "dataContractJson": "{\"type\": \"Table\", \"status\": \"VERIFIED\", \"kind\": \"DataContract\", \"dataset\": \"SALE_TXN\", \"data_source\": \"snowflake\", \"description\": \"Created by Python SDK.\", \"columns\": [{\"name\": \"order_id\", \"data_type\": \"BIGNUMERIC\", \"description\": \"\"}]}",
           "name": "Data contract for SALE_TXN", // (3)
           "qualifiedName": "default/snowflake/1717514525/RAW/WIDEWORLD/SALE_TXN/contract" // (4)
       }
    }
]
}
  1. The typeName must be exactly DataContract.

  2. Provide the data contract JSON. In this example, we're updating it with only the minimal required properties as specified by the API. Please check the reference section for the complete data contract specification.

    • type of the asset in Atlan (Table, View, or MaterializedView).
    • state of the contract (DRAFT or VERIFIED).
    • must always be DataContract.
    • name of the asset as it exists inside Atlan.
    • name of the asset connection as it exists inside Atlan.
    • (Optional) description of this dataset, for documentation purposes.
    • (Optional) columns:
      • name of the column as it is defined in the source system (often technical).
      • physical data type of values in this column.
      • description of this column, for documentation purposes.

  3. Human-readable name for your contract.

  4. The qualifiedName of your contract, ie: <assetQualifiedName>/contract (where assetQualifiedName is, in this example, the qualifiedName of a Snowflake table).

Delete a contract

Soft-delete (archive)

To soft-delete, or archive, a contract:

Coming soon

Coming soon

Coming soon

Coming soon

Hard-delete (purge)

To permanently delete (purge) a contract:

Coming soon

Coming soon

Coming soon

Coming soon