Skip to content
🐙 BunSqStat

Search Guide

This guide covers BunSqStat’s powerful search capabilities powered by Redis Search.

Quick Start

Section titled “Quick Start”
Section titled “Basic Search”
# Search in all fields
google


# Search specific field
@url:google.com


# Combine searches
@user:alice @method:GET
Section titled “Advanced Search”
# Numeric ranges
@resultStatus:[200 299] @size:[1000 +inf]


# Wildcards and patterns
@clientIP:192.168.*


# Complex queries
(@url:facebook.com | @url:twitter.com) @resultStatus:[400 499]

Search Field Types

Section titled “Search Field Types”

BunSqStat uses different field types for optimal search performance:

FieldTypeDescriptionSearch Examples
clientIPTAGIP addresses@clientIP:{192.168.1.1}
userTAGUser identifiers@user:alice
methodTAGHTTP methods@method:GET
urlTEXTURLs (full-text)@url:google
contentTypeTEXTMIME types@contentType:image
resultStatusNUMERICHTTP status codes@resultStatus:[200 299]
sizeNUMERICResponse sizes@size:[1000 +inf]
timestampNUMERICUnix timestamps@timestamp:[1640995200 1641081600]
durationNUMERICRequest duration@duration:[0 1000]

Field-Specific Search Syntax

Section titled “Field-Specific Search Syntax”

TAG Fields (Exact Matching)

Section titled “TAG Fields (Exact Matching)”

TAG fields require exact matching and special character escaping.

IP Addresses (clientIP)

Section titled “IP Addresses (clientIP)”
# Exact IP
@clientIP:{192\\.168\\.1\\.1}


# IP range with wildcards (use TEXT search instead)
@clientIP:192*168*1*


# Multiple IPs
@clientIP:{192\\.168\\.1\\.1|10\\.0\\.0\\.1}

Users (user)

Section titled “Users (user)”
# Exact user
@user:alice


# Multiple users
@user:{alice|bob|charlie}


# Users with special characters
@user:{user\\@domain\\.com}

HTTP Methods (method)

Section titled “HTTP Methods (method)”
# Single method
@method:GET


# Multiple methods
@method:{GET|POST|PUT}


# Exclude method
-@method:OPTIONS

TEXT Fields (Full-Text Search)

Section titled “TEXT Fields (Full-Text Search)”

TEXT fields support full-text search with stemming and fuzzy matching.

URLs (url)

Section titled “URLs (url)”
# Contains word
@url:google


# Exact phrase
@url:"google.com"


# Wildcard
@url:*.google.com


# Multiple terms (AND)
@url:(facebook social)


# Multiple terms (OR)
@url:(facebook|twitter)


# Fuzzy search (up to 2 character differences)
@url:%googl%

Content Type (contentType)

Section titled “Content Type (contentType)”
# Image files
@contentType:image


# Specific MIME type
@contentType:"image/jpeg"


# Text content
@contentType:(text|html|css|javascript)

NUMERIC Fields (Range Queries)

Section titled “NUMERIC Fields (Range Queries)”

NUMERIC fields use range syntax for filtering.

Status Codes (resultStatus)

Section titled “Status Codes (resultStatus)”
# Exact status
@resultStatus:[200 200]


# Success codes (2xx)
@resultStatus:[200 299]


# Client errors (4xx)
@resultStatus:[400 499]


# Server errors (5xx)
@resultStatus:[500 599]


# Not found
@resultStatus:[404 404]


# Greater than 400
@resultStatus:[400 +inf]


# Less than 400
@resultStatus:[-inf 399]

Response Size (size)

Section titled “Response Size (size)”
# Exact size
@size:[1024 1024]


# Small responses (< 1KB)
@size:[0 1023]


# Medium responses (1KB - 1MB)
@size:[1024 1048576]


# Large responses (> 1MB)
@size:[1048577 +inf]


# Empty responses
@size:[0 0]

Timestamps (timestamp)

Section titled “Timestamps (timestamp)”
# Last hour (Unix timestamps)
@timestamp:[1640995200 1640998800]


# Today (assuming current timestamp is 1641081600)
@timestamp:[1641081600 +inf]


# Specific date range
@timestamp:[1640995200 1641081600]

Advanced Query Syntax

Section titled “Advanced Query Syntax”

Boolean Operators

Section titled “Boolean Operators”

AND (Default)

Section titled “AND (Default)”
# All conditions must match (default behavior)
@user:alice @method:GET
@user:alice AND @method:GET

OR

Section titled “OR”
# Any condition can match
@user:alice | @user:bob
@method:{GET|POST}

NOT

Section titled “NOT”
# Exclude results
-@method:OPTIONS
NOT @resultStatus:[404 404]


# Complex exclusion
@url:google -@resultStatus:[400 499]

Grouping and Precedence

Section titled “Grouping and Precedence”
# Group conditions with parentheses
(@user:alice | @user:bob) @method:GET


# Complex grouping
(@url:facebook.com | @url:twitter.com) (@resultStatus:[200 299] | @resultStatus:[300 399])


# Nested groups
((@user:alice @method:GET) | (@user:bob @method:POST)) -@resultStatus:[500 599]

Wildcards and Patterns

Section titled “Wildcards and Patterns”

Wildcards in TAG Fields

Section titled “Wildcards in TAG Fields”
# Use TEXT-style search for wildcards in TAG fields
@clientIP:192*168*1*


# Or escape and use exact matching
@clientIP:{192\\.168\\.1\\.*}

Patterns in TEXT Fields

Section titled “Patterns in TEXT Fields”
# Prefix matching
@url:http*


# Suffix matching
@url:*.com


# Contains pattern
@url:*google*


# Single character wildcard
@url:googl?
Section titled “Fuzzy Search”
# Fuzzy search (Levenshtein distance)
@url:%googl%      # Matches "google", "goggle", etc.
@user:%alic%      # Matches "alice", "alica", etc.


# Control fuzzy distance
@url:%{googl}%1   # Max 1 character difference
@url:%{googl}%2   # Max 2 character differences

Query Examples

Section titled “Query Examples”

Common Use Cases

Section titled “Common Use Cases”

Monitor Specific Users

Section titled “Monitor Specific Users”
# All requests from user alice
@user:alice


# Multiple users
@user:{alice|bob|charlie}


# User activity in last hour
@user:alice @timestamp:[1640995200 +inf]

Track Errors

Section titled “Track Errors”
# All 4xx errors
@resultStatus:[400 499]


# 5xx server errors
@resultStatus:[500 599]


# Specific error
@resultStatus:[404 404]


# Errors from specific IP
@clientIP:{192\\.168\\.1\\.1} @resultStatus:[400 599]

Monitor High Traffic

Section titled “Monitor High Traffic”
# Large responses (>1MB)
@size:[1048577 +inf]


# Slow requests (>5 seconds, assuming duration in ms)
@duration:[5000 +inf]


# High volume IPs (combine with aggregation)
@clientIP:{192\\.168\\.1\\.*}

Content Analysis

Section titled “Content Analysis”
# Image requests
@contentType:image


# JavaScript and CSS
@contentType:(javascript|css)


# Video streaming
@contentType:video @size:[10485760 +inf]


# Social media sites
@url:(facebook|twitter|instagram|linkedin)

Security Monitoring

Section titled “Security Monitoring”
# Suspicious activity patterns
@method:POST @resultStatus:[401 403]


# Potential attacks
@url:(*admin*|*login*|*wp-admin*) @resultStatus:[401 404]


# Large POST requests
@method:POST @size:[1048576 +inf]


# Multiple error attempts from same IP
@clientIP:{192\\.168\\.1\\.1} @resultStatus:[400 499]

Complex Queries

Section titled “Complex Queries”

Business Hours Analysis

Section titled “Business Hours Analysis”
# Business hours (9 AM - 5 PM UTC, adjust timestamps accordingly)
@timestamp:[1640962800 1640995200]


# Weekend traffic
@timestamp:[1640995200 1641168000]


# Combine with user activity
@timestamp:[1640962800 1640995200] (@user:alice | @user:bob)

Performance Analysis

Section titled “Performance Analysis”
# Fast successful requests
@resultStatus:[200 299] @duration:[0 1000]


# Slow requests to specific domain
@url:*.example.com @duration:[5000 +inf]


# Large successful downloads
@resultStatus:[200 299] @method:GET @size:[10485760 +inf]

Content Delivery Analysis

Section titled “Content Delivery Analysis”
# Static content
@url:(*.css|*.js|*.png|*.jpg|*.gif) @method:GET


# Dynamic content
-@url:(*.css|*.js|*.png|*.jpg|*.gif) @method:{GET|POST}


# CDN effectiveness
@url:cdn.* @resultStatus:[200 299] @size:[1024 +inf]

Search Performance Tips

Section titled “Search Performance Tips”

Field Selection

Section titled “Field Selection”
  • Use TAG fields for exact matching (IPs, users, methods)
  • Use TEXT fields for partial/fuzzy matching (URLs, content)
  • Use NUMERIC fields for ranges (status, size, timestamp)

Query Optimization

Section titled “Query Optimization”
# Good: Specific field searches
@user:alice @method:GET


# Better: Use TAG fields for exact matches
@user:alice @method:GET @resultStatus:[200 200]


# Best: Combine with time ranges to limit scope
@user:alice @method:GET @timestamp:[1640995200 +inf]

Index Considerations

Section titled “Index Considerations”
  • TAG fields are fastest for exact matching
  • TEXT fields support full-text features but are slower
  • NUMERIC fields are optimized for range queries
  • Combine field types strategically

Error Handling

Section titled “Error Handling”

Common Search Errors

Section titled “Common Search Errors”
# Syntax error in query
Query syntax error near '@user:alice @method:'


# Invalid field name
No such field 'invalidField'


# Invalid numeric range
Invalid numeric range: [invalid +inf]


# Unmatched parentheses
Query syntax error: unmatched parentheses

Debugging Queries

Section titled “Debugging Queries”
# Test simple field searches first
@user:alice


# Build complexity gradually
@user:alice @method:GET


# Add ranges last
@user:alice @method:GET @timestamp:[1640995200 +inf]

Search API Integration

Section titled “Search API Integration”

REST API Queries

Section titled “REST API Queries”
Terminal window
# Basic search
curl "http://localhost:3001/api/search?q=@user:alice"


# With pagination
curl "http://localhost:3001/api/search?q=@user:alice&offset=0&limit=50"


# Complex query (URL encoded)
curl "http://localhost:3001/api/search?q=%40user%3Aalice%20%40method%3AGET"

Frontend Integration

Section titled “Frontend Integration”
// Using the search utility
import { buildSearchQuery } from '@/utils/search'


const query = buildSearchQuery({
  user: 'alice',
  method: 'GET',
  resultStatus: [200, 299]
})
// Results: "@user:alice @method:GET @resultStatus:[200 299]"

Aggregation and Analytics

Section titled “Aggregation and Analytics”

While Redis Search provides the base querying, BunSqStat extends with analytics:

Time-based Analysis

Section titled “Time-based Analysis”
# Group by hour
@timestamp:[1640995200 +inf] GROUP_BY timestamp


# Daily trends
@user:alice GROUP_BY DATE(timestamp)

Statistical Analysis

Section titled “Statistical Analysis”
# Top users by request count
GROUP_BY user ORDER_BY COUNT DESC


# Average response sizes
@method:GET AVG(size)


# Error rate analysis
@resultStatus:[400 599] / @resultStatus:[200 599]

For more advanced analytics, see API Reference and Testing Guide.