Skip to main content

Search examples

Connection by name and type​

You may have noticed that connections in Atlan have qualifiedNames that include a timestamp. As a result, they'ren't trivial to directly construct.

However, you can search for them by name and type to resolve their qualifiedName:

Find a connection by name and type
List<Connection> connections = Connection.findByName( // (1)
    client, // (2)
    "production", // (3)
    AtlanConnectorType.SNOWFLAKE); // (4)
  1. Use the findByName static method on the Connection class to search for connections by name and type. If you name your connections uniquely (by type), this should only return a single-item list.
  2. Because this operation will directly search for the asset in Atlan, you must provide it an AtlanClient through which to connect to the tenant.
  3. Provide the name of the connection (this will be exact-matched).
  4. Provide the type of the connection. You can also (optionally) provide a list of extra attributes you want to retrieve for the connection. Core attributes like qualifiedName and its GUID are already included.

All connections​

On the other hand, you may want to find all the connections that exist in the environment:

Find all connections
Connection.select(client) // (1)
    .pageSize(100) // (2)
    .stream() // (3)
    .filter(a -> a instanceof Connection) // (4)
    .forEach(c -> { // (5)
        log.info("Connection: {}", c);
    });
  1. To start building up a query to include all connections, you can use the select() convenience method on Connection itself. This will already limit results to only active (non-archived) connections. Because this operation will directly search for the asset in Atlan, you must provide it an AtlanClient through which to connect to the tenant.
  2. (Optional) You can chain a pageSize() method to control the page sizes, to further limit API calls by retrieving more results per page.
  3. The search will only run when you call the stream() method, which will then lazily-load each page of results into a stream.
  4. (Optional) You can do any other operations you might do on a stream, such as filtering the results to make sure they're of a certain type.
  5. This is the pattern for iterating through all results (across pages) covered in the Searching for assets portion of the SDK documentation.

Columns in schema​

This example finds all columns that exist in a particular schema—irrespective of the table, view, or materialized view they exist within.

Get all columns in a schema
String schemaQN = "default/snowflake/1662194632/MYDB/MY_SCH"; // (1)
Column.select(client) // (2)
    .where(Asset.QUALIFIED_NAME.startsWith(schemaQN)) // (3)
    .pageSize(100) // (4)
    .includeOnResults(Asset.DESCRIPTION) // (5)
    .stream() // (6)
    .filter(a -> a instanceof Column) // (7)
    .forEach(c -> { // (8)
        log.info("Column: {}", c);
    });
  1. Part of the trick here is that the qualifiedName of a column starts with the qualifiedName of its parent (table, view or materialized view). Similarly, the qualifiedName of the table, view or materialized view starts with the qualifiedName of its parent schema. (And so on, all the way up to the connection itself.)
  2. To start building up a query specifically for columns, you can use the select() convenience method on Column itself. Because this operation will directly search for the asset in Atlan, you must provide it an AtlanClient through which to connect to the tenant.
  3. You can use the where() method to define all the conditions the search results must match. For this example, use the Asset.QUALIFIED_NAME constant to limit to only those assets whose qualifiedName starts with the qualifiedName of the schema (by using the startsWith() predicate). In this example, that means only assets that are within this particular schema will be returned as results.
  4. (Optional) You can play around with different page sizes, to further limit API calls by retrieving more results per page.
  5. Add as many attributes as needed. Each attribute you add here will make sure that detail is included in each search result. So in this example, every column will include its description. (Limit these attributes to the minimum you need about each column to do your intended work.)
  6. The search will only run when you call the stream() method, which will then lazily-load each page of results into a stream.
  7. (Optional) You can do any other operations you might do on a stream, such as filtering the results to make sure they're of a certain type.
  8. This is the pattern for iterating through all results (across pages) covered in the Searching for assets portion of the SDK documentation.

Assets with custom metadata​

This example finds all assets with a particular custom metadata attribute populated—irrespective of the specific value of the attribute.

Get all assets with a custom metadata attribute populated
client.assets.select() // (1)
    .where(CustomMetadataField.of(client, "RACI", "Responsible").hasAnyValue()) // (2)
    ._includesOnResults(client.getCustomMetadataCache().getAttributesForSearchResults("RACI")) // (3)
    .stream() // (4)
    .forEach(a -> { // (5)
        log.info("Asset: {}", a);
    });

  1. To search across all assets, you can use the assets.select() convenience method on a client.

  2. When searching for custom metadata attributes, you can construct a CustomMetadataField to start a clause that will match a custom metadata property. Since you are searching for the custom metadata attribute itself, there is no enum for the custom metadata or its property names, so these must be provided as strings. (The CustomMetadataField will handle translating these from their human-readable values to the Atlan-internal ID strings needed for the search.)

    The hasAnyValue() predicate allows you to limit to assets that have any value for this custom metadata attribute.

  3. Since you are searching for custom metadata, you probably want to include the values for custom metadata in each search result. This getAttributesForSearchResults() helper method will return all of the custom attributes within the RACI custom metadata structure. These will be encoded in the specific form required by the search for you.

    Note the use of _includesOnResults

Since the getAttributesForSearchResults() helper will return a list of strings, you'll need to use the special _includesOnResults() method to add these for inclusion. ::: 4. The search will only run when you call the stream() method, which will then lazily-load each page of results into a stream. 5. This is the pattern for iterating through all results (across pages) covered in the Searching for assets portion of the SDK documentation.

Assets with specific custom metadata value​

This example finds all assets with a particular custom metadata attribute populated—with a specific value for the attribute.

Get all assets with a specific custom metadata attribute value
client.assets.select() // (1)
    .where(CustomMetadataField.of(client, "RACI", "Responsible").eq("This exact value", false)) // (2)
    ._includesOnResults(client.getCustomMetadataCache().getAttributesForSearchResults("RACI")) // (3)
    .stream() // (4)
    .forEach(a -> { // (5)
        log.info("Asset: {}", a);
    });

  1. To search across all assets, you can use the assets.select() convenience method on a client.

  2. When searching for custom metadata attributes, you can construct a CustomMetadataField to start a clause that will match a custom metadata property. Since you are searching for the custom metadata attribute itself, there is no enum for the custom metadata or its property names, so these must be provided as strings. (The CustomMetadataField will handle translating these from their human-readable values to the Atlan-internal ID strings needed for the search.)

    The eq() predicate allows you to limit to assets that have only the exact value provided for this custom metadata attribute (and in the case of a string value, you must supply a second parameter indicating whether the search should be case-sensitive (false) or case-insensitive (true)).

  3. Since you are searching for custom metadata, you probably want to include the values for custom metadata in each search result. This getAttributesForSearchResults() helper method will return all of the custom attributes within the RACI custom metadata structure. These will be encoded in the specific form required by the search for you.

    Note the use of _includesOnResults

Since the getAttributesForSearchResults() helper will return a list of strings, you'll need to use the special _includesOnResults() method to add these for inclusion. ::: 4. The search will only run when you call the stream() method, which will then lazily-load each page of results into a stream. 5. This is the pattern for iterating through all results (across pages) covered in the Searching for assets portion of the SDK documentation.

Assets linked to term​

This example finds all assets that are linked to a specific glossary term. (And could be extended to do find assets linked to any one of a number of glossary terms.) In this specific example we will find any assets linked to a glossary term named Revenue in a glossary named Metrics.

You'll need the qualifiedName of the glossary term

To find the assets linked to the glossary term, you'll need to search using the qualifiedName of the term. This isn't the human-readable name you see in the UI. So this example is split into two parts:

  1. Finding the qualifiedName of the glossary term from its human-readable name and the result of (1).
  2. Finding all assets linked to that glossary term.

For example:

Find qualifiedName of the term
GlossaryTerm term = GlossaryTerm.findByName(client, "Revenue", "Concepts"); // (1)
String termQualifiedName = term.getQualifiedName(); // (2)
  1. The GlossaryTerm.findByName() helper method will retrieve the glossary term by its human-readable name, given the name of the glossary in which it should exist. If the term doesn't exist (within that glossary), it will throw a NotFoundException. Because this operation will directly search for the asset in Atlan, you must provide it an AtlanClient through which to connect to the tenant.
  2. If no exception was thrown, you can retrieve the qualifiedName of the glossary term.
Get all assets linked to a specific term
client.assets.select() // (1)
    .where(Asset.ASSIGNED_TERMS.in(List.of(termQualifiedName))) // (2)
    .stream() // (3)
    .forEach(a -> { // (4)
        log.info("Asset: {}", a);
    });
  1. To search across all assets, you can use the assets.select() convenience method on a client.
  2. When searching for assets linked to one or more terms, you need to use the qualifiedName of the terms. (This example shows searching for just one term, but you could search for any number of them in the list. The search will find assets that are assigned at least one of those terms in the list.)
  3. The search will only run when you call the stream() method, which will then lazily-load each page of results into a stream.
  4. This is the pattern for iterating through all results (across pages) covered in the Searching for assets portion of the SDK documentation.

Assets with Atlan tag​

This example finds all assets that are assigned a specific Atlan tag—irrespective of whether they were directly assigned the tag or it was propagated.

Get all assets with a specific tag
client.assets.select() // (1)
    .tagged(List.of("PII")) // (2)
    .stream() // (3)
    .forEach(a -> { // (4)
        log.info("Asset: {}", a);
    });
  1. To search across all assets, you can use the assets.select() convenience method on a client.
  2. The .tagged() helper method allows us to limit to assets that match at least one of potentially multiple values (since there could be many tags on an asset). The SDK will translate the provided Atlan tag into the necessary internal representation required for the search—you can just provide the human-readable names of the Atlan tags.
  3. The search will only run when you call the stream() method, which will then lazily-load each page of results into a stream.
  4. This is the pattern for iterating through all results (across pages) covered in the Searching for assets portion of the SDK documentation.

Assets with source tag​

This example finds all assets that are assigned a specific source tag.

Get all assets with a specific tag
client.assets.select() // (1)
    .taggedWithValue( // (2)
        "Sensitivity", // (3)
        "Highly Restricted", // (4)
        true // (5)
    )
    .stream() // (6)
    .forEach(a -> { // (7)
        log.info("Asset: {}", a);
    });
  1. To search across all assets, you can use the assets.select() convenience method on a client.
  2. The .taggedWithValue() helper method allows us to limit to assets that match having this particular tag and value combination.
  3. You must specify the human-readable name of the Atlan tag that's mapped to a source tag. The SDK will translate the provided Atlan tag into the necessary internal representation required for the search—you can just provide the human-readable names of the Atlan tags.
  4. You must also provide the value you want to match.
  5. (Optional) You can restrict the search to only directly-tagged assets with the value using true, or look for all assets tagged with the value (whether directly or propagated).
  6. The search will only run when you call the stream() method, which will then lazily-load each page of results into a stream.
  7. This is the pattern for iterating through all results (across pages) covered in the Searching for assets portion of the SDK documentation.

Deprecated assets​

This example finds all assets that are marked as deprecated.

Get all deprecated assets
client.assets.select() // (1)
    .where(Asset.CERTIFICATE_STATUS.eq(CertificateStatus.DEPRECATED)) // (2)
    .stream() // (3)
    .forEach(a -> { // (4)
        log.info("Asset: {}", a);
    });

  1. To search across all assets, you can use the assets.select() convenience method on a client.

  2. The .where() method allows you to limit to only assets that have a particular value in a particular field. In this example, we're looking for values for the certificate status, so use Asset.CERTIFICATE_STATUS.

    Since we only want assets that are deprecated, we will query where that certificate is set to the CertificateStatus.DEPRECATED value. (No need to try to remember or ever even know what the precise string values for the certificates are—we've provided enums for them in the SDK.)

  3. The search will only run when you call the stream() method, which will then lazily-load each page of results into a stream.

  4. This is the pattern for iterating through all results (across pages) covered in the Searching for assets portion of the SDK documentation.

Certified but incomplete assets​

This example finds all assets that are marked as verified, but are missing a description—suggesting they're in fact incomplete.

Get all verified assets that have no description
client.assets.select() // (1)
    .where(Asset.CERTIFICATE_STATUS.eq(CertificateStatus.VERIFIED)) // (2)
    .whereNot(Asset.DESCRIPTION.hasAnyValue()) // (3)
    .whereNot(Asset.USER_DESCRIPTION.hasAnyValue())
    .includeOnResults(Asset.OWNER_USERS) // (4)
    .includeOnResults(Asset.OWNER_GROUPS) // (5)
    .stream() // (6)
    .forEach(a -> { // (7)
        log.info("Asset: {}", a);
    });

  1. To search across all assets, you can use the assets.select() convenience method on a client.

  2. The where() helper method allows us to limit to only assets that meet a a particular condition. In this example, we're looking for values for the certificate status, so use Asset.CERTIFICATE_STATUS. (No need to try to remember or ever even know what the precise string value is for the name of this field—we've provided enums for them in the SDK.)

    Since we only want assets that are verified, we will query where that certificate is set to the CertificateStatus.VERIFIED value. (No need to try to remember or ever even know what the precise string values for the certificates are—we've provided enums for them in the SDK.)

  3. You can use the whereNot() method to do the opposite—define all the conditions the search results must not match. Here we're limiting to only assets that have a description populated.

    The hasAnyValue() predicate method allows us to limit to only assets that have a user-defined description populated. In Atlan you have both description (crawled from source) and userDescription (user-defined or overridden). For this example use case, you probably want to check that both of these are empty.

  4. As part of the search, you may want certain details included in every result. In this use case, you may want to know the asset owner—someone to confirm this should really be certified when there is no description.

  5. In Atlan you have both users and groups that can own assets. For this example use case, you probably want to retrieve both of these for every result.

  6. The search will only run when you call the stream() method, which will then lazily-load each page of results into a stream.

  7. This is the pattern for iterating through all results (across pages) covered in the Searching for assets portion of the SDK documentation.

Assets with long descriptions​

When text exceeds a particular length (5K characters), the keyword field on an attribute can be empty while the text field on the same attribute is populated. For KeywordTextField types (like DESCRIPTION or USER_DESCRIPTION), use field_type=AtlanSearchableFieldType.TEXT to check the text field instead.

Coming soon
Was this page helpful?