Introduction to Table Tags

Overview

Table Tags are words or short phrases that describe a database table. They enable your organization to quickly annotate and share knowledge on tables.  For example, you can tag your production or golden tables to guide analysts to important datasets.

Manage Tags for Your Organization

To ensure that your organization has a clean, controlled vocabulary of tags, only Table Tag Admins have access to define, create, and delete tags for your organization.  Table Tag Admins are users in your organization who belong to a group with the Table Tag Admin role assigned.   If you'd like to set up Table Tag Admins, please contact support. 

As Table Tag Admin, you can create tags. To do so,

1. Navigate to the Admin dropdown on the top navigation bar in Platform
2. Click on Table Tags
3. Click on Create Tag
4. In the Create modal, input the tag you would like to create
5. Click Create

As Table Tag Admin, you can delete tags.  To do so,

1. Navigate to the Admin dropdown on the top navigation bar in Platform
2. Click on Table Tags
3. Locate the tag you want to delete
4. Click on the delete icon
   Note:  You can also delete tags that are created by your fellow Table Tag Admins.  Deleted tags are removed from tables 

Additional notes on tags:

• Tag names are case sensitive, so TagName and tagName are considered as two different tags on Platform
• Each tag name should have 30 characters or fewer. If you need to describe a table with more than 30 characters, we recommend that you leverage the table description field instead. On Platform, each table provides a description field in its Table Details page.
• Tag names should only contain letters or numbers. Tag names can also contain whitespaces or underscores. 

View Tags Under Your Organization

Anyone from your organization can view tags created by your organization's Table Tag Admins.  To do so, navigate to the Admin dropdown on the top navigation bar in Platform and click on Table Tags. 

The Table Tags page displays all the available tags alphabetically by default. For each tag, you can see who created the tag and the number of tables the tag is associated with.

For quick browsing, you can sort the tags by their name, creator, and the number of associated tables.

Apply Tags to Tables

Anyone from your organization can apply tags to a table. To do so,

1. Navigate to the Data Pane by clicking on the database icon in the navigation pane on the left
2. Locate the table you want to apply tags to
3. Click on the blue Tag icon
4. Add or remove tags from the multi-select dropdown
   Note: you can only apply up to 5 tags per table. If this limit is insufficient for your use case, please give us feedback by contacting support.
5. Click Save
6. After Save, you will see the selected tags appearing in the table.
   Note: any user with access to the same table will also see the tags.  Also, when a table that has tags is dropped, it will retain its tags so that when it is recreated the tags are still there.  

Discover Tables with Tags

Anyone from your organization can view tables with tags in 2 ways:

1. You can browse the Data Pane for quick table browsing
   1. Navigate to the Data Pane by clicking on the database icon in the navigation pane on the left
   2. Any tables with tags will appear with a Tag icon.
   3. When you hover on any of these tables, tags will appear in the tooltip.
2. You can see all the tags listed in the selected table’s Table Details page
   1. Navigate to the Data Pane by clicking on the database icon in the navigation pane on the left
   2. Locate the table and click on the table
   3. Click on its Table Details link

Under the Data Pane, you can also search tables with the tags filter in the following ways:

1. Search tables with keywords and the tag filter
2. Search tables with just the tag filter (no need to input any keywords)

To search tables with the tags filter,

1. Navigate to the Data Pane by clicking on the database icon in the navigation pane on the left
2. Click on the Tags button under the search bar
3. Select tags in the multi-select-dropdown
4. Click Apply
5. After Apply, you will see tables with the selected tags appearing in the Data Pane.  You can hover on the tables to see which tags these tables are associated with 

Here’s an example of how you can search for tables with keywords and tags.  Suppose your organization created a set of sales tables for a variety of usage.  Your organization named all these tables with sales_* and created tags for each usage type, e.g. Public, Reporting, etc.  To look for sales tables that are meant for public or reporting usage, you can type in “sales” in the search input box and select Public and Reporting from the tag filter. 

API for Additional Flexibility 

All of Platform’s capabilities can be managed via API, enabling you to tailor Platform to your exact needs. 

For example, you can programmatically create tags with the /table_tags/ endpoint. You can also use the API to retrieve and drop all the tables that are tagged with duplicate. 

The Civis API is hosted at https://api.civisanalytics.com/. 

Best Practices 

Here are some best practices for using tags in your organization: 

1. Establish a tagging system 
   1. Consider: will tags be in singular or plural terms? Will they be nouns, verbs, or some combination? Will they be in lowercase? If a tag has multiple words, will they be separated with spaces, underscores, or by capitalization?
   2. Align with your team on tagging guidelines and/or naming conventions
2. Make your tags highly relevant
   1. Consider: what’s the table really about?  What’s the table used for?  Where’s the data sourced from? 
   2. A single tag should denote a single concept 
   3. You can create tags to describe tables based on 
      1. Topic (e.g. healthcare)
      2. Purpose (e.g. reporting)
      3. Stage of a data pipeline (e.g. sandbox, released, production) 
      4. Source (e.g. public)
      5. Frequency of usage (e.g. daily, monthly) 
      6. Timeliness (e.g. Q1) 
3. Keep the number of tags small
   1. Consider: is it really critical to have both Important and a Not Important tag? 
   2. Use existing tags whenever possible
   3. Make sure tags are spelled correctly 
4. Keep tags short
   1. A couple of words or a short phrase will do (3 words is too many) 
   2. You can always tag a table with multiple tags 
      1. E.g. tag a table with Q1 and Reporting to describe tables used for Q1 reporting