Label Expressions Guide

Overview

Label expressions provide a powerful query language for filtering Wanaku entities (tools, resources, namespaces) based on their labels using logical operators and conditions.

Labels are key-value pairs attached to entities for categorization and filtering. Label expressions allow you to write complex queries that combine multiple conditions using logical operators.

Quick Start

Basic Filtering

List all weather-related tools:

bash

wanaku tools list -l "category=weather"

List weather tools that perform forecasting:

bash

wanaku tools list -l "category=weather & action=forecast"

List tools that are NOT in production:

bash

wanaku tools list -l "environment!=production"

Expression Syntax

Comparison Operators

Operator	Description	Example
`=`	Equals	`category=weather`
`!=`	Not equals	`status!=deprecated`

Logical Operators

Operator	Description	Example
`&`	Logical AND	`category=weather & version=2.0`
`\|`	Logical OR	`category=weather \| category=news`
`!`	Logical NOT	`!deprecated=true`
`( )`	Grouping	`(a=1 \| b=2) & c=3`

Operator Precedence

Operators are evaluated in this order (highest to lowest):

! (NOT) - Highest precedence
& (AND) - Medium precedence
| (OR) - Lowest precedence

Tip: Use parentheses ( ) to override default precedence and make expressions clearer.

Expression Examples

Simple Equality

Match tools where category equals "weather":

category=weather

Inequality

Match tools where environment is NOT production:

environment!=production

AND Conditions

Match weather tools with version 2.0:

category=weather & version=2.0

Match production tools that are stable:

environment=production & status=stable

OR Conditions

Match tools that are either weather or news:

category=weather | category=news

Match tools with beta or stable status:

status=beta | status=stable

NOT Conditions

Match weather tools that are NOT forecasts:

category=weather & !action=forecast

Match tools that are NOT deprecated:

!deprecated=true

Complex Expressions

Match production-ready weather or news tools:

(category=weather | category=news) & environment=production

Match non-production tools that are not deprecated:

environment!=production & !deprecated=true

Match version 2.0 tools with stable or beta status:

version=2.0 & (status=stable | status=beta)

Match tools that are either in production, or are beta weather tools:

environment=production | (status=beta & category=weather)

Understanding Operator Precedence

Example 1: AND before OR

Expression:

a=1 | b=2 & c=3

This is evaluated as:

a=1 | (b=2 & c=3)

Matches when:

a=1, OR
Both b=2 AND c=3

Example 2: NOT before AND

Expression:

!a=1 & b=2

This is evaluated as:

(!a=1) & b=2

Matches when:

a does NOT equal 1, AND
b=2

Example 3: Using Parentheses

Expression:

(a=1 | b=2) & c=3

Matches when:

Either a=1 OR b=2, AND
c=3

Without parentheses, this would mean something different!

Allowed Characters

In Keys and Values

Letters: a-z, A-Z
Numbers: 0-9
Hyphen: - (e.g., api-version=2.0)
Underscore: _ (e.g., my_category=test)
Dot: . (e.g., version=1.2.3)
Forward slash: / (e.g., path=/api/v1/tools)

Special Characters

Operators: &, |, !, =, (, )
Whitespace: Spaces for readability (automatically trimmed)

Maximum Length

1000 characters maximum per expression

Common Use Cases

By Environment

List development tools:

environment=development

List all non-production tools:

environment!=production

By Status

List stable tools:

status=stable

List tools that are stable or beta:

status=stable | status=beta

List tools that are NOT deprecated:

!deprecated=true

By Category

List weather and news tools:

category=weather | category=news

List finance tools that are NOT deprecated:

category=finance & !deprecated=true

By Version

List version 2.x tools:

version=2.0 | version=2.1 | version=2.2

List tools that are NOT version 1.0:

version!=1.0

Complex Scenarios

Production-ready, stable weather tools:

category=weather & environment=production & status=stable

Beta or alpha tools, but not deprecated:

(status=beta | status=alpha) & !deprecated=true

Weather or news tools in development or staging:

(category=weather | category=news) & (environment=development | environment=staging)

Parser Safety

Input Validation

All label expressions are validated for safety:

Character whitelist: Only allows safe characters (alphanumeric, operators, safe punctuation)
Length limit: Maximum 1000 characters (prevents DoS attacks)
Parser safety: Rejects invalid characters that could cause parser errors

Invalid Characters

These characters are rejected and will cause an error:

Semicolon: ;
Quotes: ', "
Backtick: `
Backslash: \
Angle brackets: <, >
Dollar sign: $
Curly braces: {, }
Square brackets: [, ]

Example: Rejected Input

bash

# This will fail - contains invalid semicolon
wanaku tools list -l "category=weather; DROP TABLE"

# Error: Query contains invalid characters

How It Works

Label filtering uses in-memory evaluation with Java streams:

Parse the expression into a predicate function
Fetch all entities from the cache
Filter using Java streams by applying the predicate to each entity's labels
Return only matching entities

This approach ensures:

✅ Accurate correlation of label keys and values
✅ Support for complex nested expressions
✅ No database query limitations
✅ Safe evaluation (no injection attacks)

Troubleshooting

"Query contains invalid characters"

Cause: Expression contains characters not in the whitelist.

Solution: Remove special characters. Only use alphanumeric, operators (&, |, !, =), parentheses, hyphens, underscores, dots, and forward slashes.

"Expected ')' after expression"

Cause: Unmatched parentheses in expression.

Solution: Ensure every opening ( has a matching closing ).

Example:

bash

# Wrong - missing closing parenthesis
(category=weather & action=forecast

# Correct
(category=weather & action=forecast)

"Expected label value after '='"

Cause: Missing value after = or != operator.

Solution: Provide a value after the operator.

Example:

bash

# Wrong - missing value
category=

# Correct
category=weather

"Query string too long"

Cause: Expression exceeds 1000 characters.

Solution: Simplify the expression or split into multiple queries.

No Results Returned

Possible causes:

Case sensitivity: Label matching is case-sensitive
- category=Weather ≠ category=weather
Exact matching: Values must match exactly
- version=2 ≠ version=2.0
Label not present: Entity doesn't have the specified label
- Use != to match entities without a label

Tips:

Verify labels are correctly set on entities
Check for typos in label keys and values
Test with simpler expressions first

Tips and Best Practices

Use Descriptive Labels

Good:

environment=production
status=stable
category=weather-forecast
version=2.1.0

Avoid:

env=prod
st=1
cat=wthr
v=2

Use parentheses to make complex expressions clearer:

Good:

(category=weather | category=news) & (status=stable | status=beta)

Less clear:

category=weather | category=news & status=stable | status=beta

Test Incrementally

Build complex expressions step by step:

Start simple: category=weather
Add conditions: category=weather & status=stable
Add complexity: (category=weather | category=news) & status=stable

Use Whitespace

Add spaces for readability - they're automatically trimmed:

Good:

category=weather & status=stable | environment=production

Works, but harder to read:

category=weather&status=stable|environment=production

Examples

bash

# List all tools with label filter
wanaku tools list -l "category=weather"

# List with multiple conditions
wanaku tools list -l "(category=weather | category=news) & environment=production"

# List without filter (show all)
wanaku tools list

Additional Resources

Label Expression Grammar: See LabelQueryParser.java class documentation
CLI Help: Run wanaku tools list --help for command-specific help

Summary

Label expressions provide a powerful, safe, and flexible way to filter Wanaku entities:

Simple syntax with familiar logical operators
Complex queries with AND, OR, NOT, and grouping
Safe evaluation with input validation and in-memory filtering
Case-sensitive exact matching
No injection risks - safe for user input

Start with simple expressions and build up to complex queries as needed. Use parentheses to make expressions clear and test incrementally.

Label Expressions Guide ​

Overview ​

Quick Start ​

Basic Filtering ​

Expression Syntax ​

Comparison Operators ​

Logical Operators ​

Operator Precedence ​

Expression Examples ​

Simple Equality ​

Inequality ​

AND Conditions ​

OR Conditions ​

NOT Conditions ​

Complex Expressions ​

Understanding Operator Precedence ​

Example 1: AND before OR ​

Example 2: NOT before AND ​

Example 3: Using Parentheses ​

Allowed Characters ​

In Keys and Values ​

Special Characters ​

Maximum Length ​

Common Use Cases ​

By Environment ​

By Status ​

By Category ​

By Version ​

Complex Scenarios ​

Parser Safety ​

Input Validation ​

Invalid Characters ​

Example: Rejected Input ​

How It Works ​

Troubleshooting ​

"Query contains invalid characters" ​

"Expected ')' after expression" ​

"Expected label value after '='" ​

"Query string too long" ​

No Results Returned ​

Tips and Best Practices ​

Use Descriptive Labels ​

Group Related Conditions ​

Test Incrementally ​

Use Whitespace ​

Examples ​

Additional Resources ​

Summary ​

Label Expressions Guide

Overview

Quick Start

Basic Filtering

Expression Syntax

Comparison Operators

Logical Operators

Operator Precedence

Expression Examples

Simple Equality

Inequality

AND Conditions

OR Conditions

NOT Conditions

Complex Expressions

Understanding Operator Precedence

Example 1: AND before OR

Example 2: NOT before AND

Example 3: Using Parentheses

Allowed Characters

In Keys and Values

Special Characters

Maximum Length

Common Use Cases

By Environment

By Status

By Category

By Version

Complex Scenarios

Parser Safety

Input Validation

Invalid Characters

Example: Rejected Input

How It Works

Troubleshooting

"Query contains invalid characters"

"Expected ')' after expression"

"Expected label value after '='"

"Query string too long"

No Results Returned

Tips and Best Practices

Use Descriptive Labels

Group Related Conditions

Test Incrementally

Use Whitespace

Examples

Additional Resources

Summary