Skip to main content

1. My First Asset

Pre-Requisites​

  1. Setting up server
  2. Setting up the CLI (if you want to use the CLI client)

1.1 Introduction​

In Compass, we call every metadata that you input as an Asset. All your tables, dashboards, topics, jobs are an example of assets.

In this section, we will help you to build your first Asset and hopefully it will give your clear idea about what an Asset is in Compass.

1.2 Hello, World Asset!​

Let's imagine we have a postgres instance that we keep referring to as our main-postgres. Inside it there is a database called my-database that has plenty of tables. One of the tables is named orders, and below is how you represent that table as a Compass' Asset.

{
  "urn": "main-postgres:my-database.orders",
  "type": "table",
  "service": "postgres",
  "name": "orders",
  "data": {
    "database": "my-database",
    "namespace": "main-postgres"
  }
}

  • urn is a unique name you assign to an asset. You need to make sure you don't have a duplicate urns across all of your assets because Compass treats urn as an identifier of your asset. For this example, we use the following format to make sure our urn is unique, {NAMESPACE}:{DB_NAME}.{TABLE_NAME}.

  • type is your Asset's type. The value for type has to be recognizable by Compass. More info about Asset's Type can be found here.

  • service can be seen as the source of your asset. service can be anything, in this case since our orders table resides in postgres, we can just put postgres as the service.

  • name is the name of your asset, it does not have to be unique. We don't need to worry to get mixed up if there are other tables with the same name, urn will be the main identifier for your asset, that is why we need to make it unique across all of your assets.

  • data can hold your asset's extra details if there is any. In the example, we use it to store information of the database name and the alias/namespace that we use when referring the postgres instance.

1.3 Sending your first asset to Compass​

Assets can be created ingested in Compass using the following ways:

  1. Using compass asset edit CLI command
  2. Calling to PATCH /v1beta1/assets API

Let's send this into Compass so that it would be discoverable.

$ compass asset edit --body=<path to the asset.json file>
{
    "asset": {
        "urn": "main-postgres:my-database.orders",
        "type": "table",
        "service": "postgres",
        "name": "orders",
        "data": {
            "database": "my-database",
            "namespace": "main-postgres"
        }
    }
}

There are a few things to notice here:

  1. The HTTP method used is PATCH. This is because Compass does not have a dedicated Create API, it uses a single API to Patch / Create an asset instead. So when updating or patching your asset, you can use the same API. Similarly we use compass asset edit for upserting via the Compass CLI tool

  2. Compass requires Compass-User-UUID header to be in the request. More information about the identity header can be found here. To simplify this tour, let's just use john.doe@example.com. For CLI, these configurations are to be done in the config file discussed here

  3. When sending our asset to Compass, we need to put our asset object inside an asset field as shown in the example above

  4. For using the CLI tool, create a .json file using the example configurations shown above and provide the path to it here.

On a success insertion, your will receive below response:

{ "id": "cebeb793-8933-434c-b38f-beb6dbad91a5" }

id is an identifier of your asset. Unlike urn which is provided by you, id is auto generated by Compass if there was no asset found with the given URN.

Conclusion​

Now that you have successfully ingested your asset to Compass, we can now search and find it via Compass.

In the next section, we will see how Compass can help you in searching and discovering your assets.