Tags

ProcessingSteps, WorkData, and Jobs support tags, allowing users or the system to attach metadata for better organization and resource discovery.

Tag Types

At its simplest level, a tag is a string limited to 1024 characters. Examples:

• Approved
• 2026
• 018c0b59-1234-7c64-aca4-1f5408ab621d

Key-Value Tags (Semantic Tags)

PineXQ supports Key-Value tags to enable sophisticated filtering and queries. These follow the format: <key>=<value>

• Both key and value are limited to 1024 characters each.
• Examples: year=2026, approved=true, project_id=A12

---

Tag Decomposition

When a tag is assigned to a resource, the system processes and “decomposes” it using the following logic:

1. Structure Detection: If an = is present, the right side is treated as the value. If no = exists, the tag is categorized as KeyOnly.
2. Trimming: Leading and trailing whitespace is removed from both the key and value.
3. Type Detection: The value is inspected to determine its data type.
4. Normalization: The value is reformatted to a standard system format.

Recognized Value Types

Type	Description	Examples	Normalization / Notes
KeyOnly	A simple tag with no assigned value.	draft
String	The default type for non-numeric/special text.	status=gold
Integer	Standard integer values.	offset=-1
Float	Floating point numbers (Double).	temp=-1.23	1. becomes 1.0. Precision up to 16 decimal places.
Boolean	Logical True/False values.	fog=true	Mapped to lowercase (e.g., tRuE → true).
Date	A specific calendar date.	day=2025-10-31	Format: yyyy-MM-dd
Time	A specific time or duration.	time=100:20:30 time=-10:20:30	Milliseconds are appended for consistency: 10:00:00 → 10:00:00:00.
Timestamp	ISO 8601 with time zone info.	timestamp_utc= 2024-10-01T12:00Z timestamp= 2026-01-16T11:12:35+05:30	Required: Must include “Z” or offset. Local time (no zone) is rejected. Will be normalized to UTC in “Z” notation.

Tag Query Language TQL

TQL lets you filter WorkData, Jobs and ProcessingSteps by their tags using expressions.

Example TQL expression in a WorkData query:

result = WorkDataQuery.create(
            client=client,
            tag_query_expression="mytag & year=2001", # <-- TQL
            sort_by_property_name=WorkDataSortProperties.name,
            sort_by_sort_type=SortTypes.ascending
        ).execute()

Tags in PineXQ

Tags come in two forms:

• Simple tags — a key only, e.g. draft, reviewed
• Semantic tags — a key and a typed value, e.g. status=active, priority=5, created=2025-06-01

When you assign a tag like priority=5, PineXQ automatically detects the value type (integer, date, etc.) and stores it accordingly.

Basic Filtering

Match a simple tag

Find all resources tagged with draft:

draft

Match a key=value tag (exact, typeless)

status=active

Values containing { } ( ) & | !, single quotes, or spaces must be single-quoted:

title='Final Report'

Combining Filters

AND

Both must match.

draft & reviewed

OR

At least one must match.

draft | published

NOT

Negate with !()

!(draft)

Precedence and grouping

& binds tighter than |. Use parentheses to override:

A | B & C        --> A | (B & C)
(A | B) & C      --> (A | B) then C

Complex example

!(year=2025 & status=silver) | status=gold

Typed Value Filters

For precise comparisons, use the typed syntax which enables more complex operations:

key={type:operator value}
year={int:>2025} --> will return all tag with key year, value of type integer and >2025

String operators (str)

Operator	Meaning	Example
=	Equals	status={str:=active}
!=	Not equals	status={str:!=archived}
~	LIKE (case-sensitive)	name={str:~report%}
~*	LIKE (case-insensitive)	name={str:~*%REPORT%}
!~	NOT LIKE (case-sensitive)	name={str:!~draft%}
!~*	NOT LIKE (case-insensitive)	name={str:!~*%TEMP%}
regex()	Regex match	code={str:regex('v[0-9]+')}
!regex()	Negated regex	code={str:!regex('test.*')}

• LIKE wildcards: % matches any sequence, _ matches one character. Escape with \.
• String values can be unquoted (active) or single-quoted ('my value').

Numeric operators (int, float)

Operators: =, !=, <, >, <=, >=

priority={int:>5}
priority={int:<=10}
score={float:>=3.5}
temperature={float:<-0.5}

Boolean operators (bool)

Operators: =, !=

ready={bool:=true}
ready={bool:!=false}

Date operators (date)

Format: YYYY-MM-DD. Operators: =, !=, <, >, <=, >=

created={date:=2025-01-15}
created={date:>2024-12-31}
deadline={date:<=2025-06-01}

Timestamp operators (timestamp)

ISO 8601 format, must include timezone (Z or offset). Operators: =, !=, <, >, <=, >=

processed={timestamp:>2025-01-01T00:00:00Z}
updated={timestamp:<=2025-06-15T14:30:00+02:00}

Time operators (time)

Format: HH:MM:SS or HH:MM:SS.fff, can exceed 24h, can be negative. Operators: =, !=, <, >, <=, >=

duration={time:>01:30:00}
offset={time:<-02:00:00}

Wildcards

Find all resources that have a specific tag key, regardless of value:

status={*}                 -- any value, any type
priority={int:*}           -- any integer value
ready={bool:*}             -- any boolean value

Dynamic Value Functions

Use functions instead of fixed values for time-relative queries. All functions are case-sensitive.

Function	Type	Description
dateNow()	Date	Current date
timeNowUtc()	Time	Current UTC time
timestampUtc()	Timestamp	Current UTC date and time
timestampUtcDateOnly()	Timestamp	Current UTC date at midnight (00:00:00)

With offsets

Example	Meaning
dateNow(-30)	30 days ago
dateNow(7)	7 days from now
timeNowUtc(-02:00:00)	2 hours ago
timestampUtc(-1.12:00:00)	1 day and 12 hours ago
timestampUtcDateOnly(27:00:00)	Now + 27 hours, then truncated to midnight UTC (may shift to next day)

Examples

Resources created in the last 30 days:

created={date:>=dateNow(-30)}

Resources processed before now:

processed={timestamp:<timestampUtc()}

Value Normalization

When you assign a tag, PineXQ normalizes the value before storing it. Query values are normalized the same way, so comparisons are consistent.

• Boolean: Lowercased. True, TRUE become true.
• Float: Trailing zeros and missing decimals are normalized. 3.0 stays 3.0, 3.10 becomes 3.1.
• Integer: Stored as-is (no leading zeros).
• Date: Must be in YYYY-MM-DD format. Stored as-is.
• Time: Normalized to .NET TimeSpan general format, e.g. 19:15:00 becomes 19:15:00. Milliseconds are included for consistency.
• Timestamp: Always converted to UTC. A tag like processed=2026-01-16T11:12:35+05:30 is stored as 2026-01-16T05:42:35.0000000Z. When querying, your filter values are also normalized to UTC, so processed={timestamp:=2026-01-16T05:42:35Z} will match. A timestamp must include a timezone (Z or an offset like +02:00), otherwise it is rejected.
• String: Stored as-is (fallback type when no other type matches).

Quick Reference

What you want	Query
Has tag draft	draft
Has tag status with value active	status=active
Has both tags	draft & reviewed
Has either tag	draft | published
Does NOT have tag	!(draft)
Priority greater than 5	priority={int:>5}
Name contains “report”	name={str:~%report%}
Created this year	created={date:>=2025-01-01}
Created in last 7 days	created={date:>=dateNow(-7)}
Any value for status	status={*}
Complex filter	status=active & priority={int:>=3} | urgent