# Segment Bar User Guide

## Overview

The **Segment Bar** is a powerful filtering and search tool that helps you build, save, and reuse complex queries to find relevant social media posts and news articles in your datasets. Think of it as a smart search bar combined with advanced filters that remembers your work.

### What You Can Do

* **Search** using boolean queries with AND, OR, NOT operators
* **Filter** by platform, date range, risk signals, and custom classifiers
* **Save** your searches as reusable "segments"
* **Switch** between pages while keeping your filters active


## Getting Started

### Basic Search

The simplest way to use the Segment Bar is to type a search query:

1. **Type your search terms** in the query field
  * Example of a keyword: `climate`
  * Example of a phrase: `"climate change"`
  * Example with operators: `"climate change" AND (policy OR regulation)`
  * Example with wildcard: `climat*` (matches climate, climatic, etc.)
2. **Click "Apply"** or press **Enter** to run the search
3. **View results** below the filter bar


### Search Operators

The query field supports boolean logic:

| Operator | Purpose | Example |
|  --- | --- | --- |
| **AND** | Both terms must appear | `climate AND policy` |
| **OR** | Either term can appear | `climate OR environment` |
| **NOT** | Exclude terms | `climate AND NOT hoax` |
| **"quotes"** | Exact phrase match | `"climate change"` |
| **(parentheses)** | Group operations | `(climate OR environment) AND policy` |
| ***** | Wildcard match | `climat*` (matches climate, climatic, etc.) |


NOTE: The NOT operator must be used in conjunction with AND to denote the relationship with the preceding term.

Example:

```
policy AND NOT conspiracy
```

**Pro Tip:** Operators must be in UPPERCASE (AND, OR, NOT) to be recognized.

## Adding Filters

Beyond text search, you can narrow results using dropdown filters:

### Available Filters

1. **Date Range**
  * Click the calendar icon
  * Choose from quick presets (Last 7 days, Last 30 days, etc.)
  * Or select custom start/end dates
  * Click **Apply** to activate
2. **Platforms**
  * Select which social media platforms to include
  * Options: X (Twitter), Facebook, Instagram, Reddit, etc.
  * Multiple selections allowed
  * Shows post counts when available
3. **Risk Signals** (Proprietary Classifiers)
  * **Bot-like**: Content from automated or suspicious accounts
  * **Toxic**: Content flagged for harmful language
4. **Additional Filters** (if available in your project)
  * Cohorts
  * Entities
  * Engagement ranges
  * Location spoofing indicators


### How Filters Work Together

* All filters use **AND** logic: posts must match ALL active filters
* Example: `Platform = X AND Date Range = Last 7 days AND Risk Signal = Bot-like`
* Active filters appear as removable pills below the search bar


### Removing Filters

* **Individual**: Click the **×** on any filter pill
* **All at once**: Click "Clear Segment" (see Segments section below)


### Toggle Filters On/Off

You can temporarily disable filters without removing them:

* **Click the eye icon** on any filter pill to toggle it off (grayed out)
* **Click the eye icon again** to toggle it back on
* This allows you to validate "before and after" results without losing your filter configuration


## Field-Specific Search (Advanced)

You can search within specific data fields using the format `fieldName:value`

### Auto-Suggest Fields

When you type in the query editor, field suggestions appear automatically:

1. Start typing a field name (e.g., `auth`)
2. Dropdown shows matching fields with descriptions
3. Use **Arrow keys** to navigate suggestions
4. Press **Enter** or **Tab** to insert the field name with `:`
5. Type your search value after the colon


**Example Fields:**

* `author.username:john_doe` - Search for posts by specific authors
* `platform:x` - Filter by platform in the query
* `author.followers:>1000` - Authors with many followers
* `lang:en` - Filter by language


### Field Search Syntax

```
fieldName:searchValue
fieldName:"exact phrase"
fieldName:>100 (numeric comparison)
```

**Combined Example:**

```
(climate OR environment) AND author.displayName:"EPA" AND author.followers:>500
```

### Available Field Types

The system provides access to fields across different entity types. Here are the fields available for filtering:

#### Post Content Fields

* `text` - Main text content of the post (string)
* `title` - Post title for Reddit/articles (string)
* `body` - Body text, separate from title (string)
* `lang` - Detected language code (e.g., "en", "es") (string)


#### Author Fields

* `author.displayName` - Author's display name (string)
* `author.followers` - Follower count (integer)
* `author.following` - Following count (integer)
* `author.isBotLike` - Bot-like behavior flag (boolean)
* `author.platform` - Author's platform (string)
* `author.postCount` - Total posts by author (integer)
* `author.profileBio` - Author's bio/description (string)
* `author.cohorts` - Author classification cohorts (dict_of_double)
  * Query as: `author.cohorts:LabelName>=0.5`
* `author.username` - Author's handle/username (string)


#### Aggregate/ID Fields

* `platform` - Platform where post originated (string)
* `authorId` - Unique author identifier (string)
* `postId` - Unique post identifier (string)
* `createdAt` - Post creation timestamp (timestamp)
* `narrativeId` - Unique narrative identifier (string)


#### Narrative/Story Fields

* `narrative.title` - Narrative title (string)
* `narrative.postCount` - Posts in narrative (long)
* `narrative.compassHeadline` - AI-generated headline (string)
* `narrative.compassOneSentence` - One-sentence summary (string)
* `narrative.compassSummary` - Full summary (string)
* `narrative.executiveBriefing` - Executive briefing text (string)
* `narrative.totalEngagement` - Total engagement in narrative (long)
* `narrative.totalEngagementWithoutNews` - Engagement excluding news (long)
* `narrative.weightedRiskScore` - Risk score (double)


## Working with Multi-Line Queries

For complex queries, you can expand the editor to multiple lines:

### Auto-Expansion

* The query field automatically grows as you type
* Scrolling enabled if content exceeds max height


### Collapse/Expand Toggle

For long queries, a **chevron button** appears in the bottom-right corner:

* **Chevron Down** (↓): Collapses query to 2-line preview
* **Chevron Up** (↑): Expands to show full query


**When to Collapse:**

* Save vertical space on your screen
* Keep other filters visible while working
* Quick overview of a complex query


**When to Expand:**

* Edit the query
* Review full logic
* When clicking into the collapsed query (auto-expands)


## Segments: Save Your Work

Segments let you save and reuse filter combinations.

### What Gets Saved in a Segment

* Search query text
* All active filters (platforms, dates, risk signals, etc.)


### Creating a Segment

1. **Build your filters** using search and/or dropdown filters
2. **Click the Save icon** (disk icon) in the top-right
3. **Name your segment** in the dialog
4. **Click Save**


**Result:** Your segment appears in the segments dropdown

### Save As (Create New Segment from Existing)

You can use an existing segment as a starting point for a new segment:

1. **Load a segment** you want to use as a template
2. **Make your modifications** to the filters or query
3. **Click the down arrow** next to the Save icon
4. **Select "Save As"** from the dropdown menu
5. **Enter a name** for the new segment
6. **Click Save**


**Result:** A new segment is created with your modifications, and the original segment remains unchanged.

### Loading a Saved Segment

1. **Click the Segments dropdown** (shows current segment or "No Segment")
2. **Select a segment** from the list
3. All filters and query automatically apply


**Visual Indicator:** Selected segment name appears in the dropdown button

### Modifying a Segment

When you change any filter or query text while a segment is active:

**Dirty State Indicator:**

* Query editor border changes from **indigo** (clean) to **teal** (modified)
* Only visible when the query field is focused
* Signals "You have unsaved changes"


**Three Options:**

1. **Update Segment** (Save icon)
  * Overwrites the existing segment with new values
  * Click the Save icon (becomes enabled when modified)
2. **Save As** (Save dropdown → Save As)
  * Creates a new segment with your changes
  * Original segment remains unchanged
3. **Revert Changes** (Counter-clockwise arrow icon)
  * Discards your changes
  * Restores segment to last saved state
  * Instant action, no confirmation


### Clearing a Segment

To remove the active segment and start fresh:

1. **Click the Clear icon** (X icon) in the top-right
2. **If you have unsaved changes**, a confirmation dialog appears:
  * "Clear Segment?" with warning about discarding changes
  * Click **Clear Segment** to confirm
  * Or **Cancel** to keep working
3. **If segment is unchanged**, clearing is immediate


**Result:** All filters reset, query clears, no segment selected

### Deleting a Segment

To permanently remove a saved segment:

1. **Open the Segments dropdown**
2. **Hover over the segment** you want to delete
3. **Click the trash icon** (appears on hover)
4. **Confirm deletion**


**Warning:** This action cannot be undone. The segment is permanently deleted.

## Active Filter Pills

Below the search bar, you'll see pills representing active filters.

### What Pills Show

* **Date Range**: "Jan 1, 2024 - Jan 31, 2024"
* **Platform**: "X", "Facebook" (one pill per platform)
* **Risk Signals**: "Bot-like", "Toxic", etc.
* **Search Query**: "Search: your query text"
* **Other Filters**: Cohorts, entities, engagement ranges, etc.


### Managing Pills

* **Click the × on any pill** to remove that specific filter
* **Click the eye icon** to temporarily toggle a filter on/off without removing it
  * Toggled-off filters appear grayed out
  * Click the eye icon again to re-enable the filter
  * Useful for comparing results with and without specific filters
* Pills are color-coded by filter type for easy scanning
* No limit to number of active filters


## Navigation & Persistence

### Cross-Page Filtering

The Segment Bar **stays active** as you navigate between pages:

* Move from Posts view → Analytics → Maps
* Your filters remain applied
* Same dataset filtered across all views
* Segment selection persists


## Tips & Best Practices

### For Better Search Results

1. **Start broad, then narrow**
  * Begin with general terms
  * Add filters incrementally
  * Save successful combinations as segments
2. **Use quotes for exact phrases**
  * `"climate change"` finds the exact phrase
  * `climate change` finds posts with both words anywhere
3. **Use wildcards for variations**
  * `climat*` matches climate, climatic, climatology, etc.
  * Helpful when searching for word variations
4. **Combine operators strategically**


```
("climate change" OR "global warming") AND policy AND NOT conspiracy
```

### For Segment Management

1. **Name segments descriptively**
  * Good: "Q4 Climate Policy X Bot Analysis"
  * Less helpful: "Segment 1"
2. **Use Save As to create templates**
  * Save base segments for recurring analyses
  * Use "Save As" to create variations without modifying the original
3. **Use the dirty state indicator**
  * Teal border = unsaved changes
  * Update immediately or revert if experimenting
4. **Toggle filters to validate results**
  * Use the eye icon to temporarily disable filters
  * Compare results with and without specific criteria
  * Re-enable filters when validation is complete


### For Complex Queries

1. **Use multi-line format**
  * Break long queries across lines for readability
  * Collapse when not editing to save space
2. **Test incrementally**
  * Build complex queries piece by piece
  * Verify results at each step
3. **Leverage field search**
  * More precise than general text search
  * Use auto-suggest to discover available fields


## Troubleshooting

### "No results found"

**Check:**

* Are your filters too restrictive? Try removing some
* Is your date range too narrow? Expand it
* Are boolean operators in UPPERCASE? (AND, OR, NOT)
* Do quotes match? Every `"` needs a closing `"`
* Are any filters toggled off (grayed out with eye icon)? Re-enable them if needed


### "Segment appears modified immediately after loading"

**Possible causes:**

* Default filter values differ from segment
* Browser auto-filled a field
* Try clicking **Revert** to restore exact segment state


### "Can't save segment / Save button disabled"

**Requirements:**

* At least one filter must be active OR
* Query field must have content
* Must have project access/permissions


### "Typeahead suggestions not appearing"

**Ensure:**

* You're typing in the query field (not a dropdown)
* Field names start with lowercase letter
* Wait a moment after typing for suggestions to load


## Keyboard Shortcuts

| Action | Shortcut |
|  --- | --- |
| Apply query | **Enter** (in query field) |
| Navigate typeahead | **↑** / **↓** arrows |
| Select typeahead suggestion | **Enter** or **Tab** |
| Close typeahead | **Esc** |
| Multi-line in query | **Shift + Enter** |


## Feature State Reference

### Visual Indicators

| Indicator | Meaning | Action |
|  --- | --- | --- |
| Indigo border (focused) | Clean state, matches segment | Continue working |
| Teal border (focused) | Unsaved changes | Update or Revert |
| Filter pills below bar | Active filters | Click × to remove |
| Eye icon on pill | Toggle filter on/off | Click to disable/enable filter |
| Grayed out pill | Filter is toggled off | Click eye icon to re-enable |
| Chevron button (↓) | Query is collapsed | Click to expand |
| Chevron button (↑) | Query is expanded | Click to collapse |


### Button States

| Button | Enabled When | Action |
|  --- | --- | --- |
| Save (disk icon) | Segment modified OR no segment + filters active | Save new or update existing |
| Save dropdown arrow | Segment is active | Access Save As option |
| Revert (arrow icon) | Segment modified | Restore to saved state |
| Clear (X icon) | Segment is active | Remove segment + reset filters |
| Apply | Query text differs from applied | Run search with current query |


## FAQs

**Q: Can I have multiple segments active at once?**
A: No, only one segment can be active at a time. However, you can quickly switch between saved segments.

**Q: What happens if I close the browser with a segment active?**
A: If the segment is saved, it will reload when you return (via URL). Unsaved changes are lost.

**Q: Can I export my segments?**
A: Segments are saved to your project and persist across sessions.

**Q: Do segments work across different projects?**
A: No, segments are project-specific. Create new segments for each project.

**Q: How many segments can I save?**
A: There's no hard limit in the interface, but check with your administrator for any project quotas.

**Q: Can I rename a segment after saving?**
A: Use "Save As" to create a new segment with the desired name, then delete the old one if needed.

**Q: What's the difference between toggling a filter off and removing it?**
A: Toggling (eye icon) temporarily disables the filter but keeps it in place for quick re-enabling. Removing (× icon) completely deletes the filter from your current configuration.

## Summary

The Segment Bar is your command center for data exploration:

* **Search** with powerful boolean queries and wildcards
* **Filter** with multi-dimensional criteria
* **Save** successful searches as segments
* **Reuse** segments across sessions and pages
* **Toggle** filters on/off to validate results


Master these features to work more efficiently with large datasets and collaborate effectively with your team.

*Last Updated: March 2026*