Tags & Favorites

Organize and bookmark queries using tags and favorites.

Tags

Tags help categorize and filter queries across your organization.

GET /api/queries/{id}/tags

Get all tags assigned to a query.

Authentication: Required

Path Parameters:

Parameter	Type	Description
id	string	Query ID (UUID) or natural ID

Response:

{
  "_links": {
    "self": { "href": "/api/queries/{id}/tags" }
  },
  "_embedded": {
    "inf:tag-entity": [
      {
        "tagId": "finance",
        "queryId": "550e8400-e29b-41d4-a716-446655440000",
        "tag": {
          "id": "finance",
          "name": "Finance",
          "color": "#3498db",
          "description": "Financial reporting queries"
        }
      },
      {
        "tagId": "quarterly",
        "queryId": "550e8400-e29b-41d4-a716-446655440000",
        "tag": {
          "id": "quarterly",
          "name": "Quarterly",
          "color": "#2ecc71"
        }
      },
      {
        "tagId": "revenue",
        "queryId": "550e8400-e29b-41d4-a716-446655440000",
        "tag": {
          "id": "revenue",
          "name": "Revenue",
          "color": "#f39c12"
        }
      }
    ]
  },
  "start": 0,
  "count": 3,
  "total": 3
}

---

GET /api/queries/{id}/tags/{tagId}

Get a specific tag assignment for a query.

Authentication: Required

Path Parameters:

Parameter	Type	Description
id	string	Query ID (UUID) or natural ID
tagId	string	Tag identifier

Response:

{
  "tagId": "finance",
  "queryId": "550e8400-e29b-41d4-a716-446655440000",
  "_embedded": {
    "inf:tag": {
      "id": "finance",
      "name": "Finance",
      "color": "#3498db"
    }
  }
}

Returns 404 if tag is not assigned to the query.

---

PUT /api/queries/{id}/tags/{tagId}

Assign a tag to a query.

Authentication: Required Permission: query:assignTags

Path Parameters:

Parameter	Type	Description
id	string	Query ID (UUID) or natural ID
tagId	string	Tag identifier

Response:

Returns 200 OK with the tag assignment.

{
  "tagId": "finance",
  "queryId": "550e8400-e29b-41d4-a716-446655440000"
}

Creating Tags

If the tag doesn't exist, you'll receive a 404. Create tags first using POST /api/tags before assigning them.

---

DELETE /api/queries/{id}/tags/{tagId}

Remove a tag from a query.

Authentication: Required Permission: query:assignTags

Path Parameters:

Parameter	Type	Description
id	string	Query ID (UUID) or natural ID
tagId	string	Tag identifier

Response:

Returns 204 No Content on success.

---

Favorites

Mark queries as favorites for quick access.

GET /api/queries/{id}/favorite

Check if a query is favorited by the current user.

Authentication: Required

Path Parameters:

Parameter	Type	Description
id	string	Query ID (UUID) or natural ID

Response:

{
  "queryId": "550e8400-e29b-41d4-a716-446655440000",
  "userId": "current.user",
  "createdAt": "2024-02-09T10:00:00Z"
}

Returns 404 if query is not favorited.

---

PUT /api/queries/{id}/favorite

Mark a query as favorite for the current user.

Authentication: Required

Path Parameters:

Parameter	Type	Description
id	string	Query ID (UUID) or natural ID

Response:

Returns 200 OK with the favorite record.

{
  "queryId": "550e8400-e29b-41d4-a716-446655440000",
  "userId": "current.user",
  "createdAt": "2024-02-09T11:30:00Z"
}

---

DELETE /api/queries/{id}/favorite

Remove a query from favorites.

Authentication: Required

Path Parameters:

Parameter	Type	Description
id	string	Query ID (UUID) or natural ID

Response:

Returns 204 No Content on success.

---

Tagging Best Practices

Tag Categories

Create a taxonomy of tags for different purposes:

Category	Examples	Use Case
Department	finance, sales, marketing, hr	Organize by department
Purpose	reporting, analysis, export, audit	Categorize by use case
Frequency	daily, weekly, monthly, quarterly	Track update cadence
Status	draft, reviewed, production, deprecated	Manage lifecycle
Data Source	mysql, postgres, salesforce, api	Filter by source

Naming Conventions

1. Lowercase - Use lowercase for consistency
2. Hyphens - Use hyphens for multi-word tags: sales-pipeline
3. Singular - Use singular form: report not reports
4. Specific - Be specific: q4-revenue not revenue
5. Short - Keep tags concise: fy24 not fiscal-year-2024

Multi-Tag Strategy

// Assign multiple tags to categorize comprehensively
PUT /api/queries/my-query/tags/finance
PUT /api/queries/my-query/tags/quarterly
PUT /api/queries/my-query/tags/revenue
PUT /api/queries/my-query/tags/production

Now the query can be found by:

• Department filter: finance
• Frequency filter: quarterly
• Topic filter: revenue
• Status filter: production

Tag Cleanup

Regularly review and merge similar tags:

// Find all queries with old tag
GET /api/queries?tag=old-tag

// Reassign to new tag
for (query in queries) {
  PUT /api/queries/{query.id}/tags/new-tag
  DELETE /api/queries/{query.id}/tags/old-tag
}

// Delete old tag
DELETE /api/tags/old-tag

---

Favorites Best Practices

When to Favorite

Scenario	Action
Frequently used queries	Favorite for quick access
Monitoring queries	Favorite to check regularly
Template queries	Favorite for copying
Important references	Favorite for easy finding

Organizing Favorites

Combine favorites with tags for organization:

1. Favorite queries you use often
2. Tag them by category
3. Filter favorites by tag in UI

GET /api/users/me/favorites?type=query&tag=daily

Favorite Limits

While there's no hard limit on favorites, consider:

• Too many favorites defeat the purpose
• Regularly review and remove outdated favorites
• Use folders or tags instead for large collections
• Aim for < 20 favorites for optimal usability

---

Filtering Queries

By Tag

# Get all finance queries
GET /api/queries?tag=finance

# Get all quarterly finance queries
GET /api/queries?tag=finance,quarterly

By Favorite Status

# Get current user's favorite queries
GET /api/users/me/favorites?type=query

# Get favorite queries with specific tag
GET /api/users/me/favorites?type=query&tag=daily

Combined Filters

# Favorite queries in finance department using MySQL
GET /api/users/me/favorites?type=query&tag=finance&datasource=mysql-prod

---

Tag Management Workflow

Initial Setup

1. Define Taxonomy - Decide on tag categories and naming
2. Create Tags - Use POST /api/tags to create tag library
3. Document Tags - Add descriptions explaining tag purpose
4. Set Colors - Assign colors for visual distinction

Ongoing Maintenance

1. Review Quarterly - Audit tags for consistency
2. Merge Duplicates - Combine similar tags
3. Update Colors - Refresh color scheme if needed
4. Archive Unused - Remove tags with zero usage

Bulk Operations

// Tag all queries from a specific datasource
const queries = await GET('/api/queries?datasource=mysql-prod');
for (const query of queries.items) {
  await PUT(`/api/queries/${query.id}/tags/mysql`);
}

Tag Permissions

The assignTags permission is separate from write permission. This allows team members to organize content without editing it.