Filtering with Query Syntax

The Bindplane query syntax provides a powerful way to filter and search resources using a flexible token-based format.

This guide covers how to use the --query flag in the CLI and equivalent filtering in the UI using the Filter bar on the Agents and Configurations pages.

What is Query Syntax?

Query syntax allows you to filter and search Bindplane resources using a token-based format. You can filter collectors by status, platform, version, and other fields, search by labels and configuration names, use negation operators to exclude specific criteria, and combine multiple conditions with AND logic.

Basic Syntax

Token Format

Queries are composed of space-separated tokens in the format:

[operator]name:value

Operators

• + (optional): Positive match (default)

• - : Negation (NOT match)

• No operator: Positive match (default)

Field-Based Filtering

Agent Status

Filter collectors by their connection and operational status:

# Find connected collectors
bindplane get agents --query "status:Connected"

# Find disconnected collectors
bindplane get agents --query "status:Disconnected"

# Find collectors with errors
bindplane get agents --query "status:Error"

# Find collectors that are NOT disconnected
bindplane get agents --query "-status:Disconnected"

Available Status Values:

• Connected - Collector is connected and healthy

• Disconnected - Collector is not connected

• Error - Collector has an error

• Configuring - Collector is applying a new configuration

• Deleted - Collector is marked for deletion

• Upgrading - Collector is upgrading

• Pending - Collector is queued for configuration

• Incompatible - Collector configuration is incompatible

Platform and Architecture

Filter by system characteristics:

# Find Linux collectors
bindplane get agents --query "platform:linux"

# Find Windows collectors
bindplane get agents --query "platform:windows"

# Find collectors on specific architecture
bindplane get agents --query "arch:amd64"

# Find collectors that are NOT on Linux
bindplane get agents --query "-platform:linux"

Version Management

Filter by collector version:

# Find collectors with specific version
bindplane get agents --query "version:v1.30.0"

# Find collectors with latest version (auto-resolved)
bindplane get agents --query "version:latest"

# Find collectors that are out of date
bindplane get agents --query "outOfDate:true"

# Find collectors that are NOT out of date
bindplane get agents --query "-outOfDate:true"

Collector Type and Identity

Filter by collector type and identification:

# Find specific collector type
bindplane get agents --query "type:observiq-otel-collector"

# Find collectors by hostname pattern
bindplane get agents --query "hostname:web-*"

# Find collectors by name
bindplane get agents --query "name:production-collector"

# Find collectors by MAC address
bindplane get agents --query "macAddress:00:11:22:33:44:55"

Label-Based Filtering

Labels are key-value pairs that provide flexible categorization:

# Find collectors with specific environment label
bindplane get agents --query "environment:production"

# Find collectors with specific configuration label
bindplane get agents --query "configuration:web-config"

# Find collectors without a specific label
bindplane get agents --query "-environment:test"

# Find collectors with any value for a label key
bindplane get agents --query "environment:"

Configuration-Based Filtering

Filter collectors by their configuration assignments:

# Find collectors with specific current configuration
bindplane get agents --query "configuration-current:my-config:1"

# Find collectors with pending configuration
bindplane get agents --query "configuration-pending:new-config:2"

# Find collectors with future configuration
bindplane get agents --query "configuration-future:upgrade-config:3"

Rollout-Based Filtering

Filter collectors by their rollout status:

# Find collectors with completed rollouts
bindplane get agents --query "rollout-complete:config-name"

# Find collectors with rollout errors
bindplane get agents --query "rollout-error:config-name"

# Find collectors with incompatible rollouts
bindplane get agents --query "rollout-incompatible:config-name"

# Find collectors with pending rollouts
bindplane get agents --query "rollout-pending:config-name"

# Find collectors waiting for rollouts
bindplane get agents --query "rollout-waiting:config-name"

Text Search

Perform substring matching across all searchable fields:

# Find collectors containing "prod" in any field
bindplane get agents --query "prod"

# Find collectors containing "web" in any field
bindplane get agents --query "web"

# Find collectors NOT containing "test" in any field
bindplane get agents --query "-test"

Complex Queries

Combine multiple conditions for precise filtering:

# Find connected Linux collectors with specific configuration
bindplane get agents --query "status:Connected platform:linux configuration:prod-config"

# Find collectors that are NOT disconnected and have latest version
bindplane get agents --query "-status:Disconnected version:latest"

# Find collectors with error status or specific hostname pattern
bindplane get agents --query "status:Error hostname:web-*"

# Find production collectors that are NOT out of date
bindplane get agents --query "environment:production -outOfDate:true"

Quoted Values

Use quotes to include spaces in values:

# Find collectors with configuration containing spaces
bindplane get agents --query 'configuration:"my production config"'

# Find collectors with hostname containing spaces
bindplane get agents --query 'hostname:"web server 01"'

Using Queries with Commands

Get Command

# Filter collectors for display
bindplane get agents --query "status:Connected platform:linux"

Delete Command

# Delete collectors matching query (use with caution)
bindplane delete agent --query "environment:test status:Disconnected"

Label Command

# Add labels to collectors matching query
bindplane label agent --query "platform:linux" --add "maintenance=true"

# Remove labels from collectors matching query
bindplane label agent --query "environment:staging" --remove "old-label"

UI Filtering Equivalents

In the Bindplane UI, you have access to the same filtering.

Collector List Filters

• Status dropdown: Equivalent to status:Connected

• Platform filter: Equivalent to platform:linux

• Search box: Equivalent to text search tokens

• Label filters: Equivalent to label-based queries

Advanced Search

The UI search box supports the same query syntax as the CLI.

• Type status:Connected to filter by status

• Type platform:linux to filter by platform

• Type environment:production to filter by labels

Common Use Cases

Environment Management

# Find all production collectors
bindplane get agents --query "environment:production"

# Find staging collectors that are connected
bindplane get agents --query "environment:staging status:Connected"

# Find test collectors that are disconnected (for cleanup)
bindplane get agents --query "environment:test status:Disconnected"

Maintenance Operations

# Find collectors that need updates
bindplane get agents --query "outOfDate:true"

# Find collectors with specific version for upgrade
bindplane get agents --query "version:v1.29.0"

# Find collectors with errors for troubleshooting
bindplane get agents --query "status:Error"

Configuration Management

# Find collectors using specific configuration
bindplane get agents --query "configuration:web-config"

# Find collectors with pending configuration changes
bindplane get agents --query "configuration-pending:"

# Find collectors with rollout errors
bindplane get agents --query "rollout-error:"

Platform-Specific Operations

# Find all Linux collectors
bindplane get agents --query "platform:linux"

# Find Windows collectors with specific version
bindplane get agents --query "platform:windows version:v1.30.0"

# Find collectors by architecture
bindplane get agents --query "arch:arm64"

Examples Summary

Use Case	Query Example
Find connected collectors	status:Connected
Find Linux collectors	platform:linux
Find production collectors	environment:production
Find collectors with errors	status:Error
Find collectors needing updates	outOfDate:true
Find collectors with specific config	configuration:web-config
Find collectors NOT in test	-environment:test
Find collectors with latest version	version:latest
Find collectors by hostname pattern	hostname:web-*
Find collectors with rollout errors	rollout-error:

The query syntax provides a powerful and flexible way to filter Bindplane resources, enabling efficient management and automation of your telemetry infrastructure.