Skip to content

Gira Query Language (GQL) Specification

Overview

The Gira Query Language (GQL) provides a powerful, consistent syntax for searching and filtering tickets, epics, sprints, and comments across all Gira commands. It supports complex boolean expressions, field-based queries, and fuzzy text matching.

Core Syntax Elements

Basic Structure

field:value
field:operator:value
field:function(arguments)

Query Components

  1. Fields: Specify which field to search in
  2. Operators: Define the comparison logic
  3. Values: The search term or criteria
  4. Functions: Special operations for complex queries

Field Reference

Ticket Fields

Core Fields

  • id - Ticket ID (e.g., GIRA-123)
  • uuid - Internal UUID
  • title - Brief summary
  • description - Detailed description

Status & Workflow

  • status - Current status (backlog, todo, in_progress, review, done)
  • type - Ticket type (story, task, bug, epic, feature, subtask)
  • priority - Priority level (low, medium, high, critical)

People

  • assignee - Assigned user (email or username)
  • reporter - Creator (email or username)

Relationships

  • epic_id - Parent epic ID
  • parent_id - Parent ticket ID for subtasks
  • sprint_id - Associated sprint ID

Dependencies

  • blocked_by - Tickets blocking this one
  • blocks - Tickets blocked by this one

Metadata

  • labels - Tags/labels array
  • comment_count - Number of comments
  • attachment_count - Number of attachments
  • due_date - Target completion date
  • story_points - Estimated effort (0-100)
  • order - Custom order within status

Timestamps

  • created_at - Creation timestamp
  • updated_at - Last update timestamp

Epic Fields

Core Fields

  • id - Epic ID (e.g., EPIC-123)
  • title - Brief summary
  • description - Detailed description

Status & Planning

  • status - Epic status (draft, active, completed)
  • owner - Epic owner (email)
  • target_date - Target completion date

Relationships

  • tickets - List of ticket IDs in this epic

Timestamps

  • created_at - Creation timestamp
  • updated_at - Last update timestamp

Sprint Fields

Core Fields

  • id - Sprint ID (e.g., SPRINT-2024-01-15)
  • name - Sprint name
  • goal - Sprint goal/objective

Dates & Status

  • start_date - Sprint start date
  • end_date - Sprint end date
  • status - Sprint status (planned, active, completed)

Relationships

  • tickets - List of ticket IDs in this sprint

Timestamps

  • created_at - Creation timestamp
  • updated_at - Last update timestamp

Comment Fields

Core Fields

  • id - Comment ID
  • ticket_id - Parent ticket ID
  • author - Comment author (email or username)
  • content - Comment content

Edit Tracking

  • edited - Whether comment has been edited
  • edit_count - Number of times edited

AI Metadata

  • is_ai_generated - Whether comment was AI-generated
  • ai_model - AI model used if applicable

Timestamps

  • created_at - Creation timestamp
  • updated_at - Last update timestamp

Operators

Comparison Operators

Equality

  • = or : - Exact match
  • != or !: - Not equal
  • ~ - Fuzzy match (approximate)
  • !~ - Not fuzzy match

Numeric/Date Comparison

  • > - Greater than
  • >= - Greater than or equal
  • < - Less than
  • <= - Less than or equal

Text Operators

  • contains - String contains substring
  • starts_with - String starts with prefix
  • ends_with - String ends with suffix
  • matches - Regular expression match

List Operators

  • in - Value is in list
  • not_in - Value is not in list
  • contains - List contains value
  • empty - List is empty
  • not_empty - List is not empty

Null/Empty Operators

  • is_null - Field is null/empty
  • is_not_null - Field has a value

Boolean Logic

Logical Operators

  • AND - Both conditions must be true
  • OR - Either condition must be true
  • NOT - Negate the condition

Operator Precedence

  1. Parentheses ()
  2. NOT
  3. AND
  4. OR

Grouping

Use parentheses to group conditions: 

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

Value Types and Formats

String Values

  • Unquoted: simple_value
  • Quoted: "value with spaces"
  • Escaped quotes: "value with \"quotes\""

Date/Time Values

  • ISO 8601 format: 2024-01-15T10:30:00Z
  • Date only: 2024-01-15
  • Relative: today, yesterday, this_week, last_month

Numeric Values

  • Integer: 42
  • Float: 3.14
  • Range: 1..10

Boolean Values

  • true, false
  • yes, no
  • 1, 0

List Values

  • Single value: status:todo
  • Multiple values: status:in(todo,in_progress)
  • Comma-separated: labels:contains(bug,critical)

Functions

Text Functions

  • fuzzy(text, threshold) - Fuzzy text matching with minimum threshold
  • regex(pattern) - Regular expression matching
  • normalize(text) - Normalize text for comparison

Date Functions

  • today() - Current date
  • now() - Current timestamp
  • days_ago(n) - N days ago
  • weeks_ago(n) - N weeks ago
  • months_ago(n) - N months ago
  • start_of_week() - Start of current week
  • end_of_week() - End of current week
  • start_of_month() - Start of current month
  • end_of_month() - End of current month

User Functions

  • current_user() - Current user's email/username
  • me() - Alias for current_user()

Aggregation Functions

  • count(field) - Count of non-null values
  • sum(field) - Sum of numeric values
  • avg(field) - Average of numeric values
  • min(field) - Minimum value
  • max(field) - Maximum value

Example Queries

Basic Queries

# Find tickets assigned to current user
assignee:me()

# Find high priority bugs
priority:high AND type:bug

# Find tickets in specific epic
epic_id:EPIC-123

# Find tickets with no assignee
assignee:is_null

# Find tickets created this week
created_at:>=start_of_week()

Advanced Queries

# Find critical bugs or high priority stories
(priority:critical AND type:bug) OR (priority:high AND type:story)

# Find tickets blocked by specific tickets
blocked_by:contains(GIRA-100)

# Find tickets with multiple labels
labels:contains(frontend) AND labels:contains(urgent)

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

# Find tickets with comments from specific user
comments.author:john@example.com

# Find tickets with high story points
story_points:>=8

# Find tickets updated in last 7 days
updated_at:>=days_ago(7)

Text Search Queries

# Fuzzy search in title
title:~"authentication"

# Search in description
description:contains("user interface")

# Combined text search
title:~"bug" OR description:contains("error")

# Regular expression search
title:matches("^BUG-.*")

Complex Relationship Queries

# Find epics with active tickets
status:active AND tickets:not_empty

# Find sprints ending this week
end_date:<=end_of_week()

# Find tickets in current sprint
sprint_id:current_sprint()

# Find tickets blocking others
blocks:not_empty

# Find subtasks of specific parent
parent_id:GIRA-100

Reserved Words

The following words are reserved and cannot be used as field names: - AND, OR, NOT - true, false - null, empty - today, now, me - contains, matches, starts_with, ends_with - in, not_in, is_null, is_not_null

Query Validation Rules

  1. Field Validation: All field names must exist in the target entity
  2. Type Validation: Values must match the expected field type
  3. Operator Validation: Operators must be compatible with field types
  4. Enum Validation: Enumerated fields must use valid values
  5. Date Validation: Date values must be properly formatted
  6. Reference Validation: ID references should exist (warning if not)

Error Handling

Syntax Errors

  • Invalid field names
  • Malformed operators
  • Unclosed parentheses
  • Invalid date formats

Runtime Errors

  • Type mismatches
  • Invalid enum values
  • Non-existent references
  • Function errors

Implementation Notes

Performance Considerations

  • Index commonly queried fields
  • Optimize fuzzy matching with minimum thresholds
  • Cache compiled query expressions
  • Use efficient data structures for complex queries

Extensibility

  • Support for custom fields
  • Plugin architecture for new operators
  • Custom function registration
  • Query result transformations

Integration Points

  • Command-line interface
  • REST API endpoints
  • Batch processing
  • Export/import functionality

Future Enhancements

  1. Aggregation Queries: Support for GROUP BY and aggregation functions
  2. Subqueries: Nested queries for complex relationships
  3. Saved Queries: Named queries for reuse
  4. Query Templates: Parameterized queries
  5. Real-time Queries: Live updating query results
  6. Query Optimization: Automatic query optimization
  7. Visual Query Builder: GUI for building complex queries
  8. Query Analytics: Performance metrics and optimization suggestions

Compatibility

This specification is designed to be: - Backward Compatible: Existing search functionality remains unchanged - Forward Compatible: New features can be added without breaking changes - Cross-Platform: Works consistently across all Gira interfaces - Language Agnostic: Can be implemented in any programming language

Version History

  • v1.0: Initial specification
  • v1.1: Added aggregation functions and relationship queries
  • v1.2: Enhanced text search and fuzzy matching
  • v1.3: Added comment field support and AI metadata

This specification defines the syntax and semantics of the Gira Query Language. For implementation details, see the corresponding parser and executor documentation.