SAS Viya 3.4: Search for Tags (Annotations REST API)

[#1]

In SAS Viya 3.4, you can use tags to add extra information beyond simple metadata to tables, columns, and other objects. In the user interface, these tags can be added to columns automatically when profiling the data or manually added. At this time in the user interface, you can add a new tag name, but there is not currently a way to perform the following actions:

• Search for items that have a designated tag
• Update an existing tag name
• Delete an existing tag name.

However, these actions are available using the Annotations REST API service.

I will demonstrate how the three actions listed above can be performed using the Annotations REST API service in a 3-part series. This article will focus on how you can search for items that have a designated tag.

Before using the Annotations REST API service, you must first obtain and OAuth token. For more information on this, you can read the following articles:

• Authentication to SAS Viya: a couple of approaches
• Introducing the GEL pyviyatools

Note: Make sure the username you use to retrieve the OAuth token has the necessary permissions to run any of the REST APIs you want to execute.

Once you have your OAuth token, you can then use the Annotation REST API service. In my case, I want to search for items that have a tag that contains the word "Demo". To do this I use the GET method for the Annotations REST API with a filter option:

GET http://<ViyaServerName>/annotations/annotations?filter=contains(name,'<TagNameToFind>')

For my specific example this is the REST API call I make to return any tag names that contain the word "Demo".

GET  http://sasviya01.race.sas.com/annotations/annotations/?filter=contains(name,'Demo')
Header:  Content-Type=application/vnd.sas.annotation+json
Header:  Accept=application/vnd.sas.collection+json 
Header:  Authorization= Bearer <ReplaceWithOAuthToken>

Select any image to see a larger version.

Note: You can use many different tools to perform REST API calls. For my demonstration, I am using a tool called Postman.

This returns the following results:

From these results I can see that two items containing the word Demo in their tag name are returned:

• Demo1
• Demo2.

Note: When running any of these Annotation API requests, there is by default a maximum limit of 10 items returned. To increase the number of items returned, you can use the limit option when making your Annotation REST API call.

Now that I know the IDs of the annotations with the word "Demo" in the name, I can run a call based on their returned URIs for the members relationship type. For example, to retrieve the member items for the Demo2 tag name, I run the following request based on its members relationship URI of /annotations/annotations/c2a28476-d82a-4ec9-af55-de063cc4d720/members. Note: c2a28476-d82a-4ec9-af55-de063cc4d720 is the Annotation ID for the tag with the name of Demo2.

GET  http://sasviya01.race.sas.com/annotations/annotations/c2a28476-d82a-4ec9-af55-de063cc4d720/members 
Header:  Content-Type=application/vnd.sas.annotation+json
Header:  Accept=application/vnd.sas.collection+json 
Header:  Authorization= Bearer <ReplaceWithOAuthToken>

This returns five items that are tagged with the name Demo2.

The column and table names are returned when using the Annotations REST API call for its members: GET http://<ViyaServerName>/annotations/annotations/<AnnotationID>/members

For my specific call the table and column names that are tagged with the name Demo2 are:

Table Name	CUSTOMERS in the DM CAS Library
Table Name	CUSTOMERS_NEW in the DM CAS Library
Column Name	name on the CUSTOMERS table in the DM CAS Library
Column Name	name on the CUSTOMERS_NEW table in the DM CAS Library

For items that are not tables or columns, I need to run the REST API for its resource URI to get its actual name. For example, to retrieve the Data Plan name based on its URI /dataPlans/plans/916318ea-c759-4dc1-a4b1-5796bee9976c, I need to run the following request:

GET  http://sasviya01.race.sas.com/dataPlans/plans/916318ea-c759-4dc1-a4b1-5796bee9976c
Header:  Content-Type=application/vnd.sas.data.plan+json
Header:  Accept=application/vnd.sas.data.plan+json 
Header:  Authorization= Bearer <ReplaceWithOAuthToken>

Note: The header information for Content-Type and Accept will vary depending upon the object.

This call returns that the data plan name that is tagged with Demo2 is named Plan 1.

This concludes the demonstration on how to search for items that are assigned a particular tag name using the Annotations REST API. In my next two articles, I will explore using the Annotations REST API to perform the following actions:

• Update an existing tag name
• Delete an existing tag name.

For more information on working with tags (annotations) using REST API, you can refer to the documentation.