Creating Listening Projects

Advanced Query Building

Use advanced search syntax for field targeting, phrases, fuzzy matching, wildcards, proximity, boosting, and expert exclusions.

# Advanced Query Building

Use advanced query syntax for precise searches with field targeting, nested objects, fuzzy matching, proximity, boosting, and expert exclusions.

Advanced Query Building is intended for users who need more control than the visual Query Builder provides. Kommon Poll supports advanced query syntax that allows you to target specific fields within the mention schema for more accurate searches.

Use this guide when you need to:

  • Search specific content fields.
  • Target author information.
  • Search media metadata.
  • Search extracted entities.
  • Handle spelling variations and typos.
  • Search nearby words using proximity.
  • Boost important terms.
  • Exclude unwanted matches.
Important: Advanced query syntax is strict. Invalid punctuation, unmatched quotes, or malformed field expressions may cause the query to fail. If you're unsure, use the visual Query Builder instead.

# 1. Wildcards

Wildcards allow matching unknown characters inside a word.

Leading or trailing wildcards are not supported.

Do not use:

*bank
pay*
?card
bank?

Use wildcards only within a word.

Syntax Meaning Example
* Zero or more characters colo*r
? Exactly one character wom?n

Example:

colo*r AND packaging

matches both:

  • color
  • colour

# 2. Fuzzy Matching

Fuzzy matching helps catch misspellings and OCR variations.

Syntax Meaning
term~ Default fuzziness
term~1 One edit allowed
term~2 Two edits allowed

Example:

(KommonPoll OR "Kommon Poll" OR komonpoll~1)

Avoid combining fuzzy matching with wildcards.

Do not use:

kom*on~1

# 3. Proximity Matching

Proximity matching searches for words occurring close together.

Example:

"credit card declined"~5

Field example:

content.text:"app not working"~4

# 4. Field-Specific Search

Content Fields

Need Field Example
Main text content.text content.text:"mobile app not working"
Clean text content.clean content.clean:(delivery AND delayed)
Title content.title content.title:(fraud OR scam)
Parent text content.parent_text content.parent_text:"bank charges"
Actions content.actions content.actions:(reply OR comment)
Language content.language.code content.language.code:en
Hashtags content.hashtags content.hashtags:(kommonpoll OR sociallistening)
Tags content.tags content.tags:(OpenAI OR Microsoft)
Key phrases content.key_phrases content.key_phrases:"customer service"
CTA text content.cta.text content.cta.text:"Learn More"
CTA type content.cta.type content.cta.type:button
CTA subcategory content.cta.subcategory content.cta.subcategory:shopping
Emojis content.emojis content.emojis:🔥
Sponsored content.is_sponsored content.is_sponsored:true
Post type content.post_type content.post_type:video
Reshared text content.reshared_text content.reshared_text:"Breaking News"

Author Fields

Need Field Example
Username author.username author.username:"john_doe"
Display name author.name author.name:"Daily Mirror"
Author ID author.id author.id:"12345"
Public User ID author.public_user_id author.public_user_id:"abcd123"
Parent author author.parent_author author.parent_author:"Dialog"
Verified account author.is_verified author.is_verified:true
Business account author.is_business author.is_business:true
Followers author.followers author.followers:[1000 TO *]
Following author.following author.following:[100 TO *]
Bio author.bio author.bio:"Journalist"
Job title author.job_type author.job_type:"CEO"
Job rank author.job_rank author.job_rank:"Executive"
Gender author.gender author.gender:female
Age author.age_band author.age_band:"25-34"
Nationality author.nationality author.nationality:"Sri Lankan"
Education author.education author.education:"Graduate"
Income author.income author.income:high
Author type author.type author.type:organization

Source Fields

Need Field Example
Source URL source.url source.url:"facebook.com"
Platform source.platform source.platform:facebook
Domain source.domain source.domain:"facebook.com"
Section source.section source.section:"Kommon Poll"
Mention ID source.mention_id source.mention_id:"123456"

Media Fields

Need Field Example
Media URL media.url media.url:"cdn.image.jpg"
Media type media.type media.type:image
OCR text media.text media.text:"Limited Offer"
Description media.description media.description:"Bank queue"
Detected object media.object media.object:(car OR phone)
Logo media.logo media.logo:"Nike"

Entity Fields

Need Field Example
Companies entities.companies entities.companies:"Dialog"
Persons entities.persons entities.persons:"Elon Musk"
Products entities.products entities.products:"iPhone"
Events entities.events entities.events:"Launch"
Locations entities.locations entities.locations:"Colombo"
Person groups entities.person_groups entities.person_groups:"Politicians"

Entity Sentiments

Need Field
Entity entities.entity_sentiments.entity
Adjective entities.entity_sentiments.adjective
Sentiment entities.entity_sentiments.sentiment

Geo Fields

Need Field
Country geo.country_code
Location geo.location_name
Coordinates geo.point

Time Fields

Need Field
Published time time.published_at
Collected time time.collected_at
Ingested time time.ingested_at
Published day time.published_day_of_week
Published hour time.published_hour

Metrics Fields

Need Field
Likes metrics.likes
Comments metrics.comments
Shares metrics.shares
Views metrics.views
Interactions metrics.interactions
Quotes metrics.quotes
Downloads metrics.downloads
Bookmarks metrics.bookmarks
Saved metrics.saved
Total reactions metrics.total_reactions
Upvote ratio metrics.up_vote_ratio

Context Fields

Need Field
Priority contexts.priority
Scam contexts.is_scam
Deleted contexts.is_deleted
Processed contexts.is_processed
Intent labels contexts.intent_labels
Tags contexts.tags
Context polarity contexts.contexts_polarity
Subtopics contexts.subtopic_ids

# 5. Use Filters for Structured Attributes

Whenever possible, use Kommon Poll filters instead of advanced query syntax.

Recommended filters include:

  • Platform
  • Country
  • Language
  • Gender
  • Age
  • Education
  • Income
  • Nationality
  • Business Account
  • Verified Account
  • Sentiment
  • Subjectivity
  • Date Range

These filters are optimized for structured data and generally provide better performance than field-based queries.

# 6. Boosting

Boosting increases the relevance score of matching documents without making the term mandatory.

Examples:

Dialog^2 outage
"customer service"^3 complaint
content.title:fraud^3 OR content.text:fraud

# 7. Escaping Reserved Characters

The following characters have special meaning:

+ - = && || > < ! ( ) { } [ ] ^ " ~ * ? : \ /

Escape them with a backslash (\) when searching literally.

Example:

2\*3

# 8. Practical Examples

Customer Complaint

content.text:("mobile app" AND crash) AND source.platform:google_play

Company Mentions

entities.companies:"Dialog"

Verified Authors

author.is_verified:true
source.platform:instagram AND content.is_sponsored:true

Media Logo Detection

media.logo:"Nike"

Banking Discussions

(content.text:(loan OR mortgage) AND entities.companies:"Commercial Bank")

# 9. Advanced Query Checklist

Before saving your query:

  • Wrap multi-word phrases in quotation marks.
  • Use parentheses when combining AND, OR, and NOT.
  • Do not use leading or trailing wildcards.
  • Do not combine fuzzy matching and wildcards.
  • Use filters whenever possible for structured fields.
  • Test queries using a short date range first.
  • Save a working version before making major changes.