Read, Unread, New, and Bookmarked Items

Read, Unread, New, and Bookmarked Items#

Squirro provides features to track which items have been read, identify newly created items, and bookmark important items for quick access. That functionality helps users manage content and track reading progress across projects.

Each user maintains independent read status and personal collections for items. When one user marks an item as read or adds it to a collection, it does not affect other users.

Read and Unread Items#

Items are marked as read automatically when a user opens an item in the detail view. Developers can also mark items as read programmatically using the API. For details on API usage, see to the Item Format page.

The read or unread status of an item is displayed as a badge in the item metadata section. Unread items show an “unread” badge at full opacity, while read items display a “read” badge at 50 percent opacity. This badge appears alongside other metadata, such as the creation date and source.

Users can filter search results to display only unread items. The filtering occurs at the query level, ensuring quick results even in projects with a large number of items. To apply this filter, use the search query syntax described in the Query Syntax page.

New Items#

The new item indicator helps users identify content added since their last browsing session. The system automatically determines new items by comparing the creation time of each item with the end time of the user’s previous session. No manual action is required.

New items are marked with a “new” badge in the item metadata section. The badge uses the secondary theme color, which is distinct from the colors used for read or unread badges. The new badge takes priority over read or unread indicators.

The badge is visible only for items that are both new and unread. If a user reads a new item, the new badge disappears, and the read badge is displayed instead.

Badge Display Priority#

The system displays badges according to the following priority:

  1. New and unread

    Shows “new” badge (highest priority).

  2. Read or unread

    Shows “read” or “unread” badge.

  3. No status

    No badge displayed.

This priority ensures users see the most relevant status indicator for each item.

Adjusting New Item Detection#

Adjust the new item detection using query-time parameters. Specify these parameters directly in search queries rather than through system configuration settings. These parameters require no administrative access.

Query Parameter#

min_session_age is the minimum age of a browsing session to consider (default: 1 hour). The system excludes sessions younger than that threshold from new item calculation. It prevents items from appearing as new during an active browsing session.

Where to Specify Parameters#

Specify the min_session_age parameter in multiple locations:

  • Search Queries

    Enter the parameter directly in the search interface. For example:

    profile:{is_new min_session_age:2h}

  • Dashboard Queries

    Add the parameter to the dashboard query field when configuring dashboards in the Setup space.

  • Widget Queries

    Include the parameter in the query configuration for Items widgets.

The parameter accepts time values in various units (for example: 30m for 30 minutes, 2h for 2 hours, 1d for 1 day).

For complete query syntax details, see the Query Syntax page.

Bookmarked Items and Collections#

Squirro uses a Collections-based system for bookmarking items. Users can organize important items into collections for quick access and categorization. Each user maintains personal collections that other users cannot see or modify.

The Bookmarks Collection#

Every user has access to a special system collection called Bookmarks. The Bookmarks collection appears in the collections dropdown for all users and provides a default location for saving important items without requiring collection management.

How to Bookmark Items#

Add items to collections through the following methods:

  • Item Card Interface

    Click the collections icon (folder) on the item card in the Items widget results. Select the Bookmarks collection from the dropdown menu. Items can be added to multiple collections simultaneously.

  • Item Detail View

    Click the collections icon in the item detail view header. Select the Bookmarks collection or any other collection from the dropdown menu.

  • API Methods

    Use the Collections API to add items to collections programmatically. The legacy starred flag in the API continues to work for backward compatibility and maps to the Bookmarks collection.

Collections Icon Indicator#

The collections icon on item cards displays a blue dot badge when the item belongs to one or more collections. The badge provides visual feedback showing which items have been bookmarked or organized into collections.

Viewing Bookmarked Items#

Configure the Items widget to display only bookmarked items. The widget filters for items in the Bookmarks collection, providing a dedicated view of bookmarked content.

To configure the Items widget to show bookmarked items:

  1. Navigate to the Setup space.

  2. Click the Visualization tab.

  3. Select the dashboard to configure.

  4. Add or edit an Items widget.

  5. In the widget configuration, select the Starred items radio button under Mode.

The “Starred items” mode name remains for backward compatibility. The widget displays all items in the user’s Bookmarks collection.

Query Syntax for Bookmarked Items#

Use the is:starred query syntax to filter for bookmarked items in search queries. The query syntax provides backward compatibility with the legacy starred system and filters for items in the Bookmarks collection.

Example query:

technology is:starred

For complete query syntax information, see the Query Syntax page.

For more information about the Items widget, see the Items Widget page.

Last Read Items View#

The Items widget can display the most recently read items for the current user. That view shows items in the order they were read, with the most recently read items appearing first.

The last read items view includes additional metadata:

  • Last Read Time

    The timestamp when the item was marked as read by the current user.

  • Read Count

    The number of times the current user has read the item.

To configure the Items widget to show last read items, follow the steps below:

  1. Navigate to the Setup space.

  2. Click the Visualization tab.

  3. Select the dashboard to configure.

  4. Add or edit an Items widget.

  5. In the widget configuration, select the Last read items radio button under Mode.

The number of items displayed can be controlled through query parameters. For query syntax information, see the Query Syntax page.


Contents