Skip to content

Go SDK

Repo

Obtain the SDK

Pre-release state

The Go SDK is currently in a pre-release, experimental state. While in this state, we reserve the right to make any changes to it (including breaking changes) without worrying about backwards compatibility, semantic versioning, and so on.

If you are eager to experiment with it, it is available on GitHub. You can use Go dependencies to install it directly from there.

We welcome your feedback during the pre-release, but cannot commit to any specific revisions or timelines at this point in time.

Configure the SDK

There are two ways to configure the SDK:

Using environment variables

  • ATLAN_API_KEY should be given your Atlan API token , for authentication (don't forget to assign one or more personas to the API token to give access to existing assets!)
  • ATLAN_BASE_URL should be given your Atlan URL (for example, https://tenant.atlan.com)

Here's an example of setting those environment variables:

Set environment variables
export ATLAN_BASE_URL=https://tenant.atlan.com
export ATLAN_API_KEY="..."
main.go
1
2
3
4
5
6
7
8
9
package main

import (
    "github.com/atlanhq/atlan-go/atlan/assets"
)

func main() {
    ctx := assets.NewContext()
}

On client creation

If you prefer to not use environment variables, you can do the following:

main.go
1
2
3
4
5
6
7
8
9
package main

import (
    "github.com/atlanhq/atlan-go/atlan/assets"
)

func main() {
    ctx, _ := assets.Context("https://tenant.atlan.com", "...")
}

Careful not to expose your API token!

We generally discourage including your API token directly in your code, in case you accidentally commit it into a (public) version control system. But it's your choice exactly how you manage the API token and including it for use within the client.

That's it — once these are set you can start using your SDK to make live calls against your Atlan instance! 🎉

What's next?

Delve into more detailed examples:

Error-handling

The SDK defines exceptions for the following categories of error:

Exception Description
ApiConnectionError Errors when the SDK is unable to connect to the API, for example due to a lack of network access or timeouts.
AuthenticationError Errors when the API token configured for the SDK is invalid or expired.
ConflictError Errors when there is some conflict with an existing asset and the operation cannot be completed as a result.
InvalidRequestError Errors when the request sent to Atlan does not match its expectations. If you are using the built-in methods like toCreate() and toUpdate() this exception should be treated as a bug in the SDK. (These operations take responsibility for avoiding this error.)
LogicError Errors where some assumption made in the SDK's code is proven incorrect. If ever raised, they should be reported as bugs against the SDK.
NotFoundError Errors when the requested resource or asset does not exist in Atlan.
PermissionError Errors when the API token used by the SDK does not have permission to access a resource or carry out an operation on a specific asset.
RateLimitError Errors when the Atlan server is being overwhelmed by requests.

A given API call could fail due to all of the errors above. So these all extend a generic AtlanError exception, and all API operations can potentially raise AtlanError.

Example

For example, when creating a connection there is an asynchronous process that grants permissions to the admins of that connection. So there can be a slight delay between creating the connection and being permitted to do any operations with the connection. During that delay, any attempt to interact with the connection will result in a PermissionError, even if your API token was used to create connection in the first place.

Another example you may occasionally hit is some network issue that causes your connection to Atlan to be interrupted. In these cases, an ApiConnectionError will be raised.

Advanced configuration

Atlan is a distributed, cloud-native application, where network problems can arise. The SDK therefore automatically attempts to handle ephemeral problems.

Logging

The SDK uses the slog library internally to provide a flexible framework for emitting log messages.

You can enable logging for your SDK script by adding the following lines above your snippets:

main.go
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
package main

import (
    "github.com/atlanhq/atlan-go/atlan/assets"
)

func main() {
    ctx := assets.NewContext()
    ctx.SetLogger(true, "debug") // (1)!
}

  1. You can enable logging by using .SetLogger() on the context object with various logging levels:

    • "debug": used to give detailed information, typically of interest only when diagnosing problems (mostly used level in SDK).
    • "info": used to confirm that things are working as expected.
    • "warn": used as an indication that something unexpected happened, or as a warning of some problem in the near future.
    • "error": indicates that due to a more serious problem, the SDK has not been able to perform some operation.