Data Governance
Also available as:
PDF
loading table of contents...

DSL Search

DSL enables you to search using Apache Atlas DSL. In this section, we proved an example-driven approach to help you understand DSL syntax and capabilities. The syntax used here will not be as exact as the grammar described on the Apache Atlas DSL Search page, but these simplified examples should help explain the key concepts.

You can use the Atlas web UI to test these examples. Select Search > DSL, then enter the query in the Search For box.

Discovering Entities Using Attribute Values

Search Query Format:

type_name where attribute_name OP attribute_value

Where:

  • type_name is the name of a predefined type.

  • attribute_name is the name of an attribute in that type. This does not need to be a unique attribute (unlike in “Retrieve an Entity Definition Using a Unique Attribute” shown previously in the Entities API).

  • OP is an operator: =, !=, <, >, <=, >=

  • attribute_value is the value of an attribute.

The search results are entire entity definitions that match the search criteria.

Search Query Examples:

  • hbase_table where name = ‘webtable’

  • hbase_column_family where name != ‘contents’

  • hbase_column_family where versions > 1

  • hbase_column_family where blockSize < 1000

Discovering Entities Using Combinations of Attribute Values

Search Query Format:

type_name where attribute_name OP attribute_value AND_OR_OP attribute_name OP attribute_value [AND|OR …]

Where:

  • type_name is the name of a predefined type.

  • attribute_name is the name of an attribute in that type. This does not need to be a unique attribute (unlike in “Retrieve an Entity Definition Using a Unique Attribute” shown previously in the Entities API).

  • OP is an operator: =, !=, <, >, <=, >=

  • AND_OR_OP is and or or.

  • attribute_value is the value of an attribute.

Note the following:

  • It is possible to provide any number of expressions of the form attribute_name OP attribute_value combining them with an and or an or.

  • It is also possible to impose an ordering of evaluation by enclosing the expressions within parentheses, for example:

    type_name where attribute_name OP attribute_value AND_OR_OP (attribute_name OP attribute_value AND_OR_OP attribute_name OP attribute_value)

The search results are entire entity definitions that match the search criteria.

Search Query Examples:

  • hbase_column_family where blockSize < 1000 and versions >= 2

  • hbase_column_family where compression != 'lzo' and versions > 1 and blockSize > 1000

  • hbase_column_family where compression = 'lzo' and (versions > 1 or blockSize > 1000)

Selecting Native Attributes in Searches

As described above, search query results include the entire entity definitions. You can also use a SELECT clause in the search query to return specific attributes.

Search Query Format:

search_expression select attribute_name [, attribute_name…]

Where:

  • search_expression is one of the previously described search expressions.

  • attribute_name [list] specifies the attributes to return in the search results.

Search Query Example:

  • hbase_table where name='webtable' select name, qualifiedName, isEnabled

Selecting References in Searches

The previous section showed how we can select any attributes which are of native types. But there are also more complex attribute types, such as collections, references to other entities, etc. For example, hbase_tables contain columnFamilies which are references to entities of type hbase_column_family. To help address this issue, DSL allows search queries to be combined as follows:

Search Query Format:

search_expression, reference_attribute_name

Where:

  • search_expression is one of the previously described search expressions.

  • reference_attribute_name is an attribute name in the entity being selected in search_expression that contains references to other attributes.

One variation is where the reference_attribute_name can be expanded to only select specific attributes of the reference_attribute type:

search_expression, reference_attribute_name select reference_attribute_type_attribute_name [, reference_attribute_type_attribute_name]

Another variation is where the reference_attribute_name can be filtered to include only those references which satisfy some predicate:

search_expression, reference_attribute_name where reference_attribute_type_attribute_name OP reference_attribute_type_attribute_value

Search Query Examples:

  • hbase_table, columnFamilies

  • hbase_column_family where name='anchor', columns

  • hbase_columns_family where name=’anchor’, columns select name, type

  • hbase_column_family, columns where type='byte[]'