Introductory walkthrough - Developer

The response will contain details of the change: whether the asset was created, updated, or nothing happened because the asset already had those changes. Atlan will handle idempotency By sending only the changes you want to apply, Atlan can make idempotent updates.


Introductory walkthrough - Developer

Atlan will only attempt to update the asset with the changes you send. Atlan leaves any existing metadata on the asset as-is.


Introductory walkthrough - Developer

If the asset already has the metadata values you are sending, Atlan does nothing. It will not even update audit details like the last update timestamp, and is thus idempotent.


Introductory walkthrough - Developer

What if you want to make changes to many assets, as efficiently as possible? Start by initializing a batch.


Introductory walkthrough - Developer

Through this batch, we can automatically queue up and bulk-upsert assets — in this example, 20 at a time. Be sure to include any details you might need to make a decision about whether to update the asset or not (and what to update it with).


Introductory walkthrough - Developer

You must flush() the batch outside of any loop where you've added assets into it. This ensures any final remaining elements in the batch are still sent to Atlan, even if the batch is not "full".


Introductory walkthrough - Developer

Finally, from the batch you can retrieve the minimal details about any assets it created or updated. Start by initializing a batch.


Introductory walkthrough - Developer


Introductory walkthrough - Developer

You can then add() any updated objects directly into the batch you created earlier. The batch itself will handle saving these to Atlan when a sufficient number have been queued up (20, in this example).


Introductory walkthrough - Developer

Finally, from the batch you can retrieve the minimal details about any assets it created or updated. Where to go from here Common tasks Common operations on assets, that are available across all assets.


Introductory walkthrough - Developer

Discover actions Common operations on assets, that are available across all assets. Asset-specific Operations that are specific to certain assets.


Introductory walkthrough - Developer

Focus on a specific kind of asset Operations that are specific to certain assets. Focus on a specific kind of asset Governance structures Operations dealing with governance structures, rather than assets.


Introductory walkthrough - Developer

Manage governance structures Operations dealing with governance structures, rather than assets. Manage governance structures Samples Real code samples our customers use to solve particular use cases.


Introductory walkthrough - Developer

Review live samples Real code samples our customers use to solve particular use cases. Review live samples Events Delve deep into the details of the events Atlan triggers.


Introductory walkthrough - Developer

Learn more about events Delve deep into the details of the events Atlan triggers. Learn more about events Note that this is intentionally kept as simple as possible.


Introductory walkthrough - Developer

The walkthrough is not intended to be exhaustive. Where possible, we have cross-referenced other detailed examples elsewhere in the site.


Introductory walkthrough - Developer

↩ Note that this is intentionally kept as simple as possible. The walkthrough is not intended to be exhaustive.


Introductory walkthrough - Developer

Where possible, we have cross-referenced other detailed examples elsewhere in the site. ↩ There are orders of magnitude lower chances of GUIDs conflicting with each other than there are grains of sand on the planet.


Introductory walkthrough - Developer

(And generating them does not rely on a central ID-assigning registry.) ↩ There are orders of magnitude lower chances of GUIDs conflicting with each other than there are grains of sand on the planet. (And generating them does not rely on a central ID-assigning registry.) ↩


Introductory walkthrough - Developer

An introductory walkthrough You might also like our Atlan Platform Essentials certification. Not sure where to start?


Introductory walkthrough - Developer

Allow us to introduce Atlan development through example. 1 We strongly recommend using one of our SDKs to simplify the development process.


Introductory walkthrough - Developer

As a first step, set one up: The SDK is available on Maven Central , ready to be included in your project: Include the latest version of the Java SDK in your project as a dependency. You can also give a specific version instead of the + , if you'd like.


Introductory walkthrough - Developer

The Java SDK uses slf4j for logging purposes. You can include logback as a simple binding mechanism to send any logging information out to your console (standard out).


Introductory walkthrough - Developer

Provide two values to create an Atlan client: Provide your Atlan tenant URL as the first parameter. You can also read the value from an environment variable, if you leave out both parameters.


Introductory walkthrough - Developer

Provide your API token as the second parameter. You can also read the value from another environment variable, by leaving out this parameter.


Introductory walkthrough - Developer

You can then start writing some actual code to run within a static main method. (We'll show some examples of this further below.) Once the block is complete, any resources held by the client (i.e.


Introductory walkthrough - Developer

for caching) will be automatically released. Set up logging for SDK You can also checkout to the advanced configuration section of the SDK to learn about how to set up logging.


Introductory walkthrough - Developer

The SDK is available on PyPI. You can use pip to install it as follows: Provide two values to create an Atlan client: Provide your Atlan tenant URL to the base_url parameter.


Introductory walkthrough - Developer

(You can also do this through environment variables .) Provide your API token to the api_key parameter. (You can also do this through environment variables .) Set up logging for SDK You can also checkout to the advanced configuration section of the SDK to learn about how to set up logging.


Introductory walkthrough - Developer

The SDK is available on Maven Central , ready to be included in your project: Include the latest version of the Java SDK in your project as a dependency. You can also give a specific version instead of the + , if you'd like.


Introductory walkthrough - Developer

The Java SDK uses slf4j for logging purposes. You can include slf4j-simple as a simple binding mechanism to send any logging information out to your console (standard out), along with the kotlin-logging-jvm microutil.


Introductory walkthrough - Developer


Introductory walkthrough - Developer

The SDK is available on GitHub , ready to be included in your project: Provide two values to set up connectivity to Atlan: Provide your Atlan tenant URL to the assets.Context() method. If you prefer using the value from an environment variable, you can use assets.NewContext() without any parameters.


Introductory walkthrough - Developer

Provide your API token as the second parameter to the assets.Context() method. (Or again, have it picked up automatically by the assets.NewContext() method.) Set up logging for SDK You can also checkout to the advanced configuration section of the SDK to learn about how to set up logging.


Introductory walkthrough - Developer

Don't forget to give permissions If you want to be able to access existing metadata with an API token, don't forget that you need to assign one or more personas to the API token that grant it access to metadata. Now that you have an SDK installed and configured, you are ready to code!


Introductory walkthrough - Developer

Before we jump straight to code, though, let's first introduce some key concepts in Atlan: What is an asset? In Atlan, we refer to all objects that provide context to your data as assets.


Introductory walkthrough - Developer

Each type of asset in Atlan has a set of: Properties , such as: Certificates Announcements Properties , such as: Relationships to other assets, such as: Schema child tables Table parent schema Table child columns Column parent table Relationships to other assets, such as: Schema child tables Table parent schema Table child columns Column parent table In an object-oriented programming sense, think of an asset as an instance of a class. The structure of an asset (the class itself, in this analogy) is defined by something called a type definition , but that's for another day.


Introductory walkthrough - Developer

So as you can see: There are many different kinds of assets: tables, columns, schemas, databases, business intelligence dashboards, reports, and so on. Assets inter-relate with each other: a table has a parent schema and child columns, a schema has a parent database and child tables, and so on.


Introductory walkthrough - Developer

Different kinds of assets have some common properties (like certificates) and other properties that are unique to that kind of asset (like a columnCount that only exists on tables, not on schemas or databases). When you know the asset When you already know which asset you want to retrieve, you can read it from Atlan using one of its identifiers.


Introductory walkthrough - Developer

We'll discuss these in more detail as part of updates, but for now you can think of them as: is a primary key for an asset: completely unique, but meaningless by itself is a business key for an asset: unique for a given kind of asset, and interpretable You can retrieve an asset using the static get() method on any asset type, providing the client and either the asset's GUID or qualifiedName. (Each asset type is its own unique class in the SDK.) You can retrieve an asset using the asset.get_by_guid() method on the Atlan client, providing both the type of asset you expect to retrieve and its GUID.


Introductory walkthrough - Developer

(Each asset type is its own unique class in the SDK.) You can also retrieve an asset using the asset.get_by_qualified_name() method on the Atlan client, providing the type of asset you expect to retrieve and its qualified_name. (Each asset type is its own unique class in the SDK.) You can retrieve an asset using the static get() method on any asset type, providing the client and either the asset's GUID or qualifiedName.


Introductory walkthrough - Developer

(Each asset type is its own unique class in the SDK.) You can retrieve an asset using the assets.GetByGuid() method on the Atlan client, providing both the type of asset you expect to retrieve and its GUID. (Each asset type is its own unique class in the SDK.) You can also retrieve an asset using the assets.GetByQualifiedName() method on the Atlan client, providing the type of asset you expect to retrieve and its qualifiedName.


Introductory walkthrough - Developer

(Each asset type is its own unique class in the SDK.) Note that the response is strongly typed: If you are retrieving a table, you will get a table back (as long as it exists). You do not need to figure out what properties or relationships exist on a table - the Table class defines them for for you already.


Introductory walkthrough - Developer

In any modern IDE, this means you have type-ahead support for retrieving the properties and relationships from the table variable. You can also refer to the types reference in this portal for full details of every kind of asset.


Introductory walkthrough - Developer

Retrieval by identifier can be more costly than you might expect Even though you are retrieving an asset by an identifier, this can be more costly than you might expect. Retrieving an asset in this way will: Retrieve all its properties and their values Retrieve all its relationships Imagine the asset you are retrieving has 100's or 1000's of these.


Introductory walkthrough - Developer

If you only care about its certificate and any owners, you will be retrieving far more information than you need. When you need to find it first For example, imagine you want to find all tables named MY_TABLE : You can then run the request using Execute().


Introductory walkthrough - Developer

For example, if you want to know the certificate of the asset you only need to tack that onto the query: Only this line differs from the original query. You can chain as many includeOnResults calls as you want to specify the properties and relationships you want to retrieve for matching assets.


Introductory walkthrough - Developer

Only this line differs from the original query. You can chain as many include_on_results calls as you want to specify the properties and relationships you want to retrieve for matching assets.


Introductory walkthrough - Developer

Only this line differs from the original query. You can chain as many includeOnResults calls as you want to specify the properties and relationships you want to retrieve for matching assets.


Introductory walkthrough - Developer

Only this line differs from the original query. You can include as many attributes in IncludeOnResults as you want to specify the properties and relationships you want to retrieve for matching assets.


Introductory walkthrough - Developer

Also gives the best performance If all you want to do is check or report on metadata, you should have a starting point from the information above. Or, now that you've found an asset of interest, maybe you want to update the asset with additional metadata?


Introductory walkthrough - Developer

Once again, before we jump to code, let's first understand some key concepts about how Atlan handles updates: Importance of identifiers Most operations on assets are upserts , that is, they could either create (insert) or update a given asset. How do you know which is going to happen?


Introductory walkthrough - Developer

To answer this question, you need to understand how Atlan uniquely identifies each asset. Recall earlier we discussed asset's different identifiers in Atlan.


Introductory walkthrough - Developer

Every asset in Atlan has at least the following two unique identifiers. These are both mandatory for every asset, so no asset can exist without these: Atlan uses globally-unique identifiers (GUIDs) to uniquely identify each asset, globally.


Introductory walkthrough - Developer

They look something like this: As the name implies, GUIDs are: Globally unique (across all systems). Generated in a way that makes it nearly impossible for anything else to ever generate that same ID.


Introductory walkthrough - Developer

2 Note that this means the GUID itself is not : Meaningful or capable of being interpreted in any way Atlan uses qualifiedName s to uniquely identify assets based on their characteristics. They look something like this: Qualified names are not : Globally unique (across all systems).


Introductory walkthrough - Developer

Instead, they are: Consistently constructed in a meaningful way, making it possible for them to be reconstructed. Note that this means the qualifiedName is: Meaningful and capable of being interpreted How these impact updates Since they are truly unique, operations that include a GUID will only update an asset, not create one.


Introductory walkthrough - Developer

Conversely, operations that take a qualifiedName can: Create an asset, if no exactly-matching qualifiedName is found in Atlan. Update an asset, if an exact-match for the qualifiedName is found in Atlan.


Introductory walkthrough - Developer

These operations also require a typeName , so that if creation does occur the correct type of asset is created. Unintended consequences of this behavior Be careful when using operations with only the qualifiedName.


Introductory walkthrough - Developer

You may end up creating assets when you were only expecting them to be updated or to fail if they did not already exist. This is particularly true when you do not give the exact, case-sensitive qualifiedName of an asset.


Introductory walkthrough - Developer

a/b/c/d is not the same as a/B/c/d when it comes to qualifiedName s. Perhaps this leaves you wondering: why have a qualifiedName at all?


Introductory walkthrough - Developer

The qualifiedName 's purpose is to identify what is a unique asset. Many different tools might all have information about that asset.


Introductory walkthrough - Developer

Having a common "identity" means that many different systems can each independently construct its identifier the same way. If a crawler gets table details from Snowflake it can upsert based on those identity characteristics in Atlan.


Introductory walkthrough - Developer

The crawler will not create duplicate tables every time it runs. This gives idempotency.


Introductory walkthrough - Developer

Looker knows the same identity characteristics for the Snowflake tables and columns. So if you get details from Looker about the tables it uses for reporting, you can link them together in lineage.


Introductory walkthrough - Developer

(Looker can construct the same identifier for the table as Snowflake itself.) These characteristics are not possible using GUIDs alone. Limit to changes only Now that you understand the nuances of identifiers, let's look at how you can update metadata in Atlan.


Introductory walkthrough - Developer

In general, you only need to send changes to Atlan. You do not need to send an entire asset each time you want to make changes to it.


Introductory walkthrough - Developer

For example, imagine you want to mark a table as certified but do not want to change anything else (its name, description, owner details, and so on): You can update an asset without first looking the asset up, if you know (can construct) its identifying qualifiedName. Using the updater() static method on any asset type, you pass in (typically) the qualifiedName and name of the asset.


Introductory walkthrough - Developer

This returns a builder onto which you can then chain any updates. You can then chain onto the returned builder as many updates as you want.


Introductory walkthrough - Developer

In this example, we change the certificate status to VERIFIED. At the end of your chain of updates, you need to build the builder (into an object, in-memory).


Introductory walkthrough - Developer

And then, finally, you need to .save() that object to persist those changes in Atlan (passing the client for the tenant you want to save it in). The response will contain details of the change: whether the asset was created, updated, or nothing happened because the asset already had those changes.


Introductory walkthrough - Developer

You can update an asset without first looking the asset up, if you know (can construct) its identifying qualified_name. Using the updater() class method on any asset type, you pass in (typically) the qualified_name and name of the asset.


Introductory walkthrough - Developer

You can then add onto the returned object as many updates as you want. In this example, we change the certificate status to VERIFIED.


Introductory walkthrough - Developer

And then, finally, you need to client.asset.save() that object to persist those changes in Atlan. The response will contain details of the change: whether the asset was created, updated, or nothing happened because the asset already had those changes.


Introductory walkthrough - Developer

You can update an asset without first looking the asset up, if you know (can construct) its identifying qualifiedName. Using the updater() static method on any asset type, you pass in (typically) the qualifiedName and name of the asset.


Introductory walkthrough - Developer


Introductory walkthrough - Developer

You can update an asset without first looking the asset up, if you know (can construct) its identifying qualifiedName. Using the Updater() method on any asset type, you pass in (typically) the qualifiedName and name of the asset.


Introductory walkthrough - Developer

This returns an object into which you can then place any updates. You can place into the returned object as many updates as you want.


Introductory walkthrough - Developer

In this example, we change the certificate status to VERIFIED. And then, finally, you need to .Save() that object to persist those changes in Atlan.


Introductory walkthrough - Developer

The response will contain details of the change: whether the asset was created, updated, or nothing happened because the asset already had those changes. Atlan will handle idempotency By sending only the changes you want to apply, Atlan can make idempotent updates.


Introductory walkthrough - Developer

Atlan will only attempt to update the asset with the changes you send. Atlan leaves any existing metadata on the asset as-is.


Introductory walkthrough - Developer

If the asset already has the metadata values you are sending, Atlan does nothing. It will not even update audit details like the last update timestamp, and is thus idempotent.


Introductory walkthrough - Developer

What if you want to make changes to many assets, as efficiently as possible? Start by initializing a batch.


Introductory walkthrough - Developer

Through this batch, we can automatically queue up and bulk-upsert assets — in this example, 20 at a time. Be sure to include any details you might need to make a decision about whether to update the asset or not (and what to update it with).


Introductory walkthrough - Developer

You must flush() the batch outside of any loop where you've added assets into it. This ensures any final remaining elements in the batch are still sent to Atlan, even if the batch is not "full".


Introductory walkthrough - Developer

Finally, from the batch you can retrieve the minimal details about any assets it created or updated. Start by initializing a batch.


Introductory walkthrough - Developer

You can then add() any updated objects directly into the batch you created earlier. The batch itself will handle saving these to Atlan when a sufficient number have been queued up (20, in this example).


Introductory walkthrough - Developer

Finally, from the batch you can retrieve the minimal details about any assets it created or updated. Where to go from here Common tasks Common operations on assets, that are available across all assets.


Introductory walkthrough - Developer

Discover actions Common operations on assets, that are available across all assets. Asset-specific Operations that are specific to certain assets.


Introductory walkthrough - Developer

Focus on a specific kind of asset Operations that are specific to certain assets. Focus on a specific kind of asset Governance structures Operations dealing with governance structures, rather than assets.


Introductory walkthrough - Developer

Manage governance structures Operations dealing with governance structures, rather than assets. Manage governance structures Samples Real code samples our customers use to solve particular use cases.


Introductory walkthrough - Developer

Review live samples Real code samples our customers use to solve particular use cases. Review live samples Events Delve deep into the details of the events Atlan triggers.


Introductory walkthrough - Developer

Learn more about events Delve deep into the details of the events Atlan triggers. Learn more about events Note that this is intentionally kept as simple as possible.


Introductory walkthrough - Developer

The walkthrough is not intended to be exhaustive. Where possible, we have cross-referenced other detailed examples elsewhere in the site.


Introductory walkthrough - Developer

↩ Note that this is intentionally kept as simple as possible. The walkthrough is not intended to be exhaustive.


Introductory walkthrough - Developer

Where possible, we have cross-referenced other detailed examples elsewhere in the site. ↩ There are orders of magnitude lower chances of GUIDs conflicting with each other than there are grains of sand on the planet.


Introductory walkthrough - Developer

(And generating them does not rely on a central ID-assigning registry.) ↩ There are orders of magnitude lower chances of GUIDs conflicting with each other than there are grains of sand on the planet. (And generating them does not rely on a central ID-assigning registry.) ↩


Introductory walkthrough - Developer

An introductory walkthrough You might also like our Atlan Platform Essentials certification. Not sure where to start?


Introductory walkthrough - Developer

Allow us to introduce Atlan development through example. 1 We strongly recommend using one of our SDKs to simplify the development process.


Introductory walkthrough - Developer

As a first step, set one up: The SDK is available on Maven Central , ready to be included in your project: Include the latest version of the Java SDK in your project as a dependency. You can also give a specific version instead of the + , if you'd like.


Introductory walkthrough - Developer

The Java SDK uses slf4j for logging purposes. You can include logback as a simple binding mechanism to send any logging information out to your console (standard out).


Introductory walkthrough - Developer

Provide two values to create an Atlan client: Provide your Atlan tenant URL as the first parameter. You can also read the value from an environment variable, if you leave out both parameters.


Introductory walkthrough - Developer

Provide your API token as the second parameter. You can also read the value from another environment variable, by leaving out this parameter.


Introductory walkthrough - Developer

You can then start writing some actual code to run within a static main method. (We'll show some examples of this further below.) Once the block is complete, any resources held by the client (i.e.


Introductory walkthrough - Developer

for caching) will be automatically released. Set up logging for SDK You can also checkout to the advanced configuration section of the SDK to learn about how to set up logging.


Introductory walkthrough - Developer

The SDK is available on PyPI. You can use pip to install it as follows: Provide two values to create an Atlan client: Provide your Atlan tenant URL to the base_url parameter.


Introductory walkthrough - Developer

(You can also do this through environment variables .) Provide your API token to the api_key parameter. (You can also do this through environment variables .) Set up logging for SDK You can also checkout to the advanced configuration section of the SDK to learn about how to set up logging.


Introductory walkthrough - Developer

The SDK is available on Maven Central , ready to be included in your project: Include the latest version of the Java SDK in your project as a dependency. You can also give a specific version instead of the + , if you'd like.


Introductory walkthrough - Developer

The Java SDK uses slf4j for logging purposes. You can include slf4j-simple as a simple binding mechanism to send any logging information out to your console (standard out), along with the kotlin-logging-jvm microutil.


Introductory walkthrough - Developer


Introductory walkthrough - Developer

The SDK is available on GitHub , ready to be included in your project: Provide two values to set up connectivity to Atlan: Provide your Atlan tenant URL to the assets.Context() method. If you prefer using the value from an environment variable, you can use assets.NewContext() without any parameters.


Introductory walkthrough - Developer

Provide your API token as the second parameter to the assets.Context() method. (Or again, have it picked up automatically by the assets.NewContext() method.) Set up logging for SDK You can also checkout to the advanced configuration section of the SDK to learn about how to set up logging.


Introductory walkthrough - Developer

Don't forget to give permissions If you want to be able to access existing metadata with an API token, don't forget that you need to assign one or more personas to the API token that grant it access to metadata. Now that you have an SDK installed and configured, you are ready to code!


Introductory walkthrough - Developer

Before we jump straight to code, though, let's first introduce some key concepts in Atlan: What is an asset? In Atlan, we refer to all objects that provide context to your data as assets.


Introductory walkthrough - Developer

Each type of asset in Atlan has a set of: Properties , such as: Certificates Announcements Properties , such as: Relationships to other assets, such as: Schema child tables Table parent schema Table child columns Column parent table Relationships to other assets, such as: Schema child tables Table parent schema Table child columns Column parent table In an object-oriented programming sense, think of an asset as an instance of a class. The structure of an asset (the class itself, in this analogy) is defined by something called a type definition , but that's for another day.


Introductory walkthrough - Developer

So as you can see: There are many different kinds of assets: tables, columns, schemas, databases, business intelligence dashboards, reports, and so on. Assets inter-relate with each other: a table has a parent schema and child columns, a schema has a parent database and child tables, and so on.


Introductory walkthrough - Developer

Different kinds of assets have some common properties (like certificates) and other properties that are unique to that kind of asset (like a columnCount that only exists on tables, not on schemas or databases). When you know the asset When you already know which asset you want to retrieve, you can read it from Atlan using one of its identifiers.


Introductory walkthrough - Developer

We'll discuss these in more detail as part of updates, but for now you can think of them as: is a primary key for an asset: completely unique, but meaningless by itself is a business key for an asset: unique for a given kind of asset, and interpretable You can retrieve an asset using the static get() method on any asset type, providing the client and either the asset's GUID or qualifiedName. (Each asset type is its own unique class in the SDK.) You can retrieve an asset using the asset.get_by_guid() method on the Atlan client, providing both the type of asset you expect to retrieve and its GUID.


Introductory walkthrough - Developer

(Each asset type is its own unique class in the SDK.) You can also retrieve an asset using the asset.get_by_qualified_name() method on the Atlan client, providing the type of asset you expect to retrieve and its qualified_name. (Each asset type is its own unique class in the SDK.) You can retrieve an asset using the static get() method on any asset type, providing the client and either the asset's GUID or qualifiedName.


Introductory walkthrough - Developer

(Each asset type is its own unique class in the SDK.) You can retrieve an asset using the assets.GetByGuid() method on the Atlan client, providing both the type of asset you expect to retrieve and its GUID. (Each asset type is its own unique class in the SDK.) You can also retrieve an asset using the assets.GetByQualifiedName() method on the Atlan client, providing the type of asset you expect to retrieve and its qualifiedName.


Introductory walkthrough - Developer

(Each asset type is its own unique class in the SDK.) Note that the response is strongly typed: If you are retrieving a table, you will get a table back (as long as it exists). You do not need to figure out what properties or relationships exist on a table - the Table class defines them for for you already.


Introductory walkthrough - Developer

In any modern IDE, this means you have type-ahead support for retrieving the properties and relationships from the table variable. You can also refer to the types reference in this portal for full details of every kind of asset.


Introductory walkthrough - Developer

Retrieval by identifier can be more costly than you might expect Even though you are retrieving an asset by an identifier, this can be more costly than you might expect. Retrieving an asset in this way will: Retrieve all its properties and their values Retrieve all its relationships Imagine the asset you are retrieving has 100's or 1000's of these.


Introductory walkthrough - Developer

If you only care about its certificate and any owners, you will be retrieving far more information than you need. When you need to find it first For example, imagine you want to find all tables named MY_TABLE : You can then run the request using Execute().


Introductory walkthrough - Developer

For example, if you want to know the certificate of the asset you only need to tack that onto the query: Only this line differs from the original query. You can chain as many includeOnResults calls as you want to specify the properties and relationships you want to retrieve for matching assets.


Introductory walkthrough - Developer

Only this line differs from the original query. You can chain as many include_on_results calls as you want to specify the properties and relationships you want to retrieve for matching assets.


Introductory walkthrough - Developer

Only this line differs from the original query. You can chain as many includeOnResults calls as you want to specify the properties and relationships you want to retrieve for matching assets.


Introductory walkthrough - Developer

Only this line differs from the original query. You can include as many attributes in IncludeOnResults as you want to specify the properties and relationships you want to retrieve for matching assets.


Introductory walkthrough - Developer

Also gives the best performance If all you want to do is check or report on metadata, you should have a starting point from the information above. Or, now that you've found an asset of interest, maybe you want to update the asset with additional metadata?


Introductory walkthrough - Developer

Once again, before we jump to code, let's first understand some key concepts about how Atlan handles updates: Importance of identifiers Most operations on assets are upserts , that is, they could either create (insert) or update a given asset. How do you know which is going to happen?


Introductory walkthrough - Developer

To answer this question, you need to understand how Atlan uniquely identifies each asset. Recall earlier we discussed asset's different identifiers in Atlan.


Introductory walkthrough - Developer

Every asset in Atlan has at least the following two unique identifiers. These are both mandatory for every asset, so no asset can exist without these: Atlan uses globally-unique identifiers (GUIDs) to uniquely identify each asset, globally.


Introductory walkthrough - Developer

They look something like this: As the name implies, GUIDs are: Globally unique (across all systems). Generated in a way that makes it nearly impossible for anything else to ever generate that same ID.


Introductory walkthrough - Developer

2 Note that this means the GUID itself is not : Meaningful or capable of being interpreted in any way Atlan uses qualifiedName s to uniquely identify assets based on their characteristics. They look something like this: Qualified names are not : Globally unique (across all systems).


Introductory walkthrough - Developer

Instead, they are: Consistently constructed in a meaningful way, making it possible for them to be reconstructed. Note that this means the qualifiedName is: Meaningful and capable of being interpreted How these impact updates Since they are truly unique, operations that include a GUID will only update an asset, not create one.


Introductory walkthrough - Developer

Conversely, operations that take a qualifiedName can: Create an asset, if no exactly-matching qualifiedName is found in Atlan. Update an asset, if an exact-match for the qualifiedName is found in Atlan.


Introductory walkthrough - Developer

These operations also require a typeName , so that if creation does occur the correct type of asset is created. Unintended consequences of this behavior Be careful when using operations with only the qualifiedName.


Introductory walkthrough - Developer

You may end up creating assets when you were only expecting them to be updated or to fail if they did not already exist. This is particularly true when you do not give the exact, case-sensitive qualifiedName of an asset.


Introductory walkthrough - Developer

a/b/c/d is not the same as a/B/c/d when it comes to qualifiedName s. Perhaps this leaves you wondering: why have a qualifiedName at all?


Introductory walkthrough - Developer

The qualifiedName 's purpose is to identify what is a unique asset. Many different tools might all have information about that asset.


Introductory walkthrough - Developer

Having a common "identity" means that many different systems can each independently construct its identifier the same way. If a crawler gets table details from Snowflake it can upsert based on those identity characteristics in Atlan.


Introductory walkthrough - Developer

The crawler will not create duplicate tables every time it runs. This gives idempotency.


Introductory walkthrough - Developer

Looker knows the same identity characteristics for the Snowflake tables and columns. So if you get details from Looker about the tables it uses for reporting, you can link them together in lineage.


Introductory walkthrough - Developer

(Looker can construct the same identifier for the table as Snowflake itself.) These characteristics are not possible using GUIDs alone. Limit to changes only Now that you understand the nuances of identifiers, let's look at how you can update metadata in Atlan.


Introductory walkthrough - Developer

In general, you only need to send changes to Atlan. You do not need to send an entire asset each time you want to make changes to it.


Introductory walkthrough - Developer

For example, imagine you want to mark a table as certified but do not want to change anything else (its name, description, owner details, and so on): You can update an asset without first looking the asset up, if you know (can construct) its identifying qualifiedName. Using the updater() static method on any asset type, you pass in (typically) the qualifiedName and name of the asset.


Introductory walkthrough - Developer

This returns a builder onto which you can then chain any updates. You can then chain onto the returned builder as many updates as you want.


Introductory walkthrough - Developer

In this example, we change the certificate status to VERIFIED. At the end of your chain of updates, you need to build the builder (into an object, in-memory).


Introductory walkthrough - Developer

And then, finally, you need to .save() that object to persist those changes in Atlan (passing the client for the tenant you want to save it in). The response will contain details of the change: whether the asset was created, updated, or nothing happened because the asset already had those changes.


Introductory walkthrough - Developer

You can update an asset without first looking the asset up, if you know (can construct) its identifying qualified_name. Using the updater() class method on any asset type, you pass in (typically) the qualified_name and name of the asset.


Introductory walkthrough - Developer

You can then add onto the returned object as many updates as you want. In this example, we change the certificate status to VERIFIED.


Introductory walkthrough - Developer

And then, finally, you need to client.asset.save() that object to persist those changes in Atlan. The response will contain details of the change: whether the asset was created, updated, or nothing happened because the asset already had those changes.


Introductory walkthrough - Developer

You can update an asset without first looking the asset up, if you know (can construct) its identifying qualifiedName. Using the updater() static method on any asset type, you pass in (typically) the qualifiedName and name of the asset.


Introductory walkthrough - Developer


Introductory walkthrough - Developer

You can update an asset without first looking the asset up, if you know (can construct) its identifying qualifiedName. Using the Updater() method on any asset type, you pass in (typically) the qualifiedName and name of the asset.


Introductory walkthrough - Developer

This returns an object into which you can then place any updates. You can place into the returned object as many updates as you want.


Introductory walkthrough - Developer

In this example, we change the certificate status to VERIFIED. And then, finally, you need to .Save() that object to persist those changes in Atlan.


Introductory walkthrough - Developer

The response will contain details of the change: whether the asset was created, updated, or nothing happened because the asset already had those changes. Atlan will handle idempotency By sending only the changes you want to apply, Atlan can make idempotent updates.


Introductory walkthrough - Developer

Atlan will only attempt to update the asset with the changes you send. Atlan leaves any existing metadata on the asset as-is.


Introductory walkthrough - Developer

If the asset already has the metadata values you are sending, Atlan does nothing. It will not even update audit details like the last update timestamp, and is thus idempotent.


Introductory walkthrough - Developer

What if you want to make changes to many assets, as efficiently as possible? Start by initializing a batch.


Introductory walkthrough - Developer

Through this batch, we can automatically queue up and bulk-upsert assets — in this example, 20 at a time. Be sure to include any details you might need to make a decision about whether to update the asset or not (and what to update it with).


Introductory walkthrough - Developer

You must flush() the batch outside of any loop where you've added assets into it. This ensures any final remaining elements in the batch are still sent to Atlan, even if the batch is not "full".


Introductory walkthrough - Developer

Finally, from the batch you can retrieve the minimal details about any assets it created or updated. Start by initializing a batch.


Introductory walkthrough - Developer

You can then add() any updated objects directly into the batch you created earlier. The batch itself will handle saving these to Atlan when a sufficient number have been queued up (20, in this example).


Introductory walkthrough - Developer

Finally, from the batch you can retrieve the minimal details about any assets it created or updated. Where to go from here Common tasks Common operations on assets, that are available across all assets.


Introductory walkthrough - Developer

Discover actions Common operations on assets, that are available across all assets. Asset-specific Operations that are specific to certain assets.


Introductory walkthrough - Developer

Focus on a specific kind of asset Operations that are specific to certain assets. Focus on a specific kind of asset Governance structures Operations dealing with governance structures, rather than assets.


Introductory walkthrough - Developer

Manage governance structures Operations dealing with governance structures, rather than assets. Manage governance structures Samples Real code samples our customers use to solve particular use cases.


Introductory walkthrough - Developer

Review live samples Real code samples our customers use to solve particular use cases. Review live samples Events Delve deep into the details of the events Atlan triggers.


Introductory walkthrough - Developer

Learn more about events Delve deep into the details of the events Atlan triggers. Learn more about events Note that this is intentionally kept as simple as possible.


Introductory walkthrough - Developer

The walkthrough is not intended to be exhaustive. Where possible, we have cross-referenced other detailed examples elsewhere in the site.


Introductory walkthrough - Developer

↩ Note that this is intentionally kept as simple as possible. The walkthrough is not intended to be exhaustive.


Introductory walkthrough - Developer

Where possible, we have cross-referenced other detailed examples elsewhere in the site. ↩ There are orders of magnitude lower chances of GUIDs conflicting with each other than there are grains of sand on the planet.


Introductory walkthrough - Developer

(And generating them does not rely on a central ID-assigning registry.) ↩ There are orders of magnitude lower chances of GUIDs conflicting with each other than there are grains of sand on the planet. (And generating them does not rely on a central ID-assigning registry.) ↩


Introductory walkthrough - Developer

An introductory walkthrough You might also like our Atlan Platform Essentials certification. Not sure where to start?


Introductory walkthrough - Developer

Allow us to introduce Atlan development through example. 1 We strongly recommend using one of our SDKs to simplify the development process.


Introductory walkthrough - Developer

As a first step, set one up: The SDK is available on Maven Central , ready to be included in your project: Include the latest version of the Java SDK in your project as a dependency. You can also give a specific version instead of the + , if you'd like.


Introductory walkthrough - Developer

The Java SDK uses slf4j for logging purposes. You can include logback as a simple binding mechanism to send any logging information out to your console (standard out).


Introductory walkthrough - Developer

Provide two values to create an Atlan client: Provide your Atlan tenant URL as the first parameter. You can also read the value from an environment variable, if you leave out both parameters.


Introductory walkthrough - Developer

Provide your API token as the second parameter. You can also read the value from another environment variable, by leaving out this parameter.


Introductory walkthrough - Developer

You can then start writing some actual code to run within a static main method. (We'll show some examples of this further below.) Once the block is complete, any resources held by the client (i.e.


Introductory walkthrough - Developer

for caching) will be automatically released. Set up logging for SDK You can also checkout to the advanced configuration section of the SDK to learn about how to set up logging.


Introductory walkthrough - Developer

The SDK is available on PyPI. You can use pip to install it as follows: Provide two values to create an Atlan client: Provide your Atlan tenant URL to the base_url parameter.


Introductory walkthrough - Developer

(You can also do this through environment variables .) Provide your API token to the api_key parameter. (You can also do this through environment variables .) Set up logging for SDK You can also checkout to the advanced configuration section of the SDK to learn about how to set up logging.


Introductory walkthrough - Developer

The SDK is available on Maven Central , ready to be included in your project: Include the latest version of the Java SDK in your project as a dependency. You can also give a specific version instead of the + , if you'd like.


Introductory walkthrough - Developer

The Java SDK uses slf4j for logging purposes. You can include slf4j-simple as a simple binding mechanism to send any logging information out to your console (standard out), along with the kotlin-logging-jvm microutil.


Introductory walkthrough - Developer


Introductory walkthrough - Developer

The SDK is available on GitHub , ready to be included in your project: Provide two values to set up connectivity to Atlan: Provide your Atlan tenant URL to the assets.Context() method. If you prefer using the value from an environment variable, you can use assets.NewContext() without any parameters.


Introductory walkthrough - Developer

Provide your API token as the second parameter to the assets.Context() method. (Or again, have it picked up automatically by the assets.NewContext() method.) Set up logging for SDK You can also checkout to the advanced configuration section of the SDK to learn about how to set up logging.


Introductory walkthrough - Developer

Don't forget to give permissions If you want to be able to access existing metadata with an API token, don't forget that you need to assign one or more personas to the API token that grant it access to metadata. Now that you have an SDK installed and configured, you are ready to code!


Introductory walkthrough - Developer

Before we jump straight to code, though, let's first introduce some key concepts in Atlan: What is an asset? In Atlan, we refer to all objects that provide context to your data as assets.


Introductory walkthrough - Developer

Each type of asset in Atlan has a set of: Properties , such as: Certificates Announcements Properties , such as: Relationships to other assets, such as: Schema child tables Table parent schema Table child columns Column parent table Relationships to other assets, such as: Schema child tables Table parent schema Table child columns Column parent table In an object-oriented programming sense, think of an asset as an instance of a class. The structure of an asset (the class itself, in this analogy) is defined by something called a type definition , but that's for another day.


Introductory walkthrough - Developer

So as you can see: There are many different kinds of assets: tables, columns, schemas, databases, business intelligence dashboards, reports, and so on. Assets inter-relate with each other: a table has a parent schema and child columns, a schema has a parent database and child tables, and so on.


Introductory walkthrough - Developer

Different kinds of assets have some common properties (like certificates) and other properties that are unique to that kind of asset (like a columnCount that only exists on tables, not on schemas or databases). When you know the asset When you already know which asset you want to retrieve, you can read it from Atlan using one of its identifiers.


Introductory walkthrough - Developer

We'll discuss these in more detail as part of updates, but for now you can think of them as: is a primary key for an asset: completely unique, but meaningless by itself is a business key for an asset: unique for a given kind of asset, and interpretable You can retrieve an asset using the static get() method on any asset type, providing the client and either the asset's GUID or qualifiedName. (Each asset type is its own unique class in the SDK.) You can retrieve an asset using the asset.get_by_guid() method on the Atlan client, providing both the type of asset you expect to retrieve and its GUID.


Introductory walkthrough - Developer

(Each asset type is its own unique class in the SDK.) You can also retrieve an asset using the asset.get_by_qualified_name() method on the Atlan client, providing the type of asset you expect to retrieve and its qualified_name. (Each asset type is its own unique class in the SDK.) You can retrieve an asset using the static get() method on any asset type, providing the client and either the asset's GUID or qualifiedName.


Introductory walkthrough - Developer

(Each asset type is its own unique class in the SDK.) You can retrieve an asset using the assets.GetByGuid() method on the Atlan client, providing both the type of asset you expect to retrieve and its GUID. (Each asset type is its own unique class in the SDK.) You can also retrieve an asset using the assets.GetByQualifiedName() method on the Atlan client, providing the type of asset you expect to retrieve and its qualifiedName.


Introductory walkthrough - Developer

(Each asset type is its own unique class in the SDK.) Note that the response is strongly typed: If you are retrieving a table, you will get a table back (as long as it exists). You do not need to figure out what properties or relationships exist on a table - the Table class defines them for for you already.


Introductory walkthrough - Developer

In any modern IDE, this means you have type-ahead support for retrieving the properties and relationships from the table variable. You can also refer to the types reference in this portal for full details of every kind of asset.


Introductory walkthrough - Developer

Retrieval by identifier can be more costly than you might expect Even though you are retrieving an asset by an identifier, this can be more costly than you might expect. Retrieving an asset in this way will: Retrieve all its properties and their values Retrieve all its relationships Imagine the asset you are retrieving has 100's or 1000's of these.


Introductory walkthrough - Developer

If you only care about its certificate and any owners, you will be retrieving far more information than you need. When you need to find it first For example, imagine you want to find all tables named MY_TABLE : You can then run the request using Execute().


Introductory walkthrough - Developer

For example, if you want to know the certificate of the asset you only need to tack that onto the query: Only this line differs from the original query. You can chain as many includeOnResults calls as you want to specify the properties and relationships you want to retrieve for matching assets.


Introductory walkthrough - Developer

Only this line differs from the original query. You can chain as many include_on_results calls as you want to specify the properties and relationships you want to retrieve for matching assets.


Introductory walkthrough - Developer

Only this line differs from the original query. You can chain as many includeOnResults calls as you want to specify the properties and relationships you want to retrieve for matching assets.


Introductory walkthrough - Developer

Only this line differs from the original query. You can include as many attributes in IncludeOnResults as you want to specify the properties and relationships you want to retrieve for matching assets.


Introductory walkthrough - Developer

Also gives the best performance If all you want to do is check or report on metadata, you should have a starting point from the information above. Or, now that you've found an asset of interest, maybe you want to update the asset with additional metadata?


Introductory walkthrough - Developer

Once again, before we jump to code, let's first understand some key concepts about how Atlan handles updates: Importance of identifiers Most operations on assets are upserts , that is, they could either create (insert) or update a given asset. How do you know which is going to happen?


Introductory walkthrough - Developer

To answer this question, you need to understand how Atlan uniquely identifies each asset. Recall earlier we discussed asset's different identifiers in Atlan.


Introductory walkthrough - Developer

Every asset in Atlan has at least the following two unique identifiers. These are both mandatory for every asset, so no asset can exist without these: Atlan uses globally-unique identifiers (GUIDs) to uniquely identify each asset, globally.


Introductory walkthrough - Developer

They look something like this: As the name implies, GUIDs are: Globally unique (across all systems). Generated in a way that makes it nearly impossible for anything else to ever generate that same ID.


Introductory walkthrough - Developer

2 Note that this means the GUID itself is not : Meaningful or capable of being interpreted in any way Atlan uses qualifiedName s to uniquely identify assets based on their characteristics. They look something like this: Qualified names are not : Globally unique (across all systems).


Introductory walkthrough - Developer

Instead, they are: Consistently constructed in a meaningful way, making it possible for them to be reconstructed. Note that this means the qualifiedName is: Meaningful and capable of being interpreted How these impact updates Since they are truly unique, operations that include a GUID will only update an asset, not create one.


Introductory walkthrough - Developer

Conversely, operations that take a qualifiedName can: Create an asset, if no exactly-matching qualifiedName is found in Atlan. Update an asset, if an exact-match for the qualifiedName is found in Atlan.


Introductory walkthrough - Developer

These operations also require a typeName , so that if creation does occur the correct type of asset is created. Unintended consequences of this behavior Be careful when using operations with only the qualifiedName.


Introductory walkthrough - Developer

You may end up creating assets when you were only expecting them to be updated or to fail if they did not already exist. This is particularly true when you do not give the exact, case-sensitive qualifiedName of an asset.


Introductory walkthrough - Developer

a/b/c/d is not the same as a/B/c/d when it comes to qualifiedName s. Perhaps this leaves you wondering: why have a qualifiedName at all?


Introductory walkthrough - Developer

The qualifiedName 's purpose is to identify what is a unique asset. Many different tools might all have information about that asset.


Introductory walkthrough - Developer

Having a common "identity" means that many different systems can each independently construct its identifier the same way. If a crawler gets table details from Snowflake it can upsert based on those identity characteristics in Atlan.


Introductory walkthrough - Developer

The crawler will not create duplicate tables every time it runs. This gives idempotency.


Introductory walkthrough - Developer

Looker knows the same identity characteristics for the Snowflake tables and columns. So if you get details from Looker about the tables it uses for reporting, you can link them together in lineage.


Introductory walkthrough - Developer

(Looker can construct the same identifier for the table as Snowflake itself.) These characteristics are not possible using GUIDs alone. Limit to changes only Now that you understand the nuances of identifiers, let's look at how you can update metadata in Atlan.


Introductory walkthrough - Developer

In general, you only need to send changes to Atlan. You do not need to send an entire asset each time you want to make changes to it.


Introductory walkthrough - Developer

For example, imagine you want to mark a table as certified but do not want to change anything else (its name, description, owner details, and so on): You can update an asset without first looking the asset up, if you know (can construct) its identifying qualifiedName. Using the updater() static method on any asset type, you pass in (typically) the qualifiedName and name of the asset.


Introductory walkthrough - Developer

This returns a builder onto which you can then chain any updates. You can then chain onto the returned builder as many updates as you want.


Introductory walkthrough - Developer

In this example, we change the certificate status to VERIFIED. At the end of your chain of updates, you need to build the builder (into an object, in-memory).


Introductory walkthrough - Developer

And then, finally, you need to .save() that object to persist those changes in Atlan (passing the client for the tenant you want to save it in). The response will contain details of the change: whether the asset was created, updated, or nothing happened because the asset already had those changes.


Introductory walkthrough - Developer

You can update an asset without first looking the asset up, if you know (can construct) its identifying qualified_name. Using the updater() class method on any asset type, you pass in (typically) the qualified_name and name of the asset.


Introductory walkthrough - Developer

You can then add onto the returned object as many updates as you want. In this example, we change the certificate status to VERIFIED.


Introductory walkthrough - Developer

And then, finally, you need to client.asset.save() that object to persist those changes in Atlan. The response will contain details of the change: whether the asset was created, updated, or nothing happened because the asset already had those changes.


Introductory walkthrough - Developer

You can update an asset without first looking the asset up, if you know (can construct) its identifying qualifiedName. Using the updater() static method on any asset type, you pass in (typically) the qualifiedName and name of the asset.


Introductory walkthrough - Developer


Introductory walkthrough - Developer

You can update an asset without first looking the asset up, if you know (can construct) its identifying qualifiedName. Using the Updater() method on any asset type, you pass in (typically) the qualifiedName and name of the asset.


Introductory walkthrough - Developer

This returns an object into which you can then place any updates. You can place into the returned object as many updates as you want.


Introductory walkthrough - Developer

In this example, we change the certificate status to VERIFIED. And then, finally, you need to .Save() that object to persist those changes in Atlan.


Introductory walkthrough - Developer

The response will contain details of the change: whether the asset was created, updated, or nothing happened because the asset already had those changes. Atlan will handle idempotency By sending only the changes you want to apply, Atlan can make idempotent updates.


Introductory walkthrough - Developer

Atlan will only attempt to update the asset with the changes you send. Atlan leaves any existing metadata on the asset as-is.


Introductory walkthrough - Developer

If the asset already has the metadata values you are sending, Atlan does nothing. It will not even update audit details like the last update timestamp, and is thus idempotent.


Introductory walkthrough - Developer

What if you want to make changes to many assets, as efficiently as possible? Start by initializing a batch.


Introductory walkthrough - Developer

Through this batch, we can automatically queue up and bulk-upsert assets — in this example, 20 at a time. Be sure to include any details you might need to make a decision about whether to update the asset or not (and what to update it with).


Introductory walkthrough - Developer

You must flush() the batch outside of any loop where you've added assets into it. This ensures any final remaining elements in the batch are still sent to Atlan, even if the batch is not "full".


Introductory walkthrough - Developer

Finally, from the batch you can retrieve the minimal details about any assets it created or updated. Start by initializing a batch.


Introductory walkthrough - Developer

You can then add() any updated objects directly into the batch you created earlier. The batch itself will handle saving these to Atlan when a sufficient number have been queued up (20, in this example).


Introductory walkthrough - Developer

Finally, from the batch you can retrieve the minimal details about any assets it created or updated. Where to go from here Common tasks Common operations on assets, that are available across all assets.


Introductory walkthrough - Developer

Discover actions Common operations on assets, that are available across all assets. Asset-specific Operations that are specific to certain assets.


Introductory walkthrough - Developer

Focus on a specific kind of asset Operations that are specific to certain assets. Focus on a specific kind of asset Governance structures Operations dealing with governance structures, rather than assets.


Introductory walkthrough - Developer

Manage governance structures Operations dealing with governance structures, rather than assets. Manage governance structures Samples Real code samples our customers use to solve particular use cases.


Introductory walkthrough - Developer

Review live samples Real code samples our customers use to solve particular use cases. Review live samples Events Delve deep into the details of the events Atlan triggers.


Introductory walkthrough - Developer

Learn more about events Delve deep into the details of the events Atlan triggers. Learn more about events Note that this is intentionally kept as simple as possible.


Introductory walkthrough - Developer

The walkthrough is not intended to be exhaustive. Where possible, we have cross-referenced other detailed examples elsewhere in the site.


Introductory walkthrough - Developer

↩ Note that this is intentionally kept as simple as possible. The walkthrough is not intended to be exhaustive.


Introductory walkthrough - Developer

Where possible, we have cross-referenced other detailed examples elsewhere in the site. ↩ There are orders of magnitude lower chances of GUIDs conflicting with each other than there are grains of sand on the planet.


Introductory walkthrough - Developer

(And generating them does not rely on a central ID-assigning registry.) ↩ There are orders of magnitude lower chances of GUIDs conflicting with each other than there are grains of sand on the planet. (And generating them does not rely on a central ID-assigning registry.) ↩


Introductory walkthrough - Developer

An introductory walkthrough You might also like our Atlan Platform Essentials certification. Not sure where to start?


Introductory walkthrough - Developer

Allow us to introduce Atlan development through example. 1 We strongly recommend using one of our SDKs to simplify the development process.


Introductory walkthrough - Developer

As a first step, set one up: The SDK is available on Maven Central , ready to be included in your project: Include the latest version of the Java SDK in your project as a dependency. You can also give a specific version instead of the + , if you'd like.


Introductory walkthrough - Developer

The Java SDK uses slf4j for logging purposes. You can include logback as a simple binding mechanism to send any logging information out to your console (standard out).


Introductory walkthrough - Developer

Provide two values to create an Atlan client: Provide your Atlan tenant URL as the first parameter. You can also read the value from an environment variable, if you leave out both parameters.


Introductory walkthrough - Developer

Provide your API token as the second parameter. You can also read the value from another environment variable, by leaving out this parameter.


Introductory walkthrough - Developer

You can then start writing some actual code to run within a static main method. (We'll show some examples of this further below.) Once the block is complete, any resources held by the client (i.e.


Introductory walkthrough - Developer

for caching) will be automatically released. Set up logging for SDK You can also checkout to the advanced configuration section of the SDK to learn about how to set up logging.


Introductory walkthrough - Developer

The SDK is available on PyPI. You can use pip to install it as follows: Provide two values to create an Atlan client: Provide your Atlan tenant URL to the base_url parameter.


Introductory walkthrough - Developer

(You can also do this through environment variables .) Provide your API token to the api_key parameter. (You can also do this through environment variables .) Set up logging for SDK You can also checkout to the advanced configuration section of the SDK to learn about how to set up logging.


Introductory walkthrough - Developer

The SDK is available on Maven Central , ready to be included in your project: Include the latest version of the Java SDK in your project as a dependency. You can also give a specific version instead of the + , if you'd like.


Introductory walkthrough - Developer

The Java SDK uses slf4j for logging purposes. You can include slf4j-simple as a simple binding mechanism to send any logging information out to your console (standard out), along with the kotlin-logging-jvm microutil.


Introductory walkthrough - Developer


Introductory walkthrough - Developer

The SDK is available on GitHub , ready to be included in your project: Provide two values to set up connectivity to Atlan: Provide your Atlan tenant URL to the assets.Context() method. If you prefer using the value from an environment variable, you can use assets.NewContext() without any parameters.


Introductory walkthrough - Developer

Provide your API token as the second parameter to the assets.Context() method. (Or again, have it picked up automatically by the assets.NewContext() method.) Set up logging for SDK You can also checkout to the advanced configuration section of the SDK to learn about how to set up logging.


Introductory walkthrough - Developer

Don't forget to give permissions If you want to be able to access existing metadata with an API token, don't forget that you need to assign one or more personas to the API token that grant it access to metadata. Now that you have an SDK installed and configured, you are ready to code!


Introductory walkthrough - Developer

Before we jump straight to code, though, let's first introduce some key concepts in Atlan: What is an asset? In Atlan, we refer to all objects that provide context to your data as assets.


Introductory walkthrough - Developer

Each type of asset in Atlan has a set of: Properties , such as: Certificates Announcements Properties , such as: Relationships to other assets, such as: Schema child tables Table parent schema Table child columns Column parent table Relationships to other assets, such as: Schema child tables Table parent schema Table child columns Column parent table In an object-oriented programming sense, think of an asset as an instance of a class. The structure of an asset (the class itself, in this analogy) is defined by something called a type definition , but that's for another day.


Introductory walkthrough - Developer

So as you can see: There are many different kinds of assets: tables, columns, schemas, databases, business intelligence dashboards, reports, and so on. Assets inter-relate with each other: a table has a parent schema and child columns, a schema has a parent database and child tables, and so on.


Introductory walkthrough - Developer

Different kinds of assets have some common properties (like certificates) and other properties that are unique to that kind of asset (like a columnCount that only exists on tables, not on schemas or databases). When you know the asset When you already know which asset you want to retrieve, you can read it from Atlan using one of its identifiers.


Introductory walkthrough - Developer

We'll discuss these in more detail as part of updates, but for now you can think of them as: is a primary key for an asset: completely unique, but meaningless by itself is a business key for an asset: unique for a given kind of asset, and interpretable You can retrieve an asset using the static get() method on any asset type, providing the client and either the asset's GUID or qualifiedName. (Each asset type is its own unique class in the SDK.) You can retrieve an asset using the asset.get_by_guid() method on the Atlan client, providing both the type of asset you expect to retrieve and its GUID.


Introductory walkthrough - Developer

(Each asset type is its own unique class in the SDK.) You can also retrieve an asset using the asset.get_by_qualified_name() method on the Atlan client, providing the type of asset you expect to retrieve and its qualified_name. (Each asset type is its own unique class in the SDK.) You can retrieve an asset using the static get() method on any asset type, providing the client and either the asset's GUID or qualifiedName.


Introductory walkthrough - Developer

(Each asset type is its own unique class in the SDK.) You can retrieve an asset using the assets.GetByGuid() method on the Atlan client, providing both the type of asset you expect to retrieve and its GUID. (Each asset type is its own unique class in the SDK.) You can also retrieve an asset using the assets.GetByQualifiedName() method on the Atlan client, providing the type of asset you expect to retrieve and its qualifiedName.


Introductory walkthrough - Developer

(Each asset type is its own unique class in the SDK.) Note that the response is strongly typed: If you are retrieving a table, you will get a table back (as long as it exists). You do not need to figure out what properties or relationships exist on a table - the Table class defines them for for you already.


Introductory walkthrough - Developer

In any modern IDE, this means you have type-ahead support for retrieving the properties and relationships from the table variable. You can also refer to the types reference in this portal for full details of every kind of asset.


Introductory walkthrough - Developer

Retrieval by identifier can be more costly than you might expect Even though you are retrieving an asset by an identifier, this can be more costly than you might expect. Retrieving an asset in this way will: Retrieve all its properties and their values Retrieve all its relationships Imagine the asset you are retrieving has 100's or 1000's of these.


Introductory walkthrough - Developer

If you only care about its certificate and any owners, you will be retrieving far more information than you need. When you need to find it first For example, imagine you want to find all tables named MY_TABLE : You can then run the request using Execute().


Introductory walkthrough - Developer

For example, if you want to know the certificate of the asset you only need to tack that onto the query: Only this line differs from the original query. You can chain as many includeOnResults calls as you want to specify the properties and relationships you want to retrieve for matching assets.


Introductory walkthrough - Developer

Only this line differs from the original query. You can chain as many include_on_results calls as you want to specify the properties and relationships you want to retrieve for matching assets.


Introductory walkthrough - Developer

Only this line differs from the original query. You can chain as many includeOnResults calls as you want to specify the properties and relationships you want to retrieve for matching assets.


Introductory walkthrough - Developer

Only this line differs from the original query. You can include as many attributes in IncludeOnResults as you want to specify the properties and relationships you want to retrieve for matching assets.


Introductory walkthrough - Developer

Also gives the best performance If all you want to do is check or report on metadata, you should have a starting point from the information above. Or, now that you've found an asset of interest, maybe you want to update the asset with additional metadata?


Introductory walkthrough - Developer

Once again, before we jump to code, let's first understand some key concepts about how Atlan handles updates: Importance of identifiers Most operations on assets are upserts , that is, they could either create (insert) or update a given asset. How do you know which is going to happen?


Introductory walkthrough - Developer

To answer this question, you need to understand how Atlan uniquely identifies each asset. Recall earlier we discussed asset's different identifiers in Atlan.


Introductory walkthrough - Developer

Every asset in Atlan has at least the following two unique identifiers. These are both mandatory for every asset, so no asset can exist without these: Atlan uses globally-unique identifiers (GUIDs) to uniquely identify each asset, globally.


Introductory walkthrough - Developer

They look something like this: As the name implies, GUIDs are: Globally unique (across all systems). Generated in a way that makes it nearly impossible for anything else to ever generate that same ID.


Introductory walkthrough - Developer

2 Note that this means the GUID itself is not : Meaningful or capable of being interpreted in any way Atlan uses qualifiedName s to uniquely identify assets based on their characteristics. They look something like this: Qualified names are not : Globally unique (across all systems).


Introductory walkthrough - Developer

Instead, they are: Consistently constructed in a meaningful way, making it possible for them to be reconstructed. Note that this means the qualifiedName is: Meaningful and capable of being interpreted How these impact updates Since they are truly unique, operations that include a GUID will only update an asset, not create one.


Introductory walkthrough - Developer

Conversely, operations that take a qualifiedName can: Create an asset, if no exactly-matching qualifiedName is found in Atlan. Update an asset, if an exact-match for the qualifiedName is found in Atlan.


Introductory walkthrough - Developer

These operations also require a typeName , so that if creation does occur the correct type of asset is created. Unintended consequences of this behavior Be careful when using operations with only the qualifiedName.


Introductory walkthrough - Developer

You may end up creating assets when you were only expecting them to be updated or to fail if they did not already exist. This is particularly true when you do not give the exact, case-sensitive qualifiedName of an asset.


Introductory walkthrough - Developer

a/b/c/d is not the same as a/B/c/d when it comes to qualifiedName s. Perhaps this leaves you wondering: why have a qualifiedName at all?


Introductory walkthrough - Developer

The qualifiedName 's purpose is to identify what is a unique asset. Many different tools might all have information about that asset.


Introductory walkthrough - Developer

Having a common "identity" means that many different systems can each independently construct its identifier the same way. If a crawler gets table details from Snowflake it can upsert based on those identity characteristics in Atlan.


Introductory walkthrough - Developer

The crawler will not create duplicate tables every time it runs. This gives idempotency.


Introductory walkthrough - Developer

Looker knows the same identity characteristics for the Snowflake tables and columns. So if you get details from Looker about the tables it uses for reporting, you can link them together in lineage.


Introductory walkthrough - Developer

(Looker can construct the same identifier for the table as Snowflake itself.) These characteristics are not possible using GUIDs alone. Limit to changes only Now that you understand the nuances of identifiers, let's look at how you can update metadata in Atlan.


Introductory walkthrough - Developer

In general, you only need to send changes to Atlan. You do not need to send an entire asset each time you want to make changes to it.


Introductory walkthrough - Developer

For example, imagine you want to mark a table as certified but do not want to change anything else (its name, description, owner details, and so on): You can update an asset without first looking the asset up, if you know (can construct) its identifying qualifiedName. Using the updater() static method on any asset type, you pass in (typically) the qualifiedName and name of the asset.


Introductory walkthrough - Developer

This returns a builder onto which you can then chain any updates. You can then chain onto the returned builder as many updates as you want.


Introductory walkthrough - Developer

In this example, we change the certificate status to VERIFIED. At the end of your chain of updates, you need to build the builder (into an object, in-memory).


Introductory walkthrough - Developer

And then, finally, you need to .save() that object to persist those changes in Atlan (passing the client for the tenant you want to save it in). The response will contain details of the change: whether the asset was created, updated, or nothing happened because the asset already had those changes.


Introductory walkthrough - Developer

You can update an asset without first looking the asset up, if you know (can construct) its identifying qualified_name. Using the updater() class method on any asset type, you pass in (typically) the qualified_name and name of the asset.


Introductory walkthrough - Developer

You can then add onto the returned object as many updates as you want. In this example, we change the certificate status to VERIFIED.


Introductory walkthrough - Developer

And then, finally, you need to client.asset.save() that object to persist those changes in Atlan. The response will contain details of the change: whether the asset was created, updated, or nothing happened because the asset already had those changes.


Introductory walkthrough - Developer

You can update an asset without first looking the asset up, if you know (can construct) its identifying qualifiedName. Using the updater() static method on any asset type, you pass in (typically) the qualifiedName and name of the asset.


Introductory walkthrough - Developer


Introductory walkthrough - Developer

You can update an asset without first looking the asset up, if you know (can construct) its identifying qualifiedName. Using the Updater() method on any asset type, you pass in (typically) the qualifiedName and name of the asset.


Introductory walkthrough - Developer

This returns an object into which you can then place any updates. You can place into the returned object as many updates as you want.


Introductory walkthrough - Developer

In this example, we change the certificate status to VERIFIED. And then, finally, you need to .Save() that object to persist those changes in Atlan.


Introductory walkthrough - Developer

The response will contain details of the change: whether the asset was created, updated, or nothing happened because the asset already had those changes. Atlan will handle idempotency By sending only the changes you want to apply, Atlan can make idempotent updates.


Introductory walkthrough - Developer

Atlan will only attempt to update the asset with the changes you send. Atlan leaves any existing metadata on the asset as-is.


Introductory walkthrough - Developer

If the asset already has the metadata values you are sending, Atlan does nothing. It will not even update audit details like the last update timestamp, and is thus idempotent.


Introductory walkthrough - Developer

What if you want to make changes to many assets, as efficiently as possible? Start by initializing a batch.


Introductory walkthrough - Developer

Through this batch, we can automatically queue up and bulk-upsert assets — in this example, 20 at a time. Be sure to include any details you might need to make a decision about whether to update the asset or not (and what to update it with).


Introductory walkthrough - Developer

You must flush() the batch outside of any loop where you've added assets into it. This ensures any final remaining elements in the batch are still sent to Atlan, even if the batch is not "full".


Introductory walkthrough - Developer

Finally, from the batch you can retrieve the minimal details about any assets it created or updated. Start by initializing a batch.


Introductory walkthrough - Developer

You can then add() any updated objects directly into the batch you created earlier. The batch itself will handle saving these to Atlan when a sufficient number have been queued up (20, in this example).


Introductory walkthrough - Developer

Finally, from the batch you can retrieve the minimal details about any assets it created or updated. Where to go from here Common tasks Common operations on assets, that are available across all assets.


Introductory walkthrough - Developer

Discover actions Common operations on assets, that are available across all assets. Asset-specific Operations that are specific to certain assets.


Introductory walkthrough - Developer

Focus on a specific kind of asset Operations that are specific to certain assets. Focus on a specific kind of asset Governance structures Operations dealing with governance structures, rather than assets.


Introductory walkthrough - Developer

Manage governance structures Operations dealing with governance structures, rather than assets. Manage governance structures Samples Real code samples our customers use to solve particular use cases.


Introductory walkthrough - Developer

Review live samples Real code samples our customers use to solve particular use cases. Review live samples Events Delve deep into the details of the events Atlan triggers.


Introductory walkthrough - Developer

Learn more about events Delve deep into the details of the events Atlan triggers. Learn more about events Note that this is intentionally kept as simple as possible.


Introductory walkthrough - Developer

The walkthrough is not intended to be exhaustive. Where possible, we have cross-referenced other detailed examples elsewhere in the site.


Introductory walkthrough - Developer

↩ Note that this is intentionally kept as simple as possible. The walkthrough is not intended to be exhaustive.


Introductory walkthrough - Developer

Where possible, we have cross-referenced other detailed examples elsewhere in the site. ↩ There are orders of magnitude lower chances of GUIDs conflicting with each other than there are grains of sand on the planet.


Introductory walkthrough - Developer

(And generating them does not rely on a central ID-assigning registry.) ↩ There are orders of magnitude lower chances of GUIDs conflicting with each other than there are grains of sand on the planet. (And generating them does not rely on a central ID-assigning registry.) ↩


Introductory walkthrough - Developer

An introductory walkthrough You might also like our Atlan Platform Essentials certification. Not sure where to start?


Introductory walkthrough - Developer

Allow us to introduce Atlan development through example. 1 We strongly recommend using one of our SDKs to simplify the development process.


Introductory walkthrough - Developer

As a first step, set one up: The SDK is available on Maven Central , ready to be included in your project: Include the latest version of the Java SDK in your project as a dependency. You can also give a specific version instead of the + , if you'd like.


Introductory walkthrough - Developer

The Java SDK uses slf4j for logging purposes. You can include logback as a simple binding mechanism to send any logging information out to your console (standard out).


Introductory walkthrough - Developer

Provide two values to create an Atlan client: Provide your Atlan tenant URL as the first parameter. You can also read the value from an environment variable, if you leave out both parameters.


Introductory walkthrough - Developer

Provide your API token as the second parameter. You can also read the value from another environment variable, by leaving out this parameter.


Introductory walkthrough - Developer

You can then start writing some actual code to run within a static main method. (We'll show some examples of this further below.) Once the block is complete, any resources held by the client (i.e.


Introductory walkthrough - Developer

for caching) will be automatically released. Set up logging for SDK You can also checkout to the advanced configuration section of the SDK to learn about how to set up logging.


Introductory walkthrough - Developer

The SDK is available on PyPI. You can use pip to install it as follows: Provide two values to create an Atlan client: Provide your Atlan tenant URL to the base_url parameter.


Introductory walkthrough - Developer

(You can also do this through environment variables .) Provide your API token to the api_key parameter. (You can also do this through environment variables .) Set up logging for SDK You can also checkout to the advanced configuration section of the SDK to learn about how to set up logging.


Introductory walkthrough - Developer

The SDK is available on Maven Central , ready to be included in your project: Include the latest version of the Java SDK in your project as a dependency. You can also give a specific version instead of the + , if you'd like.


Introductory walkthrough - Developer

The Java SDK uses slf4j for logging purposes. You can include slf4j-simple as a simple binding mechanism to send any logging information out to your console (standard out), along with the kotlin-logging-jvm microutil.


Introductory walkthrough - Developer


Introductory walkthrough - Developer

The SDK is available on GitHub , ready to be included in your project: Provide two values to set up connectivity to Atlan: Provide your Atlan tenant URL to the assets.Context() method. If you prefer using the value from an environment variable, you can use assets.NewContext() without any parameters.


Introductory walkthrough - Developer

Provide your API token as the second parameter to the assets.Context() method. (Or again, have it picked up automatically by the assets.NewContext() method.) Set up logging for SDK You can also checkout to the advanced configuration section of the SDK to learn about how to set up logging.


Introductory walkthrough - Developer

Don't forget to give permissions If you want to be able to access existing metadata with an API token, don't forget that you need to assign one or more personas to the API token that grant it access to metadata. Now that you have an SDK installed and configured, you are ready to code!


Introductory walkthrough - Developer

Before we jump straight to code, though, let's first introduce some key concepts in Atlan: What is an asset? In Atlan, we refer to all objects that provide context to your data as assets.


Introductory walkthrough - Developer

Each type of asset in Atlan has a set of: Properties , such as: Certificates Announcements Properties , such as: Relationships to other assets, such as: Schema child tables Table parent schema Table child columns Column parent table Relationships to other assets, such as: Schema child tables Table parent schema Table child columns Column parent table In an object-oriented programming sense, think of an asset as an instance of a class. The structure of an asset (the class itself, in this analogy) is defined by something called a type definition , but that's for another day.


Introductory walkthrough - Developer

So as you can see: There are many different kinds of assets: tables, columns, schemas, databases, business intelligence dashboards, reports, and so on. Assets inter-relate with each other: a table has a parent schema and child columns, a schema has a parent database and child tables, and so on.


Introductory walkthrough - Developer

Different kinds of assets have some common properties (like certificates) and other properties that are unique to that kind of asset (like a columnCount that only exists on tables, not on schemas or databases). When you know the asset When you already know which asset you want to retrieve, you can read it from Atlan using one of its identifiers.


Introductory walkthrough - Developer

We'll discuss these in more detail as part of updates, but for now you can think of them as: is a primary key for an asset: completely unique, but meaningless by itself is a business key for an asset: unique for a given kind of asset, and interpretable You can retrieve an asset using the static get() method on any asset type, providing the client and either the asset's GUID or qualifiedName. (Each asset type is its own unique class in the SDK.) You can retrieve an asset using the asset.get_by_guid() method on the Atlan client, providing both the type of asset you expect to retrieve and its GUID.


Introductory walkthrough - Developer

(Each asset type is its own unique class in the SDK.) You can also retrieve an asset using the asset.get_by_qualified_name() method on the Atlan client, providing the type of asset you expect to retrieve and its qualified_name. (Each asset type is its own unique class in the SDK.) You can retrieve an asset using the static get() method on any asset type, providing the client and either the asset's GUID or qualifiedName.


Introductory walkthrough - Developer

(Each asset type is its own unique class in the SDK.) You can retrieve an asset using the assets.GetByGuid() method on the Atlan client, providing both the type of asset you expect to retrieve and its GUID. (Each asset type is its own unique class in the SDK.) You can also retrieve an asset using the assets.GetByQualifiedName() method on the Atlan client, providing the type of asset you expect to retrieve and its qualifiedName.


Introductory walkthrough - Developer

(Each asset type is its own unique class in the SDK.) Note that the response is strongly typed: If you are retrieving a table, you will get a table back (as long as it exists). You do not need to figure out what properties or relationships exist on a table - the Table class defines them for for you already.


Introductory walkthrough - Developer

In any modern IDE, this means you have type-ahead support for retrieving the properties and relationships from the table variable. You can also refer to the types reference in this portal for full details of every kind of asset.


Introductory walkthrough - Developer

Retrieval by identifier can be more costly than you might expect Even though you are retrieving an asset by an identifier, this can be more costly than you might expect. Retrieving an asset in this way will: Retrieve all its properties and their values Retrieve all its relationships Imagine the asset you are retrieving has 100's or 1000's of these.


Introductory walkthrough - Developer

If you only care about its certificate and any owners, you will be retrieving far more information than you need. When you need to find it first For example, imagine you want to find all tables named MY_TABLE : You can then run the request using Execute().


Introductory walkthrough - Developer

For example, if you want to know the certificate of the asset you only need to tack that onto the query: Only this line differs from the original query. You can chain as many includeOnResults calls as you want to specify the properties and relationships you want to retrieve for matching assets.


Introductory walkthrough - Developer

Only this line differs from the original query. You can chain as many include_on_results calls as you want to specify the properties and relationships you want to retrieve for matching assets.


Introductory walkthrough - Developer

Only this line differs from the original query. You can chain as many includeOnResults calls as you want to specify the properties and relationships you want to retrieve for matching assets.


Introductory walkthrough - Developer

Only this line differs from the original query. You can include as many attributes in IncludeOnResults as you want to specify the properties and relationships you want to retrieve for matching assets.


Introductory walkthrough - Developer

Also gives the best performance If all you want to do is check or report on metadata, you should have a starting point from the information above. Or, now that you've found an asset of interest, maybe you want to update the asset with additional metadata?


Introductory walkthrough - Developer

Once again, before we jump to code, let's first understand some key concepts about how Atlan handles updates: Importance of identifiers Most operations on assets are upserts , that is, they could either create (insert) or update a given asset. How do you know which is going to happen?


Introductory walkthrough - Developer

To answer this question, you need to understand how Atlan uniquely identifies each asset. Recall earlier we discussed asset's different identifiers in Atlan.


Introductory walkthrough - Developer

Every asset in Atlan has at least the following two unique identifiers. These are both mandatory for every asset, so no asset can exist without these: Atlan uses globally-unique identifiers (GUIDs) to uniquely identify each asset, globally.


Introductory walkthrough - Developer

They look something like this: As the name implies, GUIDs are: Globally unique (across all systems). Generated in a way that makes it nearly impossible for anything else to ever generate that same ID.


Introductory walkthrough - Developer

2 Note that this means the GUID itself is not : Meaningful or capable of being interpreted in any way Atlan uses qualifiedName s to uniquely identify assets based on their characteristics. They look something like this: Qualified names are not : Globally unique (across all systems).


Introductory walkthrough - Developer

Instead, they are: Consistently constructed in a meaningful way, making it possible for them to be reconstructed. Note that this means the qualifiedName is: Meaningful and capable of being interpreted How these impact updates Since they are truly unique, operations that include a GUID will only update an asset, not create one.


Introductory walkthrough - Developer

Conversely, operations that take a qualifiedName can: Create an asset, if no exactly-matching qualifiedName is found in Atlan. Update an asset, if an exact-match for the qualifiedName is found in Atlan.


Introductory walkthrough - Developer

These operations also require a typeName , so that if creation does occur the correct type of asset is created. Unintended consequences of this behavior Be careful when using operations with only the qualifiedName.


Introductory walkthrough - Developer

You may end up creating assets when you were only expecting them to be updated or to fail if they did not already exist. This is particularly true when you do not give the exact, case-sensitive qualifiedName of an asset.


Introductory walkthrough - Developer

a/b/c/d is not the same as a/B/c/d when it comes to qualifiedName s. Perhaps this leaves you wondering: why have a qualifiedName at all?


Introductory walkthrough - Developer

The qualifiedName 's purpose is to identify what is a unique asset. Many different tools might all have information about that asset.


Introductory walkthrough - Developer

Having a common "identity" means that many different systems can each independently construct its identifier the same way. If a crawler gets table details from Snowflake it can upsert based on those identity characteristics in Atlan.


Introductory walkthrough - Developer

The crawler will not create duplicate tables every time it runs. This gives idempotency.


Introductory walkthrough - Developer

Looker knows the same identity characteristics for the Snowflake tables and columns. So if you get details from Looker about the tables it uses for reporting, you can link them together in lineage.


Introductory walkthrough - Developer

(Looker can construct the same identifier for the table as Snowflake itself.) These characteristics are not possible using GUIDs alone. Limit to changes only Now that you understand the nuances of identifiers, let's look at how you can update metadata in Atlan.


Introductory walkthrough - Developer

In general, you only need to send changes to Atlan. You do not need to send an entire asset each time you want to make changes to it.


Introductory walkthrough - Developer

For example, imagine you want to mark a table as certified but do not want to change anything else (its name, description, owner details, and so on): You can update an asset without first looking the asset up, if you know (can construct) its identifying qualifiedName. Using the updater() static method on any asset type, you pass in (typically) the qualifiedName and name of the asset.


Introductory walkthrough - Developer

This returns a builder onto which you can then chain any updates. You can then chain onto the returned builder as many updates as you want.