# 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)`
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` |


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
  * **High-risk**: Content meeting multiple risk criteria
4. **Additional Filters** (if available in your project)
  * Cohorts
  * Entities
  * Engagement ranges
  * Location spoofing indicators
  * Authenticity scores


### 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)


## 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 (read-only)
* `platform:x` - Filter by platform in the query (aggregate)
* `author.followers:>1000` - Authors with many followers (filterable)
* `lang:en` - Filter by language (filterable)


### 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 (Publicly Filterable)

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


#### Author Fields

**Publicly Filterable:**

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


**Read-Only:**

* `author.username` - Author's handle/username (string, read-only in queries)


**Hidden (Not Available in Public Queries):**

* `author.verified` - Verified status (hidden)


#### Aggregate/ID Fields

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


#### Narrative/Story Fields (Publicly Filterable)

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


#### Hidden Fields (Internal Use Only)

These fields exist but are **NOT available** in public queries:

* `engagement.total`, `engagement.likes`, `engagement.score` - All engagement metrics
* `emotion.anger`, `emotion.fear` - Emotion scores
* `toxicity.toxic` - Toxicity score
* `isExtended` - Extended content flag
* `narrative.botPostPercentage` - Bot percentage in narrative
* `author.verified` - Verification status
* `cluster` - Cluster identifier


**Field Access Levels:**

* **filter (public)** - Can be used in queries with `:` syntax
* **aggregate** - Can be used for grouping and filtering
* **read** - Display only, limited query use
* **hidden** - Not available in public API queries


**Important:** If you try to use a hidden field in your query, it will not filter results. Only use fields marked as "filter" (public) or "aggregate" in your queries.
NOTE: Fields can be exposed for search. We started with the most commonly used fields. If other fields are needed, please notify Product team.

## 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

### 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"


**Two Options:**

1. **Update Segment** (Save icon)
  * Overwrites the existing segment with new values
  * Click the Save icon (becomes enabled when modified)
2. **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
* 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


### URL Sync

* Active segments are reflected in the browser URL
* You can bookmark URLs with segments applied
* Page refresh maintains your active segment


## 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. **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. **Create templates**
  * Save base segments for recurring analyses
  * Clone by loading → modifying → saving as new
3. **Use the dirty state indicator**
  * Teal border = unsaved changes
  * Update immediately or revert if experimenting


### 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 `"`


### "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 |
| 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 |
| 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: Not directly in the current version. Best practice: save as a new segment with the desired name, then delete the old one.

## Summary

The Segment Bar is your command center for data exploration:

* **Search** with powerful boolean queries
* **Filter** with multi-dimensional criteria
* **Save** successful searches as segments
* **Reuse** segments across sessions and pages


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