Query Syntax

fsPulse provides a flexible, SQL-like query language for exploring scan results. This language supports filtering, custom column selection, ordering, and limiting the number of results.

Query Structure

Each query begins with one of the five supported domains:

• roots
• scans
• items
• versions
• alerts

You can then add any of the following optional clauses:

DOMAIN [WHERE ...] [SHOW ...] [ORDER BY ...] [LIMIT ...] [OFFSET ...]

Column Availability

Each domain has a set of available columns. Columns marked as default are shown when no SHOW clause is specified.

roots Domain

scans Domain

items Domain

The items domain queries each item’s latest version — the most recent known state. Identity columns come from the items table; state columns come from the item’s current version.

versions Domain

The versions domain queries individual item version rows — each representing a distinct state of an item over a temporal range. Use this domain to explore item history and state changes.

alerts Domain

The WHERE Clause

The WHERE clause filters results using one or more filters. Each filter has the structure:

column_name:(value1, value2, ...)

Values must match the column’s type. You can use individual values, ranges (when supported), or a comma-separated combination.

Combining Filters

When specifying multiple values within a single filter, the match is logically OR. When specifying multiple filters across different columns, the match is logically AND.

For example:

scans where started_at:(2025-01-01..2025-01-07, 2025-02-01..2025-02-07), is_hash:(T)

This query matches scans that:

• Occurred in either the first week of January 2025 or the first week of February 2025
• AND were performed with hashing enabled

The SHOW Clause

The SHOW clause controls which columns are displayed and how some of them are formatted. If omitted, a default column set is used.

You may specify:

• A list of column names
• The keyword default to insert the default set
• The keyword all to show all available columns

Formatting modifiers can be applied using the @ symbol:

item_path@name, mod_date@short

Format Specifiers by Type

The timestamp format modifier converts dates to UTC timestamps (seconds since Unix epoch), which is useful for programmatic processing or web applications that need to format dates in the user’s local timezone.

The ORDER BY Clause

Specifies sort order for the results:

items order by mod_date desc, item_path asc

If direction is omitted, ASC is assumed.

The LIMIT and OFFSET Clauses

LIMIT restricts the number of rows returned. OFFSET skips a number of rows before returning results.

items limit 50 offset 100

Examples

# Items whose path contains 'reports'
items where item_path:('reports')

# Large files sorted by size
items where item_type:(F), size:(> 1048576) show default, size order by size desc

# Version history for a specific item
versions where item_id:(42) order by first_scan_id

# Deleted items across all roots
items where is_deleted:(true)

# Versions with validation failures
versions where val_state:(I) show default, val_error order by first_scan_id desc

# Items with suspect hash state
items where hash_state:(S) show default, hash_state, file_hash order by item_path

# Open or flagged alerts for suspect hashes
alerts where alert_type:(H), alert_status:(O, F) order by created_at desc

# Scans with timestamps for programmatic processing
scans show scan_id, started_at@timestamp, file_count order by started_at desc limit 10

# Scans with change and alert counts
scans show scan_id, file_count, total_size, add_count, modify_count, delete_count, alert_count order by started_at desc

See also: Data Explorer · Validators · Configuration