Comments

Add and manage comments on queries for collaboration and documentation.

GET /api/queries/{id}/comments

Get all top-level comments for a query.

Authentication: Required

Path Parameters:

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

Query Parameters:

Parameter	Type	Default	Description
sort	string	-createdAt	Sort order
limit	integer	-	Results per page

Response:

{
  "_links": {
    "self": { "href": "/api/queries/{id}/comments" }
  },
  "_embedded": {
    "inf:comment": [
      {
        "id": "comment-uuid-1",
        "queryId": "550e8400-e29b-41d4-a716-446655440000",
        "userId": "john.doe",
        "username": "john.doe",
        "message": "Updated the date filter to use a parameter instead of hardcoded value.",
        "parentId": null,
        "createdAt": "2024-02-09T10:30:00Z",
        "updatedAt": "2024-02-09T10:30:00Z",
        "_links": {
          "self": { "href": "/api/comments/comment-uuid-1" },
          "inf:comments": { "href": "/api/comments/comment-uuid-1/replies" }
        },
        "_embedded": {
          "inf:user": {
            "username": "john.doe",
            "displayName": "John Doe",
            "email": "john.doe@company.com"
          }
        }
      },
      {
        "id": "comment-uuid-2",
        "queryId": "550e8400-e29b-41d4-a716-446655440000",
        "userId": "jane.smith",
        "message": "Can we add a region filter as well?",
        "parentId": null,
        "createdAt": "2024-02-08T14:15:00Z",
        "_embedded": {
          "inf:user": {
            "username": "jane.smith",
            "displayName": "Jane Smith"
          }
        }
      }
    ]
  },
  "start": 0,
  "count": 2,
  "total": 5
}

Nested Comments

This endpoint returns only top-level comments (where parentId is null). To get replies, follow the inf:comments link for each comment.

---

POST /api/queries/{id}/comments

Add a new comment to a query.

Authentication: Required

Path Parameters:

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

Request Body:

{
  "message": "This query is running slower than expected. Consider adding an index on the date column."
}

Validation:

Field	Type	Required	Description
message	string	Yes	Comment text

Response:

Returns the created comment with 201 Created status and Location header.

{
  "id": "new-comment-uuid",
  "queryId": "550e8400-e29b-41d4-a716-446655440000",
  "userId": "current.user",
  "message": "This query is running slower than expected...",
  "parentId": null,
  "createdAt": "2024-02-09T11:00:00Z",
  "updatedAt": "2024-02-09T11:00:00Z",
  "_links": {
    "self": { "href": "/api/comments/new-comment-uuid" }
  }
}

Activity Tracking:

Creating a comment triggers a queryAddedComment activity entry.

---

Comment Best Practices

When to Use Comments

Use Case	Example
Document changes	"Updated query to use new customer table"
Ask questions	"Should we filter out deleted records?"
Share insights	"This query returns duplicate rows for multi-tag items"
Request reviews	"Please review before promoting to production"
Performance notes	"Added index on date_field, reduced runtime by 50%"

Comment Guidelines

1. Be Specific - Reference field names, parameter values, or line numbers
2. Add Context - Explain why changes were made
3. Tag Users - Mention users by name when requesting feedback
4. Link Resources - Reference related queries, datasets, or documentation
5. Update Status - Follow up when issues are resolved

Example Workflows

Code Review:

POST /api/queries/my-query/comments
{
  "message": "@jane.smith Can you review the new JOIN clause? I'm seeing unexpected results for customers with multiple addresses."
}

Change Documentation:

POST /api/queries/my-query/comments
{
  "message": "Migration to new datasource complete. Updated connection from 'old-db' to 'new-db'. All tests passing."
}

Performance Note:

POST /api/queries/my-query/comments
{
  "message": "Benchmark: 2.5s → 0.8s after adding composite index on (region, date). See ticket #1234 for details."
}

---

Managing Comments

Viewing Comment Threads

# Get top-level comments
GET /api/queries/my-query/comments

# Get replies to a specific comment
GET /api/comments/{commentId}/replies

Editing Comments

# Update comment text
PATCH /api/comments/{commentId}
{
  "message": "Updated comment text"
}

Deleting Comments

# Remove a comment
DELETE /api/comments/{commentId}

Comment Permissions

Only the comment author or query owner can edit/delete comments. Team admins may also have access depending on team settings.

---

Comment Integration

With Drafts

Comments on the original query remain visible when viewing drafts. Draft-specific discussions should use separate comments on the draft query ID.

With Activity Feed

Comments appear in the query's activity feed and can be filtered:

GET /api/queries/my-query/activity?type=comment

With Notifications

Users can be notified of new comments via:

• Email notifications
• In-app notifications
• Activity feed updates

Mentions

Comments support @mentions to notify specific users. Mentioned users receive notifications even if they're not subscribed to the query.