Query Language User Guide¶

The Gira Query Language (GQL) provides a powerful way to search and filter tickets, epics, sprints, and comments. This guide covers practical usage with examples.

🚀 Quick Start¶

Basic Syntax¶

All queries follow the pattern: field:value

# Find tickets with status "todo"
gira ticket list --query "status:todo"

# Find high priority tickets
gira ticket list --query "priority:high"

# Find tickets assigned to you
gira ticket list --query "assignee:me()"

Combining Conditions¶

Use AND, OR, and NOT to combine conditions:

# High priority bugs
gira ticket list --query "priority:high AND type:bug"

# Tickets that are todo or in progress
gira ticket list --query "status:todo OR status:in_progress"

# Tickets not assigned to anyone
gira ticket list --query "NOT assignee:*"

🎯 Field Reference¶

Essential Ticket Fields¶

Field	Description	Example
`id`	Ticket ID	`id:GIRA-123`
`title`	Ticket title	`title:~"login bug"`
`status`	Current status	`status:todo`
`priority`	Priority level	`priority:high`
`type`	Ticket type	`type:bug`
`assignee`	Assigned person	`assignee:me()`
`reporter`	Who created it	`reporter:john@example.com`
`epic_id`	Parent epic	`epic_id:EPIC-123`
`labels`	Tags/labels	`labels:contains(urgent)`
`created_at`	Creation date	`created_at:>days_ago(7)`
`updated_at`	Last update	`updated_at:>=start_of_week()`

Epic Fields¶

Field	Description	Example
`id`	Epic ID	`id:EPIC-123`
`title`	Epic title	`title:~"authentication"`
`status`	Epic status	`status:active`
`owner`	Epic owner	`owner:me()`
`target_date`	Target completion	`target_date:<end_of_month()`

Sprint Fields¶

Field	Description	Example
`id`	Sprint ID	`id:SPRINT-2024-01-15`
`name`	Sprint name	`name:~"MVP"`
`status`	Sprint status	`status:active`
`start_date`	Start date	`start_date:>=today()`
`end_date`	End date	`end_date:<days_ago(0)`

🔍 Search Operators¶

Exact Match¶

# Exact status match
status:todo

# Exact priority match
priority:high

Fuzzy Match¶

# Fuzzy title search
title:~"authentication"

# Fuzzy description search
description:~"user interface"

Comparisons¶

# Greater than
story_points:>5

# Less than or equal
created_at:<=days_ago(30)

# Date range
updated_at:>=start_of_week() AND updated_at:<=end_of_week()

Contains¶

# Labels contain specific tag
labels:contains(urgent)

# Description contains text
description:contains("API")

Null/Empty Checks¶

# No assignee
assignee:is_null

# Has labels
labels:not_empty

# No due date
due_date:is_null

📅 Date Functions¶

Current Time¶

# Created today
created_at:>=today()

# Updated this week
updated_at:>=start_of_week()

# Due this month
due_date:<=end_of_month()

Relative Dates¶

# Created in last 7 days
created_at:>=days_ago(7)

# Updated in last 2 weeks
updated_at:>=weeks_ago(2)

# Created in last month
created_at:>=months_ago(1)

👤 User Functions¶

# Assigned to current user
assignee:me()

# Reported by current user
reporter:me()

# Either assigned or reported by current user
assignee:me() OR reporter:me()

🔗 Relationship Queries¶

Epic Relationships¶

# All tickets in an epic
epic_id:EPIC-123

# Tickets not in any epic
epic_id:is_null

# Epics with tickets
tickets:not_empty

Dependencies¶

# Blocked tickets
blocked_by:not_empty

# Tickets blocking others
blocks:not_empty

# Tickets blocked by specific ticket
blocked_by:contains(GIRA-100)

Subtasks¶

# Subtasks of a parent ticket
parent_id:GIRA-123

# Tickets with subtasks
# (parent tickets have subtasks referring to them)

💡 Advanced Examples¶

Project Management Queries¶

# Current sprint work
status:in_progress AND sprint_id:current_sprint()

# Overdue tickets
due_date:<today() AND status:not_in(done,cancelled)

# High priority work for current user
priority:high AND assignee:me() AND status:not_in(done)

# Recently updated tickets
updated_at:>=days_ago(3)

# Tickets ready for review
status:review

# Blocked work items
blocked_by:not_empty AND status:in_progress

Quality Assurance¶

# All bugs
type:bug

# Critical bugs not fixed
type:bug AND priority:critical AND status:!=done

# Recently reported bugs
type:bug AND created_at:>=days_ago(7)

# Bugs with no assignee
type:bug AND assignee:is_null

Planning Queries¶

# Unestimated tickets
story_points:is_null AND type:!=subtask

# Large tickets
story_points:>=8

# Tickets without epics
epic_id:is_null AND type:!=subtask

# Epic progress
status:active AND tickets:not_empty

Team Coordination¶

# Work assigned to team member
assignee:john@example.com

# Recently commented tickets
comment_count:>0 AND updated_at:>=days_ago(1)

# Tickets with attachments
attachment_count:>0

# Tickets with many comments
comment_count:>=5

🛠️ Using with Commands¶

Ticket Commands¶

# List tickets with query
gira ticket list --query "status:todo AND priority:high"

# Show ticket details
gira ticket show GIRA-123

# Update specific tickets (no query support in update command)
gira ticket update GCM-123 GCM-124 --priority high

Epic Commands¶

# List active epics
gira epic list --query "status:active"

# Find epics by owner
gira epic list --query "owner:me()"

Sprint Commands¶

# List current sprints
gira sprint list --query "status:active"

# Find sprints ending soon
gira sprint list --query "end_date:<=days_ago(-7)"

Search All Entities¶

# Query commands work with --query option on each entity type
gira ticket list --query "priority:high"
gira epic list --query "status:active" 
gira sprint list --query "name:~'MVP'"

🎨 Output Formats¶

Table Format (default)¶

gira ticket list --query "status:todo" --format table

JSON Format¶

gira ticket list --query "priority:high" --format json

IDs Only¶

gira ticket list --query "assignee:me()" --ids-only

🔧 Query Tips¶

Performance¶

Use specific fields when possible
Avoid complex nested queries for large datasets
Use pagination with --limit and --offset

Debugging¶

Use --verbose flag for detailed error messages
Test simple queries first, then add complexity
Use parentheses to group conditions clearly

Common Patterns¶

Always quote strings with spaces: title:"bug fix"
Use fuzzy match for partial text: title:~"auth"
Combine user functions: assignee:me() OR reporter:me()
Use date functions for relative searches: created_at:>=days_ago(7)

📚 Quick Reference¶

Common Queries¶

# My work
assignee:me()

# High priority
priority:high

# Recent updates
updated_at:>=days_ago(7)

# Needs attention
status:todo AND priority:high AND assignee:me()

# Blocked work
blocked_by:not_empty

# Ready for review
status:review

# Overdue
due_date:<today() AND status:!=done

Boolean Logic¶

# AND (both conditions)
status:todo AND priority:high

# OR (either condition)  
status:todo OR status:in_progress

# NOT (negation)
NOT status:done

# Grouping
(status:todo OR status:in_progress) AND priority:high

Comparison Operators¶

:         # equals
!=        # not equals
~         # fuzzy match
>         # greater than
>=        # greater than or equal
<         # less than
<=        # less than or equal
contains  # contains substring/value
is_null   # is null/empty
not_empty # is not empty

This query language makes it easy to find exactly what you're looking for across all your project data. Start with simple queries and gradually build up to more complex searches as you become comfortable with the syntax.