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:
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:
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:
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:
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
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:
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:
For more information on working with tags (annotations) using REST API, you can refer to the documentation.
Registration is open! SAS is returning to Vegas for an AI and analytics experience like no other! Whether you're an executive, manager, end user or SAS partner, SAS Innovate is designed for everyone on your team. Register for just $495 by 12/31/2023.
If you are interested in speaking, there is still time to submit a session idea. More details are posted on the website.
Data Literacy is for all, even absolute beginners. Jump on board with this free e-learning and boost your career prospects.